SGallery

The completely static Web image gallery system

Introduction

First of all: the white-on-black page is supposed to scare you. This is neither "drag and drop" nor "plug and play" thing. There are few things to learn, config files to be written, you might need some additional software, etc. This is probably UNIX-only (or at least quite difficult to make it run under Windows). If you are looking for something that will "just work" and don't care that much about the details - it might not be what you want (however it might work for you). If you are a geek that likes the command-line, file-driven kind of stuff - read on :)

What we've got here is a Perl script. It requires:

Image::ExifTool
Image::Magick
URI::Escape
Cwd
DateTime
File::Copy
File::Basename
File::stat

It works in the following fashion:

You create your directories with images
(optional) You add some metadata files to the image structure:
- Nicer album/image titles
- Custom image sizes/arrangements for particular albums
- Some additional descriptions, separators between different groups of the images in one page
- Custom CSS files
- Etc. etc. - see below for the list of features.
You go to the image directory and say: gallery.pl dest_dir
The script (re)generates the gallery

If you would like to see some real-life examples, you can visit my website: http://photosite.pl, or the galleries of my friends that use this script:

Quick start

Please unpack the sgallery-examples tarfile. In the source/ subdirectory there are source images (cross-linked, to save space) and the three sample gallery hierarchies. In the result/ subdirectory, you will find the outputs of the script.

Example 1

Look in the example1. This could be more or less what you could have in your photo archive. Directories, possibly with some meaningful names (like 'Gallery #1'), inside them some photos etc. That's just fine for SGallery - except that the result will be a bit.. hmm, boring at least. Point your browser to the result/example1/index.html to see what I mean.

Example 2

Please go to example2. Some improvements here:

First of all, the album names have been changed to some more manageable ones. In general, it's recommended to stick with the standard [a-z0-9_] convention.

Despite the above change, the titles in the HTML will be still "nice". This is thanks to the introduction of the album.dat file in every directory: example2/, example2/album1/ and example2/album2/:

CSS: style.css	"please use this file as a global style for the gallery"
TITLE: Example gallery #2	The title
album1 album2	Which directories are included
+*.jpg	'+' means "please include all the files that match the expression" (see the album1 and album2 directories)

The style file has been copied to the root directory of the gallery

Example 3

It demonstrates some other tricks that you can use in the album.dat file

(Sub-album #1) Between groups of images in album.dat you can include a BREAK tag with some text. This is to separate groups of images within the same page
(Sub-album #1) There is a LOCAL_COLUMNS tag that specifies how many columns per page you want. By default, some reasonable assumptions are done.
(Sub-album #1) The LOCAL_THUMB_SIZE tag that lets you specify the requested size of the thumbnails
(Sub-album #2) If you put ; sign after the file name, you can write an image title there. You can use simple HTML here, just look at the remark about the TITLE tag below.

That's basically just to get you going. I will not provide more examples, you should be able to figure out the things using the tag reference below.

LOCAL_ and non-LOCAL_

Before you start to dig the tags: sometimes you will find some parameters that have two versions. Let's take LOCAL_THUMB_SIZE and THUMB_SIZE as an example. The rule are following:

In the given album (but not in sub-albums) LOCAL overrides non-LOCAL
In the sub-albums, non-LOCAL settings are copied from the parent ones. LOCAL ones - aren't

The idea behind such approach is the following: Imagine that one of your albums is a gallery from the music festival (look here to see one). You would like to have four sub-galleries, from different parts of the concert, with big thumbnails on the main page and 2x2 layout. However, inside the sub-galleries, you'd prefer to keep the consistent 4 columns layout, with relatively small thumbnails. What you do? In the main festival gallery you specify:

LOCAL options for the festival gallery index (bigger thumbnails, 2 columns)
non-LOCAL options that will be applied to sub-galleries

Tag reference

# ...	Line beginning with `#` is treated as a comment and ignored
TITLE: string	Title of the gallery. You can use some basic HTML tags here (fonts, colours etc. Just be reasonable - the script will not prevent you from wrecking the generated HTML by including some `"`'s and `<`'s in the wrong place. Use the HTML `&something;` codes when neccessary.
DATE: string	What you want to put in the top-right corner. Note that some reasonable defaults are used, like the EXIF info or the directory creation time. What's more, if you try to specify manually some date and there will be image newer than this date in the album - its date will be used
BREAK: string	Spacer between groups of images
ABOUT: string	File to put in the "about the author" link on the bottom of each page. This works a bit like the CSS tag below, in a sense that it's inherited by all the sub-levels (however, there is just one file that can be put there).
RSS_BASE: url	If specified, causes the RSS to be generated, with the given URL (needs to be complete, http://...) as a base. Remember that you have to add the `leaf` option tags to every album that you want to be visible in the RSS!
CSS: filename LOCAL_CSS: filename	CSS file to use. You just need to put them in the same directory as album.dat, the HTML links will be arranged properly. Note that the style sheets are really 'cascading' - this means, that if you've had some `CSS` tags on the upper levels of your hierarchy, the HTML links to them will be generated.
HIGHLIGHT: filename	By default, the thumbnail of a gallery is generated from the first image on a page. Here you can specify another one
COLUMNS: number LOCAL_COLUMNS: number	Number of columns on page
TABLE_WIDTH: number	What to put as "width" in HTML
IMAGE_SIZE: NNNxNNN LOCAL_IMAGE_SIZE: NNNXNNN	Full size image resolution
ALBUM_SIZE: NNNxNNN LOCAL_ALBUM_SIZE: NNNXNNN	Resolution for thumbnails of the albums
THUMB_SIZE: NNNxNNN LOCAL_THUMB_SIZE: NNNXNNN	Resolution for thumbnails of the images
META_KEYWORDS: string LOCAL_META_KEYWORDS: string	Strings to put in the HTML header. Name of the gallery and the upper-level galleries are always included.
UNSHARP: geometry	Optional Unsharp Mask (ImageMagick syntax)
GAMMA: float	Optional gamma conversion
IMAGE_QUALITY: integer	JPG quality for big images
THUMB_QUALITY: integer	JPG quality for album/image thumbnails
OPTIONS: option, option, ...	Triggers for options. Currently recognized: noexif - disable display of the EXIF information (default) exif - enable display of the EXIF information noconv - disable conversion of the big images (they will be copied directly) conv - enable conversion of the big images (default) hidden - this album will not show up in the upper-level album lists leaf - add this album to RSS
LENS: XX-YY description	Define a lens for the EXIF recognition. The script can often detect the zoom range of the lens, but not the exact model - it's a way to help it. The best practice is to put all your lenses in the main album.dat of the gallery
FOOTER: number	Text for the bottom line of the page
+mask	Include all the files/directories that match the mask (unix shell regexp)
string	Everything else is treated as the dirname/filename to include

Misc. notes

EXIF and lens info

EXIF tags are analyzed using the Perl library, some tricks are used to make the display look good, depending on how much information the camera provides. However, in order to reliably detect the lens used, some heuristics is needed. Hints for the heuristics is provided using the LENS tag in the configuration file.

Image cache

During the generation of thumbnails/images, the script generates (and maintains) some additional metatada, stored in the target directory, to avoid repetitive conversion of the same images. However, this mechanism is not perfect. Once in a while it's a good idea to regenerate all the gallery from scratch.

HTML

While the CSS files are customizable, the generated HTML is not. It's created entirely from Perl and I don't plan to implement any templates in a near future.

Speed

The main bottleneck is the creation of images/thumbnails. On my Athlon64 3800+ X2, regenerating my complete gallery (source: 3.2GB, result: 600MB) takes around 2 hours.

TODO

Nothing for now :)

Download

To see the available releases, go to the download page on SourceForge.

Changes

- CVS version

Improved the RSS generation (OPTION leaf tag)
Escaped the ALT tags (wrecked the code when HTML was used in the image/album titles)

- Version 0.7

Fixed the empty directory generation bug
Updated documentation

- Version 0.6

Split the sgallery and sgallery-examples packages
First release using the Sourceforge release system

- Version 0.5

Added RSS generation, LiveBookmarks icon in the header
Added Prev/Next/Up LINK elements in the header
More inteligent file copying (only if modified - makes the remote synchronization faster)
Added 'hidden' option in the album.dat
Added gamma/unsharp/quality data to the image cache
Added ALT attribute for the images/thumbs

- Version 0.4

Changed default style, to provide black frame around the images
Speed improvements (conditional image/thumb generation)
Added image quality settings for thumbs/images
HTML style fixes
Added noconv/noexif options

- Version 0.3

Removed CONVERT OPTIONS tag, created UNSHARP and GAMMA instead
Got rid of the shell dependencies - it's Perl-only now
PerlMagick instead of calling convert
Removed pseudo-parallelism (not neccessary any more with proper PerlMagick handling)

- Version 0.2

Added better EXIF lens analysis
smart "about" page

- Version 0.1

(initial release)