<imdoc>
<p>
By default, the image format is determined by its magic number, i.e., the
first few bytes of the file. To specify
a particular image format, precede the filename with an image format name
and a colon (<i>i.e.</i><s>ps:image</s>) or specify the image type as the
filename suffix (<i>i.e.</i><s>image.ps</s>).
The magic number takes precedence over the filename suffix
and the prefix takes precedence over the magic number and the suffix
in input files.
When a file is read, its magic number is stored in the "image->magick"
string.
In output files, the prefix takes precedence over the filename suffix,
and the filename suffix takes precedence over the
"image->magick" string.
</p>
<p>To read the "built-in" formats (GRANITE, H, LOGO,
NETSCAPE, PLASMA, and ROSE) use a prefix (including the colon) without a
filename or suffix.  To read the XC format, follow the colon with a color
specification.  To read the CAPTION format, follow the colon with a text
string or with a filename prefixed with the at symbol (<s>@</s>).
</p>
<p>
When you specify <s>X</s> as your image type, the filename has special
meaning. It specifies an X window by <s>id, name</s>, or
<s>root</s>. If
no filename is specified, the window is selected by clicking the mouse
in the desired window.</p>

<p>
Specify <i>input_file</i> as <s>-</s> for standard input,
<i>output_file</i> as <s>-</s> for standard output.
If <i>input_file</i> has the extension <s>.Z</s> or <s>.gz</s>, the
file is uncompressed with <s>uncompress</s> or <s>gunzip</s>
respectively.
If <i>output_file</i> has the extension <s>.Z</s> or <s>.gz</s>,
the file is compressed using with <i>compress</i> or <i>gzip</i> respectively.</p>

<p>
Use an optional index enclosed in brackets after an input file name to
specify a desired subimage of a multi-resolution image format like
Photo CD (e.g. <tt>"img0001.pcd[4]"</tt>) or a range for MPEG images
(e.g. <tt>"video.mpg[50-75]"</tt>). A subimage specification can be
disjoint (e.g. <tt>"image.tiff[2,7,4]"</tt>). For raw images, specify
a subimage with a geometry (e.g. <tt>-size 640x512</tt>
<tt>"image.rgb[320x256+50+50]"</tt>).  Surround the image name with
quotation marks to prevent your shell from interpreting the square
brackets.</p> <p>Single images are written with the filename you
specify. However, multi-part images (e.g., a multi-page PostScript
document with <s>+adjoin</s> specified) may be written with the scene
number included as part of the filename. In order to include the scene
number in the filename, it is necessary to include a printf-style
<tt>%d</tt> format specification in the file name and use the +adjoin
option. For example,</p>

<pre>
    image%02d.miff
</pre>

<p>
writes files <i>image00.miff, image01.miff,</i> etc. Only a single
specification is allowed within an output filename. If more than one
specification is present, it will be ignored. It is best to embed the
scene number in the base part of the file name, not in the extension,
because the extension will not be a recognizeable image type.</p>
<p>
When running a commandline utility, you can
prepend an at sign <tt>@</tt> to a filename to read a list of image
filenames from that file. This is convenient in the event you have too
many image filenames to fit on the command line.</p>
</imdoc>
