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:block-smoothing={true|false}
1136 Enables or disables block smoothing when reading a JPEG
1138 file (default enabled).
1139 jpeg:dct-method=<value>
1141 Selects the IJG JPEG library DCT implementation to use.
1143 The encoding implementations vary in speed and encoding
1144 error. The available choices for value are islow, ifast,
1145 float, default and fastest. Note that fastest might not
1146 necessarily be fastest on your CPU, depending on the
1147 choices made when the JPEG library was built and how your
1148 CPU behaves.
1149 jpeg:fancy-upsampling={true|false}
1151 Enables or disables fancy upsampling when reading a JPEG
1153 file (default enabled).
1154 jpeg:max-scan-number=<value>
1156 Specifies an integer value for the maximum number of pro‐
1158 gressive scans allowed in a JPEG file. The default maxi‐
1159 mum is 100 scans. This limit is imposed due to a weakness
1160 in the JPEG standard which allows small JPEG files to take
1161 many minutes or hours to be read.
1162 jpeg:max-warnings=<value>
1164 Specifies an integer value for how many warnings are al‐
1166 lowed for any given error type before being promoted to a
1167 hard error. JPEG files producing excessive warnings indi‐
1168 cate a problem with the file.
1169 jpeg:optimize-coding={true|false}
1171 Selects if huffman encoding should be used. Huffman encod‐
1173 ing is enabled by default, but may be disabled for very
1174 large images since it encoding requires that the entire
1175 image be buffered in memory. Huffman encoding produces
1176 smaller JPEG files at the expense of added compression
1177 time and memory consumption.
1178 jpeg:preserve-settings
1180 If the jpeg:preserve-settings flag is defined, the JPEG
1182 encoder will use the same "quality" and "sampling-factor"
1183 settings that were found in the input file, if the input
1184 was in JPEG format. These settings are also preserved if
1185 the input is a JPEG file and the output is a JNG file. If
1186 the colorspace of the output file differs from that of the
1187 input file, the quality setting is preserved but the sam‐
1188 pling-factors are not.
1189 pcl:fit-to-page
1191 If the pcl:fit-to-page flag is defined, then the printer
1193 is requested to scale the image to fit the page size
1194 (width and/or height).
1195 png:chunk-malloc-max=<value>
1196 png:chunk-malloc-max specifies the maximum chunk size that
1198 libpng will be allowed to read. Libpng's default is nor‐
1199 mally 8,000,000 bytes. Very rarely, a valid PNG file may
1200 be encountered where the error is reported "chunk data is
1201 too large". In this case, the limit may be increased us‐
1202 ing this option. Take care when increasing this limit
1203 since an excessively large limit could allow untrusted
1204 files to use excessive memory.
1205 mng:maximum-loops=<value>
1207 mng:maximum-loops specifies the maximum number of loops
1209 allowed to be specified by a MNG LOOP chunk. Without an
1210 imposed limit, a MNG file could request up to 2147483647
1211 loops, which could run for a very long time. The current
1212 default limit is 512 loops.
1213 pdf:use-cropbox={true|false}
1215 If the pdf:use-cropbox flag is set to true, then Ghost‐
1217 script is requested to apply the PDF crop box.
1218 pdf:stop-on-error={true|false}
1220 If the pdf:stop-on-error flag is set to true, then Ghost‐
1222 script is requested to stop processing the PDF when the
1223 first error is encountered. Otherwise it will attempt to
1224 process all requested pages.
1225 ps:imagemask
1227 If the ps:imagemask flag is defined, the PS3 and EPS3
1229 coders will create Postscript files that render bilevel
1230 images with the Postscript imagemask operator instead of
1231 the image operator.
1232 ptif:minimum-geometry=<geometry>
1234 If the ptif:minimum-geometry key is defined, GraphicsMag‐
1236 ick will use it to determine the minimum frame size to
1237 output when writing a pyramid TIFF file (a TIFF file con‐
1238 taining a succession of reduced versions of the first
1239 frame). The default minimum geometry is 32x32.
1240 tiff:alpha={unspecified|associated|unassociated}
1242 Specify the TIFF alpha channel type when reading or writ‐
1244 ing TIFF files, overriding the normal value. The default
1245 alpha channel type for new files is unspecified alpha. Ex‐
1246 isting alpha settings are preserved when converting from
1247 one TIFF file to another. When a TIFF file uses associated
1248 alpha, the image pixels are pre-multiplied (i.e. altered)
1249 with the alpha channel. Files with "associated" alpha ap‐
1250 pear as if they were alpha composited on a black back‐
1251 ground when the matte channel is disabled. If the unasso‐
1252 ciated alpha type is selected, then the alpha channel is
1253 saved without altering the pixels. Photoshop recognizes
1254 associated alpha as transparency information, if the file
1255 is saved with unassociated alpha, the alpha information is
1256 loaded as an independent channel. Note that for many
1257 years, ImageMagick and GraphicsMagick marked TIFF files as
1258 using associated alpha, without properly pre-multiplying
1259 the pixels.
1260 tiff:fill-order={msb2lsb|lsb2msb}
1262 If the tiff:fill-order key is defined, GraphicsMagick will
1264 use it to determine the bit fill order used while writing
1265 TIFF files. The normal default is "msb2lsb", which matches
1266 the native bit order of all modern CPUs. The only excep‐
1267 tion to this is when Group3 or Group4 FAX compression is
1268 requested since FAX machines send data in bit-reversed or‐
1269 der and therefore RFC 2301 recommends using reverse order.
1270 tiff:group-three-options=<value>
1272 If the tiff:group-three-options key is defined, Graphics‐
1274 Magick will use it to set the group3 options tag when
1275 writing group3-compressed TIFF. Please see the TIFF spec‐
1276 ification for the usage of this tag. The default value is
1277 4.
1278 tiff:ignore-tags=<tags>
1280 If the tiff:ignore-tags key is defined, then it is used as
1282 a list of comma-delimited integer TIFF tag values to ig‐
1283 nore while reading the TIFF file. This is useful in order
1284 to be able to read files which which otherwise fail to
1285 read due to problems with TIFF tags. Note that some TIFF
1286 tags are required in order to be able to read the image
1287 data at all.
1288 tiff:report-warnings={false|true}
1290 If the tiff:report-warnings key is defined and set to
1292 true, then TIFF warnings are reported as a warning excep‐
1293 tion rather than as a coder log message. Such warnings
1294 are reported after the image has been read or written.
1295 Most TIFF warnings are benign but sometimes they may help
1296 deduce problems with the TIFF file, or help detect that
1297 the TIFF file requires a special application to read suc‐
1298 cessfully due to the use of proprietary or specialized ex‐
1299 tensions.
1300 tiff:sample-format={unsigned|ieeefp}
1302 If the tiff:sample-format key is defined, GraphicsMagick
1304 will use it to determine the sample format used while
1305 writing TIFF files. The default is "unsigned". Specify
1306 "ieeefp" in order to write floating-point TIFF files with
1307 float (32-bit) or double (64-bit) values. Use the
1308 tiff:bits-per-sample define to determine the type of
1309 floating-point value to use.
1310 tiff:max-sample-value=<value>
1312 If the tiff:max-sample-value key is defined, GraphicsMag‐
1314 ick will use the assigned value as the maximum floating
1315 point value while reading or writing IEEE floating point
1316 TIFFs. Otherwise the maximum value is 1.0 or the value ob‐
1317 tained from the file's SMaxSampleValue tag (if present).
1318 The floating point data is currently not scanned in ad‐
1319 vance to determine a best maximum sample value so if the
1320 range is not 1.0, or the SMaxSampleValue tag is not
1321 present, it may be necessary to (intelligently) use this
1322 parameter to properly read a file.
1323 tiff:min-sample-value=<value>
1325 If the tiff:min-sample-value key is defined, GraphicsMag‐
1327 ick will use the assigned value as the minimum floating
1328 point value while reading or writing IEEE floating point
1329 TIFFs. Otherwise the minimum value is 0.0 or the value ob‐
1330 tained from the file's SMinSampleValue tag (if present).
1331 tiff:bits-per-sample=<value>
1333 If the tiff:bits-per-sample key is defined, GraphicsMagick
1335 will write images with the specified bits per sample,
1336 overriding any existing depth value. Value may be any in
1337 the range of 1 to 32, or 64 when the default ´unsigned'
1338 format is written, or 16/32/24/64 if IEEEFP format is
1339 written. Please note that the baseline TIFF 6.0 specifi‐
1340 cation only requires readers to handle certain powers of
1341 two, and the values to be handled depend on the nature of
1342 the image (e.g. colormapped, grayscale, RGB, CMYK).
1343 tiff:samples-per-pixel=<value>
1345 If the tiff:samples-per-pixel key is defined to a value,
1347 the TIFF coder will write TIFF images with the defined
1348 samples per pixel, overriding any value stored in the im‐
1349 age. This option should not normally be used.
1350 tiff:rows-per-strip=<value>
1352 Allows the user to specify the number of rows per TIFF
1354 strip. Rounded up to a multiple of 16 when using JPEG
1355 compression. Ignored when using tiles.
1356 tiff:strip-per-page=true
1358 Requests that the image is written in a single TIFF strip.
1360 This is normally the default when group3 or group4 com‐
1361 pression is requested within reasonable limits. Requesting
1362 a single strip for large images may result in failure due
1363 to resource consumption in the writer or reader.
1364 tiff:tile
1366 Enable writing tiled TIFF (rather than stripped) using the
1368 default tile size. Tiled TIFF organizes the image as an
1369 array of smaller images (tiles) in order to enable random
1370 access.
1371 tiff:tile-geometry=<width>x<height>
1373 Specify the tile size to use while writing tiled TIFF.
1375 Width and height should be a multiple of 16. If the value
1376 is not a multiple of 16, then it will be rounded down. En‐
1377 ables tiled TIFF if it has not already been enabled.
1378 GraphicsMagick does not use tiled storage internally so
1379 tiles need to be converted back and forth from the inter‐
1380 nal scanline-oriented storage to tile-oriented storage.
1381 Testing with typical RGB images shows that useful square
1382 tile size values range from 128x128 to 1024x1024. Large
1383 images which require using a disk-based pixel cache bene‐
1384 fit from large tile sizes while images which fit in memory
1385 work well with smaller tile sizes.
1386 tiff:tile-width=<width>
1388 Specify the tile width to use while writing tiled TIFF.
1390 The tile height is then defaulted to an appropriate size.
1391 Width should be a multiple of 16. If the value is not a
1392 multiple of 16, then it will be rounded down. Enables
1393 tiled TIFF if it has not already been enabled.
1394 tiff:tile-height=<height>
1396 Specify the tile height to use while writing tiled TIFF.
1398 The tile width is then defaulted to an appropriate size.
1399 Height should be a multiple of 16. If the value is not a
1400 multiple of 16, then it will be rounded down. Enables
1401 tiled TIFF if it has not already been enabled.
1402 tiff:webp-lossless={TRUE|FALSE}
1404 Specify a value of TRUE to enable lossless mode while
1406 writing WebP-compressed TIFF files. The WebP webp:lossless
1407 option may also be used. The quality factor set by the
1408 -quality option may be used to influence the level of ef‐
1409 fort expended while compressing.
1410 tiff:zstd-compress-level=<value>
1412 Specify the compression level to use while writing Zstd-
1414 compressed TIFF files. The valid range is 1 to 22. If this
1415 define is not specified, then the 'quality' value is used
1416 such that the default quality setting of 75 is translated
1417 to a compress level of 9 such that ´quality' has a useful
1418 range of 10-184 if used for this purpose.
1419 webp:lossless={true|false}
1421 Enable lossless encoding.
1423 webp:method={0-6}
1425 Quality/speed trade-off.
1427 webp:image-hint={default,graph,photo,picture}
1429 Hint for image type.
1431 webp:target-size=<integer>
1433 Target size in bytes.
1435 webp:target-psnr=<float>
1437 Minimal distortion to try to achieve.
1439 webp:segments={1-4}
1441 Maximum number of segments to use.
1443 webp:sns-strength={0-100}
1445 Spatial Noise Shaping.
1447 webp:filter-strength={0-100}
1449 Filter strength.
1451 webp:filter-sharpness={0-7}
1453 Filter sharpness.
1455 webp:filter-type={0,1}
1457 Filtering type. 0 = simple, 1 = strong (only used if fil‐
1459 ter-strength > 0 or autofilter is enabled).
1460 webp:auto-filter={true|false}
1462 Auto adjust filter's strength.
1464 webp:alpha-compression=<integer>
1466 Algorithm for encoding the alpha plane (0 = none, 1 = com‐
1468 pressed with WebP lossless). Default is 1.
1469 webp:alpha-filtering=<integer>
1471 Predictive filtering method for alpha plane. 0: none, 1:
1473 fast, 2: best. Default is 1.
1474 webp:alpha-quality={0-100}
1476 Between 0 (smallest size) and 100 (lossless). Default is
1478 100.
1479 webp:pass=[1..10]
1481 Number of entropy-analysis passes.
1483 webp:show-compressed={true|false}
1485 Export the compressed picture back. In-loop filtering is
1487 not applied.
1488 webp:preprocessing=[0,1,2]
1490 0=none, 1=segment-smooth, 2=pseudo-random dithering
1492 webp:partitions=[0-3]
1494 log2(number of token partitions) in [0..3]. Default is 0
1496 for easier progressive decoding.
1497 webp:partition-limit={0-100}
1499 Quality degradation allowed to fit the 512k limit on pre‐
1501 diction modes coding (0: no degradation, 100: maximum pos‐
1502 sible degradation).
1503 webp:emulate-jpeg-size={true|false}
1505 If true, compression parameters will be remapped to better
1507 match the expected output size from JPEG compression. Gen‐
1508 erally, the output size will be similar but the degrada‐
1509 tion will be lower.
1510 webp:thread-level=<integer>
1512 If non-zero, try and use multi-threaded encoding.
1514 webp:low-memory={true|false}
1516 If set, reduce memory usage (but increase CPU use)
1518 webp:use-sharp-yuv={true|false}
1520 If set, if needed, use sharp (and slow) RGB->YUV conver‐
1522 sion
1523 For example, to create a postscript file that will render only
1528 the black pixels of a bilevel image, use:
1529 gm convert bilevel.tif -define ps:imagemask eps3:stencil.ps
1531 -delay <1/100ths of a second>
1533 display the next image after pausing
1534 This option is useful for regulating the animation of image se‐
1536 quences Delay/100 seconds must expire before the display of the
1537 next image. The default is no delay between each showing of the
1538 image sequence. The maximum delay is 65535.
1539 You can specify a delay range (e.g. -delay 10-500) which sets
1541 the minimum and maximum delay.
1542 -density <width>x<height>
1544 horizontal and vertical resolution in pixels of the image This
1545 option specifies the image resolution to store while encoding a
1546 raster image or the canvas resolution while rendering (reading)
1547 vector formats such as Postscript, PDF, WMF, and SVG into a
1548 raster image. Image resolution provides the unit of measure to
1549 apply when rendering to an output device or raster image. The
1550 default unit of measure is in dots per inch (DPI). The -units
1551 option may be used to select dots per centimeter instead.
1552 The default resolution is 72 dots per inch, which is equivalent
1553 to one point per pixel (Macintosh and Postscript standard). Com‐
1554 puter screens are normally 72 or 96 dots per inch while printers
1555 typically support 150, 300, 600, or 1200 dots per inch. To de‐
1556 termine the resolution of your display, use a ruler to measure
1557 the width of your screen in inches, and divide by the number of
1558 horizontal pixels (1024 on a 1024x768 display). If the file
1559 format supports it, this option may be used to update the stored
1560 image resolution. Note that Photoshop stores and obtains image
1561 resolution from a proprietary embedded profile. If this profile
1562 is not stripped from the image, then Photoshop will continue to
1563 treat the image using its former resolution, ignoring the image
1564 resolution specified in the standard file header. The density
1565 option is an attribute and does not alter the underlying raster
1566 image. It may be used to adjust the rendered size for desktop
1567 publishing purposes by adjusting the scale applied to the pix‐
1568 els. To resize the image so that it is the same size at a dif‐
1569 ferent resolution, use the -resample option.
1570 -depth <value>
1572 depth of the image
1573 This is the number of bits of color to preserve in the image.
1575 Any value between 1 and QuantumDepth (build option) may be spec‐
1576 ified, although 8 or 16 are the most common values. Use this op‐
1577 tion to specify the depth of raw images whose depth is unknown
1578 such as GRAY, RGB, or CMYK, or to change the depth of any image
1579 after it has been read. The depth option is applied to the pix‐
1580 els immediately so it may be used as a form of simple compres‐
1581 sion by discarding the least significant bits. Reducing the
1582 depth in advance may speed up color quantization, and help cre‐
1583 ate smaller file sizes when using a compression algorithm like
1584 LZW or ZIP.
1585 -descend
1587 obtain image by descending window hierarchy
1588 -despeckle
1590 reduce the speckles within an image
1591 -displace <horizontal scale>x<vertical scale>
1593 shift image pixels as defined by a displacement map
1594 With this option, composite image is used as a displacement map.
1596 Black, within the displacement map, is a maximum positive dis‐
1597 placement. White is a maximum negative displacement and middle
1598 gray is neutral. The displacement is scaled to determine the
1599 pixel shift. By default, the displacement applies in both the
1600 horizontal and vertical directions. However, if you specify
1601 mask, composite image is the horizontal X displacement and mask
1602 the vertical Y displacement.
1603 -display <host:display[.screen]>
1605 specifies the X server to contact
1606 This option is used with convert for obtaining image or font
1608 from this X server. See X(1).
1609 -dispose <method>
1611 GIF disposal method
1612 The Disposal Method indicates the way in which the graphic is to
1614 be treated after being displayed.
1615 Here are the valid methods:
1617 Undefined No disposal specified.
1619 None Do not dispose between frames.
1620 Background Overwrite the image area with
1621 the background color.
1622 Previous Overwrite the image area with
1623 what was there prior to rendering
1624 the image.
1625 -dissolve <percent>
1627 dissolve an image into another by the given percent
1628 The opacity of the composite image is multiplied by the given
1630 percent, then it is composited over the main image.
1631 -dither
1633 apply Floyd/Steinberg error diffusion to the image
1634 The basic strategy of dithering is to trade intensity resolution
1636 for spatial resolution by averaging the intensities of several
1637 neighboring pixels. Images which suffer from severe contouring
1638 when reducing colors can be improved with this option.
1639 The -colors or -monochrome option is required for this option to
1641 take effect.
1642 Use +dither to turn off dithering and to render PostScript with‐
1644 out text or graphic aliasing. Disabling dithering often (but not
1645 always) leads to decreased processing time.
1646 -draw <string>
1648 annotate an image with one or more graphic primitives
1649 Use this option to annotate an image with one or more graphic
1651 primitives. The primitives include shapes, text, transforma‐
1652 tions, and pixel operations. The shape primitives are
1653 point x,y
1655 line x0,y0 x1,y1
1656 rectangle x0,y0 x1,y1
1657 roundRectangle x0,y0 x1,y1 wc,hc
1658 arc x0,y0 x1,y1 a0,a1
1659 ellipse x0,y0 rx,ry a0,a1
1660 circle x0,y0 x1,y1
1661 polyline x0,y0 ... xn,yn
1662 polygon x0,y0 ... xn,yn
1663 Bezier x0,y0 ... xn,yn
1664 path path specification
1665 image operator x0,y0 w,h filename
1666 The text primitive is
1668 text x0,y0 string
1670 The text gravity primitive is
1672 gravity NorthWest, North, NorthEast, West, Center,
1674 East, SouthWest, South, or SouthEast
1675 The text gravity primitive only affects the placement of text
1677 and does not interact with the other primitives. It is equiva‐
1678 lent to using the -gravity commandline option, except that it is
1679 limited in scope to the -draw option in which it appears.
1680 The transformation primitives are
1682 rotate degrees
1684 translate dx,dy
1685 scale sx,sy
1686 skewX degrees
1687 skewY degrees
1688 The pixel operation primitives are
1690 color x0,y0 method
1692 matte x0,y0 method
1693 The shape primitives are drawn in the color specified in the
1695 preceding -stroke option. Except for the line and point primi‐
1696 tives, they are filled with the color specified in the preceding
1697 -fill option. For unfilled shapes, use -fill none.
1698 Point requires a single coordinate.
1700 Line requires a start and end coordinate.
1702 Rectangle expects an upper left and lower right coordinate.
1704 RoundRectangle has the upper left and lower right coordinates
1706 and the width and height of the corners.
1707 Circle has a center coordinate and a coordinate for the outer
1709 edge.
1710 Use Arc to inscribe an elliptical arc within a rectangle. Arcs
1712 require a start and end point as well as the degree of rotation
1713 (e.g. 130,30 200,100 45,90).
1714 Use Ellipse to draw a partial ellipse centered at the given
1716 point with the x-axis and y-axis radius and start and end of arc
1717 in degrees (e.g. 100,100 100,150 0,360).
1718 Finally, polyline and polygon require three or more coordinates
1720 to define its boundaries. Coordinates are integers separated by
1721 an optional comma. For example, to define a circle centered at
1722 100,100 that extends to 150,150 use:
1723 -draw 'circle 100,100 150,150'
1725 Paths (See Paths) represent an outline of an object which is de‐
1727 fined in terms of moveto (set a new current point), lineto (draw
1728 a straight line), curveto (draw a curve using a cubic Bezier),
1729 arc (elliptical or circular arc) and closepath (close the cur‐
1730 rent shape by drawing a line to the last moveto) elements. Com‐
1731 pound paths (i.e., a path with subpaths, each consisting of a
1732 single moveto followed by one or more line or curve operations)
1733 are possible to allow effects such as "donut holes" in objects.
1734 Use image to composite an image with another image. Follow the
1736 image keyword with the composite operator, image location, image
1737 size, and filename:
1738 -draw 'image Over 100,100 225,225 image.jpg'
1740 You can use 0,0 for the image size, which means to use the ac‐
1742 tual dimensions found in the image header. Otherwise, it will be
1743 scaled to the given dimensions. See -compose for a description
1744 of the composite operators.
1745 Use text to annotate an image with text. Follow the text coordi‐
1747 nates with a string. If the string has embedded spaces, enclose
1748 it in single or double quotes. Optionally you can include the
1749 image filename, type, width, height, or other image attribute by
1750 embedding special format character. See -comment for details.
1751 For example,
1753 -draw 'text 100,100 "%m:%f %wx%h"'
1756 annotates the image with MIFF:bird.miff 512x480 for an image titled
1759 bird.miff
1760 and whose width is 512 and height is 480.
1761 If the first character of string is @, the text is read
1763 from a file titled by the remaining characters in the string. Please
1764 note that if the string comes from an untrusted source that it should
1765 be sanitized before use (a security risk).
1766 Rotate rotates subsequent shape primitives and text primitives about
1768 the origin of the main image. If the -region option precedes the
1769 -draw option, the origin for transformations is the upper left
1770 corner of the region.
1771 Translate translates them.
1773 Scale scales them.
1775 SkewX and SkewY skew them with respect to the origin of
1777 the main image or the region.
1778 The transformations modify the current affine matrix, which is initialized
1780 from the initial affine matrix defined by the -affine option.
1781 Transformations are cumulative within the -draw option.
1782 The initial affine matrix is not affected; that matrix is only changed by the
1783 appearance of another -affine option. If another -draw
1784 option appears, the current affine matrix is reinitialized from
1785 the initial affine matrix.
1786 Use color to change the color of a pixel to the fill color (see
1788 -fill). Follow the pixel coordinate
1789 with a method:
1790 point
1792 replace
1793 floodfill
1794 filltoborder
1795 reset
1796 Consider the target pixel as that specified by your coordinate.
1798 The point method recolors the target pixel. The replace method
1799 recolors any pixel that matches the color of the target pixel.
1800 Floodfill recolors any pixel that matches the color of the tar‐
1801 get pixel and is a neighbor, whereas filltoborder recolors any
1802 neighbor pixel that is not the border color. Finally, reset re‐
1803 colors all pixels.
1804 Use matte to the change the pixel matte value to transparent.
1806 Follow the pixel coordinate with a method (see the color primi‐
1807 tive for a description of methods). The point method changes the
1808 matte value of the target pixel. The replace method changes the
1809 matte value of any pixel that matches the color of the target
1810 pixel. Floodfill changes the matte value of any pixel that
1811 matches the color of the target pixel and is a neighbor, whereas
1812 filltoborder changes the matte value of any neighbor pixel that
1813 is not the border color (-bordercolor). Finally reset changes
1814 the matte value of all pixels.
1815 You can set the primitive color, font, and font bounding box
1817 color with -fill, -font, and -box respectively. Options are pro‐
1818 cessed in command line order so be sure to use these options be‐
1819 fore the -draw option.
1820 -edge <radius>
1822 detect edges within an image
1823 -emboss <radius>
1825 emboss an image
1826 -encoding <type>
1828 specify the text encoding
1829 Choose from AdobeCustom, AdobeExpert, AdobeStandard, AppleRoman,
1831 BIG5, GB2312, Latin 2, None, SJIScode, Symbol, Unicode, Wansung.
1832 -endian <type>
1834 specify endianness (MSB, LSB, or Native) of image
1835 MSB indicates big-endian (e.g. SPARC, Motorola 68K) while LSB
1837 indicates little-endian (e.g. Intel 'x86, VAX) byte ordering.
1838 Native indicates to use the normal ordering for the current CPU.
1839 This option currently only influences the CMYK, DPX, GRAY, RGB,
1840 and TIFF, formats.
1841 Use +endian to revert to unspecified endianness.
1843 -enhance
1845 apply a digital filter to enhance a noisy image
1846 -equalize
1848 perform histogram equalization to the image
1849 -extent <width>x<height>{+-}<x>{+-}<y>
1851 composite image on background color canvas image
1852 This option composites the image on a new background color
1854 (-background) canvas image of size <width>x<height>. The exist‐
1855 ing image content is composited at the position specified by ge‐
1856 ometry x and y offset and/or desired gravity (-gravity) using
1857 the current image compose (-compose) method. Image content
1858 which falls outside the bounds of the new image dimensions is
1859 discarded.
1860 For example, this command creates a thumbnail of an image, and
1862 centers it on a red color backdrop image, offsetting the canvas
1863 ten pixels to the left and five pixels up, with respect to the
1864 thumbnail:
1865 gm convert infile.jpg -thumbnail 120x80 -background red -gravity center \
1867 -extent 140x100-10-5 outfile.jpg
1868 This command reduces or expands a JPEG image to fit on an
1870 800x600 display:
1871 gm convert -size 800x600 input.jpg \
1873 -resize 800x600 -background black \
1874 -compose Copy -gravity center \
1875 -extent 800x600 \
1876 -quality 92 output.jpg
1877 If the aspect ratio of the input image isn't exactly 4:3, then
1879 the image is centered on an 800x600 black canvas.
1880 -file <filename>
1882 write annotated difference image to file
1883 If -file is specified, then an annotated difference image is
1885 generated and written to the specified file. Pixels which differ
1886 between the reference and compare images are modified from those
1887 in the compare image so that the changed pixels become more ob‐
1888 vious. Some images may require use of an alternative highlight
1889 style (see -highlight-style) or highlight color (see -highlight-
1890 color) before the changes are obvious.
1891 -fill <color>
1893 color to use when filling a graphic primitive
1894 Colors are represented in GraphicsMagick in the same form used
1896 by SVG. Use "gm convert -list color" to list named colors:
1897 name (named color)
1899 #RGB (hex numbers, 4 bits each)
1900 #RRGGBB (8 bits each)
1901 #RRRGGGBBB (12 bits each)
1902 #RRRRGGGGBBBB (16 bits each)
1903 #RGBA (4 bits each)
1904 #RRGGBBAA (8 bits each)
1905 #RRRGGGBBBAAA (12 bits each)
1906 #RRRRGGGGBBBBAAAA (16 bits each)
1907 rgb(r,g,b) (r,g,b are decimal numbers)
1908 rgba(r,g,b,a) (r,g,b,a are decimal numbers)
1909 Enclose the color specification in quotation marks to prevent
1911 the "#" or the parentheses from being interpreted by your shell.
1912 For example,
1914 gm convert -fill blue ...
1916 gm convert -fill "#ddddff" ...
1917 gm convert -fill "rgb(65000,65000,65535)" ...
1918 The shorter forms are scaled up, if necessary by replication.
1920 For example, #3af, #33aaff, and #3333aaaaffff are all equiva‐
1921 lent.
1922 See -draw for further details.
1924 -filter <type>
1926 use this type of filter when resizing an image
1927 Use this option to affect the resizing operation of an image
1929 (see -geometry). Choose from these filters (ordered by approxi‐
1930 mate increasing CPU time):
1931 Point
1933 Box
1934 Triangle
1935 Hermite
1936 Hanning
1937 Hamming
1938 Blackman
1939 Gaussian
1940 Quadratic
1941 Cubic
1942 Catrom
1943 Mitchell
1944 Lanczos
1945 Bessel
1946 Sinc
1947 The default filter is automatically selected to provide the best
1949 quality while consuming a reasonable amount of time. The
1950 Mitchell filter is used if the image supports a palette, sup‐
1951 ports a matte channel, or is being enlarged, otherwise the Lanc‐
1952 zos filter is used.
1953 -flatten
1955 flatten a sequence of images
1956 In some file formats (e.g. Photoshop's PSD) complex images may
1958 be represented by "layers" (independent images) which must be
1959 composited in order to obtain the final rendition. The -flatten
1960 option accomplishes this composition. The sequence of images is
1961 replaced by a single image created by compositing each image in
1962 turn, while respecting composition operators and page offsets.
1963 While -flatten is immediately useful for eliminating layers, it
1964 is also useful as a general-purpose composition tool.
1965 The sequence of images is terminated by the appearance of any
1967 option. If the -flatten option appears after all of the input
1968 images, all images are flattened. Also see -mosaic which is
1969 similar to -flatten except that it adds a suitably-sized canvas
1970 base image.
1971 For example, this composites an image on top of a 640x400 trans‐
1973 parent black canvas image:
1974 gm convert -size 640x300 xc:transparent \
1976 -compose over -page +0-100 \
1977 frame.png -flatten output.png
1978 and this flattens a Photoshop PSD file:
1980 gm convert input.psd -flatten output.png
1982 -flip create a "mirror image"
1984 reflect the scanlines in the vertical direction.
1986 -flop create a "mirror image"
1988 reflect the scanlines in the horizontal direction.
1990 -font <name>
1992 use this font when annotating the image with text
1993 You can tag a font to specify whether it is a PostScript, True‐
1995 Type, or X11 font. For example, Arial.ttf is a TrueType font,
1996 ps:helvetica is PostScript, and x:fixed is X11.
1997 -foreground <color>
1999 define the foreground color
2000 The color is specified using the format described under the
2002 -fill option.
2003 -format <type>
2005 the image format type
2006 When used with the mogrify utility, this option will convert any
2008 image to the image format you specify. See GraphicsMagick(1)
2009 for a list of image format types supported by GraphicsMagick, or
2010 see the output of 'gm -list format'.
2011 By default the file is written to its original name. However,
2013 if the filename extension matches a supported format, the exten‐
2014 sion is replaced with the image format type specified with -for‐
2015 mat. For example, if you specify tiff as the format type and
2016 the input image filename is image.gif, the output image filename
2017 becomes image.tiff.
2018 -format <string>
2020 output formatted image characteristics
2021 When used with the identify utility, or the convert utility with
2023 output written to the 'info:-' file specification, use this op‐
2024 tion to print information about the image in a format of your
2025 choosing. You can include the image filename, type, width,
2026 height, Exif data, or other image attributes by embedding spe‐
2027 cial format characters:
2028 %b file size
2030 %c comment
2031 %d directory
2032 %e filename extension
2033 %f filename
2034 %g page dimensions and offsets
2035 %h height
2036 %i input filename
2037 %k number of unique colors
2038 %l label
2039 %m magick
2040 %n number of scenes
2041 %o output filename
2042 %p page number
2043 %q image bit depth
2044 %r image type description
2045 %s scene number
2046 %t top of filename
2047 %u unique temporary filename
2048 %w width
2049 %x horizontal resolution
2050 %y vertical resolution
2051 %A transparency supported
2052 %C compression type
2053 %D GIF disposal method
2054 %G Original width and height
2055 %H page height
2056 %M original filename specification
2057 %O page offset (x,y)
2058 %P page dimensions (width,height)
2059 %Q compression quality
2060 %T time delay (in centi-seconds)
2061 %U resolution units
2062 %W page width
2063 %X page horizontal offset (x)
2064 %Y page vertical offset (y)
2065 %@ trim bounding box
2066 %# signature
2067 \n newline
2068 \r carriage return
2069 %% %
2070 For example,
2072 -format "%m:%f %wx%h"
2074 displays MIFF:bird.miff 512x480 for an image titled bird.miff
2076 and whose width is 512 and height is 480.
2077 If the first character of string is @, the format is read from a
2079 file titled by the remaining characters in the string. Please
2080 note that if the string comes from an untrusted source that it
2081 should be sanitized before use since this may be used to incor‐
2082 porate any readable file on the system (a security risk).
2083 The values of image type (%r) which may be returned include:
2085 Bilevel
2087 Grayscale
2088 GrayscaleMatte
2089 Palette
2090 PaletteMatte
2091 TrueColor
2092 TrueColorMatte
2093 ColorSeparation
2094 ColorSeparationMatte
2095 Optimize
2096 You can also use the following special formatting syntax to
2098 print Exif information contained in the file:
2099 %[EXIF:<tag>]
2101 Where "<tag>" may be one of the following:
2103 * (print all Exif tags, in keyword=data format)
2105 ! (print all Exif tags, in tag_number format)
2106 #hhhh (print data for Exif tag #hhhh)
2107 ImageWidth
2108 ImageLength
2109 BitsPerSample
2110 Compression
2111 PhotometricInterpretation
2112 FillOrder
2113 DocumentName
2114 ImageDescription
2115 Make
2116 Model
2117 StripOffsets
2118 Orientation
2119 SamplesPerPixel
2120 RowsPerStrip
2121 StripByteCounts
2122 XResolution
2123 YResolution
2124 PlanarConfiguration
2125 ResolutionUnit
2126 TransferFunction
2127 Software
2128 DateTime
2129 Artist
2130 WhitePoint
2131 PrimaryChromaticities
2132 TransferRange
2133 JPEGProc
2134 JPEGInterchangeFormat
2135 JPEGInterchangeFormatLength
2136 YCbCrCoefficients
2137 YCbCrSubSampling
2138 YCbCrPositioning
2139 ReferenceBlackWhite
2140 CFARepeatPatternDim
2141 CFAPattern
2142 BatteryLevel
2143 Copyright
2144 ExposureTime
2145 FNumber
2146 IPTC/NAA
2147 ExifOffset
2148 InterColorProfile
2149 ExposureProgram
2150 SpectralSensitivity
2151 GPSInfo
2152 ISOSpeedRatings
2153 OECF
2154 ExifVersion
2155 DateTimeOriginal
2156 DateTimeDigitized
2157 ComponentsConfiguration
2158 CompressedBitsPerPixel
2159 ShutterSpeedValue
2160 ApertureValue
2161 BrightnessValue
2162 ExposureBiasValue
2163 MaxApertureValue
2164 SubjectDistance
2165 MeteringMode
2166 LightSource
2167 Flash
2168 FocalLength
2169 MakerNote
2170 UserComment
2171 SubSecTime
2172 SubSecTimeOriginal
2173 SubSecTimeDigitized
2174 FlashPixVersion
2175 ColorSpace
2176 ExifImageWidth
2177 ExifImageLength
2178 InteroperabilityOffset
2179 FlashEnergy
2180 SpatialFrequencyResponse
2181 FocalPlaneXResolution
2182 FocalPlaneYResolution
2183 FocalPlaneResolutionUnit
2184 SubjectLocation
2185 ExposureIndex
2186 SensingMethod
2187 FileSource
2188 SceneType
2189 JPEG specific information (from reading a JPEG file) may be ob‐
2191 tained like this:
2192 %[JPEG-<tag>]
2194 Where "<tag>" may be one of the following:
2196 * (all JPEG-related tags, in
2198 keyword=data format)
2199 Quality IJG JPEG "quality" estimate
2200 Colorspace JPEG colorspace numeric ID
2201 Colorspace-Name JPEG colorspace name
2202 Sampling-factors JPEG sampling factors
2203 Please note that JPEG has no notion of "quality" and that the
2205 quality metric used by, and estimated by the software is based
2206 on the quality metric established by IJG JPEG 6b. Other en‐
2207 coders (e.g. that used by Adobe Photoshop) use different encod‐
2208 ing metrics.
2209 Surround the format specification with quotation marks to pre‐
2211 vent your shell from misinterpreting any spaces and square
2212 brackets.
2213 -frame <width>x<height>+<outer bevel width>+<inner bevel width>
2215 surround the image with an ornamental border
2216 See -geometry for details about the geometry specification. The
2218 -frame option is not affected by the -gravity option.
2219 The color of the border is specified with the -mattecolor com‐
2221 mand line option.
2222 -frame include the X window frame in the imported image
2224 -fuzz <distance>{%}
2226 colors within this Euclidean distance are considered equal
2227 A number of algorithms search for a target color. By default the
2229 color must be exact. Use this option to match colors that are
2230 close (in Euclidean distance) to the target color in RGB 3D
2231 space. For example, if you want to automatically trim the edges
2232 of an image with -trim but the image was scanned and the target
2233 background color may differ by a small amount. This option can
2234 account for these differences.
2235 The distance can be in absolute intensity units or, by appending
2237 "%", as a percentage of the maximum possible intensity (255,
2238 65535, or 4294967295).
2239 -gamma <value>
2241 level of gamma correction
2242 The same color image displayed on two different workstations may
2244 look different due to differences in the display monitor. Use
2245 gamma correction to adjust for this color difference. Reasonable
2246 values extend from 0.8 to 2.3. Gamma less than 1.0 darkens the
2247 image and gamma greater than 1.0 lightens it. Large adjustments
2248 to image gamma may result in the loss of some image information
2249 if the pixel quantum size is only eight bits (quantum range 0 to
2250 255).
2251 You can apply separate gamma values to the red, green, and blue
2253 channels of the image with a gamma value list delimited with
2254 slashes (e.g., 1.7/2.3/1.2).
2255 Use +gamma value to set the image gamma level without actually
2257 adjusting the image pixels. This option is useful if the image
2258 is of a known gamma but not set as an image attribute (e.g. PNG
2259 images).
2260 -gaussian <radius>{x<sigma>}
2262 blur the image with a Gaussian operator
2263 Use the given radius and standard deviation (sigma).
2265 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
2267 Specify dimension, offset, and resize options.
2268 The -geometry option is used for a number of different purposes,
2270 depending on the utility it is used with.
2271 For the X11 commands ('animate', 'display', and 'import'), it
2273 specifies the preferred size and location of the Image window.
2274 By default, the window size is the image size and the location
2275 is chosen by you (or your window manager) when it is mapped.
2276 For the 'import', 'convert', 'mogrify' utility commands it may
2277 be used to specify the desired size when resizing an image. In
2278 this case, symbols representing resize options may be appended
2279 to the geometry string to influence how the resize request is
2280 treated.
2281 See later notes corresponding to usage by particular commands.
2283 The following notes apply to when -geometry is used to express a
2284 resize request, taking into account the current properties of
2285 the image.
2286 By default, the width and height are maximum values. That is,
2288 the image is expanded or contracted to fit the width and height
2289 value while maintaining the aspect ratio of the image.
2290 Append a ^ to the geometry so that the image aspect ratio is
2292 maintained when the image is resized, but the resulting width or
2293 height are treated as minimum values rather than maximum values.
2294 Append a ! (exclamation point) to the geometry to force the im‐
2296 age size to exactly the size you specify. For example, if you
2297 specify 640x480! the image width is set to 640 pixels and height
2298 to 480.
2299 If only the width is specified, without the trailing 'x', then
2301 height is set to width (e.g., -geometry 100 is the same as -ge‐
2302 ometry 100x100). If only the width is specified but with the
2303 trailing 'x', then width assumes the value and the height is
2304 chosen to maintain the aspect ratio of the image. Similarly, if
2305 only the height is specified prefixed by 'x' (e.g., -geometry
2306 x256), the width is chosen to maintain the aspect ratio.
2307 To specify a percentage width or height instead, append %. The
2309 image size is multiplied by the width and height percentages to
2310 obtain the final image dimensions. To increase the size of an
2311 image, use a value greater than 100 (e.g. 125%). To decrease an
2312 image's size, use a percentage less than 100.
2313 Use @ to specify the maximum area in pixels of an image.
2315 Use > to change the dimensions of the image only if its width or
2317 height exceeds the geometry specification. < resizes the image
2318 only if both of its dimensions are less than the geometry speci‐
2319 fication. For example, if you specify '640x480>' and the image
2320 size is 256x256, the image size does not change. However, if the
2321 image is 512x512 or 1024x1024, it is resized to 480x480. En‐
2322 close the geometry specification in quotation marks to prevent
2323 the < or > from being interpreted by your shell as a file redi‐
2324 rection.
2325 When used with animate and display, offsets are handled in the
2327 same manner as in X(1) and the -gravity option is not used. If
2328 the x is negative, the offset is measured leftward from the
2329 right edge of the screen to the right edge of the image being
2330 displayed. Similarly, negative y is measured between the bottom
2331 edges. The offsets are not affected by "%"; they are always
2332 measured in pixels.
2333 When used as a composite option, -geometry gives the dimensions
2335 of the image and its location with respect to the composite im‐
2336 age. If the -gravity option is present with NorthEast, East, or
2337 SouthEast gravity, the x represents the distance from the right
2338 edge of the image to the right edge of the composite image.
2339 Similarly, if the -gravity option is present with SouthWest,
2340 South, or SouthEast gravity, y is measured between the bottom
2341 edges. Accordingly, a positive offset will never point in the
2342 direction outside of the image. The offsets are not affected by
2343 "%"; they are always measured in pixels. To specify the dimen‐
2344 sions of the composite image, use the -resize option.
2345 When used as a convert, import or mogrify option, -geometry is
2347 synonymous with -resize and specifies the size of the output im‐
2348 age. The offsets, if present, are ignored.
2349 When used as a montage option, -geometry specifies the image
2351 size and border size for each tile; default is 256x256+0+0.
2352 Negative offsets (border dimensions) are meaningless. The
2353 -gravity option affects the placement of the image within the
2354 tile; the default gravity for this purpose is Center. If the
2355 "%" sign appears in the geometry specification, the tile size is
2356 the specified percentage of the original dimensions of the first
2357 tile. To specify the dimensions of the montage, use the -resize
2358 option.
2359 -gravity <type>
2361 direction primitive gravitates to when annotating the image.
2362 Choices are: NorthWest, North, NorthEast, West, Center, East,
2364 SouthWest, South, SouthEast.
2365 The direction you choose specifies where to position the text
2367 when annotating the image. For example Center gravity forces the
2368 text to be centered within the image. By default, the image
2369 gravity is NorthWest. See -draw for more details about graphic
2370 primitives. Only the text primitive is affected by the -gravity
2371 option.
2372 The -gravity option is also used in concert with the -geometry
2374 option and other options that take <geometry> as a parameter,
2375 such as the -crop option. See -geometry for details of how the
2376 -gravity option interacts with the <x> and <y> parameters of a
2377 geometry specification.
2378 When used as an option to composite, -gravity gives the direc‐
2380 tion that the image gravitates within the composite.
2381 When used as an option to montage, -gravity gives the direction
2383 that an image gravitates within a tile. The default gravity is
2384 Center for this purpose.
2385 -green-primary <x>,<y>
2387 green chromaticity primary point
2388 -hald-clut <clut>
2390 apply a Hald CLUT to the image
2391 A Hald CLUT ("Color Look-Up Table") is a special square color
2393 image which contains a look-up table for red, green, and blue.
2394 The size of the Hald CLUT image is determined by its order. The
2395 width (and height) of a Hald CLUT is the cube of the order. For
2396 example, a Hald CLUT of order 8 is 512x512 pixels (262,144 col‐
2397 ors) and of order 16 is 4096x4096 (16,777,216 colors). A spe‐
2398 cial CLUT is the identity CLUT which which causes no change to
2399 the input image. In order to use the Hald CLUT, one takes an
2400 identity CLUT and adjusts its colors in some way. The modified
2401 CLUT can then be used to transform any number of images in an
2402 identical way.
2403 GraphicsMagick contains a built-in identity CLUT generator via
2405 the IDENTITY coder. For example reading from the file name
2406 IDENTITY:8 returns an identity CLUT of order 8. Typical Hald
2407 CLUT identity images have an order of between 8 and 16. The de‐
2408 fault order for the IDENTITY CLUT generator is 8. Interpolation
2409 is used so it is not usually necessary for CLUT images to be
2410 very large. The PNG file format is ideal for storing Hald CLUT
2411 images because it compresses them very well.
2412 -help print usage instructions
2414 -highlight-color <color>
2416 pixel annotation color
2417 Specifies the color to use when annotating difference pixels.
2419 -highlight-style <style>
2421 pixel annotation style
2422 Specifies the pixel difference annotation style used to draw at‐
2424 tention to changed pixels. May be one of Assign, Threshold,
2425 Tint, or XOR; where Assign replaces the pixel with the highlight
2426 color (see -highlight-color), Threshold replaces the pixel with
2427 black or white based on the difference in intensity, Tint alpha
2428 tints the pixel with the highlight color, and XOR does an XOR
2429 between the pixel and the highlight color.
2430 -iconGeometry <geometry>
2432 specify the icon geometry
2433 Offsets, if present in the geometry specification, are handled
2435 in the same manner as the -geometry option, using X11 style to
2436 handle negative offsets.
2437 -iconic
2439 iconic animation
2440 -immutable
2442 make image immutable
2443 -implode <factor>
2445 implode image pixels about the center
2446 -intent <type>
2448 use this type of rendering intent when managing the image color
2449 Use this option to affect the the color management operation of
2451 an image (see -profile). Choose from these intents: Absolute,
2452 Perceptual, Relative, Saturation.
2453 The default intent is undefined.
2455 -interlace <type>
2457 the type of interlacing scheme
2458 Choices are: None, Line, Plane, or Partition. The default is
2460 None.
2461 This option is used to specify the type of interlacing scheme
2463 for raw image formats such as RGB or YUV. None means do not in‐
2464 terlace (RGBRGBRGBRGBRGBRGB...),
2465 Line uses scanline interlacing
2467 (RRR...GGG...BBB...RRR...GGG...BBB...), and Plane uses plane in‐
2468 terlacing (RRRRRR...GGGGGG...BBBBBB...).
2469 Partition is like plane except the different planes are saved to
2471 individual files (e.g. image.R, image.G, and image.B).
2472 Use Line to create an interlaced PNG or GIF or progressive JPEG
2474 image.
2475 -label <name>
2477 assign a label to an image
2478 Use this option to assign a specific label to the image, when
2480 writing to an image format that supports labels, such as TIFF,
2481 PNG, MIFF, or PostScript. You can include the the image file‐
2482 name, type, width, height, or other image attribute by embedding
2483 special format character. A label is not drawn on the image,
2484 but is embedded in the image datastream via a "Label" tag or
2485 similar mechanism. If you want the label to be visible on the
2486 image itself, use the -draw option. See -comment for details.
2487 For example,
2489 -label "%m:%f %wx%h"
2491 produces an image label of MIFF:bird.miff 512x480 for an image
2493 titled bird.miff and whose width is 512 and height is 480.
2494 If the first character of string is @, the image label is read
2496 from a file titled by the remaining characters in the string.
2497 Please note that if the string comes from an untrusted source
2498 that it should be sanitized before use since otherwise the con‐
2499 tent of an arbitrary readable file might be incorporated into
2500 the image label (a security risk).
2501 If the -label option appears multiple times, only the last label
2503 is stored.
2504 In PNG images, the label is stored in a tEXt or zTXt chunk with
2506 the keyword "label".
2507 When converting to PostScript, use this option to specify a
2509 header string to print above the image. Specify the label font
2510 with -font.
2511 When creating a montage, by default the label associated with an
2513 image is displayed with the corresponding tile in the montage.
2514 Use the +label option to suppress this behavior.
2515 -lat <width>x<height>{+-}<offset>{%}
2519 perform local adaptive thresholding
2520 Perform local adaptive thresholding using the specified width,
2522 height, and offset. The offset is a distance in sample space
2523 from the mean, as an absolute integer ranging from 0 to the max‐
2524 imum sample value or as a percentage. If the percent option is
2525 supplied, then the offset is computed as a percentage of the
2526 quantum range. It is strongly recommended to use the percent
2527 option so that results are not sensitive to pixel quantum depth.
2528 For example,
2530 -colorspace gray -lat "10x10-5%"
2532 will help clarify a scanned grayscale or color document, produc‐
2534 ing a bi-level equivalent.
2535 -level <black_point>{,<gamma>}{,<white_point>}{%}
2537 adjust the level of image contrast
2538 Give one, two or three values delimited with commas: black-
2540 point, gamma, white-point (e.g. 10,1.0,250 or 2%,0.5,98%). The
2541 black and white points range from 0 to MaxRGB or from 0 to 100%;
2542 if the white point is omitted it is set to MaxRGB-black_point.
2543 If a "%" sign is present anywhere in the string, the black and
2544 white points are percentages of MaxRGB. Gamma is an exponent
2545 that ranges from 0.1 to 10.; if it is omitted, the default of
2546 1.0 (no gamma correction) is assumed. This interface works simi‐
2547 lar to Photoshop's "Image->Adjustments->Levels..." "Input Lev‐
2548 els" interface.
2549 -limit <type> <value>
2551 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
2552 resource limit
2553 By default, resource limits are estimated based on the available
2555 resources and capabilities of the system. The resource limits
2556 are Disk, maximum total disk space consumed; File, maximum num‐
2557 ber of file descriptors allowed to be open at once; Map, maximum
2558 total number of file bytes which may be memory mapped; Memory,
2559 maximum total number of bytes of heap memory used for image
2560 storage; Pixels, maximum absolute image size (per image); Width,
2561 maximum image pixels width; Height, maximum image pixels height;
2562 Read, maximum number of uncompressed bytes to read; and Threads,
2563 the maximum number of worker threads to use per OpenMP thread
2564 team.
2565 The Disk and Map resource limits are used to decide if (for a
2567 given image) the decoded image ("pixel cache") should be stored
2568 in heap memory (RAM), in a memory-mapped disk file, or in a disk
2569 file accessed via read/write I/O.
2570 The number of total pixels in one image (Pixels), and/or the
2572 width/height (Width/Height), may be limited in order to force
2573 the reading, or creation of images larger than the limit (in
2574 pixels) to intentionally fail. The disk limit (Disk) establishes
2575 an overall limit since using the disk is the means of last re‐
2576 sort. When the disk limit has been reached, no more images may
2577 be read.
2578 The amount of uncompressed data read when reading one image may
2580 be limited by the Read limit. Reading the image fails when the
2581 limit is hit. This option is useful if the data is read from a
2582 stream (pipe) or from a compressed file such as a gzipped file.
2583 Some files are very compressable and so a small compressed file
2584 can decompress to a huge amount of data. This option also de‐
2585 fends against files which produce seemingly endless loops while
2586 decoding by seeking backwards in the file.
2587 The value argument is an absolute value, but may have standard
2589 binary suffix characters applied ('K', 'M', 'G', 'T', 'P', 'E')
2590 to apply a scaling to the value (based on a multiplier of 1024).
2591 Any additional characters are ignored. For example, '-limit Pix‐
2592 els 10MP' limits the maximum image size to 10 megapixels and
2593 '-limit memory 32MB -limit map 64MB' limits memory and memory
2594 mapped files to 32 megabytes and 64 megabytes respectively.
2595 Resource limits may also be set using environment variables. The
2597 environment variables MAGICK_LIMIT_DISK, MAGICK_LIMIT_FILES,
2598 MAGICK_LIMIT_MAP, MAGICK_LIMIT_MEMORY, MAGICK_LIMIT_PIXELS, MAG‐
2599 ICK_LIMIT_WIDTH, MAGICK_LIMIT_HEIGHT. MAGICK_LIMIT_READ, and
2600 OMP_NUM_THREADS may be used to set the limits for disk space,
2601 open files, memory mapped size, heap memory, per-image pixels,
2602 image width, image height, and threads respectively.
2603 Use the option -list resource list the current limits.
2605 -linewidth
2607 the line width for subsequent draw operations
2608 -list <type>
2610 the type of list
2611 Choices are: Color, Delegate, Format, Magic, Module, Resource,
2613 or Type. The Module option is only available if GraphicsMagick
2614 was built to support loadable modules.
2615 This option lists information about the GraphicsMagick configu‐
2617 ration.
2618 -log <string>
2620 Specify format for debug log
2621 This option specifies the format for the log printed when the
2623 -debug option is active.
2624 You can display the following components by embedding special
2626 format characters:
2627 %d domain
2629 %e event
2630 %f function
2631 %l line
2632 %m module
2633 %p process ID
2634 %r real CPU time
2635 %t wall clock time
2636 %u user CPU time
2637 %% percent sign
2638 \n newline
2639 \r carriage return
2640 For example:
2642 gm convert -debug coders -log "%u %m:%l %e" in.gif out.png
2644 The default behavior is to print all of the components.
2646 -loop <iterations>
2648 add Netscape loop extension to your GIF animation
2649 A value other than zero forces the animation to repeat itself up
2651 to iterations times.
2652 -magnify
2654 magnify the image
2655 The image size is doubled using linear interpolation.
2657 -magnify <factor>
2659 magnify the image
2660 The displayed image is magnified by factor.
2662 -map <filename>
2664 choose a particular set of colors from this image
2665 [convert or mogrify]
2667 By default, color reduction chooses an optimal set of colors
2669 that best represent the original image. Alternatively, you can
2670 choose a particular set of colors from an image file with this
2671 option.
2672 Use +map to reduce all images in the image sequence that follows
2674 to a single optimal set of colors that best represent all the
2675 images. The sequence of images is terminated by the appearance
2676 of any option. If the +map option appears after all of the in‐
2677 put images, all images are mapped.
2678 -map <type>
2680 display image using this type.
2681 [animate or display]
2683 Choose from these Standard Colormap types:
2685 best
2687 default
2688 gray
2689 red
2690 green
2691 blue
2692 The X server must support the Standard Colormap you choose, oth‐
2694 erwise an error occurs. Use list as the type and display
2695 searches the list of colormap types in top-to-bottom order until
2696 one is located. See xstdcmap(1) for one way of creating Standard
2697 Colormaps.
2698 -mask <filename>
2700 Specify a clipping mask
2701 The image read from the file is used as a clipping mask. It
2703 must have the same dimensions as the image being masked.
2704 If the mask image contains an opacity channel, the opacity of
2706 each pixel is used to define the mask. Otherwise, the intensity
2707 (gray level) of each pixel is used. Unmasked (black) pixels are
2708 modified while masked pixels (not black) are protected from al‐
2709 teration.
2710 Use +mask to remove the clipping mask.
2712 It is not necessary to use -clip to activate the mask; -clip is
2714 implied by -mask.
2715 -matte store matte channel if the image has one
2717 If the image does not have a matte channel, create an opaque
2719 one.
2720 Use +matte to ignore the matte channel (treats it as opaque) and
2722 to avoid writing a matte channel in the output file.
2723 For the compare command, -matte will add an opaque matte channel
2725 to images if they do not already have a matte channel, and matte
2726 will be enabled for both images. Likewise, if +matte is used,
2727 the matte channel is disabled for both images. This makes it
2728 easier to compare images regardless of if they already have a
2729 matte channel.
2730 -mattecolor <color>
2732 specify the color to be used with the -frame option
2733 The color is specified using the format described under the
2735 -fill option.
2736 -maximum-error <limit>
2738 specifies the maximum amount of total image error
2739 Specifies the maximum amount of total image error (based on com‐
2741 parison using a specified metric) before an error ("image dif‐
2742 ference exceeds limit") is reported. The error is reported via
2743 a non-zero command execution return status.
2744 -median <radius>
2746 apply a median filter to the image
2747 -metric <metric>
2749 comparison metric (MAE, MSE, PAE, PSNR, RMSE)
2750 -minify <factor>
2752 minify the image
2753 The image size is halved using linear interpolation.
2755 -mode <value>
2757 mode of operation
2758 The available montage modes are frame to place the images in a
2760 rectangular grid while adding a decorative frame with drop‐
2761 shadow, unframe to place undecorated images in a rectangular
2762 grid, and concatenate to pack the images closely together with‐
2763 out any well-defined grid or decoration.
2764 -modulate brightness[,saturation[,hue]]
2766 vary the brightness, saturation, and hue of an image
2767 Specify the percent change in brightness, color saturation, and
2769 hue separated by commas. Default argument values are 100 per‐
2770 cent, resulting in no change. For example, to increase the color
2771 brightness by 20% and decrease the color saturation by 10% and
2772 leave the hue unchanged, use: -modulate 120,90.
2773 Hue is the percentage of absolute rotation from the current po‐
2775 sition. For example 50 results in a counter-clockwise rotation
2776 of 90 degrees, 150 results in a clockwise rotation of 90 de‐
2777 grees, with 0 and 200 both resulting in a rotation of 180 de‐
2778 grees.
2779 -monitor
2781 show progress indication
2782 A simple command-line progress indication is shown while the
2784 command is running. The process indication shows the operation
2785 currently being performed and the percent completed. Commands
2786 using X11 may replace the command line progress indication with
2787 a graphical one once an image has been displayed.
2788 -monochrome
2790 transform the image to black and white
2791 -morph <frames>
2793 morphs an image sequence
2794 Both the image pixels and size are linearly interpolated to give
2796 the appearance of a meta-morphosis from one image to the next.
2797 The sequence of images is terminated by the appearance of any
2799 option. If the -morph option appears after all of the input im‐
2800 ages, all images are morphed.
2801 -mosaic
2803 create a mosaic from an image or an image sequence
2804 The -mosaic option provides a flexible way to composite one or
2806 more images onto a solid-color canvas image. It works similar to
2807 -flatten except that a base canvas image is automatically cre‐
2808 ated with a suitable size given the image size, page dimensions,
2809 and page offsets of images to be composited. The color of the
2810 base canvas image may be set via the -background option. The
2811 default canvas color is 'white', but 'black' or 'transparent'
2812 may be more suitable depending on the composition algorithm re‐
2813 quested.
2814 The -compose option may be used to specify the composition algo‐
2816 rithm to use when compositing the subsequent image on the base
2817 canvas.
2818 The -page option can be used to establish the dimensions of the
2820 mosaic and to position the subsequent image within the mosaic.
2821 If the -page argument does not specify width and height, then
2822 the canvas dimensions are evaluated based on the image sizes and
2823 offsets.
2824 The sequence of images is terminated by the appearance of any
2826 option. If the -mosaic option appears after all of the input
2827 images, all images are included in the mosaic.
2828 The following is an example of composing an image based on red,
2830 green, and blue layers extracted from a sequence of images and
2831 pasted on the canvas image at specified offsets:
2832 gm convert -background black \
2834 -compose CopyRed -page +0-100 red.png \
2835 -compose CopyGreen -page +0+40 green.png \
2836 -compose CopyBlue -page +0+180 blue.png \
2837 -mosaic output.png
2838 -motion-blur <radius>{x<sigma>}{+angle}
2840 Simulate motion blur
2841 Simulate motion blur by convolving the image with a Gaussian op‐
2843 erator of the given radius and standard deviation (sigma). For
2844 reasonable results, radius should be larger than sigma. If ra‐
2845 dius is zero, then a suitable radius is automatically selected
2846 based on sigma. The angle specifies the angle that the object is
2847 coming from (side which is blurred).
2848 -name name an image
2850 -negate
2852 replace every pixel with its complementary color
2853 The red, green, and blue intensities of an image are negated.
2855 White becomes black, yellow becomes blue, etc. Use +negate to
2856 only negate the grayscale pixels of the image.
2857 -noise <radius|type>
2859 add or reduce noise in an image
2860 The principal function of noise peak elimination filter is to
2862 smooth the objects within an image without losing edge informa‐
2863 tion and without creating undesired structures. The central idea
2864 of the algorithm is to replace a pixel with its next neighbor in
2865 value within a pixel window, if this pixel has been found to be
2866 noise. A pixel is defined as noise if and only if this pixel is
2867 a maximum or minimum within the pixel window.
2868 Use radius to specify the width of the neighborhood.
2870 Use +noise followed by a noise type to add noise to an image.
2872 The noise added modulates the existing image pixels. Choose from
2873 these noise types:
2874 Uniform
2876 Gaussian
2877 Multiplicative
2878 Impulse
2879 Laplacian
2880 Poisson
2881 Random (uniform distribution)
2882 -noop NOOP (no option)
2884 The -noop option can be used to terminate a group of images and
2886 reset all options to their default values, when no other option
2887 is desired.
2888 -normalize
2890 transform image to span the full range of color values
2891 This is a contrast enhancement technique based on the image his‐
2893 togram.
2894 When computing the contrast enhancement values, the histogram
2896 edges are truncated so that the majority of the image pixels are
2897 considered in the constrast enhancement, and outliers (e.g. ran‐
2898 dom noise or minute details) are ignored. The default is that
2899 0.1 percent of the histogram entries are ignored. The percent‐
2900 age of the histogram to ignore may be specified by using the
2901 -set option with the histogram-threshold parameter similar to
2902 -set histogram-threshold 0.01 to specify 0.01 percent. Use 0
2903 percent to use the entire histogram, with possibly diminished
2904 contrast enhancement.
2905 -opaque <color>
2907 change this color to the pen color within the image
2908 The color is specified using the format described under the
2910 -fill option. The color is replaced if it is identical to the
2911 target color, or close enough to the target color in a 3D space
2912 as defined by the Euclidean distance specified by -fuzz.
2913 See -fill and -fuzz for more details.
2915 -operator channel operator rvalue[%]
2917 apply a mathematical, bitwise, or value operator to an image
2918 channel
2919 Apply a low-level mathematical, bitwise, or value operator to a
2921 selected image channel or all image channels. Operations which
2922 result in negative results are reset to zero, and operations
2923 which overflow the available range are reset to the maximum pos‐
2924 sible value.
2925 Select a channel from: Red, Green, Blue, Opacity, Matte, Cyan,
2927 Magenta, Yellow, Black, All, or Gray. All only modifies the
2928 color channels and does not modify the Opacity channel. Except
2929 for the threshold operators, All operates on each channel inde‐
2930 pendently so that operations are on a per-channel basis.
2931 Gray treats the color channels as a grayscale intensity and per‐
2933 forms the requested operation on the equivalent pixel intensity
2934 so the result is a gray image. Select an operator from Add,
2935 And, Assign, Depth, Divide, Gamma, Negate, LShift, Log, Max,
2936 Min, Multiply, Or, Pow, RShift, Subtract, Threshold, Threshold-
2937 White, Threshold-White-Negate, Threshold-Black, Threshold-Black-
2938 Negate, Xor, Noise-Gaussian, Noise-Impulse, Noise-Laplacian,
2939 Noise-Multiplicative, Noise-Poisson, Noise-Random, and Noise-
2940 Uniform.
2941 Rvalue may be any floating point or integer value. Normally
2943 rvalue will be in the range of 0 to MaxRGB, where MaxRGB is the
2944 largest quantum value supported by the GraphicsMagick build
2945 (255, 65535, or 4294967295) but values outside this range are
2946 useful for some arithmetic operations. Arguments to logical or
2947 bit-wise operations are rounded to a positive integral value
2948 prior to use. If a percent (%) symbol is appended to the argu‐
2949 ment, then the argument has a range of 0 to 100 percent.
2950 The following is a description of the operators:
2952 Add
2955 Result is rvalue added to channel value.
2957 And
2959 Result is the logical AND of rvalue with channel value.
2961 Assign
2963 Result is rvalue.
2965 Depth
2967 Result is channel value adjusted so that it may be (ap‐
2969 proximately) stored in the specified number of bits with‐
2970 out additional loss.
2971 Divide
2973 Result is channel value divided by rvalue.
2975 Gamma
2977 Result is channel value gamma adjusted by rvalue.
2979 LShift
2981 Result is channel value bitwise left shifted by rvalue
2983 bits.
2984 Log
2986 Result is computed as log(value*rvalue+1)/log(rvalue+1).
2988 Max
2990 Result is assigned to rvalue if rvalue is greater than
2992 value.
2993 Min
2995 Result is assigned to rvalue if rvalue is less than value.
2997 Multiply
2999 Result is channel value multiplied by rvalue.
3001 Negate
3003 Result is inverse of channel value (like a film negative).
3005 An rvalue must be supplied but is currently not used. In‐
3006 verting the image twice results in the original image.
3007 Or
3009 Result is the logical OR of rvalue with channel value.
3011 Pow
3013 Result is computed as pow(value,rvalue). Similar to Gamma
3015 except that rvalue is not inverted.
3016 RShift
3018 Result is channel value bitwise right shifted by rvalue
3020 bits.
3021 Subtract
3023 Result is channel value minus rvalue.
3025 Threshold
3027 Result is maximum (white) if channel value is greater than
3029 rvalue, or minimum (black) if it is less than or equal to
3030 rvalue. If all channels are specified, then thresholding
3031 is done based on computed pixel intensity.
3032 Threshold-white
3034 Result is maximum (white) if channel value is greater than
3036 rvalue and is unchanged if it is less than or equal to
3037 rvalue. This can be used to remove apparent noise from the
3038 bright parts of an image. If all channels are specified,
3039 then thresholding is done based on computed pixel inten‐
3040 sity.
3041 Threshold-White-Negate
3043 Result is set to black if channel value is greater than
3045 rvalue and is unchanged if it is less than or equal to
3046 rvalue. If all channels are specified, then thresholding
3047 is done based on computed pixel intensity.
3048 Threshold-black
3050 Result is minimum (black) if channel value is less than
3052 than rvalue and is unchanged if it is greater than or
3053 equal to rvalue. This can be used to remove apparent noise
3054 from the dark parts of an image. If all channels are spec‐
3055 ified, then thresholding is done based on computed pixel
3056 intensity.
3057 Threshold-Black-Negate
3059 Result is set to white if channel value is less than than
3061 rvalue and is unchanged if it is greater than or equal to
3062 rvalue. If all channels are specified, then thresholding
3063 is done based on computed pixel intensity.
3064 Xor
3066 Result is the logical XOR of rvalue with channel value. An
3068 interesting property of XOR is that performing the same
3069 operation twice results in the original value.
3070 Noise-Gaussian
3072 Result is the current channel value modulated with gauss‐
3074 ian noise according to the intensity specified by rvalue.
3075 Noise-Impulse
3077 Result is the current channel value modulated with impulse
3079 noise according to the intensity specified by rvalue.
3080 Noise-Laplacian
3082 Result is the current channel value modulated with lapla‐
3084 cian noise according to the intensity specified by rvalue.
3085 Noise-Multiplicative
3087 Result is the current channel value modulated with multi‐
3089 plicative gaussian noise according to the intensity speci‐
3090 fied by rvalue.
3091 Noise-Poisson
3093 Result is the current channel value modulated with poisson
3095 noise according to the intensity specified by rvalue.
3096 Noise-Random
3098 Result is the current channel value modulated with random
3100 (uniform distribution) noise according to the intensity
3101 specified by rvalue. The initial noise intensity
3102 (rvalue=1.0) is the range of one pixel quantum span.
3103 Noise-Uniform
3105 Result is the channel value with uniform noise applied ac‐
3107 cording to the intensity specified by rvalue.
3108 As an example, the Assign operator assigns a fixed value to a
3113 channel. For example, this command sets the red channel to the
3114 mid-range value:
3115 gm convert in.bmp -operator red assign "50%" out.bmp
3117 The following applies 50% thresholding to the image and returns
3119 a gray image:
3120 gm convert in.bmp -operator gray threshold "50%" out.bmp
3122 -ordered-dither <channeltype> <NxN>
3124 ordered dither the image
3125 The channel or channels specified in the channeltype argument
3127 are reduced to binary, using an ordered dither method. The
3128 choices for channeltype are All, Intensity, Red, Green, Blue,
3129 Cyan, Magenta, Yellow, Black, and Opacity
3130 When channeltype is "All", the color samples are dithered into a
3132 gray level and then that gray level is stored in the three color
3133 channels. Separately, the opacity channel is dithered into a
3134 bilevel opacity value which is stored in the opacity channel.
3135 When channeltype is "Intensity", only the color samples are
3137 dithered. When channeltype is "opacity" or "matte", only the
3138 opacity channel is dithered. When a color channel is specified,
3139 only that channel is dithered.
3140 The choices for N are 2 through 7. The image is divided into NxN
3142 pixel tiles. In each tile, some or all pixels are turned to
3143 white depending on their intensity. For each N, (N**2)+1 levels
3144 of gray can be represented. For N == 2, 3, or 4, the pixels are
3145 turned to white in an order that maximizes dispersion (i.e., re‐
3146 duces granularity), while for N == 5, 6, and 7, they are turned
3147 to white in an order that creates a roughly circular black blob
3148 in the middle of each tile. An attractive "half-tone" looking
3149 image can be obtained by first rotating the image 45 degrees,
3150 performing a 5x5 ordered-dither operation, then rotating it back
3151 to the original orientation and cropping to the original image
3152 dimensions. If the original image is gamma-encoded, it is ad‐
3153 viseable to convert it to linear intensity first, e.g., with the
3154 "-gamma 0.45455" option.
3155 -output-directory <directory>
3157 output files to directory
3158 Use -output-directory to specify a directory under which to
3160 write the output files. Normally mogrify overwrites the input
3161 files, but with this option the output files may be written to a
3162 different directory tree so that the input files are preserved.
3163 The algorithm used preserves all of the input path specification
3164 in the output path so that the user-specified input path (in‐
3165 cluding any sub-directory part) is appended to the output path.
3166 If the input file lacks an extension, then a suitable extension
3167 is automatically added to the output file. The user is respon‐
3168 sible for creating the output directory specified as an argu‐
3169 ment, but subdirectories will be created as needed if the -cre‐
3170 ate-directories option is supplied. This option may be used to
3171 apply transformations on files from one directory and write the
3172 transformed files to a different directory. In conjunction with
3173 -create-directories, this option is designed to support trans‐
3174 forming whole directory trees of files provided that the rela‐
3175 tive path of the input file is included as part the list of
3176 filenames.
3177 -orient <orientation>
3179 Set the image orientation attribute
3180 Sets the image orientation attribute. The image orientation at‐
3182 tribute is compatible with the TIFF orientation tag (and the
3183 EXIF orientation tag). Accepted values are undefined, TopLeft,
3184 TopRight, BottomRight, BottomLeft, LeftTop, RightTop, RightBot‐
3185 tom, LeftBottom, and hyphenated versions thereof (e.g. left-bot‐
3186 tom). Please note that GraphicsMagick does not include an EXIF
3187 editor so if an EXIF profile is written to the output image, the
3188 value in the EXIF profile might not match the image. It is pos‐
3189 sible for an image file to indicate its orientation in several
3190 different ways simultaneously.
3191 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
3193 size and location of an image canvas
3194 Use this option to specify the dimensions of the PostScript page
3196 in dots per inch or a TEXT page in pixels. The choices for a
3197 PostScript page are:
3198 11x17 792 1224
3200 Ledger 1224 792
3201 Legal 612 1008
3202 Letter 612 792
3203 LetterSmall 612 792
3204 ArchE 2592 3456
3205 ArchD 1728 2592
3206 ArchC 1296 1728
3207 ArchB 864 1296
3208 ArchA 648 864
3209 A0 2380 3368
3210 A1 1684 2380
3211 A2 1190 1684
3212 A3 842 1190
3213 A4 595 842
3214 A4Small 595 842
3215 A5 421 595
3216 A6 297 421
3217 A7 210 297
3218 A8 148 210
3219 A9 105 148
3220 A10 74 105
3221 B0 2836 4008
3222 B1 2004 2836
3223 B2 1418 2004
3224 B3 1002 1418
3225 B4 709 1002
3226 B5 501 709
3227 C0 2600 3677
3228 C1 1837 2600
3229 C2 1298 1837
3230 C3 918 1298
3231 C4 649 918
3232 C5 459 649
3233 C6 323 459
3234 Flsa 612 936
3235 Flse 612 936
3236 HalfLetter 396 612
3237 For convenience you can specify the page size by media (e.g. A4,
3239 Ledger, etc.). Otherwise, -page behaves much like -geometry
3240 (e.g. -page letter+43+43>).
3241 This option is also used to place subimages when writing to a
3243 multi-image format that supports offsets, such as GIF89 and MNG.
3244 When used for this purpose the offsets are always measured from
3245 the top left corner of the canvas and are not affected by the
3246 -gravity option. To position a GIF or MNG image, use
3247 -page{+-}<x>{+-}<y> (e.g. -page +100+200). When writing to a
3248 MNG file, a -page option appearing ahead of the first image in
3249 the sequence with nonzero width and height defines the width and
3250 height values that are written in the MHDR chunk. Otherwise,
3251 the MNG width and height are computed from the bounding box that
3252 contains all images in the sequence. When writing a GIF89 file,
3253 only the bounding box method is used to determine its dimen‐
3254 sions.
3255 For a PostScript page, the image is sized as in -geometry and
3257 positioned relative to the lower left hand corner of the page by
3258 {+-}<xoffset>{+-}<y offset>. Use -page 612x792>, for example, to
3259 center the image within the page. If the image size exceeds the
3260 PostScript page, it is reduced to fit the page. The default
3261 gravity for the -page option is NorthWest, i.e., positive x and
3262 y offset are measured rightward and downward from the top left
3263 corner of the page, unless the -gravity option is present with a
3264 value other than NorthWest.
3265 The default page dimensions for a TEXT image is 612x792.
3267 This option is used in concert with -density.
3269 Use +page to remove the page settings for an image.
3271 -paint <radius>
3273 simulate an oil painting
3274 Each pixel is replaced by the most frequent color in a circular
3276 neighborhood whose width is specified with radius.
3277 -pause <seconds>
3279 pause between animation loops [animate]
3280 Pause for the specified number of seconds before repeating the
3282 animation.
3283 -pause <seconds>
3285 pause between snapshots [import]
3286 Pause for the specified number of seconds before taking the next
3288 snapshot.
3289 -pen <color>
3291 (This option has been replaced by the -fill option)
3292 -ping efficiently determine image characteristics
3294 Use this option to disable reading the image pixels so that im‐
3296 age characteristics such as the image dimensions may be obtained
3297 very quickly. For identify, use +ping to force reading the image
3298 pixels so that the pixel read rate may be included in the dis‐
3299 played information.
3300 -pointsize <value>
3302 pointsize of the PostScript, X11, or TrueType font
3303 -preview <type>
3305 image preview type
3306 Use this option to affect the preview operation of an image
3308 (e.g. convert file.png -preview Gamma Preview:gamma.png).
3309 Choose from these previews:
3310 Rotate
3312 Shear
3313 Roll
3314 Hue
3315 Saturation
3316 Brightness
3317 Gamma
3318 Spiff
3319 Dull
3320 Grayscale
3321 Quantize
3322 Despeckle
3323 ReduceNoise
3324 AddNoise
3325 Sharpen
3326 Blur
3327 Threshold
3328 EdgeDetect
3329 Spread
3330 Shade
3331 Raise
3332 Segment
3333 Solarize
3334 Swirl
3335 Implode
3336 Wave
3337 OilPaint
3338 CharcoalDrawing
3339 JPEG
3340 The default preview is JPEG.
3342 -process <command>
3344 process a sequence of images using a process module
3345 The command argument has the form module=arg1,arg2,arg3,...,argN
3347 where module is the name of the module to invoke (e.g. "Ana‐
3348 lyze") and arg1,arg2,arg3,...,argN are an arbitrary number of
3349 arguments to pass to the process module. The sequence of images
3350 is terminated by the appearance of any option.
3351 If the -process option appears after all of the input images,
3353 all images are processed.
3354 For example:
3356 gm convert logo: -process Analyze= \
3358 -format "%[BrightnessMean],%[BrightnessStddev]" info:-
3359 51952,23294
3360 -profile <filename>
3363 add ICM, IPTC, or generic profile to image
3364 -profile filename adds an ICM (ICC color management), IPTC
3366 (newswire information), or a generic (including Exif) profile to the image
3367 Use +profile icm, +profile iptc, or
3369 +profile profile_name to remove the respective profile.
3370 Multiple profiles may be listed, separated by commas. Profiles may be
3371 excluded from subsequent listed matches by preceding their name with
3372 an exclamation point. For example, +profile '!icm,*' strips
3373 all profiles except for the ICM profile. Use identify
3374 -verbose to find out what profiles are in the image file. Use
3375 +profile "*" to remove all profiles.
3376 Writing the image to a format that does not support profiles will
3377 of course also cause all profiles to be removed. The JPEG and PNG
3378 formats will store any profiles that have been read and not removed.
3379 In JPEG they are stored in APP1 markers, and in PNG they are stored
3380 as hex-coded binary in compressed zTXt chunks, except for the iCC
3381 chunk which is stored in the iCCP chunk.
3382 To extract a profile, the -profile option is not used. Instead,
3384 simply write the file to an image
3385 format such as APP1, 8BIM, ICM, or IPTC.
3386 For example, to extract the Exif data (which is stored in JPEG files
3388 in the APP1 profile), use
3389 gm convert cockatoo.jpg exifdata.app1
3392 Note that GraphicsMagick does not attempt to update any profile
3393 to reflect changes made to the image, e.g., rotation from por‐
3394 trait to landscape orientation, so it is possible that the pre‐
3395 served profile may contain invalid data.
3396 -preserve-timestamp
3398 preserve the original timestamps of the file
3399 Use this option to preserve the original modification and access
3401 timestamps of the file, even if it has been modified.
3402 +progress
3404 disable progress monitor and busy cursor
3405 By default, when an image is displayed, a progress monitor bar
3407 is shown in the top left corner of an existing image display
3408 window, and the current cursor is replaced with an hourglass
3409 cursor. Use +progress to disable the progress monitor and busy
3410 cursor during display operations. While the progress monitor is
3411 disabled for all operations, the busy cursor continues to be en‐
3412 abled for non-display operations such as image processing. This
3413 option is useful for non-interactive display operations, or when
3414 a "clean" look is desired.
3415 -quality <value>
3417 JPEG/MIFF/PNG/TIFF compression level
3418 For the JPEG and MPEG image formats, quality is 0 (lowest image
3419 quality and highest compression) to 100 (best quality but least
3420 effective compression). The default quality is 75. Use the
3421 -sampling-factor option to specify the factors for chroma down‐
3422 sampling. To use the same quality value as that found by the
3423 JPEG decoder, use the -define jpeg:preserve-settings flag.
3424 For the MIFF image format, and the TIFF format while using ZIP
3426 compression, quality/10 is the zlib compression level, which is
3427 0 (worst but fastest compression) to 9 (best but slowest). It
3428 has no effect on the image appearance, since the compression is
3429 always lossless.
3430 For the JPEG-2000 image format, quality is mapped using a non-
3432 linear equation to the compression ratio required by the Jasper
3433 library. This non-linear equation is intended to loosely approx‐
3434 imate the quality provided by the JPEG v1 format. The default
3435 quality value 75 results in a request for 16:1 compression. The
3436 quality value 100 results in a request for non-lossy compres‐
3437 sion.
3438 For the MNG and PNG image formats, the quality value sets the
3440 zlib compression level (quality / 10) and filter-type (quality %
3441 10). Compression levels range from 0 (fastest compression) to
3442 100 (best but slowest). For compression level 0, the Huffman-
3443 only strategy is used, which is fastest but not necessarily the
3444 worst compression.
3445 If filter-type is 4 or less, the specified filter-type is used
3447 for all scanlines:
3448 0: none
3450 1: sub
3451 2: up
3452 3: average
3453 4: Paeth
3454 If filter-type is 5, adaptive filtering is used when quality is
3456 greater than 50 and the image does not have a color map, other‐
3457 wise no filtering is used.
3458 If filter-type is 6, adaptive filtering with minimum-sum-of-ab‐
3460 solute-values is used.
3461 Only if the output is MNG, if filter-type is 7, the LOCO color
3463 transformation and adaptive filtering with minimum-sum-of-abso‐
3464 lute-values are used.
3465 The default is quality is 75, which means nearly the best com‐
3467 pression with adaptive filtering. The quality setting has no
3468 effect on the appearance of PNG and MNG images, since the com‐
3469 pression is always lossless.
3470 For further information, see the PNG specification.
3472 When writing a JNG image with transparency, two quality values
3474 are required, one for the main image and one for the grayscale
3475 image that conveys the opacity channel. These are written as a
3476 single integer equal to the main image quality plus 1000 times
3477 the opacity quality. For example, if you want to use quality 75
3478 for the main image and quality 90 to compress the opacity data,
3479 use -quality 90075.
3480 For the PNM family of formats (PNM, PGM, and PPM) specify a
3482 quality factor of zero in order to obtain the ASCII variant of
3483 the format. Note that -compress none used to be used to trigger
3484 ASCII output but provided the opposite result of what was ex‐
3485 pected as compared with other formats.
3486 For the TIFF format, the JPEG, WebP, Zip, and Zstd compression
3488 algorithms are influenced by the quality value. JPEG and WebP
3489 provide lossy compression so higher quality produces a larger
3490 file with less degradation. The Zip and Zstd compression algo‐
3491 rithms (and WebP in lossless mode) are lossless and for these
3492 algorithms a higher ´quality' means to work harder to produce a
3493 smaller file, but with no difference in image quality.
3494 -raise <width>x<height>
3496 lighten or darken image edges
3497 This will create a 3-D effect. See -geometry for details details
3499 about the geometry specification. Offsets are not used.
3500 Use -raise to create a raised effect, otherwise use +raise.
3502 -random-threshold <channeltype> <LOWxHIGH>
3504 random threshold the image
3505 The channel or channels specified in the <channeltype> argument
3507 are reduced to binary, using an random-threshold method. The
3508 choices for channeltype are All, Intensity, Red, Green, Blue,
3509 Cyan, Magenta, Yellow, Black, and Opacity
3510 When channeltype is "All", the color samples are thresholded
3512 into a graylevel and then that gray level is stored in the three
3513 color channels. Separately, the opacity channel is thresholded
3514 into a bilevel opacity value which is stored in the opacity
3515 channel. For each pixel, a new random number is used to estab‐
3516 lish the threshold to be used. The threshold never exceeds the
3517 specified maximum (HIGH) and is never less than the specified
3518 minimum (LOW).
3519 When channeltype is "intensity", only the color samples are
3521 thresholded. When channeltype is "opacity" or "matte", only the
3522 opacity channel is thresholded. The other named channels only
3523 threshold the associated channel.
3524 -recolor <matrix>
3526 apply a color translation matrix to image channels
3527 A user supplied color translation matrix (expressed as a text
3529 string) is used to translate/blend the image channels based on
3530 weightings in a supplied matrix which may be of order 3 (color
3531 channels only), 4 (color channels plus opacity), or 5 (color
3532 channels plus opacity and offset). Values in the columns of the
3533 matrix (red, green, blue, opacity) are used as multipliers with
3534 the existing channel values and added together according to the
3535 rows of the matrix. Matrix values are floating point and may be
3536 negative. The offset column (column 5) is purely additive and
3537 is scaled such that 0.0 to 1.0 represents the maximum quantum
3538 range (but values are not limited to this range). The math for
3539 the color translation matrix is similar to that used by Adobe
3540 Flash except that the offset is scaled to 1.0 (divide Flash off‐
3541 set by 255 for use with GraphicsMagick) so that the results are
3542 independent of quantum depth.
3543 An identity matrix exists for each matrix order which results in
3545 no change to the image. The translation matrix should be based
3546 on an alteration of the identity matrix.
3547 Identity matrix of order 3
3549 1 0 0
3551 0 1 0
3552 0 0 1
3553 which may be formatted into a convenient matrix argument similar
3555 to (comma is treated as white space):
3556 -recolor "1 0 0, 0 1 0, 0 0 1"
3558 Identity matrix of order 4
3560 1 0 0 0
3562 0 1 0 0
3563 0 0 1 0
3564 0 0 0 1
3565 Identity matrix of order 5. The last row is required to exist
3567 for the purpose of parsing, but is otherwise not used.
3568 1 0 0 0 0
3570 0 1 0 0 0
3571 0 0 1 0 0
3572 0 0 0 1 0
3573 0 0 0 0 1
3574 As an example, an image wrongly in BGR channel order may be con‐
3576 verted to RGB using this matrix (blue->red, red->blue):
3577 0 0 1
3579 0 1 0
3580 1 0 0
3581 and an RGB image using standard Rec.709 primaries may be con‐
3583 verted to grayscale using this matrix of standard weighting fac‐
3584 tors:
3585 0.2126 0.7152 0.0722
3587 0.2126 0.7152 0.0722
3588 0.2126 0.7152 0.0722
3589 and contrast may be reduced by scaling down by 80% and adding a
3591 10% offset:
3592 0.8 0.0 0.0 0.0 0.1
3594 0.0 0.8 0.0 0.0 0.1
3595 0.0 0.0 0.8 0.0 0.1
3596 0.0 0.0 0.0 0.8 0.1
3597 0.0 0.0 0.0 0.0 1.0
3598 -red-primary <x>,<y>
3600 red chromaticity primary point
3601 -region <width>x<height>{+-}<x>{+-}<y>
3603 apply options to a portion of the image
3604 The x and y offsets are treated in the same manner as in -crop.
3606 -remote
3608 perform a X11 remote operation
3609 The -remote command sends a command to a "gm display" or "gm an‐
3611 imate" which is already running. The only command recognized at
3612 this time is the name of an image file to load. This capability
3613 is very useful to load new images without needing to restart
3614 GraphicsMagick (e.g. for a slide-show or to use GraphicsMagick
3615 as the display engine for a different GUI). Also see the
3616 +progress option for a way to disable progress indication for a
3617 clean look while loading new images.
3618 -render
3620 render vector operations
3621 Use +render to turn off rendering vector operations. This is
3623 useful when saving the result to vector formats such as MVG or
3624 SVG.
3625 -repage <width>x<height>+xoff+yoff[!]
3627 Adjust image page offsets
3628 Adjust the current image page canvas and position based on a
3630 relative page specification. This option may be used to change
3631 the location of a subframe (e.g. part of an animation) prior to
3632 composition. If the geometry specification is absolute (in‐
3633 cludes a '!'), then the offset adjustment is absolute and there
3634 is no adjustment to page width and height, otherwise the page
3635 width and height values are also adjusted based on the current
3636 image dimensions. Use +repage to set the image page offsets to
3637 default.
3638 -resample <horizontal>x<vertical>
3640 Resample image to specified horizontal and vertical resolution
3641 Resize the image so that its rendered size remains the same as
3643 the original at the specified target resolution. Either the cur‐
3644 rent image resolution units or the previously set with -units
3645 are used to interpret the argument. For example, if a 300 DPI
3646 image renders at 3 inches by 2 inches on a 300 DPI device, when
3647 the image has been resampled to 72 DPI, it will render at 3
3648 inches by 2 inches on a 72 DPI device. Note that only a small
3649 number of image formats (e.g. JPEG, PNG, and TIFF) are capable
3650 of storing the image resolution. For formats which do not sup‐
3651 port an image resolution, the original resolution of the image
3652 must be specified via -density on the command line prior to
3653 specifying the resample resolution.
3654 Note that Photoshop stores and obtains image resolution from a
3656 proprietary embedded profile. If this profile exists in the im‐
3657 age, then Photoshop will continue to treat the image using its
3658 former resolution, ignoring the image resolution specified in
3659 the standard file header.
3660 Some image formats (e.g. PNG) require use of metric or english
3662 units so even if the original image used a particular unit sys‐
3663 tem, if it is saved to a different format prior to resampling,
3664 then it may be necessary to specify the desired resolution units
3665 using -units since the original units may have been lost. In
3666 other words, do not assume that the resolution units are re‐
3667 stored if the image has been saved to a file.
3668 -resize <width>x<height>{%}{@}{!}{<}{>}
3670 resize an image
3671 This is an alias for the -geometry option and it behaves in the
3673 same manner. If the -filter option precedes the -resize option,
3674 the specified filter is used.
3675 There are some exceptions:
3677 When used as a composite option, -resize conveys the preferred
3679 size of the output image, while -geometry conveys the size and
3680 placement of the composite image within the main image.
3681 When used as a montage option, -resize conveys the preferred
3683 size of the montage, while -geometry conveys information about
3684 the tiles.
3685 -roll {+-}<x>{+-}<y>
3687 roll an image vertically or horizontally
3688 See -geometry for details the geometry specification. The x and
3690 y offsets are not affected by the -gravity option.
3691 A negative x offset rolls the image left-to-right. A negative y
3693 offset rolls the image top-to-bottom.
3694 -rotate <degrees>{<}{>}
3696 rotate the image
3697 Positive angles rotate the image in a clockwise direction while
3699 negative angles rotate counter-clockwise.
3700 Use > to rotate the image only if its width exceeds the height.
3702 < rotates the image only if its width is less than the height.
3703 For example, if you specify -rotate "-90>" and the image size is
3704 480x640, the image is not rotated. However, if the image is
3705 640x480, it is rotated by -90 degrees. If you use > or <, en‐
3706 close it in quotation marks to prevent it from being misinter‐
3707 preted as a file redirection.
3708 Empty triangles left over from rotating the image are filled
3710 with the color defined as background (class backgroundColor).
3711 The color is specified using the format described under the
3712 -fill option.
3713 -sample <geometry>
3715 scale image using pixel sampling
3716 See -geometry for details about the geometry specification.
3718 -sample ignores the -filter selection if the -filter option is
3719 present. Offsets, if present in the geometry string, are ig‐
3720 nored, and the -gravity option has no effect.
3721 -sampling-factor <horizontal_factor>x<vertical_factor>
3723 chroma subsampling factors
3724 This option specifies the sampling factors to be used by the
3726 DPX, JPEG, MPEG, or YUV encoders for chroma downsampling. The
3727 sampling factor must be specified while reading the raw YUV for‐
3728 mat since it is not preserved in the file header. Industry-
3729 standard video subsampling notation such as "4:2:2" may also be
3730 used to specify the sampling factors. "4:2:2" is equivalent to a
3731 specification of "2x1"
3732 The JPEG decoder obtains the original sampling factors (and
3734 quality settings) when a JPEG file is read. To re-use the origi‐
3735 nal sampling factors (and quality setting) when JPEG is output,
3736 use the -define jpeg:preserve-settings flag.
3737 -scale <geometry>
3739 scale the image.
3740 See -geometry for details about the geometry specification.
3742 -scale uses a simpler, faster algorithm, and it ignores the
3743 -filter selection if the -filter option is present. Offsets, if
3744 present in the geometry string, are ignored, and the -gravity
3745 option has no effect.
3746 -scene <value>
3748 set scene number
3749 This option sets the scene number of an image or the first image
3751 in an image sequence.
3752 -scenes <value-value>
3754 range of image scene numbers to read
3755 Each image in the range is read with the filename followed by a
3757 period (.) and the decimal scene number. You can change this
3758 behavior by embedding a %d, %0Nd, %o, %0No, %x, or %0Nx printf
3759 format specification in the file name. For example,
3760 gm montage -scenes 5-7 image.miff montage.miff
3762 makes a montage of files image.miff.5, image.miff.6, and im‐
3764 age.miff.7, and
3765 gm animate -scenes 0-12 image%02d.miff
3767 animates files image00.miff, image01.miff, through image12.miff.
3769 -screen
3771 specify the screen to capture
3772 This option indicates that the GetImage request used to obtain
3774 the image should be done on the root window, rather than di‐
3775 rectly on the specified window. In this way, you can obtain
3776 pieces of other windows that overlap the specified window, and
3777 more importantly, you can capture menus or other popups that are
3778 independent windows but appear over the specified window.
3779 -set <attribute> <value>
3781 set an image attribute
3782 Set a named image attribute. The attribute is set on the cur‐
3784 rent (previously specified on command line) image.
3785 +set <attribute>
3787 unset an image attribute
3788 Unset a named image attribute. The attribute is removed from
3790 the current (previously specified on command line) image.
3791 -segment <cluster threshold>x<smoothing threshold>
3793 segment an image
3794 Segment an image by analyzing the histograms of the color compo‐
3796 nents and identifying units that are homogeneous with the fuzzy
3797 c-means technique.
3798 Segmentation is a very useful fast and and approximate color
3800 quantization algorithm for scanned printed pages or scanned car‐
3801 toons. It may also be used as a special effect. Specify cluster
3802 threshold as the minimum percentage of total pixels in a cluster
3803 before it is considered valid. For huge images containing small
3804 detail, this may need to be a tiny fraction of a percent (e.g.
3805 0.015) so that important detail is not lost. Smoothing thresh‐
3806 old eliminates noise in the second derivative of the histogram.
3807 As the value is increased, you can expect a smoother second de‐
3808 rivative. The default is 1.5. Add the -verbose option to see a
3809 dump of cluster statistics given the parameters used. The sta‐
3810 tistics may be used as a guide to help fine tune the options.
3811 -shade <azimuth>x<elevation>
3813 shade the image using a distant light source
3814 Specify azimuth and elevation as the position of the light
3816 source. Use +shade to return the shading results as a grayscale
3817 image.
3818 -shadow <radius>{x<sigma>}
3820 shadow the montage
3821 -shared-memory
3823 use shared memory
3824 This option specifies whether the utility should attempt to use
3826 shared memory for pixmaps. GraphicsMagick must be compiled with
3827 shared memory support, and the display must support the MIT-SHM
3828 extension. Otherwise, this option is ignored. The default is
3829 True.
3830 -sharpen <radius>{x<sigma>}
3832 sharpen the image
3833 Use a Gaussian operator of the given radius and standard devia‐
3835 tion (sigma).
3836 -shave <width>x<height>{%}
3838 shave pixels from the image edges
3839 Specify the width of the region to be removed from both sides of
3841 the image and the height of the regions to be removed from top
3842 and bottom.
3843 -shear <x degrees>x<y degrees>
3845 shear the image along the X or Y axis
3846 Use the specified positive or negative shear angle.
3848 Shearing slides one edge of an image along the X or Y axis, cre‐
3850 ating a parallelogram. An X direction shear slides an edge along
3851 the X axis, while a Y direction shear slides an edge along the Y
3852 axis. The amount of the shear is controlled by a shear angle.
3853 For X direction shears, x degrees is measured relative to the Y
3854 axis, and similarly, for Y direction shears y degrees is mea‐
3855 sured relative to the X axis.
3856 Empty triangles left over from shearing the image are filled
3858 with the color defined as background (class backgroundColor).
3859 The color is specified using the format described under the
3860 -fill option.
3861 -silent
3863 operate silently
3864 -size <width>x<height>{+offset}
3866 width and height of the image
3867 Use this option to specify the width and height of raw images
3869 whose dimensions are unknown such as GRAY, RGB, or CMYK. In ad‐
3870 dition to width and height, use -size with an offset to skip any
3871 header information in the image or tell the number of colors in
3872 a MAP image file, (e.g. -size 640x512+256).
3873 For Photo CD images, choose from these sizes:
3875 192x128
3877 384x256
3878 768x512
3879 1536x1024
3880 3072x2048
3881 Finally, use this option to choose a particular resolution layer
3883 of a JBIG or JPEG image (e.g. -size 1024x768).
3884 -snaps <value>
3886 number of screen snapshots
3887 Use this option to grab more than one image from the X server
3889 screen, to create an animation sequence.
3890 -solarize <factor>
3892 negate all pixels above the threshold level
3893 Specify factor as the percent threshold of the intensity (0 -
3895 99.9%).
3896 This option produces a solarization effect seen when exposing a
3898 photographic film to light during the development process.
3899 -spread <amount>
3901 displace image pixels by a random amount
3902 Amount defines the size of the neighborhood around each pixel to
3904 choose a candidate pixel to swap.
3905 -stegano <offset>
3907 hide watermark within an image
3908 Use an offset to start the image hiding some number of pixels
3910 from the beginning of the image. Note this offset and the image
3911 size. You will need this information to recover the stegano‐
3912 graphic image (e.g. display -size 320x256+35 stegano:image.png).
3913 -stereo
3915 composite two images to create a stereo anaglyph
3916 The left side of the stereo pair is saved as the red channel of
3918 the output image. The right side is saved as the green channel.
3919 Red-green stereo glasses are required to properly view the
3920 stereo image.
3921 -strip remove all profiles and text attributes from the image
3923 All embedded profiles and text attributes are stripped from the
3925 image. This is useful for images used for the web, or when out‐
3926 put files need to be as small as possible
3927 Be careful not to use this option to remove author, copyright,
3929 and license information that you are required to retain when re‐
3930 distributing an image.
3931 -stroke <color>
3933 color to use when stroking a graphic primitive
3934 The color is specified using the format described under the
3936 -fill option.
3937 See -draw for further details.
3939 -strokewidth <value>
3941 set the stroke width
3942 See -draw for further details.
3944 -swirl <degrees>
3946 swirl image pixels about the center
3947 Degrees defines the tightness of the swirl.
3949 -text-font <name>
3951 font for writing fixed-width text
3952 Specifies the name of the preferred font to use in fixed (type‐
3954 writer style) formatted text. The default is 14 point Courier.
3955 You can tag a font to specify whether it is a PostScript, True‐
3957 Type, or X11 font. For example, Courier.ttf is a TrueType font
3958 and x:fixed is X11.
3959 -texture <filename>
3961 name of texture to tile onto the image background
3962 -threshold <value>{%}
3964 threshold the image
3965 Modify the image such that any pixel sample with an intensity
3967 value greater than the threshold is assigned the maximum inten‐
3968 sity (white), or otherwise is assigned the minimum intensity
3969 (black). If a percent prefix is applied, then the threshold is a
3970 percentage of the available range.
3971 To efficiently create a black and white image from a color im‐
3973 age, use
3974 gm convert -threshold 50% in.png out.png
3976 The optimum threshold value depends on the nature of the image.
3978 In order to threshold individual channels, use the -operator
3979 subcommand with it's Threshold, Threshold-White, or Threshold-
3980 Black options.
3981 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
3983 resize an image (quickly)
3984 The -thumbnail command resizes the image as quickly as possible,
3986 with more concern for speed than resulting image quality. Re‐
3987 gardless, resulting image quality should be acceptable for many
3988 uses. It is primarily intended to be used to generate smaller
3989 versions of the image, but may also be used to enlarge the im‐
3990 age. The -thumbnail geometry argument observes the same syntax
3991 and rules as it does for -resize.
3992 -tile <filename>
3994 tile image when filling a graphic primitive
3995 -tile <geometry>
3997 layout of images [montage]
3998 -title <string>
4000 assign title to displayed image [animate, display, montage]
4001 Use this option to assign a specific title to the image. This is
4003 assigned to the image window and is typically displayed in the
4004 window title bar. Optionally you can include the image file‐
4005 name, type, width, height, Exif data, or other image attribute
4006 by embedding special format characters described under the -for‐
4007 mat option.
4008 For example,
4010 -title "%m:%f %wx%h"
4012 produces an image title of MIFF:bird.miff 512x480 for an image
4014 titled bird.miff and whose width is 512 and height is 480.
4015 -transform
4017 transform the image
4018 This option applies the transformation matrix from a previous
4020 -affine option.
4021 gm convert -affine 2,2,-2,2,0,0 -transform bird.ppm bird.jpg
4023 -transparent <color>
4025 make this color transparent within the image
4026 The color is specified using the format described under the
4028 -fill option.
4029 -treedepth <value>
4031 tree depth for the color reduction algorithm
4032 Normally, this integer value is zero or one. A value of zero or
4034 one causes the use of an optimal tree depth for the color reduc‐
4035 tion algorithm
4036 An optimal depth generally allows the best representation of the
4038 source image with the fastest computational speed and the least
4039 amount of memory. However, the default depth is inappropriate
4040 for some images. To assure the best representation, try values
4041 between 2 and 8 for this parameter. Refer to quantize for more
4042 details.
4043 The -colors or -monochrome option, or writing to an image format
4045 which requires color reduction, is required for this option to
4046 take effect.
4047 -trim trim an image
4049 This option removes any edges that are exactly the same color as
4051 the corner pixels. Use -fuzz to make -trim remove edges that
4052 are nearly the same color as the corner pixels.
4053 -type <type>
4055 the image type
4056 Choose from: Bilevel, Grayscale, Palette, PaletteMatte, True‐
4058 Color, TrueColorMatte, ColorSeparation, ColorSeparationMatte, or
4059 Optimize.
4060 Normally, when a format supports different subformats such as
4062 bilevel, grayscale, palette, truecolor, and truecolor+alpha, the
4063 encoder will try to choose a suitable subformat based on the na‐
4064 ture of the image. The -type option may be used to tailor the
4065 output subformat. By default the output subformat is based on
4066 readily available image information and is usually similar to
4067 the input format.
4068 Specify -type Optimize in order to enable inspecting all pixels
4070 (if necessary) in order to find the most efficient subformat.
4071 Inspecting all of the pixels may be slow for very large images,
4072 particularly if they are stored in a disk cache. If an RGB image
4073 contains only gray pixels, then every pixel in the image must be
4074 inspected in order to decide that the image is actually
4075 grayscale!
4076 Sometimes a specific subformat is desired. For example, to force
4078 a JPEG image to be written in TrueColor RGB format even though
4079 only gray pixels are present, use
4080 gm convert bird.pgm -type TrueColor bird.jpg
4082 Similarly, using -type TrueColorMatte will force the encoder to
4084 write an alpha channel even though the image is opaque, if the
4085 output format supports transparency.
4086 Some pseudo-formats (e.g. the XC format) will respect the re‐
4088 quested type if it occurs previously on the command line. For
4089 example, to obtain a DirectClass solid color canvas image rather
4090 than PsuedoClass, use
4091 gm convert -size 640x480 -type TrueColor xc:red red.miff
4093 Likewise, specify -type Bilevel, Grayscale, TrueColor, or True‐
4095 ColorMatte prior to reading a Postscript (or PDF file) in order
4096 to influence the type of image that Ghostcript returns. Reading
4097 performance will be dramatically improved for black/white Post‐
4098 script if Bilevel is specified, and will be considerably faster
4099 if Grayscale is specified.
4100 -update <seconds>
4102 detect when image file is modified and redisplay.
4103 Suppose that while you are displaying an image the file that is
4105 currently displayed is over-written. display will automatically
4106 detect that the input file has been changed and update the dis‐
4107 played image accordingly.
4108 -units <type>
4110 the units of image resolution
4111 Choose from: Undefined, PixelsPerInch, or PixelsPerCentimeter.
4113 This option is normally used in conjunction with the -density
4114 option.
4115 -unsharp <radius>{x<sigma>}{+<amount>}{+<threshold>}
4117 sharpen the image with an unsharp mask operator
4118 The -unsharp option sharpens an image. The image is convolved
4120 with a Gaussian operator of the given radius and standard devia‐
4121 tion (sigma). For reasonable results, radius should be larger
4122 than sigma. Use a radius of 0 to have the method select a suit‐
4123 able radius.
4124 The parameters are:
4126 radius
4129 The radius of the Gaussian, in pixels, not counting the
4132 center pixel (default 0).
4133 sigma
4135 The standard deviation of the Gaussian, in pixels (default
4138 1.0).
4139 amount
4141 The percentage of the difference between the original and
4144 the blur image that is added back into the original (de‐
4145 fault 1.0).
4146 threshold
4148 The threshold, as a fraction of MaxRGB, needed to apply
4151 the difference amount (default 0.05).
4152 -use-pixmap
4157 use the pixmap
4158 -verbose
4160 print detailed information about the image
4161 This information is printed: image scene number; image name; im‐
4163 age size; the image class (DirectClass or PseudoClass); the to‐
4164 tal number of unique colors; and the number of seconds to read
4165 and transform the image. If the image is DirectClass, the total
4166 number of unique colors is not displayed unless -verbose is
4167 specified twice since it may take quite a long time to compute,
4168 particularly for deep images. If the image is PseudoClass then
4169 its pixels are defined by indexes into a colormap. If the image
4170 is DirectClass then each pixel includes a complete and indepen‐
4171 dent color specification.
4172 If -colors is also specified, the total unique colors in the im‐
4174 age and color reduction error values are printed. Refer to quan‐
4175 tize for a description of these values.
4176 -version
4178 print GraphicsMagick version string
4179 -view <string>
4181 FlashPix viewing parameters
4182 -virtual-pixel <method>
4184 specify contents of "virtual pixels"
4185 This option defines "virtual pixels" for use in operations that
4187 can access pixels outside the boundaries of an image.
4188 Choose from these methods:
4190 Constant
4193 Use the image background color.
4196 Edge
4198 Extend the edge pixel toward infinity (default).
4201 Mirror
4203 Mirror the image.
4206 Tile
4208 Tile the image.
4211 This option affects operations that use virtual pixels such as
4216 -blur, -sharpen, -wave, etc.
4217 -visual <type>
4219 animate images using this X visual type
4220 Choose from these visual classes:
4222 StaticGray
4224 GrayScale
4225 StaticColor
4226 PseudoColor
4227 TrueColor
4228 DirectColor
4229 default
4230 visual id
4231 The X server must support the visual you choose, otherwise an
4233 error occurs. If a visual is not specified, the visual class
4234 that can display the most simultaneous colors on the default
4235 screen is chosen.
4236 -watermark <brightness>x<saturation>
4238 percent brightness and saturation of a watermark
4239 -wave <amplitude>x<wavelength>
4241 alter an image along a sine wave
4242 Specify amplitude and wavelength of the wave.
4244 -white-point <x>,<y>
4246 chromaticity white point
4247 -white-threshold red[,green][,blue][,opacity]
4249 pixels above the threshold become white
4250 Use -white-threshold to set pixels with values above the speci‐
4252 fied threshold to maximum value (white). If only one value is
4253 supplied, or the red, green, and blue values are identical, then
4254 intensity thresholding is used. If the color threshold values
4255 are not identical then channel-based thresholding is used, and
4256 color distortion will occur. Specify a negative value (e.g. -1)
4257 if you want a channel to be ignored but you do want to threshold
4258 a channel later in the list. If a percent (%) symbol is ap‐
4259 pended, then the values are treated as a percentage of maximum
4260 range.
4261 -window <id>
4263 make image the background of a window
4264 id can be a window id or name. Specify root to select X's root
4266 window as the target window.
4267 By default the image is tiled onto the background of the target
4269 window. If backdrop or -geometry are specified, the image is
4270 surrounded by the background color. Refer to X RESOURCES for
4271 details.
4272 The image will not display on the root window if the image has
4274 more unique colors than the target window colormap allows. Use
4275 -colors to reduce the number of colors.
4276 -window-group
4278 specify the window group
4279 -write <filename>
4281 write an intermediate image [convert, composite]
4282 The current image is written to the specified filename and then
4284 processing continues using that image. The following is an exam‐
4285 ple of how several sizes of an image may be generated in one
4286 command (repeat as often as needed):
4287 gm convert input.jpg -resize 50% -write input50.jpg \
4289 -resize 25% input25.jpg
4290 -write <filename>
4292 write the image to a file [display]
4293 If filename already exists, you will be prompted as to whether
4295 it should be overwritten.
4296 By default, the image is written in the format that it was read
4298 in as. To specify a particular image format, prefix filename
4299 with the image type and a colon (e.g., ps:image) or specify the
4300 image type as the filename suffix (e.g., image.ps). Specify file
4301 as - for standard output. If file has the extension .Z or .gz,
4302 the file size is compressed using compress or gzip respectively.
4303 Precede the image file name with | to pipe to a system command.
4304 Use -compress to specify the type of image compression.
4306 The equivalent X resource for this option is writeFilename
4308 (class WriteFilename). See "X Resources", below, for details.
4309
4311 COLUMNS
4312 Output screen width. Used when formatting text for the screen.
4313 Many Unix systems keep this shell variable up to date, but it
4314 may need to be explicitly exported in order for GraphicsMagick
4315 to see it.
4316 DISPLAY
4318 X11 display ID (host, display number, and screen in the form
4319 hostname:display.screen).
4320 HOME Location of user's home directory. For security reasons, now
4322 only observed by "uninstalled" builds of GraphicsMagick which do
4323 not have their location hard-coded or set by an installer. When
4324 supported, GraphicsMagick searches for configuration files in
4325 $HOME/.magick if the directory exists. See MAGICK_CODER_MOD‐
4326 ULE_PATH, MAGICK_CONFIGURE_PATH, and MAGICK_FILTER_MODULE_PATH
4327 if more flexibility is needed.
4328 MAGICK_ACCESS_MONITOR
4330 When set to TRUE, command line monitor mode (enabled by -moni‐
4331 tor) will also show files accessed (including temporary files)
4332 and any external commands which are executed. This is useful for
4333 debugging, but also illustrates arguments made available to an
4334 access handler registered by the MagickSetConfirmAccessHandler()
4335 C library function.
4336 MAGICK_CODER_STABILITY
4338 The minimum coder stability level before it will be used. The
4339 available levels are PRIMARY, STABLE, UNSTABLE, and BROKEN. The
4340 default minimum level is UNSTABLE, which means that all avail‐
4341 able working coders will be used. The purpose of this option is
4342 to reduce the security exposure (or apparent complexity) due to
4343 the huge number of formats supported. Coders at the PRIMARY
4344 level are commonly used formats with very well maintained imple‐
4345 mentations. Coders at the STABLE level are reasonably well main‐
4346 tained but represent less used formats. Coders at the UNSTABLE
4347 level either have weak implementations, the file format itself
4348 is weak, or the probability the coder will be needed is vanish‐
4349 ingly small. Coders at the BROKEN level are known to often not
4350 work properly or might not be useful in their current state at
4351 all.
4352 MAGICK_CODER_MODULE_PATH
4354 Search path to use when searching for image format coder mod‐
4355 ules. This path allows the user to arbitrarily extend the image
4356 formats supported by GraphicsMagick by adding loadable modules
4357 to an arbitrary location rather than copying them into the
4358 GraphicsMagick installation directory. The formatting of the
4359 search path is similar to operating system search paths (i.e.
4360 colon delimited for Unix, and semi-colon delimited for Microsoft
4361 Windows). This user specified search path is used before trying
4362 the default search path.
4363 MAGICK_CONFIGURE_PATH
4365 Search path to use when searching for configuration (.mgk)
4366 files. The formatting of the search path is similar to operat‐
4367 ing system search paths (i.e. colon delimited for Unix, and
4368 semi-colon delimited for Microsoft Windows). This user specified
4369 search path is used before trying the default search path.
4370 MAGICK_DEBUG
4372 Debug options (see -debug for details). Setting the configure
4373 debug option via an environment variable (e.g. MAGICK_DEBUG=con‐
4374 figure) is necessary to see the complete initialization process,
4375 which includes searching for configuration files.
4376 MAGICK_FILTER_MODULE_PATH
4378 Search path to use when searching for filter process modules
4379 (invoked via -process). This path allows the user to arbitrarily
4380 extend GraphicsMagick's image processing functionality by adding
4381 loadable modules to an arbitrary location rather than copying
4382 them into the GraphicsMagick installation directory. The format‐
4383 ting of the search path is similar to operating system search
4384 paths (i.e. colon delimited for Unix, and semi-colon delimited
4385 for Microsoft Windows). This user specified search path is used
4386 before trying the default search path.
4387 MAGICK_GHOSTSCRIPT_PATH
4389 For Microsoft Windows, specify the path to the Ghostscript in‐
4390 stallation rather than searching for it via the Windows reg‐
4391 istry. This helps in case Ghostscript is not installed via the
4392 Ghostscript Windows installer or the user wants more control
4393 over the Ghostscript used.
4394 MAGICK_HOME
4396 Path to top of GraphicsMagick installation directory. Only ob‐
4397 served by "uninstalled" builds of GraphicsMagick which do not
4398 have their location hard-coded or set by an installer.
4399 MAGICK_MMAP_READ
4401 If MAGICK_MMAP_READ is set to TRUE, GraphicsMagick will attempt
4402 to memory-map the input file for reading. This usually substan‐
4403 tially improves repeated read performance since the file is al‐
4404 ready in memory after the first time it has been read. However,
4405 testing shows that performance may be reduced for files accessed
4406 for the first time since data is accessed via page-faults (upon
4407 first access) and many operating systems fail to do sequential
4408 read-ahead of memory mapped files, and particularly if those
4409 files are accessed over a network. If many large input files
4410 are read, then enabling this option may harm performance by
4411 overloading the operating system's VM system as it then needs to
4412 free unmapped pages and map new ones.
4413 MAGICK_IO_FSYNC
4415 If MAGICK_IO_FSYNC is set to TRUE, then GraphicsMagick will re‐
4416 quest that the output file is fully flushed and synchronized to
4417 disk when it is closed. This incurs a performance penalty, but
4418 has the benefit that if the power fails or the system crashes,
4419 the file should be valid on disk. If image files are referenced
4420 from a database, then this option helps assure that the files
4421 referenced by the database are valid.
4422 MAGICK_IOBUF_SIZE
4424 The amount of I/O buffering (in bytes) to use when reading and
4425 writing encoded files. The default is 16384, which is observed
4426 to work well for many cases. The best value for a local filesys‐
4427 tem is usually the the native filesystem block size (e.g. 4096,
4428 8192, or even 131,072 for ZFS) in order to minimize the number
4429 of physical disk I/O operations. I/O performance to files ac‐
4430 cessed over a network may benefit significantly by tuning this
4431 option. Larger values are not necessarily better (they may be
4432 slower!), and there is rarely any benefit from using values
4433 larger than 32768. Use convert's -verbose option in order to
4434 evaluate read and write rates in pixels per second while keeping
4435 in mind that the operating system will try to cache files in
4436 RAM.
4437 MAGICK_LIMIT_DISK
4439 Maximum amount of disk space allowed for use by the pixel cache.
4440 MAGICK_LIMIT_FILES
4442 Maximum number of open files.
4443 MAGICK_LIMIT_MAP
4445 Maximum size of a memory mapped file allocation. A memory
4446 mapped file consumes memory when the file is accessed, although
4447 the system may reclaim such memory when needed.
4448 MAGICK_LIMIT_MEMORY
4450 Maximum amount of memory to allocate from the heap.
4451 MAGICK_LIMIT_PIXELS
4453 Maximum number of total pixels (image rows times image colums)
4454 to allow for any image which is requested to be created or read.
4455 This is useful to place a limit on how large an image may be.
4456 If the input image file has image dimensions larger than the
4457 pixel limit, then the image memory allocation is denied and an
4458 error is returned immediately. This is a per-image limit and
4459 does not limit the total number of pixels due to multiple image
4460 frames/pages (e.g. multi-page document or an animation).
4461 MAGICK_LIMIT_READ
4463 Maximum number of uncompressed bytes which may be read while de‐
4464 coding an image. Each read by the software from the input file
4465 is counted against the total, even if it has been read before.
4466 Decoding fails when the limit is reached. This limit helps de‐
4467 fend against highly compressed files (e.g. via gzip), or files
4468 which use complex looping structures, or when data is being read
4469 from a stream (pipe).
4470 MAGICK_LIMIT_WIDTH
4472 Maximum pixel width of an image read, or created.
4473 MAGICK_LIMIT_HEIGHT
4475 Maximum pixel height of an image read, or created.
4476 MAGICK_TMPDIR
4478 Path to directory where GraphicsMagick should write temporary
4479 files. The default is to use the system default, or the location
4480 set by TMPDIR.
4481 TMPDIR For POSIX-compatible systems (Unix-compatible), the path to the
4483 directory where all applications should write temporary files.
4484 Overridden by MAGICK_TMPDIR if it is set.
4485 TMP or TEMP
4487 For Microsoft Windows, the path to the directory where applica‐
4488 tions should write temporary files. Overridden by MAGICK_TMPDIR
4489 if it is set.
4490 OMP_NUM_THREADS
4492 As per the OpenMP standard, this specifies the number of threads
4493 to use in parallel regions. Some compilers default the number of
4494 threads to use to the number of processor cores available while
4495 others default to just one thread. See the OpenMP specification
4496 for other standard adjustments and your compiler's manual for
4497 vendor-specific settings.
4498
4500 GraphicsMagick uses a number of XML format configuration files:
4501 colors.mgk
4503 colors configuration file
4504 <?xml version="1.0"?>
4506 <colormap>
4507 <color name="AliceBlue" red="240" green="248" blue="255"
4508 compliance="SVG, X11, XPM" />
4509 </colormap>
4510 delegates.mgk
4512 delegates configuration file
4513 log.mgk
4515 logging configuration file
4516 <?xml version="1.0"?>
4518 <magicklog>
4519 <log events="None" />
4520 <log output="stdout" />
4521 <log filename="Magick-%d.log" />
4522 <log generations="3" />
4523 <log limit="2000" />
4524 <log format="%t %r %u %p %m/%f/%l/%d:\n %e" />
4525 </magicklog>
4526 modules.mgk
4528 loadable modules configuration file
4529 <?xml version="1.0"?>
4531 <modulemap>
4532 <module magick="8BIM" name="META" />
4533 </modulemap>
4534 type.mgk
4536 master type (fonts) configuration file
4537 <?xml version="1.0"?>
4539 <typemap>
4540 <include file="type-windows.mgk" />
4541 <type
4542 name="AvantGarde-Book"
4543 fullname="AvantGarde Book"
4544 family="AvantGarde"
4545 foundry="URW"
4546 weight="400"
4547 style="normal"
4548 stretch="normal"
4549 format="type1"
4550 metrics="/usr/local/share/ghostscript/fonts/a010013l.afm"
4551 glyphs="/usr/local/share/ghostscript/fonts/a010013l.pfb"
4552 />
4553 </typemap>
4554
4556 Animate displays a sequence of images on any workstation display run‐
4557 ning an X server. animate first determines the hardware capabilities of
4558 the workstation. If the number of unique colors in an image is less
4559 than or equal to the number the workstation can support, the image is
4560 displayed in an X window. Otherwise the number of colors in the image
4561 is first reduced to match the color resolution of the workstation be‐
4562 fore it is displayed.
4563 This means that a continuous-tone 24 bits-per-pixel image can display
4565 on a 8 bit pseudo-color device or monochrome device. In most instances
4566 the reduced color image closely resembles the original. Alternatively,
4567 a monochrome or pseudo-color image sequence can display on a continu‐
4568 ous-tone 24 bits-per-pixel device.
4569 To help prevent color flashing on X server visuals that have colormaps,
4571 animate creates a single colormap from the image sequence. This can be
4572 rather time consuming. You can speed this operation up by reducing the
4573 colors in the image before you "animate" them. Use mogrify to color re‐
4574 duce the images to a single colormap. See mogrify(1) for details. Al‐
4575 ternatively, you can use a Standard Colormap; or a static, direct, or
4576 true color visual. You can define a Standard Colormap with xstdcmap.
4577 See xstdcmap(1) for details. This method is recommended for colormapped
4578 X server because it eliminates the need to compute a global colormap.
4579
4581 To animate a set of images of a cockatoo, use:
4582 gm animate cockatoo.*
4584 To animate a cockatoo image sequence while using the Standard Colormap
4586 best, use:
4587 xstdcmap -best
4589 gm animate -map best cockatoo.*
4590 To animate an image of a cockatoo without a border centered on a back‐
4592 drop, use:
4593 gm animate +borderwidth -backdrop cockatoo.*
4596
4598 For a more detailed description of each option, see Options, above.
4599 -authenticate <string>
4602 decrypt image with this password
4603 -backdrop
4605 display the image centered on a backdrop.
4606 -background <color>
4608 the background color
4609 -bordercolor <color>
4611 the border color
4612 -borderwidth <geometry>
4614 the border width
4615 -chop <width>x<height>{+-}<x>{+-}<y>{%}
4617 remove pixels from the interior of an image
4618 -colormap <type>
4620 define the colormap type
4621 -colors <value>
4623 preferred number of colors in the image
4624 -colorspace <value>
4626 the type of colorspace
4627 -crop <width>x<height>{+-}<x>{+-}<y>{%}
4629 preferred size and location of the cropped image
4630 -debug <events>
4632 enable debug printout
4633 -define <key>{=<value>},...
4635 add coder/decoder specific options
4636 -delay <1/100ths of a second>
4638 display the next image after pausing
4639 -density <width>x<height>
4641 horizontal and vertical resolution in pixels of the image
4642 -depth <value>
4644 depth of the image
4645 -display <host:display[.screen]>
4647 specifies the X server to contact
4648 -dispose <method>
4650 GIF disposal method
4651 -dither
4653 apply Floyd/Steinberg error diffusion to the image
4654 -font <name>
4656 use this font when annotating the image with text
4657 -foreground <color>
4659 define the foreground color
4660 -gamma <value>
4662 level of gamma correction
4663 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
4665 Specify dimension, offset, and resize options.
4666 -help print usage instructions
4668 -iconGeometry <geometry>
4670 specify the icon geometry
4671 -iconic
4673 iconic animation
4674 -interlace <type>
4676 the type of interlacing scheme
4677 -limit <type> <value>
4679 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
4680 resource limit
4681 -log <string>
4683 Specify format for debug log
4684 -map <type>
4686 display image using this type.
4687 -matte store matte channel if the image has one
4689 -mattecolor <color>
4691 specify the color to be used with the -frame option
4692 -monitor
4694 show progress indication
4695 -monochrome
4697 transform the image to black and white
4698 -name name an image
4700 -noop NOOP (no option)
4702 -pause <seconds>
4704 pause between animation loops [animate]
4705 -remote
4707 perform a X11 remote operation
4708 -rotate <degrees>{<}{>}
4710 rotate the image
4711 -sampling-factor <horizontal_factor>x<vertical_factor>
4713 chroma subsampling factors
4714 -scenes <value-value>
4716 range of image scene numbers to read
4717 -shared-memory
4719 use shared memory
4720 -size <width>x<height>{+offset}
4722 width and height of the image
4723 -text-font <name>
4725 font for writing fixed-width text
4726 -title <string>
4728 assign title to displayed image [animate, display, montage]
4729 -treedepth <value>
4731 tree depth for the color reduction algorithm
4732 -trim trim an image
4734 -type <type>
4736 the image type
4737 -verbose
4739 print detailed information about the image
4740 -version
4742 print GraphicsMagick version string
4743 -visual <type>
4745 animate images using this X visual type
4746 -window <id>
4748 make image the background of a window
4749 For a more detailed description of each option, see Options,
4751 above.
4752 Any option you specify on the command line remains in effect for
4755 the group of images following it, until the group is terminated
4756 by the appearance of any option or -noop. For example, to ani‐
4757 mate three images, the first with 32 colors, the second with an
4758 unlimited number of colors, and the third with only 16 colors,
4759 use:
4760 gm animate -colors 32 cockatoo.1 -noop cockatoo.2
4763 -colors 16 cockatoo.3
4764 Animate options can appear on the command line or in your X re‐
4766 sources file. See X(1). Options on the command line supersede
4767 values specified in your X resources file. Image filenames may
4768 appear in any order on the command line if the image format is
4769 MIFF (refer to miff(5) and the scene keyword is specified in the
4770 image. Otherwise the images will display in the order they ap‐
4771 pear on the command line.
4772
4774 Press any button to map or unmap the Command widget. See the next sec‐
4775 tion for more information about the Command widget.
4776
4778 The Command widget lists a number of sub-menus and commands. They are
4779 Animate
4781 Open
4783 Play
4784 Step
4785 Repeat
4786 Auto Reverse
4787 Speed
4789 Faster
4791 Slower
4792 Direction
4794 Forward
4796 Reverse
4797 Image Info
4799 Help
4800 Quit
4801 Menu items with a indented triangle have a sub-menu. They are repre‐
4804 sented above as the indented items. To access a sub-menu item, move the
4805 pointer to the appropriate menu and press a button and drag. When you
4806 find the desired sub-menu item, release the button and the command is
4807 executed. Move the pointer away from the sub-menu if you decide not to
4808 execute a particular command.
4809
4811 Ctl+O
4812 Press to load an image from a file.
4814 space
4815 Press to display the next image in the sequence.
4817 <
4818 Press to speed-up the display of the images. Refer to
4820 -delay for more information.
4821 >
4822 Press to slow the display of the images. Refer to -delay
4824 for more information.
4825 ?
4826 Press to display information about the image. Press any
4828 key or button to erase the information.
4829 This information is printed: image name; image size; and
4830 the total number of unique colors in the image.
4831 F1
4832 Press to display helpful information about animate(1).
4834 Ctl-q
4835 Press to discard all images and exit program.
4837
4840 Animate options can appear on the command line or in your X resource
4841 file. Options on the command line supersede values specified in your X
4842 resource file. See X(1) for more information on X resources.
4843 All animate options have a corresponding X resource. In addition, the
4845 animate program uses the following X resources:
4846 background (class Background)
4848 Specifies the preferred color to use for the Image window
4851 background. The default is #ccc.
4852 borderColor (class BorderColor)
4853 Specifies the preferred color to use for the Image window
4856 border. The default is #ccc.
4857 borderWidth (class BorderWidth)
4858 Specifies the width in pixels of the Image window border.
4861 The default is 2.
4862 font (class Font or FontList)
4863 Specifies the name of the preferred font to use in normal
4866 formatted text. The default is 14 point Helvetica.
4867 foreground (class Foreground)
4868 Specifies the preferred color to use for text within the
4871 Image window. The default is black.
4872 geometry (class geometry)
4873 Specifies the preferred size and position of the image
4876 window. It is not necessarily obeyed by all window man‐
4877 agers. Offsets, if present, are handled in X(1) style. A
4878 negative x offset is measured from the right edge of the
4879 screen to the right edge of the icon, and a negative y
4880 offset is measured from the bottom edge of the screen to
4881 the bottom edge of the icon.
4882 iconGeometry (class IconGeometry)
4883 Specifies the preferred size and position of the applica‐
4886 tion when iconified. It is not necessarily obeyed by all
4887 window managers. Offsets, if present, are handled in the
4888 same manner as in class Geometry.
4889 iconic (class Iconic)
4890 This resource indicates that you would prefer that the ap‐
4893 plication's windows initially not be visible as if the
4894 windows had be immediately iconified by you. Window man‐
4895 agers may choose not to honor the application's request.
4896 matteColor (class MatteColor)
4897 Specify the color of windows. It is used for the back‐
4900 grounds of windows, menus, and notices. A 3D effect is
4901 achieved by using highlight and shadow colors derived from
4902 this color. Default value: #ddd.
4903 name (class Name)
4904 This resource specifies the name under which resources for
4907 the application should be found. This resource is useful
4908 in shell aliases to distinguish between invocations of an
4909 application, without resorting to creating links to alter
4910 the executable file name. The default is the application
4911 name.
4912 sharedMemory (class SharedMemory)
4913 This resource specifies whether animate should attempt use
4916 shared memory for pixmaps. ImageMagick must be compiled
4917 with shared memory support, and the display must support
4918 the MIT-SHM extension. Otherwise, this resource is ig‐
4919 nored. The default is True.
4920 text_font (class textFont)
4921 Specifies the name of the preferred font to use in fixed
4924 (typewriter style) formatted text. The default is 14 point
4925 Courier.
4926 title (class Title)
4927 This resource specifies the title to be used for the Image
4930 window. This information is sometimes used by a window
4931 manager to provide some sort of header identifying the
4932 window. The default is the image file name.
4933
4937 batch executes an arbitary number of the utility commands (e.g. con‐
4938 vert) in the form of a simple linear batch script in order to improve
4939 execution efficiency, and/or to allow use as a subordinate co-process
4940 under the control of an arbitrary script or program.
4941
4943 To drive 'gm batch' using a shell script (or a program written in any
4944 language), have the script/program send commands to 'gm batch' via its
4945 standard input. Specify that standard input should be used by using
4946 '-' as the file name. The following example converts all files match‐
4947 ing '*.jpg' to TIFF format while rotating each file by 90 degrees and
4948 stripping all embedded profiles. The shell script syntax is standard
4949 Unix shell:
4950 for file in *.jpg
4952 do
4953 outfile=`basename $file .jpg`.tiff
4954 echo convert -verbose "'$file'" -rotate 90 \
4955 +profile "'*'" "'$outfile'"
4956 done | gm batch -echo on -feedback on -
4957 We can accomplish the same as the previous example by putting all the
4959 commands in a text file and then specifying the name of the text file
4960 as the script to execute:
4961 for file in *.jpg
4963 do
4964 outfile=`basename $file .jpg`.tiff
4965 echo convert -verbose "'$file'" -rotate 90 \
4966 +profile "'*'" "'$outfile'"
4967 done > script.txt
4968 gm batch -echo on -feedback on script.txt
4969
4971 Options are processed from left to right and must appear before any
4972 filename argument.
4973 -echo on|off
4975 command echo on or off
4976 Specify on to enable echoing commands to standard output as they
4978 are read or off to disable. The default is off.
4979 -escape unix|windows
4981 Parse using unix or windows syntax
4982 Commands must be parsed from the input stream and escaping needs
4984 to be used to protect spaces or quoting characters in the input.
4985 Specify unix to use unix-style command line parsing or windows
4986 for Microsoft Windows command shell style parsing. The default
4987 depends on if the software is compiled for Microsoft Windows or
4988 for a Unix-type system (including Cygwin on Microsoft Windows).
4989 It is recommended to use unix syntax because it is more powerful
4990 and more portable.
4991 -fail text
4993 text to print if a command fails
4994 When feedback is enabled, this specifies the text to print when
4996 the command fails. The default text is FAIL.
4997 -feedback on|off
4999 enable error feedback
5000 Print text (see -pass and -fail options) feedback after each
5002 command to indicate the result, the default is off.
5003 -help
5005 Prints batch command help.
5007 -pass text
5009 text to print if a command passes
5010 When feedback is enabled, this specifies the text to print when
5012 the command passes. The default text is PASS.
5013 -prompt text
5015 Prompt text to use for command line
5016 If no filename argument was specified, a simple command prompt
5018 appears where you may enter GraphicsMagick commands. The de‐
5019 fault prompt is GM>. Use this option to change the prompt to
5020 something else.
5021 -stop-on-error on|off
5023 Specify if command processing stops on error
5024 Normally command processing continues if a command encounters an
5026 error. Specify -stop-on-error on to cause processing to quit
5027 immediately on error.
5028
5031 benchmark executes an arbitrary gm utility command (e.g. convert) for
5032 one or more loops, and/or a specified execution time, and reports many
5033 execution metrics. For builds using OpenMP, a mode is provided to exe‐
5034 cute the benchmark with an increasing number of threads and provide a
5035 report of speedup and multi-thread execution efficiency. If benchmark
5036 is used to execute a command without any additional benchmark options,
5037 then the command is run once.
5038
5040 To obtain benchmark information for a single execution of a command:
5041 gm benchmark convert input.ppm -gaussian 0x1 output.ppm
5043 To obtain benchmark information from 100 iterations of the command:
5044 gm benchmark -iterations 100 convert input.ppm \
5046 -gaussian 0x1 output.ppm
5047 To obtain benchmark information by iterating the command until a speci‐
5048 fied amount of time (in seconds) has been consumed:
5049 gm benchmark -duration 30 convert input.ppm \
5051 -gaussian 0x1 output.ppm
5052 To obtain a full performance report with an increasing number of
5053 threads (1-32 threads, stepping the number of threads by four each
5054 time):
5055 gm benchmark -duration 3 -stepthreads 4 convert \
5057 input.ppm -gaussian 0x2 output.ppm
5058 Here is the interpretation of the output:
5059 threads - number of threads used.
5061 iter - number of command iterations executed.
5062 user - total user time consumed.
5063 total - total elapsed time consumed.
5064 iter/s - number of command iterations per second.
5065 iter/cpu - amount of CPU time consumed per iteration.
5066 speedup - speedup compared with one thread.
5067 karp-flatt - Karp-Flatt measure of speedup efficiency.
5068 Please note that the reported "speedup" is based on the execution time
5070 of just one thread. A preliminary warm-up pass is used before timing
5071 the first loop in order to ensure that the CPU is brought out of power-
5072 saving modes and that system caches are warmed up. Most modern CPUs
5073 provide a "turbo" mode where the CPU clock speed is increased (e.g. by
5074 a factor of two) when only one or two cores are active. If the CPU
5075 grows excessively hot (due to insufficient cooling), then it may dial
5076 back its clock rates as a form of thermal management. These factors
5077 result in an under-reporting of speedup compared to if "turbo" mode was
5078 disabled and the CPU does not need to worry about thermal management.
5079 The powertop utility available under Linux and Solaris provides a way
5080 to observe CPU core clock rates while a benchmark is running.
5081
5083 Options are processed from left to right and must appear before any
5084 argument.
5085 -duration duration
5087 duration to run benchmark Specify the number of seconds to run
5088 the benchmark. The command is executed repeatedly until the
5089 specified amount of time has elapsed.
5090 -help
5092 Prints benchmark command help.
5094 -iterations loops
5096 number of command iterations Specify the number of iterations to
5097 run the benchmark. The command is executed repeatedly until the
5098 specified number of iterations has been reached.
5099 -rawcsv
5101 Print results in CSV format Print results in a comma-separated
5102 value (CSV) format which is easy to parse for plotting or im‐
5103 porting into a spreadsheet or database. The values reported are
5104 threads, iterations, user_time, and elapsed_time.
5105 -stepthreads step
5107 execute a per-thread benchmark ramp
5108 Execute a per-thread benchmark ramp, incrementing the number of
5109 threads at each step by the specified value. The maximum number
5110 of threads is taken from the standard OMP_NUM_THREADS environ‐
5111 ment variable.
5112
5114 compare compares two similar images using a specified statistical
5115 method (see -metric) and/or by writing a difference image (-file), with
5116 the altered pixels annotated using a specified method (see -highlight-
5117 style) and color (see -highlight-color). Reference-image is the origi‐
5118 nal image and compare-image is the (possibly) altered version, which
5119 should have the same dimensions as reference-image.
5120
5122 To compare two images using Mean Square Error (MSE) statistical analy‐
5123 sis use:
5124 gm compare -metric mse original.miff compare.miff
5126 To create an annotated difference image use:
5128 gm compare -highlight-style assign -highlight-color purple \
5130 -file diff.miff original.miff compare.miff
5131
5133 Options are processed in command line order. Any option you specify on
5134 the command line remains in effect only for the image that follows.
5135 All options are reset to their default values after each image is read.
5136 For a more detailed description of each option, see Options, above.
5138 -authenticate <string>
5141 decrypt image with this password
5142 -auto-orient
5144 orient (rotate) image so it is upright
5145 -colorspace <value>
5147 the type of colorspace
5148 -compress <type>
5150 the type of image compression
5151 -debug <events>
5153 enable debug printout
5154 -define <key>{=<value>},...
5156 add coder/decoder specific options
5157 -density <width>x<height>
5159 horizontal and vertical resolution in pixels of the image
5160 -depth <value>
5162 depth of the image
5163 -display <host:display[.screen]>
5165 specifies the X server to contact
5166 -endian <type>
5168 specify endianness (MSB, LSB, or Native) of image
5169 -file <filename>
5171 write annotated difference image to file
5172 -help print usage instructions
5174 -highlight-color <color>
5176 pixel annotation color
5177 -highlight-style <style>
5179 pixel annotation style
5180 -interlace <type>
5182 the type of interlacing scheme
5183 -limit <type> <value>
5185 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
5186 resource limit
5187 -log <string>
5189 Specify format for debug log
5190 -matte store matte channel if the image has one
5192 -maximum-error <limit>
5194 specifies the maximum amount of total image error
5195 -metric <metric>
5197 comparison metric (MAE, MSE, PAE, PSNR, RMSE)
5198 -monitor
5200 show progress indication
5201 -sampling-factor <horizontal_factor>x<vertical_factor>
5203 chroma subsampling factors
5204 -size <width>x<height>{+offset}
5206 width and height of the image
5207 -type <type>
5209 the image type
5210 -verbose
5212 print detailed information about the image
5213 -version
5215 print GraphicsMagick version string
5216 For a more detailed description of each option, see Options,
5218 above.
5219
5222 composite composites (combines) images to create new images. base-im‐
5223 age is the base image and change-image contains the changes. ouput-im‐
5224 age is the result, and normally has the same dimensions as base-image.
5225 The optional mask-image can be used to provide opacity information for
5228 change-image when it has none or if you want a different mask. A mask
5229 image is typically grayscale and the same size as base-image. If mask-
5230 image is not grayscale, it is converted to grayscale and the resulting
5231 intensities are used as opacity information.
5232
5234 To composite an image of a cockatoo with a perch, use:
5235 gm composite cockatoo.miff perch.ras composite.miff
5237 To compute the difference between images in a series, use:
5239 gm composite -compose difference series.2 series.1
5241 difference.miff
5242 To composite an image of a cockatoo with a perch starting at location
5244 (100,150), use:
5245 gm composite -geometry +100+150 cockatoo.miff
5247 perch.ras composite.miff
5248 To tile a logo across your image of a cockatoo, use
5250 gm convert +shade 30x60 cockatoo.miff mask.miff
5252 gm composite -compose bumpmap -tile logo.png
5253 cockatoo.miff mask.miff composite.miff
5254 To composite a red, green, and blue color plane into a single composite
5256 image, try
5257 gm composite -compose CopyGreen green.png red.png
5259 red-green.png
5260 gm composite -compose CopyBlue blue.png red-green.png
5261 gm composite.png
5262
5264 Options are processed in command line order. Any option you specify on
5265 the command line remains in effect only for the image that follows.
5266 All options are reset to their default values after each image is read.
5267 For a more detailed description of each option, see Options, above.
5269 -authenticate <string>
5272 decrypt image with this password
5273 -background <color>
5275 the background color
5276 -blue-primary <x>,<y>
5278 blue chromaticity primary point
5279 -colors <value>
5281 preferred number of colors in the image
5282 -colorspace <value>
5284 the type of colorspace
5285 -comment <string>
5287 annotate an image with a comment
5288 -compose <operator>
5290 the type of image composition
5291 -compress <type>
5293 the type of image compression
5294 -debug <events>
5296 enable debug printout
5297 -define <key>{=<value>},...
5299 add coder/decoder specific options
5300 -density <width>x<height>
5302 horizontal and vertical resolution in pixels of the image
5303 -depth <value>
5305 depth of the image
5306 -displace <horizontal scale>x<vertical scale>
5308 shift image pixels as defined by a displacement map
5309 -display <host:display[.screen]>
5311 specifies the X server to contact
5312 -dispose <method>
5314 GIF disposal method
5315 -dissolve <percent>
5317 dissolve an image into another by the given percent
5318 -dither
5320 apply Floyd/Steinberg error diffusion to the image
5321 -encoding <type>
5323 specify the text encoding
5324 -endian <type>
5326 specify endianness (MSB, LSB, or Native) of image
5327 -filter <type>
5329 use this type of filter when resizing an image
5330 -font <name>
5332 use this font when annotating the image with text
5333 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
5335 Specify dimension, offset, and resize options.
5336 -gravity <type>
5338 direction primitive gravitates to when annotating the image.
5339 -green-primary <x>,<y>
5341 green chromaticity primary point
5342 -help print usage instructions
5344 -interlace <type>
5346 the type of interlacing scheme
5347 -label <name>
5349 assign a label to an image
5350 -limit <type> <value>
5352 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
5353 resource limit
5354 -log <string>
5356 Specify format for debug log
5357 -matte store matte channel if the image has one
5359 -monitor
5361 show progress indication
5362 -monochrome
5364 transform the image to black and white
5365 -negate
5367 replace every pixel with its complementary color
5368 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
5370 size and location of an image canvas
5371 -profile <filename>
5373 add ICM, IPTC, or generic profile to image
5374 -quality <value>
5376 JPEG/MIFF/PNG/TIFF compression level
5377 -recolor <matrix>
5379 apply a color translation matrix to image channels
5380 -red-primary <x>,<y>
5382 red chromaticity primary point
5383 -render
5385 render vector operations
5386 -repage <width>x<height>+xoff+yoff[!]
5388 Adjust image page offsets
5389 -resize <width>x<height>{%}{@}{!}{<}{>}
5391 resize an image
5392 -rotate <degrees>{<}{>}
5394 rotate the image
5395 -sampling-factor <horizontal_factor>x<vertical_factor>
5397 chroma subsampling factors
5398 -scene <value>
5400 set scene number
5401 -set <attribute> <value>
5403 set an image attribute
5404 +set <attribute>
5406 unset an image attribute
5407 -sharpen <radius>{x<sigma>}
5409 sharpen the image
5410 -size <width>x<height>{+offset}
5412 width and height of the image
5413 -stegano <offset>
5415 hide watermark within an image
5416 -stereo
5418 composite two images to create a stereo anaglyph
5419 -strip remove all profiles and text attributes from the image
5421 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
5423 resize an image (quickly)
5424 -treedepth <value>
5426 tree depth for the color reduction algorithm
5427 -trim trim an image
5429 -type <type>
5431 the image type
5432 -units <type>
5434 the units of image resolution
5435 -unsharp <radius>{x<sigma>}{+<amount>}{+<threshold>}
5437 sharpen the image with an unsharp mask operator
5438 -verbose
5440 print detailed information about the image
5441 -version
5443 print GraphicsMagick version string
5444 -watermark <brightness>x<saturation>
5446 percent brightness and saturation of a watermark
5447 -white-point <x>,<y>
5449 chromaticity white point
5450 -write <filename>
5452 write an intermediate image [convert, composite]
5453 For a more detailed description of each option, see Options,
5455 above.
5456
5459 The Magick scripting language (MSL) will primarily benefit those that
5460 want to accomplish custom image processing tasks but do not wish to
5461 program, or those that do not have access to a Perl interpreter or a
5462 compiler. The interpreter is called conjure and here is an example
5463 script:
5464 <?xml version="1.0" encoding="UTF-8"?>
5466 <image size="400x400" >
5467 <read filename="image.gif" />
5468 <get width="base-width" height="base-height" />
5469 <resize geometry="%[dimensions]" />
5470 <get width="width" height="height" />
5471 <print output=
5472 "Image sized from %[base-width]x%[base-height]
5473 to %[width]x%[height].\n" />
5474 <write filename="image.png" />
5475 </image>
5476 invoked with
5478 gm conjure -dimensions 400x400 incantation.msl
5480 All operations will closely follow the key/value pairs defined in Perl‐
5482 Magick, unless otherwise noted.
5483
5485 Options are processed in command line order. Any option you specify on
5486 the command line remains in effect until it is explicitly changed by
5487 specifying the option again with a different effect, or if it is
5488 changed by a statement in the scripting language.
5489 You can define your own keyword/value pairs on the command line. The
5491 script can then use this information when setting values by including
5492 %[keyword] in the string. For example, if you included "-dimensions
5493 400x400" on the command line, as illustrated above, then any string
5494 containing "%[dimensions]" would have 400x400 substituted. The
5495 "%[string]" can be used either an entire string, such as geome‐
5496 try="%[dimensions]" or as a part of a string such as filename="%[base‐
5497 name].png".
5498 The keyword can be any string except for the following reserved strings
5500 (in any upper, lower, or mixed case variant): debug, help, and verbose,
5501 whose usage is described below.
5502 The value can be any string. If either the keyword or the value con‐
5504 tains white space or any symbols that have special meanings to your
5505 shell such as "#", "|", or "%", enclose the string in quotation marks
5506 or use "\" to escape the white space and special symbols.
5507 Keywords and values are case dependent. "Key", "key", and "KEY" would
5509 be three different keywords.
5510 For a more detailed description of each option, see Options, above.
5512 -debug <events>
5515 enable debug printout
5516 -define <key>{=<value>},...
5518 add coder/decoder specific options
5519 -help print usage instructions
5521 -log <string>
5523 Specify format for debug log
5524 -verbose
5526 print detailed information about the image
5527 -version
5529 print GraphicsMagick version string
5530
5532 The Magick Scripting Language (MSL) presently defines the following el‐
5533 ements and their attributes:
5534 <image>
5536 background, color, id, size
5538 Define a new image object. </image> destroys it. Because
5540 of this, if you wish to reference multiple "subimages"
5541 (aka pages or layers), you can embed one image element in‐
5542 side of another. For example:
5543 <image>
5547 <read filename="input.png" />
5548 <get width="base-width" height="base-height" />
5549 <image height="base-height" width="base-width">
5550 <image />
5551 <write filename="output.mng" />
5552 </image>
5553 <image size="400x400" />
5557 <group>
5559 Define a new group of image objects. By default, images
5562 are only valid for the life of their <image>element.
5563 <image> -- creates the image
5567 ..... -- do stuff with it
5568 </image> -- dispose of the image
5569 However, in a group, all images in that group will stay
5572 around for the life of the group:
5573 <group> -- start a group
5577 <image> -- create an image
5578 .... -- do stuff
5579 </image> -- NOOP
5580 <image> -- create another image
5581 .... -- do more stuff
5582 </image> -- NOOP
5583 <write filename="image.mng" /> -- output
5584 </group> -- dispose of both images
5585 <read>
5587 filename
5589 Read a new image from a disk file.
5591 <read filename="image.gif" />
5595 To read two images use
5598 <read filename="image.gif" />
5602 <read filename="image.png />
5603 <write>
5605 filename
5607 Write the image(s) to disk, either as a single multiple-
5608 image file or multiple ones if necessary.
5609 <write filename=image.tiff" />
5613 <get>
5614 Get any attribute recognized by PerlMagick's GetAt‐
5616 tribute() and stores it as an image attribute for later
5617 use. Currently only width and height are supported.
5618 <get width="base-width" height="base-height" />
5621 <print output="Image size is %[base-width]x%[base-height].\n" />
5622 <set>
5624 background, bordercolor, clip-mask, colorspace, density,
5626 magick, mattecolor, opacity. Set an attribute recognized
5627 by PerlMagick's GetAttribute().
5628 <profile>
5629 [profilename]
5631 Read one or more IPTC, ICC or generic profiles from file
5633 and assign to image
5634 <profile iptc="profile.iptc" generic="generic.dat" />
5638 To remove a specified profile use "!" as the filename eg
5641 <profile icm="!" iptc="profile.iptc" />
5645 <border>
5647 fill, geometry, height, width
5649 <blur>
5650 radius, sigma
5652 <charcoal>
5653 radius, sigma
5655 <chop>
5656 geometry, height, width, x, y
5658 <crop>
5659 geometry, height, width, x, y
5661 <composite>
5662 compose, geometry, gravity, image, x, y
5664 <?xml version="1.0" encoding="UTF-8"?>
5667 <group>
5668 <image id="image_01">
5669 <read filename="cloud3.gif"/>
5670 <resize geometry="250x90"/>
5671 </image>
5672 <image id="image_02">
5673 <read filename="cloud4.gif"/>
5674 <resize geometry="190x100"/>
5675 </image>
5676 <image>
5677 <read filename="background.jpg"/>
5678 <composite image="image_01" geometry="+740+470"/>
5679 <composite image="image_02" geometry="+390+415"/>
5680 </image>
5681 <write filename="result.png"/>
5682 </group>
5683 <despeckle>
5685 <emboss>
5687 radius, sigma
5689 <enhance>
5690 <equalize>
5692 <edge>
5694 radius
5696 <flip>
5697 <flop>
5699 <frame>
5701 fill, geometry, height, width, x, y, inner, outer
5703 <flatten>
5704 <get>
5706 height, width
5708 <gamma>
5709 red, green, blue
5711 <image>
5712 background, color, id, size
5714 <implode>
5715 amount
5717 <magnify>
5718 <minify>
5720 <medianfilter>
5722 radius
5724 <normalize>
5725 <oilpaint>
5727 radius
5729 <print>
5730 output
5732 <profile>
5733 [profilename]
5735 <read>
5736 <resize>
5738 blur, filter, geometry, height, width
5740 <roll>
5741 geometry, x, y
5743 <rotate>
5744 degrees
5746 <reducenoise>
5747 radius
5749 <sample>
5750 geometry, height, width
5752 <scale>
5753 geometry, height, width
5755 <sharpen>
5756 radius, sigma
5758 <shave>
5759 geometry, height, width
5761 <shear>
5762 x, y
5764 <solarize>
5765 threshold
5767 <spread>
5768 radius
5770 <stegano>
5771 image
5773 <stereo>
5774 image
5776 <swirl>
5777 degrees
5779 <texture>
5780 image
5782 <threshold>
5783 threshold
5785 <transparent>
5786 color
5788 <trim>
5789
5793 Convert converts an input file using one image format to an output file
5794 with a differing image format. In addition, various types of image pro‐
5795 cessing can be performed on the converted image during the conversion
5796 process. Convert recognizes the image formats listed in GraphicsMag‐
5797 ick(1).
5798
5801 To make a thumbnail of a JPEG image, use:
5802 gm convert -size 120x120 cockatoo.jpg -resize 120x120
5804 +profile "*" thumbnail.jpg
5805 In this example, '-size 120x120' gives a hint to the JPEG decoder that
5807 the image is going to be downscaled to 120x120, allowing it to run
5808 faster by avoiding returning full-resolution images to GraphicsMagick
5809 for the subsequent resizing operation. The ´-resize 120x120' specifies
5810 the desired dimensions of the output image. It will be scaled so its
5811 largest dimension is 120 pixels. The ´+profile "*"' removes any ICM,
5812 EXIF, IPTC, or other profiles that might be present in the input and
5813 aren't needed in the thumbnail.
5814 To convert a MIFF image of a cockatoo to a SUN raster image, use:
5816 gm convert cockatoo.miff sun:cockatoo.ras
5818 To convert a multi-page PostScript document to individual FAX pages,
5820 use:
5821 gm convert -monochrome document.ps fax:page
5823 To convert a TIFF image to a PostScript A4 page with the image in the
5825 lower left-hand corner, use:
5826 gm convert -page A4+0+0 image.tiff document.ps
5828 To convert a raw Gray image with a 128 byte header to a portable
5830 graymap, use:
5831 gm convert -depth 8 -size 768x512+128 gray:raw
5833 image.pgm
5834 In this example, "raw" is the input file. Its format is "gray" and it
5836 has the dimensions and number of header bytes specified by the -size
5837 option and the sample depth specified by the -depth option. The output
5838 file is "image.pgm". The suffix ".pgm" specifies its format.
5839 To convert a Photo CD image to a TIFF image, use:
5841 gm convert -size 1536x1024 img0009.pcd image.tiff
5843 gm convert img0009.pcd[4] image.tiff
5844 To create a visual image directory of all your JPEG images, use:
5846 gm convert 'vid:*.jpg' directory.miff
5848 To annotate an image with blue text using font 12x24 at position
5850 (100,100), use:
5851 gm convert -font helvetica -fill blue
5853 -draw "text 100,100 Cockatoo"
5854 bird.jpg bird.miff
5855 To tile a 640x480 image with a JPEG texture with bumps use:
5857 gm convert -size 640x480 tile:bumps.jpg tiled.png
5859 To surround an icon with an ornamental border to use with Mosaic(1),
5861 use:
5862 gm convert -mattecolor "#697B8F" -frame 6x6 bird.jpg
5864 icon.png
5865 To create a MNG animation from a DNA molecule sequence, use:
5867 gm convert -delay 20 dna.* dna.mng
5869
5871 Options are processed in command line order. Any option you specify on
5872 the command line remains in effect for the set of images that follows,
5873 until the set is terminated by the appearance of any option or -noop.
5874 Some options only affect the decoding of images and others only the en‐
5875 coding. The latter can appear after the final group of input images.
5876 For a more detailed description of each option, see Options, above.
5878 -adjoin
5881 join images into a single multi-image file
5882 -affine <matrix>
5884 drawing transform matrix
5885 -antialias
5887 remove pixel aliasing
5888 -append
5890 append a set of images
5891 -asc-cdl <spec>
5893 apply ASC CDL color transform
5894 -authenticate <string>
5896 decrypt image with this password
5897 -auto-orient
5899 orient (rotate) image so it is upright
5900 -average
5902 average a set of images
5903 -background <color>
5905 the background color
5906 -black-threshold red[,green][,blue][,opacity]
5908 pixels below the threshold become black
5909 -blue-primary <x>,<y>
5911 blue chromaticity primary point
5912 -blur <radius>{x<sigma>}
5914 blur the image with a Gaussian operator
5915 -border <width>x<height>
5917 surround the image with a border of color
5918 -bordercolor <color>
5920 the border color
5921 -box <color>
5923 set the color of the annotation bounding box
5924 -channel <type>
5926 the type of channel
5927 -charcoal <factor>
5929 simulate a charcoal drawing
5930 -chop <width>x<height>{+-}<x>{+-}<y>{%}
5932 remove pixels from the interior of an image
5933 -clip apply the clipping path, if one is present
5935 -coalesce
5937 merge a sequence of images
5938 -colorize <value>
5940 colorize the image with the pen color
5941 -colors <value>
5943 preferred number of colors in the image
5944 -colorspace <value>
5946 the type of colorspace
5947 -comment <string>
5949 annotate an image with a comment
5950 -compose <operator>
5952 the type of image composition
5953 -compress <type>
5955 the type of image compression
5956 -contrast
5958 enhance or reduce the image contrast
5959 -convolve <kernel>
5961 convolve image with the specified convolution kernel
5962 -crop <width>x<height>{+-}<x>{+-}<y>{%}
5964 preferred size and location of the cropped image
5965 -cycle <amount>
5967 displace image colormap by amount
5968 -debug <events>
5970 enable debug printout
5971 -deconstruct
5973 break down an image sequence into constituent parts
5974 -define <key>{=<value>},...
5976 add coder/decoder specific options
5977 -delay <1/100ths of a second>
5979 display the next image after pausing
5980 -density <width>x<height>
5982 horizontal and vertical resolution in pixels of the image
5983 -depth <value>
5985 depth of the image
5986 -despeckle
5988 reduce the speckles within an image
5989 -display <host:display[.screen]>
5991 specifies the X server to contact
5992 -dispose <method>
5994 GIF disposal method
5995 -dither
5997 apply Floyd/Steinberg error diffusion to the image
5998 -draw <string>
6000 annotate an image with one or more graphic primitives
6001 -edge <radius>
6003 detect edges within an image
6004 -emboss <radius>
6006 emboss an image
6007 -encoding <type>
6009 specify the text encoding
6010 -endian <type>
6012 specify endianness (MSB, LSB, or Native) of image
6013 -enhance
6015 apply a digital filter to enhance a noisy image
6016 -equalize
6018 perform histogram equalization to the image
6019 -extent <width>x<height>{+-}<x>{+-}<y>
6021 composite image on background color canvas image
6022 -fill <color>
6024 color to use when filling a graphic primitive
6025 -filter <type>
6027 use this type of filter when resizing an image
6028 -flatten
6030 flatten a sequence of images
6031 -flip create a "mirror image"
6033 -flop create a "mirror image"
6035 -font <name>
6037 use this font when annotating the image with text
6038 -format <string>
6040 output formatted image characteristics
6041 -frame <width>x<height>+<outer bevel width>+<inner bevel width>
6043 surround the image with an ornamental border
6044 -fuzz <distance>{%}
6046 colors within this Euclidean distance are considered equal
6047 -gamma <value>
6049 level of gamma correction
6050 -gaussian <radius>{x<sigma>}
6052 blur the image with a Gaussian operator
6053 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
6055 Specify dimension, offset, and resize options.
6056 -gravity <type>
6058 direction primitive gravitates to when annotating the image.
6059 -green-primary <x>,<y>
6061 green chromaticity primary point
6062 -hald-clut <clut>
6064 apply a Hald CLUT to the image
6065 -help print usage instructions
6067 -implode <factor>
6069 implode image pixels about the center
6070 -intent <type>
6072 use this type of rendering intent when managing the image color
6073 -interlace <type>
6075 the type of interlacing scheme
6076 -label <name>
6078 assign a label to an image
6079 -lat <width>x<height>{+-}<offset>{%}
6081 perform local adaptive thresholding
6082 -level <black_point>{,<gamma>}{,<white_point>}{%}
6084 adjust the level of image contrast
6085 -limit <type> <value>
6087 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
6088 resource limit
6089 -list <type>
6091 the type of list
6092 -log <string>
6094 Specify format for debug log
6095 -loop <iterations>
6097 add Netscape loop extension to your GIF animation
6098 -magnify
6100 magnify the image
6101 -map <filename>
6103 choose a particular set of colors from this image
6104 -mask <filename>
6106 Specify a clipping mask
6107 -matte store matte channel if the image has one
6109 -mattecolor <color>
6111 specify the color to be used with the -frame option
6112 -median <radius>
6114 apply a median filter to the image
6115 -minify <factor>
6117 minify the image
6118 -modulate brightness[,saturation[,hue]]
6120 vary the brightness, saturation, and hue of an image
6121 -monitor
6123 show progress indication
6124 -monochrome
6126 transform the image to black and white
6127 -morph <frames>
6129 morphs an image sequence
6130 -mosaic
6132 create a mosaic from an image or an image sequence
6133 -motion-blur <radius>{x<sigma>}{+angle}
6135 Simulate motion blur
6136 -negate
6138 replace every pixel with its complementary color
6139 -noise <radius|type>
6141 add or reduce noise in an image
6142 -noop NOOP (no option)
6144 -normalize
6146 transform image to span the full range of color values
6147 -opaque <color>
6149 change this color to the pen color within the image
6150 -operator channel operator rvalue[%]
6152 apply a mathematical, bitwise, or value operator to an image
6153 channel
6154 -ordered-dither <channeltype> <NxN>
6156 ordered dither the image
6157 -orient <orientation>
6159 Set the image orientation attribute
6160 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
6162 size and location of an image canvas
6163 -paint <radius>
6165 simulate an oil painting
6166 -pen <color>
6168 (This option has been replaced by the -fill option)
6169 -ping efficiently determine image characteristics
6171 -pointsize <value>
6173 pointsize of the PostScript, X11, or TrueType font
6174 -preview <type>
6176 image preview type
6177 -process <command>
6179 process a sequence of images using a process module
6180 -profile <filename>
6182 add ICM, IPTC, or generic profile to image
6183 -quality <value>
6185 JPEG/MIFF/PNG/TIFF compression level
6186 -raise <width>x<height>
6188 lighten or darken image edges
6189 -random-threshold <channeltype> <LOWxHIGH>
6191 random threshold the image
6192 -recolor <matrix>
6194 apply a color translation matrix to image channels
6195 -red-primary <x>,<y>
6197 red chromaticity primary point
6198 -region <width>x<height>{+-}<x>{+-}<y>
6200 apply options to a portion of the image
6201 -render
6203 render vector operations
6204 -repage <width>x<height>+xoff+yoff[!]
6206 Adjust image page offsets
6207 -resample <horizontal>x<vertical>
6209 Resample image to specified horizontal and vertical resolution
6210 -resize <width>x<height>{%}{@}{!}{<}{>}
6212 resize an image
6213 -roll {+-}<x>{+-}<y>
6215 roll an image vertically or horizontally
6216 -rotate <degrees>{<}{>}
6218 rotate the image
6219 -sample <geometry>
6221 scale image using pixel sampling
6222 -sampling-factor <horizontal_factor>x<vertical_factor>
6224 chroma subsampling factors
6225 -scale <geometry>
6227 scale the image.
6228 -scene <value>
6230 set scene number
6231 -set <attribute> <value>
6233 set an image attribute
6234 +set <attribute>
6236 unset an image attribute
6237 -segment <cluster threshold>x<smoothing threshold>
6239 segment an image
6240 -shade <azimuth>x<elevation>
6242 shade the image using a distant light source
6243 -sharpen <radius>{x<sigma>}
6245 sharpen the image
6246 -shave <width>x<height>{%}
6248 shave pixels from the image edges
6249 -shear <x degrees>x<y degrees>
6251 shear the image along the X or Y axis
6252 -size <width>x<height>{+offset}
6254 width and height of the image
6255 -solarize <factor>
6257 negate all pixels above the threshold level
6258 -spread <amount>
6260 displace image pixels by a random amount
6261 -strip remove all profiles and text attributes from the image
6263 -stroke <color>
6265 color to use when stroking a graphic primitive
6266 -strokewidth <value>
6268 set the stroke width
6269 -swirl <degrees>
6271 swirl image pixels about the center
6272 -texture <filename>
6274 name of texture to tile onto the image background
6275 -threshold <value>{%}
6277 threshold the image
6278 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
6280 resize an image (quickly)
6281 -tile <filename>
6283 tile image when filling a graphic primitive
6284 -transform
6286 transform the image
6287 -transparent <color>
6289 make this color transparent within the image
6290 -treedepth <value>
6292 tree depth for the color reduction algorithm
6293 -trim trim an image
6295 -type <type>
6297 the image type
6298 -units <type>
6300 the units of image resolution
6301 -unsharp <radius>{x<sigma>}{+<amount>}{+<threshold>}
6303 sharpen the image with an unsharp mask operator
6304 -use-pixmap
6306 use the pixmap
6307 -verbose
6309 print detailed information about the image
6310 -version
6312 print GraphicsMagick version string
6313 -view <string>
6315 FlashPix viewing parameters
6316 -virtual-pixel <method>
6318 specify contents of "virtual pixels"
6319 -wave <amplitude>x<wavelength>
6321 alter an image along a sine wave
6322 -white-point <x>,<y>
6324 chromaticity white point
6325 -white-threshold red[,green][,blue][,opacity]
6327 pixels above the threshold become white
6328 -write <filename>
6330 write an intermediate image [convert, composite]
6331 For a more detailed description of each option, see Options,
6333 above.
6334
6336 Display is a machine architecture independent image processing and dis‐
6337 play program. It can display an image on any workstation screen running
6338 an X server. Display can read and write many of the more popular image
6339 formats (e.g. JPEG, TIFF, PNM, Photo CD, etc.).
6340 With display, you can perform these functions on an image:
6342 o load an image from a file
6344 o display the next image
6345 o display the former image
6346 o display a sequence of images as a slide show
6347 o write the image to a file
6348 o print the image to a PostScript printer
6349 o delete the image file
6350 o create a Visual Image Directory
6351 o select the image to display by its thumbnail rather than
6352 name
6353 o undo last image transformation
6354 o copy a region of the image
6355 o paste a region to the image
6356 o restore the image to its original size
6357 o refresh the image
6358 o half the image size
6359 o double the image size
6360 o resize the image
6361 o crop the image
6362 o cut the image
6363 o flop image in the horizontal direction
6364 o flip image in the vertical direction
6365 o rotate the image 90 degrees clockwise
6366 o rotate the image 90 degrees counter-clockwise
6367 o rotate the image
6368 o shear the image
6369 o roll the image
6370 o trim the image edges
6371 o invert the colors of the image
6372 o vary the color brightness
6373 o vary the color saturation
6374 o vary the image hue
6375 o gamma correct the image
6376 o sharpen the image contrast
6377 o dull the image contrast
6378 o perform histogram equalization on the image
6379 o perform histogram normalization on the image
6380 o negate the image colors
6381 o convert the image to grayscale
6382 o set the maximum number of unique colors in the image
6383 o reduce the speckles within an image
6384 o eliminate peak noise from an image
6385 o detect edges within the image
6386 o emboss an image
6387 o segment the image by color
6388 o simulate an oil painting
6389 o simulate a charcoal drawing
6390 o annotate the image with text
6391 o draw on the image
6392 o edit an image pixel color
6393 o edit the image matte information
6394 o composite an image with another
6395 o add a border to the image
6396 o surround image with an ornamental border
6397 o apply image processing techniques to a region of interest
6398 o display information about the image
6399 o zoom a portion of the image
6400 o show a histogram of the image
6401 o display image to background of a window
6402 o set user preferences
6403 o display information about this program
6404 o discard all images and exit program
6405 o change the level of magnification
6406 o display images specified by a World Wide Web (WWW) uniform
6407 resource locator (URL)
6408
6411 To scale an image of a cockatoo to exactly 640 pixels in width and 480
6412 pixels in height and position the window at location (200,200), use:
6413 gm display -geometry 640x480+200+200! cockatoo.miff
6415 To display an image of a cockatoo without a border centered on a back‐
6417 drop, use:
6418 gm display +borderwidth -backdrop cockatoo.miff
6420 To tile a slate texture onto the root window, use:
6422 gm display -size 1280x1024 -window root slate.png
6424 To display a visual image directory of all your JPEG images, use:
6426 gm display 'vid:*.jpg'
6428 To display a MAP image that is 640 pixels in width and 480 pixels in
6430 height with 256 colors, use:
6431 gm display -size 640x480+256 cockatoo.map
6433 To display an image of a cockatoo specified with a World Wide Web (WWW)
6435 uniform resource locator (URL), use:
6436 gm display ftp://wizards.dupont.com/images/cockatoo.jpg
6438 To display histogram of an image, use:
6440 gm gm convert file.jpg HISTOGRAM:- | gm display -
6442
6444 Options are processed in command line order. Any option you specify on
6445 the command line remains in effect until it is explicitly changed by
6446 specifying the option again with a different effect. For example to
6447 display three images, the first with 32 colors, the second with an un‐
6448 limited number of colors, and the third with only 16 colors, use:
6449 gm display -colors 32 cockatoo.miff -noop duck.miff
6451 -colors 16 macaw.miff
6452 Display options can appear on the command line or in your X resources
6454 file. See X(1). Options on the command line supersede values specified
6455 in your X resources file.
6456 For a more detailed description of each option, see Options, above.
6458 -authenticate <string>
6461 decrypt image with this password
6462 -backdrop
6464 display the image centered on a backdrop.
6465 -background <color>
6467 the background color
6468 -border <width>x<height>
6470 surround the image with a border of color
6471 -bordercolor <color>
6473 the border color
6474 -borderwidth <geometry>
6476 the border width
6477 -colormap <type>
6479 define the colormap type
6480 -colors <value>
6482 preferred number of colors in the image
6483 -colorspace <value>
6485 the type of colorspace
6486 -comment <string>
6488 annotate an image with a comment
6489 -compress <type>
6491 the type of image compression
6492 -contrast
6494 enhance or reduce the image contrast
6495 -crop <width>x<height>{+-}<x>{+-}<y>{%}
6497 preferred size and location of the cropped image
6498 -debug <events>
6500 enable debug printout
6501 -define <key>{=<value>},...
6503 add coder/decoder specific options
6504 -delay <1/100ths of a second>
6506 display the next image after pausing
6507 -density <width>x<height>
6509 horizontal and vertical resolution in pixels of the image
6510 -depth <value>
6512 depth of the image
6513 -despeckle
6515 reduce the speckles within an image
6516 -display <host:display[.screen]>
6518 specifies the X server to contact
6519 -dispose <method>
6521 GIF disposal method
6522 -dither
6524 apply Floyd/Steinberg error diffusion to the image
6525 -edge <radius>
6527 detect edges within an image
6528 -endian <type>
6530 specify endianness (MSB, LSB, or Native) of image
6531 -enhance
6533 apply a digital filter to enhance a noisy image
6534 -filter <type>
6536 use this type of filter when resizing an image
6537 -flip create a "mirror image"
6539 -flop create a "mirror image"
6541 -font <name>
6543 use this font when annotating the image with text
6544 -foreground <color>
6546 define the foreground color
6547 -frame <width>x<height>+<outer bevel width>+<inner bevel width>
6549 surround the image with an ornamental border
6550 -gamma <value>
6552 level of gamma correction
6553 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
6555 Specify dimension, offset, and resize options.
6556 -help print usage instructions
6558 -iconGeometry <geometry>
6560 specify the icon geometry
6561 -iconic
6563 iconic animation
6564 -immutable
6566 make image immutable
6567 -interlace <type>
6569 the type of interlacing scheme
6570 -label <name>
6572 assign a label to an image
6573 -limit <type> <value>
6575 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
6576 resource limit
6577 -log <string>
6579 Specify format for debug log
6580 -magnify <factor>
6582 magnify the image
6583 -map <type>
6585 display image using this type.
6586 -matte store matte channel if the image has one
6588 -mattecolor <color>
6590 specify the color to be used with the -frame option
6591 -monitor
6593 show progress indication
6594 -monochrome
6596 transform the image to black and white
6597 -name name an image
6599 -negate
6601 replace every pixel with its complementary color
6602 -noop NOOP (no option)
6604 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
6606 size and location of an image canvas
6607 +progress
6609 disable progress monitor and busy cursor
6610 -quality <value>
6612 JPEG/MIFF/PNG/TIFF compression level
6613 -raise <width>x<height>
6615 lighten or darken image edges
6616 -remote
6618 perform a X11 remote operation
6619 -roll {+-}<x>{+-}<y>
6621 roll an image vertically or horizontally
6622 -rotate <degrees>{<}{>}
6624 rotate the image
6625 -sample <geometry>
6627 scale image using pixel sampling
6628 -sampling-factor <horizontal_factor>x<vertical_factor>
6630 chroma subsampling factors
6631 -scenes <value-value>
6633 range of image scene numbers to read
6634 -set <attribute> <value>
6636 set an image attribute
6637 +set <attribute>
6639 unset an image attribute
6640 -segment <cluster threshold>x<smoothing threshold>
6642 segment an image
6643 -shared-memory
6645 use shared memory
6646 -sharpen <radius>{x<sigma>}
6648 sharpen the image
6649 -size <width>x<height>{+offset}
6651 width and height of the image
6652 -text-font <name>
6654 font for writing fixed-width text
6655 -texture <filename>
6657 name of texture to tile onto the image background
6658 -title <string>
6660 assign title to displayed image [animate, display, montage]
6661 -treedepth <value>
6663 tree depth for the color reduction algorithm
6664 -trim trim an image
6666 -type <type>
6668 the image type
6669 -update <seconds>
6671 detect when image file is modified and redisplay.
6672 -use-pixmap
6674 use the pixmap
6675 -verbose
6677 print detailed information about the image
6678 -version
6680 print GraphicsMagick version string
6681 -visual <type>
6683 animate images using this X visual type
6684 -window <id>
6686 make image the background of a window
6687 -window-group
6689 specify the window group
6690 -write <filename>
6692 write the image to a file [display]
6693 For a more detailed description of each option, see Options,
6695 above.
6696
6699 The effects of each button press is described below. Three buttons are
6700 required. If you have a two button mouse, button 1 and 3 are returned.
6701 Press ALT and button 3 to simulate button 2.
6702 1 Press this button to map or unmap the Command widget . See the
6704 next section for more information about the Command widget.
6705 2 Press and drag to define a region of the image to magnify.
6707 3 Press and drag to choose from a select set of display(1) com‐
6709 mands. This button behaves differently if the image being dis‐
6710 played is a visual image directory. Choose a particular tile of
6711 the directory and press this button and drag to select a command
6712 from a pop-up menu. Choose from these menu items:
6713 Open
6715 Next
6716 Former
6717 Delete
6718 Update
6719 If you choose Open, the image represented by the tile is dis‐
6722 played. To return to the visual image directory, choose Next
6723 from the Command widget (refer to Command Widget). Next and
6724 Former moves to the next or former image respectively. Choose
6725 Delete to delete a particular image tile. Finally, choose Update
6726 to synchronize all the image tiles with their respective images.
6727 See montage and miff for more details.
6728
6730 The Command widget lists a number of sub-menus and commands. They are
6731 File
6733 Open...
6735 Next
6736 Former
6737 Select...
6738 Save...
6739 Print...
6740 Delete...
6741 Canvas...
6742 Visual Directory...
6743 Quit
6744 Edit
6748 Undo
6750 Redo
6751 Cut
6752 Copy
6753 Paste
6754 View
6758 Half Size
6760 Original Size
6761 Double Size
6762 Resize...
6763 Apply
6764 Refresh
6765 Restore
6766 Transform
6770 Crop
6772 Chop
6773 Flop
6774 Flip
6775 Rotate Right
6776 Rotate Left
6777 Rotate...
6778 Shear...
6779 Roll...
6780 Trim Edges
6781 Enhance
6785 Hue...
6787 Saturation...
6788 Brightness...
6789 Gamma...
6790 Spiff...
6791 Dull
6792 Equalize
6793 Normalize
6794 Negate
6795 GRAYscale
6796 Quantize...
6797 Effects
6801 Despeckle
6803 Emboss
6804 Reduce Noise
6805 Add Noise
6806 Sharpen...
6807 Blur...
6808 Threshold...
6809 Edge Detect...
6810 Spread...
6811 Shade...
6812 Raise...
6813 Segment...
6814 F/X
6818 Solarize...
6820 Swirl...
6821 Implode...
6822 Wave...
6823 Oil Paint...
6824 Charcoal Draw...
6825 Image Edit
6829 Annotate...
6831 Draw...
6832 Color...
6833 Matte...
6834 Composite...
6835 Add Border...
6836 Add Frame...
6837 Comment...
6838 Launch...
6839 Region of Interest...
6840 Miscellany
6844 Image Info
6846 Zoom Image
6847 Show Preview...
6848 Show Histogram
6849 Show Matte
6850 Background...
6851 Slide Show
6852 Preferences...
6853 Help
6857 Overview
6859 Browse Documentation
6860 About Display
6861 Menu items with a indented triangle have a sub-menu. They are repre‐
6865 sented above as the indented items. To access a sub-menu item, move the
6866 pointer to the appropriate menu and press button 1 and drag. When you
6867 find the desired sub-menu item, release the button and the command is
6868 executed. Move the pointer away from the sub-menu if you decide not to
6869 execute a particular command.
6870
6872 Accelerators are one or two key presses that effect a particular com‐
6873 mand. The keyboard accelerators that display understands is:
6874 Ctl+O Press to load an image from a file.
6876 space Press to display the next image.
6877 If the image is a multi-paged document such as a PostScript document,
6879 you can skip ahead several pages by preceding this command with a num‐
6880 ber. For example to display the fourth page beyond the current page,
6881 press 4space.
6882 backspace Press to display the former image.
6884 If the image is a multi-paged document such as a PostScript document,
6886 you can skip behind several pages by preceding this command with a num‐
6887 ber. For example to display the fourth page preceding the current
6888 page, press 4n.
6889 Ctl-S Press to save the image to a file.
6891 Ctl-P Press to print the image to a
6892 PostScript printer.
6893 Ctl-D Press to delete an image file.
6894 Ctl-N Press to create a blank canvas.
6895 Ctl-Q Press to discard all images and exit program.
6896 Ctl+Z Press to undo last image transformation.
6897 Ctl+R Press to redo last image transformation.
6898 Ctl-X Press to cut a region of
6899 the image.
6900 Ctl-C Press to copy a region of
6901 the image.
6902 Ctl-V Press to paste a region to
6903 the image.
6904 < Press to halve the image size.
6905 . Press to return to the original image size.
6906 > Press to double the image size.
6907 % Press to resize the image to a width and height
6908 you specify.
6909 Cmd-A Press to make any image transformations
6910 permanent.
6911 By default, any image size transformations are
6912 applied to the original image to create the
6913 image displayed on the X server. However, the
6914 transformations are not permanent (i.e. the
6915 original image does not change size only the
6916 X image does). For example, if you press ">"
6917 the X image will appear to double in size, but
6918 the original image will in fact remain the same
6919 size. To force the original image to double in
6920 size, press ">" followed by "Cmd-A".
6921 @ Press to refresh the image window.
6922 C Press to crop the image.
6923 [ Press to chop the image.
6924 H Press to flop image in the horizontal direction.
6925 V Press to flip image in the vertical direction.
6926 / Press to rotate the image 90 degrees clockwise.
6927 \ Press to rotate the image 90 degrees
6928 counter-clockwise.
6929 * Press to rotate the image
6930 the number of degrees you specify.
6931 S Press to shear the image the number of degrees
6932 you specify.
6933 R Press to roll the image.
6934 T Press to trim the image edges.
6935 Shft-H Press to vary the color hue.
6936 Shft-S Press to vary the color saturation.
6937 Shft-L Press to vary the image brightness.
6938 Shft-G Press to gamma correct the image.
6939 Shft-C Press to spiff up the image contrast.
6940 Shft-Z Press to dull the image contrast.
6941 = Press to perform histogram equalization on
6942 the image.
6943 Shft-N Press to perform histogram normalization on
6944 the image.
6945 Shft-~ Press to negate the colors of the image.
6946 . Press to convert the image colors to gray.
6947 Shft-# Press to set the maximum number of unique
6948 colors in the image.
6949 F2 Press to reduce the speckles in an image.
6950 F2 Press to emboss an image.
6951 F4 Press to eliminate peak noise from an image.
6952 F5 Press to add noise to an image.
6953 F6 Press to sharpen an image.
6954 F7 Press to blur image an image.
6955 F8 Press to threshold the image.
6956 F9 Press to detect edges within an image.
6957 F10 Press to displace pixels by a random amount.
6958 F11 Press to shade the image using a distant light
6959 source.
6960 F12 Press to lighten or darken image edges to
6961 create a 3-D effect.
6962 F13 Press to segment the image by color.
6963 Meta-S Press to swirl image pixels about the center.
6964 Meta-I Press to implode image pixels about the center.
6965 Meta-W Press to alter an image along a sine wave.
6966 Meta-P Press to simulate an oil painting.
6967 Meta-C Press to simulate a charcoal drawing.
6968 Alt-X Press to composite the image
6969 with another.
6970 Alt-A Press to annotate the image with text.
6971 Alt-D Press to draw a line on the image.
6972 Alt-P Press to edit an image pixel color.
6973 Alt-M Press to edit the image matte information.
6974 Alt-X Press to composite the image with another.
6975 Alt-A Press to add a border to the image.
6976 Alt-F Press to add a ornamental frame to the image.
6977 Alt-Shft-! Press to add an image comment.
6978 Ctl-A Press to apply image processing techniques to a
6979 region of interest.
6980 Shft-? Press to display information about the image.
6981 Shft-+ Press to map the zoom image window.
6982 Shft-P Press to preview an image enhancement, effect,
6983 or f/x.
6984 F1 Press to display helpful information about
6985 the "display" utility.
6986 Find Press to browse documentation about
6987 GraphicsMagick.
6988 1-9 Press to change the level of magnification.
6989 Use the arrow keys to move the image one pixel up, down, left, or right
6991 within the magnify window. Be sure to first map the magnify window by
6992 pressing button 2.
6993 Press ALT and one of the arrow keys to trim off one pixel from any side
6995 of the image.
6996
6998 Display options can appear on the command line or in your X resource
6999 file. Options on the command line supersede values specified in your X
7000 resource file. See X(1) for more information on X resources.
7001 Most display options have a corresponding X resource. In addition, dis‐
7003 play uses the following X resources:
7004 background (class Background)
7006 Specifies the preferred color to use for the Image window back‐
7007 ground. The default is #ccc.
7008 borderColor (class BorderColor)
7010 Specifies the preferred color to use for the Image window bor‐
7011 der. The default is #ccc.
7012 borderWidth (class BorderWidth)
7014 Specifies the width in pixels of the image window border. The
7015 default is 2.
7016 browseCommand (class browseCommand)
7018 Specifies the name of the preferred browser when displaying
7019 GraphicsMagick documentation. The default is netscape %s.
7020 confirmExit (class ConfirmExit)
7022 Display pops up a dialog box to confirm exiting the program
7023 when exiting the program. Set this resource to False to exit
7024 without a confirmation.
7025 displayGamma (class DisplayGamma)
7027 Specifies the gamma of the X server. You can apply separate
7028 gamma values to the red, green, and blue channels of the image
7029 with a gamma value list delineated with slashes (i.e.
7030 1.7/2.3/1.2). The default is 2.2.
7031 displayWarnings (class DisplayWarnings)
7033 Display pops up a dialog box whenever a warning message occurs.
7034 Set this resource to False to ignore warning messages.
7035 font (class FontList)
7037 Specifies the name of the preferred font to use in normal for‐
7038 matted text. The default is 14 point Helvetica.
7039 font[1-9] (class Font[1-9])
7041 Specifies the name of the preferred font to use when annotating
7042 the image window with text. The default fonts are fixed, vari‐
7043 able, 5x8, 6x10, 7x13bold, 8x13bold, 9x15bold, 10x20, and 12x24.
7044 foreground (class Foreground)
7046 Specifies the preferred color to use for text within the image
7047 window. The default is black.
7048 gammaCorrect (class gammaCorrect)
7050 This resource, if true, will lighten or darken an image of
7051 known gamma to match the gamma of the display (see resource dis‐
7052 playGamma). The default is True.
7053 geometry (class Geometry)
7055 Specifies the preferred size and position of the image window.
7056 It is not necessarily obeyed by all window managers.
7057 Offsets, if present, are handled in X(1) style. A negative x
7059 offset is measured from the right edge of the screen to the
7060 right edge of the icon, and a negative y offset is measured from
7061 the bottom edge of the screen to the bottom edge of the icon.
7062 iconGeometry (class IconGeometry)
7064 Specifies the preferred size and position of the application
7065 when iconified. It is not necessarily obeyed by all window man‐
7066 agers.
7067 Offsets, if present, are handled in the same manner as in class
7069 Geometry.
7070 iconic (class Iconic)
7072 This resource indicates that you would prefer that the applica‐
7073 tion's windows initially not be visible as if the windows had be
7074 immediately iconified by you. Window managers may choose not to
7075 honor the application's request.
7076 magnify (class Magnify)
7078 specifies an integral factor by which the image should be en‐
7079 larged. The default is 3. This value only affects the magnifi‐
7080 cation window which is invoked with button number 3 after the
7081 image is displayed.
7082 matteColor (class MatteColor)
7084 Specify the color of windows. It is used for the backgrounds of
7085 windows, menus, and notices. A 3D effect is achieved by using
7086 highlight and shadow colors derived from this color. Default
7087 value: #697B8F.
7088 name (class Name)
7090 This resource specifies the name under which resources for the
7091 application should be found. This resource is useful in shell
7092 aliases to distinguish between invocations of an application,
7093 without resorting to creating links to alter the executable file
7094 name. The default is the application name.
7095 pen[1-9] (class Pen[1-9])
7097 Specifies the color of the preferred font to use when annotat‐
7098 ing the image window with text. The default colors are black,
7099 blue, green, cyan, gray, red, magenta, yellow, and white.
7100 printCommand (class PrintCommand)
7102 This command is executed whenever Print is issued. In general,
7103 it is the command to print PostScript to your printer. Default
7104 value: lp -c -s %i.
7105 sharedMemory (class SharedMemory)
7107 This resource specifies whether display should attempt use
7108 shared memory for pixmaps. GraphicsMagick must be compiled with
7109 shared memory support, and the display must support the MIT-SHM
7110 extension. Otherwise, this resource is ignored. The default is
7111 True.
7112 textFont (class textFont)
7114 Specifies the name of the preferred font to use in fixed (type‐
7115 writer style) formatted text. The default is 14 point Courier.
7116 title (class Title)
7118 This resource specifies the title to be used for the image win‐
7119 dow. This information is sometimes used by a window manager to
7120 provide a header identifying the window. The default is the im‐
7121 age file name.
7122 undoCache (class UndoCache)
7124 Specifies, in mega-bytes, the amount of memory in the undo edit
7125 cache. Each time you modify the image it is saved in the undo
7126 edit cache as long as memory is available. You can subsequently
7127 undo one or more of these transformations. The default is 16
7128 Megabytes.
7129 usePixmap (class UsePixmap)
7131 Images are maintained as a XImage by default. Set this resource
7132 to True to utilize a server Pixmap instead. This option is use‐
7133 ful if your image exceeds the dimensions of your server screen
7134 and you intend to pan the image. Panning is much faster with
7135 Pixmaps than with a XImage. Pixmaps are considered a precious
7136 resource, use them with discretion.
7137 To set the geometry of the Magnify or Pan or window, use the ge‐
7139 ometry resource. For example, to set the Pan window geometry to
7140 256x256, use:
7141 gm display.pan.geometry: 256x256
7143
7145 To select an image to display, choose Open of the File sub-menu from
7146 the Command widget. A file browser is displayed. To choose a particu‐
7147 lar image file, move the pointer to the filename and press any button.
7148 The filename is copied to the text window. Next, press Open or press
7149 the RETURN key. Alternatively, you can type the image file name di‐
7150 rectly into the text window. To descend directories, choose a directory
7151 name and press the button twice quickly. A scrollbar allows a large
7152 list of filenames to be moved through the viewing area if it exceeds
7153 the size of the list area.
7154 You can trim the list of file names by using shell globbing characters.
7156 For example, type *.jpg to list only files that end with .jpg.
7157 To select your image from the X server screen instead of from a file,
7159 Choose Grab of the Open widget.
7160
7162 To create a Visual Image Directory, choose Visual Directory of the File
7163 sub-menu from the Command widget . A file browser is displayed. To cre‐
7164 ate a Visual Image Directory from all the images in the current direc‐
7165 tory, press Directory or press the RETURN key. Alternatively, you can
7166 select a set of image names by using shell globbing characters. For ex‐
7167 ample, type *.jpg to include only files that end with .jpg. To descend
7168 directories, choose a directory name and press the button twice
7169 quickly. A scrollbar allows a large list of filenames to be moved
7170 through the viewing area if it exceeds the size of the list area.
7171 After you select a set of files, they are turned into thumbnails and
7173 tiled onto a single image. Now move the pointer to a particular thumb‐
7174 nail and press button 3 and drag. Finally, select Open. The image rep‐
7175 resented by the thumbnail is displayed at its full size. Choose Next
7176 from the File sub-menu of the Command widget to return to the Visual
7177 Image Directory.
7178
7180 Note that cut information for image window is not retained for col‐
7181 ormapped X server visuals (e.g. StaticColor, StaticColor, GRAYScale,
7182 PseudoColor). Correct cutting behavior may require a TrueColor or Di‐
7183 rectColor visual or a Standard Colormap.
7184 To begin, press choose Cut of the Edit sub-menu from the Command wid‐
7186 get. Alternatively, press F3 in the image window.
7187 A small window appears showing the location of the cursor in the image
7189 window. You are now in cut mode. In cut mode, the Command widget has
7190 these options:
7191 Help
7193 Dismiss
7194 To define a cut region, press button 1 and drag. The cut region is de‐
7197 fined by a highlighted rectangle that expands or contracts as it fol‐
7198 lows the pointer. Once you are satisfied with the cut region, release
7199 the button. You are now in rectify mode. In rectify mode, the Command
7200 widget has these options:
7201 Cut
7203 Help
7204 Dismiss
7205 You can make adjustments by moving the pointer to one of the cut rec‐
7208 tangle corners, pressing a button, and dragging. Finally, press Cut to
7209 commit your copy region. To exit without cutting the image, press Dis‐
7210 miss.
7211
7213 To begin, press choose Copy of the Edit sub-menu from the Command wid‐
7214 get. Alternatively, press F4 in the image window.
7215 A small window appears showing the location of the cursor in the image
7217 window. You are now in copy mode. In copy mode, the Command widget has
7218 these options:
7219 Help
7221 Dismiss
7222 To define a copy region, press button 1 and drag. The copy region is
7225 defined by a highlighted rectangle that expands or contracts as it fol‐
7226 lows the pointer. Once you are satisfied with the copy region, release
7227 the button. You are now in rectify mode. In rectify mode, the Command
7228 widget has these options:
7229 Copy
7231 Help
7232 Dismiss
7233 You can make adjustments by moving the pointer to one of the copy rec‐
7236 tangle corners, pressing a button, and dragging. Finally, press Copy to
7237 commit your copy region. To exit without copying the image, press Dis‐
7238 miss.
7239
7241 To begin, press choose Paste of the Edit sub-menu from the Command wid‐
7242 get. Alternatively, press F5 in the image window.
7243 A small window appears showing the location of the cursor in the image
7245 window. You are now in Paste mode. To exit immediately, press Dismiss.
7246 In Paste mode, the Command widget has these options:
7247 Operators
7249 over
7251 in
7252 out
7253 atop
7254 xor
7255 plus
7256 minus
7257 add
7258 subtract
7259 difference
7260 multiply
7261 bumpmap
7262 replace
7263 Help
7265 Dismiss
7266 Choose a composite operation from the Operators sub-menu of the Command
7269 widget. How each operator behaves is described below. image window is
7270 the image currently displayed on your X server and image is the image
7271 obtained with the File Browser widget.
7272 over The result is the union of the two image shapes, with image ob‐
7274 scuring image window in the region of overlap.
7275 in The result is simply image cut by the shape of image window.
7277 None of the image data of image window is in the result.
7278 out The resulting image is image with the shape of image window cut
7280 out.
7281 atop The result is the same shape as image window, with image ob‐
7283 scuring image window where the image shapes overlap. Note this
7284 differs from over because the portion of image outside image
7285 window's shape does not appear in the result.
7286 xor The result is the image data from both image and image window
7288 that is outside the overlap region. The overlap region is blank.
7289 plus The result is just the sum of the image data. Output values are
7291 cropped to the maximum value (no overflow). This operation is
7292 independent of the matte channels.
7293 minus The result of image - image window, with underflow cropped to
7295 zero. The matte channel is ignored (set to opaque, full cover‐
7296 age).
7297 add The result of image + image window, with overflow wrapping
7299 around (mod MaxRGB+1).
7300 subtract
7302 The result of image - image window, with underflow wrapping
7303 around (mod MaxRGB+1). The add and subtract operators can be
7304 used to perform reversible transformations.
7305 difference
7307 The result of abs(image - image window). This is useful for
7308 comparing two very similar images.
7309 multiply
7311 The result of image * image window. This is useful for the cre‐
7312 ation of drop-shadows.
7313 bumpmap
7315 The result of image window shaded by window.
7316 replace
7318 The resulting image is image window replaced with image. Here
7319 the matte information is ignored.
7320 The image compositor requires a matte, or alpha channel in the
7322 image for some operations. This extra channel usually defines a
7323 mask which represents a sort of a cookie-cutter for the image.
7324 This is the case when matte is 255 (full coverage) for pixels
7325 inside the shape, zero outside, and between zero and 255 on the
7326 boundary. If image does not have a matte channel, it is initial‐
7327 ized with 0 for any pixel matching in color to pixel location
7328 (0,0), otherwise 255. See Matte Editing for a method of defining
7329 a matte channel.
7330 Note that matte information for image window is not retained for
7332 colormapped X server visuals (e.g. StaticColor, StaticColor,
7333 GrayScale, PseudoColor). Correct compositing behavior may re‐
7334 quire a TrueColor or DirectColor visual or a Standard Colormap.
7335 Choosing a composite operator is optional. The default operator
7337 is replace. However, you must choose a location to composite
7338 your image and press button 1. Press and hold the button before
7339 releasing and an outline of the image will appear to help you
7340 identify your location.
7341 The actual colors of the pasted image is saved. However, the
7343 color that appears in image window may be different. For exam‐
7344 ple, on a monochrome screen image window will appear black or
7345 white even though your pasted image may have many colors. If the
7346 image is saved to a file it is written with the correct colors.
7347 To assure the correct colors are saved in the final image, any
7348 PseudoClass image is promoted to DirectClass. To force a Pseu‐
7349 doClass image to remain PseudoClass, use -colors.
7350
7352 To begin, press choose Crop of the Transform submenu from the Command
7353 widget. Alternatively, press C in the image window.
7354 A small window appears showing the location of the cursor in the image
7356 window. You are now in crop mode. In crop mode, the Command widget has
7357 these options:
7358 Help
7360 Dismiss
7361 To define a cropping region, press button 1 and drag. The cropping re‐
7364 gion is defined by a highlighted rectangle that expands or contracts as
7365 it follows the pointer. Once you are satisfied with the cropping re‐
7366 gion, release the button. You are now in rectify mode. In rectify mode,
7367 the Command widget has these options:
7368 Crop
7370 Help
7371 Dismiss
7372 You can make adjustments by moving the pointer to one of the cropping
7375 rectangle corners, pressing a button, and dragging. Finally, press Crop
7376 to commit your cropping region. To exit without cropping the image,
7377 press Dismiss.
7378
7380 An image is chopped interactively. There is no command line argument to
7381 chop an image. To begin, choose Chop of the Transform sub-menu from the
7382 Command widget. Alternatively, press [ in the Image window.
7383 You are now in Chop mode. To exit immediately, press Dismiss. In Chop
7385 mode, the Command widget has these options:
7386 Direction
7388 horizontal
7390 vertical
7391 Help
7393 Dismiss
7394 If the you choose the horizontal direction (this is the default), the
7397 area of the image between the two horizontal endpoints of the chop line
7398 is removed. Otherwise, the area of the image between the two vertical
7399 endpoints of the chop line is removed.
7400 Select a location within the image window to begin your chop, press and
7402 hold any button. Next, move the pointer to another location in the im‐
7403 age. As you move a line will connect the initial location and the
7404 pointer. When you release the button, the area within the image to chop
7405 is determined by which direction you choose from the Command widget.
7406 To cancel the image chopping, move the pointer back to the starting
7408 point of the line and release the button.
7409
7411 Press the / key to rotate the image 90 degrees or \ to rotate -90 de‐
7412 grees. To interactively choose the degree of rotation, choose Ro‐
7413 tate... of the Transform submenu from the Command Widget. Alterna‐
7414 tively, press * in the image window.
7415 A small horizontal line is drawn next to the pointer. You are now in
7417 rotate mode. To exit immediately, press Dismiss. In rotate mode, the
7418 Command widget has these options:
7419 Pixel Color
7421 black
7423 blue
7424 cyan
7425 green
7426 gray
7427 red
7428 magenta
7429 yellow
7430 white
7431 Browser...
7432 Direction
7434 horizontal
7436 vertical
7437 Help
7439 Dismiss
7440 Choose a background color from the Pixel Color sub-menu. Additional
7443 background colors can be specified with the color browser. You can
7444 change the menu colors by setting the X resources pen1 through pen9.
7445 If you choose the color browser and press Grab, you can select the
7447 background color by moving the pointer to the desired color on the
7448 screen and press any button.
7449 Choose a point in the image window and press this button and hold.
7451 Next, move the pointer to another location in the image. As you move a
7452 line connects the initial location and the pointer. When you release
7453 the button, the degree of image rotation is determined by the slope of
7454 the line you just drew. The slope is relative to the direction you
7455 choose from the Direction sub-menu of the Command widget.
7456 To cancel the image rotation, move the pointer back to the starting
7458 point of the line and release the button.
7459
7461 An image is annotated interactively. There is no command line argument
7462 to annotate an image. To begin, choose Annotate of the Image Edit sub-
7463 menu from the Command widget. Alternatively, press a in the image win‐
7464 dow.
7465 A small window appears showing the location of the cursor in the image
7467 window. You are now in annotate mode. To exit immediately, press Dis‐
7468 miss. In annotate mode, the Command widget has these options:
7469 Font Name
7472 fixed
7475 variable
7477 5x8
7479 6x10
7481 7x13bold
7483 8x13bold
7485 9x15bold
7487 10x20
7489 12x24
7491 Browser...
7493 Font Color
7496 black
7499 blue
7501 cyan
7503 green
7505 gray
7507 red
7509 magenta
7511 yellow
7513 white
7515 transparent
7517 Browser...
7519 Box Color
7522 black
7525 blue
7527 cyan
7529 green
7531 gray
7533 red
7535 magenta
7537 yellow
7539 white
7541 transparent
7543 Browser...
7545 Rotate Text
7548 -90
7551 -45
7553 -30
7555 0
7557 30
7559 45
7561 90
7563 180
7565 Dialog...
7567 Help
7570 Dismiss
7572 Choose a font name from the Font Name sub-menu. Additional font names
7575 can be specified with the font browser. You can change the menu names
7576 by setting the X resources font1 through font9.
7577 Choose a font color from the Font Color sub-menu. Additional font col‐
7579 ors can be specified with the color browser. You can change the menu
7580 colors by setting the X resources pen1 through pen9.
7581 If you select the color browser and press Grab, you can choose the font
7583 color by moving the pointer to the desired color on the screen and
7584 press any button.
7585 If you choose to rotate the text, choose Rotate Text from the menu and
7587 select an angle. Typically you will only want to rotate one line of
7588 text at a time. Depending on the angle you choose, subsequent lines may
7589 end up overwriting each other.
7590 Choosing a font and its color is optional. The default font is fixed
7592 and the default color is black. However, you must choose a location to
7593 begin entering text and press a button. An underscore character will
7594 appear at the location of the pointer. The cursor changes to a pencil
7595 to indicate you are in text mode. To exit immediately, press Dismiss.
7596 In text mode, any key presses will display the character at the loca‐
7598 tion of the underscore and advance the underscore cursor. Enter your
7599 text and once completed press Apply to finish your image annotation. To
7600 correct errors press BACK SPACE. To delete an entire line of text,
7601 press DELETE. Any text that exceeds the boundaries of the image window
7602 is automatically continued onto the next line.
7603 The actual color you request for the font is saved in the image. How‐
7605 ever, the color that appears in your Image window may be different. For
7606 example, on a monochrome screen the text will appear black or white
7607 even if you choose the color red as the font color. However, the image
7608 saved to a file with -write is written with red lettering. To assure
7609 the correct color text in the final image, any PseudoClass image is
7610 promoted to DirectClass (see miff(5)). To force a PseudoClass image to
7611 remain PseudoClass, use -colors.
7612
7614 An image composite is created interactively. There is no command line
7615 argument to composite an image. To begin, choose Composite of the Image
7616 Edit from the Command widget. Alternatively, press x in the Image win‐
7617 dow.
7618 First a popup window is displayed requesting you to enter an image
7620 name. Press Composite, Grab or type a file name. Press Cancel if you
7621 choose not to create a composite image. When you choose Grab, move the
7622 pointer to the desired window and press any button.
7623 If the Composite image does not have any matte information, you are in‐
7625 formed and the file browser is displayed again. Enter the name of a
7626 mask image. The image is typically grayscale and the same size as the
7627 composite image. If the image is not grayscale, it is converted to
7628 grayscale and the resulting intensities are used as matte information.
7629 A small window appears showing the location of the cursor in the image
7631 window. You are now in composite mode. To exit immediately, press Dis‐
7632 miss. In composite mode, the Command widget has these options:
7633 Operators
7636 over
7639 in
7641 out
7643 atop
7645 xor
7647 plus
7649 minus
7651 add
7653 subtract
7655 difference
7657 bumpmap
7659 replace
7661 Blend
7664 Displace
7666 Help
7668 Dismiss
7670 Choose a composite operation from the Operators sub-menu of the Command
7673 widget. How each operator behaves is described below. image window is
7674 the image currently displayed on your X server and image is the image
7675 obtained
7676 over The result is the union of the two image shapes, with image ob‐
7678 scuring image window in the region of overlap.
7679 in The result is simply image cut by the shape of image window.
7681 None of the image data of image window is in the result.
7682 out The resulting image is image with the shape of image window cut
7684 out.
7685 atop The result is the same shape as image window, with image ob‐
7687 scuring image window where the image shapes overlap. Note this
7688 differs from over because the portion of image outside image
7689 window's shape does not appear in the result.
7690 xor The result is the image data from both image and image window
7692 that is outside the overlap region. The overlap region is blank.
7693 plus The result is just the sum of the image data. Output values are
7695 cropped to 255 (no overflow). This operation is independent of
7696 the matte channels.
7697 minus The result of image - image window, with underflow cropped to
7699 zero. The matte channel is ignored (set to 255, full coverage).
7700 add The result of image + image window, with overflow wrapping
7702 around (mod 256).
7703 subtract
7705 The result of image - image window, with underflow wrapping
7706 around (mod 256). The add and subtract operators can be used to
7707 perform reversible transformations.
7708 difference
7710 The result of abs(image - image window). This is useful for
7711 comparing two very similar images.
7712 bumpmap
7714 The result of image window shaded by window.
7715 replace
7717 The resulting image is image window replaced with image. Here
7718 the matte information is ignored.
7719 The image compositor requires a matte, or alpha channel in the
7721 image for some operations. This extra channel usually defines a
7722 mask which represents a sort of a cookie-cutter for the image.
7723 This is the case when matte is 255 (full coverage) for pixels
7724 inside the shape, zero outside, and between zero and 255 on the
7725 boundary. If image does not have a matte channel, it is initial‐
7726 ized with 0 for any pixel matching in color to pixel location
7727 (0,0), otherwise 255. See Matte Editing for a method of defining
7728 a matte channel.
7729 If you choose blend, the composite operator becomes over. The
7731 image matte channel percent transparency is initialized to fac‐
7732 tor. The image window is initialized to (100-factor). Where
7733 factor is the value you specify in the Dialog widget.
7734 Displace shifts the image pixels as defined by a displacement
7736 map. With this option, image is used as a displacement map.
7737 Black, within the displacement map, is a maximum positive dis‐
7738 placement. White is a maximum negative displacement and middle
7739 gray is neutral. The displacement is scaled to determine the
7740 pixel shift. By default, the displacement applies in both the
7741 horizontal and vertical directions. However, if you specify
7742 mask, image is the horizontal X displacement and mask the verti‐
7743 cal Y displacement.
7744 Note that matte information for image window is not retained for
7746 colormapped X server visuals (e.g. StaticColor, StaticColor,
7747 GrayScale, PseudoColor). Correct compositing behavior may re‐
7748 quire a TrueColor or DirectColor visual or a Standard Colormap.
7749 Choosing a composite operator is optional. The default operator
7751 is replace. However, you must choose a location to composite
7752 your image and press button 1. Press and hold the button before
7753 releasing and an outline of the image will appear to help you
7754 identify your location.
7755 The actual colors of the composite image is saved. However, the
7757 color that appears in image window may be different. For exam‐
7758 ple, on a monochrome screen Image window will appear black or
7759 white even though your composited image may have many colors. If
7760 the image is saved to a file it is written with the correct col‐
7761 ors. To assure the correct colors are saved in the final image,
7762 any PseudoClass image is promoted to DirectClass (see miff). To
7763 force a PseudoClass image to remain PseudoClass, use -colors.
7764
7766 Changing the the color of a set of pixels is performed interactively.
7767 There is no command line argument to edit a pixel. To begin, choose
7768 Color from the Image Edit submenu of the Command widget. Alterna‐
7769 tively, press c in the image window.
7770 A small window appears showing the location of the cursor in the image
7772 window. You are now in color edit mode. To exit immediately, press Dis‐
7773 miss. In color edit mode, the Command widget has these options:
7774 Method
7777 point
7780 replace
7782 floodfill
7784 reset
7786 Pixel Color
7789 black
7792 blue
7794 cyan
7796 green
7798 gray
7800 red
7802 magenta
7804 yellow
7806 white
7808 Browser...
7810 Border Color
7813 black
7816 blue
7818 cyan
7820 green
7822 gray
7824 red
7826 magenta
7828 yellow
7830 white
7832 Browser...
7834 Fuzz
7837 0
7840 2
7842 4
7844 8
7846 16
7848 Dialog...
7849 Undo
7852 Help
7854 Dismiss
7856 Choose a color editing method from the Method sub-menu of the Command
7859 widget. The point method recolors any pixel selected with the pointer
7860 unless the button is released. The replace method recolors any pixel
7861 that matches the color of the pixel you select with a button press.
7862 Floodfill recolors any pixel that matches the color of the pixel you
7863 select with a button press and is a neighbor. Whereas filltoborder
7864 changes the matte value of any neighbor pixel that is not the border
7865 color. Finally reset changes the entire image to the designated color.
7866 Next, choose a pixel color from the Pixel Color sub-menu. Additional
7868 pixel colors can be specified with the color browser. You can change
7869 the menu colors by setting the X resources pen1 through pen9.
7870 Now press button 1 to select a pixel within the Image window to change
7872 its color. Additional pixels may be recolored as prescribed by the
7873 method you choose. additional pixels by increasing the Delta value.
7874 If the Magnify widget is mapped, it can be helpful in positioning your
7876 pointer within the image (refer to button 2). Alternatively you can se‐
7877 lect a pixel to recolor from within the Magnify widget. Move the
7878 pointer to the Magnify widget and position the pixel with the cursor
7879 control keys. Finally, press a button to recolor the selected pixel (or
7880 pixels).
7881 The actual color you request for the pixels is saved in the image. How‐
7883 ever, the color that appears in your Image window may be different. For
7884 example, on a monochrome screen the pixel will appear black or white
7885 even if you choose the color red as the pixel color. However, the image
7886 saved to a file with -write is written with red pixels. To assure the
7887 correct color text in the final image, any PseudoClass image is pro‐
7888 moted to DirectClass To force a PseudoClass image to remain Pseudo‐
7889 Class, use -colors.
7890
7892 Matte information within an image is useful for some operations such as
7893 image compositing. This extra channel usually defines a mask which rep‐
7894 resents a sort of a cookie-cutter for the image. This is the case when
7895 matte is 255 (full coverage) for pixels inside the shape, zero outside,
7896 and between zero and 255 on the boundary.
7897 Setting the matte information in an image is done interactively. There
7899 is no command line argument to edit a pixel. To begin, and choose Matte
7900 of the Image Edit sub-menu from the Command widget.
7901 Alternatively, press m in the image window.
7903 A small window appears showing the location of the cursor in the image
7905 window. You are now in matte edit mode. To exit immediately, press Dis‐
7906 miss. In matte edit mode, the Command widget has these options:
7907 Method
7910 point
7913 replace
7915 floodfill
7917 reset
7919 Border Color
7922 black
7925 blue
7927 cyan
7929 green
7931 gray
7933 red
7935 magenta
7937 yellow
7939 white
7941 Browser...
7943 Fuzz
7946 0
7949 2
7951 4
7953 8
7955 16
7957 Dialog...
7958 Matte
7961 Undo
7963 Help
7965 Dismiss
7967 Choose a matte editing method from the Method sub-menu of the Command
7969 widget. The point method changes the matte value of the any pixel se‐
7970 lected with the pointer until the button is released. The replace
7971 method changes the matte value of any pixel that matches the color of
7972 the pixel you select with a button press. Floodfill changes the matte
7973 value of any pixel that matches the color of the pixel you select with
7974 a button press and is a neighbor. Whereas filltoborder recolors any
7975 neighbor pixel that is not the border color. Finally reset changes the
7976 entire image to the designated matte value. Choose Matte Value and a
7977 dialog appears requesting a matte value. Enter a value between 0 and
7978 255. This value is assigned as the matte value of the selected pixel or
7979 pixels. Now, press any button to select a pixel within the Image win‐
7980 dow to change its matte value. You can change the matte value of addi‐
7981 tional pixels by increasing the Delta value. The Delta value is first
7982 added then subtracted from the red, green, and blue of the target
7983 color. Any pixels within the range also have their matte value updated.
7984 If the Magnify widget is mapped, it can be helpful in positioning your
7985 pointer within the image (refer to button 2). Alternatively you can se‐
7986 lect a pixel to change the matte value from within the Magnify widget.
7987 Move the pointer to the Magnify widget and position the pixel with the
7988 cursor control keys. Finally, press a button to change the matte value
7989 of the selected pixel (or pixels). Matte information is only valid in
7990 a DirectClass image. Therefore, any PseudoClass image is promoted to
7991 DirectClass. Note that matte information for PseudoClass is not re‐
7992 tained for colormapped X server visuals (e.g. StaticColor, StaticColor,
7993 GrayScale, PseudoColor) unless you immediately save your image to a
7994 file (refer to Write). Correct matte editing behavior may require a
7995 TrueColor or DirectColor visual or a Standard Colormap.
7996
7998 An image is drawn upon interactively. There is no command line argument
7999 to draw on an image. To begin, choose Draw of the Image Edit sub-menu
8000 from the Command widget. Alternatively, press d in the image window.
8001 The cursor changes to a crosshair to indicate you are in draw mode. To
8003 exit immediately, press Dismiss. In draw mode, the Command widget has
8004 these options:
8005 Primitive
8008 point
8011 line
8013 rectangle
8015 fill rectangle
8017 circle
8019 fill circle
8021 ellipse
8023 fill ellipse
8025 polygon
8027 fill polygon
8029 Color
8032 black
8035 blue
8037 cyan
8039 green
8041 gray
8043 red
8045 magenta
8047 yellow
8049 white
8051 transparent
8053 Browser...
8055 Stipple
8058 Brick
8061 Diagonal
8063 Scales
8065 Vertical
8067 Wavy
8069 Translucent
8071 Opaque
8073 Open...
8075 Width
8078 1
8081 2
8083 4
8085 8
8087 16
8089 Dialog...
8090 Undo
8093 Help
8095 Dismiss
8097 Choose a drawing primitive from the Primitive sub-menu.
8099 Next, choose a color from the Color sub-menu. Additional colors can be
8101 specified with the color browser. You can change the menu colors by
8102 setting the X resources pen1 through pen9. The transparent color up‐
8103 dates the image matte channel and is useful for image compositing.
8104 If you choose the color browser and press Grab, you can select the
8106 primitive color by moving the pointer to the desired color on the
8107 screen and press any button. The transparent color updates the image
8108 matte channel and is useful for image compositing.
8109 Choose a stipple, if appropriate, from the Stipple sub-menu. Additional
8111 stipples can be specified with the file browser. Stipples obtained from
8112 the file browser must be on disk in the X11 bitmap format.
8113 Choose a line width, if appropriate, from the Width sub-menu. To choose
8115 a specific width select the Dialog widget.
8116 Choose a point in the image window and press button 1 and hold. Next,
8118 move the pointer to another location in the image. As you move, a line
8119 connects the initial location and the pointer. When you release the
8120 button, the image is updated with the primitive you just drew. For
8121 polygons, the image is updated when you press and release the button
8122 without moving the pointer.
8123 To cancel image drawing, move the pointer back to the starting point of
8125 the line and release the button.
8126
8128 To begin, press choose Region of Interest of the Pixel Transform sub-
8129 menu from the Command widget. Alternatively, press R in the image win‐
8130 dow.
8131 A small window appears showing the location of the cursor in the image
8133 window. You are now in region of interest mode. In region of interest
8134 mode, the Command widget has these options:
8135 Help
8138 Dismiss
8140 To define a region of interest, press button 1 and drag. The region of
8143 interest is defined by a highlighted rectangle that expands or con‐
8144 tracts as it follows the pointer. Once you are satisfied with the re‐
8145 gion of interest, release the button. You are now in apply mode. In ap‐
8146 ply mode the Command widget has these options:
8147 File
8150 Save...
8153 Print...
8155 Edit
8158 Undo
8161 Redo
8163 Transform
8166 Flip
8169 Flop
8171 Rotate Right
8173 Rotate Left
8175 Enhance
8178 Hue...
8181 Saturation...
8183 Brightness...
8185 Gamma...
8187 Spiff
8189 Dull
8191 Equalize
8193 Normalize
8195 Negate
8197 GRAYscale
8199 Quantize...
8201 Effects
8204 Despeckle
8207 Emboss
8209 Reduce Noise
8211 Add Noise
8213 Sharpen...
8215 Blur...
8217 Threshold...
8219 Edge Detect...
8221 Spread...
8223 Shade...
8225 Raise...
8227 Segment...
8229 F/X
8234 Solarize...
8237 Swirl...
8239 Implode...
8241 Wave...
8243 Oil Paint
8245 Charcoal Draw...
8247 Miscellany
8252 Image Info
8255 Zoom Image
8257 Show Preview...
8259 Show Histogram
8261 Show Matte
8263 Help
8266 Dismiss
8268 You can make adjustments to the region of interest by moving the
8271 pointer to one of the rectangle corners, pressing a button, and drag‐
8272 ging. Finally, choose an image processing technique from the Command
8273 widget. You can choose more than one image processing technique to ap‐
8274 ply to an area. Alternatively, you can move the region of interest be‐
8275 fore applying another image processing technique. To exit, press Dis‐
8276 miss.
8277
8279 When an image exceeds the width or height of the X server screen, dis‐
8280 play maps a small panning icon. The rectangle within the panning icon
8281 shows the area that is currently displayed in the the image window. To
8282 pan about the image, press any button and drag the pointer within the
8283 panning icon. The pan rectangle moves with the pointer and the image
8284 window is updated to reflect the location of the rectangle within the
8285 panning icon. When you have selected the area of the image you wish to
8286 view, release the button.
8287 Use the arrow keys to pan the image one pixel up, down, left, or right
8289 within the image window.
8290 The panning icon is withdrawn if the image becomes smaller than the di‐
8292 mensions of the X server screen.
8293
8295 Preferences affect the default behavior of display(1). The preferences
8296 are either true or false and are stored in your home directory as .dis‐
8297 playrc:
8298 display image centered on a backdrop"
8300 This backdrop covers the entire workstation screen and is
8303 useful for hiding other X window activity while viewing
8304 the image. The color of the backdrop is specified as the
8305 background color. Refer to X Resources for details.
8306 confirm on program exit"
8307 Ask for a confirmation before exiting the display(1) pro‐
8310 gram.
8311 correct image for display gamma"
8312 If the image has a known gamma, the gamma is corrected to
8315 match that of the X server (see the X Resource dis‐
8316 playGamma).
8317 display warning messages"
8318 Display any warning messages.
8321 apply Floyd/Steinberg error diffusion to image"
8322 The basic strategy of dithering is to trade intensity res‐
8325 olution for spatial resolution by averaging the intensi‐
8326 ties of several neighboring pixels. Images which suffer
8327 from severe contouring when reducing colors can be im‐
8328 proved with this preference.
8329 use a shared colormap for colormapped X visuals"
8330 This option only applies when the default X server visual
8333 is PseudoColor or GRAYScale. Refer to -visual for more de‐
8334 tails. By default, a shared colormap is allocated. The im‐
8335 age shares colors with other X clients. Some image colors
8336 could be approximated, therefore your image may look very
8337 different than intended. Otherwise the image colors appear
8338 exactly as they are defined. However, other clients may go
8339 technicolor when the image colormap is installed.
8340 display images as an X server pixmap"
8341 Images are maintained as a XImage by default. Set this re‐
8344 source to True to utilize a server Pixmap instead. This
8345 option is useful if your image exceeds the dimensions of
8346 your server screen and you intend to pan the image. Pan‐
8347 ning is much faster with Pixmaps than with a XImage.
8348 Pixmaps are considered a precious resource, use them with
8349 discretion.
8350 GM IDENTIFY
8354 Identify describes the format and characteristics of one or more
8356 image files as internally supported by the software. It will
8357 also report if an image is incomplete or corrupt. The informa‐
8358 tion displayed includes the scene number, the file name, the
8359 width and height of the image, whether the image is colormapped
8360 or not, the number of colors in the image, the number of bytes
8361 in the image, the format of the image (JPEG, PNM, etc.), and fi‐
8362 nally the number of seconds in both user time and elapsed time
8363 it took to read and process the image. If -verbose or +ping are
8364 provided as an option, the pixel read rate is also displayed. An
8365 example line output from identify follows:
8366 images/aquarium.miff 640x480 PseudoClass 256c
8368 308135b MIFF 0.000u 0:01
8369 If -verbose is set, expect additional output including any image
8371 comment:
8372 Image: images/aquarium.miff
8375 class: PseudoClass
8376 colors: 256
8377 signature: eb5dca81dd93ae7e6ffae99a527eb5dca8...
8378 matte: False
8379 geometry: 640x480
8380 depth: 8
8381 bytes: 308135
8382 format: MIFF
8383 comments:
8384 Imported from MTV raster image: aquarium.mtv
8385 For some formats, additional format-specific information about
8387 the file will be written if the -debug coder or -debug all op‐
8388 tion is used.
8389
8391 Options are processed in command line order. Any option you specify on
8392 the command line remains in effect for the set of images immediately
8393 following, until the set is terminated by the appearance of any option
8394 or -noop.
8395 For a more detailed description of each option, see Options, above.
8397 -authenticate <string>
8400 decrypt image with this password
8401 -debug <events>
8403 enable debug printout
8404 -define <key>{=<value>},...
8406 add coder/decoder specific options
8407 -density <width>x<height>
8409 horizontal and vertical resolution in pixels of the image
8410 -depth <value>
8412 depth of the image
8413 -format <string>
8415 output formatted image characteristics
8416 -help print usage instructions
8418 -interlace <type>
8420 the type of interlacing scheme
8421 -limit <type> <value>
8423 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
8424 resource limit
8425 -log <string>
8427 Specify format for debug log
8428 -ping efficiently determine image characteristics
8430 -sampling-factor <horizontal_factor>x<vertical_factor>
8432 chroma subsampling factors
8433 -size <width>x<height>{+offset}
8435 width and height of the image
8436 -verbose
8438 print detailed information about the image
8439 -version
8441 print GraphicsMagick version string
8442 For a more detailed description of each option, see Options,
8444 above.
8445
8448 Import reads an image from any visible window on an X server and out‐
8449 puts it as an image file. You can capture a single window, the entire
8450 screen, or any rectangular portion of the screen. Use display for re‐
8451 display, printing, editing, formatting, archiving, image processing,
8452 etc. of the captured image.
8453 The target window can be specified by id, name, or may be selected by
8455 clicking the mouse in the desired window. If you press a button and
8456 then drag, a rectangle will form which expands and contracts as the
8457 mouse moves. To save the portion of the screen defined by the rectan‐
8458 gle, just release the button. The keyboard bell is rung once at the be‐
8459 ginning of the screen capture and twice when it completes.
8460
8462 To select an X window or an area of the screen with the mouse and save
8463 it in the MIFF image format to a file entitled window.miff, use:
8464 gm import window.miff
8466 To select an X window or an area of the screen with the mouse and save
8468 it in the Encapsulated PostScript format to include in another docu‐
8469 ment, use:
8470 gm import figure.eps
8472 To capture the entire X server screen in the JPEG image format in a
8474 file entitled root.jpeg, without using the mouse, use:
8475 gm import -window root root.jpeg
8477 To capture the 512x256 area at the upper right corner of the X server
8479 screen in the PNG image format in a well-compressed file entitled cor‐
8480 ner.png, without using the mouse, use:
8481 gm import -window root -crop 512x256-0+0 -quality 90
8483 corner.png
8484
8486 Options are processed in command line order. Any option you specify on
8487 the command line remains in effect until it is explicitly changed by
8488 specifying the option again with a different effect.
8489 Import options can appear on the command line or in your X resources
8491 file. See X(1). Options on the command line supersede values specified
8492 in your X resources file.
8493 For a more detailed description of each option, see Options, above.
8495 -bordercolor <color>
8498 the border color
8499 -colors <value>
8501 preferred number of colors in the image
8502 -colorspace <value>
8504 the type of colorspace
8505 -comment <string>
8507 annotate an image with a comment
8508 -crop <width>x<height>{+-}<x>{+-}<y>{%}
8510 preferred size and location of the cropped image
8511 -debug <events>
8513 enable debug printout
8514 -define <key>{=<value>},...
8516 add coder/decoder specific options
8517 -delay <1/100ths of a second>
8519 display the next image after pausing
8520 -density <width>x<height>
8522 horizontal and vertical resolution in pixels of the image
8523 -depth <value>
8525 depth of the image
8526 -descend
8528 obtain image by descending window hierarchy
8529 -display <host:display[.screen]>
8531 specifies the X server to contact
8532 -dispose <method>
8534 GIF disposal method
8535 -dither
8537 apply Floyd/Steinberg error diffusion to the image
8538 -encoding <type>
8540 specify the text encoding
8541 -endian <type>
8543 specify endianness (MSB, LSB, or Native) of image
8544 -frame include the X window frame in the imported image
8546 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
8548 Specify dimension, offset, and resize options.
8549 -help print usage instructions
8551 -interlace <type>
8553 the type of interlacing scheme
8554 -label <name>
8556 assign a label to an image
8557 -limit <type> <value>
8559 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
8560 resource limit
8561 -log <string>
8563 Specify format for debug log
8564 -monitor
8566 show progress indication
8567 -monochrome
8569 transform the image to black and white
8570 -negate
8572 replace every pixel with its complementary color
8573 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
8575 size and location of an image canvas
8576 -pause <seconds>
8578 pause between snapshots [import]
8579 -ping efficiently determine image characteristics
8581 -pointsize <value>
8583 pointsize of the PostScript, X11, or TrueType font
8584 -quality <value>
8586 JPEG/MIFF/PNG/TIFF compression level
8587 -resize <width>x<height>{%}{@}{!}{<}{>}
8589 resize an image
8590 -rotate <degrees>{<}{>}
8592 rotate the image
8593 -sampling-factor <horizontal_factor>x<vertical_factor>
8595 chroma subsampling factors
8596 -scene <value>
8598 set scene number
8599 -screen
8601 specify the screen to capture
8602 -set <attribute> <value>
8604 set an image attribute
8605 +set <attribute>
8607 unset an image attribute
8608 -silent
8610 operate silently
8611 -snaps <value>
8613 number of screen snapshots
8614 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
8616 resize an image (quickly)
8617 -transparent <color>
8619 make this color transparent within the image
8620 -trim trim an image
8622 -verbose
8624 print detailed information about the image
8625 -version
8627 print GraphicsMagick version string
8628 For a more detailed description of each option, see Options,
8630 above.
8631
8634 Mogrify transforms an image or a sequence of images. These transforms
8635 include image scaling, image rotation, color reduction, and others.
8636 Each transmogrified image overwrites the corresponding original image,
8637 unless an option such as -format causes the output filename to be dif‐
8638 ferent from the input filename.
8639 The graphics formats supported by mogrify are listed in GraphicsMag‐
8641 ick(1).
8642
8644 To convert all the TIFF files in a particular directory to JPEG, use:
8645 gm mogrify -format jpeg *.tiff
8647 To convert a directory full of JPEG images to thumbnails, use:
8649 gm mogrify -size 120x120 *.jpg -resize 120x120 +profile "*"
8651 In this example, '-size 120x120' gives a hint to the JPEG decoder that
8653 the images are going to be downscaled to 120x120, allowing it to run
8654 faster by avoiding returning full-resolution images to GraphicsMagick
8655 for the subsequent resizing operation. The ´-resize 120x120' specifies
8656 the desired dimensions of the output images. It will be scaled so its
8657 largest dimension is 120 pixels. The ´+profile "*"' removes any ICM,
8658 EXIF, IPTC, or other profiles that might be present in the input and
8659 aren't needed in the thumbnails.
8660 To scale an image of a cockatoo to exactly 640 pixels in width and 480
8662 pixels in height, use:
8663 gm mogrify -resize 640x480! cockatoo.miff
8665
8667 Options are processed in command line order. Any option you specify on
8668 the command line remains in effect for the set of images that follows,
8669 until the set is terminated by the appearance of any option or -noop.
8670 For a more detailed description of each option, see Options, above.
8672 -affine <matrix>
8675 drawing transform matrix
8676 -antialias
8678 remove pixel aliasing
8679 -asc-cdl <spec>
8681 apply ASC CDL color transform
8682 -authenticate <string>
8684 decrypt image with this password
8685 -auto-orient
8687 orient (rotate) image so it is upright
8688 -background <color>
8690 the background color
8691 -black-threshold red[,green][,blue][,opacity]
8693 pixels below the threshold become black
8694 -blue-primary <x>,<y>
8696 blue chromaticity primary point
8697 -blur <radius>{x<sigma>}
8699 blur the image with a Gaussian operator
8700 -border <width>x<height>
8702 surround the image with a border of color
8703 -bordercolor <color>
8705 the border color
8706 -channel <type>
8708 the type of channel
8709 -charcoal <factor>
8711 simulate a charcoal drawing
8712 -colorize <value>
8714 colorize the image with the pen color
8715 -colors <value>
8717 preferred number of colors in the image
8718 -colorspace <value>
8720 the type of colorspace
8721 -comment <string>
8723 annotate an image with a comment
8724 -compose <operator>
8726 the type of image composition
8727 -compress <type>
8729 the type of image compression
8730 -contrast
8732 enhance or reduce the image contrast
8733 -convolve <kernel>
8735 convolve image with the specified convolution kernel
8736 -create-directories
8738 create output directory if required
8739 -crop <width>x<height>{+-}<x>{+-}<y>{%}
8741 preferred size and location of the cropped image
8742 -cycle <amount>
8744 displace image colormap by amount
8745 -debug <events>
8747 enable debug printout
8748 -define <key>{=<value>},...
8750 add coder/decoder specific options
8751 -delay <1/100ths of a second>
8753 display the next image after pausing
8754 -density <width>x<height>
8756 horizontal and vertical resolution in pixels of the image
8757 -depth <value>
8759 depth of the image
8760 -despeckle
8762 reduce the speckles within an image
8763 -display <host:display[.screen]>
8765 specifies the X server to contact
8766 -dispose <method>
8768 GIF disposal method
8769 -dither
8771 apply Floyd/Steinberg error diffusion to the image
8772 -draw <string>
8774 annotate an image with one or more graphic primitives
8775 -edge <radius>
8777 detect edges within an image
8778 -emboss <radius>
8780 emboss an image
8781 -encoding <type>
8783 specify the text encoding
8784 -endian <type>
8786 specify endianness (MSB, LSB, or Native) of image
8787 -enhance
8789 apply a digital filter to enhance a noisy image
8790 -equalize
8792 perform histogram equalization to the image
8793 -extent <width>x<height>{+-}<x>{+-}<y>
8795 composite image on background color canvas image
8796 -fill <color>
8798 color to use when filling a graphic primitive
8799 -filter <type>
8801 use this type of filter when resizing an image
8802 -flip create a "mirror image"
8804 -flop create a "mirror image"
8806 -font <name>
8808 use this font when annotating the image with text
8809 -format <type>
8811 the image format type
8812 -frame <width>x<height>+<outer bevel width>+<inner bevel width>
8814 surround the image with an ornamental border
8815 -fuzz <distance>{%}
8817 colors within this Euclidean distance are considered equal
8818 -gamma <value>
8820 level of gamma correction
8821 -gaussian <radius>{x<sigma>}
8823 blur the image with a Gaussian operator
8824 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
8826 Specify dimension, offset, and resize options.
8827 -gravity <type>
8829 direction primitive gravitates to when annotating the image.
8830 -green-primary <x>,<y>
8832 green chromaticity primary point
8833 -hald-clut <clut>
8835 apply a Hald CLUT to the image
8836 -help print usage instructions
8838 -implode <factor>
8840 implode image pixels about the center
8841 -interlace <type>
8843 the type of interlacing scheme
8844 -label <name>
8846 assign a label to an image
8847 -lat <width>x<height>{+-}<offset>{%}
8849 perform local adaptive thresholding
8850 -level <black_point>{,<gamma>}{,<white_point>}{%}
8852 adjust the level of image contrast
8853 -limit <type> <value>
8855 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
8856 resource limit
8857 -linewidth
8859 the line width for subsequent draw operations
8860 -list <type>
8862 the type of list
8863 -log <string>
8865 Specify format for debug log
8866 -loop <iterations>
8868 add Netscape loop extension to your GIF animation
8869 -magnify
8871 magnify the image
8872 -map <filename>
8874 choose a particular set of colors from this image
8875 -mask <filename>
8877 Specify a clipping mask
8878 -matte store matte channel if the image has one
8880 -mattecolor <color>
8882 specify the color to be used with the -frame option
8883 -median <radius>
8885 apply a median filter to the image
8886 -minify <factor>
8888 minify the image
8889 -modulate brightness[,saturation[,hue]]
8891 vary the brightness, saturation, and hue of an image
8892 -monitor
8894 show progress indication
8895 -monochrome
8897 transform the image to black and white
8898 -motion-blur <radius>{x<sigma>}{+angle}
8900 Simulate motion blur
8901 -negate
8903 replace every pixel with its complementary color
8904 -noise <radius|type>
8906 add or reduce noise in an image
8907 -noop NOOP (no option)
8909 -normalize
8911 transform image to span the full range of color values
8912 -opaque <color>
8914 change this color to the pen color within the image
8915 -operator channel operator rvalue[%]
8917 apply a mathematical, bitwise, or value operator to an image
8918 channel
8919 -ordered-dither <channeltype> <NxN>
8921 ordered dither the image
8922 -output-directory <directory>
8924 output files to directory
8925 -orient <orientation>
8927 Set the image orientation attribute
8928 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
8930 size and location of an image canvas
8931 -paint <radius>
8933 simulate an oil painting
8934 -pen <color>
8936 (This option has been replaced by the -fill option)
8937 -pointsize <value>
8939 pointsize of the PostScript, X11, or TrueType font
8940 -profile <filename>
8942 add ICM, IPTC, or generic profile to image
8943 -preserve-timestamp
8945 preserve the original timestamps of the file
8946 -quality <value>
8948 JPEG/MIFF/PNG/TIFF compression level
8949 -raise <width>x<height>
8951 lighten or darken image edges
8952 -random-threshold <channeltype> <LOWxHIGH>
8954 random threshold the image
8955 -recolor <matrix>
8957 apply a color translation matrix to image channels
8958 -red-primary <x>,<y>
8960 red chromaticity primary point
8961 -region <width>x<height>{+-}<x>{+-}<y>
8963 apply options to a portion of the image
8964 -render
8966 render vector operations
8967 -repage <width>x<height>+xoff+yoff[!]
8969 Adjust image page offsets
8970 -resample <horizontal>x<vertical>
8972 Resample image to specified horizontal and vertical resolution
8973 -resize <width>x<height>{%}{@}{!}{<}{>}
8975 resize an image
8976 -roll {+-}<x>{+-}<y>
8978 roll an image vertically or horizontally
8979 -rotate <degrees>{<}{>}
8981 rotate the image
8982 -sample <geometry>
8984 scale image using pixel sampling
8985 -sampling-factor <horizontal_factor>x<vertical_factor>
8987 chroma subsampling factors
8988 -scale <geometry>
8990 scale the image.
8991 -scene <value>
8993 set scene number
8994 -set <attribute> <value>
8996 set an image attribute
8997 +set <attribute>
8999 unset an image attribute
9000 -segment <cluster threshold>x<smoothing threshold>
9002 segment an image
9003 -shade <azimuth>x<elevation>
9005 shade the image using a distant light source
9006 -sharpen <radius>{x<sigma>}
9008 sharpen the image
9009 -shave <width>x<height>{%}
9011 shave pixels from the image edges
9012 -shear <x degrees>x<y degrees>
9014 shear the image along the X or Y axis
9015 -size <width>x<height>{+offset}
9017 width and height of the image
9018 -solarize <factor>
9020 negate all pixels above the threshold level
9021 -spread <amount>
9023 displace image pixels by a random amount
9024 -strip remove all profiles and text attributes from the image
9026 -stroke <color>
9028 color to use when stroking a graphic primitive
9029 -strokewidth <value>
9031 set the stroke width
9032 -swirl <degrees>
9034 swirl image pixels about the center
9035 -texture <filename>
9037 name of texture to tile onto the image background
9038 -threshold <value>{%}
9040 threshold the image
9041 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
9043 resize an image (quickly)
9044 -tile <filename>
9046 tile image when filling a graphic primitive
9047 -transform
9049 transform the image
9050 -transparent <color>
9052 make this color transparent within the image
9053 -treedepth <value>
9055 tree depth for the color reduction algorithm
9056 -trim trim an image
9058 -type <type>
9060 the image type
9061 -units <type>
9063 the units of image resolution
9064 -unsharp <radius>{x<sigma>}{+<amount>}{+<threshold>}
9066 sharpen the image with an unsharp mask operator
9067 -verbose
9069 print detailed information about the image
9070 -version
9072 print GraphicsMagick version string
9073 -view <string>
9075 FlashPix viewing parameters
9076 -virtual-pixel <method>
9078 specify contents of "virtual pixels"
9079 -wave <amplitude>x<wavelength>
9081 alter an image along a sine wave
9082 -white-point <x>,<y>
9084 chromaticity white point
9085 -white-threshold red[,green][,blue][,opacity]
9087 pixels above the threshold become white
9088 For a more detailed description of each option, see Options,
9090 above.
9091
9094 montage creates a composite image by combining several separate images.
9095 The images are tiled on the composite image with the name of the image
9096 optionally appearing just below the individual tile.
9097 The composite image is constructed in the following manner. First, each
9099 image specified on the command line, except for the last, is scaled to
9100 fit the maximum tile size. The maximum tile size by default is 120x120.
9101 It can be modified with the -geometry command line argument or X re‐
9102 source. See Options for more information on command line arguments. See
9103 X(1) for more information on X resources. Note that the maximum tile
9104 size need not be a square.
9105 Next the composite image is initialized with the color specified by the
9107 -background command line argument or X resource. The width and height
9108 of the composite image is determined by the title specified, the maxi‐
9109 mum tile size, the number of tiles per row, the tile border width and
9110 height, the image border width, and the label height. The number of
9111 tiles per row specifies how many images are to appear in each row of
9112 the composite image. The default is to have 5 tiles in each row and 4
9113 tiles in each column of the composite. A specific value is specified
9114 with -tile. The tile border width and height, and the image border
9115 width defaults to the value of the X resource -borderwidth. It can be
9116 changed with the -borderwidth or -geometry command line argument or X
9117 resource. The label height is determined by the font you specify with
9118 the -font command line argument or X resource. If you do not specify a
9119 font, a font is chosen that allows the name of the image to fit the
9120 maximum width of a tiled area. The label colors is determined by the
9121 -background and -fill command line argument or X resource. Note, that
9122 if the background and pen colors are the same, labels will not appear.
9123 Initially, the composite image title is placed at the top if one is
9125 specified (refer to -fill). Next, each image is set onto the composite
9126 image, surrounded by its border color, with its name centered just be‐
9127 low it. The individual images are left-justified within the width of
9128 the tiled area. The order of the images is the same as they appear on
9129 the command line unless the images have a scene keyword. If a scene
9130 number is specified in each image, then the images are tiled onto the
9131 composite in the order of their scene number. Finally, the last argu‐
9132 ment on the command line is the name assigned to the composite image.
9133 By default, the image is written in the MIFF format and can be viewed
9134 or printed with display(1).
9135 Note, that if the number of tiles exceeds the default number of 20 (5
9138 per row, 4 per column), more than one composite image is created. To
9139 ensure a single image is produced, use -tile to increase the number of
9140 tiles to meet or exceed the number of input images.
9141 Finally, to create one or more empty spaces in the sequence of tiles,
9143 use the "NULL:" image format.
9144 Note, a composite MIFF image displayed to an X server with display be‐
9146 haves differently than other images. You can think of the composite as
9147 a visual image directory. Choose a particular tile of the composite and
9148 press a button to display it. See display(1) and miff(5)
9149
9151 To create a montage of a cockatoo, a parrot, and a hummingbird and
9152 write it to a file called birds, use:
9153 gm montage cockatoo.miff parrot.miff hummingbird.miff
9155 birds.miff
9156 To tile several bird images so that they are at most 256 pixels in
9158 width and 192 pixels in height, surrounded by a red border, and sepa‐
9159 rated by 10 pixels of background color, use:
9160 gm montage -geometry 256x192+10+10 -bordercolor red
9162 birds.* montage.miff
9163 To create an unlabeled parrot image, 640 by 480 pixels, and surrounded
9165 by a border of black, use:
9166 gm montage -geometry 640x480 -bordercolor black
9168 -label "" parrot.miff bird.miff
9169 To create an image of an eagle with a textured background, use:
9171 gm montage -texture bumps.jpg eagle.jpg eagle.png
9173 To join several GIF images together without any extraneous graphics
9175 (e.g. no label, no shadowing, no surrounding tile frame), use:
9176 gm montage +frame +shadow +label -tile 5x1
9178 -geometry 50x50+0+0 *.png joined.png
9179
9181 Any option you specify on the command line remains in effect for the
9182 group of images following it, until the group is terminated by the ap‐
9183 pearance of any option or -noop. For example, to make a montage of
9184 three images, the first with 32 colors, the second with an unlimited
9185 number of colors, and the third with only 16 colors, use:
9186 gm montage -colors 32 cockatoo.1 -noop cockatoo.2
9189 -colors 16 cockatoo.3 cockatoos.miff
9190 For a more detailed description of each option, see Options, above.
9192 -adjoin
9195 join images into a single multi-image file
9196 -affine <matrix>
9198 drawing transform matrix
9199 -authenticate <string>
9201 decrypt image with this password
9202 -background <color>
9204 the background color
9205 -blue-primary <x>,<y>
9207 blue chromaticity primary point
9208 -blur <radius>{x<sigma>}
9210 blur the image with a Gaussian operator
9211 -bordercolor <color>
9213 the border color
9214 -borderwidth <geometry>
9216 the border width
9217 -chop <width>x<height>{+-}<x>{+-}<y>{%}
9219 remove pixels from the interior of an image
9220 -colors <value>
9222 preferred number of colors in the image
9223 -colorspace <value>
9225 the type of colorspace
9226 -comment <string>
9228 annotate an image with a comment
9229 -compose <operator>
9231 the type of image composition
9232 -compress <type>
9234 the type of image compression
9235 -crop <width>x<height>{+-}<x>{+-}<y>{%}
9237 preferred size and location of the cropped image
9238 -debug <events>
9240 enable debug printout
9241 -define <key>{=<value>},...
9243 add coder/decoder specific options
9244 -density <width>x<height>
9246 horizontal and vertical resolution in pixels of the image
9247 -depth <value>
9249 depth of the image
9250 -display <host:display[.screen]>
9252 specifies the X server to contact
9253 -dispose <method>
9255 GIF disposal method
9256 -dither
9258 apply Floyd/Steinberg error diffusion to the image
9259 -draw <string>
9261 annotate an image with one or more graphic primitives
9262 -encoding <type>
9264 specify the text encoding
9265 -endian <type>
9267 specify endianness (MSB, LSB, or Native) of image
9268 -fill <color>
9270 color to use when filling a graphic primitive
9271 -filter <type>
9273 use this type of filter when resizing an image
9274 -font <name>
9276 use this font when annotating the image with text
9277 -frame <width>x<height>+<outer bevel width>+<inner bevel width>
9279 surround the image with an ornamental border
9280 -gamma <value>
9282 level of gamma correction
9283 -geometry <width>x<height>{+-}<x>{+-}<y>{%}{@}{!}{^}{<}{>}
9285 Specify dimension, offset, and resize options.
9286 -gravity <type>
9288 direction primitive gravitates to when annotating the image.
9289 -green-primary <x>,<y>
9291 green chromaticity primary point
9292 -help print usage instructions
9294 -interlace <type>
9296 the type of interlacing scheme
9297 -label <name>
9299 assign a label to an image
9300 -limit <type> <value>
9302 Disk, File, Map, Memory, Pixels, Width, Height, Read, or Threads
9303 resource limit
9304 -log <string>
9306 Specify format for debug log
9307 -matte store matte channel if the image has one
9309 -mattecolor <color>
9311 specify the color to be used with the -frame option
9312 -mode <value>
9314 mode of operation
9315 -monitor
9317 show progress indication
9318 -monochrome
9320 transform the image to black and white
9321 -noop NOOP (no option)
9323 -page <width>x<height>{+-}<x>{+-}<y>{%}{!}{<}{>}
9325 size and location of an image canvas
9326 -pen <color>
9328 (This option has been replaced by the -fill option)
9329 -pointsize <value>
9331 pointsize of the PostScript, X11, or TrueType font
9332 -quality <value>
9334 JPEG/MIFF/PNG/TIFF compression level
9335 -red-primary <x>,<y>
9337 red chromaticity primary point
9338 -render
9340 render vector operations
9341 -repage <width>x<height>+xoff+yoff[!]
9343 Adjust image page offsets
9344 -resize <width>x<height>{%}{@}{!}{<}{>}
9346 resize an image
9347 -rotate <degrees>{<}{>}
9349 rotate the image
9350 -sampling-factor <horizontal_factor>x<vertical_factor>
9352 chroma subsampling factors
9353 -scenes <value-value>
9355 range of image scene numbers to read
9356 -shadow <radius>{x<sigma>}
9358 shadow the montage
9359 -sharpen <radius>{x<sigma>}
9361 sharpen the image
9362 -size <width>x<height>{+offset}
9364 width and height of the image
9365 -strip remove all profiles and text attributes from the image
9367 -stroke <color>
9369 color to use when stroking a graphic primitive
9370 -strokewidth <value>
9372 set the stroke width
9373 -texture <filename>
9375 name of texture to tile onto the image background
9376 -thumbnail <width>x<height>{%}{@}{!}{<}{>}
9378 resize an image (quickly)
9379 -tile <geometry>
9381 layout of images [montage]
9382 -title <string>
9384 assign title to displayed image [animate, display, montage]
9385 -transform
9387 transform the image
9388 -transparent <color>
9390 make this color transparent within the image
9391 -treedepth <value>
9393 tree depth for the color reduction algorithm
9394 -trim trim an image
9396 -type <type>
9398 the image type
9399 -verbose
9401 print detailed information about the image
9402 -version
9404 print GraphicsMagick version string
9405 -white-point <x>,<y>
9407 chromaticity white point
9408 For a more detailed description of each option, see Options,
9410 above.
9411
9414 Montage options can appear on the command line or in your X resource
9415 file. Options on the command line supersede values specified in your X
9416 resource file. See X(1) for more information on X resources.
9417 All montage options have a corresponding X resource. In addition, mon‐
9419 tage uses the following X resources:
9420 background (class Background)
9422 background color
9423 Specifies the preferred color to use for the composite image
9425 background. The default is #ccc.
9426 borderColor (class BorderColor)
9428 border color
9429 Specifies the preferred color to use for the composite image
9431 border. The default is #ccc.
9432 borderWidth (class BorderWidth)
9434 border width
9435 Specifies the width in pixels of the composite image border. The
9437 default is 2.
9438 font (class Font)
9440 font to use
9441 Specifies the name of the preferred font to use when displaying
9443 text within the composite image. The default is 9x15, fixed, or
9444 5x8 determined by the composite image size.
9445 matteColor (class MatteColor)
9447 color of the frame
9448 Specify the color of an image frame. A 3D effect is achieved by
9450 using highlight and shadow colors derived from this color. The
9451 default value is #697B8F.
9452 pen (class Pen)
9454 text color
9455 Specifies the preferred color to use for text within the compos‐
9457 ite image. The default is black.
9458 title (class Title)
9460 composite image title
9461 This resource specifies the title to be placed at the top of the
9463 composite image. The default is not to place a title at the top
9464 of the composite image.
9465
9468 time executes an arbitrary gm utility command (e.g. convert) and re‐
9469 ports the user and elapsed time. This provides way to measure command
9470 execution times similar to the Unix ´time' command but in a portable
9471 and consistent way.
9472
9474 To obtain time information for the execution of a command:
9475 % gm time convert input.ppm -gaussian 0x2 output.ppm
9477 convert input.ppm -gaussian 0x2 output.ppm 22.60s user 0.00s system 2354% cpu 0.960 total
9478 Here is the interpretation of the above output:
9479 user - the total user time consumed.
9481 system - the total system time consumed.
9482 total - the total elapsed time consumed.
9483
9486 The time command reqires no options other than the gm command to exe‐
9487 cute.
9488
9491 version displays the software release version, build quantum (pixel
9492 sample) depth, web site URL, copyright notice, enabled features sup‐
9493 port, configuration parameters, and final build options used to build
9494 the software. The available information depends on how the software
9495 was configured and the host system.
9496
9498 To display the version information:
9499 GraphicsMagick 1.3.37 2021-12-12 Q16 http://www.GraphicsMagick.org/
9501 Copyright (C) 2002-2021 GraphicsMagick Group.
9502 Additional copyrights and licenses apply to this software.
9503 See http://www.GraphicsMagick.org/www/Copyright.html for details.
9504 Feature Support:
9505 Native Thread Safe yes
9506 Large Files (> 32 bit) yes
9507 Large Memory (> 32 bit) yes
9508 BZIP yes
9509 DPS no
9510 FlashPix no
9511 FreeType yes
9512 Ghostscript (Library) no
9513 JBIG yes
9514 JPEG-2000 yes
9515 JPEG yes
9516 Little CMS yes
9517 Loadable Modules no
9518 Solaris mtmalloc no
9519 Google perftools tcmalloc no
9520 OpenMP yes (201511 "4.5")
9521 PNG yes
9522 TIFF yes
9523 TRIO no
9524 Solaris umem no
9525 WebP yes
9526 WMF yes
9527 X11 yes
9528 XML yes
9529 ZLIB yes
9530 Host type: x86_64-unknown-linux-gnu
9531 Configured using the command:
9532 ./configure ...
9533 Final Build Parameters:
9534 CC = ...
9535 CFLAGS = ...
9536 CPPFLAGS = ...
9537 CXX = ...
9538 CXXFLAGS = ...
9539 LDFLAGS = ...
9540 LIBS = ...
9541
9543 The version command does not currently support any options.
9544GraphicsMagick 2022/03/11 gm(1)