LIGHTBOX 0.6
============

This package is Lightbox version 0.6.  Lightbox is yet another
web-based photo album.  It was inspired by Slooze (www.slooze.com), a
good piece of software that met some of my requirements but fell short
in other areas.  In particular, Lightbox has all of the following
features:

o Support for multiple languages.

  All text in Lightbox can be displayed in any western (ISO-8859)
  language.  Information about a particular photo (caption, etc.) can
  be entered in any or all supported languages.  By default, Lightbox
  supports Italian and English.  Adding other languages is
  straightforward and requires no code changes.

o Support for multiple image sizes, including persistent user-specific
  image size preferences.

  Lightbox can set cookies on viewers' browsers to record image size
  preference.  Thus, users on slow links can choose to view small
  images, and users on fast links can enjoy larger images by default.

  The number of photos displayed on an "album" page can be customized
  in the same manner.

o Extensible and searchable photo meta-data.  Lightbox currently
  supports the following meta-data:

  - basic shot information: date, camera, lens, film;
  - location;
  - caption;
  - keywords (explicitly for search purposes);
  - technote (arbitrary-length text that gives additional technical
    information about the photograph, such as exposure, etc.)
  - story (arbitrary-length text intended to elaborate on the caption).

  Meta-data is multi-lingual.  Search on meta-data is "google-like"
  (terms are ANDed by default, but there is an explicit OR operator),
  and produces a list of photos that match.

  New meta-data types can be added with a simple code change.

o Fast navigation, even without a mouse.

  Lightbox gives you direct, well-labeled links to album lists, to
  multiple adjacent pages within the current album, and to adjacent
  photos.  Enjoy it with a browser that supports keyboard navigation
  (like Mozilla).

o Minimum graphical clutter (except for the photos, of course!) and
  maximum portability.

  All HTML code generated by Lightbox conforms to HTML 4.01 Strict
  DTD, and attempts to follow W3C best practices.  All style
  information is conveyed through cascading style sheets (CSS1).
  Minimal use of client-side scripts.

o Scalability.

  Lightbox has been tested on collections of several thousands of
  photos.  Even on modest hardware, performance is good.

Other web-based photo albums offer additional features: slide show
modes, user permissions, etc.  Some of these will make it into
Lightbox as time permits.  See the TODO file for what's coming.


AUTHOR

Max Poletto, maxp at alum dot mit dot edu.  http://maxp.net.


LICENSE

Lightbox is released under a BSD-style license.  Please see the
LICENSE file in this directory.


REQUIREMENTS

To use Lightbox, you will need the following software:

o PostgreSQL relational database (version 7.3+)
o PHP 4 (version 4.2+)
o Apache (versions 1.3+, 2.0+)
o ImageMagick (versions 5.4+)

PHP must be compiled with support for POSIX regular expressions
(--with-pcre-regex) and PostgreSQL (--with-pgsql).

Apache must be configured with PHP as a module (not as a CGI script).
Other web servers that support PHP as a module probably work too.

To develop Lightbox, I used PostgreSQL 7.3.2, PHP 4.2.2, Apache
2.0.40, and ImageMagick 5.4.7 on Redhat Linux.  I have also tested it
with PostgreSQL 7.4.1, PHP 4.3.4, Apache 2.0.48, and ImageMagick 5.5.7
on Redhat.  It should be easy to install on any Linux and most modern
Unix systems.


CONCEPTS

1. Overall structure

Lightbox is a collection of "albums."  Each album is a collection of
photos.  Each photo can be tagged with a variety of meta-data
(caption, date, technical information, etc.) in one or more languages.

Photos are stored in the file system.  There is one root photo
directory per Lightbox installation.  All albums are subdirectories of
this root directory.  The name of each album subdirectory corresponds to
that album's "album_id," which is used as part of the key for the
meta-data of that album and its constituent photos.

Photo meta-data is stored in a relational database (only Postgres is
supported at present, but that will change in the future).  The
Lightbox schema is straightforward: see sql/schema.sql.

2. Image sizes

Lightbox allows users to download images at different resolutions to
adapt to their available bandwidth.  Each album should contain
versions of each original at different resolutions, because on-demand
generation of resized images from a single hi-res original (for
example, a 4000dpi slide scan) is too resource-intensive to be
practical with current (January 2004) hardware.

Lightbox provides a tool (utils/mjpg) that automatically converts a
single original into multiple JPEG files with a range of resolutions
and compression qualities.  You should run mjpg on every photo in an
album prior to adding the album to Lightbox.

Supported image sizes are listed in the database table "image_sizes".
Those image sizes are the defaults generated by mjpg.  If you wish to
change the sizes supported by a Lightbox installation, change the
values in the image_sizes table and run mjpg with the "-s" flag (run
it with no arguments for full usage information).

3. Languages

Lightbox supports multiple languages.  Italian and English are the
defaults.  To add a new language, simply list it in the database table
"languages" and add the appropriate text to the table "ui_labels".  If
you forget to define a certain label (for example, the text that
should go on a "Submit" button), then Lightbox will display the string
"ERROR" in its place.

4. Operating modes

Lightbox has an "administrator" mode and a "user" mode.  Users can
view albums and photos and set personal preferences.  Administrators
can create, edit, and delete albums, edit photo information, and set
user defaults that can be overriden by individual user preferences.
Administrator mode is available via the file admin.php, and user mode is
available via the file photos.php.  The quick-start example below
describes the basics of operation of each mode.


QUICK-START EXAMPLE

This section will guide you through the installation and use of
Lightbox by example.

Let DOCUMENTROOT be your httpd document root directory.  For example,
if DOCUMENTROOT=/var/www/html, then /var/www/html/index.html appears
as http://localhost/index.html.

0. Start Postgres and Apache.

   % /etc/init.d/postgresql start
   % /etc/init.d/httpd start

1. Unpack Lightbox into a subdirectory of DOCUMENTROOT.

   % cd $DOCUMENTROOT
   % tar xzf lightbox-X.Y.tgz
   % ln -s lightbox-X.Y lightbox

2. Create a root photo directory accessible by the web server.

   % mkdir -p $DOCUMENTROOT/photos

3. Create a Postgres user that corresponds to the httpd user.

   % createuser apache
   Shall the new user be allowed to create databases? (y/n) n
   Shall the new user be allowed to create more new users? (y/n) n
   CREATE USER

4. Create the lightbox data base instance.

   % createdb lightbox
   CREATE DATABASE
   % cd $DOCUMENTROOT/lightbox/sql
   % psql -q -f schema.sql lightbox

5. Create the photo data for your first album:

   % cd $DOCUMENTROOT/photos
   % mkdir album1; cd album1
   % $DOCUMENTROOT/lightbox/utils/mjpg -v ~/myphotos/*.tif

6. Log onto the Lightbox admin interface:

   http://localhost/lightbox/admin.php

   The default username is 'admin', with an empty password.

7. Click on edit "advanced settings".

   The settings should be self-explanatory.  The key thing to set at
   this point is the album root directory.  Given the directory
   structure in this example so far, set it to "../photos/".  Note the
   trailing slash.  Click submit.

8. Create a new album.

   The "album ID" should be the name of the subdirectory of the album
   root directory that contains the photos.  In this example, it is
   "album1".

   You must also provide an album title in any language in which you
   wish to display this album.  For instance, if you do not furnish an
   Italian album title, this album will not be visible to people who
   choose to view the list of albums in Italian.

   Click on submit.  This will send you to the album edit page.

9. Edit the album.

   The album edit page consists of two sections.  The top part is a
   list of photos that are "not yet in the album": they exist as image
   files on the file system, but they are not in the Lightbox
   database.  The bottom part is a list of photos that have already
   been imported into lightbox.

   "Adding" a photo moves it from the top section to the bottom
   section.  "Removing" a photo moves it from the bottom section to
   the top section.

   At first, the top part has all the photos in
   $DOCUMENTROOT/photos/album1, and the bottom part is empty.  You can
   pick individual photos to add or remove, or add all photos at once.

10. Edit individual photos.

    Once a photo is added on the album edit page, it becomes
    clickable.  Click on it to go to the photo edit page, where you
    can edit its meta-data (caption, etc.).

    You can enter information in text boxes, or choose from previously
    entered information displayed in drop-down menus (useful if many
    shots are taken in the same place, or with the same camera, etc.).

    You may enter some, all, or none of the meta-data for each photo.
    Lightbox will try to do a good job of displaying the photo with
    whatever information it has.

11. Test the results via the "user mode" interface:

    http://localhost/lightbox/photos.php

    If you don't think the user mode interface is self-explanatory,
    please send me a bug report or suggestion on how I can improve it.

    NOTE: The interface lets the user view the photo collection in up
    to three levels: album list, album (photo list), and photo.  If
    you only want users to view a specific album, turn off the
    album_list member variable in the Lightbox object.  You can do
    this by editing lightbox.php, or writing your own PHP:

        <?php
        require("lightbox.php");
        $lb = new Lightbox();
        $lb->album_list = FALSE;
        $lb->album_id = "album1";
        $v = $lb->set_defaults();
        $body = $lb->render_body($v);
        ...
        ?>


COMMENTS AND SUGGESTIONS

Send comments, suggestions, bug reports, and any patches to me at maxp
at alum dot mit dot edu.


VERSION HISTORY

For full information, see the ChangeLog file in this directory.

Lightbox 0.6, 2004-02-06

  o Small bug fixes
  o Javascript to accelerate data entry
  o Better navigation on photo and album pages

Lightbox 0.5, 2004-01-24

  o Initial packaged version
