man convert

     NAME
          convert - converts an input file using one image format to
          an output file with a differing image format.

     SYNOPSIS
          convert [ options ... ] input_file output_file

     DESCRIPTION
          convert converts an input file using one image format to an
          output file with a differing image format.

          convert recognizes the following image formats:

          Tag   Description

          -------------------------------------------------------------------------------

          AVS   AVS X image file.

          BMP   Microsoft Windows bitmap image file.

          CMYK  Raw cyan, magenta, yellow, and black bytes.

          EPS   Adobe Encapsulated PostScript file.

          EPSF  Adobe Encapsulated PostScript file.

          EPSI  Adobe Encapsulated PostScript Interchange format.

          FAX   Group 3.

          FITS  Flexible Image Transport System.

          GIF   Compuserve Graphics image file.

          GIF87 Compuserve Graphics image file (version 87a).

          GRAY  Raw gray bytes.

          HISTOGRAM

          IRIS  SGI RGB image file.

          JPEG

          MAP   Red, green, and blue colormap bytes followed by the
                image colormap indexes.

          MATTE Raw matte bytes.

          MIFF  Magick image file format.

          MTV

          NULL  NULL image.

          PCD   Photo CD.

          PCX   ZSoft IBM PC Paintbrush file.

          PICT  Apple Macintosh QuickDraw/PICT file.

          PNM   Portable bitmap.

          PS    Adobe PostScript file.

          PS2   Adobe Level II PostScript file.

          RAD   Radiance image format.

          RGB   Raw red, green, and blue bytes.

          RLE   Utah Run length encoded image file; read only.

          SUN   SUN Rasterfile.

          TEXT  raw text file; read only.

          TGA   Truevision Targa image file.

          TIFF  Tagged Image File Format.

          VICAR read only.

          VID   Visual Image Directory.

          VIFF  Khoros Visualization image file.

          X     select image from X server screen.

          XC    constant image of X server color.  Specify the desired
                color as the filename.

          XBM   X11 bitmap file.

          XPM   X11 pixmap file.

          XWD   X Window System window dump image file.

          YUV   CCIR 601 4:1:1 file.

          YUV3  CCIR-601 4:1:1 files.

     EXAMPLES

          To convert a MIFF image of a cockatoo to a SUN raster image,
          use:

               convert cockatoo.miff sun:cockatoo.ras

          To convert a multi-page Postscript document to individual
          FAX pages, use:

               convert -monochrome document.ps fax:page

          To convert a TIFF image to a Postscript A4 page with the
          image in the lower left-hand corner, use:

               convert -page 595x842+0+0 image.tiff document.ps

          To convert a raw GRAY image to a portable graymap, use:

               convert -size 768x512 gray:raw image.pgm

          To convert a Photo CD image to a TIFF image, use:

               convert -size 1536x1024 img0009.pcd image.tiff
               convert img0009.pcd[4] image.tiff

          To create a visual image directory of all your JPEG images,
          use:

               convert 'vid:*.jpg' directory.miff

          To identify the dimensions and the type of an image file,
          use:

               convert -verbose image null:

     OPTIONS
          -blur
               blur the image.

          -border <width>x<height>fP
               surround the image with a border or color.  See X(1)
               for details about the geometry specification.

               The color of the border is obtained from the X server
               and is defined as bordercolor (class borderColor).  See
               X(1) for details.

          -colors value
               preferred number of colors in the image.

               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 remain unchanged.
               Refer to quantize(9) for more details.

               Note, options -dither, -colorspace, and -treedepth
               affect the color reduction algorithm.

          -colorspace value
               the type of colorspace: GRAY, OHTA, RGB, XYZ, YCbCr,
               YIQ, YPbPr, or YUV.

               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
               quantize(9) for more details.

               The -colors or -monochrome option is required for this
               option to take effect.

          -comment string
               annotate an image with a comment.

               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 scene number by embedding
               special format characters.  Embed %f for filename, %m
               for magick, %w for width, %h for height, %s for scene
               number, or \n for newline.  For example,

                    -comment "%m:%f %wx%h"

               produces an image comment of MIFF:bird.miff 512x480 for
               an image titled bird.miff and whose width is 512 and
               height is 480.

               If the first character of string is @, the image
               comment is read from a file titled by the remaining
               characters in the string.

          -compress type
               the type of image compression: QEncoded or
               RunlengthEncoded.

               Specify +compress to store the binary image in an
               uncompressed format.  The default is the compression
               type of the specified image file.

          -contrast
               enhance or reduce the image contrast.
               This option enhances the intensity differences between
               the lighter and darker elements of the image.  Use
               -contrast to enhance the image or +contrast to reduce
               the image contrast.

          -crop <width>x<height>{+-}<x offset>{+-}<y offset>
               preferred size and location of the cropped image.  See
               X(1) for details about the geometry specification.

               Use cropping to crop a particular area of an image.
               Use -crop 0x0 to remove edges that are the background
               color.

          -density <width>x<height>
               vertical and horizontal density of the image.

               This option specifies an image density for a Postscript
               page.  The default is 72 dots per inch in the
               horizontal and vertical direction.  Use this option to
               alter the default density.

          -despeckle
               reduce the speckles within an image.

          -display host:display[.screen]
               specifies the X server to contact; see X(1).

          -dither
               apply Floyd/Steinberg error diffusion to the image.

               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.

               The -colors option is required for dithering to take
               effect.

          -edge
               detect edges with an image.

          -enhance
               apply a digital filter to enhance a noisy image.

          -equalize
               perform histogram equalization to the image.

          -flip
               create a "mirror image" by reflecting the image
               scanlines in the vertical direction.
          -flop
               create a "mirror image" by reflecting the image
               scanlines in the horizontal direction.

          -font name
               This option specifies the font to be used for
               displaying normal text.  The default is fixed.

          -gamma value
               level of gamma correction.

               The same color image displayed on two different
               workstations may look different due to differences in
               the display monitor.  Use gamma correction to adjust
               for this color difference.  Reasonable values extend
               from 0.8 to 2.3.

               You can apply separate gamma values to the red, green,
               and blue channels of the image with a gamma value list
               delineated with commas (i.e. 1.7,2.3,1.2).

          -geometry <width>{%}x<height>{%}{!}
               perferred size or location of the image.

               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 640x480! 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.

               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.

          -interlace type
               the type of interlacing scheme: NONE, LINE, or PLANE.

               This option is used to specify the type of interlacing
               scheme for raw image formats such as RGB or YUV.  NONE
               means do not interlace (RGBRGBRGBRGBRGBRGB...), LINE
               uses scanline interlacing
               (RRR...GGG...BBB...RRR...GGG...BBB...), and PLANE uses
               plane interlacing (RRRRRR...GGGGGG...BBBBBB...).  -
               label name assign a label to an image.
               Use this option to assign a specific label to the
               image.  Optionally you can include the image filename,
               type, width, height, or scene number in the label by
               embedding special format characters.   Embed %f for
               filename, %m for magick, %w for width, %h for height,
               or %s for scene number.  For example,
                    -label "%m:%f %wx%h"
               produces an image label of MIFF:bird.miff 512x480 for
               an image titled bird.miff and whose width is 512 and
               height is 480.

               If the first character of string is @, the image label
               is read from a file titled by the remaining characters
               in the string.

               When converting to Postscript, use this option to
               specify a header string to print above the image.

          -map filename
               choose a particular set of colors from this image.

               By default, color reduction chooses an optimal set of
               colors that best represent the original image.
               Alternatively, you can choose a particular set of
               colors with this option.

          -matte
               store matte channel if the image has one.

          -modulate value
               vary the brightness, saturation, and hue of an image.

               Specify the percent change in brightness, the color
               saturation, and the color hue separated by commas.  For
               example, to increase the color brightness by 20% and
               decrease the color saturation by 10% and leave the hue
               unchanged, use: -modulate 20,-10.

          -monochrome
               transform the image to black and white.

          -negate
               apply color inversion to image.

               The red, green, and blue intensities of an image are
               negated.

          -noise
               reduce the noise in an image with a noise peak
               elimination filter.

               The principal function of noise peak elimination filter
               is to smooth the objects within an image without losing
               edge information and without creating undesired
               structures.  The central idea of the algorithm is to
               replace a pixel with its next neighbor in value within
               a 3 x 3 window, if this pixel has been found to be
               noise.  A pixel is defined as noise if and only if this
               pixel is a maximum or minimum within the 3 x 3 window.

          -normalize
               transform image to span the full range of color values.

               This is a contrast enhancement technique.

          -page <width>x<height>{+-}<x offset>{+-}<y offset>
               preferred size and location of the Postscript page.

               Use this option to specify the dimensions of the
               Postscript page in picas or a TEXT page in pixels.  The
               default for a Postscript page is to center the image on
               a letter page 612 by 792 dots per inch.  The left and
               right margins are 18 picas and the top and bottom 94
               picas (i.e.  612x792+36+36).  Other common sizes are:

                   540x720   Note
                   612x1008  Legal
                   842x1190  A3
                   595x842   A4
                   421x595   A5
                   297x421   A6
                   709x1002  B4
                   612x936   U.S. Foolscap
                   612x936   European Foolscap
                   396x612   Half Letter
                   792x1224  11x17
                   1224x792  Ledger

               The page geometry is relative to the vertical and
               horizontal density of the Postscript page.  See
               -density for details.

               The default page dimensions for a TEXT image is
               612x792+36+36.

          -quality value
               JPEG quality setting.

               Quality is 0 (worst) to 100 (best). The default is 85.

          -roll {+-}<x offset>{+-}<y offset>
               roll an image vertically or horizontally.  See X(1) for
               details about the geometry specification.
               A negative x offset rolls the image left-to-right.  A
               negative y offset rolls the image top-to-bottom.

          -rotate degrees
               apply Paeth image rotation to the image.

               Empty triangles left over from rotating the image are
               filled with the color defined as bordercolor (class
               borderColor).  See X(1) for details.

          -sample geometry
               scale image with pixel sampling.

          -scene value
               image scene number.

          -sharpen
               sharpen the image.

          -shear <x degrees>x<y degrees>
               shear the image along the X or Y axis by a positive or
               negative shear angle.

               Shearing slides one edge of an image along the X or Y
               axis, creating a parallelogram.  An X direction shear
               slides an edge along the X axis, while a Y direction
               shear slides an edge along the Y axis.  The amount of
               the shear is controlled by a shear angle.  For X
               direction shears, x degrees is measured relative to the
               Y axis, and similarly, for Y direction shears y degrees
               is measured relative to the X axis.

               Empty triangles left over from shearing the image are
               filled with the color defined as bordercolor (class
               borderColor).  See X(1) for details.

          -size <width>{%}x<height>
               width and height of the image.

               Use this option to specify the width and height of raw
               images whose dimensions are unknown such as GRAY, RGB,
               or CMYK.  In addition to width and height, use -size to
               tell the number of colors in a MAP image file, (e.g.
               -size 640x512+256).

               For Photo CD images, choose from these sizes:

                  192x128
                  384x256
                  768x512
                 1536x1024
                 3072x2048

          -treedepth value
               Normally, this integer value is zero or one.  A zero or
               one tells convert to choose a optimal tree depth for
               the color reduction algorithm.

               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
               quantize(9) for more details.

               The -colors option is required for this option to take
               effect.

          -undercolor <undercolor factor>x<black-generation factor>
               control undercolor removal and black generation on CMYK
               images.

               This option enables you to perform undercolor removal
               and black generation on CMYK images-- images to be
               printed on a four-color printing system. You can
               control how much cyan, magenta, and yellow to remove
               from your image and how much black to add to it.  The
               standard undercolor removal is 1.0x1.0.  You'll
               frequently get better results, though, if the
               percentage of black you add to your image is slightly
               higher than the percentage of C, M, and Y you remove
               from it.  For example you might try 0.5x0.7.

          -verbose
               print detailed information about the image.

               This information is printed: image scene number;  image
               name;  converted image name;  image size;  the image
               class (DirectClass or PseudoClass);  the total number
               of unique colors;  and the number of seconds to read
               and convert the image.

          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.

          Change '-' to '+' in any option above to reverse its effect.
          For example, specify +matte to store the image without its
          matte channel.

          By default, the image format is determined by its magic
          number. To specify a particular image format, precede the
          filename with an image format name and a colon (i.e.
          ps:image) or specify the image type as the filename suffix
          (i.e. image.ps).  See DESCRIPTION for a list of valid
          formats.

          When you specify X as your image type, the filename has
          special meaning.  It specifies an X window by id, name, or
          root.  If no filename is specified, the window is selected
          by clicking the mouse in the desired window.

          Specify input_file as - for standard input, output_file as -
          for standard output.  If input_file has the extension .Z or
          .gz, the file is uncompressed with uncompress or gunzip
          respectively.  If output_file has the extension .Z or .gz,
          the file size is compressed using with compress or gzip
          respectively.  Finally, precede the image file name with |
          to pipe to or from a system command.

          Use an optional index enclosed in brackets after a file name
          to specify a desired subimage of a multi-resolution image
          format like Photo CD (e.g. img0001.pcd[4]).

          Single images are written with the filename you specify.
          However, multi-part images (i.e. a multi-page Postscript
          document) are written with the filename followed by a period
          (.) and the scene number.  You can change this behavior by
          embedding a printf format specification in the file name.
          For example,
              image%02d.miff
          converts files image00.miff, image01.miff, etc.

     ENVIRONMENT
          display
               To get the default host, display number, and screen.

     SEE ALSO
          display(1), animate(1), import(1), montage(1), mogrify(1),
          segment(1), combine(1), xtp(1)

     COPYRIGHT
          Copyright 1994 E. I. du Pont de Nemours and Company

          Permission to use, copy, modify, distribute, and sell this
          software and its documentation for any purpose is hereby
          granted without fee, provided that the above copyright
          notice appear in all copies and that both that copyright
          notice and this permission notice appear in supporting
          documentation, and that the name of E. I. du Pont de Nemours
          and Company not be used in advertising or publicity
          pertaining to distribution of the software without specific,
          written prior permission.  E. I. du Pont de Nemours and
          Company makes no representations about the suitability of
          this software for any purpose.  It is provided "as is"
          without express or implied warranty.

          E. I. du Pont de Nemours and Company disclaims all
          warranties with regard to this software, including all
          implied warranties of merchantability and fitness, in no
          event shall E. I. du Pont de Nemours and Company be liable
          for any special, indirect or consequential damages or any
          damages whatsoever resulting from loss of use, data or
          profits, whether in an action of contract, negligence or
          other tortuous action, arising out of or in connection with
          the use or performance of this software.

     AUTHORS
          John Cristy, E.I. du Pont De Nemours and Company
          Incorporated

     Page 12                                        (printed 10/27/94)