Documentation

Converting Images and Videos for Web Use

You put all your original photos and videos in a directory (or a series of sub-directories within a directory). This directory is called your origin directory and represents the full, original high-resolution versions of the photos and videos. The gallery plugin then takes this directroy structure and creates a destination directory which contains 6 sub-directories, each mirroring the directory structure of the origin directory, but containing different content. The sub-directories are named as follows:

stills

One frame stills of the each of the videos

h264

Flash Player 9/10 compatible videos

1024

Photos resized to a maximum size of 1024x1024

150

Thumbnails 150x150 zoomed in on the centre of the photo to make a square and slightly sharpened

exif

The EXIF/metadata extracted from each of the original files

meta

Extra metadata I want to add to the photos or videos

The thumb command takes the origin directory and creates the destination directory structure. It then converts files from the origin directory or extracts information so that it can populate the stills, h264, 1024, 150 and exif directories. It doesn’t popualte meta because that is designed for metadata you write yourself.

The commands to perform the conversion look like this:

python -m gallery convert --gallery-exif /path/to/origin /path/to/dest
python -m gallery convert --gallery-still /path/to/origin /path/to/dest
python -m gallery convert --gallery-reduced /path/to/origin /path/to/dest
python -m gallery convert --gallery-thumb -y video.png /path/to/origin /path/to/dest
python -m gallery convert --gallery-h264  /path/to/origin /path/to/dest

Tip

Don’t start off the thumbnails until the stills and reduced pictures are finished, otherwise you may not get the correct orientation on the thumbnails.

Remember the -o video.png option for generating thumbs if you want a video overlay.

Tip

You can replace python -m gallery convert with due thumb if you are using sitetool directly.

Depending on the size of the origin directory this command could take minutes, hours or weeks to run as it does a lot of processing.

• For detailed output you can also use the -v option.
• You can run the command more than once to pick up where you left off. The commands don’t over-write existing files.
• The 150 thumbnails are produced based on the 1024 directory files and the stills from the video, so they have to be present first.

Note

For the command to work you need to install some command line tools including convert, ffmeg and exiv2. This isn’t very straightforward but is described for Ubuntu Intrepid at http://jimmyg.org/blog/2009/building_a_gallery.html.

Photo Metadata from a CSV File

Next you can add metadata about the images and galleries. The metadata will be displayed along with the photo on individual pages and can be used to determine which photos appear in which galleries.

The metadata command extracts metadata for photos from a spreadsheet saved in a special .csv format and populate the meta destination directory.

The first row of the spreadsheet represents the labels of the metadata. If there is a Category column, it can be used to decide which gallery the photo or video should be used in. The spreadsheet must have a Filename column containing the relative path from the origin directory to the photo.

You can create the metadata files from a CSV file like this:

python -m gallery csv -F photo photos.csv /path/to/dest/meta

Tip

You can replace python -m gallery csv with due metadata if you are using sitetool directly.

Here the second argument is the path to the meta directory within the destination directory.

Note

All the required sub-directories need to already exist.

Creating Galleries from a CSV File

You can also create galleries in two ways:

1. With the csv sub-command using the -F gallery option
2. With the autogen sub-command
3. Manually

Either way, what you wnd up with is a text file with a .gllery extensions containing information about the gallery which you can put on your website. Using the SiteTool program’s gallery plugin you can then convert the gallery file into a series of HTML pages for viewing the thumbnails, photos and videos the gallery contains.

From a CSV file

The first row of the spreadsheet should be the column titles and the spreadsheet must contain the following columns:

Path

The name to use for the gallery (the URL path)

Title

The title of the gallery

Description

A description of the gallery

Index

The relative path from the root to a thumbnail to represent the gallery

As the file is being parsed, the data in the meta directory is read and the Category field is used to determine which photos go in which galleries so the photo metadata ust exist before you run this command.

Here’s how to create galleries from a spreadsheet called galleries.csv

python -m gallery csv -F gallery galleries.csv /path/to/galleries /path/to/dest/meta

From the Directory Structure

You can also scan the meta directory structure and generate galleries from it. First you have to populate the meta directory:

python -m gallery convert --gallery-meta /path/to/origin /path/to/dest

Then generate the galleries:

python -m gallery autogen /path/to/dest/meta galleries

Tip

You can replace python -m gallery autogen with due gallery if you are using sitetool directly.

This command will create a different folder and index.gallery file for each directory in the structure which is usually what you want. You can then move these folders to your website.

Note

The meta directory containing the metadata comes before the output in this command.

The idea is that you then edit the index.gallery files produced so that your galleries have the correct information displayed about them. By default they will just be titled according the directory name and have the description Auto-generated gallery.

If you want to edit the photo metadata you can edit the corresponding file in the meta directory.

After any changes you’ll need to regenerate the gallery.

Manually

You can also create galleries manually by creating an empty directory and placing an index.gallery file within it in the correct format which looks like this:

Path       : trevor
Title      : Trevor's Photos
Description: Auto-generated gallery
Index      : Photos 8/2008-10-21 Malta/Trevor/SANY1272.JPG
photos     : Photos 8/2008-10-21 Malta/Trevor/SANY1272.JPG, Photos 8/2008-10-21 Malta/Trevor/SANY1273.JPG, Photos 8/2008-10-21 Malta/Trevor/SANY1274.MP4,

Notice that the photos option is a comma separated list of photos and videos in the order they need to appear in the gallery. The paths are all relative to the PHOTO_DIRECTORY config option you’ll learn about in the next section.

Converting Galleries to HTML Pages

Now that you have the .gallery files you need them converted into HTML pages. This is done using SiteTool. First you need to add some options to the configuration file you are using for your site.

Configuration

You need to set the destination path and the gallery root in the config file. Here’s how a section looks:

<tr>
    <td><tt>PHOTO_DIRECTORY</tt></td><td>Base directory for binary photos</td><td>bin/photos</td>
</tr>
<tr>
    <td><tt>GALLERY_DIRECTORY</tt></td><td>Base directory for the gallery itself</td><td>life/photos</td>
</tr>
<tr>
    <td><tt>GALLERY_TEMPLATE</tt></td><td>Gallery template</td><td>Templates/jimmyg.dwt</td>
</tr>

The idea here is that there will be a gallery section on your website where all the galleries will be put. The GALLERY_DIRECTORY is the path from the site root to where this gallery is and the PHOTO_DIRETORY is the path from the site root to your destination directory. GALLERY_TEMPLATE specifies which template you wish to use.

Structuring Galleries

You can place galleries within other galleries or in nested directory strucutres. When the galleries get converted, the converter will automatically build any index pages which are necessary, using the index files from galleries if possible, and using a folder icon otherwise.

Caution

If you don’t specify GALLERY_DIRECTORY correctly in the config file, Gallery won’t know which directories to automatically generate index pages for so you won’t be able to nest galleries within other directories properly.

Conversion

Once the .gallery files are in place and the configuration is set up you can convert files as usual with the SiteTool convert sub-command in your website site root:

due convert -c about.html -ugrC -S life/photos

Deploying

You probably don’t want to upload all the files in the bin directory, just those used in galleries.

You can get all the orphaned files like this:

due orphan -c about.html --relative > exclude.txt

Then you can deploy all but the uploaded files like this:

due deploy -c about.html --exclude-from exclude.txt

Useful Commands

Here are some other commands I’ve found useful.

Get a list of all origin files which need rotating:

due thumb /home/james/Desktop/Archive/Photos/ bin/photos/ -y /home/james/Desktop/Cur/CommandTool/trunk/example/gallery/video.png -v --gallery-still --gallery-meta --gallery-exif --gallery-reduced --gallery-thumb

Delete all files in a list relative to the current directory:

cd dir_with_files_to_delete
cat to_delete.txt | xargs rm

Possible Improvements

-r fps Get the actual video size from the thumbnail size