ALBATROSS

Web Photo Album Generator

Keywords: bash, script, album, generate, command line, photos, camera, digicam, dSLR, SLR, digital photography, web, http, html, cygwin, linux, windows, bsd, solaris, manual, instructions, help, development, roadmap, bug, bugs, change notes, latest news, warning

The legal bit

Albatross is Copyright (c) 2005-2006 Anders "Ichimusai" Pettersson.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Introduction

Albatross is an album generator written completely in bash. It has been tested and will run on many different platforms, including Linux, BSD and even Microsoft Windows by way of the Cygwin package.

Albatross relies on two command which are not standard in most GNU implementations. These commands are convert which is part of the ImageMagick package and then there is the jhead that will extract EXIF information from JPEG files.

Albatross recognizes a number of files but is happies with JPEG files (.jpg .JPG .jpeg .JPEG et cetera) because most cameras use that kind of format and stores EXIF information int it. It makes it possible for us to extract this info from the picture and display it.

The script also recognizes text captions and will typeset those with the images, both on the index page and on the individual page for each image. This makes it possible to give the image a name and a description the way you like it. Standard HTML, for making links et cetera can also be used in these captions.

What does it look like?

Well, you are welcome to browse the images over here, this i my test bed for the script. Let me know what you think about it.

If you want to know more about known issues, roadmap, change notes and todolists, check the column to the left, this part of the web page is updated frequently as progress is being made...

Installation

The installation script that comes with Albatross should be good enough to get it installed on most systems. The script itself will default to installation in /usr/bin and that's really what you need. Convert and jhead should be already installed anywhere in the systems path.

To get the necessary tools

ImageMagick can be downloaded from this site. You really only need the convert application for this script so you might grab the proper binary and stick somewhere in your $PATH.

JHead can be found over here. You may have to rustle this one through the compiler but there are binaries for most platforms around if you look.

Running the script

Running the script is rather simple. Locate yourself in the topmost folder of your image tree and type the command albatross and press enter. The script will recurse through any sub-folders generating thumbnail pictures as well as medium sized resolution pictures.

What you will get is an index.html which is the index file. The script will then create the subdirectory .albatross in each directory it traverses. This directory is used to store thumbnails, HTML files for the individual pictures and also the medium sized pictures.

If you wish to clean out all the files that albatross have created you can run it with option --clean which will remove all these files.

A word of caution - the script will over-write any pre-existing files. Also if the thumbnails and medium sized pictures already exists the script will not re-create them. However all structural files such as the HTML files will be recreated every time the script is ran.

Default settings

All default settings can be changed. They are located in the top part of the script and should be reasonably self explanatory. Be mindful of what you do when you change these since a small error can have a rather huge impact on the behaviour of the script.

The default values have been chosen as pretty reasonable. Once you get comfortable with the script you may wish to tweak them into something that you like better yourself.

By using command line options (listed below) you can tweak most of these settings temporarily. Some people also use the alias functionality of their shell, for example

alias myalbum="albatross --mediumsize 600x600 --mediumquality 80 --thumbnailquality 60"

This will create the "new command" called myalbum that will call albatross with the options listed above. This can be placed in one of the startup files for the shell so that the alias is always there when needed. Startup files may be .bashrc or something similar.

Captions

I know that everyone loves to write a short note on each of their pictures. No? Well, there is a rather simple way of doing this in albatross. The first thing you need to do is to rerun albatross with the switch --captions, that will create a file called captions.txt in every directory that albatross finds any pictures.

This file has the following syntax

<file name>:<short desc.>:<long desc.>

When the captions file have been generated by the script it will look something like this:

DSCN_0176.JPG::
DSCN_0178.JPG::
DSCN_0288.JPG::

The next step is to view your index in your normal browser, just open the file or navigate to the file on your web page as if you where casually viewing your latest pictures.

Then use any text editor to edit this captions file. The captions file will be found in the same directory as the index file will be created. After editing it may now look like this:

DSCN_0176.JPG:Mom &amp; Dad:My mom and dad at Acapulco
DSCN_0178.JPG:Brother:My brother from Teguciagalpa waiting for the annual herring rain
DSCN_0288.JPG:Car:This is my brand new Jaguar XJS12!!!

As you can se certain special signs better be HTML-quoted such as ampersand & to not create any problem, although most characters won't. When the file has been edited you should re-run albatross again and it will put the short description on the index pages and as a headline on the medium size pages and it will put the long description under the picture on the medium sized pages.

One cool thing is that you can give the entire directory a description by adding something like the following line:

dir:Flowers:This album contains pictures of flowers that I like...

The keyword here is dir when it picks up on this the description will be typeset on the index page rather than on the individual picture pages.

Any picture you do not wish to comment on, just leave - or delete, the corresponding line in the captions.txt file as you wish.

You can embed HTML links and other things in your descriptions to other pages if you like and many other features...

Cleaing up after a mess

If something does go wrong, please try and run the script again. First with the --clear optin and then as normal. Do you get any error messages? What about convert and jhead, are those installed properly in your $PATH?

Locate the troubled directory and list all files in it, ls -al is usually good. If you find a ".albatross" folder or similar, delete it. Try running the script again, does it recover?

If nothing else helps, please send me a description of the problem over email if you please. I might not give you a personal answer back but I promise I will take a look at whatever problem you found and see if I can fix that.

Command line options

Here are the command line options for albatross listed. One or several of those may be combined together to for a special layout of your web album.

Options that are listed in red below have not yet been verified to work on all platforms. They will be maked black when they are verified to work.

Miscellaneous commands

--version

Will of course give you the version information on the script.

--clear, --clean

This option will clean out all files that the script have created. Be aware that the script is recursive and may clean out index.html from sub-folders that you did not expect! You have been warned!

--indexname

Change the file name of index files. Default is index.html but some pissy web servers like MS IIS like them to be called "default.htm" or something equally ridiculous.

--workdir <dirname>

Change the albatross working directory to something else. The default is ".albatross". If you are using this option and wish to use the --clear option also, make sure you specify this BEFORE the --clear option on the command line, otherwise it will try to delete the default hiding places for the thumbnails and the medium size files.

Commands that affect the dimensions and quality of images

--mediumsize <dimensions>

This will set the maximum size of pictures in the medium format. Default dimensions is "800x800" which will keep aspect ratio on the picture but limit the longest side to only 800 pixels. (About 0,5 MP which will load pretty fast). Dimensions is alwas WxH, that is the maximum allowed number of pixels on the width x the maximum allowed pixels on the height. Usually this is the same for both dimensions.

--mediumquality <percentage>

Set the quality of the JPEG conversion process that creates the medium sized pictures. The default is 75%. The percentage is given without the %-sign.

--thumbnailsize <dimension>

This will set the size of the thumbnails longest side. Default this is "120x120" pixels which yields files that are small in size and loads fast.

--thumbnailquality <percentage>

This will set the JPEG quality percentage to a different value. The default is 40% for thumbnails. The value is given without the %-sign.

--nomedium

This will use the original size of the images and not link directly to the originals. Only thumbnails will be created. All the medium size flags will lose their effect if this is used.

Layout commands

--columns

This affects the number of thumbnail columns on the indices. Normally there are 4 columns, with this parameter you can change that. Reasonable values would bet 2-7 or so - depending on the size of your thumb nail pictures.

--light

Render the pages in a white background fashion, setting all colors to reasonable values at the same time. The default is a black backgrund, a dark rendering of the pages.

--bgcolor <colour>

Sets the bacground color for the HTML web pages. This follows HTML conventions for color codes of the format "#RRGGBB" where RR GG and BB are 2 char hexadecimal numbers.

--textcolor <colour>

Same as --bgcolor but for the foreground text.

--linkcolor <colour>

Same as --bgcolor but sets the link colors (and thus the border around the images in the index and medium sized images)

--vlinkcolor <colour>

Exactly as --linkcolor but for visited links.

--dirfontsize <fontsize>

This will change the font size used for the directory font. This can either be a fixed number or a relative number such as "+2" according to HTML standards for the tag <font size="+2">

--dirtablewidth <tablewidth in percent>

This will change the amount of screen real estate in the x direction that the table will use. Default value is "90%" which will leave a 5% margin on both sides of the thumbnail table when it is being generated.

--exifcolor <colour>

Follows the same scheme as the other color commands, but sets the color for the EXIF information rendering instead.

--noexif

Suppress the display of EXIF information on the medium sized picture pages.

--border <pixels>

Affects the way tables are drawn. Using a border of 1-n pixels can be effectful. Or just look really crappy depending on your preferences. Default is no border.

--cellspacing <pixels>

Affects the spacing between the cells in the tables. This mainly affects the index pages. Default is no cell spacing.

--cellpadding <pixels>

The distance from the border line of the table to the contents of the table cell. This mainly affects the index page. Default is 2 pixels of cell padding.

--width <percentage>

Affects the width of the master table. This is how much of the screen that will be occupied by the index table and how much will be "air" around it. Default is "90%". This parameter needs the percent sign.

--captions <filename>

This will change the default file name of the captions file to something else. The default name is "captions.txt".

--captionfontsize <size>

This is a relative font size for captions text. Default is "-1". Recommended values would be between -3 to +2 roughly.

Bug reports

I am aware of many bugs in the code already and will be fixing them when they become a priority, when I feel like it, have the time and so on. But you are welcome to send bug reports to my email if you wish, chances are you may have found something that is not listed on this page and that I don't know of.

I try to update this page as often as possible, so if your bug is already listed here, don't email, sit tight and I'll fix it eventually. If you can not find it on this page, please send it here and I will take a look.

If you can propose a fix for it, that would be smashing - I'd write, test and incorporate it into the official version and you'd get your name in it as a contributor.

Thank you.