goof.com HtmlGallery

goof.com HtmlGallery

Overview
Command Line Help
Page Templates
External Dependencies and Libraries
License
Download
Sample Output
Update
Download Source Code

Overview

A number of people have been asking me how I build the galleries of images that can be seen various places on goof.com. I have built a tool which was intended as a free-for-noncommercial use release, which is now ready.

I call it simply HtmlGallery.

The principle behind the program is that there are some standard things done to generate a set of webpages intended to display a collection of images. These are mostly content generation:

Thumbnails
Intermediate-sized images for browser display
Thumbnail indexes
Intermediate Image display pages

Additionally, there is often some set of content that must be copied into the gallery directory structure to support the HTML - icons, etc., as well as a copy of the original images, if there presence in the gallery is desire.

HtmlGallery automates the process of the content copying and generation while allowing a large degree of flexibility and control in particular over the contentgeneration.

Thumbnail and intermediate images are scaled versions of the original images such that their aspect ratio is identical, and they fit inside the default (or command line specified) bounding boxes for the two types of images. The aspect ratio of the bounding box does not need to be the same as theimages- the largest dimension of the image will be scaled to the correspondingdimensionof the bounding box, and the other dimension will be scaled by thesame factor.

Thumbnail indexes and intermediate image display pages are generated by two separate templates. The Apache Velocity engine is embedded and used for HTML generation, and the templates must contain valid Velocity template content. The templates provide an opportunity to highly customize the HTML output of HtmlGallery, and are in and of themselves, also a program. The templates are executed within an environment that contains a fair amount of information about the gallery being generated.

Command Line Help

The command line options for HtmlGallery are

Usage:
gallerygenerator [options]   

Options available:
-v[ersion]	Print version information.
-h[elp]		Print this help information.
-tw <int>	Width of bounding box for thumbnails.
		Default: 224
-th <int>	Height of bounding box for thumbnails.
		Default: 168
-iw <int>	Width of bounding box for intermediate images.
		Default: 800
-ih <int>	Height of bounding box for intermediate images.
		Default: 600
-tq <int>	JPEG quality setting for thumbnail image compression.
		Default: 85
-iq <int>	JPEG quality setting for intermediate image compression.
		Default: 85
-it <string>	Intermediate Image Page template filename.
		Defaults to an example template stored in the jar file.
-tt <string>	Thumbnail Page template filename.
		Defaults to an example template stored in the jar file.
-is		Include a copy of source images in gallery directory.
-pp <string>	Prefix of thumbnail page filenames.
		Default: "index".
		For a gallery with n pages there will be files named:
		"index.html" and "index2.html" through "indexn.html".
-ipp <int>	Number of thumbnail images per top level gallery page.
		Setting this to 0 will result in a single top level gallery
		page that contains all images.
-nig		Skip image generation.  Sizes for images NOT generated
		previously will be 0x0 as provided to the html generation
		templates.
-nhg		Skip html generation.
-cdc <string>	Path of directory the contents of which to copy into the
		gallery directory.
-owc		Overwrite files in gallery directory with files from directory
		specified in previous option.

Most command line options are self explanatory.

The directory scanner that searches for image files to convert and place in the gallery currently only detects files with the extensions:

jpg
jpeg
png
tif
tiff
gif

If you would like another image format supported, please let me know. I will add common file extensions as they are requested, but only those that JAI will support. Additionally, I am considering a command line option that will take a list of comma separated (e.g. jpg,jpeg,png,tif,tiff,gif) extensions to include from the specified source images directory.

Page Templates

HtmlGallery allows the user to define templates that control how the HTML used to display both image thumbnail indexes and individual images. These templates are called the thumbnail template and the intermediate image template, respectively. HtmlGallery has a sample/example template for each of these purposes that are included in the HtmlGallery.jar file. If the program is run without specifying files to read for the two templates, it will use the internal sample template for HTML generation. A second set of templates is provided as an example of another look and feel thatcaneasily be created.

The thumbnail index page template is provided with the following variables/objects in its environment:

Variable/Object Name	Class/Type	Description
thumbnailImageFilenames	ArrayList	Contains the image filenames for all thumbnails that were generated as part of this gallery.
thumbnailImageURI	String	Contains the relative URI to the directory containing the thumbnail images, with a trailing /
thumbnailImageDims	ArrayList	Contains ArrayList objects each of which containsat index 0 the width (as an Integer) of the corresponding thumbnail image,and at index 1 the height (as an Integer) of the corresponding thumbnailimage.
intermediatePageFilenames	ArrayList	Contains the page filenames for all intermediate image HTML files generated as part of this gallery.
intermediatePageURI	String	Contains the relative URI to the directory containing the intermediate image HTML files, with a trailing /
sourcesIncluded	Boolean	True if the user specified source images to be included in the gallery generator's output.
sourceImageFilenames	ArrayList	Contains the image filenames for all source images included as part of this gallery.
sourceImageURI	String	Contains the relative URI to the directory containing the source images, with a trailing /
galleryName	String	The name of the gallery the user specified on thecommand line.
startIndex	Integer	The first index number in the ArrayLists of information for which this invocation of the thumbnail template is responsible for generating HTML output.
stopIndex	Integer	The last index number in the ArrayLists of information for which this invocation of the thumbnail template is reponsible for generating HTML output.
currentPageNum	Integer	The number of the thumbnail index page for which this invocation of the thumbnail template is responsible for generating HTML output.
totalPages	Integer	The total number of thumbnail index pages that will be generated.
pagePrefix	String	The prefix used to derive thumbnail index filenames. The full filename is the prefix appended with the current page number, appended with the suffix. When the page number is 1 it is not included in the filename.
pageSuffix	String	The suffix used to derive thumbnail index filenames. The full filename is the prefix appended with the current page number, appended with the suffix. When the page number is 1 it is not included in the filename.

The intermediate image page template is provided with the following variables/objects in its environment:

Variable/Object Name	Class/Type	Description
intermediateImageURL	String	Contains the relative URL to the intermediate image for which this invocation of the intermediate image template is responsible for generating HTML output.
intermediateImageDims	ArrayList	Contains ArrayList objects each of which containsat index 0 the width (as an Integer) of the corresponding intermediate image, and at index 1 the height (as an Integer) of the corresponding intermediate image.
intermediatePageFilenames	ArrayList	Contains the page filenames for all intermediate image HTML files generated as part of this gallery.
currentIndex	Integer	Contains the index to all intermediate image information arrays that corresponds to the intermediate image for which this invocation of the intermediate image template is responsible for generating HTML output.
sourcesIncluded	Boolean	True if the user specified source images to be included in the gallery generator's output.
sourceImageFilenames	ArrayList	Contains the image filenames for all source images included as part of this gallery.
sourceImageURI	String	Contains the relative URI to the directory containing the source images, with a trailing /
galleryName	String	Contains the name of the gallery the user specified on thecommand line.
currentThumbnailURL	String	Contains the relative URL to the thumbnail index page responsible for rendering HTML output for the thumbnail that correspondsto the intermediate image for this invocation of the intermediate image template.

External Dependencies and Libraries

HtmlGallery is dependent on the Java 2 Runtime Environment 1.3. It can be downloaded from SunMicrosystems' Pages.

HtmlGallery makes use of several libraries in order to perform image and HTML generation

For image generation, HtmlGallery depends on the Java Advanced Imaging API Version 1.1.1. The jar files shippedwith this API must be in your classpath. For quicker execution, if you use a platform that is supported by Sun's libraries, putting them in your shared library load path (or simply PATH under windows) will allow faster image scaling.
For HTML generation, HtmlGallery depends on The Jakarta Project's Velocity Templating Engine Version 1.1. The jar file shipped with this API must be in your classpath.
For command line processing, HtmlGallery depends on GNU Java Getopt Version 1.0.8. The jar file for this software must be in your classpath.

License

HtmlGallery 1.0 is distributed under the following license. By downloading and using it, you agree to the terms of this license. The important part is that it is free for noncommercial use. For commercial use, please contact me for terms.

All of the documentation and software included in this software distribution
is copyrighted by Matthew C. Mead (mmead@goof.com).

Copyright 2001, Matthew C. Mead. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
must display the following acknowledgement:
This product includes software developed by Matthew C. Mead.
4. Neither the name of the author nor the names of any co-contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
5. Commercial use of this software and that derived from it is expressly
prohibited without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY MATTHEW C. MEAD ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL MATTHEW C. MEAD OR CO-CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OFUSE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Download

HtmlGallery 1.0 is distributed as a jar file containing the jar file for HtmlGallery byte-compiled code, a batch file that can be customized and used to invoke HtmlGallery, and an example set of templates and content that can be used as an example for a frames based look and feel to the resulting html.

Source code for HtmlGallery 1.0 will be released shortly.

Sample Output

I've created two different galleries based on the same set of images using this program for the purposes of demonstrating its capabilities. The first is the default output that HtmlGallery creates by simply specifying a gallery name, source images directory, and destination directory. The second uses the example templates and command line options in the sample_frames directory included with the software distribution.

Yes, that's my ugly mug in there.

Update

I've changed HtmlGallery to use JMagick (with passthrough using JNI to ImageMagick) for its image manipulation. It is many times faster. In the future I will be expanding this application and rewriting it in Ruby with a GUI built in wxWidgets. It will be multiplatform and much faster.

Download Source Code

The latest source code is here.