PyAlbum Options

This page describes all options of PyAlbum in depth and where each option may be used.
All options (their names) are in general not case sensitive. you can write them all lower case or upper case or even mixed as you like. The only exception are the user defined options (more on them later), which must be all lower case when used in template files.
But this is not true for the option values! Most of the time they must be written exactly as defined here.

First, we have to understand the sources of options. Each option has an allowed item, which can be up to four different sources.
Those four possible sources are divided into two classes:

Command Line:
Here you must precede each name with -- (two minus characters). The syntax from the command line is:
 --optionName=optionvalue
Some options have a short form usable only from the command line. They only have one preceding '-', such as '-h' or '-v'. These options take an immediate action and need no value.
Configuration Files:
Within configuration files (e.g. 'pyalbum.cfg' or 'template.cfg') the syntax is slightly different:
 optionName=optionvalue 
Those files may contain empty lines and lines beginning with a '#', which are skipped as comments. They are stored in the template directory ('template.cfg' is a must there!) or in each directory where the source pictures are read from.

The four sources are: (caption "allowed" in table below)

cmdline
These options are set from the command line. There are only few which can be used from here. But they always have highest priority. That means, if you set a specific option from the command line and later on change it from a configuration file, the new value is ignored!
first
This is the first read configuration file. It can be defined from the command line with '-c file' or '--config=file'. If this option is not given, PyAlbum tries to read the first file 'pyalbum.cfg' in the current directory.
first options are only allowed before the program really starts, and changing them later would be useless and senseless. For example, the InputDir can be defined only once at the beginning.
album
This is an optional file named 'pyalbum.cfg' in the current input directory. It is searched for at each directory level. Here you can switch your preferred title and description methods or even the template.
template
This is a mandatory 'template.cfg' file in the template directory. Within these files the output files must be defined. And user options are only declarable within a 'template.cfg'.

Option types are: (caption "type" in table below)

string
A simple character string. Do not use quotes or double quotes here, except explicitly stated! (This will be fixed soon!)
Multi value string
Use this option multiple times. All values will be collected in a list. Order is important for some options. The list will be cleared for each read option source if that option is inside the source, otherwise the list will remain unchanged.
One choice
Choose one of the possible values.
Multi value choice
This is almost the same as Multi value string except you have to use one or more of the given choices.
Boolean
This sets an option to True or False. You can set those options like this:
False: "0", "f", "false", "n" or "no"
True: "1", "t", "true", "y" or "yes"
Integer
A simple whole number >= 0
Float
A floating point number >= 0.0 You must use a decimal point, not a comma!

User options

To extend the usability and configuration possibilities, user options can be declared inside templates an dused inside templates and album files. They are declared in 'template.cfg' files with the multi value option xUserOpts. You can use them from now on within the same 'template.cfg' file or within album configurations.
User options must begin with 'user' and be all lower case! Inside a template file they are used by @user.xxx
User options can be defined (=set) before they are declared, but if they are used before they are declared, a run time error occurs. With this method you are forced to be consistent between template.cfg and template files.
You can use this feature for internationalisation. Simply define a user.textback and use it within the template file.
Let us look at an example part of a template.cfg:

# declare two user options:
xUserOpt = user.tableborder1
xUserOpt=user.copyright
xUserOpt = user.textnext
# define the values:
user.tableborder1=3
user.copyright = © 2004 Zaphod Beeblebrox
# german for "next":
user.textnext = nächstes
And now into a template source file index_em.htt:
<table border="@user.tableborder1">
  <tr>
    <td>
      Copyright: @user.copyright
      <a href="@pic.nextHref">@user.textnext<a>
    ...

In summary, these option do not have any meaning inside the program. They solely exist to be given verbatim to the generated output files. Currently you have to change the values in the templates, but in a later version it will be possible to alter them in the GUI.

Table of all options

The following table contains all options in functional order, grouped by internally defined option groups.

Basic Options

Defined by system and PyAlbum

version
type: [N/A]
default: NODEFAULT
allowed: cmdline
show program's version number and exit
help (-h)
type: [N/A]
default: NODEFAULT
allowed: cmdline
show this help message and exit
Verbosity
type: Integer (0 to 5)
default: 1
allowed: cmdline
Defines verbosity level of shell output. Each level includes all lower levels.
  • 0: show errors only
  • 1: show warnings (default)
  • 2: show directory processing
  • 3: show picture processing
  • 4: show processing of each output file
  • 5: show information for each directory at the end
-v
type: [N/A]
default: <none>
allowed: cmdline
Set output verbose. This is a shortcut for "--verbosity=2"
TemplateDir
type: String
default: <none>
allowed: cmdline, first
Directory where the template directories are in.
TemplateName
type: String
default: testall
allowed: cmdline, first, album
Name of the template to use. This is a directory inside the TemplateDir
Gui (-g)
type: [N/A]
default: <none>
allowed: cmdline
Show the GUI.
Recursive
type: Boolean
default: True
allowed: cmdline, first, album
Process the InputDir and all subdirectories.
RebuildAll
type: Boolean
default: False
allowed: cmdline, first
Rebuild all pictures and output files. Bypass the optimization.
RebuildOut
type: Boolean
default: False
allowed: cmdline, first
Rebuild all output files. Bypass the optimization. Set to True, if you want to generate output files despite of optimization (eg. changed FocalFactors.txt).
Config (-c)
type: String
default: <none>
allowed: cmdline
Read a configuration file (first).
ExcludeDir (-x)
type: Multi value string
default: ['preview', 'ignore', 'template', 'output']
allowed: cmdline, first
Directories to ignore while processing the input tree. Can only be used from command line or the first configuration file!
ExtPicture (-p)
type: Multi value string
default: ['.jpg', '.jpeg', '.tga', '.tif', '.tiff', '.gif', '.bmp', '.png', '.pcx']
allowed: cmdline, first
Which file types are considered as 'pictures'? With this option you define the file extensions processed. Case is insignificant here, and the leading dots are optional.
If the imaging library can not read or process such a file, an error is shown and the file is ignored.
If the default does not fit your needs, you should set this option in 'first', i. e. within a pyalbum.cfg in the input directory.
ExtMovie (-m)
type: Multi value string
default: ['.avi', '.mpg', '.mpe', '.mpeg']
allowed: cmdline, first, album
Which file types are considered as 'movies'? With this option you define the file extensions processed. Case is insignificant here, and the leading dots are optional.
If option 'useMovie' is enabled, the program looks for files with the same base name as the picture (case must match!) and all extensions given by this option 'ExtMovie'. The first found matching file delivers the 'pic.movieXX' attributes.
The file is copied to the 'full' output directory (if option FullCopy is enabled) and renamed according to the 'full' options.
Movies are not processed on their own, they always are tied to a picture.
ExtSound (-s)
type: Multi value string
default: ['.wav', '.mp3']
allowed: cmdline, first, album
Which file types are considered as 'sounds'? With this option you define the file extensions processed. Case is insignificant here, and the leading dots are optional.
If option 'useSound' is enabled, the program looks for files with the same base name as the picture (case must match!) and all extensions given by this option 'ExtSound'. The first found matching file delivers the 'pic.soundXX' attributes.
The file is copied to the 'full' output directory (if option FullCopy is enabled) and renamed according to the 'full' options.
Sounds are not processed on their own, they always are tied to a picture.
Title
type: String
default: <none>
allowed: cmdline, first, album
Title of the first album.
RootParent
type: String
default: index.html
allowed: cmdline, first
Defines the file name of the parent of the topmost directory. Default is "index.html", which generates a @gal.parentHref of "../index.html". This file does not need to exist in the file system of the generating machine. Set this to an empty string if you do not want this feature. Instead you can set and define user options, which lead to a 'home' page.
CharSet
type: String
default: ISO-8859-1
allowed: cmdline, first, album, template
Defines the output character set, but has no influence on the output. May be used as '@gal.charset' inside templates.
Sort
type: One choice (filename, filesize, filetime, exiftime)
default: filename
allowed: cmdline, first, album
Defines how pictures are sorted.
SortOrder
type: One choice (asc, desc)
default: asc
allowed: cmdline, first, album
Defines how pictures are sorted: ascending or descending.
DateFormat
type: String
default: %d.%m.%Y
allowed: cmdline, first, album
A Python format string for displaying dates. Used in file dates and EXIF dates.
Format codes for time and date (see also Python documentation on 'time' module):
%a Locale's abbreviated weekday name.
%A Locale's full weekday name.
%b Locale's abbreviated month name.
%B Locale's full month name.
%c Locale's appropriate date and time representation.
%d Day of the month as a decimal number [01,31].
%H Hour (24-hour clock) as a decimal number [00,23].
%I Hour (12-hour clock) as a decimal number [01,12].
%j Day of the year as a decimal number [001,366].
%m Month as a decimal number [01,12].
%M Minute as a decimal number [00,59].
%p Locale's equivalent of either AM or PM.
%S Second as a decimal number [00,61].
%U Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.
%w Weekday as a decimal number [0(Sunday),6].
%W Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0.
%x Locale's appropriate date representation.
%X Locale's appropriate time representation.
%y Year without century as a decimal number [00,99].
%Y Year with century as a decimal number.
%Z Time zone name (no characters if no time zone exists).
%% A literal "%" character.
TimeFormat
type: String
default: %H:%M:%S
allowed: cmdline, first, album
A Python format string for displaying times. Format codes see DateFormat.
InputDir (-i)
type: String
default: .
allowed: cmdline, first
The directory, where the pictures (and other files) are read from. Can also be given as a normal argument to PyAlbum.
OutputDir (-o)
type: String
default: output
allowed: cmdline, first
Where to put all output? Defaults to <current dir>/output. Can also be given as a normal argument to PyAlbum.
FolderTitleMethod
type: Multi value choice (MPR, FNR, ONR, PAR)
default: Title, ONR
allowed: cmdline, first, album
Defines how the title of a folder (album, gallery) is determined. The possible sources are tried one after the other, until a value is found.
May be used as @gal.title or @dir.title inside templates.
MPR: Value xxx of line 'folderTitle=xxx' in file "meta.properties" in input directory.
PAR: Title of the parent gallery. At level 0 this is always option "Title".
FNR: Name of the output directory (converted for safe output). This value is never empty.
ONR: Name of the original directory. This value is never empty.
FolderDescriptionMethod
type: Multi value choice (MPR, TXT)
default: <none>
allowed: cmdline, first, album
Defines how the description of a folder (album, gallery) is determined. The possible sources are tried one after the other. Each non empty value adds an entry to the description[] list.
May be used as @gal.description or @dir.description inside templates. The result is converted for HTML output, so do not use HTML tags here!
MPR: Value xxx of line 'folderDescription=xxx' in file "meta.properties" in input directory.
TXT: Content of a text file named "<dirname>.txt" outside of the input directory. So the directory and the file are at the same level within the file system.
PicTitleMethod
type: Multi value choice (DES, CPR, MPR, FNR, FNE, ONR, ONE, EID, COM)
default: ONR
allowed: cmdline, first, album
Defines how the title of a picture is determined. The possible sources are tried one after the other, until a value is found.
May be used as @pic.title inside templates. The resulting value is converted to HTML.
Defaults to value of ONR if no option given.
DES: Value xxx of line <picname.ext><whitespace>xxx or line "<picname.ext>"<whitespace>xxx in file "descript.ion" in input directory.
CPR: Value xxx of line <picname.ext><=xxx in file "comments.properties" in input directory.
MPR: Value xxx of line title.<picname.ext>=xxx in file "meta.properties" in input directory.
FNR: File name without extension of the (cleaned and unique) output picture.
FNE: File name with extension of the (cleaned and unique) output picture.
ONR: Original filename without extension of picture.
ONE: Original filename with extension of the picture.
EID: Value "ImageDescription" from EXIF data.
COM: JPEG comment
PicDescriptionMethod
type: Multi value choice (DES, CPR, MPR, TXT, EID, EUC, COM)
default: <none>
allowed: cmdline, first, album
Defines how the description of a picture is determined. The possible sources are tried one after the other. Each non empty value adds an entry to the description[] list.
May be used as @pic.description inside templates. The result is converted for HTML output, so do not use HTML tags here!
DES: Value xxx of line <picname.ext><whitespace>xxx or line "<picname.ext>"<whitespace>xxx in file "descript.ion" in input directory.
CPR: Value xxx of line <picname.ext>=xxx in file "comments.properties" in input directory.
MPR: Value xxx of line description.<picname.ext>=xxx in file "meta.properties" in input directory.
TXT: Content of a file <picnamewithoutExtension>.txt inside the input directory.
EID: Value "ImageDescription" from EXIF data.
EUC: Value "UserComment" from EXIF data.
COM: JPEG comment
KillNlInTitles
type: Boolean
default: True
allowed: cmdline, first, album, template
Defines whether NEWLINEs in titles are replaced by a space. Useful, if you have line breaks in title sources and use that title as html page title.
DefaultFocalFactor
type: Float (>=0.0)
default: 0.0
allowed: cmdline, first, album
Normally pic.exif.FocalLengthConv (focal length equivalent for 35 mm cameras) is calculated by looking up the factor in file FocalFactors.txt with camera Make and Model.
If there is an EXIF FocalLengthIn35mmFilm defined within the file, its value is used, otherwise if there is no factor for the specific camera found inside the file, there are 2 possibilities:
  1. This option is 0.0 (the default): an error text is returned "No value found..."
  2. This option is greater than 0.0: this value is taken as multiplier.
The best way is to take the camera manual, calculate the factor and create a new entry in FocalFactors.txt (and drop me a mail, so I can extend the default file!)
FilterDir
type: String
default: <programPath>/filters
allowed: cmdline, first
Directory where the filters reside.
Filter
type: Multi value string
default: <None>
allowed: cmdline, first, album
Define image filters. See own Filters page. For filters used in templates see option TFilter.
TFilter
type: Multi value string
default: <None>
allowed: template
Define image filters. See own Filters page. These are reserved for templates and build their own filter chain.
FontDir
type: String
default: <programPath>/fonts
allowed: cmdline, first
Directory where the PIL fonts reside. They are used to create the album thumbnail and by all text filters.

Output (HTML) and template Options

What and where to generate.

HtmlRelDir
type: String
default: html
allowed: cmdline, first, album, template
The directory where to put the html PICTURE files, relative to OutputDir.
OutputFormat
type: One choice (TEXT, HTML)
default: HTML
allowed: template
Determines, whether special characters are replaced by HTML entities during output.
PicsPerRow
type: Integer (>=1)
default: 5
allowed: cmdline, first, album, template
Maximum thumbnails beneath on index pages. (Table columns)
MaxRows
type: Integer (>=1)
default: 5
allowed: cmdline, first, album, template
Maximum rows of thumbnails per index page (Table rows)
ResDir
type: String
default: <none>
allowed: template
A resource directory within the template, which is copied to the destination album.
ResRoot
type: Boolean
default: True
allowed: template
Copy resource directory only ONCE (True) or to each album level (False).
OnceFile
type: Multi value string
default: <none>
allowed: template
Multiple template files ONCE for base output dir
IndexFile
type: Multi value string
default: <none>
allowed: template
Multiple template files for each index page in base output dir
PictureFile
type: Multi value string
default: <none>
allowed: template
Multiple template files for each slide/picture page in htmlreldir

Full (original) Picture Options

How to handle original pictures.

FullCreate
type: Boolean
default: True
allowed: template
Create links to full sized pictures?
FullCopy
type: Boolean
default: <none>
allowed: cmdline, first, template
Copy original pictures to outputdir? If full pictures are created, but not copied, HREFs link to the InputDir!
Beware: if this option is disabled, be sure to copy the content of the input directory to the web server with the same relative path to the output directory! And be sure, that picture and directory names are web safe!
FullRelDir
type: String
default: pics_fl
allowed: template
The directory where to put the original pictures, relative to OutputDir
FullOutName
type: String
default: %s
allowed: template
Template for base name of output (html) files containing FULL size pictures. MUST contain a '%s'
readEXIF
type: One choice (none, normal, full)
default: normal
allowed: cmdline, first, album, template
Define, how much EXIF data should be read from the pictures. The pic.exif attributes are always available, but will be empty if this option is set to none.
Normal means, read the defined standard properties, but no MakerNotes and no extended thumbnail data. This is the default.
The JPEG comments COM, Comment, UCCOM and UCComment are always read since they are no real EXIF parts.
A template can use all EXIF properties through the pic.exif.exiflist object, which is a sorted list of (name, value) pairs.
useMovie
type: Boolean
default: False
allowed: cmdline, template
Search for a movie with the same base name as the picture in the input directory and 'tie' it to the picture (see properties pic.movieXX and option ExtMovie).
useSound
type: Boolean
default: False
allowed: cmdline, template
Search for a sound file with the same base name as the picture in the input directory and 'tie' it to the picture (see properties pic.soundXX and option ExtSound).

Thumbnail Picture Options

How to handle thumbnail pictures.

ThumbCreate
type: Boolean
default: True
allowed: template
Create thumbnail sized pictures?
ThumbGallery
type: Boolean
default: True
allowed: template
Create thumbnails for galleries (directories)?
ThumbGalleryTexts
type: String
default: '1 Subalbum','%d Subalbums','1 Picture','%d Pictures'
allowed: template, album
Which texts on gallery thumbnails? These must be 4 comma separated strings. The generated text is placed at the bottom of galler ythumbnails.
ThumbGalleryOnlyImage
type: String
default: <none>
allowed: cmdline, first, album, template
The image for galleries without pictures, but only with subgalleries
ThumbRelDir
type: String
default: pics_tn
allowed: template
The directory where to put the thumbnail pictures, relative to OutputDir.
ThumbOutName
type: String
default: %s_TN
allowed: template
Template for base name of generated thumbnails. MUST contain a '%s'!
ThumbFill
type: One choice (normal, fill, crop)
default: normal
allowed: cmdline, first, album, template
Extend all thumbnails to maximum thumb size (and fill the background with color ThumbFillColor), do nothing or crop them to maximum thumbnail size.
ThumbFillColor
type: String
default: #FF0000
allowed: cmdline, first, album, template
The background color for filled thumbnails. Only used if option ThumbFill=fill!
ThumbMaxWidth
type: Integer (>=1)
default: 130
allowed: template
Maximum width of thumbnails (with PanoramaWidth==1).
ThumbMaxHeight
type: Integer (>=1)
default: 100
allowed: template
Maximum height of thumbnails.
ThumbRatio
type: Float (>=0.0)
default: 1.4
allowed: cmdline, first, album, template
Calculate panorama width for thumbs. The panoramaWidth of a picture is calculated by int(round(width/height/ThumbRatio)). It will always be a whole number between 1 and option PicsPerRow.
If you do not want this feature at all, set this value to 0.0, so all pictures are generated with panoramaWidth=1

LowRes Picture Options

How to handle lowres pictures.

LowResCreate
type: Boolean
default: True
allowed: template
Create lowres pictures?
LowResRelDir
type: String
default: pics_lr
allowed: template
The directory where to put the lowres pictures, relative to OutputDir
LowResOutName
type: String
default: %s_LR
allowed: template
Template for base name of generated lowres pictures. MUST contain a '%s'!
LowResWidth
type: Integer (>=1)
default: 640
allowed: template
Maximum width of lowres pictures.
LowResHeight
type: Integer (>=1)
default: 512
allowed: template
Maximum height of lowres pictures.

User defined template Options

This option defines, which user options may be used within templates.

XUserOpts
type: Multi value string
default: <none>
allowed: template
User defined options usable within template files. Must be declared with this option. All names must begin with 'user.'.
user.xxxx
type: String
default: ""
allowed: template, album
User defined options usable within template files and album configuration files. Must be declared within a template. All names must begin with 'user.'
Set with user.xx=test, use in a template file as @user.xx
It is allowed to declare and define them in any case (lower, upper, mixed), but usage within templates always has to be lower case!

top of page