Tutorial – PhotoPrism

Organizing a photo library containing thousands of RAW files, photos, and videos can be a time-consuming and mind-numbing task. The mere thought of manually tagging, grouping, and organizing photos and videos can give even the most patient photographers shivers. Good thing then that we live in the age of artificial intelligence (AI) that can take the burden of boring tasks off our shoulders. For anyone who is not keen on spending countless evenings fighting a losing battle of keeping their photo libraries neatly organized, PhotoPrism [1] might be manna from heaven. This application pairs a polished yet capable user interface with the powerful TensorFlow machine learning engine, providing you with a platform that can take care of keeping tabs on your photos and videos as if by magic. That description is not an exaggeration: The inner workings of TensorFlow are hidden away from the user's sight so well that it's almost too easy to forget that PhotoPrism is powered by a complex piece of software engineering and not fairy dust. Of course, TensorFlow is not perfect, and sometimes it produces some hilarious results. But they are pretty much the only telltales of what actually powers PhotoPrism.

TensorFlow and PhotoPrism

PhotoPrism relies on TensorFlow to perform three important tasks. The first task is image classification. To simplify, TensorFlow analyzes images and assigns relevant labels to them. For example, all architectural photos get the Building label, and wildlife photos may get various labels, depending on the main subject (for example, Bird, Butterfly, etc.). The second task is face recognition, which allows PhotoPrism to find similar faces and group them into clusters. The third task is detecting images that are usually referred to as "not safe for work," which in most cases means photos containing nudity.

Deploying PhotoPrism

Because PhotoPrism consists of several complex moving parts, deploying it would be a rather daunting proposition if it weren't for containers. PhotoPrism is distributed as a Docker container image that reduces the task of getting the application up and running to a few simple steps.

The first order of business is to install Docker and Docker Compose on the machine that you plan to use for running PhotoPrism. If the machine happens to run an Ubuntu-based Linux distribution, installing both packages is a matter of issuing the command:

sudo apt install docker docker-compose

With the required software installed, use

wget https://dl.photoprism.org/docker/docker-compose.yml

to fetch the configuration file.

While you can start PhotoPrism right away, it's a good idea to adjust the application's default settings first. To do this, open the docker-compose.yml file for editing. Most of the settings in the file are best left at their default values, but there are a few options that require tweaking. By default, PhotoPrism is configured to run in the private (password-protected) mode. If you want to keep it that way, you should replace the default password with a stronger one by replacing the PHOTOPRISM_ADMIN_PASSWORD variable. But if you plan to run the application on a machine that is not exposed to the Internet, and you feel confident that your PhotoPrism instance doesn't need any protection, enable the public mode by setting PHOTOPRISM_PUBLIC to true. And, of course, you might want to replace the generic name and description of your PhotoPrism instance by editing the PHOTOPRISM_SITE_TITLE, PHOTOPRISM_SITE_CAPTION, PHOTOPRISM_SITE_DESCRIPTION, and PHOTOPRISM_SITE_AUTHOR options.

By default, PhotoPrism uses the ~Photos directory as the location of your photo library. But if you store images and videos in a different location, you need to point PhotoPrism to it. To do this, locate the following line in the docker-compose.yml file:

- "~/Pictures:/photoprism/originals"

Replace ~/Pictures with the absolute path to the library as follows:

- "/path/to/library:/photoprism/originals"

But what if you don't keep all your files in just one directory? It's not unusual to keep videos in a separate directory or even on a different storage device, and you might prefer to keep casual snaps in a dedicated library. PhotoPrism makes it possible to include other directories as subdirectories in the originals directory. To do this, specify additional entries under the volumes section as follows:

volumes:
  - "/path/to/videos:/photoprism/originals/videos"
  - "/path/to/snaps:/photoprism/originals/snaps"

Each option in docker-compose.yml contains a description that can help you decide whether you want to modify it or leave it as is. Once you're done editing the configuration file, save the changes, and you're almost ready to start PhotoPrism – almost because there is one more thing you might want to do. By default, PhotoPrism supports a wide range of file formats, and the application indexes all compatible files by default. But that might not necessarily be what you want. For example, if each RAW file in the library has a matching JPEG, there is probably little point in indexing the RAW original. To exclude specific files from being indexed, create a .ppignore file in the root of your photo library, and specify the desired pattern in the file. You can use wildcards when defining patterns, so adding the *.NEF pattern will exclude all NEF files from being indexed. Patterns specified in the .ppignore file apply both to the directory the file is in and all subdirectories. When you place the file in the root directory, the patterns specified in the file will be applied to the entire library. You can, however, place the file into any subdirectory, leaving all directories above it unaffected.

Now you can launch PhotoPrism by running

docker-compose up -d

as root in the directory that contains the docker-compose.yml file. Assuming you haven't changed the default port in the configuration file, point the browser to the 127.0.0.1:2342 address (replace 127.0.0.1 with the actual IP address of the machine running PhotoPrism), and log in using the admin username and the password you've specified in the configuration file.

Now that PhotoPrism is up and running, you need to run an indexing operation (Figure 1) that processes all RAW and JPEG files as well as videos (excluding, of course, the files specified in the .ppignore file). To do this, switch to the Library section and press Start to initiate the indexing operation. This task may take a while to complete, depending on the number of files in your library and the hardware PhotoPrism is running on. That's one of the reasons why you'd want to exclude certain files from being indexed – this may significantly reduce the indexing time. Keep in mind that you have to perform indexing every time you add new files to the library. Don't forget to disable the Complete Rescan option when indexing newly added files; otherwise, PhotoPrism will perform full re-indexing of the entire library.

Figure 1: To populate PhotoPrism with photos and videos, you need to index your library first.

During indexing, PhotoPrism not only classifies files but also groups related images into so-called stacks. For example, if you have a RAW file 19700101-112501.RAW, its JPEG version 19700101-112501.JPG, and processed variant 19700101-112501.jpeg, PhotoPrism conveniently stacks them together, with the 19700101-112501.JPG file at the top of the stack (i.e., this is the file PhotoPrism shows you). Stacks in PhotoPrism are identifiable by the icon in their upper-left corner. If the stack contains a RAW file, you can view it by clicking on the Camera icon, and if the stack consists of files in JPEG and other supported formats, you can view all of them by clicking on the Stack icon (Figure 2).

Figure 2: PhotoPrism groups photos into stacks. You can manually choose which image should be the primary one.

That's all fine and good, but what if you want to have another file in the stack at the top? What if in the example above, you'd rather see the processed 19700101-112501.jpeg file than the unprocessed 19700101-112501.JPG one? To do this, click on the image to open it in the view mode, then click on the Edit icon in the toolbar at the top. Switch to the Files section (its title shows the number of files in the stack), click on the desired file item, and press the Primary button in the Actions section. Exit the editing mode, refresh the page, and you should see the selected file at the top of the stack.

Browse and Search

In many respects, PhotoPrism behaves like a regular photo management application. The Folders module provides access to the library directories, the Calendar module displays all indexed files grouped by year and month, and the Places module presents you with a map where all photos and videos are displayed as clusters (Figure 3). While you can use the mouse to drag the map around to locate the desired spot and then zoom in and out, you can quickly jump to the desired location using the Search field. Type the name of the desired place (e.g., Ravenna) and hit Enter to jump to the specified location.

Figure 3: Places shows all the photos in the library as clusters on a map.

PhotoPrism groups all similar faces into clusters, and you can view and manage them in the People module. Because PhotoPrism does all the heavy lifting of detecting and grouping faces during the indexing operation, you only need to add names to the created clusters.

The Moments module provides a slightly different take on presenting photos from the past. Instead of the more conventional approach of showing photos taken on the current date in previous years, PhotoPrism uses an algorithm that creates albums based on a significant number (Figure 4) of photos taken in a certain year and in a certain place. For example, if in 2017 you took a significant number of photos on your trip to Japan, PhotoPrism will create an album for them in the Moments module. In addition to that, the algorithm also finds labels with a significant number of photos and creates albums in the Moments module based on the results. The "significant number" value is determined dynamically, based on the overall number of items in the library.

Figure 4: The Moments module determines the most important moments in your life by the number of photos you took.

Navigating the library by traversing the available categories provides a convenient way to quickly locate photos that you already know where to find. But that, of course, is not always the case. This is where PhotoPrism's search functionality comes into play, and the Search section gives you access to all the search features the application has to offer. Unsurprisingly, the most straightforward way to run a search is to type the desired search term in the Search field and hit Enter. This way, you can search for people, objects in the photos, filenames, locations, and even the dominating color (Figure 5). PhotoPrism also makes it possible to filter photos using several predefined criteria, such as country, year, camera, and lens. To access the filters, click on the Expand Search triangle on the right side of the search bar and select the desired filter or filters.

Figure 5: PhotoPrism offers a wide range of filters to refine your search.

For more advanced and fine-grained searches, you can create advanced search queries using the available filters. For example, to find all photos taken after a certain date, specify the after filter in the search field as follows: after:1970-01-31. You can specify multiple filters. To find, for example, photos in a certain country before a specific date, you can combine the before and country filters: country:de before:1970-01-31. Search queries can include the OR operator. The query color:red|green will find photos with either red or green as the dominant color. The name filter makes it possible to search for filenames, and you can use wildcards with it. PhotoPrism gives you a wide range of filters, and the dedicated documentation page [2] contains a list of all supported filters along with their descriptions and examples.