1gm(1) General Commands Manual gm(1)
2 NAME
6 gm - command-line utility to create, edit, compare, convert, or
8 display images
9
12 gm animate [ options ... ] file [ [ options ... ] file ... ]
13 gm batch [ options ... ] [ script ]
15 gm benchmark [ options ... ] subcommand
17 gm compare [ options ... ] reference-image [ options ... ] compare-im‐
19 age [ options ... ]
20 gm composite [ options ... ] change-image base-image [ mask-image ]
22 output-image
23 gm conjure [ options ] script.msl [ [ options ] script.msl ]
25 gm convert [ [ options ... ] [ input-file ... ] [ options ... ] ] out‐
27 put-file
28 gm display [ options ... ] file ... [ [options ... ]file ... ]
30 gm identify file [ file ... ]
32 gm import [ options ... ] file
34 gm mogrify [ options ... ] file ...
36 gm montage [ options ... ] file [ [ options ... ] file ... ] output-
38 file
39 gm time subcommand
41 gm version
43
45 GraphicsMagick's gm provides a suite of utilities for creating, compar‐
46 ing, converting, editing, and displaying images. All of the utilities
47 are provided as sub-commands of a single gm executable. The gm exe‐
48 cutable returns the exit code 0 to indicate success, or 1 to indicate
49 failure:
50 animate displays an animation (e.g. a GIF file) on any workstation dis‐
52 play running an X server.
53 batch executes an arbitary number of the utility commands (e.g. con‐
55 vert) in the form of a simple linear batch script in order to improve
56 execution efficiency, and/or to allow use as a subordinate co-process
57 under the control of an arbitrary script or program.
58 benchmark executes one of the other utility commands (e.g. convert) for
60 a specified number of iterations, or execution time, and reports execu‐
61 tion time and other profiling information such as CPU utilization.
62 Benchmark provides various operating modes including executing the com‐
63 mand with a varying number of threads, and alternate reporting formats
64 such as comma-separated value (CSV).
65 compare compares two images and reports difference statistics according
67 to specified metrics and/or outputs an image with a visual representa‐
68 tion of the differences. It may also be used to test if images are
69 similar within a particular range and specified metric, returning a
70 truth value to the executing environment.
71 composite composites images (blends or merges images together) to cre‐
73 ate new images.
74 conjure interprets and executes scripts in the Magick Scripting Lan‐
76 guage (MSL).
77 convert converts an input file using one image format to an output file
79 with the same or differing image format while applying an arbitrary
80 number of image transformations.
81 display is a machine architecture independent image processing and dis‐
83 play facility. It can display an image on any workstation display run‐
84 ning an X server.
85 identify describes the format and characteristics of one or more image
87 files. It will also report if an image is incomplete or corrupt.
88 import reads an image from any visible window on an X server and out‐
90 puts it as an image file. You can capture a single window, the entire
91 screen, or any rectangular portion of the screen.
92 mogrify transforms an image or a sequence of images. These transforms
94 include image scaling, image rotation, color reduction, and others. The
95 transmogrified image overwrites the original image.
96 montage creates a composite by combining several separate images. The
98 images are tiled on the composite image with the name of the image op‐
99 tionally appearing just below the individual tile.
100 time executes a subcommand and reports the user, system, and total exe‐
102 cution time consumed.
103 version reports the GraphicsMagick release version, maximum sample-
105 depth, copyright notice, supported features, and the options used while
106 building the software.
107 The GraphicsMagick utilities recognize the following image formats:
109 Name Mode Description
112 o 3FR r-- Hasselblad Photo RAW
113 o 8BIM rw- Photoshop resource format
114 o 8BIMTEXT rw- Photoshop resource text format
115 o 8BIMWTEXT rw- Photoshop resource wide text format
116 o APP1 rw- Raw application information
117 o APP1JPEG rw- Raw JPEG binary data
118 o ART r-- PF1: 1st Publisher
119 o ARW r-- Sony Alpha DSLR RAW
120 o AVS rw+ AVS X image
121 o BIE rw- Joint Bi-level Image experts Group
122 interchange format
123 o BMP rw+ Microsoft Windows bitmap image
124 o BMP2 -w- Microsoft Windows bitmap image v2
125 o BMP3 -w- Microsoft Windows bitmap image v3
126 o CACHE --- Magick Persistent Cache image format
127 o CALS rw- Continuous Acquisition and Life-cycle
128 Support Type 1 image
129 o CAPTION r-- Caption (requires separate size info)
130 o CIN rw- Kodak Cineon Format
131 o CMYK rw- Raw cyan, magenta, yellow, and black
132 samples (8 or 16 bits, depending on
133 the image depth)
134 o CMYKA rw- Raw cyan, magenta, yellow, black, and
135 matte samples (8 or 16 bits, depending
136 on the image depth)
137 o CR2 r-- Canon Photo RAW
138 o CRW r-- Canon Photo RAW
139 o CUR r-- Microsoft Cursor Icon
140 o CUT r-- DR Halo
141 o DCM r-- Digital Imaging and Communications in
142 Medicine image
143 o DCR r-- Kodak Photo RAW
144 o DCX rw+ ZSoft IBM PC multi-page Paintbrush
145 o DNG r-- Adobe Digital Negative
146 o DPS r-- Display PostScript Interpreter
147 o DPX rw- Digital Moving Picture Exchange
148 o EPDF rw- Encapsulated Portable Document Format
149 o EPI rw- Adobe Encapsulated PostScript
150 Interchange format
151 o EPS rw- Adobe Encapsulated PostScript
152 o EPS2 -w- Adobe Level II Encapsulated PostScript
153 o EPS3 -w- Adobe Level III Encapsulated PostScript
154 o EPSF rw- Adobe Encapsulated PostScript
155 o EPSI rw- Adobe Encapsulated PostScript
156 Interchange format
157 o EPT rw- Adobe Encapsulated PostScript with MS-DOS
158 TIFF preview
159 o EPT2 rw- Adobe Level II Encapsulated PostScript
160 with MS-DOS TIFF preview
161 o EPT3 rw- Adobe Level III Encapsulated PostScript
162 with MS-DOS TIFF preview
163 o EXIF rw- Exif digital camera binary data
164 o FAX rw+ Group 3 FAX (Not TIFF Group3 FAX!)
165 o FITS rw- Flexible Image Transport System
166 o FRACTAL r-- Plasma fractal image
167 o FPX rw- FlashPix Format
168 o GIF rw+ CompuServe graphics interchange format
169 o GIF87 rw- CompuServe graphics interchange format
170 (version 87a)
171 o GRADIENT r-- Gradual passing from one shade to
172 another
173 o GRAY rw+ Raw gray samples (8/16/32 bits,
174 depending on the image depth)
175 o HISTOGRAM -w- Histogram of the image
176 o HRZ r-- HRZ: Slow scan TV
177 o HTML -w- Hypertext Markup Language and a
178 client-side image map
179 o ICB rw+ Truevision Targa image
180 o ICC rw- ICC Color Profile
181 o ICM rw- ICC Color Profile
182 o ICO r-- Microsoft icon
183 o ICON r-- Microsoft icon
184 o IDENTITY r-- Hald CLUT identity image
185 o IMAGE r-- GraphicsMagick Embedded Image
186 o INFO -w+ Image descriptive information and
187 statistics
188 o IPTC rw- IPTC Newsphoto
189 o IPTCTEXT rw- IPTC Newsphoto text format
190 o IPTCWTEXT rw- IPTC Newsphoto wide text format
191 o JBG rw+ Joint Bi-level Image experts Group
192 interchange format
193 o JBIG rw+ Joint Bi-level Image experts Group
194 interchange format
195 o JNG rw- JPEG Network Graphics
196 o JP2 rw- JPEG-2000 JP2 File Format Syntax
197 o JPC rw- JPEG-2000 Code Stream Syntax
198 o JPEG rw- Joint Photographic Experts Group
199 JFIF format
200 o JPG rw- Joint Photographic Experts Group
201 JFIF format
202 o K25 r-- Kodak Photo RAW
203 o KDC r-- Kodak Photo RAW
204 o LABEL r-- Text image format
205 o M2V rw+ MPEG-2 Video Stream
206 o MAP rw- Colormap intensities and indices
207 o MAT r-- MATLAB image format
208 o MATTE -w+ MATTE format
209 o MIFF rw+ Magick Image File Format
210 o MNG rw+ Multiple-image Network Graphics
211 o MONO rw- Bi-level bitmap in least-significant-
212 -byte-first order
213 o MPC rw+ Magick Persistent Cache image format
214 o MPEG rw+ MPEG-1 Video Stream
215 o MPG rw+ MPEG-1 Video Stream
216 o MRW r-- Minolta Photo Raw
217 o MSL r-- Magick Scripting Language
218 o MTV rw+ MTV Raytracing image format
219 o MVG rw- Magick Vector Graphics
220 o NEF r-- Nikon Electronic Format
221 o NULL r-- Constant image of uniform color
222 o OTB rw- On-the-air bitmap
223 o P7 rw+ Xv thumbnail format
224 o PAL rw- 16bit/pixel interleaved YUV
225 o PALM rw- Palm Pixmap
226 o PBM rw+ Portable bitmap format (black and white)
227 o PCD rw- Photo CD
228 o PCDS rw- Photo CD
229 o PCL -w- Page Control Language
230 o PCT rw- Apple Macintosh QuickDraw/PICT
231 o PCX rw- ZSoft IBM PC Paintbrush
232 o PDB rw+ Palm Database ImageViewer Format
233 o PDF rw+ Portable Document Format
234 o PEF r-- Pentax Electronic File
235 o PFA r-- TrueType font
236 o PFB r-- TrueType font
237 o PGM rw+ Portable graymap format (gray scale)
238 o PGX r-- JPEG-2000 VM Format
239 o PICON rw- Personal Icon
240 o PICT rw- Apple Macintosh QuickDraw/PICT
241 o PIX r-- Alias/Wavefront RLE image format
242 o PLASMA r-- Plasma fractal image
243 o PNG rw- Portable Network Graphics
244 o PNG24 rw- Portable Network Graphics, 24 bit RGB
245 opaque only
246 o PNG32 rw- Portable Network Graphics, 32 bit RGBA
247 semitransparency OK
248 o PNG8 rw- Portable Network Graphics, 8-bit
249 indexed, binary transparency only
250 o PNM rw+ Portable anymap
251 o PPM rw+ Portable pixmap format (color)
252 o PREVIEW -w- Show a preview an image enhancement,
253 effect, or f/x
254 o PS rw+ Adobe PostScript
255 o PS2 -w+ Adobe Level II PostScript
256 o PS3 -w+ Adobe Level III PostScript
257 o PSD rw- Adobe Photoshop bitmap
258 o PTIF rw- Pyramid encoded TIFF
259 o PWP r-- Seattle Film Works
260 o RAF r-- Fuji Photo RAW
261 o RAS rw+ SUN Rasterfile
262 o RGB rw+ Raw red, green, and blue samples
263 o RGBA rw+ Raw red, green, blue, and matte samples
264 o RLA r-- Alias/Wavefront image
265 o RLE r-- Utah Run length encoded image
266 o SCT r-- Scitex HandShake
267 o SFW r-- Seattle Film Works
268 o SGI rw+ Irix RGB image
269 o SHTML -w- Hypertext Markup Language and a
270 client-side image map
271 o STEGANO r-- Steganographic image
272 o SUN rw+ SUN Rasterfile
273 o SVG rw+ Scalable Vector Gaphics
274 o TEXT rw+ Raw text
275 o TGA rw+ Truevision Targa image
276 o TIFF rw+ Tagged Image File Format
277 o TILE r-- Tile image with a texture
278 o TIM r-- PSX TIM
279 o TOPOL r-- TOPOL X Image
280 o TTF r-- TrueType font
281 o TXT rw+ Raw text
282 o UIL -w- X-Motif UIL table
283 o UYVY rw- 16bit/pixel interleaved YUV
284 o VDA rw+ Truevision Targa image
285 o VICAR rw- VICAR rasterfile format
286 o VID rw+ Visual Image Directory
287 o VIFF rw+ Khoros Visualization image
288 o VST rw+ Truevision Targa image
289 o WBMP rw- Wireless Bitmap (level 0) image
290 o WMF r-- Windows Metafile
291 o WPG r-- Word Perfect Graphics
292 o X rw- X Image
293 o X3F r-- Foveon X3 (Sigma/Polaroid) RAW
294 o XBM rw- X Windows system bitmap (black
295 and white)
296 o XC r-- Constant image uniform color
297 o XCF r-- GIMP image
298 o XMP rw- Adobe XML metadata
299 o XPM rw- X Windows system pixmap (color)
300 o XV rw+ Khoros Visualization image
301 o XWD rw- X Windows system window dump (color)
302 o YUV rw- CCIR 601 4:1:1 or 4:2:2 (8-bit only)
303 Modes:
305 r Read
306 w Write
307 + Multi-image
308 Support for some of these formats require additional programs or li‐
311 braries. See README in the source package for where to find optional
312 additional software.
313 Note, a format delineated with + means that if more than one image is
315 specified, frames are combined into a single multi-image file. Use +ad‐
316 join if you want a single image produced for each frame.
317 Your installation might not support all of the formats in the list. To
319 get an accurate listing of the formats supported by your particular
320 configuration, run "gm convert -list format".
321 Raw images are expected to have one byte per pixel unless gm is com‐
323 piled in 16-bit quantum mode or in 32-bit quantum mode. Here, the raw
324 data is expected to be stored two or four bytes per pixel, respec‐
325 tively, in most-significant-byte-first order. For example, you can
326 tell if gm was compiled in 16-bit mode by typing "gm version" without
327 any options, and looking for "Q:16" in the first line of output.
328
330 By default, the image format is determined by its magic number, i.e.,
331 the first few bytes of the file. To specify a particular image format,
332 precede the filename with an image format name and a colon (i.e.ps:im‐
333 age) or specify the image type as the filename suffix (i.e.image.ps).
334 The magic number takes precedence over the filename suffix and the pre‐
335 fix takes precedence over the magic number and the suffix in input
336 files. When a file is read, its magic number is stored in the "im‐
337 age->magick" string. In output files, the prefix takes precedence over
338 the filename suffix, and the filename suffix takes precedence over the
339 "image->magick" string.
340 To read the "built-in" formats (GRANITE, H, LOGO, NETSCAPE, PLASMA, and
342 ROSE) use a prefix (including the colon) without a filename or suffix.
343 To read the XC format, follow the colon with a color specification. To
344 read the CAPTION format, follow the colon with a text string or with a
345 filename prefixed with the at symbol (@).
346 When you specify X as your image type, the filename has special mean‐
349 ing. It specifies an X window by id, name, or root. If no filename is
350 specified, the window is selected by clicking the mouse in the desired
351 window.
352 Specify input_file as - for standard input, output_file as - for stan‐
354 dard output. If input_file has the extension .Z or .gz, the file is
355 uncompressed with uncompress or gunzip respectively. If output_file
356 has the extension .Z or .gz, the file is compressed using with compress
357 or gzip respectively.
358 Use an optional index enclosed in brackets after an input file name to
360 specify a desired subimage of a multi-resolution image format like
361 Photo CD (e.g. "img0001.pcd[4]") or a range for MPEG images (e.g.
362 "video.mpg[50-75]"). A subimage specification can be disjoint (e.g.
363 "image.tiff[2,7,4]"). For raw images, specify a subimage with a geome‐
364 try (e.g. -size 640x512 "image.rgb[320x256+50+50]"). Surround the im‐
365 age name with quotation marks to prevent your shell from interpreting
366 the square brackets. Single images are written with the filename you
367 specify. However, multi-part images (e.g., a multi-page PostScript doc‐
368 ument with +adjoin specified) may be written with the scene number in‐
369 cluded as part of the filename. In order to include the scene number in
370 the filename, it is necessary to include a printf-style %d format spec‐
371 ification in the file name and use the +adjoin option. For example,
372 image%02d.miff
374 writes files image00.miff, image01.miff, etc. Only a single specifica‐
376 tion is allowed within an output filename. If more than one specifica‐
377 tion is present, it will be ignored. It is best to embed the scene num‐
378 ber in the base part of the file name, not in the extension, because
379 the extension will not be a recognizeable image type.
380 When running a commandline utility, you can prepend an at sign @ to a
382 filename to read a list of image filenames from that file. This is con‐
383 venient in the event you have too many image filenames to fit on the
384 command line.
385
387 Options are processed in command line order. Any option you specify on
388 the command line remains in effect for the set of images that follows,
389 until the set is terminated by the appearance of any option or -noop.
390 Some options only affect the decoding of images and others only the en‐
391 coding. The latter can appear after the final group of input images.
392 This is a combined list of the command-line options used by the Graph‐
394 icsMagick utilities (animate, compare, composite, convert, display,
395 identify, import, mogrify and montage).
396 In this document, angle brackets ("<>") enclose variables and curly
399 brackets ("{}") enclose optional parameters. For example, "-fuzz <dis‐
400 tance>{%}" means you can use the option "-fuzz 10" or "-fuzz 2%".
401 -adjoin
404 join images into a single multi-image file
405 By default, all images of an image sequence are stored in the
407 same file. However, some formats (e.g. JPEG) do not support
408 storing more than one image per file and only the first frame in
409 an image sequence will be saved unless the result is saved to
410 separate files. Use +adjoin to force saving multiple frames to
411 multiple numbered files. If +adjoin is used, then the output
412 filename must include a printf style formatting specification
413 for the numeric part of the filename. For example,
414 image%02d.miff
416 -affine <matrix>
418 drawing transform matrix
419 This option provides a transform matrix {sx,rx,ry,sy,tx,ty} for
421 use by subsequent -draw or -transform options.
422 -antialias
424 remove pixel aliasing
425 By default antialiasing algorithms are used when drawing objects
427 (e.g. lines) or rendering vector formats (e.g. WMF and Post‐
428 script). Use +antialias to disable use of antialiasing algo‐
429 rithms. Reasons to disable antialiasing include avoiding in‐
430 creasing colors in the image, or improving rendering speed.
431 -append
433 append a set of images
434 This option creates a single image where the images in the orig‐
436 inal set are stacked top-to-bottom. If they are not of the same
437 width, any narrow images will be expanded to fit using the back‐
438 ground color. Use +append to stack images left-to-right. The
439 set of images is terminated by the appearance of any option. If
440 the -append option appears after all of the input images, all
441 images are appended.
442 -asc-cdl <spec>
444 apply ASC CDL color transform
445 Applies ("bakes in") the ASC CDL, which is a format for the ex‐
447 change of basic primary color grading information between equip‐
448 ment and software from different manufacturers. The format de‐
449 fines the math for three functions: slope, offset and power.
450 Each function uses a number for the red, green, and blue color
451 channels for a total of nine numbers comprising a single color
452 decision. The tenth number (optional) is for chromiance (satura‐
453 tion) as specified by ASC CDL 1.2.
454 The argument string is comma delimited and is in the following
456 form (but without invervening spaces or line breaks)
457 redslope,redoffset,redpower:
459 greenslope,greenoffset,greenpower:
460 blueslope,blueoffset,bluepower:
461 saturation
462 with the unity (no change) specification being:
464 "1.0,0.0,1.0:1.0,0.0,1.0:1.0,0.0,1.0:1.0"
466 -authenticate <string>
468 decrypt image with this password
469 Use this option to supply a password for decrypting an image or
471 an image sequence, if it is being read from a format such as PDF
472 that supports encryption. Encrypting images being written is
473 not supported.
474 -auto-orient
476 orient (rotate) image so it is upright
477 Adjusts the image orienation so that it is suitable for viewing.
479 Uses the orientation tag obtained from the image file or as sup‐
480 plied by the -orient option.
481 -average
483 average a set of images
484 The set of images is terminated by the appearance of any option.
486 If the -average option appears after all of the input images,
487 all images are averaged.
488 -backdrop
490 display the image centered on a backdrop.
491 This backdrop covers the entire workstation screen and is useful
493 for hiding other X window activity while viewing the image. The
494 color of the backdrop is specified as the foreground color (X11
495 default is black). Refer to "X Resources", below, for details.
496 -background <color>
498 the background color
499 The color is specified using the format described under the
501 -fill option.
502 -black-threshold red[,green][,blue][,opacity]
504 pixels below the threshold become black
505 Use -black-threshold to set pixels with values below the speci‐
507 fied threshold to minimum value (black). If only one value is
508 supplied, or the red, green, and blue values are identical, then
509 intensity thresholding is used. If the color threshold values
510 are not identical then channel-based thresholding is used, and
511 color distortion will occur. Specify a negative value (e.g. -1)
512 if you want a channel to be ignored but you do want to threshold
513 a channel later in the list. If a percent (%) symbol is ap‐
514 pended, then the values are treated as a percentage of maximum
515 range.
516 -blue-primary <x>,<y>
518 blue chromaticity primary point
519 -blur <radius>{x<sigma>}
521 blur the image with a Gaussian operator
522 Blur with the given radius and standard deviation (sigma).
524 -border <width>x<height>
526 surround the image with a border of color
527 See -geometry for details about the geometry specification.
529 -bordercolor <color>
531 the border color
532 The color is specified using the format described under the
534 -fill option.
535 -borderwidth <geometry>
537 the border width
538 -box <color>
540 set the color of the annotation bounding box
541 The color is specified using the format described under the
543 -fill option.
544 See -draw for further details.
546 -channel <type>
548 the type of channel
549 Choose from: Red, Green, Blue, Opacity, Matte, Cyan, Magenta,
551 Yellow, Black, or Gray.
552 Use this option to extract a particular channel from the image.
554 Opacity, for example, is useful for extracting the opacity val‐
555 ues from an image.
556 -charcoal <factor>
558 simulate a charcoal drawing
559 -chop <width>x<height>{+-}<x>{+-}<y>{%}
561 remove pixels from the interior of an image
562 Width and height give the number of columns and rows to remove,
564 and x and y are offsets that give the location of the leftmost
565 column and topmost row to remove.
566 The x offset normally specifies the leftmost column to remove.
568 If the -gravity option is present with NorthEast, East, or
569 SouthEast gravity, it gives the distance leftward from the right
570 edge of the image to the rightmost column to remove. Similarly,
571 the y offset normally specifies the topmost row to remove, but
572 if the -gravity option is present with SouthWest, South, or
573 SouthEast gravity, it specifies the distance upward from the
574 bottom edge of the image to the bottom row to remove.
575 The -chop option removes entire rows and columns, and moves the
577 remaining corner blocks leftward and upward to close the gaps.
578 -clip apply the clipping path, if one is present
580 If a clipping path is present, it will be applied to subsequent
582 operations.
583 For example, if you type the following command:
585 gm convert -clip -negate cockatoo.tif negated.tif
587 only the pixels within the clipping path are negated.
589 The -clip feature requires the XML library. If the XML library
591 is not present, the option is ignored.
592 -coalesce
594 merge a sequence of images
595 Each image N in the sequence after Image 0 is replaced with the
597 image created by flattening images 0 through N.
598 The set of images is terminated by the appearance of any option.
600 If the -coalesce option appears after all of the input images,
601 all images are coalesced.
602 -colorize <value>
604 colorize the image with the pen color
605 Specify the amount of colorization as a percentage. You can ap‐
607 ply separate colorization values to the red, green, and blue
608 channels of the image with a colorization value list delimited
609 with slashes (e.g. 0/0/50).
610 The -colorize option may be used in conjunction with -modulate
612 to produce a nice sepia toned image like:
613 gm convert input.ppm -modulate 115,0,100 \
615 -colorize 7,21,50 output.ppm.
616 -colormap <type>
618 define the colormap type
619 Choose between shared or private.
621 This option only applies when the default X server visual is
623 PseudoColor or GRAYScale. Refer to -visual for more details. By
624 default, a shared colormap is allocated. The image shares colors
625 with other X clients. Some image colors could be approximated,
626 therefore your image may look very different than intended.
627 Choose Private and the image colors appear exactly as they are
628 defined. However, other clients may go technicolor when the im‐
629 age colormap is installed.
630 -colors <value>
632 preferred number of colors in the image
633 The actual number of colors in the image may be less than your
635 request, but never more. Note, this is a color reduction option.
636 Images with less unique colors than specified with this option
637 will have any duplicate or unused colors removed. The ordering
638 of an existing color palette may be altered. When converting an
639 image from color to grayscale, convert the image to the gray
640 colorspace before reducing the number of colors since doing so
641 is most efficient. Refer to <a href="quantize.html">quantize for
642 more details.
643 Note, options -dither, -colorspace, and -treedepth affect the
645 color reduction algorithm.
646 -colorspace <value>
648 the type of colorspace
649 Choices are: CineonLog, CMYK, GRAY, HSL, HWB, OHTA, RGB,
651 Rec601Luma, Rec709Luma, Rec601YCbCr, Rec709YCbCr, Transparent,
652 XYZ, YCbCr, YIQ, YPbPr, or YUV.
653 Color reduction, by default, takes place in the RGB color space.
655 Empirical evidence suggests that distances in color spaces such
656 as YUV or YIQ correspond to perceptual color differences more
657 closely than do distances in RGB space. These color spaces may
658 give better results when color reducing an image. Refer to
659 quantize for more details. Two gray colorspaces are supported.
660 The Rec601Luma space is based on the recommendations for legacy
661 NTSC television (ITU-R BT.601-5). The Rec709Luma space is based
662 on the recommendations for HDTV (Rec. ITU-R BT.709-5) and is
663 suitable for use with computer graphics, and for contemporary
664 CRT displays. The GRAY colorspace currently selects the
665 Rec601Luma colorspace by default for backwards compatibly rea‐
666 sons. This default may be re-considered in the future.
667 Two YCbCr colorspaces are supported. The Rec601YCbCr space is
669 based on the recommendations for legacy NTSC television (ITU-R
670 BT.601-5). The Rec709CbCr space is based on the recommendations
671 for HDTV (Rec. ITU-R BT.709-5) and is suitable for suitable for
672 use with computer graphics, and for contemporary CRT displays.
673 The YCbCr colorspace specification is equivalent toRec601YCbCr.
674 The Transparent color space behaves uniquely in that it pre‐
677 serves the matte channel of the image if it exists.
678 The -colors or -monochrome option, or saving to a file format
680 which requires color reduction, is required for this option to
681 take effect.
682 -comment <string>
684 annotate an image with a comment
685 Use this option to assign a specific comment to the image, when
687 writing to an image format that supports comments. You can in‐
688 clude the image filename, type, width, height, or other image
689 attribute by embedding special format characters listed under
690 the -format option. The comment is not drawn on the image, but
691 is embedded in the image datastream via a "Comment" tag or simi‐
692 lar mechanism. If you want the comment to be visible on the im‐
693 age itself, use the -draw option instead.
694 For example,
696 -comment "%m:%f %wx%h"
698 produces an image comment of MIFF:bird.miff 512x480 for an image
700 titled bird.miff and whose width is 512 and height is 480.
701 If the first character of string is @, the image comment is read
703 from a file titled by the remaining characters in the string.
704 Please note that if the string comes from an untrusted source
705 that it should be sanitized before use since otherwise the con‐
706 tent of an arbitrary readable file could be incorporated in a
707 comment in the output file (a security risk).
708 If the -comment option appears multiple times, only the last
710 comment is stored.
711 In PNG images, the comment is stored in a tEXt or zTXt chunk
713 with the keyword "comment".
714 -compose <operator>
716 the type of image composition
717 The description of composition uses abstract terminology in or‐
719 der to allow the the description to be more clear, while avoid‐
720 ing constant values which are specific to a particular build
721 configuration. Each image pixel is represented by red, green,
722 and blue levels (which are equal for a gray pixel). MaxRGB is
723 the maximum integral value which may be stored in the red,
724 green, or blue channels of the image. Each image pixel may also
725 optionally (if the image matte channel is enabled) have an asso‐
726 ciated level of opacity (ranging from opaque to transparent),
727 which may be used to determine the influence of the pixel color
728 when compositing the pixel with another image pixel. If the im‐
729 age matte channel is disabled, then all pixels in the image are
730 treated as opaque. The color of an opaque pixel is fully visi‐
731 ble while the color of a transparent pixel color is entirely ab‐
732 sent (pixel color is ignored).
733 By definition, raster images have a rectangular shape. All image
735 rows are of equal length, and all image columns have the same
736 number of rows. By treating the opacity channel as a visual
737 "mask" the rectangular image may be given a "shape" by treating
738 the opacity channel as a cookie-cutter for the image. Pixels
739 within the shape are opaque, while pixels outside the shape are
740 transparent. Pixels on the boundary of the shape may be between
741 opaque and transparent in order to provide antialiasing (vis‐
742 ually smooth edges). The description of the composition opera‐
743 tors use this concept of image "shape" in order to make the de‐
744 scription of the operators easier to understand. While it is
745 convenient to describe the operators in terms of "shapes" they
746 are by no means limited to mask-style operations since they are
747 based on continuous floating-point mathematics rather than sim‐
748 ple boolean operations.
749 By default, the Over composite operator is used. The following
751 composite operators are available:
752 Over
754 In
755 Out
756 Atop
757 Xor
758 Plus
759 Minus
760 Add
761 Subtract
762 Difference
763 Divide
764 Multiply
765 Bumpmap
766 Copy
767 CopyRed
768 CopyGreen
769 CopyBlue
770 CopyOpacity
771 CopyCyan
772 CopyMagenta
773 CopyYellow
774 CopyBlack
775 The behavior of each operator is described below.
777 Over
780 The result will be the union of the two image shapes, with
782 opaque areas of change-image obscuring base-image in the
783 region of overlap.
784 In
786 The result is simply change-image cut by the shape of
788 base-image. None of the image data of base-image will be
789 in the result.
790 Out
792 The resulting image is change-image with the shape of
794 base-image cut out.
795 Atop
797 The result is the same shape as base-image, with change-
799 image obscuring base-image where the image shapes overlap.
800 Note this differs from over because the portion of change-
801 image outside base-image's shape does not appear in the
802 result.
803 Xor
805 The result is the image data from both change-image and
807 base-image that is outside the overlap region. The overlap
808 region will be blank.
809 Plus
811 The result is just the sum of the image data. Output val‐
813 ues are cropped to MaxRGB (no overflow). This operation is
814 independent of the matte channels.
815 Minus
817 The result of change-image - base-image, with underflow
819 cropped to zero. The matte channel is ignored (set to
820 opaque, full coverage).
821 Add
823 The result of change-image + base-image, with overflow
825 wrapping around (mod MaxRGB+1).
826 Subtract
828 The result of change-image - base-image, with underflow
830 wrapping around (mod MaxRGB+1). The add and subtract oper‐
831 ators can be used to perform reversible transformations.
832 Difference
834 The result of abs(change-image - base-image). This is use‐
836 ful for comparing two very similar images.
837 Divide
839 The result of change-image / base-image. This is useful
841 for improving the readability of text on unevenly illumi‐
842 nated photos (by using a gaussian blurred copy of change-
843 image as base-image).
844 Multiply
846 The result of change-image * base-image. This is useful
848 for the creation of drop-shadows.
849 Bumpmap
851 The result base-image shaded by change-image.
853 Copy
855 The resulting image is base-image replaced with change-im‐
857 age. Here the matte information is ignored.
858 CopyRed
860 The resulting image is the red channel in base-image re‐
862 placed with the red channel in change-image. The other
863 channels are copied untouched.
864 CopyGreen
866 The resulting image is the green channel in base-image re‐
868 placed with the green channel in change-image. The other
869 channels are copied untouched.
870 CopyBlue
872 The resulting image is the blue channel in base-image re‐
874 placed with the blue channel in change-image. The other
875 channels are copied untouched.
876 CopyOpacity
878 The resulting image is the opacity channel in base-image
880 replaced with the opacity channel in change-image. The
881 other channels are copied untouched.
882 CopyCyan
884 The resulting image is the cyan channel in base-image re‐
886 placed with the cyan channel in change-image. The other
887 channels are copied untouched. Use of this operator re‐
888 quires that base-image be in CMYK(A) colorspace.
889 CopyMagenta
891 The resulting image is the magenta channel in base-image
893 replaced with the magenta channel in change-image. The
894 other channels are copied untouched. Use of this operator
895 requires that base-image be in CMYK(A) colorspace.
896 CopyYellow
898 The resulting image is the yellow channel in base-image
900 replaced with the yellow channel in change-image. The
901 other channels are copied untouched. Use of this operator
902 requires that base-image be in CMYK(A) colorspace.
903 CopyBlack
905 The resulting image is the black channel in base-image re‐
907 placed with the black channel in change-image. The other
908 channels are copied untouched. Use of this operator re‐
909 quires that base-image be in CMYK(A) colorspace. If
910 change-image is not in CMYK space, then the change-image
911 pixel intensities are used.
912 -compress <type>
917 the type of image compression
918 Choices are: None, BZip, Fax, Group3, Group4, JPEG, Lossless,
920 LZW, RLE, Zip, LZMA, JPEG2000, JPEG2000, JBIG, JBIG2, WebP, or
921 ZSTD.
922 Specify +compress to store the binary image in an uncompressed
925 format. The default is the compression type of the specified
926 image file.
927 "Lossless" refers to lossless JPEG, which is only available if
929 the JPEG library has been patched to support it. Use of lossless
930 JPEG is generally not recommended.
931 Use the -quality option to set the compression level to be used
933 by the JPEG, JPEG-2000, PNG, MIFF, MPEG, and TIFF encoders. Use
934 the -sampling-factor option to set the sampling factor to be
935 used by the DPX, JPEG, MPEG, and YUV encoders for downsampling
936 the chroma channels.
937 -contrast
939 enhance or reduce the image contrast
940 This option enhances the intensity differences between the
942 lighter and darker elements of the image. Use -contrast to en‐
943 hance the image or +contrast to reduce the image contrast.
944 For a more pronounced effect you can repeat the option:
947 gm convert rose: -contrast -contrast rose_c2.png
949 -convolve <kernel>
951 convolve image with the specified convolution kernel
952 The kernel is specified as a comma-separated list of floating
954 point values, ordered left-to right, starting with the top row.
955 The order of the kernel is determined by the square root of the
956 number of entries. Presently only square kernels are supported.
957 -create-directories
959 create output directory if required
960 Use this option with -output-directory if the input paths con‐
962 tain subdirectories and it is desired to create similar subdi‐
963 rectories in the output directory. Without this option, mogrify
964 will fail if the required output directory does not exist.
965 -crop <width>x<height>{+-}<x>{+-}<y>{%}
967 preferred size and location of the cropped image
968 See -geometry for details about the geometry specification.
970 The width and height give the size of the image that remains af‐
972 ter cropping, and x and y are offsets that give the location of
973 the top left corner of the cropped image with respect to the
974 original image. To specify the amount to be removed, use -shave
975 instead.
976 If the x and y offsets are present, a single image is generated,
978 consisting of the pixels from the cropping region. The offsets
979 specify the location of the upper left corner of the cropping
980 region measured downward and rightward with respect to the upper
981 left corner of the image. If the -gravity option is present
982 with NorthEast, East, or SouthEast gravity, it gives the dis‐
983 tance leftward from the right edge of the image to the right
984 edge of the cropping region. Similarly, if the -gravity option
985 is present with SouthWest, South, or SouthEast gravity, the dis‐
986 tance is measured upward between the bottom edges.
987 If the x and y offsets are omitted, a set of tiles of the speci‐
989 fied geometry, covering the entire input image, is generated.
990 The rightmost tiles and the bottom tiles are smaller if the
991 specified geometry extends beyond the dimensions of the input
992 image.
993 -cycle <amount>
995 displace image colormap by amount
996 Amount defines the number of positions each colormap entry is‐
998 shifted.
999 -debug <events>
1002 enable debug printout
1003 The events parameter specifies which events are to be logged.
1005 It can be either None, All, or a comma-separated list consisting
1006 of one or more of the following domains: Annotate, Blob, Cache,
1007 Coder, Configure, Deprecate, Error, Exception, FatalError, In‐
1008 formation, Locale, Option, Render, Resource, TemporaryFile,
1009 Transform, User. Warning, or X11, For example, to log cache and
1010 blob events, use
1011 gm convert -debug "Cache,Blob" rose: rose.png
1013 The "User" domain is normally empty, but developers can log
1015 "User" events in their private copy of GraphicsMagick.
1016 Use the -log option to specify the format for debugging output.
1018 Use +debug to turn off all logging.
1020 An alternative to using -debug is to use the MAGICK_DEBUG envi‐
1022 ronment variable. The allowed values for the MAGICK_DEBUG envi‐
1023 ronment variable are the same as for the -debug option.
1024 -deconstruct
1026 break down an image sequence into constituent parts
1027 This option compares each image with the next in a sequence and
1029 returns the maximum bounding region of any pixel differences it
1030 discovers. This method can undo a coalesced sequence returned
1031 by the -coalesce option, and is useful for removing redundant
1032 information from a GIF or MNG animation.
1033 The sequence of images is terminated by the appearance of any
1035 option. If the -deconstruct option appears after all of the in‐
1036 put images, all images are deconstructed.
1037 -define <key>{=<value>},...
1039 add coder/decoder specific options This option creates one or
1040 more definitions for coders and decoders to use while reading
1041 and writing image data. Definitions may be passed to coders and
1042 decoders to control options that are specific to certain image
1043 formats. If value is missing for a definition, an empty-valued
1044 definition of a flag will be created with that name. This is
1045 used to control on/off options. Use +define <key>,... to remove
1046 definitions previously created. Use +define "*" to remove all
1047 existing definitions.
1048 The following definitions may be created:
1050 cineon:colorspace={rgb|cineonlog}
1053 Use the cineon:colorspace option when reading a Cineon
1055 file to specify the colorspace the Cineon file uses. This
1056 overrides the colorspace type implied by the DPX header
1057 (if any).
1058 dpx:bits-per-sample=<value>
1060 If the dpx:bits-per-sample key is defined, GraphicsMagick
1062 will write DPX images with the specified bits per sample,
1063 overriding any existing depth value. If this option is not
1064 specified, then the value is based on the existing image
1065 depth value from the original image file. The DPX standard
1066 supports bits per sample values of 1, 8, 10, 12, and 16.
1067 Many DPX readers demand a sample size of 10 bits with type
1068 A padding (see below).
1069 dpx:colorspace={rgb|cineonlog}
1071 Use the dpx:colorspace option when reading a DPX file to
1073 specify the colorspace the DPX file uses. This overrides
1074 the colorspace type implied by the DPX header (if any).
1075 dpx:packing-method={packed|a|b|lsbpad|msbpad}
1077 DPX samples are output within 32-bit words. They may be
1079 tightly packed end-to-end within the words ("packed"),
1080 padded with null bits to the right of the sample ("a" or
1081 "lsbpad"), or padded with null bits to the left of the
1082 sample ("b" or "msbpad"). This option only has an effect
1083 for sample sizes of 10 or 12 bits. If samples are not
1084 packed, the DPX standard recommends type A padding. Many
1085 DPX readers demand a sample size of 10 bits with type A
1086 padding.
1087 dpx:pixel-endian={lsb|msb}
1089 Allows the user to specify the endian order of the pixels
1091 when reading or writing the DPX files. Sometimes this is
1092 useful if the file is (or must be) written incorrectly so
1093 that the file header and the pixels use different endian‐
1094 ness.
1095 dpx:swap-samples={true|false}
1097 dpx:swap-samples-read={true|false}
1099 dpx:swap-samples-write={true|false}
1101 GraphicsMagick strives to adhere to the DPX standard but
1103 certain aspects of the standard can be quite confusing. As
1104 a result, some 10-bit DPX files have Red and Blue inter‐
1105 changed, or Cb and Cr interchanged due to an different in‐
1106 terpretation of the standard, or getting the wires
1107 crossed. The swap-samples option may be supplied when
1108 reading or writing in order to read or write using the
1109 necessary sample order. Use swap-samples-read when swap‐
1110 ping should only occur in the reader, or swap-samples-
1111 write when swapping should only occur in the writer.
1112 gradient:direction={South|North|West|East|NorthWest|North‐
1114 East|SouthWest|SouthEast}
1115 By default, the gradient coder produces a gradient from
1117 top to bottom ("South"). Since GraphicsMagick 1.3.35, the
1118 gradient direction may be specified to produce gradient
1119 vectors according to a gravity-like specification. The
1120 arguments are South (Top to Bottom), North (Bottom to
1121 Top), West (Right to Left), East (Left to Right), North‐
1122 West (Bottom-Right to Top-Left), NorthEast (Bottom-Left to
1123 Top-Right), SouthWest (Top-Right Bottom-Left), and South‐
1124 East (Top-Left to Bottom-Right).
1125 jp2:rate=<value>
1127 Specify the compression factor to use while writing
1129 JPEG-2000 files. The compression factor is the reciprocal
1130 of the compression ratio. The valid range is 0.0 to 1.0,
1131 with 1.0 indicating lossless compression. If defined, this
1132 value overrides the -quality setting. The default quality
1133 setting of 75 results in a rate value of 0.06641.
1134 jpeg:arithmetic={true|false}
1136 Enables or disables arithmetic encoding if the JPEG li‐
1138 brary supports it (default disabled). When this is en‐
1139 abled, optimize-coding is necessarily disabled.
1140 jpeg:block-smoothing={true|false}
1142 Enables or disables block smoothing when reading a JPEG
1144 file (default enabled).
1145 jpeg:dct-method=<value>
1147 Selects the IJG JPEG library DCT implementation to use.
1149 The encoding implementations vary in speed and encoding
1150 error. The available choices for value are islow, ifast,
1151 float, default and fastest. Note that fastest might not
1152 necessarily be fastest on your CPU, depending on the
1153 choices made when the JPEG library was built and how your
1154 CPU behaves.
1155 jpeg:fancy-upsampling={true|false}
1157 Enables or disables fancy upsampling when reading a JPEG
1159 file (default enabled).
1160 jpeg:max-scan-number=<value>
1162 Specifies an integer value for the maximum number of pro‐
1164 gressive scans allowed in a JPEG file. The default maxi‐
1165 mum is 100 scans. This limit is imposed due to a weakness
1166 in the JPEG standard which allows small JPEG files to take
1167 many minutes or hours to be read.
1168 jpeg:max-warnings=<value>
1170 Specifies an integer value for how many warnings are al‐
1172 lowed for any given error type before being promoted to a
1173 hard error. JPEG files producing excessive warnings indi‐
1174 cate a problem with the file.
1175 jpeg:optimize-coding={true|false}
1177 Selects if huffman encoding should be used. Huffman encod‐
1179 ing is enabled by default, but may be disabled for very
1180 large images since it encoding requires that the entire
1181 image be buffered in memory. Huffman encoding produces
1182 smaller JPEG files at the expense of added compression
1183 time and memory consumption.
1184 jpeg:preserve-settings
1186 If the jpeg:preserve-settings flag is defined, the JPEG
1188 encoder will use the same "quality" and "sampling-factor"
1189 settings that were found in the input file, if the input
1190 was in JPEG format. These settings are also preserved if
1191 the input is a JPEG file and the output is a JNG file. If
1192 the colorspace of the output file differs from that of the
1193 input file, the quality setting is preserved but the sam‐
1194 pling-factors are not.
1195 pcl:fit-to-page
1197 If the pcl:fit-to-page flag is defined, then the printer
1199 is requested to scale the image to fit the page size
1200 (width and/or height).
1201 png:chunk-malloc-max=<value>
1202 png:chunk-malloc-max specifies the maximum chunk size that
1204 libpng will be allowed to read. Libpng's default is nor‐
1205 mally 8,000,000 bytes. Very rarely, a valid PNG file may
1206 be encountered where the error is reported "chunk data is
1207 too large". In this case, the limit may be increased us‐
1208 ing this option. Take care when increasing this limit
1209 since an excessively large limit could allow untrusted
1210 files to use excessive memory.
1211 mng:maximum-loops=<value>
1213 mng:maximum-loops specifies the maximum number of loops
1215 allowed to be specified by a MNG LOOP chunk. Without an
1216 imposed limit, a MNG file could request up to 2147483647
1217 loops, which could run for a very long time. The current
1218 default limit is 512 loops.
1219 pdf:use-cropbox={true|false}
1221 If the pdf:use-cropbox flag is set to true, then Ghost‐
1223 script is requested to apply the PDF crop box.
1224 pdf:stop-on-error={true|false}
1226 If the pdf:stop-on-error flag is set to true, then Ghost‐
1228 script is requested to stop processing the PDF when the
1229 first error is encountered. Otherwise it will attempt to
1230 process all requested pages.
1231 ps:imagemask
1233 If the ps:imagemask flag is defined, the PS3 and EPS3
1235 coders will create Postscript files that render bilevel
1236 images with the Postscript imagemask operator instead of
1237 the image operator.
1238 ptif:minimum-geometry=<geometry>
1240 If the ptif:minimum-geometry key is defined, GraphicsMag‐
1242 ick will use it to determine the minimum frame size to
1243 output when writing a pyramid TIFF file (a TIFF file con‐
1244 taining a succession of reduced versions of the first
1245 frame). The default minimum geometry is 32x32.
1246 tiff:alpha={unspecified|associated|unassociated}
1248 Specify the TIFF alpha channel type when reading or writ‐
1250 ing TIFF files, overriding the normal value. The default
1251 alpha channel type for new files is unspecified alpha. Ex‐
1252 isting alpha settings are preserved when converting from
1253 one TIFF file to another. When a TIFF file uses associated
1254 alpha, the image pixels are pre-multiplied (i.e. altered)
1255 with the alpha channel. Files with "associated" alpha ap‐
1256 pear as if they were alpha composited on a black back‐
1257 ground when the matte channel is disabled. If the unasso‐
1258 ciated alpha type is selected, then the alpha channel is
1259 saved without altering the pixels. Photoshop recognizes
1260 associated alpha as transparency information, if the file
1261 is saved with unassociated alpha, the alpha information is
1262 loaded as an independent channel. Note that for many
1263 years, ImageMagick and GraphicsMagick marked TIFF files as
1264 using associated alpha, without properly pre-multiplying
1265 the pixels.
1266 tiff:fill-order={msb2lsb|lsb2msb}
1268 If the tiff:fill-order key is defined, GraphicsMagick will
1270 use it to determine the bit fill order used while writing
1271 TIFF files. The normal default is "msb2lsb", which matches
1272 the native bit order of all modern CPUs. The only excep‐
1273 tion to this is when Group3 or Group4 FAX compression is
1274 requested since FAX machines send data in bit-reversed or‐
1275 der and therefore RFC 2301 recommends using reverse order.
1276 tiff:group-three-options=<value>
1278 If the tiff:group-three-options key is defined, Graphics‐
1280 Magick will use it to set the group3 options tag when
1281 writing group3-compressed TIFF. Please see the TIFF spec‐
1282 ification for the usage of this tag. The default value is
1283 4.
1284 tiff:ignore-tags=<tags>
1286 If the tiff:ignore-tags key is defined, then it is used as
1288 a list of comma-delimited integer TIFF tag values to ig‐
1289 nore while reading the TIFF file. This is useful in order
1290 to be able to read files which which otherwise fail to
1291 read due to problems with TIFF tags. Note that some TIFF
1292 tags are required in order to be able to read the image
1293 data at all.
1294 tiff:report-warnings={false|true}
1296 If the tiff:report-warnings key is defined and set to
1298 true, then TIFF warnings are reported as a warning excep‐
1299 tion rather than as a coder log message. Such warnings
1300 are reported after the image has been read or written.
1301 Most TIFF warnings are benign but sometimes they may help
1302 deduce problems with the TIFF file, or help detect that
1303 the TIFF file requires a special application to read suc‐
1304 cessfully due to the use of proprietary or specialized ex‐
1305 tensions.
1306 tiff:sample-format={unsigned|ieeefp}
1308 If the tiff:sample-format key is defined, GraphicsMagick
1310 will use it to determine the sample format used while
1311 writing TIFF files. The default is "unsigned". Specify
1312 "ieeefp" in order to write floating-point TIFF files with
1313 float (32-bit) or double (64-bit) values. Use the
1314 tiff:bits-per-sample define to determine the type of
1315 floating-point value to use.
1316 tiff:max-sample-value=<value>
1318 If the tiff:max-sample-value key is defined, GraphicsMag‐
1320 ick will use the assigned value as the maximum floating
1321 point value while reading or writing IEEE floating point
1322 TIFFs. Otherwise the maximum value is 1.0 or the value ob‐
1323 tained from the file's SMaxSampleValue tag (if present).
1324 The floating point data is currently not scanned in ad‐
1325 vance to determine a best maximum sample value so if the
1326 range is not 1.0, or the SMaxSampleValue tag is not
1327 present, it may be necessary to (intelligently) use this
1328 parameter to properly read a file.
1329 tiff:min-sample-value=<value>
1331 If the tiff:min-sample-value key is defined, GraphicsMag‐
1333 ick will use the assigned value as the minimum floating
1334 point value while reading or writing IEEE floating point
1335 TIFFs. Otherwise the minimum value is 0.0 or the value ob‐
1336 tained from the file's SMinSampleValue tag (if present).
1337 tiff:bits-per-sample=<value>
1339 If the tiff:bits-per-sample key is defined, GraphicsMagick
1341 will write images with the specified bits per sample,
1342 overriding any existing depth value. Value may be any in
1343 the range of 1 to 32, or 64 when the default ´unsigned'
1344 format is written, or 16/32/24/64 if IEEEFP format is
1345 written. Please note that the baseline TIFF 6.0 specifi‐
1346 cation only requires readers to handle certain powers of
1347 two, and the values to be handled depend on the nature of
1348 the image (e.g. colormapped, grayscale, RGB, CMYK).
1349 tiff:samples-per-pixel=<value>
1351 If the tiff:samples-per-pixel key is defined to a value,
1353 the TIFF coder will write TIFF images with the defined
1354 samples per pixel, overriding any value stored in the im‐
1355 age. This option should not normally be used.
1356 tiff:rows-per-strip=<value>
1358 Allows the user to specify the number of rows per TIFF
1360 strip. Rounded up to a multiple of 16 when using JPEG
1361 compression. Ignored when using tiles.
1362 tiff:strip-per-page=true
1364 Requests that the image is written in a single TIFF strip.
1366 This is normally the default when group3 or group4 com‐
1367 pression is requested within reasonable limits. Requesting
1368 a single strip for large images may result in failure due
1369 to resource consumption in the writer or reader.
1370 tiff:tile
1372 Enable writing tiled TIFF (rather than stripped) using the
1374 default tile size. Tiled TIFF organizes the image as an
1375 array of smaller images (tiles) in order to enable random
1376 access.
1377 tiff:tile-geometry=<width>x<height>
1379 Specify the tile size to use while writing tiled TIFF.
1381 Width and height should be a multiple of 16. If the value
1382 is not a multiple of 16, then it will be rounded down. En‐
1383 ables tiled TIFF if it has not already been enabled.
1384 GraphicsMagick does not use tiled storage internally so
1385 tiles need to be converted back and forth from the inter‐
1386 nal scanline-oriented storage to tile-oriented storage.
1387 Testing with typical RGB images shows that useful square
1388 tile size values range from 128x128 to 1024x1024. Large
1389 images which require using a disk-based pixel cache bene‐
1390 fit from large tile sizes while images which fit in memory
1391 work well with smaller tile sizes.
1392 tiff:tile-width=<width>
1394 Specify the tile width to use while writing tiled TIFF.
1396 The tile height is then defaulted to an appropriate size.
1397 Width should be a multiple of 16. If the value is not a
1398 multiple of 16, then it will be rounded down. Enables
1399 tiled TIFF if it has not already been enabled.
1400 tiff:tile-height=<height>
1402 Specify the tile height to use while writing tiled TIFF.
1404 The tile width is then defaulted to an appropriate size.
1405 Height should be a multiple of 16. If the value is not a
1406 multiple of 16, then it will be rounded down. Enables
1407 tiled TIFF if it has not already been enabled.
1408 tiff:webp-lossless={TRUE|FALSE}
1410 Specify a value of TRUE to enable lossless mode while
1412 writing WebP-compressed TIFF files. The WebP webp:lossless
1413 option may also be used. The quality factor set by the
1414 -quality option may be used to influence the level of ef‐
1415 fort expended while compressing.
1416 tiff:zstd-compress-level=<value>
1418 Specify the compression level to use while writing Zstd-
1420 compressed TIFF files. The valid range is 1 to 22. If this
1421 define is not specified, then the 'quality' value is used
1422 such that the default quality setting of 75 is translated
1423 to a compress level of 9 such that ´quality' has a useful
1424 range of 10-184 if used for this purpose.
1425 webp:lossless={true|false}
1427 Enable lossless encoding.
1429 webp:method={0-6}
1431 Quality/speed trade-off.
1433 webp:image-hint={default,graph,photo,picture}
1435 Hint for image type.
1437 webp:target-size=<integer>
1439 Target size in bytes.
1441 webp:target-psnr=<float>
1443 Minimal distortion to try to achieve.
1445 webp:segments={1-4}
1447 Maximum number of segments to use.
1449 webp:sns-strength={0-100}
1451 Spatial Noise Shaping.
1453 webp:filter-strength={0-100}
1455 Filter strength.
1457 webp:filter-sharpness={0-7}
1459 Filter sharpness.
1461 webp:filter-type={0,1}
1463 Filtering type. 0 = simple, 1 = strong (only used if fil‐
1465 ter-strength > 0 or autofilter is enabled).
1466 webp:auto-filter={true|false}
1468 Auto adjust filter's strength.
1470 webp:alpha-compression=<integer>
1472 Algorithm for encoding the alpha plane (0 = none, 1 = com‐
1474 pressed with WebP lossless). Default is 1.
1475 webp:alpha-filtering=<integer>
1477 Predictive filtering method for alpha plane. 0: none, 1:
1479 fast, 2: best. Default is 1.
1480 webp:alpha-quality={0-100}
1482 Between 0 (smallest size) and 100 (lossless). Default is
1484 100.
1485 webp:pass=[1..10]
1487 Number of entropy-analysis passes.
1489 webp:show-compressed={true|false}
1491 Export the compressed picture back. In-loop filtering is
1493 not applied.
1494 webp:preprocessing=[0,1,2]
1496 0=none, 1=segment-smooth, 2=pseudo-random dithering
1498 webp:partitions=[0-3]
1500 log2(number of token partitions) in [0..3]. Default is 0
1502 for easier progressive decoding.
1503 webp:partition-limit={0-100}
1505 Quality degradation allowed to fit the 512k limit on pre‐
1507 diction modes coding (0: no degradation, 100: maximum pos‐
1508 sible degradation).
1509 webp:emulate-jpeg-size={true|false}
1511 If true, compression parameters will be remapped to better
1513 match the expected output size from JPEG compression. Gen‐
1514 erally, the output size will be similar but the degrada‐
1515 tion will be lower.
1516 webp:thread-level=<integer>
1518 If non-zero, try and use multi-threaded encoding.
1520 webp:low-memory={true|false}
1522 If set, reduce memory usage (but increase CPU use)
1524 webp:use-sharp-yuv={true|false}
1526 If set, if needed, use sharp (and slow) RGB->YUV conver‐
1528 sion
1529 For example, to create a postscript file that will render only
1534 the black pixels of a bilevel image, use:
1535 gm convert bilevel.tif -define ps:imagemask eps3:stencil.ps
1537 -delay <1/100ths of a second>
1539 display the next image after pausing
1540 This option is useful for regulating the animation of image se‐
1542 quences Delay/100 seconds must expire before the display of the
1543 next image. The default is no delay between each showing of the
1544 image sequence. The maximum delay is 65535.
1545 You can specify a delay range (e.g. -delay 10-500) which sets
1547 the minimum and maximum delay.
1548 -density <width>x<height>
1550 horizontal and vertical resolution in pixels of the image This
1551 option specifies the image resolution to store while encoding a
1552 raster image or the canvas resolution while rendering (reading)
1553 vector formats such as Postscript, PDF, WMF, and SVG into a
1554 raster image. Image resolution provides the unit of measure to
1555 apply when rendering to an output device or raster image. The
1556 default unit of measure is in dots per inch (DPI). The -units
1557 option may be used to select dots per centimeter instead.
1558 The default resolution is 72 dots per inch, which is equivalent
1559 to one point per pixel (Macintosh and Postscript standard). Com‐
1560 puter screens are normally 72 or 96 dots per inch while printers
1561 typically support 150, 300, 600, or 1200 dots per inch. To de‐
1562 termine the resolution of your display, use a ruler to measure
1563 the width of your screen in inches, and divide by the number of
1564 horizontal pixels (1024 on a 1024x768 display). If the file
1565 format supports it, this option may be used to update the stored
1566 image resolution. Note that Photoshop stores and obtains image
1567 resolution from a proprietary embedded profile. If this profile
1568 is not stripped from the image, then Photoshop will continue to
1569 treat the image using its former resolution, ignoring the image
1570 resolution specified in the standard file header. The density
1571 option is an attribute and does not alter the underlying raster
1572 image. It may be used to adjust the rendered size for desktop
1573 publishing purposes by adjusting the scale applied to the pix‐
1574 els. To resize the image so that it is the same size at a dif‐
1575 ferent resolution, use the -resample option.
1576 -depth <value>
1578 depth of the image
1579 This is the number of bits of color to preserve in the image.
1581 Any value between 1 and QuantumDepth (build option) may be spec‐
1582 ified, although 8 or 16 are the most common values. Use this op‐
1583 tion to specify the depth of raw images whose depth is unknown
1584 such as GRAY, RGB, or CMYK, or to change the depth of any image
1585 after it has been read. The depth option is applied to the pix‐
1586 els immediately so it may be used as a form of simple compres‐
1587 sion by discarding the least significant bits. Reducing the
1588 depth in advance may speed up color quantization, and help cre‐
1589 ate smaller file sizes when using a compression algorithm like
1590 LZW or ZIP.
1591 -descend
1593 obtain image by descending window hierarchy
1594 -despeckle
1596 reduce the speckles within an image
1597 -displace <horizontal scale>x<vertical scale>
1599 shift image pixels as defined by a displacement map
1600 With this option, composite image is used as a displacement map.
1602 Black, within the displacement map, is a maximum positive dis‐
1603 placement. White is a maximum negative displacement and middle
1604 gray is neutral. The displacement is scaled to determine the
1605 pixel shift. By default, the displacement applies in both the
1606 horizontal and vertical directions. However, if you specify
1607 mask, composite image is the horizontal X displacement and mask
1608 the vertical Y displacement.
1609 -display <host:display[.screen]>
1611 specifies the X server to contact
1612 This option is used with convert for obtaining image or font
1614 from this X server. See X(1).
1615 -dispose <method>
1617 GIF disposal method
1618 The Disposal Method indicates the way in which the graphic is to
1620 be treated after being displayed.
1621 Here are the valid methods:
1623 Undefined No disposal specified.
1625 None Do not dispose between frames.
1626 Background Overwrite the image area with
1627 the background color.
1628 Previous Overwrite the image area with
1629 what was there prior to rendering
1630 the image.
1631 -dissolve <percent>
1633 dissolve an image into another by the given percent
1634 The opacity of the composite image is multiplied by the given
1636 percent, then it is composited over the main image.
1637 -dither
1639 apply Floyd/Steinberg error diffusion to the image
1640 The basic strategy of dithering is to trade intensity resolution
1642 for spatial resolution by averaging the intensities of several
1643 neighboring pixels. Images which suffer from severe contouring
1644 when reducing colors can be improved with this option.
1645 The -colors or -monochrome option is required for this option to
1647 take effect.
1648 Use +dither to turn off dithering and to render PostScript with‐
1650 out text or graphic aliasing. Disabling dithering often (but not
1651 always) leads to decreased processing time.
1652 -draw <string>
1654 annotate an image with one or more graphic primitives
1655 Use this option to annotate an image with one or more graphic
1657 primitives. The primitives include shapes, text, transforma‐
1658 tions, and pixel operations. The shape primitives are
1659 point x,y
1661 line x0,y0 x1,y1
1662 rectangle x0,y0 x1,y1
1663 roundRectangle x0,y0 x1,y1 wc,hc
1664 arc x0,y0 x1,y1 a0,a1
1665 ellipse x0,y0 rx,ry a0,a1
1666 circle x0,y0 x1,y1
1667 polyline x0,y0 ... xn,yn
1668 polygon x0,y0 ... xn,yn
1669 Bezier x0,y0 ... xn,yn
1670 path path specification
1671 image operator x0,y0 w,h filename
1672 The text primitive is
1674 text x0,y0 string
1676 The text gravity primitive is
1678 gravity NorthWest, North, NorthEast, West, Center,
1680 East, SouthWest, South, or SouthEast
1681 The text gravity primitive only affects the placement of text
1683 and does not interact with the other primitives. It is equiva‐
1684 lent to using the -gravity commandline option, except that it is
1685 limited in scope to the -draw option in which it appears.
1686 The transformation primitives are
1688 rotate degrees
1690 translate dx,dy
1691 scale sx,sy
1692 skewX degrees
1693 skewY degrees
1694 The pixel operation primitives are
1696 color x0,y0 method
1698 matte x0,y0 method
1699 The shape primitives are drawn in the color specified in the
1701 preceding -stroke option. Except for the line and point primi‐
1702 tives, they are filled with the color specified in the preceding
1703 -fill option. For unfilled shapes, use -fill none.
1704 Point requires a single coordinate.
1706 Line requires a start and end coordinate.
1708 Rectangle expects an upper left and lower right coordinate.
1710 RoundRectangle has the upper left and lower right coordinates
1712 and the width and height of the corners.
1713 Circle has a center coordinate and a coordinate for the outer
1715 edge.
1716 Use Arc to inscribe an elliptical arc within a rectangle. Arcs
1718 require a start and end point as well as the degree of rotation
1719 (e.g. 130,30 200,100 45,90).
1720 Use Ellipse to draw a partial ellipse centered at the given
1722 point with the x-axis and y-axis radius and start and end of arc
1723 in degrees (e.g. 100,100 100,150 0,360).
1724 Finally, polyline and polygon require three or more coordinates
1726 to define its boundaries. Coordinates are integers separated by
1727 an optional comma. For example, to define a circle centered at
1728 100,100 that extends to 150,150 use:
1729 -draw 'circle 100,100 150,150'
1731 Paths (See Paths) represent an outline of an object which is de‐
1733 fined in terms of moveto (set a new current point), lineto (draw
1734 a straight line), curveto (draw a curve using a cubic Bezier),
1735 arc (elliptical or circular arc) and closepath (close the cur‐
1736 rent shape by drawing a line to the last moveto) elements. Com‐
1737 pound paths (i.e., a path with subpaths, each consisting of a
1738 single moveto followed by one or more line or curve operations)
1739 are possible to allow effects such as "donut holes" in objects.
1740 Use image to composite an image with another image. Follow the
1742 image keyword with the composite operator, image location, image
1743 size, and filename:
1744 -draw 'image Over 100,100 225,225 image.jpg'
1746 You can use 0,0 for the image size, which means to use the ac‐
1748 tual dimensions found in the image header. Otherwise, it will be
1749 scaled to the given dimensions. See -compose for a description
1750 of the composite operators.
1751 Use text to annotate an image with text. Follow the text coordi‐
1753 nates with a string. If the string has embedded spaces, enclose
1754 it in single or double quotes. Optionally you can include the
1755 image filename, type, width, height, or other image attribute by
1756 embedding special format character. See -comment for details.
1757 For example,
1759 -draw 'text 100,100 "%m:%f %wx%h"'
1762 annotates the image with MIFF:bird.miff 512x480 for an image titled
1765 bird.miff
1766 and whose width is 512 and height is 480.
1767 If the first character of string is @, the text is read
1769 from a file titled by the remaining characters in the string. Please
1770 note that if the string comes from an untrusted source that it should
1771 be sanitized before use (a security risk).
1772 Rotate rotates subsequent shape primitives and text primitives about
1774 the origin of the main image. If the -region option precedes the
1775 -draw option, the origin for transformations is the upper left
1776 corner of the region.
1777 Translate translates them.
1779 Scale scales them.
1781 SkewX and SkewY skew them with respect to the origin of
1783 the main image or the region.
1784 The transformations modify the current affine matrix, which is initialized
1786 from the initial affine matrix defined by the -affine option.
1787 Transformations are cumulative within the -draw option.
1788 The initial affine matrix is not affected; that matrix is only changed by the
1789 appearance of another -affine option. If another -draw
1790 option appears, the current affine matrix is reinitialized from
1791 the initial affine matrix.
1792 Use color to change the color of a pixel to the fill color (see
1794 -fill). Follow the pixel coordinate
1795 with a method:
1796 point
1798 replace
1799 floodfill
1800 filltoborder
1801 reset
1802 Consider the target pixel as that specified by your coordinate.
1804 The point method recolors the target pixel. The replace method
1805 recolors any pixel that matches the color of the target pixel.
1806 Floodfill recolors any pixel that matches the color of the tar‐
1807 get pixel and is a neighbor, whereas filltoborder recolors any
1808 neighbor pixel that is not the border color. Finally, reset re‐
1809 colors all pixels.
1810 Use matte to the change the pixel matte value to transparent.
1812 Follow the pixel coordinate with a method (see the color primi‐
1813 tive for a description of methods). The point method changes the
1814 matte value of the target pixel. The replace method changes the
1815 matte value of any pixel that matches the color of the target
1816 pixel. Floodfill changes the matte value of any pixel that
1817 matches the color of the target pixel and is a neighbor, whereas
1818 filltoborder changes the matte value of any neighbor pixel that
1819 is not the border color (-bordercolor). Finally reset changes
1820 the matte value of all pixels.
1821 You can set the primitive color, font, and font bounding box
1823 color with -fill, -font, and -box respectively. Options are pro‐
1824 cessed in command line order so be sure to use these options be‐
1825 fore the -draw option.
1826 -edge <radius>
1828 detect edges within an image
1829 -emboss <radius>
1831 emboss an image
1832 -encoding <type>
1834 specify the text encoding
1835 Choose from AdobeCustom, AdobeExpert, AdobeStandard, AppleRoman,
1837 BIG5, GB2312, Latin 2, None, SJIScode, Symbol, Unicode, Wansung.
1838 -endian <type>
1840 specify endianness (MSB, LSB, or Native) of image
1841 MSB indicates big-endian (e.g. SPARC, Motorola 68K) while LSB
1843 indicates little-endian (e.g. Intel 'x86, VAX) byte ordering.
1844 Native indicates to use the normal ordering for the current CPU.
1845 This option currently only influences the CMYK, DPX, GRAY, RGB,
1846 and TIFF, formats.
1847 Use +endian to revert to unspecified endianness.
1849 -enhance
1851 apply a digital filter to enhance a noisy image
1852 -equalize
1854 perform histogram equalization to the image
1855 -extent <width>x<height>{+-}<x>{+-}<y>
1857 composite image on background color canvas image
1858 This option composites the image on a new background color
1860 (-background) canvas image of size <width>x<height>. The exist‐
1861 ing image content is composited at the position specified by ge‐
1862 ometry x and y offset and/or desired gravity (-gravity) using
1863 the current image compose (-compose) method. Image content
1864 which falls outside the bounds of the new image dimensions is
1865 discarded.
1866 For example, this command creates a thumbnail of an image, and
1868 centers it on a red color backdrop image, offsetting the canvas
1869 ten pixels to the left and five pixels up, with respect to the
1870 thumbnail:
1871 gm convert infile.jpg -thumbnail 120x80 -background red -gravity center \
1873 -extent 140x100-10-5 outfile.jpg
1874 This command reduces or expands a JPEG image to fit on an
1876 800x600 display:
1877 gm convert -size 800x600 input.jpg \
1879 -resize 800x600 -background black \
1880 -compose Copy -gravity center \
1881 -extent 800x600 \
1882 -quality 92 output.jpg
1883 If the aspect ratio of the input image isn't exactly 4:3, then
1885 the image is centered on an 800x600 black canvas.
1886 -file <filename>
1888 write annotated difference image to file
1889 If -file is specified, then an annotated difference image is
1891 generated and written to the specified file. Pixels which differ
1892 between the reference and compare images are modified from those
1893 in the compare image so that the changed pixels become more ob‐
1894 vious. Some images may require use of an alternative highlight
1895 style (see -highlight-style) or highlight color (see -highlight-
1896 color) before the changes are obvious.
1897 -fill <color>
1899 color to use when filling a graphic primitive
1900 Colors are represented in GraphicsMagick in the same form used
1902 by SVG. Use "gm convert -list color" to list named colors:
1903 name (named color)
1905 #RGB (hex numbers, 4 bits each)
1906 #RRGGBB (8 bits each)
1907 #RRRGGGBBB (12 bits each)
1908 #RRRRGGGGBBBB (16 bits each)
1909 #RGBA (4 bits each)
1910 #RRGGBBAA (8 bits each)
1911 #RRRGGGBBBAAA (12 bits each)
1912 #RRRRGGGGBBBBAAAA (16 bits each)
1913 rgb(r,g,b) (r,g,b are decimal numbers)
1914 rgba(r,g,b,a) (r,g,b,a are decimal numbers)
1915 Enclose the color specification in quotation marks to prevent
1917 the "#" or the parentheses from being interpreted by your shell.
1918 For example,
1920 gm convert -fill blue ...
1922 gm convert -fill "#ddddff" ...
1923 gm convert -fill "rgb(65000,65000,65535)" ...
1924 The shorter forms are scaled up, if necessary by replication.
1926 For example, #3af, #33aaff, and #3333aaaaffff are all equiva‐
1927 lent.
1928 See -draw for further details.
1930 -filter <type>
1932 use this type of filter when resizing an image
1933 Use this option to affect the resizing operation of an image
1935 (see -geometry). Choose from these filters (ordered by approxi‐
1936 mate increasing CPU time):
1937 Point
1939 Box
1940 Triangle
1941 Hermite
1942 Hanning
1943 Hamming
1944 Blackman
1945 Gaussian
1946 Quadratic
1947 Cubic
1948 Catrom
1949 Mitchell
1950 Lanczos
1951 Bessel
1952 Sinc
1953 The default filter is automatically selected to provide the best
1955 quality while consuming a reasonable amount of time. The
1956 Mitchell filter is used if the image supports a palette, sup‐
1957 ports a matte channel, or is being enlarged, otherwise the Lanc‐
1958 zos filter is used.
1959 -flatten
1961 flatten a sequence of images
1962 In some file formats (e.g. Photoshop's PSD) complex images may
1964 be represented by "layers" (independent images) which must be
1965 composited in order to obtain the final rendition. The -flatten
1966 option accomplishes this composition. The sequence of images is
1967 replaced by a single image created by compositing each image in
1968 turn, while respecting composition operators and page offsets.
1969 While -flatten is immediately useful for eliminating layers, it
1970 is also useful as a general-purpose composition tool.
1971 The sequence of images is terminated by the appearance of any
1973 option. If the -flatten option appears after all of the input
1974 images, all images are flattened. Also see -mosaic which is
1975 similar to -flatten except that it adds a suitably-sized canvas
1976 base image.
1977 For example, this composites an image on top of a 640x400 trans‐
1979 parent black canvas image:
1980 gm convert -size 640x300 xc:transparent \
1982 -compose over -page +0-100 \
1983 frame.png -flatten output.png
1984 and this flattens a Photoshop PSD file:
1986 gm convert input.psd -flatten output.png
1988 -flip create a "mirror image"
1990 reflect the scanlines in the vertical direction.
1992 -flop create a "mirror image"
1994 reflect the scanlines in the horizontal direction.
1996 -font <name>
1998 use this font when annotating the image with text
1999 You can tag a font to specify whether it is a PostScript, True‐
2001 Type, or X11 font. For example, Arial.ttf is a TrueType font,
2002 ps:helvetica is PostScript, and x:fixed is X11.
2003 -foreground <color>
2005 define the foreground color
2006 The color is specified using the format described under the
2008 -fill option.
2009 -format <type>
2011 the image format type
2012 When used with the mogrify utility, this option will convert any
2014 image to the image format you specify. See GraphicsMagick(1)
2015 for a list of image format types supported by GraphicsMagick, or
2016 see the output of 'gm -list format'.
2017 By default the file is written to its original name. However,
2019 if the filename extension matches a supported format, the exten‐
2020 sion is replaced with the image format type specified with -for‐
2021 mat. For example, if you specify tiff as the format type and
2022 the input image filename is image.gif, the output image filename
2023 becomes image.tiff.
2024 -format <string>
2026 output formatted image characteristics
2027 When used with the identify utility, or the convert utility with
2029 output written to the 'info:-' file specification, use this op‐
2030 tion to print information about the image in a format of your
2031 choosing. You can include the image filename, type, width,
2032 height, Exif data, or other image attributes by embedding spe‐
2033 cial format characters:
2034 %b file size
2036 %c comment
2037 %d directory
2038 %e filename extension
2039 %f filename
2040 %g page dimensions and offsets
2041 %h height
2042 %i input filename
2043 %k number of unique colors
2044 %l label
2045 %m magick
2046 %n number of scenes
2047 %o output filename
2048 %p page number
2049 %q image bit depth
2050 %r image type description
2051 %s scene number
2052 %t top of filename
2053 %u unique temporary filename
2054 %w width
2055 %x horizontal resolution
2056 %y vertical resolution
2057 %A transparency supported
2058 %C compression type
2059 %D GIF disposal method
2060 %G Original width and height
2061 %H page height
2062 %M original filename specification
2063 %O page offset (x,y)
2064 %P page dimensions (width,height)
2065 %Q compression quality
2066 %T time delay (in centi-seconds)
2067 %U resolution units
2068 %W page width
2069 %X page horizontal offset (x)
2070 %Y page vertical offset (y)
2071 %@ trim bounding box
2072 %# signature
2073 \n newline
2074 \r carriage return
2075 %% %
2076 For example,
2078 -format "%m:%f %wx%h"
2080 displays MIFF:bird.miff 512x480 for an image titled bird.miff
2082 and whose width is 512 and height is 480.
2083 If the first character of string is @, the format is read from a
2085 file titled by the remaining characters in the string. Please
2086 note that if the string comes from an untrusted source that it
2087 should be sanitized before use since this may be used to incor‐
2088 porate any readable file on the system (a security risk).
2089 The values of image type (%r) which may be returned include:
2091 Bilevel
2093 Grayscale
2094 GrayscaleMatte
2095 Palette
2096 PaletteMatte
2097 TrueColor
2098 TrueColorMatte
2099 ColorSeparation
2100 ColorSeparationMatte
2101 Optimize
2102 You can also use the following special formatting syntax to
2104 print Exif information contained in the file:
2105 %[EXIF:<tag>]
2107 Where "<tag>" may be one of the following:
2109 * (print all Exif tags, in keyword=data format)
2111 ! (print all Exif tags, in tag_number format)
2112 #hhhh (print data for Exif tag #hhhh)
2113 ImageWidth
2114 ImageLength
2115 BitsPerSample
2116 Compression
2117 PhotometricInterpretation
2118 FillOrder
2119 DocumentName
2120 ImageDescription
2121 Make
2122 Model
2123 StripOffsets
2124 Orientation
2125 SamplesPerPixel
2126 RowsPerStrip
2127 StripByteCounts
2128 XResolution
2129 YResolution
2130 PlanarConfiguration
2131 ResolutionUnit
2132 TransferFunction
2133 Software
2134 DateTime
2135 Artist
2136 WhitePoint
2137 PrimaryChromaticities
2138 TransferRange
2139 JPEGProc
2140 JPEGInterchangeFormat
2141 JPEGInterchangeFormatLength
2142 YCbCrCoefficients
2143 YCbCrSubSampling
2144 YCbCrPositioning
2145 ReferenceBlackWhite
2146 CFARepeatPatternDim
2147 CFAPattern
2148 BatteryLevel
2149 Copyright
2150 ExposureTime
2151 FNumber
2152 IPTC/NAA
2153 ExifOffset
2154 InterColorProfile
2155 ExposureProgram
2156 SpectralSensitivity
2157 GPSInfo
2158 ISOSpeedRatings
2159 OECF
2160 ExifVersion
2161 DateTimeOriginal
2162 DateTimeDigitized
2163 ComponentsConfiguration
2164 CompressedBitsPerPixel
2165 ShutterSpeedValue
2166 ApertureValue
2167 BrightnessValue
2168 ExposureBiasValue
2169 MaxApertureValue
2170 SubjectDistance
2171 MeteringMode
2172 LightSource
2173 Flash
2174 FocalLength
2175 MakerNote
2176 UserComment
2177 SubSecTime
2178 SubSecTimeOriginal
2179 SubSecTimeDigitized
2180 FlashPixVersion
2181 ColorSpace
2182 ExifImageWidth
2183 ExifImageLength
2184 InteroperabilityOffset
2185 FlashEnergy
2186 SpatialFrequencyResponse
2187 FocalPlaneXResolution
2188 FocalPlaneYResolution
2189 FocalPlaneResolutionUnit
2190 SubjectLocation
2191 ExposureIndex
2192 SensingMethod
2193 FileSource
2194 SceneType
2195 JPEG specific information (from reading a JPEG file) may be ob‐
2197 tained like this:
2198 %[JPEG-<tag>]
2200 Where "<tag>" may be one of the following:
2202 * (all JPEG-related tags, in
2204 keyword=data format)
2205 Quality IJG JPEG "quality" estimate
2206 Colorspace JPEG colorspace numeric ID
2207 Colorspace-Name JPEG colorspace name
2208 Sampling-factors JPEG sampling factors
2209 Please note that JPEG has no notion of "quality" and that the
2211 quality metric used by, and estimated by the software is based
2212 on the quality metric established by IJG JPEG 6b. Other en‐
2213 coders (e.g. that used by Adobe Photoshop) use different encod‐
2214 ing metrics.
2215 Surround the format specification with quotation marks to pre‐
2217 vent your shell from misinterpreting any spaces and square
2218 brackets.
2219 -frame <width>x<height>+<outer bevel width>+<inner bevel width>
2221 surround the image with an ornamental border
2222 See -geometry for details about the geometry specification. The
2224 -frame option is not affected by the -gravity option.
2225 The color of the border is specified with the -mattecolor com‐
2227 mand line option.
2228 -frame include the X window frame in the imported image
2230 -fuzz <distance>{%}
2232 colors within this Euclidean distance are considered equal
2233 A number of algorithms search for a target color. By default the
2235 color must be exact. Use this option to match colors that are
2236 close (in Euclidean distance) to the target color in RGB 3D
2237 space. For example, if you want to automatically trim the edges
2238 of an image with -trim but the image was scanned and the target
2239 background color may differ by a small amount. This option can
2240 account for these differences.
2241 The distance can be in absolute intensity units or, by appending
2243 "%", as a percentage of the maximum possible intensity (255,
2244 65535, or 4294967295).
2245 -gamma <value>
2247 level of gamma correction
2248 The same color image displayed on two different workstations may
2250 look different due to differences in the display monitor. Use
2251 gamma correction to adjust for this color difference. Reasonable
2252 values extend from 0.8 to 2.3. Gamma less than 1.0 darkens the
2253 image and gamma greater than 1.0 lightens it. Large adjustments
2254 to image gamma may result in the loss of some image information
2255 if the pixel quantum size is only eight bits (quantum range 0 to
2256 255).
2257 You can apply separate gamma values to the red, green, and blue
2259 channels of the image with a gamma value list delimited with
2260 slashes (e.g., 1.7/2.3/1.2).
2261 Use +gamma value to set the image gamma level without actually
2263 adjusting the image pixels. This option is useful if the image
2264 is of a known gamma but not set as an image attribute (e.g. PNG
2265 images).
2266 -gaussian <radius>{x<sigma>}
2268 blur the image with a Gaussian operator
2269 Use the given radius and standard deviation (sigma).
2271 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
2273 Specify dimension, offset, and resize options.
2274 The -geometry option is used for a number of different purposes,
2276 depending on the utility it is used with.
2277 For the X11 commands ('animate', 'display', and 'import'), it
2279 specifies the preferred size and location of the Image window.
2280 By default, the window size is the image size and the location
2281 is chosen by you (or your window manager) when it is mapped.
2282 For the 'import', 'convert', 'mogrify' utility commands it may
2283 be used to specify the desired size when resizing an image. In
2284 this case, symbols representing resize options may be appended
2285 to the geometry string to influence how the resize request is
2286 treated.
2287 See later notes corresponding to usage by particular commands.
2289 The following notes apply to when -geometry is used to express a
2290 resize request, taking into account the current properties of
2291 the image.
2292 By default, the width and height are maximum values. That is,
2294 the image is expanded or contracted to fit the width and height
2295 value while maintaining the aspect ratio of the image.
2296 Append a ^ to the geometry so that the image aspect ratio is
2298 maintained when the image is resized, but the resulting width or
2299 height are treated as minimum values rather than maximum values.
2300 Append a ! (exclamation point) to the geometry to force the im‐
2302 age size to exactly the size you specify. For example, if you
2303 specify 640x480! the image width is set to 640 pixels and height
2304 to 480.
2305 If only the width is specified, without the trailing 'x', then
2307 height is set to width (e.g., -geometry 100 is the same as -ge‐
2308 ometry 100x100). If only the width is specified but with the
2309 trailing 'x', then width assumes the value and the height is
2310 chosen to maintain the aspect ratio of the image. Similarly, if
2311 only the height is specified prefixed by 'x' (e.g., -geometry
2312 x256), the width is chosen to maintain the aspect ratio.
2313 To specify a percentage width or height instead, append %. The
2315 image size is multiplied by the width and height percentages to
2316 obtain the final image dimensions. To increase the size of an
2317 image, use a value greater than 100 (e.g. 125%). To decrease an
2318 image's size, use a percentage less than 100.
2319 Use @ to specify the maximum area in pixels of an image.
2321 Use > to change the dimensions of the image only if its width or
2323 height exceeds the geometry specification. < resizes the image
2324 only if both of its dimensions are less than the geometry speci‐
2325 fication. For example, if you specify '640x480>' and the image
2326 size is 256x256, the image size does not change. However, if the
2327 image is 512x512 or 1024x1024, it is resized to 480x480. En‐
2328 close the geometry specification in quotation marks to prevent
2329 the < or > from being interpreted by your shell as a file redi‐
2330 rection.
2331 When used with animate and display, offsets are handled in the
2333 same manner as in X(1) and the -gravity option is not used. If
2334 the x is negative, the offset is measured leftward from the
2335 right edge of the screen to the right edge of the image being
2336 displayed. Similarly, negative y is measured between the bottom
2337 edges. The offsets are not affected by "%"; they are always
2338 measured in pixels.
2339 When used as a composite option, -geometry gives the dimensions
2341 of the image and its location with respect to the composite im‐
2342 age. If the -gravity option is present with NorthEast, East, or
2343 SouthEast gravity, the x represents the distance from the right
2344 edge of the image to the right edge of the composite image.
2345 Similarly, if the -gravity option is present with SouthWest,
2346 South, or SouthEast gravity, y is measured between the bottom
2347 edges. Accordingly, a positive offset will never point in the
2348 direction outside of the image. The offsets are not affected by
2349 "%"; they are always measured in pixels. To specify the dimen‐
2350 sions of the composite image, use the -resize option.
2351 When used as a convert, import or mogrify option, -geometry is
2353 synonymous with -resize and specifies the size of the output im‐
2354 age. The offsets, if present, are ignored.
2355 When used as a montage option, -geometry specifies the image
2357 size and border size for each tile; default is 256x256+0+0.
2358 Negative offsets (border dimensions) are meaningless. The
2359 -gravity option affects the placement of the image within the
2360 tile; the default gravity for this purpose is Center. If the
2361 "%" sign appears in the geometry specification, the tile size is
2362 the specified percentage of the original dimensions of the first
2363 tile. To specify the dimensions of the montage, use the -resize
2364 option.
2365 -gravity <type>
2367 direction primitive gravitates to when annotating the image.
2368 Choices are: NorthWest, North, NorthEast, West, Center, East,
2370 SouthWest, South, SouthEast.
2371 The direction you choose specifies where to position the text
2373 when annotating the image. For example Center gravity forces the
2374 text to be centered within the image. By default, the image
2375 gravity is NorthWest. See -draw for more details about graphic
2376 primitives. Only the text primitive is affected by the -gravity
2377 option.
2378 The -gravity option is also used in concert with the -geometry
2380 option and other options that take <geometry> as a parameter,
2381 such as the -crop option. See -geometry for details of how the
2382 -gravity option interacts with the <x> and <y> parameters of a
2383 geometry specification.
2384 When used as an option to composite, -gravity gives the direc‐
2386 tion that the image gravitates within the composite.
2387 When used as an option to montage, -gravity gives the direction
2389 that an image gravitates within a tile. The default gravity is
2390 Center for this purpose.
2391 -green-primary <x>,<y>
2393 green chromaticity primary point
2394 -hald-clut <clut>
2396 apply a Hald CLUT to the image
2397 A Hald CLUT ("Color Look-Up Table") is a special square color
2399 image which contains a look-up table for red, green, and blue.
2400 The size of the Hald CLUT image is determined by its order. The
2401 width (and height) of a Hald CLUT is the cube of the order. For
2402 example, a Hald CLUT of order 8 is 512x512 pixels (262,144 col‐
2403 ors) and of order 16 is 4096x4096 (16,777,216 colors). A spe‐
2404 cial CLUT is the identity CLUT which which causes no change to
2405 the input image. In order to use the Hald CLUT, one takes an
2406 identity CLUT and adjusts its colors in some way. The modified
2407 CLUT can then be used to transform any number of images in an
2408 identical way.
2409 GraphicsMagick contains a built-in identity CLUT generator via
2411 the IDENTITY coder. For example reading from the file name
2412 IDENTITY:8 returns an identity CLUT of order 8. Typical Hald
2413 CLUT identity images have an order of between 8 and 16. The de‐
2414 fault order for the IDENTITY CLUT generator is 8. Interpolation
2415 is used so it is not usually necessary for CLUT images to be
2416 very large. The PNG file format is ideal for storing Hald CLUT
2417 images because it compresses them very well.
2418 -help print usage instructions
2420 -highlight-color <color>
2422 pixel annotation color
2423 Specifies the color to use when annotating difference pixels.
2425 -highlight-style <style>
2427 pixel annotation style
2428 Specifies the pixel difference annotation style used to draw at‐
2430 tention to changed pixels. May be one of Assign, Threshold,
2431 Tint, or XOR; where Assign replaces the pixel with the highlight
2432 color (see -highlight-color), Threshold replaces the pixel with
2433 black or white based on the difference in intensity, Tint alpha
2434 tints the pixel with the highlight color, and XOR does an XOR
2435 between the pixel and the highlight color.
2436 -iconGeometry <geometry>
2438 specify the icon geometry
2439 Offsets, if present in the geometry specification, are handled
2441 in the same manner as the -geometry option, using X11 style to
2442 handle negative offsets.
2443 -iconic
2445 iconic animation
2446 -immutable
2448 make image immutable
2449 -implode <factor>
2451 implode image pixels about the center
2452 -intent <type>
2454 use this type of rendering intent when managing the image color
2455 Use this option to affect the the color management operation of
2457 an image (see -profile). Choose from these intents: Absolute,
2458 Perceptual, Relative, Saturation.
2459 The default intent is undefined.
2461 -interlace <type>
2463 the type of interlacing scheme
2464 Choices are: None, Line, Plane, or Partition. The default is
2466 None.
2467 This option is used to specify the type of interlacing scheme
2469 for raw image formats such as RGB or YUV. None means do not in‐
2470 terlace (RGBRGBRGBRGBRGBRGB...),
2471 Line uses scanline interlacing
2473 (RRR...GGG...BBB...RRR...GGG...BBB...), and Plane uses plane in‐
2474 terlacing (RRRRRR...GGGGGG...BBBBBB...).
2475 Partition is like plane except the different planes are saved to
2477 individual files (e.g. image.R, image.G, and image.B).
2478 Use Line to create an interlaced PNG or GIF or progressive JPEG
2480 image.
2481 -label <name>
2483 assign a label to an image
2484 Use this option to assign a specific label to the image, when
2486 writing to an image format that supports labels, such as TIFF,
2487 PNG, MIFF, or PostScript. You can include the the image file‐
2488 name, type, width, height, or other image attribute by embedding
2489 special format character. A label is not drawn on the image,
2490 but is embedded in the image datastream via a "Label" tag or
2491 similar mechanism. If you want the label to be visible on the
2492 image itself, use the -draw option. See -comment for details.
2493 For example,
2495 -label "%m:%f %wx%h"
2497 produces an image label of MIFF:bird.miff 512x480 for an image
2499 titled bird.miff and whose width is 512 and height is 480.
2500 If the first character of string is @, the image label is read
2502 from a file titled by the remaining characters in the string.
2503 Please note that if the string comes from an untrusted source
2504 that it should be sanitized before use since otherwise the con‐
2505 tent of an arbitrary readable file might be incorporated into
2506 the image label (a security risk).
2507 If the -label option appears multiple times, only the last label
2509 is stored.
2510 In PNG images, the label is stored in a tEXt or zTXt chunk with
2512 the keyword "label".
2513 When converting to PostScript, use this option to specify a
2515 header string to print above the image. Specify the label font
2516 with -font.
2517 When creating a montage, by default the label associated with an
2519 image is displayed with the corresponding tile in the montage.
2520 Use the +label option to suppress this behavior.
2521 -lat <width>x<height>{+-}<offset>{%}
2525 perform local adaptive thresholding
2526 Perform local adaptive thresholding using the specified width,
2528 height, and offset. The offset is a distance in sample space
2529 from the mean, as an absolute integer ranging from 0 to the max‐
2530 imum sample value or as a percentage. If the percent option is
2531 supplied, then the offset is computed as a percentage of the
2532 quantum range. It is strongly recommended to use the percent
2533 option so that results are not sensitive to pixel quantum depth.
2534 For example,
2536 -colorspace gray -lat "10x10-5%"
2538 will help clarify a scanned grayscale or color document, produc‐
2540 ing a bi-level equivalent.
2541 -level <black_point>{,<gamma>}{,<white_point>}{%}
2543 adjust the level of image contrast
2544 Give one, two or three values delimited with commas: black-
2546 point, gamma, white-point (e.g. 10,1.0,250 or 2%,0.5,98%). The
2547 black and white points range from 0 to MaxRGB or from 0 to 100%;
2548 if the white point is omitted it is set to MaxRGB-black_point.
2549 If a "%" sign is present anywhere in the string, the black and
2550 white points are percentages of MaxRGB. Gamma is an exponent
2551 that ranges from 0.1 to 10.; if it is omitted, the default of
2552 1.0 (no gamma correction) is assumed. This interface works simi‐
2553 lar to Photoshop's "Image->Adjustments->Levels..." "Input Lev‐
2554 els" interface.
2555 -limit <type> <value>
2557 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
2558 resource limit
2559 By default, resource limits are estimated based on the available
2561 resources and capabilities of the system. The resource limits
2562 are Disk, maximum total disk space consumed; File, maximum num‐
2563 ber of file descriptors allowed to be open at once; Map, maximum
2564 total number of file bytes which may be memory mapped; Memory,
2565 maximum total number of bytes of heap memory used for image
2566 storage; Pixels, maximum absolute image size (per image); Width,
2567 maximum image pixels width; Height, maximum image pixels height;
2568 Read, maximum number of uncompressed bytes to read; and Threads,
2569 the maximum number of worker threads to use per OpenMP thread
2570 team.
2571 The Disk and Map resource limits are used to decide if (for a
2573 given image) the decoded image ("pixel cache") should be stored
2574 in heap memory (RAM), in a memory-mapped disk file, or in a disk
2575 file accessed via read/write I/O.
2576 The number of total pixels in one image (Pixels), and/or the
2578 width/height (Width/Height), may be limited in order to force
2579 the reading, or creation of images larger than the limit (in
2580 pixels) to intentionally fail. The disk limit (Disk) establishes
2581 an overall limit since using the disk is the means of last re‐
2582 sort. When the disk limit has been reached, no more images may
2583 be read.
2584 The amount of uncompressed data read when reading one image may
2586 be limited by the Read limit. Reading the image fails when the
2587 limit is hit. This option is useful if the data is read from a
2588 stream (pipe) or from a compressed file such as a gzipped file.
2589 Some files are very compressable and so a small compressed file
2590 can decompress to a huge amount of data. This option also de‐
2591 fends against files which produce seemingly endless loops while
2592 decoding by seeking backwards in the file.
2593 The value argument is an absolute value, but may have standard
2595 binary suffix characters applied ('K', 'M', 'G', 'T', 'P', 'E')
2596 to apply a scaling to the value (based on a multiplier of 1024).
2597 Any additional characters are ignored. For example, '-limit Pix‐
2598 els 10MP' limits the maximum image size to 10 megapixels and
2599 '-limit memory 32MB -limit map 64MB' limits memory and memory
2600 mapped files to 32 megabytes and 64 megabytes respectively.
2601 Resource limits may also be set using environment variables. The
2603 environment variables MAGICK_LIMIT_DISK, MAGICK_LIMIT_FILES,
2604 MAGICK_LIMIT_MAP, MAGICK_LIMIT_MEMORY, MAGICK_LIMIT_PIXELS, MAG‐
2605 ICK_LIMIT_WIDTH, MAGICK_LIMIT_HEIGHT. MAGICK_LIMIT_READ, and
2606 OMP_NUM_THREADS may be used to set the limits for disk space,
2607 open files, memory mapped size, heap memory, per-image pixels,
2608 image width, image height, and threads respectively.
2609 Use the option -list resource list the current limits.
2611 -linewidth
2613 the line width for subsequent draw operations
2614 -list <type>
2616 the type of list
2617 Choices are: Color, Delegate, Format, Magic, Module, Resource,
2619 or Type. The Module option is only available if GraphicsMagick
2620 was built to support loadable modules.
2621 This option lists information about the GraphicsMagick configu‐
2623 ration.
2624 -log <string>
2626 Specify format for debug log
2627 This option specifies the format for the log printed when the
2629 -debug option is active.
2630 You can display the following components by embedding special
2632 format characters:
2633 %d domain
2635 %e event
2636 %f function
2637 %l line
2638 %m module
2639 %p process ID
2640 %r real CPU time
2641 %t wall clock time
2642 %u user CPU time
2643 %% percent sign
2644 \n newline
2645 \r carriage return
2646 For example:
2648 gm convert -debug coders -log "%u %m:%l %e" in.gif out.png
2650 The default behavior is to print all of the components.
2652 -loop <iterations>
2654 add Netscape loop extension to your GIF animation
2655 A value other than zero forces the animation to repeat itself up
2657 to iterations times.
2658 -magnify
2660 magnify the image
2661 The image size is doubled using linear interpolation.
2663 -magnify <factor>
2665 magnify the image
2666 The displayed image is magnified by factor.
2668 -map <filename>
2670 choose a particular set of colors from this image
2671 [convert or mogrify]
2673 By default, color reduction chooses an optimal set of colors
2675 that best represent the original image. Alternatively, you can
2676 choose a particular set of colors from an image file with this
2677 option.
2678 Use +map to reduce all images in the image sequence that follows
2680 to a single optimal set of colors that best represent all the
2681 images. The sequence of images is terminated by the appearance
2682 of any option. If the +map option appears after all of the in‐
2683 put images, all images are mapped.
2684 -map <type>
2686 display image using this type.
2687 [animate or display]
2689 Choose from these Standard Colormap types:
2691 best
2693 default
2694 gray
2695 red
2696 green
2697 blue
2698 The X server must support the Standard Colormap you choose, oth‐
2700 erwise an error occurs. Use list as the type and display
2701 searches the list of colormap types in top-to-bottom order until
2702 one is located. See xstdcmap(1) for one way of creating Standard
2703 Colormaps.
2704 -mask <filename>
2706 Specify a clipping mask
2707 The image read from the file is used as a clipping mask. It
2709 must have the same dimensions as the image being masked.
2710 If the mask image contains an opacity channel, the opacity of
2712 each pixel is used to define the mask. Otherwise, the intensity
2713 (gray level) of each pixel is used. Unmasked (black) pixels are
2714 modified while masked pixels (not black) are protected from al‐
2715 teration.
2716 Use +mask to remove the clipping mask.
2718 It is not necessary to use -clip to activate the mask; -clip is
2720 implied by -mask.
2721 -matte store matte channel if the image has one
2723 If the image does not have a matte channel, create an opaque
2725 one.
2726 Use +matte to ignore the matte channel (treats it as opaque) and
2728 to avoid writing a matte channel in the output file.
2729 For the compare command, -matte will add an opaque matte channel
2731 to images if they do not already have a matte channel, and matte
2732 will be enabled for both images. Likewise, if +matte is used,
2733 the matte channel is disabled for both images. This makes it
2734 easier to compare images regardless of if they already have a
2735 matte channel.
2736 -mattecolor <color>
2738 specify the color to be used with the -frame option
2739 The color is specified using the format described under the
2741 -fill option.
2742 -maximum-error <limit>
2744 specifies the maximum amount of total image error
2745 Specifies the maximum amount of total image error (based on com‐
2747 parison using a specified metric) before an error ("image dif‐
2748 ference exceeds limit") is reported. The error is reported via
2749 a non-zero command execution return status.
2750 -median <radius>
2752 apply a median filter to the image
2753 -metric <metric>
2755 comparison metric (MAE, MSE, PAE, PSNR, RMSE)
2756 -minify <factor>
2758 minify the image
2759 The image size is halved using linear interpolation.
2761 -mode <value>
2763 mode of operation
2764 The available montage modes are frame to place the images in a
2766 rectangular grid while adding a decorative frame with drop‐
2767 shadow, unframe to place undecorated images in a rectangular
2768 grid, and concatenate to pack the images closely together with‐
2769 out any well-defined grid or decoration.
2770 -modulate brightness[,saturation[,hue]]
2772 vary the brightness, saturation, and hue of an image
2773 Specify the percent change in brightness, color saturation, and
2775 hue separated by commas. Default argument values are 100 per‐
2776 cent, resulting in no change. For example, to increase the color
2777 brightness by 20% and decrease the color saturation by 10% and
2778 leave the hue unchanged, use: -modulate 120,90.
2779 Hue is the percentage of absolute rotation from the current po‐
2781 sition. For example 50 results in a counter-clockwise rotation
2782 of 90 degrees, 150 results in a clockwise rotation of 90 de‐
2783 grees, with 0 and 200 both resulting in a rotation of 180 de‐
2784 grees.
2785 -monitor
2787 show progress indication
2788 A simple command-line progress indication is shown while the
2790 command is running. The process indication shows the operation
2791 currently being performed and the percent completed. Commands
2792 using X11 may replace the command line progress indication with
2793 a graphical one once an image has been displayed.
2794 -monochrome
2796 transform the image to black and white
2797 -morph <frames>
2799 morphs an image sequence
2800 Both the image pixels and size are linearly interpolated to give
2802 the appearance of a meta-morphosis from one image to the next.
2803 The sequence of images is terminated by the appearance of any
2805 option. If the -morph option appears after all of the input im‐
2806 ages, all images are morphed.
2807 -mosaic
2809 create a mosaic from an image or an image sequence
2810 The -mosaic option provides a flexible way to composite one or
2812 more images onto a solid-color canvas image. It works similar to
2813 -flatten except that a base canvas image is automatically cre‐
2814 ated with a suitable size given the image size, page dimensions,
2815 and page offsets of images to be composited. The color of the
2816 base canvas image may be set via the -background option. The
2817 default canvas color is 'white', but 'black' or 'transparent'
2818 may be more suitable depending on the composition algorithm re‐
2819 quested.
2820 The -compose option may be used to specify the composition algo‐
2822 rithm to use when compositing the subsequent image on the base
2823 canvas.
2824 The -page option can be used to establish the dimensions of the
2826 mosaic and to position the subsequent image within the mosaic.
2827 If the -page argument does not specify width and height, then
2828 the canvas dimensions are evaluated based on the image sizes and
2829 offsets.
2830 The sequence of images is terminated by the appearance of any
2832 option. If the -mosaic option appears after all of the input
2833 images, all images are included in the mosaic.
2834 The following is an example of composing an image based on red,
2836 green, and blue layers extracted from a sequence of images and
2837 pasted on the canvas image at specified offsets:
2838 gm convert -background black \
2840 -compose CopyRed -page +0-100 red.png \
2841 -compose CopyGreen -page +0+40 green.png \
2842 -compose CopyBlue -page +0+180 blue.png \
2843 -mosaic output.png
2844 -motion-blur <radius>{x<sigma>}{+angle}
2846 Simulate motion blur
2847 Simulate motion blur by convolving the image with a Gaussian op‐
2849 erator of the given radius and standard deviation (sigma). For
2850 reasonable results, radius should be larger than sigma. If ra‐
2851 dius is zero, then a suitable radius is automatically selected
2852 based on sigma. The angle specifies the angle that the object is
2853 coming from (side which is blurred).
2854 -name name an image
2856 -negate
2858 replace every pixel with its complementary color
2859 The red, green, and blue intensities of an image are negated.
2861 White becomes black, yellow becomes blue, etc. Use +negate to
2862 only negate the grayscale pixels of the image.
2863 -noise <radius|type>
2865 add or reduce noise in an image
2866 The principal function of noise peak elimination filter is to
2868 smooth the objects within an image without losing edge informa‐
2869 tion and without creating undesired structures. The central idea
2870 of the algorithm is to replace a pixel with its next neighbor in
2871 value within a pixel window, if this pixel has been found to be
2872 noise. A pixel is defined as noise if and only if this pixel is
2873 a maximum or minimum within the pixel window.
2874 Use radius to specify the width of the neighborhood.
2876 Use +noise followed by a noise type to add noise to an image.
2878 The noise added modulates the existing image pixels. Choose from
2879 these noise types:
2880 Uniform
2882 Gaussian
2883 Multiplicative
2884 Impulse
2885 Laplacian
2886 Poisson
2887 Random (uniform distribution)
2888 -noop NOOP (no option)
2890 The -noop option can be used to terminate a group of images and
2892 reset all options to their default values, when no other option
2893 is desired.
2894 -normalize
2896 transform image to span the full range of color values
2897 This is a contrast enhancement technique based on the image his‐
2899 togram.
2900 When computing the contrast enhancement values, the histogram
2902 edges are truncated so that the majority of the image pixels are
2903 considered in the constrast enhancement, and outliers (e.g. ran‐
2904 dom noise or minute details) are ignored. The default is that
2905 0.1 percent of the histogram entries are ignored. The percent‐
2906 age of the histogram to ignore may be specified by using the
2907 -set option with the histogram-threshold parameter similar to
2908 -set histogram-threshold 0.01 to specify 0.01 percent. Use 0
2909 percent to use the entire histogram, with possibly diminished
2910 contrast enhancement.
2911 -opaque <color>
2913 change this color to the pen color within the image
2914 The color is specified using the format described under the
2916 -fill option. The color is replaced if it is identical to the
2917 target color, or close enough to the target color in a 3D space
2918 as defined by the Euclidean distance specified by -fuzz.
2919 See -fill and -fuzz for more details.
2921 -operator channel operator rvalue[%]
2923 apply a mathematical, bitwise, or value operator to an image
2924 channel
2925 Apply a low-level mathematical, bitwise, or value operator to a
2927 selected image channel or all image channels. Operations which
2928 result in negative results are reset to zero, and operations
2929 which overflow the available range are reset to the maximum pos‐
2930 sible value.
2931 Select a channel from: Red, Green, Blue, Opacity, Matte, Cyan,
2933 Magenta, Yellow, Black, All, or Gray. All only modifies the
2934 color channels and does not modify the Opacity channel. Except
2935 for the threshold operators, All operates on each channel inde‐
2936 pendently so that operations are on a per-channel basis.
2937 Gray treats the color channels as a grayscale intensity and per‐
2939 forms the requested operation on the equivalent pixel intensity
2940 so the result is a gray image. Select an operator from Add,
2941 And, Assign, Depth, Divide, Gamma, Negate, LShift, Log, Max,
2942 Min, Multiply, Or, Pow, RShift, Subtract, Threshold, Threshold-
2943 White, Threshold-White-Negate, Threshold-Black, Threshold-Black-
2944 Negate, Xor, Noise-Gaussian, Noise-Impulse, Noise-Laplacian,
2945 Noise-Multiplicative, Noise-Poisson, Noise-Random, and Noise-
2946 Uniform.
2947 Rvalue may be any floating point or integer value. Normally
2949 rvalue will be in the range of 0 to MaxRGB, where MaxRGB is the
2950 largest quantum value supported by the GraphicsMagick build
2951 (255, 65535, or 4294967295) but values outside this range are
2952 useful for some arithmetic operations. Arguments to logical or
2953 bit-wise operations are rounded to a positive integral value
2954 prior to use. If a percent (%) symbol is appended to the argu‐
2955 ment, then the argument has a range of 0 to 100 percent.
2956 The following is a description of the operators:
2958 Add
2961 Result is rvalue added to channel value.
2963 And
2965 Result is the logical AND of rvalue with channel value.
2967 Assign
2969 Result is rvalue.
2971 Depth
2973 Result is channel value adjusted so that it may be (ap‐
2975 proximately) stored in the specified number of bits with‐
2976 out additional loss.
2977 Divide
2979 Result is channel value divided by rvalue.
2981 Gamma
2983 Result is channel value gamma adjusted by rvalue.
2985 LShift
2987 Result is channel value bitwise left shifted by rvalue
2989 bits.
2990 Log
2992 Result is computed as log(value*rvalue+1)/log(rvalue+1).
2994 Max
2996 Result is assigned to rvalue if rvalue is greater than
2998 value.
2999 Min
3001 Result is assigned to rvalue if rvalue is less than value.
3003 Multiply
3005 Result is channel value multiplied by rvalue.
3007 Negate
3009 Result is inverse of channel value (like a film negative).
3011 An rvalue must be supplied but is currently not used. In‐
3012 verting the image twice results in the original image.
3013 Or
3015 Result is the logical OR of rvalue with channel value.
3017 Pow
3019 Result is computed as pow(value,rvalue). Similar to Gamma
3021 except that rvalue is not inverted.
3022 RShift
3024 Result is channel value bitwise right shifted by rvalue
3026 bits.
3027 Subtract
3029 Result is channel value minus rvalue.
3031 Threshold
3033 Result is maximum (white) if channel value is greater than
3035 rvalue, or minimum (black) if it is less than or equal to
3036 rvalue. If all channels are specified, then thresholding
3037 is done based on computed pixel intensity.
3038 Threshold-white
3040 Result is maximum (white) if channel value is greater than
3042 rvalue and is unchanged if it is less than or equal to
3043 rvalue. This can be used to remove apparent noise from the
3044 bright parts of an image. If all channels are specified,
3045 then thresholding is done based on computed pixel inten‐
3046 sity.
3047 Threshold-White-Negate
3049 Result is set to black if channel value is greater than
3051 rvalue and is unchanged if it is less than or equal to
3052 rvalue. If all channels are specified, then thresholding
3053 is done based on computed pixel intensity.
3054 Threshold-black
3056 Result is minimum (black) if channel value is less than
3058 than rvalue and is unchanged if it is greater than or
3059 equal to rvalue. This can be used to remove apparent noise
3060 from the dark parts of an image. If all channels are spec‐
3061 ified, then thresholding is done based on computed pixel
3062 intensity.
3063 Threshold-Black-Negate
3065 Result is set to white if channel value is less than than
3067 rvalue and is unchanged if it is greater than or equal to
3068 rvalue. If all channels are specified, then thresholding
3069 is done based on computed pixel intensity.
3070 Xor
3072 Result is the logical XOR of rvalue with channel value. An
3074 interesting property of XOR is that performing the same
3075 operation twice results in the original value.
3076 Noise-Gaussian
3078 Result is the current channel value modulated with gauss‐
3080 ian noise according to the intensity specified by rvalue.
3081 Noise-Impulse
3083 Result is the current channel value modulated with impulse
3085 noise according to the intensity specified by rvalue.
3086 Noise-Laplacian
3088 Result is the current channel value modulated with lapla‐
3090 cian noise according to the intensity specified by rvalue.
3091 Noise-Multiplicative
3093 Result is the current channel value modulated with multi‐
3095 plicative gaussian noise according to the intensity speci‐
3096 fied by rvalue.
3097 Noise-Poisson
3099 Result is the current channel value modulated with poisson
3101 noise according to the intensity specified by rvalue.
3102 Noise-Random
3104 Result is the current channel value modulated with random
3106 (uniform distribution) noise according to the intensity
3107 specified by rvalue. The initial noise intensity
3108 (rvalue=1.0) is the range of one pixel quantum span.
3109 Noise-Uniform
3111 Result is the channel value with uniform noise applied ac‐
3113 cording to the intensity specified by rvalue.
3114 As an example, the Assign operator assigns a fixed value to a
3119 channel. For example, this command sets the red channel to the
3120 mid-range value:
3121 gm convert in.bmp -operator red assign "50%" out.bmp
3123 The following applies 50% thresholding to the image and returns
3125 a gray image:
3126 gm convert in.bmp -operator gray threshold "50%" out.bmp
3128 -ordered-dither <channeltype> <NxN>
3130 ordered dither the image
3131 The channel or channels specified in the channeltype argument
3133 are reduced to binary, using an ordered dither method. The
3134 choices for channeltype are All, Intensity, Red, Green, Blue,
3135 Cyan, Magenta, Yellow, Black, and Opacity
3136 When channeltype is "All", the color samples are dithered into a
3138 gray level and then that gray level is stored in the three color
3139 channels. Separately, the opacity channel is dithered into a
3140 bilevel opacity value which is stored in the opacity channel.
3141 When channeltype is "Intensity", only the color samples are
3143 dithered. When channeltype is "opacity" or "matte", only the
3144 opacity channel is dithered. When a color channel is specified,
3145 only that channel is dithered.
3146 The choices for N are 2 through 7. The image is divided into NxN
3148 pixel tiles. In each tile, some or all pixels are turned to
3149 white depending on their intensity. For each N, (N**2)+1 levels
3150 of gray can be represented. For N == 2, 3, or 4, the pixels are
3151 turned to white in an order that maximizes dispersion (i.e., re‐
3152 duces granularity), while for N == 5, 6, and 7, they are turned
3153 to white in an order that creates a roughly circular black blob
3154 in the middle of each tile. An attractive "half-tone" looking
3155 image can be obtained by first rotating the image 45 degrees,
3156 performing a 5x5 ordered-dither operation, then rotating it back
3157 to the original orientation and cropping to the original image
3158 dimensions. If the original image is gamma-encoded, it is ad‐
3159 viseable to convert it to linear intensity first, e.g., with the
3160 "-gamma 0.45455" option.
3161 -output-directory <directory>
3163 output files to directory
3164 Use -output-directory to specify a directory under which to
3166 write the output files. Normally mogrify overwrites the input
3167 files, but with this option the output files may be written to a
3168 different directory tree so that the input files are preserved.
3169 The algorithm used preserves all of the input path specification
3170 in the output path so that the user-specified input path (in‐
3171 cluding any sub-directory part) is appended to the output path.
3172 If the input file lacks an extension, then a suitable extension
3173 is automatically added to the output file. The user is respon‐
3174 sible for creating the output directory specified as an argu‐
3175 ment, but subdirectories will be created as needed if the -cre‐
3176 ate-directories option is supplied. This option may be used to
3177 apply transformations on files from one directory and write the
3178 transformed files to a different directory. In conjunction with
3179 -create-directories, this option is designed to support trans‐
3180 forming whole directory trees of files provided that the rela‐
3181 tive path of the input file is included as part the list of
3182 filenames.
3183 -orient <orientation>
3185 Set the image orientation attribute
3186 Sets the image orientation attribute. The image orientation at‐
3188 tribute is compatible with the TIFF orientation tag (and the
3189 EXIF orientation tag). Accepted values are undefined, TopLeft,
3190 TopRight, BottomRight, BottomLeft, LeftTop, RightTop, RightBot‐
3191 tom, LeftBottom, and hyphenated versions thereof (e.g. left-bot‐
3192 tom). Please note that GraphicsMagick does not include an EXIF
3193 editor so if an EXIF profile is written to the output image, the
3194 value in the EXIF profile might not match the image. It is pos‐
3195 sible for an image file to indicate its orientation in several
3196 different ways simultaneously.
3197 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
3199 size and location of an image canvas
3200 Use this option to specify the dimensions of the PostScript page
3202 in dots per inch or a TEXT page in pixels. The choices for a
3203 PostScript page are:
3204 11x17 792 1224
3206 Ledger 1224 792
3207 Legal 612 1008
3208 Letter 612 792
3209 LetterSmall 612 792
3210 ArchE 2592 3456
3211 ArchD 1728 2592
3212 ArchC 1296 1728
3213 ArchB 864 1296
3214 ArchA 648 864
3215 A0 2380 3368
3216 A1 1684 2380
3217 A2 1190 1684
3218 A3 842 1190
3219 A4 595 842
3220 A4Small 595 842
3221 A5 421 595
3222 A6 297 421
3223 A7 210 297
3224 A8 148 210
3225 A9 105 148
3226 A10 74 105
3227 B0 2836 4008
3228 B1 2004 2836
3229 B2 1418 2004
3230 B3 1002 1418
3231 B4 709 1002
3232 B5 501 709
3233 C0 2600 3677
3234 C1 1837 2600
3235 C2 1298 1837
3236 C3 918 1298
3237 C4 649 918
3238 C5 459 649
3239 C6 323 459
3240 Flsa 612 936
3241 Flse 612 936
3242 HalfLetter 396 612
3243 For convenience you can specify the page size by media (e.g. A4,
3245 Ledger, etc.). Otherwise, -page behaves much like -geometry
3246 (e.g. -page letter+43+43>).
3247 This option is also used to place subimages when writing to a
3249 multi-image format that supports offsets, such as GIF89 and MNG.
3250 When used for this purpose the offsets are always measured from
3251 the top left corner of the canvas and are not affected by the
3252 -gravity option. To position a GIF or MNG image, use
3253 -page{+-}<x>{+-}<y> (e.g. -page +100+200). When writing to a
3254 MNG file, a -page option appearing ahead of the first image in
3255 the sequence with nonzero width and height defines the width and
3256 height values that are written in the MHDR chunk. Otherwise,
3257 the MNG width and height are computed from the bounding box that
3258 contains all images in the sequence. When writing a GIF89 file,
3259 only the bounding box method is used to determine its dimen‐
3260 sions.
3261 For a PostScript page, the image is sized as in -geometry and
3263 positioned relative to the lower left hand corner of the page by
3264 {+-}<xoffset>{+-}<y offset>. Use -page 612x792>, for example, to
3265 center the image within the page. If the image size exceeds the
3266 PostScript page, it is reduced to fit the page. The default
3267 gravity for the -page option is NorthWest, i.e., positive x and
3268 y offset are measured rightward and downward from the top left
3269 corner of the page, unless the -gravity option is present with a
3270 value other than NorthWest.
3271 The default page dimensions for a TEXT image is 612x792.
3273 This option is used in concert with -density.
3275 Use +page to remove the page settings for an image.
3277 -paint <radius>
3279 simulate an oil painting
3280 Each pixel is replaced by the most frequent color in a circular
3282 neighborhood whose width is specified with radius.
3283 -pause <seconds>
3285 pause between animation loops [animate]
3286 Pause for the specified number of seconds before repeating the
3288 animation.
3289 -pause <seconds>
3291 pause between snapshots [import]
3292 Pause for the specified number of seconds before taking the next
3294 snapshot.
3295 -pen <color>
3297 (This option has been replaced by the -fill option)
3298 -ping efficiently determine image characteristics
3300 Use this option to disable reading the image pixels so that im‐
3302 age characteristics such as the image dimensions may be obtained
3303 very quickly. For identify, use +ping to force reading the image
3304 pixels so that the pixel read rate may be included in the dis‐
3305 played information.
3306 -pointsize <value>
3308 pointsize of the PostScript, X11, or TrueType font
3309 -preview <type>
3311 image preview type
3312 Use this option to affect the preview operation of an image
3314 (e.g. convert file.png -preview Gamma Preview:gamma.png).
3315 Choose from these previews:
3316 Rotate
3318 Shear
3319 Roll
3320 Hue
3321 Saturation
3322 Brightness
3323 Gamma
3324 Spiff
3325 Dull
3326 Grayscale
3327 Quantize
3328 Despeckle
3329 ReduceNoise
3330 AddNoise
3331 Sharpen
3332 Blur
3333 Threshold
3334 EdgeDetect
3335 Spread
3336 Shade
3337 Raise
3338 Segment
3339 Solarize
3340 Swirl
3341 Implode
3342 Wave
3343 OilPaint
3344 CharcoalDrawing
3345 JPEG
3346 The default preview is JPEG.
3348 -process <command>
3350 process a sequence of images using a process module
3351 The command argument has the form module=arg1,arg2,arg3,...,argN
3353 where module is the name of the module to invoke (e.g. "Ana‐
3354 lyze") and arg1,arg2,arg3,...,argN are an arbitrary number of
3355 arguments to pass to the process module. The sequence of images
3356 is terminated by the appearance of any option.
3357 If the -process option appears after all of the input images,
3359 all images are processed.
3360 For example:
3362 gm convert logo: -process Analyze= \
3364 -format "%[BrightnessMean],%[BrightnessStddev]" info:-
3365 51952,23294
3366 -profile <filename>
3369 add ICM, IPTC, or generic profile to image
3370 -profile filename adds an ICM (ICC color management), IPTC
3372 (newswire information), or a generic (including Exif) profile to the image
3373 Use +profile icm, +profile iptc, or
3375 +profile profile_name to remove the respective profile.
3376 Multiple profiles may be listed, separated by commas. Profiles may be
3377 excluded from subsequent listed matches by preceding their name with
3378 an exclamation point. For example, +profile '!icm,*' strips
3379 all profiles except for the ICM profile. Use identify
3380 -verbose to find out what profiles are in the image file. Use
3381 +profile "*" to remove all profiles.
3382 Writing the image to a format that does not support profiles will
3383 of course also cause all profiles to be removed. The JPEG and PNG
3384 formats will store any profiles that have been read and not removed.
3385 In JPEG they are stored in APP1 markers, and in PNG they are stored
3386 as hex-coded binary in compressed zTXt chunks, except for the iCC
3387 chunk which is stored in the iCCP chunk.
3388 To extract a profile, the -profile option is not used. Instead,
3390 simply write the file to an image
3391 format such as APP1, 8BIM, ICM, or IPTC.
3392 For example, to extract the Exif data (which is stored in JPEG files
3394 in the APP1 profile), use
3395 gm convert cockatoo.jpg exifdata.app1
3398 Note that GraphicsMagick does not attempt to update any profile
3399 to reflect changes made to the image, e.g., rotation from por‐
3400 trait to landscape orientation, so it is possible that the pre‐
3401 served profile may contain invalid data.
3402 -preserve-timestamp
3404 preserve the original timestamps of the file
3405 Use this option to preserve the original modification and access
3407 timestamps of the file, even if it has been modified.
3408 +progress
3410 disable progress monitor and busy cursor
3411 By default, when an image is displayed, a progress monitor bar
3413 is shown in the top left corner of an existing image display
3414 window, and the current cursor is replaced with an hourglass
3415 cursor. Use +progress to disable the progress monitor and busy
3416 cursor during display operations. While the progress monitor is
3417 disabled for all operations, the busy cursor continues to be en‐
3418 abled for non-display operations such as image processing. This
3419 option is useful for non-interactive display operations, or when
3420 a "clean" look is desired.
3421 -quality <value>
3423 JPEG/MIFF/PNG/TIFF compression level
3424 For the JPEG and MPEG image formats, quality is 0 (lowest image
3425 quality and highest compression) to 100 (best quality but least
3426 effective compression). The default quality is 75. Use the
3427 -sampling-factor option to specify the factors for chroma down‐
3428 sampling. To use the same quality value as that found by the
3429 JPEG decoder, use the -define jpeg:preserve-settings flag.
3430 For the MIFF image format, and the TIFF format while using ZIP
3432 compression, quality/10 is the zlib compression level, which is
3433 0 (worst but fastest compression) to 9 (best but slowest). It
3434 has no effect on the image appearance, since the compression is
3435 always lossless.
3436 For the JPEG-2000 image format, quality is mapped using a non-
3438 linear equation to the compression ratio required by the Jasper
3439 library. This non-linear equation is intended to loosely approx‐
3440 imate the quality provided by the JPEG v1 format. The default
3441 quality value 75 results in a request for 16:1 compression. The
3442 quality value 100 results in a request for non-lossy compres‐
3443 sion.
3444 For the MNG and PNG image formats, the quality value sets the
3446 zlib compression level (quality / 10) and filter-type (quality %
3447 10). Compression levels range from 0 (fastest compression) to
3448 100 (best but slowest). For compression level 0, the Huffman-
3449 only strategy is used, which is fastest but not necessarily the
3450 worst compression.
3451 If filter-type is 4 or less, the specified filter-type is used
3453 for all scanlines:
3454 0: none
3456 1: sub
3457 2: up
3458 3: average
3459 4: Paeth
3460 If filter-type is 5, adaptive filtering is used when quality is
3462 greater than 50 and the image does not have a color map, other‐
3463 wise no filtering is used.
3464 If filter-type is 6, adaptive filtering with minimum-sum-of-ab‐
3466 solute-values is used.
3467 Only if the output is MNG, if filter-type is 7, the LOCO color
3469 transformation and adaptive filtering with minimum-sum-of-abso‐
3470 lute-values are used.
3471 The default is quality is 75, which means nearly the best com‐
3473 pression with adaptive filtering. The quality setting has no
3474 effect on the appearance of PNG and MNG images, since the com‐
3475 pression is always lossless.
3476 For further information, see the PNG specification.
3478 When writing a JNG image with transparency, two quality values
3480 are required, one for the main image and one for the grayscale
3481 image that conveys the opacity channel. These are written as a
3482 single integer equal to the main image quality plus 1000 times
3483 the opacity quality. For example, if you want to use quality 75
3484 for the main image and quality 90 to compress the opacity data,
3485 use -quality 90075.
3486 For the PNM family of formats (PNM, PGM, and PPM) specify a
3488 quality factor of zero in order to obtain the ASCII variant of
3489 the format. Note that -compress none used to be used to trigger
3490 ASCII output but provided the opposite result of what was ex‐
3491 pected as compared with other formats.
3492 For the TIFF format, the JPEG, WebP, Zip, and Zstd compression
3494 algorithms are influenced by the quality value. JPEG and WebP
3495 provide lossy compression so higher quality produces a larger
3496 file with less degradation. The Zip and Zstd compression algo‐
3497 rithms (and WebP in lossless mode) are lossless and for these
3498 algorithms a higher ´quality' means to work harder to produce a
3499 smaller file, but with no difference in image quality.
3500 -raise <width>x<height>
3502 lighten or darken image edges
3503 This will create a 3-D effect. See -geometry for details details
3505 about the geometry specification. Offsets are not used.
3506 Use -raise to create a raised effect, otherwise use +raise.
3508 -random-threshold <channeltype> <LOWxHIGH>
3510 random threshold the image
3511 The channel or channels specified in the <channeltype> argument
3513 are reduced to binary, using an random-threshold method. The
3514 choices for channeltype are All, Intensity, Red, Green, Blue,
3515 Cyan, Magenta, Yellow, Black, and Opacity
3516 When channeltype is "All", the color samples are thresholded
3518 into a graylevel and then that gray level is stored in the three
3519 color channels. Separately, the opacity channel is thresholded
3520 into a bilevel opacity value which is stored in the opacity
3521 channel. For each pixel, a new random number is used to estab‐
3522 lish the threshold to be used. The threshold never exceeds the
3523 specified maximum (HIGH) and is never less than the specified
3524 minimum (LOW).
3525 When channeltype is "intensity", only the color samples are
3527 thresholded. When channeltype is "opacity" or "matte", only the
3528 opacity channel is thresholded. The other named channels only
3529 threshold the associated channel.
3530 -recolor <matrix>
3532 apply a color translation matrix to image channels
3533 A user supplied color translation matrix (expressed as a text
3535 string) is used to translate/blend the image channels based on
3536 weightings in a supplied matrix which may be of order 3 (color
3537 channels only), 4 (color channels plus opacity), or 5 (color
3538 channels plus opacity and offset). Values in the columns of the
3539 matrix (red, green, blue, opacity) are used as multipliers with
3540 the existing channel values and added together according to the
3541 rows of the matrix. Matrix values are floating point and may be
3542 negative. The offset column (column 5) is purely additive and
3543 is scaled such that 0.0 to 1.0 represents the maximum quantum
3544 range (but values are not limited to this range). The math for
3545 the color translation matrix is similar to that used by Adobe
3546 Flash except that the offset is scaled to 1.0 (divide Flash off‐
3547 set by 255 for use with GraphicsMagick) so that the results are
3548 independent of quantum depth.
3549 An identity matrix exists for each matrix order which results in
3551 no change to the image. The translation matrix should be based
3552 on an alteration of the identity matrix.
3553 Identity matrix of order 3
3555 1 0 0
3557 0 1 0
3558 0 0 1
3559 which may be formatted into a convenient matrix argument similar
3561 to (comma is treated as white space):
3562 -recolor "1 0 0, 0 1 0, 0 0 1"
3564 Identity matrix of order 4
3566 1 0 0 0
3568 0 1 0 0
3569 0 0 1 0
3570 0 0 0 1
3571 Identity matrix of order 5. The last row is required to exist
3573 for the purpose of parsing, but is otherwise not used.
3574 1 0 0 0 0
3576 0 1 0 0 0
3577 0 0 1 0 0
3578 0 0 0 1 0
3579 0 0 0 0 1
3580 As an example, an image wrongly in BGR channel order may be con‐
3582 verted to RGB using this matrix (blue->red, red->blue):
3583 0 0 1
3585 0 1 0
3586 1 0 0
3587 and an RGB image using standard Rec.709 primaries may be con‐
3589 verted to grayscale using this matrix of standard weighting fac‐
3590 tors:
3591 0.2126 0.7152 0.0722
3593 0.2126 0.7152 0.0722
3594 0.2126 0.7152 0.0722
3595 and contrast may be reduced by scaling down by 80% and adding a
3597 10% offset:
3598 0.8 0.0 0.0 0.0 0.1
3600 0.0 0.8 0.0 0.0 0.1
3601 0.0 0.0 0.8 0.0 0.1
3602 0.0 0.0 0.0 0.8 0.1
3603 0.0 0.0 0.0 0.0 1.0
3604 -red-primary <x>,<y>
3606 red chromaticity primary point
3607 -region <width>x<height>{+-}<x>{+-}<y>
3609 apply options to a portion of the image
3610 The x and y offsets are treated in the same manner as in -crop.
3612 -remote
3614 perform a X11 remote operation
3615 The -remote command sends a command to a "gm display" or "gm an‐
3617 imate" which is already running. The only command recognized at
3618 this time is the name of an image file to load. This capability
3619 is very useful to load new images without needing to restart
3620 GraphicsMagick (e.g. for a slide-show or to use GraphicsMagick
3621 as the display engine for a different GUI). Also see the
3622 +progress option for a way to disable progress indication for a
3623 clean look while loading new images.
3624 -render
3626 render vector operations
3627 Use +render to turn off rendering vector operations. This is
3629 useful when saving the result to vector formats such as MVG or
3630 SVG.
3631 -repage <width>x<height>+xoff+yoff[!]
3633 Adjust image page offsets
3634 Adjust the current image page canvas and position based on a
3636 relative page specification. This option may be used to change
3637 the location of a subframe (e.g. part of an animation) prior to
3638 composition. If the geometry specification is absolute (in‐
3639 cludes a '!'), then the offset adjustment is absolute and there
3640 is no adjustment to page width and height, otherwise the page
3641 width and height values are also adjusted based on the current
3642 image dimensions. Use +repage to set the image page offsets to
3643 default.
3644 -resample <horizontal>x<vertical>
3646 Resample image to specified horizontal and vertical resolution
3647 Resize the image so that its rendered size remains the same as
3649 the original at the specified target resolution. Either the cur‐
3650 rent image resolution units or the previously set with -units
3651 are used to interpret the argument. For example, if a 300 DPI
3652 image renders at 3 inches by 2 inches on a 300 DPI device, when
3653 the image has been resampled to 72 DPI, it will render at 3
3654 inches by 2 inches on a 72 DPI device. Note that only a small
3655 number of image formats (e.g. JPEG, PNG, and TIFF) are capable
3656 of storing the image resolution. For formats which do not sup‐
3657 port an image resolution, the original resolution of the image
3658 must be specified via -density on the command line prior to
3659 specifying the resample resolution.
3660 Note that Photoshop stores and obtains image resolution from a
3662 proprietary embedded profile. If this profile exists in the im‐
3663 age, then Photoshop will continue to treat the image using its
3664 former resolution, ignoring the image resolution specified in
3665 the standard file header.
3666 Some image formats (e.g. PNG) require use of metric or english
3668 units so even if the original image used a particular unit sys‐
3669 tem, if it is saved to a different format prior to resampling,
3670 then it may be necessary to specify the desired resolution units
3671 using -units since the original units may have been lost. In
3672 other words, do not assume that the resolution units are re‐
3673 stored if the image has been saved to a file.
3674 -resize <width>x<height>{%}{@}{!}{<}{>}
3676 resize an image
3677 This is an alias for the -geometry option and it behaves in the
3679 same manner. If the -filter option precedes the -resize option,
3680 the specified filter is used.
3681 There are some exceptions:
3683 When used as a composite option, -resize conveys the preferred
3685 size of the output image, while -geometry conveys the size and
3686 placement of the composite image within the main image.
3687 When used as a montage option, -resize conveys the preferred
3689 size of the montage, while -geometry conveys information about
3690 the tiles.
3691 -roll {+-}<x>{+-}<y>
3693 roll an image vertically or horizontally
3694 See -geometry for details the geometry specification. The x and
3696 y offsets are not affected by the -gravity option.
3697 A negative x offset rolls the image left-to-right. A negative y
3699 offset rolls the image top-to-bottom.
3700 -rotate <degrees>{<}{>}
3702 rotate the image
3703 Positive angles rotate the image in a clockwise direction while
3705 negative angles rotate counter-clockwise.
3706 Use > to rotate the image only if its width exceeds the height.
3708 < rotates the image only if its width is less than the height.
3709 For example, if you specify -rotate "-90>" and the image size is
3710 480x640, the image is not rotated. However, if the image is
3711 640x480, it is rotated by -90 degrees. If you use > or <, en‐
3712 close it in quotation marks to prevent it from being misinter‐
3713 preted as a file redirection.
3714 Empty triangles left over from rotating the image are filled
3716 with the color defined as background (class backgroundColor).
3717 The color is specified using the format described under the
3718 -fill option.
3719 -sample <geometry>
3721 scale image using pixel sampling
3722 See -geometry for details about the geometry specification.
3724 -sample ignores the -filter selection if the -filter option is
3725 present. Offsets, if present in the geometry string, are ig‐
3726 nored, and the -gravity option has no effect.
3727 -sampling-factor <horizontal_factor>x<vertical_factor>
3729 chroma subsampling factors
3730 This option specifies the sampling factors to be used by the
3732 DPX, JPEG, MPEG, or YUV encoders for chroma downsampling. The
3733 sampling factor must be specified while reading the raw YUV for‐
3734 mat since it is not preserved in the file header. Industry-
3735 standard video subsampling notation such as "4:2:2" may also be
3736 used to specify the sampling factors. "4:2:2" is equivalent to a
3737 specification of "2x1"
3738 The JPEG decoder obtains the original sampling factors (and
3740 quality settings) when a JPEG file is read. To re-use the origi‐
3741 nal sampling factors (and quality setting) when JPEG is output,
3742 use the -define jpeg:preserve-settings flag.
3743 -scale <geometry>
3745 scale the image.
3746 See -geometry for details about the geometry specification.
3748 -scale uses a simpler, faster algorithm, and it ignores the
3749 -filter selection if the -filter option is present. Offsets, if
3750 present in the geometry string, are ignored, and the -gravity
3751 option has no effect.
3752 -scene <value>
3754 set scene number
3755 This option sets the scene number of an image or the first image
3757 in an image sequence.
3758 -scenes <value-value>
3760 range of image scene numbers to read
3761 Each image in the range is read with the filename followed by a
3763 period (.) and the decimal scene number. You can change this
3764 behavior by embedding a %d, %0Nd, %o, %0No, %x, or %0Nx printf
3765 format specification in the file name. For example,
3766 gm montage -scenes 5-7 image.miff montage.miff
3768 makes a montage of files image.miff.5, image.miff.6, and im‐
3770 age.miff.7, and
3771 gm animate -scenes 0-12 image%02d.miff
3773 animates files image00.miff, image01.miff, through image12.miff.
3775 -screen
3777 specify the screen to capture
3778 This option indicates that the GetImage request used to obtain
3780 the image should be done on the root window, rather than di‐
3781 rectly on the specified window. In this way, you can obtain
3782 pieces of other windows that overlap the specified window, and
3783 more importantly, you can capture menus or other popups that are
3784 independent windows but appear over the specified window.
3785 -set <attribute> <value>
3787 set an image attribute
3788 Set a named image attribute. The attribute is set on the cur‐
3790 rent (previously specified on command line) image.
3791 +set <attribute>
3793 unset an image attribute
3794 Unset a named image attribute. The attribute is removed from
3796 the current (previously specified on command line) image.
3797 -segment <cluster threshold>x<smoothing threshold>
3799 segment an image
3800 Segment an image by analyzing the histograms of the color compo‐
3802 nents and identifying units that are homogeneous with the fuzzy
3803 c-means technique.
3804 Segmentation is a very useful fast and and approximate color
3806 quantization algorithm for scanned printed pages or scanned car‐
3807 toons. It may also be used as a special effect. Specify cluster
3808 threshold as the minimum percentage of total pixels in a cluster
3809 before it is considered valid. For huge images containing small
3810 detail, this may need to be a tiny fraction of a percent (e.g.
3811 0.015) so that important detail is not lost. Smoothing thresh‐
3812 old eliminates noise in the second derivative of the histogram.
3813 As the value is increased, you can expect a smoother second de‐
3814 rivative. The default is 1.5. Add the -verbose option to see a
3815 dump of cluster statistics given the parameters used. The sta‐
3816 tistics may be used as a guide to help fine tune the options.
3817 -shade <azimuth>x<elevation>
3819 shade the image using a distant light source
3820 Specify azimuth and elevation as the position of the light
3822 source. Use +shade to return the shading results as a grayscale
3823 image.
3824 -shadow <radius>{x<sigma>}
3826 shadow the montage
3827 -shared-memory
3829 use shared memory
3830 This option specifies whether the utility should attempt to use
3832 shared memory for pixmaps. GraphicsMagick must be compiled with
3833 shared memory support, and the display must support the MIT-SHM
3834 extension. Otherwise, this option is ignored. The default is
3835 True.
3836 -sharpen <radius>{x<sigma>}
3838 sharpen the image
3839 Use a Gaussian operator of the given radius and standard devia‐
3841 tion (sigma).
3842 -shave <width>x<height>{%}
3844 shave pixels from the image edges
3845 Specify the width of the region to be removed from both sides of
3847 the image and the height of the regions to be removed from top
3848 and bottom.
3849 -shear <x degrees>x<y degrees>
3851 shear the image along the X or Y axis
3852 Use the specified positive or negative shear angle.
3854 Shearing slides one edge of an image along the X or Y axis, cre‐
3856 ating a parallelogram. An X direction shear slides an edge along
3857 the X axis, while a Y direction shear slides an edge along the Y
3858 axis. The amount of the shear is controlled by a shear angle.
3859 For X direction shears, x degrees is measured relative to the Y
3860 axis, and similarly, for Y direction shears y degrees is mea‐
3861 sured relative to the X axis.
3862 Empty triangles left over from shearing the image are filled
3864 with the color defined as background (class backgroundColor).
3865 The color is specified using the format described under the
3866 -fill option.
3867 -silent
3869 operate silently
3870 -size <width>x<height>{+offset}
3872 width and height of the image
3873 Use this option to specify the width and height of raw images
3875 whose dimensions are unknown such as GRAY, RGB, or CMYK. In ad‐
3876 dition to width and height, use -size with an offset to skip any
3877 header information in the image or tell the number of colors in
3878 a MAP image file, (e.g. -size 640x512+256).
3879 For Photo CD images, choose from these sizes:
3881 192x128
3883 384x256
3884 768x512
3885 1536x1024
3886 3072x2048
3887 Finally, use this option to choose a particular resolution layer
3889 of a JBIG or JPEG image (e.g. -size 1024x768).
3890 -snaps <value>
3892 number of screen snapshots
3893 Use this option to grab more than one image from the X server
3895 screen, to create an animation sequence.
3896 -solarize <factor>
3898 negate all pixels above the threshold level
3899 Specify factor as the percent threshold of the intensity (0 -
3901 99.9%).
3902 This option produces a solarization effect seen when exposing a
3904 photographic film to light during the development process.
3905 -spread <amount>
3907 displace image pixels by a random amount
3908 Amount defines the size of the neighborhood around each pixel to
3910 choose a candidate pixel to swap.
3911 -stegano <offset>
3913 hide watermark within an image
3914 Use an offset to start the image hiding some number of pixels
3916 from the beginning of the image. Note this offset and the image
3917 size. You will need this information to recover the stegano‐
3918 graphic image (e.g. display -size 320x256+35 stegano:image.png).
3919 -stereo
3921 composite two images to create a stereo anaglyph
3922 The left side of the stereo pair is saved as the red channel of
3924 the output image. The right side is saved as the green channel.
3925 Red-green stereo glasses are required to properly view the
3926 stereo image.
3927 -strip remove all profiles and text attributes from the image
3929 All embedded profiles and text attributes are stripped from the
3931 image. This is useful for images used for the web, or when out‐
3932 put files need to be as small as possible
3933 Be careful not to use this option to remove author, copyright,
3935 and license information that you are required to retain when re‐
3936 distributing an image.
3937 -stroke <color>
3939 color to use when stroking a graphic primitive
3940 The color is specified using the format described under the
3942 -fill option.
3943 See -draw for further details.
3945 -strokewidth <value>
3947 set the stroke width
3948 See -draw for further details.
3950 -swirl <degrees>
3952 swirl image pixels about the center
3953 Degrees defines the tightness of the swirl.
3955 -text-font <name>
3957 font for writing fixed-width text
3958 Specifies the name of the preferred font to use in fixed (type‐
3960 writer style) formatted text. The default is 14 point Courier.
3961 You can tag a font to specify whether it is a PostScript, True‐
3963 Type, or X11 font. For example, Courier.ttf is a TrueType font
3964 and x:fixed is X11.
3965 -texture <filename>
3967 name of texture to tile onto the image background
3968 -threshold <value>{%}
3970 threshold the image
3971 Modify the image such that any pixel sample with an intensity
3973 value greater than the threshold is assigned the maximum inten‐
3974 sity (white), or otherwise is assigned the minimum intensity
3975 (black). If a percent prefix is applied, then the threshold is a
3976 percentage of the available range.
3977 To efficiently create a black and white image from a color im‐
3979 age, use
3980 gm convert -threshold 50% in.png out.png
3982 The optimum threshold value depends on the nature of the image.
3984 In order to threshold individual channels, use the -operator
3985 subcommand with it's Threshold, Threshold-White, or Threshold-
3986 Black options.
3987 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
3989 resize an image (quickly)
3990 The -thumbnail command resizes the image as quickly as possible,
3992 with more concern for speed than resulting image quality. Re‐
3993 gardless, resulting image quality should be acceptable for many
3994 uses. It is primarily intended to be used to generate smaller
3995 versions of the image, but may also be used to enlarge the im‐
3996 age. The -thumbnail geometry argument observes the same syntax
3997 and rules as it does for -resize.
3998 -tile <filename>
4000 tile image when filling a graphic primitive
4001 -tile <geometry>
4003 layout of images [montage]
4004 -title <string>
4006 assign title to displayed image [animate, display, montage]
4007 Use this option to assign a specific title to the image. This is
4009 assigned to the image window and is typically displayed in the
4010 window title bar. Optionally you can include the image file‐
4011 name, type, width, height, Exif data, or other image attribute
4012 by embedding special format characters described under the -for‐
4013 mat option.
4014 For example,
4016 -title "%m:%f %wx%h"
4018 produces an image title of MIFF:bird.miff 512x480 for an image
4020 titled bird.miff and whose width is 512 and height is 480.
4021 -transform
4023 transform the image
4024 This option applies the transformation matrix from a previous
4026 -affine option.
4027 gm convert -affine 2,2,-2,2,0,0 -transform bird.ppm bird.jpg
4029 -transparent <color>
4031 make this color transparent within the image
4032 The color is specified using the format described under the
4034 -fill option.
4035 -treedepth <value>
4037 tree depth for the color reduction algorithm
4038 Normally, this integer value is zero or one. A value of zero or
4040 one causes the use of an optimal tree depth for the color reduc‐
4041 tion algorithm
4042 An optimal depth generally allows the best representation of the
4044 source image with the fastest computational speed and the least
4045 amount of memory. However, the default depth is inappropriate
4046 for some images. To assure the best representation, try values
4047 between 2 and 8 for this parameter. Refer to quantize for more
4048 details.
4049 The -colors or -monochrome option, or writing to an image format
4051 which requires color reduction, is required for this option to
4052 take effect.
4053 -trim trim an image
4055 This option removes any edges that are exactly the same color as
4057 the corner pixels. Use -fuzz to make -trim remove edges that
4058 are nearly the same color as the corner pixels.
4059 -type <type>
4061 the image type
4062 Choose from: Bilevel, Grayscale, Palette, PaletteMatte, True‐
4064 Color, TrueColorMatte, ColorSeparation, ColorSeparationMatte, or
4065 Optimize.
4066 Normally, when a format supports different subformats such as
4068 bilevel, grayscale, palette, truecolor, and truecolor+alpha, the
4069 encoder will try to choose a suitable subformat based on the na‐
4070 ture of the image. The -type option may be used to tailor the
4071 output subformat. By default the output subformat is based on
4072 readily available image information and is usually similar to
4073 the input format.
4074 Specify -type Optimize in order to enable inspecting all pixels
4076 (if necessary) in order to find the most efficient subformat.
4077 Inspecting all of the pixels may be slow for very large images,
4078 particularly if they are stored in a disk cache. If an RGB image
4079 contains only gray pixels, then every pixel in the image must be
4080 inspected in order to decide that the image is actually
4081 grayscale!
4082 Sometimes a specific subformat is desired. For example, to force
4084 a JPEG image to be written in TrueColor RGB format even though
4085 only gray pixels are present, use
4086 gm convert bird.pgm -type TrueColor bird.jpg
4088 Similarly, using -type TrueColorMatte will force the encoder to
4090 write an alpha channel even though the image is opaque, if the
4091 output format supports transparency.
4092 Some pseudo-formats (e.g. the XC format) will respect the re‐
4094 quested type if it occurs previously on the command line. For
4095 example, to obtain a DirectClass solid color canvas image rather
4096 than PsuedoClass, use
4097 gm convert -size 640x480 -type TrueColor xc:red red.miff
4099 Likewise, specify -type Bilevel, Grayscale, TrueColor, or True‐
4101 ColorMatte prior to reading a Postscript (or PDF file) in order
4102 to influence the type of image that Ghostcript returns. Reading
4103 performance will be dramatically improved for black/white Post‐
4104 script if Bilevel is specified, and will be considerably faster
4105 if Grayscale is specified.
4106 -update <seconds>
4108 detect when image file is modified and redisplay.
4109 Suppose that while you are displaying an image the file that is
4111 currently displayed is over-written. display will automatically
4112 detect that the input file has been changed and update the dis‐
4113 played image accordingly.
4114 -units <type>
4116 the units of image resolution
4117 Choose from: Undefined, PixelsPerInch, or PixelsPerCentimeter.
4119 This option is normally used in conjunction with the -density
4120 option.
4121 -unsharp <radius>{x<sigma>}{+<amount>}{+<threshold>}
4123 sharpen the image with an unsharp mask operator
4124 The -unsharp option sharpens an image. The image is convolved
4126 with a Gaussian operator of the given radius and standard devia‐
4127 tion (sigma). For reasonable results, radius should be larger
4128 than sigma. Use a radius of 0 to have the method select a suit‐
4129 able radius.
4130 The parameters are:
4132 radius
4135 The radius of the Gaussian, in pixels, not counting the
4138 center pixel (default 0).
4139 sigma
4141 The standard deviation of the Gaussian, in pixels (default
4144 1.0).
4145 amount
4147 The percentage of the difference between the original and
4150 the blur image that is added back into the original (de‐
4151 fault 1.0).
4152 threshold
4154 The threshold, as a fraction of MaxRGB, needed to apply
4157 the difference amount (default 0.05).
4158 -use-pixmap
4163 use the pixmap
4164 -verbose
4166 print detailed information about the image
4167 This information is printed: image scene number; image name; im‐
4169 age size; the image class (DirectClass or PseudoClass); the to‐
4170 tal number of unique colors; and the number of seconds to read
4171 and transform the image. If the image is DirectClass, the total
4172 number of unique colors is not displayed unless -verbose is
4173 specified twice since it may take quite a long time to compute,
4174 particularly for deep images. If the image is PseudoClass then
4175 its pixels are defined by indexes into a colormap. If the image
4176 is DirectClass then each pixel includes a complete and indepen‐
4177 dent color specification.
4178 If -colors is also specified, the total unique colors in the im‐
4180 age and color reduction error values are printed. Refer to quan‐
4181 tize for a description of these values.
4182 -version
4184 print GraphicsMagick version string
4185 -view <string>
4187 FlashPix viewing parameters
4188 -virtual-pixel <method>
4190 specify contents of "virtual pixels"
4191 This option defines "virtual pixels" for use in operations that
4193 can access pixels outside the boundaries of an image.
4194 Choose from these methods:
4196 Constant
4199 Use the image background color.
4202 Edge
4204 Extend the edge pixel toward infinity (default).
4207 Mirror
4209 Mirror the image.
4212 Tile
4214 Tile the image.
4217 This option affects operations that use virtual pixels such as
4222 -blur, -sharpen, -wave, etc.
4223 -visual <type>
4225 animate images using this X visual type
4226 Choose from these visual classes:
4228 StaticGray
4230 GrayScale
4231 StaticColor
4232 PseudoColor
4233 TrueColor
4234 DirectColor
4235 default
4236 visual id
4237 The X server must support the visual you choose, otherwise an
4239 error occurs. If a visual is not specified, the visual class
4240 that can display the most simultaneous colors on the default
4241 screen is chosen.
4242 -watermark <brightness>x<saturation>
4244 percent brightness and saturation of a watermark
4245 -wave <amplitude>x<wavelength>
4247 alter an image along a sine wave
4248 Specify amplitude and wavelength of the wave.
4250 -white-point <x>,<y>
4252 chromaticity white point
4253 -white-threshold red[,green][,blue][,opacity]
4255 pixels above the threshold become white
4256 Use -white-threshold to set pixels with values above the speci‐
4258 fied threshold to maximum value (white). If only one value is
4259 supplied, or the red, green, and blue values are identical, then
4260 intensity thresholding is used. If the color threshold values
4261 are not identical then channel-based thresholding is used, and
4262 color distortion will occur. Specify a negative value (e.g. -1)
4263 if you want a channel to be ignored but you do want to threshold
4264 a channel later in the list. If a percent (%) symbol is ap‐
4265 pended, then the values are treated as a percentage of maximum
4266 range.
4267 -window <id>
4269 make image the background of a window
4270 id can be a window id or name. Specify root to select X's root
4272 window as the target window.
4273 By default the image is tiled onto the background of the target
4275 window. If backdrop or -geometry are specified, the image is
4276 surrounded by the background color. Refer to X RESOURCES for
4277 details.
4278 The image will not display on the root window if the image has
4280 more unique colors than the target window colormap allows. Use
4281 -colors to reduce the number of colors.
4282 -window-group
4284 specify the window group
4285 -write <filename>
4287 write an intermediate image [convert, composite]
4288 The current image is written to the specified filename and then
4290 processing continues using that image. The following is an exam‐
4291 ple of how several sizes of an image may be generated in one
4292 command (repeat as often as needed):
4293 gm convert input.jpg -resize 50% -write input50.jpg \
4295 -resize 25% input25.jpg
4296 -write <filename>
4298 write the image to a file [display]
4299 If filename already exists, you will be prompted as to whether
4301 it should be overwritten.
4302 By default, the image is written in the format that it was read
4304 in as. To specify a particular image format, prefix filename
4305 with the image type and a colon (e.g., ps:image) or specify the
4306 image type as the filename suffix (e.g., image.ps). Specify file
4307 as - for standard output. If file has the extension .Z or .gz,
4308 the file size is compressed using compress or gzip respectively.
4309 Precede the image file name with | to pipe to a system command.
4310 Use -compress to specify the type of image compression.
4312 The equivalent X resource for this option is writeFilename
4314 (class WriteFilename). See "X Resources", below, for details.
4315
4317 COLUMNS
4318 Output screen width. Used when formatting text for the screen.
4319 Many Unix systems keep this shell variable up to date, but it
4320 may need to be explicitly exported in order for GraphicsMagick
4321 to see it.
4322 DISPLAY
4324 X11 display ID (host, display number, and screen in the form
4325 hostname:display.screen).
4326 HOME Location of user's home directory. For security reasons, now
4328 only observed by "uninstalled" builds of GraphicsMagick which do
4329 not have their location hard-coded or set by an installer. When
4330 supported, GraphicsMagick searches for configuration files in
4331 $HOME/.magick if the directory exists. See MAGICK_CODER_MOD‐
4332 ULE_PATH, MAGICK_CONFIGURE_PATH, and MAGICK_FILTER_MODULE_PATH
4333 if more flexibility is needed.
4334 MAGICK_ACCESS_MONITOR
4336 When set to TRUE, command line monitor mode (enabled by -moni‐
4337 tor) will also show files accessed (including temporary files)
4338 and any external commands which are executed. This is useful for
4339 debugging, but also illustrates arguments made available to an
4340 access handler registered by the MagickSetConfirmAccessHandler()
4341 C library function.
4342 MAGICK_CODER_STABILITY
4344 The minimum coder stability level before it will be used. The
4345 available levels are PRIMARY, STABLE, UNSTABLE, and BROKEN. The
4346 default minimum level is UNSTABLE, which means that all avail‐
4347 able working coders will be used. The purpose of this option is
4348 to reduce the security exposure (or apparent complexity) due to
4349 the huge number of formats supported. Coders at the PRIMARY
4350 level are commonly used formats with very well maintained imple‐
4351 mentations. Coders at the STABLE level are reasonably well main‐
4352 tained but represent less used formats. Coders at the UNSTABLE
4353 level either have weak implementations, the file format itself
4354 is weak, or the probability the coder will be needed is vanish‐
4355 ingly small. Coders at the BROKEN level are known to often not
4356 work properly or might not be useful in their current state at
4357 all.
4358 MAGICK_CODER_MODULE_PATH
4360 Search path to use when searching for image format coder mod‐
4361 ules. This path allows the user to arbitrarily extend the image
4362 formats supported by GraphicsMagick by adding loadable modules
4363 to an arbitrary location rather than copying them into the
4364 GraphicsMagick installation directory. The formatting of the
4365 search path is similar to operating system search paths (i.e.
4366 colon delimited for Unix, and semi-colon delimited for Microsoft
4367 Windows). This user specified search path is used before trying
4368 the default search path.
4369 MAGICK_CONFIGURE_PATH
4371 Search path to use when searching for configuration (.mgk)
4372 files. The formatting of the search path is similar to operat‐
4373 ing system search paths (i.e. colon delimited for Unix, and
4374 semi-colon delimited for Microsoft Windows). This user specified
4375 search path is used before trying the default search path.
4376 MAGICK_DEBUG
4378 Debug options (see -debug for details). Setting the configure
4379 debug option via an environment variable (e.g. MAGICK_DEBUG=con‐
4380 figure) is necessary to see the complete initialization process,
4381 which includes searching for configuration files.
4382 MAGICK_FILTER_MODULE_PATH
4384 Search path to use when searching for filter process modules
4385 (invoked via -process). This path allows the user to arbitrarily
4386 extend GraphicsMagick's image processing functionality by adding
4387 loadable modules to an arbitrary location rather than copying
4388 them into the GraphicsMagick installation directory. The format‐
4389 ting of the search path is similar to operating system search
4390 paths (i.e. colon delimited for Unix, and semi-colon delimited
4391 for Microsoft Windows). This user specified search path is used
4392 before trying the default search path.
4393 MAGICK_GHOSTSCRIPT_PATH
4395 For Microsoft Windows, specify the path to the Ghostscript in‐
4396 stallation rather than searching for it via the Windows reg‐
4397 istry. This helps in case Ghostscript is not installed via the
4398 Ghostscript Windows installer or the user wants more control
4399 over the Ghostscript used.
4400 MAGICK_HOME
4402 Path to top of GraphicsMagick installation directory. Only ob‐
4403 served by "uninstalled" builds of GraphicsMagick which do not
4404 have their location hard-coded or set by an installer.
4405 MAGICK_MMAP_READ
4407 If MAGICK_MMAP_READ is set to TRUE, GraphicsMagick will attempt
4408 to memory-map the input file for reading. This usually substan‐
4409 tially improves repeated read performance since the file is al‐
4410 ready in memory after the first time it has been read. However,
4411 testing shows that performance may be reduced for files accessed
4412 for the first time since data is accessed via page-faults (upon
4413 first access) and many operating systems fail to do sequential
4414 read-ahead of memory mapped files, and particularly if those
4415 files are accessed over a network. If many large input files
4416 are read, then enabling this option may harm performance by
4417 overloading the operating system's VM system as it then needs to
4418 free unmapped pages and map new ones.
4419 MAGICK_IO_FSYNC
4421 If MAGICK_IO_FSYNC is set to TRUE, then GraphicsMagick will re‐
4422 quest that the output file is fully flushed and synchronized to
4423 disk when it is closed. This incurs a performance penalty, but
4424 has the benefit that if the power fails or the system crashes,
4425 the file should be valid on disk. If image files are referenced
4426 from a database, then this option helps assure that the files
4427 referenced by the database are valid.
4428 MAGICK_IOBUF_SIZE
4430 The amount of I/O buffering (in bytes) to use when reading and
4431 writing encoded files. The default is 16384, which is observed
4432 to work well for many cases. The best value for a local filesys‐
4433 tem is usually the the native filesystem block size (e.g. 4096,
4434 8192, or even 131,072 for ZFS) in order to minimize the number
4435 of physical disk I/O operations. I/O performance to files ac‐
4436 cessed over a network may benefit significantly by tuning this
4437 option. Larger values are not necessarily better (they may be
4438 slower!), and there is rarely any benefit from using values
4439 larger than 32768. Use convert's -verbose option in order to
4440 evaluate read and write rates in pixels per second while keeping
4441 in mind that the operating system will try to cache files in
4442 RAM.
4443 MAGICK_LIMIT_DISK
4445 Maximum amount of disk space allowed for use by the pixel cache.
4446 MAGICK_LIMIT_FILES
4448 Maximum number of open files.
4449 MAGICK_LIMIT_MAP
4451 Maximum size of a memory mapped file allocation. A memory
4452 mapped file consumes memory when the file is accessed, although
4453 the system may reclaim such memory when needed.
4454 MAGICK_LIMIT_MEMORY
4456 Maximum amount of memory to allocate from the heap.
4457 MAGICK_LIMIT_PIXELS
4459 Maximum number of total pixels (image rows times image colums)
4460 to allow for any image which is requested to be created or read.
4461 This is useful to place a limit on how large an image may be.
4462 If the input image file has image dimensions larger than the
4463 pixel limit, then the image memory allocation is denied and an
4464 error is returned immediately. This is a per-image limit and
4465 does not limit the total number of pixels due to multiple image
4466 frames/pages (e.g. multi-page document or an animation).
4467 MAGICK_LIMIT_READ
4469 Maximum number of uncompressed bytes which may be read while de‐
4470 coding an image. Each read by the software from the input file
4471 is counted against the total, even if it has been read before.
4472 Decoding fails when the limit is reached. This limit helps de‐
4473 fend against highly compressed files (e.g. via gzip), or files
4474 which use complex looping structures, or when data is being read
4475 from a stream (pipe).
4476 MAGICK_LIMIT_WIDTH
4478 Maximum pixel width of an image read, or created.
4479 MAGICK_LIMIT_HEIGHT
4481 Maximum pixel height of an image read, or created.
4482 MAGICK_TMPDIR
4484 Path to directory where GraphicsMagick should write temporary
4485 files. The default is to use the system default, or the location
4486 set by TMPDIR.
4487 TMPDIR For POSIX-compatible systems (Unix-compatible), the path to the
4489 directory where all applications should write temporary files.
4490 Overridden by MAGICK_TMPDIR if it is set.
4491 TMP or TEMP
4493 For Microsoft Windows, the path to the directory where applica‐
4494 tions should write temporary files. Overridden by MAGICK_TMPDIR
4495 if it is set.
4496 OMP_NUM_THREADS
4498 As per the OpenMP standard, this specifies the number of threads
4499 to use in parallel regions. Some compilers default the number of
4500 threads to use to the number of processor cores available while
4501 others default to just one thread. See the OpenMP specification
4502 for other standard adjustments and your compiler's manual for
4503 vendor-specific settings.
4504
4506 GraphicsMagick uses a number of XML format configuration files:
4507 colors.mgk
4509 colors configuration file
4510 <?xml version="1.0"?>
4512 <colormap>
4513 <color name="AliceBlue" red="240" green="248" blue="255"
4514 compliance="SVG, X11, XPM" />
4515 </colormap>
4516 delegates.mgk
4518 delegates configuration file
4519 log.mgk
4521 logging configuration file
4522 <?xml version="1.0"?>
4524 <magicklog>
4525 <log events="None" />
4526 <log output="stdout" />
4527 <log filename="Magick-%d.log" />
4528 <log generations="3" />
4529 <log limit="2000" />
4530 <log format="%t %r %u %p %m/%f/%l/%d:\n %e" />
4531 </magicklog>
4532 modules.mgk
4534 loadable modules configuration file
4535 <?xml version="1.0"?>
4537 <modulemap>
4538 <module magick="8BIM" name="META" />
4539 </modulemap>
4540 type.mgk
4542 master type (fonts) configuration file
4543 <?xml version="1.0"?>
4545 <typemap>
4546 <include file="type-windows.mgk" />
4547 <type
4548 name="AvantGarde-Book"
4549 fullname="AvantGarde Book"
4550 family="AvantGarde"
4551 foundry="URW"
4552 weight="400"
4553 style="normal"
4554 stretch="normal"
4555 format="type1"
4556 metrics="/usr/local/share/ghostscript/fonts/a010013l.afm"
4557 glyphs="/usr/local/share/ghostscript/fonts/a010013l.pfb"
4558 />
4559 </typemap>
4560
4562 Animate displays a sequence of images on any workstation display run‐
4563 ning an X server. animate first determines the hardware capabilities of
4564 the workstation. If the number of unique colors in an image is less
4565 than or equal to the number the workstation can support, the image is
4566 displayed in an X window. Otherwise the number of colors in the image
4567 is first reduced to match the color resolution of the workstation be‐
4568 fore it is displayed.
4569 This means that a continuous-tone 24 bits-per-pixel image can display
4571 on a 8 bit pseudo-color device or monochrome device. In most instances
4572 the reduced color image closely resembles the original. Alternatively,
4573 a monochrome or pseudo-color image sequence can display on a continu‐
4574 ous-tone 24 bits-per-pixel device.
4575 To help prevent color flashing on X server visuals that have colormaps,
4577 animate creates a single colormap from the image sequence. This can be
4578 rather time consuming. You can speed this operation up by reducing the
4579 colors in the image before you "animate" them. Use mogrify to color re‐
4580 duce the images to a single colormap. See mogrify(1) for details. Al‐
4581 ternatively, you can use a Standard Colormap; or a static, direct, or
4582 true color visual. You can define a Standard Colormap with xstdcmap.
4583 See xstdcmap(1) for details. This method is recommended for colormapped
4584 X server because it eliminates the need to compute a global colormap.
4585
4587 To animate a set of images of a cockatoo, use:
4588 gm animate cockatoo.*
4590 To animate a cockatoo image sequence while using the Standard Colormap
4592 best, use:
4593 xstdcmap -best
4595 gm animate -map best cockatoo.*
4596 To animate an image of a cockatoo without a border centered on a back‐
4598 drop, use:
4599 gm animate +borderwidth -backdrop cockatoo.*
4602
4604 For a more detailed description of each option, see Options, above.
4605 -authenticate <string>
4608 decrypt image with this password
4609 -backdrop
4611 display the image centered on a backdrop.
4612 -background <color>
4614 the background color
4615 -bordercolor <color>
4617 the border color
4618 -borderwidth <geometry>
4620 the border width
4621 -chop <width>x<height>{+-}<x>{+-}<y>{%}
4623 remove pixels from the interior of an image
4624 -colormap <type>
4626 define the colormap type
4627 -colors <value>
4629 preferred number of colors in the image
4630 -colorspace <value>
4632 the type of colorspace
4633 -crop <width>x<height>{+-}<x>{+-}<y>{%}
4635 preferred size and location of the cropped image
4636 -debug <events>
4638 enable debug printout
4639 -define <key>{=<value>},...
4641 add coder/decoder specific options
4642 -delay <1/100ths of a second>
4644 display the next image after pausing
4645 -density <width>x<height>
4647 horizontal and vertical resolution in pixels of the image
4648 -depth <value>
4650 depth of the image
4651 -display <host:display[.screen]>
4653 specifies the X server to contact
4654 -dispose <method>
4656 GIF disposal method
4657 -dither
4659 apply Floyd/Steinberg error diffusion to the image
4660 -font <name>
4662 use this font when annotating the image with text
4663 -foreground <color>
4665 define the foreground color
4666 -gamma <value>
4668 level of gamma correction
4669 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
4671 Specify dimension, offset, and resize options.
4672 -help print usage instructions
4674 -iconGeometry <geometry>
4676 specify the icon geometry
4677 -iconic
4679 iconic animation
4680 -interlace <type>
4682 the type of interlacing scheme
4683 -limit <type> <value>
4685 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
4686 resource limit
4687 -log <string>
4689 Specify format for debug log
4690 -map <type>
4692 display image using this type.
4693 -matte store matte channel if the image has one
4695 -mattecolor <color>
4697 specify the color to be used with the -frame option
4698 -monitor
4700 show progress indication
4701 -monochrome
4703 transform the image to black and white
4704 -name name an image
4706 -noop NOOP (no option)
4708 -pause <seconds>
4710 pause between animation loops [animate]
4711 -remote
4713 perform a X11 remote operation
4714 -rotate <degrees>{<}{>}
4716 rotate the image
4717 -sampling-factor <horizontal_factor>x<vertical_factor>
4719 chroma subsampling factors
4720 -scenes <value-value>
4722 range of image scene numbers to read
4723 -shared-memory
4725 use shared memory
4726 -size <width>x<height>{+offset}
4728 width and height of the image
4729 -text-font <name>
4731 font for writing fixed-width text
4732 -title <string>
4734 assign title to displayed image [animate, display, montage]
4735 -treedepth <value>
4737 tree depth for the color reduction algorithm
4738 -trim trim an image
4740 -type <type>
4742 the image type
4743 -verbose
4745 print detailed information about the image
4746 -version
4748 print GraphicsMagick version string
4749 -visual <type>
4751 animate images using this X visual type
4752 -window <id>
4754 make image the background of a window
4755 For a more detailed description of each option, see Options,
4757 above.
4758 Any option you specify on the command line remains in effect for
4761 the group of images following it, until the group is terminated
4762 by the appearance of any option or -noop. For example, to ani‐
4763 mate three images, the first with 32 colors, the second with an
4764 unlimited number of colors, and the third with only 16 colors,
4765 use:
4766 gm animate -colors 32 cockatoo.1 -noop cockatoo.2
4769 -colors 16 cockatoo.3
4770 Animate options can appear on the command line or in your X re‐
4772 sources file. See X(1). Options on the command line supersede
4773 values specified in your X resources file. Image filenames may
4774 appear in any order on the command line if the image format is
4775 MIFF (refer to miff(5) and the scene keyword is specified in the
4776 image. Otherwise the images will display in the order they ap‐
4777 pear on the command line.
4778
4780 Press any button to map or unmap the Command widget. See the next sec‐
4781 tion for more information about the Command widget.
4782
4784 The Command widget lists a number of sub-menus and commands. They are
4785 Animate
4787 Open
4789 Play
4790 Step
4791 Repeat
4792 Auto Reverse
4793 Speed
4795 Faster
4797 Slower
4798 Direction
4800 Forward
4802 Reverse
4803 Image Info
4805 Help
4806 Quit
4807 Menu items with a indented triangle have a sub-menu. They are repre‐
4810 sented above as the indented items. To access a sub-menu item, move the
4811 pointer to the appropriate menu and press a button and drag. When you
4812 find the desired sub-menu item, release the button and the command is
4813 executed. Move the pointer away from the sub-menu if you decide not to
4814 execute a particular command.
4815
4817 Ctl+O
4818 Press to load an image from a file.
4820 space
4821 Press to display the next image in the sequence.
4823 <
4824 Press to speed-up the display of the images. Refer to
4826 -delay for more information.
4827 >
4828 Press to slow the display of the images. Refer to -delay
4830 for more information.
4831 ?
4832 Press to display information about the image. Press any
4834 key or button to erase the information.
4835 This information is printed: image name; image size; and
4836 the total number of unique colors in the image.
4837 F1
4838 Press to display helpful information about animate(1).
4840 Ctl-q
4841 Press to discard all images and exit program.
4843
4846 Animate options can appear on the command line or in your X resource
4847 file. Options on the command line supersede values specified in your X
4848 resource file. See X(1) for more information on X resources.
4849 All animate options have a corresponding X resource. In addition, the
4851 animate program uses the following X resources:
4852 background (class Background)
4854 Specifies the preferred color to use for the Image window
4857 background. The default is #ccc.
4858 borderColor (class BorderColor)
4859 Specifies the preferred color to use for the Image window
4862 border. The default is #ccc.
4863 borderWidth (class BorderWidth)
4864 Specifies the width in pixels of the Image window border.
4867 The default is 2.
4868 font (class Font or FontList)
4869 Specifies the name of the preferred font to use in normal
4872 formatted text. The default is 14 point Helvetica.
4873 foreground (class Foreground)
4874 Specifies the preferred color to use for text within the
4877 Image window. The default is black.
4878 geometry (class geometry)
4879 Specifies the preferred size and position of the image
4882 window. It is not necessarily obeyed by all window man‐
4883 agers. Offsets, if present, are handled in X(1) style. A
4884 negative x offset is measured from the right edge of the
4885 screen to the right edge of the icon, and a negative y
4886 offset is measured from the bottom edge of the screen to
4887 the bottom edge of the icon.
4888 iconGeometry (class IconGeometry)
4889 Specifies the preferred size and position of the applica‐
4892 tion when iconified. It is not necessarily obeyed by all
4893 window managers. Offsets, if present, are handled in the
4894 same manner as in class Geometry.
4895 iconic (class Iconic)
4896 This resource indicates that you would prefer that the ap‐
4899 plication's windows initially not be visible as if the
4900 windows had be immediately iconified by you. Window man‐
4901 agers may choose not to honor the application's request.
4902 matteColor (class MatteColor)
4903 Specify the color of windows. It is used for the back‐
4906 grounds of windows, menus, and notices. A 3D effect is
4907 achieved by using highlight and shadow colors derived from
4908 this color. Default value: #ddd.
4909 name (class Name)
4910 This resource specifies the name under which resources for
4913 the application should be found. This resource is useful
4914 in shell aliases to distinguish between invocations of an
4915 application, without resorting to creating links to alter
4916 the executable file name. The default is the application
4917 name.
4918 sharedMemory (class SharedMemory)
4919 This resource specifies whether animate should attempt use
4922 shared memory for pixmaps. ImageMagick must be compiled
4923 with shared memory support, and the display must support
4924 the MIT-SHM extension. Otherwise, this resource is ig‐
4925 nored. The default is True.
4926 text_font (class textFont)
4927 Specifies the name of the preferred font to use in fixed
4930 (typewriter style) formatted text. The default is 14 point
4931 Courier.
4932 title (class Title)
4933 This resource specifies the title to be used for the Image
4936 window. This information is sometimes used by a window
4937 manager to provide some sort of header identifying the
4938 window. The default is the image file name.
4939
4943 batch executes an arbitary number of the utility commands (e.g. con‐
4944 vert) in the form of a simple linear batch script in order to improve
4945 execution efficiency, and/or to allow use as a subordinate co-process
4946 under the control of an arbitrary script or program.
4947
4949 To drive 'gm batch' using a shell script (or a program written in any
4950 language), have the script/program send commands to 'gm batch' via its
4951 standard input. Specify that standard input should be used by using
4952 '-' as the file name. The following example converts all files match‐
4953 ing '*.jpg' to TIFF format while rotating each file by 90 degrees and
4954 stripping all embedded profiles. The shell script syntax is standard
4955 Unix shell:
4956 for file in *.jpg
4958 do
4959 outfile=`basename $file .jpg`.tiff
4960 echo convert -verbose "'$file'" -rotate 90 \
4961 +profile "'*'" "'$outfile'"
4962 done | gm batch -echo on -feedback on -
4963 We can accomplish the same as the previous example by putting all the
4965 commands in a text file and then specifying the name of the text file
4966 as the script to execute:
4967 for file in *.jpg
4969 do
4970 outfile=`basename $file .jpg`.tiff
4971 echo convert -verbose "'$file'" -rotate 90 \
4972 +profile "'*'" "'$outfile'"
4973 done > script.txt
4974 gm batch -echo on -feedback on script.txt
4975
4977 Options are processed from left to right and must appear before any
4978 filename argument.
4979 -echo on|off
4981 command echo on or off
4982 Specify on to enable echoing commands to standard output as they
4984 are read or off to disable. The default is off.
4985 -escape unix|windows
4987 Parse using unix or windows syntax
4988 Commands must be parsed from the input stream and escaping needs
4990 to be used to protect spaces or quoting characters in the input.
4991 Specify unix to use unix-style command line parsing or windows
4992 for Microsoft Windows command shell style parsing. The default
4993 depends on if the software is compiled for Microsoft Windows or
4994 for a Unix-type system (including Cygwin on Microsoft Windows).
4995 It is recommended to use unix syntax because it is more powerful
4996 and more portable.
4997 -fail text
4999 text to print if a command fails
5000 When feedback is enabled, this specifies the text to print when
5002 the command fails. The default text is FAIL.
5003 -feedback on|off
5005 enable error feedback
5006 Print text (see -pass and -fail options) feedback after each
5008 command to indicate the result, the default is off.
5009 -help
5011 Prints batch command help.
5013 -pass text
5015 text to print if a command passes
5016 When feedback is enabled, this specifies the text to print when
5018 the command passes. The default text is PASS.
5019 -prompt text
5021 Prompt text to use for command line
5022 If no filename argument was specified, a simple command prompt
5024 appears where you may enter GraphicsMagick commands. The de‐
5025 fault prompt is GM>. Use this option to change the prompt to
5026 something else.
5027 -stop-on-error on|off
5029 Specify if command processing stops on error
5030 Normally command processing continues if a command encounters an
5032 error. Specify -stop-on-error on to cause processing to quit
5033 immediately on error.
5034
5037 benchmark executes an arbitrary gm utility command (e.g. convert) for
5038 one or more loops, and/or a specified execution time, and reports many
5039 execution metrics. For builds using OpenMP, a mode is provided to exe‐
5040 cute the benchmark with an increasing number of threads and provide a
5041 report of speedup and multi-thread execution efficiency. If benchmark
5042 is used to execute a command without any additional benchmark options,
5043 then the command is run once.
5044
5046 To obtain benchmark information for a single execution of a command:
5047 gm benchmark convert input.ppm -gaussian 0x1 output.ppm
5049 To obtain benchmark information from 100 iterations of the command:
5050 gm benchmark -iterations 100 convert input.ppm \
5052 -gaussian 0x1 output.ppm
5053 To obtain benchmark information by iterating the command until a speci‐
5054 fied amount of time (in seconds) has been consumed:
5055 gm benchmark -duration 30 convert input.ppm \
5057 -gaussian 0x1 output.ppm
5058 To obtain a full performance report with an increasing number of
5059 threads (1-32 threads, stepping the number of threads by four each
5060 time):
5061 gm benchmark -duration 3 -stepthreads 4 convert \
5063 input.ppm -gaussian 0x2 output.ppm
5064 Here is the interpretation of the output:
5065 threads - number of threads used.
5067 iter - number of command iterations executed.
5068 user - total user time consumed.
5069 total - total elapsed time consumed.
5070 iter/s - number of command iterations per second.
5071 iter/cpu - amount of CPU time consumed per iteration.
5072 speedup - speedup compared with one thread.
5073 karp-flatt - Karp-Flatt measure of speedup efficiency.
5074 Please note that the reported "speedup" is based on the execution time
5076 of just one thread. A preliminary warm-up pass is used before timing
5077 the first loop in order to ensure that the CPU is brought out of power-
5078 saving modes and that system caches are warmed up. Most modern CPUs
5079 provide a "turbo" mode where the CPU clock speed is increased (e.g. by
5080 a factor of two) when only one or two cores are active. If the CPU
5081 grows excessively hot (due to insufficient cooling), then it may dial
5082 back its clock rates as a form of thermal management. These factors
5083 result in an under-reporting of speedup compared to if "turbo" mode was
5084 disabled and the CPU does not need to worry about thermal management.
5085 The powertop utility available under Linux and Solaris provides a way
5086 to observe CPU core clock rates while a benchmark is running.
5087
5089 Options are processed from left to right and must appear before any
5090 argument.
5091 -duration duration
5093 duration to run benchmark Specify the number of seconds to run
5094 the benchmark. The command is executed repeatedly until the
5095 specified amount of time has elapsed.
5096 -help
5098 Prints benchmark command help.
5100 -iterations loops
5102 number of command iterations Specify the number of iterations to
5103 run the benchmark. The command is executed repeatedly until the
5104 specified number of iterations has been reached.
5105 -rawcsv
5107 Print results in CSV format Print results in a comma-separated
5108 value (CSV) format which is easy to parse for plotting or im‐
5109 porting into a spreadsheet or database. The values reported are
5110 threads, iterations, user_time, and elapsed_time.
5111 -stepthreads step
5113 execute a per-thread benchmark ramp
5114 Execute a per-thread benchmark ramp, incrementing the number of
5115 threads at each step by the specified value. The maximum number
5116 of threads is taken from the standard OMP_NUM_THREADS environ‐
5117 ment variable.
5118
5120 compare compares two similar images using a specified statistical
5121 method (see -metric) and/or by writing a difference image (-file), with
5122 the altered pixels annotated using a specified method (see -highlight-
5123 style) and color (see -highlight-color). Reference-image is the origi‐
5124 nal image and compare-image is the (possibly) altered version, which
5125 should have the same dimensions as reference-image.
5126
5128 To compare two images using Mean Square Error (MSE) statistical analy‐
5129 sis use:
5130 gm compare -metric mse original.miff compare.miff
5132 To create an annotated difference image use:
5134 gm compare -highlight-style assign -highlight-color purple \
5136 -file diff.miff original.miff compare.miff
5137
5139 Options are processed in command line order. Any option you specify on
5140 the command line remains in effect only for the image that follows.
5141 All options are reset to their default values after each image is read.
5142 For a more detailed description of each option, see Options, above.
5144 -authenticate <string>
5147 decrypt image with this password
5148 -auto-orient
5150 orient (rotate) image so it is upright
5151 -colorspace <value>
5153 the type of colorspace
5154 -compress <type>
5156 the type of image compression
5157 -debug <events>
5159 enable debug printout
5160 -define <key>{=<value>},...
5162 add coder/decoder specific options
5163 -density <width>x<height>
5165 horizontal and vertical resolution in pixels of the image
5166 -depth <value>
5168 depth of the image
5169 -display <host:display[.screen]>
5171 specifies the X server to contact
5172 -endian <type>
5174 specify endianness (MSB, LSB, or Native) of image
5175 -file <filename>
5177 write annotated difference image to file
5178 -help print usage instructions
5180 -highlight-color <color>
5182 pixel annotation color
5183 -highlight-style <style>
5185 pixel annotation style
5186 -interlace <type>
5188 the type of interlacing scheme
5189 -limit <type> <value>
5191 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
5192 resource limit
5193 -log <string>
5195 Specify format for debug log
5196 -matte store matte channel if the image has one
5198 -maximum-error <limit>
5200 specifies the maximum amount of total image error
5201 -metric <metric>
5203 comparison metric (MAE, MSE, PAE, PSNR, RMSE)
5204 -monitor
5206 show progress indication
5207 -sampling-factor <horizontal_factor>x<vertical_factor>
5209 chroma subsampling factors
5210 -size <width>x<height>{+offset}
5212 width and height of the image
5213 -type <type>
5215 the image type
5216 -verbose
5218 print detailed information about the image
5219 -version
5221 print GraphicsMagick version string
5222 For a more detailed description of each option, see Options,
5224 above.
5225
5228 composite composites (combines) images to create new images. base-im‐
5229 age is the base image and change-image contains the changes. ouput-im‐
5230 age is the result, and normally has the same dimensions as base-image.
5231 The optional mask-image can be used to provide opacity information for
5234 change-image when it has none or if you want a different mask. A mask
5235 image is typically grayscale and the same size as base-image. If mask-
5236 image is not grayscale, it is converted to grayscale and the resulting
5237 intensities are used as opacity information.
5238
5240 To composite an image of a cockatoo with a perch, use:
5241 gm composite cockatoo.miff perch.ras composite.miff
5243 To compute the difference between images in a series, use:
5245 gm composite -compose difference series.2 series.1
5247 difference.miff
5248 To composite an image of a cockatoo with a perch starting at location
5250 (100,150), use:
5251 gm composite -geometry +100+150 cockatoo.miff
5253 perch.ras composite.miff
5254 To tile a logo across your image of a cockatoo, use
5256 gm convert +shade 30x60 cockatoo.miff mask.miff
5258 gm composite -compose bumpmap -tile logo.png
5259 cockatoo.miff mask.miff composite.miff
5260 To composite a red, green, and blue color plane into a single composite
5262 image, try
5263 gm composite -compose CopyGreen green.png red.png
5265 red-green.png
5266 gm composite -compose CopyBlue blue.png red-green.png
5267 gm composite.png
5268
5270 Options are processed in command line order. Any option you specify on
5271 the command line remains in effect only for the image that follows.
5272 All options are reset to their default values after each image is read.
5273 For a more detailed description of each option, see Options, above.
5275 -authenticate <string>
5278 decrypt image with this password
5279 -background <color>
5281 the background color
5282 -blue-primary <x>,<y>
5284 blue chromaticity primary point
5285 -colors <value>
5287 preferred number of colors in the image
5288 -colorspace <value>
5290 the type of colorspace
5291 -comment <string>
5293 annotate an image with a comment
5294 -compose <operator>
5296 the type of image composition
5297 -compress <type>
5299 the type of image compression
5300 -debug <events>
5302 enable debug printout
5303 -define <key>{=<value>},...
5305 add coder/decoder specific options
5306 -density <width>x<height>
5308 horizontal and vertical resolution in pixels of the image
5309 -depth <value>
5311 depth of the image
5312 -displace <horizontal scale>x<vertical scale>
5314 shift image pixels as defined by a displacement map
5315 -display <host:display[.screen]>
5317 specifies the X server to contact
5318 -dispose <method>
5320 GIF disposal method
5321 -dissolve <percent>
5323 dissolve an image into another by the given percent
5324 -dither
5326 apply Floyd/Steinberg error diffusion to the image
5327 -encoding <type>
5329 specify the text encoding
5330 -endian <type>
5332 specify endianness (MSB, LSB, or Native) of image
5333 -filter <type>
5335 use this type of filter when resizing an image
5336 -font <name>
5338 use this font when annotating the image with text
5339 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
5341 Specify dimension, offset, and resize options.
5342 -gravity <type>
5344 direction primitive gravitates to when annotating the image.
5345 -green-primary <x>,<y>
5347 green chromaticity primary point
5348 -help print usage instructions
5350 -interlace <type>
5352 the type of interlacing scheme
5353 -label <name>
5355 assign a label to an image
5356 -limit <type> <value>
5358 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
5359 resource limit
5360 -log <string>
5362 Specify format for debug log
5363 -matte store matte channel if the image has one
5365 -monitor
5367 show progress indication
5368 -monochrome
5370 transform the image to black and white
5371 -negate
5373 replace every pixel with its complementary color
5374 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
5376 size and location of an image canvas
5377 -profile <filename>
5379 add ICM, IPTC, or generic profile to image
5380 -quality <value>
5382 JPEG/MIFF/PNG/TIFF compression level
5383 -recolor <matrix>
5385 apply a color translation matrix to image channels
5386 -red-primary <x>,<y>
5388 red chromaticity primary point
5389 -render
5391 render vector operations
5392 -repage <width>x<height>+xoff+yoff[!]
5394 Adjust image page offsets
5395 -resize <width>x<height>{%}{@}{!}{<}{>}
5397 resize an image
5398 -rotate <degrees>{<}{>}
5400 rotate the image
5401 -sampling-factor <horizontal_factor>x<vertical_factor>
5403 chroma subsampling factors
5404 -scene <value>
5406 set scene number
5407 -set <attribute> <value>
5409 set an image attribute
5410 +set <attribute>
5412 unset an image attribute
5413 -sharpen <radius>{x<sigma>}
5415 sharpen the image
5416 -size <width>x<height>{+offset}
5418 width and height of the image
5419 -stegano <offset>
5421 hide watermark within an image
5422 -stereo
5424 composite two images to create a stereo anaglyph
5425 -strip remove all profiles and text attributes from the image
5427 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
5429 resize an image (quickly)
5430 -treedepth <value>
5432 tree depth for the color reduction algorithm
5433 -trim trim an image
5435 -type <type>
5437 the image type
5438 -units <type>
5440 the units of image resolution
5441 -unsharp <radius>{x<sigma>}{+<amount>}{+<threshold>}
5443 sharpen the image with an unsharp mask operator
5444 -verbose
5446 print detailed information about the image
5447 -version
5449 print GraphicsMagick version string
5450 -watermark <brightness>x<saturation>
5452 percent brightness and saturation of a watermark
5453 -white-point <x>,<y>
5455 chromaticity white point
5456 -write <filename>
5458 write an intermediate image [convert, composite]
5459 For a more detailed description of each option, see Options,
5461 above.
5462
5465 The Magick scripting language (MSL) will primarily benefit those that
5466 want to accomplish custom image processing tasks but do not wish to
5467 program, or those that do not have access to a Perl interpreter or a
5468 compiler. The interpreter is called conjure and here is an example
5469 script:
5470 <?xml version="1.0" encoding="UTF-8"?>
5472 <image size="400x400" >
5473 <read filename="image.gif" />
5474 <get width="base-width" height="base-height" />
5475 <resize geometry="%[dimensions]" />
5476 <get width="width" height="height" />
5477 <print output=
5478 "Image sized from %[base-width]x%[base-height]
5479 to %[width]x%[height].\n" />
5480 <write filename="image.png" />
5481 </image>
5482 invoked with
5484 gm conjure -dimensions 400x400 incantation.msl
5486 All operations will closely follow the key/value pairs defined in Perl‐
5488 Magick, unless otherwise noted.
5489
5491 Options are processed in command line order. Any option you specify on
5492 the command line remains in effect until it is explicitly changed by
5493 specifying the option again with a different effect, or if it is
5494 changed by a statement in the scripting language.
5495 You can define your own keyword/value pairs on the command line. The
5497 script can then use this information when setting values by including
5498 %[keyword] in the string. For example, if you included "-dimensions
5499 400x400" on the command line, as illustrated above, then any string
5500 containing "%[dimensions]" would have 400x400 substituted. The
5501 "%[string]" can be used either an entire string, such as geome‐
5502 try="%[dimensions]" or as a part of a string such as filename="%[base‐
5503 name].png".
5504 The keyword can be any string except for the following reserved strings
5506 (in any upper, lower, or mixed case variant): debug, help, and verbose,
5507 whose usage is described below.
5508 The value can be any string. If either the keyword or the value con‐
5510 tains white space or any symbols that have special meanings to your
5511 shell such as "#", "|", or "%", enclose the string in quotation marks
5512 or use "\" to escape the white space and special symbols.
5513 Keywords and values are case dependent. "Key", "key", and "KEY" would
5515 be three different keywords.
5516 For a more detailed description of each option, see Options, above.
5518 -debug <events>
5521 enable debug printout
5522 -define <key>{=<value>},...
5524 add coder/decoder specific options
5525 -help print usage instructions
5527 -log <string>
5529 Specify format for debug log
5530 -verbose
5532 print detailed information about the image
5533 -version
5535 print GraphicsMagick version string
5536
5538 The Magick Scripting Language (MSL) presently defines the following el‐
5539 ements and their attributes:
5540 <image>
5542 background, color, id, size
5544 Define a new image object. </image> destroys it. Because
5546 of this, if you wish to reference multiple "subimages"
5547 (aka pages or layers), you can embed one image element in‐
5548 side of another. For example:
5549 <image>
5553 <read filename="input.png" />
5554 <get width="base-width" height="base-height" />
5555 <image height="base-height" width="base-width">
5556 <image />
5557 <write filename="output.mng" />
5558 </image>
5559 <image size="400x400" />
5563 <group>
5565 Define a new group of image objects. By default, images
5568 are only valid for the life of their <image>element.
5569 <image> -- creates the image
5573 ..... -- do stuff with it
5574 </image> -- dispose of the image
5575 However, in a group, all images in that group will stay
5578 around for the life of the group:
5579 <group> -- start a group
5583 <image> -- create an image
5584 .... -- do stuff
5585 </image> -- NOOP
5586 <image> -- create another image
5587 .... -- do more stuff
5588 </image> -- NOOP
5589 <write filename="image.mng" /> -- output
5590 </group> -- dispose of both images
5591 <read>
5593 filename
5595 Read a new image from a disk file.
5597 <read filename="image.gif" />
5601 To read two images use
5604 <read filename="image.gif" />
5608 <read filename="image.png />
5609 <write>
5611 filename
5613 Write the image(s) to disk, either as a single multiple-
5614 image file or multiple ones if necessary.
5615 <write filename=image.tiff" />
5619 <get>
5620 Get any attribute recognized by PerlMagick's GetAt‐
5622 tribute() and stores it as an image attribute for later
5623 use. Currently only width and height are supported.
5624 <get width="base-width" height="base-height" />
5627 <print output="Image size is %[base-width]x%[base-height].\n" />
5628 <set>
5630 background, bordercolor, clip-mask, colorspace, density,
5632 magick, mattecolor, opacity. Set an attribute recognized
5633 by PerlMagick's GetAttribute().
5634 <profile>
5635 [profilename]
5637 Read one or more IPTC, ICC or generic profiles from file
5639 and assign to image
5640 <profile iptc="profile.iptc" generic="generic.dat" />
5644 To remove a specified profile use "!" as the filename eg
5647 <profile icm="!" iptc="profile.iptc" />
5651 <border>
5653 fill, geometry, height, width
5655 <blur>
5656 radius, sigma
5658 <charcoal>
5659 radius, sigma
5661 <chop>
5662 geometry, height, width, x, y
5664 <crop>
5665 geometry, height, width, x, y
5667 <composite>
5668 compose, geometry, gravity, image, x, y
5670 <?xml version="1.0" encoding="UTF-8"?>
5673 <group>
5674 <image id="image_01">
5675 <read filename="cloud3.gif"/>
5676 <resize geometry="250x90"/>
5677 </image>
5678 <image id="image_02">
5679 <read filename="cloud4.gif"/>
5680 <resize geometry="190x100"/>
5681 </image>
5682 <image>
5683 <read filename="background.jpg"/>
5684 <composite image="image_01" geometry="+740+470"/>
5685 <composite image="image_02" geometry="+390+415"/>
5686 </image>
5687 <write filename="result.png"/>
5688 </group>
5689 <despeckle>
5691 <emboss>
5693 radius, sigma
5695 <enhance>
5696 <equalize>
5698 <edge>
5700 radius
5702 <flip>
5703 <flop>
5705 <frame>
5707 fill, geometry, height, width, x, y, inner, outer
5709 <flatten>
5710 <get>
5712 height, width
5714 <gamma>
5715 red, green, blue
5717 <image>
5718 background, color, id, size
5720 <implode>
5721 amount
5723 <magnify>
5724 <minify>
5726 <medianfilter>
5728 radius
5730 <normalize>
5731 <oilpaint>
5733 radius
5735 <print>
5736 output
5738 <profile>
5739 [profilename]
5741 <read>
5742 <resize>
5744 blur, filter, geometry, height, width
5746 <roll>
5747 geometry, x, y
5749 <rotate>
5750 degrees
5752 <reducenoise>
5753 radius
5755 <sample>
5756 geometry, height, width
5758 <scale>
5759 geometry, height, width
5761 <sharpen>
5762 radius, sigma
5764 <shave>
5765 geometry, height, width
5767 <shear>
5768 x, y
5770 <solarize>
5771 threshold
5773 <spread>
5774 radius
5776 <stegano>
5777 image
5779 <stereo>
5780 image
5782 <swirl>
5783 degrees
5785 <texture>
5786 image
5788 <threshold>
5789 threshold
5791 <transparent>
5792 color
5794 <trim>
5795
5799 Convert converts an input file using one image format to an output file
5800 with a differing image format. In addition, various types of image pro‐
5801 cessing can be performed on the converted image during the conversion
5802 process. Convert recognizes the image formats listed in GraphicsMag‐
5803 ick(1).
5804
5807 To make a thumbnail of a JPEG image, use:
5808 gm convert -size 120x120 cockatoo.jpg -resize 120x120
5810 +profile "*" thumbnail.jpg
5811 In this example, '-size 120x120' gives a hint to the JPEG decoder that
5813 the image is going to be downscaled to 120x120, allowing it to run
5814 faster by avoiding returning full-resolution images to GraphicsMagick
5815 for the subsequent resizing operation. The ´-resize 120x120' specifies
5816 the desired dimensions of the output image. It will be scaled so its
5817 largest dimension is 120 pixels. The ´+profile "*"' removes any ICM,
5818 EXIF, IPTC, or other profiles that might be present in the input and
5819 aren't needed in the thumbnail.
5820 To convert a MIFF image of a cockatoo to a SUN raster image, use:
5822 gm convert cockatoo.miff sun:cockatoo.ras
5824 To convert a multi-page PostScript document to individual FAX pages,
5826 use:
5827 gm convert -monochrome document.ps fax:page
5829 To convert a TIFF image to a PostScript A4 page with the image in the
5831 lower left-hand corner, use:
5832 gm convert -page A4+0+0 image.tiff document.ps
5834 To convert a raw Gray image with a 128 byte header to a portable
5836 graymap, use:
5837 gm convert -depth 8 -size 768x512+128 gray:raw
5839 image.pgm
5840 In this example, "raw" is the input file. Its format is "gray" and it
5842 has the dimensions and number of header bytes specified by the -size
5843 option and the sample depth specified by the -depth option. The output
5844 file is "image.pgm". The suffix ".pgm" specifies its format.
5845 To convert a Photo CD image to a TIFF image, use:
5847 gm convert -size 1536x1024 img0009.pcd image.tiff
5849 gm convert img0009.pcd[4] image.tiff
5850 To create a visual image directory of all your JPEG images, use:
5852 gm convert 'vid:*.jpg' directory.miff
5854 To annotate an image with blue text using font 12x24 at position
5856 (100,100), use:
5857 gm convert -font helvetica -fill blue
5859 -draw "text 100,100 Cockatoo"
5860 bird.jpg bird.miff
5861 To tile a 640x480 image with a JPEG texture with bumps use:
5863 gm convert -size 640x480 tile:bumps.jpg tiled.png
5865 To surround an icon with an ornamental border to use with Mosaic(1),
5867 use:
5868 gm convert -mattecolor "#697B8F" -frame 6x6 bird.jpg
5870 icon.png
5871 To create a MNG animation from a DNA molecule sequence, use:
5873 gm convert -delay 20 dna.* dna.mng
5875
5877 Options are processed in command line order. Any option you specify on
5878 the command line remains in effect for the set of images that follows,
5879 until the set is terminated by the appearance of any option or -noop.
5880 Some options only affect the decoding of images and others only the en‐
5881 coding. The latter can appear after the final group of input images.
5882 For a more detailed description of each option, see Options, above.
5884 -adjoin
5887 join images into a single multi-image file
5888 -affine <matrix>
5890 drawing transform matrix
5891 -antialias
5893 remove pixel aliasing
5894 -append
5896 append a set of images
5897 -asc-cdl <spec>
5899 apply ASC CDL color transform
5900 -authenticate <string>
5902 decrypt image with this password
5903 -auto-orient
5905 orient (rotate) image so it is upright
5906 -average
5908 average a set of images
5909 -background <color>
5911 the background color
5912 -black-threshold red[,green][,blue][,opacity]
5914 pixels below the threshold become black
5915 -blue-primary <x>,<y>
5917 blue chromaticity primary point
5918 -blur <radius>{x<sigma>}
5920 blur the image with a Gaussian operator
5921 -border <width>x<height>
5923 surround the image with a border of color
5924 -bordercolor <color>
5926 the border color
5927 -box <color>
5929 set the color of the annotation bounding box
5930 -channel <type>
5932 the type of channel
5933 -charcoal <factor>
5935 simulate a charcoal drawing
5936 -chop <width>x<height>{+-}<x>{+-}<y>{%}
5938 remove pixels from the interior of an image
5939 -clip apply the clipping path, if one is present
5941 -coalesce
5943 merge a sequence of images
5944 -colorize <value>
5946 colorize the image with the pen color
5947 -colors <value>
5949 preferred number of colors in the image
5950 -colorspace <value>
5952 the type of colorspace
5953 -comment <string>
5955 annotate an image with a comment
5956 -compose <operator>
5958 the type of image composition
5959 -compress <type>
5961 the type of image compression
5962 -contrast
5964 enhance or reduce the image contrast
5965 -convolve <kernel>
5967 convolve image with the specified convolution kernel
5968 -crop <width>x<height>{+-}<x>{+-}<y>{%}
5970 preferred size and location of the cropped image
5971 -cycle <amount>
5973 displace image colormap by amount
5974 -debug <events>
5976 enable debug printout
5977 -deconstruct
5979 break down an image sequence into constituent parts
5980 -define <key>{=<value>},...
5982 add coder/decoder specific options
5983 -delay <1/100ths of a second>
5985 display the next image after pausing
5986 -density <width>x<height>
5988 horizontal and vertical resolution in pixels of the image
5989 -depth <value>
5991 depth of the image
5992 -despeckle
5994 reduce the speckles within an image
5995 -display <host:display[.screen]>
5997 specifies the X server to contact
5998 -dispose <method>
6000 GIF disposal method
6001 -dither
6003 apply Floyd/Steinberg error diffusion to the image
6004 -draw <string>
6006 annotate an image with one or more graphic primitives
6007 -edge <radius>
6009 detect edges within an image
6010 -emboss <radius>
6012 emboss an image
6013 -encoding <type>
6015 specify the text encoding
6016 -endian <type>
6018 specify endianness (MSB, LSB, or Native) of image
6019 -enhance
6021 apply a digital filter to enhance a noisy image
6022 -equalize
6024 perform histogram equalization to the image
6025 -extent <width>x<height>{+-}<x>{+-}<y>
6027 composite image on background color canvas image
6028 -fill <color>
6030 color to use when filling a graphic primitive
6031 -filter <type>
6033 use this type of filter when resizing an image
6034 -flatten
6036 flatten a sequence of images
6037 -flip create a "mirror image"
6039 -flop create a "mirror image"
6041 -font <name>
6043 use this font when annotating the image with text
6044 -format <string>
6046 output formatted image characteristics
6047 -frame <width>x<height>+<outer bevel width>+<inner bevel width>
6049 surround the image with an ornamental border
6050 -fuzz <distance>{%}
6052 colors within this Euclidean distance are considered equal
6053 -gamma <value>
6055 level of gamma correction
6056 -gaussian <radius>{x<sigma>}
6058 blur the image with a Gaussian operator
6059 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
6061 Specify dimension, offset, and resize options.
6062 -gravity <type>
6064 direction primitive gravitates to when annotating the image.
6065 -green-primary <x>,<y>
6067 green chromaticity primary point
6068 -hald-clut <clut>
6070 apply a Hald CLUT to the image
6071 -help print usage instructions
6073 -implode <factor>
6075 implode image pixels about the center
6076 -intent <type>
6078 use this type of rendering intent when managing the image color
6079 -interlace <type>
6081 the type of interlacing scheme
6082 -label <name>
6084 assign a label to an image
6085 -lat <width>x<height>{+-}<offset>{%}
6087 perform local adaptive thresholding
6088 -level <black_point>{,<gamma>}{,<white_point>}{%}
6090 adjust the level of image contrast
6091 -limit <type> <value>
6093 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
6094 resource limit
6095 -list <type>
6097 the type of list
6098 -log <string>
6100 Specify format for debug log
6101 -loop <iterations>
6103 add Netscape loop extension to your GIF animation
6104 -magnify
6106 magnify the image
6107 -map <filename>
6109 choose a particular set of colors from this image
6110 -mask <filename>
6112 Specify a clipping mask
6113 -matte store matte channel if the image has one
6115 -mattecolor <color>
6117 specify the color to be used with the -frame option
6118 -median <radius>
6120 apply a median filter to the image
6121 -minify <factor>
6123 minify the image
6124 -modulate brightness[,saturation[,hue]]
6126 vary the brightness, saturation, and hue of an image
6127 -monitor
6129 show progress indication
6130 -monochrome
6132 transform the image to black and white
6133 -morph <frames>
6135 morphs an image sequence
6136 -mosaic
6138 create a mosaic from an image or an image sequence
6139 -motion-blur <radius>{x<sigma>}{+angle}
6141 Simulate motion blur
6142 -negate
6144 replace every pixel with its complementary color
6145 -noise <radius|type>
6147 add or reduce noise in an image
6148 -noop NOOP (no option)
6150 -normalize
6152 transform image to span the full range of color values
6153 -opaque <color>
6155 change this color to the pen color within the image
6156 -operator channel operator rvalue[%]
6158 apply a mathematical, bitwise, or value operator to an image
6159 channel
6160 -ordered-dither <channeltype> <NxN>
6162 ordered dither the image
6163 -orient <orientation>
6165 Set the image orientation attribute
6166 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
6168 size and location of an image canvas
6169 -paint <radius>
6171 simulate an oil painting
6172 -pen <color>
6174 (This option has been replaced by the -fill option)
6175 -ping efficiently determine image characteristics
6177 -pointsize <value>
6179 pointsize of the PostScript, X11, or TrueType font
6180 -preview <type>
6182 image preview type
6183 -process <command>
6185 process a sequence of images using a process module
6186 -profile <filename>
6188 add ICM, IPTC, or generic profile to image
6189 -quality <value>
6191 JPEG/MIFF/PNG/TIFF compression level
6192 -raise <width>x<height>
6194 lighten or darken image edges
6195 -random-threshold <channeltype> <LOWxHIGH>
6197 random threshold the image
6198 -recolor <matrix>
6200 apply a color translation matrix to image channels
6201 -red-primary <x>,<y>
6203 red chromaticity primary point
6204 -region <width>x<height>{+-}<x>{+-}<y>
6206 apply options to a portion of the image
6207 -render
6209 render vector operations
6210 -repage <width>x<height>+xoff+yoff[!]
6212 Adjust image page offsets
6213 -resample <horizontal>x<vertical>
6215 Resample image to specified horizontal and vertical resolution
6216 -resize <width>x<height>{%}{@}{!}{<}{>}
6218 resize an image
6219 -roll {+-}<x>{+-}<y>
6221 roll an image vertically or horizontally
6222 -rotate <degrees>{<}{>}
6224 rotate the image
6225 -sample <geometry>
6227 scale image using pixel sampling
6228 -sampling-factor <horizontal_factor>x<vertical_factor>
6230 chroma subsampling factors
6231 -scale <geometry>
6233 scale the image.
6234 -scene <value>
6236 set scene number
6237 -set <attribute> <value>
6239 set an image attribute
6240 +set <attribute>
6242 unset an image attribute
6243 -segment <cluster threshold>x<smoothing threshold>
6245 segment an image
6246 -shade <azimuth>x<elevation>
6248 shade the image using a distant light source
6249 -sharpen <radius>{x<sigma>}
6251 sharpen the image
6252 -shave <width>x<height>{%}
6254 shave pixels from the image edges
6255 -shear <x degrees>x<y degrees>
6257 shear the image along the X or Y axis
6258 -size <width>x<height>{+offset}
6260 width and height of the image
6261 -solarize <factor>
6263 negate all pixels above the threshold level
6264 -spread <amount>
6266 displace image pixels by a random amount
6267 -strip remove all profiles and text attributes from the image
6269 -stroke <color>
6271 color to use when stroking a graphic primitive
6272 -strokewidth <value>
6274 set the stroke width
6275 -swirl <degrees>
6277 swirl image pixels about the center
6278 -texture <filename>
6280 name of texture to tile onto the image background
6281 -threshold <value>{%}
6283 threshold the image
6284 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
6286 resize an image (quickly)
6287 -tile <filename>
6289 tile image when filling a graphic primitive
6290 -transform
6292 transform the image
6293 -transparent <color>
6295 make this color transparent within the image
6296 -treedepth <value>
6298 tree depth for the color reduction algorithm
6299 -trim trim an image
6301 -type <type>
6303 the image type
6304 -units <type>
6306 the units of image resolution
6307 -unsharp <radius>{x<sigma>}{+<amount>}{+<threshold>}
6309 sharpen the image with an unsharp mask operator
6310 -use-pixmap
6312 use the pixmap
6313 -verbose
6315 print detailed information about the image
6316 -version
6318 print GraphicsMagick version string
6319 -view <string>
6321 FlashPix viewing parameters
6322 -virtual-pixel <method>
6324 specify contents of "virtual pixels"
6325 -wave <amplitude>x<wavelength>
6327 alter an image along a sine wave
6328 -white-point <x>,<y>
6330 chromaticity white point
6331 -white-threshold red[,green][,blue][,opacity]
6333 pixels above the threshold become white
6334 -write <filename>
6336 write an intermediate image [convert, composite]
6337 For a more detailed description of each option, see Options,
6339 above.
6340
6342 Display is a machine architecture independent image processing and dis‐
6343 play program. It can display an image on any workstation screen running
6344 an X server. Display can read and write many of the more popular image
6345 formats (e.g. JPEG, TIFF, PNM, Photo CD, etc.).
6346 With display, you can perform these functions on an image:
6348 o load an image from a file
6350 o display the next image
6351 o display the former image
6352 o display a sequence of images as a slide show
6353 o write the image to a file
6354 o print the image to a PostScript printer
6355 o delete the image file
6356 o create a Visual Image Directory
6357 o select the image to display by its thumbnail rather than
6358 name
6359 o undo last image transformation
6360 o copy a region of the image
6361 o paste a region to the image
6362 o restore the image to its original size
6363 o refresh the image
6364 o half the image size
6365 o double the image size
6366 o resize the image
6367 o crop the image
6368 o cut the image
6369 o flop image in the horizontal direction
6370 o flip image in the vertical direction
6371 o rotate the image 90 degrees clockwise
6372 o rotate the image 90 degrees counter-clockwise
6373 o rotate the image
6374 o shear the image
6375 o roll the image
6376 o trim the image edges
6377 o invert the colors of the image
6378 o vary the color brightness
6379 o vary the color saturation
6380 o vary the image hue
6381 o gamma correct the image
6382 o sharpen the image contrast
6383 o dull the image contrast
6384 o perform histogram equalization on the image
6385 o perform histogram normalization on the image
6386 o negate the image colors
6387 o convert the image to grayscale
6388 o set the maximum number of unique colors in the image
6389 o reduce the speckles within an image
6390 o eliminate peak noise from an image
6391 o detect edges within the image
6392 o emboss an image
6393 o segment the image by color
6394 o simulate an oil painting
6395 o simulate a charcoal drawing
6396 o annotate the image with text
6397 o draw on the image
6398 o edit an image pixel color
6399 o edit the image matte information
6400 o composite an image with another
6401 o add a border to the image
6402 o surround image with an ornamental border
6403 o apply image processing techniques to a region of interest
6404 o display information about the image
6405 o zoom a portion of the image
6406 o show a histogram of the image
6407 o display image to background of a window
6408 o set user preferences
6409 o display information about this program
6410 o discard all images and exit program
6411 o change the level of magnification
6412 o display images specified by a World Wide Web (WWW) uniform
6413 resource locator (URL)
6414
6417 To scale an image of a cockatoo to exactly 640 pixels in width and 480
6418 pixels in height and position the window at location (200,200), use:
6419 gm display -geometry 640x480+200+200! cockatoo.miff
6421 To display an image of a cockatoo without a border centered on a back‐
6423 drop, use:
6424 gm display +borderwidth -backdrop cockatoo.miff
6426 To tile a slate texture onto the root window, use:
6428 gm display -size 1280x1024 -window root slate.png
6430 To display a visual image directory of all your JPEG images, use:
6432 gm display 'vid:*.jpg'
6434 To display a MAP image that is 640 pixels in width and 480 pixels in
6436 height with 256 colors, use:
6437 gm display -size 640x480+256 cockatoo.map
6439 To display an image of a cockatoo specified with a World Wide Web (WWW)
6441 uniform resource locator (URL), use:
6442 gm display ftp://wizards.dupont.com/images/cockatoo.jpg
6444 To display histogram of an image, use:
6446 gm gm convert file.jpg HISTOGRAM:- | gm display -
6448
6450 Options are processed in command line order. Any option you specify on
6451 the command line remains in effect until it is explicitly changed by
6452 specifying the option again with a different effect. For example to
6453 display three images, the first with 32 colors, the second with an un‐
6454 limited number of colors, and the third with only 16 colors, use:
6455 gm display -colors 32 cockatoo.miff -noop duck.miff
6457 -colors 16 macaw.miff
6458 Display options can appear on the command line or in your X resources
6460 file. See X(1). Options on the command line supersede values specified
6461 in your X resources file.
6462 For a more detailed description of each option, see Options, above.
6464 -authenticate <string>
6467 decrypt image with this password
6468 -backdrop
6470 display the image centered on a backdrop.
6471 -background <color>
6473 the background color
6474 -border <width>x<height>
6476 surround the image with a border of color
6477 -bordercolor <color>
6479 the border color
6480 -borderwidth <geometry>
6482 the border width
6483 -colormap <type>
6485 define the colormap type
6486 -colors <value>
6488 preferred number of colors in the image
6489 -colorspace <value>
6491 the type of colorspace
6492 -comment <string>
6494 annotate an image with a comment
6495 -compress <type>
6497 the type of image compression
6498 -contrast
6500 enhance or reduce the image contrast
6501 -crop <width>x<height>{+-}<x>{+-}<y>{%}
6503 preferred size and location of the cropped image
6504 -debug <events>
6506 enable debug printout
6507 -define <key>{=<value>},...
6509 add coder/decoder specific options
6510 -delay <1/100ths of a second>
6512 display the next image after pausing
6513 -density <width>x<height>
6515 horizontal and vertical resolution in pixels of the image
6516 -depth <value>
6518 depth of the image
6519 -despeckle
6521 reduce the speckles within an image
6522 -display <host:display[.screen]>
6524 specifies the X server to contact
6525 -dispose <method>
6527 GIF disposal method
6528 -dither
6530 apply Floyd/Steinberg error diffusion to the image
6531 -edge <radius>
6533 detect edges within an image
6534 -endian <type>
6536 specify endianness (MSB, LSB, or Native) of image
6537 -enhance
6539 apply a digital filter to enhance a noisy image
6540 -filter <type>
6542 use this type of filter when resizing an image
6543 -flip create a "mirror image"
6545 -flop create a "mirror image"
6547 -font <name>
6549 use this font when annotating the image with text
6550 -foreground <color>
6552 define the foreground color
6553 -frame <width>x<height>+<outer bevel width>+<inner bevel width>
6555 surround the image with an ornamental border
6556 -gamma <value>
6558 level of gamma correction
6559 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
6561 Specify dimension, offset, and resize options.
6562 -help print usage instructions
6564 -iconGeometry <geometry>
6566 specify the icon geometry
6567 -iconic
6569 iconic animation
6570 -immutable
6572 make image immutable
6573 -interlace <type>
6575 the type of interlacing scheme
6576 -label <name>
6578 assign a label to an image
6579 -limit <type> <value>
6581 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
6582 resource limit
6583 -log <string>
6585 Specify format for debug log
6586 -magnify <factor>
6588 magnify the image
6589 -map <type>
6591 display image using this type.
6592 -matte store matte channel if the image has one
6594 -mattecolor <color>
6596 specify the color to be used with the -frame option
6597 -monitor
6599 show progress indication
6600 -monochrome
6602 transform the image to black and white
6603 -name name an image
6605 -negate
6607 replace every pixel with its complementary color
6608 -noop NOOP (no option)
6610 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
6612 size and location of an image canvas
6613 +progress
6615 disable progress monitor and busy cursor
6616 -quality <value>
6618 JPEG/MIFF/PNG/TIFF compression level
6619 -raise <width>x<height>
6621 lighten or darken image edges
6622 -remote
6624 perform a X11 remote operation
6625 -roll {+-}<x>{+-}<y>
6627 roll an image vertically or horizontally
6628 -rotate <degrees>{<}{>}
6630 rotate the image
6631 -sample <geometry>
6633 scale image using pixel sampling
6634 -sampling-factor <horizontal_factor>x<vertical_factor>
6636 chroma subsampling factors
6637 -scenes <value-value>
6639 range of image scene numbers to read
6640 -set <attribute> <value>
6642 set an image attribute
6643 +set <attribute>
6645 unset an image attribute
6646 -segment <cluster threshold>x<smoothing threshold>
6648 segment an image
6649 -shared-memory
6651 use shared memory
6652 -sharpen <radius>{x<sigma>}
6654 sharpen the image
6655 -size <width>x<height>{+offset}
6657 width and height of the image
6658 -text-font <name>
6660 font for writing fixed-width text
6661 -texture <filename>
6663 name of texture to tile onto the image background
6664 -title <string>
6666 assign title to displayed image [animate, display, montage]
6667 -treedepth <value>
6669 tree depth for the color reduction algorithm
6670 -trim trim an image
6672 -type <type>
6674 the image type
6675 -update <seconds>
6677 detect when image file is modified and redisplay.
6678 -use-pixmap
6680 use the pixmap
6681 -verbose
6683 print detailed information about the image
6684 -version
6686 print GraphicsMagick version string
6687 -visual <type>
6689 animate images using this X visual type
6690 -window <id>
6692 make image the background of a window
6693 -window-group
6695 specify the window group
6696 -write <filename>
6698 write the image to a file [display]
6699 For a more detailed description of each option, see Options,
6701 above.
6702
6705 The effects of each button press is described below. Three buttons are
6706 required. If you have a two button mouse, button 1 and 3 are returned.
6707 Press ALT and button 3 to simulate button 2.
6708 1 Press this button to map or unmap the Command widget . See the
6710 next section for more information about the Command widget.
6711 2 Press and drag to define a region of the image to magnify.
6713 3 Press and drag to choose from a select set of display(1) com‐
6715 mands. This button behaves differently if the image being dis‐
6716 played is a visual image directory. Choose a particular tile of
6717 the directory and press this button and drag to select a command
6718 from a pop-up menu. Choose from these menu items:
6719 Open
6721 Next
6722 Former
6723 Delete
6724 Update
6725 If you choose Open, the image represented by the tile is dis‐
6728 played. To return to the visual image directory, choose Next
6729 from the Command widget (refer to Command Widget). Next and
6730 Former moves to the next or former image respectively. Choose
6731 Delete to delete a particular image tile. Finally, choose Update
6732 to synchronize all the image tiles with their respective images.
6733 See montage and miff for more details.
6734
6736 The Command widget lists a number of sub-menus and commands. They are
6737 File
6739 Open...
6741 Next
6742 Former
6743 Select...
6744 Save...
6745 Print...
6746 Delete...
6747 Canvas...
6748 Visual Directory...
6749 Quit
6750 Edit
6754 Undo
6756 Redo
6757 Cut
6758 Copy
6759 Paste
6760 View
6764 Half Size
6766 Original Size
6767 Double Size
6768 Resize...
6769 Apply
6770 Refresh
6771 Restore
6772 Transform
6776 Crop
6778 Chop
6779 Flop
6780 Flip
6781 Rotate Right
6782 Rotate Left
6783 Rotate...
6784 Shear...
6785 Roll...
6786 Trim Edges
6787 Enhance
6791 Hue...
6793 Saturation...
6794 Brightness...
6795 Gamma...
6796 Spiff...
6797 Dull
6798 Equalize
6799 Normalize
6800 Negate
6801 GRAYscale
6802 Quantize...
6803 Effects
6807 Despeckle
6809 Emboss
6810 Reduce Noise
6811 Add Noise
6812 Sharpen...
6813 Blur...
6814 Threshold...
6815 Edge Detect...
6816 Spread...
6817 Shade...
6818 Raise...
6819 Segment...
6820 F/X
6824 Solarize...
6826 Swirl...
6827 Implode...
6828 Wave...
6829 Oil Paint...
6830 Charcoal Draw...
6831 Image Edit
6835 Annotate...
6837 Draw...
6838 Color...
6839 Matte...
6840 Composite...
6841 Add Border...
6842 Add Frame...
6843 Comment...
6844 Launch...
6845 Region of Interest...
6846 Miscellany
6850 Image Info
6852 Zoom Image
6853 Show Preview...
6854 Show Histogram
6855 Show Matte
6856 Background...
6857 Slide Show
6858 Preferences...
6859 Help
6863 Overview
6865 Browse Documentation
6866 About Display
6867 Menu items with a indented triangle have a sub-menu. They are repre‐
6871 sented above as the indented items. To access a sub-menu item, move the
6872 pointer to the appropriate menu and press button 1 and drag. When you
6873 find the desired sub-menu item, release the button and the command is
6874 executed. Move the pointer away from the sub-menu if you decide not to
6875 execute a particular command.
6876
6878 Accelerators are one or two key presses that effect a particular com‐
6879 mand. The keyboard accelerators that display understands is:
6880 Ctl+O Press to load an image from a file.
6882 space Press to display the next image.
6883 If the image is a multi-paged document such as a PostScript document,
6885 you can skip ahead several pages by preceding this command with a num‐
6886 ber. For example to display the fourth page beyond the current page,
6887 press 4space.
6888 backspace Press to display the former image.
6890 If the image is a multi-paged document such as a PostScript document,
6892 you can skip behind several pages by preceding this command with a num‐
6893 ber. For example to display the fourth page preceding the current
6894 page, press 4n.
6895 Ctl-S Press to save the image to a file.
6897 Ctl-P Press to print the image to a
6898 PostScript printer.
6899 Ctl-D Press to delete an image file.
6900 Ctl-N Press to create a blank canvas.
6901 Ctl-Q Press to discard all images and exit program.
6902 Ctl+Z Press to undo last image transformation.
6903 Ctl+R Press to redo last image transformation.
6904 Ctl-X Press to cut a region of
6905 the image.
6906 Ctl-C Press to copy a region of
6907 the image.
6908 Ctl-V Press to paste a region to
6909 the image.
6910 < Press to halve the image size.
6911 . Press to return to the original image size.
6912 > Press to double the image size.
6913 % Press to resize the image to a width and height
6914 you specify.
6915 Cmd-A Press to make any image transformations
6916 permanent.
6917 By default, any image size transformations are
6918 applied to the original image to create the
6919 image displayed on the X server. However, the
6920 transformations are not permanent (i.e. the
6921 original image does not change size only the
6922 X image does). For example, if you press ">"
6923 the X image will appear to double in size, but
6924 the original image will in fact remain the same
6925 size. To force the original image to double in
6926 size, press ">" followed by "Cmd-A".
6927 @ Press to refresh the image window.
6928 C Press to crop the image.
6929 [ Press to chop the image.
6930 H Press to flop image in the horizontal direction.
6931 V Press to flip image in the vertical direction.
6932 / Press to rotate the image 90 degrees clockwise.
6933 \ Press to rotate the image 90 degrees
6934 counter-clockwise.
6935 * Press to rotate the image
6936 the number of degrees you specify.
6937 S Press to shear the image the number of degrees
6938 you specify.
6939 R Press to roll the image.
6940 T Press to trim the image edges.
6941 Shft-H Press to vary the color hue.
6942 Shft-S Press to vary the color saturation.
6943 Shft-L Press to vary the image brightness.
6944 Shft-G Press to gamma correct the image.
6945 Shft-C Press to spiff up the image contrast.
6946 Shft-Z Press to dull the image contrast.
6947 = Press to perform histogram equalization on
6948 the image.
6949 Shft-N Press to perform histogram normalization on
6950 the image.
6951 Shft-~ Press to negate the colors of the image.
6952 . Press to convert the image colors to gray.
6953 Shft-# Press to set the maximum number of unique
6954 colors in the image.
6955 F2 Press to reduce the speckles in an image.
6956 F2 Press to emboss an image.
6957 F4 Press to eliminate peak noise from an image.
6958 F5 Press to add noise to an image.
6959 F6 Press to sharpen an image.
6960 F7 Press to blur image an image.
6961 F8 Press to threshold the image.
6962 F9 Press to detect edges within an image.
6963 F10 Press to displace pixels by a random amount.
6964 F11 Press to shade the image using a distant light
6965 source.
6966 F12 Press to lighten or darken image edges to
6967 create a 3-D effect.
6968 F13 Press to segment the image by color.
6969 Meta-S Press to swirl image pixels about the center.
6970 Meta-I Press to implode image pixels about the center.
6971 Meta-W Press to alter an image along a sine wave.
6972 Meta-P Press to simulate an oil painting.
6973 Meta-C Press to simulate a charcoal drawing.
6974 Alt-X Press to composite the image
6975 with another.
6976 Alt-A Press to annotate the image with text.
6977 Alt-D Press to draw a line on the image.
6978 Alt-P Press to edit an image pixel color.
6979 Alt-M Press to edit the image matte information.
6980 Alt-X Press to composite the image with another.
6981 Alt-A Press to add a border to the image.
6982 Alt-F Press to add a ornamental frame to the image.
6983 Alt-Shft-! Press to add an image comment.
6984 Ctl-A Press to apply image processing techniques to a
6985 region of interest.
6986 Shft-? Press to display information about the image.
6987 Shft-+ Press to map the zoom image window.
6988 Shft-P Press to preview an image enhancement, effect,
6989 or f/x.
6990 F1 Press to display helpful information about
6991 the "display" utility.
6992 Find Press to browse documentation about
6993 GraphicsMagick.
6994 1-9 Press to change the level of magnification.
6995 Use the arrow keys to move the image one pixel up, down, left, or right
6997 within the magnify window. Be sure to first map the magnify window by
6998 pressing button 2.
6999 Press ALT and one of the arrow keys to trim off one pixel from any side
7001 of the image.
7002
7004 Display options can appear on the command line or in your X resource
7005 file. Options on the command line supersede values specified in your X
7006 resource file. See X(1) for more information on X resources.
7007 Most display options have a corresponding X resource. In addition, dis‐
7009 play uses the following X resources:
7010 background (class Background)
7012 Specifies the preferred color to use for the Image window back‐
7013 ground. The default is #ccc.
7014 borderColor (class BorderColor)
7016 Specifies the preferred color to use for the Image window bor‐
7017 der. The default is #ccc.
7018 borderWidth (class BorderWidth)
7020 Specifies the width in pixels of the image window border. The
7021 default is 2.
7022 browseCommand (class browseCommand)
7024 Specifies the name of the preferred browser when displaying
7025 GraphicsMagick documentation. The default is netscape %s.
7026 confirmExit (class ConfirmExit)
7028 Display pops up a dialog box to confirm exiting the program
7029 when exiting the program. Set this resource to False to exit
7030 without a confirmation.
7031 displayGamma (class DisplayGamma)
7033 Specifies the gamma of the X server. You can apply separate
7034 gamma values to the red, green, and blue channels of the image
7035 with a gamma value list delineated with slashes (i.e.
7036 1.7/2.3/1.2). The default is 2.2.
7037 displayWarnings (class DisplayWarnings)
7039 Display pops up a dialog box whenever a warning message occurs.
7040 Set this resource to False to ignore warning messages.
7041 font (class FontList)
7043 Specifies the name of the preferred font to use in normal for‐
7044 matted text. The default is 14 point Helvetica.
7045 font[1-9] (class Font[1-9])
7047 Specifies the name of the preferred font to use when annotating
7048 the image window with text. The default fonts are fixed, vari‐
7049 able, 5x8, 6x10, 7x13bold, 8x13bold, 9x15bold, 10x20, and 12x24.
7050 foreground (class Foreground)
7052 Specifies the preferred color to use for text within the image
7053 window. The default is black.
7054 gammaCorrect (class gammaCorrect)
7056 This resource, if true, will lighten or darken an image of
7057 known gamma to match the gamma of the display (see resource dis‐
7058 playGamma). The default is True.
7059 geometry (class Geometry)
7061 Specifies the preferred size and position of the image window.
7062 It is not necessarily obeyed by all window managers.
7063 Offsets, if present, are handled in X(1) style. A negative x
7065 offset is measured from the right edge of the screen to the
7066 right edge of the icon, and a negative y offset is measured from
7067 the bottom edge of the screen to the bottom edge of the icon.
7068 iconGeometry (class IconGeometry)
7070 Specifies the preferred size and position of the application
7071 when iconified. It is not necessarily obeyed by all window man‐
7072 agers.
7073 Offsets, if present, are handled in the same manner as in class
7075 Geometry.
7076 iconic (class Iconic)
7078 This resource indicates that you would prefer that the applica‐
7079 tion's windows initially not be visible as if the windows had be
7080 immediately iconified by you. Window managers may choose not to
7081 honor the application's request.
7082 magnify (class Magnify)
7084 specifies an integral factor by which the image should be en‐
7085 larged. The default is 3. This value only affects the magnifi‐
7086 cation window which is invoked with button number 3 after the
7087 image is displayed.
7088 matteColor (class MatteColor)
7090 Specify the color of windows. It is used for the backgrounds of
7091 windows, menus, and notices. A 3D effect is achieved by using
7092 highlight and shadow colors derived from this color. Default
7093 value: #697B8F.
7094 name (class Name)
7096 This resource specifies the name under which resources for the
7097 application should be found. This resource is useful in shell
7098 aliases to distinguish between invocations of an application,
7099 without resorting to creating links to alter the executable file
7100 name. The default is the application name.
7101 pen[1-9] (class Pen[1-9])
7103 Specifies the color of the preferred font to use when annotat‐
7104 ing the image window with text. The default colors are black,
7105 blue, green, cyan, gray, red, magenta, yellow, and white.
7106 printCommand (class PrintCommand)
7108 This command is executed whenever Print is issued. In general,
7109 it is the command to print PostScript to your printer. Default
7110 value: lp -c -s %i.
7111 sharedMemory (class SharedMemory)
7113 This resource specifies whether display should attempt use
7114 shared memory for pixmaps. GraphicsMagick must be compiled with
7115 shared memory support, and the display must support the MIT-SHM
7116 extension. Otherwise, this resource is ignored. The default is
7117 True.
7118 textFont (class textFont)
7120 Specifies the name of the preferred font to use in fixed (type‐
7121 writer style) formatted text. The default is 14 point Courier.
7122 title (class Title)
7124 This resource specifies the title to be used for the image win‐
7125 dow. This information is sometimes used by a window manager to
7126 provide a header identifying the window. The default is the im‐
7127 age file name.
7128 undoCache (class UndoCache)
7130 Specifies, in mega-bytes, the amount of memory in the undo edit
7131 cache. Each time you modify the image it is saved in the undo
7132 edit cache as long as memory is available. You can subsequently
7133 undo one or more of these transformations. The default is 16
7134 Megabytes.
7135 usePixmap (class UsePixmap)
7137 Images are maintained as a XImage by default. Set this resource
7138 to True to utilize a server Pixmap instead. This option is use‐
7139 ful if your image exceeds the dimensions of your server screen
7140 and you intend to pan the image. Panning is much faster with
7141 Pixmaps than with a XImage. Pixmaps are considered a precious
7142 resource, use them with discretion.
7143 To set the geometry of the Magnify or Pan or window, use the ge‐
7145 ometry resource. For example, to set the Pan window geometry to
7146 256x256, use:
7147 gm display.pan.geometry: 256x256
7149
7151 To select an image to display, choose Open of the File sub-menu from
7152 the Command widget. A file browser is displayed. To choose a particu‐
7153 lar image file, move the pointer to the filename and press any button.
7154 The filename is copied to the text window. Next, press Open or press
7155 the RETURN key. Alternatively, you can type the image file name di‐
7156 rectly into the text window. To descend directories, choose a directory
7157 name and press the button twice quickly. A scrollbar allows a large
7158 list of filenames to be moved through the viewing area if it exceeds
7159 the size of the list area.
7160 You can trim the list of file names by using shell globbing characters.
7162 For example, type *.jpg to list only files that end with .jpg.
7163 To select your image from the X server screen instead of from a file,
7165 Choose Grab of the Open widget.
7166
7168 To create a Visual Image Directory, choose Visual Directory of the File
7169 sub-menu from the Command widget . A file browser is displayed. To cre‐
7170 ate a Visual Image Directory from all the images in the current direc‐
7171 tory, press Directory or press the RETURN key. Alternatively, you can
7172 select a set of image names by using shell globbing characters. For ex‐
7173 ample, type *.jpg to include only files that end with .jpg. To descend
7174 directories, choose a directory name and press the button twice
7175 quickly. A scrollbar allows a large list of filenames to be moved
7176 through the viewing area if it exceeds the size of the list area.
7177 After you select a set of files, they are turned into thumbnails and
7179 tiled onto a single image. Now move the pointer to a particular thumb‐
7180 nail and press button 3 and drag. Finally, select Open. The image rep‐
7181 resented by the thumbnail is displayed at its full size. Choose Next
7182 from the File sub-menu of the Command widget to return to the Visual
7183 Image Directory.
7184
7186 Note that cut information for image window is not retained for col‐
7187 ormapped X server visuals (e.g. StaticColor, StaticColor, GRAYScale,
7188 PseudoColor). Correct cutting behavior may require a TrueColor or Di‐
7189 rectColor visual or a Standard Colormap.
7190 To begin, press choose Cut of the Edit sub-menu from the Command wid‐
7192 get. Alternatively, press F3 in the image window.
7193 A small window appears showing the location of the cursor in the image
7195 window. You are now in cut mode. In cut mode, the Command widget has
7196 these options:
7197 Help
7199 Dismiss
7200 To define a cut region, press button 1 and drag. The cut region is de‐
7203 fined by a highlighted rectangle that expands or contracts as it fol‐
7204 lows the pointer. Once you are satisfied with the cut region, release
7205 the button. You are now in rectify mode. In rectify mode, the Command
7206 widget has these options:
7207 Cut
7209 Help
7210 Dismiss
7211 You can make adjustments by moving the pointer to one of the cut rec‐
7214 tangle corners, pressing a button, and dragging. Finally, press Cut to
7215 commit your copy region. To exit without cutting the image, press Dis‐
7216 miss.
7217
7219 To begin, press choose Copy of the Edit sub-menu from the Command wid‐
7220 get. Alternatively, press F4 in the image window.
7221 A small window appears showing the location of the cursor in the image
7223 window. You are now in copy mode. In copy mode, the Command widget has
7224 these options:
7225 Help
7227 Dismiss
7228 To define a copy region, press button 1 and drag. The copy region is
7231 defined by a highlighted rectangle that expands or contracts as it fol‐
7232 lows the pointer. Once you are satisfied with the copy region, release
7233 the button. You are now in rectify mode. In rectify mode, the Command
7234 widget has these options:
7235 Copy
7237 Help
7238 Dismiss
7239 You can make adjustments by moving the pointer to one of the copy rec‐
7242 tangle corners, pressing a button, and dragging. Finally, press Copy to
7243 commit your copy region. To exit without copying the image, press Dis‐
7244 miss.
7245
7247 To begin, press choose Paste of the Edit sub-menu from the Command wid‐
7248 get. Alternatively, press F5 in the image window.
7249 A small window appears showing the location of the cursor in the image
7251 window. You are now in Paste mode. To exit immediately, press Dismiss.
7252 In Paste mode, the Command widget has these options:
7253 Operators
7255 over
7257 in
7258 out
7259 atop
7260 xor
7261 plus
7262 minus
7263 add
7264 subtract
7265 difference
7266 multiply
7267 bumpmap
7268 replace
7269 Help
7271 Dismiss
7272 Choose a composite operation from the Operators sub-menu of the Command
7275 widget. How each operator behaves is described below. image window is
7276 the image currently displayed on your X server and image is the image
7277 obtained with the File Browser widget.
7278 over The result is the union of the two image shapes, with image ob‐
7280 scuring image window in the region of overlap.
7281 in The result is simply image cut by the shape of image window.
7283 None of the image data of image window is in the result.
7284 out The resulting image is image with the shape of image window cut
7286 out.
7287 atop The result is the same shape as image window, with image ob‐
7289 scuring image window where the image shapes overlap. Note this
7290 differs from over because the portion of image outside image
7291 window's shape does not appear in the result.
7292 xor The result is the image data from both image and image window
7294 that is outside the overlap region. The overlap region is blank.
7295 plus The result is just the sum of the image data. Output values are
7297 cropped to the maximum value (no overflow). This operation is
7298 independent of the matte channels.
7299 minus The result of image - image window, with underflow cropped to
7301 zero. The matte channel is ignored (set to opaque, full cover‐
7302 age).
7303 add The result of image + image window, with overflow wrapping
7305 around (mod MaxRGB+1).
7306 subtract
7308 The result of image - image window, with underflow wrapping
7309 around (mod MaxRGB+1). The add and subtract operators can be
7310 used to perform reversible transformations.
7311 difference
7313 The result of abs(image - image window). This is useful for
7314 comparing two very similar images.
7315 multiply
7317 The result of image * image window. This is useful for the cre‐
7318 ation of drop-shadows.
7319 bumpmap
7321 The result of image window shaded by window.
7322 replace
7324 The resulting image is image window replaced with image. Here
7325 the matte information is ignored.
7326 The image compositor requires a matte, or alpha channel in the
7328 image for some operations. This extra channel usually defines a
7329 mask which represents a sort of a cookie-cutter for the image.
7330 This is the case when matte is 255 (full coverage) for pixels
7331 inside the shape, zero outside, and between zero and 255 on the
7332 boundary. If image does not have a matte channel, it is initial‐
7333 ized with 0 for any pixel matching in color to pixel location
7334 (0,0), otherwise 255. See Matte Editing for a method of defining
7335 a matte channel.
7336 Note that matte information for image window is not retained for
7338 colormapped X server visuals (e.g. StaticColor, StaticColor,
7339 GrayScale, PseudoColor). Correct compositing behavior may re‐
7340 quire a TrueColor or DirectColor visual or a Standard Colormap.
7341 Choosing a composite operator is optional. The default operator
7343 is replace. However, you must choose a location to composite
7344 your image and press button 1. Press and hold the button before
7345 releasing and an outline of the image will appear to help you
7346 identify your location.
7347 The actual colors of the pasted image is saved. However, the
7349 color that appears in image window may be different. For exam‐
7350 ple, on a monochrome screen image window will appear black or
7351 white even though your pasted image may have many colors. If the
7352 image is saved to a file it is written with the correct colors.
7353 To assure the correct colors are saved in the final image, any
7354 PseudoClass image is promoted to DirectClass. To force a Pseu‐
7355 doClass image to remain PseudoClass, use -colors.
7356
7358 To begin, press choose Crop of the Transform submenu from the Command
7359 widget. Alternatively, press C in the image window.
7360 A small window appears showing the location of the cursor in the image
7362 window. You are now in crop mode. In crop mode, the Command widget has
7363 these options:
7364 Help
7366 Dismiss
7367 To define a cropping region, press button 1 and drag. The cropping re‐
7370 gion is defined by a highlighted rectangle that expands or contracts as
7371 it follows the pointer. Once you are satisfied with the cropping re‐
7372 gion, release the button. You are now in rectify mode. In rectify mode,
7373 the Command widget has these options:
7374 Crop
7376 Help
7377 Dismiss
7378 You can make adjustments by moving the pointer to one of the cropping
7381 rectangle corners, pressing a button, and dragging. Finally, press Crop
7382 to commit your cropping region. To exit without cropping the image,
7383 press Dismiss.
7384
7386 An image is chopped interactively. There is no command line argument to
7387 chop an image. To begin, choose Chop of the Transform sub-menu from the
7388 Command widget. Alternatively, press [ in the Image window.
7389 You are now in Chop mode. To exit immediately, press Dismiss. In Chop
7391 mode, the Command widget has these options:
7392 Direction
7394 horizontal
7396 vertical
7397 Help
7399 Dismiss
7400 If the you choose the horizontal direction (this is the default), the
7403 area of the image between the two horizontal endpoints of the chop line
7404 is removed. Otherwise, the area of the image between the two vertical
7405 endpoints of the chop line is removed.
7406 Select a location within the image window to begin your chop, press and
7408 hold any button. Next, move the pointer to another location in the im‐
7409 age. As you move a line will connect the initial location and the
7410 pointer. When you release the button, the area within the image to chop
7411 is determined by which direction you choose from the Command widget.
7412 To cancel the image chopping, move the pointer back to the starting
7414 point of the line and release the button.
7415
7417 Press the / key to rotate the image 90 degrees or \ to rotate -90 de‐
7418 grees. To interactively choose the degree of rotation, choose Ro‐
7419 tate... of the Transform submenu from the Command Widget. Alterna‐
7420 tively, press * in the image window.
7421 A small horizontal line is drawn next to the pointer. You are now in
7423 rotate mode. To exit immediately, press Dismiss. In rotate mode, the
7424 Command widget has these options:
7425 Pixel Color
7427 black
7429 blue
7430 cyan
7431 green
7432 gray
7433 red
7434 magenta
7435 yellow
7436 white
7437 Browser...
7438 Direction
7440 horizontal
7442 vertical
7443 Help
7445 Dismiss
7446 Choose a background color from the Pixel Color sub-menu. Additional
7449 background colors can be specified with the color browser. You can
7450 change the menu colors by setting the X resources pen1 through pen9.
7451 If you choose the color browser and press Grab, you can select the
7453 background color by moving the pointer to the desired color on the
7454 screen and press any button.
7455 Choose a point in the image window and press this button and hold.
7457 Next, move the pointer to another location in the image. As you move a
7458 line connects the initial location and the pointer. When you release
7459 the button, the degree of image rotation is determined by the slope of
7460 the line you just drew. The slope is relative to the direction you
7461 choose from the Direction sub-menu of the Command widget.
7462 To cancel the image rotation, move the pointer back to the starting
7464 point of the line and release the button.
7465
7467 An image is annotated interactively. There is no command line argument
7468 to annotate an image. To begin, choose Annotate of the Image Edit sub-
7469 menu from the Command widget. Alternatively, press a in the image win‐
7470 dow.
7471 A small window appears showing the location of the cursor in the image
7473 window. You are now in annotate mode. To exit immediately, press Dis‐
7474 miss. In annotate mode, the Command widget has these options:
7475 Font Name
7478 fixed
7481 variable
7483 5x8
7485 6x10
7487 7x13bold
7489 8x13bold
7491 9x15bold
7493 10x20
7495 12x24
7497 Browser...
7499 Font Color
7502 black
7505 blue
7507 cyan
7509 green
7511 gray
7513 red
7515 magenta
7517 yellow
7519 white
7521 transparent
7523 Browser...
7525 Box Color
7528 black
7531 blue
7533 cyan
7535 green
7537 gray
7539 red
7541 magenta
7543 yellow
7545 white
7547 transparent
7549 Browser...
7551 Rotate Text
7554 -90
7557 -45
7559 -30
7561 0
7563 30
7565 45
7567 90
7569 180
7571 Dialog...
7573 Help
7576 Dismiss
7578 Choose a font name from the Font Name sub-menu. Additional font names
7581 can be specified with the font browser. You can change the menu names
7582 by setting the X resources font1 through font9.
7583 Choose a font color from the Font Color sub-menu. Additional font col‐
7585 ors can be specified with the color browser. You can change the menu
7586 colors by setting the X resources pen1 through pen9.
7587 If you select the color browser and press Grab, you can choose the font
7589 color by moving the pointer to the desired color on the screen and
7590 press any button.
7591 If you choose to rotate the text, choose Rotate Text from the menu and
7593 select an angle. Typically you will only want to rotate one line of
7594 text at a time. Depending on the angle you choose, subsequent lines may
7595 end up overwriting each other.
7596 Choosing a font and its color is optional. The default font is fixed
7598 and the default color is black. However, you must choose a location to
7599 begin entering text and press a button. An underscore character will
7600 appear at the location of the pointer. The cursor changes to a pencil
7601 to indicate you are in text mode. To exit immediately, press Dismiss.
7602 In text mode, any key presses will display the character at the loca‐
7604 tion of the underscore and advance the underscore cursor. Enter your
7605 text and once completed press Apply to finish your image annotation. To
7606 correct errors press BACK SPACE. To delete an entire line of text,
7607 press DELETE. Any text that exceeds the boundaries of the image window
7608 is automatically continued onto the next line.
7609 The actual color you request for the font is saved in the image. How‐
7611 ever, the color that appears in your Image window may be different. For
7612 example, on a monochrome screen the text will appear black or white
7613 even if you choose the color red as the font color. However, the image
7614 saved to a file with -write is written with red lettering. To assure
7615 the correct color text in the final image, any PseudoClass image is
7616 promoted to DirectClass (see miff(5)). To force a PseudoClass image to
7617 remain PseudoClass, use -colors.
7618
7620 An image composite is created interactively. There is no command line
7621 argument to composite an image. To begin, choose Composite of the Image
7622 Edit from the Command widget. Alternatively, press x in the Image win‐
7623 dow.
7624 First a popup window is displayed requesting you to enter an image
7626 name. Press Composite, Grab or type a file name. Press Cancel if you
7627 choose not to create a composite image. When you choose Grab, move the
7628 pointer to the desired window and press any button.
7629 If the Composite image does not have any matte information, you are in‐
7631 formed and the file browser is displayed again. Enter the name of a
7632 mask image. The image is typically grayscale and the same size as the
7633 composite image. If the image is not grayscale, it is converted to
7634 grayscale and the resulting intensities are used as matte information.
7635 A small window appears showing the location of the cursor in the image
7637 window. You are now in composite mode. To exit immediately, press Dis‐
7638 miss. In composite mode, the Command widget has these options:
7639 Operators
7642 over
7645 in
7647 out
7649 atop
7651 xor
7653 plus
7655 minus
7657 add
7659 subtract
7661 difference
7663 bumpmap
7665 replace
7667 Blend
7670 Displace
7672 Help
7674 Dismiss
7676 Choose a composite operation from the Operators sub-menu of the Command
7679 widget. How each operator behaves is described below. image window is
7680 the image currently displayed on your X server and image is the image
7681 obtained
7682 over The result is the union of the two image shapes, with image ob‐
7684 scuring image window in the region of overlap.
7685 in The result is simply image cut by the shape of image window.
7687 None of the image data of image window is in the result.
7688 out The resulting image is image with the shape of image window cut
7690 out.
7691 atop The result is the same shape as image window, with image ob‐
7693 scuring image window where the image shapes overlap. Note this
7694 differs from over because the portion of image outside image
7695 window's shape does not appear in the result.
7696 xor The result is the image data from both image and image window
7698 that is outside the overlap region. The overlap region is blank.
7699 plus The result is just the sum of the image data. Output values are
7701 cropped to 255 (no overflow). This operation is independent of
7702 the matte channels.
7703 minus The result of image - image window, with underflow cropped to
7705 zero. The matte channel is ignored (set to 255, full coverage).
7706 add The result of image + image window, with overflow wrapping
7708 around (mod 256).
7709 subtract
7711 The result of image - image window, with underflow wrapping
7712 around (mod 256). The add and subtract operators can be used to
7713 perform reversible transformations.
7714 difference
7716 The result of abs(image - image window). This is useful for
7717 comparing two very similar images.
7718 bumpmap
7720 The result of image window shaded by window.
7721 replace
7723 The resulting image is image window replaced with image. Here
7724 the matte information is ignored.
7725 The image compositor requires a matte, or alpha channel in the
7727 image for some operations. This extra channel usually defines a
7728 mask which represents a sort of a cookie-cutter for the image.
7729 This is the case when matte is 255 (full coverage) for pixels
7730 inside the shape, zero outside, and between zero and 255 on the
7731 boundary. If image does not have a matte channel, it is initial‐
7732 ized with 0 for any pixel matching in color to pixel location
7733 (0,0), otherwise 255. See Matte Editing for a method of defining
7734 a matte channel.
7735 If you choose blend, the composite operator becomes over. The
7737 image matte channel percent transparency is initialized to fac‐
7738 tor. The image window is initialized to (100-factor). Where
7739 factor is the value you specify in the Dialog widget.
7740 Displace shifts the image pixels as defined by a displacement
7742 map. With this option, image is used as a displacement map.
7743 Black, within the displacement map, is a maximum positive dis‐
7744 placement. White is a maximum negative displacement and middle
7745 gray is neutral. The displacement is scaled to determine the
7746 pixel shift. By default, the displacement applies in both the
7747 horizontal and vertical directions. However, if you specify
7748 mask, image is the horizontal X displacement and mask the verti‐
7749 cal Y displacement.
7750 Note that matte information for image window is not retained for
7752 colormapped X server visuals (e.g. StaticColor, StaticColor,
7753 GrayScale, PseudoColor). Correct compositing behavior may re‐
7754 quire a TrueColor or DirectColor visual or a Standard Colormap.
7755 Choosing a composite operator is optional. The default operator
7757 is replace. However, you must choose a location to composite
7758 your image and press button 1. Press and hold the button before
7759 releasing and an outline of the image will appear to help you
7760 identify your location.
7761 The actual colors of the composite image is saved. However, the
7763 color that appears in image window may be different. For exam‐
7764 ple, on a monochrome screen Image window will appear black or
7765 white even though your composited image may have many colors. If
7766 the image is saved to a file it is written with the correct col‐
7767 ors. To assure the correct colors are saved in the final image,
7768 any PseudoClass image is promoted to DirectClass (see miff). To
7769 force a PseudoClass image to remain PseudoClass, use -colors.
7770
7772 Changing the the color of a set of pixels is performed interactively.
7773 There is no command line argument to edit a pixel. To begin, choose
7774 Color from the Image Edit submenu of the Command widget. Alterna‐
7775 tively, press c in the image window.
7776 A small window appears showing the location of the cursor in the image
7778 window. You are now in color edit mode. To exit immediately, press Dis‐
7779 miss. In color edit mode, the Command widget has these options:
7780 Method
7783 point
7786 replace
7788 floodfill
7790 reset
7792 Pixel Color
7795 black
7798 blue
7800 cyan
7802 green
7804 gray
7806 red
7808 magenta
7810 yellow
7812 white
7814 Browser...
7816 Border Color
7819 black
7822 blue
7824 cyan
7826 green
7828 gray
7830 red
7832 magenta
7834 yellow
7836 white
7838 Browser...
7840 Fuzz
7843 0
7846 2
7848 4
7850 8
7852 16
7854 Dialog...
7855 Undo
7858 Help
7860 Dismiss
7862 Choose a color editing method from the Method sub-menu of the Command
7865 widget. The point method recolors any pixel selected with the pointer
7866 unless the button is released. The replace method recolors any pixel
7867 that matches the color of the pixel you select with a button press.
7868 Floodfill recolors any pixel that matches the color of the pixel you
7869 select with a button press and is a neighbor. Whereas filltoborder
7870 changes the matte value of any neighbor pixel that is not the border
7871 color. Finally reset changes the entire image to the designated color.
7872 Next, choose a pixel color from the Pixel Color sub-menu. Additional
7874 pixel colors can be specified with the color browser. You can change
7875 the menu colors by setting the X resources pen1 through pen9.
7876 Now press button 1 to select a pixel within the Image window to change
7878 its color. Additional pixels may be recolored as prescribed by the
7879 method you choose. additional pixels by increasing the Delta value.
7880 If the Magnify widget is mapped, it can be helpful in positioning your
7882 pointer within the image (refer to button 2). Alternatively you can se‐
7883 lect a pixel to recolor from within the Magnify widget. Move the
7884 pointer to the Magnify widget and position the pixel with the cursor
7885 control keys. Finally, press a button to recolor the selected pixel (or
7886 pixels).
7887 The actual color you request for the pixels is saved in the image. How‐
7889 ever, the color that appears in your Image window may be different. For
7890 example, on a monochrome screen the pixel will appear black or white
7891 even if you choose the color red as the pixel color. However, the image
7892 saved to a file with -write is written with red pixels. To assure the
7893 correct color text in the final image, any PseudoClass image is pro‐
7894 moted to DirectClass To force a PseudoClass image to remain Pseudo‐
7895 Class, use -colors.
7896
7898 Matte information within an image is useful for some operations such as
7899 image compositing. This extra channel usually defines a mask which rep‐
7900 resents a sort of a cookie-cutter for the image. This is the case when
7901 matte is 255 (full coverage) for pixels inside the shape, zero outside,
7902 and between zero and 255 on the boundary.
7903 Setting the matte information in an image is done interactively. There
7905 is no command line argument to edit a pixel. To begin, and choose Matte
7906 of the Image Edit sub-menu from the Command widget.
7907 Alternatively, press m in the image window.
7909 A small window appears showing the location of the cursor in the image
7911 window. You are now in matte edit mode. To exit immediately, press Dis‐
7912 miss. In matte edit mode, the Command widget has these options:
7913 Method
7916 point
7919 replace
7921 floodfill
7923 reset
7925 Border Color
7928 black
7931 blue
7933 cyan
7935 green
7937 gray
7939 red
7941 magenta
7943 yellow
7945 white
7947 Browser...
7949 Fuzz
7952 0
7955 2
7957 4
7959 8
7961 16
7963 Dialog...
7964 Matte
7967 Undo
7969 Help
7971 Dismiss
7973 Choose a matte editing method from the Method sub-menu of the Command
7975 widget. The point method changes the matte value of the any pixel se‐
7976 lected with the pointer until the button is released. The replace
7977 method changes the matte value of any pixel that matches the color of
7978 the pixel you select with a button press. Floodfill changes the matte
7979 value of any pixel that matches the color of the pixel you select with
7980 a button press and is a neighbor. Whereas filltoborder recolors any
7981 neighbor pixel that is not the border color. Finally reset changes the
7982 entire image to the designated matte value. Choose Matte Value and a
7983 dialog appears requesting a matte value. Enter a value between 0 and
7984 255. This value is assigned as the matte value of the selected pixel or
7985 pixels. Now, press any button to select a pixel within the Image win‐
7986 dow to change its matte value. You can change the matte value of addi‐
7987 tional pixels by increasing the Delta value. The Delta value is first
7988 added then subtracted from the red, green, and blue of the target
7989 color. Any pixels within the range also have their matte value updated.
7990 If the Magnify widget is mapped, it can be helpful in positioning your
7991 pointer within the image (refer to button 2). Alternatively you can se‐
7992 lect a pixel to change the matte value from within the Magnify widget.
7993 Move the pointer to the Magnify widget and position the pixel with the
7994 cursor control keys. Finally, press a button to change the matte value
7995 of the selected pixel (or pixels). Matte information is only valid in
7996 a DirectClass image. Therefore, any PseudoClass image is promoted to
7997 DirectClass. Note that matte information for PseudoClass is not re‐
7998 tained for colormapped X server visuals (e.g. StaticColor, StaticColor,
7999 GrayScale, PseudoColor) unless you immediately save your image to a
8000 file (refer to Write). Correct matte editing behavior may require a
8001 TrueColor or DirectColor visual or a Standard Colormap.
8002
8004 An image is drawn upon interactively. There is no command line argument
8005 to draw on an image. To begin, choose Draw of the Image Edit sub-menu
8006 from the Command widget. Alternatively, press d in the image window.
8007 The cursor changes to a crosshair to indicate you are in draw mode. To
8009 exit immediately, press Dismiss. In draw mode, the Command widget has
8010 these options:
8011 Primitive
8014 point
8017 line
8019 rectangle
8021 fill rectangle
8023 circle
8025 fill circle
8027 ellipse
8029 fill ellipse
8031 polygon
8033 fill polygon
8035 Color
8038 black
8041 blue
8043 cyan
8045 green
8047 gray
8049 red
8051 magenta
8053 yellow
8055 white
8057 transparent
8059 Browser...
8061 Stipple
8064 Brick
8067 Diagonal
8069 Scales
8071 Vertical
8073 Wavy
8075 Translucent
8077 Opaque
8079 Open...
8081 Width
8084 1
8087 2
8089 4
8091 8
8093 16
8095 Dialog...
8096 Undo
8099 Help
8101 Dismiss
8103 Choose a drawing primitive from the Primitive sub-menu.
8105 Next, choose a color from the Color sub-menu. Additional colors can be
8107 specified with the color browser. You can change the menu colors by
8108 setting the X resources pen1 through pen9. The transparent color up‐
8109 dates the image matte channel and is useful for image compositing.
8110 If you choose the color browser and press Grab, you can select the
8112 primitive color by moving the pointer to the desired color on the
8113 screen and press any button. The transparent color updates the image
8114 matte channel and is useful for image compositing.
8115 Choose a stipple, if appropriate, from the Stipple sub-menu. Additional
8117 stipples can be specified with the file browser. Stipples obtained from
8118 the file browser must be on disk in the X11 bitmap format.
8119 Choose a line width, if appropriate, from the Width sub-menu. To choose
8121 a specific width select the Dialog widget.
8122 Choose a point in the image window and press button 1 and hold. Next,
8124 move the pointer to another location in the image. As you move, a line
8125 connects the initial location and the pointer. When you release the
8126 button, the image is updated with the primitive you just drew. For
8127 polygons, the image is updated when you press and release the button
8128 without moving the pointer.
8129 To cancel image drawing, move the pointer back to the starting point of
8131 the line and release the button.
8132
8134 To begin, press choose Region of Interest of the Pixel Transform sub-
8135 menu from the Command widget. Alternatively, press R in the image win‐
8136 dow.
8137 A small window appears showing the location of the cursor in the image
8139 window. You are now in region of interest mode. In region of interest
8140 mode, the Command widget has these options:
8141 Help
8144 Dismiss
8146 To define a region of interest, press button 1 and drag. The region of
8149 interest is defined by a highlighted rectangle that expands or con‐
8150 tracts as it follows the pointer. Once you are satisfied with the re‐
8151 gion of interest, release the button. You are now in apply mode. In ap‐
8152 ply mode the Command widget has these options:
8153 File
8156 Save...
8159 Print...
8161 Edit
8164 Undo
8167 Redo
8169 Transform
8172 Flip
8175 Flop
8177 Rotate Right
8179 Rotate Left
8181 Enhance
8184 Hue...
8187 Saturation...
8189 Brightness...
8191 Gamma...
8193 Spiff
8195 Dull
8197 Equalize
8199 Normalize
8201 Negate
8203 GRAYscale
8205 Quantize...
8207 Effects
8210 Despeckle
8213 Emboss
8215 Reduce Noise
8217 Add Noise
8219 Sharpen...
8221 Blur...
8223 Threshold...
8225 Edge Detect...
8227 Spread...
8229 Shade...
8231 Raise...
8233 Segment...
8235 F/X
8240 Solarize...
8243 Swirl...
8245 Implode...
8247 Wave...
8249 Oil Paint
8251 Charcoal Draw...
8253 Miscellany
8258 Image Info
8261 Zoom Image
8263 Show Preview...
8265 Show Histogram
8267 Show Matte
8269 Help
8272 Dismiss
8274 You can make adjustments to the region of interest by moving the
8277 pointer to one of the rectangle corners, pressing a button, and drag‐
8278 ging. Finally, choose an image processing technique from the Command
8279 widget. You can choose more than one image processing technique to ap‐
8280 ply to an area. Alternatively, you can move the region of interest be‐
8281 fore applying another image processing technique. To exit, press Dis‐
8282 miss.
8283
8285 When an image exceeds the width or height of the X server screen, dis‐
8286 play maps a small panning icon. The rectangle within the panning icon
8287 shows the area that is currently displayed in the the image window. To
8288 pan about the image, press any button and drag the pointer within the
8289 panning icon. The pan rectangle moves with the pointer and the image
8290 window is updated to reflect the location of the rectangle within the
8291 panning icon. When you have selected the area of the image you wish to
8292 view, release the button.
8293 Use the arrow keys to pan the image one pixel up, down, left, or right
8295 within the image window.
8296 The panning icon is withdrawn if the image becomes smaller than the di‐
8298 mensions of the X server screen.
8299
8301 Preferences affect the default behavior of display(1). The preferences
8302 are either true or false and are stored in your home directory as .dis‐
8303 playrc:
8304 display image centered on a backdrop"
8306 This backdrop covers the entire workstation screen and is
8309 useful for hiding other X window activity while viewing
8310 the image. The color of the backdrop is specified as the
8311 background color. Refer to X Resources for details.
8312 confirm on program exit"
8313 Ask for a confirmation before exiting the display(1) pro‐
8316 gram.
8317 correct image for display gamma"
8318 If the image has a known gamma, the gamma is corrected to
8321 match that of the X server (see the X Resource dis‐
8322 playGamma).
8323 display warning messages"
8324 Display any warning messages.
8327 apply Floyd/Steinberg error diffusion to image"
8328 The basic strategy of dithering is to trade intensity res‐
8331 olution for spatial resolution by averaging the intensi‐
8332 ties of several neighboring pixels. Images which suffer
8333 from severe contouring when reducing colors can be im‐
8334 proved with this preference.
8335 use a shared colormap for colormapped X visuals"
8336 This option only applies when the default X server visual
8339 is PseudoColor or GRAYScale. Refer to -visual for more de‐
8340 tails. By default, a shared colormap is allocated. The im‐
8341 age shares colors with other X clients. Some image colors
8342 could be approximated, therefore your image may look very
8343 different than intended. Otherwise the image colors appear
8344 exactly as they are defined. However, other clients may go
8345 technicolor when the image colormap is installed.
8346 display images as an X server pixmap"
8347 Images are maintained as a XImage by default. Set this re‐
8350 source to True to utilize a server Pixmap instead. This
8351 option is useful if your image exceeds the dimensions of
8352 your server screen and you intend to pan the image. Pan‐
8353 ning is much faster with Pixmaps than with a XImage.
8354 Pixmaps are considered a precious resource, use them with
8355 discretion.
8356 GM IDENTIFY
8360 Identify describes the format and characteristics of one or more
8362 image files as internally supported by the software. It will
8363 also report if an image is incomplete or corrupt. The informa‐
8364 tion displayed includes the scene number, the file name, the
8365 width and height of the image, whether the image is colormapped
8366 or not, the number of colors in the image, the number of bytes
8367 in the image, the format of the image (JPEG, PNM, etc.), and fi‐
8368 nally the number of seconds in both user time and elapsed time
8369 it took to read and process the image. If -verbose or +ping are
8370 provided as an option, the pixel read rate is also displayed. An
8371 example line output from identify follows:
8372 images/aquarium.miff 640x480 PseudoClass 256c
8374 308135b MIFF 0.000u 0:01
8375 If -verbose is set, expect additional output including any image
8377 comment:
8378 Image: images/aquarium.miff
8381 class: PseudoClass
8382 colors: 256
8383 signature: eb5dca81dd93ae7e6ffae99a527eb5dca8...
8384 matte: False
8385 geometry: 640x480
8386 depth: 8
8387 bytes: 308135
8388 format: MIFF
8389 comments:
8390 Imported from MTV raster image: aquarium.mtv
8391 For some formats, additional format-specific information about
8393 the file will be written if the -debug coder or -debug all op‐
8394 tion is used.
8395
8397 Options are processed in command line order. Any option you specify on
8398 the command line remains in effect for the set of images immediately
8399 following, until the set is terminated by the appearance of any option
8400 or -noop.
8401 For a more detailed description of each option, see Options, above.
8403 -authenticate <string>
8406 decrypt image with this password
8407 -debug <events>
8409 enable debug printout
8410 -define <key>{=<value>},...
8412 add coder/decoder specific options
8413 -density <width>x<height>
8415 horizontal and vertical resolution in pixels of the image
8416 -depth <value>
8418 depth of the image
8419 -format <string>
8421 output formatted image characteristics
8422 -help print usage instructions
8424 -interlace <type>
8426 the type of interlacing scheme
8427 -limit <type> <value>
8429 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
8430 resource limit
8431 -log <string>
8433 Specify format for debug log
8434 -ping efficiently determine image characteristics
8436 -sampling-factor <horizontal_factor>x<vertical_factor>
8438 chroma subsampling factors
8439 -size <width>x<height>{+offset}
8441 width and height of the image
8442 -verbose
8444 print detailed information about the image
8445 -version
8447 print GraphicsMagick version string
8448 For a more detailed description of each option, see Options,
8450 above.
8451
8454 Import reads an image from any visible window on an X server and out‐
8455 puts it as an image file. You can capture a single window, the entire
8456 screen, or any rectangular portion of the screen. Use display for re‐
8457 display, printing, editing, formatting, archiving, image processing,
8458 etc. of the captured image.
8459 The target window can be specified by id, name, or may be selected by
8461 clicking the mouse in the desired window. If you press a button and
8462 then drag, a rectangle will form which expands and contracts as the
8463 mouse moves. To save the portion of the screen defined by the rectan‐
8464 gle, just release the button. The keyboard bell is rung once at the be‐
8465 ginning of the screen capture and twice when it completes.
8466
8468 To select an X window or an area of the screen with the mouse and save
8469 it in the MIFF image format to a file entitled window.miff, use:
8470 gm import window.miff
8472 To select an X window or an area of the screen with the mouse and save
8474 it in the Encapsulated PostScript format to include in another docu‐
8475 ment, use:
8476 gm import figure.eps
8478 To capture the entire X server screen in the JPEG image format in a
8480 file entitled root.jpeg, without using the mouse, use:
8481 gm import -window root root.jpeg
8483 To capture the 512x256 area at the upper right corner of the X server
8485 screen in the PNG image format in a well-compressed file entitled cor‐
8486 ner.png, without using the mouse, use:
8487 gm import -window root -crop 512x256-0+0 -quality 90
8489 corner.png
8490
8492 Options are processed in command line order. Any option you specify on
8493 the command line remains in effect until it is explicitly changed by
8494 specifying the option again with a different effect.
8495 Import options can appear on the command line or in your X resources
8497 file. See X(1). Options on the command line supersede values specified
8498 in your X resources file.
8499 For a more detailed description of each option, see Options, above.
8501 -bordercolor <color>
8504 the border color
8505 -colors <value>
8507 preferred number of colors in the image
8508 -colorspace <value>
8510 the type of colorspace
8511 -comment <string>
8513 annotate an image with a comment
8514 -crop <width>x<height>{+-}<x>{+-}<y>{%}
8516 preferred size and location of the cropped image
8517 -debug <events>
8519 enable debug printout
8520 -define <key>{=<value>},...
8522 add coder/decoder specific options
8523 -delay <1/100ths of a second>
8525 display the next image after pausing
8526 -density <width>x<height>
8528 horizontal and vertical resolution in pixels of the image
8529 -depth <value>
8531 depth of the image
8532 -descend
8534 obtain image by descending window hierarchy
8535 -display <host:display[.screen]>
8537 specifies the X server to contact
8538 -dispose <method>
8540 GIF disposal method
8541 -dither
8543 apply Floyd/Steinberg error diffusion to the image
8544 -encoding <type>
8546 specify the text encoding
8547 -endian <type>
8549 specify endianness (MSB, LSB, or Native) of image
8550 -frame include the X window frame in the imported image
8552 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
8554 Specify dimension, offset, and resize options.
8555 -help print usage instructions
8557 -interlace <type>
8559 the type of interlacing scheme
8560 -label <name>
8562 assign a label to an image
8563 -limit <type> <value>
8565 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
8566 resource limit
8567 -log <string>
8569 Specify format for debug log
8570 -monitor
8572 show progress indication
8573 -monochrome
8575 transform the image to black and white
8576 -negate
8578 replace every pixel with its complementary color
8579 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
8581 size and location of an image canvas
8582 -pause <seconds>
8584 pause between snapshots [import]
8585 -ping efficiently determine image characteristics
8587 -pointsize <value>
8589 pointsize of the PostScript, X11, or TrueType font
8590 -quality <value>
8592 JPEG/MIFF/PNG/TIFF compression level
8593 -resize <width>x<height>{%}{@}{!}{<}{>}
8595 resize an image
8596 -rotate <degrees>{<}{>}
8598 rotate the image
8599 -sampling-factor <horizontal_factor>x<vertical_factor>
8601 chroma subsampling factors
8602 -scene <value>
8604 set scene number
8605 -screen
8607 specify the screen to capture
8608 -set <attribute> <value>
8610 set an image attribute
8611 +set <attribute>
8613 unset an image attribute
8614 -silent
8616 operate silently
8617 -snaps <value>
8619 number of screen snapshots
8620 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
8622 resize an image (quickly)
8623 -transparent <color>
8625 make this color transparent within the image
8626 -trim trim an image
8628 -verbose
8630 print detailed information about the image
8631 -version
8633 print GraphicsMagick version string
8634 For a more detailed description of each option, see Options,
8636 above.
8637
8640 Mogrify transforms an image or a sequence of images. These transforms
8641 include image scaling, image rotation, color reduction, and others.
8642 Each transmogrified image overwrites the corresponding original image,
8643 unless an option such as -format causes the output filename to be dif‐
8644 ferent from the input filename.
8645 The graphics formats supported by mogrify are listed in GraphicsMag‐
8647 ick(1).
8648
8650 To convert all the TIFF files in a particular directory to JPEG, use:
8651 gm mogrify -format jpeg *.tiff
8653 To convert a directory full of JPEG images to thumbnails, use:
8655 gm mogrify -size 120x120 *.jpg -resize 120x120 +profile "*"
8657 In this example, '-size 120x120' gives a hint to the JPEG decoder that
8659 the images are going to be downscaled to 120x120, allowing it to run
8660 faster by avoiding returning full-resolution images to GraphicsMagick
8661 for the subsequent resizing operation. The ´-resize 120x120' specifies
8662 the desired dimensions of the output images. It will be scaled so its
8663 largest dimension is 120 pixels. The ´+profile "*"' removes any ICM,
8664 EXIF, IPTC, or other profiles that might be present in the input and
8665 aren't needed in the thumbnails.
8666 To scale an image of a cockatoo to exactly 640 pixels in width and 480
8668 pixels in height, use:
8669 gm mogrify -resize 640x480! cockatoo.miff
8671
8673 Options are processed in command line order. Any option you specify on
8674 the command line remains in effect for the set of images that follows,
8675 until the set is terminated by the appearance of any option or -noop.
8676 For a more detailed description of each option, see Options, above.
8678 -affine <matrix>
8681 drawing transform matrix
8682 -antialias
8684 remove pixel aliasing
8685 -asc-cdl <spec>
8687 apply ASC CDL color transform
8688 -authenticate <string>
8690 decrypt image with this password
8691 -auto-orient
8693 orient (rotate) image so it is upright
8694 -background <color>
8696 the background color
8697 -black-threshold red[,green][,blue][,opacity]
8699 pixels below the threshold become black
8700 -blue-primary <x>,<y>
8702 blue chromaticity primary point
8703 -blur <radius>{x<sigma>}
8705 blur the image with a Gaussian operator
8706 -border <width>x<height>
8708 surround the image with a border of color
8709 -bordercolor <color>
8711 the border color
8712 -channel <type>
8714 the type of channel
8715 -charcoal <factor>
8717 simulate a charcoal drawing
8718 -colorize <value>
8720 colorize the image with the pen color
8721 -colors <value>
8723 preferred number of colors in the image
8724 -colorspace <value>
8726 the type of colorspace
8727 -comment <string>
8729 annotate an image with a comment
8730 -compose <operator>
8732 the type of image composition
8733 -compress <type>
8735 the type of image compression
8736 -contrast
8738 enhance or reduce the image contrast
8739 -convolve <kernel>
8741 convolve image with the specified convolution kernel
8742 -create-directories
8744 create output directory if required
8745 -crop <width>x<height>{+-}<x>{+-}<y>{%}
8747 preferred size and location of the cropped image
8748 -cycle <amount>
8750 displace image colormap by amount
8751 -debug <events>
8753 enable debug printout
8754 -define <key>{=<value>},...
8756 add coder/decoder specific options
8757 -delay <1/100ths of a second>
8759 display the next image after pausing
8760 -density <width>x<height>
8762 horizontal and vertical resolution in pixels of the image
8763 -depth <value>
8765 depth of the image
8766 -despeckle
8768 reduce the speckles within an image
8769 -display <host:display[.screen]>
8771 specifies the X server to contact
8772 -dispose <method>
8774 GIF disposal method
8775 -dither
8777 apply Floyd/Steinberg error diffusion to the image
8778 -draw <string>
8780 annotate an image with one or more graphic primitives
8781 -edge <radius>
8783 detect edges within an image
8784 -emboss <radius>
8786 emboss an image
8787 -encoding <type>
8789 specify the text encoding
8790 -endian <type>
8792 specify endianness (MSB, LSB, or Native) of image
8793 -enhance
8795 apply a digital filter to enhance a noisy image
8796 -equalize
8798 perform histogram equalization to the image
8799 -extent <width>x<height>{+-}<x>{+-}<y>
8801 composite image on background color canvas image
8802 -fill <color>
8804 color to use when filling a graphic primitive
8805 -filter <type>
8807 use this type of filter when resizing an image
8808 -flip create a "mirror image"
8810 -flop create a "mirror image"
8812 -font <name>
8814 use this font when annotating the image with text
8815 -format <type>
8817 the image format type
8818 -frame <width>x<height>+<outer bevel width>+<inner bevel width>
8820 surround the image with an ornamental border
8821 -fuzz <distance>{%}
8823 colors within this Euclidean distance are considered equal
8824 -gamma <value>
8826 level of gamma correction
8827 -gaussian <radius>{x<sigma>}
8829 blur the image with a Gaussian operator
8830 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
8832 Specify dimension, offset, and resize options.
8833 -gravity <type>
8835 direction primitive gravitates to when annotating the image.
8836 -green-primary <x>,<y>
8838 green chromaticity primary point
8839 -hald-clut <clut>
8841 apply a Hald CLUT to the image
8842 -help print usage instructions
8844 -implode <factor>
8846 implode image pixels about the center
8847 -interlace <type>
8849 the type of interlacing scheme
8850 -label <name>
8852 assign a label to an image
8853 -lat <width>x<height>{+-}<offset>{%}
8855 perform local adaptive thresholding
8856 -level <black_point>{,<gamma>}{,<white_point>}{%}
8858 adjust the level of image contrast
8859 -limit <type> <value>
8861 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
8862 resource limit
8863 -linewidth
8865 the line width for subsequent draw operations
8866 -list <type>
8868 the type of list
8869 -log <string>
8871 Specify format for debug log
8872 -loop <iterations>
8874 add Netscape loop extension to your GIF animation
8875 -magnify
8877 magnify the image
8878 -map <filename>
8880 choose a particular set of colors from this image
8881 -mask <filename>
8883 Specify a clipping mask
8884 -matte store matte channel if the image has one
8886 -mattecolor <color>
8888 specify the color to be used with the -frame option
8889 -median <radius>
8891 apply a median filter to the image
8892 -minify <factor>
8894 minify the image
8895 -modulate brightness[,saturation[,hue]]
8897 vary the brightness, saturation, and hue of an image
8898 -monitor
8900 show progress indication
8901 -monochrome
8903 transform the image to black and white
8904 -motion-blur <radius>{x<sigma>}{+angle}
8906 Simulate motion blur
8907 -negate
8909 replace every pixel with its complementary color
8910 -noise <radius|type>
8912 add or reduce noise in an image
8913 -noop NOOP (no option)
8915 -normalize
8917 transform image to span the full range of color values
8918 -opaque <color>
8920 change this color to the pen color within the image
8921 -operator channel operator rvalue[%]
8923 apply a mathematical, bitwise, or value operator to an image
8924 channel
8925 -ordered-dither <channeltype> <NxN>
8927 ordered dither the image
8928 -output-directory <directory>
8930 output files to directory
8931 -orient <orientation>
8933 Set the image orientation attribute
8934 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
8936 size and location of an image canvas
8937 -paint <radius>
8939 simulate an oil painting
8940 -pen <color>
8942 (This option has been replaced by the -fill option)
8943 -pointsize <value>
8945 pointsize of the PostScript, X11, or TrueType font
8946 -profile <filename>
8948 add ICM, IPTC, or generic profile to image
8949 -preserve-timestamp
8951 preserve the original timestamps of the file
8952 -quality <value>
8954 JPEG/MIFF/PNG/TIFF compression level
8955 -raise <width>x<height>
8957 lighten or darken image edges
8958 -random-threshold <channeltype> <LOWxHIGH>
8960 random threshold the image
8961 -recolor <matrix>
8963 apply a color translation matrix to image channels
8964 -red-primary <x>,<y>
8966 red chromaticity primary point
8967 -region <width>x<height>{+-}<x>{+-}<y>
8969 apply options to a portion of the image
8970 -render
8972 render vector operations
8973 -repage <width>x<height>+xoff+yoff[!]
8975 Adjust image page offsets
8976 -resample <horizontal>x<vertical>
8978 Resample image to specified horizontal and vertical resolution
8979 -resize <width>x<height>{%}{@}{!}{<}{>}
8981 resize an image
8982 -roll {+-}<x>{+-}<y>
8984 roll an image vertically or horizontally
8985 -rotate <degrees>{<}{>}
8987 rotate the image
8988 -sample <geometry>
8990 scale image using pixel sampling
8991 -sampling-factor <horizontal_factor>x<vertical_factor>
8993 chroma subsampling factors
8994 -scale <geometry>
8996 scale the image.
8997 -scene <value>
8999 set scene number
9000 -set <attribute> <value>
9002 set an image attribute
9003 +set <attribute>
9005 unset an image attribute
9006 -segment <cluster threshold>x<smoothing threshold>
9008 segment an image
9009 -shade <azimuth>x<elevation>
9011 shade the image using a distant light source
9012 -sharpen <radius>{x<sigma>}
9014 sharpen the image
9015 -shave <width>x<height>{%}
9017 shave pixels from the image edges
9018 -shear <x degrees>x<y degrees>
9020 shear the image along the X or Y axis
9021 -size <width>x<height>{+offset}
9023 width and height of the image
9024 -solarize <factor>
9026 negate all pixels above the threshold level
9027 -spread <amount>
9029 displace image pixels by a random amount
9030 -strip remove all profiles and text attributes from the image
9032 -stroke <color>
9034 color to use when stroking a graphic primitive
9035 -strokewidth <value>
9037 set the stroke width
9038 -swirl <degrees>
9040 swirl image pixels about the center
9041 -texture <filename>
9043 name of texture to tile onto the image background
9044 -threshold <value>{%}
9046 threshold the image
9047 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
9049 resize an image (quickly)
9050 -tile <filename>
9052 tile image when filling a graphic primitive
9053 -transform
9055 transform the image
9056 -transparent <color>
9058 make this color transparent within the image
9059 -treedepth <value>
9061 tree depth for the color reduction algorithm
9062 -trim trim an image
9064 -type <type>
9066 the image type
9067 -units <type>
9069 the units of image resolution
9070 -unsharp <radius>{x<sigma>}{+<amount>}{+<threshold>}
9072 sharpen the image with an unsharp mask operator
9073 -verbose
9075 print detailed information about the image
9076 -version
9078 print GraphicsMagick version string
9079 -view <string>
9081 FlashPix viewing parameters
9082 -virtual-pixel <method>
9084 specify contents of "virtual pixels"
9085 -wave <amplitude>x<wavelength>
9087 alter an image along a sine wave
9088 -white-point <x>,<y>
9090 chromaticity white point
9091 -white-threshold red[,green][,blue][,opacity]
9093 pixels above the threshold become white
9094 For a more detailed description of each option, see Options,
9096 above.
9097
9100 montage creates a composite image by combining several separate images.
9101 The images are tiled on the composite image with the name of the image
9102 optionally appearing just below the individual tile.
9103 The composite image is constructed in the following manner. First, each
9105 image specified on the command line, except for the last, is scaled to
9106 fit the maximum tile size. The maximum tile size by default is 120x120.
9107 It can be modified with the -geometry command line argument or X re‐
9108 source. See Options for more information on command line arguments. See
9109 X(1) for more information on X resources. Note that the maximum tile
9110 size need not be a square.
9111 Next the composite image is initialized with the color specified by the
9113 -background command line argument or X resource. The width and height
9114 of the composite image is determined by the title specified, the maxi‐
9115 mum tile size, the number of tiles per row, the tile border width and
9116 height, the image border width, and the label height. The number of
9117 tiles per row specifies how many images are to appear in each row of
9118 the composite image. The default is to have 5 tiles in each row and 4
9119 tiles in each column of the composite. A specific value is specified
9120 with -tile. The tile border width and height, and the image border
9121 width defaults to the value of the X resource -borderwidth. It can be
9122 changed with the -borderwidth or -geometry command line argument or X
9123 resource. The label height is determined by the font you specify with
9124 the -font command line argument or X resource. If you do not specify a
9125 font, a font is chosen that allows the name of the image to fit the
9126 maximum width of a tiled area. The label colors is determined by the
9127 -background and -fill command line argument or X resource. Note, that
9128 if the background and pen colors are the same, labels will not appear.
9129 Initially, the composite image title is placed at the top if one is
9131 specified (refer to -fill). Next, each image is set onto the composite
9132 image, surrounded by its border color, with its name centered just be‐
9133 low it. The individual images are left-justified within the width of
9134 the tiled area. The order of the images is the same as they appear on
9135 the command line unless the images have a scene keyword. If a scene
9136 number is specified in each image, then the images are tiled onto the
9137 composite in the order of their scene number. Finally, the last argu‐
9138 ment on the command line is the name assigned to the composite image.
9139 By default, the image is written in the MIFF format and can be viewed
9140 or printed with display(1).
9141 Note, that if the number of tiles exceeds the default number of 20 (5
9144 per row, 4 per column), more than one composite image is created. To
9145 ensure a single image is produced, use -tile to increase the number of
9146 tiles to meet or exceed the number of input images.
9147 Finally, to create one or more empty spaces in the sequence of tiles,
9149 use the "NULL:" image format.
9150 Note, a composite MIFF image displayed to an X server with display be‐
9152 haves differently than other images. You can think of the composite as
9153 a visual image directory. Choose a particular tile of the composite and
9154 press a button to display it. See display(1) and miff(5)
9155
9157 To create a montage of a cockatoo, a parrot, and a hummingbird and
9158 write it to a file called birds, use:
9159 gm montage cockatoo.miff parrot.miff hummingbird.miff
9161 birds.miff
9162 To tile several bird images so that they are at most 256 pixels in
9164 width and 192 pixels in height, surrounded by a red border, and sepa‐
9165 rated by 10 pixels of background color, use:
9166 gm montage -geometry 256x192+10+10 -bordercolor red
9168 birds.* montage.miff
9169 To create an unlabeled parrot image, 640 by 480 pixels, and surrounded
9171 by a border of black, use:
9172 gm montage -geometry 640x480 -bordercolor black
9174 -label "" parrot.miff bird.miff
9175 To create an image of an eagle with a textured background, use:
9177 gm montage -texture bumps.jpg eagle.jpg eagle.png
9179 To join several GIF images together without any extraneous graphics
9181 (e.g. no label, no shadowing, no surrounding tile frame), use:
9182 gm montage +frame +shadow +label -tile 5x1
9184 -geometry 50x50+0+0 *.png joined.png
9185
9187 Any option you specify on the command line remains in effect for the
9188 group of images following it, until the group is terminated by the ap‐
9189 pearance of any option or -noop. For example, to make a montage of
9190 three images, the first with 32 colors, the second with an unlimited
9191 number of colors, and the third with only 16 colors, use:
9192 gm montage -colors 32 cockatoo.1 -noop cockatoo.2
9195 -colors 16 cockatoo.3 cockatoos.miff
9196 For a more detailed description of each option, see Options, above.
9198 -adjoin
9201 join images into a single multi-image file
9202 -affine <matrix>
9204 drawing transform matrix
9205 -authenticate <string>
9207 decrypt image with this password
9208 -background <color>
9210 the background color
9211 -blue-primary <x>,<y>
9213 blue chromaticity primary point
9214 -blur <radius>{x<sigma>}
9216 blur the image with a Gaussian operator
9217 -bordercolor <color>
9219 the border color
9220 -borderwidth <geometry>
9222 the border width
9223 -chop <width>x<height>{+-}<x>{+-}<y>{%}
9225 remove pixels from the interior of an image
9226 -colors <value>
9228 preferred number of colors in the image
9229 -colorspace <value>
9231 the type of colorspace
9232 -comment <string>
9234 annotate an image with a comment
9235 -compose <operator>
9237 the type of image composition
9238 -compress <type>
9240 the type of image compression
9241 -crop <width>x<height>{+-}<x>{+-}<y>{%}
9243 preferred size and location of the cropped image
9244 -debug <events>
9246 enable debug printout
9247 -define <key>{=<value>},...
9249 add coder/decoder specific options
9250 -density <width>x<height>
9252 horizontal and vertical resolution in pixels of the image
9253 -depth <value>
9255 depth of the image
9256 -display <host:display[.screen]>
9258 specifies the X server to contact
9259 -dispose <method>
9261 GIF disposal method
9262 -dither
9264 apply Floyd/Steinberg error diffusion to the image
9265 -draw <string>
9267 annotate an image with one or more graphic primitives
9268 -encoding <type>
9270 specify the text encoding
9271 -endian <type>
9273 specify endianness (MSB, LSB, or Native) of image
9274 -fill <color>
9276 color to use when filling a graphic primitive
9277 -filter <type>
9279 use this type of filter when resizing an image
9280 -font <name>
9282 use this font when annotating the image with text
9283 -frame <width>x<height>+<outer bevel width>+<inner bevel width>
9285 surround the image with an ornamental border
9286 -gamma <value>
9288 level of gamma correction
9289 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
9291 Specify dimension, offset, and resize options.
9292 -gravity <type>
9294 direction primitive gravitates to when annotating the image.
9295 -green-primary <x>,<y>
9297 green chromaticity primary point
9298 -help print usage instructions
9300 -interlace <type>
9302 the type of interlacing scheme
9303 -label <name>
9305 assign a label to an image
9306 -limit <type> <value>
9308 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
9309 resource limit
9310 -log <string>
9312 Specify format for debug log
9313 -matte store matte channel if the image has one
9315 -mattecolor <color>
9317 specify the color to be used with the -frame option
9318 -mode <value>
9320 mode of operation
9321 -monitor
9323 show progress indication
9324 -monochrome
9326 transform the image to black and white
9327 -noop NOOP (no option)
9329 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
9331 size and location of an image canvas
9332 -pen <color>
9334 (This option has been replaced by the -fill option)
9335 -pointsize <value>
9337 pointsize of the PostScript, X11, or TrueType font
9338 -quality <value>
9340 JPEG/MIFF/PNG/TIFF compression level
9341 -red-primary <x>,<y>
9343 red chromaticity primary point
9344 -render
9346 render vector operations
9347 -repage <width>x<height>+xoff+yoff[!]
9349 Adjust image page offsets
9350 -resize <width>x<height>{%}{@}{!}{<}{>}
9352 resize an image
9353 -rotate <degrees>{<}{>}
9355 rotate the image
9356 -sampling-factor <horizontal_factor>x<vertical_factor>
9358 chroma subsampling factors
9359 -scenes <value-value>
9361 range of image scene numbers to read
9362 -shadow <radius>{x<sigma>}
9364 shadow the montage
9365 -sharpen <radius>{x<sigma>}
9367 sharpen the image
9368 -size <width>x<height>{+offset}
9370 width and height of the image
9371 -strip remove all profiles and text attributes from the image
9373 -stroke <color>
9375 color to use when stroking a graphic primitive
9376 -strokewidth <value>
9378 set the stroke width
9379 -texture <filename>
9381 name of texture to tile onto the image background
9382 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
9384 resize an image (quickly)
9385 -tile <geometry>
9387 layout of images [montage]
9388 -title <string>
9390 assign title to displayed image [animate, display, montage]
9391 -transform
9393 transform the image
9394 -transparent <color>
9396 make this color transparent within the image
9397 -treedepth <value>
9399 tree depth for the color reduction algorithm
9400 -trim trim an image
9402 -type <type>
9404 the image type
9405 -verbose
9407 print detailed information about the image
9408 -version
9410 print GraphicsMagick version string
9411 -white-point <x>,<y>
9413 chromaticity white point
9414 For a more detailed description of each option, see Options,
9416 above.
9417
9420 Montage options can appear on the command line or in your X resource
9421 file. Options on the command line supersede values specified in your X
9422 resource file. See X(1) for more information on X resources.
9423 All montage options have a corresponding X resource. In addition, mon‐
9425 tage uses the following X resources:
9426 background (class Background)
9428 background color
9429 Specifies the preferred color to use for the composite image
9431 background. The default is #ccc.
9432 borderColor (class BorderColor)
9434 border color
9435 Specifies the preferred color to use for the composite image
9437 border. The default is #ccc.
9438 borderWidth (class BorderWidth)
9440 border width
9441 Specifies the width in pixels of the composite image border. The
9443 default is 2.
9444 font (class Font)
9446 font to use
9447 Specifies the name of the preferred font to use when displaying
9449 text within the composite image. The default is 9x15, fixed, or
9450 5x8 determined by the composite image size.
9451 matteColor (class MatteColor)
9453 color of the frame
9454 Specify the color of an image frame. A 3D effect is achieved by
9456 using highlight and shadow colors derived from this color. The
9457 default value is #697B8F.
9458 pen (class Pen)
9460 text color
9461 Specifies the preferred color to use for text within the compos‐
9463 ite image. The default is black.
9464 title (class Title)
9466 composite image title
9467 This resource specifies the title to be placed at the top of the
9469 composite image. The default is not to place a title at the top
9470 of the composite image.
9471
9474 time executes an arbitrary gm utility command (e.g. convert) and re‐
9475 ports the user and elapsed time. This provides way to measure command
9476 execution times similar to the Unix ´time' command but in a portable
9477 and consistent way.
9478
9480 To obtain time information for the execution of a command:
9481 % gm time convert input.ppm -gaussian 0x2 output.ppm
9483 convert input.ppm -gaussian 0x2 output.ppm 22.60s user 0.00s system 2354% cpu 0.960 total
9484 Here is the interpretation of the above output:
9485 user - the total user time consumed.
9487 system - the total system time consumed.
9488 total - the total elapsed time consumed.
9489
9492 The time command reqires no options other than the gm command to exe‐
9493 cute.
9494
9497 version displays the software release version, build quantum (pixel
9498 sample) depth, web site URL, copyright notice, enabled features sup‐
9499 port, configuration parameters, and final build options used to build
9500 the software. The available information depends on how the software
9501 was configured and the host system.
9502
9504 To display the version information:
9505 GraphicsMagick 1.3.37 2021-12-12 Q16 http://www.GraphicsMagick.org/
9507 Copyright (C) 2002-2021 GraphicsMagick Group.
9508 Additional copyrights and licenses apply to this software.
9509 See http://www.GraphicsMagick.org/www/Copyright.html for details.
9510 Feature Support:
9511 Native Thread Safe yes
9512 Large Files (> 32 bit) yes
9513 Large Memory (> 32 bit) yes
9514 BZIP yes
9515 DPS no
9516 FlashPix no
9517 FreeType yes
9518 Ghostscript (Library) no
9519 JBIG yes
9520 JPEG-2000 yes
9521 JPEG yes
9522 Little CMS yes
9523 Loadable Modules no
9524 Solaris mtmalloc no
9525 Google perftools tcmalloc no
9526 OpenMP yes (201511 "4.5")
9527 PNG yes
9528 TIFF yes
9529 TRIO no
9530 Solaris umem no
9531 WebP yes
9532 WMF yes
9533 X11 yes
9534 XML yes
9535 ZLIB yes
9536 Host type: x86_64-unknown-linux-gnu
9537 Configured using the command:
9538 ./configure ...
9539 Final Build Parameters:
9540 CC = ...
9541 CFLAGS = ...
9542 CPPFLAGS = ...
9543 CXX = ...
9544 CXXFLAGS = ...
9545 LDFLAGS = ...
9546 LIBS = ...
9547
9549 The version command does not currently support any options.
9550GraphicsMagick 2022/05/02 gm(1)