NAME

icontact - create contact sheets from images of different formats

SYNOPSIS

icontact [ switches ] [ { image file | parameter file } ... ]

DESCRIPTION

icontact is a highly configurable perl script that takes a bunch of image files and creates contact sheets. icontact determines the file format by the file name extension of the input files and then uses internal tables to look up the commands it needs to execute in order to convert the images to the PPM format. Once in the PPM format, icontact uses various pbmplus commands to create the contact sheets. icontact is particularly useful if you have lots of image files in all sorts of different formats and you want to create an index of all of them without converting them all to a common format first.

Besides perl, icontact requires the NetPBM package which is based on pbmplus. The Independent JPEG Group's package (cjpeg, djpeg) is also necessary if you are going to be processing any JPEG files. Ghostscript can be used to turn PostScript files into PPM files for inclusion in a contact sheet. It should not be difficult to make icontact use filters from other packages as long as there is a way to go to and from the PPM format with them.

OPTIONS

Switches that do not take arguments may be combined into a single switch: -abBlv. Switches that take arguments must be followed by their arguments with space in between: -c 10 -r 5. The fancy way combine all these switches is: -abBlvc 10 -r 5. That is, you can combine the switches together in any way you like so long as the switches that take an argument are followed by said argument with a space in between. If you don't want to get fancy, just specify each switch by itself: -a -b -B -c 10 -l -r 5 -v.

In all cases in which a switch does not take an argument, -switch will turn the switch on, and +switch will turn the switch off. For example, -l will turn labels on, and +l will turn labels off. This can be useful if you have a particular set of switches set in a configuration file and you want to temporarily disable a switch to make a sheet without changing the configuration file. If a set of switches are combined into a single switch that leads with either a + or a -, the + or - affects all the switches in that set of switches. If a switch that takes an argument is specified with a leading +, it is assumed that you meant -.

An argument of -- terminates the options list and signals the beginning of the file list.

Switches can be specified in two places: the command line and a configuration file. The command line switches are the most potent — they override everything. The switches in a configuration file are the next most potent — they are only overridden by the command line switches. The internal defaults of icontact are overridden by both the command line and configuration file.

±a: Make the output sheets fit into the size specified with the -x and -y switches. Setting the -x and -y switches to the size of your screen will yield contact sheets which are no larger than your screen. The -r and -c switches will be ignored if the -a switch is present because the number of rows and columns is figured out dynamically and will probably change from sheet to sheet unless the -i switch is specified or all the source images are of the same size to begin with.
±B: Add a border to each image in the contact sheet. The colors of the border stripes may be specified with the -z switch.
±b: Use the basename(1) of the file name instead of the whole path name to the file in labels. This switch will be ignored if the -l switch is not specified.
-C color: Use color for the background of the contact sheet. The default value is ``black''.
-c n: Make the contact sheets with n columns of images. This switch is ignored if the -a switch is specified. The default value is 7.
-D format: If a file without a suffix is processed, assume it is a format file. The default value is ``.gif''.
-d dir: Put the contact sheets in dir when completed. The default value is ``.''.
-F file: file will be used with pbmtext as a font for labels. Each image's height will be increased by the height of the characters in the font. This switch will be ignored if the -l switch is not specified. By default, pbmtext's internal font is used. Check out pbmtext's man page for instructions on how to create a font file.
-f format: Encode the finished contact sheets as format files. The default value is ``.ppm.Z''.
±g: Generate a parameter file for each contact sheet produced. This parameter file will be named prefix###.format.suffix, where prefix is the contact sheet name, ### is the number of the contact sheet, format is the file format of the contact sheet, and suffix is the parameter file suffix specified with the -P switch. When icontact sees one of these files on the command line, it looks in the parameter file for the names and locations of images inside the sheet specified by removing the suffix from the parameter file name. These images will be cut out and put in the new output sheets instead of being fully processed again. For best results when using parameter files on the command line, select no quantization and a lossless file format both when the sheet is first created and also when its parameter file is used on the command line. This will prevent information loss if this operation is performed multiple times.
±help: This is a special case which will print out a help message explaining icontact's switches. Any other unrecognized switch will do the same.
-h n: Make each image in the contact sheets a maximum of n pixels high. The aspect ratio of the images will not be changed. This switch will be ignored if the -X switch is also specified. The default value is 100.
-I color: Use color for the area around the images when the -i switch is used. This switch will be ignored if the -i switch is not also specified. The default value is ``black''.
±i: Make all of the images the same size. The size of the images is determined by the dimensions specified with the -w and -h switches. If the shrunken image is smaller than the dimensions specified with the -w and -h switches, the image will be padded with blank space. The color of this blank space can be set with the -I switch. Use of this switch can create contact sheets with lots of blank space between images. This switch cannot be used with the -X or -Y switches.
-K file: Use file as the configuration file. The default configuration file name is ``~/.icrc''. Putting this switch in the configuration file will have no effect since once you're in a configuration file, it's too late to switch to another one.
±k: Don't reference the configuration file. Putting this switch in the configuration file will have no effect since once you're in the configuration file, it's too late to back out.
±L: When creating sheets, use left justification on the rows instead of the default center justification. If this option is used in conjunction with the -R option, the options will negate each other.
±l: Attach a label containing the image's file name below each image. This name may be truncated if the label is wider than the image. The behavior of this switch can be changed with the -b, -F, and -T switches.
-M scale: Scale all the input images to scale*100 percent of their original size. The value of scale may be in the range (0.0, infinity), although using values towards the upper end of that range will require a great deal of memory. Values of scale greater than 1.0 will enlarge the input images (i.e., a scale of 2.0 will double the size), and values less than 1.0 will shrink the input images (i.e., a scale of 0.5 will halve the size). This switch may not be used with the -i, -X, -Y, or -Z switches for semi-obvious reasons. The default is not to scale images in this way.
±m: Attach a label containing the image's size in pixels (widthxheight) below each image. If the -l switch is also specified, this label will go under the label containing the file name. This label may be truncated if the label is wider than the image. The behavior of this switch can be changed with the -F and -T switches.
-N value: Use value as the nice value for all child processes. The default value is 0. Only root may specify negative nice values.
-n file: Take the file names from file and add them to the ones specified on the command line, if any. The file names in file must be one per line. These file names will be processed after the file names specified on the command line.
±O: Find the number for the first sheet by looking in the destination directory for sheets with the same prefix and format that we are going to create. Take the highest numbered one, increment, and this is the new starting number for the new sheets. If there are no files with the same prefix and format in the destination directory, the new sheets will start with 001. This switch cannot be used with the -o switch.
-o n: The output sheet numbering will begin with n and increase from there. This switch cannot be used with the -O switch. The default value is 001.
-P suffix: suffix will be used as the extension of the contact sheet parameter files if the -g switch is specified. See the -g switch description for more details. The default value is ``.icp''.
-p prefix: Name the contact sheets prefix###.format, where ### is the number of the contact sheet and format is the format of the contact sheet. The default value is ``ic-''.
-Q quantization program: Use quantization program to quantize the contact sheets. The quantization program should accept PPM format files as input and take one numeric argument specifying the number of colors to be left in the contact sheets. It is possible to use a pipeline such as: ``cjpeg -Q 100 | djpeg -q''. The default value is: ``ppmquant -fs''.
-q n: Quantize the contact sheets down to n colors. A value of 0 will turn off quantization. The default value is 0.
±R: When creating sheets, use right justification on the rows instead of the default center justification. If this option is used in conjunction with the -L option, the options will negate each other.
-r n: Make the contact sheets with n rows of images. This switch is ignored if the -a switch is specified. The default value is 7.
±S: Sort the file names taken from the command line (and, optionally, from the file specified with the -n switch) into alphabetical order before making the sheet.
±s: Be silent. Don't output anything except warnings and fatal errors.
-T color: Use color as the color of the text of the image labels. The format of color may be any that pgmtoppm understands. The default value is ``white''.
-t tmpdir: Use tempdir to hold icontact's intermediate files. icontact tries to minimize the amount of temporary space it needs, but it's disk space requirements can be large depending upon the particular operation it is performing. If you have a tiny /tmp directory, you'll want to use this switch to aim icontact at a larger chunk of disk. The default value is ``/tmp''.
±U: Delete duplicate entries in the list of image file names, even if they differ in capitalization. For example, ``Foo.gif'' and ``foo.gif'' would compare as if the same. The first file with any particular name will make it through, but following files with the same name will be deleted from the file name list. The default is to allow duplicate file names. If this switch is used with the -u switch, the -u switch will be ignored and the comparisons will be done in a case insensitive fashion.
±u: Delete duplicate entries in the list of image file names. The first file with any particular name will make it through, but following files with the same name will be deleted from the file name list. The default is to allow duplicate file names. If this switch is used with the -U switch, the -u switch will be overridden and the comparisons will be done in a case insensitive fashion.
±v: Cause all sorts of possibly interesting output to be printed to the screen. The output includes the current parameters of icontact and all the shell commands it is running. If you're having difficulty getting icontact to do what you want it to do, try using this switch to see what icontact is doing behind your back.
-w n: Make each image in the contact sheets a maximum of n pixels wide. The aspect ratio of the images will not be changed. This switch will be ignored if the -Y switch is also specified. The default value is 100.
±X: This switch will make all the images the same width. Their heights will be whatever they are when the image comes out of pnmscale. The aspect ratios of the images will not be changed. Wide images will be short and tall images will be tall. This switch cannot be used with the -i or -Y switches.
-x n: When used with the -a switch, n specifies the width of the output sheets in pixels. This switch will be ignored unless the -a switch is specified. The default value is 1152.
±Y: This switch will make all the images the same height. Their widths will be whatever they are when the image comes out of pnmscale. Wide images will be wide and tall images will be skinny. The aspect ratios of the images will not be changed. This switch cannot be used with the -i or -X switches.
-y n: When used with the -a switch, n specifies the height of the output sheets in pixels. This switch will be ignored unless the -a switch is specified. The default value is 900.
±Z: This switch will prevent the images from being scaled. For obvious reasons, you should probably only use this option when the input images are fairly small. This switch cannot be used with the -i switch. If it is used with the -X, -Y, -w, or -h switches, -Z will override.
-z color [color ...]: When used with the -B switch, the layers of the borders around the images will be striped (from the inside out) with the colors specified after this switch. Double quotes should be used to group the colors together with white space in between. The colors can be in any format that ppmmake understands. The default is ``white black white''.

ENVIRONMENT

TMPDIR, TEMPDIR: These environment variables can be used to set the location of icontact's temporary directory. If both TMPDIR and TEMPDIR are set, a warning will be printed and the value of TMPDIR will be used. If only one of them is set, that one will be used. This value will be overridden if the -t switch is used on the command line or in the configuration file.

FILES

configuration file

The name of the default configuration file is .icrc in your home directory. The proper syntax of this file is as follows: Comments begin with a # and terminate with a newline. Lines may be blank. Double quotes may be used to group words together after the keyword switches. Configuration lines begin with one of the following keywords: encode, decode, switches, or quantize. Lines beginning with encode are used to define commands icontact will use to encode files into a specific format. Lines beginning with decode are used to define commands icontact will use to decode files of a specific format. Lines beginning with quantize are used to define the quantization value of sheets created in a specific format. The format of lines beginning with encode, decode or quantize is this:

<keyword> <format> <value>

<format> may not contain white space, but <value> may. If <keyword> is quantize, then <value> must be a non negative integer. The format of lines beginning with switches is this:

switches <command line switches>

<command line switches> may be any set of switches that you can specify on the command line and may contain white space.

# sample icontact configuration file
switches    -g                   # parameter file generation
switches    -B                   # borders
switches    -l                   # add labels
switches    -b                   # basename(1) the labels
switches    -S                   # sort all the filenames
switches    -v                   # verbose
switches    -a                   # automatic sizing
switches    -x 640               # screen width
switches    -y 480               # screen height
switches    -Q ppmquant          # quantization program
switches    -z "red white blue"  # stripes
# OR:
# switches  -gBlBSvWax 640 -y 480 -Q ppmquant -z "red white blue"
encode      jpg    cjpeg -o
decode      jpg    djpeg
encode      ppm       
decode      ppm       
quantize    gif    256
quantize    jpg    0

contact sheet parameter files

These files are lists of file names (one per line) followed by the image's x and y offsets into the contact sheet and then the image's height and width. They are created by using the -g switch. These files allow blank lines and comments beginning with # and terminating with a newline.

$TMPDIR/icb-$$

a temporary file for storing the image border when the -i and -B switches are specified

$TMPDIR/icc-$$

temporary file for storing a color pixmap for background colorization

$TMPDIR/ice-$$

a temporary file for holding the image pad when the -i switch is specified

$TMPDIR/ici#-$$

temporary files for storing images before they are made into rows

$TMPDIR/icp#-$$

temporary files for holding expanded sheets while icontact cuts images out of them

$TMPDIR/icr#-$$

temporary files for storing rows before they are made into sheets

$TMPDIR/ict-$$

a temporary file for storing labels and borders

DIAGNOSTICS

The diagnostic messages are intended to be self explanatory. If icontact dies and tells you that a pipeline returned an unsuccessful exit code and you can't tell what caused the crash, try running the same command with the -v switch. You should then be able to see an error message indicating what part of the pipeline was not successful.

BUGS

If an image's file name has dots in it that do not come before a recognized file format extension, the unrecognized extensions will be ignored and icontact will try to decode the image using the remaining extensions. It may guess wrong, though, and the decode command may fail.

icontact allows you to specify stupid output formats like ``.gif.Z''.

When in automatic sheet sizing mode (-a), if a single processed image is larger than the dimensions of a sheet, this image will appear in a sheet all by itself, and the sheet will be larger than you specified with -x and -y.

The parameter file processing code will fail if it is used on filenames that contain white space.

When images are cut out of previously made contact sheets by specifying a parameter file on the command line, they are not rescaled. So, even though you may have specified -w 100 -h 100 this time, the images cut from the previously made contact sheet will be the same size they were when that sheet was first made. This shouldn't be a problem for you if you choose an image size early and stick with it.

If a particular file name appears in two or more different parameter files on the command line, the image will be displayed more than once, but the image used will be cut from the last parameter file listed. A warning will be printed if this situation occurs.

The dimensions of images specified in parameter files are listed as the dimensions of the sheet the image was cut from when the -m switch is used. The original size information for each image is not stored in the parameter files.

AUTHOR

Mark B. Hanson
mbh@panix.com

Bug reports, patch donations, suggestions, questions, and suitcases full of unmarked $20's are all welcome.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA