Generated: Monday, November 14, 2011, 09:14:55 Copyright © 2011 , Kurt NÝrmark The local LAML software home page

Reference Manual of LAML Photo Show Tool

Kurt NÝrmark © normark@cs.aau.dk Department of Computer Science, Aalborg University, Denmark.

This is the reference manual of the LAML Photo Show tool. This tool allows you to create a set of HTML files embedded in a directory with photos (jpg files). The HTML files that surround the images provides for smooth navigation, and it provides nice overviews of your pictures, all made by HTML files which can be shown in any Internet browser. Some help to photo management is also provided. This tool is based on XML-in-LAML.

A few features of this tool depend on MzScheme. Some of the more advanced features depend on ImageMagick. In order (in order to make the MzScheme system procedure available) to initiate ImageMatick from MzScheme put (require (lib "process.ss")) into your .laml file.

Seen from the context of LAML, the LAML Photo Show facility serves as a simple example of my personal use of LAML within the area of batch photo management.

Table of Contents:
1. Organization of photos 3. The photo element
2. The Top Level 4. Examples
A. Mirror Information Appendix

Alphabetic index:
lower-caption Defines the default lower caption of a photo page.
photo Defines the characteristics of each presented photo in the show.
photo-list The list of photos in the show.
photo-show The top level element which holds a number of attributes that affect the photo show of all pictures in a film.
photos-in-current-directory Automatically forms a photo list of the photos in the current directory.
title-of-show Determines the title (caption) of the current film
upper-caption Defines the default upper caption of a photo page.


1 Organization of photos

A LAML photo show is a directory of films. Each film is a directory itself. Films cannot be nested into each other; Thus the films obey a flat organization within the top-level photo show directory. There may, however, be subdirs of the photo show directory with other photo shows directories (recursive orgnization). As of now, no linking is provided to these.

The directory corresponding to a film contains a flat list of jpg files, with arbitrary names. To use the LAML photo show generator you should put a LAML file side-by-side with the photos, which describes the properties of the photo show, as related to the current film. This reference manual documents how this LAML is made. To make things easy, use the Emacs command M-x make-laml-photo-show (found in 'Tools>LAML>Make new photo show...') for this.

Thus, the typical directory and file organization is like the following:

process-all-films.laml
index.html
Film1
  1.jpg
  2.jpg
  3.jpg
  make-show.laml
  index.html
  html
   1.html
   ...
  internal
   film-description-entry.lsp
   photo-ast.lsp
   photo-list
Film2
  1.jpg
  2.jpg
  3.jpg
  index.html
  make-show.laml
  html
   1.html
   ...
  internal
   film-description-entry.lsp
   photo-ast.lsp
   photo-list
Film3
  4.jpg
  5.jpg
  6.jpg
  index.html
  make-show.laml
  html
   1.html
   ...
  internal
   film-description-entry.lsp
   photo-ast.lsp
   photo-list

You are supposed to make to top level directory and the film directories. The directory names are arbitrary. The jpg files are created by the software that transfers photos from your digital camera. You write the make-show.laml files with your text editor - Emacs, for instance. The name of this file is arbitrary, but you should use the laml extension. The LAML photo show generator makes the remaining files and directories.

Notice the file process-all-films.laml in the root which, when processed, regenerates the photo shows for all (already once processed) films; This laml file is made automatically the first to you process one of the films. If you delete it a new process-all-films.laml will appear the next time you have processed a film.

You can use the LAML photo show generator to make collections of photos from different directories, without copying any photo. To do so, make a film directory without jpg files, and address individual photos in arbitrary films from there. LAML makes it easy to do so, because you can copy the necessary photo clauses from your browser into the text editor. The names of the photos are linked to the appropriate photo clauses.

If some existing film is not supposed to make it into the index, place a file named 'exclude' side by side with the jpg files.



2 The Top Level
In this section we document the top level photo-show element, and not least its numerous attributes.

photo-show
Description The top level element which holds a number of attributes that affect the photo show of all pictures in a film. As constituents there is either a list of photo entries, or a directive to automatically collect the photos in the current directory.
XML content model ( title-of-show , upper-caption , lower-caption , ( photo-list | photos-in-current-directory ) )
XML attributes
Required: *
Default values: red
time * CDATA The time in second each picture is show in automatically progressing shows. This is a default value, which can be overwritten for each photo.
background-color CDATA The background color of photo pages. As an example "#000000" represent black, like in HTML. The LAML function rgb-color-encoding is useful to give colors.
text-color CDATA The color of the text in photo pages. As an example "#ffffff" represent white, like in HTML. The LAML function rgb-color-encoding is useful to give colors.
home-path CDATA The path to the directory with all the film. Should always be "../" with the current and flat organization of the films.
previous-film CDATA The to path of the previous film. The path is relative from the current directory. The path must have a trailing '/'. Example "../Film1/".
next-film CDATA The path to the next film. The path is relative from the current directory. The path must have a trailing '/'. Example "../Film2/".
before-first ( last-picture | previous-film | none ) Determines what comes before the first photo in the film. last-picture means 'cyclic show'. previous-film means that a link is made to the last picture in previous-film. none means that there is nothing before the first picture.
after-last ( first-picture | next-film | stop-page | none ) Determins what comes after the last photo in the film. first-picture means 'cyclic show'. next-film means that a link is made to the first picture of the next-film. stop-page means that the photo show ends with a stop page. none means that thre is is nothing after the last picture.
transition ( blend | none ) The browser transition used when shifting from photo to phote during automatically progressing shows. Notice that blend only works in Internet Explorer from Microsoft.
verbosity-level CDATA           ( 2 ) A number between 0 and 2 which controls the amount of messages given by the tool. 0 is minial and 2 is maximal.
language ( danish | english ) The language of the fixed text generated by the tool
html-mode ( raw | pp ) The formatting of the HTML pages generated by the tool. pp means pretty printed, and it takes appr. the double amount of disk space than raw. If you never read the HTML files - and why should you - you can use raw.
index-linking ( run | stop ) Determines the kind of linking used from a film page to the photos. run means that the links go to automatically progressing pages. stop means that the links go to pages without automatically progress.
default-size ( original | auto | explicit ) Determines the size of the photos, as presented by the tool. original means that the photos are presented directly, without enlarging or reducing them. auto means that the photos are enlarged or reduced to make them fit with the real estate of the browser. explicit means that we should use the witdh and height are given for each photo.
default-orientation ( portrait | landscape ) Controls the automatically enlarging or reduction, when auto is used for default-size.
portrait-percentage CDATA           ( 90 ) An image size percentage, used to affect the height of the photo. Only used for default-size auto and default-orientation portrait. An integer between 0 and 100.
landscape-percentage CDATA           ( 95 ) An image size percentage, used to affect the width of the photo. Only used for default-size auto and default-orientation landscape. An integer between 0 and 100.
photo-displacement-left CDATA           ( 0 ) A number of pixels that act as left margin of the picture. Used for horizontal displacement of the picture. Typically used to compensate for invisible scroll bar. An integer number.
photo-displacement-right CDATA           ( 0 ) A number of pixels that act as right margin of the picture. Used for horizontal displacement of the picture. An integer number.
tabular-overview-dimension CDATA           ( 3 ) An integer such as 1, 2, 3 or 4 which determines the tabular layout of the overview pages. If, for instance, 3 is given, 9 photos are shown on each overview page.
photo-tabular-window-width CDATA           ( 870 ) The width of the photo table window (pixels). Used to determine width of n x n landscape photos in an overview overview.
photo-tabular-window-height CDATA           ( 740 ) The height of the photo table window (pixels). Used to determine height of n x n landscape photos in an overview overview.
copy-film ( true | false ) A boolean attribute that controls if the photos (the jpg files) are copied to the copy-destination directories. Useful for photo management.
copy-destination CDATA An absolute path on the your computer which defines the target directory of photo copying. Only relevant if copy-film is true.
shave-resize-and-copy ( true | false ) A boolean attribute that controls shaving, resizing and copying via ImageMagic. If true, first a number of pixes is shaved both at top, bottom, left, and right side. At both top and bottom shave-height pixels are removed. At both left and right side shave-width pixels are removed. Next, the photos are reshaped to resize-width x resize-height pixels. The aspect rative is not preserved. The shaved and resized pictures are copyied to the copy-destination directory.
shave-width CDATA           ( 0 ) The number of pixels to shave both at the left and right side. Does only apply if shave-resize-and-copy is true, and if copy-destination is provided.
shave-height CDATA           ( 0 ) The number of pixels to shave both at the the top and the bottom. Does only apply if shave-resize-and-copy is true, and if copy-destination is provided.
resize-width CDATA           ( 0 ) The exact width of the resize picture. Does only apply if shave-resize-and-copy is true, and if copy-destination is provided.
resize-height CDATA           ( 0 ) The exact height of the resize picture. Does only apply if shave-resize-and-copy is true, and if copy-destination is provided.
camera CDATA           ( Canon-G3 ) The name of the camera. Intended for (future) special handling of camera specific features, such as automatic rotation of pictures.
image-transformation-software ( image-magick | none ) The kind of image transformation software interfaced to from the LAML Photoshow software. Currently we make use of ImageMagick for creation of thumbnails. If the value image-magick is used, you are supposed to have an installation of ImageMagick on your machine. See http://www.imagemagick.org/. In order for this software to be able to activate ImageMagick, the system function must be supported by your Scheme system. In PLT MzScheme the system function is supported if you use the process.ss library. For instance, put (require (lib "process.ss")) in your .laml file.
make-thumbnails-of ( all | non-existing | none ) Controls the generation of thumbnail photos. These are small pictures that act as visual indexes. The value all means that all thumbnail photos are regenerated. The value non-existing means that only non-existing thumbnails photos are generated. The value none means that no thumbnails are generated at all.
time-stamp ( auto | from-file-system | from-jpg-file | none ) How to access the time stamp of a photo file. from-file-system: Take it from the file's time stamp, as provided by the oprating system. from-jpg-file: Take it from the initial part of the JPG file. auto: Take it from the jpg file (if there), else take it from the file. none: Do not access the time stamp.
time-stamp-presentation ( date | weekday-date | time | date-time | weekday-date-time | none ) How to present the accessed time stamp of a photo file.
rotate CDATA A white-space separated sequence of rotation descriptions. A single rotation description looks like photo-file.ext:n, where n is the number of degrees to rotatethe phote. Example: "123.jpg:90" Typically used to rotate photos 90 degrees from landscape to portrait mode.

title-of-show
Description Determines the title (caption) of the current film
XML content model (#PCDATA)
See also enclosing element photo-show

upper-caption
Description Defines the default upper caption of a photo page. Can be overruled by each photo element.
XML content model (#PCDATA)
XML attributes
Required: *
Default values: red
size CDATA The size of the upper caption. A number between 1 and 6.
See also enclosing elements photo-show photo

lower-caption
Description Defines the default lower caption of a photo page. Can be overruled by each photo element.
XML content model (#PCDATA)
XML attributes
Required: *
Default values: red
size CDATA The size of the lower caption. A number between 1 and 6.
See also enclosing elements photo-show photo

photos-in-current-directory
Description Automatically forms a photo list of the photos in the current directory. This clause can be given instead of a photo list. It means that the tool automatically makes a photo list of all the jpg files in the current directory. The sorting is done in a smart way, by taking the numeric part of the file names into account. Default properties are assigned to the photos. As an important practical observation, the tool will make a file photo-list in the internal directory, with a photo list. You can replace the (photos-in-current-directory) clause with this list, and thereby control the show in a much better way.
XML content model EMPTY
See also enclosing element photo-show

photo-list
Description The list of photos in the show. Notice that the order of the photo elements in the photo-list controls the ordering of the photos in the show.
XML content model ( photo * )
See also enclosing element photo-show


3 The photo element
In this section we document the photo element, which can be used to describe each photo in the show.

photo
Description Defines the characteristics of each presented photo in the show. Some of the attributes overrules the default attributes given in the photo-show element.
XML content model ( upper-caption ? , lower-caption ? )
XML attributes
Required: *
Default values: red
file * CDATA The name of a photo file, either from the current directory (current film) or from another directory (another film). In the latter case, the path attribute must address the other film. The name consist of the proper name and the file extension (jpg). For instance "1.jpg".
path CDATA           ( ) The path of the photo file, as given by the file attribute. The path is relative to the current directory. It must end with a '/'. Example: "../Film3/", where .. means the parent directory.
time CDATA The time in second this photo is show in automatically progressing shows. Overrules the time in the enclosing photo-show element.
transition ( blend | none ) The browser transition used when shifting from this photo to the next. Notice that blend only works in Internet Explorer from Microsoft. Overrules the transition in photo-element.
size ( original | auto | explicit ) Determines the size of this photo, as presented by the tool. original means that the photo is presented directly, without enlarging or reducing it. auto means that the photo is enlarged or reduced to make it fit with the real estate of the browser. explicit means that we should use the width and height attribute of this photo. Overrules the default value given in the enclosing photo-element.
orientation ( portrait | landscape ) Controls the automatically enlarging or reduction, when auto is used as size for this photo.
width CDATA The width to be used for this photo. Use the value explicit for size if you give the width. Normally you will not want to give both width and height.
height CDATA The height to be used for this photo. Use the value explicit for size if you give the height. Normally you will not want to give both width and height.
See also enclosing element photo-list


4 Examples

In this section we show examples of LAML files.

The first file is similar to the file produced by the Emacs command M-x M-x make-laml-photo-show:

(load (string-append laml-dir "laml.scm"))
(laml-style "xml-in-laml/photo-show/photo-show")

(define photo-show-title "Example")

(photo-show
  'language "danish"                                       ; danish or english
  'time "3"
  'background-color (rgb-color-encoding black)             ; color string, like "#123456"
  'text-color (rgb-color-encoding white)                   ; color string, like "#123456"
  'home-path "../"
  'transition "none"                                       ; none or blend
  'tabular-overview-dimension "3"                          

  'previous-film "../Film1/"
  'before-first "previous-film"                            ; last-picture, previous-film, none
  'next-film "../Film3/"
  'after-last "next-film"                                  ; first-picture, next-film, stop-page, none

  'index-linking "stop"                                    ; run or stop
  'default-size "auto"                                     ; original, auto, explicit
  'default-orientation "landscape"                         ; portrait or landscape

  'verbosity-level "2"                                     ; 0, 1, 2


  (title-of-show photo-show-title)
  (upper-caption 'size "6" photo-show-title)
  (lower-caption 'size "4" "")

  (photos-in-current-directory)

)

The purpose of the next laml file is to enumerate 'the best photos' in a large collection of films and photos:

(load (string-append laml-dir "laml.scm"))
(lib-load "xml-in-laml/xml-in-laml.scm")
(laml-style "xml-in-laml/photo-show/photo-show")

(photo-show
  'time "8"
  'language "english"
  'transition "blend"
  'html-mode "pp"
  'home-path "../"

  'tabular-overview-dimension "3"
  'before-first "none"
  'after-last "stop-page"

  (title-of-show "My Best Photos")
  (upper-caption 'size "6" "")
  (lower-caption 'size "3" "")
  

  (photo-list
    (photo 'time "3" 'path "../Film34/" 'file "109_0957.JPG" 'size "auto" (upper-caption 'size "6" "") )
    (photo 'time "3" 'path "../Film34/" 'file "109_0960.JPG" 'size "auto" (upper-caption 'size "6" "") ) 
    (photo 'time "3" 'path "../Film34/" 'file "109_0968.JPG" 'size "auto" (upper-caption 'size "6" "") )
    (photo 'time "3" 'path "../Film34/" 'file "109_0974.JPG" 'size "auto" (upper-caption 'size "6" "") )   
    (photo 'time "3" 'path "../Film34/" 'file "109_0975.JPG" 'size "auto" (upper-caption 'size "6" "") ) 
    (photo 'time "3" 'path "../Film32/" 'file "109_0915.JPG" 'size "auto" (upper-caption 'size "6" "") )

  )

)



Mirror Information Appendix.
Mirror name: laml-photo
Automatic loading of common XML-in-LAML library? No
List of action elements (photo-show)
Generation of named mirror functions: Yes
Mirror name prefix: None
Transliteration of CDATA? Yes
List of elements for which transliteration does not apply: '()
List of elements for which all white spacing is preserved: '()
Name of HTML character transformation table: html-char-transformation-table
Are default DTD attributes passed explicitly? No
Are attributes only allowed to be text strings? Yes
Is extended textual contents allowed? No
Is white space represented by this mirror? Yes
How are duplicated XML attributes handled: 'keep-all


Generated: Monday, November 14, 2011, 09:14:55
Generated by LAML SchemeDoc using LAML Version 38.0 (November 14, 2011, full)