Zoph/Using the commandline tools before 0.8.2

Install the perl scripts
If you are using Zoph 0.8.2 or later, the Perl scripts have been replaced by PHP scripts. Please read CLI in 0.8.2 and later.

Check the path to perl
The perl scripts points to /usr/bin/perl. If your perl is in a different place, edit the first line of the script.

Configure the database variables
Edit zophrc.sample (in the bin directory of the Zoph tar.gz) so that the following variables match the values you put in config.inc.php: $db_host = 'localhost'; $db_name = 'zoph'; $db_user = 'zoph_rw'; $db_pass = 'pass'; $db_prefix = 'zoph_';

$image_dir = '/data/images/';

And then move this file to the home directory of the user you are planning on using to import photo's. Probably your own home directory. Save it under the name .zophrc.

You can also set some defaults in this file, in this way you do not need to always provide these commandline arguments:

$datedDirs = 0; $copy = 0; $hierarchical = 0; $verbose = 0; $resolveSymlinks = 0;

Make sure the file ends with 1; Because Perl does not like it when the last assignment of the file is negative.

Copy bin/zophImport.pl and bin/zophExport.pl to /usr/local/bin
Or some other directory in your PATH.

Install the man page
A man page for zophImport.pl is in the man/ directory. Copy this to somewhere in your manpath, /usr/local/man/man1 for example.

Loading Images
This section describes the command line Perl importer. The next one talks about the web based importer.

First get some images to load. Zoph was created to manage photos taken by digital cameras (which contain info in their exif headers) but you could use anything.

You should have defined an IMAGE_DIR variable in config.inc.php during installation. For this example, I have the image service disabled and my IMAGE_DIR set to a photos directory in my home directory. I have created a symbolic link from zoph/photos (off the web server's doc root) to this directory:

> ln -s $HOME/photos /var/www/zoph/photos

You can organize your photos under this directory in any way you choose. I'll provide examples of two possible systems. Read over these minimal examples before actually loading your photos.

Minimal Examples
Within my images directory I separate things by camera and by date. I have a Kodak DC280 so I created a dc280 directory:

> pwd /home/jgeiger/photos > ls dc280

Here is one way to import photos. I store photos to be imported in an incoming directory in my home directory.

> ls ~/incoming DCP_0155.JPG > zophImport.pl --path dc280 --datedDirs ~/incoming/*.JPG

The --path flag tells the importer I want the photos to be put in the dc280 directory. The --datedDirs flag means that the photo should be put in a subdirectory based on the date field found in the photos Exif header. After running the script:

> ls dc280 2002.03.14 > ls dc280/2002.03.14 DCP_0155.JPG mid thumb

The mid/ and thumb/ directories hold images scaled down to 120 and 480 pixels respectively. If you wonder why zophImport.pl takes so long to import photos it is because it is creating these two smaller images (using ImageMagick's convert utility).

What if you don't want to use dated directories to store your images? Here is an alternative way:

> pwd /home/jgeiger/photos > mkdir christmas_2001 > zophImport.pl --path christmas_2001 ~/incoming/*.JPG > ls christmas_2001 DCP_0155.JPG mid thumb

The same result could have been accomplished by:

> mkdir christmas_2001 > mv ~/incoming/*.JPG christmas_2001/ > zophImport.pl christmas_2001/*.JPG

By not specifying a path, the importer uses the path that the photos are currently in.

Whatever way you import photos, make sure you run the script from within your photos directory (as specified by IMAGE_DIR). The importer needs to be able to correctly extract the relative path to the photos from here to be stored in the database.

Detailed Example
It is best to set as much information about photos during import so you don't have to do it one photo at a time within Zoph. I often have a directory of images to import that were all taken at the same time which makes this easy to do.

Here is what I used to load the images I took for this tutorial:

> pwd /home/jgeiger/photos > zophImport.pl --path dc280 --datedDirs --photographer "Jason Geiger" --location "Jason's Apartment" --album "Zoph Tutorial" ~/incoming/*.JPG

To use the --photographer, --location and --album parameters, corresponding records must have been previously created in Zoph. So first create a person/place/album/category using the web interface, then import using them.

What if you made a mistake, or remembered a piece of information you want to add? Pass the --update parameter so that the photos will not be inserted again:

> zophImport.pl --update --field rating=5 --field description="This is part of the zoph tutorial" dc280/2002.03.14/*.JPG

This will set the rating and description for all the photos I just imported. To set any of the fields found in the photos table (such as rating, title, description, etc.), use the --field NAME=VALUE flag.

For more info and examples about the importer, see the section at the end of this document.

Broken Images
It is not uncommon to make a mistake while loading images so that when you view the ui you see a bunch of broken images. This most likely due to an invalid path. To check, edit one of the images in Zoph and click on "show additional attributes" at the bottom. Then you should be able to see the path info. It should always be the case that WEB_IMAGE_PATH (or IMAGE_PATH) + the photo's path field + the photo's name reflects the photo's location.

You can use the importer to correct the paths for broken images:

> zophImport.pl --update --path 'dc280/2002.03.14' dc280/2002.03.14/*.JPG

If you still see broken images, check the permissions on the files and directories.

Command Line Options
Here is a list of all the fields that can be set when importing:


 * --datedDirs (put photos in YYYY.MM.DD dirs)
 * --hierarchical (put photos in hierarchical dated dirs (YYYY/MM/DD) (>v0.5) you need to also specify the --datedDirs argument, otherwise this will not work.
 * --update (update existing photos)
 * --updateSize (update the photo's width, height and size. implies --update.)
 * --updateExif (reparse and load the exif headers. implied --update.)
 * --useIds (use photo_ids not file names to identify photos for update)
 * --noThumbnails (do not generate thumbnails)
 * --album ALBUM
 * --category CATEGORY
 * --photographer "FIRST_NAME LAST_NAME"
 * --location PLACE_TITLE
 * --people "FIRST_NAME LAST_NAME, FIRST_NAME LAST_NAME"
 * --path PATH (relative to IMAGE_DIR)
 * --field NAME=VALUE (use to set title, view, description, rating, level, etc.)
 * --verbose (give more information about what's going on) (>v0.5)
 * --copy (copy instead of move photos) (>v0.5)
 * --resolveSymlinks (resolve symlinks before importing) (>=0.7)

Photos can appear in multiple albums and categories, and multiple people can be in a photo. To handle this, you can either pass a comma separated list or set the flag multiple times. Actually, you can use a comma separated list for categories and people but not for albums (since I realized that I have many albums with commas in their names and have yet to build an escape mechanism).

EXIF Fields
The following fields will be set automatically if they can be extracted from the EXIF header. They can also be set manually, using the --field NAME=VALUE flag, if you wish. This is by no means an exhaustive list of possible EXIF headers but these are the ones that have been set by the cameras I have used or that have been reported to me. The resolution and size fields are ignored, this info being instead extracted by Image::Size in the importer.


 * date
 * time
 * camera_make
 * camera_model
 * flash_used
 * focal_length
 * exposure (Exposure and Exposure time headers)
 * compression (Jpeg process and JPG Quality headers)
 * aperture
 * iso_equiv
 * metering_mode
 * ccd_width
 * focus_dist
 * comment

Further Examples
Below are a couple more examples.

Adding a list of people to a photo (if there are many people it is often faster to do this using the importer rather than through the web ui):

> zophImport.pl --update --people "Jason Geiger, Virginia Wolfe" dc280/2002.03.14/DCP_0155.JPG

People should be listed left to right, front to back. These people must already be the database. If one of the names could not be found the importer will complain.

Updating all the photos in a directory:

> find dc280/ -iname "*.jpg" -maxdepth 2 | xargs zophImport.pl --updateSize

You may want to use the --updateSize option like above if you had rotated or resized a bunch of images and wanted to get the correct dimensions into zoph. Specifying a maxdepth prevents the thumbnails from being included.

Starting in version 0.3 of the importer you can also update photos based on their photo_ids rather than names. Say you notice couple sequences of your photos have an incorrect location. You can see the photo_id for a photos in the url and it may be simpler to update based on that rather than by passing the file names:

> zophImport.pl --update --useIds --location "Yuka's House" 1562-1571 1580-1585

As of version 0.7, you can influence the way zophImport.pl handles symbolic links.

For example, you have the following files IMG_0001.JPG, IMG_0002.JPG, both taken 01-01-2007 and LNK_0002.JPG, which is a symlink to IMG_0002.JPG.

If you would import these files with zophImport.pl --datedDirs IMG_0001.JPG LNK_0002.JPG

You would have two files in 2007.01.01: IMG_0001.JPG and LNK_0002.JPG - both will be "normal" files. You will also have IMG_0002.JPG, still in its old location.

If you would import these files with zophImport.pl --datedDirs --resolveSymlinks IMG_0001.JPG LNK_0002.JPG

You would have two files in 2007.01.01: IMG_0001.JPG and IMG_0002.JPG - both will be "normal" files. You will also have IMG_0002.JPG, still in its old location.

Reducing Thumbnail Size
Based on a suggestion from Alan Shutko, in version 0.3.1 of zophImport.pl I added +profile "*" to the calls to convert. (And in 0.3.3 I commented out this since for some users multiple thumbnails were being generated for an image. I did not see this problem, maybe it was a shell expansion issue. For most people it probably works so you may want to re-enable this feature.)

From http://www.imagemagick.org/www/convert.html:

"The '+profile "*"' removes any ICM, EXIF, IPTC, or other profiles that might be present in the input and aren't needed in the thumbnail."

This can result in a significant reduction in file sizes. If you do wish to preserve the profiles, remove this argument to convert.

Also, if you wish to regenerate your thumbnails after this change to save space, you can run a command like this from your image directory:

> find. -iname "*.jpg" -a -not -name "mid_*" -a -not -name "thumb_*" | xargs zophImport.pl --update --thumbnails

ZophExport.pl
Zoph is a dynamic sort of application tied closely to the database. But sometimes you want static html files of your photos to burn to a cd or whatnot. Zoph includes a perl script, zophExport.pl, that lets you easily create static galleries.

There are numerous programs whose focus is to generate these sorts of static photo albums. Though I included a very simple built-in static album generator, zophExport.pl is primarily intended to be used with other scripts. Currently two such programs are supported:


 * album (http://marginalhacks.com/Hacks/album/)
 * BINS (http://bins.sautret.org/)

Both of these are easy to use and provided customizable interfaces.

Before you run the exporter make sure you configure it to use your database settings and image directory as described in the install doc.

A Quick Example
Here is a command that creates an export for use with the album program:

> zophExport.pl --dir "~/Winter Pics" --format album --category Snow

After the exporter finishes it's up to you to run album. zophExport.pl prints out an example command to run album which you can copy and run as is or update with your own options.

In this simple example all photos placed in the Snow category are exported. Within the "Winter Pics" directory zophExport.pl will have created a directory structure mirroring the album structure in Zoph for the selected photos.

There are only two required arguments: the directory to export to (--dir) which will be created if it does not exist, and the format of the export (--format) which currently must be either "zoph", "album" or "bins".

Selecting Photos
Fields to search by are specified in the same was as in zophImport.pl. For example, you can say

> zophExport.pl --dir "~/My Album" --format album --album "Boston Trip" --photographer "Jason Geiger" --field rating=5

Only photos I took on my trip to Boston that I rated 5 or more would be exported. By default subalbums of an album are automatically included (so my "Duck Tour" subalbum is also exported). You can disable this by passing --nosubalbums. The same goes for categories (use --nosubcategories to disable). Most fields match using the equals operator. Two exceptions are rating (which defaults to >=) and description (which defaults to like).

You can probably do most things you want by using this system, especially since you can run zophExport.pl multiple times with different parameters, and even edit the results by hand if you wish, before you run album or bins to generate the galleries.

But if you have a particularly complicated query you want to run you can just pass it in directly using the --sql argument. Your query must select * from the photos table, other than that it can be anything. If you pass a sql statement any other constraint arguments are ignored. Make sure to only pass select statements, the script does no checking to make sure you aren't deleting all your data

Here's a tip if you run a complicated search within Zoph and then want to export only those photos. After you get to the results page open up config.inc.php and set DEBUG to 2. Then reload the results page and you should see two sql queries at the top of the page. Copy the first (the count query) and replace "count(distinct ph.photo_id)" with "ph.*", append "order by ph.date asc, ph.time asc" and pass this to zophExport.pl using the --sql argument.

Choosing What to Display
By default zophExport.pl will export everything about your photos except the last modified time, the rating and the albums or categories in which the photo appears.

To prevent the display of a particular field, use the --noshowFIELD argument. For example: --noshowlocation or --noshowdescription. Passing --noshowexif prevents any exif info from being shown. (Note, however, that the BINS program extracts exif info on its own).

The exporter can translate field labels using the same language files that Zoph uses. Pass --lang /path/to/php/lang/file to enable this option.

By default the exporter creates directories to mirror the structure of the albums in which the exported photos appear. To disable this and have all the photos appear directly under the export dir use the --noalbumdirs flag.

A Simple Export
The exporter contains the ability to generate a very simple static gallery. To use the simple exporter, pass --format zoph to zophExport.pl.

There are two advantages to this format. The first is that it requires no additional software. The second is speed. The simple format is much much faster simply because it uses the thumbnails already generated by Zoph whereas album and BINS generate their own. Someone could probably alter album or BINS so that they could reuse the thumbnails.

There's not really any elegant way to change the appearance of the gallery generated by this exporter. To do so you probably would want to edit zophExport.pl. It wouldn't be too difficult to add css support but I didn't. I only wanted to spend so much time reinventing the wheel.

Exporting to Album
album is written by David Ljung Madison. http://marginalhacks.com/Hacks/album/

album is a single perl script which requires nothing more than you already have from using Zoph (ImageMagick and Image::Size). A debian package is available.

To use album, specify --format album to zophExport.pl. The exporter will create a captions.txt file in each directory that contains images.

Album is themeable and a number of themes are available from the website. I'd recommend you download a different theme, or create your own, simply because the default theme displays all of the info about a photo on the thumbnails page which can be quite a bit if you include descriptions and exif data. You specify a theme by passing -theme /path/to/theme/dir to album.

Exporting to BINS
BINS is written by Jerome Sautret, based on SWIGS, written by Brendan McMahan, which was in turn based on IDS by John Moose. http://bins.sautret.org/

BINS consists of three perl scripts: an exporter and two image/album description editors. A debian package is available. BINS requires a number of perl modules which you can get from CPAN if you need to.

To use BINS, specify --format bins to zophExport.pl. The exporter will create an image.jpg.xml file for each photo and an album.xml file in each directory.

BINS takes a source directory and a target directory. zophExport.pl will create the target directory based on the --dir you specify. It will also append ".tmp" to the target directory name and create another directory to which it will copy the images from Zoph and which will act as the source dir for BINS. You can remove this temp dir after BINS finishes. You can set the source and target directory to the same dir in BINS but you can only run BINS against that directory once, after that it will start creating thumbnails of the thumbnails, etc.

You can create a config xml file for BINS to use. I found it useful to set the defaultSize parameter to 0 (default to small images).