ChickenPhoto

In the summer of 2006 I got my first Mac. I spent a while trying out all the cool software that came with it. After taking a bunch of weird photos of myself with Photobooth, it was time to delve into the more powerful and serious apps. The one that I was most interested in was iPhoto. I’d seen it in action before and was excited to import my many thousands of digital photos taken over the past six years since I got my first digital camera. But I’ve had a photo gallery on the web for a long time, and it didn’t work with iPhoto. So I figured that it was time to make something new that would give me the kind of online photo gallery I was used to, but with full iPhoto integration. The result of this work is ChickenPhoto. Sorry about the name, but after receiving evil threats from some loser who claimed to own the name Simple Photo Gallery, (the name of the gallery that I used to use, made by a friend of mine) I decided to choose something hopefully more unlikely to cause a problem. (If you call your company Chicken-anything then you’re just silly.)

You may be wondering how this program differs from iPhoto’s HTML export feature. Well, the HTML export built into iPhoto appears to be a one-shot deal. Each time you want a gallery exported, iPhoto rebuilds the entire site, which rebuilds all of the images and static HTML pages. First of all, this takes a lot of time because iPhoto is quite a pig and seems to take a long time to do any sort of exporting function. And secondly, if you’re using some sort of smart file synchronizing tool to only upload the parts of your gallery that are new or changed, this scheme won’t work well. (if you don’t currently use a program like rsync, or want to know how that can help save you a lot of time, read the section on rsync below)

Because most photo galleries are living creations, constantly growing as new albums and photos are added, it seems logical to have a tool which, when run, makes an only gallery that reflects the current state of the albums and photos in iPhoto. This means that you can be free to rearrange images, add captions to previously uploaded images, add and remove albums, and so on, without worrying about which stuff you’ve changed. The web version of your photo collection will just mirror what you have in iPhoto. Enter ChickenPhoto…

ChickenPhoto uses the best parts of iPhoto: namely its GUI and easy manipulation of images, and provides an easy-to-use backend that makes nice looking, low-overhead web photo galleries that synchronize efficiently and are easy to set up on most web servers.

ChickenPhoto consists of two parts. The first part is the Java-based ChickenPhotoUpdate program, which reads the iPhoto album XML file and generates thumbnails, lowres images, and data files to be used by the online gallery script. The second part is the actual online gallery script, which is just a simple Perl CGI program that runs on the webserver. It doesn’t need any extra Perl modules and is very fast. A shell script is included which rebuilds the web gallery and then rsyncs it to the server. You need to have rsync installed if you want to be able to perform incremental synchronization of your files to a remote web directory.

Since iPhoto only runs on OS X, I’ve made some assumptions as to the user environment. First of all, since OS X comes with Apache installed, I’m assuming you have a Sites/ directory within your home directory, and that you can view it from your browser using Apache (referred to as Personal Web Server or something like that in your internet settings). When you run the update script, a local version of your online gallery is created or updated. You can try it out on your Mac before it goes “live” on your remote webserver. When rsync runs is brings your remote gallery in sync with the local copy and even deletes remote files that are no longer needed.

What’s all this rsync stuff?

Instead of reinventing the wheel, ChickenPhoto builds the web previews in y our local Sites directory so that you can preview them on your own computer. Since OS X comes with a web server (Apache) installed, this is very easy. You might need to make some changs to your apache config to make the Perl CGI program to work… there are sites which can explain how to do this.

The point of rsync is to make two directories have the same files. It only sends files that have changed from the source to the destination, and even works over the internet. (that’s the cool part) I use rsync for all kinds of stuff, including keeping this website updated. I only ever edit the files on my Mac, and when I’m happy with my changes, I run rsync and it ensures that my online copy of the site (the one you get from my webserver) is identical to the one on my computer. This usually takes only a few seconds, since usually most of the site is unchanged.

Since photos can be big, and you can have a lot of them, it doesn’t make sense to upload them all each time. And if you edit ones that you’ve previously uploaded, you want to make sure that the new versions replace the old ones in your online gallery. ChickenPhoto makes sure not to mess with files that haven’t changed, therefore ensuring that rsync doesn’t upload stuff that’s already online. My gallery has over 6000 images, and this method saves hours and hours of time.

ChickenPhotoUpdate

The ChickenPhotoUpdate program is a Java program (shipped as a jar file) which reads the AlbumData.xml file from iPhoto (usually located in /Users/yourname/Pictures/iPhoto Library/ and parses the album and image data into memory. It then does the following:

  • cross-checks all links to make sure image references are valid and files exist on the disk
  • forgets about movie files, since they can’t be shown by the gallery (yet)
  • forgets about hidden albums (which are made when importing photos into iPhoto from directories)
  • forgets about any album which has a name starting with the ‘_’ (underscore) character - this is useful for making private albums that don’t get added to the gallery
  • forgets about the Library, Last Roll and Last 12 Months albums which may contain images which are not public
  • cross-references the image list and forgets about images that are no longer needed
  • builds data index files in the web directory on the local machine to be read by the web CGI script - including captions and EXIF data from your camera
  • makes thumbnail and lowres images in the web directory on the local machine - only creates ones that are missing or have changed (because you rotated or otherwise modified an image) - including optional image sharpening to improve the perceived image quality at low resolutions
  • cleans up orphaned image files in the web directory on the local machine (which happens when you delete or modify images)

ChickenPhoto CGI Script

The ChickenPhoto CGI script is a simple Perl program that runs as a CGI in the web directory where the album data files and images exist. It reads the data files generated by the java program to determine the list of albums, and the images within each album. The index files are smaller and easier to parse than the huge and poorly structured XML file made by iPhoto. Each album has its own data file to keep the overhead low on the webserver. For instance, a data file for an album with >6000 images in it is approx. 360KB, whereas the corresponding AlbumData.xml file (with the same number of images, plus a lot of other stuff) is 5.2MB.

Try the demo linked at the top of the page to see my actual gallery running ChickenPhoto. Captions are supported on albums and images, and images are sorted by creation date and displayed in thumbnails twenty to a page. Image aspect ratio and rotation is preserved, so if you use a camera with a non-4:3 aspect (digital SLRs) or if you crop images they will display properly. For thumbnail images, the long side is 160 pixels. For screen resolution images, the long side is 640 pixels. These resolutions can be configured if you want different sizes. JPEG compression is set to 0.8.

Installation and Use

For those not familiar with using the unix shell, I’m sorry about that… it makes sense for me so I haven’t felt the need to write a graphical front-end for the update program. I’ll try to explain the basics here so that you can get going quickly. I probably could have made some of it simpler, but it works fine for me so please just bear with me. This is still the first version. :)

Make Sure Apache is On / Set Up

If you want to look at your gallery on your Mac, you need to make sure that your webserver (called Apache) is on and configured properly. More specifically, it needs to know that pages called index.cgi should be index pages and be run as scripts. There are lots of docs on the web about Apache, which is the default web server included with your Mac. If these steps don’t work, you’ll have to figure out Apache by reading some other docs. I can’t help you with your web server configuration.

Here are a few steps to get you going:

Turn On Personal Web Sharing

Check that Personal Web Sharing is turned on in your System Preferences Sharing screen. Just check the box. This makes Apache (one of the most popular web servers, and the one included with the Mac) run.

Configure Apache to Execute CGI Programs

You need to make sure that Apache is configured to run CGI programs in your web directory. This will allow the little Perl program that displays your galleries to work. Check out the file: /private/etc/httpd/users/andrew.conf (where “andrew” is your own username in all cases) and make sure it looks like so:

<Directory "/Users/andrew/Sites/">
   Options Indexes MultiViews ExecCGI
   AllowOverride None
   Order allow,deny
   Allow from all
</Directory>

Make Sure Apache’s Config is Right

Check the file /private/etc/httpd/httpd.conf for a line that says: AddHandler cgi-script .cgi and make sure it’s not commented out. (no # in front of it) Also, make sure that index.cgi is a valid DirectoryIndex filename.

Unpack the Files

Download the bin version below (not the source code unless you waant to hack it yourself) and unpack it. It will make a directory called ChickenPhoto which you can use if you want. The basic idea is to copy the files into a directory in your Sites dir. This lets you see your photo gallery with the Personal Web Server that comes with the Mac. You can either host your gallery from here or just look at it locally for fun.

I made a dir called photos in my Sites directory. You can get to it through Safari by going to http://localhost/~andrew/photos where “andrew” is your username. Put all the files from the ChickenPhoto dir that you unpacked into this dir.

Configure the Program

There are two files you need to edit: chickenphoto.properties affects how the update program works with your images. And update.sh which affects what happens when you want to update your gallery and (maybe) sync it to your web host.

chickenphoto.properties

Check out chickenphoto.properties and you’ll see a few options. Just edit the albumXML and outputDir lines to fix the directories for your system. I recommend leaving the sharpen options as they are. It will improve how your pictures look when they get scaled down to fit on the screen.

update.sh

This is the script that you run to make your gallery update. Normally you just go into the directory with Terminal and type: ./update.sh but make sure that the file is executable by doing this once: chmod 755 update.sh when you’re in the dir.

The only line in this file you will need to adjust is the rsync line. If you’re using rsync to synchronize your gallery with an external host, then you need to change this to the right paths. If you don’t care to use rsync, you can just delete this line or change it to something else depending on your setting.

To actually update your gallery, go into the dir with Terminal and type: ./update.sh And then wait a while… it might take a while the first time if you have a lot of pictures. After that only images you add or change will need to be processed.

Have fun!

Downloads

Latest version: 1.04 - released: 2007-04-08

Changes

1.03 to 1.04

  • The image scaler for producing web resolution output now has a sharpen filter! Used carefully this can produce much crisper looking images, especially for the very small thumbnails. This is a 3×3 matrix sharpen filter. To use this filter the following fields must appear in the chickenphoto.properties file:
    • sharpen = true - this turns on the filter
    • sharpenAmount = 0.1 - try 0.1 first - higher numbers make sharper images, but even slightly more than 0.1 might be too sharp
  • The output resolutions can now be configured in the properties file. The longest side of the image is specified, which is automatically determined based on whether the photo is portrait or landscape. The defaults are 160 pixels for thumbnails and 640 pixels for lowres images. To override these defaults use one or both of the following fields in the config file:
    • thumbSize = 200 - sets the thumbnail size to 200 pixels on the long side
    • lowresSize = 800 - sets the lowres (screen size) images to 800 pixels on the long side

    Note: You may need to adjust the HTML layout code in the index.cgi program if you use large images and the layout of the pages look wrong.

1.02 to 1.03

  • Image aspect ratio is now preserved for cropped or non-4:3 images. The long side of the image is always 160 pixels for thumbnails or 640 pixels for screen resolution images.
  • Color profiles are now converted to create standard RGB output images that look correct when reading images with Adobe RGB or other enhanced profiles. You may notice a slight shift in the reds of an Adove RGB image, however by using a standard RGB output it ensures that all browsers will display the colors correctly. Previous ChickenPhotoUpdate versions used ImageIO.read() which ignores color profiles and made severly distorted color output. (washed out images with poor reds and low contrast)

1.01 to 1.02

  • Images are now kept out of web directories if they are not intended to be public. (in albums starting with ‘_’ or in Library album)

1.0 to 1.01

  • Now excludes “Library”, “Last Roll” and “Last 12 Months” albums in output. - These albums may contain images which are not intended to be public.

Licence

ChickenPhoto is released under a BSD-style licence. You may modify this software and use it for your own use, even commercial. This software comes with NO WARRANTY.

Please direct bug reports, feature requests, etc. to me. Also, if you make important improvements, please submit your changes so that I can include them in the next version. Everyone has their own coding style, but please follow the existing source code style when making changes if you want them to be included in future releases.