The Album

WebPics "photo-album" is a directory with a number of .jpg (or some other format of image files that a web-browser program can render) and .html files, compiled with the purpose of displaying an ordered and annotated collection of photograps in a browser program window.

The album consists of an html "index file" which contains the album title and an optional description, as well as a matrix of image "thumbnails", one for each image in the album. "Clicking" on the thumbnail loads, in the same browser window, an html page with the photograph, its caption and an optional description.

Photograph pages also include the navigational arrows for previous and next photograph page, as well as the one that reloads the index page.

Further description of the program assumes that the reader has browsed the webPics [demo photoalbum], included on the site.

Names of index html file(s) are given in the album definition ("webPics.def") file, while the names of image html page files will be the same as image file names, with .jpg (or other image-type file extension) replaced by .html.

WebPics album conctruction process is cross-platform, it requires no commercial "photo-management" aplication suite, it is, and will remain free, as the program itself can be copied to any computer with Python interpreter, and can be executed without any "installation", by any user, with no administrator credentials. The html files it produces can easily be, if this is desired or neccessary, modifies in any text editor. Without any meta information, style manipulation or scripting, the display is extremely fast and can be done with any browser, however simple, on any platform, present or future. The robustness and simplicy of webPics albums makes them particularly usefull for private distribution, either via explicit URL reference on servers isolated from web search engines, or on physically transfered media or on media in long-term off-line storage.

Source files

The program operates on two types of files, all co-resident in a directory where the photoalbum is to be created:

• Display images and their thumbnails (usually .jpg files)
• Album definition text file(s) (webPics.def, .dscr files)

Images

WebPics program can create a web collection that includes two parallel sets of images and .html files, for two diferent levels of display resolution of the device on which the end-user's browser is running; most often one resolution ("high") for display on desktp computer monitors, and another, ("low") for display on tablets and laptops. Two sets are independently "anchored" by two distinct index html files. This "two-resolution-level" facility is optional, see the <index> directive in the description of webPics.def file below.

For each (possibly only one) resolution level, there must be one "display image" (.jpg, .png...) file for each photograph in the album, and its corresponding "thumbnail" mini-image file. How these are generated from the camera (or scanner) files depends on the general photographic workflow that preceeds the ceation of webPics albums. The simplest method is probably to use the popular "imagemagic" program, available on all three principal OS'es: Linux, MacOS and MS Windows. (cf.: http://imagemagick.org). As a very simple example of it's use, assuming there is a number of "out-of-camera" .jpg files named dsc_1234.jpg, dsc_5678.jpg... etc., in the current directory, the following imagemagic command:

convert -resize '800x600>' dsc*.jpg photo_800x600%02d.jpg

will create their corresponding images down-sampled to 800x600 pixels, and:

convert -thumbnail '200x200' dsc*.jpg photo_thumb%02d.jpg

will create their corresponding thumbnails. All required details can be found in Imagemagic documentation.

There must be a minimum od 4 images in an album. No maximum is enforced by the program.

Album Definition File(s)

A utf8 encoded text file, named "webPics.def", is the principal repository of the information the program requires to construct the photoalbum.

This file consists of "directive" lines, which start with one of the "keywords" described below, and of any number of either blank lines used to enhance the file readeability, or lines starting with a "#" character used for documentation and commentary. Both of the latter are ignored by the program.

The order of lines in the file is arbitrary, with one exception: the order of <pic> lines determines the order of thumbnails in the album index .html file.

All directive lines have the same general format: <keyword> , starting at the begining (i.e., first character position) of the line, followed by one or more blanks, followed by a number of comma-separated line items. If the line item includes a comma or blank chatacters, the item must be enclosed in single quote ("'") characters, which will be stripped from the item by the parser. An item can include single quote character, if it is surounded by alphanumeric characters. ("webPics.def file that is included in the demo-album, contains many examples of the directive line format and the syntax).

Directives and the associated line items are as follows:

<index> file_1, file_2
Where file_1 and (optional) file_2 are the file names of the output "index" html files. If both are given, two "parallel" albums will be constructed, commonly having the same content, but with images (and their thumbnails) in two different resolutions.

The advantage of constructing two albums in parallel, instead of as two completely separate albums, is the ease of maintenance of image captions and descriptions (see below) which are in a single text file for both resolution level albums. This is especially useful when these items are added to existing albums, as the time permits or as the data becomes available.

<head> item
Where item is the "title" of the header section of the html index file(s). This item usually appears in the title-bar od the browser window.

<title> item
Where item is the "album title" as it appears in the album index html file(s).

<description> item
Where item is the "description" of the album. This directive (and thus the album description) are optional.

<footer1> item
Where item is the first of two (both optional) "footer" lines of the album index file.

<footer2> item
Where item is the second of two "footer" lines.

<img> file_1, file_2, file_3, file_4, caption, description
or,
<img> file_1, file_2, caption, description

If two albums are constructed in parallel; i.e., if two file names were specified on the <index> directive line, there should be six items on the line, ordered as follows:
existing hi-resolution image .jpg file name
existing hi-resolution thumbnail .jpg file name
existing low-resolution image .jpg file name
existing low-resolution thumbnail .jpg file name
image caption
(optional) image description

If there is only one album being constructed, there will be no second set of existing image and thumbnail (.jpg or some other image type) file items.

"Inclusion" of descriptions

Descriptions (both the one for the whole album as well as the descriptions of individual photographs) are inluded as a paragraph of html text at the top of the index page or under the photograph in the page html file. Surrounding html tags (<p>, </p>) are creted by the program, and additional simple html text formatting tags (<i>xxx</i>, <b>xxx</b>, <br>...) can be used in the text.

However, a more voluminous, multi-paragraph description text might be impractical to fit on and edit on the single line of text in webPicd.def file. Therefore, description text can be included from a separate text "include file". In order to do so, the description item must specify not the description text itself, but the file name where the description text can be found, enclosed in "pointed brackets", for instance:
...<album.dscr>

All required html tags, including (typically) all the required <p> and </p> tags should be included in such description include text file.

Running webPics

The program is written in Python version 3.xx, and should therefore properly handle caption and description text using utf-8 character encoding.

Python interreter is part of the standard installation on most Linux/Unix and MacOS computers. This can be verified by opening command-line window and typing:
python3 --version
As a response, the Python iterpreter will report current version - likely something such as: "Python 3.5.2"

On MS Windows computers, Python interpreter might have to be installed prior to executing any python program. The instructions can be found on [Python.org web-site]

The folowing assumes that the working directory - one where webPics .html files will be created - includes the following files:

webPics.def: This is the text file that contains exact specifications of the content of the album. Its format and directives have been explained above in this document.

Any number of utf8 encoded description text files, (usually named "...dscr", specified in the description include directive of the webPics.def.

A set of photo files with associated "thumbnal" imeges, for either a single, or both high- and low-resolution version of the album.

In such directory, the album is created by executing the webPics.py command, with no arguments. The program will simply open webPics.def file, and execute the directives specified in it. Id any errors or inconsistencies are detected, an appropriate error message will be printed on the console before the wexacution is aborted. Otherwise, the required .html files (together with the required navigational arrow .png files) are generated. At this point, a copy of generated .html files, image files and .png arrows can be copied to a directory from where an web server (Apache or similar) can make the album available over the Internet, of a directory from where a browser can display a local-computer-resident album.

In order to further edit/correct/add to an album, yhe content of webPics.def or any of "...dscr" files can be at any point be simply modified by a text editor and the process can be repaeated as often as desired.

Download

All files required to build the demo album, as well as the webPics.py program itself, can be downloaded from:
[webPics download directory]