Tools to Generate an HTML Photo Gallery With Maps


The Leaflet-1.6 directory holds the contents of obtained from To use a new version of Leaflet, either:
  1. overlay the contents in the Leaflet-1.6 directory or
  2. make a new version-specific directory and update the LEAFLET_VERSION variable in makeRegionPageHTML.awk and makeGalleryPageHTML or
  3. drop the versioning for good, place the content in a Leaflet directory (no version qualifiers) and update makeRegionPageHTML.awk and makeGalleryPageHTML to set LEAFLET_VERSION to the null string.
The exiftool is used to extract GPS coordinates, picture size and other embedded metadata from images and videos. See Often installed as the perl-Image-ExifTool package.
The convert tool from the ImagicMagick suite is required to generate thumbnails and auto-rotate images.
The findFile utility from the FARGOS Development, LLC sandbox development utilities package is used to locate image files.
If videos are to be handled, ffmpeg is used to perform transcoding and generate poster images. See

Environment Variables

Specifies the path to the directory in which *.photo_metadata or *.video_metada files are maintained. Defaults to metaDataFiles.
Comma-separated list of region names for which links should be provided. Defaults to the special phrase AUTO, which causes createPhotoGalleryPages to determine the set of regions referenced by the meta data files that are processed and then sets the environment variable to the computed list.
Colon- or space-separated list of directories to search for referenced image data.
Colon- or space-separated list of directories to search for preferenced replacements for image data. Files found in these directories are typically adjusted versions from the originals, such as JPEGs generated from raws after color-correction.
Optional reference to a root page to be placed on each generated page.
Label to appear in root page link.

Doing Everything Automatically

To batch process a collection of photo meta data, invoke createPhotoGalleryPages with the desired arguments.

This will process all *.photo_metdata and *.video_metadata files in the directory specified by the PHOTO_META_DIR environment variable. The meta data files will first be passed over using runSedScripts with alterImagePaths.sed and wordSubstitutes.sed. Alter these as needed. The available latitude and longitude data is extracted and the images are sorted in an attempt to group photos of a particular area together.

A pass is made over each known region name and generatePagesFromPhotoMetaData is invoked with the sorted subset of images for that region.

As a final step, it loops over the regions of interest and uses generateRegionPage to create a top-level region page for each distinct region and a world map as globe.html.

Example Usage

A potentially more useful sample usage, which assumes:

is realized by the following command invocation:

createPhotoGalleryPages ‑‑regen ‑‑makethumbnails ‑‑downsize 800 ‑‑makelinks ‑‑copydir `pwd`/images ‑‑droproot `pwd`/

A more complicated setup is illustrated by the scenario of having content from different trips stored in distinct directories. The PHOTO_PATHS variable is set to point at the various trip directories.

Raw images that have been post-processed for color-correction and dust removal are stored in a common BestOf directory and the OVERRIDE_PHOTO_PATHS variable is set to its location.

# NOTE: source this file
# set environment for photo gallery generation

PHOTO_PATHS="${PHOTO_PATHS} /NASmount/pictures/Trip_2017"
PHOTO_PATHS="${PHOTO_PATHS} /NASmount/pictures/Trip_2016"
PHOTO_PATHS="${PHOTO_PATHS} /NASmount/pictures"




With these environment variables set, all of the content is processed via:

createPhotoGalleryPages ‑‑regen  ‑‑downsize 752 ‑‑copydir `pwd`/MyTrips/images ‑‑makethumbnails ‑‑makelinks ‑‑droproot `pwd`/ -v ‑‑addroot /MyTrips

Low-level Commands

Top-level generation of individual photo-and-map pages:

generatePagesFromPhotoMetaData *.photo_metadata  

which is a trivial cover script that invokes generatePhotoPage.

The generatePhotoPage script does most of the work, as it updates the image database CSV file for subsequent use in creating a region map with generateRegionPage, creates thumbnails, copies or sets up symbolic links for a directory of prepared images, rotates images if needed and transcodes videos into the MP4 format.

The generatePhotoPage script invokes the script makeGalleryPageHTML to generate the actual HTML document that will display a single photograph or video and the associated detail map indicating where the imagery was obtained.

A top-level map of a region with markers is created by the script generateRegionPage using content from the image database CSV file. It uses the AWK script makeRegionPageHTML.awk to generate the HTML page for the region map.

The script getPhotoMetaData is used to retrieve data from the *.photo_metadata files, which are in a trivial XML-like format. This trivial format has the restriction that the begin and end tags must all begin on new lines and be the sole content of that line.

Templates of photo meta data can be generated by makePhotoMetaTemplate, but the actual content is expected to be populated by hand using a text editor.

Generated Directory Structure

Individual photo pages are named similar to: regionMaps/{regionName}/imageAndMap_XXXXXX.html

The top-level map for a region is named: regionMaps/{regionName}.html

Note: Spaces in a {regionName} are converted to underscores ("_").

The createPhotoGalleryPages script generates a master page of all regions as globe.html.

Important Options

The ‑‑droproot option can be used to remove the initial part of an image path in the generated files, which is useful for removing absolute paths that reference the original filesystem locations. A common argument value is `pwd`/, which drops the path of the current working directory. Note the trailing "/".

The ‑‑addroot option can be used to add a prefix to all of the generated files, which is useful if one wants the content assembled in a subdirectory. If it begins with a "/", the generated links will be absolute; otherwise a relative link will be generated.

Drag-and-Drop Support on Microsoft Windows

The A_HOOK_from_batch_to_shell.bat Windows batch script can be used as a drag-and-drop target in Microsoft Windows File Explorer. It will invoke a Bourne shell script, currently DO_intendedCmd_makePhotoMetaTemplate.runsh, which usually means cygwin needs to be installed. The batch script can be edited to invoke a different program if similar utility is useful elsewhere.

The DO_intendedCmd_makePhotoMetaTemplate gets the target invocation program from the final part of the filename. It can be copied or used as a hard link with alternate names to invoke different programs without requiring modification of the script. It is normally called from the A_HOOK_batch_to_shell.bat script as a result of a Windows File Explorer drag-and-drop operation.

Sample Meta Data File Format

The .photo_metadata/.video_metadata file format has a trivial XML-like syntax that has two restrictions:

Both of the two file suffixes are recognized and video-related metadata can be stored in a .photo_metadata file. It is a matter of personal preference as to whether the distinct file name suffixes are used depending on the type of the source content to be displayed.

World Peace Gate at Seoul Olympic Park
The World Peace Gate was built for the 1988 Olympics held in Seoul.
South Korea

Note that content between the corresponding start and ending attribute tag may consist of multiple lines. The description content is often comprised of several lines of text.

Recognized Tags

These tags are currently recognized by createPhotoGalleryPages and generatePagesFromPhotoMetaData.

Provides text for title of image.
Provides the base name, path fragment or full path to the image or video file.
Similar to image_source, but specifies an alternate file from which the GPS coordinates to be used should be obtained. Used in createPhotoGalleryPages and generatePhotoPage. Use latlong if an explicit override is required.
Prose that describes the image.
Prose that will appear if the mouse hovers over the content.
Specifies the geographical region under which the image should be grouped.
Forces image to be resized, overriding the default. A value of 100 forces the image to be retained as original size.
Specifies the amount of time to be skipped from the beginning of a video. This requests generatePhotoPage to make a trivial cut from the start of a video if ‑‑copydir was specified.
Specifies the time point at which the video should end. This requests generatePhotoPage to make a trivial truncation of the video if ‑‑copydir was specified.
Specifies the latitude and longitude as comma-separated elements. Takes precedence over any GPS data embedded with the source image/video and use_location_from.

Additional user-defined tags can be used without breaking existing scripts.

Program Dependency Tree

The hierarchy of programs appears as illustrated below:

Graph of Program Hierarchy
Dependency chain of photo/video gallery generation tools


Questions can be sent to:

Geoff Carpenter