===========
pynakotheka
===========

:Author: Iigo Serna, inigoserna AT telefonica DOT net

:Version: 1.0.2, May 7th., 2006

:License: \(C\) 2005-6, Iigo Serna

          This software has been released under the `GPL License`_,
          see the COPYING_ file that comes with this package.
          There is NO WARRANTY.

:Last update: Sun May  7 00:41:53 2006

.. contents:: Table of Contents


Introduction
============
Not much to say, **pynakotheka** is a simple python script which generates 
static HTML photo albums to be added to web sites or to be burnt in CDs.

The gallery can contain folders and/or pictures
and the folders can contain other folders and/or pictures, recursively. 
There are 4 views: folder, tree, thumbnails and photo detail (with or 
without exif info). You can even create your own templates easily.

Released under GNU Public License, read COPYING for more details.

Some inspiration from curator_, another python gallery builder.

Here you have a `demo site`_ with some photos of my friends.


You don't need to install the script, uncompress the package and
select the proper path of the templates when executing the program.
Anyway, since v1.0.1 you can use the usual python process to install 
*pynakotheka* and let the program to find out where the templates are
located::

  # python setup.py install


These are the options:

::

  Usage:  pynakotheka.py <options> [source_dir [target_dir]]

  Arguments:
      source_dir       Location of the source photos, defaults to current dir
      target_dir       Directory where to save the gallery, defaults to current dir

  Options:
      -h, --help       Show this text
      -q, --quiet      Don't show progress information messages, default SHOW
      -c, --color      Show information messages with colors, default NO COLOR

      -o, --copy-originals
                       Copy original images to the gallery, default NO
      -s, --thumbsize  Thumbnail size, defaults to 250
      -i, --imagesize  Image size, defaults to 640
      -d, --templates-dir
                       Path to templates directory, defaults to 
		       "$PREFIX/share/pynakotheka/templates"
      -t, --template   Template to use, defaults to "default"

      --clean=all|images|html
                       Remove all files / images / html and style files
                       generated by the program


Templates
=========
Each template has his own directory which **must** contain exactly these 7 files:

- *view_albums.tmpl*: html template for the album view
- *view_tree.tmpl*: html template for the tree view
- *view_thumbs.tmpl*: html template for the thumbnails view
- *view_image.tmpl*: html template for the image detail view
- *style.css*: cascading style sheet
- *background.jpeg*: background image
- *transparent_black.gif*: image

All of these files must exist in your template directory. If you don't need 
any of them, create an empty file anyway (yes, this could be improved).

The name of the template is taken from the directory name.

 
There are only three templates by now:

- *default*: nice and elegant look with exif information and previous and
  next images preview
- *noexif*: similar to *default* but without exif information
- *simple*: you see, no colors, no css, no background

Thanks to http://wancam.precompiled.org/tdigs and 
http://photolib.sourceforge.net from which I've taken some ideas and html code 
for these templates.

If you design a new template, please contribute back to the community. Thanks.


Album folder description file
=============================
You can specify some information for each folder.

To do it, create a file called *album.xml* and place it in the base directory
for the folder. This is the example included with *pynakotheka* (if you have
installed the program you can find it in */usr/share/doc/pynakotheka*)::

  <?xml version="1.0" encoding="latin1"?>
  <album>
    <title>
      This is the title
    </title>
    <description>
      These photos were taken during our holidays in Mars last October
    </description>
    <sample_photo>
      path/to/photo1.jpeg
    </sample_photo>
    <omit_album>
      FALSE
    </omit_album>
    <omitted_files>
      <omitted_file>
        photo12.jpeg
      </omitted_file>
      <omitted_file>
        photo26.jpeg
      </omitted_file>
    </omitted_files>
  </album>

- the first line sets the *encoding* for the file
- *title*: the name for the folder, instead of directory name
- *description*: summary for the folder contents
- *sample_photo*: path to the image you want as sample for this folder
- *omit_album*: either TRUE or FALSE. If you want *pynakotheka* not to
  include this directory in the gallery set it to TRUE
- *omitted_files*: list of photos to be omitted


Requirements and Download
=========================
- pynakotheka_, you can download it from here_
- Python_
- `Python Imaging Library`_
- EXIF_ 
- `Cheetah Template`_


FAQ
===
**Q: It's a bit slow... what can I do?**

A: Templates could be compiled (consult `Cheetah Template`_ documentation). 
Or you can generate the gallery after going to sleep.

**Q: How can I disable exif information in my gallery?**

A: Use the *noexif* template.

**Q: pynakotheka crashes when using a template without "background.jpeg" file**

A: File must exist. See Templates_ section.


CHANGES
=======
Changes from v1.0.1 to v1.0.2:

  - now albums are sorted by creation time

Changes from v1.0 to v1.0.1:

  - distutils support. Now you can install *pynakotheka*
  - added a man page
  - fixed some typos in templates


TODO
====
Post v1.0 ideas:
  
  - more templates
  - define schema for templates: template.index
  - comments for photos

Rejected ideas:

  - add text/watermark to images, let specify font and size
    Shane Hathaway and Terry Carroll "Watermark with PIL"
    http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/362879
  - add a shadow or other effects to the photos
  - option to disable exif: use template with no exif info


---------------------------------------------------------------


[This documentation was generated with `reStructuredText`_]


.. _pynakotheka: http://inigo.katxi.org/devel/pynakotheka
.. _here: ./pynakotheka-1.0.2.tar.gz
.. _`demo site`: http://gallery.katxi.org/katxi
.. _Python: http://www.python.org
.. _`Python Imaging Library`: http://www.pythonware.com/products/pil/
.. _`Cheetah Template`: http://cheetahtemplate.org
.. _EXIF: http://home.cfl.rr.com/genecash/digital_camera.html

.. _curator: http://curator.sourceforge.net

.. _COPYING: COPYING
.. _`GPL License`: http://www.gnu.org/licenses/licenses.html#GPL
.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html
