<HTML VERSION="2.0">
<HEAD>
<TITLE>ImageMagick Image Capturing Utility</TITLE>
<LINK rev="made" href="mailto:magick@wizards.dupont.com">
<meta name="description" content="ImageMagick, version 4.2.2, is a package for
  display and interactive manipulation of images for the X Window System. It
  is written in C and interfaces to the X library, and therefore does not
  require any proprietary toolkit in order to compile.  Although the software
  is copyrighted, it is available for free and can be redistributed without
  fee.">
<meta name="keywords" content="ImageMagick, Image Magick, Image Magic,
  PerlMagick, Perl Magick, Perl Magic, CineMagick, PixelMagick, Pixel Magic,
  WebMagick, Web Magic, visualization, image processing, software development,
  simulation, image, software, AniMagick, Animagic, X11">
</HEAD>
<body background="../images/background.gif">
<A NAME="top"></A>
<CENTER>
<img src="../images/import.gif" align=bottom width=186 height=52>
</CENTER>
<pre>
 
</pre>
<H2>
<A NAME="Contents">Contents</A>
</H2>
<UL>
<LI><A HREF="#syno">Synopsis</A>
<LI><A HREF="#desc">Description</A>
<LI><A HREF="#exam">Examples</A>
<LI><A HREF="#opti">Options</A>
<LI><A HREF="#envi">Environment</A>
<LI><A HREF="#copy">Copyright</A>
<LI><A HREF="#auth">Authors</A>
</UL>
<DL>
<H2>
<A NAME="syno">
<DT>Synopsis
</A>
</H2>
<DD> <B>import</B> <B>[</B> <I>options</I> <B>... ]</B> <I> file</I>
</DL>
<P>
<A HREF="#top"><I>Back to Contents</I></A>
<HR>
<DL>
<H2>
<A NAME="desc">
<DT>Description
</A>
</H2>
<DD> 
<B>Import</B> reads an image from any visible window on an X server
and outputs it as an image file.  You can capture a single
window, the entire screen, or any rectangular portion of the
screen.  Use 
<A HREF="display.html"><I>display</I></A>
for
redisplay,
printing, editing, formatting, archiving, image processing,
etc. of the captured image.
<P>
The target window can be specified by id, name, or may be
selected by clicking the mouse in the desired window.  If
you press a button and then drag, a rectangle will form
which expands and contracts as the mouse moves.  To save the
portion of the screen  defined by the rectangle, just
release the button.  The keyboard bell is rung once at the
beginning of the screen capture and twice when it completes.
</DL>
<P>
<A HREF="#top"><I>Back to Contents</I></A>
<HR>
<DL>  
<H2>
<A NAME="exam">
<DT>Examples  
</A>
</H2>
<DD>To select an X window with the mouse and save it in the MIFF
image format to a file titled window.miff, use:
<p><dl>
  <dd><tt>import window.miff</tt>
</p></dl>
<P>
<DD>To select an X window and save it in the Encapsulated
Postscript format to include in another document, use:
<p><dl>
  <dd><tt>import figure.eps</tt>
</p></dl>
<P>
<DD>To capture the entire X server screen in the JPEG image
format in a file titled root.jpeg, use:
<p><dl>
  <dd><tt>import -window root root.jpeg</tt>
</p></dl>
<P>
</DL>
<P>
<A HREF="#top"><I>Back to Contents</I></A>
<HR>
<DL>
<H2>
<A NAME="opti">
<DT>Options
</A>
</H2>
<P>
<DD><B>Import</B> options can appear on the command line or in your X
resources file. See <I>X(1)</I>. Options on the command line 
supersede values specified in your X resources file.
<DL>
<P>
<DT><B>-adjoin</B>
<DD> join images into a single multi-image file.
<p>
<DD>By default, all images of an image sequence are stored in the same
file.  However, some formats (e.g. JPEG) do not support more than one image
and are saved to separate files.  Use <b>+adjoin</b> to force this behavior.
<P>
<DT><B>-border</B>
<DD>include image borders in the output image.
<P>
<DD>The color of the border is obtained from the <I>X server</I>
and is defined as <B>bordercolor</B> (class <B>borderColor</B>).
See <I>X(1)</I> for details.
<P>
<DT><B>-colors</B> <I>value</I>
<DD>preferred number of colors in the image.
<P>
<DD>The actual number of colors in the image may be less
than your request, but never more.  Note, this is a
color reduction option.  Images with less unique
colors than specified with this option will have any duplicate
or unused colors removed.
Refer to <A HREF="quantize.html">quantize</A> for
more details.
<P>
Note, options <B>-dither</B>, <B>-colorspace</B>, and <B>-treedepth</B>
affect the color reduction algorithm.
<P>
<DT><B>-colorspace</B> <I>value</I>
<DD>the type of colorspace: <B>GRAY</B>, <B>OHTA</B>, <B>RGB</B>,
<B>Transparent</B>, <B>XYZ</B>, <B>YCbCr</B>, <B>YIQ</B>, <B>YPbPr</B>,
<B>YUV</B>, or <B>CMYK</B>.
<P>
<DD>Color reduction, by default, takes place in the RGB
color space.  Empirical evidence suggests that
distances in color spaces such as YUV or YIQ
correspond to perceptual color differences more
closely than do distances in RGB space.  These color
spaces may give better results when color reducing an
image.  Refer to <A HREF="quantize.html">quantize</A> for more details.
<P>
The <B>Transparent</B> color space behaves uniquely in that it preserves
the matte channel of the image if it exists.
<P>
The <B>-colors</B> or <B>-monochrome</B> option is required for
this option to take effect.
<P>
<DT><B>-comment</B> <I>name</I>
<DD>annotate an image with a comment.
<P>
<DD>By default, each image is commented with its file
name.  Use this option to assign a specific comment
to the image.  Optionally you can include the image
filename, type, width, height, or other image attribute by
embedding special format characters:
<p>
<dd><pre>
    %b   file size
    %d   directory
    %e   filename extention
    %f   filename
    %h   height
    %m   magick
    %p   page number
    %s   scene number
    %t   top of filename
    %w   width
    %x   x resolution
    %y   y resolution
    \n   newline
    \r   carriage return
</pre>
<p>
For example,
<P> 
<DD><B>-comment "%m:%f %wx%h"</B>
<P>
<DD>produces an image comment of <B>MIFF:bird.miff 512x480</B> for an
image titled <B>bird.miff</B> and whose width is 512 and height
is 480.
<P>
<DD>If the first character of <I>string</I> is <I>@</I>, the image comment
is read from a file titled by the remaining characters in
the string.
<P>
<DT><B>-compress</B> <I>type</I>
<DD>the type of image compression: <I>None</I>, <I>BZip</I>, <I>Fax</I>,
<i>Group4</i>, <I>JPEG</I>, <I>LZW</I>, <I>RunlengthEncoded</I> or <I>Zip</I>.
<P>
<DD>Specify <B>+compress</B> to store the binary image in an
uncompressed format.  The default is the compression
type of the specified image file.
<P>
<DT><B>-crop</B> <I>&lt;width&gt;x&lt;height&gt;{+-}&lt;x offset&gt;{+-}&lt;y offset&gt;{%}</I>   
<DD>preferred size and location of the cropped image.
See <I>X(1)</I> for details about the geometry
specification.
<P>
<DD>To specify a percentage width or height instead,
append <B>%</B>.  For example to crop the image by ten   
percent on all sides of the image, use <B>-crop 10%</B>.
<P>
<DD>Use cropping to apply image processing options to, or
display, a particular area of an image.
<p>
<DD>Omit the x and y offset to generate one or more subimages of a uniform size.
<p>
<DD>Use cropping to crop a particular area of an image.   Use <b>-crop
0x0</b> to trim edges that are the background color.  Add an x and y offset
to leave a portion of the trimmed edges with the image.
<P>
<DT><B>-delay</B> <I>&lt;1/100ths of a second&gt;x&lt;seconds&gt;I>
<DD>display the next image after pausing.
<P>
This option is useful for regulating the display of the
sequence of images. <I>1/100ths of a second</I> must
expire before the display of the next image. The
default is 6/100th of a second between each frame of the image sequence.
The second value is optional.  It specifies the
number of <em>seconds</em> to pause before repeating your animation
sequence.
<P>  
<DT><B>-density</B> <I>&lt;width&gt;x&lt;height&gt;</I>
<DD>vertical and horizontal resolution in pixels of the image.
<P> 
<DD>This option specifies an image density when decoding
a <I>PostScript</I> or Portable Document page.  The default
is 72 pixels per inch in the horizontal and vertical
direction. This option is used in concert with <b>-page</b>.
<P>
<DT><B>-density</B> <I>&lt;width&gt;x&lt;height&gt;</I>
<DD>vertical and horizontal resolution in pixels of the image.
<P>
<DD>This option specifies an image density when decoding
a <I>PostScript</I> or Portable Document page.  The default
is 72 pixels per inch in the horizontal and vertical
direction.
<P>
<DT><B>-descend</B>
<DD>obtain image by descending window hierarchy.
<P>
<DT><B>-display</B> <I>host:display[.screen]</I>
<DD>specifies the X server to contact. This option is used with convert for
obtaining image or font from this X server. see <I>X(1)</I>.
<P>
<dt><b>-dispose</b> <i>method</i>
<dd>GIF disposal method.
<p>
<dd> Here are the valid methods:
<p>
<pre>
  0     No disposal specified.
  1     Do not dispose between frames.      
  2     Overwrite frame with background color from header.
  3     Overwrite with previous frame.
</pre>
<P>
<DT><B>-dither</B>
<DD>apply Floyd/Steinberg error diffusion to the image.
<P>
<DD>The basic strategy of dithering is to trade intensity
resolution for spatial resolution by averaging the
intensities of several neighboring pixels.  Images
which suffer from severe contouring when reducing
colors can be improved with this option.
<P>
<DD>The <B>-colors</B> or <B>-monochrome</B> option is required for
this option to take effect.
<P>
<DD>Use <B>+dither</B> to render Postscript without text or graphic aliasing.
<P>
<DT><B>-frame</B>
<DD>include window manager frame.
<P>
<DT><B>-geometry</B> <I>&lt;width&gt;x&lt;height&gt;{+-}&lt;x offset&gt;{+-}&lt;yoffset&gt;{%}{!}{&lt;}{&gt;}</I>
<DD>the with and height of the image.
<P>
<DD>By default, the width and height are maximum values.
That is, the image is expanded or contracted to fit
the width and height value while maintaining the
aspect ratio of the image.  Append an exclamation
point to the geometry to force the image size to
exactly the size you specify.  For example, if you
specify <B>640x480!</B> the image width is set to 640 pixels
and height to 480.  If only one factor is specified,
both the width and height assume the value.
<P>
<DD>To specify a percentage width or height instead,
append %.  The image size is multiplied by the width
and height percentages to obtain the final image
dimensions.  To increase the size of an image, use a
value greater than 100 (e.g. 125%).  To decrease an
image's size, use a percentage less than 100.
<P>
Use <B>&gt;</B> to change the dimensions of the image <em>only</em>
if its size exceeds the geometry specification.  <B>&lt;</B> resizes
the image <em>only</em> if its dimensions is less than the geometry
specification.  For example, if you specify <b>640x480&gt;</b> and the
image size is 512x512, the image size does not change.  However, if
the image is 1024x1024, it is resized to 640x480.
<P>
<DT><B>-interlace</B> <I>type</I>
<DD>the type of interlacing scheme: <B>None</B>, <B>Line</B>, <B>Plane</B>,
or <b>Partition</b>.  The default is <B>None</B>.
<P>
<DD>This option is used to specify the type of interlacing scheme for raw
image formats such as <B>RGB</B> or <B>YUV</B>.  <B>None</B> means do not
interlace (RGBRGBRGBRGBRGBRGB...), <B>Line</B> uses scanline interlacing
(RRR...GGG...BBB...RRR...GGG...BBB...), and <B>Plane</B> uses plane
interlacing (RRRRRR...GGGGGG...BBBBBB...).    <b>Partition</b> is like plane
except the different planes are saved to individual files (e.g.  image.R,
image.G, and image.B).
<P>
<DD>Use <B>Line</B>, or <B>Plane</B> to create an <B>interlaced GIF</B> 
or <B>progressive JPEG</b> image.
<P>  
<DT><B>-label</B> <I>name</I>
<DD>assign a label to an image.
<P> 
<DD>Use this option to assign a  specific  label  to  the
image.   Optionally you can include the image
filename, type, width, height, or other image attribute by
embedding special format character.  See <b>-comment</b> for details.
<p>
<dd>For example,
<P>
<DD><B>-label "%m:%f %wx%h"</B>
<P>
<DD>produces an image label of <B>MIFF:bird.miff 512x480</B> for an
image titled <B>bird.miff</B> and whose width is 512 and height
is 480.
<P> 
<DD>If the first character of <I>string</I> is <I>@</I>, the image label is
read from a file titled by the remaining characters in the
string.
<P>
<DD>When converting to <I>PostScript</I>, use this option to specify
a header string to print above the image. Specify the label font with
<b>-font</b>.
<P>
<DT><B>-monochrome</B>
<DD>transform the image to black and white.
<P> 
<DT><B>-negate</B>
<DD>replace every pixel with its complementary color (white becomes black,
yellow becomes blue, etc.).
<P>
<DD>The red, green, and blue intensities of an image are
negated.   Use <b>+negate</b> to only negate the grayscale pixels of the
image.
<P>
<DT><B>-page</B> <I>&lt;width&gt;x&lt;height&gt;{+-}&lt;x offset&gt;{+-}&lt;y offset&gt;{%}{!}{&lt;}{&gt;}</I>
<DD>size and location of an image canvas.
<P>
<DD>Use this option to specify the dimensions of the
<I>PostScript</I> page in dots per inch or a TEXT page in
pixels.  The choices for a Postscript page are:
<PRE>
       11x17         792  1224 
       Ledger       1224   792    
       Legal         612  1008
       Letter        612   792
       LetterSmall   612   792
       ArchE        2592  3456
       ArchD        1728  2592
       ArchC        1296  1728
       ArchB         864  1296
       ArchA         648   864
       A0           2380  3368
       A1           1684  2380
       A2           1190  1684
       A3            842  1190
       A4            595   842
       A4Small       595   842
       A5            421   595
       A6            297   421
       A7            210   297
       A8            148   210
       A9            105   148
       A10            74   105
       B0           2836  4008
       B1           2004  2836
       B2           1418  2004
       B3           1002  1418
       B4            709  1002
       B5            501   709
       C0           2600  3677
       C1           1837  2600
       C2           1298  1837
       C3            918  1298
       C4            649   918
       C5            459   649
       C6            323   459
       Flsa          612   936 
       Flse          612   936
       HalfLetter    396   612
</PRE>
<DD>For convenience you can specify the page size by media
(e.g. A4, Ledger, etc.).  Otherwise, <b>-page</b> behaves much like
<b>-geometry</b> (e.g. <tt>-page letter+43+43&gt</tt>).
<p>
<dd>To position a GIF image, use <b>-page</b>
<i>{+-}&lt;x offset&gt;{+-}&lt;y offset&gt;</i>
(e.g. -page +100+200).
<p>
<dd>For a Postscript page, the image is sized as in <b>-geometry</b> and
positioned relative to the lower left hand corner of the page by
{+-}&lt;<B>x</B> <EM>offset</EM>&gt;{+-}&lt;<B>y</B> <EM>offset</EM>&gt;.
Use <tt>-page 612x792&gt</tt>, for example, to center the image within the
page.  If the image size exceeds the Postscript page, it is reduced to fit the
page.
<p>
<dd>The default page dimensions for a TEXT image is 612x792.
<p>
<dd>This option is used in concert with <b>-density</b>.
<P>
<DT><B>-pointsize</B> <I>value</I>
<DD>pointsize of the Postscript font.
<P>
<DT><B>-quality</B> <I>value</I>
<DD>JPEG/MIFF/PNG compression level.
<P>
<DD> For the JPEG image format, quality is 0 (worst) to 100 (best).
The default quality is 75.
<p>
<dd> Quality for the MIFF and PNG image format sets the amount of image compression 
(quality / 10) and filter-type (quality % 10).  Compression quality
values range from 0 (worst) to 100 (best).  If filter-type is 4
or less, the specified filter-type is used for all scanlines:
<p>
<pre>
    0: none
    1: sub
    2: up
    3: average
    4: Paeth
</pre>
<p>
<dd>If filter-type is 5, adaptive filtering is used when quality
is greater than 50 and the image does not have a color map,
otherwise no filtering is used.
<p>
<dd>If filter-type is 6 or more, adaptive filtering with 
<em>minimum-sum-of-absolute-values</em> is used.
<p>
<dd>The default is quality is 75.  Which means nearly the best compression
with adaptive filtering.
<p>
<dd>For further information, see the PNG specification
(<a href=http://www.w3.org/pub/WWW/TR>RFC 2083</a>).
<P>
<DT><B>-rotate</B> <I>degrees{&lt;}{&gt;}</I>
<DD>apply Paeth image rotation to the image.
<P>   
<dd>Use <tt>&gt;</tt> to rotate the image </t>only</i> if its width exceeds the
height.  <tt>&lt;</tt> rotates the image <i>only</i> if its width is less than
the height.  For example, if you specify <tt>-90&gt;</tt> and the image size
is 480x640, the image is not rotated by the specified angle.  However,
if the image is 640x480, it is rotated by -90 degrees.
<P>
<DD>Empty triangles left over from rotating the image are
filled with the color defined as <B>bordercolor</B> (class
<B>borderColor</B>).  See <I>X(1)</I> for details.
<P>
<DT><B>-scene</B> <I>value</I>
<DD>number of screen snapshots.
<p>
<DD>Use this option to grab more than one image from the X server screen to
create an animation sequence.
<P>
<DT><B>-screen</B>
<P>
<DD>This option indicates that the GetImage request used to
obtain the image should be done on the root window,
rather than directly on the specified window.  In this
way, you can obtain pieces of other windows that
overlap the specified window, and more importantly, you
can capture menus or other popups that are independent
windows but appear over the specified window.
<P>
<DT><B>-screen</B>
<P>
<DD>operate silently, i.e. don't ring any bells.
<P>
<DT><B>-transparency</B> <I>color</I>
<dd>make this color transparent within the image.
<P>
<DT><B>-treedepth</B> <I>value</I>
<DD>Normally, this integer value is zero or one.  A zero
or one tells display to choose an optimal tree depth
for the color reduction algorithm.
<P>
<DD>An optimal depth generally allows the best
representation of the source image with the fastest
computational speed and the least amount of memory.
However, the default depth is inappropriate for some
images.  To assure the best representation, try
values between 2 and 8 for this parameter.  Refer to
<A HREF="quantize.html">quantize</A> for more details.
<P>
<DD>The <B>-colors</B> or <B>-monochrome</B> option is required for
this option to take effect.
<P>
<DT><B>-verbose</B>
<DD>print detailed information about the image.
<P>
<DD>This information is printed: image scene number;
image name;  image size; the image class (<I>DirectClass</I>
or <I>PseudoClass</I>);  the total number of unique colors;
and the number of seconds to read and transform the
image.  Refer to <A HREF="miff.html">miff</A> for a description
of the image class.
<P>
<DT><B>-window</B> <I>id</I>
<P>
<DD>select window with this id or name.
<P>
<DD>With this option you can specify the target window by
id or name rather than using the mouse.  Specify <I>root</I>
to select X's root window as the target window.
</DL>
<P>
Options are processed in command line order.  Any option you
specify on the command line remains in effect until it is
explicitly changed by specifying the option again with a
different effect.
<P>     
<EM>file</EM> specifies the image filename.  If <em>file</em> is omitted, it
defaults to <tt>magick.miff</tt>.  The default image format is MIFF.
To specify a particular image format, precede the filename with an image
format name and a colon (i.e.  <tt>gif:image</tt>) or specify the
image type as the filename suffix (i.e.  <tt>image.jpg</tt>).  See
<A HREF="../www/formats.html">Image Formats Supported by ImageMagick</A> for
a list of valid image formats.
<P>
Specify <EM>file</EM> as - for standard output.  If <EM>file</EM> has the
extension <STRONG>.Z</STRONG> or <STRONG>.gz</STRONG>, the file size is com
pressed using with
<STRONG>compress</STRONG> or <STRONG>gzip</STRONG> respectively.  Precede t
he image file name
| to pipe to a system command. If <EM>file</EM> already exists, you
will be prompted as to whether it should be overwritten.
</dl>
<P>
<A HREF="#top"><I>Back to Contents</I></A>
<HR>
<DL>
<H2>
<A NAME="envi">
<DT>Environment
</A>
</H2>
<DL>
<DT><B>DISPLAY</B>
<DD>To get the default host, display number, and screen.
</DL>
</DL>
<P>
<A HREF="#top"><I>Back to Contents</I></A>
<HR>
<DL>
<H2>
<A NAME="copy">
<DT>Copyright
</A>
</H2>
<B>
<dd>Copyright 1999 E. I. du Pont de Nemours and Company
<p>
<dd>Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files ("ImageMagick"),
to deal in ImageMagick without restriction, including without limitation 
the rights to use, copy, modify, merge, publish, distribute, sublicense, 
and/or sell copies of ImageMagick, and to permit persons to whom the 
ImageMagick is furnished to do so, subject to the following conditions:
<p>
<dd>The above copyright notice and this permission notice shall be included in 
all copies or substantial portions of ImageMagick. 
<p>
<dd>The software is provided "as is", without warranty of any kind, express or 
implied, including but not limited to the warranties of merchantability, 
fitness for a particular purpose and noninfringement.In no event shall 
E. I. du Pont de Nemours and Company be liable for any claim, damages or 
other liability, whether in an action of contract, tort or otherwise,
arising from, out of or in connection with ImageMagick or the use or other 
dealings in ImageMagick. 
<p>
<dd>Except as contained in this notice, the name of the E. I. du Pont de 
Nemours and Company shall not be used in advertising or otherwise to 
promote the sale, use or other dealings in ImageMagick without prior 
written authorization from the E. I. du Pont de Nemours and Company. 
</B>
</DL>
<P>
<A HREF="#top"><I>Back to Contents</I></A>
<HR>
<DL>
<H2>
<A NAME="auth">
<DT>Authors
</A>
</H2>
<DD><I>John Cristy</I>, <A HREF="mailto:magick@wizards.dupont.com">
<I>magick@wizards.dupont.com</I></A> <B>E.I. du Pont de Nemours and Company
Incorporated</B>.
</DL>
<P>
<A HREF="#top"><I>Back to Contents</I></A>
<p><hr><p>
<a href="../ImageMagick.html"><img alt="Home Page"
  src="../images/home.gif" width=40 height=40 align=middle border=0></a>
<font size="-2">Image manipulation software that works like magic.</font>
</body>
</html>
