PhotoTrove User Manual

Copyright © 2018, 2019, 2020, 2022, 2023, 2024 Theodore B. Ruegsegger. The source components of this document are written in asciidoc markup and used to generate a finished manual in HTML, PDF or other formats as needed.

Now that we all have digital cameras that never run out of film, more and more of us are finding it difficult to keep track of all our photos and videos. It’s easy to accumulate tens of thousands of photos in a short time, and sticking them into labeled folders on our computers works about as well as when we kept our prints and negatives in shoeboxes. Why not use all this computer power to do the housekeeping for us?

PhotoTrove uses an industrial-quality database management system to keep track of every photo and video in a large collection, with detailed descriptions, timestamps and locations so you can find them easily, edit them, group them, compare them, arrange them and conveniently publish them. It includes a comprehensive search tool as well as easy handoff to your favorite photo-editing tools.

PhotoTrove runs as a web application on your local network, so multiple users can work independently and simultaneously. Anyone whose browser can see the PhotoTrove server
[Server: Don’t be put off by the word server; PhotoTrove can easily run on the same machine as your browser, perhaps as a virtual machine running on your laptop.]
can view photo sets and albums, carry out searches and download individual photos, but only authorized users can change anything. Since all the data is in one place, it’s easy to set up automatic backups so you can be confident your valued photos are safe.

PhotoTrove is designed to serve clients on an internal network (or a single machine), not the open Internet.

While PhotoTrove does let you assemble photos and videos from anywhere in your collection into albums for publishing, the resulting albums are nothing fancy, just a series of linked pages containing your photos, videos and captions that can be burned to a CD or DVD, copied to a thumbdrive or uploaded to a static website. There are many applications as well as web services available that let you arrange a set of photos into a visually stunning album. If that’s what you want, use PhotoTrove to find and collect the particular photos you want and then hand them off to an album-finishing tool or service.

With PhotoTrove and your favorite web browser, you can:

Here and here are some sample albums produced using PhotoTrove and its predecessor the Photo Album Manager. Note that they make little use of style sheets, but that can easily be added. I welcome suggestions for a nice default style, or perhaps a set of user-selectable styles. Naturally, I also welcome URLs for sample albums to add to this section.

PhotoTrove is a web application written mainly in PHP using the Apache web server and the PostgreSQL database management system. It also makes use of the GraphicsMagick graphic tool collection, the ffmpeg video converter and the oggvideotools set, the MPlayer video player/analyzer, the ExifTool metadata reader, and traditional Unix tools like Bourne shell, cat, grep, sort, tr and sed.

For more details, see the Architecture and Design appendix.

This collection of program code and documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This collection is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this collection; if not, write to the Free Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Depending on the camera and client computer (the one from which you’re connecting to PhotoTrove, not the server
[Client: As noted previously, the client and server could be the same machine.]
) platform, there are several ways to access the photos. Most cameras have a folder named dcim or DCIM, per the Digital Camera IMages specification, containing one or more subfolders with images.

Whatever you do, verify that your computer sees a dcim folder, preferably as the top of the mounted flash drive.

This also depends on server configuration, client platform and camera.

Below the action widgets you’ll see a thumbnail gallery of all the photos and videos in the set. Things you can do here:

Clicking any individual thumbnail opens the webpic view in a separate tab.

Things you can do here:

Note that in the webpic view, clicking on the right or left margin of the image moves forward or backward through the photo set. For videos, small navigation arrows below the video server the same purpose.

Finally, back on the Photo Set Worksheet page, you can click the Edit Notes button to annotate the photo set as a whole. You can enter a nickname, which is any descriptive text that helps you identify the set. You can also enter any notes you wish. If you’ve entered locations and descriptions for all the photos, the Summarize Descriptions button will be a good start. Be sure to save changes.

Much of the time, we look for photos taken around the same time, in photo sets. If we’ve named the sets with timestamps and given them helpful nicknames, they’re easy to find.

From the main menu, select View photo sets and scroll through the menu.

When you select a set, you’ll see the notes followed by the thumbnail gallery.

If you’re logged in, you’ll see an Edit Set button to the right of the notes. Clicking that will open the familiar Photo Set Worksheet page.

Clicking on an individual thumbnail opens the webpic view (but without the editing widgets).

To show off our photos, we look through our photo albums. From the main menu, select View albums and scroll through the menu. When you select a photo album, you see the finished product.

Creating and editing photo albums is covered below.

The real power of PhotoTrove is the search screen, Search for photos in the main menu. You can specify just about any criteria and find all photos that match.

After you press Search you’ll see the familiar thumbnail gallery of matching photos. If you’re logged in, you’ll see the selection buttons and action options above the gallery.

If your search finds more matches than the specified limit (Limit results near the bottom) PhotoTrove automatically checks the box Display only first and last matches which not only does precisely that but, if you’re logged in, automatically selects all matching photos for action.

Having all your photos neatly annotated and accounted for is better than having a shoebox full of prints, but it doesn’t offer much flexibility when you want to display them. For that, you’ll want to organize your best photos into albums. Your audience can browse albums directly in PhotoTrove, or you can upload them to a static website, or you can burn them to a CD, DVD or thumbdrive, viewable on any computer.

All album operations (except just viewing one) assume you’re logged in to PhotoTrove.

You could just select Edit albums from the main menu, type an album name
[Album name: An album name must be a legal file name, an alphanumeric followed by alphanumerics, underscores or hyphens, with no embedded spaces or “weird” characters. Not to be confused with the album’s title, which can be pretty much anything.]
into the field at the top and click Create, but most often you’ll just create an album on the fly as you add photos to it:

Adding photos to an already-existing album works exactly the same way, except that you choose the album from the menu.

From the main menu, open the Edit albums tool and select the desired album. The Album Worksheet page displays all the photos on Page 0.

Page 0 serves two purposes:

You create album pages by moving photos to them. You can rearrange the photos on a particular page using the drop-down position numbers in the corner of each thumbnail.

Of particular interest is the Edit Page Text and Format button, which opens a separate tab where you can set the color scheme for the entire album and heading, text, and title picture for each page.

You can, at any time, see how the album will appear to others by clicking View Album.

There are innumerable ways to group photos, some temporary:

Some long-term:

PhotoTrove lets you make up any number of descriptive tags, attach them to any photos you wish, and then treat the tagged photos as a group:

It’s easy to download an individual photo from PhotoTrove to your client machine, whence you can email it, upload it to a website, or post it to your favorite social media site. You need not be logged in to do it.

In any thumbnail gallery, click on the desired image to open the webpic view. You now have a choice:

For videos, there’s a similar choice, not of size, but of the video/audio encoding scheme (or “codec”).

Once you have an album built, you can view it at any time; the separate pages will be generated on demand. You can also use PhotoTrove to write all the data to its own folder as a set of static web pages, which you can then upload to a static website or burn to a CD, DVD or thumbdrive. And yes, everything will still work, including the video player.

To publish an album:

You can write more than one album, in which case PhotoTrove automatically updates the index.html file with links to each one.

To retrieve a written album from PhotoTrove server, select the one you want from the Download ZIP file of an album menu, then click Download.

At this point you can unzip the file and

If you’d like to display the album on the web but don’t have access to a website, you have some options:

When you’re logged in, it’s a good idea to click the Export database tool in the main menu every so often, and certainly before you log out at the end of a session. This saves the entire database as a specially-formatted text file from which the database management system can rebuild everything. Database dumps will accumulate under /home/public/dumps/ but don’t worry; older ones get purged so there will never be more than 8 dump files.

You need a place to save the photos and database dumps.

Whatever method you use:

The general idea is to take a series of shots, either left-to-right or right-to-left, with some overlap (say a third) between each photo and the next. Keeping the whole series level is tricky, and a tripod can help here.

Many cameras offer features (“panorama assist” or “stitch assist”) to help align successive images with consistent focus and exposure. Moreover, they identify photos that are panorama components with distinctive filenames or even separate folders, as well as including some indicator in each image’s EXIF caption.

Some cameras and smartphones let you create a panorama on-the-fly, carefully rotating the camera in place. Again the image’s EXIF caption will contain some indicator.

But if your camera lacks those features, don’t despair; a little practice will do the job well enough that the increasingly-smarter panorama stitching software can take care of the rest.

Whenever you import a photo set containing panorama segments, be sure to tag them with “panorama-to-do”. PhotoTrove will do this automatically whenever the EXIF caption so indicates.

The Add single photos/videos does just that. First select the target photo set, then browse for the photo or video you want to add. Click Upload File, enter the appropriate metadata and add the new image.

A photo set is the most basic grouping for photos and videos. Analogous to rolls of film, photo sets contain sequences of images taken during a single time period or at a single location. Photo sets can be fragmented: vigorous culling of similar photos can leave a photo set all but empty; a trip may start in the middle of one set and go on to span several later ones; some cameras start a fresh folder after a set number of shots or for every panoramic sequence. In such cases, some housekeeping can help organize photo sets more logically and efficiently.

When a photo set contains no more photos, perhaps because you’ve deleted the last one or moved it elsewhere, you’ll see a button offering to delete it.

Of course, this won’t affect the original folder under originalphotos, but don’t worry, PhotoTrove remembers the folder names of deleted photo sets so they don’t reappear in the menu of folders to import!

Photo Trove saves photo timestamps in Coordinated Univeral Time (UTC) and displays them in the current local time
[Local time: this means the time zone of the PhotoTrove server (just in case you’re using PhotoTrove from far away!)]
. Sometimes photo timestamps are incorrect by a fixed amount, perhaps because the camera’s clock was set to a different time zone or because the clock was simply wrong. The Adjust timestamps tool adjusts the timestamps for any number of photos in a single action.

Sometimes photos have no timestamps, for example, digital scans of slides, negatives or prints. In such cases, the approximate date may be known, though not the precise time. The Apply dates tool applies a date (with time 00:00:00 local) to selected photos.

Many cameras and smart phones now use the Global Positioning System (GPS) to tag photos and videos with latitude, longitude, and altitude (“geotagging”). PhotoTrove captures this information from any photos or videos newly added to the collection, records it in the database, and displays it along with the named location as a hyperlink to geohack.toolforge.org so that you can see the location on your choice of map.

If your collection contains photos and videos added before PhotoTrove acquired this capability but which might be geotagged, you can use the “capture geo-data” tool to extract and record whatever geo-data they contain. The tool accomplishes this by examining the metadata in the actual image or video; this can take some time for a large number of them, so try it with small batches first.

The Manage locations tool lets you:

The Manage tags tool lets you:

In addition to the regular album-editing operations, the Edit albums tool offers some occasionally-used housekeeping features. You can:

If you carry a laptop with you when you travel, you could install PhotoTrove on it—either directly or inside a virtual machine like Trovester—and then while away your evenings uploading photos and editing photo sets. But how do you get all that into your regular PhotoTrove server when you return home?

The answer is to configure your laptop PhotoTrove as a “travel version”, set up exactly like the regular server except that the root is one directory down, that is:
/home/web/webroot-ssl/trove/tvl/
instead of
/home/web/webroot-ssl/trove/

To set it up:

When you return from your travels:

Occasionally you might wish to make several similar albums, perhaps with a slightly different mix of photos, or a different text or page arrangement, but otherwise the same. The simplest way to accomplish this is to build an album as a “baseline” or “template”, make copies of it, and then modify the copies as needed.

Since an album is entirely a database construct, a script can do this.

Run the script:
sh clonealbum.sh database albumname newalbumname
where:
database is the name of the database, normally trove
albumname is the name of the original album to be cloned
newalbumname is the name for the new album to be created.

Sometimes you don’t need to clone a whole album but you might want to copy or move a page or two from one album to another.

Run the script:
sh copypagebetweenalbums.sh database album1 page album2
where:
database is the name of the database, normally trove
album1 is the name of the album that has the page
page is the number of the page to be copied
album2 is the name of the album to receive the copied page.

PhotoTrove appends the desired page as the last page of album2. Use Edit albums to move the page where you want it.

PhotoTrove comes as a zip file; when unpacked, it contains a tree of the following folders:

The PHP code (under web/ in the distribution) resides under Apache’s SSL service (https://) document root. My recommended location for PhotoTrove’s code (and where EasyPhotoTrove puts it) is /home/web/webroot-ssl/trove/. The “regular” service (http://) tree contains, at /home/web/webroot/trove/index.php, a redirector page that switches to the SSL tree.

Four data subfolders are added within PhotoTrove’s code folder /home/web/webroot-ssl/trove/ at installation:

I maintain the data model using pgModeler, which automatically generates the schema-building SQL scripts and ERA diagrams:

The central entity in the PhotoTrove model is, not surprisingly, the photo. Every photo is contained in a photoset, a sequential series analogous to a roll of film. A video is a separate entity associated with a single photo that serves as its still image, or thumbnail.

The location entity allows for a user-defined list of locations where photos are taken. Users may also define tags and apply them to photos to support complex groupings.

The primary product of PhotoTrove is photo albums that present collections of photos for display and distribution:

An album comprises one or more albumpages, each of which can contain any number of albumphotos. Each albumphoto is an instance of a photo in a particular position on a particular albumpage.

Albums, locations and tags may be archived; this means simply that they don’t appear in menus, but can be restored to regular status when needed again.

A separate ERA diagram depicts the common underlying architecture of GAPPKit applications, documented elsewhere:

If your computer is of relatively recent vintage, you can probably run Trovester, but check this list just to be sure:

This boils down to installing VirtualBox, importing Trovester as an appliance, setting its network address, and defining the shared folder: