Image Browser

Introduction

Image Browser is a Web-based application for browsing through large image archives. It traverses a specified directory and caches specific images on-demand without exposing the original files. The original images are copied as needed for public display (aka Moveable image) and the creation of thumbnails.

Thumbnail images are cached with no expiration or maximum cache size. Moveable images are cached separately from the thumbnail cache until the maximum moveable cache size is reached (eg: 5,000), at which point the moveable cache is emptied. Thumbnail and Moveable image filenames are hashed, thereby obfuscating any reference to the original location. File information about the source images is included in the XML output, and it is up to user preference to include any of those details in the interface.

Cached images and transformations (refer Note about User Interface) persist on the disk, so once a thumbnail is built, it will not be removed until the thumbnail cache is cleared.

Because the Image Browser does not - and should not - directly implement or contain original images, it is otherwise safe to delete or undeploy the entire application as needed.

Note about Images

The Image Browser does not perform any operations on original images. It is designed to create an on-demand thumbnail cache, and an on-demand public-access pool.

Note about User Interface

The User Interface is a cached XML transformation. That is, just as the thumbnails are cached, so is the interface representing a given directory or file view. There are two XSL files, xsl/file.xsl and xsl/directory.xsl used to perform the transformations.

Also, the cached XML transformation, or simply the output HTML, is cached by a robust compression buffer. At first, the application can seem a bit pokey while the thumbnails are built for each image set within a directory, but you can really cruise through your image archive once the thumbnails are built.

Installation

At present, the only available version is for Java application servers (eg: Tomcat).

• Download browser.war (v1.9.1 - 67.7kb)
• Deploy browser.war or copy it to the webapps directory.
• When the file is expanded by the application server, proceed directly to the configuration section.

Non-Windows Note: Some considerations are required when running the application from a console because no UI is present to provide the required graphics support for manipulating images.

Use

Navigate to: http://[server]/browser/ and browse away.

The full URL is: http://[server]/browser/ImageBrowser

Configuration

Configuration values are stored in WEB-INF/config/browser.xml. It is necessary to at least specify a valid directory on first use. The default value is /Invalid/.

After making configuration changes that alter the user interface, it is necessary to clear the XSL cache, which is different than the thumbnail cache.

The following configurable options may be changed per individual preference.

• output-path : Location where pre-compiled HTML is stored.
• directory-xsl : Relative file path identifying the XSL file used to create the directory and thumbnail view page.
• file-xsl : Relative file path identifying the XSL file used to create the image view page.
• source-path : Location where images are stored. This does not have to be accessible through the web server, just permissable to the account.
• temp-image-name : Image names are obfuscated and prefixed with this value. Default value is "moveable"
• thumb-size : The maximum height or width of the thumbnail.
• cache-size : The maximum number of moveable files to copy to the image cache from the source-path before the image cache is emptied.
• set-length : The number of thumbnails to display on the directory view page.
• set-browse-length : The number of thumbnails to display in the thumbnail browser of the image view page.
• show-thumbnail-browser : Specifies whether the thumbnail browser should be displayed on the image view page.
• show-folder-view : Specifies to generate folder icons using the thumbnail icons for that folder. This allows for faster browsing through many directories.
• get-image-dimensions : Specifies whether to lookup the original image dimensions prior to creating the output. This value is cached for the lifetime of the running application, or until the cache is cleared.
• show-page-navigate : Specifies whether a drop down list containing all pages is included.
• enable-random-mode : Specifies whether random mode is enabled.
• enable-slide-mode : Specifies whether random mode is enabled.
• enable-cache-controls : Specifies whether directives may be sent via the browser to clear the caches, reload XSL, or clean internal tables. If enabled, cache control options are displayed at the bottom of the page. If this feature is enabled, it is recommended that the cache-size be increased because there is a performance hit scaling the images.
• enable-max-image-size : Specifies whether images are scaled to be smaller than 'max-image-size'.
• max-image-size : Specifies the maximum height/width an image in full view may be. If 'enable-max-image-size' is enabled, images exceeding the max-image-size value are scaled down to that value. If this value is changed, be sure to clear out the cache.

Runtime Query Parameters

All query parameters apply to /browser/ImageBrowser

* WARNING: Some of the administrative features such as clearing the cache and rebuilding all thumbnails (ref: enable-cache-controls option) is a risk because someone who knows these commands could repetetively clear and rebuild the cache and cause untold performance degradation on the system. The ability to disable these options is specified by the enable-cache-controls configuration option.

action

• clear : clears the cache directories.
• reloadxsl : reloads the directory and file xsl files used to create the output.
• buildnails : builds all thumbnail files for all files and directories under the specified source path.
• reset : resets the internal objects containing directory and files lists.
• random : loads an image view where the source is a random image from a random directory.
• dir : (default) loads the directory and thumbnail view page.
• file : loads an image view where the image source is identified by action-type and action-index.

action-type

primarily used for referencing the current path context, relative to the source root.

action-set

current page in the paginated set of images for the specified path

action-setlen

number of thumbnails to display on the page.

action-type

primarily used for referencing the current path context, relative to the source root.

action-index

Index into the buffered directory scan identifying the specific image within the specific context (per action-type). If the index is out of bounds, a debug dump is returned. The debug data has no meaning outside of the application and what is specified in the URL. In other words, there are no actionable data points.

Caching

There are five different file-system and memory caches. These caches are used to create a smooth browsing experience.

• Thumbnail Cache : file system repository of scaled thumbnail images located within the Image Browser application directory. The default directory is nails/. This directory must be publically readable. The thumbnail cache is built based on requests for specific contexts, regardless of whether a UI cache exists.
• Moveable Cache : file system repository of optionally scaled images located within the Image Browser application directory. The default directory is moveables/. This directory must be publically readable. The moveable cache is populated based on requests for specific images, regardless of whether a UI cache exists.
• Transformation Cache : file system repository of XML transformations. The default directory is transforms/. This directory does not need to be public. This directory does not need to be public.
• Directory Scan Cache : in-memory cache of directory scans. These scans are made on first request, or completely when random mode is first used. Each scan includes valid images, and file and image information.
• Compression Cache :
  • Compression Cache (level 1) : in-memory cache of compressed content. Clients that do not support compression draw directly from the Transformations Cache. Clients that do support compression draw from the in-memory cache. As the cache size grows, only the most frequently requested items are held in memory while the less frequently requested items are served from the level-2 cache.
  • Compression Cache (level 2) : file system repository of compressed content. Cached items are replaced when content changes.

Note #1: If the moveable cache size is limited, or the image caches emptied, then any browser with a cached copy of a specific context or image will reference non-existent images.

Note #2: Unless the thumbnail cache is prebuilt, the first person to reference a set of thumbnails will experience noticeable lag while the cache for the specified context and specified set length (ref: action-setlen) is built.

Release Notes

2.0

• Reworked browser.jsp and moved it into ImageBrowserServlet.
• Add optional folder view for directory icons.

1.9.1

• Add detailed image and file information to XML output.
• Include example XML output for use when customizing the XSLs.

1.9

• Add maximum size to browse mode. Images are scaled within the maximum x/y dimension; same as the dimension setting for thumbnails.
• Fixed bug in page list (only affected drop down)
• Fixed stylesheet bug for IE.

1.8

• Add slide show mode. Works in both file browse mode by moving through all images in a directory, or perpetually in random mode. Has a 3 second delay.
• Fixed directory scan bug when in random mode.

1.7

• Replaced instances of Hashtable with HashMap

1.6

• Replaced instances of Vector with ArrayList
• Add support for random browsing
• All configuration is now XML-based.

1.5

• buffered directory scans
• buffered image dimensions
• XML-based output
• Cached XML/XSL transformations

1.0

• original version