|±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 images 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, pbmtexts internal font is used. Check out pbmtexts 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 icontacts 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 youre in a configuration file, its too late to switch to another one.|
|±k||Dont reference the configuration file. Putting this switch in the configuration file will have no effect since once youre in the configuration file, its 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 images 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 images 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. Dont 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 icontacts intermediate files. icontact tries to minimize the amount of temporary space it needs, but its disk space requirements can be large depending upon the particular operation it is performing. If you have a tiny /tmp directory, youll 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 youre 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.|
TMPDIR, TEMPDIR These environment variables can be used to set the location of icontacts 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.
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 images x and y offsets into the contact sheet and then the images 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
basename(1), perl(1), pbm(5), pgm(5), ppm(5), pnm(5), cjpeg(1), djpeg(1), gs(1), gzip(1), gunzip(1), compress(1), hpcdtoppm(1)
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 cant 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.
If an images 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 shouldnt 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.
Mark B. Hanson
Bug reports, patch donations, suggestions, questions, and suitcases full of unmarked $20s are all welcome.
Copyright (C) 1992-1999 Mark B. Hanson (firstname.lastname@example.org)
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
|-->||ICONTACT (1)||icontact-1.5 (1999-09-11)|