Zoph 0.3.3 Manual
13 Dec 2002

This manual will describe how to start using Zoph.  It assumes you have
successfully installed all the components and are presented the logon
screen when you visit http://localhost/zoph/logon.php.

Prior to version 0.3.3 this document was referred to as the tutorial.


1. Logging In For The First Time
================================

An admin user was created when you loaded the database.  You should be
able to login as 'admin' using the password 'admin'.  You will be
presented with Zoph's home page where you will be greeted as 'Unknown
Person'.  There will be a blank square where a random photo would
normally appear.

The first thing you should do is change the admin's password:

1. Click on the 'prefs' tab.
2. Click the 'change password' link.
3. Enter a new password and click 'submit'.

Next, create a 'person' record for yourself:

1. Click on the 'people' tab.
2. Click on the [ new ] link on the right.
3. Fill in your first name, last name and whatever other fields you wish.
4. Click the 'Insert' button.

Now create a user for yourself:

1. Click on the 'users' tab.
2. Click on [ new ].
3. Pick a username and password.
4. Select yourself from the person pulldown.
5. Change your class to Admin.
6. Click the 'Insert' button.

An admin has permission to do anything so you don't need to grant the
specific 'browse' or 'view details' permissions, nor grant permissions
to individual albums.

Now that you have created a user:

1. Click on the 'logout' tab.
2. Login as your user.


2. Creating An Album, Category and Place
========================================

Before importing some images we'll create an album to put them in.  Note
that you do not need to assign photos to an album if you don't want to.

To create an album:

1. Click on the 'albums' tab.
2. Click on [ new ].
3. Pick an album name.  I'm using "Zoph Tutorial" for this example.
4. Add an album description if you wish.  This can be left blank.
5. Click the 'Insert' button.

To create a category, click on the 'category' tab and do exactly as above.
In creating this tutorial I took a picture of my hand so I created an
"Appendages" category for it.

Both albums and categories are hierarchical in nature (each entry can have
children entries as well).  When you view photos in an album or category
within Zoph you automatically see photos placed in that album or
category's children as well.

To create a place:

1. Click on the 'places' tab.
2. Click on [ new ].
3. Enter a title and city at minimum.
4. Click the 'Insert' button.


3. 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.

3.1 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.

3.2 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.

3.3 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.


4. The Web Based Importer
=========================

The web based importer is a new template in Zoph 0.3 that provides an
alternative to the command line importer, zophImport.pl.  This template
does not yet contain all the functionality of zophImport.pl.

To use the importer, WEB_IMPORT must be set to 1 in config.inc.php and
you must be logged in as either an admin or a user that has been granted
permission to import.

If you are going to be importing directories of photos you will probably
need to increase the size of max_execution_time in php.ini.  The default
is 30 seconds but you will probably need this to be a couple minutes or
more, depending on how many images you import and how fast your computer
is.

If you are running PHP >= 4.2, the importer will try to read the EXIF headers
of the images you are loading.  Beware that if you specify a date and an
EXIF date header is found, the EXIF date will overwrite your date field.

4.1 Importing Images
--------------------

Files can be loaded in two ways:

1. Importing a Local File - a local file means one on the same computer as the
person using Zoph (and not, necessarily, the computer running Zoph).  The
image is uploading using HTTP and is copied to the destination path.  The
file may be an image or a zip or tar archive.  The images should not be
placed in any directories within an archive.

To be able to upload archives you need to define the programs with which to
do the extraction in config.inc.php.  Example are given.  Archives are
extracted to a temporary directory created with the EXTRACT_DIR defined in
config.inc.php.  This directory should be writable by the webserver.  The
zip or tar files themselves are copies to the same location as the images
and are not removed by Zoph.

2. Importing Files on the Server - the uploading step can be skipped for files
already on the server running Zoph.  This method also allows you to load a
directory of images at once.  Specify an absolute path in 'file/directory'.

If you are loading a directory of images, the fields you specify will apply
to all of them.

4.2 File And Directory Permissions
----------------------------------

In order to copy images and create thumbnails Zoph needs write permission to
the directory you are importing to.  The simplest but least secure way to do
this is to give the import directory 777 permissions.  Alternatively, you
could try creating a new group, put yourself and the webserver user in that
group, and give the group write permission to the directory.

Files and directories are affected by the IMPORT_UMASK in config.inc.php.
The default setting is 0 which leads to files with 777 permissions.
Directories are created with DIR_MODE permissions, the default is also
777.

So by default everything created by the importer is open to everyone.
Beware!


5. Viewing Photos
=================

Now that there are some photos in the database, I'll go over some features of
the web interface.  The UI is fairly self explanatory so you probably don't
really have to read this section.

5.1 Finding Photos
------------------

There are numerous ways to find the photos you just entered, a few of which
are:

1. Browse to the album you created and click [ view photos ].
2. Browse to yourself in 'people' and click [ photos by ].
3. Browse to the place you took of photo and click [ photos at ].
4. Use the search form.  Specifying no criteria will bring up all photos.
5. Use the 'photos' tab and you can browse every photo in Zoph.

5.2 The Results Page
--------------------

By default the results page will show thumbnails of up to 12 photos (you
can change this from the 'prefs' page).  On the prefs page you can also
choose whether or not to display descriptions under the thumbnails.

From this page you can:

1. Click on a thumbnail to go to the photo page.
2. Click on [ Prev ] or [ Next ], or use the pager, to page through the
   photos (if your results span more than one page).
3. Click on [ Slideshow] to enter slideshow mode.
4. Reorder the photos by choosing a field from the pulldown.
5. Change the direction of ordering by clicking on one of the triangles.
   The white triangle/arrow represents the current direction.
6. Change the number of rows and columns displayed.

5.3 The Photo Page
------------------

Here you'll see a mid sized version of the photo plus all the information
about the photo available.

From this page you can:

1. Click the name of the file or the image itself to bring up the full
   sized photo.
2. Click on a person, place, album, category or date to take you to the
   corresponding pages.
3. Click on [ Prev ] or [ Next ] to move through the photos as they appeared
   on the results page.
4. Click on [ email ] to email the photo (if EMAIL_PHOTOS was set).
5. Click on [ lightbox ] to add the photo to your lightbox (if you have one)
6. Click on [ edit ] or [ delete ] (if you are an admin or have been given
   write permission on the album in which the photo appears).

If you set the auto edit pref, you will automatically be presented with
fields to edit the info about a photo whenever you click on a thumbnail.
Clicking [ return ] takes you back to the regular view.

5.4 Slideshows
--------------

The slideshow mode (entered from the results page) will cycle through the
current set of photos by refreshing the browser window.  The interval
between refreshes can be set on the 'prefs' page.

From the slideshow page you can:

1. Click on [ pause ] to pause the slideshow.
2. Click on [ stop ] to return to the results page.
3. Click on [ open ] to view the current photo on the normal photo page.

5.5 The Search Page
-------------------

You can search for photos using multiple criteria on the search page.
Note that when you select an album or category, all descendant albums or
categories will also automatically be chosen.

By default all criteria are joined by "and".  You can choose "or" instead
from the pulldowns in the left most column.  Since you can not specify
groupings of the conditions, you might not get the results you want if
you try to construct complex queries using different conjunctions.

Note that the album, category, location, person and photographer menus
are pruned so that only those entries that actually appear in a photo
that the user has access to are shown.

5.6 Random Photos
-----------------

The thumbnail that appears on the 'home' page is randomly selected.  I tend
to like this photo to be somewhat good so I created a setting on the 'prefs'
page that lets you specify the minimum rating to be used when selecting a
random photo.

If you want to create a never ending slideshow of random photos, you can do
this by clicking the "randomly chosen photo" link on the home page.  If you
then click the [ Slideshow ] link on the results page a new random photo
will be chosen for each slide.


5.7 Lightboxes
--------------

Lightboxes give someone a place to gather and share their favorite photos.
In Zoph, lightboxes are simply albums.  When editing a user, an admin can
declare a certain album to be the lightbox for that user.  The admin must
grant the user permission to view the lightbox album as well.

IMPORTANT: Don't give a user write permission on their lightbox album.
The user could then add any photo to their lightbox and be able to edit
it.

Whenever the user views a photo they can click a 'lightbox' link which
will add that photo to their lightbox.  When a user is viewing their
lightbox, each photo will have an 'x' below it.  Clicking this will
remove that photo from the lightbox.

Lightboxes allow users to gather photos of interest to them without
requiring the ability to edit a photo to place it in an album.

Lightboxes are only activated for a user by specifying a lightbox album.
The setup I used was to create a "Lightbox" album, under which I created
separate albums for each user's lightbox (e.g. "Jason's Lightbox").

To share a lightbox an admin must grant permission to that album to other
users.


6. Managing Users & Restricting Access
======================================

One of the features of Zoph is its system of access privileges.  You have
already created an admin class user for yourself.  If you desire, you can
create other users as well.

6.1 Users
---------

A description of some of the attributes of users follows:

- user name: the name for account (e.g. first initial + last name).
- person: every account must be associated with a person.  You can use
  "Unknown Person" or create a similar person record for generic
  accounts.
- class: an Admin can do anything at all.  A User has restrictions.

The following only apply to non-Admin users:

- browse people: the user can view the 'people' page in which all the
  people stored in the database can be seen.
- browse places: the user can view the 'places' page in which all the
  places stored in the database can be seen.
- details of people: if "Yes" the user can see all information about any
  person.  If "No" the user will only see a person's name.
- details of places: if "Yes" the user can see all information about any
  place.  If "No" the user will only see a place's title and city.
- import: if "Yes" the user can import photos
- lightbox: the user's lightbox album

6.2 Albums
----------

For non-Admin users, permissions to view photos are granted on a per album
basis.  For each album you grant a user access to, you must specify:

1. An access level
2. Whether that album will be writable

Zoph determines whether a user has access to a photo checking two things:

1. Is this photo in an album that the user has access to?
2. If so, is the user's access level for that album greater than or equal to
   the level of the photo?

If both of these conditions are met, the user has access to the photo.

If a photo appears in more than one album, a user needs only to have
permission on one of them to see the photo.  If the user has access to
multiple albums in which a photo is found, the least restrictive (highest
access level) permission is used.

The level of a photo (and therefore of access levels) can range from 0 to 10.
The default access level is 5.

Zoph is designed so that these privileges should work transparently.  It
should appear to any user that they have access to all photos.  There
should be no reference to any album or photo (including photo counts) to
which a user does not have access.

If an album is marked writable, that user may edit (but not delete) the
photos that they have access to in that album.

If you want to grant a user access to all albums you can do this all at once
and the access level and writable flag will apply to every album.  This is
handy if you want to let someone see everything but don't want them to change
anything.

Note that when you create new albums you will have to grant permissions to
any non-Admins before they will be able to see those album.

6.3 Scenarios
-------------

Say you create an account for your parents but you don't want them to see
the photos in the "New Years Party" album.  Simply don't grant them
permission to that album.

However, say the photos in this album are mostly harmless, except for a few
that you would like to keep hidden.  In this case, change the level of those
photos to 6 (or higher) and grant the user permission to the album with an
access level of 5 (or less).

6.4 The Image Service
---------------------

If you plan on having multiple users of Zoph and you are planning on
hiding some pictures or albums from some users, you may want to turn
on the image service in config.inc.php.

The simplest and fastest setup is to have the images served by the web
server.  However, this requires that the images are accessible to the
web server.  And if this is true, they are also accessible to any user.
Even if the application never links to a photo that a user should not
be allowed to see, that user could still view that photo (or any photo)
by simply typing its url directly into their browser.  Since the image
names tend to follow a well defined pattern, it would not be too
hard for someone to just guess image names and see what came up.

One solution to this problem is to have the application serve the
images rather than the web server.  This is what the image service
does.  If is is used, the IMAGE_DIR defined in config.inc.php should
NOT be reachable by the web server.  The image service will instead
set the proper headers and read out the file itself.

Unfortunately, this makes Zoph slower and can make handling the images
more cumbersome.  If you don't care about people seeing all of your
images, don't bother with the image service.

6.5 But Don't Trust Me
----------------------

Zoph has all these privilege mechanisms, but don't trust them too much to
keep your secret photos hidden.  It is beta software and hasn't been tested
nearly enough for you to assume you'll be protected.

6.6 Defining a Default User
---------------------------

Starting with Zoph 0.2.1 a default user can be defined.  This user is
automatically logged in when a person first opens Zoph in their browser.

If you use Zoph locally you may want to make yourself the default user so
that you never have to bother logging in.  You may also want to use this
feature to create a guest account with limited permissions.

To create a guest user, first create a person record to associate with the
user (this could just be first name Guest, last name User).  Then create a
guest user, grant that user whatever permissions you want and set the user's
preferences.  Whichever user is defined as the default user is unable to
modify their preferences while they are the default.

You will now need to find the user_id of your guest user.  The simplest way
is probably to look at the url when you are viewing the users's record in
zoph (user.php?user_id=3).

The default user is defined in config.inc.php:

      // set to the id of a non admin user or to 0 to disable
      // note that this is a user_id, not a person_id
      define(DEFAULT_USER, 3);

That's it.  Now when you hit /zoph/zoph.php for the first time you'll be
logged in as the guest user (if you are already logged in as someone you'll
first have to log out).  You can also log out when you are the guest user
to be able to log back in as someone else.

What if a guest hits logout and wants to get back in but doesn't know the
guest account info?  Hitting submit on the logon page without specifying a
user name or password will log you in as the default user.


7. Preferences
==============

A user can customize Zoph using the preferences page.  Below are
descriptions of a few of the prefs.

7.1 Breadcrumbs
---------------

Between the tabs and the title bar you'll see a list of breadcrumbs by
default.  On the prefs page You can specify the number of breadcrumbs
to show or you can choose to disable the breadcrumbs completely.

One note about breadcrumbs: clicking on the small x to the right of the
breadcrumbs will clear the list of crumbs.

7.2 Choosing a Language
-----------------------

The default value is 'Browser Default'.  This means that Zoph will try to
present itself in the language you can specify in your browser's settings.
If no translations are present for any of the languages in your browser's
list, English will be displayed by default.

If you specify a language on the prefs page instead of 'Browser Default'
your setting will override whatever you have your browser set to.

If you would like to provide a translation for another language please
let me know (zoph@nother.net).  The language files are stored in php/lang.
Creating a new translation involves creating a file in this directory
with the language's two letter code.  Use one of the existing (non English)
language files as an example.

7.3 Other Prefs
---------------

Here are descriptions of a few of the other prefs:

- days paste for recent photos links: the home page has links to view
  photos taken or modified in the past X days, this pref sets the number
  of days.
- display camera info: if set to No, when viewing the details of a photo,
  fields like camera make and model, focal length, exposure, etc. are not
  displayed.
- automatically edit photos: if set to Yes, when an admin or a user with
  write permission views the details of a photo, they are immediately
  taken to the edit screen.  This is handy for editing one photo after
  another.
- color scheme: the color scheme to use.  Admins can click on "color
  scheme" to add, edit and delete color schemes.


8. Backing Up Your Data
=======================

It's always a good idea to back up you photos.  Periodically sync them to
another machine or burn them to a cd.  Zoph should never delete your photos,
when you delete something from the ui only the database record is removed.

You should also periodically export the database.  After you spend hours
inserting and updating photos into Zoph, take two seconds and do the
following:

> mysqldump -u zoph_admin -p zoph > zoph-`date +%Y%m%d`.sql


9. The Exporter
===============

Zoph is 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.

9.1 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 Christmas 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".

9.2 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.

9.3 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.

9.4 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.

9.5 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.

9.6 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).


10. More About the Importer
==========================

This section applies to the command line importer, zophImport.pl.

10.1 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)
  - --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)

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).

10.2 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

10.3 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
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

10.4 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


11. Integrating Zoph
====================

In this section I thought I'd mention a couple of tips if you are interested
in trying to integrate Zoph with other parts of your website.  This is still
a work in progress.

11.1 Looking Up People
----------------------

Say you have a site that has its own person or user records and you would like
to map between the two systems (you want to put a "photos of" link on the
profile page of a user, for example).  Though Zoph usually uses it's own
person_id field, you can pass a name instead:

http://www.nother.net/zoph/photos.php?person=Geiger,Jason

will show you photos of a person.  You also can use "photographer":

http://www.nother.net/zoph/photos.php?photographer=Geiger,Jason

Or instead of jumping to the photos page you can hit the person page:

http://www.nother.net/zoph/person.php?person=Geiger,Jason

11.2 Other Lookups
------------------

For albums, categories and locations these sorts of lookups don't exist at the
moment.  But they are fairly easy to incorporate if anyone is interested.

Of course it is easy to generate urls for the other photo fields (that don't
require joins) like title or description.  Just call photos.php?field=val.
Any string that does not start with an underscore is assumed to be a field to
search on.


12. Incompatibilities
=====================

While developing Zoph I've discovered a couple of oddities which I'll
mention below.  Problems that have solutions are likely to appear in
the FAQ.

12.1 Slideshows
---------------

For some reason this feature does not work with IE 5 for Mac OS X.
Every other photo is shown or the same photo is shown over and over.

The slideshow involves a simple refresh header so I'm not sure what the
problem is.  It works correctly with IE for Windows and OmniWeb for OSX.

Slideshows worked fine for me using Netscape 4.7 under Linux and Windows
but I have been told of one problem using Netscape under Windows where
once the slideshow is finished the photo results page that you are
redirected to starts refreshing itself.  Browsing to another page stops
the problem.  This may be slightly annoying but at least it doesn't
prevent the slideshow from functioning.

12.2 Emailing a Photo
---------------------

Some servers or clients seem to have a problem with preserving or
decoding the attachments generated by the Mime class.  The often
seems related to how lines are terminated.

I have currently set things up to terminate lines with \n (and not
a \r\n).  Here is the behavior I have observed:

- Worked: Postfix + Mutt, Exchange + Outlook, IMail Server + Outlook,
Sun Internet Mail Server + Mutt
- Didn't Work: InterMail + Eudora

To play around with this, edit mail.php.

12.3 Optgroups
--------------

Most browsers still don't completely support optgroups in select tags.
Mozilla and IE 5 for Windows label the pulldown according to the groups
but do not display cascading menus.  IE 5 Mac does attempt to display a
cascading pulldown but it seems there is a problem where a cache get
corrupted or something.  I often see results from one pulldown being
merged with another (people and places, for example).  When I view the
page source everything looks ok but somehow it is being displayed
incorrectly.

You can set GROUPED_PULLDOWN_SIZE in config.inc.php to something small
to experiment yourself.
