The -define command-line option adds specific global settings generally used to control coders and image processing operations.
About Definitions
This option creates one or more definitions for coders and decoders while reading and writing image data. Definitions control file format coder modules and image processing operations beyond normal options.
Defined settings appear in -verbose information ("info:" output format) as Artifacts.
Usage & Management
- Missing values create empty-valued flags (on/off control).
- Use
-define keysto remove previous definitions. - Use
+define "*"to clear all existing definitions. - Equivalent settings can use
-set "option:key" "value"with Format Properties.
example-define.sh
$ magick bilevel.tif -define ps:imagemask eps3:stencil.ps
$ magick arrow.tga -set colorspace:auto-grayscale=off myArrow.tga
$ magick arrow.tga -set colorspace:auto-grayscale=off myArrow.tga
registry-define.sh
# Set temporary work path in registry
$ magick -define registry:temporary-path=/data/tmp input.png output.png
$ magick -define registry:temporary-path=/data/tmp input.png output.png
Recognized Defines
The options and keys are case-independent (converted to lowercase for decoders) while values are case-dependent. Here is the complete list of recognized defines:
| Define Key / Pattern | Description |
|---|---|
| Command-line Defines | |
| ashlar:best-fit | align tiles on both the left and right edges. |
| ashlar:tiles | set the maximum number of image tiles to render per canvas. |
| auto-threshold:verbose | return derived threshold as the auto-threshold:threshold image property. |
| color:illuminant | reference illuminant, defaults to D65. |
| colorspace:auto-grayscale=on|off | Prevent automatic conversion to grayscale inside coders that support grayscale. Should be accompanied by -type truecolor. |
| compare:frequency-domain=boolean | Certain similarity metrics operate in frequency domain when FFTW and HDRI are enabled. Use -define compare:frequency-domain=false for spatial equivalents. |
| compare:ssim-radius=value | Set the structural similarity index radius. |
| compare:ssim-sigma=value | Set the structural similarity index sigma. |
| compare:ssim-k1=value | Set the structural similarity index k1 argument. |
| compare:ssim-k2=value | Set the structural similarity index k2 argument. |
| compare:virtual-pixels=boolean | Treat unmatched areas as virtual pixels or limit comparison to authentic pixels using -define compare:virtual-pixels=false. |
| complex:snr=value | Set the divide SNR constant -complex. |
| compose:args=arguments | Set certain compose argument values. See Image Composition. |
| compose:clip-to-self=true|false | Some -compose methods can modify destination outside overlay area. Disabled by default. |
| compose:clamp=on|off | Set each pixel below zero to zero and above quantum range to quantum range. Supported in ImageMagick 6.9.1-3+. |
| compose:colorspace=colorspace | Set the colorspace for colorize composite operator. Default is HCL. |
| compose:compose=on|off | Perform true mathematics of image channels without alpha composition effects. |
| connected-components:angle-threshold=value | Merges any region with equivalent ellipse angle smaller than value. Imagemagick 7.0.9.24+. |
| connected-components:area-threshold=value | Merges any region with area smaller than value into surrounding region. Optional ranges e.g. 410-1600. |
| connected-components:background-id=object-id | Identify background object. Imagemagick 7.0.9.21+. |
| connected-components:circularity-threshold=value | Merge region with circularity smaller than value. Computed as 4*pi*area/perimeter^2. IM 7.0.9.24+. |
| connected-components:diameter-threshold=value | Merge region with diameter smaller than value. Computed as sqrt(4*area/pi). IM 7.0.9.24+. |
| connected-components:eccentricity-threshold=value | Merge region with equivalent ellipse eccentricity smaller than value. IM 7.0.9.24+. |
| connected-components:exclude-header=true | List objects without header. IM 7.0.9.21+. |
| connected-components:keep=list-of-ids | Comma and/or hyphenated list of id values to keep. IM 6.9.3-0+. |
| connected-components:keep-colors=red;green;blue | Keeps objects identified by color in semicolon separated list. IM 6.9.3-0+. |
| connected-components:keep-top=number | Keeps only top number of objects by area. IM 7.0.9.21+. |
| connected-components:major-axis-threshold=value | Merge region with major axis diameter smaller than value. IM 7.0.9.24+. |
| connected-components:mean-color=true | Change output image from id values to mean color values. IM 6.9.2-8+. |
| connected-components:minor-axis-threshold=value | Merge region with minor axis diameter smaller than value. IM 7.0.9.24+. |
| connected-components:perimeter-threshold=value | Merge region with perimeter smaller than value. IM 7.0.9.24+. |
| connected-components:remove=list-of-ids | Comma/hyphenated list of id values to remove. IM 6.9.2-9+. |
| connected-components:remove-colors=red;green;blue | Remove objects identified by color in semicolon list. IM 6.9.3-0+. |
| connected-components:verbose=true | Lists id, bounding box, centroid, area, mean color for each region. |
| convolve:scale=scale[!^] [,add] [%] | Define kernel scaling. Flag ! auto scales to full range. Flag ^ assures zero-summing. Origin addition adds value to center pixel. |
| deskew:auto-crop=true | Auto crop image after deskewing. |
| delegate:bimodal=true | Specify direct conversion from Postscript to PDF. |
| distort:scale=value | Set output scaling factor for -distort. |
| distort:viewport=WxH+X+Y | Set viewport for -distort. |
| dither:diffusion-amount=X% | Set amount of diffusion for Floyd-Steinberg diffusion. |
| exif:sync-image=false | Ignore EXIF profile for image resolution syncing. |
| filename:literal=true | Bypass interpreting embedded formatting characters and use filename literally. |
| filter:option=value | Set filter option for -resize. |
| filter:b=value | Redefine spline factor for cubic filters (Mitchell-Netravali definition). |
| filter:blur=factor | Scale X axis of filter (> 1.0 blurry, < 1.0 sharp). Use with Gaussian-like filters. |
| filter:c=value | Redefine Keys alpha factor for cubic filters. |
| filter:kaiser-alpha=value | Set Kaiser window alpha value (equivalent to kaiser-beta when multiplied by PI). |
| filter:kaiser-beta=value | Set Kaiser window beta value. Default is 6.5. |
| filter:lobes=count | Set number of lobes for Sinc/Bessel filter (support range). |
| filter:sigma=value | Set sigma value for Gaussian filter. Default is 0.5. |
| filter:support=radius | Set filter support radius. |
| filter:verbose=true | Enable printing internal filter selection info to standard output. |
| filter:window=filter_function | Specify filter function for windowing IIR filters Sinc and Jinc. |
| filter:window-support=radius | Scale windowing function to this size. |
| h:format=value | Set image encoding format for C-style header. Defaults to GIF (PseudoClass) and PNM (DirectClass). |
| fourier:normalize=inverse | Set FFT/IFT normalization location for +-fft / +-ift. Default is forward. |
| frames:step | Step interval when selecting image frames (e.g., step 2 skips alternating frames). |
| fx:debug=true | Debug -fx expression. |
| hough-lines:accumulator=true | Return accumulator image alongside lines image. |
| identify:convex-hull=true | Display convex hull & minimum bounding box. |
| identify:locate=value | Display minimum or maximum pixel locations (default: maximum). |
| identify:limit=value | Maximum pixel locations to display with identify:locate. |
| image:frames | Select specific frames from multi-image formats (e.g., 0-3). |
| json:features | Include features in verbose JSON information. |
| kmeans:seed-colors=color-list | Initialize colors with semicolon-delimited list of seed colors. |
| magick:format=value | Equivalent to h:format=format for C-style headers. |
| magnify:method=value | Choose pixel art magnification method (eagle2X, scale2X default, xbr2X, etc.). |
| modulate:colorspace=colorspace | Define colorspace for -modulate (default HSL). |
| morphology:compose=method | Specify how to merge multiple -morphology kernels. |
| morphology:showKernel=1 | Output kernel information to standard error. |
| phash:colorspaces=list | Specify up to six alternative colorspaces for perceptual hash (IM 7.0.3-8+). |
| phash:normalize=true | Normalize phash metric. |
| pixel:compliance=standard | Format color values based on standard compliance (svg, mvg, x11, etc.). |
| png:bit-depth=value | Set PNG bit depth. |
| png:chunk-malloc-max=value | Set maximum chunk size. |
| profile:skip=names | Skip named profiles (ICC, EXIF, XMP, etc.) when reading image. Use skip="*" for all. |
| precision:highres-transform=true | Increase profile transform precision using floating point. |
| preserve-timestamp=true|false | Preserve file timestamp (mogrify only). |
| q-table=file.xml | Custom JPEG quantization tables. |
| quantum:format=type | Specify floating-point or signed format for raw files or HDRI preservation. |
| quantum:maximum=value | Maximum value for formats like DCM (defaults to QuantumRange). |
| quantum:minimum=value | Minimum value for formats like DCM (defaults to zero). |
| quantum:polarity=interpretation | Set TIFF photometric-interpretation (min-is-black or min-is-white). |
| registry:attr=val | Set image registry attributes. |
| registry:date:precision=len | Set max characters printed for timestamps. |
| registry:option:pedantic=bool | Interpret ambiguous command-line options as options instead of filenames when true. |
| registry:precision=value | Set max significant digits printed. |
| resample:verbose=true | Output EWA cylindrical filter lookup table for debugging. |
| sample:offset=geometry | Sampling point location expressed as percentages. |
| shepards:power=value | Set exponent in Shepard's distortion (default: 2). |
| stream:buffer-size=value | Set stream buffer size (0 for unbuffered I/O). |
| trim:percent-background=X% | Tolerance amount of background tolerated in an edge. |
| trim:edges=edges | Only trim specified edges (north,east,south,west). |
| trim:minSize=geometry | Limit trim to specified size. |
| type:features=string | Add font feature for RAQM delegate during complex text layout. |
| type:hinting=false | Disable font hinting. |
| white-balance:vibrance=value | Change color vibrance of a & b channels. |
| x:screen=true | Obtain image from root window. |
| x:silent=true | Turn off beep when importing image. |
| Image Formats | |
| bmp3:alpha=true|false | Include alpha channel when writing BMP. |
| bmp:format=value | Valid values: bmp2, bmp3, bmp4. Useful with mogrify. |
| bmp:subtype=value | BMP channel depth subtypes (RGB555, RGB565, ARGB4444, ARGB1555). |
| {caption,label}:max-pointsize=val | Set bounding pointsize for maximum fit. |
| dcm:display-range=reset | Set display range to min/max pixel values for DCM. |
| dcm:fix-byte-order=true | Fix incorrect byte order when reading DCM pixels. |
| dcm:rescale=true | Enable interpretation of rescale slope and intercept. |
| dcm:window=CxW | Specify DCM window center and width. |
| dds:cluster-fit=true|false | Enable DDS cluster-fit. |
| dds:compression=dxt1|dxt5|none | Set DDS compression. |
| dds:mipmaps=value | Set DDS number of mipmaps. |
| dds:weight-by-alpha=true|false | Enable DDS alpha weighting. |
| dng:max-raw-memory=value | Stop processing if raw buffer exceeds megabytes (default: 8192). |
| dng:no-auto-bright=true | Disable histogram-based white level. |
| dng:output-color=value | Select output colorspace (0-6). |
| dng:read-thumbnail=true | Store embedded thumbnail as 'dng:thumbnail' profile. |
| dng:read-thumbnails=true | Read embedded thumbnails as images instead of full raw image. |
| dng:use-auto-wb=true | Compute white balance by averaging entire image. |
| dng:use-camera-wb=true | Use camera-specified white balance (default: true). |
| dot:layout-engine=value | Specify layout engine for DOT format (e.g. neato). |
| eps:use-cropbox=true | Force ImageMagick to respect crop box. |
| exr:color-type=value | Specify color type for EXR format (RGB, RGBA, YC, Y, etc.). |
| fpx:view=value | Specify FlashPix viewing object and transform commands. |
| ftxt:chsep=value | Character separating channel values (default: ","). |
| ftxt:format=value | Format string for reading/writing text. |
| heic:chroma=value | Set HEIC chroma parameter ("420", "422", "444"). |
| heic:cicp=value | Set HEIC color primaries, transfer characteristics, and matrix. |
| heic:preserve-orientation=true | Preserve original EXIF orientation during HEIC decoding. |
| heic:primary-image=true | Read only primary image of HEIC/AVIF container. |
| heic:speed=value | Set HEIC speed parameter (0-9, default 5). |
| icon:auto-resize | Automatically store multiple sizes when writing ICO (requires 256x256 input). |
| json:moments | Include image moments in verbose JSON information. |
| jp2:layer-number=value | Set max quality layers to decode for JPEG-2000. |
| jp2:rate=value | Specify compression factor (0.0 to 1.0, 1.0 = lossless), overriding -quality. |
| jpeg:arithmetic-coding=on|off | Enable/disable Huffman optimization. |
| jpeg:dct-method=value | Choose DCT method (default, fastest, float, ifast, islow). |
| jpeg:extent=value | Restrict max JPEG file size (e.g., 400KB). |
| jpeg:high-bit-depth=on|off | Produce 12-bit or 16-bit JPEG images if source depth exceeds 8 bits. |
| jpeg:size=geometry | Set size hint for downscaling large JPEGs efficiently. |
| jxl:decoding-speed=value | Set JPEG XL decoding speed (0 to 4). |
| jxl:effort=value | Set JPEG XL encoding effort (3 to 9). |
| minimum-bounding-box:orientation=val | Find smallest perpendicular distance (horizontal or vertical). |
| pdf:author=author | Set PDF document author. |
| pdf:fit-page=geometry | Specify scaling dimensions when reading PDF. |
| pdf:thumbnail=false | Generate image thumbnails when saving PDF. |
| png:color-type=value | Force PNG bit-depth and color-type without quality loss. |
| png:compression-level=value | Set zlib compression level (0 through 9). |
| png:format=value | Specify PNG format variant (png8, png24, png32, png48, png64, png00). |
| png:include-chunk=value | Ancillary chunks to be included/excluded from PNG output. |
| ps:imagemask | Render bilevel images using PostScript imagemask operator. |
| psd:additional-info=all|selective | Preserve non-geometric additional PSD information between conversions. IM 6.9.5-8+. |
| ptif:pyramid=min-basexlevels | Specify pyramid parameters for PTIF (e.g., 64x4). |
| svg:parse-huge=true | Enable rendering of very large trusted SVGs. |
| tga:preserve-orientation=true | Preserve TGA image orientation. |
| tiff:alpha=mode | Specify alpha extra samples (associated, unassociated, unspecified). |
| tiff:predictor=value | Apply mathematical predictor before compression (1=none, 2=horizontal, 3=floating-point). |
| uhdr:gainmap-quality=value | Set UltraHDR gainmap encoding quality (1 to 100). |
| video:intermediate-format=format | Set video intermediate format option for ffmpeg (pam, webp). |
| Pseudo-Image Formats | |
| caption:max-pointsize=pointsize | Limit maximum point size for caption layout. |
| caption:split=boolean | Split text if required to fit caption on canvas. |
| gradient:angle=angle | Specify direction of linear gradient or rotation of radial gradient. IM 6.9.2-5+. |
| gradient:bounding-box=WxH+X+Y | Limit gradient region. IM 6.9.2-5+. |
| gradient:center=x,y | Specify coordinates of center point for radial gradient. IM 6.9.2-5+. |
| gradient:direction=value | Specify linear gradient direction (NorthWest, North, etc.). IM 6.9.2-5+. |
| gradient:extent=value | Specify shape of centered radial gradient (Circle, Diagonal, Ellipse, Maximum, Minimum). |
| gradient:radii=x,y | Specify X and Y radii of gradient. |
| gradient:vector=x1,y1,x2,y2 | Specify direction vector from start to end color positions. |
| histogram:unique-colors=false | Suppress textual listing of image's unique colors. |
| pango:tag=value | Configure Pango layout properties (align, ellipsize, justify, wrap, etc.). |
| webp:tag=value | WebP specific encoding options. See WebP documentation. |
| xmp:validate=bool | Validate embedded XMP profiles (enabled by default). |