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 = &copy; 2004 Zaphod Beeblebrox
# german for "next":
user.textnext = n&auml;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:

This option is 0.0 (the default): an error text is returned "No value found..."
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