=============================================
   curator: Static Image Gallery Generator
=============================================

.. contents:: Table of Contents

Description
===========

Curator is a powerful script that allows one to generate web page image
galleries with the intent of displaying photographic images on the Web, or for a
CD-ROM presentation or archiving.

It generates static web pages only - no special configuration or running scripts
are required on the server. The script supports many file formats, hierarchical
directories, thumbnail generation and update, per-image description file with
any attributes, and 'tracks' of images spanning multiple directories.

The templates consist of HTML with embedded Python. Running this script only
requires a recent Python interpreter and the ImageMagick tools. If you've been
looking for a simple yet very powerful script to do this task you've come to the
right place.


Motivation
----------

There are many other worthy similar systems on the web. It seems everyone and
their sister has been writing an image gallery generation script these days. Why
did I write my own, mind you ask? Most of the existing ones required server
customizations (PHP, cgi scripts) and thus will not work off of an archive
CDROM, or required some annoying installation of some special image manipulation
packages, or didn't support templating. Besides, I really wanted the
*tracks* feature, and when I started diddling a prototype for the embedded
Python execution within the template HTML, I thought it was so cool, I just had
to do it.

Another way to view the services that this script provides is this:

- it gathers a per-directory, per-track, and global index of a hierarchy of
  files;

- templates for each file, directory, track, all, are processed with embedded
  python code in the template running in a specialized environment for the page
  to generate, including access to the per-file attributes;

- it knows about some image-specific stuff (thumbnails, alternate
  representations)

You could probably easily retarget it to some other application (e.g. viewing
hierarchies of animations, text files, mp3's, etc.).


Features
--------

This script was written with the following requirements/goals/features:

- on the client side: nothing more should be required than a **web browser** to
  use it;

- on the server side: the web pages should be **statically** generated (no need
  for special server configuration, no cgi, no PHP, no Zope, no nonsense, just
  HTML);

- all links are **relative links** (i.e. it should work when burned on a CDROM
  or moved);

- the output HTML should be **templated/themeable** (i.e. the user can change
  the look of the output HTML). In fact, the templates themselves are written
  with embedded Python code in the HTML, the possibilities are endless;

- each photograph can have arbitrary attributes associated to it, in a
  **per-image attributes file**. The script simply makes these available to the
  template code to take advantage of. For example, this is how you can include
  photo description, EXIF camera settings, or any other user-define attribute
  (just write a template that uses those);

- **thumbnails** should be generated automatically, the thumbnails reside
  alongside the photos themselves;

- can be created to fill in variables in the templates (e.g. title, description,
  camera settings, other);

- **tracks** of images, independent (and across) of directories can be generated
  using the attributes file. The script compiles these list of images and
  they're available to the templates. This could be used, for example, to links
  are your "people", or "black and white" images together, each photograph can
  be part of one or more tracks;

- a **global**, **per-track** and **per-directory** index page should be
  generated;

- it should be **simple to use** (it should be able to work with a simple
  hierarchy of image files, with a trivial invocation, try it now, if it don't
  work, I've failed);

- we're not assuming that the names of the files are unique across the hierarchy
  (for digital camera images);

- supports **many file formats**;

- it should be **trivial to install, and portable** (i.e. should not use more
  than what is available in base installs of most linux distributions).  In this
  respect, thus this script only depends on the availability of:

   - Python, version 2 or more;

   - ImageMagick tools;

There is no special library to install, no special tools, nothing. Download and
run. This runs on a default redhat install. There is a switch for supporting old
versions of the ImageMagick tools.

.. note::

   Note that curator does not resize the large digital camera images to a
   viewable size automatically.  We have planned a redesign which will allow to
   integrate this feature elegantly and generically.

Notes
-----

This program packages `Gene Cash's EXIF.py library
<http://home.cfl.rr.com/genecash/digital_camera.html>`_.


Documentation
=============

- `CHANGES <CHANGES>`_ (recent changes, history);
- `TODO <TODO>`_

- `Reporting Bugs <http://sourceforge.net/tracker/?group_id=31897>`_
  (**please** use the sourceforge bug tracker, do **not** send email
  for bugs)

- `Example Output <share/demo/dirindex.html>`_

- `Redesign documentation (2004-03-23) <doc/redesign.html>`_

Invocation
----------

Running the script with the default templates should be as easy as cd'ing in the
root of the image hierarchy and typing ``curator``.

Run ``curator --help`` for command line interface options, description of the
required inputs and of what the script generates.


Download
========

- Download `releases from SourceForge
  <http://sourceforge.net/project/showfiles.php?group_id=31897>`_;


Installation
============

Dependencies
------------

One of the most important "features" of curator is that it does not depend on
much to run or to view the pages.

- Python-2.3 or greater;
- ImageMagick or PIL (Python Imaging Library);


Portability
-----------

curator will run under any platform that has a Python2 (or more) interpreter and
the ImageMagick tools. It has been tested under Linux and IRIX.  curator is
known to have worked under Windows using the PIL (tested on 2003-11).


Contributions
=============

Contributions from other people can be found in the source code.


External Links
==============

- `Sourceforge Project Page <http://sourceforge.net/projects/curator>`_

- `Freshmeat Appindex <http://www.freshmeat.net/projects/curator>`_

- Getting `Python <http://python.org>`_

- Getting `ImageMagick <http://www.imagemagick.org>`_

- Extracting camera settings from EXIF JPEG's (can easily be integrated with
  curator):

  - `PyExif <http://pyexif.sourceforge.net>`_
  - `Gene Cash's EXIF.py <http://home.cfl.rr.com/genecash/digital_camera.html>`_
  - `exifdump.py <http://topo.math.u-psud.fr/~bousch/exifdump.py>`_
  - `Exif-Tools. <http://exif-tools.sourceforge.net>`_


Copyright and License
=====================

Copyright (C) 2001-2004  Martin Blais.  All Rights Reserved.

This code is distributed under the `GNU General Public License <COPYING>`_;

Author
======

Martin Blais <blais@furius.ca>


.. official sourceforge logo code snippet

.. image:: http://sourceforge.net/sflogo.php?group_id=2198&type=1
   :width: 88
   :height: 31
   :alt: SourceForge Logo
