Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ICONTACT(1)		    General Commands Manual		   ICONTACT(1)

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 im-
       age files and creates contact sheets.   icontact	 determines  the  file
       format  by the file name	extension of the input files and then uses in-
       ternal 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	-  af-
       fects 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  im-
	      age'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  im-
	      ages  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  ex-
	      plaining	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  im-
	      age.   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 im-
	      age.  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 de-
	      fault 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  de-
	      fault 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 de-
	      scription	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 in-
	      stead 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 er-
	      rors.

       -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 de-
	      fault 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 pn-
	      mscale.  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  ob-
	      vious 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 ALSO
       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)

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 ig-
       nored and icontact will try to decode the image using the remaining ex-
       tensions.  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
       icontact	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)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | FILES | SEE ALSO | DIAGNOSTICS | BUGS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=icontact&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help