Rhotoalbum

It is simple. Everything is ready in three steps:

Copy your photos to directories and their subdirectories. (more details)
Modify optional settings and run the Rhotoalbum generator. (more details)
Enjoy :)

Real photo albums:

surprisingly my ;) www.valibuk.net/photoalbum
Viktor's album http://www.alephzarro.com/foto/albums/

simple to use
nested albums
plain HTML page behavior
integrated JavaScript viewer
titles and descriptions
album statistics
optional EXIF support
multiple styles and style switcher
effects for thumbnails and album thumbnails (examples)
customizable

Please, visit the Rhotoalbum's GitHub page.

The latest version 0.9 was released on January 17, 2011. The first one on May 25, 2007.

Rhotoalbum is a photo album generator programmed in Ruby.

It works with a directory structure, it produces static web content and it does not require any database.

Rhotoalbum generates thumbnails and the index.html (rss.xml) file in each subdirectory. There is a possibility to add titles and descriptions of the images.

I. What do I need?

Minimal configuration

Any OS runnning Ruby 1.8+ and the ImageMagick library (the convert tool is used to generate thumbnails).
Nice photos :)

Additional configuration

i) for generating cute thumbnails by applying various effects:

the RMagick library
gem install rmagick (version 2.13.1 or higher)

ii) for displaying EXIF data of the photos:

the exifr library
gem install exifr (version 1.0.1 or higher)

For installing the libraries you may need an admin or root access, e.g. on Linux you may use sudo gem install exifr.

Publishing

There are two ways how to publish the photos and files generated by rhotoalbum:

a) a web hosting with a shell account

If the server configuration meets all the needed requirements, you may use the rhotoalbum generator directly on the server.

b) a minimal web hosting or without Ruby or libraries

You can use the rhotoalbum generator on your local system and then transfer photos and generated files to the remote web hosting. However this implies that your local system should meet all the requirements.
For effective transfer of photos and generated files use rsync
e.g. the command rsync -av . user@server:directory_on_the_server transfers all files from the actual directory to the server.

II. Directory Structure

Rhotoalbum expects that your photos are stored in directories (and their subdirectories). The Rhotoalbum files should be installed (do not worry, it means unpacked) it the top directory of this structure.

Example 1:

  photos
    2005
      01_London
      02_Stockholm
      03_Oslo
    2006
      01_Paris
      02_Madrid
      03_Rome
    2007
      01_Sydney
      02_Melbourne

In this example, the Rhotoalbum files should be stored in the photos directory.

Example 2:

  photos
    john
      200702 Beach
      200705 Party
    alice
      200703 Nice sunset
      200705 Party

Again, the Rhotoalbum files should be stored in the photos directory.

III. How does it work?

ruby rhotoalbum.rb

That's all :)

and in details...

Rhotoalbum starts in the actual directory where it gathers all subdirectories and image files.

If there are image files, it creates the thumbnails directory, creates a thumbnail for each image and stores is in the thumbnails directory.

Then it creates the index.html file that contains:

a menu with links to all parent directories
links to all subdirectories
thumbnails of image files
titles of images (taken from filename)
description of the images (taken from accompanying text files)

And it repeats these steps for each subdirectory (and its subdirectories).

Directories and files are ordered by their names.

IV. Customization

There are plenty of possibilities how to customize the generated result.

The first step is to prepare your options file options.yml by copying the options template options.yml.template, so the next rhotoalbum update does not overwrite your settings:
(Windows) copy options.yml.template options.yml
(Linux or OS X) cp options.yml.template options.yml

IV.1 Title and Author

Change the title option to set the photoalbum title:
title: My Photos

Change the author option to set the author name:
author: John Smith

IV.2 Thumbnail effects

There are various thumbnail effects that can be set in the effect setting:

Effect Effect Effect Effect Effect
reflection shadow polaroid glow rotate

And there are various album thumbnail effects that can be set in the effectAlbum setting:

Effect Effect
stack polaroid_stack

All effects that include rotating (rotate, polaroid and all album effects) are randomly rotated - each thumnail looks slightly different; and each generator run will produce different thumbnails.

Once a thumbnail is generated, it is not generated again - it is necessary to remove existing thumbnails to reflect a changed effect option. This can be done by calling the rhotoalbum generator with the clean command:
ruby rhotoalbum.rb clean

To clean only album thumnails (highlight.jpg) you may use the cleanhighlight command:
ruby rhotoalbum.rb cleanhighlight

IV.3 Album cover

The album cover is by default the first image in the album. The album cover image is used to generate an album thumbnail - that is used in the parent album page as an image for the album link.

To change the default behaviour (the first image of album) just create the cover.jpg file the album:

on Linux, create a symbolic link to one of the photos of the directory
```
    ln -s img_1234.jpg cover.jpg
```
on Windows (or Linux), make a copy of one of the photos in the directory and name it as cover.jpg
```
    copy img_1234.jpg cover.jpg
```

IV.4 Album thumbnail

A link to an album = subdirectory uses a thumbnail highlight.jpg located in that subdirectory.

It is automatically created from the first image or the cover image in the album = directory, however there is a possibility to set own or already genereated thumbnail:

on Linux, create a symbolic link to one of the thumbnails of the directory
```
    ln -s thumbnails/th_img_1234.jpg highlight.jpg
```
on Windows (or Linux), copy one of the thumbnails to the directory and rename it to highlight.jpg
```
    copy thumbnails/img_1234.jpg .
    mv img_1234.jpg highlight.jpg
```

Note: This is an older way how to set an album thumbnail, but it is still supported and it allows to use own images as thumnails.

IV.4 Best Practice

The best practice / sequence of steps for generating albums:

Deployment
- Upload directory structure with your images and install Rhotoalbum to the root directory.
Descriptions (optional)
1. Run
```
./rhotoalbum.rb text
```
  to generate description.txt files.
2. Write descriptions of the albums and images to the description.txt file in each directory.
Customisation (optional)
1. Copy options.yml.template to options.yml, e.g.
```
cp options.yml.template options.yml
```
2. Customize the options in the options.yml file, e.g. enable cool effects for the photo slideshow:
```
panning: true
fading: true
```
Generation
- Run
```
./rhotoalbum.rb
```
  All thumbnails, index pages will be generated.
Highlights
- Create cover.jpg or highlight.jpg (by copy or symbolic link) in each directory for the album front page.
- Run
  rhotoalbum.rb cleanhighlight
  and
  rhotoalbum.rb
  to refresh album thumbnails changes.

V. JavaScript Image Viewer

Rhotoalbum uses the TripTracker slideshow. See the link for more details.

VI. License

Rhotoalbum is distributed under the GPL license.

VII. F.A.Q.

A few of (not so) frequently asked questions:

ssh account, FTP

Q: I do not have an ssh account, only FTP. Is there a way how to use Rhotoalbum?
A: No.

Q: Really?
A: Well, there is a possibility to generate your album on your computer and then transfer all files to your server. Usually, photos are quite large, so to copy the whole album again and again is cumbersome. Of course, you could copy only the changed files, but if you would install a new version of Rhotoalbum :), you would have to manually copy all changed files in all directories.
image viewer

Q: Is it possible to change the image viewer?
A: Hmmm... It is possible but... I tried several JavaScript image viewers -- the TripTRacker slideshow was the best (and also the license is fine).

Q: The panning and fading effects are cool, but it does not run smoothly on slower computers. What to do?
A: Unfortunately, then there is only one way: to disable them. For that reason they are disabled by default.
best practice

Q: What should I do to regenerate some or all files?
A: There are two options:
1. delete manually the generated files (thumbnails, index.html, description.txt) and re-run the respective generation command
2. to remove all generated files you can run
```
./rhotoalbum.rb cleanindex
```
  to remove all index files, or
```
./rhotoalbum.rb clean
```
  to delete thumbnails, indices, highlights
Q: What should I do if I added photos to already existing structure?
A: As simple as you may think :) Just copy them to a directory where you want to have them and execute the ./rhotoalbum.rb as you did the first time.

VIII. Advanced

VIII.1 Command Line

./rhotoalbum.db [command]
Commands:
  generate (default)        generates index.html, thumbnails for all subdirectories
                            recursively (doesn't overwrite already generated files)

  text                      generates descriptions.txt file in each subdirectory where
                            album/photo descriptions can be written

  rebuild                   combines cleanindex, text, and generate (helpful when using text description for your photos)

  cleanindex                remove all index.html files recursively

  clean                     remove all generated thumbnails, indices, highlights
                            recursively

  help                      displays a short Usage

VIII.2 Description Files

If a photo title is not enough, you can assign a description text to any album or photo.

Thereare two ways how to do it:

One file per description. This is useful for ad-hoc description of few images. The text file name is the original file name of image or directory + '.txt', e.g. for IMG123.JPG the description file is IMG123.JPG.txt
Central file for all description per album. description.txt containing one-line mappings of the format: image name, text separated by colon, semicolon, comma or tab, e.g.
```
IMG123.JPG  : Sunset
My Album    : Vacation 2007
```

VIII.3 Customization

You can customize the album generation. You can do it in the options.yml file. If this file is present the options will be used. You can copy the file from options.yml.template

The following properties can be customized:

title:: name of the album
author:: author or authors
author_label:: a label that should be used in the copyright section for author(s), e.g. Author, Authors or Artist
css:: default style to be used
explicitIndexHtml: true or false -- if true, appends '/index.html' to links; useful when you're browsing the album locally
styleSwitcher:: true or false -- to show the style switcher
showTitleAlbum:: true or false -- to show the album title
showStatsAlbum:: true or false -- to show the album statistics
showTitlePhoto:: true or false -- to show the photo title
showDescription:: true or false -- to show the photo description
descriptionAsName:: true or false -- displays photo/album descriptions instead of the name everywhere
showDate:: true or false -- to show the photo date
showExif:: true or false -- to show the basic EXIF data (exposure time, focal length and f-number)
showExtendedExif:: true or false -- to show extended EXIF data (camera model)
thumbnailDim:: 256x256 -- the thumbnail size
panning:: true or false -- to enable the panning effect for the JavaScript photo viewer
fading:: true or false -- to enable the fading effect for the JavaScript photo viewer
labelNoPhoto:: no photos -- a label for no photo in an album
labelOnePhoto:: one photo -- a label for one photo in an album
labelMorePhotos:: # photos -- a label for more photos in an album
labelOneAlbum:: one album -- a label for one subalbum in an album
labelMoreAlbums:: # albums -- a label for more subalbums in an album
copyright:: your copyright section, it may include links to e.g. creative commons licenses.
generateRss:: true or false -- generate RSS (MediaRSS 2.0) feed for each album
google_analytics:: tracker-code or nil -- if the trackers code is given, it generates google analytics for each album
nonrecursive:: true or false -- do not process all album directories, just the root
maxPerPage:: number-of-items-per-page or -1 -- enables/defines pagination for albums.
debug:: true or false -- verbose debuging messages
effect:: options (nil, 'reflection', 'shadow', 'polaroid', 'glow', 'rotate') -- applies an effect to the thumbnail
effectAlbum: options( nil, 'stack', 'polaroid_stack') -- applies an effect to an album thumbnail
effectBackground:: color definitions, e.g. '#000000', red -- background for the effectss

Thanks to:

Michael Adams for his CSS file optimisation and double thumbnails fix.

Mooffie for the relative links, adding index.html to URLs for browsing without a web server and a fix for the too many open files bug.

Ondrej Jaura

Viktor Zigo

May 2007 - January 2011