ICONTACT(1)ICONTACT(1)NAMEicontact - create contact sheets from images of different formats
SYNOPSISicontact [ switches ] [ { image file | parameter file } ... ]
DESCRIPTIONicontact 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 with‐
out 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. Ghost‐
script can be used to turn PostScript files into PPM files for inclu‐
sion 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 use‐
ful 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 with‐
out 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 config‐
uration 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 fig‐
ured 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 pre‐
fix is the contact sheet name, ### is the number of the contact
sheet, format is the file format of the contact sheet, and suf‐
fix 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 configura‐
tion file will have no effect since once you're in a configura‐
tion 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 origi‐
nal size. The value of scale may be in the range (0.0, infin‐
ity), 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 (widthx‐
height) 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 destina‐
tion directory for sheets with the same prefix and format that
we are going to create. Take the highest numbered one, incre‐
ment, 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 param‐
eter 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 num‐
ber 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, option‐
ally, from the file specified with the -n switch) into alphabet‐
ical 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 insensi‐
tive fashion.
±v Cause all sorts of possibly interesting output to be printed to
the screen. The output includes the current parameters of icon‐
tact 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 out‐
put 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 out‐
put 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 col‐
ors 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: Com‐
ments 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 begin‐
ning 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 <key‐
word> 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 col‐
orization
$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
SEE ALSObasename(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)DIAGNOSTICS
The diagnostic messages are intended to be self explanatory. If icon‐
tact 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 recog‐
nized 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.
COPYRIGHTicontact is:
Copyright (C) 1992-1999 Mark B. Hanson (mbh@panix.com)
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 MER‐
CHANTABILITY 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.5 (1999-09-11) ICONTACT(1)
