NOAA

Geophysical Fluid
Dynamics Laboratory

Skip to: [content] [navigation]
If you are using Navigator 4.x or Internet Explorer 4.x or Omni Web 4.x , this site will not render correctly!

Vis > image_printing > GFDL Visualization Guide: convert

GFDL Visualization Guide: 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.

     BIE+   Joint Bi-level Image experts Group file interchange	format.

     BMP+   Microsoft Windows bitmap image file.

     CGM    Computer Graphics Metafile.

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

     DCX+   ZSoft IBM PC multi-page Paintbrush file.

     DIB    Microsoft Windows bitmap image file.

     EPS    Adobe Encapsulated PostScript file.

     EPS2   Adobe Level	II 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	interchange format; 8-bit color.

     GIF87+ CompuServe graphics	interchange format; 8-bit color	(version 87a).

     GRAY   Raw	gray bytes.

     GRADATION
	    gradual passing from one shade to  another.	 Specify  the  desired
	    shading as the filename (e.g. gradation:red-blue).

     HDF+   Hierarchical Data Format.

     HTML   Hypertext Markup Language with a client-side image map.

     HISTOGRAM

     JBIG+  Joint Bi-level Image experts Group file interchange	format.

     JPEG   Joint Photographic Experts Group JFIF  format;  compressed	24-bit
	    color.

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

     MATTE  Raw	matte bytes.

     MIFF+  Magick image file format.

     MONO   Bi-level bitmap in least-significant-byte (LSB) first order.

     MPEG+  Motion Picture Experts Group file interchange format.

     MTV+   MTV	Raytracing image format.

     NETSCPAPE
	    Netscape 216 color cube.

     NULL   NULL image.

     PBM+   Portable bitmap format (black and white).

     PCD    Photo CD.

     PCL    Page Control Language.

     PCX    ZSoft IBM PC Paintbrush file.

     PDF+   Portable Document Format.

     PGM+   Portable graymap format (gray scale).

     PICT   Apple Macintosh QuickDraw/PICT file.

     PNG    Portable Network Graphics.

     PNM+   Portable anymap.

     PPM+   Portable pixmap format (color).

     PS+    Adobe PostScript file.

     PS2+   Adobe Level	II PostScript file.

     RAD    Radiance image format.

     RGB    Raw red, green, and blue bytes.

     RGBA   Raw	red, green, blue and matte bytes.

     RLA    Alias/Wavefront image file;	read only

     RLE    Utah Run length encoded image file;	read only.

     SGI+   Irix RGB image file.

     SHTML  Hypertext Markup Language with a client-side image map.

     SUN+   SUN	Rasterfile.

     TEXT   raw	text file; read	only.

     TGA+   Truevision Targa image file.

     TIFF+  Tagged Image File Format.

     TILE   tile image with a texture.

     UYVY   16bit/pixel	interleaved YUV	(e.g. used by AccomWSD).

     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 (e.g. xc:yellow).

     XBM    X11	bitmap file.

     XPM    X Windows system pixmap file (color).

     XWD    X Windows system window dump file (color).

     YUV    CCIR 601 4:1:1 file.

     Note, a format delineated with + means that if more  than	one  image  is
     specified,	it is combined into a single multi-image file.	Use +adjoin if
     you want a	single image produced for each frame.

     Raw images	are expected to	have one byte per pixel	unless ImageMagick  is
     compiled in 16-bit	mode.  Here, the raw data is expected to be stored two
     bytes per pixel in	most-significant-byte-first order.

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	A4+0+0 image.tiff document.ps

     To	convert	a raw GRAY image with a	128 byte header	to a portable graymap,
     use:

	  convert -size	768x512+128 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	annotate an  image  with  blue	text  using  font  12x24  at  position
     (100,100),	use:

	  convert  -font  12x24	 -pen  blue  -draw  "text  +100+100  Cockatoo"
     bird.jpg bird.miff

     To	tile a 640x480 image with a JPEG texture with bumps use:

	  convert -size	640x480	tile:bumps.jpg tiled.png

     To	surround an icon with an ornamental border to use with Mosaic(1), use:

	  convert -mattecolor #ccc -frame 6x6 bird.jpg icon.png

     To	create a GIF animation image from a DNA	molecule sequence, use:

	  convert -delay 20 dna.* dna.gif

OPTIONS

     -adjoin
	    join images	into a single multi-image file.

     -average
	    averages a set of images.
	    99.9%).

     -blur factor
            blurs an image.  Specify factor as the percent enhancement (0.0  -
            99.9%).

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

	    The	color of the border is specified with the -bordercolor command
	    line option.

     -box color
	    set	the color of the annotation bounding box.  See	-draw  or  for
	    further details.

	    See	X(1) for details about the color specification.

     -charcoal factor
	    simulate a charcoal	drawing.

     -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, Transparent, 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	Transparent color space	behaves	uniquely in that it  preserves
	    the	matte channel of the image if it exists.

	    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, %b for file size in kilobytes, or  
  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: Zip 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.

	    To specify a percentage width or height instead,  append  %.   For
	    example  to	 crop  the  image  by  ten percent on all sides	of the
	    image, use -crop 10%.

	    Use	cropping to crop a particular area of an  image.    Use	 -crop
	    0x0	to remove edges	that are the background	color.	Omit the x and
	    y offset to	generate one or	more subimages of a uniform size.

     -cycle amount
	    displace image colormap by amount.

	    Amount defines the number of  positions  each  colormap  entry  is
	    shifted.

     -delay <1/100ths of a second>
	    display the	next image after pausing.

	    This option	is useful for regulating the animation of  a  sequence
	    of	GIF  images within Netscape.  1/100ths of a second must	expire
	    before the redisplay of the	image sequence.	  The  default	is  no
	    delay  between  each  showing  of the image	sequence.  The maximum
	    delay is 65535.

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

            This option specifies an image density when decoding a  Postscript
            or Portable Document page.  The default is 72 pixels per  inch  in
            the horizontal and vertical direction.

     -despeckle
	    reduce the speckles	within an image.

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

     -dispose method
	    GIF	disposal method.

	    Graphics Interchange Format	(GIF) Specification 89a	 of  July  31,
	    1990 for details.

     -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.

     -draw string
	    annotate an	image with one or more graphic primitives.

	    Use	this option to annotate	an image  with	one  or	 more  graphic
	    primitives.	 The primitives	include

	      rectangle
	      circle
	      polygon
	      color
	      matte
	      text
	      image

	    Rectangle, color, matte, text, and image require an	upper left and
	    lower right	coordinate.  Circle requires the center	coordinate and
	    a coordinate on the	outer edge.  Finally, polygon  requires	 three
	    or	more  coordinates  defining  its  boundaries.  Coordinates are
	    integers separated by an optional comma.  For example, to define a
	    circle centered at 100,100 that extends to 150,150 use:

	      -draw 'circle 100,100 150,150'

	    Use	color to change	the  color  of	a  pixel.   Follow  the	 pixel
	    coordinate with a method:

	      point
	      replace
	      floodfill
              reset

            Consider the target pixel as that specified  by  your  coordinate.
            The  point  method  recolors the target pixel.  The replace method
	    recolors any pixel that matches the	color  of  the	target	pixel.
	    Floodfill  recolors	any pixel that matches the color of the	target
	    pixel and is a neighbor.  Finally, reset recolors all pixels.

	    Use	matte to the change the	 pixel	matte  value  to  transparent.
	    Follow the pixel coordinate	with a method (see the color primitive
	    for	a description of methods).  The	point method changes the matte
	    value  of  the target pixel.  The replace method changes the matte
	    value of any pixel that matches the	color  of  the	target	pixel.
	    Floodfill  changes	the  matte value of any	pixel that matches the
	    color of the target	pixel and is a neighbor. Finally reset changes
	    the	matte value of all pixels.

	    Use	text  to  annotate  an	image  with  text.   Follow  the  text
	    coordinates	 with  a  string.   If the string has embedded spaces,
	    enclose it in double quotes.  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, %b for file size
	    in kilobytes, or \n	for newline.  For example,

		 -draw 'text 100,100 "%m:%f %wx%h"'

	    annotates the image	 with  MIFF:bird.miff  512x480	for  an	 image
	    titled bird.miff and whose width is	512 and	height is 480.

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

	    Use	image to composite an image with another  image.   Follow  the
	    image coordinates with the filename	of an image.

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

	    You	can set	the primitive color, font color, and font bounding box
	    color  with	 -pen,	-font,	and  -box  respectively.   Options are
	    processed in command line order so be sure to use -pen before  the
	    -draw option.

     -edge factor
	    detect edges  with	an  image.   Specify  factor  as  the  percent
	    enhancement	(0.0 - 99.9%).

     -emboss
	    emboss the 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
	    use	this font when annotating the image with text.

	    Convert contacts an	X server to obtain the font.  If an  X	server
	    is	not  available,	 a  Postscript	font is	used.  You can set the
	    pointsize with -pointsize.

     -frame <width>x<height>+<outer bevel width>+<inner	bevel width>
	    surround the image	with  an  ornamental  border.	See  X(1)  for
	    details about the geometry specification.

	    The	color of the border is specified with the -mattecolor  command
	    line option.

     -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>{%}{!}{<}{>}
	    preferred size or location of the image when encoding.

	    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.

	    Use	< to change the	dimensions of  the  image  only	 if  its  size
	    exceeds  the  geometry specification.  > resizes the image only if
	    its	dimensions is  less  than  the	geometry  specification.   For
	    example,  if  you  specify 640x480>	and the	image size is 512x512,
            the image  size  does  not  change.   However,  if  the  image  is
            1024x1024, it is resized to 640x480.

            There are 72 pixels per inch in Postscript coordinates. 

     -implode factor
	    implode image pixels about the  center.   Specify  factor  as  the
	    percent implosion (0 - 99.9%) or explosion (-99.9 -	0%).

     -interlace	type
	    the	type of	interlacing scheme: None, Line,	Plane,	or  Partition.
	    The	default	is 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...).	  Partition  is	  like
	    plane  except  the	different planes are saved to individual files
	    (e.g.  image.R, image.G, and image.B).

	    Use	Line, or Plane to create an interlaced GIF or progressive JPEG
	    image.  -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, %s for scene	number,	%b for file size in kilobytes,
	    or \n for newline.	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.

     -loop iterations
	    add	Netscape loop extension	to your	GIF animation.

	    A value other than zero forces the animation to repeat  itself  up
	    to iterations times.

     -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.  Use
	    +negate to only negate the grayscale pixels	of the image.

     -noise add	or reduce the noise in an image.

	    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.

     Use +noise	followed by a noise type to add	noise  to  an  image.	Choose
     from these	noise types:

	 uniform
	 gaussian
	 multiplicative
	 impulse
	 laplacian
	 poisson

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

	    This is a contrast enhancement technique.

     -opaque color
	    change this	color to the pen color within the image.  See -pen for
	    more details.

     -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	pixels	per  inch or a TEXT page in pixels.  The default for a
	    Postscript page is to center the image on a	letter page 612	by 792
	    pixels.  The margins are 1/2" (i.e.	 612x792+42+42).  Other	common
	    sizes are:

		Letter	    612x 792
		Tabloid	    792x1224
		Ledger	   1224x 792
                Legal       612x1008
                Statement   396x 612
                Executive   540x 720
                A3          842x1190
		A4	    595x 842
		A5	    420x 595
		B4	    729x1032
		B5	    516x 729
		Folio	    612x 936
		Quarto	    610x 780
		10x14	    720x1008

     For convenience you can specify the page size by media (e.g.  A4, Ledger,
     etc.).

     To	place a	Postscript image with a	given size on a	given  location	 on  a
     page,   use   -page  +HOFFSET+VOFFSET  -geometry  WIDTHxHEIGHT  (fill  in
     numbers). Note: this is only for generating Postscript, not  Encapsulated
     Postscript.

     To	position a GIF image, use -page	+LEFT+TOP (e.g.	-page +100+200).

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

     -paint radius
	    simulate an	oil painting.

	    Each pixel is replaced by the most frequent	color  in  a  circular
	    neighborhood whose width is	specified with radius.

     -pen color
	    set	the color of the font or opaque	color.	See -annotate or -draw
	    for	further	details.

	    See	X(1) for details about the color specification.

     -pointsize	value
	    pointsize of the Postscript	font.

     -quality value
	    JPEG quality setting.

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

     -raise <width>x<height>
	    lighten or darken image edges to create a 3-D effect.    See  X(1)
	    for	details	about the geometry specification.

	    Use	-raise to create a raised effect, otherwise use	+raise.

     -region <width>x<height>{+-}<x offset>{+-}<y offset>
	    apply options to a portion of the image.

	    By default,	any command line options are  applied  to  the	entire
	    image.  Use	-region	to restrict operations to a particular area of
	    the	image.

     -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.

     -segment <cluster threshold>x<smoothing threshold>
	    segment  an	 image	by  analyzing  the  histograms	of  the	 color
	    components	and  identifying  units	 that are homogeneous with the
	    fuzzy c-means technique.

	    Specify cluster threshold as the number of pixels in each  cluster
	    must  exceed  the  the  cluster  threshold to be considered	valid.
	    Smoothing threshold	eliminates noise in the	second	derivative  of
	    the	 histogram.   As  the  value  is  increased,  you can expect a
	    smoother second  derivative.   The	default	 is  1.5.   See	 IMAGE
	    SEGMENTATION for details.

     -shade <azimuth>x<elevation>
	    shade the image using a distant light source.

	    Specify azimuth and	elevation as the position of the light source.
	    Use	+shade to return the shading results as	a grayscale image.

     -sharpen factor
	    sharpen an image.  Specify factor as the percent enhancement  (0.0
	    - 99.9%).

     -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>{%}+<offset>
	    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  skip  any	header
	    information	 in  the  image	 or 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

	    Finally, use this option to	choose a particular  resolution	 layer
	    of a JBIG image (e.g. -size	1024x768).

     -solarize factor
	    negate all pixels above the	threshold level.   Specify  factor  as
	    the	percent	threshold of the intensity (0 -	99.9%).

	    This option	produces a solarization	effect seen  when  exposing  a
	    photographic film to light during the development process.

     -spread amount
	    displace image pixels by a random amount.

	    Amount defines the size of the neighborhood	around each  pixel  to
	    choose a candidate pixel to	swap.

     -swirl degrees
	    swirl image	pixels about the center.

	    Degrees defines the	tightness of the swirl.

     -texture filename
	    name of texture to tile onto the image background.

     -transparency color
	    make this color transparent	within the image.

     -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 transform 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]) or	a range	for MPEG images	 (e.g.	video.mpg[50-75]).   A
     subimage specification can	be disjoint (e.g. image.tiff[2,4,7]).  For raw
     images,  specify  a  subimage  with  a  geometry  (e.g.   -size   640x512
     image.rgb[320x256+50+50]).

     Single images are written with the filename you specify.  However, multi-
     part   images   (e.g.  a  multi-page  Postscript  document  with  +adjoin
     specified)	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.

IMAGE SEGMENTATION

     Use -segment to segment an	image by analyzing the histograms of the color
     components	 and  identifying units	that are homogeneous with the fuzzy c-
     means technique.  The scale-space filter analyzes the histograms  of  the
     three color components of the image and identifies	a set of classes.  The
     extents of	each  class  is	 used  to  coarsely  segment  the  image  with
     thresholding.   The color associated with each class is determined	by the
     mean color	of all pixels  within  the  extents  of	 a  particular	class.
     Finally,  any  unclassified pixels	are assigned to	the closest class with
     the fuzzy c-means technique.

     The fuzzy c-Means algorithm can be	summarized as follows:

     o Build a histogram, one for each color component of the image.

     o For each	histogram, successively	apply the scale-space filter and build
     an	 interval  tree	 of  zero  crossings  in the second derivative at each
     scale.  Analyze this scale-space ``fingerprint'' to determine which peaks
     or	valleys	in the histogram are most predominant.

     o The fingerprint defines intervals on the	axis of	the  histogram.	  Each
     interval contains either a	minima or a maxima in the original signal.  If
     each color	component lies within  the  maxima  interval,  that  pixel  is
     considered	``classified'' and is assigned an unique class number.

     o Any pixel that fails to be classified in	the above thresholding pass is
     classified	 using	the fuzzy c-Means technique.  It is assigned to	one of
     the classes discovered in the histogram analysis phase.

     The fuzzy c-Means technique attempts to cluster a pixel  by  finding  the
     local  minima  of	the  generalized  within  group	 sum  of squared error
     objective function.  A pixel is assigned to the closest  class  of	 which
     the fuzzy membership has a	maximum	value.

     For additional information	see

	    Young Won Lim, Sang	Uk  Lee,  "On  The  Color  Image  Segmentation
	    Algorithm	Based  on  the	Thresholding  and  the	Fuzzy  c-Means
	    Techniques", Pattern Recognition, Volume 23, Number	9, pages  935-
	    952, 1990.

ENVIRONMENT

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

SEE ALSO

     display(1), animate(1), import(1),	 montage(1),  mogrify(1),  combine(1),
     xtp(1)

COPYRIGHT

     Copyright 1996 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
smaller bigger reset
last modified: February 20 2004.