command-line-options.html revision 776113a8fda18c5666145dca6a3b80e910ab48cd
1 2 3 4 5<!DOCTYPE html> 6<html lang="en"> 7<head> 8 <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" /> 9 <title>ImageMagick: Command-line Options</title> 10 <meta http-equiv="content-type" content="text/html; charset=utf-8"/> 11 <meta name="application-name" content="ImageMagick"/> 12 <meta name="description" content="ImageMagick® is a software suite to create, edit, compose, or convert bitmap images. It can read and write images in a variety of formats (over 200) including PNG, JPEG, JPEG-2000, GIF, WebP, Postscript, PDF, and SVG. Use ImageMagick to resize, flip, mirror, rotate, distort, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves."/> 13 <meta name="application-url" content="http://www.imagemagick.org"/> 14 <meta name="generator" content="PHP"/> 15 <meta name="keywords" content="command-line, options, ImageMagick, PerlMagick, image processing, image, photo, software, Magick++, OpenMP, convert"/> 16 <meta name="rating" content="GENERAL"/> 17 <meta name="robots" content="INDEX, FOLLOW"/> 18 <meta name="generator" content="ImageMagick Studio LLC"/> 19 <meta name="author" content="ImageMagick Studio LLC"/> 20 <meta name="revisit-after" content="2 DAYS"/> 21 <meta name="resource-type" content="document"/> 22 <meta name="copyright" content="Copyright (c) 1999-2015 ImageMagick Studio LLC"/> 23 <meta name="distribution" content="Global"/> 24 <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1"/> 25 <link rel="icon" href="/images/wand.png"/> 26 <link rel="shortcut icon" href="/images/wand.ico"/> 27 <link rel="stylesheet" href="css/magick.css"/> 28</head> 29<body> 30<div class="main"> 31<div class="magick-masthead"> 32 <div class="container"> 33 <script async="async" src="http://localhost/pagead/js/adsbygoogle.js"></script> <ins class="adsbygoogle" 34 style="display:block" 35 data-ad-client="ca-pub-3129977114552745" 36 data-ad-slot="6345125851" 37 data-ad-format="auto"></ins> 38 <script> 39 (adsbygoogle = window.adsbygoogle || []).push({}); 40 </script> 41 <nav class="magick-nav"> 42 <a class="magick-nav-item " href="/index.html">Home</a> 43 <a class="magick-nav-item " href="binary-releases.html">Download</a> 44 <a class="magick-nav-item " href="command-line-tools.html">Tools</a> 45 <a class="magick-nav-item " href="command-line-processing.html">Command-line</a> 46 <a class="magick-nav-item " href="resources.html">Resources</a> 47 <a class="magick-nav-item " href="api.html">Develop</a> 48 <a class="magick-nav-item " href="http://nextgen.imagemagick.org/script/search.php">Search</a> 49 <a class="magick-nav-item pull-right" href="https://www.imagemagick.org/discourse-server/">Community</a> 50 </nav> 51 </div> 52</div> 53<div class="container"> 54<div class="magick-header"> 55<p class="text-center"><a href="command-line-options.html#adaptive-blur">‑adaptive‑blur</a> • <a href="command-line-options.html#adaptive-resize">‑adaptive‑resize</a> • <a href="command-line-options.html#adaptive-sharpen">‑adaptive‑sharpen</a> • <a href="command-line-options.html#adjoin">‑adjoin</a> • <a href="command-line-options.html#affine">‑affine</a> • <a href="command-line-options.html#alpha">‑alpha</a> • <a href="command-line-options.html#alpha-color">‑alpha‑color</a> • <a href="command-line-options.html#annotate">‑annotate</a> • <a href="command-line-options.html#antialias">‑antialias</a> • <a href="command-line-options.html#append">‑append</a> • <a href="command-line-options.html#attenuate">‑attenuate</a> • <a href="command-line-options.html#authenticate">‑authenticate</a> • <a href="command-line-options.html#auto-gamma">‑auto‑gamma</a> • <a href="command-line-options.html#auto-level">‑auto‑level</a> • <a href="command-line-options.html#auto-orient">‑auto‑orient</a> • <a href="command-line-options.html#backdrop">‑backdrop</a> • <a href="command-line-options.html#background">‑background</a> • <a href="command-line-options.html#bench">‑bench</a> • <a href="command-line-options.html#bias">‑bias</a> • <a href="command-line-options.html#black-point-compensation">‑black‑point‑compensation</a> • <a href="command-line-options.html#black-threshold">‑black‑threshold</a> • <a href="command-line-options.html#blend">‑blend</a> • <a href="command-line-options.html#blue-primary">‑blue‑primary</a> • <a href="command-line-options.html#blue-shift">‑blue‑shift</a> • <a href="command-line-options.html#blur">‑blur</a> • <a href="command-line-options.html#border">‑border</a> • <a href="command-line-options.html#bordercolor">‑bordercolor</a> • <a href="command-line-options.html#borderwidth">‑borderwidth</a> • <a href="command-line-options.html#brightness-contrast">‑brightness‑contrast</a> • <a href="command-line-options.html#cache">‑cache</a> • <a href="command-line-options.html#canny">‑canny</a> • <a href="command-line-options.html#caption">‑caption</a> • <a href="command-line-options.html#cdl">‑cdl</a> • <a href="command-line-options.html#channel">‑channel</a> • <a href="command-line-options.html#charcoal">‑charcoal</a> • <a href="command-line-options.html#chop">‑chop</a> • <a href="command-line-options.html#clamp">‑clamp</a> • <a href="command-line-options.html#clip">‑clip</a> • <a href="command-line-options.html#clip-mask">‑clip‑mask</a> • <a href="command-line-options.html#clip-path">‑clip‑path</a> • <a href="command-line-options.html#clone">‑clone</a> • <a href="command-line-options.html#clut">‑clut</a> • <a href="command-line-options.html#coalesce">‑coalesce</a> • <a href="command-line-options.html#colorize">‑colorize</a> • <a href="command-line-options.html#colormap">‑colormap</a> • <a href="command-line-options.html#color-matrix">‑color‑matrix</a> • <a href="command-line-options.html#colors">‑colors</a> • <a href="command-line-options.html#colorspace">‑colorspace</a> • <a href="command-line-options.html#combine">‑combine</a> • <a href="command-line-options.html#comment">‑comment</a> • <a href="command-line-options.html#compare">‑compare</a> • <a href="command-line-options.html#complex">‑complex</a> • <a href="command-line-options.html#compose">‑compose</a> • <a href="command-line-options.html#composite">‑composite</a> • <a href="command-line-options.html#compress">‑compress</a> • <a href="command-line-options.html#connected-components">‑connected‑components</a> • <a href="command-line-options.html#contrast">‑contrast</a> • <a href="command-line-options.html#contrast-stretch">‑contrast‑stretch</a> • <a href="command-line-options.html#convolve">‑convolve</a> • <a href="command-line-options.html#copy">‑copy</a> • <a href="command-line-options.html#crop">‑crop</a> • <a href="command-line-options.html#cycle">‑cycle</a> • <a href="command-line-options.html#debug">‑debug</a> • <a href="command-line-options.html#decipher">‑decipher</a> • <a href="command-line-options.html#deconstruct">‑deconstruct</a> • <a href="command-line-options.html#define">‑define</a> • <a href="command-line-options.html#delay">‑delay</a> • <a href="command-line-options.html#delete">‑delete</a> • <a href="command-line-options.html#density">‑density</a> • <a href="command-line-options.html#depth">‑depth</a> • <a href="command-line-options.html#descend">‑descend</a> • <a href="command-line-options.html#deskew">‑deskew</a> • <a href="command-line-options.html#despeckle">‑despeckle</a> • <a href="command-line-options.html#direction">‑direction</a> • <a href="command-line-options.html#displace">‑displace</a> • <a href="command-line-options.html#display">‑display</a> • <a href="command-line-options.html#dispose">‑dispose</a> • <a href="command-line-options.html#dissimilarity-threshold">‑dissimilarity‑threshold</a> • <a href="command-line-options.html#dissolve">‑dissolve</a> • <a href="command-line-options.html#distort">‑distort</a> • <a href="command-line-options.html#distribute-cache">‑distribute‑cache</a> • <a href="command-line-options.html#dither">‑dither</a> • <a href="command-line-options.html#draw">‑draw</a> • <a href="command-line-options.html#duplicate">‑duplicate</a> • <a href="command-line-options.html#edge">‑edge</a> • <a href="command-line-options.html#emboss">‑emboss</a> • <a href="command-line-options.html#encipher">‑encipher</a> • <a href="command-line-options.html#encoding">‑encoding</a> • <a href="command-line-options.html#endian">‑endian</a> • <a href="command-line-options.html#enhance">‑enhance</a> • <a href="command-line-options.html#equalize">‑equalize</a> • <a href="command-line-options.html#evaluate">‑evaluate</a> • <a href="command-line-options.html#evaluate-sequence">‑evaluate‑sequence</a> • <a href="command-line-options.html#extent">‑extent</a> • <a href="command-line-options.html#extract">‑extract</a> • <a href="command-line-options.html#family">‑family</a> • <a href="command-line-options.html#features">‑features</a> • <a href="command-line-options.html#fft">‑fft</a> • <a href="command-line-options.html#fill">‑fill</a> • <a href="command-line-options.html#filter">‑filter</a> • <a href="command-line-options.html#flatten">‑flatten</a> • <a href="command-line-options.html#flip">‑flip</a> • <a href="command-line-options.html#floodfill">‑floodfill</a> • <a href="command-line-options.html#flop">‑flop</a> • <a href="command-line-options.html#font">‑font</a> • <a href="command-line-options.html#foreground">‑foreground</a> • <a href="command-line-options.html#format">‑format</a> • <a href="command-line-options.html#format_identify_">‑format[identify]</a> • <a href="command-line-options.html#frame">‑frame</a> • <a href="command-line-options.html#frame_import_">‑frame[import]</a> • <a href="command-line-options.html#function">‑function</a> • <a href="command-line-options.html#fuzz">‑fuzz</a> • <a href="command-line-options.html#fx">‑fx</a> • <a href="command-line-options.html#gamma">‑gamma</a> • <a href="command-line-options.html#gaussian-blur">‑gaussian‑blur</a> • <a href="command-line-options.html#geometry">‑geometry</a> • <a href="command-line-options.html#gravity">‑gravity</a> • <a href="command-line-options.html#grayscale">‑grayscale</a> • <a href="command-line-options.html#green-primary">‑green‑primary</a> • <a href="command-line-options.html#hald-clut">‑hald‑clut</a> • <a href="command-line-options.html#help">‑help</a> • <a href="command-line-options.html#highlight-color">‑highlight‑color</a> • <a href="command-line-options.html#hough-lines">‑hough‑lines</a> • <a href="command-line-options.html#iconGeometry">‑iconGeometry</a> • <a href="command-line-options.html#iconic">‑iconic</a> • <a href="command-line-options.html#identify">‑identify</a> • <a href="command-line-options.html#ift">‑ift</a> • <a href="command-line-options.html#immutable">‑immutable</a> • <a href="command-line-options.html#implode">‑implode</a> • <a href="command-line-options.html#insert">‑insert</a> • <a href="command-line-options.html#intensity">‑intensity</a> • <a href="command-line-options.html#intent">‑intent</a> • <a href="command-line-options.html#interlace">‑interlace</a> • <a href="command-line-options.html#interpolate">‑interpolate</a> • <a href="command-line-options.html#interline-spacing">‑interline‑spacing</a> • <a href="command-line-options.html#interword-spacing">‑interword‑spacing</a> • <a href="command-line-options.html#kerning">‑kerning</a> • <a href="command-line-options.html#kuwahara">‑kuwahara</a> • <a href="command-line-options.html#label">‑label</a> • <a href="command-line-options.html#lat">‑lat</a> • <a href="command-line-options.html#layers">‑layers</a> • <a href="command-line-options.html#level">‑level</a> • <a href="command-line-options.html#level-colors">‑level‑colors</a> • <a href="command-line-options.html#limit">‑limit</a> • <a href="command-line-options.html#linear-stretch">‑linear‑stretch</a> • <a href="command-line-options.html#linewidth">‑linewidth</a> • <a href="command-line-options.html#liquid-rescale">‑liquid‑rescale</a> • <a href="command-line-options.html#list">‑list</a> • <a href="command-line-options.html#log">‑log</a> • <a href="command-line-options.html#loop">‑loop</a> • <a href="command-line-options.html#lowlight-color">‑lowlight‑color</a> • <a href="command-line-options.html#magnify">‑magnify</a> • <a href="command-line-options.html#map">‑map</a> • <a href="command-line-options.html#map_stream_">‑map[stream]</a> • <a href="command-line-options.html#mask">‑mask</a> • <a href="command-line-options.html#mattecolor">‑mattecolor</a> • <a href="command-line-options.html#median">‑median</a> • <a href="command-line-options.html#mean-shift">‑mean‑shift</a> • <a href="command-line-options.html#metric">‑metric</a> • <a href="command-line-options.html#mode">‑mode</a> • <a href="command-line-options.html#modulate">‑modulate</a> • <a href="command-line-options.html#moments">‑moments</a> • <a href="command-line-options.html#monitor">‑monitor</a> • <a href="command-line-options.html#monochrome">‑monochrome</a> • <a href="command-line-options.html#morph">‑morph</a> • <a href="command-line-options.html#morphology">‑morphology</a> • <a href="command-line-options.html#mosaic">‑mosaic</a> • <a href="command-line-options.html#motion-blur">‑motion‑blur</a> • <a href="command-line-options.html#name">‑name</a> • <a href="command-line-options.html#negate">‑negate</a> • <a href="command-line-options.html#noise">‑noise</a> • <a href="command-line-options.html#normalize">‑normalize</a> • <a href="command-line-options.html#opaque">‑opaque</a> • <a href="command-line-options.html#ordered-dither">‑ordered‑dither</a> • <a href="command-line-options.html#orient">‑orient</a> • <a href="command-line-options.html#page">‑page</a> • <a href="command-line-options.html#paint">‑paint</a> • <a href="command-line-options.html#path">‑path</a> • <a href="command-line-options.html#pause_animate_">‑pause[animate]</a> • <a href="command-line-options.html#pause_import_">‑pause[import]</a> • <a href="command-line-options.html#perceptible">‑perceptible</a> • <a href="command-line-options.html#ping">‑ping</a> • <a href="command-line-options.html#pointsize">‑pointsize</a> • <a href="command-line-options.html#polaroid">‑polaroid</a> • <a href="command-line-options.html#poly">‑poly</a> • <a href="command-line-options.html#posterize">‑posterize</a> • <a href="command-line-options.html#precision">‑precision</a> • <a href="command-line-options.html#preview">‑preview</a> • <a href="command-line-options.html#print">‑print</a> • <a href="command-line-options.html#process">‑process</a> • <a href="command-line-options.html#profile">‑profile</a> • <a href="command-line-options.html#quality">‑quality</a> • <a href="command-line-options.html#quantize">‑quantize</a> • <a href="command-line-options.html#quiet">‑quiet</a> • <a href="command-line-options.html#radial-blur">‑radial‑blur</a> • <a href="command-line-options.html#raise">‑raise</a> • <a href="command-line-options.html#random-threshold">‑random‑threshold</a> • <a href="command-line-options.html#red-primary">‑red‑primary</a> • <a href="command-line-options.html#regard-warnings">‑regard‑warnings</a> • <a href="command-line-options.html#region">‑region</a> • <a href="command-line-options.html#remap">‑remap</a> • <a href="command-line-options.html#remote">‑remote</a> • <a href="command-line-options.html#render">‑render</a> • <a href="command-line-options.html#repage">‑repage</a> • <a href="command-line-options.html#resample">‑resample</a> • <a href="command-line-options.html#resize">‑resize</a> • <a href="command-line-options.html#respect-parentheses">‑respect‑parentheses</a> • <a href="command-line-options.html#reverse">‑reverse</a> • <a href="command-line-options.html#roll">‑roll</a> • <a href="command-line-options.html#rotate">‑rotate</a> • <a href="command-line-options.html#sample">‑sample</a> • <a href="command-line-options.html#sampling-factor">‑sampling‑factor</a> • <a href="command-line-options.html#scale">‑scale</a> • <a href="command-line-options.html#scene">‑scene</a> • <a href="command-line-options.html#screen">‑screen</a> • <a href="command-line-options.html#seed">‑seed</a> • <a href="command-line-options.html#segment">‑segment</a> • <a href="command-line-options.html#selective-blur">‑selective‑blur</a> • <a href="command-line-options.html#separate">‑separate</a> • <a href="command-line-options.html#sepia-tone">‑sepia‑tone</a> • <a href="command-line-options.html#set">‑set</a> • <a href="command-line-options.html#shade">‑shade</a> • <a href="command-line-options.html#shadow">‑shadow</a> • <a href="command-line-options.html#shared-memory">‑shared‑memory</a> • <a href="command-line-options.html#sharpen">‑sharpen</a> • <a href="command-line-options.html#shave">‑shave</a> • <a href="command-line-options.html#shear">‑shear</a> • <a href="command-line-options.html#sigmoidal-contrast">‑sigmoidal‑contrast</a> • <a href="command-line-options.html#silent">‑silent</a> • <a href="command-line-options.html#similarity-threshold">‑similarity‑threshold</a> • <a href="command-line-options.html#size">‑size</a> • <a href="command-line-options.html#sketch">‑sketch</a> • <a href="command-line-options.html#smush">‑smush</a> • <a href="command-line-options.html#snaps">‑snaps</a> • <a href="command-line-options.html#solarize">‑solarize</a> • <a href="command-line-options.html#sparse-color">‑sparse‑color</a> • <a href="command-line-options.html#splice">‑splice</a> • <a href="command-line-options.html#spread">‑spread</a> • <a href="command-line-options.html#statistic">‑statistic</a> • <a href="command-line-options.html#stegano">‑stegano</a> • <a href="command-line-options.html#stereo">‑stereo</a> • <a href="command-line-options.html#storage-type">‑storage‑type</a> • <a href="command-line-options.html#stretch">‑stretch</a> • <a href="command-line-options.html#strip">‑strip</a> • <a href="command-line-options.html#stroke">‑stroke</a> • <a href="command-line-options.html#strokewidth">‑strokewidth</a> • <a href="command-line-options.html#style">‑style</a> • <a href="command-line-options.html#subimage-search">‑subimage‑search</a> • <a href="command-line-options.html#swap">‑swap</a> • <a href="command-line-options.html#swirl">‑swirl</a> • <a href="command-line-options.html#synchronize">‑synchronize</a> • <a href="command-line-options.html#taint">‑taint</a> • <a href="command-line-options.html#text-font">‑text‑font</a> • <a href="command-line-options.html#texture">‑texture</a> • <a href="command-line-options.html#threshold">‑threshold</a> • <a href="command-line-options.html#thumbnail">‑thumbnail</a> • <a href="command-line-options.html#tile">‑tile</a> • <a href="command-line-options.html#tile-offset">‑tile‑offset</a> • <a href="command-line-options.html#tint">‑tint</a> • <a href="command-line-options.html#title">‑title</a> • <a href="command-line-options.html#transform">‑transform</a> • <a href="command-line-options.html#transparent">‑transparent</a> • <a href="command-line-options.html#transparent-color">‑transparent‑color</a> • <a href="command-line-options.html#transpose">‑transpose</a> • <a href="command-line-options.html#transverse">‑transverse</a> • <a href="command-line-options.html#treedepth">‑treedepth</a> • <a href="command-line-options.html#trim">‑trim</a> • <a href="command-line-options.html#type">‑type</a> • <a href="command-line-options.html#undercolor">‑undercolor</a> • <a href="command-line-options.html#unique-colors">‑unique‑colors</a> • <a href="command-line-options.html#units">‑units</a> • <a href="command-line-options.html#unsharp">‑unsharp</a> • <a href="command-line-options.html#update">‑update</a> • <a href="command-line-options.html#verbose">‑verbose</a> • <a href="command-line-options.html#version">‑version</a> • <a href="command-line-options.html#view">‑view</a> • <a href="command-line-options.html#vignette">‑vignette</a> • <a href="command-line-options.html#virtual-pixel">‑virtual‑pixel</a> • <a href="command-line-options.html#visual">‑visual</a> • <a href="command-line-options.html#watermark">‑watermark</a> • <a href="command-line-options.html#wave">‑wave</a> • <a href="command-line-options.html#wavelet-denoise">‑wavelet‑denoise</a> • <a href="command-line-options.html#weight">‑weight</a> • <a href="command-line-options.html#white-point">‑white‑point</a> • <a href="command-line-options.html#white-threshold">‑white‑threshold</a> • <a href="command-line-options.html#window">‑window</a> • <a href="command-line-options.html#window-group">‑window‑group</a> • <a href="command-line-options.html#write">‑write</a> </p> 56 57<p class="lead magick-description">Below is list of command-line options recognized by the ImageMagick <a href="command-line-tools.html">command-line tools</a>. If you want a description of a particular option, click on the option name in the navigation bar above and you will go right to it. Unless otherwise noted, each option is recognized by the commands: <a href="convert.html">convert</a> and <a href="mogrify.html">mogrify</a>.</p> 58 59<div style="margin: auto;"> 60 <h3 class="magick-header"><a id="adaptive-blur"></a>-adaptive-blur <var>radius</var>[x<var>sigma</var>]</h3> 61</div> 62 63<p class="magick-description">Adaptively blur pixels, with decreasing effect near edges.</p> 64 65<p>A Gaussian operator of the given radius and standard deviation (<var>sigma</var>) is used. If <var>sigma</var> is not given it 66defaults to 1.</p> 67 68<div style="margin: auto;"> 69 <h3 class="magick-header"><a id="adaptive-resize"></a>-adaptive-resize <var>geometry</var></h3> 70</div> 71 72<p class="magick-description">Resize the image using data-dependent triangulation.</p> 73 74<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <a href="command-line-options.html#adaptive-resize">-adaptive-resize</a> 75option defaults to data-dependent triangulation. Use the <a 76href="command-line-options.html#filter">-filter</a> to choose a different resampling algorithm. 77Offsets, if present in the geometry string, are ignored, and the <a 78href="command-line-options.html#gravity">-gravity</a> option has no effect.</p> 79 80<div style="margin: auto;"> 81 <h3 class="magick-header"><a id="adaptive-sharpen"></a>-adaptive-sharpen <var>radius</var>[x<var>sigma</var>]</h3> 82</div> 83 84<p class="magick-description">Adaptively sharpen pixels, with increasing effect near edges.</p> 85 86<p>A Gaussian operator of the given radius and standard deviation 87(<var>sigma</var>) is used. If <var>sigma</var> is not given it 88defaults to 1.</p> 89 90<div style="margin: auto;"> 91 <h3 class="magick-header"><a id="adjoin"></a>-adjoin</h3> 92</div> 93 94<p class="magick-description">Join images into a single multi-image file.</p> 95 96<p>This option is enabled by default. An attempt is made to save all images of 97an image sequence into the given output file. However, some formats, such as 98JPEG and PNG, do not support more than one image per file, and in that case 99ImageMagick is forced to write each image as a separate file. As such, if 100more than one image needs to be written, the filename given is modified by 101adding a <a href="command-line-options.html#scene">-scene</a> number before the suffix, in order to 102make distinct names for each image. </p> 103 104<p>Use <a href="command-line-options.html#adjoin">+adjoin</a> to force each image to be written to 105separate files, whether or not the file format allows multiple images per file 106(for example, GIF, MIFF, and TIFF). </p> 107 108<p>Including a C-style integer format string in the output filename will 109automagically enable <a href="command-line-options.html#adjoin">+adjoin</a> and are used to specify 110where the <a href="command-line-options.html#scene">-scene</a> number is placed in the filenames. These 111strings, such as '<code>%d</code>' or '<code>%03d</code>', are familiar to those 112who have used the standard <code>printf()</code>' C-library function. As an 113example, the command</p> 114 115<pre> 116convert logo: rose: -morph 15 my%02dmorph.jpg 117</pre> 118 119<p>will create a sequence of 17 images (the two given plus 15 more created by 120<a href="command-line-options.html#morph">-morph</a>), named: my00morph.jpg, my01morph.jpg, 121my02morph.jpg, ..., my16morph.jpg. </p> 122 123<p>In summary, ImageMagick tries to write all images to one file, but will 124save to multiple files, if any of the following conditions exist...</p> 125<ol> 126<li>the output image's file format does not allow multi-image files,</li> 127<li>the <a href="command-line-options.html#adjoin">+adjoin</a> option is given, or</li> 128<li>a printf() integer format string (eg: "%d") is present in the output 129 filename.</li> 130</ol> 131 132 133<div style="margin: auto;"> 134 <h3 class="magick-header"><a id="affine"></a>-affine 135 <var>s<sub>x</sub></var>,<var>r<sub>x</sub></var>,<var>r<sub>y</sub></var>,<var>s<sub>y</sub></var>[,<var>t<sub>x</sub></var>,<var>t<sub>y</sub></var>]</h3> 136</div> 137 138<p class="magick-description">Set the drawing transformation matrix for combined rotating and scaling.</p> 139 140<p>This option sets a transformation matrix, for use by subsequent <a 141href="command-line-options.html#draw">-draw</a> or <a href="command-line-options.html#transform">-transform</a> options. </p> 142 143<p>The matrix entries are entered as comma-separated numeric values either in 144quotes or without spaces. </p> 145 146<p>Internally, the transformation matrix has 3x3 elements, but three of them 147are omitted from the input because they are constant. The new (transformed) 148coordinates (<var>x'</var>, <var>y'</var>) of a pixel at 149position (<var>x</var>, <var>y</var>) in the original 150image are calculated using the following matrix equation.</p> 151 152<p class="text-center"><img class="img-thumbnail" alt="affine transformation" src="/images/affine.png"/> </p> 153 154<p> The size of the resulting image is that of the smallest rectangle that 155contains the transformed source image. The parameters 156<var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> 157subsequently shift the image pixels so that those that are moved out of the 158image area are cut off.</p> 159 160<p>The transformation matrix complies with the left-handed pixel coordinate 161system: positive <var>x</var> and <var>y</var> directions 162are rightward and downward, resp.; positive rotation is clockwise.</p> 163 164<p> If the translation coefficients <var>t<sub>x</sub></var> and 165<var>t<sub>y</sub></var> are omitted they default to 0,0. Therefore, 166four parameters suffice for rotation and scaling without translation.</p> 167 168<p>Scaling by the factors <var>s<sub>x</sub></var> and 169<var>s<sub>y</sub></var> in the <var>x</var> and <var>y</var> directions, 170respectively, is accomplished with the following.</p> 171 172<p>See <a href="command-line-options.html#transform">-transform</a>, and the <a 173href="command-line-options.html#distort">-distort</a> method '<code>Affineprojection</code> for more 174information </p> 175 176 177<pre> 178-affine <var>s<sub>x</sub></var>,0,0,<var>s<sub>y</sub></var> 179</pre> 180 181<p>Translation by a displacement (<var>t<sub>x</sub></var>, <var>t<sub>y</sub></var>) is accomplished like so:</p> 182 183<pre> 184-affine 1,0,0,1,<var>t<sub>x</sub></var>,<var>t<sub>y</sub></var> 185</pre> 186 187<p>Rotate clockwise about the origin (the upper left-hand corner) by an angle 188<var>a</var> by letting <var>c</var> = cos(<var>a</var>), <var>s</var> 189= sin(<var>a</var>), and using the following.</p> 190 191<pre> 192-affine <var>c</var>,<var>s</var>,-<var>s</var>,<var>c</var> 193</pre> 194 195<p>The cumulative effect of a sequence of <a href="command-line-options.html#affine" >-affine</a> 196transformations can be accomplished by instead by a single <a href="command-line-options.html#affine" 197>-affine</a> operation using the matrix equal to the product of the matrices 198of the individual transformations.</p> 199 200<p>An attempt is made to detect near-singular transformation matrices. If the 201matrix determinant has a sufficiently small absolute value it is rejected.</p> 202 203<div style="margin: auto;"> 204 <h3 class="magick-header"><a id="alpha"></a>-alpha <var>type</var></h3> 205</div> 206 207<p class="magick-description">Gives control of the alpha/matte channel of an image.</p> 208 209<p>Used to set a flag on an image indicating whether or not to use existing alpha 210channel data, to create an alpha channel, or to perform other operations on the alpha channel. Choose the argument <var>type</var> from the list below.</p> 211 212<dl class="dl-horizontal"> 213 <dt>Activate</dt> 214 <dd> 215 Enable the image's transparency channel. Note normally Set 216 should be used instead of this, unless you specifically need to 217 preserve existing (but specifically turned Off) transparency 218 channel. </dd> 219 220 <dt>Associate</dt> 221 <dd> 222 associate the alpha channel with the image.</dd> 223 224 <dt>Deactivate</dt> 225 <dd> 226 Disables the image's transparency channel. Does not delete or change the 227 existing data, just turns off the use of that data.</dd> 228 229 <dt>Disassociate</dt> 230 <dd> 231 disassociate the alpha channel from the image.</dd> 232 233 <dt>Set</dt> 234 <dd> 235 Activates the alpha/matte channel. If it was previously turned off 236 then it also resets the channel to opaque. If the image already had 237 the alpha channel turned on, it will have no effect.</dd> 238 239 <dt>Opaque</dt> 240 <dd> 241 Enables the alpha/matte channel and forces it to be fully opaque. 242 </dd> 243 244 <dt>Transparent</dt> 245 <dd> 246 Activates the alpha/matte channel and forces it to be fully 247 transparent. This effectively creates a fully transparent image the 248 same size as the original and with all its original RGB data still 249 intact, but fully transparent. </dd> 250 251 <dt>Extract</dt> 252 <dd> 253 Copies the alpha channel values into all the color channels and turns 254 'Off' the the image's transparency, so as to generate 255 a grayscale mask of the image's shape. The alpha channel data is left 256 intact just deactivated. This is the inverse of 'Copy'. 257 </dd> 258 259 <dt>Copy</dt> 260 <dd> 261 Turns 'On' the alpha/matte channel, then copies the 262 grayscale intensity of the image, into the alpha channel, converting 263 a grayscale mask into a transparent shaped mask ready to be colored 264 appropriately. The color channels are not modified. </dd> 265 266 <dt>Shape</dt> 267 <dd> 268 As per 'Copy' but also colors the resulting shape mask with 269 the current background color. That is the RGB color channels is 270 replaced, with appropriate alpha shape. 271 </dd> 272 273 <dt>Remove</dt> 274 <dd> 275 Composite the image over the background color. 276 </dd> 277 278 <dt>Background</dt> 279 <dd> 280 Set any fully-transparent pixel to the background color, while leaving 281 it fully-transparent. This can make some image file formats, such as 282 PNG, smaller as the RGB values of transparent pixels are more uniform, 283 and thus can compress better. 284 </dd> 285</dl> 286 287<p>Note that while the obsolete <code>+matte</code> operation was the 288same as "<code><a href="command-line-options.html#alpha" >-alpha</a> Off</code>", the <code> 289>-matte</code> operation was the same as "<code><a href="command-line-options.html#alpha" >-alpha</a> 290Set</code>" and not "<code><a href="command-line-options.html#alpha" >-alpha</a> On</code>". </p> 291 292<div style="margin: auto;"> 293 <h3 class="magick-header"><a id="alpha-color"></a>-alpha-color <var>color</var></h3> 294</div> 295 296<p class="magick-description">Specify the color to be used with the <a href="command-line-options.html#frame">-frame</a> option.</p> 297 298<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 299 300<p>The default matte color is <code>#BDBDBD</code>, <span 301style="background-color: #bdbdbd;">this shade of gray</span>.</p> 302 303<p>This is an IMv7 option, use <a href="command-line-options.html#mattecolor">mattecolor</a> with IMv6.</p> 304 305 306<div style="margin: auto;"> 307 <h3 class="magick-header"><a id="annotate"></a> 308 -annotate <var>degrees</var> <var>text</var><br /> 309 -annotate <var>Xdegrees</var>x<var>Ydegrees</var> <var>text</var><br /> -annotate <var>Xdegrees</var>x<var>Ydegrees</var> {+-}<var>t<sub>x</sub></var>{+-}<var>t<sub>y</sub></var> <var>text</var><br /> -annotate {+-}<var>t<sub>x</sub></var>{+-}<var>t<sub>y</sub></var> <var>text</var></h3> 310</div> 311 312<p class="magick-description">Annotate an image with text</p> 313 314<p>This is a convenience for annotating an image with text. For more precise 315control over text annotations, use <a href="command-line-options.html#draw">-draw</a>.</p> 316 317 318<p>The values <var>Xdegrees</var> and <var>Ydegrees</var> 319control the shears applied to the text, while <var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> are offsets that give the location of the text relative any <a href="command-line-options.html#gravity" >-gravity</a> setting and defaults to the upper left corner of the image.</p> 320 321<p>Using <a href="command-line-options.html#annotate">-annotate</a> <var>degrees</var> 322or <a href="command-line-options.html#annotate">-annotate</a> <var>degrees</var>x<var>degrees</var> produces an unsheared rotation of the text. The 323direction of the rotation is positive, which means a clockwise rotation if <var>degrees</var> is positive. (This conforms to the usual mathematical 324convention once it is realized that the positive <var>y</var>–direction is 325conventionally considered to be <var>downward</var> for images.)</p> 326 327<p>The new (transformed) coordinates (<var>x'</var>, <var>y'</var>) of a pixel at position (<var>x</var>, <var>y</var>) in the image are calculated using the following matrix 328equation.</p> 329 330<p class="text-center"><img class="img-thumbnail" alt="annotate transformation" src="/images/annotate.png"/></p> 331 332<p>If <var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> are omitted, they default to 0. This makes the 333bottom-left of the text becomes the upper-left corner of the image, which is 334probably undesirable. Adding a <a href="command-line-options.html#gravity" >-gravity</a> option in this 335case leads to nice results.</p> 336 337<p>Text is any UTF-8 encoded character sequence. If <var>text</var> 338is of the form '@mytext.txt', the text is read from the file 339<code>mytext.txt</code>. Text in a file is taken literally; no embedded 340formatting characters are recognized.</p> 341 342<div style="margin: auto;"> 343 <h3 class="magick-header"><a id="antialias"></a>-antialias</h3> 344</div> 345 346<p class="magick-description">Enable/Disable of the rendering of anti-aliasing pixels when drawing fonts and lines.</p> 347 348<p>By default, objects (e.g. text, lines, polygons, etc.) are antialiased when 349drawn. Use <a href="command-line-options.html#antialias">+antialias</a> to disable the addition of 350antialiasing edge pixels. This will then reduce the number of colors added to 351an image to just the colors being directly drawn. That is, no mixed colors 352are added when drawing such objects. </p> 353 354<div style="margin: auto;"> 355 <h3 class="magick-header"><a id="append"></a>-append</h3> 356</div> 357 358<p class="magick-description">Join current images vertically or horizontally.</p> 359 360<p>This option creates a single longer image, by joining all the current 361images in sequence top-to-bottom. Use <a href="command-line-options.html#append">+append</a> to 362stack images left-to-right. </p> 363 364<p>If they are not of the same width, narrower images are padded with the 365current <a href="command-line-options.html#background">-background</a> color setting, and their 366position relative to each other can be controlled by the current <a 367href="command-line-options.html#gravity">-gravity</a> setting. </p> 368 369 370<div style="margin: auto;"> 371 <h3 class="magick-header"><a id="attenuate"></a>-attenuate <var>value</var></h3> 372</div> 373 374<p class="magick-description">Lessen (or intensify) when adding noise to an image.</p> 375 376<p>If unset the value is equivalent to 1.0, or a maximum noise addition</p> 377 378<div style="margin: auto;"> 379 <h3 class="magick-header"><a id="authenticate"></a>-authenticate <var>password</var></h3> 380</div> 381 382<p class="magick-description">Decrypt a PDF with a password.</p> 383 384<p>Use this option to supply a <var>password</var> for decrypting 385a PDF that has been encrypted using Microsoft Crypto API (MSC API). The 386encrypting using the MSC API is not supported.</p> 387 388<p>For a different encryption method, see <a href="command-line-options.html#encipher">-encipher</a> 389and <a href="command-line-options.html#decipher">-decipher</a>. </p> 390 391 392<div style="margin: auto;"> 393 <h3 class="magick-header"><a id="auto-gamma"></a>-auto-gamma</h3> 394</div> 395 396<p class="magick-description">Automagically adjust gamma level of image.</p> 397 398<p>This calculates the mean values of an image, then applies a calculated <a 399href="command-line-options.html#gamma" >-gamma</a> adjustment so that is the mean color exists in the 400image it will get a have a value of 50%. </p> 401 402<p>This means that any solid 'gray' image becomes 50% gray. </p> 403 404<p>This works well for real-life images with little or no extreme dark and 405light areas, but tend to fail for images with large amounts of bright sky or 406dark shadows. It also does not work well for diagrams or cartoon like images. 407</p> 408 409<p>It uses the <a href="command-line-options.html#channel" >-channel</a> setting, (including the 410'<var>sync</var>' flag for channel synchronization), to determine which color 411values is used and modified. As the default <a href="command-line-options.html#channel" 412>-channel</a> setting is '<var>RGB,sync</var>', channels are modified 413together by the same gamma value, preserving colors. </p> 414 415 416 417<div style="margin: auto;"> 418 <h3 class="magick-header"><a id="auto-level"></a>-auto-level</h3> 419</div> 420 421<p class="magick-description">Automagically adjust color levels of image.</p> 422 423<p>This is a 'perfect' image normalization operator. It finds the exact 424minimum and maximum color values in the image and then applies a <a 425href="command-line-options.html#level" >-level</a> operator to stretch the values to the full range of 426values. </p> 427 428<p>The operator is not typically used for real-life images, image scans, or 429JPEG format images, as a single 'out-rider' pixel can set a bad min/max values 430for the <a href="command-line-options.html#level" >-level</a> operation. On the other hand it is the 431right operator to use for color stretching gradient images being used to 432generate Color lookup tables, distortion maps, or other 'mathematically' 433defined images. </p> 434 435<p>The operator is very similar to the <a href="command-line-options.html#normalize">-normalize</a>, <a 436href="command-line-options.html#contrast-stretch" >-contrast-stretch</a>, and <a href="command-line-options.html#linear-stretch" 437>-linear-stretch</a> operators, but without 'histogram binning' or 'clipping' 438problems that these operators may have. That is <a href="command-line-options.html#auto-level" 439>-auto-level</a> is the perfect or ideal version these operators. </p> 440 441<p>It uses the <a href="command-line-options.html#channel" >-channel</a> setting, (including the 442special '<var>sync</var>' flag for channel synchronization), to determine 443which color values are used and modified. As the default <a 444href="command-line-options.html#channel" >+channel</a> setting is '<var>RGB,sync</var>', the 445'<var>sync</var>' ensures that the color channels will are modified 446together by the same gamma value, preserving colors, and ignoring 447transparency. </p> 448 449 450<div style="margin: auto;"> 451 <h3 class="magick-header"><a id="auto-orient"></a>-auto-orient</h3> 452</div> 453 454<p class="magick-description">adjusts an image so that its orientation is suitable for viewing (i.e. top-left orientation).</p> 455 456<p>This operator reads and resets the EXIF image profile setting 'Orientation' 457and then performs the appropriate 90 degree rotation on the image to orient 458the image, for correct viewing. </p> 459 460<p>This EXIF profile setting is usually set using a gravity sensor in digital 461camera, however photos taken directly downward or upward may not have an 462appropriate value. Also images that have been orientation 'corrected' without 463reseting this setting, may be 'corrected' again resulting in a incorrect 464result. If the EXIF profile was previously stripped, the <a 465href="command-line-options.html#auto-orient" >-auto-orient</a> operator will do nothing. </p> 466 467 468<div style="margin: auto;"> 469 <h3 class="magick-header"><a id="average"></a>-average</h3> 470</div> 471 472<p class="magick-description">Average a set of images.</p> 473 474<p>An error results if the images are not identically sized.</p> 475 476 477<div style="margin: auto;"> 478 <h3 class="magick-header"><a id="backdrop"></a>-backdrop</h3> 479</div> 480 481<p class="magick-description">Display the image centered on a backdrop.</p> 482 483<p>This backdrop covers the entire workstation screen and is useful for hiding 484other X window activity while viewing the image. The color of the backdrop is 485specified as the background color. The color is specified using the format 486described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 487 488<div style="margin: auto;"> 489 <h3 class="magick-header"><a id="background"></a>-background <var>color</var></h3> 490</div> 491 492<p class="magick-description">Set the background color.</p> 493 494<p>The color is specified using the format described under the <a 495href="command-line-options.html#fill">-fill</a> option. The default background color (if none is 496specified or found in the image) is white.</p> 497 498<div style="margin: auto;"> 499 <h3 class="magick-header"><a id="bench"></a>-bench <var>iterations</var></h3> 500</div> 501 502<p class="magick-description">Measure performance.</p> 503 504<p>Repeat the entire command for the given number of <var>iterations</var> and report the user-time and elapsed time. For instance, 505consider the following command and its output. Modify the benchmark with the 506-duration to run the benchmark for a fixed number of seconds and -concurrent 507to run the benchmark in parallel (requires the OpenMP feature).</p> 508 509<pre> 510-> convert logo: -resize 200% -bench 5 logo.png 511Performance[1]: 5i 1.344ips 1.000e 3.710u 0:03.720 512Performance[2]: 5i 1.634ips 0.549e 3.890u 0:03.060 513Performance[3]: 5i 2.174ips 0.618e 3.190u 0:02.300 514Performance[4]: 5i 1.678ips 0.555e 3.810u 0:02.980 515Performance[4]: 5i 0.875657ips 6.880u 0:05.710 516</pre> 517 518<p>In this example, 5 iterations were completed at 2.174 iterations per 519second, using 3 threads and 3.190 seconds of the user allotted time, for 520a total elapsed time of 2.300 seconds.</p> 521 522<div style="margin: auto;"> 523 <h3 class="magick-header"><a id="bias"></a>-bias <var>value</var>{<var>%</var>}</h3> 524</div> 525 526<p class="magick-description">Add bias when convolving an image.</p> 527 528<p>This option shifts the output of <a href="command-line-options.html#convolve">‑convolve</a> so that 529positive and negative results are relative to the specified bias value. </p> 530 531<p>This is important for non-HDRI compilations of ImageMagick when dealing 532with convolutions that contain negative as well as positive values. This is 533especially the case with convolutions involving high pass filters or edge 534detection. Without an output bias, the negative values are clipped at 535zero.</p> 536 537<p>When using an ImageMagick with the HDRI compile-time setting, <a href="command-line-options.html#bias">‑bias</a> is not needed, as ImageMagick is able to store/handle any 538negative results without clipping to the color value range 539(0..QuantumRange).</p> 540 541<p>See the discussion on HDRI implementations of ImageMagick on the page <a 542href="high-dynamic-range.html" >High Dynamic-Range Images</a>. For more 543about HDRI go the ImageMagick <a 544href="http://www.imagemagick.org/Usage/basics/#hdri" >Usage</a> pages or this 545<a 546href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> 547entry. </p> 548 549<div style="margin: auto;"> 550 <h3 class="magick-header"><a id="black-point-compensation"></a>-black-point-compensation</h3> 551</div> 552 553<p class="magick-description">Use black point compensation.</p> 554 555<div style="margin: auto;"> 556 <h3 class="magick-header"><a id="black-threshold"></a>-black-threshold <var>value</var>{<var>%</var>}</h3> 557</div> 558 559<p class="magick-description">Force to black all pixels below the threshold while leaving all pixels at or above the threshold unchanged.</p> 560 561<p> The threshold value can be given as a percentage or as an absolute integer 562value within [0, <var>QuantumRange</var>] corresponding to the 563desired <a href="command-line-options.html#channel">‑channel</a> value. See <a href="command-line-options.html#threshold">‑threshold</a>for more details on thresholds and resulting values. </p> 564 565 566<div style="margin: auto;"> 567 <h3 class="magick-header"><a id="blend"></a>-blend <var>geometry</var></h3> 568</div> 569 570<p class="magick-description">blend an image into another by the given absolute value or percent.</p> 571 572<p>Blend will average the images together ('plus') according to the 573percentages given and each pixels transparency. If only a single percentage 574value is given it sets the weight of the composite or 'source' image, while 575the background image is weighted by the exact opposite amount. That is a 576<code>-blend 30%</code> merges 30% of the 'source' image with 70% of the 577'destination' image. Thus it is equivalent to <code>-blend 30x70%</code>.</p> 578 579 580<div style="margin: auto;"> 581 <h3 class="magick-header"><a id="blue-primary"></a>-blue-primary <var>x</var>,<var>y</var></h3> 582</div> 583 584<p class="magick-description">Set the blue chromaticity primary point.</p> 585 586<div style="margin: auto;"> 587 <h3 class="magick-header"><a id="blue-shift"></a>-blue-shift <var>factor</var></h3> 588</div> 589 590<p class="magick-description">simulate a scene at nighttime in the moonlight. Start with a factor of 1.5</p> 591 592<div style="margin: auto;"> 593 594<div style="margin: auto;"> 595 <h3 class="magick-header"><a id="blur"></a>-blur <var>radius</var><br />-blur <var>radius</var>x<var>sigma</var></h3> 596</div> 597 598<p class="magick-description">Reduce image noise and reduce detail levels.</p> 599 600<p>Convolve the image with a Gaussian or normal distribution using the given 601<var >Sigma</var> value. The formula is:</p> 602 603<p class="text-center"><img class="img-thumbnail" alt="gaussian distribution" width="243px" height="42px" src="/images/gaussian-blur.png"/></p> 604 605<p>The <var >Sigma</var> value is the important argument, and 606determines the actual amount of blurring that will take place. </p> 607 608<p>The <var >Radius</var> is only used to determine the size of the 609array which will hold the calculated Gaussian distribution. It should be an 610integer. If not given, or set to zero, IM will calculate the largest possible 611radius that will provide meaningful results for the Gaussian distribution. 612</p> 613 614<p>The larger the <var >Radius</var> the slower the 615operation is. However too small a <var >Radius</var>, and sever 616aliasing effects may result. As a guideline, <var >Radius</var> 617should be at least twice the <var >Sigma</var> value, though three 618times will produce a more accurate result. </p> 619 620<p>This option differs from <a href="command-line-options.html#gaussian-blur">-gaussian-blur</a> simply 621by taking advantage of the separability properties of the distribution. Here 622we apply a single-dimensional Gaussian matrix in the horizontal direction, 623then repeat the process in the vertical direction.</p> 624 625<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 626pixels which are outside the image proper are blurred into the final result. 627</p> 628 629 630<div style="margin: auto;"> 631 <h3 class="magick-header">-blur <var>Width</var>[x<var>Height</var>[+<var>Angle</var>]]</h3> 632</div> 633 634<p class="magick-description">Variably blur an image according to the overlay mapping.</p> 635 636<p>Each pixel in the overlaid region is replaced with an Elliptical Weighted 637Average (EWA) of the source image, scaled according to the grayscale 638mapping. </p> 639 640<p>The ellipse is weighted with sigma set to the given <var>Width</var> and <var >Height</var>. The <var >Height</var> 641defaults to the <var >Width</var> for a normal circular Gaussian 642weighting. The <var >Angle</var> will rotate the ellipse from 643horizontal clock-wise. </p> 644 645<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 646pixels which are outside the image proper are blurred into the final result. 647</p> 648 649 650<div style="margin: auto;"> 651 <h3 class="magick-header"><a id="border"></a>-border <var>geometry</var></h3> 652</div> 653 654<p class="magick-description">Surround the image with a border of color. </p> 655 656<p>Set the width and height using the <var>size</var> portion of the 657<var>geometry</var> argument. See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets are 658ignored. </p> 659 660<p>As of IM 6.7.8-8, the <var>geometry</var> arguments behave as follows:</p> 661 662<dl class="dl-horizontal"> 663<dt><var>value</var></dt> 664<dd>value is added to both left/right and top/bottom</dd> 665<dt><var>value-x</var><kbd>x</kbd></dt> 666<dd>value-x is added only to left/right and top/bottom are unchanged</dd> 667<dt><kbd>x</kbd><var>value-y</var></dt> 668<dd>value-y is added only to top/bottom and left/right are unchanged</dd> 669<dt><var>value-x</var><kbd>x</kbd><var>value-y</var></dt> 670<dd>value-x is added to left/right and value-y added to top/bottom</dd> 671<dt><var>value-x</var><kbd>x</kbd>0</dt> 672<dd>value-x is added only to left/right and top/bottom are unchanged</dd> 673<dt>0<kbd>x</kbd><var>value-y</var></dt> 674<dd>value-y is added only to top/bottom and left/right are unchanged</dd> 675<dt><var>value</var>%</dt> 676<dd>value % of width is added to left/right and value % of height is added to top/bottom</dd> 677<dt><var>value-x</var><kbd>x</kbd>%</dt> 678<dd>value-x % of width is added to left/right and to top/bottom</dd> 679<dt>x<var>value-y</var>%</dt> 680<dd>value-y % of height is added to top/bottom and to left/right</dd> 681<dt><var>value-x</var>%<kbd>x</kbd><var>value-y</var>%</dt> 682<dd>value-x % of width is added to left/right and value-y % of height is added to top/bottom</dd> 683<dt><var>value-x</var>%<kbd>x</kbd>0%</dt> 684<dd>value-x % of width is added to left/right and top/bottom are unchanged</dd> 685<dt>0%<kbd>x</kbd><var>value-y</var>%</dt> 686<dd>value-y % of height is added to top/bottom and left/right are unchanged</dd> 687</dl> 688 689<p>Set the border color by preceding with the <a 690href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p> 691 692<p>The <a href="command-line-options.html#border">-border</a> operation is affected by the current <a 693href="command-line-options.html#compose">-compose</a> setting and assumes that this is using the default 694'<code>Over</code>' composition method. It generates an image of the appropriate 695size colors by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> before 696overlaying the original image in the center of this net image. This means that 697with the default compose method of '<code>Over</code>' any transparent parts may 698be replaced by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p> 699<p>See also the <a href="command-line-options.html#frame">-frame</a> option, which has more 700functionality.</p> 701 702<div style="margin: auto;"> 703 <h3 class="magick-header"><a id="bordercolor"></a>-bordercolor <var>color</var></h3> 704</div> 705 706<p class="magick-description">Set the border color.</p> 707 708<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 709 710<p>The default border color is <code>#DFDFDF</code>, <span style="background-color: #dfdfdf;">this shade of gray</span>.</p> 711 712<div style="margin: auto;"> 713 <h3 class="magick-header"><a id="borderwidth"></a>-borderwidth <var>geometry</var> </h3> 714</div> 715 716<p class="magick-description">Set the border width.</p> 717 718<div style="margin: auto;"> 719 <h3 class="magick-header"><a id="brightness-contrast"></a>-brightness-contrast <var>brightness</var><br />-brightness-contrast <var>brightness</var>{x<var>contrast</var>}{<var>%</var>}</h3> 720</div> 721 722<p class="magick-description">Adjust the brightness and/or contrast of the image.</p> 723 724<p>Brightness and Contrast values apply changes to the input image. They are 725not absolute settings. A brightness or contrast value of zero means no change. 726The range of values is -100 to +100 on each. Positive values increase the 727brightness or contrast and negative values decrease the brightness or contrast. 728To control only contrast, set the brightness=0. To control only brightness, 729set contrast=0 or just leave it off.</p> 730 731<p>You may also use <a href="command-line-options.html#fill">-channel</a> to control which channels to 732apply the brightness and/or contrast change. The default is to apply the same 733transformation to all channels.</p> 734 735<p>Brightness and Contrast arguments are converted to offset and slope of a 736linear transform and applied 737using <a href="command-line-options.html#fill">-function polynomial "slope,offset"</a>.</p> 738 739<p>The slope varies from 0 at contrast=-100 to almost vertical at 740contrast=+100. For brightness=0 and contrast=-100, the result are totally 741midgray. For brightness=0 and contrast=+100, the result will approach but 742not quite reach a threshold at midgray; that is the linear transformation 743is a very steep vertical line at mid gray.</p> 744 745<p>Negative slopes, i.e. negating the image, are not possible with this 746function. All achievable slopes are zero or positive.</p> 747 748<p>The offset varies from -0.5 at brightness=-100 to 0 at brightness=0 to +0.5 749at brightness=+100. Thus, when contrast=0 and brightness=100, the result is 750totally white. Similarly, when contrast=0 and brightness=-100, the result is 751totally black.</p> 752 753<p>As the range of values for the arguments are -100 to +100, adding the '%' 754symbol is no different than leaving it off.</p> 755 756<div style="margin: auto;"> 757 <h3 class="magick-header"><a id="cache"></a>-cache <var>threshold</var></h3> 758</div> 759 760<p class="magick-description">(This option has been replaced by the <a href='command-line-options.html#limit'>-limit</a> option).</p> 761 762<div style="margin: auto;"> 763 <h3 class="magick-header"><a id="canny"></a>-canny <var>radius</var><br/>-canny <var>radius</var>x<var>sigma</var>{<var>+lower-percent</var>}{<var>+upper-percent</var>}</h3> 764</div> 765 766<p class="magick-description">Canny edge detector uses a multi-stage algorithm to detect a wide range of edges in the image.</p> 767 768<p>The thresholds range from 0 to 100% (e.g. -canny 0x1+10%+30%) with {<var>+lower-percent</var>} < {<var>+upper-percent</var>}. If {<var>+upper-percent</var>} is increased but {<var>+lower-percent</var>} remains the same, lesser edge components will be detected, but their lengths will be the same. If {<var>+lower-percent</var>} is increased but {<var>+upper-percent</var>} is the same, the same number of edge components will be detected but their lengths will be shorter. The default thresholds are shown. The <var>radius</var>x<var>sigma</var> controls a gaussian blur applied to the input image to reduce noise and smooth the edges.</p> 769 770<div style="margin: auto;"> 771 <h3 class="magick-header"><a id="caption"></a>-caption <var>string</var></h3> 772</div> 773 774<p class="magick-description">Assign a caption to an image.</p> 775 776<p>This option sets the caption meta-data of an image read in after this 777option has been given. To modify a caption of images already in memory use 778"<code><a href="command-line-options.html#set">-set</a> caption</code>". </p> 779 780<p>The caption can contain special format characters listed in the <a 781href="escape.html">Format and 782Print Image Properties</a>. These attributes are expanded when the caption 783is finally assigned to the individual images. </p> 784 785<p>If the first character of <var>string</var> is <var>@</var>, the image caption is read from a file titled by the 786remaining characters in the string. Comments read in from a file are literal; 787no embedded formatting characters are recognized.</p> 788 789<p>Caption meta-data is not visible on the image itself. To do that use the 790<a href="command-line-options.html#annotate">-annotate</a> or <a href="command-line-options.html#draw">-draw</a> options 791instead.</p> 792 793<p>For example,</p> 794 795<pre> 796-caption "%m:%f %wx%h" bird.miff 797</pre> 798 799<p>produces an image caption of <code>MIFF:bird.miff 512x480</code> (assuming 800that the image <code>bird.miff</code> has a width of 512 and a height of 801480.</p> 802 803 804<div style="margin: auto;"> 805 <h3 class="magick-header"><a id="cdl"></a>-cdl <var>filename</var></h3> 806</div> 807 808<p class="magick-description">color correct with a color decision list.</p> 809 810<p>Here is an example color correction collection:</p> 811 812<pre> 813<?xml version="1.0" encoding="UTF-8"?> 814<ColorCorrectionCollection xmlns="urn:ASC:CDL:v1.2"> 815 <ColorCorrection id="cc06668"> 816 <SOPNode> 817 <Slope> 0.9 1.2 0.5 </Slope> 818 <Offset> 0.4 -0.5 0.6 </Offset> 819 <Power> 1.0 0.8 1.5 </Power> 820 </SOPNode> 821 <SATNode> 822 <Saturation> 0.85 </Saturation> 823 </SATNode> 824 </ColorCorrection> 825</ColorCorrectionCollection> 826</pre> 827 828<div style="margin: auto;"> 829 <h3 class="magick-header"><a id="channel"></a>-channel <var>type</var></h3> 830</div> 831 832<p class="magick-description">Specify those image color channels to which subsequent operators are limited.</p> 833 834<p>Choose from: <code>Red</code>, <code>Green</code>, <code>Blue</code>, 835<code>Alpha</code>, <code>Gray</code>, <code>Cyan</code>, <code>Magenta</code>, 836<code>Yellow</code>, <code>Black</code>, <code>Opacity</code>, 837<code>Index</code>, <code>RGB</code>, <code>RGBA</code>, <code>CMYK</code>, or 838<code>CMYKA</code>.</p> 839 840<p>The channels above can also be specified as a comma-separated list or can be 841abbreviated as a concatenation of the letters '<code>R</code>', '<code>G</code>', 842'<code>B</code>', '<code>A</code>', '<code>O</code>', '<code>C</code>', 843'<code>M</code>', '<code>Y</code>', '<code>K</code>'. 844 845For example, to only select the <code>Red</code> and <code>Blue</code> channels 846you can either use </p> 847<pre> 848-channel Red,Blue 849</pre> 850<p>or you can use the short hand form</p> 851<pre> 852-channel RB 853</pre> 854 855<p>All the channels that are present in an image can be specified using the 856special channel type <code>All</code>. Not all operators are 'channel capable', 857but generally any operators that are generally 'grey-scale' image operators, 858will understand this setting. See individual operator documentation. </p> 859 860<br/> 861 862<p>On top of the normal channel selection an extra flag can be specified, 863'<code>Sync</code>'. This is turned on by default and if set means that 864operators that understand this flag should perform: cross-channel 865synchronization of the channels. If not specified, then most grey-scale 866operators will apply their image processing operations to each individual 867channel (as specified by the rest of the <a href="command-line-options.html#channel">-channel</a> 868setting) completely independently from each other. </p> 869 870<p>For example for operators such as <a href="command-line-options.html#auto-level">-auto-level</a> and 871<a href="command-line-options.html#auto-gamma">-auto-gamma</a> the color channels are modified 872together in exactly the same way so that colors will remain in-sync. Without 873it being set, then each channel is modified separately and 874independently, which may produce color distortion. </p> 875 876<p>The <a href="command-line-options.html#morphology">-morphology</a> '<code>Convolve</code>' method 877and the <a href="command-line-options.html#compose">-compose</a> mathematical methods, also understands 878the '<code>Sync</code>' flag to modify the behavior of pixel colors according 879to the alpha channel (if present). That is to say it will modify the image 880processing with the understanding that fully-transparent colors should not 881contribute to the final result. </p> 882 883<p>Basically, by default, operators work with color channels in synchronous, and 884treats transparency as special, unless the <a href="command-line-options.html#channel">-channel</a> 885setting is modified so as to remove the effect of the '<code>Sync</code>' flag. 886How each operator does this depends on that operators current implementation. 887Not all operators understands this flag at this time, but that is changing. 888</p> 889 890<p>To print a complete list of channel types, use <a href="command-line-options.html#list">-list 891channel</a>.</p> 892 893<p>By default, ImageMagick sets <a href="command-line-options.html#channel">-channel</a> to the value 894'<code>RGBK,sync</code>', which specifies that operators act on all color 895channels except the transparency channel, and that all the color channels are 896to be modified in exactly the same way, with an understanding of transparency 897(depending on the operation being applied). The 'plus' form <a 898href="command-line-options.html#channel" >+channel</a> will reset the value back to this default. </p> 899 900<p>Options that are affected by the <a href="command-line-options.html#channel" >-channel</a> setting 901include the following. 902 903<a href="command-line-options.html#auto-gamma">-auto-gamma</a>, 904<a href="command-line-options.html#auto-level">-auto-level</a>, 905<a href="command-line-options.html#black-threshold">-black-threshold</a>, 906<a href="command-line-options.html#blur">-blur</a>, 907<a href="command-line-options.html#clamp">-clamp</a>, 908<a href="command-line-options.html#clut">-clut</a>, 909<a href="command-line-options.html#combine">-combine</a>, 910<a href="command-line-options.html#composite">-composite</a> (Mathematical compose methods only), 911<a href="command-line-options.html#convolve">-convolve</a>, 912<a href="command-line-options.html#contrast-stretch">-contrast-stretch</a>, 913<a href="command-line-options.html#evaluate">-evaluate</a>, 914<a href="command-line-options.html#function">-function</a>, 915<a href="command-line-options.html#fx">-fx</a>, 916<a href="command-line-options.html#gaussian-blur">-gaussian-blur</a>, 917<a href="command-line-options.html#hald-clut">-hald-clut</a>, 918<a href="command-line-options.html#motion-blur">-motion-blur</a>, 919<a href="command-line-options.html#morphology">-morphology</a>, 920<a href="command-line-options.html#negate">-negate</a>, 921<a href="command-line-options.html#normalize">-normalize</a>, 922<a href="command-line-options.html#ordered-dither">-ordered-dither</a>, 923<a href="command-line-options.html#radial-blur">-radial-blur</a>, 924<a href="command-line-options.html#random-threshold">-random-threshold</a>, 925<a href="command-line-options.html#separate">-separate</a>, 926<a href="command-line-options.html#threshold">-threshold</a>, and 927<a href="command-line-options.html#white-threshold">-white-threshold</a>. 928</p> 929 930<p>Warning, some operators behave differently when the <a href="command-line-options.html#channel" 931>+channel</a> default setting is in effect, verses ANY user defined <a 932href="command-line-options.html#channel" >-channel</a> setting (including the equivalent of the 933default). These operators have yet to be made to understand the newer 'Sync' 934flag. </p> 935 936<p>For example <a href="command-line-options.html#threshold">-threshold</a> will by default grayscale 937the image before thresholding, if no <a href="command-line-options.html#channel" >-channel</a> setting 938has been defined. This is not 'Sync flag controlled, yet. </p> 939 940<p>Also some operators such as <a href="command-line-options.html#blur">-blur</a>, <a 941href="command-line-options.html#gaussian-blur">-gaussian-blur</a>, will modify their handling of the 942color channels if the '<code>alpha</code>' channel is also enabled by <a 943href="command-line-options.html#channel" >-channel</a>. Generally this done to ensure that 944fully-transparent colors are treated as being fully-transparent, and thus any 945underlying 'hidden' color has no effect on the final results. Typically 946resulting in 'halo' effects. The newer <a href="command-line-options.html#morphology">-morphology</a> 947convolution equivalents however does have a understanding of the 'Sync' flag 948and will thus handle transparency correctly by default. </p> 949 950<p>As a alpha channel is optional within images, some operators will read the 951color channels of an image as a greyscale alpha mask, when the image has no 952alpha channel present, and the <a href="command-line-options.html#channel" >-channel</a> setting tells 953the operator to apply the operation using alpha channels. The <a 954href="command-line-options.html#clut">-clut</a> operator is a good example of this. </p> 955 956 957 958<div style="margin: auto;"> 959 <h3 class="magick-header"><a id="charcoal"></a>-charcoal <var>factor</var></h3> 960</div> 961 962<p class="magick-description">Simulate a charcoal drawing.</p> 963 964<div style="margin: auto;"> 965 <h3 class="magick-header"><a id="chop"></a>-chop <var>geometry</var></h3> 966</div> 967 968<p class="magick-description">Remove pixels from the interior of an image.</p> 969 970<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <var>width</var> 971and <var>height</var> given in the of the <var>size</var> 972portion of the <var>geometry</var> argument give the number of 973columns and rows to remove. The <var>offset</var> portion of 974the <var>geometry</var> argument is influenced by 975a <a href="command-line-options.html#gravity">-gravity</a> setting, if present.</p> 976 977<p>The <a href="command-line-options.html#chop">-chop</a> option removes entire rows and columns, 978and moves the remaining corner blocks leftward and upward to close the gaps.</p> 979 980<p>While it can remove internal rows and columns of pixels, it is more 981typically used with as <a href="command-line-options.html#gravity">-gravity</a> setting and zero 982offsets so as to remove a single edge from an image. Compare this to <a 983href="command-line-options.html#shave" >-shave</a> which removes equal numbers of pixels from opposite 984sides of the image. </p> 985 986<p>Using <a href="command-line-options.html#chop">-chop</a> effectively undoes the results of a <a 987href="command-line-options.html#splice">-splice</a> that was given the same <var>geometry</var> and <a href="command-line-options.html#gravity">-gravity</a> settings. </p> 988 989<div style="margin: auto;"> 990 <h3 class="magick-header"><a id="clamp"></a>-clamp</h3> 991</div> 992 993<p class="magick-description">set each pixel whose value is below zero to zero and any the pixel whose value is above the quantum range to the quantum range (e.g. 65535) otherwise the pixel value remains unchanged.</p> 994 995<div style="margin: auto;"> 996 <h3 class="magick-header"><a id="clip"></a>-clip</h3> 997</div> 998 999<p class="magick-description">Apply the clipping path if one is present.</p> 1000 1001<p>If a clipping path is present, it is applied to subsequent operations.</p> 1002 1003<p>For example, in the command</p> 1004 1005<pre> 1006convert cockatoo.tif -clip -negate negated.tif 1007</pre> 1008 1009<p>only the pixels within the clipping path are negated.</p> 1010 1011<p>The <a href="command-line-options.html#clip">-clip</a> feature requires SVG support. If the SVG 1012delegate library is not present, the option is ignored.</p> 1013 1014<p>Use <a href="command-line-options.html#clip">+clip</a> to disable clipping for subsequent operations.</p> 1015 1016<div style="margin: auto;"> 1017 <h3 class="magick-header"><a id="clip-mask"></a>-clip-mask</h3> 1018</div> 1019 1020<p class="magick-description">Clip the image as defined by this mask.</p> 1021 1022<p>Use the alpha channel of the current image as a mask. Any areas that is 1023white is not modified by any of the 'image processing operators' that follow, 1024until the mask is removed. Pixels in the black areas of the clip mask are 1025modified per the requirements of the operator. </p> 1026 1027<p>In some ways this is similar to (though not the same) as defining 1028a rectangular <a href="command-line-options.html#region" >-region</a>, or using the negative of the 1029mask (third) image in a three image <a href="command-line-options.html#composite" >-composite</a>, 1030operation. </p> 1031 1032<p>Use <a href="command-line-options.html#clip-mask">+clip-mask</a> to disable clipping for subsequent operations.</p> 1033 1034<div style="margin: auto;"> 1035 <h3 class="magick-header"><a id="clip-path"></a>-clip-path <var>id</var></h3> 1036</div> 1037 1038<p class="magick-description">Clip along a named path from the 8BIM profile.</p> 1039 1040<p>This is identical to <a href="command-line-options.html#clip">-clip</a> except choose a specific clip path in the event the image has more than one path available. </p> 1041 1042<p>Use <a href="command-line-options.html#clip-path">+clip-path</a> to disable clipping for subsequent operations.</p> 1043 1044<div style="margin: auto;"> 1045 <h3 class="magick-header"><a id="clone"></a>-clone <var>index(s)</var></h3> 1046</div> 1047 1048<p class="magick-description">make a clone of an image (or images).</p> 1049 1050<p>Inside parenthesis (where the operator is normally used) it will make a 1051clone of the images from the last 'pushed' image sequence, and adds them to 1052the end of the current image sequence. Outside parenthesis 1053(not recommended) it clones the images from the current image sequence. </p> 1054 1055<p>Specify the image by its index in the sequence. The first image is index 10560. Negative indexes are relative to the end of the sequence; for 1057example, <code>−1</code> 1058represents the last image of the sequence. Specify a range of images with a 1059dash (e.g. <code>0−4</code>). Separate multiple indexes with commas but no 1060spaces (e.g. <code>0,2,5</code>). A value of '<code>0−−1</code> will 1061effectively clone all the images. </p> 1062 1063<p>The <a href="command-line-options.html#clone">+clone</a> will simply make a copy of the last image 1064in the image sequence, and is thus equivalent to using a argument of 1065'<code>−1</code>'. </p> 1066 1067<div style="margin: auto;"> 1068 <h3 class="magick-header"><a id="clut"></a>-clut</h3> 1069</div> 1070 1071<p class="magick-description">Replace the channel values in the first image using each corresponding channel in the second image as a <b>c</b>olor <b>l</b>ook<b>u</b>p <b>t</b>able.</p> 1072 1073<p>The second (LUT) image is ordinarily a gradient image containing the 1074histogram mapping of how each channel should be modified. Typically it is a 1075either a single row or column image of replacement color values. If larger 1076than a single row or column, values are taken from a diagonal line from 1077top-left to bottom-right corners.</p> 1078 1079<p>The lookup is further controlled by the <a 1080href="command-line-options.html#interpolate">-interpolate</a> setting, which is especially handy for an 1081LUT which is not the full length needed by the ImageMagick installed Quality 1082(Q) level. Good settings for this are the '<code>bilinear</code>' and 1083'<code>bicubic</code>' interpolation settings, which give smooth color 1084gradients, and the '<code>integer</code>' setting for a direct, unsmoothed 1085lookup of color values. </p> 1086 1087<p>This operator is especially suited to replacing a grayscale image with a 1088specific color gradient from the CLUT image. </p> 1089 1090<p>Only the channel values defined by the <a href="command-line-options.html#channel">-channel</a> 1091setting will have their values replaced. In particular, since the default <a 1092href="command-line-options.html#channel">-channel</a> setting is <code>RGB</code>, this means that 1093transparency (alpha/matte channel) is not affected, unless the <a 1094href="command-line-options.html#channel">-channel</a> setting is modified. When the alpha channel is 1095set, it is treated by the <a href="command-line-options.html#clut" >-clut</a> operator in the same way 1096as the other channels, implying that alpha/matte values are replaced using the 1097alpha/matte values of the original image. </p> 1098 1099<p>If either the image being modified, or the lookup image, contains no 1100transparency (i.e. <a href="command-line-options.html#alpha" >-alpha</a> is turned 'off') but the <a 1101href="command-line-options.html#channel">-channel</a> setting includes alpha replacement, then it is 1102assumed that image represents a grayscale gradient which is used for the 1103replacement alpha values. That is you can use a grayscale CLUT image to 1104adjust a existing images alpha channel, or you can color a grayscale image 1105using colors form CLUT containing the desired colors, including transparency. 1106</p> 1107 1108<p>See also <a href="command-line-options.html#hald-clut" >-hald-clut</a> which replaces colors 1109according to the lookup of the full color RGB value from a 2D representation 1110of a 3D color cube. </p> 1111 1112 1113<div style="margin: auto;"> 1114 <h3 class="magick-header"><a id="coalesce"></a>-coalesce</h3> 1115</div> 1116 1117<p class="magick-description">Fully define the look of each frame of an GIF animation sequence, to form a 'film strip' animation.</p> 1118 1119<p>Overlay each image in an image sequence according to 1120its <a href="command-line-options.html#dispose">-dispose</a> meta-data, to reproduce the look of 1121an animation at each point in the animation sequence. All images should be 1122the same size, and are assigned appropriate GIF disposal settings for the 1123animation to continue working as expected as a GIF animation. Such frames 1124are more easily viewed and processed than the highly optimized GIF overlay 1125images. </p> 1126 1127<p>The animation can be re-optimized after processing using 1128the <a href="command-line-options.html#layers">-layers</a> method '<code>optimize</code>', although 1129there is no guarantee that the restored GIF animation optimization is 1130better than the original. </p> 1131 1132 1133<div style="margin: auto;"> 1134 <h3 class="magick-header"><a id="colorize"></a>-colorize <var>value</var></h3> 1135</div> 1136 1137<p class="magick-description">Colorize the image by an amount specified by <var>value</var> using the color specified by the most recent <a href="command-line-options.html#fill" >-fill</a> setting.</p> 1138 1139<p>Specify the amount of colorization as a percentage. Separate colorization 1140values can be applied to the red, green, and blue channels of the image with 1141a comma-delimited list of colorization 1142values (e.g., <code>-colorize 0,0,50</code>).</p> 1143 1144<div style="margin: auto;"> 1145 <h3 class="magick-header"><a id="colormap"></a>-colormap <var>type</var></h3> 1146</div> 1147 1148<p class="magick-description">Define the colormap type.</p> 1149 1150<p>The <var>type</var> can be <code>shared</code> or <code>private</code>.</p> 1151 1152<p>This option only applies when the default X server visual 1153is <code>PseudoColor</code> or <code>GrayScale</code>. Refer 1154to <a href="command-line-options.html#visual">-visual</a> for more details. By default, 1155a shared colormap is allocated. The image shares colors with 1156other X clients. Some image colors could be approximated, 1157therefore your image may look very different than intended. 1158If <code>private</code> is chosen, the image colors appear exactly 1159as they are defined. However, other clients may go <var>technicolor</var> 1160when the image colormap is installed.</p> 1161 1162<div style="margin: auto;"> 1163 <h3 class="magick-header"><a id="colors"></a>-colors <var>value</var></h3> 1164</div> 1165 1166<p class="magick-description">Set the preferred number of colors in the image.</p> 1167 1168<p>The actual number of colors in the image may be less than your request, 1169but never more. Note that this a color reduction option. Images with fewer 1170unique colors than specified by <var>value</var> will have any 1171duplicate or unused colors removed. The ordering of an existing color 1172palette may be altered. When converting an image from color to grayscale, 1173it is more efficient to convert the image to the gray colorspace before 1174reducing the number of colors. Refer to 1175the <a href="quantize.html"> 1176color reduction algorithm</a> for more details.</p> 1177 1178<div style="margin: auto;"> 1179 <h3 class="magick-header"><a id="color-matrix"></a>-color-matrix <var>matrix</var></h3> 1180</div> 1181 1182<p class="magick-description">apply color correction to the image.</p> 1183 1184<p>This option permits saturation changes, hue rotation, luminance to alpha, 1185and various other effects. Although variable-sized transformation matrices 1186can be used, typically one uses a 5x5 matrix for an RGBA image and a 6x6 1187for CMYKA (or RGBA with offsets). The matrix is similar to those used by 1188Adobe Flash except offsets are in column 6 rather than 5 (in support of 1189CMYKA images) and offsets are normalized (divide Flash offset by 255).</p> 1190 1191<p>As an example, to add contrast to an image with offsets, try this command:</p> 1192 1193<pre> 1194convert kittens.jpg -color-matrix \ 1195 " 1.5 0.0 0.0 0.0, 0.0, -0.157 \ 1196 0.0 1.5 0.0 0.0, 0.0, -0.157 \ 1197 0.0 0.0 1.5 0.0, 0.0, -0.157 \ 1198 0.0 0.0 0.0 1.0, 0.0, 0.0 \ 1199 0.0 0.0 0.0 0.0, 1.0, 0.0 \ 1200 0.0 0.0 0.0 0.0, 0.0, 1.0" kittens.png 1201</pre> 1202<div style="margin: auto;"> 1203 <h3 class="magick-header"><a id="colorspace"></a>-colorspace <var>value</var></h3> 1204</div> 1205 1206<p class="magick-description">Set the image colorspace.</p> 1207 1208<p>Choices are:</p> 1209 1210<pre> 1211CMY CMYK Gray HCL 1212HCLp HSB HSI HSL 1213HSV HWB Lab LCHab 1214LCHuv LMS Log Luv 1215OHTA Rec601YCbCr Rec709YCbCr RGB 1216scRGB sRGB Transparent xyY 1217XYZ YCbCr YCC YDbDr 1218YIQ YPbPr YUV 1219</pre> 1220 1221<p>To print a complete list of colorspaces, use <a href="command-line-options.html#list">-list colorspace</a>.</p> 1222 1223<p>For a more accurate color conversion to or from the linear RGB, CMYK, or grayscale colorspaces, use the <a href="command-line-options.html#profile">-profile</a> option. Note, ImageMagick assumes the sRGB colorspace if the image format does not indicate otherwise. For colorspace conversion, the gamma function is first removed to produce linear RGB.</p> 1224 1225<table class="table table-condensed table-striped"> 1226 <caption>Conversion of RGB to Other Color Spaces</caption> 1227 <tr><th valign="middle">CMY</th></tr> 1228 <tr><td valign="middle">C=<var>QuantumRange</var>−R</td></tr> 1229 <tr><td valign="middle">M=<var>QuantumRange</var>−G</td></tr> 1230 <tr><td valign="middle">Y=<var>QuantumRange</var>−B</td></tr> 1231 <tr><th valign="middle">CMYK — starts with CMY from above</th></tr> 1232 <tr><td valign="middle">K=min(C,Y,M)</td></tr> 1233 <tr><td valign="middle">C=<var>QuantumRange</var>*(C−K)/(<var>QuantumRange</var>−K)</td></tr> 1234 <tr><td valign="middle">M=<var>QuantumRange</var>*(M−K)/(<var>QuantumRange</var>−K)</td></tr> 1235 <tr><td valign="middle">Y=<var>QuantumRange</var>*(Y−K)/(<var>QuantumRange</var>−K)</td></tr> 1236 1237 <tr><th valign="middle">Gray</th></tr> 1238 <tr><td valign="middle">Gray = 0.298839*R+0.586811*G+0.114350*B</td></tr> 1239 1240 <tr><th valign="middle">HSB — Hue, Saturation, Brightness; like a cone peak downward</th></tr> 1241 <tr><td valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr> 1242 <tr><td valign="middle">S=distance from axis outward</td></tr> 1243 <tr><td valign="middle">B=distance along axis from bottom upward; B=max(R,G,B); <var>intensity-like</var></td></tr> 1244 1245 <tr><th valign="middle">HSL — Hue, Saturation, Lightness; like a double cone end-to-end with peaks at very top and bottom</th></tr> 1246 <tr><td valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr> 1247 <tr><td valign="middle">S=distance from axis outward</td></tr> 1248 <tr><td valign="middle">L=distance along axis from bottom upward; L=0.5*max(R,G,B) + 0.5*min(R,G,B); <var>intensity-like</var></td></tr> 1249 1250 <tr><th valign="middle">HWB — Hue, Whiteness, Blackness</th></tr> 1251 <tr><td valign="middle">Hue (complicated equation)</td></tr> 1252 <tr><td valign="middle">Whiteness (complicated equation)</td></tr> 1253 <tr><td valign="middle">Blackness (complicated equation)</td></tr> 1254 1255 <tr><th valign="middle">LAB</th></tr> 1256 <tr><td valign="middle">L (complicated equation relating X,Y,Z)</td></tr> 1257 <tr><td valign="middle">A (complicated equation relating X,Y,Z)</td></tr> 1258 <tr><td valign="middle">B (complicated equation relating X,Y,Z)</td></tr> 1259 1260 <tr><th valign="middle">LOG</th></tr> 1261 <tr><td valign="middle">I1 (complicated equation involving logarithm of R)</td></tr> 1262 <tr><td valign="middle">I2 (complicated equation involving logarithm of G)</td></tr> 1263 <tr><td valign="middle">I3 (complicated equation involving logarithm of B)</td></tr> 1264 1265 <tr><th valign="middle">OHTA — approximates principal components transformation</th></tr> 1266 <tr><td valign="middle">I1=0.33333*R+0.33334*G+0.33333*B; <var>intensity-like</var></td></tr> 1267 <tr><td valign="middle">I2=(0.50000*R+0.00000*G−0.50000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1268 <tr><td valign="middle">I3=(−0.25000*R+0.50000*G−0.25000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1269 1270 <tr><th valign="middle">Rec601Luma</th></tr> 1271 <tr><td valign="middle">Gray = 0.298839*R+0.586811*G+0.114350*B</td></tr> 1272 1273 <tr><th valign="middle">Rec601YCbCr</th></tr> 1274 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1275 <tr><td valign="middle">Cb=(−0.168736*R-0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1276 <tr><td valign="middle">Cr=(0.500000*R−0.418688*G−0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1277 1278 <tr><th valign="middle">Rec709Luma</th></tr> 1279 <tr><td valign="middle">Gray=0.212656*R+0.715158*G+0.072186*B</td></tr> 1280 1281 <tr><th valign="middle">Rec709YCbCr</th></tr> 1282 <tr><td valign="middle">Y=0.212656*R+0.715158*G+0.072186*B; <var>intensity-like</var></td></tr> 1283 <tr><td valign="middle">Cb=(−0.114572*R−0.385428*G+0.500000*B)+(<var>QuantumRange</var>+1)/2</td></tr> 1284 <tr><td valign="middle">Cr=(0.500000*R−0.454153*G−0.045847*B)+(<var>QuantumRange</var>+1)/2</td></tr> 1285 1286 <tr><th valign="middle">sRGB</th></tr> 1287 <tr><td valign="middle">if R ≤ .0.0031308 then Rs=R/12.92 else Rs=1.055 R ^ (1.0 / 2.4) ? 0.055</td></tr> 1288 <tr><td valign="middle">if G ≤ .0.0031308 then Gs=B/12.92 else Gs=1.055 R ^ (1.0 / 2.4) ? 0.055</td></tr> 1289 <tr><td valign="middle">if B ≤ .0.0031308 then Bs=B/12.92 else Bs=1.055 R ^ (1.0 / 2.4) ? 0.055</td></tr> 1290 1291 <tr><th valign="middle">XYZ</th></tr> 1292 <tr><td valign="middle">X=0.4124564*R+0.3575761*G+0.1804375*B</td></tr> 1293 <tr><td valign="middle">Y=0.2126729*R+0.7151522*G+0.0721750*B</td></tr> 1294 <tr><td valign="middle">Z=0.0193339*R+0.1191920*G+0.9503041*B</td></tr> 1295 1296 <tr><th valign="middle">YCC</th></tr> 1297 <tr><td valign="middle">Y=(0.298839*R+0.586811*G+0.114350*B) (with complicated scaling); <var>intensity-like</var></td></tr> 1298 <tr><td valign="middle">C1=(−0.298839*R−0.586811*G+0.88600*B) (with complicated scaling)</td></tr> 1299 <tr><td valign="middle">C2=(0.70100*R−0.586811*G−0.114350*B) (with complicated scaling)</td></tr> 1300 1301 <tr><th valign="middle">YCbCr</th></tr> 1302 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1303 <tr><td valign="middle">Cb=(−0.168736*R−0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1304 <tr><td valign="middle">Cr=(0.500000*R−0.418688*G−0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1305 1306 <tr><th valign="middle">YIQ</th></tr> 1307 <tr><td valign="middle">Y=0.298839*R+0.586811*G+0.114350*B; <var>intensity-like</var></td></tr> 1308 <tr><td valign="middle">I=(0.59600*R−0.27400*G−0.32200*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1309 <tr><td valign="middle">Q=(0.21100*R−0.52300*G+0.31200*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1310 1311 <tr><th valign="middle">YPbPr</th></tr> 1312 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1313 <tr><td valign="middle">Pb=(−0.168736*R−0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1314 <tr><td valign="middle">Pr=(0.500000*R−0.418688*G−0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1315 1316 <tr><th valign="middle">YUV</th></tr> 1317 <tr><td valign="middle">Y=0.298839*R+0.586811*G+0.114350*B; <var>intensity-like</var></td></tr> 1318 <tr><td valign="middle">U=(−0.14740*R−0.28950*G+0.43690*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1319 <tr><td valign="middle">V=(0.61500*R−0.51500*G−0.10000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1320</table> 1321 1322<p>Note the scRGB colorspace requires HDRI support otherwise it behaves just like linear RGB.</p> 1323 1324<div style="margin: auto;"> 1325 <h3 class="magick-header"><a id="combine"></a>-combine</h3> 1326</div> 1327 1328<p class="magick-description">Combine one or more images into a single image.</p> 1329 1330<p>The channels (previously set by <a href="command-line-options.html#channel">-channel</a>) of the 1331combined image are taken from the grayscale values of each image in the 1332sequence, in order. For the default -channel setting of <code>RGB</code>, this 1333means the first image is assigned to the <code>Red</code> channel, the second 1334to the <code>Green</code> channel, the third to the <code>Blue</code>.</p> 1335 1336<p>This option can be thought of as the inverse to <a 1337href="command-line-options.html#separate">-separate</a>, so long as the channel settings are the same. 1338Thus, in the following example, the final image should be a copy of the 1339original. </p> 1340 1341<pre> 1342convert original.png -channel RGB -separate sepimage.png 1343convert sepimage-0.png sepimage-1.png sepimage-2.png -channel RGB \ 1344 -combine imagecopy.png 1345</pre> 1346 1347<div style="margin: auto;"> 1348 <h3 class="magick-header"><a id="comment"></a>-comment <var>string</var></h3> 1349</div> 1350 1351<p class="magick-description">Embed a comment in an image.</p> 1352 1353<p>This option sets the comment meta-data of an image read in after this 1354option has been given. To modify a comment of images already in memory use 1355"<code><a href="command-line-options.html#set">-set</a> comment</code>". </p> 1356 1357<p>The comment can contain special format characters listed in the <a 1358href="escape.html">Format and 1359Print Image Properties</a>. These attributes are expanded when the comment 1360is finally assigned to the individual images. </p> 1361 1362<p>If the first character of <var>string</var> is <var>@</var>, the image comment is read from a file titled by the 1363remaining characters in the string. Comments read in from a file are literal; 1364no embedded formatting characters are recognized.</p> 1365 1366<p>Comment meta-data are not visible on the image itself. To do that use the 1367<a href="command-line-options.html#annotate">-annotate</a> or <a href="command-line-options.html#draw">-draw</a> options 1368instead.</p> 1369 1370<p>For example,</p> 1371 1372<pre> 1373-comment "%m:%f %wx%h" bird.miff 1374</pre> 1375 1376<p>produces an image comment of <code>MIFF:bird.miff 512x480</code> (assuming 1377that the image <code>bird.miff</code> has a width of 512 and a height of 1378480.</p> 1379 1380<div style="margin: auto;"> 1381 <h3 class="magick-header"><a id="compare"></a>-compare</h3> 1382</div> 1383 1384<p class="magick-description">mathematically and visually annotate the difference between an image and its reconstruction</p> 1385 1386<p>This is a convert version of "<code>compare</code>" for two same sized images. The syntax is as follows, but other metrics are allowed.</p> 1387 1388<pre> 1389convert image.png reference.png -metric RMSE -compare \ <br/> difference.png 1390</pre> 1391 1392<p>To get the metric value use the string format "%[distortion]".</p> 1393 1394<pre> 1395convert image.png reference.png -metric RMSE -compare -format \ 1396 "%[distortion]" info: 1397</pre> 1398 1399<div style="margin: auto;"> 1400 <h3 class="magick-header"><a id="complex"></a>-complex <var>operator</var></h3> 1401</div> 1402 1403<p class="magick-description">perform complex mathematics on an image sequence</p> 1404 1405Choose from these operators: 1406 1407<pre> 1408add 1409conjugate 1410divide 1411magnitude-phase 1412multiply 1413real-imaginary 1414subtract 1415</pre> 1416 1417<p>Optionally specify the <code>divide</code> operator SNR with <code><a href="command-line-options.html#define">-define</a> complex:snr=float</code>.</p> 1418 1419<div style="margin: auto;"> 1420 <h3 class="magick-header"><a id="compose"></a>-compose <var>operator</var></h3> 1421</div> 1422 1423<p class="magick-description">Set the type of image composition.</p> 1424 1425<p>See <a href="compose.html">Alpha Compositing</a> for 1426a detailed discussion of alpha compositing.</p> 1427 1428<p>This setting effects image processing operators that merge two (or more) 1429images together in some way. This includes the operators, 1430<a href="command-line-options.html#composite">-compare</a>, 1431<a href="command-line-options.html#composite">-composite</a>, 1432<a href="command-line-options.html#layers">-layers</a> composite, 1433<a href="command-line-options.html#flatten">-flatten</a>, 1434<a href="command-line-options.html#mosaic">-mosaic</a>, 1435<a href="command-line-options.html#layers">-layers</a> merge, 1436<a href="command-line-options.html#border">-border</a>, 1437<a href="command-line-options.html#frame">-frame</a>, 1438and <a href="command-line-options.html#extent">-extent</a>. </p> 1439 1440<p>It is also one of the primary options for the "<code>composite</code>" 1441command. </p> 1442 1443 1444<div style="margin: auto;"> 1445 <h3 class="magick-header"><a id="composite"></a>-composite</h3> 1446</div> 1447 1448<p class="magick-description">Perform alpha composition on two images and an optional mask</p> 1449 1450<p>Take the first image 'destination' and overlay the second 'source' image 1451according to the current <a href="command-line-options.html#compose">-compose</a> setting. The location 1452of the 'source' or 'overlay' image is controlled according to <a 1453href="command-line-options.html#gravity" >-gravity</a>, and <a href="command-line-options.html#geometry" >-geometry</a> 1454settings. </p> 1455 1456<p>If a third image is given this is treated as a grayscale blending 'mask' image 1457relative to the first 'destination' image. This mask is blended with the 1458source image. However for the '<code>displace</code>' compose method, the 1459mask is used to provide a separate Y-displacement image instead. </p> 1460 1461<p>If a <a href="command-line-options.html#compose">-compose</a> method requires extra numerical 1462arguments or flags these can be provided by setting the <a 1463href="command-line-options.html#set">-set</a> '<code>option:compose:args</code>' 1464appropriately for the compose method. </p> 1465 1466<p>Some <a href="command-line-options.html#compose">-compose</a> methods can modify the 'destination' 1467image outside the overlay area. You can disable this by setting the special <a 1468href="command-line-options.html#set">-set</a> '<code>option:compose:outside-overlay</code>' 1469to '<code>false</code>'. </p> 1470 1471<p>The SVG compositing specification requires that color and opacity values range between zero and QuantumRange inclusive. You can permit values outside this range with this option: <a href="command-line-options.html#set">-set</a> '<code>option:compose:clamp=false</code></p> 1472 1473 1474<div style="margin: auto;"> 1475 <h3 class="magick-header"><a id="compress"></a>-compress <var>type</var></h3> 1476</div> 1477 1478<p class="magick-description">Use pixel compression specified by <var>type</var> when writing the image.</p> 1479 1480<p>Choices are: <code>None</code>, <code>BZip</code>, <code 1481>Fax</code>, <code>Group4</code>, <code 1482>JPEG</code>, <code>JPEG2000</code>, <code 1483>Lossless</code>, <code>LZW</code>, <code 1484>RLE</code> or <code>Zip</code>.</p> 1485 1486<p>To print a complete list of compression types, use <a href="command-line-options.html#list">-list 1487compress</a>.</p> 1488 1489<p>Specify <a href="command-line-options.html#compress">+compress</a> to store the binary image in an 1490uncompressed format. The default is the compression type of the specified 1491image file.</p> 1492 1493<p>If <code>LZW</code> compression is specified but LZW compression has not been 1494enabled, the image data is written in an uncompressed LZW format that can be 1495read by LZW decoders. This may result in larger-than-expected GIF files.</p> 1496 1497<p><code>Lossless</code> refers to lossless JPEG, which is only available if the 1498JPEG library has been patched to support it. Use of lossless JPEG is generally 1499not recommended.</p> 1500 1501<p> 1502When writing an ICO file, you may request that the images be encoded in 1503PNG format, by specifying <code>Zip</code> compression.</p> 1504 1505<p> 1506When writing a JNG file, specify <code>Zip</code> compression to request that 1507the alpha channel be encoded in PNG "IDAT" format, or <code>JPEG</code> 1508to request that it be encoded in JPG "JDAA" format.</p> 1509 1510<p>Use the <a href="command-line-options.html#quality">-quality</a> option to set the compression level 1511to be used by JPEG, PNG, MIFF, and MPEG encoders. 1512Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to set the 1513sampling factor to be used by JPEG, MPEG, and YUV encoders for down-sampling 1514the chroma channels.</p> 1515 1516<div style="margin: auto;"> 1517 <h3 class="magick-header"><a id="connected-components"></a>-connected-components <var>connectivity</var></h3> 1518</div> 1519 1520<p class="magick-description"><a href="connected-components.html">connected-components</a> labeling detects connected regions in an image, choose from 4 or 8 way connectivity.</p> 1521 1522<p>Use <code><a href="command-line-options.html#define" >-define</a> connected-components:verbose=true</code> to output statistics associated with each unique label.</p> 1523 1524<div style="margin: auto;"> 1525 <h3 class="magick-header"><a id="contrast"></a>-contrast</h3> 1526</div> 1527 1528<p class="magick-description">Enhance or reduce the image contrast.</p> 1529 1530<p>This option enhances the intensity differences between the lighter and 1531darker elements of the image. Use <a href="command-line-options.html#contrast">-contrast</a> to enhance 1532the image or <a href="command-line-options.html#contrast">+contrast</a> to reduce the image 1533contrast.</p> 1534 1535<p>For a more pronounced effect you can repeat the option:</p> 1536 1537<pre> 1538convert rose: -contrast -contrast rose_c2.png 1539</pre> 1540 1541<div style="margin: auto;"> 1542 <h3 class="magick-header"><a id="contrast-stretch"></a>-contrast-stretch <var>black-point</var><br />-contrast-stretch <var>black-point</var>{x<var>white-point</var>}{<var>%</var>}</h3> 1543</div> 1544 1545<p class="magick-description">Increase the contrast in an image by <var>stretching</var> the range of intensity values.</p> 1546 1547<p>While performing the stretch, black-out at most <var>black-point</var> pixels and white-out at most <var>white-point</var> pixels. Or, if percent is used, black-out at most 1548<var >black-point %</var> pixels and white-out at most <var>white-point %</var> pixels.</p> 1549 1550<p>Prior to ImageMagick 6.4.7-0, <a href="command-line-options.html#contrast-stretch" 1551>-contrast-stretch</a> will black-out at most <var>black-point</var> pixels and white-out at most <var >total pixels 1552minus white-point</var> pixels. Or, if percent is used, black-out at most <var>black-point %</var> pixels and white-out at most <var>100% minus white-point %</var> pixels.</p> 1553 1554<p>Note that <code>-contrast-stretch 0</code> will modify the image such that 1555the image's min and max values are stretched to 0 and <var>QuantumRange</var>, respectively, without any loss of data due to burn-out or 1556clipping at either end. This is not the same as <a href="command-line-options.html#normalize" 1557>-normalize</a>, which is equivalent to <code>-contrast-stretch 0.15x0.05%</code> (or 1558prior to ImageMagick 6.4.7-0, <code>-contrast-stretch 2%x99%</code>).</p> 1559 1560<p>Internally operator works by creating a histogram bin, and then uses that 1561bin to modify the image. As such some colors may be merged together when they 1562originally fell into the same 'bin'. </p> 1563 1564<p>All the channels are normalized in concert by the same amount so as to 1565preserve color integrity, when the default <a href="command-line-options.html#channel" >+channel</a> 1566setting is in use. Specifying any other <a href="command-line-options.html#channel" >-channel</a> 1567setting will normalize the RGB channels independently.</p> 1568 1569<p>See also <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' 1570normalization of mathematical images. </p> 1571 1572<p>This operator is under review for re-development. </p> 1573 1574 1575<div style="margin: auto;"> 1576 <h3 class="magick-header"><a id="convolve"></a>-convolve <var>kernel</var></h3> 1577</div> 1578 1579<p class="magick-description">Convolve an image with a user-supplied convolution kernel.</p> 1580 1581<p>The <var>kernel</var> is a matrix specified as 1582a comma-separated list of integers (with no spaces), ordered left-to right, 1583starting with the top row. Presently, only odd-dimensioned kernels are 1584supported, and therefore the number of entries in the specified <var>kernel</var> must be 3<sup>2</sup>=9, 5<sup>2</sup>=25, 15857<sup>2</sup>=49, etc. </p> 1586 1587<p>Note that the <a href="command-line-options.html#convolve">‑convolve</a> operator supports the <a href="command-line-options.html#bias">‑bias</a> setting. This option shifts the convolution so that 1588positive and negative results are relative to a user-specified bias value. 1589This is important for non-HDRI compilations of ImageMagick when dealing with 1590convolutions that contain negative as well as positive values. This is 1591especially the case with convolutions involving high pass filters or edge 1592detection. Without an output bias, the negative values is clipped at zero. 1593</p> 1594 1595<p>When using an ImageMagick with the HDRI compile-time setting, <a href="command-line-options.html#bias">‑bias</a> is not needed, as ImageMagick is able to store/handle any 1596negative results without clipping to the color value range (0..QuantumRange). 1597See the discussion on HDRI implementations of ImageMagick on the page <a 1598href="high-dynamic-range.html">High 1599Dynamic-Range Images</a>. For more about HDRI go the ImageMagick <a 1600href="http://www.imagemagick.org/Usage/basics/#hdri">Usage</a> pages or this 1601<a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> 1602entry. </p> 1603 1604 1605<div style="margin: auto;"> 1606 <h3 class="magick-header"><a id="copy"></a>-copy <var>geometry</var> <var>offset</var></h3> 1607</div> 1608 1609<p class="magick-description">copy pixels from one area of an image to another.</p> 1610 1611<div style="margin: auto;"> 1612 <h3 class="magick-header"><a id="crop"></a>-crop <var>geometry</var>{<var>@</var>}{<var>!</var>}</h3> 1613</div> 1614 1615<p class="magick-description">Cut out one or more rectangular regions of the image.</p> 1616 1617<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 1618 1619<p>The <var>width</var> and <var>height</var> of the <var>geometry</var> argument give the size of the image that remains 1620after cropping, and <var>x</var> and <var>y</var> in the 1621<var>offset</var> (if present) gives the location of the top left 1622corner of the cropped image with respect to the original image. To specify the 1623amount to be removed, use <a href="command-line-options.html#shave">-shave</a> instead.</p> 1624 1625<p>If the <var>x</var> and <var>y</var> offsets are 1626present, a single image is generated, consisting of the pixels from the 1627cropping region. The offsets specify the location of the upper left corner of 1628the cropping region measured downward and rightward with respect to the upper 1629left corner of the image. If the <a href="command-line-options.html#gravity">-gravity</a> option is 1630present with <code>NorthEast</code>, <code>East</code>, or <code>SouthEast</code> 1631gravity, it gives the distance leftward from the right edge of the image to 1632the right edge of the cropping region. Similarly, if the <a 1633href="command-line-options.html#gravity">-gravity</a> option is present with <code>SouthWest</code>, 1634<code>South</code>, or <code>SouthEast</code> gravity, the distance is measured 1635upward between the bottom edges.</p> 1636 1637<p>If the <var>x</var> and <var>y</var> offsets are 1638omitted, a set of tiles of the specified geometry, covering the entire input 1639image, is generated. The rightmost tiles and the bottom tiles are smaller if 1640the specified geometry extends beyond the dimensions of the input image.</p> 1641 1642<p>You can add the <var>@</var> to the geometry argument to equally divide the image into the number of tiles generated.</p> 1643 1644<p>By adding a exclamation character flag to the geometry argument, the 1645cropped images virtual canvas page size and offset is set as if the 1646geometry argument was a viewport or window. This means the canvas page size 1647is set to exactly the same size you specified, the image offset set 1648relative top left corner of the region cropped. </p> 1649 1650<p>If the cropped image 'missed' the actual image on its virtual canvas, a 1651special single pixel transparent 'missed' image is returned, and a 'crop 1652missed' warning given. </p> 1653 1654<p>It might be necessary to <a href="command-line-options.html#repage" >+repage</a> the image prior to 1655cropping the image to ensure the crop coordinate frame is relocated to the 1656upper-left corner of the visible image. 1657 1658Similarly you may want to use <a href="command-line-options.html#repage" >+repage</a> after cropping to 1659remove the page offset that will be left behind. This is especially true when 1660you are going to write to an image format such as PNG that supports an image 1661offset.</p> 1662 1663<div style="margin: auto;"> 1664 <h3 class="magick-header"><a id="cycle"></a>-cycle <var>amount</var></h3> 1665</div> 1666 1667<p class="magick-description">displace image colormap by amount.</p> 1668 1669<p><var>Amount</var> defines the number of positions each 1670colormap entry is shifted.</p> 1671 1672 1673<div style="margin: auto;"> 1674 <h3 class="magick-header"><a id="debug"></a>-debug <var>events</var></h3> 1675</div> 1676 1677<p class="magick-description">enable debug printout.</p> 1678 1679<p>The <code>events</code> parameter specifies which events are to be logged. It 1680can be either <code>None</code>, <code>All</code>, <code>Trace</code>, or 1681a comma-separated list consisting of one or more of the following domains: 1682<code>Accelerate</code>, <code>Annotate</code>, <code>Blob</code>, <code>Cache</code>, 1683<code>Coder</code>, <code>Configure</code>, <code>Deprecate</code>, 1684<code>Exception</code>, <code>Locale</code>, <code>Render</code>, 1685<code>Resource</code>, <code>Security</code>, <code>TemporaryFile</code>, 1686<code>Transform</code>, <code>X11</code>, or <code>User</code>. </p> 1687 1688 1689<p>For example, to log cache and blob events, use.</p> 1690 1691<pre> 1692convert -debug "Cache,Blob" rose: rose.png 1693</pre> 1694 1695<p>The <code>User</code> domain is normally empty, but developers can log user 1696events in their private copy of ImageMagick.</p> 1697 1698<p>To print the complete list of debug methods, use <a href="command-line-options.html#list">-list 1699debug</a>.</p> 1700 1701<p>Use the <a href="command-line-options.html#log">-log</a> option to specify the format for debugging 1702output.</p> 1703 1704<p>Use <a href="command-line-options.html#debug">+debug</a> to turn off all logging.</p> 1705 1706<p>Debugging may also be set using the <code>MAGICK_DEBUG</code> <a href="resources.html#environment" 1707>environment variable</a>. The allowed values for the <code>MAGICK_DEBUG</code> 1708environment variable are the same as for the <a href="command-line-options.html#debug">-debug</a> 1709option.</p> 1710 1711 1712<div style="margin: auto;"> 1713 <h3 class="magick-header"><a id="decipher"></a>-decipher <var>filename</var></h3> 1714</div> 1715 1716<p class="magick-description">Decipher and restore pixels that were previously transformed by <a href="command-line-options.html#encipher">-encipher</a>.</p> 1717 1718<p>Get the passphrase from the file specified by <var>filename</var>.</p> 1719 1720<p>For more information, see the webpage, <a 1721href="http://www.imagemagick.org/www/cipher.html">ImageMagick: Encipher or 1722Decipher an Image</a>.</p> 1723 1724 1725<div style="margin: auto;"> 1726 <h3 class="magick-header"><a id="deconstruct"></a>-deconstruct</h3> 1727</div> 1728 1729<p class="magick-description">find areas that has changed between images </p> 1730 1731<p>Given a sequence of images all the same size, such as produced by <a 1732href="command-line-options.html#coalesce">-coalesce</a>, replace the second and later images, with 1733a smaller image of just the area that changed relative to the previous image. 1734</p> 1735 1736<p>The resulting sequence of images can be used to optimize an animation 1737sequence, though will not work correctly for GIF animations when parts of the 1738animation can go from opaque to transparent. </p> 1739 1740<p>This option is actually equivalent to the <a href="command-line-options.html#layers">-layers</a> 1741method '<code>compare-any</code>'. </p> 1742 1743 1744<div style="margin: auto;"> 1745 <h3 class="magick-header"><a id="define"></a>-define <var>key</var>{<var>=value</var>}<var>...</var></h3> 1746</div> 1747 1748<p class="magick-description">add specific global settings generally used to control coders and image processing operations.</p> 1749 1750<p>This option creates one or more definitions for coders and decoders to use 1751while reading and writing image data. Definitions are generally used to 1752control image file format coder modules, and image processing operations, 1753beyond what is provided by normal means. Defined settings are listed in <a 1754href="command-line-options.html#verbose" >-verbose</a> information ("<code>info:</code>" output format) 1755as "Artifacts". </p> 1756 1757<p>If <var>value</var> is missing for a definition, an empty-valued 1758definition of a flag is created with that name. This used to control on/off 1759options. Use <a href="command-line-options.html#define">+define key</a> to remove definitions 1760previously created. Use <a href="command-line-options.html#define">+define "*"</a> to remove all 1761existing definitions.</p> 1762 1763<p>The same 'artifact' settings can also be defined using the <a 1764href="command-line-options.html#set" >-set "option:<var>key</var>" "<var>value</var>"</a> option, which also allows the use of <a href="escape.html" >Format and Print Image 1765Properties</a> in the defined value. </p> 1766 1767<p>The <var>option</var> and <var>key</var> are case-independent (they are 1768converted to lowercase for use within the decoders) while the <var>value</var> 1769is case-dependent.</p> 1770 1771<p>Such settings are global in scope, and affect all images and operations. </p> 1772 1773<p>The following definitions are just some of the artifacts that are 1774available:</p> 1775 1776<table class="table table-condensed table-striped"> 1777 <tr> 1778 <td>bmp:format=<var>value</var></td> 1779 <td> valid values are <var>bmp2</var>, <var>bmp3</var>, 1780 and <var>bmp4</var>. This option can be useful when the 1781 method of prepending "BMP2:" to the output filename is inconvenient or 1782 is not available, such as when using the <a href="mogrify.html">mogrify</a> utility.</td> 1783 </tr> 1784 1785 <tr> 1786 <td>colorspace:auto-grayscale=<var>on|off</var></td> 1787 <td>prevent automatic conversion to grayscale inside coders that support 1788 grayscale. This should be accompanied by -type truecolor. PNG and TIF do 1789 not need this define. With PNG, just use PNG24:image. With TIF, just use 1790 -type truecolor. JPG and PSD will need this define.</td> 1791 </tr> 1792 1793 <tr> 1794 <td>complex:snr=<var>value</var></td> 1795 <td>Set the divide SNR constant<a href="command-line-options.html#complex">-complex</a></td> 1796 </tr> 1797 1798 <tr> 1799 <td>compose:args=<var>arguments</var></td> 1800 <td>Sets certain compose argument values when using convert ... -compose ... 1801 -composite. See <a href="http://www.imagemagick.org/www/compose.html" 1802 >Image Composition</a></td> 1803 </tr> 1804 1805 <tr> 1806 <td>compose:clamp=<var>on|off</var></td> 1807 <td>set each pixel whose value is below zero to zero and any the pixel whose value is above the quantum range to the quantum range (e.g. 65535) otherwise the pixel value remains unchanged. Define supported in ImageMagick 6.9.1-3 and above.</td> 1808 </tr> 1809 1810 <tr> 1811 <td>connected-components:area-threshold=<var>value</var></td> 1812 <td>Merges any region with area smaller than <var>value</var> into its surrounding region or largest neighbor.</td> 1813 </tr> 1814 1815 <tr> 1816 <td>connected-components:keep=<var>list-of-ids</var></td> 1817 <td>Command and/or hyphenated list of id values to keep in the output. Supported in Imagemagick 6.9.3-0.</td> 1818 </tr> 1819 1820 <tr> 1821 <td>connected-components:mean-color=<var>true</var></td> 1822 <td>Changes the output image from id values to mean color values. Supported in Imagemagick 6.9.2-8.</td> 1823 </tr> 1824 1825 <tr> 1826 <td>connected-components:remove=<var>list-of-ids</var></td> 1827 <td>Command and/or hyphenated list of id values to remove from the output. Supported in Imagemagick 6.9.2-9.</td> 1828 </tr> 1829 1830 <tr> 1831 <td>connected-components:verbose=<var>true</var></td> 1832 <td>Lists id, bounding box, centroid, area, mean color for each region.</td> 1833 </tr> 1834 1835 <tr> 1836 <td>convolve:scale=<var>{kernel_scale}[!^] [,{origin_addition}] [%]</var></td> 1837 <td>Defines the kernel scaling. The special flag ! automatically scales to 1838 full dynamic range. The ! flag can be used in combination with a factor or 1839 percent. The factor or percent is then applied after the automatic scaling. 1840 An example is 50%!. This produces a result 50% darker than full dynamic 1841 range scaling. The ^ flag assures the kernel is 'zero-summing', for 1842 example when some values are positive and some are negative as in edge 1843 detection kernels. The origin addition adds that value to the center 1844 pixel of the kernel. This produces and effect that is like adding the image 1845 that many times to the result of the filtered image. The typical value 1846 is 1 so that the original image is added to the result of the convolution. 1847 The default is 0.</td> 1848 </tr> 1849 1850 <tr> 1851 <td>convolve:showkernel=<var>1</var></td> 1852 <td>Outputs (to 'standard error') all the information about a specified <a 1853 href="command-line-options.html#morphology" >-morphology convolve</a> kernel.</td> 1854 </tr> 1855 1856 <tr> 1857 <td>dcm:display-range=<var>reset</var></td> 1858 <td>Sets the display range to the minimum and maximum pixel values for the 1859 DCM image format.</td> 1860 </tr> 1861 1862 <tr> 1863 <td>dds:cluster-fit=<var>true|false</var></td> 1864 <td>Enables the dds cluster-fit.</td> 1865 </tr> 1866 1867 <tr> 1868 <td>dds:compression=<var>dxt1|dxt5|none</var></td> 1869 <td>Sets the dds compression.</td> 1870 </tr> 1871 1872 <tr> 1873 <td>dds:mipmaps=<var>value</var></td> 1874 <td>Sets the dds number of mipmaps.</td> 1875 </tr> 1876 1877 <tr> 1878 <td>dds:weight-by-alpha=<var>true|false</var></td> 1879 <td>Enables the dds alpha weighting.</td> 1880 </tr> 1881 1882 <tr> 1883 <td>delegate:bimodal=<var>true</var></td> 1884 <td>Specifies direct conversion from Postscript to PDF.</td> 1885 </tr> 1886 1887 <tr> 1888 <td>distort:scale=<var>value</var></td> 1889 <td>Sets the output scaling factor for use with <a href="command-line-options.html#distort" 1890 >-distort</a></td> 1891 </tr> 1892 1893 <tr> 1894 <td>distort:viewport=<var>WxH+X+Y</var></td> 1895 <td>Sets the viewport for use with <a href="command-line-options.html#distort">-distort</a></td> 1896 </tr> 1897 1898 <tr> 1899 <td>dot:layout-engine=<var>value</var></td> 1900 <td>Specifies the layout engine for the DOT image format (e.g. 1901 <code>neato</code>).</td> 1902 </tr> 1903 1904 <tr> 1905 <td>filter:option=<var>value</var></td> 1906 <td>Set a filter option for use with <a href="command-line-options.html#resize">-resize</a>. 1907 See <a href="command-line-options.html#filter">-filter</a> for details.</td> 1908 </tr> 1909 1910 <tr> 1911 <td>fourier:normalize=<var>inverse</var></td> 1912 <td>Sets the location for the FFT/IFT normalization as use by 1913 <a href="command-line-options.html#fft">+-fft</a> and <a href="command-line-options.html#ift">+-ift</a>. The default is 1914 <var>forward</var>.</td> 1915 </tr> 1916 1917 <tr> 1918 <td>h:format=<var>value</var></td> 1919 <td>Set the image encoding format use when writing a C-style header. 1920 <var>format</var> can be any output format supported by ImageMagick 1921 except for <var>h</var> and <var>magick</var></td>. If this 1922 option is omitted, the default is <var>GIF</var> for PseudoClass 1923 images and <var>PNM</var> for DirectClass images. 1924 </tr> 1925 1926 <tr> 1927 <td>icon:auto-resize</td> 1928 <td>Automatically stores multiple sizes when writing an ico image 1929 (requires a 256x256 input image).</td> 1930 </tr> 1931 1932 <tr> 1933 <td>jp2:layer-number=<var>value</var></td> 1934 <td>Sets the maximum number of quality layers to decode. Same for JPT, JC2, 1935 and J2K</td> 1936 </tr> 1937 1938 <tr> 1939 <td>jp2:number-resolutions=<var>value</var></td> 1940 <td>Sets the number of resolutions to encode.Same for JPT, JC2, and J2K</td> 1941 </tr> 1942 1943 <tr> 1944 <td>jp2:progression-order=<var>value</var></td> 1945 <td>choose from LRCP, RLCP, RPCL, PCRL or CPRL. Same for JPT, JC2, and 1946 J2K</td> 1947 </tr> 1948 1949 <tr> 1950 <td>jp2:quality=<var>value,value...</var></td> 1951 <td>Sets the quality layer PSNR, given in dB. The order is from left to 1952 right in ascending order. The default is a single lossless quality layer. 1953 Same for JPT, JC2, and J2K</td> 1954 </tr> 1955 1956 <tr> 1957 <td>jp2:rate=<var>value</var></td> 1958 <td>Specify the compression factor to use while writing JPEG-2000 files. The 1959 compression factor is the reciprocal of the compression ratio. The valid 1960 range is 0.0 to 1.0, with 1.0 indicating lossless compression. If defined, 1961 this value overrides the -quality setting. A quality setting of 75 1962 results in a rate value of 0.06641. Same for JPT, JC2, and J2K</td> 1963 </tr> 1964 1965 <tr> 1966 <td>jp2:reduce-factor=<var>value</var></td> 1967 <td>Sets the number of highest resolution levels to be discarded.Same for 1968 JPT, JC2, and J2K</td> 1969 </tr> 1970 1971 <tr> 1972 <td>jpeg:block-smoothing=<var>on|off</var></td> 1973 <td> </td> 1974 </tr> 1975 1976 <tr> 1977 <td>jpeg:colors=<var>value</var></td> 1978 <td>Set the desired number of colors and let the JPEG encoder do the 1979 quantizing.</td> 1980 </tr> 1981 1982 <tr> 1983 <td>jpeg:dct-method=<var>value</var></td> 1984 <td>Choose from <code>default</code>, <code>fastest</code>, 1985 <code>float</code>, <code>ifast</code>, and <code>islow</code>.</td> 1986 </tr> 1987 1988 <tr> 1989 <td>jpeg:extent=<var>value</var></td> 1990 <td>Restrict the maximum JPEG file size, for example <code>-define 1991 jpeg:extent=400KB</code>. The JPEG encoder will search for the highest 1992 compression quality level that results in an output file that does not 1993 exceed the value. The <code>-quality</code> option also will be respected 1994 starting with version 6.9.2-5. Between 6.9.1-0 and 6.9.2-4, add -quality 1995 100 in order for the jpeg:extent to work properly. Prior to 6.9.1-0, the 1996 -quality setting was ignored.</td> 1997 </tr> 1998 1999 <tr> 2000 <td>jpeg:fancy-upsampling=<var>on|off</var></td> 2001 <td> </td> 2002 </tr> 2003 2004 <tr> 2005 <td>jpeg:optimize-coding=<var>on|off</var></td> 2006 <td> </td> 2007 </tr> 2008 2009 <tr> 2010 <td>jpeg:q-table=<var>table</var></td> 2011 <td> </td> 2012 </tr> 2013 2014 <tr> 2015 <td>jpeg:sampling-factor=<var>sampling-factor-string</var></td> 2016 <td> </td> 2017 </tr> 2018 2019 <tr> 2020 <td>jpeg:size=<var>geometry</var></td> 2021 <td>Set the size hint of a JPEG image, for 2022 example, <code>-define jpeg:size=128x128</code>. 2023 It is most useful for increasing performance and reducing the memory 2024 requirements when reducing the size of a large JPEG image.</td> 2025 </tr> 2026 2027 <tr> 2028 <td>json:features</td> 2029 <td>includes features in verbose information</td> 2030 </tr> 2031 2032 <tr> 2033 <td>json:limit</td> 2034 <td> </td> 2035 </tr> 2036 2037 <tr> 2038 <td>json:locate</td> 2039 <td> </td> 2040 </tr> 2041 2042 <tr> 2043 <td>json:moments</td> 2044 <td>includes image moments in verbose information</td> 2045 </tr> 2046 2047 <tr> 2048 <td>magick:format=<var>value</var></td> 2049 <td>Set the image encoding format use when writing a C-style header. 2050 This is the same as "h:format=format" described above.</td>. 2051 </tr> 2052 2053 <tr> 2054 <td>mng:need-cacheoff</td> 2055 <td>turn playback caching off for streaming MNG.</td> 2056 </tr> 2057 2058 <tr> 2059 <td>morphology:compose=<var>compose-method</var></td> 2060 <td>Specifies how to merge results generated by multiple<a 2061 href="command-line-options.html#morphology" >-morphology</a> kernel. The default is none. One 2062 typical value is 'lighten' as used, for example, with the sobel edge 2063 kernels. </td> 2064 </tr> 2065 2066 <tr> 2067 <td>morphology:showkernel=<var>1</var></td> 2068 <td>Outputs (to 'standard error') all the information about a generated <a 2069 href="command-line-options.html#morphology" >-morphology</a> kernel.</td> 2070 </tr> 2071 2072 <tr> 2073 <td>pcl:fit-to-page=<var>true</var></td> 2074 2075 <tr> 2076 <td>pdf:fit-page=<var>geometry</var></td> 2077 <td> geometry specifies the scaling dimensions for resizing when the PDF is 2078 being read. The geometry is either WxH{%} or page size. No offsets are 2079 allowed. (introduced in IM 6.8.8-8)</td> 2080 </tr> 2081 2082 <tr> 2083 <td>pdf:fit-to-page=<var>true</var></td> 2084 <td> </td> 2085 </tr> 2086 2087 <tr> 2088 <td>pdf:use-cropbox=<var>true</var></td> 2089 <td> </td> 2090 </tr> 2091 2092 <tr> 2093 <td>pdf:use-trimbox=<var>true</var></td> 2094 <td> </td> 2095 </tr> 2096 2097 <tr> 2098 <td>png:bit-depth=<var>value</var></td> 2099 <td> </td> 2100 </tr> 2101 <tr> 2102 <td>png:color-type=<var>value</var></td> 2103 <td>desired bit-depth and color-type for PNG output. You can force the PNG 2104 encoder to use a different bit-depth and color-type than it would have 2105 normally selected, but only if this does not cause any loss of image 2106 quality. Any attempt to reduce image quality is treated as an error and no 2107 PNG file is written. E.g., if you have a 1-bit black-and-white image, you 2108 can use these "defines" to cause it to be written as an 8-bit grayscale, 2109 indexed, or even a 64-bit RGBA. But if you have a 16-million color image, 2110 you cannot force it to be written as a grayscale or indexed PNG. If you 2111 wish to do this, you must use the appropriate <a href="command-line-options.html#depth">-depth</a>, 2112 <a href="command-line-options.html#colors">-colors</a>, or <a href="command-line-options.html#type">-type</a> directives to 2113 reduce the image quality prior to using the PNG encoder. Note that in 2114 indexed PNG files, "bit-depth" refers to the number of bits per index, 2115 which can be 1, 2, 4, or 8. In such files, the color samples always have 2116 8-bit depth.</td> 2117 </tr> 2118 2119 <tr> 2120 <td>png:compression-filter=<var>value</var></td> 2121 <td> valid values are 0 through 9. 0-4 are the corresponding PNG filters, 2122 5 means adaptive filtering except for images with a colormap, 6 means 2123 adaptive filtering for all images, 7 means MNG "loco" compression, 8 means 2124 Z_RLE strategy with adaptive filtering, and 9 means Z_RLE strategy with no 2125 filtering.</td> 2126 </tr> 2127 2128 <tr> 2129 <td>png:compression-level=<var>value</var></td> 2130 <td> valid values are 0 through 9, with 0 providing the least but fastest 2131 compression and 9 usually providing the best and always the slowest.</td> 2132 </tr> 2133 2134 <tr> 2135 <td>png:compression-strategy=<var>value</var></td> 2136 <td> valid values are 0 through 4, meaning default, filtered, huffman_only, 2137 rle, and fixed ZLIB compression strategy. If you are using an old zlib 2138 that does not support Z_RLE (before 1.2.0) or Z_FIXED (before 1.2.2.2), 2139 values 3 and 4, respectively, will use the zlib default strategy 2140 instead.</td> 2141 </tr> 2142 2143 <tr> 2144 <td>png:format=<var>value</var></td> 2145 <td> valid values are <var>png8</var>, <var>png24</var>, 2146 <var>png32</var>, <var>png48</var>, 2147 <var>png64</var>, and <var>png00</var>. 2148 This property can be useful for specifying 2149 the specific PNG format to be used, when the usual method of prepending the 2150 format name to the output filename is inconvenient, such as when writing 2151 a PNG-encoded ICO file or when using <a href="mogrify.html">mogrify</a>. 2152 Value = <var>png8</var> reduces the number of colors to 256, 2153 only one of which may be fully transparent, if necessary. The other 2154 values do not force any reduction of quality; it is an error to request 2155 a format that cannot represent the image data without loss (except that 2156 it is allowed to reduce the bit-depth from 16 to 8 for all formats). 2157 Value = <var>png24</var> and <var>png48</var> 2158 allow transparency, only if a single color is fully transparent and that 2159 color does not also appear in an opaque pixel; such transparency is 2160 written in a PNG <code>tRNS</code> chunk. 2161 Value = <var>png00</var> causes the image to inherit its 2162 color-type and bit-depth from the input image, if the input was also 2163 a PNG.</td> 2164 </tr> 2165 2166 <tr> 2167 <td>png:exclude-chunk=<var>value</var></td> 2168 2169 <tr> 2170 <td>png:include-chunk=<var>value</var></td> 2171 <td>ancillary chunks to be excluded from or included in PNG output. 2172 2173 <p>The <var>value</var> can be the name of a PNG chunk-type such 2174 as <var>bKGD</var>, a comma-separated list of chunk-names 2175 (which can include the word <var>date</var>, the word 2176 <var>all</var>, or the word <var>none</var>). 2177 Although PNG chunk-names are case-dependent, you can use all lowercase 2178 names if you prefer.</p> 2179 2180 <p>The "include-chunk" and "exclude-chunk" lists only affect the behavior 2181 of the PNG encoder and have no effect on the PNG decoder.</p> 2182 2183 <p>As a special case, if the <code>sRGB</code> chunk is excluded and 2184 the <code>gAMA</code> chunk is included, the <code>gAMA</code> chunk will 2185 only be written if gamma is not 1/2.2, since most decoders assume 2186 sRGB and gamma=1/2.2 when no colorspace information is included in 2187 the PNG file. Because the list is processed from left to right, you 2188 can achieve this with a single define:</p> 2189 2190<pre> 2191-define png:include-chunk=none,gAMA 2192</pre> 2193 2194 <p>As a special case, if the <code>sRGB</code> chunk is not excluded and 2195 the PNG encoder recognizes that the image contains the sRGB ICC profile, 2196 the PNG encoder will write the <code>sRGB</code> chunk instead of the 2197 entire ICC profile. To force the PNG encoder to write the sRGB 2198 profile as an <code>iCCP</code> chunk in the output PNG instead of the 2199 <code>sRGB</code> chunk, exclude the <code>sRGB</code> chunk.</p> 2200 2201 <p>The critical PNG chunks <code>IHDR</code>, <code>PLTE</code>, 2202 <code>IDAT</code>, and <code>IEND</code> cannot be excluded. Any such 2203 entries appearing in the list will be ignored.</p> 2204 2205 <p>If the ancillary PNG <code>tRNS</code> chunk is excluded and the 2206 image has transparency, the PNG colortype is forced to be 4 or 6 2207 (GRAY_ALPHA or RGBA). If the image is not transparent, then the 2208 <code>tRNS</code> chunk isn't written anyhow, and there is no effect 2209 on the PNG colortype of the output image.</p> 2210 2211 <p>The <a href="command-line-options.html#strip">-strip</a> option does the equivalent of the 2212 following for PNG output:</p> 2213 2214<pre> 2215-define png:exclude-chunk=EXIF,iCCP,iTXt,sRGB,tEXt,zCCP,zTXt,date 2216</pre> 2217 2218 <p>The default behavior is to include all known PNG ancillary chunks 2219 plus ImageMagick's private <code>vpAg</code> ("virtual page") chunk, 2220 and to exclude all PNG chunks that are unknown to ImageMagick, 2221 regardless of their PNG "copy-safe" status as described in the 2222 PNG specification.</p> 2223 2224 <p>Any chunk names that are not known to ImageMagick are ignored 2225 if they appear in either the "include-chunk" or "exclude-chunk" list. 2226 The ancillary chunks currently known to ImageMagick are 2227 <code>bKGD</code>, <code>cHRM</code>, <code>gAMA</code>, <code>iCCP</code>, 2228 <code>oFFs</code>, <code>pHYs</code>, <code>sRGB</code>, <code>tEXt</code>, 2229 <code>tRNS</code>, <code>vpAg</code>, and <code>zTXt</code>.</p> 2230 2231 <p>You can also put <code>date</code> in the list to include or exclude 2232 the "Date:create" and "Date:modify" text chunks that ImageMagick normally 2233 inserts in the output PNG.</p></td> 2234 </tr> 2235 2236 <tr> 2237 <td>png:preserve-colormap[=<var>true</var>]</td> 2238 <td>Use the existing image->colormap. Normally the PNG encoder will 2239 try to optimize the palette, eliminating unused entries and putting 2240 the transparent colors first. If this flag is set, that behavior 2241 is suppressed.</td> 2242 </tr> 2243 2244 <tr> 2245 <td>png:preserve-iCCP[=<var>true</var>]</td> 2246 <td>By default, the PNG decoder and encoder examine any ICC profile 2247 that is present, either from an <code>iCCP</code> chunk in the PNG 2248 input or supplied via an option, and if the profile is recognized 2249 to be the sRGB profile, converts it to the <code>sRGB</code> chunk. 2250 You can use <code>-define png:preserve-iCCP</code> to prevent 2251 this from happening; in such cases the <code>iCCP</code> chunk 2252 will be read or written and no <code>sRGB</code> chunk will be 2253 written. There are some ICC profiles that claim to be sRGB but 2254 have various errors that cause them to be rejected by libpng16; such 2255 profiles are recognized anyhow and converted to the <code>sRGB</code> 2256 chunk, but are rejected if the <code>-define png:preserve-iCCP</code> 2257 is present. Note that not all "sRGB" ICC profiles are recognized 2258 yet; we will add them to the list as we encounter them.</td> 2259 </tr> 2260 2261 <tr> 2262 <td>png:swap-bytes[=<var>true</var>]</td> 2263 <td>The PNG specification requires that any multi-byte integers be stored in 2264 network byte order (MSB-LSB endian). This option allows you to 2265 fix any invalid PNG files that have 16-bit samples stored incorrectly 2266 in little-endian order (LSB-MSB). The "-define png:swap-bytes" option 2267 must appear before the input filename on the commandline. The swapping 2268 is done during the libpng decoding operation.</td> 2269 </tr> 2270 2271 <tr> 2272 <td>profile:skip=<var>name1,name2,...</var></td> 2273 <td>Skip the named profile[s] when reading the image. Use skip="*" to 2274 skip all named profiles in the image. Many named profiles exist, 2275 including ICC, EXIF, APP1, IPTC, XMP, and others.</td> 2276 </tr> 2277 2278 <tr> 2279 <td>ps:imagemask</td> 2280 <td>If the ps:imagemask flag is defined, the PS3 and EPS3 coders will 2281 create Postscript files that render bilevel images with the Postscript 2282 imagemask operator instead of the image operator.</td> 2283 </tr> 2284 2285 <tr> 2286 <td>psd:alpha-unblend=off</td> 2287 <td>Disables new automatic un-blending of transparency with the base image 2288 for the flattened layer 0 before adding the alpha channel to the output 2289 image. This define must be placed before the input psd image. (Available 2290 as of IM 6.9.2.5). The automatic un-blending is new to IM 6.9.2.5 and 2291 prevents the transparency from being applied twice in the output 2292 image.</td> 2293 </tr> 2294 2295 <tr> 2296 <td>quantum:format=<var>type</var></td> 2297 <td>Set the type to <code>floating-point</code> to specify a floating-point 2298 format for raw files (e.g. GRAY:) or for MIFF and TIFF images in HDRI mode 2299 to preserve negative values. If <a href="command-line-options.html#depth">-depth</a> 16 is 2300 included, the result is a single precision floating point format. 2301 If <a href="command-line-options.html#depth">-depth</a> 32 is included, the result is 2302 double precision floating point format.</td> 2303 </tr> 2304 2305 <tr> 2306 <td>quantum:polarity=<var>photometric-interpretation</var></td> 2307 <td>Set the photometric-interpretation of an image (typically for TIFF image 2308 file format) to either <code>min-is-black</code> (default) or 2309 <code>min-is-white</code>.</td> 2310 </tr> 2311 2312 <tr> 2313 <td>sample:offset=<var>geometry</var></td> 2314 <td>Location of the sampling point within the sub-region being sampled, 2315 expressed as percentages (see <a href="command-line-options.html#sample" >-sample</a>).</td> 2316 </tr> 2317 2318 <tr> 2319 <td>showkernel=<var>1</var></td> 2320 <td>Outputs (to 'standard error') all the information about a generated <a 2321 href="command-line-options.html#morphology" >-morphology</a> kernel.</td> 2322 </tr> 2323 2324 <tr> 2325 <td>stream:buffer-size=<var>value</var></td> 2326 <td>Set the stream buffer size. Select 0 for unbuffered I/O.</td> 2327 </tr> 2328 2329 <tr> 2330 <td>tiff:alpha=<var>associated|unassociated|unspecified</var></td> 2331 <td>Specify the alpha extra samples as associated, unassociated or unspecified </td> 2332 </tr> 2333 2334 <tr> 2335 <td>tiff:endian=<var>msb|lsb</var></td> 2336 <td> </td> 2337 </tr> 2338 2339 <tr> 2340 <td>tiff:exif-properties=<var>false</var></td> 2341 <td>Skips reading the EXIF properties.</td> 2342 </tr> 2343 2344 <tr> 2345 <td>tiff:fill-order=<var>msb|lsb</var></td> 2346 <td> </td> 2347 </tr> 2348 2349 <tr> 2350 <td>tiff:ignore-layers=<var>true</var></td> 2351 <td>Ignores the photoshop layers.</td> 2352 </tr> 2353 2354 <tr> 2355 <td>tiff:ignore-tags=<var>comma-separate-list-of-tag-IDs</var></td> 2356 <td>Allows one or more tag ID values to be ignored.</td> 2357 </tr> 2358 2359 <tr> 2360 <td>tiff:rows-per-strip=<var>value</var></td> 2361 <td>Sets the number of rows per strip</td> 2362 </tr> 2363 2364 <tr> 2365 <td>tiff:tile-geometry=<var>WxH</var></td> 2366 <td>Sets the tile size for pyramid tiffs. Requires the suffix 2367 PTIF: before the outputname</td> 2368 </tr> 2369 2370 <tr> 2371 <td>type:features=<var>string</var></td> 2372 <td> </td> 2373 </tr> 2374 2375 <tr> 2376 <td>type:hinting=<var>off</var></td> 2377 <td> </td> 2378 </tr> 2379</table> 2380 2381<p>For example, to create a postscript file that will render only the black 2382pixels of a bilevel image, use:</p> 2383 2384<pre> 2385convert bilevel.tif -define ps:imagemask eps3:stencil.ps 2386</pre> 2387 2388<p>Set attributes of the image registry by prefixing the value with 2389<code>registry:</code>. For example, to set a temporary path to put work files, 2390use:</p> 2391 2392<pre> 2393-define registry:temporary-path=/data/tmp 2394</pre> 2395 2396<div style="margin: auto;"> 2397 <h3 class="magick-header"><a id="delay"></a>-delay <var>ticks</var> <br />-delay <var>ticks</var>x<var>ticks-per-second</var> {<var><</var>} {<var>></var>}</h3> 2398</div> 2399 2400<p class="magick-description">display the next image after pausing.</p> 2401 2402<p>This option is useful for regulating the animation of image sequences 2403<var>ticks/ticks-per-second</var> seconds must expire before the display of the 2404next image. The default is no delay between each showing of the image 2405sequence. The default ticks-per-second is 100.</p> 2406 2407<p>Use <code>></code> to change the image delay <var>only</var> if its current 2408value exceeds the given delay. <code><</code> changes the image delay 2409<var>only</var> if current value is less than the given delay. For example, if 2410you specify <code>30></code> and the image delay is 20, the image delay does 2411not change. However, if the image delay is 40 or 50, the delay it is changed 2412to 30. Enclose the given delay in quotation marks to prevent the 2413<code><</code> or <code>></code> from being interpreted by your shell as 2414a file redirection.</p> 2415 2416 2417<div style="margin: auto;"> 2418 <h3 class="magick-header"><a id="delete"></a>-delete <var>indexes</var></h3> 2419</div> 2420 2421<p class="magick-description">delete the images specified by index, from the image sequence.</p> 2422 2423<p>Specify the image by its index in the sequence. The first image is index 24240. Negative indexes are relative to the end of the sequence, for example, -1 2425represents the last image of the sequence. Specify a range of images with 2426a dash (e.g. 0-4). Separate indexes with a comma (e.g. 0,2). Use 2427<code>+delete</code> to delete the last image in the current image sequence.</p> 2428 2429 2430<div style="margin: auto;"> 2431 <h3 class="magick-header"><a id="density"></a>-density <var>width</var><br />-density <var>width</var>x<var>height</var></h3> 2432</div> 2433 2434<p class="magick-description">Set the horizontal and vertical resolution of an image for rendering to devices.</p> 2435 2436<p>This option specifies the image resolution to store while encoding a raster 2437image or the canvas resolution while rendering (reading) vector formats such 2438as Postscript, PDF, WMF, and SVG into a raster image. Image resolution 2439provides the unit of measure to apply when rendering to an output device or 2440raster image. The default unit of measure is in dots per inch (DPI). The <a 2441href="command-line-options.html#units">-units</a> option may be used to select dots per centimeter 2442instead.</p> 2443 2444<p>The default resolution is 72 dots per inch, which is equivalent to one 2445point per pixel (Macintosh and Postscript standard). Computer screens are 2446normally 72 or 96 dots per inch, while printers typically support 150, 300, 2447600, or 1200 dots per inch. To determine the resolution of your display, use 2448a ruler to measure the width of your screen in inches, and divide by the 2449number of horizontal pixels (1024 on a 1024x768 display).</p> 2450 2451<p>If the file format supports it, this option may be used to update the 2452stored image resolution. Note that Photoshop stores and obtains image 2453resolution from a proprietary embedded profile. If this profile is not 2454stripped from the image, then Photoshop will continue to treat the image using 2455its former resolution, ignoring the image resolution specified in the standard 2456file header.</p> 2457 2458<p>The <a href="command-line-options.html#density">-density</a> option sets an <var>attribute</var> and 2459does not alter the underlying raster image. It may be used to adjust the 2460rendered size for desktop publishing purposes by adjusting the scale applied 2461to the pixels. To resize the image so that it is the same size at a different 2462resolution, use the <a href="command-line-options.html#resample">-resample</a> option.</p> 2463 2464<div style="margin: auto;"> 2465 <h3 class="magick-header"><a id="depth"></a>-depth <var>value</var></h3> 2466</div> 2467 2468<p class="magick-description">depth of the image.</p> 2469 2470<p>This the number of bits in a color sample within a pixel. Use this option 2471to specify the depth of raw images whose depth is unknown such as GRAY, RGB, 2472or CMYK, or to change the depth of any image after it has been read.</p> 2473 2474<div style="margin: auto;"> 2475 <h3 class="magick-header"><a id="descend"></a>-descend</h3> 2476</div> 2477 2478<p class="magick-description">obtain image by descending window hierarchy.</p> 2479 2480<div style="margin: auto;"> 2481 <h3 class="magick-header"><a id="deskew"></a>-deskew <var>threshold{%}</var></h3> 2482</div> 2483 2484<p class="magick-description">straighten an image. A threshold of 40% works for most images.</p> 2485 2486<p>Use <a href="command-line-options.html#set">-set</a> <code>option:deskew:auto-crop 2487<var>width</var></code> to auto crop the image. The set argument is the pixel 2488width of the image background (e.g 40).</p> 2489 2490<div style="margin: auto;"> 2491 <h3 class="magick-header"><a id="despeckle"></a>-despeckle</h3> 2492</div> 2493 2494<p class="magick-description">reduce the speckles within an image.</p> 2495 2496<div style="margin: auto;"> 2497 <h3 class="magick-header"><a id="direction"></a>-direction <var>type</var></h3> 2498</div> 2499 2500<p class="magick-description">render text right-to-left or left-to-right.</p> 2501 2502<div style="margin: auto;"> 2503 <h3 class="magick-header"><a id="displace"></a>-displace <var>horizontal-scale</var>{%}{!}<br />-displace <var>horizontal-scale</var>x<var>vertical-scale</var>{%}{!}</h3> 2504</div> 2505 2506<p class="magick-description">shift image pixels as defined by a displacement map.</p> 2507 2508<p>With this option, the 'overlay' image, and optionally the 'mask' image, 2509is used as a displacement map, which is used to displace the lookup of 2510what part of the 'background' image is seen at each point of the overlaid 2511area. Much like the displacement map is a 'lens' that redirects light shining 2512through it so as to present a distorted view the original 'background' image 2513behind it. </p> 2514 2515<p>Any perfect grey areas of the displacement map produce a zero 2516displacement of the image. Black areas produce the given maximum negative 2517displacement of the lookup point, while white produce a maximum positive 2518displacement of the lookup. </p> 2519 2520<p>Note that it is the lookup of the 'background' that is displaced, not a 2521displacement of the image itself. As such an area of the displacement map 2522containing 'white' will have the lookup point 'shifted' by a positive amount, 2523and thus generating a copy of the destination image to the right/downward from 2524the correct position. That is the image will look like it may have been 2525'shifted' in a negative left/upward direction. Understanding this is a very 2526important in understanding how displacement maps work. </p> 2527 2528<p>The given arguments define the maximum amount of displacement in pixels 2529that a particular map can produce. If the displacement scale is large enough 2530it is also possible to lookup parts of the 'background' image that lie well 2531outside the bounds of the displacement map itself. That is you could very 2532easily copy a section of the original image from outside the overlay area 2533into the overlay area. </p> 2534 2535<p>The '%' flag makes the displacement scale relative to the size of the 2536overlay image (100% = half width/height of image). Using '!' switches 2537percentage arguments to refer to the destination image size instead. 2538these flags were added as of IM v6.5.3-5.</p> 2539 2540<p>Normally a single grayscale displacement map is provided, which with the 2541given scaling values will determine a single direction (vector) in which 2542displacements can occur (positively or negatively). However, if you also 2543specify a third image which is normally used as a <var>mask</var>, 2544the <var>composite image</var> is used for horizontal X 2545displacement, while the <var>mask image</var> is used for vertical Y 2546displacement. This allows you to define completely different displacement 2547values for the X and Y directions, and allowing you to lookup any point within 2548the <var>scale</var> bounds. In other words each pixel can lookup 2549any other nearby pixel, producing complex 2 dimensional displacements, rather 2550than a simple 1 dimensional vector displacements. </p> 2551 2552<p>Alternatively rather than supplying two separate images, as of IM v6.4.4-0, 2553you can use the 'red' channel of the overlay image to specify the horizontal 2554or X displacement, and the 'green' channel for the vertical or Y displacement. 2555</p> 2556 2557<p>As of IM v6.5.3-5 any alpha channel in the overlay image is used as a 2558mask the transparency of the destination image. However areas outside the 2559overlaid areas will not be effected. </p> 2560 2561 2562<div style="margin: auto;"> 2563 <h3 class="magick-header"><a id="display"></a>-display <var>host:display[.screen]</var></h3> 2564</div> 2565 2566<p class="magick-description">Specifies the X server to contact.</p> 2567 2568<p>This option is used with convert for obtaining image or font from this 2569X server. See <var>X(1)</var>.</p> 2570 2571<div style="margin: auto;"> 2572 <h3 class="magick-header"><a id="dispose"></a>-dispose <var>method</var></h3> 2573</div> 2574 2575<p class="magick-description">define the GIF disposal image setting for images that are being created or read in. </p> 2576 2577<p>The layer disposal method defines the way each the displayed image is to be 2578modified after the current 'frame' of an animation has finished being 2579displayed (after its 'delay' period), but before the next frame on an 2580animation is to be overlaid onto the display. </p> 2581 2582<p>Here are the valid methods:</p> 2583 2584<dl class="dl-horizontal"> 2585<dt>Undefined</dt><dd>0: No disposal specified (equivalent to '<code>none</code>').</dd> 2586<dt>None</dt><dd>1: Do not dispose, just overlay next frame image.</dd> 2587<dt>Background</dt><dd>2: Clear the frame area with the background color.</dd> 2588<dt>Previous</dt><dd>3: Clear to the image prior to this frames overlay.</dd> 2589</dl> 2590 2591<p>You can also use the numbers given above, which is what the GIF format 2592uses internally to represent the above settings. </p> 2593 2594<p>To print a complete list of dispose methods, use <a href="command-line-options.html#list">-list dispose</a>.</p> 2595 2596<p>Use <a href="command-line-options.html#dispose" >+dispose</a>, turn off the setting and prevent 2597resetting the layer disposal methods of images being read in. </p> 2598 2599<p>Use <a href="command-line-options.html#set">-set</a> '<code>dispose</code>' method to set the image 2600disposal method for images already in memory.</p> 2601 2602<div style="margin: auto;"> 2603 <h3 class="magick-header"><a id="dissimilarity-threshold"></a>-dissimilarity-threshold <var>value</var></h3> 2604</div> 2605 2606<p class="magick-description">maximum RMSE for subimage match (default 0.2).</p> 2607 2608 2609<div style="margin: auto;"> 2610 <h3 class="magick-header"><a id="dissolve"></a>-dissolve <var>src_percent</var>[x<var>dst_percent</var>]</h3> 2611</div> 2612 2613<p class="magick-description">dissolve an image into another by the given percent.</p> 2614 2615<p>The opacity of the composite image is multiplied by the given percent, then 2616it is composited 'over' the main image. If <var>src_percent</var> 2617is greater than 100, start dissolving the main image so it becomes 2618transparent at a value of '<code>200</code>'. If both percentages 2619are given, each image are dissolved to the percentages given. </p> 2620 2621<p>Note that dissolve percentages do not add, two opaque images dissolved 2622'50,50', produce a 75% transparency. For a 50% + 50% blending of the two 2623images, you would need to use dissolve values of '50,100'. </p> 2624 2625<div style="margin: auto;"> 2626 <h3 class="magick-header"><a id="distort"></a>-distort <var>method arguments</var></h3> 2627</div> 2628 2629<p class="magick-description">distort an image, using the given <var>method</var> and its required <var>arguments</var>.</p> 2630 2631<p>The <var>arguments</var> is a single string containing a list 2632of floating point numbers separated by commas or spaces. The number of 2633and meaning of the floating point values depends on the distortion <var>method</var> being used. </p> 2634 2635<p>Choose from these distortion types:</p> 2636 2637<table class="table table-condensed table-striped"> 2638 <tr> 2639 <th style="width: 8%">Method</th> 2640 <th>Description</th> 2641 </tr> 2642 2643 <tr> 2644 <td>ScaleRotateTranslate <br/> SRT</td> 2645 <td> 2646 Distort image by first scaling and rotating about a given 'center', 2647 before translating that 'center' to the new location, in that order. It 2648 is an alternative method of specifying a 'Affine' type of 2649 distortion, but without shearing effects. It also provides a good way 2650 of rotating and displacing a smaller image for tiling onto a larger 2651 background (IE 2-dimensional animations). <br/> 2652 2653 The number of arguments determine the specific meaning of each 2654 argument for the scales, rotation, and translation operations. <br/> 2655 2656 <dl class="dl-horizontal"> 2657 <dt>2:</dt><dd><var>Scale Angle</var></dd> 2658 <dt>3:</dt><dd><var>X,Y Angle</var></dd> 2659 <dt>4:</dt><dd><var>X,Y Scale Angle</var></dd> 2660 <dt>5:</dt> <dd><var>X,Y ScaleX,ScaleY Angle</var></dd> 2661 <dt>6:</dt> <dd><var>X,Y Scale Angle NewX,NewY</var></dd> 2662 <dt>7:</dt> <dd><var>X,Y ScaleX,ScaleY Angle NewX,NewY</var></dd> 2663 </dl> 2664 2665 This is actually an alternative way of specifying a 2 dimensional linear 2666 'Affine' or 'AffineProjection' distortion. </td> </tr> 2667 2668 <tr> 2669 <td>Affine</td> 2670 <td> 2671 Distort the image linearly by moving a list of at least 3 or more sets 2672 of control points (as defined below). Ideally 3 sets or 12 floating 2673 point values are given allowing the image to be linearly scaled, 2674 rotated, sheared, and translated, according to those three points. See 2675 also the related 'AffineProjection' and 'SRT' 2676 distortions. <br/> 2677 2678 More than 3 sets given control point pairs (12 numbers) is least 2679 squares fitted to best match a linear affine distortion. If only 2 2680 control point pairs (8 numbers) are given a two point image translation 2681 rotation and scaling is performed, without any possible shearing, 2682 flipping or changes in aspect ratio to the resulting image. If only one 2683 control point pair is provides the image is only translated, (which may 2684 be a floating point non-integer translation). <br/> 2685 2686 This distortion does not include any form of perspective distortion. 2687 </td> 2688 2689 </tr> 2690 2691 <tr> 2692 <td>AffineProjection</td> 2693 <td> 2694 Linearly distort an image using the given Affine Matrix of 6 2695 pre-calculated coefficients forming a set of Affine Equations to map 2696 the source image to the destination image. 2697 2698 <p class="text-center"><var> 2699 s<sub>x</sub>, r<sub>x</sub>, 2700 r<sub>y</sub>, s<sub>y</sub>, 2701 t<sub>x</sub>, t<sub>y</sub> 2702 </var></p> 2703 2704 See <a href="command-line-options.html#affine" >-affine</a> setting for more detail, and 2705 meanings of these coefficients. <br/> 2706 2707 The distortions 'Affine' and 'SRT' provide 2708 alternative methods of defining this distortion, with ImageMagick doing 2709 the calculations needed to generate the required coefficients. You can 2710 see the internally generated coefficients, by using a <a 2711 href="command-line-options.html#verbose" >-verbose</a> setting with those other variants. </td> 2712 2713 </tr> 2714 2715 <tr> 2716 <td>BilinearForward<br/> 2717 BilinearReverse</td> 2718 <td> 2719 Bilinear Distortion, given a minimum of 4 sets of coordinate pairs, or 2720 16 values (see below). Not that lines may not appear straight after 2721 distortion, though the distance between coordinates will remain 2722 consistent. <br/> 2723 2724 The 'BilinearForward' is used to map rectangles to any 2725 quadrilateral, while the 'BilinearReverse' form maps any 2726 quadrilateral to a rectangle, while preserving the straight line edges 2727 in each case. <br/> 2728 2729 Note that 'BilinearForward' can generate invalid pixels 2730 which will be colored using the <a href="command-line-options.html#alpha-color" >-alpha-color</a> 2731 color setting. Also if the quadrilateral becomes 'flipped' the image 2732 may disappear. <br/> 2733 2734 There are future plans to produce a true Bilinear distortion that will 2735 attempt to map any quadrilateral to any other quadrilateral, while 2736 preserving edges (and edge distance ratios). 2737 2738 </td> 2739 </tr> 2740 2741 <tr> 2742 <td>Perspective</td> 2743 <td> 2744 Perspective distort the images, using a list of 4 or more sets of 2745 control points (as defined below). More that 4 sets (16 numbers) of 2746 control points provide least squares fitting for more accurate 2747 distortions (for the purposes of image registration and panorama 2748 effects). Less than 4 sets will fall back to a 'Affine' 2749 linear distortion. <br/> 2750 2751 Perspective Distorted images ensures that straight lines remain 2752 straight, but the scale of the distorted image will vary. The horizon 2753 is anti-aliased, and the 'sky' color may be set using the 2754 <a href="command-line-options.html#alpha-color" >-alpha-color</a> setting. </td> 2755 </tr> 2756 2757 <tr> 2758 <td>PerspectiveProjection </td> 2759 <td> 2760 Do a 'Perspective' distortion biased on a set of 8 2761 pre-calculated coefficients. You can get these coefficients by looking 2762 at the <a href="command-line-options.html#verbose" >-verbose</a> output of a 2763 'Perspective' distortion, or by calculating them yourself. 2764 If the last two perspective scaling coefficients are zero, the 2765 remaining 6 represents a transposed 'Affine Matrix'. </td> 2766 2767 </tr> 2768 2769 <tr> 2770 <td>Arc</td> 2771 <td> 2772 Arc the image (variation of polar mapping) over the angle given around 2773 a circle. 2774 2775 <p><dl class="dl-horizontal"> 2776 <dt>arc_angle</dt> 2777 <dd>The angle over which to arc the image side-to-side</dd> 2778 <dt>rotate_angle</dt> 2779 <dd>Angle to rotate resulting image from vertical center</dd> 2780 <dt>top_radius</dt> 2781 <dd>Set top edge of source image at this radius</dd> 2782 <dt>bottom_radius </dt> 2783 <dd>Set bottom edge to this radius (radial scaling)</dd> 2784 </dl></p> 2785 2786 The resulting image is always resized to best fit the resulting image, 2787 (as if using <a href="command-line-options.html#distort" >+distort</a>) while attempting to 2788 preserve scale and aspect ratio of the original image as much as 2789 possible with the arguments given by the user. All four arguments will 2790 be needed to change the overall aspect ratio of an 'Arc'ed image. <br/> 2791 2792 This a variation of a polar distortion designed to try to preserve the 2793 aspect ratio of the image rather than direct Cartesian to Polar 2794 conversion. </td> 2795 </tr> 2796 2797 <tr> 2798 <td>Polar</td> 2799 <td> 2800 Like 'Arc' but do a complete Cartesian to Polar mapping of 2801 the image. that is the height of the input image is mapped to the 2802 radius limits, while the width is wrapped around between the 2803 angle limits. <br/> 2804 2805 Arguments: <var>Rmax,Rmin CenterX,CenterY, start,end_angle</var> <br/> 2806 2807 All arguments are optional. With <var>Rmin</var> defaulting to zero, the 2808 center to the center of the image, and the angles going from -180 (top) 2809 to +180 (top). If <var>Rmax</var> is given the special value of 2810 '0', the the distance from the center to the nearest edge 2811 is used for the radius of the output image, which will ensure the whole 2812 image is visible (though scaled smaller). However a special value of 2813 '-1' will use the distance from the center to the furthest 2814 corner, This may 'clip' the corners from the input rectangular image, 2815 but will generate the exact reverse of a 'DePolar' with 2816 the same arguments. <br/> 2817 2818 If the plus form of distort (<a href="command-line-options.html#distort" >+distort</a>) is used 2819 output image center will default to 0,0 of the virtual 2820 canvas, and the image size adjusted to ensure the whole input image is 2821 made visible in the output image on the virtual canvas. </td> 2822 2823 </tr> 2824 2825 <tr> 2826 <td>DePolar</td> 2827 <td> 2828 Uses the same arguments and meanings as a 'Polar' distortion 2829 but generates the reverse Polar to Cartesian distortion. <br/> 2830 2831 The special <var>Rmax</var> setting of '0' may however clip 2832 the corners of the input image. However using the special 2833 <var>Rmax</var> setting of '-1' (maximum center to corner 2834 distance) will ensure the whole distorted image is preserved in the 2835 generated result, so that the same argument to 'Polar' will 2836 reverse the distortion re-producing the original. 2837 2838 Note that as this distortion requires the area resampling of a circular 2839 arc, which can not be handled by the builtin EWA resampling function. 2840 As such the normal EWA filters are turned off. It is recommended some 2841 form of 'super-sampling' image processing technique be used to produce 2842 a high quality result. </td> 2843 2844 </tr> 2845 2846 <tr> 2847 <td>Barrel</td> 2848 <td> 2849 Given the four coefficients (A,B,C,D) as defined by <a 2850 href="http://wiki.panotools.org/Lens_correction_model" >Helmut 2851 Dersch</a>, perform a barrel or pin-cushion distortion appropriate to 2852 correct radial lens distortions. That is in photographs, make straight 2853 lines straight again. <br/> 2854 2855 <p class="text-center">Arguments: <var>A B C</var> [ <var>D</var> [ 2856 <var>X</var> , <var>Y</var> ] ] <br/> 2857 or <var>A<sub>x</sub> B<sub>x</sub> C<sub>x</sub> D<sub>x</sub> 2858 A<sub>y</sub> B<sub>y</sub> C<sub>y</sub> D<sub>y</sub></var> 2859 [ <var>X</var> , <var>Y</var> ] </p> 2860 So that it forms the function 2861 <p class="text-center">Rsrc = r * ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> + 2862 <var>C</var>*r + <var>D</var> )</p> 2863 2864 Where <var>X</var>,<var>Y</var> is the optional center of the distortion 2865 (defaulting to the center of the image). <br/> 2866 The second form is typically used to distort images, rather than 2867 correct lens distortions. <br/> 2868 </td> 2869 2870 </tr> 2871 2872 <tr> 2873 <td>BarrelInverse</td> 2874 <td> 2875 This is very similar to 'Barrel' with the same set of 2876 arguments, and argument handling. However it uses the inverse 2877 of the radial polynomial, 2878 so that it forms the function 2879 <p class="text-center">Rsrc = r / ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> + 2880 <var>C</var>*r + <var>D</var> )</p> 2881 Note that this is not the reverse of the 'Barrel' 2882 distortion, just a different barrel-like radial distortion method. 2883 2884 </td> 2885 </tr> 2886 2887 <tr> 2888 <td>Shepards</td> 2889 <td> 2890 Distort the given list control points (any number) using an Inverse 2891 Squared Distance Interpolation Method (<a 2892 href="http://en.wikipedia.org/wiki/Shepard%27s_method" >Shepards 2893 Method</a>). The control points in effect do 'localized' displacement 2894 of the image around the given control point (preserving the look and 2895 the rotation of the area near the control points. For best results 2896 extra control points should be added to 'lock' the positions of the 2897 corners, edges and other unchanging parts of the image, to prevent 2898 their movement. <br/> 2899 2900 The distortion has been likened to 'taffy pulling' using nails, or 2901 pins' stuck in a block of 'jelly' which is then moved to the new 2902 position, distorting the surface of the jelly. <br/> 2903 2904 Internally it is equivalent to generating a displacement map (see <a 2905 href="command-line-options.html#displace" >-displace</a>) for source image color look-up using 2906 the <a href="command-line-options.html#sparse-color" >-sparse-color</a> method of the same name. 2907 2908 </td> 2909 </tr> 2910 2911</table> 2912 2913<p>To print a complete list of distortion methods, use <a href="command-line-options.html#list">-list 2914distort</a>.</p> 2915 2916<p>Many of the above distortion methods such as '<code>Affine</code>', 2917'<code>Perspective</code>', and '<code>Shepards</code>' use a list control points 2918defining how these points in the given image should be distorted in the 2919destination image. Each set of four floating point values represent a source 2920image coordinate, followed immediately by the destination image coordinate. 2921This produces a list of values such as...</p> 2922<p class="text-center"><var> 2923 U<sub>1</sub>,V<sub>1</sub> X<sub>1</sub>,Y<sub>1</sub> 2924 U<sub>2</sub>,V<sub>2</sub> X<sub>2</sub>,Y<sub>2</sub> 2925 U<sub>3</sub>,V<sub>3</sub> X<sub>3</sub>,Y<sub>3</sub> 2926 ... 2927 U<sub>n</sub>,V<sub>n</sub> X<sub>n</sub>,Y<sub>n</sub> 2928</var></p> 2929<p>where <var>U,V</var> on the source image is mapped to <var>X,Y</var> on the 2930destination image. </p> 2931 2932<p>For example, to warp an image using '<code>perspective</code>' distortion, 2933needs a list of at least 4 sets of coordinates, or 16 numbers. Here is the 2934perspective distortion of the built-in "rose:" image. Note how spaces were 2935used to group the 4 sets of coordinate pairs, to make it easier to read and 2936understand.</p> 2937 2938<pre> 2939convert rose: -virtual-pixel black \ 2940 -distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35' \ 2941 rose_3d_rotated.gif" 2942</pre> 2943 2944<p>If more that the required number of coordinate pairs are given for 2945a distortion, the distortion method is 'least squares' fitted to produce the 2946best result for all the coordinate pairs given. If less than the ideal number 2947of points are given, the distort will generally fall back to a simpler form of 2948distortion that can handles the smaller number of coordinates (usually a linear 2949'<code>Affine</code>' distortion). </p> 2950 2951<p>By using more coordinates you can make use of image registration tool to 2952find matching coordinate pairs in overlapping images, so as to improve the 2953'fit' of the distortion. Of course a bad coordinate pair can also make the 2954'fit' worse. Caution is always advised. </p> 2955 2956<p>Colors are acquired from the source image according to a cylindrical 2957resampling <a href="command-line-options.html#filter" >-filter</a>, using a special technique known as 2958EWA resampling. This produces very high quality results, especially when 2959images become smaller (minified) in the output, which is very common when 2960using '<code>perspective</code>' distortion. For example here we view 2961a infinitely tiled 'plane' all the way to the horizon. </p> 2962 2963<pre> 2964convert -size 90x90 pattern:checkerboard -normalize -virtual-pixel tile \ 2965 -distort perspective '0,0,5,45 89,0,45,46 0,89,0,89 89,89,89,89' \ 2966 checks_tiled.jpg 2967</pre> 2968 2969<p>Note that a infinitely tiled perspective images involving the horizon can 2970be very slow, because of the number of pixels that are compressed to generate 2971each individual pixel close to the 'horizon'. You can turn off EWA 2972resampling, by specifying the special <a href="command-line-options.html#filter" >-filter</a> setting of 2973'<code>point</code>' (recommended if you plan to use super-sampling instead). 2974</p> 2975 2976<p>If an image generates <i>invalid pixels</i>, such as the 'sky' in the last 2977example, <a href="command-line-options.html#distort" >-distort</a> will use the current <a 2978href="command-line-options.html#alpha-color" >-alpha-color</a> setting for these pixels. If you do not 2979what these pixels to be visible, set the color to match the rest of the 2980ground. </p> 2981 2982<p>The output image size will by default be the same as the input image. This 2983means that if the part of the distorted image falls outside the viewed area of 2984the 'distorted space', those parts is clipped and lost. However if you use 2985the plus form of the operator (<a href="command-line-options.html#distort" >+distort</a>) the operator 2986will attempt (if possible) to show the whole of the distorted image, while 2987retaining a correct 'virtual canvas' offset, for image layering. This offset 2988may need to be removed using <a href="command-line-options.html#repage" >+repage</a>, to remove if it 2989is unwanted. </p> 2990 2991<p>Setting <a href="command-line-options.html#verbose" >-verbose</a> setting, will cause <a 2992href="command-line-options.html#distort" >-distort</a> to attempt to output the internal coefficients, 2993and the <a href="command-line-options.html#fx" >-fx</a> equivalent to the distortion, for expert study, 2994and debugging purposes. This many not be available for all distorts. </p> 2995 2996<p>You can alternatively specify a special "<code><a href="command-line-options.html#define" 2997>-define</a> distort:viewport={geometry_string}</code>" setting which will 2998specify the size and the offset of the generated 'viewport' image of the 2999distorted image space.</p> 3000 3001<p>Setting a "<code><a href="command-line-options.html#define" >-define</a> 3002distort:scale=<var>scale_factor</var></code>" will scale the output image (viewport or 3003otherwise) by that factor without changing the viewed contents of the 3004distorted image. This can be used either for 'super-sampling' the image for 3005a higher quality result, or for panning and zooming around the image (with 3006appropriate viewport changes, or post-distort cropping and resizing). </p> 3007 3008<p>Setting "<code><a href="command-line-options.html#define" >-define</a> resample:verbose=1</code>" 3009will output the cylindrical filter lookup table created by the EWA (Elliptical 3010Weighted Average) resampling algorithm. Note this table uses a squared radius 3011lookup value. This is typically only used for debugging EWA resampling. </p> 3012 3013 3014<div style="margin: auto;"> 3015 <h3 class="magick-header"><a id="distribute-cache"></a>-distribute-cache <var>port</var></h3> 3016</div> 3017 3018<p class="magick-description">launch a distributed pixel cache server. </p> 3019 3020<div style="margin: auto;"> 3021 <h3 class="magick-header"><a id="dither"></a>-dither <var>method</var></h3> 3022</div> 3023 3024<p class="magick-description">Apply a Riemersma or Floyd-Steinberg error diffusion dither to 3025images when general color reduction is applied via an option, or automagically 3026when saving to specific formats. This enabled by default.</p> 3027 3028<p>Dithering places two or more colors in neighboring pixels so that to the 3029eye a closer approximation of the images original color is reproduced. This 3030reduces the number of colors needed to reproduce the image but at the cost of 3031a lower level pattern of colors. Error diffusion dithers can use any set of 3032colors (generated or user defined) to an image. </p> 3033 3034<p>Dithering is turned on by default, to turn it off use the plus form of the 3035setting, <a href="command-line-options.html#dither">+dither</a>. This will also also render PostScript 3036without text or graphic aliasing. Disabling dithering often (but not always) 3037leads to faster process, a smaller number of colors, but more cartoon like 3038image coloring. Generally resulting in 'color banding' effects in areas with 3039color gradients. </p> 3040 3041<p>The color reduction operators <a href="command-line-options.html#colors">-colors</a>, <a 3042href="command-line-options.html#monochrome">-monochrome</a>, <a href="command-line-options.html#remap ">-remap</a>, and <a 3043href="command-line-options.html#posterize">-posterize</a>, apply dithering to images using the reduced 3044color set they created. These operators are also used as part of automatic 3045color reduction when saving images to formats with limited color support, such 3046as <code>GIF:</code>, <code>XBM:</code>, and others, so dithering may also be used 3047in these cases. </p> 3048 3049<p>Alternatively you can use <a href="command-line-options.html#random-threshold">-random-threshold</a> 3050to generate purely random dither. Or use <a 3051href="command-line-options.html#ordered-dither">-ordered-dither</a> to apply threshold mapped dither 3052patterns, using uniform color maps, rather than specific color maps. </p> 3053 3054 3055<div style="margin: auto;"> 3056 <h3 class="magick-header"><a id="draw"></a>-draw <var>string</var></h3> 3057</div> 3058 3059<p class="magick-description">Annotate an image with one or more graphic primitives.</p> 3060 3061<p>Use this option to annotate or decorate an image with one or more graphic 3062primitives. The primitives include shapes, text, transformations, and pixel 3063operations.</p> 3064 3065<p>The shape primitives:</p> 3066 3067<dl class="dl-horizontal"> 3068<dt>point</dt><dd> x,y</dd> 3069<dt>line</dt><dd> x0,y0 x1,y1</dd> 3070<dt>rectangle</dt><dd> x0,y0 x1,y1</dd> 3071<dt>roundRectangle</dt><dd> x0,y0 x1,y1 wc,hc</dd> 3072<dt>arc</dt><dd> x0,y0 x1,y1 a0,a1</dd> 3073<dt>ellipse</dt><dd> x0,y0 rx,ry a0,a1</dd> 3074<dt>circle</dt><dd> x0,y0 x1,y1</dd> 3075<dt>polyline</dt><dd> x0,y0 ... xn,yn</dd> 3076<dt>polygon</dt><dd> x0,y0 ... xn,yn</dd> 3077<dt>bezier</dt><dd> x0,y0 ... xn,yn</dd> 3078<dt>path</dt><dd>specification </dd> 3079<dt>image</dt><dd> operator x0,y0 w,h filename</dd> 3080</dl> 3081 3082<p>The text primitive:</p> 3083 3084<dl class="dl-horizontal"> 3085<dt>text</dt><dd>x0,y0 string</dd> 3086</dl> 3087<p>The text gravity primitive:</p> 3088 3089<dl class="dl-horizontal"> 3090<dt>gravity</dt><dd>NorthWest, North, NorthEast, West, Center, East, SouthWest, South, or SouthEast</dd> 3091</dl> 3092 3093<p>The text gravity primitive only affects the placement of text and does not 3094interact with the other primitives. It is equivalent to using the <a 3095href="command-line-options.html#gravity">-gravity</a> command-line option, except that it is limited in 3096scope to the <a href="command-line-options.html#draw">-draw</a> option in which it appears.</p> 3097 3098<p>The transformation primitives:</p> 3099 3100<dl class="dl-horizontal"> 3101<dt>rotate</dt><dd>degrees</dd> 3102<dt>translate</dt><dd>dx,dy</dd> 3103<dt>scale</dt><dd>sx,sy</dd> 3104<dt>skewX</dt><dd>degrees</dd> 3105<dt>skewY</dt><dd>degrees</dd> 3106</dl> 3107 3108<p>The pixel operation primitives:</p> 3109 3110<dl class="dl-horizontal"> 3111<dt>color</dt><dd>x0,y0 method</dd> 3112<dt>matte</dt><dd>x0,y0 method</dd> 3113</dl> 3114 3115<p>The shape primitives are drawn in the color specified by the preceding <a 3116href="command-line-options.html#fill">-fill</a> setting. For unfilled shapes, use <a 3117href="command-line-options.html#fill">-fill none</a>. You can optionally control the stroke (the 3118"outline" of a shape) with the <a href="command-line-options.html#stroke">-stroke</a> and <a 3119href="command-line-options.html#strokewidth">-strokewidth</a> settings.</p> 3120 3121<p>A <code>point</code> primitive is specified by a single <var>point</var> in the 3122pixel plane, that is, by an ordered pair of integer coordinates, 3123<var>x</var>,<var>y</var>. (As it involves only a single pixel, a <code>point</code> 3124primitive is not affected by <a href="command-line-options.html#stroke">-stroke</a> or <a 3125href="command-line-options.html#strokewidth">-strokewidth</a>.)</p> 3126 3127<p>A <code>line</code> primitive requires a start point and end point.</p> 3128 3129<p>A <code>rectangle</code> primitive is specified by the pair of points at the 3130upper left and lower right corners.</p> 3131 3132<p>A <code>roundRectangle</code> primitive takes the same corner points as 3133a <code>rectangle</code> followed by the width and height of the rounded corners 3134to be removed.</p> 3135 3136<p>The <code>circle</code> primitive makes a disk (filled) or circle (unfilled). 3137Give the center and any point on the perimeter (boundary).</p> 3138 3139<p>The <code>arc</code> primitive is used to inscribe an elliptical segment in 3140to a given rectangle. An <code>arc</code> requires the two corners used for 3141<code>rectangle</code> (see above) followed by the start and end angles of the 3142arc of the segment segment (e.g. 130,30 200,100 45,90). The start and end 3143points produced are then joined with a line segment and the resulting segment 3144of an ellipse is filled.</p> 3145 3146<p>Use <code>ellipse</code> to draw a partial (or whole) ellipse. Give the 3147center point, the horizontal and vertical "radii" (the <var>semi-axes</var> of 3148the ellipse) and start and end angles in degrees (e.g. 100,100 100,150 31490,360).</p> 3150 3151<p>The <code>polyline</code> and <code>polygon</code> primitives require three or 3152more points to define their perimeters. A <code>polyline</code> is simply 3153a <code>polygon</code> in which the final point is not stroked to the start 3154point. When unfilled, this is a <var>polygonal line</var>. If the <a 3155href="command-line-options.html#stroke">-stroke</a> setting is <code>none</code> (the default), then 3156a <code>polyline</code> is identical to a <code>polygon</code>. </p> 3157 3158<p>A <var>coordinate</var> is a pair of integers separated by a space or 3159optional comma. </p> 3160 3161<p>As an example, to define a circle centered at 100,100 that extends to 3162150,150 use:</p> 3163 3164<pre> 3165-draw 'circle 100,100 150,150' 3166</pre> 3167 3168<p>The <code>Bezier</code> primitive creates a spline curve and requires three 3169or points to define its shape. The first and last points are the 3170<var>knots</var> and these points are attained by the curve, while any 3171intermediate coordinates are <var>control points</var>. If two control points 3172are specified, the line between each end knot and its sequentially respective 3173control point determines the tangent direction of the curve at that end. If 3174one control point is specified, the lines from the end knots to the one 3175control point determines the tangent directions of the curve at each end. If 3176more than two control points are specified, then the additional control points 3177act in combination to determine the intermediate shape of the curve. In order 3178to draw complex curves, it is highly recommended either to use the 3179<code>path</code> primitive or to draw multiple four-point bezier segments with 3180the start and end knots of each successive segment repeated. For example:</p> 3181 3182<pre> 3183-draw 'bezier 20,50 45,100 45,0 70,50' 3184-draw 'bezier 70,50 95,100 95,0 120,50' 3185</pre> 3186 3187<p>A <code>path</code> represents an outline of an object, defined in terms of 3188moveto (set a new current point), lineto (draw a straight line), curveto (draw 3189a Bezier curve), arc (elliptical or circular arc) and closepath (close the 3190current shape by drawing a line to the last moveto) elements. Compound paths 3191(i.e., a path with subpaths, each consisting of a single moveto followed by 3192one or more line or curve operations) are possible to allow effects such as 3193<var>donut holes</var> in objects. (See <a 3194href="http://www.w3.org/TR/SVG/paths.html">Paths</a>.)</p> 3195 3196<p>Use <code>image</code> to composite an image with another image. Follow the 3197image keyword with the composite operator, image location, image size, and 3198filename:</p> 3199 3200<pre> 3201-draw 'image SrcOver 100,100 225,225 image.jpg' 3202</pre> 3203 3204<p>You can use 0,0 for the image size, which means to use the actual 3205dimensions found in the image header. Otherwise, it is scaled to the given 3206dimensions. See <a href="compose.html">Alpha Compositing</a> for 3207a detailed discussion of alpha composition methods that are available. </p> 3208 3209<p>The "special augmented compose operators" such as "dissolve" that require 3210arguments cannot be used at present with the <code>-draw image</code> option. 3211 </p> 3212 3213<p>Use <code>text</code> to annotate an image with text. Follow the text 3214coordinates with a string. If the string has embedded spaces, enclose it in 3215single or double quotes.</p> 3216 3217<p>For example, the following annotates the image with <code>Works like 3218magick!</code> for an image titled <code>bird.miff</code>. </p> 3219 3220<pre> 3221-draw "text 100,100 'Works like magick!' " 3222</pre> 3223 3224<p>See the <a href="command-line-options.html#annotate">-annotate</a> option for another convenient way 3225to annotate an image with text.</p> 3226 3227<p>The <code>rotate</code> primitive rotates subsequent shape primitives and 3228text primitives about the origin of the main image. If the <a 3229href="command-line-options.html#region">-region</a> option precedes the <a href="command-line-options.html#draw">-draw</a> 3230option, the origin for transformations is the upper left corner of the 3231region.</p> 3232 3233<p>The <code>translate</code> primitive translates subsequent shape and text 3234primitives.</p> 3235 3236<p>The <code>scale</code> primitive scales them.</p> 3237 3238<p>The <code>skewX</code> and <code>skewY</code> primitives skew them with respect 3239to the origin of the main image or the region.</p> 3240 3241<p>The transformations modify the current affine matrix, which is initialized 3242from the initial affine matrix defined by the <a href="command-line-options.html#affine">-affine</a> 3243option. Transformations are cumulative within the <a href="command-line-options.html#draw">-draw</a> 3244option. The initial affine matrix is not affected; that matrix is only changed 3245by the appearance of another <a href="command-line-options.html#affine">-affine</a> option. If another 3246<a href="command-line-options.html#draw">-draw</a> option appears, the current affine matrix is 3247reinitialized from the initial affine matrix.</p> 3248 3249<p>Use the <code>color</code> primitive to change the color of a pixel to the 3250fill color (see <a href="command-line-options.html#fill">-fill</a>). Follow the pixel coordinate with 3251a method:</p> 3252 3253<pre> 3254point 3255replace 3256floodfill 3257filltoborder 3258reset 3259</pre> 3260 3261<p>Consider the target pixel as that specified by your coordinate. The 3262<code>point</code> method recolors the target pixel. The <code>replace</code> 3263method recolors any pixel that matches the color of the target pixel. 3264<code>Floodfill</code> recolors any pixel that matches the color of the target 3265pixel and is a neighbor, whereas <code>filltoborder</code> recolors any neighbor 3266pixel that is not the border color. Finally, <code>reset</code> recolors all 3267pixels.</p> 3268 3269<p>Use <code>matte</code> to the change the pixel matte value to transparent. 3270Follow the pixel coordinate with a method (see the <code>color</code> primitive 3271for a description of methods). The <code>point</code> method changes the matte 3272value of the target pixel. The <code>replace</code> method changes the matte 3273value of any pixel that matches the color of the target pixel. 3274<code>Floodfill</code> changes the matte value of any pixel that matches the 3275color of the target pixel and is a neighbor, whereas <code>filltoborder</code> 3276changes the matte value of any neighbor pixel that is not the border color (<a 3277href="command-line-options.html#bordercolor">-bordercolor</a>). Finally <code>reset</code> changes the 3278matte value of all pixels.</p> 3279 3280<p>You can set the primitive color, font, and font bounding box color with <a 3281href="command-line-options.html#fill">-fill</a>, <a href="command-line-options.html#font">-font</a>, and <a href="command-line-options.html#box">-box</a> 3282respectively. Options are processed in command line order so be sure to use 3283these options <var>before</var> the <a href="command-line-options.html#draw">-draw</a> option.</p> 3284 3285<p>Strings that begin with a number must be quoted (e.g. use '1.png' rather 3286than 1.png).</p> 3287 3288<p>Drawing primitives conform to the <a href="magick-vector-graphics.html" >Magick 3289Vector Graphics</a> format.</p> 3290 3291 3292<div style="margin: auto;"> 3293 <h3 class="magick-header"><a id="duplicate"></a>-duplicate <var>count,indexes</var></h3> 3294</div> 3295 3296<p class="magick-description">duplicate an image one or more times.</p> 3297 3298<p>Specify the count and the image to duplicate by its index in the sequence. 3299The first image is index 0. Negative indexes are relative to the end of the 3300sequence, for example, -1 represents the last image of the sequence. Specify 3301a range of images with a dash (e.g. 0-4). Separate indexes with a comma (e.g. 33020,2). Use <code>+duplicate</code> to duplicate the last image in the current 3303image sequence.</p> 3304 3305<div style="margin: auto;"> 3306 <h3 class="magick-header"><a id="edge"></a>-edge <var>radius</var></h3> 3307</div> 3308 3309<p class="magick-description">detect edges within an image.</p> 3310 3311<div style="margin: auto;"> 3312 <h3 class="magick-header"><a id="emboss"></a>-emboss <var>radius</var></h3> 3313</div> 3314 3315<p class="magick-description">emboss an image.</p> 3316 3317<div style="margin: auto;"> 3318 <h3 class="magick-header"><a id="encipher"></a>-encipher <var>filename</var></h3> 3319</div> 3320 3321<p class="magick-description">Encipher pixels for later deciphering by <a href="command-line-options.html#decipher">-decipher</a>.</p> 3322 3323<p>Get the passphrase from the file specified by <var>filename</var>.</p> 3324 3325<p>For more information, see the webpage, <a 3326href="http://www.imagemagick.org/www/cipher.html">ImageMagick: Encipher or 3327Decipher an Image</a>.</p> 3328 3329 3330 3331<div style="margin: auto;"> 3332 <h3 class="magick-header"><a id="encoding"></a>-encoding <var>type</var></h3> 3333</div> 3334 3335<p class="magick-description">specify the text encoding.</p> 3336 3337<p>Choose from</p> 3338 3339<pre> 3340AdobeCustom AdobeExpert 3341AdobeStandard AppleRoman 3342BIG5 GB2312 3343Latin 2 None 3344SJIScode Symbol 3345Unicode Wansung 3346</pre> 3347 3348<div style="margin: auto;"> 3349 <h3 class="magick-header"><a id="endian"></a>-endian <var>type</var></h3> 3350</div> 3351 3352<p class="magick-description">Specify endianness (<code>MSB</code> or <code>LSB</code>) of the image.</p> 3353 3354<p>To print a complete list of endian types, use the <a href="command-line-options.html#list">-list endian</a> option.</p> 3355 3356<p>Use <a href="command-line-options.html#endian">+endian</a> to revert to unspecified endianness.</p> 3357 3358 3359<div style="margin: auto;"> 3360 <h3 class="magick-header"><a id="enhance"></a>-enhance</h3> 3361</div> 3362 3363<p class="magick-description">Apply a digital filter to enhance a noisy image.</p> 3364 3365 3366<div style="margin: auto;"> 3367 <h3 class="magick-header"><a id="equalize"></a>-equalize</h3> 3368</div> 3369 3370<p class="magick-description">perform histogram equalization on the image channel-by-channel.</p> 3371 3372<p>To perform histogram equalization on all channels in concert, transform the 3373image into some other color space, such as HSL, OHTA, YIQ or YUV, then 3374equalize the appropriate intensity-like channel, then convert back to RGB.</p> 3375 3376<p>For example using HSL, we have: ... <code>-colorspace HSL -channel lightness 3377-equalize -colorspace RGB</code> ...</p> 3378 3379<p>For YIQ, YUV and OHTA use the red channel. For example, OHTA is a principal 3380components transformation that puts most of the information in the first 3381channel. Here we have ... <code>-colorspace OHTA -channel red -equalize 3382-colorspace RGB</code> ...</p> 3383 3384<div style="margin: auto;"> 3385 <h3 class="magick-header"><a id="evaluate"></a>-evaluate <var>operator value</var></h3> 3386</div> 3387 3388<p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or logical expression.</p> 3389 3390<p>(See the <a href="command-line-options.html#function" >-function</a> operator for some 3391multi-parameter functions. See the <a href="command-line-options.html#fx" >-fx</a> operator if more 3392elaborate calculations are needed.)</p> 3393 3394<p>The behaviors of each <var>operator</var> are summarized in the 3395following list. For brevity, the numerical value of a "pixel" referred to 3396below is the value of the corresponding channel of that pixel, while 3397a "normalized pixel" is that number divided by the maximum 3398(installation-dependent) value <var>QuantumRange</var>. (If 3399normalized pixels are used, they are restored, following the other 3400calculations, to the full range by multiplying by <var>QuantumRange</var>.)</p> 3401 3402<table class="table table-condensed table-striped"> 3403 <col width="25%" /> 3404 <col width="75%" /> 3405 <thead> 3406 <tr> 3407 <th><var>operator</var></th> 3408 <th>Summary (see further below for details)</th> 3409 </tr> 3410 </thead> 3411 <tbody> 3412 3413 <tr><td>Abs </td> <td>Add <var>value</var> to pixels and return absolute value. </td></tr> 3414 <tr><td>Add </td> <td>Add <var>value</var> to pixels. </td></tr> 3415 <tr><td>AddModulus </td> <td>Add <var>value</var> to pixels modulo <var>QuantumRange</var>.</td></tr> 3416 <tr><td>And </td> <td>Binary AND of pixels with <var>value</var>.</td></tr> 3417 <tr><td>Cos, Cosine </td> <td>Apply cosine to pixels with frequency <var>value</var> with 50% bias added.</td></tr> 3418 <tr><td>Divide </td> <td>Divide pixels by <var>value</var>.</td></tr> 3419 <tr><td>Exp </td> <td>base-e exponential function</td></tr> 3420 <tr><td>Exponential </td> <td>base-e exponential function</td></tr> 3421 <tr><td>LeftShift </td> <td>Shift the pixel values left by <var>value</var> bits (i.e., multiply pixels by 2<sup><var>value</var></sup>).</td></tr> 3422 <tr><td>Log </td> <td>Apply scaled logarithm to normalized pixels.</td></tr> 3423 <tr><td>Max </td> <td>Set pixels to maximum of <var>value</var> and current pixel <var>value</var> (i.e. set any pixels currently less than <var>value</var> to <var>value</var>).</td></tr> 3424 <tr><td>Mean </td> <td>Add the <var>value</var> and divide by 2.</td></tr> 3425 <tr><td>Median </td> <td>Choose the median value from an image sequence.</td></tr> 3426 <tr><td>Min </td> <td>Set pixels to minimum of <var>value</var> and current pixel <var>value</var> (i.e. set any pixels currently greater than <var>value</var> to <var>value</var>).</td></tr> 3427 <tr><td>Multiply </td> <td>Multiply pixels by <var>value</var>.</td></tr> 3428 <tr><td>Or </td> <td>Binary OR of pixels with <var>value</var>.</td></tr> 3429 <tr><td>Pow </td> <td>Raise normalized pixels to the power <var>value</var>.</td></tr> 3430 <tr><td>RightShift </td> <td>Shift the pixel values right by <var>value</var> bits (i.e., divide pixels by 2<sup><var>value</var></sup>).</td></tr> 3431 <tr><td>RMS</td> <td>Square the pixel and add the <var>value</var>.</td></tr> 3432 <tr><td>RootMeanSquare</td> <td>Square the pixel and add the <var>value</var>.</td></tr> 3433 <tr><td>Set </td> <td>Set pixel equal to <var>value</var>.</td></tr> 3434 <tr><td>Sin, Sine </td> <td>Apply sine to pixels with frequency <var>value</var> with 50% bias added.</td></tr> 3435 <tr><td>Subtract </td> <td>Subtract <var>value</var> from pixels.</td></tr> 3436 <tr><td>Xor </td> <td>Binary XOR of pixels with <var>value.</var></td></tr> 3437 3438 <tr><td> </td><td> </td></tr> 3439 3440 <tr><td>Gaussian-noise</td><td> </td></tr> 3441 <tr><td>Impulse-noise</td><td> </td></tr> 3442 <tr><td>Laplacian-noise</td><td> </td></tr> 3443 <tr><td>Multiplicative-noise</td> <td>(These are equivalent to the corresponding <a href="command-line-options.html#noise" >-noise</a> operators.)</td></tr> 3444 <tr><td>PoissonNoise</td><td> </td></tr> 3445 <tr><td>Uniform-noise</td><td> </td></tr> 3446 3447 <tr><td> </td><td> </td></tr> 3448 3449 <tr><td>Threshold </td> <td>Threshold pixels larger than <var>value</var>.</td></tr> 3450 <tr><td>ThresholdBlack </td> <td>Threshold pixels to zero values equal to or below <var>value</var>.</td></tr> 3451 <tr><td>ThresholdWhite </td> <td>Threshold pixels to maximum values above <var>value</var>. </td></tr> 3452 </tbody> 3453 </table> 3454 3455<p>The specified functions are applied only to each previously set <a 3456href="command-line-options.html#channel" >-channel</a> in the image. If necessary, the results of the 3457calculations are truncated (clipped) to fit in the interval [0, <var>QuantumRange</var>]. The transparency channel of the image is 3458represented as a 'alpha' values (0 = fully transparent), so, for example, a 3459<code>Divide</code> by 2 of the alpha channel will make the image 3460semi-transparent. Append the percent symbol '<code>%</code>' to specify a value 3461as a percentage of the <var>QuantumRange</var>.</p> 3462 3463<p>To print a complete list of <a href="command-line-options.html#evaluate">-evaluate</a> operators, use 3464<a href="command-line-options.html#list">-list evaluate</a>.</p> 3465 3466<p>The results of the <code>Add</code>, <code>Subtract</code> and 3467<code>Multiply</code> methods can also be achieved using either the <a 3468href="command-line-options.html#level" >-level</a> or the <a href="command-line-options.html#level" >+level</a> operator, with 3469appropriate argument, to linearly modify the overall range of color values. 3470Please note, however, that <a href="command-line-options.html#level" >-level</a> treats transparency as 3471'matte' values (0 = opaque), while <a href="command-line-options.html#level" >-evaluate</a> works with 3472'alpha' values.</p> 3473 3474<p><code>AddModulus</code> has been added as of ImageMagick 6.4.8-4 and provides 3475addition modulo the <var>QuantumRange</var>. It is therefore 3476equivalent to <code>Add</code> unless the resulting pixel value is outside the 3477interval [0, <var>QuantumRange</var>]. </p> 3478 3479<p><code>Exp or Exponential</code> has been added as of ImageMagick 6.6.5-1 and 3480works on normalized pixel values. The <var>value</var> used with 3481<code>Exp</code> should be negative so as to produce a decaying exponential 3482function. Non-negative values will always produce results larger unity and 3483thus outside the interval [0, <var>QuantumRange</var>]. The 3484formula is expressed below. </p> 3485 3486<p class="text-center"> 3487exp(<var>value</var> × <b><var>u</var></b>) 3488</p> 3489 3490<p> If the input image is squared, for example, using <a href="command-line-options.html#-function" 3491>-function polynomial "2 0 0"</a>, then a decaying Gaussian function will be 3492the result.</p> 3493 3494<p><code>Log</code> has been added as of ImageMagick 6.4.2-1 and works on 3495normalized pixel values. This a <var>scaled</var> log function. The <var>value</var> used with <code>Log</code> provides a <var>scaling 3496factor</var> that adjusts the curvature in the graph of the log function. The 3497formula applied to a normalized value <b><var>u</var></b> is below. </p> 3498 3499<p class="text-center"> 3500log(<var>value</var> × <b><var>u</var></b> + 1) / log(<var>value</var> + 1) 3501</p> 3502 3503<p><code>Pow</code> has been added as of ImageMagick 6.4.1-9, and works on 3504normalized pixel values. Note that <code>Pow</code> is related to the <a 3505href="command-line-options.html#gamma" >-gamma</a> operator. For example, <b>-gamma 2</b> is equivalent 3506to <b>-evaluate pow 0.5</b>, i.e., a 'square root' function. The value used 3507with <a href="command-line-options.html#gamma" >-gamma</a> is simply the reciprocal of the value used 3508with <code>Pow</code>.</p> 3509 3510<p><code>Cosine</code> and <code>Sine</code> was added as of IM v6.4.8-8 and 3511converts the image values into a value according to a (co)sine wave function. 3512The synonyms <code>Cos</code> and <code>Sin</code> may also be used. The output 3513is biased 50% and normalized by 50% so as to fit in the respective color value 3514range. The <var>value</var> scaling of the <var>period</var> of the 3515function (its frequency), and thus determines the number of 'waves' that will 3516be generated over the input color range. For example, if the <var>value</var> is 1, the effective period is simply the <var>QuantumRange</var>; but if the <var>value</var> is 2, 3517then the effective period is the <var>half</var> the <var>QuantumRange</var>.</p> 3518 3519<p class="text-center"> 35200.5 + 0.5 × cos(2 π <b><var>u</var></b> × <var>value</var>). 3521</p> 3522 3523<p>See also the <a href="command-line-options.html#function" >-function</a> operator, which is a 3524multi-value version of evaluate. </p> 3525 3526<div style="margin: auto;"> 3527 <h3 class="magick-header"><a id="evaluate-sequence"></a>-evaluate-sequence <var>operator</var></h3> 3528</div> 3529 3530<p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or 3531logical expression over a sequence of images.</p> 3532 3533<p>To print a complete list of <a 3534href="command-line-options.html#evaluate-sequence">-evaluate-sequence</a> operators, use <a 3535href="command-line-options.html#list">-list evaluate</a>.</p> 3536 3537<div style="margin: auto;"> 3538 <h3 class="magick-header"><a id="extent"></a>-extent <var>geometry</var></h3> 3539</div> 3540 3541<p class="magick-description">Set the image size and offset.</p> 3542 3543<p>If the image is enlarged, unfilled areas are set to the background color. 3544To position the image, use offsets in the <var>geometry</var> 3545specification or precede with a <a href="command-line-options.html#gravity">-gravity</a> setting. To 3546specify how to compose the image with the background, use <a href="command-line-options.html#compose" 3547>-compose</a>.</p> 3548 3549<p>This command reduces or expands a JPEG image to fit on an 800x600 3550display. If the aspect ratio of the input image isn't exactly 4:3, then the 3551image is centered on an 800x600 black canvas: </p> 3552 3553<pre> 3554convert input.jpg -resize 800x600 -background black -compose Copy \ 3555 -gravity center -extent 800x600 -quality 92 output.jpg 3556</pre> 3557 3558<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 3559 3560<div style="margin: auto;"> 3561 <h3 class="magick-header"><a id="extract"></a>-extract <var>geometry</var></h3> 3562</div> 3563 3564<p class="magick-description">Extract the specified area from image.</p> 3565 3566<p>This option is most useful for extracting a subregion of a very large raw 3567image. Note that these two commands are equivalent:</p> 3568 3569<pre> 3570convert -size 16000x16000 -depth 8 -extract 640x480+1280+960 \ 3571 image.rgb image.png", 3572convert -size 16000x16000 -depth 8 'image.rgb[640x480+1280+960]' \ 3573 image.rgb image.png" 3574</pre> 3575 3576<p>If you omit the offsets, as in</p> 3577 3578<pre> 3579convert -size 16000x16000 -depth 8 -extract 640x480 \ 3580 image.rgb image.png 3581</pre> 3582 3583<p>the image is <var>resized</var> to the specified dimensions instead, 3584equivalent to:</p> 3585 3586<pre> 3587convert -size 16000x16000 -depth 8 -resize 640x480 image.rgb image.png 3588</pre> 3589 3590<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 3591 3592<div style="margin: auto;"> 3593 <h3 class="magick-header"><a id="family"></a>-family <var>fontFamily</var></h3> 3594</div> 3595 3596<p class="magick-description">Set a font family for text.</p> 3597 3598<p>This setting suggests a font family that ImageMagick should try to use for 3599rendering text. If the family can be found it is used; if not, a default font 3600(e.g., "Arial") or a family known to be similar is substituted (e.g., 3601"Courier" might be used if "System" is requested but not found). </p> 3602 3603<p>For other settings that affect fonts, see the options <a 3604href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a 3605href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 3606 3607<div style="margin: auto;"> 3608 <h3 class="magick-header"><a id="features"></a>-features <var>distance</var></h3> 3609</div> 3610 3611<p class="magick-description">display (co-occurrence matrix) texture measure features for each channel in the image in each of four directions (horizontal, vertical, left and right diagonals) for the specified distance.</p> 3612 3613<pre> 3614Angular Second Moment Sum Entropy 3615Contrast Entropy 3616Correlation Difference Variance 3617Sum of Squares Variance Difference Entropy 3618Inverse Difference Moment Information Measure of Correlation 1 3619Sum Average Information Measure of Correlation 2 3620Sum Variance Maximum Correlation Coefficient 3621</pre> 3622 3623<div style="margin: auto;"> 3624 <h3 class="magick-header"><a id="fft"></a>-fft</h3> 3625</div> 3626 3627<p class="magick-description">implements the forward discrete Fourier transform (DFT).</p> 3628 3629<p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows 3630users in ImageMagick 6.6.0-9). It transforms an image from the normal 3631(spatial) domain to the frequency domain. In the frequency domain, an image is 3632represented as a superposition of complex sinusoidal waves of varying 3633amplitudes. The image x and y coordinates are the possible frequencies along 3634the x and y directions, respectively, and the pixel intensity values are 3635complex numbers that correspond to the sinusoidal wave amplitudes. See for 3636example, <a href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier 3637Transform</a>, <a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier 3638Transform</a> and <a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier 3639Transform</a>.</p> 3640 3641<p>A single image name is provided as output for this option. However, the 3642output result will have two components. It is either a two-frame image or two 3643separate images, depending upon whether the image format specified supports 3644multi-frame images. The reason that we get a dual output result is because the 3645frequency domain represents an image using complex numbers, which cannot be 3646visualized directly. Therefore, the complex values are automagically separated 3647into a two-component image representation. The first component is the 3648magnitude of the complex number and the second is the phase of the complex 3649number. See for example, <a 3650href="http://en.wikipedia.org/wiki/Complex_numbers">Complex Numbers</a>.</p> 3651 3652<p>The magnitude and phase component images must be specified using image 3653formats that do not limit the color or compress the image. Thus, MIFF, TIF, 3654PFM, EXR and PNG are the recommended image formats to use. All of these 3655formats, except PNG support multi-frame images. So for example,</p> 3656 3657<pre> 3658convert image.png -fft fft_image.miff 3659</pre> 3660 3661<p>generates a magnitude image as <code>fft_image.miff[0]</code> and a phase 3662image as <code>fft_image.miff[1]</code>. Similarly,</p> 3663 3664<pre> 3665convert image.png -fft fft_image.png 3666</pre> 3667 3668<p>generates a magnitude image as <code>fft_image-0.png</code> and a phase image 3669as <code>fft_image-1.png</code>. If you prefer this representation, then you can 3670force any of the other formats to produce two output images by including <a 3671href="command-line-options.html#adjoin">+adjoin</a> following -fft in the command line.</p> 3672 3673<p>The input image can be any size, but if not square and even-dimensioned, it 3674is padded automagically to the larger of the width or height of the input 3675image and to an even number of pixels. The padding will occur at the bottom 3676and/or right sides of the input image. The resulting output magnitude and 3677phase images is square at this size. The kind of padding relies on the <a 3678href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting.</p> 3679 3680<p>Both output components will have dynamic ranges that fit within 3681[0, <var>QuantumRange</var>], so that HDRI need not be enabled. 3682Phase values nominally range from 0 to 2*π, but is scaled to span the full 3683dynamic range. (The first few releases had non-HDRI scaled but HDRI not 3684scaled). The magnitude image is not scaled and thus generally will contain 3685very small values. As such, the image normally will appear totally black. In 3686order to view any detail, the magnitude image typically is enhanced with a log 3687function into what is usually called the spectrum. A log function is used to 3688enhance the darker values more in comparison to the lighter values. This can 3689be done, for example, as follows:</p> 3690 3691<pre> 3692convert fft_image.miff[0] -contrast-stretch 0 \ 3693 -evaluate log 1000 fft_image_spectrum.png" 3694</pre> 3695 3696<p>where either <a href="command-line-options.html#contrast-stretch">-contrast-stretch</a> 0 or <a 3697href="command-line-options.html#auto-level">-auto-level</a> is used to scale the image to full dynamic 3698range, first. The argument to the <a href="command-line-options.html#evaluate">-evaluate</a> log 3699typically is specified between 100 and 10,000, depending upon the amount of 3700detail that one wants to bring out in the spectrum. Larger values produce more 3701visible detail. Too much detail, however, may hide the important features.</p> 3702 3703<p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to 3704use <a href="command-line-options.html#fft">-fft</a>.</p> 3705 3706<p>Use <a href="command-line-options.html#fft">+fft</a> to produce two output images that are the real 3707and imaginary components of the complex valued Fourier transform.</p> 3708 3709<p>However, as the real and imaginary components can contain negative values, 3710this requires that IM be configured with HDRI enabled. In this case, you must 3711use either MIFF, TIF, PFM or MPC formats for the real and imaginary component 3712results, since they are formats that preserve both negative and fractional 3713values without clipping them or truncating the fractional part. With either 3714MIFF or TIF, one should add -define quantum:format=32, to allow those image 3715types to work properly in HDRI mode without clipping.</p> 3716 3717<p>The real and imaginary component images resulting from <a 3718href="command-line-options.html#fft">+fft</a> are also square, even dimensioned images due to the same 3719padding that was discussed above for the magnitude and phase component 3720images.</p> 3721 3722<p>See the discussion on HDRI implementations of ImageMagick on the page <a 3723href="high-dynamic-range.html" >High Dynamic-Range Images</a>. For more 3724about HDRI go the ImageMagick <a 3725href="http://www.imagemagick.org/Usage/basics/#hdri" >Usage</a> pages, <a 3726href="http://www.fmwconcepts.com/imagemagick/fourier_transforms/fourier.html" 3727>Fred's Fourier Processing With ImageMagick page</a> or this <a 3728 href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging" >Wikipedia</a> 3729 entry. </p> 3730 3731<p>By default the FFT is normalized (and the IFT is not). Use "<code><a href="command-line-options.html#define" >-define</a> fourier:normalize=forward</code> to explicitly normalize the FFT and unnormalize the IFT.</p> 3732 3733 3734<div style="margin: auto;"> 3735 <h3 class="magick-header"><a id="fill"></a>-fill <var>color</var></h3> 3736</div> 3737 3738<p class="magick-description">color to use when filling a graphic primitive.</p> 3739 3740<p>This option accepts a color name, a hex color, or a numerical RGB, RGBA, 3741HSL, HSLA, CMYK, or CMYKA specification. See <a href="color.html" >Color Names</a> for 3742a description of how to properly specify the color argument.</p> 3743 3744<p>Enclose the color specification in quotation marks to prevent the "#" or 3745the parentheses from being interpreted by your shell.</p> 3746 3747<p>For example,</p> 3748 3749<pre> 3750-fill blue 3751-fill "#ddddff" 3752-fill "rgb(255,255,255)" 3753</pre> 3754 3755<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 3756 3757<p>To print a complete list of color names, use the <a href="command-line-options.html#list">-list color</a> option.</p> 3758 3759<div style="margin: auto;"> 3760 <h3 class="magick-header"><a id="filter"></a>-filter <var>type</var></h3> 3761</div> 3762 3763<p class="magick-description">Use this <var>type</var> of filter when resizing or distorting an image.</p> 3764 3765<p>Use this option to affect the resizing operation of an image during 3766operations such as <a href="command-line-options.html#resize">-resize</a> and <a href="command-line-options.html#distort" 3767>-distort</a>. For example you can use a simple resize filter such as:</p> 3768 3769<pre> 3770Point Hermite Cubic 3771Box Gaussian Catrom 3772Triangle Quadratic Mitchell 3773</pre> 3774 3775<p>The <code>Bessel</code> and <code>Sinc</code> filter is also provided (as well 3776as a faster <code>SincFast</code> equivalent form). However these filters are 3777generally useless on their own as they are infinite filters that are being 3778clipped to the filters support size. Their direct use is not recommended 3779except via expert settings (see below). </p> 3780 3781<p>Instead these special filter functions are typically windowed by a windowing 3782function that the <a href="command-line-options.html#filter" >-filter</a> setting defines. That is 3783using these functions will define a 'Windowed' filter, appropriate to the 3784operator involved. Windowed filters include: </p> 3785 3786<pre> 3787Lanczos Hamming Parzen 3788Blackman Kaiser Welsh 3789Hanning Bartlett Bohman 3790</pre> 3791 3792<p>Also one special self-windowing filter is also provided 3793<code>Lagrange</code>, which will automagically re-adjust its function depending 3794on the current 'support' or 'lobes' expert settings (see below).</p> 3795 3796<p>If you do not select a filter with this option, the filter defaults to 3797<code>Mitchell</code> for a colormapped image, an image with a matte channel, or 3798if the image is enlarged. Otherwise the filter default to 3799<code>Lanczos</code>.</p> 3800 3801<p>To print a complete list of resize filters, use the <a href="command-line-options.html#list">-list 3802filter</a> option.</p> 3803 3804<p>You can modify how the filter behaves as it scales your image through the 3805use of these expert settings (see also <a href="command-line-options.html#define" >-define</a> and <a 3806href="command-line-options.html#set" >-set</a>):-</p> 3807 3808<table class="table table-condensed table-striped"> 3809 <tr> 3810 <td>-define filter:blur=<var>factor</var></td> 3811 <td>Scale the X axis of the filter (and its window). Use > 1.0 for 3812 blurry or < 1.0 for sharp. This should only be used with Gaussian and 3813 Gaussian-like filters simple filters, or you may not get the expected 3814 results. </td> 3815 </tr> 3816 3817 <tr> 3818 <td>-define filter:support=<var>radius</var></td> 3819 <td>Set the filter support radius. Defines how large the filter should be and 3820 thus directly defines how slow the filtered resampling process is. All 3821 filters have a default 'preferred' support size. Some filters like 3822 <code>Lagrange</code> and windowed filters adjust themselves depending on 3823 this value. With simple filters this value either does nothing (but slow 3824 the resampling), or will clip the filter function in a detrimental way. 3825 </td> 3826 </tr> 3827 3828 <tr> 3829 <td>-define filter:lobes=<var>count</var></td> 3830 <td>Set the number of lobes to use for the Sinc/Bessel filter. This an 3831 alternative way of specifying the 'support' range of the filter, that is 3832 designed to be more suited to windowed filters, especially when used for 3833 image distorts.</td> 3834 </tr> 3835 3836 <tr> 3837 <td>-define filter:sigma=<var>value</var></td> 3838 <td>The 'sigma' value used to define the <code>Gaussian</code> filter. Default 3839 sigma value is '<code>0.5</code>'. It only effects <code>Gaussian</code> but 3840 does not shrink (but may enlarge) the filter's 'support'. It can be used 3841 to generate very small blurs but without the filter 'missing' pixels due 3842 to using a small support setting. A larger value of '<code>0.707</code>' 3843 (a value of '1/sqrt(2)') is another common setting. </td> 3844 </tr> 3845 3846 <tr> 3847 <td>-define filter:b=<var>b-spline_factor</var></td> 3848 <tr> 3849 <td>-define filter:c=<var>keys_alpha_factor</var></td> 3850 <td>Redefine the values used for cubic filters such as <code>Cubic</code>, 3851 <code>Catrom</code>, <code>Mitchel</code>, and <code>Hermite</code>, as well as 3852 the <code>Parzen</code> cubic windowing function. If only one of the values 3853 are defined, the other is set so as to generate a 'Cubic-Keys' filter. 3854 The values meaning was defined by a research paper by 3855 Mitchell-Netravali.</td> 3856 </tr> 3857 3858 <tr> 3859 <td>-define filter:kaiser-beta=<var>value</var></td> 3860 <td>The 'alpha' value used to as part of the Kaiser Windowing function. 3861 Default value is '6.5'. It only effects Kaiser windowing function, and 3862 does not effect any other attributes. 3863 Before ImageMagick v6.7.6-10, this option was known as "filter:alpha", (an 3864 inheritance from the very old "zoom" program). It was changed to bring the 3865 function in line with more modern academic research usage, and better 3866 assign it be more definitive. </td> 3867 </tr> 3868 3869 <tr> 3870 <td>-define filter:kaiser-alpha=<var>value</var></td> 3871 <td>This value when multiplied by 'PI' is equivalent to "kaiser-beta", and 3872 will override that setting. It only effects Kaiser windowing function, 3873 and does not effect any other attributes. </td> 3874 </tr> 3875 3876 <tr> 3877 <td>-define filter:filter=<var>filter_function</var></td> 3878 <td>Use this function directly as the weighting filter. This will allow 3879 you to directly use a windowing function such as <code>Blackman</code>, 3880 as a resampling filter, rather than as its normal usage as a windowing 3881 function. If defined, no windowing function also defined, the window function is set 3882 to <code>Box</code>). Directly specifying <code>Sinc</code> or <code>Jinc</code> 3883 as a filter will also do this. </td> 3884 </tr> 3885 3886 <tr> 3887 <td>-define filter:window=<var>filter_function</var></td> 3888 <td>The IIR (infinite impulse response) filters <code>Sinc</code> and 3889 <code>Jinc</code> are windowed (brought down to zero over the defined 3890 support range) with the given filter. This allows you to specify a filter 3891 function to be used as a windowing function for these IIR filters. 3892 Many of the defined filters are actually windowing functions for these IIR 3893 filters. A typical choices is <code>Box</code>, (which effectively turns 3894 off the windowing function). </td> 3895 </tr> 3896 3897 <tr> 3898 <td>-define filter:win-support=<var>radius</var></td> 3899 <td>Scale windowing function to this size instead. This causes the windowing 3900 (or self-windowing Lagrange filter) to act is if the support window is 3901 larger than what is actually supplied to the calling operator. The filter 3902 however is still clipped to the real support size given. If unset this 3903 will equal the normal filter support size. </td> 3904 </tr> 3905 3906 <tr> 3907 <td>-define filter:verbose=<var>1</var></td> 3908 <td>This causes IM to print information on the final internal filter 3909 selection to standard output. This includes a commented header on the 3910 filter settings being used, and data allowing the filter weights to be 3911 easily graphed. Note however that some filters are internally defined in terms of other filters. The <code>Lanczos</code> filter for example is defined in terms of 3912 a <code>SincFast</code> windowed <code>SincFast</code> filter, while 3913 <code>Mitchell</code> is defined as a general <code>Cubic</code> family filter 3914 with specific 'B' and 'C' settings. </td> 3915 </tr> 3916 3917</table> 3918 3919<p>For example, to get a 8 lobe jinc windowed sinc filter (Genseng filter?):</p> 3920 3921<pre> 3922convert image.png \ 3923 -filter sinc \ 3924 -set filter:window=jinc \ 3925 -set filter:lobes=8 \ 3926 -resize 150% image.jpg" 3927</pre> 3928 3929<p>Or a raw un-windowed Sinc filter with 4 lobes:</p> 3930 3931<pre> 3932convert image.png \ 3933 -set filter:filter=sinc \ 3934 -set filter:lobes=4 \ 3935 -resize 150% image.jpg" 3936</pre> 3937 3938<p>To extract the data for a raw windowing function, combine it with 3939a '<code>Box</code>' filter. For example the '<code>Welch</code> parabolic 3940windowing function. </p> 3941 3942<pre> 3943convert null: -define filter:filter=Box \ 3944 -define filter:window=Welch \ 3945 -define filter:support=1.0 \ 3946 -define filter:verbose=1 \ 3947 -resize 2 null: > window_welch.dat 3948gnuplot 3949 set grid 3950 plot \"window_welch.dat\" with lines 3951</pre> 3952 3953<p>Note that the use of expert options is provided for image processing experts 3954who have studied and understand how resize filters work. Without this 3955knowledge, and an understanding of the definition of the actual filters 3956involved, using expert settings are more likely to be detrimental to your image 3957resizing.</p> 3958 3959 3960<div style="margin: auto;"> 3961 <h3 class="magick-header"><a id="flatten"></a>-flatten</h3> 3962</div> 3963 3964<p class="magick-description">This is a simple alias for the <a href="command-line-options.html#layers" >-layers</a> method "flatten".</p> 3965 3966 3967<div style="margin: auto;"> 3968 <h3 class="magick-header"><a id="flip"></a>-flip</h3> 3969</div> 3970 3971<p class="magick-description">create a <var>mirror image</var></p> 3972 3973<p>reflect the scanlines in the vertical direction. The image will be mirrored 3974upside-down. </p> 3975 3976 3977<div style="margin: auto;"> 3978 <h3 class="magick-header"><a id="floodfill"></a>-floodfill {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var> <var>color</var></h3> 3979</div> 3980 3981<p class="magick-description">floodfill the image with color at the specified offset.</p> 3982 3983<p>Flood fill starts from the given 'seed point' which is not gravity effected. 3984Any color that matches within <a href="command-line-options.html#fuzz" >-fuzz</a> color distance of the 3985given <var>color</var> argument, connected to that 'seed point' 3986will be replaced with the current <a href="command-line-options.html#fill" >-fill</a> color. </p> 3987 3988<p>Note that if the pixel at the 'seed point' does not itself match the given 3989<var>color</var> (according to <a href="command-line-options.html#fuzz" >-fuzz</a>), then no 3990action will be taken. </p> 3991 3992<p>This operator works more like the <a href="command-line-options.html#opaque" >-opaque</a> option, than 3993a more general flood fill that reads the matching color directly at the 'seed 3994point'. For this form of flood fill, look at <a href="command-line-options.html#draw" >-draw</a> and 3995its 'color floodfill' drawing method. </p> 3996 3997 3998<div style="margin: auto;"> 3999 <h3 class="magick-header"><a id="flop"></a>-flop</h3> 4000</div> 4001 4002<p class="magick-description">create a <var>mirror image</var>.</p> 4003 4004<p>Reflect the scanlines in the horizontal direction, just like the image in 4005a vertical mirror. </p> 4006 4007 4008<div style="margin: auto;"> 4009 <h3 class="magick-header"><a id="font"></a>-font <var>name</var></h3> 4010</div> 4011 4012<p class="magick-description">set the font to use when annotating images with text, or creating labels.</p> 4013 4014<p>To print a complete list of fonts, use the <a href="command-line-options.html#list">-list font</a> 4015option (for versions prior to 6.3.6, use 'type' instead of 'font').</p> 4016 4017<p>In addition to the fonts specified by the above pre-defined list, you can 4018also specify a font from a specific source. For example <code>Arial.ttf</code> 4019is a TrueType font file, <code>ps:helvetica</code> is PostScript font, and 4020<code>x:fixed</code> is X11 font.</p> 4021 4022<p>For other settings that affect fonts, see the options <a 4023href="command-line-options.html#family">-family</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a 4024href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 4025 4026 4027<div style="margin: auto;"> 4028 <h3 class="magick-header"><a id="foreground"></a>-foreground <var>color</var></h3> 4029</div> 4030 4031<p class="magick-description">Define the foreground color for menus.", "display</p> 4032 4033<p>The color is specified using the format described under the <a 4034href="command-line-options.html#fill">-fill</a> option.</p> 4035 4036<p>The default foreground color is black.</p> 4037 4038<div style="margin: auto;"> 4039 <h3 class="magick-header"><a id="format"></a>-format <var>type</var></h3> 4040</div> 4041 4042<p class="magick-description">the image format type.</p> 4043 4044<p>When used with the <code>mogrify</code> utility, this option converts any 4045image to the image <a href="formats.html">format</a> you specify. 4046For a list of image format types supported by ImageMagick, use <a 4047href="command-line-options.html#list">-list format</a>.</p> 4048 4049<p>By default the file is written to its original name. However, if the 4050filename extension matches a supported format, the extension is replaced with 4051the image format type specified with <a href="command-line-options.html#format">-format</a>. For 4052example, if you specify <var>tiff</var> as the format type and the 4053input image filename is <var>image.gif</var>, the output image 4054filename becomes <var>image.tiff</var>.</p> 4055 4056<div style="margin: auto;"> 4057 <h3 class="magick-header"><a id="format_identify_"></a>-format <var>string</var></h3> 4058</div> 4059 4060<p class="magick-description">output formatted image characteristics.</p> 4061 4062<p>See <a href="escape.html">Format and Print Image 4063Properties</a> for an explanation on how to specify the argument to this 4064option.</p> 4065 4066<div style="margin: auto;"> 4067 <h3 class="magick-header"><a id="frame"></a>-frame <var>geometry</var></h3> 4068</div> 4069 4070<p class="magick-description">Surround the image with a border or beveled frame.</p> 4071 4072<p>The color of the border is specified with the <a href="command-line-options.html#alpha-color" 4073>-alpha-color</a> command line option. </p> 4074 4075<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <var>size</var> portion of the <var>geometry</var> argument indicates the amount of extra width and 4076height that is added to the dimensions of the image. If no offsets are given 4077in the <var>geometry</var> argument, then the border added is 4078a solid color. Offsets <var>x</var> and <var>y</var>, if present, specify that 4079the width and height of the border is partitioned to form an outer bevel of 4080thickness <var>x</var> pixels and an inner bevel of thickness 4081<var>y</var> pixels. Negative offsets make no sense as frame arguments. 4082</p> 4083 4084<p>The <a href="command-line-options.html#frame">-frame</a> option is affected by the current <a 4085href="command-line-options.html#compose">-compose</a> setting and assumes that this is using the default 4086'<code>Over</code>' composition method. It generates an image of the appropriate 4087size with the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting, and then 4088draws the frame of four distinct colors close to the current <a 4089href="command-line-options.html#alpha-color">-alpha-color</a>. The original image is then overlaid onto 4090center of this image. This means that with the default compose method of 4091'<code>Over</code>' any transparent parts may be replaced by the current <a 4092href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p> 4093 4094<p>The image composition is not 4095affected by the <a href="command-line-options.html#gravity">-gravity</a> option.</p> 4096 4097 4098<div style="margin: auto;"> 4099 <h3 class="magick-header"><a id="frame_import_"></a>-frame</h3> 4100</div> 4101 4102<p class="magick-description">include the X window frame in the imported image. </p> 4103<div style="margin: auto;"> 4104 <h3 class="magick-header"><a id="function"></a>-function <var>function</var> <var>parameters</var></h3> 4105</div> 4106 4107<p class="magick-description">Apply a function to channel values.</p> 4108 4109<p>This operator performs calculations based on the given arguments to modify 4110each of the color values for each previously set <a 4111href="command-line-options.html#channel">-channel</a> in the image. See <a 4112href="command-line-options.html#evaluate">-evaluate</a> for details concerning how the results of the 4113calculations are handled.</p> 4114 4115<p>This is can be considered a multi-argument version of the <a 4116href="command-line-options.html#evaluate">-evaluate</a> operator. (Added in 4117ImageMagick 6.4.8−8.)</p> 4118 4119<p>Here, <var>parameters</var> is a comma-separated list of 4120numerical values. The number of values varies depending on which <var>function</var> is selected. Choose the <var>function</var> from:</p> 4121 4122<pre> 4123Polynomial 4124Sinusoid 4125Arcsin 4126Arctan 4127</pre> 4128 4129<p>To print a complete list of <a href="command-line-options.html#function">-function</a> operators, 4130use <a href="command-line-options.html#list">-list function</a>. Descriptions follow.</p> 4131 4132<dl class="dl-horizontal"> 4133 <dt>Polynomial</dt> 4134 <dd><p>The <code>Polynomial</code> function takes an arbitrary number of parameters, 4135these being the coefficients of a polynomial, in decreasing order of degree. 4136That is, entering</p> 4137 4138<pre> 4139-function Polynomial <var>a</var><sub><var>n</var></sub>,<var>a</var><sub><var>n</var>-1</sub>,...<var>a</var><sub>1</sub>,<var>a</var><sub>0</sub> 4140</pre> 4141 4142<p>will invoke a polynomial function given by</p> 4143 4144<pre> 4145<var>a</var><sub><var>n</var></sub> <b><var>u</var></b><sup><var>n</var></sup> + <var>a</var><sub><var>n</var>-1</sub> <b><var>u</var></b><sup><var>n</var>-1</sup> + ··· <var>a</var><sub>1</sub> <b><var>u</var></b> + <var>a</var><sub>0</sub>, 4146</pre> 4147 4148<p>where <b><var>u</var></b> is pixel's original normalized channel value.</p> 4149 4150<p>The <code>Polynomial</code> function can be used in place of <code>Set</code> 4151(the <var>constant</var> polynomial) and <code>Add</code>, <code>Divide</code>, 4152<code>Multiply</code>, and <code>Subtract</code> (some <var>linear</var> 4153polynomials) of the <a href="command-line-options.html#evaluate">-evaluate</a> operator. The <a 4154href="command-line-options.html#level">-level</a> operator also affects channels linearly. Some 4155correspondences follow.</p> 4156 4157<table class="table table-condensed table-striped"> 4158 <tr> 4159 <td>-evaluate Set <var>value</var> </td> 4160 <td>-function Polynomial <var>value</var></td> 4161 <td>(Constant functions; set <var>value</var>×100% gray when channels are RGB.)</td> 4162 </tr> 4163 <tr> 4164 <td>-evaluate Add <var>value</var> </td> 4165 <td>-function Polynomial 1,<var>value</var></td> 4166 </tr> 4167 <tr> 4168 <td>-evaluate Subtract <var>value</var> </td> 4169 <td>-function Polynomial 1,−<var>value</var></td> 4170 </tr> 4171 <tr> 4172 <td>-evaluate Multiply <var>value</var> </td> 4173 <td>-function Polynomial <var>value</var>,0</td> 4174 </tr> 4175 <tr> 4176 <td>+level black% x white%</td> 4177 <td>-function Polynomial A,B</td> 4178 <td>(Reduce contrast. Here, A=(white-black)/100 and B=black/100.)</td> 4179 </tr> 4180</table> 4181 4182<p>The <code>Polynomial</code> function gives great versatility, since 4183polynomials can be used to fit any continuous curve to any degree of accuracy 4184desired.</p> 4185 4186</dd> 4187<dt>Sinusoid</dt> 4188<dd> 4189<p>The <code>Sinusoid</code> function can be used to vary the channel values 4190sinusoidally by setting frequency, phase shift, amplitude, and a bias. These 4191values are given as one to four parameters, as follows,</p> 4192 4193<pre> 4194-function <code>Sinusoid</code> <var>freq</var>,[<var>phase</var>,[<var>amp</var>,[<var>bias</var>]]] 4195</pre> 4196 4197<p>where <var>phase</var> is in degrees. (The domain [0,1] of the function 4198corresponds to 0 through <var>freq</var>×360 degrees.) 4199The result is that if a pixel's normalized channel value is originally 4200<b><var>u</var></b>, its resulting normalized value is given by </p> 4201 4202<pre> 4203<var>amp</var> * sin(2*π* (<var>freq</var> * <b><var>u</var></b> + <var>phase</var> / 360)) + <var>bias</var> 4204</pre> 4205 4206<p> For example, the following generates a curve that starts and ends at 0.9 4207(when <b><var>u</var></b>=0 and 1, resp.), oscillating three times between 4208.7−.2=.5 and .7+.2=.9. </p> 4209 4210<pre> 4211-function Sinusoid 3,-90,.2,.7 4212</pre> 4213 4214<p>The default values of <var>amp</var> and <var>bias</var> are both .5. The default for <var>phase</var> 4215is 0.</p> 4216 4217<p>The <code>Sinusoid</code> function generalizes <code>Sin</code> and 4218<code>Cos</code> of the <a href="command-line-options.html#evaluate">-evaluate</a> operator by allowing 4219varying amplitude, phase and bias. The correspondence is as follows.</p> 4220 4221<table class="table table-condensed table-striped"> 4222 <tr> 4223 <td>-evaluate Sin <var>freq</var> </td> 4224 <td>-function Sinusoid <var>freq</var>,0 </td> 4225 </tr> 4226 <tr> 4227 <td>-evaluate Cos <var>freq</var> </td> 4228 <td>-function Sinusoid <var>freq</var>,90 </td> 4229 </tr> 4230</table> 4231 </dd> 4232<dt>ArcSin</dt> 4233<dd> 4234<p>The <code>ArcSin</code> function generates the inverse curve of a Sinusoid, 4235and can be used to generate cylindrical distortion and displacement maps. 4236The curve can be adjusted relative to both the input values and output range 4237of values.</p> 4238 4239<pre> 4240-function <code>ArcSin</code> <var>width</var>,[<var>center</var>,[<var>range</var>,[<var>bias</var>]]] 4241</pre> 4242 4243<p>with all values given in terms of normalized color values (0.0 for black, 42441.0 for white). Defaulting to values covering the full range from 0.0 to 1.0 4245for bout input (<var>width</var>), and output (<var>width</var>) values. '<code>1.0,0.5,1.0,0.5</code>' </p> 4246 4247<pre> 4248<var>range</var>/π * asin( 2/<var>width</var> * ( <b><var>u</var></b> - <var>center</var> ) ) + <var>bias</var> 4249</pre> 4250 4251</dd> 4252<dt>ArcTan</dt> 4253<dd> 4254<p>The <code>ArcTan</code> function generates a curve that smooth crosses from 4255limit values at infinities, though a center using the given slope value. 4256All these values can be adjusted via the arguments.</p> 4257 4258<pre> 4259-function <code>ArcTan</code> <var>slope</var>,[<var>center</var>,[<var>range</var>,[<var>bias</var>]]] 4260</pre> 4261 4262<p>Defaulting to '<code>1.0,0.5,1.0,0.5</code>'. 4263</p> 4264 4265<pre> 4266<var>range</var>/π * atan( <var>slope</var>*π * ( <b><var>u</var></b> - <var>center</var> ) ) + <var>bias</var> 4267</pre> 4268 </dd> 4269 </tr> 4270</dl> 4271 4272 4273 4274<div style="margin: auto;"> 4275 <h3 class="magick-header"><a id="fuzz"></a>-fuzz <var>distance</var>{<var>%</var>}</h3> 4276</div> 4277 4278<p class="magick-description">Colors within this <var>distance</var> are considered equal.</p> 4279 4280<p>A number of algorithms search for a target color. By default the color must 4281be exact. Use this option to match colors that are close to the target color 4282in RGB space. For example, if you want to automagically trim the edges of an 4283image with <a href="command-line-options.html#trim">-trim</a> but the image was scanned and the target 4284background color may differ by a small amount. This option can account for 4285these differences.</p> 4286 4287<p>The <var>distance</var> can be in absolute intensity units or, by 4288appending <code>%</code> as a percentage of the maximum possible intensity (255, 428965535, or 4294967295).</p> 4290 4291<p>Use <a href="command-line-options.html#fuzz" >+fuzz</a> to reset the fuzz value to 0.</p> 4292 4293 4294<div style="margin: auto;"> 4295 <h3 class="magick-header"><a id="fx"></a>-fx <var>expression</var></h3> 4296</div> 4297 4298<p class="magick-description">apply a mathematical expression to an image or image channels.</p> 4299 4300<p>If the first character of <var>expression</var> is <code>@</code>, 4301the expression is read from a file titled by the remaining characters in the 4302string.</p> 4303 4304<p>See <a href="fx.html">FX, 4305The Special Effects Image Operator</a> for a detailed discussion of this 4306option.</p> 4307 4308 4309<div style="margin: auto;"> 4310 <h3 class="magick-header"><a id="gamma"></a>-gamma <var>value</var></h3> 4311</div> 4312 4313<p class="magick-description">level of gamma correction.</p> 4314 4315<p>The same color image displayed on two different workstations may look 4316different due to differences in the display monitor. Use gamma correction to 4317adjust for this color difference. Reasonable values extend from 4318<code>0.8</code> to <code>2.3</code>. Gamma less than 1.0 darkens the image and 4319gamma greater than 1.0 lightens it. Large adjustments to image gamma may 4320result in the loss of some image information if the pixel quantum size is only 4321eight bits (quantum range 0 to 255).</p> 4322 4323<p>Gamma adjusts the image's channel values pixel-by-pixel according to 4324a power law, namely, pow(pixel,1/gamma) or pixel^(1/gamma), where pixel is the 4325normalized or 0 to 1 color value. For example, using a value of gamma=2 is the 4326same as taking the square root of the image.</p> 4327 4328<p>You can apply separate gamma values to the red, green, and blue channels of 4329the image with a gamma value list delimited with commas (e.g., 4330<code>1.7,2.3,1.2</code>).</p> 4331 4332<p>Use <a href="command-line-options.html#gamma">+gamma <var>value</var></a> to set the 4333image gamma level without actually adjusting the image pixels. This option 4334is useful if the image is of a known gamma but not set as an image attribute 4335(e.g. PNG images). Write the "file gamma" which is the reciprocal of the 4336display gamma; e.g., if your image is sRGB and you want to write a PNG gAMA 4337chunk, use</p> 4338 4339<pre> 4340convert input.png +gamma .45455 output.png 4341</pre> 4342 4343<p>(0.45455 is 1/2.2)</p> 4344 4345<p>Note that gamma adjustments are also available via the <a href="command-line-options.html#level">-level</a> operator.</p> 4346 4347<div style="margin: auto;"> 4348 <h3 class="magick-header"><a id="gaussian-blur"></a>-gaussian-blur <var>radius</var><br />-gaussian-blur <var>radius</var>x<var>sigma</var></h3> 4349</div> 4350 4351<p class="magick-description">Blur the image with a Gaussian operator.</p> 4352 4353<p>Convolve the image with a Gaussian or normal distribution using the given 4354<var >Sigma</var> value. The formula is:</p> 4355 4356<p class="text-center"><img class="img-thumbnail" alt="gaussian distribution" width="243px" height="42px" src="/images/gaussian-blur.png"/> </p> 4357 4358<p>The <var >Sigma</var> value is the important argument, and 4359determines the actual amount of blurring that will take place. </p> 4360 4361<p>The <var >Radius</var> is only used to determine the size of the 4362array which will hold the calculated Gaussian distribution. It should be an 4363integer. If not given, or set to zero, IM will calculate the largest possible 4364radius that will provide meaningful results for the Gaussian distribution. 4365</p> 4366 4367<p>The larger the <var >Radius</var> the radius the slower the 4368operation is. However too small a <var >Radius</var>, and sever 4369aliasing effects may result. As a guideline, <var >Radius</var> 4370should be at least twice the <var >Sigma</var> value, though three 4371times will produce a more accurate result. </p> 4372 4373<p>This differs from the faster <a href="command-line-options.html#blur">-blur</a> operator in that a 4374full 2-dimensional convolution is used to generate the weighted average of the 4375neighboring pixels. </p> 4376 4377<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 4378pixels which are outside the image proper are blurred into the final result. 4379</p> 4380 4381 4382<div style="margin: auto;"> 4383 <h3 class="magick-header"><a id="geometry"></a>-geometry <var>geometry</var></h3> 4384</div> 4385 4386<p class="magick-description">Set the preferred size and location of the image.</p> 4387 4388<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 4389 4390<div style="margin: auto;"> 4391 <h3 class="magick-header"><a id="gravity"></a>-gravity <var>type</var></h3> 4392</div> 4393 4394<p class="magick-description">Sets the current gravity suggestion for various other settings and options.</p> 4395 4396<p>Choices include: <code>NorthWest</code>, <code>North</code>, 4397<code>NorthEast</code>, <code>West</code>, <code>Center</code>, <code>East</code>, 4398<code>SouthWest</code>, <code>South</code>, <code>SouthEast</code>. Use <a 4399href="command-line-options.html#list">-list gravity</a> to get a complete list of <a 4400href="command-line-options.html#gravity">-gravity</a> settings available in your ImageMagick 4401installation.</p> 4402 4403<p>The direction you choose specifies where to position text or subimages. For 4404example, a gravity of <code>Center</code> forces the text to be centered within 4405the image. By default, the image gravity is <code>undefined</code>. See <a 4406href="command-line-options.html#draw">-draw</a> for more details about graphic primitives. Only the 4407text primitive of <a href="command-line-options.html#draw">-draw</a> is affected by the <a 4408href="command-line-options.html#gravity">-gravity</a> option.</p> 4409 4410<p>The <a href="command-line-options.html#gravity">-gravity</a> option is also used in concert with the 4411<a href="command-line-options.html#geometry">-geometry</a> setting and other settings or options that 4412take <var>geometry</var> as an argument, such as the <a 4413href="command-line-options.html#crop">-crop</a> option. </p> 4414 4415<p>If a <a href="command-line-options.html#gravity">-gravity</a> setting occurs before another option 4416or setting having a <var>geometry</var> argument that specifies an 4417offset, the offset is usually applied to the point within the image suggested 4418by the <a href="command-line-options.html#gravity">-gravity</a> argument. Thus, in the following 4419command, for example, suppose the file <code>image.png</code> has dimensions 4420200x100. The offset specified by the argument to <a href="command-line-options.html#region">-region</a> 4421is (−40,+20). The argument to <a href="command-line-options.html#gravity">-gravity</a> is 4422<code>Center</code>, which suggests the midpoint of the image, at the point 4423(100,50). The offset (−40,20) is applied to that point, giving 4424(100−40,50+20)=(60,70), so the specified 10x10 region is located at 4425that point. (In addition, the <a href="command-line-options.html#gravity">-gravity</a> affects the 4426region itself, which is <var>centered</var> at the pixel 4427coordinate (60,70). (See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.)</p> 4428 4429<pre> 4430convert image.png -gravity Center -region 10x10-40+20 \ 4431 -negate output.png 4432</pre> 4433 4434<p>When used as an option to <a href="composite.html">composite</a>, <a 4435href="command-line-options.html#gravity">-gravity</a> gives the direction that the image gravitates 4436within the composite.</p> 4437 4438<p>When used as an option to <a href="montage.html">montage</a>, <a 4439href="command-line-options.html#gravity">-gravity</a> gives the direction that an image gravitates 4440within a tile. The default gravity is <code>Center</code> for this purpose.</p> 4441 4442 4443<div style="margin: auto;"> 4444 <h3 class="magick-header"><a id="grayscale"></a>-grayscale <var>method</var></h3> 4445</div> 4446 4447<p class="magick-description">convert image to grayscale.</p> 4448 4449<p>This will use one of the <a href="command-line-options.html#intensity" >-intensity</a> methods to 4450convert the given image into a linear-grayscale image. </p> 4451 4452<p>For example, to convert an image to (linear) Rec709Luminance grayscale, type:</p> 4453 4454<pre> 4455convert in.png -grayscale Rec709Luminance out.png 4456</pre> 4457 4458<p>which is equivalent to:</p> 4459 4460<pre> 4461convert in.png -colorspace gray out.png 4462</pre> 4463 4464<p>Similarly, to convert an image to (non-linear) Rec709Luma grayscale, type:</p> 4465 4466<pre> 4467convert in.png -grayscale Rec709Luma out.png 4468</pre> 4469 4470<p>which is equivalent to:</p> 4471 4472<pre> 4473convert in.png -set colorspace RGB -colorspace gray out.png 4474</pre> 4475 4476<p>Note that a 'colorspace' intensity method will produce the same result 4477regardless of the current colorpsace of the image. But a 'mathematical' 4478intensity method will depend on the current colorspace the image is currently 4479using. </p> 4480 4481<p>While this operation uses an <a href="command-line-options.html#intensity" >-intensity</a> method, 4482it does not use or set the <a href="command-line-options.html#intensity" >-intensity</a> setting, so 4483will not effect other operations that may use that setting.</p> 4484 4485 4486<div style="margin: auto;"> 4487 <h3 class="magick-header"><a id="green-primary"></a>-green-primary <var>x,y</var></h3> 4488</div> 4489 4490<p class="magick-description">green chromaticity primary point.</p> 4491 4492 4493<div style="margin: auto;"> 4494 <h3 class="magick-header"><a id="hald-clut"></a>-hald-clut</h3> 4495</div> 4496 4497<p class="magick-description">apply a Hald color lookup table to the image.</p> 4498 4499<p>A Hald color lookup table is a 3-dimensional color cube mapped to 2 4500dimensions. Create it with the <code>HALD:</code> prefix (e.g. HALD:8). You 4501can apply any color transformation to the Hald image and then use this option 4502to apply the transform to the image. </p> 4503 4504<pre> 4505convert image.png hald.png -hald-clut transform.png 4506</pre> 4507 4508<p>This option provides a convenient method for you to use Gimp or Photoshop 4509to make color corrections to the Hald CLUT image and subsequently apply them 4510to multiple images using an ImageMagick script. </p> 4511 4512<p>Note that the representation is only of the normal RGB color space and that 4513the whole color value triplet is used for the interpolated lookup of the 4514represented Hald color cube image. Because of this the operation is not <a 4515href="command-line-options.html#channel" >-channel</a> setting effected, nor can it adjust or modify an 4516images transparency or alpha/matte channel.</p> 4517 4518<p>See also <a href="command-line-options.html#clut" >-clut</a> which provides color value replacement 4519of the individual color channels, usually involving a simpler grayscale 4520image. E.g: grayscale to color replacement, or modification by a histogram 4521mapping. </p> 4522 4523 4524<div style="margin: auto;"> 4525 <h3 class="magick-header"><a id="help"></a>-help</h3> 4526</div> 4527 4528<p class="magick-description">print usage instructions.</p> 4529 4530<div style="margin: auto;"> 4531 <h3 class="magick-header"><a id="highlight-color"></a>-highlight-color <var>color</var></h3> 4532</div> 4533 4534<p class="magick-description">when comparing images, emphasize pixel differences with this color.</p> 4535 4536<div style="margin: auto;"> 4537 <h3 class="magick-header"><a id="hough-lines"></a>-hough-lines <var>width</var>x<var>height</var>{<var>+threshold</var>}</h3> 4538</div> 4539 4540<p class="magick-description">identify straight lines in the image (e.g. -hough-lines 9x9+195).</p> 4541 4542<p>Use the Hough line detector with any binary edge extracted image to locate and draw any straight lines that it finds.</p> 4543 4544<p>The process accumulates counts for every white pixel in the binary edge image for every possible orientation (for angles from 0 to 179 in 1 deg increments) and distance from the center of the image to the corners (in 1 px increments). It stores the counts in an accumulator matrix of angle vs distance. The size of the accumulator will be 180x(diagonal/2). Next it searches the accumulator for peaks in counts and converts the locations of the peaks to slope and intercept in the normal x,y input image space. The algorithm uses slope/intercepts to find the endpoints clipped to the bounds of the image. The lines are drawn from the given endpoints. The counts are a measure of the length of the lines.</p>. 4545 4546<p>The WxH arguments specify the filter size for locating the peaks in the Hough accumulator. The threshold excludes lines whose counts are less than the threshold value.</p> 4547 4548<p>Use <code><a href="command-line-options.html#background" >-background</a></code> to specify the color of the background onto which the lines will be drawn. The default is black.</p> 4549 4550<p>Use <code><a href="command-line-options.html#fill" >-fill</a></code> to specify the color of the lines. The default is black.</p> 4551 4552<p>Use <code><a href="command-line-options.html#stroke" >-stroke</a></code> and <code><a href="command-line-options.html#strokewidth" >-strokewidth</a></code> to specify the thickness of the lines. The default is black and no strokewidth.</p> 4553 4554<p>A text file listing the endpoints and counts may be created by using the suffix, .mvg, for the output image.</p> 4555 4556<p>Use <code><a href="command-line-options.html#define" >-define</a> hough-lines:accumulator=true</code> to return the accumulator image in addition to the lines image.</p> 4557 4558<div style="margin: auto;"> 4559 <h3 class="magick-header"><a id="iconGeometry"></a>-iconGeometry <var>geometry</var></h3> 4560</div> 4561 4562<p class="magick-description">specify the icon geometry.</p> 4563 4564<p>Offsets, if present in the geometry specification, are handled in the same 4565manner as the <a href="command-line-options.html#geometry">-geometry</a> option, using X11 style to 4566handle negative offsets.</p> 4567 4568<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 4569 4570<div style="margin: auto;"> 4571 <h3 class="magick-header"><a id="iconic"></a>-iconic</h3> 4572</div> 4573 4574<p class="magick-description">start in icon mode in X Windows", 'animate', 'display</p> 4575 4576<div style="margin: auto;"> 4577 <h3 class="magick-header"><a id="identify"></a>-identify</h3> 4578</div> 4579 4580<p class="magick-description">identify the format and characteristics of the image.</p> 4581 4582<p>This information is printed: image scene number; image name; image size; 4583the image class (<var>DirectClass</var> or <var>PseudoClass</var>); the total number of unique colors; and the 4584number of seconds to read and transform the image. Refer to <a href="miff.html">MIFF</a> for 4585a description of the image class.</p> 4586 4587<p>If <a href="command-line-options.html#colors">-colors</a> is also specified, the total unique colors 4588in the image and color reduction error values are printed. Refer to <a 4589href="quantize.html">color 4590reduction algorithm</a> for a description of these values.</p> 4591 4592<p>If <a href="command-line-options.html#verbose">-verbose</a> precedes this option, copious 4593amounts of image properties are displayed including image statistics, profiles, 4594image histogram, and others.</p> 4595 4596<div style="margin: auto;"> 4597 <h3 class="magick-header"><a id="ift"></a>-ift</h3> 4598</div> 4599 4600<p class="magick-description">implements the inverse discrete Fourier transform (DFT).</p> 4601 4602<p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows 4603users in ImageMagick 6.6.0-9). It transforms a pair of magnitude and phase 4604images from the frequency domain to a single image in the normal or spatial 4605domain. See for example, <a 4606href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier Transform</a>, 4607<a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier Transform</a> and 4608<a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier Transform</a>.</p> 4609 4610<p>For example, depending upon the image format used to store the result of 4611the <a href="command-line-options.html#fft">-fft</a>, one would use either</p> 4612 4613<pre> 4614convert fft_image.miff -ift fft_image_ift.png 4615</pre> 4616 4617<p>or</p> 4618 4619<pre> 4620convert fft_image-0.png fft_image-1.png -ift fft_image_ift.png 4621</pre> 4622 4623<p>The resulting image may need to be cropped due to padding introduced when 4624the original image, prior to the <a href="command-line-options.html#fft">-fft</a> or <a 4625href="command-line-options.html#fft">+fft</a>, was not square or even dimensioned. Any padding is at 4626the right and/or bottom sides of the image.</p> 4627 4628<p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to 4629use <a href="command-line-options.html#ift">-ift</a>.</p> 4630 4631<p>Use <a href="command-line-options.html#ift">+ift</a> (with HDRI enabled) to transform a pair of real 4632and imaginary images from the frequency domain to a single image in the normal 4633(spatial) domain.</p> 4634 4635<p>By default the IFT is not normalized (and the FFT is). Use "<code><a href="command-line-options.html#define" >-define</a> fourier:normalize=inverse</code> to explicitly normalize the IFT and unnormalize the FFT.</p> 4636 4637<div style="margin: auto;"> 4638 <h3 class="magick-header"><a id="immutable"></a>-immutable</h3> 4639</div> 4640 4641<p class="magick-description">make image immutable.</p> 4642 4643<div style="margin: auto;"> 4644 <h3 class="magick-header"><a id="implode"></a>-implode <var>factor</var></h3> 4645</div> 4646 4647<p class="magick-description">implode image pixels about the center.</p> 4648 4649<div style="margin: auto;"> 4650 <h3 class="magick-header"><a id="insert"></a>-insert <var>index</var></h3> 4651</div> 4652 4653<p class="magick-description">insert the last image into the image sequence.</p> 4654 4655<p>This option takes last image in the current image sequence and inserts it 4656at the given index. If a negative index is used, the insert position is 4657calculated before the last image is removed from the sequence. As such 4658<code>-insert -1</code> will result in no change to the image sequence.</p> 4659 4660<p>The <code>+insert</code> option is equivalent to <code>-insert -1</code>. In 4661other words, insert the last image, at the end of the current image sequence. 4662Consequently this has no effect on the image sequence order.</p> 4663 4664<div style="margin: auto;"> 4665 <h3 class="magick-header"><a id="intensity"></a>-intensity <var>method</var></h3> 4666</div> 4667 4668<p class="magick-description">method to generate intensity value from pixel.</p> 4669 4670<p>ImageMagick provides a number of methods used in situations where an 4671operator needs to determine a single grayscale value for some purpose, from 4672an image with red, green, and blue pixel components. Typically the linear 4673<code>Rec709Luminance</code> formula is used, which is the same formula used when 4674converting images to <code>-colorspace gray</code>. </p> 4675 4676<p>The following formulas are currently provided, and will first convert 4677the pixel values to linear-RGB or non-linear sRGB colorspace before 4678being applied to calculate the final greyscale value. </p> 4679 4680<dl class="dl-horizontal"> 4681<dt>Rec601Luma</dt><dd> 0.298839R' + 0.586811G'+ 0.114350B'</dd> 4682<dt>Rec601Luminance</dt><dd> 0.298839R + 0.586811G + 0.114350B</dd> 4683<dt>Rec709Luma</dt><dd> 0.212656R' + 0.715158G' + 0.072186B'</dd> 4684<dt>Rec709Luminance</dt><dd> 0.212656R + 0.715158G + 0.072186B</dd> 4685<dt>Brightness</dt><dd> max(R', G', B')</dd> 4686<dt>Lightness</dt><dd> (min(R', G', B') + max(R', G', B')) / 2.0</dd> 4687</dl> 4688 4689<p>Note that the above R,G,B values is the image's linear-RGB values, while 4690R',G',B' are sRGB non-linear values. </p> 4691 4692<p>These intensity methods are mathematical in nature and will use the 4693current value in the images respective R,G,B channel regardless of 4694what that is, or what colorspace the image is currently using.</p> 4695 4696<dl class="dl-horizontal"> 4697<dt>Average</dt><dd>(R + G + B) / 3.0</dd> 4698<dt>MS</dt><dd>(R^2 + G^2 + B^2) / 3.0</dd> 4699<dt>RMS</dt><dd>sqrt( (R^2 + G^2 + B^2) / 3.0 )</dd> 4700</dl> 4701 4702<p>These methods are often used for other purposes, such as generating a 4703grayscale difference image between two color images (using <a href="command-line-options.html#compose" 4704>-compose</a> '<code>Difference</code>' composition. </p> 4705 4706<p> For example The 'MS' (Mean Squared) setting is good for minimizing color 4707error comparisions. While... The method 'RMS' (Root Mean Squared) for 4708example is appropriate for calculating color vector distance, from a color 4709difference image. This is equivalent to the color only component of the <a 4710href="command-line-options.html#fuzz" >-fuzz</a> factor color compare setting. </p> 4711 4712<p>See also <a href="command-line-options.html#grayscale" >-grayscale</a> which applies one of the above 4713grayscaling formula directly to an image without setting the <a 4714href="command-line-options.html#intensity" >-intensity</a> setting.</p> 4715 4716<p>The <a href="command-line-options.html#colorspace" >-colorspace gray</a> image conversion also uses 4717the current intensity setting, but will always convert the image to the 4718appropriate sRGB or linear-RGB colorspace before appling the above 4719function.</p> 4720 4721<p>To print a complete list of possible pixel intensity setting methods, use <a href="command-line-options.html#list">-list intensity</a>.</p> 4722 4723<p>Operators affected by the <a href="command-line-options.html#intensity" >-intensity</a> setting include:</p> 4724 4725<pre> 4726-adaptive-blur 4727-adaptive-sharpen 4728-black-threshold 4729-clut (when mapping greyscale CLUT image to alpha channel if set by -channels) 4730-colors for gray colorspace 4731-compose {LightenIntensity, DarkenIntensity, CopyOpacity, CopyBlack} 4732-contrast-stretch 4733-distort {ErodeIntensity, DilateIntensity} 4734-normalize 4735-random-threshold 4736-selective-blur 4737-shade 4738-threshold 4739-tint 4740-white-threshold 4741</pre> 4742 4743<div style="margin: auto;"> 4744 <h3 class="magick-header"><a id="intent"></a>-intent <var>type</var></h3> 4745</div> 4746 4747<p class="magick-description">use this type of rendering intent when managing the image color.</p> 4748 4749<p>Use this option to affect the color management operation of an image (see 4750<a href="command-line-options.html#profile">-profile</a>). Choose from these intents: <code>Absolute, 4751Perceptual, Relative, Saturation</code>.</p> 4752 4753<p>The default intent is Perceptual for the sRGB colorspace and undefined for the RGB and gray colorspaces.</p> 4754 4755<p>To print a complete list of rendering intents, use <a href="command-line-options.html#list">-list intent</a>.</p> 4756 4757<div style="margin: auto;"> 4758 <h3 class="magick-header"><a id="interlace"></a>-interlace <var>type</var></h3> 4759</div> 4760 4761<p class="magick-description">the type of interlacing scheme.</p> 4762 4763<p>Choose from:</p> 4764 4765<pre> 4766none 4767line 4768plane 4769partition 4770JPEG 4771GIF 4772PNG 4773</pre> 4774 4775<p>This option is used to specify the type of interlacing scheme for raw image 4776formats such as <code>RGB</code> or <code>YUV</code>.</p> 4777 4778<p><code>None</code> means do not interlace (RGBRGBRGBRGBRGBRGB...),</p> 4779 4780<p><code>Line</code> uses scanline interlacing (RRR...GGG...BBB...RRR...GGG...BBB...), and.</p> 4781 4782<p><code>Plane</code> uses plane interlacing (RRRRRR...GGGGGG...BBBBBB...).</p> 4783 4784<p><code>Partition</code> is like plane except the different planes are saved to 4785individual files (e.g. image.R, image.G, and image.B).</p> 4786 4787<p>Use <code>Line</code> or <code>Plane</code> to create an <code>interlaced 4788PNG</code> or <code>GIF</code> or <code>progressive JPEG</code> image.</p> 4789 4790<p>To print a complete list of interlacing schemes, use <a href="command-line-options.html#list">-list 4791interlace</a>.</p> 4792 4793<div style="margin: auto;"> 4794 <h3 class="magick-header"><a id="interpolate"></a>-interpolate <var>type</var></h3> 4795</div> 4796 4797<p class="magick-description">Set the pixel color interpolation method to use when looking up a color based on a floating point or real value.</p> 4798 4799<p>When looking up the color of a pixel using a non-integer floating point 4800value, you typically fall in between the pixel colors defined by the source 4801image. This setting determines how the color is determined from the colors of 4802the pixels surrounding that point. That is how to determine the color of a 4803point that falls between two, or even four different colored pixels. </p> 4804 4805<dl class="dl-horizontal"> 4806 <dt>integer</dt> 4807 <dd>The color of the top-left pixel (floor function)</dd> 4808 <dt>nearest-neighbor</dt> 4809 <dd>The nearest pixel to the lookup point (rounded function)</dd> 4810 <dt>average</dt> 4811 <dd>The average color of the surrounding four pixels</dd> 4812 <dt>bilinear</dt> 4813 <dd>A double linear interpolation of pixels (the default)</dd> 4814 <dt>mesh</dt> 4815 <dd>Divide area into two flat triangular interpolations</dd> 4816 <dt>bicubic</dt> 4817 <dd>Fitted bicubic-spines of surrounding 16 pixels</dd> 4818 <dt>spline</dt> 4819 <dd>Direct spline curves (colors are blurred)</dd> 4820 <dt>filter</dt> 4821 <dd>Use resize <a href="command-line-options.html#filter">-filter</a> settings</dd> 4822</dl> 4823 4824<p>This most important for distortion operators such as <a href="command-line-options.html#distort" 4825>-distort</a>, <a href="command-line-options.html#implode" >-implode</a>, <a href="command-line-options.html#transform" 4826>-transform</a> and <a href="command-line-options.html#fx" >-fx</a>. </p> 4827 4828<p>To print a complete list of interpolation methods, use <a href="command-line-options.html#list">-list interpolate</a>.</p> 4829 4830<p>See also <a href="command-line-options.html#virtual-pixel" >-virtual-pixel</a>, for control of the 4831lookup for positions outside the boundaries of the image. </p> 4832 4833 4834<div style="margin: auto;"> 4835 <h3 class="magick-header"><a id="interline-spacing"></a>-interline-spacing <var>value</var></h3> 4836</div> 4837 4838<p class="magick-description">the space between two text lines.</p> 4839 4840<div style="margin: auto;"> 4841 <h3 class="magick-header"><a id="interword-spacing"></a>-interword-spacing <var>value</var></h3> 4842</div> 4843 4844<p class="magick-description">the space between two words.</p> 4845 4846<div style="margin: auto;"> 4847 <h3 class="magick-header"><a id="kerning"></a>-kerning <var>value</var></h3> 4848</div> 4849 4850<p class="magick-description">the space between two letters.</p> 4851 4852<div style="margin: auto;"> 4853 <h3 class="magick-header"><a id="kuwahara"></a>-kuwahara <var>radius</var><br />-kuwahara <var>radius</var>x<var>sigma</var></h3> 4854</div> 4855 4856<p class="magick-description">edge preserving noise reduction filter.</p> 4857 4858<p>The <var >radius</var> is more important than the <var >sigma</var>. If <var >sigma</var> is left off, it will be computed automatically from the <var >radius</var> as <var >sigma</var>=<var >radius</var>-0.5. The <var >sigma</var> provides a bit of additional smoothing control.</p> 4859 4860 4861<div style="margin: auto;"> 4862 <h3 class="magick-header"><a id="label"></a>-label <var>name</var></h3> 4863</div> 4864 4865<p class="magick-description">assign a label to an image.</p> 4866 4867<p>Use this option to assign a specific label to the image, as it is read in 4868or created. You can use the <a href="command-line-options.html#set" >-set</a> operation to re-assign 4869a the labels of images already read in. Image formats such as TIFF, PNG, 4870MIFF, supports saving the label information with the image.</p> 4871 4872<p>When saving an image to a <var>PostScript</var> file, any label 4873assigned to an image is used as a header string to print above the postscript 4874image. </p> 4875 4876<p>You can include the image filename, type, width, height, or other image 4877attribute by embedding special format character. See <a href="escape.html">Format and Print Image 4878Properties</a> for details of the percent escape codes.</p> 4879 4880<p>For example,</p> 4881 4882<pre> 4883-label "%m:%f %wx%h" bird.miff 4884</pre> 4885 4886<p>assigns an image label of <code>MIFF:bird.miff 512x480</code> to the 4887"<code>bird.miff</code>" image and whose width is 512 and height is 480, as it 4888is read in. If a <a href="command-line-options.html#label">+label</a> option was used instead, any 4889existing label present in the image would be used. You can remove all labels 4890from an image by assigning the empty string. </p> 4891 4892<p>A label is not drawn on the image, but is embedded in the image datastream 4893via <var>Label</var> tag or similar mechanism. If you want the label to be 4894visible on the image itself, use the <a href="command-line-options.html#draw">-draw</a> option, or 4895during the final processing in the creation of an image montage.</p> 4896 4897<p>If the first character of <var>string</var> is <var>@</var>, the image label is read from a file titled by the 4898remaining characters in the string. Labels in a file are literal, no embedded 4899formatting characters are recognized.</p> 4900 4901 4902<div style="margin: auto;"> 4903 <h3 class="magick-header"><a id="lat"></a>-lat <var>width</var><br />-lat <var>width</var>x<var>height</var>{<var>+-</var>}<var>offset</var>{<var>%</var>}</h3> 4904</div> 4905 4906<p class="magick-description">perform local adaptive threshold.</p> 4907 4908<p>Adaptively threshold each pixel based on the value of pixels in a 4909surrounding window. If the current pixel is lighter than this average plus 4910the optional <code>offset</code>, then it is made white, otherwise it is made 4911black. Small variations in pixel values such as found in scanned documents 4912can be ignored if offset is positive. A negative offset will make it more 4913sensitive to those small variations. </p> 4914 4915<p>This is commonly used to threshold images with an uneven background. It is 4916based on the assumption that average color of the small window is the 4917the local background color, from which to separate the foreground color. </p> 4918 4919 4920<div style="margin: auto;"> 4921 <h3 class="magick-header"><a id="layers"></a>-layers <var>method</var></h3> 4922</div> 4923 4924<p class="magick-description">handle multiple images forming a set of image layers or animation frames.</p> 4925 4926<p>Perform various image operation methods to a ordered sequence of images 4927which may represent either a set of overlaid 'image layers', a GIF disposal 4928animation, or a fully-'coalesced' animation sequence. </p> 4929 4930<table class="table table-condensed table-striped"> 4931 <tbody> 4932 <tr> 4933 <th style="width: 8%">Method</th> 4934 <th>Description</th> 4935 </tr> 4936 4937 <tr> 4938 <td>compare-any</td> 4939 <td>Crop the second and later frames to the smallest rectangle 4940 that contains all the differences between the two images. No GIF <a 4941 href="command-line-options.html#dispose" >-dispose</a> methods are taken into account. </td> 4942 </tr> 4943 4944 <tr><td></td><td>This exactly the same as the <a href="command-line-options.html#deconstruct" 4945 >-deconstruct</a> operator, and does not preserve animations normal 4946 working, especially when animation used layer disposal methods such as 4947 '<code>Previous</code>' or '<code>Background</code>'. </td> 4948 </tr> 4949 4950 <tr> 4951 <td>compare-clear</td> 4952 <td>As '<code>compare-any</code>' but crop to the bounds of any 4953 opaque pixels which become transparent in the second frame. That is the 4954 smallest image needed to mask or erase pixels for the next frame. </td> 4955 </tr> 4956 4957 <tr> 4958 <td>compare-overlay</td> 4959 <td>As '<code>compare-any</code>' but crop to pixels that add 4960 extra color to the next image, as a result of overlaying color pixels. 4961 That is the smallest single overlaid image to add or change colors. </td> 4962 </tr> 4963 4964 <tr><td></td><td>This can be used with the <a href="command-line-options.html#compose" >-compose</a> alpha 4965 composition method '<code>change-mask</code>', to reduce the image to 4966 just the pixels that need to be overlaid. </td> 4967 </tr> 4968 4969 <tr> 4970 <td>coalesce</td> 4971 <td>Equivalent to a call to the <a href="command-line-options.html#coalesce" 4972 >-coalesce</a> operator. Apply the layer disposal methods set in the 4973 current image sequence to form a fully defined animation sequence, as 4974 it should be displayed. Effectively converting a GIF animation into a 4975 'film strip'-like animation. </td> 4976 </tr> 4977 4978 <tr> 4979 <td>composite</td> 4980 <td>Alpha Composition of two image lists, separated by a 4981 "<code>null:</code>" image, with the destination image list first, and 4982 the source images last. An image from each list are composited 4983 together until one list is finished. The separator image and source 4984 image lists are removed. </td> 4985 </tr> 4986 4987 4988 <tr><td></td> 4989 <td>The <a href="command-line-options.html#geometry" >-geometry</a> offset is adjusted according 4990 to <a href="command-line-options.html#gravity" >-gravity</a> in accordance of the virtual 4991 canvas size of the first image in each list. Unlike a normal <a 4992 href="command-line-options.html#composite" >-composite</a> operation, the canvas offset is also 4993 added to the final composite positioning of each image. </td> </tr> 4994 4995 <tr><td></td> 4996 <td>If one of the image lists only contains one image, that image is 4997 applied to all the images in the other image list, regardless of which 4998 list it is. In this case it is the image meta-data of the list which 4999 preserved. </td> 5000 </tr> 5001 5002 5003 <tr> 5004 <td>dispose</td> 5005 <td>This like '<code>coalesce</code>' but shows the look of 5006 the animation after the layer disposal method has been applied, before 5007 the next sub-frame image is overlaid. That is the 'dispose' image that 5008 results from the application of the GIF <a href="command-line-options.html#dispose" 5009 >-dispose</a> method. This allows you to check what 5010 is going wrong with a particular animation you may be developing. 5011 </td> 5012 </tr> 5013 5014 <tr> 5015 <td>flatten</td> 5016 <td>Create a canvas the size of the first images virtual 5017 canvas using the current <a href="command-line-options.html#background" >-background</a> color, 5018 and <a href="command-line-options.html#compose" >-compose</a> each image in turn onto that 5019 canvas. Images falling outside that canvas is clipped. Final 5020 image will have a zero virtual canvas offset. </td> 5021 </tr> 5022 5023 <tr><td></td> 5024 <td>This usually used as one of the final 'image layering' operations 5025 overlaying all the prepared image layers into a final image. </td> 5026 </tr> 5027 5028 <tr><td></td> 5029 <td>For a single image this method can also be used to fillout a virtual 5030 canvas with real pixels, or to underlay an opaque color to remove 5031 transparency from an image.</td> 5032 </tr> 5033 5034 5035 <tr> 5036 <td>merge</td> 5037 <td>As 'flatten' method but merging all the given image 5038 layers to create a new layer image just large enough to hold all the 5039 image without clipping or extra space. The new images virtual offset 5040 will preserve the position of the new layer, even if this offset is 5041 negative. The virtual canvas size of the first image is preserved. 5042 </td> 5043 </tr> 5044 5045 <tr><td></td><td>Caution is advised when handling image layers with 5046 negative offsets as few image file formats handle them correctly. 5047 Following this operation method with <a href="command-line-options.html#repage" >+repage</a> 5048 will remove the layer offset, and create an image in which all the 5049 overlaid image positions relative to each other is preserved, though 5050 not necessarily exactly where you specified them. 5051 </td> 5052 </tr> 5053 5054 <tr><td></td><td>See also 'trim-bounds' below which is closely related but 5055 without doing the'flatten' to merge the images together. </td> 5056 </tr> 5057 5058 <tr> 5059 <td>mosaic</td> 5060 <td>As 'flatten' method but expanding the initial canvas size 5061 of the first image in a positive direction only so as to hold all the 5062 image layers. However as a virtual canvas is 'locked' to the origin, 5063 by its own definition, image layers with a negative offsets will still 5064 become clipped by the top and left edges. See 'merge' or 'trim-bounds' 5065 if this could be a problem. </td> 5066 5067 </tr> 5068 5069 <tr><td></td><td>This method is commonly used to layout individual image 5070 using various offset but without knowing the final canvas size. The 5071 resulting image will, like 'flatten' not have any virtual offset, so 5072 can be saved to any image file format. </td> 5073 </tr> 5074 5075 5076 <tr> 5077 <td>optimize</td> 5078 <td>Optimize a coalesced animation, into GIF animation using 5079 a number of general techniques. This currently a short cut to 5080 apply both the '<code>optimize-frame</code>', and 5081 '<code>optimize-transparency</code>' methods but may be expanded to 5082 include other optimization methods as they are developed. </td> 5083 </tr> 5084 5085 <tr> 5086 <td>optimize-frame</td> 5087 <td>Optimize a coalesced animation, into GIF animation by 5088 reducing the number of pixels per frame as much as possible by 5089 attempting to pick the best layer disposal method to use, while ensuring 5090 the result will continue to animate properly. </td> 5091 </tr> 5092 5093 <tr><td></td><td> There is no guarantee that the best optimization is found. 5094 But then no reasonably fast GIF optimization algorithm can do this. 5095 However this does seem to do better than most other GIF frame 5096 optimizers seen. </td> 5097 </tr> 5098 5099 <tr> 5100 <td>optimize-plus</td> 5101 <td>As '<code>optimize-frame</code>' but attempt to improve the 5102 overall optimization by adding extra frames to the animation, without 5103 changing the final look or timing of the animation. The frames are 5104 added to attempt to separate the clearing of pixels from the 5105 overlaying of new additional pixels from one animation frame to the 5106 next. If this does not improve the optimization (for the next frame 5107 only), it will fall back to the results of the previous normal 5108 '<code>optimize-frame</code>' technique. </td> 5109 </tr> 5110 5111 <tr><td></td><td>There is the possibility that the change in the disposal 5112 style will result in a worsening in the optimization of later frames, 5113 though this is unlikely. In other words there no guarantee that it is 5114 better than the normal '<code>optimize-frame</code>' technique. For some 5115 animations however you can get a vast improvement in the final 5116 animation size. </td> 5117 </tr> 5118 5119 <tr> 5120 <td>optimize-transparency</td> 5121 <td>Given a GIF animation, replace any pixel in the sub-frame 5122 overlay images with transparency, if it does not change the resulting 5123 animation by more than the current <a href="command-line-options.html#fuzz" >-fuzz</a> factor. 5124 </td> 5125 </tr> 5126 5127 <tr><td></td><td>This should allow a existing frame optimized GIF animation 5128 to compress into a smaller file size due to larger areas of one 5129 (transparent) color rather than a pattern of multiple colors repeating 5130 the current disposed image of the last frame. </td> 5131 </tr> 5132 5133 <tr> 5134 <td>remove-dups</td> 5135 <td>Remove (and merge time delays) of duplicate consecutive 5136 images, so as to simplify layer overlays of coalesced animations. 5137 </td> 5138 </tr> 5139 5140 <tr><td></td><td>Usually this a result of using a constant time delay 5141 across the whole animation, or after a larger animation was split into 5142 smaller sub-animations. The duplicate frames could also have been 5143 used as part of some frame optimization methods. </td> 5144 </tr> 5145 5146 <tr> 5147 <td>remove-zero</td> 5148 <td>Remove any image with a zero time delay, unless ALL the 5149 images have a zero time delay (and is not a proper timed animation, a 5150 warning is then issued). </td> 5151 </tr> 5152 5153 <tr><td></td><td>In a GIF animation, such images are usually frames which 5154 provide partial intermediary updates between the frames that are 5155 actually displayed to users. These frames are usually added for 5156 improved frame optimization in GIF animations. </td> 5157 </tr> 5158 5159 <tr> 5160 <td>trim-bounds</td> 5161 <td>Find the bounds of all the images in the current 5162 image sequence, then adjust the offsets so all images are contained on 5163 a minimal positive canvas. None of the image data is modified or 5164 merged, only the individual image virtual canvas size and offset. 5165 All the images is given the same canvas size, and and will have 5166 a positive offset, but will remain in the same position relative to 5167 each other. As a result of the minimal canvas size at least one image 5168 will touch every edge of that canvas. The image data touching those 5169 edges however may be transparent. </td> 5170 </tr> 5171 5172 <tr><td></td><td>The result is much like if you used 'merge' followed by a 5173 <a href="command-line-options.html#repage" >+repage</a> option, except that all the images 5174 have been kept separate. If 'flatten' is used after using 5175 'trim-bounds' you will get the same result. </td> 5176 </tr> 5177 5178 </tbody> 5179</table> 5180 5181<p>To print a complete list of layer types, use <a href="command-line-options.html#list">-list layers</a>.</p> 5182 5183<p>The operators <a href="command-line-options.html#coalesce" >-coalesce</a>, <a href="command-line-options.html#deconstruct" 5184>-deconstruct</a>, <a href="command-line-options.html#flatten" >-flatten</a>, and <a href="command-line-options.html#mosaic" 5185>-mosaic</a> are only aliases for the above methods and may be depreciated in 5186the future. Also see <a href="command-line-options.html#page" >-page</a>, <a href="command-line-options.html#repage" 5187>-repage</a> operators, the <a href="command-line-options.html#compose" >-compose</a> setting, and the 5188GIF <a href="command-line-options.html#dispose" >-dispose</a> and <a href="command-line-options.html#delay" >-delay</a> 5189settings. </p> 5190 5191 5192<div style="margin: auto;"> 5193 <h3 class="magick-header"><a id="level"></a>-level <var>black_point</var>{,<var>white_point</var>}{<var>%</var>}{,<var>gamma</var>}</h3> 5194</div> 5195 5196<p class="magick-description">adjust the level of image channels.</p> 5197 5198<p>Given one, two or three values delimited with commas: black-point, 5199white-point, gamma (for example: 10,250,1.0 or 2%,98%,0.5). The black and 5200white points range from 0 to <var>QuantumRange</var>, or from 0 to 5201100%; if the white point is omitted it is set to (<var>QuantumRange</var> - black_point), so as to center contrast changes. 5202If a <code>%</code> sign is present anywhere in the string, both black and white 5203points are percentages of the full color range. Gamma will do a <a 5204href="command-line-options.html#gamma">-gamma</a> adjustment of the values. If it is omitted, the 5205default of 1.0 (no gamma correction) is assumed.</p> 5206 5207<p>In normal usage (<code>-level</code>) the image values are stretched so that 5208the given '<code>black_point</code>' value in the original image is set to zero 5209(or black), while the given '<code>white_point</code>' value is set to <var>QuantumRange</var> (or white). This provides you with direct 5210contrast adjustments to the image. The '<code>gamma</code>' of the resulting 5211image will then be adjusted. </p> 5212 5213<p>From ImageMagick v6.4.1-9 using the plus form of the operator 5214(<code>+level</code>) or adding the special '!' flag anywhere in the argument 5215list, will cause the operator to do the reverse of the level adjustment. That 5216is a zero, or <var>QuantumRange</var> value (black, and white, resp.) 5217in the original image, is adjusted to the given level values, allowing you to 5218de-contrast, or compress the channel values within the image. The 5219'<code>gamma</code>' is adjusted before the level adjustment to de-contrast the 5220image is made. </p> 5221 5222<p>Only the channels defined by the current <a href="command-line-options.html#channel">-channel</a> 5223setting are adjusted (defaults to RGB color channels only), allowing you to 5224limit the effect of this operator. </p> 5225 5226<p>Please note that the transparency channel is treated as 'matte' 5227values (0 is opaque) and not as 'alpha' values (0 is transparent).</p> 5228 5229 5230<div style="margin: auto;"> 5231 <h3 class="magick-header"><a id="level-colors"></a>-level-colors {<var>black_color</var>}{,}{<var>white_color</var>}</h3> 5232</div> 5233 5234<p class="magick-description">adjust the level of an image using the provided dash separated colors.</p> 5235 5236<p>This function is exactly like <a href="command-line-options.html#level">-level</a>, except that the 5237value value for each color channel is determined by the 5238'<code>black_color</code>' and '<code>white_color</code>' colors given (as 5239described under the <a href="command-line-options.html#fill">-fill</a> option). </p> 5240 5241<p>This effectually means the colors provided to <code>-level-colors</code> 5242is mapped to become 'black' and 'white' respectively, with all the other 5243colors linearly adjusted (or clipped) to match that change. Each channel is 5244adjusted separately using the channel values of the colors specified. </p> 5245 5246<p>On the other hand the plus form of the operator (<code>+level-colors</code>) 5247will map the image color 'black' and 'white' to the given colors 5248respectively, resulting in a gradient (de-contrasting) tint of the image to 5249those colors. This can also be used to convert a plain grayscale image into a 5250one using the gradient of colors specified. </p> 5251 5252<p>By supplying a single color with a comma separator either before or after 5253that color, will just replace the respective 'black' or 'white' point 5254respectively. But if no comma separator is provided, the given color is 5255used for both the black and white color points, making the operator either 5256threshold the images around that color (- form) or set all colors to that 5257color (+ form). </p> 5258 5259 5260<div style="margin: auto;"> 5261 <h3 class="magick-header"><a id="limit"></a>-limit <var>type value</var></h3> 5262</div> 5263 5264<p class="magick-description">Set the pixel cache resource limit.</p> 5265 5266<p>Choose from: <code>width</code>, <code>height</code>, <code>area</code>, <code>memory</code>, <code>map</code>, <code>disk</code>, <code>file</code>, <code>thread</code>, <code>throttle</code>, or <code>time</code>.</p> 5267 5268<p>The value for <code>file</code> is in number of files. The other limits are 5269in bytes. Define arguments for the memory, map, area, and disk resource limits 5270with SI prefixes (.e.g 100MB).</p> 5271 5272<p>By default the limits are 768 files, 3GB of image area, 1.5GiB memory, 3GiB 5273memory map, and 18.45EB of disk. These limits are adjusted relative to the 5274available resources on your computer if this information is available. When 5275any limit is reached, ImageMagick fails in some fashion but attempts to take 5276compensating actions, if possible. For example, the following limits 5277memory:</p> 5278 5279<pre> 5280-limit memory 32MiB -limit map 64MiB 5281</pre> 5282 5283<p>Use <a href="command-line-options.html#list">-list resource</a> to list the current limits. For example, our system shows these limits:</p> 5284 5285<pre> 5286-> identify -list resource 5287Resource limits: 5288 Width: 100MP 5289 Height: 100MP 5290 Area: 25.181GB 5291 Memory: 11.726GiB 5292 Map: 23.452GiB 5293 Disk: unlimited 5294 File: 768 5295 Thread: 12 5296 Throttle: 0 5297 Time: unlimited 5298</pre> 5299 5300<p>Requests for pixel storage to keep intermediate images are satisfied by one 5301of three resource categories: in-memory pool, memory-mapped files pool, and 5302disk pool (in that order) depending on the <a href="command-line-options.html#limit">‑limit</a> settings 5303and whether the system honors a resource request. If the total size of 5304allocated pixel storage in the given pool reaches the corresponding limit, the 5305request is passed to the next pool. Additionally, requests that exceed the 5306<code>area</code> limit automagically are allocated on disk.</p> 5307 5308<p>To illustrate how ImageMagick utilizes resource limits, consider a typical 5309image resource request. First, ImageMagick tries to allocate the pixels in 5310memory. The request might be denied if the resource request exceeds the 5311<code>memory</code> limit or if the system does not honor the request. If 5312a memory request is not honored, the pixels are allocated to disk and the file 5313is memory-mapped. However, if the allocation request exceeds the 5314<code>map</code> limit, the resource allocation goes to disk. In all cases, if 5315the resource request exceeds the <code>area</code> limit, the pixels are 5316automagically cached to disk. If the disk has a hard limit, the program 5317fails.</p> 5318 5319<p>In most cases you simply do not need to concern yourself with resource 5320limits. ImageMagick chooses reasonable defaults and most images do not tax 5321your computer resources. Where limits do come in handy is when you process 5322images that are large or on shared systems where ImageMagick can consume all 5323or most of the available memory. In this case, the ImageMagick workflow slows 5324other processes or, in extreme cases, brings the system to a halt. Under 5325these circumstances, setting limits give some assurances that the ImageMagick 5326workflow will not interfere with other concurrent uses of the computer. For 5327example, assume you have a web interface that processes images uploaded from 5328the Internet. To assure ImageMagick does not exceed 10MiB of memory you can 5329simply set the area limit to 10MiB:</p> 5330 5331<pre> 5332-limit area 10MB 5333</pre> 5334 5335<p>Now whenever a large image is processed, the pixels are automagically 5336cached to disk instead of memory. This of course implies that large images 5337typically process very slowly, simply because pixel processing in memory can 5338be an order of magnitude faster than on disk. Because your web site users 5339might inadvertently upload a huge image to process, you should set a disk 5340limit as well:</p> 5341 5342<pre> 5343-limit area 10MB -limit disk 500MB 5344</pre> 5345 5346<p>Here ImageMagick stops processing if an image requires more than 500MB of disk storage.</p> 5347 5348<p>In addition to command-line resource limit option, resources can be set 5349with <a href="resources.html#environment" >environment variables</a>. Set the 5350environment variables <code>MAGICK_AREA_LIMIT</code>, 5351<code>MAGICK_DISK_LIMIT</code>, <code>MAGICK_FILE_LIMIT</code>, 5352<code>MAGICK_MEMORY_LIMIT</code>, <code>MAGICK_MAP_LIMIT</code>, 5353<code>MAGICK_THREAD_LIMIT</code>, <code>MAGICK_TIME_LIMIT</code> for limits of 5354image area, disk space, open files, heap memory, memory map, number of threads 5355of execution, and maximum elapsed time in seconds respectively.</p> 5356 5357<p> Inquisitive users can try adding <a href="command-line-options.html#debug">-debug cache</a> to 5358their commands and then scouring the generated output for references to the 5359pixel cache, in order to determine how the pixel cache was allocated and how 5360resources were consumed. Advanced Unix/Linux users can pipe that output 5361through <code>grep memory|open|destroy|disk</code> for more readable sifting. 5362</p> 5363 5364<p>For more about ImageMagick's use of resources, see the section <b>Cache 5365Storage and Resource Requirements</b> on the <a href="architecture.html#cache 5366">Architecture</a> page. </p> 5367 5368<div style="margin: auto;"> 5369 <h3 class="magick-header"><a id="linear-stretch"></a>-linear-stretch <var>black-point</var><br />-linear-stretch <var>black-point</var>{x<var>white-point</var>}{<var>%</var>}</h3> 5370</div> 5371 5372<p class="magick-description">Linear with saturation stretch.</p> 5373 5374<p>This is very similar to <a href="command-line-options.html#contrast-stretch" >-contrast-stretch</a>, 5375and uses a 'histogram bin' to determine the range of color values that needs to 5376be stretched. However it then stretches those colors using the <a 5377href="command-line-options.html#level" >-level</a> operator.</p> 5378 5379<p>As such while the initial determination may have 'binning' round off 5380effects, the image colors are stretched mathematically, rather than using the 5381histogram bins. This makes the operator more accurate. </p> 5382 5383<p>note however that a <a href="command-line-options.html#linear-stretch" >-linear-stretch</a> of 5384'<code>0</code>' does nothing, while a value of '<code>1</code>' does a near 5385perfect stretch of the color range. </p> 5386 5387<p>See also <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' 5388normalization of mathematical images. </p> 5389 5390<p>This operator is under review for re-development. </p> 5391 5392 5393<div style="margin: auto;"> 5394 <h3 class="magick-header"><a id="linewidth"></a>-linewidth</h3> 5395</div> 5396 5397<p class="magick-description">the line width for subsequent draw operations.</p> 5398 5399<div style="margin: auto;"> 5400 <h3 class="magick-header"><a id="liquid-rescale"></a>-liquid-rescale <var>geometry</var></h3> 5401</div> 5402 5403<p class="magick-description">rescale image with seam-carving.</p> 5404 5405<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 5406 5407<div style="margin: auto;"> 5408 <h3 class="magick-header"><a id="list"></a>-list <var>type</var></h3> 5409</div> 5410 5411<p class="magick-description">Print a list of supported arguments for various options or settings. Choose from these list types:</p> 5412 5413<pre class="pre-scrollable"> 5414Align 5415Alpha 5416Boolean 5417Cache 5418Channel 5419Class 5420ClipPath 5421Coder 5422Color 5423Colorspace 5424Command 5425Complex 5426Compose 5427Compress 5428Configure 5429DataType 5430Debug 5431Decoration 5432Delegate 5433Direction 5434Dispose 5435Distort 5436Dither 5437Endian 5438Evaluate 5439FillRule 5440Filter 5441Font 5442Format 5443Function 5444Gravity 5445Intensity 5446Intent 5447Interlace 5448Interpolate 5449Kernel 5450Layers 5451LineCap 5452LineJoin 5453List 5454Locale 5455LogEvent 5456Log 5457Magic 5458Method 5459Metric 5460Mime 5461Mode 5462Morphology 5463Module 5464Noise 5465Orientation 5466PixelIntensity 5467Policy 5468PolicyDomain 5469PolicyRights 5470Preview 5471Primitive 5472QuantumFormat 5473Resource 5474SparseColor 5475Statistic 5476Storage 5477Stretch 5478Style 5479Threshold 5480Type 5481Units 5482Validate 5483VirtualPixel 5484</pre> 5485 5486<p>These lists vary depending on your version of ImageMagick. Use "<code>-list 5487list</code>" to get a complete listing of all the "<code>-list</code>" arguments 5488available:</p> 5489 5490<pre> 5491identify -list list 5492</pre> 5493 5494<div style="margin: auto;"> 5495 <h3 class="magick-header"><a id="log"></a>-log <var>string</var></h3> 5496</div> 5497 5498<p class="magick-description">Specify format for debug log.</p> 5499 5500<p>This option specifies the format for the log printed when the <a 5501href="command-line-options.html#debug">-debug</a> option is active.</p> 5502 5503<p>You can display the following components by embedding special format 5504characters:</p> 5505 5506<dl class="dl-horizontal"> 5507<dt>%d</dt><dd>domain</dd> 5508<dt>%e</dt><dd>event</dd> 5509<dt>%f</dt><dd>function</dd> 5510<dt>%l</dt><dd>line</dd> 5511<dt>%m</dt><dd>module</dd> 5512<dt>%p</dt><dd>process ID</dd> 5513<dt>%r</dt><dd>real CPU time</dd> 5514<dt>%t</dt><dd>wall clock time</dd> 5515<dt>%u</dt><dd>user CPU time</dd> 5516<dt>%%</dt><dd>percent sign</dd> 5517<dt>\n</dt><dd>newline</dd> 5518<dt>\r</dt><dd>carriage return</dd> 5519</dl> 5520 5521<p>For example:</p> 5522 5523<pre> 5524convert -debug coders -log "%u %m:%l %e" in.gif out.png 5525</pre> 5526 5527<p>The default behavior is to print all of the components.</p> 5528 5529<div style="margin: auto;"> 5530 <h3 class="magick-header"><a id="loop"></a>-loop <var>iterations</var></h3> 5531</div> 5532 5533<p class="magick-description">add Netscape loop extension to your GIF animation.</p> 5534 5535<p>Set iterations to zero to repeat the animation an infinite number of times, 5536otherwise the animation repeats itself up to <var>iterations</var> 5537times.</p> 5538 5539<div style="margin: auto;"> 5540 <h3 class="magick-header"><a id="lowlight-color"></a>-lowlight-color <var>color</var></h3> 5541</div> 5542 5543<p class="magick-description">when comparing images, de-emphasize pixel differences with this color.</p> 5544 5545<div style="margin: auto;"> 5546 <h3 class="magick-header"><a id="magnify"></a>-magnify</h3> 5547</div> 5548 5549<p class="magick-description">double the size of the image with pixel art scaling.</p> 5550 5551 5552<div style="margin: auto;"> 5553 <h3 class="magick-header"><a id="map"></a>-map <var>type</var></h3> 5554</div> 5555 5556<p class="magick-description">Display image using this <var>type</var>.</p> 5557 5558<p>Choose from these <var>Standard Colormap</var> types:</p> 5559 5560<pre> 5561best 5562default 5563gray 5564red 5565green 5566blue 5567</pre> 5568 5569<p>The <var>X server</var> must support the <var>Standard 5570Colormap</var> you choose, otherwise an error occurs. Use <code>list</code> as 5571the type and <code>display</code> searches the list of colormap types in 5572<code>top-to-bottom</code> order until one is located. See <var>xstdcmap(1)</var> for one way of creating Standard Colormaps.</p> 5573 5574 5575<div style="margin: auto;"> 5576 <h3 class="magick-header"><a id="map_stream_"></a>-map <var>components</var></h3> 5577</div> 5578 5579<p class="magick-description">pixel map.</p> 5580 5581<p>Here are the valid components of a map:</p> 5582 5583<dl class="dl-horizontal"> 5584<dt>r</dt><dd> red pixel component</dd> 5585<dt>g</dt><dd> green pixel component</dd> 5586<dt>b</dt><dd> blue pixel component</dd> 5587<dt>a</dt><dd> alpha pixel component (0 is transparent)</dd> 5588<dt>o</dt><dd> opacity pixel component (0 is opaque)</dd> 5589<dt>i</dt><dd> grayscale intensity pixel component</dd> 5590<dt>c</dt><dd> cyan pixel component</dd> 5591<dt>m</dt><dd> magenta pixel component</dd> 5592<dt>y</dt><dd> yellow pixel component</dd> 5593<dt>k</dt><dd> black pixel component</dd> 5594<dt>p</dt><dd> pad component (always 0)</dd> 5595</dl> 5596 5597<p>You can specify as many of these components as needed in any order (e.g. 5598bgr). The components can repeat as well (e.g. rgbr).</p> 5599 5600 5601<div style="margin: auto;"> 5602 <h3 class="magick-header"><a id="mask"></a>-mask 5603<var>filename</var></h3> 5604</div> 5605 5606<p class="magick-description">Prevent updates to image pixels specified by the mask.</p> 5607 5608<p>This the same as using a mask used for composite masking operations, with 5609grayscale values causing blended updates of the image the mask is attached to. 5610</p> 5611 5612<p>Use <a href="command-line-options.html#mask">+mask</a> to remove the mask from images.</p> 5613 5614<p>Also see <a href="command-line-options.html#clip-mask">-clip-mask</a> which work in the same way, 5615but with strict boolean masking. </p> 5616 5617<div style="margin: auto;"> 5618 <h3 class="magick-header"><a id="mattecolor"></a>-mattecolor <var>color</var></h3> 5619</div> 5620 5621<p class="magick-description">Specify the color to be used with the <a href="command-line-options.html#frame">-frame</a> option.</p> 5622 5623<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 5624 5625<p>The default matte color is <code>#BDBDBD</code>, <span 5626style="background-color: #bdbdbd;">this shade of gray</span>.</p> 5627 5628<p>This is an IMv6 option, use <a href="command-line-options.html#alpha-color">-alpha-color</a> with IMv7.</p> 5629 5630<div style="margin: auto;"> 5631 <h3 class="magick-header"><a id="maximum"></a>-maximum</h3> 5632</div> 5633 5634<p class="magick-description">return the maximum intensity of an image sequence.</p> 5635 5636<p>Select the 'maximum' value from all the surrounding pixels. </p> 5637 5638<p>This is legacy option from the <a href="command-line-options.html#statistic" >method</a> of the same 5639name. </p> 5640 5641<div style="margin: auto;"> 5642 <h3 class="magick-header"><a id="median"></a>-median <var>geometry</var></h3> 5643</div> 5644 5645<p class="magick-description">apply a median filter to the image.</p> 5646 5647<p>Select the 'middle' value from all the surrounding pixels. </p> 5648 5649<p>This is legacy option from the <a href="command-line-options.html#statistic" >method</a> of the same 5650name. </p> 5651 5652<div style="margin: auto;"> 5653 <h3 class="magick-header"><a id="mean-shift"></a>-mean-shift <var>width</var>x<var>height</var>{<var>+distance</var>{%}</h3> 5654</div> 5655 5656<p class="magick-description">image noise removal and color reduction/segmentation (e.g. -mean-shift 7x7+10%).</p> 5657 5658<p><var>width</var>x<var>height</var> is the window size and <var>distance</var> is the color distance measured in the range 0 to 1 or 0 to 100%</p> 5659 5660<p>The mean shift algorithm is iterative and thus slower the larger the window size. For each pixel, it gets all the pixels in the window centered at the pixel and excludes those that are outside the <var>radius=sqrt((width-1)(height-1)/4)</var> surrounding the pixel. From those pixels, it finds which of them are within the specified squared color distance from the current mean. It then computes a new x,y centroid from those coordinates and a new mean. This new x,y centroid is used as the center for a new window. This process is iterated until it converges and the final mean is then used to replace the original pixel value. It repeats this process for the next pixel, etc, until it processes all pixels in the image. Results are better when using other colorspaces rather than RGB. Recommend YIQ, YUV or YCbCr, which seem to give equivalent results.</p> 5661 5662<div style="margin: auto;"> 5663 <h3 class="magick-header"><a id="metric"></a>-metric <var>type</var></h3> 5664</div> 5665 5666<p class="magick-description">Output to STDERR a measure of the differences between images according to the <var>type</var> given metric.</p> 5667 5668<p>Choose from:</p> 5669 5670<dl class="dl-horizontal"> 5671<dt>AE</dt><dd> absolute error count, number of different pixels (-fuzz effected)</dd> 5672<dt>FUZZ</dt><dd> mean color distance</dd> 5673<dt>MAE</dt><dd> mean absolute error (normalized), average channel error distance</dd> 5674<dt>MEPP</dt><dd> mean error per pixel (normalized mean error, normalized peak error)</dd> 5675<dt>MSE</dt><dd> mean error squared, average of the channel error squared</dd> 5676<dt>NCC</dt><dd> normalized cross correlation</dd> 5677<dt>PAE</dt><dd> peak absolute (normalized peak absolute)</dd> 5678<dt>PHASH</dt><dd> perceptual hash</dd> 5679<dt>PSNR</dt><dd> peak signal to noise ratio</dd> 5680<dt>RMSE</dt><dd> root mean squared (normalized root mean squared)</dd> 5681</dl> 5682 5683<p>Control the '<code>AE</code>', or absolute count of pixels that are different, 5684with the <a href="command-line-options.html#fuzz" >-fuzz</a> factor (ignore pixels which 5685only changed by a small amount). Use '<code>PAE</code>' to find the 5686size of the <a href="command-line-options.html#fuzz" >-fuzz</a> factor needed to make all pixels 5687'similar', while '<code>MAE</code>' determines the factor needed 5688for about half the pixels to be similar. </p> 5689 5690<p>The '<code>MEPP</code>' metric returns three different metrics 5691('<code>MAE</code>', '<code>MAE</code>' normalized, and '<code>PAE</code>' 5692normalized) from a single comparison run. </p> 5693 5694<p>To print a complete list of metrics, use the <a href="command-line-options.html#list">-list 5695metric</a> option.</p> 5696 5697 5698<div style="margin: auto;"> 5699 <h3 class="magick-header"><a id="minimum"></a>-minimum</h3> 5700</div> 5701 5702<p class="magick-description">return the minimum intensity of an image sequence.</p> 5703 5704<p>Select the 'minimal' value from all the surrounding pixels. </p> 5705 5706<p>This is legacy option from the <a href="command-line-options.html#statistic" >method</a> of the same 5707name. </p> 5708 5709 5710 5711<div style="margin: auto;"> 5712 <h3 class="magick-header"><a id="mode"></a>-mode <var>geometry</var></h3> 5713</div> 5714 5715<p class="magick-description">make each pixel the \'predominant color\' of the neighborhood.'</p> 5716 5717<div style="margin: auto;"> 5718 <h3 class="magick-header">-mode <var>value</var></h3> 5719</div> 5720 5721<p class="magick-description">Mode of operation.</p> 5722 5723<p>Choose the <var>value</var> from these styles: <code>Frame, 5724Unframe, or Concatenate</code></p> 5725 5726<p>Use the <a href="command-line-options.html#list" >-list</a> option with a '<code>Mode</code>' argument 5727for a list of <a href="command-line-options.html#mode" >-mode</a> arguments available in your 5728ImageMagick installation.</p> 5729 5730 5731<div style="margin: auto;"> 5732 <h3 class="magick-header"><a id="modulate"></a>-modulate <var>brightness</var>[,<var>saturation</var>,<var>hue</var>]</h3> 5733</div> 5734 5735<p class="magick-description">Vary the <var>brightness</var>, <var>saturation</var>, and <var>hue</var> of an image.</p> 5736 5737<p>The arguments are given as a percentages of variation. A value of 100 means 5738no change, and any missing values are taken to mean 100.</p> 5739 5740<p>The <var>brightness</var> is a multiplier of the overall 5741brightness of the image, so 0 means pure black, 50 is half as bright, 200 is 5742twice as bright. To invert its meaning <a href="command-line-options.html#negate">-negate</a> the image 5743before and after. </p> 5744 5745<p>The <var>saturation</var> controls the amount of color in an 5746image. For example, 0 produce a grayscale image, while a large value such as 5747200 produce a very colorful, 'cartoonish' color.</p> 5748 5749<p>The <var>hue</var> argument causes a "rotation" of the colors 5750within the image by the amount specified. For example, 50 results in 5751a counter-clockwise rotation of 90, mapping red shades to purple, and so on. 5752A value of either 0 or 200 results in a complete 180 degree rotation of the 5753image. Using a value of 300 is a 360 degree rotation resulting in no change to 5754the original image. </p> 5755 5756<p>For example, to increase the color brightness by 20% and decrease the color 5757saturation by 10% and leave the hue unchanged, use <a 5758href="command-line-options.html#modulate">-modulate 120,90</a>.</p> 5759 5760<p>Use <a href="command-line-options.html#set">-set</a> attribute of '<code 5761>option:modulate:colorspace</code>' to specify which colorspace to 5762modulate. Choose from <code>HCL</code>, <code>HCLp</code>, <code>HSB</code>, <code>HSI</code>, <code>HSL</code> (the default), <code>HSV</code>, <code>HWB</code>, or <code>LCH</code> (LCHuv). For example,</p> 5763 5764<pre> 5765convert image.png -set option:modulate:colorspace hsb -modulate 120,90 modulate.png 5766</pre> 5767 5768<div style="margin: auto;"> 5769 <h3 class="magick-header"><a id="moments"></a>-moments</h3> 5770</div> 5771 5772<p class="magick-description">report image moments and perceptual hash.</p> 5773 5774 5775<div style="margin: auto;"> 5776 <h3 class="magick-header"><a id="monitor"></a>-monitor</h3> 5777</div> 5778 5779<p class="magick-description">monitor progress.</p> 5780 5781 5782<div style="margin: auto;"> 5783 <h3 class="magick-header"><a id="monochrome"></a>-monochrome</h3> 5784</div> 5785 5786<p class="magick-description">transform the image to black and white.</p> 5787 5788<div style="margin: auto;"> 5789 <h3 class="magick-header"><a id="morph"></a>-morph <var>frames</var></h3> 5790</div> 5791 5792<p class="magick-description">morphs an image sequence.</p> 5793 5794<p>Both the image pixels and size are linearly interpolated to give the 5795appearance of a metamorphosis from one image to the next, over all the images 5796in the current image list. The added images are the equivalent of a <a 5797href="command-line-options.html#blend">-blend</a> composition. The <var>frames</var> 5798argument determine how many images to interpolate between each image. </p> 5799 5800 5801<div style="margin: auto;"> 5802 <h3 class="magick-header"><a id="morphology"></a>-morphology</h3> 5803 <h3 class="magick-header">-morphology <var>method</var> <var>kernel</var></h3> 5804</div> 5805 5806<p class="magick-description">apply a morphology method to the image.</p> 5807 5808<p>Until I get around to writing an option summary for this, see <a 5809href="http://www.imagemagick.org/Usage/morphology/" >IM Usage Examples, 5810Morphology</a>. </p> 5811 5812 5813<div style="margin: auto;"> 5814 <h3 class="magick-header"><a id="mosaic"></a>-mosaic</h3> 5815</div> 5816 5817<p class="magick-description">an simple alias for the <a href="command-line-options.html#layers" >-layers</a> method "mosaic"</p> 5818 5819 5820<div style="margin: auto;"> 5821 <h3 class="magick-header"><a id="motion-blur"></a>-motion-blur <var>radius</var><br />-motion-blur <var>radius</var>x<var>sigma</var>+<var>angle</var></h3> 5822</div> 5823 5824<p class="magick-description">simulate motion blur.</p> 5825 5826<p>Blur with the given radius, standard deviation (sigma), and angle. The 5827angle given is the angle toward which the image is blurred. That is the 5828direction people would consider the object is coming from. </p> 5829 5830<p>Note that the blur is not uniform distribution, giving the motion a 5831definite sense of direction of movement. </p> 5832 5833<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 5834pixels which are outside the image proper are blurred into the final result. 5835</p> 5836 5837<div style="margin: auto;"> 5838 <h3 class="magick-header"><a id="name"></a>-name</h3> 5839</div> 5840 5841<p class="magick-description">name an image.</p> 5842<div style="margin: auto;"> 5843 <h3 class="magick-header"><a id="negate"></a>-negate</h3> 5844</div> 5845 5846<p class="magick-description">replace each pixel with its complementary color.</p> 5847 5848<p>The red, green, and blue intensities of an image are negated. White becomes 5849black, yellow becomes blue, etc. Use <a href="command-line-options.html#negate">+negate</a> to only 5850negate the grayscale pixels of the image.</p> 5851 5852<div style="margin: auto;"> 5853 <h3 class="magick-header"><a id="noise"></a>-noise <var>geometry</var><br/> 5854 +noise <var>type</var></h3> 5855</div> 5856 5857<p class="magick-description">Add or reduce noise in an image.</p> 5858 5859<p>The principal function of noise peak elimination filter is to smooth the 5860objects within an image without losing edge information and without creating 5861undesired structures. The central idea of the algorithm is to replace a pixel 5862with its next neighbor in value within a pixel window, if this pixel has been 5863found to be noise. A pixel is defined as noise if and only if this pixel is 5864a maximum or minimum within the pixel window.</p> 5865 5866<p>Use <code><a href="command-line-options.html#noise">-noise</a> <var>radius</var></code> to 5867specify the width of the neighborhood when reducing noise. This is equivalent 5868to using a <code><a href="command-line-options.html#statistic" >-statistic</a> NonPeak</code> operation, 5869which should be used in preference.</p> 5870 5871<p>Use <a href="command-line-options.html#noise">+noise</a> followed by a noise <var>type</var> to add noise to an image. Choose from these noise 5872types:</p> 5873 5874<pre> 5875Gaussian 5876Impulse 5877Laplacian 5878Multiplicative 5879Poisson 5880Random 5881Uniform 5882</pre> 5883 5884<p>The amount of noise added can be controlled by the <code><a 5885href="command-line-options.html#attenuate" >-attenuate</a></code> setting. If unset the value is 5886equivalent to 1.0, or a maximum noise addition.</p> 5887 5888<p>Note that Random will replace the image with noise rather than add noise to the image. Use Uniform, if you wish to add random noise to the image.</p> 5889 5890<p>To print a complete list of noises, use the <a href="command-line-options.html#list">-list noise</a> option.</p> 5891 5892<p>Also see the <a href="command-line-options.html#evaluate">-evaluate</a> noise functions that allows 5893the use of a controlling value to specify the amount of noise that should be 5894added to an image. </p> 5895 5896 5897<div style="margin: auto;"> 5898 <h3 class="magick-header"><a id="normalize"></a>-normalize</h3> 5899</div> 5900 5901<p class="magick-description">Increase the contrast in an image by <var>stretching</var> the range of intensity values.</p> 5902 5903<p>The intensity values are stretched to cover the entire range of possible 5904values. While doing so, black-out at most <var>2%</var> of the pixels and 5905white-out at most <var>1%</var> of the pixels.</p> 5906 5907<p>Note that as of ImageMagick 6.4.7-0, <a href="command-line-options.html#normalize" >-normalize</a> 5908is equivalent to <a href="command-line-options.html#contrast-stretch" >-contrast-stretch 2%x1%</a>. 5909(Before this version, it was equivalent to <a href="command-line-options.html#contrast-stretch" 5910>-contrast-stretch 2%x99%</a>).</p> 5911 5912<p>All the channels are normalized in concert by the same amount so as to 5913preserve color integrity, when the default <a href="command-line-options.html#channel" >+channel</a> 5914setting is in use. Specifying any other <a href="command-line-options.html#channel" >-channel</a> 5915setting will normalize the RGB channels independently.</p> 5916 5917<p>See <a href="command-line-options.html#contrast-stretch" >-contrast-stretch</a> for more details. 5918Also see <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' normalization 5919that is better suited to mathematically generated images. </p> 5920 5921<p>This operator is under review for re-development. </p> 5922 5923 5924<div style="margin: auto;"> 5925 <h3 class="magick-header"><a id="opaque"></a>-opaque <var>color</var></h3> 5926</div> 5927 5928<p class="magick-description">change this color to the fill color within the image.</p> 5929 5930<p>The <var>color</var> argument is defined using the format 5931described under the <a href="command-line-options.html#fill" >-fill</a> option. The <a href="command-line-options.html#fuzz" 5932>-fuzz</a> setting can be used to match and replace colors similar to the one 5933given.</p> 5934 5935<p>Use <a href="command-line-options.html#opaque">+opaque</a> to paint any pixel that does not match 5936the target color. </p> 5937 5938<p>The <a href="command-line-options.html#transparent">-transparent</a> operator is exactly the same 5939as <a href="command-line-options.html#opaque" >-opaque</a> but replaces the matching color with 5940transparency rather than the current <a href="command-line-options.html#fill">-fill</a> color setting. 5941To ensure that it can do this it also ensures that the image has an alpha 5942channel enabled, as per "<code><a href="command-line-options.html#alpha" >-alpha</a> set</code>", for 5943the new transparent colors, and does not require you to modify the <a 5944href="command-line-options.html#channel">-channel</a> to enable alpha channel handling. </p> 5945 5946 5947<div style="margin: auto;"> 5948 <h3 class="magick-header"><a id="ordered-dither"></a>-ordered-dither <var>threshold_map</var>{,<var>level</var>...}</h3> 5949</div> 5950 5951<p class="magick-description">dither the image using a pre-defined ordered dither <var>threshold map</var> specified, and a uniform color map with the 5952given number of <var>levels</var> per color channel.</p> 5953 5954<p>You can choose from these standard threshold maps:</p> 5955 5956<pre class="pre-scrollable"> 5957threshold 1x1 Threshold 1x1 (non-dither) 5958checks 2x1 Checkerboard 2x1 (dither) 5959o2x2 2x2 Ordered 2x2 (dispersed) 5960o3x3 3x3 Ordered 3x3 (dispersed) 5961o4x4 4x4 Ordered 4x4 (dispersed) 5962o8x8 8x8 Ordered 8x8 (dispersed) 5963h3x4a 4x1 Halftone 4x4 (angled) 5964h6x6a 6x1 Halftone 6x6 (angled) 5965h8x8a 8x1 Halftone 8x8 (angled) 5966h3x4o Halftone 4x4 (orthogonal) 5967h6x6o Halftone 6x6 (orthogonal) 5968h8x8o Halftone 8x8 (orthogonal) 5969h36x16o Halftone 16x16 (orthogonal) 5970c5x5b c5x5 Circles 5x5 (black) 5971c5x5w Circles 5x5 (white) 5972c6x6b c6x6 Circles 6x6 (black) 5973c6x6w Circles 6x6 (white) 5974c7x7b c7x7 Circles 7x7 (black) 5975c7x7w Circles 7x7 (white) 5976</pre> 5977 5978<p> The <code>threshold</code> generated a simple 50% threshold of the image. 5979This could be used with <var >level</var> to do the equivalent of <a 5980href="command-line-options.html#posterize" >-posterize</a> to reduce an image to basic primary colors. 5981</p> 5982 5983<p>The <code>checks</code> pattern produces a 3 level checkerboard dither 5984pattern. That is a grayscale will become a pattern of solid black, solid 5985white, and mid-tone colors into a checkerboard pattern of black and white. 5986</p> 5987 5988<p>You can define your own <var >threshold map</var> for ordered 5989dithering and halftoning your images, in either personal or system 5990<code>thresholds.xml</code> XML file. See <a href="resources.html" >Resources</a> 5991for more details of configuration files. </p> 5992 5993<p>To print a complete list of the thresholds that have been defined, use the 5994<a href="command-line-options.html#list" >-list threshold</a> option.</p> 5995 5996<p>Note that at this time the same threshold dithering map is used for all 5997color channels, no attempt is made to offset or rotate the map for different 5998channels is made, to create an offset printing effect. Also as the maps are 5999simple threshold levels, the halftone and circle maps will create incomplete 6000circles along the edges of a colored area. Also all the effects are purely 6001on/off boolean effects, without anti-aliasing to make the circles smooth 6002looking. Large dots can be made to look better with a small amount of blurring 6003after being created. </p> 6004 6005 6006<div style="margin: auto;"> 6007 <h3 class="magick-header"><a id="orient"></a>-orient <var>image orientation</var></h3> 6008</div> 6009 6010<p class="magick-description">specify orientation of a digital camera image.</p> 6011 6012<p>Choose from these orientations:</p> 6013 6014<pre> 6015bottom-left right-top 6016bottom-right top-left 6017left-bottom top-right 6018left-top undefined 6019right-bottom 6020</pre> 6021 6022<p>To print a complete list of orientations, use the <a href="command-line-options.html#list" >-list 6023orientation</a> option.</p> 6024 6025 6026<div style="margin: auto;"> 6027 <h3 class="magick-header"><a id="page"></a>-page <var>geometry</var><br/> 6028 -page <var>media</var>[<var>offset</var>][{<var>^!<></var>}]<br/> 6029 +page 6030 </h3> 6031</div> 6032 6033<p class="magick-description">Set the size and location of an image on the larger virtual canvas.</p> 6034 6035<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6036 6037<p>For convenience you can specify the page size using <var>media</var> (see below). Offsets can then be added as with other 6038<var>geometry</var> arguments (e.g. <a 6039href="command-line-options.html#page">-page</a> <code>Letter+43+43</code>).</p> 6040 6041<p>Use <var>media</var> as shorthand to specify the dimensions (<var>width</var>x<var>height</var>) of the <var>PostScript</var> page in dots per inch or a TEXT page in pixels. 6042The choices for a PostScript page are:</p> 6043 6044<dl class="dl-horizontal"> 6045<dt> 11x17 </dt> <dd> 792 x 1224</dd> 6046<dt> Ledger </dt> <dd> 1224 x 792</dd> 6047<dt> Legal </dt> <dd> 612 x 1008</dd> 6048<dt> Letter </dt> <dd> 612 x 792</dd> 6049<dt> LetterSmall</dt> <dd> 612 x 792</dd> 6050<dt> ArchE </dt> <dd> 2592 x 3456</dd> 6051<dt> ArchD </dt> <dd> 1728 x 2592</dd> 6052<dt> ArchC </dt> <dd> 1296 x 1728</dd> 6053<dt> ArchB </dt> <dd> 864 x 1296</dd> 6054<dt> ArchA </dt> <dd> 648 x 864</dd> 6055<dt> A0 </dt> <dd> 2380 x 3368</dd> 6056<dt> A1 </dt> <dd> 1684 x 2380</dd> 6057<dt> A2 </dt> <dd> 1190 x 1684</dd> 6058<dt> A3 </dt> <dd> 842 x 1190</dd> 6059<dt> A4 </dt> <dd> 595 x 842</dd> 6060<dt> A4Small </dt> <dd> 595 x 842</dd> 6061<dt> A5 </dt> <dd> 421 x 595</dd> 6062<dt> A6 </dt> <dd> 297 x 421</dd> 6063<dt> A7 </dt> <dd> 210 x 297</dd> 6064<dt> A8 </dt> <dd> 148 x 210</dd> 6065<dt> A9 </dt> <dd> 105 x 148</dd> 6066<dt> A10 </dt> <dd> 74 x 105</dd> 6067<dt> B0 </dt> <dd> 2836 x 4008</dd> 6068<dt> B1 </dt> <dd> 2004 x 2836</dd> 6069<dt> B2 </dt> <dd> 1418 x 2004</dd> 6070<dt> B3 </dt> <dd> 1002 x 1418</dd> 6071<dt> B4 </dt> <dd> 709 x 1002</dd> 6072<dt> B5 </dt> <dd> 501 x 709</dd> 6073<dt> C0 </dt> <dd> 2600 x 3677</dd> 6074<dt> C1 </dt> <dd> 1837 x 2600</dd> 6075<dt> C2 </dt> <dd> 1298 x 1837</dd> 6076<dt> C3 </dt> <dd> 918 x 1298</dd> 6077<dt> C4 </dt> <dd> 649 x 918</dd> 6078<dt> C5 </dt> <dd> 459 x 649</dd> 6079<dt> C6 </dt> <dd> 323 x 459</dd> 6080<dt> Flsa </dt> <dd> 612 x 936</dd> 6081<dt> Flse </dt> <dd> 612 x 936</dd> 6082<dt> HalfLetter </dt> <dd> 396 x 612</dd> 6083</dl> 6084 6085<p>This option is also used to place subimages when writing to a multi-image 6086format that supports offsets, such as GIF89 and MNG. When used for this 6087purpose the offsets are always measured from the top left corner of the canvas 6088and are not affected by the <a href="command-line-options.html#gravity">-gravity</a> option. To 6089position a GIF or MNG image, use <a href="command-line-options.html#page">-page</a><var>{+-}x{+-}y</var> (e.g. -page +100+200). When writing to a MNG 6090file, a <a href="command-line-options.html#page">-page</a> option appearing ahead of the first image in 6091the sequence with nonzero width and height defines the width and height values 6092that are written in the <code>MHDR</code> chunk. Otherwise, the MNG width and 6093height are computed from the bounding box that contains all images in the 6094sequence. When writing a GIF89 file, only the bounding box method is used to 6095determine its dimensions.</p> 6096 6097<p>For a PostScript page, the image is sized as in <a 6098href="command-line-options.html#geometry">-geometry</a> but positioned relative to the <var>lower 6099left-hand corner</var> of the page by {+-}<code>x</code><var>offset</var>{+-}<code>y</code> <var>offset</var>. Use <a 6100href="command-line-options.html#page">-page 612x792</a>, for example, to center the image within the 6101page. If the image size exceeds the PostScript page, it is reduced to fit the 6102page. The default gravity for the <a href="command-line-options.html#page">-page</a> option is <var>NorthWest</var>, i.e., positive <code>x</code> and <code>y</code> <var>offset</var> are measured rightward and downward from the top left 6103corner of the page, unless the <a href="command-line-options.html#gravity">-gravity</a> option is 6104present with a value other than <var>NorthWest</var>.</p> 6105 6106<p>The default page dimensions for a TEXT image is 612x792.</p> 6107 6108<p>This option is used in concert with <a href="command-line-options.html#density">-density</a>.</p> 6109 6110<p>Use <a href="command-line-options.html#page">+page</a> to remove the page settings for an image.</p> 6111 6112<div style="margin: auto;"> 6113 <h3 class="magick-header"><a id="paint"></a>-paint <var>radius</var></h3> 6114</div> 6115 6116<p class="magick-description">simulate an oil painting.</p> 6117 6118<p>Each pixel is replaced by the most frequent color in a circular 6119neighborhood whose width is specified with <var>radius</var>.</p> 6120 6121<div style="margin: auto;"> 6122 <h3 class="magick-header"><a id="path"></a>-path <var>path</var></h3></div> 6123 6124<p class="magick-description">write images to this path on disk.</p> 6125 6126<div style="margin: auto;"> 6127 <h3 class="magick-header"><a id="pause_animate_"></a>-pause <var>seconds</var></h3> 6128</div> 6129 6130<p class="magick-description">Pause between animation loops</p> 6131 6132<p>Pause for the specified number of seconds before repeating the animation.</p> 6133 6134<div style="margin: auto;"> 6135 <h3 class="magick-header"><a id="pause_import_"></a>-pause <var>seconds</var></h3> 6136</div> 6137 6138<p class="magick-description">Pause between snapshots.</p> 6139 6140<p>Pause for the specified number of seconds before taking the next snapshot.</p> 6141 6142<div style="margin: auto;"> 6143 <h3 class="magick-header"><a id="perceptible"></a>-perceptible <var>epsilon</var></h3> 6144</div> 6145 6146<p class="magick-description">set each pixel whose value is less than |<var>epsilon</var>| to <var>-epsilon</var> or <var>epsilon</var> (whichever is closer) otherwise the pixel value remains unchanged.</p> 6147 6148<div style="margin: auto;"> 6149 <h3 class="magick-header"><a id="ping"></a>-ping</h3> 6150</div> 6151 6152<p class="magick-description">efficiently determine image characteristics.</p> 6153 6154<div style="margin: auto;"> 6155 <h3 class="magick-header"><a id="pointsize"></a>-pointsize <var>value</var></h3> 6156</div> 6157 6158<p class="magick-description">pointsize of the PostScript, OPTION1, or TrueType font.</p> 6159 6160<div style="margin: auto;"> 6161 <h3 class="magick-header"><a id="polaroid"></a>-polaroid <var>angle</var></h3> 6162</div> 6163 6164<p class="magick-description">simulate a Polaroid picture.</p> 6165 6166<p>Use <code>+polaroid</code> to rotate the image at a random angle between -15 and +15 degrees.</p> 6167 6168<div style="margin: auto;"> 6169 <h3 class="magick-header"><a id="poly"></a>-poly <var>"wt,exp ..."</var></h3> 6170</div> 6171 6172<p class="magick-description">combines multiple images according to a weighted sum of polynomials; one floating point weight (coefficient) and one floating point polynomial exponent (power) for each image expressed as comma separated pairs.</p> 6173 6174<p> The weights should typically be fractions between -1 and 1. But the sum of weights should be 1 or at least between 0 and 1 to avoid clamping in non-hdri mode at black and white.</p> 6175 6176<p>The exponents may be positive, negative or zero. A negative exponent is equivalent to 1 divided by the image raised to the corresponding positive exponent. A zero exponent always produces 1 scaled by quantumrange to white, i.e. wt*white, no matter what the image.</p> 6177 6178<p>The format is: <var>output = wt1*image1^exp1 + wt2*image2^exp2 </var>...</p> 6179 6180<p>Some simple uses are:</p> 6181<ul> 6182<li>A weighted sum of each image provided all weights add to unity and all exponents=1. If the the weights are all equal to 1/(number of images), then this is equivalent to <a href="command-line-options.html#profile">-evaluate-sequence</a> <var>mean</var>.</li> 6183<li>The sum of squares of two or more images, provided the weights are equal (and sum to 1 to avoid clamping) and the exponents equal 2.</li> 6184</ul> 6185 6186<p>Note that one may add a constant color to the expression simply by using xc:somecolor for one of the images and specifying the desired weight and exponent equal to 0.</p> 6187 6188<p>Similarly one may add white to the expression by simply using null: (or xc:white) for one of the images with the appropriate weight and exponent equal to 0.</p> 6189 6190 6191<div style="margin: auto;"> 6192 <h3 class="magick-header"><a id="posterize"></a>-posterize <var>levels</var></h3> 6193</div> 6194 6195<p class="magick-description">reduce the image to a limited number of color levels per channel.</p> 6196 6197<p>Very low values of <var>levels</var>, e.g., 2, 3, 4, have the most 6198visible effect.</p> 6199 6200<div style="margin: auto;"> 6201 <h3 class="magick-header"><a id="precision"></a>-precision <var>value</var></h3> 6202</div> 6203 6204<p class="magick-description">set the maximum number of significant digits to be printed.</p> 6205 6206<div style="margin: auto;"> 6207 <h3 class="magick-header"><a id="preview"></a>-preview <var>type</var></h3> 6208</div> 6209 6210<p class="magick-description">image preview type.</p> 6211 6212<p>Use this option to affect the preview operation of an image (e.g. 6213<code>convert file.png -preview Gamma Preview:gamma.png</code>). Choose from 6214these previews:</p> 6215 6216<pre class="pre-scrollable"> 6217AddNoise 6218Blur 6219Brightness 6220Charcoal 6221Despeckle 6222Dull 6223EdgeDetect 6224Gamma 6225Grayscale 6226Hue 6227Implode 6228JPEG 6229OilPaint 6230Quantize 6231Raise 6232ReduceNoise 6233Roll 6234Rotate 6235Saturation 6236Segment 6237Shade 6238Sharpen 6239Shear 6240Solarize 6241Spiff 6242Spread 6243Swirl 6244Threshold 6245Wave 6246</pre> 6247 6248<p>To print a complete list of previews, use the <a href="command-line-options.html#list">-list preview</a> option.</p> 6249 6250<p>The default preview is <code>JPEG</code>.</p> 6251 6252<div style="margin: auto;"> 6253 <h3 class="magick-header"><a id="print"></a>-print <var>string</var></h3> 6254</div> 6255 6256<p class="magick-description">interpret string and print to console.</p> 6257 6258<div style="margin: auto;"> 6259 <h3 class="magick-header"><a id="process"></a>-process <var>command</var></h3> 6260</div> 6261 6262<p class="magick-description">process the image with a custom image filter.</p> 6263 6264<p>The command arguments has the form <code>"module arg1 arg2 arg3 ... 6265argN"</code> where <code>module</code> is the name of the module to invoke (e.g. 6266"Analyze") and arg1 arg2 arg3 ... argN are an arbitrary number of arguments to 6267pass to the process module.</p> 6268 6269<div style="margin: auto;"> 6270 <h3 class="magick-header"><a id="profile"></a>-profile <var>filename</var><br/> 6271 +profile <var>profile_name</var></h3> 6272</div> 6273 6274<p class="magick-description">Manage ICM, IPTC, or generic profiles in an image.</p> 6275 6276<p>Using <a href="command-line-options.html#profile">-profile</a> <var>filename</var> adds an 6277ICM (ICC color management), IPTC (newswire information), or a generic profile 6278to the image.</p> 6279 6280<p>Use <a href="command-line-options.html#profile">+profile <var>profile_name</var></a> to 6281remove the indicated profile. ImageMagick uses standard filename globbing, so 6282wildcard expressions may be used to remove more than one profile. Here we 6283remove all profiles from the image except for the XMP profile: <code>+profile 6284"!xmp,*"</code>. </p> 6285 6286<p>Use <code>identify -verbose</code> to find out which profiles are in the 6287image file. Use <a href="command-line-options.html#strip">-strip</a> to remove all profiles (and 6288comments).</p> 6289 6290<p>To extract a profile, the <a href="command-line-options.html#profile">-profile</a> option is not 6291used. Instead, simply write the file to an image format such as <var>APP1, 8BIM, ICM,</var> or <var>IPTC</var>.</p> 6292 6293<p>For example, to extract the Exif data (which is stored in JPEG files in the 6294<var>APP1</var> profile), use.</p> 6295 6296<pre> 6297convert cockatoo.jpg profile.exif 6298</pre> 6299 6300<p>It is important to note that results may depend on whether or not the 6301original image already has an included profile. Also, keep in mind that <a 6302href="command-line-options.html#profile">-profile</a> is an "operator" (as opposed to a "setting") and 6303therefore a conversion is made each time it is encountered, in order, in the 6304command-line. For instance, in the following example, if the original image is 6305CMYK with profile, a CMYK-CMYK-RGB conversion results.</p> 6306 6307<pre> 6308convert CMYK.tif -profile "CMYK.icc" -profile "RGB.icc" RGB.tiff 6309</pre> 6310 6311<p>Furthermore, since ICC profiles are not necessarily symmetric, extra 6312conversion steps can yield unwanted results. CMYK profiles are often very 6313asymmetric since they involve 3−>4 and 4−>3 channel mapping. 6314</p> 6315 6316<div style="margin: auto;"> 6317 <h3 class="magick-header"><a id="quality"></a>-quality <var>value</var></h3> 6318</div> 6319 6320<p class="magick-description">JPEG/MIFF/PNG compression level.</p> 6321 6322<p>For the JPEG and MPEG image formats, quality is 1 (lowest image quality and 6323highest compression) to 100 (best quality but least effective compression). 6324The default is to use the estimated quality of your input image if it can 6325be determined, otherwise 92. When the quality is greater than 90, then the 6326chroma channels are not downsampled. 6327Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to specify the 6328factors for chroma downsampling.</p> 6329 6330<p>For the JPEG-2000 image format, quality is mapped using a non-linear 6331equation to the compression ratio required by the Jasper library. This 6332non-linear equation is intended to loosely approximate the quality provided by 6333the JPEG v1 format. The default quality value 100, a request for non-lossy 6334compression. A quality of 75 results in a request for 16:1 compression.</p> 6335 6336<p>For the MNG and PNG image formats, the quality value sets the zlib 6337compression level (quality / 10) and filter-type (quality % 10). The default 6338PNG "quality" is 75, which means compression level 7 with adaptive PNG 6339filtering, unless the image has a color map, in which case it means 6340compression level 7 with no PNG filtering.</p> 6341 6342<p>For compression level 0 (quality value less than 10), the Huffman-only 6343strategy is used, which is fastest but not necessarily the worst 6344compression.</p> 6345 6346<p>If filter-type is 4 or less, the specified PNG filter-type is used for 6347all scanlines:</p> 6348 6349<dl class="dl-horizontal"> 6350<dt>0</dt><dd>none</dd> 6351<dt>1</dt><dd>sub</dd> 6352<dt>2</dt><dd>up</dd> 6353<dt>3</dt><dd>average</dd> 6354<dt>4</dt><dd>Paeth</dd> 6355</dl> 6356 6357<p>If filter-type is 5, adaptive filtering is used when quality is greater 6358than 50 and the image does not have a color map, otherwise no filtering is 6359used.</p> 6360 6361<p>If filter-type is 6, adaptive filtering 6362with <var>minimum-sum-of-absolute-values</var> is used.</p> 6363 6364<p>Only if the output is MNG, if filter-type is 7, the LOCO color 6365transformation (intrapixel differencing) and adaptive filtering 6366with <var>minimum-sum-of-absolute-values</var> are used.</p> 6367 6368<p>If the filter-type is 8 the zlib Z_RLE compression strategy (or the 6369Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with 6370adaptive PNG filtering.</p> 6371 6372<p>If the filter-type is 9 the zlib Z_RLE compression strategy (or the 6373Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with 6374no PNG filtering.</p> 6375 6376<p>The quality setting has no effect on the appearance or signature of PNG 6377and MNG images, since the compression is always lossless.</p> 6378 6379<p>Not all combinations of compression level, strategy, and PNG filter type 6380can be obtained using the -quality option. For more precise control, 6381you can use the PNG:compression-level=N, PNG:compression-strategy=N, and 6382PNG:compression-filter=N defines, respectively, instead. 6383See <a href="command-line-options.html#define">-define</a>. Values from the defines take precedence 6384over values from the -quality option.</p> 6385 6386<p>For further information, see 6387the <a href="http://www.w3.org/pub/WWW/TR">PNG</a> specification.</p> 6388 6389<p>For the MIFF and TIFF image formats, quality/10 is the <a href="command-line-options.html#compress">Zip/BZip</a> compression level, which is 0 (worst but fastest compression) to 9 (best but slowest). It has no effect on the image appearance, since the compression is always lossless.</p> 6390 6391<p>For the BPG image format, quality/2 is the actual BPG compression level (range from 0 to 51).</p> 6392 6393<div style="margin: auto;"> 6394 <h3 class="magick-header"><a id="quantize"></a>-quantize <var>colorspace</var></h3> 6395</div> 6396 6397<p class="magick-description">reduce colors using this colorspace.</p> 6398 6399<p>This setting defines the colorspace used to sort out and reduce the number 6400of colors needed by an image (for later dithering) by operators such as <a 6401href="command-line-options.html#colors" >-colors</a>, Note that color reduction also happens 6402automatically when saving images to color-limited image file formats, such as 6403GIF, and PNG8.</p> 6404 6405 6406<div style="margin: auto;"> 6407 <h3 class="magick-header"><a id="quiet"></a>-quiet</h3> 6408</div> 6409 6410<p class="magick-description">suppress all warning messages. Error messages are still reported.</p> 6411 6412<div style="margin: auto;"> 6413 <h3 class="magick-header"><a id="radial-blur"></a>-radial-blur <var>angle</var></h3> 6414</div> 6415 6416<p class="magick-description">Blur around the center of the image.</p> 6417 6418<p>Note that this is actually a rotational blur rather than a radial and as 6419such actually mis-named. </p> 6420 6421<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 6422pixels which are outside the image proper are blurred into the final result. 6423</p> 6424 6425 6426<div style="margin: auto;"> 6427 <h3 class="magick-header"><a id="raise"></a>-raise <var>thickness</var></h3> 6428</div> 6429 6430<p class="magick-description">Lighten or darken image edges.</p> 6431 6432<p>This will create a 3-D effect. Use <a href="command-line-options.html#raise">-raise</a> to create 6433a raised effect, otherwise use <a href="command-line-options.html#raise">+raise</a>. </p> 6434 6435<p>Unlike the similar <a href="command-line-options.html#frame">-frame</a> option, <a 6436href="command-line-options.html#raise">-raise</a> does not alter the dimensions of the image.</p> 6437 6438<div style="margin: auto;"> 6439 <h3 class="magick-header"><a id="random-threshold"></a>-random-threshold <var>low</var>x<var>high</var></h3> 6440</div> 6441 6442<p class="magick-description">Apply a random threshold to the image.</p> 6443 6444<div style="margin: auto;"> 6445 <h3 class="magick-header"><a id="red-primary"></a>-red-primary <var>x,y</var></h3> 6446</div> 6447 6448<p class="magick-description">Set the red chromaticity primary point.</p> 6449 6450<div style="margin: auto;"> 6451 <h3 class="magick-header"><a id="regard-warnings"></a>-regard-warnings</h3> 6452</div> 6453 6454<p class="magick-description">Pay attention to warning messages.</p> 6455 6456<p>This option causes some warnings in some image formats to be treated 6457as errors. </p> 6458 6459<div style="margin: auto;"> 6460 <h3 class="magick-header"><a id="remap"></a>-remap <var>filename</var></h3> 6461</div> 6462 6463<p class="magick-description">Reduce the number of colors in an image to the colors used by this image.</p> 6464 6465<p>If the <a href="command-line-options.html#dither">-dither</a> setting is enabled (the default) then 6466the given colors are dithered over the image as necessary, otherwise the closest 6467color (in RGB colorspace) is selected to replace that pixel in the image. </p> 6468 6469<p>As a side effect of applying a <a href="command-line-options.html#remap">-remap</a> of colors across all 6470images in the current image sequence, all the images will have the same color 6471table. That means that when saved to a file format such as GIF, it will use 6472that color table as a single common or global color table, for all the images, 6473without requiring extra local color tables. </p> 6474 6475<p>Use <a href="command-line-options.html#remap">+remap</a> to reduce all images in the current image 6476sequence to use a common color map over all the images. This equivalent to 6477appending all the images together (without extra background colors) and color 6478reducing those images using <a href="command-line-options.html#colors">-colors</a> with a 256 color 6479limit, then <a href="command-line-options.html#remap">-remap</a> those colors over the original list of 6480images. This ensures all the images follow a single color map. </p> 6481 6482<p>If the number of colors over all the images is less than 256, then <a 6483href="command-line-options.html#remap">+remap</a> should not perform any color reduction or dithering, as 6484no color changes are needed. In that case, its only effect is to force the use 6485of a global color table. This recommended after using either <a 6486href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#ordered-dither">-ordered-dither</a> to 6487reduce the number of colors in an animated image sequence. </p> 6488 6489<p>Note, the remap image colormap has at most 8-bits of precision. Deeper color maps are automagically coalesced with other colors to meet this requirement.</p> 6490 6491<div style="margin: auto;"> 6492 <h3 class="magick-header"><a id="region"></a>-region <var>geometry</var></h3> 6493</div> 6494 6495<p class="magick-description">Set a region in which subsequent operations apply.</p> 6496 6497<p>The <var>x</var> and <var>y</var> offsets are treated 6498in the same manner as in <a href="command-line-options.html#crop">-crop</a>.</p> 6499 6500<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6501 6502<p>Use <code>+region</code> to remove any previously set regions.</p> 6503 6504<div style="margin: auto;"> 6505 <h3 class="magick-header"><a id="remote"></a>-remote</h3> 6506</div> 6507 6508<p class="magick-description">perform a remote operation.</p> 6509 6510<p>The only command recognized is the name of an image file to load.</p> 6511 6512<p>If you have more than one <a href="display.html">display</a> application 6513running simultaneously, use the <a href="command-line-options.html#window"> window</a> option to 6514specify which application to control.</p> 6515 6516<div style="margin: auto;"> 6517 <h3 class="magick-header"><a id="render"></a>-render</h3> 6518</div> 6519 6520<p class="magick-description">render vector operations.</p> 6521 6522<p>Use <a href="command-line-options.html#render">+render</a> to turn off rendering vector operations. 6523This useful when saving the result to vector formats such as MVG or SVG.</p> 6524 6525<div style="margin: auto;"> 6526<h3 class="magick-header"><a id="repage"></a>-repage <var>geometry</var></h3> 6527</div> 6528 6529<p class="magick-description">Adjust the canvas and offset information of the image.</p> 6530 6531<p>This option is like <a href="command-line-options.html#page">-page</a> but acts as an image operator 6532rather than a setting. You can separately set the canvas size or the offset 6533of the image on that canvas by only providing those components. </p> 6534 6535<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6536 6537<p>If a <code>!</code> flag is given the offset given is added to the existing 6538offset to move the image relative to its previous position. This useful for 6539animation sequences. </p> 6540 6541<p>A given a canvas size of zero such as '<code>0x0</code>' forces it to 6542recalculate the canvas size so the image (at its current offset) will appear 6543completely on that canvas (unless it has a negative offset).</p> 6544 6545<p>Use <a href="command-line-options.html#repage">+repage</a> to completely remove/reset the virtual 6546canvas meta-data from the images. </p> 6547 6548<p>The <a href="command-line-options.html#set">-set</a> '<code>page</code>' option can be used to 6549directly assign virtual canvas meta-data. </p> 6550 6551 6552<div style="margin: auto;"> 6553 <h3 class="magick-header"><a id="resample"></a>-resample <var>horizontal</var>x<var>vertical</var></h3> 6554</div> 6555 6556<p class="magick-description">Resample image to specified horizontal and vertical resolution.</p> 6557 6558<p>Resize the image so that its rendered size remains the same as the original 6559at the specified target resolution. For example, if a 300 DPI image renders at 65603 inches by 2 inches on a 300 DPI device, when the image has been resampled to 656172 DPI, it will render at 3 inches by 2 inches on a 72 DPI device. Note that 6562only a small number of image formats (e.g. JPEG, PNG, and TIFF) are capable of 6563storing the image resolution. For formats which do not support an image 6564resolution, the original resolution of the image must be specified via <a 6565href="command-line-options.html#density">-density</a> on the command line prior to specifying the 6566resample resolution.</p> 6567 6568<p>Note that Photoshop stores and obtains image resolution from a proprietary 6569embedded profile. If this profile exists in the image, then Photoshop will 6570continue to treat the image using its former resolution, ignoring the image 6571resolution specified in the standard file header.</p> 6572 6573<div style="margin: auto;"> 6574 <h3 class="magick-header"><a id="resize"></a>-resize <var>geometry</var></h3> 6575</div> 6576 6577<p class="magick-description">Resize an image.</p> 6578 6579<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets, if present in the geometry string, are 6580ignored, and the <a href="command-line-options.html#gravity">-gravity</a> option has no effect.</p> 6581 6582<p>If the <a href="command-line-options.html#filter">-filter</a> option 6583or <code>-define filter:option=value</code> precedes the <a 6584href="command-line-options.html#resize">-resize</a> option, the image is resized with the specified 6585filter.</p> 6586 6587<p>Many image processing algorithms assume your image is in a linear-light 6588coding. If your image is gamma-corrected, you can remove the nonlinear gamma 6589correction, apply the transform, then restore it like this:</p> 6590 6591<pre> 6592convert portrait.jpg -gamma .45455 -resize 25% -gamma 2.2 \ 6593 -quality 92 passport.jpg 6594</pre> 6595 6596<div style="margin: auto;"> 6597 <h3 class="magick-header"><a id="respect-parentheses"></a>-respect-parentheses</h3> 6598</div> 6599 6600<p class="magick-description">settings remain in effect until parenthesis boundary.</p> 6601 6602<div style="margin: auto;"> 6603 <h3 class="magick-header"><a id="reverse"></a>-reverse</h3> 6604</div> 6605 6606<p class="magick-description">Reverse the order of images in the current image list.</p> 6607 6608 6609<div style="margin: auto;"> 6610 <h3 class="magick-header"><a id="roll"></a>-roll {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var></h3> 6611</div> 6612 6613<p class="magick-description">roll an image vertically or horizontally by the amount given.</p> 6614 6615<p>A negative <var>x</var> offset rolls the image right-to-left. 6616A negative <var>y</var> offset rolls the image bottom-to-top.</p> 6617 6618 6619<div style="margin: auto;"> 6620 <h3 class="magick-header"><a id="rotate"></a>-rotate <var>degrees</var>{<var><</var>}{<var>></var>}</h3> 6621</div> 6622 6623<p class="magick-description">Apply Paeth image rotation (using shear operations) to the image.</p> 6624 6625<p>Use <code>></code> to rotate the image only if its width exceeds the 6626height. <code><</code> rotates the image <var>only</var> if its width is less 6627than the height. For example, if you specify <code>-rotate "-90>"</code> and 6628the image size is 480x640, the image is not rotated. However, if the image is 6629640x480, it is rotated by -90 degrees. If you use <code>></code> or 6630<code><</code>, enclose it in quotation marks to prevent it from being 6631misinterpreted as a file redirection.</p> 6632 6633<p>Empty triangles in the corners, left over from rotating the image, are 6634filled with the <code>background</code> color. </p> 6635 6636<p>See also the <a href="command-line-options.html#distort">-distort</a> operator and specifically the 6637'<code>ScaleRotateTranslate</code>' distort method. </p> 6638 6639 6640<div style="margin: auto;"> 6641 <h3 class="magick-header"><a id="sample"></a>-sample <var>geometry</var></h3> 6642</div> 6643 6644<p class="magick-description">minify / magnify the image with pixel subsampling and pixel replication, respectively.</p> 6645 6646<p>Change the image size simply by directly sampling the pixels original 6647from the image. When magnifying, pixels are replicated in blocks. When 6648minifying, pixels are sub-sampled (i.e., some rows and columns are skipped 6649over). </p> 6650 6651<p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with 6652a <a href="command-line-options.html#filter">-filter</a> setting of <code>point</code> (nearest 6653neighbor), though <a href="command-line-options.html#sample">-sample</a> is a lot faster, as it 6654avoids all the filter processing of the image. As such it completely ignores 6655the current <a href="command-line-options.html#filter">-filter</a> setting. </p> 6656 6657<p>The key feature of the <a href="command-line-options.html#sample">-sample</a> is that no new colors 6658will be added to the resulting image, though some colors may disappear. </p> 6659 6660<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets, if present in the geometry string, are 6661ignored, unlike <a href="command-line-options.html#resize">-resize</a>. </p> 6662 6663 6664<p>The actual sampling point is the middle of the sub-region being sampled. 6665As such a single pixel sampling of an image will take the middle pixel, (or 6666top-left-middle if image has even dimensions). However the <a 6667href="command-line-options.html#define">-define</a> '<code>sample:offset</code>' can be set to modify 6668this position some other location within each sub-region being sampled, as 6669a percentage offset.</p> 6670 6671<p>By default this value is '<code>50</code>' for the midpoint, but could be set 6672to '<code>0</code>' for top-left, '<code>100</code>' for bottom-right, or with 6673separate X and Y offsets such as '<code>0x50</code>' for left-middle edge of 6674sampling sub-region.</p> 6675 6676 6677<div style="margin: auto;"> 6678 <h3 class="magick-header"><a id="sampling-factor"></a>-sampling-factor <var>horizontal-factor</var>x<var>vertical-factor</var></h3> 6679</div> 6680 6681<p class="magick-description">sampling factors used by JPEG or MPEG-2 encoder and YUV decoder/encoder.</p> 6682 6683<p>This option specifies the sampling factors to be used by the JPEG encoder 6684for chroma downsampling. If this option is omitted, the JPEG library will use 6685its own default values. When reading or writing the YUV format and when 6686writing the M2V (MPEG-2) format, use <a 6687href="command-line-options.html#sampling-factor">-sampling-factor 2x1</a> or <a 6688href="command-line-options.html#sampling-factor">-sampling-factor 4:2:2</a> to specify the 4:2:2 6689downsampling method.</p> 6690 6691<div style="margin: auto;"> 6692 <h3 class="magick-header"><a id="scale"></a>-scale <var>geometry</var></h3> 6693</div> 6694 6695<p class="magick-description">minify / magnify the image with pixel block averaging and pixel replication, respectively.</p> 6696 6697<p>Change the image size simply by replacing pixels by averaging pixels 6698together when minifying, or replacing pixels when magnifying. </p> 6699 6700<p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with 6701a <a href="command-line-options.html#filter">-filter</a> setting of <code>box</code>. Though it is a lot 6702faster, as it avoids all the filter processing of the image. As such it 6703completely ignores the current <a href="command-line-options.html#filter">-filter</a> setting. </p> 6704 6705<p>If when shrinking (minifying) images the original image is some integer 6706multiple of the new image size, the number of pixels averaged together to 6707produce the new pixel color is the same across the whole image. This is 6708a special case known as 'binning' and is often used as a method of reducing 6709noise in image such as those generated by digital cameras, especially in low 6710light conditions. </p> 6711 6712 6713<div style="margin: auto;"> 6714 <h3 class="magick-header"><a id="scene"></a>-scene <var>value</var></h3> 6715</div> 6716 6717<p class="magick-description">set scene number.</p> 6718 6719<p>This option sets the scene number of an image or the first image in an image sequence.</p> 6720 6721<div style="margin: auto;"> 6722 <h3 class="magick-header"><a id="screen"></a>-screen</h3> 6723</div> 6724 6725<p class="magick-description">specify the screen to capture.</p> 6726 6727<p>This option indicates that the GetImage request used to obtain the image 6728should be done on the root window, rather than directly on the specified 6729window. In this way, you can obtain pieces of other windows that overlap the 6730specified window, and more importantly, you can capture menus or other popups 6731that are independent windows but appear over the specified window.</p> 6732 6733<div style="margin: auto;"> 6734 <h3 class="magick-header"><a id="seed"></a>-seed</h3> 6735</div> 6736 6737<p class="magick-description">seed a new sequence of pseudo-random numbers</p> 6738 6739<div style="margin: auto;"> 6740 <h3 class="magick-header"><a id="segment"></a>-segment <var>cluster-threshold</var>x<var>smoothing-threshold</var></h3> 6741</div> 6742 6743<p class="magick-description">segment the colors of an image.</p> 6744 6745<p>Segment an image by analyzing the histograms of the color components and 6746identifying units that are homogeneous with the fuzzy c-means technique. This 6747is part of the ImageMagick color quantization routines. </p> 6748 6749<p>Specify <var>cluster threshold</var> as the number of pixels in 6750each cluster that must exceed the cluster threshold to be considered valid. 6751<var>Smoothing threshold</var> eliminates noise in the second 6752derivative of the histogram. As the value is increased, you can expect 6753a smoother second derivative. The default is 1.5.</p> 6754 6755<p>If the <a href="command-line-options.html#verbose">-verbose</a> setting is defined, a detailed report 6756of the color clusters is returned.</p> 6757 6758 6759<div style="margin: auto;"> 6760 <h3 class="magick-header"><a id="selective-blur"></a>-selective-blur <var>radius</var><br />-selective-blur <var>radius</var>x<var>sigma</var>{<var>+threshold</var>}</h3> 6761</div> 6762 6763<p class="magick-description">Selectively blur pixels within a contrast threshold.</p> 6764 6765<p>Blurs those pixels that are less than or equal to the threshold in 6766contrast. The threshold may be expressed as a fraction of <var>QuantumRange</var> or as a percentage.</p> 6767 6768<div style="margin: auto;"> 6769 <h3 class="magick-header"><a id="separate"></a>-separate</h3> 6770</div> 6771 6772<p class="magick-description">separate an image channel into a grayscale image. Specify the channel with <a href="command-line-options.html#channel">-channel</a>.</p> 6773 6774<div style="margin: auto;"> 6775 <h3 class="magick-header"><a id="sepia-tone"></a>-sepia-tone <var>percent-threshold</var></h3> 6776</div> 6777 6778<p class="magick-description">simulate a sepia-toned photo.</p> 6779 6780<p>Specify <var>threshold</var> as the percent threshold of the intensity (0 - 99.9%).</p> 6781 6782<p>This option applies a special effect to the image, similar to the effect 6783achieved in a photo darkroom by sepia toning. Threshold ranges from 0 to <var>QuantumRange</var> and is a measure of the extent of the sepia 6784toning. A threshold of 80% is a good starting point for a reasonable 6785tone.</p> 6786 6787 6788 6789<div style="margin: auto;"> 6790 <h3 class="magick-header"><a id="set"></a>-set <var>key value</var></h3> 6791 <h3 class="magick-header">+set <var>key</var></h3> 6792</div> 6793 6794<p class="magick-description">sets image attributes and properties for images in the current image sequence.</p> 6795 6796<p>This will assign (or modify) specific settings attached to all the images 6797in the current image sequence. Using the <a href="command-line-options.html#set">+set</a> form of the 6798option will either remove, or reset that setting to a default state, as 6799appropriate. </p> 6800 6801<p>For example, it will modify specific well known image meta-data 6802'attributes' such as those normally overridden by: the options <a 6803href="command-line-options.html#delay" >-delay</a>, <a href="command-line-options.html#dispose" >-dispose</a>, and <a 6804href="command-line-options.html#page" >-page</a>, <a href="command-line-options.html#colorspace" >-colorspace</a>; generally 6805assigned before the image is read in, by using a <var>key</var> of 6806the same name. </p> 6807 6808<p>If the given <var>key</var> does not match a specific known 6809'attribute ', such as shown above, the setting is stored as a a free form 6810'property' string. Such settings are listed in <a href="command-line-options.html#verbose" 6811>-verbose</a> information ("<code>info:</code>" output format) as "Properties". 6812</p> 6813 6814<p>This includes string 'properties' that are set by and assigned to images 6815using the options <a href="command-line-options.html#comment" >-comment</a>, <a href="command-line-options.html#label" 6816>-label</a>, <a href="command-line-options.html#caption" >-caption</a>. These options actually assign 6817a global 'artifact' which are automatically assigned (and any <a href="escape.html" >Format Percent 6818Escapes</a> expanded) to images as they are read in. For example:</p> 6819 6820<pre> 6821-> convert rose: -set comment 'Rose is a rose is a rose is a rose' rose.png 6822identify -format %c rose.png 6823Rose is a rose is a rose is a rose 6824</pre> 6825 6826<p>The set value can also make use of <a href="escape.html" >Format and Print Image 6827Properties</a> in the defined value. For example:</p> 6828 6829<pre> 6830-> convert rose: -set origsize '%wx%h' -resize 50% \ 6831 -format 'Old size = %[origsize] New size = %wx%h' info: 6832Old size = 70x46 New size = 35x23 6833</pre> 6834 6835<p>Other well known 'properties' that are available include: 6836'<code>date:create</code>' and '<code>date:modify</code>' and 6837'<code>signature</code>'. </p> 6838 6839<p>The <a href="command-line-options.html#repage">-repage</a> operator will also allow you to modify 6840the '<code>page</code>' attribute of an image for images already in memory (also 6841see <a href="command-line-options.html#repage">-page</a>). However it is designed to provide a finer 6842control of the sub-parts of this 'attribute'. The <a href="command-line-options.html#set">-set page</a> 6843option will only provide a direct, unmodified assignment of '<code>page</code>' 6844attribute. </p> 6845 6846<p>This option can also associate a colorspace or profile with your image. 6847For example,</p> 6848 6849<pre> 6850convert image.psd -set profile ISOcoated_v2_eci.icc image-icc.psd 6851</pre> 6852 6853<p>Some 'properties' must be defined in a specific way to be used. For 6854example only 'properties' prefixed with "<code>filename:</code>" can be used to 6855modify the output filename of an image. For example</p> 6856 6857<pre> 6858convert rose: -set filename:mysize '%wx%h' 'rose_%[filename:mysize].png' 6859</pre> 6860 6861<p>If the setting value is prefixed with "<code>option:</code>" the setting will 6862be saved as a global "Artifact" exactly as if it was set using the <a 6863href="command-line-options.html#define" >-define</a> option. As such settings are global in scope, they 6864can be used to pass 'attributes' and 'properties' of one specific image, 6865in a way that allows you to use them in a completely different image, even if 6866the original image has long since been modified or destroyed. For example: </p> 6867 6868<pre> 6869convert rose: -set option:rosesize '%wx%h' -delete 0 \ 6870 label:'%[rosesize]' label_size_of_rose.gif" 6871</pre> 6872 6873<p>Note that <a href="escape.html" >Format Percent Escapes</a> will only match 6874a 'artifact' if the given <var>key</var> does not match an existing 6875'attribute' or 'property'. </p> 6876 6877<p>You can set the attributes of the image registry by prefixing the value 6878with <code>registry:</code>.</p> 6879 6880<p>The <a href="command-line-options.html#set">-set profile</a> option can also be used to inject 6881previously-formatted ancillary chunks into the output PNG file, using 6882the commandline option as shown below or by setting the profile via a 6883programming interface:</p> 6884 6885<pre> 6886convert in.png -set profile PNG-chunk-x:<filename> out.png 6887</pre> 6888 6889<p>where <var>x</var> is a location flag and 6890<var>filename</var> is a file containing the chunk 6891name in the first 4 bytes, then a colon (":"), followed by the chunk data. 6892This encoder will compute the chunk length and CRC, so those must not 6893be included in the file.</p> 6894 6895<p>"x" can be "b" (before PLTE), "m" (middle, i.e., between PLTE and IDAT), 6896or "e" (end, i.e., after IDAT). If you want to write multiple chunks 6897of the same type, then add a short unique string after the "x" to prevent 6898subsequent profiles from overwriting the preceding ones, e.g.,</p> 6899 6900 6901<pre> 6902convert in.png -set profile PNG-chunk-b01:file01 \ 6903 -profile PNG-chunk-b02:file02 out.png 6904</pre> 6905 6906<div style="margin: auto;"> 6907 <h3 class="magick-header"><a id="shade"></a>-shade <var>azimuth</var>x<var>elevation</var></h3> 6908</div> 6909 6910<p class="magick-description">shade the image using a distant light source.</p> 6911 6912<p>Specify <var>azimuth</var> and <var>elevation</var> as 6913the position of the light source. Use <a href="command-line-options.html#shade">+shade</a> to return 6914the shading results as a grayscale image.</p> 6915 6916<div style="margin: auto;"> 6917 <h3 class="magick-header"><a id="shadow"></a>-shadow <var>percent-opacity</var>{x<var>sigma</var>}{<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var>{<var>%</var>}</h3> 6918</div> 6919 6920<p class="magick-description">simulate an image shadow.</p> 6921 6922<div style="margin: auto;"> 6923 <h3 class="magick-header"><a 6924id="shared-memory"></a>-shared-memory</h3> 6925</div> 6926 6927<p class="magick-description">use shared memory.</p> 6928 6929<p>This option specifies whether the utility should attempt to use shared 6930memory for pixmaps. ImageMagick must be compiled with shared memory support, 6931and the display must support the <var>MIT-SHM</var> extension. 6932Otherwise, this option is ignored. The default is <code>True</code>.</p> 6933 6934<div style="margin: auto;"> 6935 <h3 class="magick-header"><a id="sharpen"></a>-sharpen <var>radius</var><br />-sharpen <var>radius</var>x<var>sigma</var></h3> 6936</div> 6937 6938<p class="magick-description">sharpen the image.</p> 6939 6940<p>Use a Gaussian operator of the given radius and standard deviation (sigma).</p> 6941 6942<div style="margin: auto;"> 6943 <h3 class="magick-header"><a id="shave"></a>-shave <var>geometry</var></h3> 6944</div> 6945 6946<p class="magick-description">Shave pixels from the image edges.</p> 6947 6948<p>The <var>size</var> portion of the <var>geometry</var> 6949argument specifies the width of the region to be removed from both sides of 6950the image and the height of the regions to be removed from top and bottom. 6951Offsets are ignored.</p> 6952 6953<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6954 6955<div style="margin: auto;"> 6956 <h3 class="magick-header"><a id="shear"></a>-shear <var>Xdegrees</var>[x<var>Ydegrees</var>]</h3> 6957</div> 6958 6959<p class="magick-description">Shear the image along the x-axis and/or y-axis.</p> 6960 6961<p>The shear angles may be positive, negative, or zero. When <var>Ydegrees</var> is omitted it defaults to 0. When both angles are 6962given, the horizontal component of the shear is performed before the vertical 6963component.</p> 6964 6965<p>Shearing slides one edge of an image along the x-axis or y-axis (i.e., 6966horizontally or vertically, respectively),creating a parallelogram. The amount 6967of each is controlled by the respective shear angle. For horizontal shears, 6968<var>Xdegrees</var> is measured clockwise relative to "up" (the 6969negative y-axis), sliding the top edge to the right when 0°<<var>Xdegrees</var><90° and to the left when 90°<<var>Xdegrees</var><180°. For vertical shears <var>Ydegrees</var> is measured clockwise relative to "right" (the 6970positive x-axis), sliding the right edge down when 0°<<var>Ydegrees</var><90° and up when 90°<<var>Ydegrees</var><180°.</p> 6971 6972<p>Empty triangles left over from shearing the image are filled with the color 6973defined by the <a href="command-line-options.html#fill">-background</a> option. The color is specified 6974using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 6975 6976<p>The horizontal shear is performed before the vertical part. This is 6977important to note, since horizontal and vertical shears do not 6978<var>commute</var>, i.e., the order matters in a sequence of shears. For 6979example, the following two commands are not equivalent.</p> 6980 6981<pre> 6982convert logo: -shear 20x0 -shear 0x60 logo-sheared.png 6983convert logo: -shear 0x60 -shear 20x0 logo-sheared.png 6984</pre> 6985 6986<p>The first of the two commands above is equivalent to the following, except 6987for the amount of empty space created; the command that follows generates 6988a smaller image, and so is a better choice in terms of time and space.</p> 6989 6990<pre> 6991convert logo: -shear 20x60 logo-sheared.png 6992</pre> 6993 6994<div style="margin: auto;"> 6995 <h3 class="magick-header"><a id="sigmoidal-contrast"></a>-sigmoidal-contrast <var>contrast</var>x<var>mid-point</var></h3> 6996</div> 6997 6998<p class="magick-description">increase the contrast without saturating highlights or shadows.</p> 6999 7000<p>Increase the contrast of the image using a sigmoidal transfer function 7001without saturating highlights or shadows. <var>Contrast</var> 7002indicates how much to increase the contrast. For example, 0 is none, 3 is 7003typical and 20 is a lot. 7004</p> 7005 7006<p>The <var>mid-point</var> indicates where the maximum change 7007'slope' in contrast should fall in the resultant image (0 is white; 50% is 7008middle-gray; 100% is black). </p> 7009 7010<p>By default the image contrast is increased, use <var>+sigmoidal-contrast</var> to decrease the contrast.</p> 7011 7012<p>To achieve the equivalent of a sigmoidal brightness change (similar to 7013a gamma adjustment), you would use <var>-sigmoidal-contrast 7014{brightness}x0%</var> to increase brightness and <var>+sigmoidal-contrast {brightness}x0%</var> to decrease brightness. 7015Note the use of '0' fo rthe mid-point of the sigmoidal curve. </p> 7016 7017<p>Using a very high <var>contrast</var> will produce a sort of 7018'smoothed thresholding' of the image. Not as sharp (with high aliasing 7019effects) of a true threshold, but with tapered gray-levels around the threshold 7020<var>mid-point</var>. </p> 7021 7022<div style="margin: auto;"> 7023 <h3 class="magick-header"><a id="silent"></a>-silent</h3> 7024 7025 7026</div> 7027 7028<p class="magick-description">operate silently. This option is only used 7029by the <a href="import.html">import</a> tool.</p> 7030 7031<div style="margin: auto;"> 7032 <h3 class="magick-header"><a id="similarity-threshold"></a>-similarity-threshold <var>value</var></h3> 7033</div> 7034 7035<p class="magick-description">minimum RMSE for subimage match.</p> 7036 7037<p>If this setting is used, then the search will stop as soon as it finds a match whose metric is less than or equal to the value. A partially filled second output image will result. Using a value of zero, will cause the search to stop at the first perfect match it finds. If this setting is left off, then the search will proceed to completion or as limited by <var>-dissimilarity-threshold</var>.</p> 7038 7039<div style="margin: auto;"> 7040 <h3 class="magick-header"><a id="size"></a>-size <var>width</var>[x<var>height</var>][<var>+offset</var>]</h3> 7041</div> 7042 7043<p class="magick-description">set the width and height of the image.</p> 7044 7045<p>Use this option to specify the width and height of raw images whose 7046dimensions are unknown such as <code>GRAY</code>, <code>RGB</code>, or 7047<code>CMYK</code>. In addition to width and height, use <a 7048href="command-line-options.html#size">-size</a> with an offset to skip any header information in the 7049image or tell the number of colors in a <code>MAP</code> image file, (e.g. -size 7050640x512+256).</p> 7051 7052<p>For Photo CD images, choose from these sizes:</p> 7053 7054<pre> 7055192x128 7056384x256 7057768x512 70581536x1024 70593072x2048 7060</pre> 7061 7062<div style="margin: auto;"> 7063 <h3 class="magick-header"><a id="sketch"></a>-sketch <var>radius</var><br />-sketch <var>radius</var>x<var>sigma</var>+<var>angle</var></h3> 7064</div> 7065 7066<p class="magick-description">simulate a pencil sketch.</p> 7067 7068<p>Sketch with the given radius, standard deviation (sigma), and angle. The 7069angle given is the angle toward which the image is sketched. That is the 7070direction people would consider the object is coming from. </p> 7071 7072<div style="margin: auto;"> 7073 <h3 class="magick-header"><a id="smush"></a>-smush <var>offset</var></h3> 7074</div> 7075 7076<p class="magick-description">smush an image sequence together.</p> 7077 7078<div style="margin: auto;"> 7079 <h3 class="magick-header"><a id="snaps"></a>-snaps <var>value</var></h3> 7080</div> 7081 7082<p class="magick-description">Set the number of screen snapshots.</p> 7083 7084<p>Use this option to grab more than one image from the X server screen, to create an animation sequence.</p> 7085 7086<div style="margin: auto;"> 7087 <h3 class="magick-header"><a id="solarize"></a>-solarize <var>percent-threshold</var></h3> 7088</div> 7089 7090<p class="magick-description">negate all pixels above the threshold level.</p> 7091 7092<p>Specify <var>factor</var> as the percent threshold of the intensity (0 - 99.9%).</p> 7093 7094<p>This option produces a <var>solarization</var> effect seen when 7095exposing a photographic film to light during the development process.</p> 7096 7097<div style="margin: auto;"> 7098 <h3 class="magick-header"><a id="sparse-color"></a>-sparse-color <var>method</var> '<var>x</var>,<var>y</var> <var>color</var> ...'</h3> 7099</div> 7100 7101<p class="magick-description"> color the given image using the specified points of color, and filling the other intervening colors using the given methods. </p> 7102 7103 7104<dl class="dl-horizontal"> 7105 <dt>barycentric</dt> 7106 <dd>three point triangle of color given 3 points. 7107 Giving only 2 points will form a linear gradient between those points. 7108 The gradient generated extends beyond the triangle created by those 7109 3 points. </dd> 7110 <dt>bilinear</dt> 7111 <dd>Like barycentric but for 4 points. Less than 4 points 7112 fall back to barycentric. </dd> 7113 <dt>voronoi</dt> 7114 <dd>Simply map each pixel to the to nearest color point 7115 given. The result are polygonal 'cells' of solid color. </dd> 7116 <dt>manhatten</dt> 7117 <dd>Like voronoi, but resulting polygonal 'cells' are mapped to a fixed coordinate system.</dd> 7118 <dt>shepards</dt> 7119 <dd>Colors points biased on the ratio of inverse distance 7120 squared. Generating spots of color in a sea of the average of 7121 colors. </dd> 7122 <dt>inverse</dt> 7123 <dd>Colors points biased on the ratio of inverse distance. 7124 This generates sharper points of color rather than rounded spots of 7125 '<code>shepards</code>' Generating spots of color in a sea of the 7126 average of colors. </dd> 7127</dl> 7128 7129<p>The points are placed according to the images location on the virtual 7130canvas (<a href="command-line-options.html#page" >-page</a> or <a href="command-line-options.html#repage" >-repage</a> 7131offset), and do not actually have to exist on the given image, but may be 7132some point beyond the edge of the image. All points are floating point values. 7133</p> 7134 7135<p>Only the color channels defined by the <a href="command-line-options.html#channel" >-channel</a> are 7136modified, which means that by default matte/alpha transparency channel is not 7137effected. Typically transparency channel is turned off either before or after 7138the operation. </p> 7139 7140<p>Of course if some color points are transparent to generate a transparent 7141gradient, then the image also requires transparency enabled to store the 7142values. </p> 7143 7144<p>All the above methods when given a single point of color will replace all 7145the colors in the image with the color given, regardless of the point. This is 7146logical, and provides an alternative technique to recolor an image to some 7147default value. </p> 7148 7149 7150<div style="margin: auto;"> 7151 <h3 class="magick-header"><a id="splice"></a>-splice <var>geometry</var></h3> 7152</div> 7153 7154<p class="magick-description">Splice the current background color into the image.</p> 7155 7156<p>This will add rows and columns of the current <a 7157href="command-line-options.html#background">-background</a> color into the given image according to the 7158given <a href="command-line-options.html#gravity">-gravity</a> geometry setting. See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Essentially <a href="command-line-options.html#splice">-splice</a> will divide the 7159image into four quadrants, separating them by the inserted rows and columns. 7160</p> 7161 7162<p>If a dimension of geometry is zero no rows or columns will be added for that 7163dimension. Similarly using a zero offset with the appropriate <a 7164href="command-line-options.html#gravity">-gravity</a> setting will add rows and columns to the edges of 7165the image, padding the image only along that one edge. Edge padding is what <a 7166href="command-line-options.html#splice">-splice</a> is most commonly used for. </p> 7167 7168<p>If the exact same <var>geometry</var> and <a 7169href="command-line-options.html#gravity">-gravity</a> is later used with <a href="command-line-options.html#chop">-chop</a> the 7170added added all splices removed. </p> 7171 7172<div style="margin: auto;"> 7173 <h3 class="magick-header"><a id="spread"></a>-spread <var>amount</var></h3> 7174</div> 7175 7176<p class="magick-description">displace image pixels by a random amount.</p> 7177 7178<p>The argument <var>amount</var> defines the size of the 7179neighborhood around each pixel from which to choose a candidate pixel to 7180blend.</p> 7181 7182<p>The lookup is controlled by the <a href="command-line-options.html#interpolate">-interpolate</a> setting.</p> 7183 7184<div style="margin: auto;"> 7185 <h3 class="magick-header"><a id="statistic"></a>-statistic <var>type</var> <var>geometry</var></h3> 7186</div> 7187 7188<p class="magick-description">replace each pixel with corresponding statistic from the neighborhood.</p> 7189 7190<p>Choose from these statistic types:</p> 7191<dl class="dl-horizontal"> 7192<dt>Gradient</dt><dd>maximum difference (max - min) value in neighborhood</dd> 7193<dt>Maximum</dt><dd>maximum value per channel in neighborhood</dd> 7194<dt>Minimum</dt><dd>minimum value per channel in neighborhood</dd> 7195<dt>Mean</dt><dd>average value per channel in neighborhood</dd> 7196<dt>Median</dt><dd>median value per channel in neighborhood</dd> 7197<dt>Mode</dt><dd>mode (most frequent) value per channel in neighborhood</dd> 7198<dt>Nonpeak</dt><dd>value just before or after the median value per channel in neighborhood</dd> 7199<dt>RMS</dt><dd>root mean square value per channel in neighborhood</dd> 7200<dt>StandardDeviation</dt><dd> standard deviation value per channel in neighborhood</dd> 7201</dl> 7202 7203<div style="margin: auto;"> 7204 <h3 class="magick-header"><a id="stegano"></a>-stegano <var>offset</var></h3> 7205</div> 7206 7207<p class="magick-description">hide watermark within an image.</p> 7208 7209<p>Use an offset to start the image hiding some number of pixels from the 7210beginning of the image. Note this offset and the image size. You will need 7211this information to recover the steganographic image (e.g. display -size 7212320x256+35 stegano:image.png).</p> 7213 7214<div style="margin: auto;"> 7215 <h3 class="magick-header"><a id="stereo"></a>-stereo <var>+x</var>{<var>+y</var>}</h3> 7216</div> 7217 7218<p class="magick-description">composite two images to create a red / cyan stereo anaglyph.</p> 7219 7220<p>The left side of the stereo pair (second image) is saved as the red channel of the output image. The right side (first image) is saved as the green and blue channels. Red-green stereo glasses are required to properly view the stereo image.</p> 7221 7222<div style="margin: auto;"> 7223 <h3 class="magick-header"><a id="storage-type"></a>-storage-type <var>type</var></h3> 7224</div> 7225 7226<p class="magick-description">pixel storage type. Here are the valid types:</p> 7227 7228<dl class="dl-horizontal"> 7229<dt>char</dt><dd>unsigned characters</dd> 7230<dt>double</dt><dd>doubles</dd> 7231<dt>float</dt><dd>floats</dd> 7232<dt>integer</dt><dd>integers</dd> 7233<dt>long</dt><dd>longs</dd> 7234<dt>quantum</dt><dd>pixels in the native depth of your ImageMagick distribution</dd> 7235<dt>short</dt><dd>unsigned shorts</dd> 7236</dl> 7237 7238<p>Float and double types are normalized from 0.0 to 1.0 otherwise the pixels 7239values range from 0 to the maximum value the storage type can support.</p> 7240 7241<div style="margin: auto;"> 7242 <h3 class="magick-header"><a id="stretch"></a>-stretch <var>fontStretch</var></h3> 7243</div> 7244 7245<p class="magick-description">Set a type of stretch style for fonts.</p> 7246 7247<p>This setting suggests a type of stretch that ImageMagick should try to 7248apply to the currently selected font family. Select <var>fontStretch</var> from the following.</p> 7249 7250<pre> 7251Any 7252Condensed 7253Expanded 7254ExtraCondensed 7255ExtraExpanded 7256Normal 7257SemiCondensed 7258SemiExpanded 7259UltraCondensed 7260UltraExpanded 7261</pre> 7262 7263<p>To print a complete list of stretch types, use <a href="command-line-options.html#list">-list 7264stretch</a>.</p> 7265 7266<p>For other settings that affect fonts, see the options <a 7267href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 7268href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 7269 7270<div style="margin: auto;"> 7271 <h3 class="magick-header"><a id="strip"></a>-strip</h3> 7272</div> 7273 7274<p class="magick-description">strip the image of any profiles, comments or these PNG chunks: bKGD,cHRM,EXIF,gAMA,iCCP,iTXt,sRGB,tEXt,zCCP,zTXt,date.</p> 7275 7276<div style="margin: auto;"> 7277 <h3 class="magick-header"><a id="stroke"></a>-stroke <var>color</var></h3> 7278</div> 7279 7280<p class="magick-description">color to use when stroking a graphic primitive.</p> 7281 7282<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 7283 7284<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 7285 7286<div style="margin: auto;"> 7287 <h3 class="magick-header"><a id="strokewidth"></a>-strokewidth <var>value</var></h3> 7288</div> 7289 7290<p class="magick-description">set the stroke width.</p> 7291 7292<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 7293 7294<div style="margin: auto;"> 7295 <h3 class="magick-header"><a id="style"></a>-style <var>fontStyle</var></h3> 7296</div> 7297 7298<p class="magick-description">Set a font style for text.</p> 7299 7300<p>This setting suggests a font style that ImageMagick should try to apply to 7301the currently selected font family. Select <var>fontStyle</var> from 7302the following.</p> 7303 7304<pre> 7305Any 7306Italic 7307Normal 7308Oblique 7309</pre> 7310 7311<p>For other settings that affect fonts, see the options <a 7312href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 7313href="command-line-options.html#stretch">-stretch</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 7314 7315<div style="margin: auto;"> 7316 <h3 class="magick-header"><a id="subimage-search"></a>-subimage-search</h3> 7317</div> 7318 7319<p class="magick-description">search for subimage.</p> 7320 7321<p>This option is required to have compare search for the best match location 7322of a small image within a larger image. This search will produce two images 7323(or two frames). The first is the "difference" image and the second will 7324be the "match score" image.</p> 7325 7326<p>The "match-score" image is smaller containing a pixel for ever possible 7327position of the top-left corner of the given sub-image. that is its size will 7328be the size of the larger_image - sub_image + 1. The brightest location in 7329this image is the location s the locate on the best match that is also 7330reported. Note that this may or may not be a perfect match, and the actual 7331brightness will reflect this. Other bright 'peaks' can be used to locate other 7332possible matching locations. </p> 7333 7334<p>Note that the search will try to compare the sub-image at every possible 7335location in the larger image, as such it can be very slow. The smaller the 7336sub-image the faster this search is. </p> 7337 7338 7339<div style="margin: auto;"> 7340 <h3 class="magick-header"><a id="swap"></a>-swap <var>index,index</var></h3> 7341</div> 7342 7343<p class="magick-description">Swap the positions of two images in the image sequence.</p> 7344 7345<p>For example, <a href="command-line-options.html#swap">-swap 0,2</a> swaps the first and the third 7346images in the current image sequence. Use <a href="command-line-options.html#swap">+swap</a> to switch 7347the last two images in the sequence.</p> 7348 7349<div style="margin: auto;"> 7350 <h3 class="magick-header"><a id="swirl"></a>-swirl <var>degrees</var></h3> 7351</div> 7352 7353<p class="magick-description">swirl image pixels about the center.</p> 7354 7355<p><var>Degrees</var> defines the tightness of the swirl.</p> 7356 7357<div style="margin: auto;"> 7358 <h3 class="magick-header"><a id="synchronize"></a>-synchronize</h3> 7359</div> 7360 7361<p class="magick-description">synchronize image to storage device.</p> 7362 7363<p>Set to "true" to ensure all image data is fully flushed and synchronized 7364to disk. There is a performance penalty, but the benefits include ensuring a 7365valid image file in the event of a system crash and early reporting if there 7366is not enough disk space for the image pixel cache.</p> 7367 7368<div style="margin: auto;"> 7369 <h3 class="magick-header"><a id="taint"></a>-taint</h3> 7370</div> 7371 7372<p class="magick-description">Mark the image as modified.</p> 7373 7374<div style="margin: auto;"> 7375 <h3 class="magick-header"><a id="text-font"></a>-text-font <var>name</var></h3> 7376</div> 7377 7378<p class="magick-description">font for writing fixed-width text.</p> 7379 7380<p>Specifies the name of the preferred font to use in fixed (typewriter style) 7381formatted text. The default is 14 point <var>Courier</var>.</p> 7382 7383<p>You can tag a font to specify whether it is a PostScript, TrueType, or 7384OPTION1 font. For example, <code>Courier.ttf</code> is a TrueType font and 7385<code>x:fixed</code> is OPTION1.</p> 7386 7387<div style="margin: auto;"> 7388 <h3 class="magick-header"><a id="texture"></a>-texture <var>filename</var></h3> 7389</div> 7390 7391<p class="magick-description">name of texture to tile onto the image background.</p> 7392 7393<div style="margin: auto;"> 7394 <h3 class="magick-header"><a id="threshold"></a>-threshold <var>value</var>{<var>%</var>}</h3> 7395</div> 7396 7397<!-- {<var>green,blue,opacity</var>} 7398<p>If the green or blue value is omitted, these channels use the same value as 7399the first one provided. If all three color values are the same, the result is 7400a bi-level image. If the opacity threshold is omitted, OpaqueOpacity is used 7401and any partially transparent pixel becomes fully transparent.</p> 7402--> 7403 7404<p class="magick-description">Apply simultaneous black/white threshold to the image.</p> 7405 7406<p>Any pixel values (more specifically, those channels set using <a href="command-line-options.html#channel">‑channel</a>) that exceed the specified threshold are reassigned the 7407maximum channel value, while all other values are assigned the minimum.</p> 7408 7409<p> The threshold value can be given as a percentage or as an absolute integer 7410value corresponding to the desired channel value. When given as an integer, 7411the minimum attainable value is 0 (corresponding to black when all channels 7412are affected), but the maximum value (corresponding to white) is that of the 7413<code>quantum depth</code> of the particular build of ImageMagick, and is 7414therefore dependent on the installation. For that reason, a reasonable 7415recommendation for most applications is to specify the threshold values as 7416a percentage. </p> 7417 7418<p> The following would force pixels with red values above 50% to have 100% 7419red values, while those at or below 50% red would be set to 0 in the red 7420channel. The green, blue, and alpha channels (if present) would be unchanged. 7421</p> 7422 7423<pre> 7424convert in.png -channel red -threshold 50% out.png 7425</pre> 7426 7427<p>As (possibly) impractical but instructive examples, the following would 7428generate an all-black and an all-white image with the same dimensions as the 7429input image.</p> 7430 7431 7432<pre> 7433convert in.png -threshold 100% black.png 7434convert in.png -threshold -1 white.png 7435</pre> 7436 7437<p>Note that the values of the transparency channel is treated as 'matte' 7438values (0 is opaque) and not as 'alpha' values (0 is transparent).</p> 7439 7440<p> See also <a href="command-line-options.html#black-threshold">‑black‑threshold</a> and <a href="command-line-options.html#white-threshold">‑white‑threshold</a>. 7441</p> 7442 7443<div style="margin: auto;"> 7444 <h3 class="magick-header"><a id="thumbnail"></a>-thumbnail <var>geometry</var></h3> 7445</div> 7446 7447<p class="magick-description">Create a thumbnail of the image.</p> 7448 7449<p>This is similar to <a href="command-line-options.html#resize">-resize</a>, except it is optimized 7450for speed and any image profile, other than a color profile, is removed to 7451reduce the thumbnail size. To strip the color profiles as well, add <a 7452href="command-line-options.html#strip">-strip</a> just before of after this option.</p> 7453 7454<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 7455 7456<div style="margin: auto;"> 7457 <h3 class="magick-header"><a id="tile"></a>-tile <var>filename</var></h3> 7458</div> 7459 7460<p class="magick-description">Set the tile image used for filling a subsequent graphic primitive.</p> 7461 7462<div style="margin: auto;"> 7463 <h3 class="magick-header">-tile <var>geometry</var></h3> 7464</div> 7465 7466<p class="magick-description">Specify the layout of images.</p> 7467 7468<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 7469 7470<div style="margin: auto;"> 7471 <h3 class="magick-header">-tile</h3> 7472</div> 7473 7474<p class="magick-description">Specifies that a subsequent composite operation is repeated across and down image.</p> 7475 7476<div style="margin: auto;"> 7477 <h3 class="magick-header"><a id="tile-offset"></a>-tile-offset {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var></h3> 7478</div> 7479 7480<p class="magick-description">Specify the offset for tile images, relative to the background image it is tiled on.</p> 7481 7482<p>This should be set before the tiling image is set by <a href="command-line-options.html#tile" 7483>-tile</a> or <a href="command-line-options.html#texture" >-texture</a>, or directly applied for 7484creating a tiled canvas using <code>TILE:</code> or <code>PATTERN:</code> input 7485formats. </p> 7486 7487<p>Internally ImageMagick does a <a href="command-line-options.html#roll" >-roll</a> of the tile image 7488by the arguments given when the tile image is set. </p> 7489 7490<div style="margin: auto;"> 7491 <h3 class="magick-header"><a id="tint"></a>-tint <var>value</var></h3> 7492</div> 7493 7494<p class="magick-description">Tint the image with the fill color.</p> 7495 7496<p>Tint the image with the fill color.</p> 7497 7498<p>Specify the amount of tinting as a percentage. Pure colors like black, 7499white red, yellow, will not be affected by -tint. Only mid-range colors such 7500as the various shades of grey.</p> 7501 7502<div style="margin: auto;"> 7503 <h3 class="magick-header"><a id="title"></a>-title <var>string</var></h3> 7504</div> 7505 7506<p class="magick-description">Assign a title to displayed image.", "animate", "display", "montage</p> 7507 7508<p>Use this option to assign a specific title to the image. This assigned to 7509the image window and is typically displayed in the window title bar. 7510Optionally you can include the image filename, type, width, height, Exif data, 7511or other image attribute by embedding special format characters described 7512under the <a href="command-line-options.html#format">-format</a> option.</p> 7513 7514<p>For example,</p> 7515 7516<pre> 7517-title "%m:%f %wx%h" 7518</pre> 7519 7520<p>produces an image title of <code>MIFF:bird.miff 512x480</code> for an image 7521titled <code>bird.miff</code> and whose width is 512 and height is 480.</p> 7522 7523 7524<div style="margin: auto;"> 7525 <h3 class="magick-header"><a id="transform"></a>-transform</h3> 7526</div> 7527 7528<p class="magick-description">transform the image.</p> 7529 7530<p>This option applies the transformation matrix from a previous <a href="command-line-options.html#affine">-affine</a> option.</p> 7531 7532<pre> 7533convert -affine 2,2,-2,2,0,0 -transform bird.ppm bird.jpg 7534</pre> 7535 7536 7537<p>This operator has been now been superseded by the <a 7538href="command-line-options.html#distort">-distort</a> '<code>AffineProjection</code>' method. </p> 7539 7540 7541<div style="margin: auto;"> 7542 <h3 class="magick-header"><a id="transparent"></a>-transparent <var>color</var></h3> 7543</div> 7544 7545<p class="magick-description">Make this color transparent within the image.</p> 7546 7547<p>The <var>color</var> argument is defined using the format 7548described under the <a href="command-line-options.html#fill">-fill</a> option. The <a href="command-line-options.html#fuzz" 7549>-fuzz</a> setting can be used to match and replace colors similar to the one 7550given. </p> 7551 7552<p>Use <a href="command-line-options.html#transparent" >+transparent</a> to invert the pixels matched. 7553that is make all non-matching colors transparent. </p> 7554 7555<p>The <a href="command-line-options.html#opaque">-opaque</a> operator is exactly the same as <a 7556href="command-line-options.html#transparent" >-transparent</a> but replaces the matching color with the 7557current <a href="command-line-options.html#fill">-fill</a> color setting, rather than transparent. 7558However the <a href="command-line-options.html#transparent" >-transparent</a> operator also ensures 7559that the image has an alpha channel enabled, as per "<code><a href="command-line-options.html#alpha" 7560>-alpha</a> set</code>", and does not require you to modify the <a 7561href="command-line-options.html#channel">-channel</a> to enable alpha channel handling. </p> 7562 7563<p>Note that this does not define the color as being the 'transparency color' 7564used for color-mapped image formats, such as GIF. For that use <a 7565href="command-line-options.html#transparent-color" >-transparent-color</a> </p> 7566 7567 7568<div style="margin: auto;"> 7569 <h3 class="magick-header"><a id="transparent-color"></a>-transparent-color <var>color</var></h3> 7570</div> 7571 7572<p class="magick-description">Set the transparent color.</p> 7573 7574<p>Sometimes this is used for saving to image formats such as 7575GIF and PNG8 which uses this color to represent boolean transparency. This 7576does not make a color transparent, it only defines what color the transparent 7577color is in the color palette of the saved image. Use <a 7578href="command-line-options.html#transparent">-transparent</a> to make an opaque color transparent.</p> 7579 7580<p>This option allows you to have both an opaque visible color, as well as a 7581transparent color of the same color value without conflict. That is, you can 7582use the same color for both the transparent and opaque color areas within an 7583image. This, in turn, frees to you to select a transparent color that is 7584appropriate when an image is displayed by an application that does not handle a 7585transparent color index, while allowing ImageMagick to correctly handle images of this 7586type. </p> 7587 7588<p>The default transparent color is <code>#00000000</code>, which is fully transparent black.</p> 7589 7590<div style="margin: auto;"> 7591 <h3 class="magick-header"><a id="transpose"></a>-transpose</h3> 7592</div> 7593 7594<p class="magick-description">Mirror the image along the top-left to bottom-right diagonal.</p> 7595 7596<p> This option mathematically transposes the pixel array. It is equivalent to the sequence <code>-flip -rotate 90</code>. 7597</p> 7598 7599<div style="margin: auto;"> 7600 <h3 class="magick-header"><a id="transverse"></a>-transverse</h3> 7601</div> 7602 7603<p class="magick-description">Mirror the image along the images bottom-left top-right diagonal. Equivalent to the operations <code>-flop -rotate 90</code>.</p> 7604 7605 7606<div style="margin: auto;"> 7607 <h3 class="magick-header"><a id="treedepth"></a>-treedepth <var>value</var></h3> 7608</div> 7609 7610<p class="magick-description">tree depth for the color reduction algorithm.</p> 7611 7612<p>Normally, this integer value is zero or one. A value of zero or one causes 7613the use of an optimal tree depth for the color reduction algorithm.</p> 7614 7615<p>An optimal depth generally allows the best representation of the source 7616image with the fastest computational speed and the least amount of memory. 7617However, the default depth is inappropriate for some images. To assure the 7618best representation, try values between 2 and 8 for this parameter. Refer to 7619the <a href="quantize.html" 7620>color reduction algorithm</a> for more details.</p> 7621 7622<p>The <a href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#monochrome">-monochrome</a> 7623option, or writing to an image format which requires color reduction, is 7624required for this option to take effect.</p> 7625 7626<div style="margin: auto;"> 7627 <h3 class="magick-header"><a id="trim"></a>-trim</h3> 7628</div> 7629 7630<p class="magick-description">trim an image.</p> 7631 7632<p>This option removes any edges that are exactly the same color as the corner 7633pixels. Use <a href="command-line-options.html#fuzz">-fuzz</a> to make <a href="command-line-options.html#trim">-trim</a> remove 7634edges that are nearly the same color as the corner pixels.</p> 7635 7636<p>The page or virtual canvas information of the image is preserved allowing 7637you to extract the result of the <a href="command-line-options.html#trim">-trim</a> operation from the 7638image. Use a <a href="command-line-options.html#repage">+repage</a> to remove the virtual canvas page 7639information if it is unwanted.</p> 7640 7641<p>If the trimmed image 'disappears' an warning is produced, and a special 7642single pixel transparent 'missed' image is returned, in the same way as when a 7643<a href="command-line-options.html#crop">-crop</a> operation 'misses' the image proper. </p> 7644 7645 7646<div style="margin: auto;"> 7647 <h3 class="magick-header"><a id="type"></a>-type <var>type</var></h3> 7648</div> 7649 7650<p class="magick-description">the image type.</p> <p>Choose from: <code>Bilevel</code>, 7651<code>Grayscale</code>, <code>GrayscaleMatte</code>, <code>Palette</code>, 7652<code>PaletteMatte</code>, <code>TrueColor</code>, <code>TrueColorMatte</code>, 7653<code>ColorSeparation</code>, or <code>ColorSeparationMatte</code>.</p> 7654 7655<p>Normally, when a format supports different subformats such as grayscale and 7656truecolor, the encoder will try to choose an efficient subformat. The <a 7657href="command-line-options.html#type">-type</a> option can be used to override this behavior. For 7658example, to prevent a JPEG from being written in grayscale format even though 7659only gray pixels are present, use.</p> 7660 7661<pre> 7662convert bird.png -type TrueColor bird.jpg 7663</pre> 7664 7665<p>Similarly, use <a href="command-line-options.html#type">-type TrueColorMatte</a> to force the 7666encoder to write an alpha channel even though the image is opaque, if the 7667output format supports transparency.</p> 7668 7669<p>Use <a href="command-line-options.html#type">-type optimize</a> to ensure the image is written in the smallest possible file size.</p> 7670 7671<div style="margin: auto;"> 7672 <h3 class="magick-header"><a id="undercolor"></a>-undercolor <var>color</var></h3> 7673</div> 7674 7675<p class="magick-description">set the color of the annotation bounding box.</p> 7676 7677<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 7678 7679<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 7680 7681 7682<div style="margin: auto;"> 7683 <h3 class="magick-header"><a id="update"></a>-update <var>seconds</var></h3> 7684</div> 7685 7686<p class="magick-description">detect when image file is modified and redisplay.</p> 7687 7688<p>Suppose that while you are displaying an image the file that is currently 7689displayed is over-written. <code>display</code> will automagically detect that 7690the input file has been changed and update the displayed image 7691accordingly.</p> 7692 7693 7694<div style="margin: auto;"> 7695 <h3 class="magick-header"><a id="unique-colors"></a>-unique-colors</h3> 7696</div> 7697 7698<p class="magick-description">discard all but one of any pixel color.</p> 7699 7700 7701<div style="margin: auto;"> 7702 <h3 class="magick-header"><a id="units"></a>-units <var>type</var></h3> 7703</div> 7704 7705<p class="magick-description">the units of image resolution.</p> 7706 7707<p>Choose from: <code>Undefined</code>, <code>PixelsPerInch</code>, or 7708<code>PixelsPerCentimeter</code>. This option is normally used in conjunction 7709with the <a href="command-line-options.html#density">-density</a> option.</p> 7710 7711 7712<div style="margin: auto;"> 7713 <h3 class="magick-header"><a id="unsharp"></a>-unsharp <var>radius</var><br />-unsharp <var>radius</var>x<var>sigma</var>{<var>+gain</var>}{<var>+threshold</var>}</h3> 7714</div> 7715 7716<p class="magick-description">sharpen the image with an unsharp mask operator.</p> 7717 7718<p>The <a href="command-line-options.html#unsharp">-unsharp</a> option sharpens an image. The image is 7719convolved with a Gaussian operator of the given radius and standard deviation 7720(sigma). For reasonable results, radius should be larger than sigma. Use 7721a radius of 0 to have the method select a suitable radius.</p> 7722 7723<p>The parameters are:</p> 7724 7725<dl class="dl-horizontal"> 7726<dt>radius</dt> 7727<dd>The radius of the Gaussian, in pixels, not counting the center pixel (default 0).</dd> 7728<dt>sigma</dt> 7729<dd>The standard deviation of the Gaussian, in pixels (default 1.0).</dd> 7730<dt>gain</dt> 7731<dd>The fraction of the difference between the original and the blur image that is added back into the original (default 1.0).</dd> 7732<dt>threshold</dt> 7733<dd>The threshold, as a fraction of <var>QuantumRange</var>, needed to apply the difference amount (default 0.05).</dd> 7734</dl> 7735 7736<div style="margin: auto;"> 7737 <h3 class="magick-header"><a id="verbose"></a>-verbose</h3> 7738</div> 7739 7740<p class="magick-description">print detailed information about the image when this option precedes the <a href="command-line-options.html#identify">-identify</a> option or <code>info:</code>.</p> 7741 7742 7743<div style="margin: auto;"> 7744 <h3 class="magick-header"><a id="version"></a>-version</h3> 7745</div> 7746 7747<p class="magick-description">print ImageMagick version string and exit.</p> 7748 7749 7750<div style="margin: auto;"> 7751 <h3 class="magick-header"><a id="view"></a>-view <var>string</var></h3> 7752</div> 7753 7754<p class="magick-description">FlashPix viewing parameters.</p> 7755 7756 7757<div style="margin: auto;"> 7758 <h3 class="magick-header"><a id="vignette"></a>-vignette <var>radius</var>{x<var>sigma</var>}{<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var>{<var>%</var>}</h3> 7759</div> 7760 7761<p class="magick-description">soften the edges of the image in vignette style.</p> 7762 7763<p>The vignette effect rolloff is controlled by radiusxsigma. For nominal rolloff, this would be set to 0xsigma. A value of 0x0 will produce a circle/ellipse with no rolloff. The arguments x and y control the size of the circle. Larger values decrease the radii and smaller values increase the radii. Values of +0+0 will generate a circle/ellipse the same size as the image. The default values for x and y are 10% of the corresponding image dimension. Thus, the radii will be decreased by 10%, i.e., the diameters of the circle/ellipse will be 80% of the corresponding image dimension.</p> 7764 7765<div style="margin: auto;"> 7766 <h3 class="magick-header"><a id="virtual-pixel"></a>-virtual-pixel <var>method</var></h3> 7767</div> 7768 7769<p class="magick-description">Specify contents of <var>virtual pixels</var>.</p> 7770 7771<p>This option defines what color source should be used if and when a color 7772lookup completely 'misses' the source image. The color(s) that appear to 7773surround the source image. Generally this color is derived from the source 7774image, but could also be set to a specify background color. </p> 7775 7776<p>Choose from these methods:</p> 7777 7778<dl class="dl-horizontal"> 7779<dt>background</dt><dd>the area surrounding the image is the background color</dd> 7780<dt>black</dt><dd>the area surrounding the image is black</dd> 7781<dt>checker-tile</dt><dd>alternate squares with image and background color</dd> 7782<dt>dither</dt><dd>non-random 32x32 dithered pattern</dd> 7783<dt>edge</dt><dd>extend the edge pixel toward infinity</dd> 7784<dt>gray</dt><dd>the area surrounding the image is gray</dd> 7785<dt>horizontal-tile</dt><dd>horizontally tile the image, background color above/below</dd> 7786<dt>horizontal-tile-edge</dt><dd>horizontally tile the image and replicate the side edge pixels</dd> 7787<dt>mirror</dt><dd>mirror tile the image</dd> 7788<dt>random</dt><dd>choose a random pixel from the image</dd> 7789<dt>tile</dt><dd>tile the image (default)</dd> 7790<dt>transparent</dt><dd>the area surrounding the image is transparent blackness</dd> 7791<dt>vertical-tile</dt><dd>vertically tile the image, sides are background color</dd> 7792<dt>vertical-tile-edge</dt><dd>vertically tile the image and replicate the side edge pixels</dd> 7793<dt>white</dt><dd>the area surrounding the image is white</dd> 7794</dl> 7795 7796<p>The default value is "edge".</p> 7797 7798<p>This most important for distortion operators such as <a href="command-line-options.html#distort" 7799>-distort</a>, <a href="command-line-options.html#implode" >-implode</a>, and <a href="command-line-options.html#fx" >-fx</a>. 7800However it also effects operations that may access pixels just outside the 7801image proper, such as <a href="command-line-options.html#convolve">-convolve</a>, <a 7802href="command-line-options.html#blur">-blur</a>, and <a href="command-line-options.html#sharpen">-sharpen</a>. </p> 7803 7804<p>To print a complete list of virtual pixel types, use the <a 7805href="command-line-options.html#list">-list virtual-pixel</a> option.</p> 7806 7807 7808<div style="margin: auto;"> 7809 <h3 class="magick-header"><a id="visual"></a>-visual <var>type</var></h3> 7810</div> 7811 7812<p class="magick-description">Animate images using this X visual type.", 'animate', 'display'</p> 7813 7814<p>Choose from these visual classes:</p> 7815 7816<pre> 7817StaticGray TrueColor 7818GrayScale DirectColor 7819StaticColor default 7820PseudoColor visual id 7821</pre> 7822 7823<p>The X server must support the visual you choose, otherwise an error occurs. 7824If a visual is not specified, the visual class that can display the most 7825simultaneous colors on the default screen is chosen.</p> 7826 7827 7828<div style="margin: auto;"> 7829 <h3 class="magick-header"><a id="watermark"></a>-watermark <var>brightness</var>x<var>saturation</var></h3> 7830</div> 7831 7832<p class="magick-description">Watermark an image using the given percentages of brightness and saturation.</p> 7833 7834<p>Take a grayscale image (with alpha mask) and modify the destination image's 7835brightness according to watermark image's grayscale value and the 7836<var>brightness</var> percentage. The destinations color saturation 7837attribute is just direct modified by the <var>saturation</var> 7838percentage, which defaults to 100 percent (no color change). </p> 7839 7840 7841<div style="margin: auto;"> 7842 <h3 class="magick-header"><a id="wave"></a>-wave <var>amplitude</var><br />-wave <var>amplitude</var>x<var>wavelength</var></h3> 7843</div> 7844 7845<p class="magick-description">Shear the columns of an image into a sine wave.</p> 7846 7847<div style="margin: auto;"> 7848 <h3 class="magick-header"><a id="wavelet-denoise"></a>-wavelet-denoise <var>threshold</var><br />-wavelet-denoise <var>threshold</var>x<var>softness</var></h3> 7849</div> 7850 7851<p class="magick-description">removes noise from the image using a wavelet transform. The threshold is the value below which everything is considered noise and ranges from 0.0 (none) to QuantumRange or use percent (e.g. 5%). Softness attenuates the threshold and typically ranges from 0.0 (none) to 1.0. The higher the value the more noise that remains in the image.</p> 7852 7853<div style="margin: auto;"> 7854 <h3 class="magick-header"><a id="weight"></a>-weight <var>fontWeight</var></h3> 7855</div> 7856 7857<p class="magick-description">Set a font weight for text.</p> 7858 7859<p>This setting suggests a font weight that ImageMagick should try to apply to 7860the currently selected font family. Use a positive integer for 7861<var>fontWeight</var> or select from the following.</p> 7862 7863<dl class="dl-horizontal"> 7864<dt>Thin </dt> 7865<dd>Same as <var>fontWeight</var> = 100.</dd> 7866<dt>ExtraLight </dt> 7867<dd>Same as <var>fontWeight</var> = 200.</dd> 7868<dt>Light </dt> 7869<dd>Same as <var>fontWeight</var> = 300.</dd> 7870<dt>Normal </dt> 7871<dd>Same as <var>fontWeight</var> = 400.</dd> 7872<dt>Medium </dt> 7873<dd>Same as <var>fontWeight</var> = 500.</dd> 7874<dt>DemiBold </dt> 7875<dd>Same as <var>fontWeight</var> = 600.</dd> 7876<dt>Bold </dt> 7877<dd>Same as <var>fontWeight</var> = 700.</dd> 7878<dt>ExtraBold </dt> 7879<dd>Same as <var>fontWeight</var> = 800.</dd> 7880<dt>Heavy </dt> 7881<dd>Same as <var>fontWeight</var> = 900.</dd> 7882</dl> 7883<br/> 7884 7885<p>To print a complete list of weight types, use <a href="command-line-options.html#list">-list weight</a>.</p> 7886 7887<p>For other settings that affect fonts, see the options <a 7888href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 7889href="command-line-options.html#stretch">-stretch</a>, and <a href="command-line-options.html#style">-style</a>. </p> 7890 7891<div style="margin: auto;"> 7892 <h3 class="magick-header"><a id="white-point"></a>-white-point <var>x,y</var></h3> 7893</div> 7894 7895<p class="magick-description">chromaticity white point.</p> 7896 7897<div style="margin: auto;"> 7898 <h3 class="magick-header"><a id="white-threshold"></a>-white-threshold <var>value</var>{<var>%</var>}</h3> 7899</div> 7900 7901<p class="magick-description">Force to white all pixels above the threshold while leaving all pixels at or below the threshold unchanged.</p> 7902 7903<p> The threshold value can be given as a percentage or as an absolute integer 7904value within [0, <var>QuantumRange</var>] corresponding to the 7905desired <a href="command-line-options.html#channel">‑channel</a> value. See <a href="command-line-options.html#threshold">‑threshold</a>for more details on thresholds and resulting values. </p> 7906 7907<div style="margin: auto;"> 7908 <h3 class="magick-header"><a id="window"></a>-window <var>id</var></h3> 7909</div> 7910 7911<p class="magick-description">Make the image the background of a window.", 'animate', 'display'</p> 7912 7913<p><var>id</var> can be a window id or name. Specify <code>root</code> 7914to select X's root window as the target window.</p> 7915 7916<p>By default the image is tiled onto the background of the target window. If 7917<code>backdrop</code> or <a href="command-line-options.html#geometry">-resize</a> are specified, the 7918image is surrounded by the background color. Refer to <code>X RESOURCES</code> 7919for details.</p> 7920 7921<p>The image will not display on the root window if the image has more unique 7922colors than the target window colormap allows. Use <a 7923href="command-line-options.html#colors">-colors</a> to reduce the number of colors.</p> 7924 7925<div style="margin: auto;"> 7926 <h3 class="magick-header"><a id="window-group"></a>-window-group</h3> 7927</div> 7928 7929<p class="magick-description">specify the window group.</p> 7930 7931<div style="margin: auto;"> 7932 <h3 class="magick-header"><a id="write"></a>-write <var>filename</var></h3> 7933</div> 7934 7935<p class="magick-description">write an image sequence.</p> 7936 7937<p>The image sequence preceding the <a href="command-line-options.html#write">-write</a> <var>filename</var> option is written out, and processing continues with the same image in its current state if there are additional options. To restore the image to its original state after writing it, use the <a href="command-line-options.html#write">+write</a> <var>filename</var> option.</p> 7938 7939<p>Use <a href="command-line-options.html#compress">-compress</a> to specify the type of image compression.</p> 7940</div> 7941</div> 7942 7943 7944 7945 <footer class="magick-footer"> 7946 <p><a href="support.html">Donate</a> • 7947 <a href="sitemap.html">Sitemap</a> • 7948 <a href="links.html">Related</a> • 7949 <a href="architecture.html">Architecture</a> 7950</p> 7951 <p><a href="command-line-options.html#">Back to top</a> • 7952 <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x89AB63D48277377A">Public Key</a> • 7953 <a href="http://nextgen.imagemagick.org/script/contact.php">Contact Us</a></p> 7954 <p><small>© 1999-2016 ImageMagick Studio LLC</small></p> 7955 </footer> 7956</div><!-- /.container --> 7957 7958 <script src="https://localhost/ajax/libs/jquery/1.11.3/jquery.min.js"></script> 7959 <script src="http://nextgen.imagemagick.org/js/magick.html"></script> 7960</div> 7961</body> 7962</html> 7963
