About swiggle

swiggle is a small command line tool that generates HTML pages, including thumbnail indexes, for given images (a so called "web gallery"). It's intended to be easy to use, and since it is written in C, it's quite speedy. It uses libjpeg for decompression and compression of images, libexif for getting EXIF information contained in the images, and it caches scaled images so that subsequent runs don't need to scale images again and are faster. Of course, the original images aren't changed.

Currently, it only processes JPEG images, and it's thought to be used primarily with images taken with digital cameras.

swiggle was developed on FreeBSD and runs on FreeBSD, Linux and AIX (people have reported some problems on Linux that I wasn't able to reproduce - patches and bugfixes are very welcome). It may run on other Un*x variants, too, but that wasn't tested yet.

swiggle is Open Source software.

How to use it

As the name says it, swiggle is simple. It takes one argument on the command line: the 'main gallery' directory, which in turn contains subdirectories meant to be the 'albums'. It descends into every 'album directory' and processes every JPEG file in there. It creates thumbnails, scaled images and index pages for every album, and of course a gallery index in the 'main gallery' directory.

There are several options that you can pass to swiggle to change the way swiggle generates images and HTML pages. The following options are available:

   -f     ... force rebuild of everything; ignore cache
   -l     ... use bilinear resizing instead of bicubic (faster, but image quality is poor)
   -o     ... don't remove orphaned files
   -c <x> ... columns per thumbnail index page (default: 5)
   -r <y> ... rows per thumbnail index page (default: 3)
   -h <i> ... height of the thumbnails in pixel (default: 96)
   -H <j> ... height of the scaled images in pixel (default: 480)
   -s <n> ... sort images according to argument
              ('name', 'size', 'mtime'; default is 'name')
   -d     ... title string for gallery and albums, if not provided in 
              '.description' files (default: 'my webgallery')

Example usage

Start with an empty directory, for example ~/gallery. Now create one or more subdirectories in ~/gallery and copy your desired images into each of the subdirectories. You might end up with a directory structure like this one:

   |- gallery/
       |- album1/
       |   |- IMG_001.JPG
       |   |- IMG_002.JPG
       |   |- IMG_003.JPG
       |   | ....
       |- album2/
       |   |- IMG_011.JPG
       |   |- IMG_022.JPG
       |   |- IMG_033.JPG
       |   | ....
       |- album3/
           |- IMG_111.JPG
           |- IMG_221.JPG
           |- IMG_331.JPG
           | ....

Now just run "swiggle ~/gallery" and wait until it completes. That's all: copy over the whole ~/gallery directory to your webspace and enjoy :-). Don't delete ~/gallery if you intend to add or change images later: you need to re-run swiggle, and it will take less time if it can use the already created images and thumbnails.

Image descriptions

By default, swiggle displays just the filenames or directory names on the HTML pages. If you want to give some or all images a specific description, just create a file called '.description' in the directory that contains the image. This file should contain one entry per line, the first word of each record is the image filename (without directory prefix) and the rest of the line is the desired description. An entry for the filename '.' is treated specially as the description for the current album.


Example galleries

If you are using swiggle and would like to have your gallery listed here, please drop me a mail!