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 Bzier 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="../image/wand.png"/> 26 <link rel="shortcut icon" href="../image/wand.ico"/> 27 <link rel="stylesheet" href="../css/magick.php"/> 28 </head> 29 <body> 30 <div class="main"> 31 <div class="magick-masthead"> 32 <div class="container"> 33 <script async="async" src="http://pagead2.googlesyndication.com/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.php">Home</a> 43 <a class="magick-nav-item " href="binary-releases.php">Download</a> 44 <a class="magick-nav-item " href="command-line-tools.php">Tools</a> 45 <a class="magick-nav-item " href="command-line-processing.php">Command-line</a> 46 <a class="magick-nav-item " href="resources.php">Resources</a> 47 <a class="magick-nav-item " href="api.php">Develop</a> 48 <a class="magick-nav-item " href="search.php">Search</a> 49 <a class="magick-nav-item pull-right" href="http://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.php#adaptive-blur">‑adaptive‑blur</a> <a href="command-line-options.php#adaptive-resize">‑adaptive‑resize</a> <a href="command-line-options.php#adaptive-sharpen">‑adaptive‑sharpen</a> <a href="command-line-options.php#adjoin">‑adjoin</a> <a href="command-line-options.php#affine">‑affine</a> <a href="command-line-options.php#alpha">‑alpha</a> <a href="command-line-options.php#annotate">‑annotate</a> <a href="command-line-options.php#antialias">‑antialias</a> <a href="command-line-options.php#append">‑append</a> <a href="command-line-options.php#attenuate">‑attenuate</a> <a href="command-line-options.php#authenticate">‑authenticate</a> <a href="command-line-options.php#auto-gamma">‑auto‑gamma</a> <a href="command-line-options.php#auto-level">‑auto‑level</a> <a href="command-line-options.php#auto-orient">‑auto‑orient</a> <a href="command-line-options.php#backdrop">‑backdrop</a> <a href="command-line-options.php#background">‑background</a> <a href="command-line-options.php#bench">‑bench</a> <a href="command-line-options.php#bias">‑bias</a> <a href="command-line-options.php#black-point-compensation">‑black‑point‑compensation</a> <a href="command-line-options.php#black-threshold">‑black‑threshold</a> <a href="command-line-options.php#blend">‑blend</a> <a href="command-line-options.php#blue-primary">‑blue‑primary</a> <a href="command-line-options.php#blue-shift">‑blue‑shift</a> <a href="command-line-options.php#blur">‑blur</a> <a href="command-line-options.php#border">‑border</a> <a href="command-line-options.php#bordercolor">‑bordercolor</a> <a href="command-line-options.php#borderwidth">‑borderwidth</a> <a href="command-line-options.php#brightness-contrast">‑brightness‑contrast</a> <a href="command-line-options.php#cache">‑cache</a> <a href="command-line-options.php#canny">‑canny</a> <a href="command-line-options.php#caption">‑caption</a> <a href="command-line-options.php#cdl">‑cdl</a> <a href="command-line-options.php#channel">‑channel</a> <a href="command-line-options.php#charcoal">‑charcoal</a> <a href="command-line-options.php#chop">‑chop</a> <a href="command-line-options.php#clamp">‑clamp</a> <a href="command-line-options.php#clip">‑clip</a> <a href="command-line-options.php#clip-mask">‑clip‑mask</a> <a href="command-line-options.php#clip-path">‑clip‑path</a> <a href="command-line-options.php#clone">‑clone</a> <a href="command-line-options.php#clut">‑clut</a> <a href="command-line-options.php#coalesce">‑coalesce</a> <a href="command-line-options.php#colorize">‑colorize</a> <a href="command-line-options.php#colormap">‑colormap</a> <a href="command-line-options.php#color-matrix">‑color‑matrix</a> <a href="command-line-options.php#colors">‑colors</a> <a href="command-line-options.php#colorspace">‑colorspace</a> <a href="command-line-options.php#combine">‑combine</a> <a href="command-line-options.php#comment">‑comment</a> <a href="command-line-options.php#compare">‑compare</a> <a href="command-line-options.php#complex">‑complex</a> <a href="command-line-options.php#compose">‑compose</a> <a href="command-line-options.php#composite">‑composite</a> <a href="command-line-options.php#compress">‑compress</a> <a href="command-line-options.php#connected-components">‑connected‑components</a> <a href="command-line-options.php#contrast">‑contrast</a> <a href="command-line-options.php#contrast-stretch">‑contrast‑stretch</a> <a href="command-line-options.php#convolve">‑convolve</a> <a href="command-line-options.php#copy">‑copy</a> <a href="command-line-options.php#crop">‑crop</a> <a href="command-line-options.php#cycle">‑cycle</a> <a href="command-line-options.php#debug">‑debug</a> <a href="command-line-options.php#decipher">‑decipher</a> <a href="command-line-options.php#deconstruct">‑deconstruct</a> <a href="command-line-options.php#define">‑define</a> <a href="command-line-options.php#delay">‑delay</a> <a href="command-line-options.php#delete">‑delete</a> <a href="command-line-options.php#density">‑density</a> <a href="command-line-options.php#depth">‑depth</a> <a href="command-line-options.php#descend">‑descend</a> <a href="command-line-options.php#deskew">‑deskew</a> <a href="command-line-options.php#despeckle">‑despeckle</a> <a href="command-line-options.php#direction">‑direction</a> <a href="command-line-options.php#displace">‑displace</a> <a href="command-line-options.php#display">‑display</a> <a href="command-line-options.php#dispose">‑dispose</a> <a href="command-line-options.php#dissimilarity-threshold">‑dissimilarity‑threshold</a> <a href="command-line-options.php#dissolve">‑dissolve</a> <a href="command-line-options.php#distort">‑distort</a> <a href="command-line-options.php#distribute-cache">‑distribute‑cache</a> <a href="command-line-options.php#dither">‑dither</a> <a href="command-line-options.php#draw">‑draw</a> <a href="command-line-options.php#duplicate">‑duplicate</a> <a href="command-line-options.php#edge">‑edge</a> <a href="command-line-options.php#emboss">‑emboss</a> <a href="command-line-options.php#encipher">‑encipher</a> <a href="command-line-options.php#encoding">‑encoding</a> <a href="command-line-options.php#endian">‑endian</a> <a href="command-line-options.php#enhance">‑enhance</a> <a href="command-line-options.php#equalize">‑equalize</a> <a href="command-line-options.php#evaluate">‑evaluate</a> <a href="command-line-options.php#evaluate-sequence">‑evaluate‑sequence</a> <a href="command-line-options.php#extent">‑extent</a> <a href="command-line-options.php#extract">‑extract</a> <a href="command-line-options.php#family">‑family</a> <a href="command-line-options.php#features">‑features</a> <a href="command-line-options.php#fft">‑fft</a> <a href="command-line-options.php#fill">‑fill</a> <a href="command-line-options.php#filter">‑filter</a> <a href="command-line-options.php#flatten">‑flatten</a> <a href="command-line-options.php#flip">‑flip</a> <a href="command-line-options.php#floodfill">‑floodfill</a> <a href="command-line-options.php#flop">‑flop</a> <a href="command-line-options.php#font">‑font</a> <a href="command-line-options.php#foreground">‑foreground</a> <a href="command-line-options.php#format">‑format</a> <a href="command-line-options.php#format_identify_">‑format[identify]</a> <a href="command-line-options.php#frame">‑frame</a> <a href="command-line-options.php#frame_import_">‑frame[import]</a> <a href="command-line-options.php#function">‑function</a> <a href="command-line-options.php#fuzz">‑fuzz</a> <a href="command-line-options.php#fx">‑fx</a> <a href="command-line-options.php#gamma">‑gamma</a> <a href="command-line-options.php#gaussian-blur">‑gaussian‑blur</a> <a href="command-line-options.php#geometry">‑geometry</a> <a href="command-line-options.php#gravity">‑gravity</a> <a href="command-line-options.php#grayscale">‑grayscale</a> <a href="command-line-options.php#green-primary">‑green‑primary</a> <a href="command-line-options.php#hald-clut">‑hald‑clut</a> <a href="command-line-options.php#help">‑help</a> <a href="command-line-options.php#highlight-color">‑highlight‑color</a> <a href="command-line-options.php#hough-lines">‑hough‑lines</a> <a href="command-line-options.php#iconGeometry">‑iconGeometry</a> <a href="command-line-options.php#iconic">‑iconic</a> <a href="command-line-options.php#identify">‑identify</a> <a href="command-line-options.php#ift">‑ift</a> <a href="command-line-options.php#immutable">‑immutable</a> <a href="command-line-options.php#implode">‑implode</a> <a href="command-line-options.php#insert">‑insert</a> <a href="command-line-options.php#intensity">‑intensity</a> <a href="command-line-options.php#intent">‑intent</a> <a href="command-line-options.php#interlace">‑interlace</a> <a href="command-line-options.php#interpolate">‑interpolate</a> <a href="command-line-options.php#interline-spacing">‑interline‑spacing</a> <a href="command-line-options.php#interword-spacing">‑interword‑spacing</a> <a href="command-line-options.php#kerning">‑kerning</a> <a href="command-line-options.php#kuwahara">‑kuwahara</a> <a href="command-line-options.php#label">‑label</a> <a href="command-line-options.php#lat">‑lat</a> <a href="command-line-options.php#layers">‑layers</a> <a href="command-line-options.php#level">‑level</a> <a href="command-line-options.php#level-colors">‑level‑colors</a> <a href="command-line-options.php#limit">‑limit</a> <a href="command-line-options.php#linear-stretch">‑linear‑stretch</a> <a href="command-line-options.php#linewidth">‑linewidth</a> <a href="command-line-options.php#liquid-rescale">‑liquid‑rescale</a> <a href="command-line-options.php#list">‑list</a> <a href="command-line-options.php#log">‑log</a> <a href="command-line-options.php#loop">‑loop</a> <a href="command-line-options.php#lowlight-color">‑lowlight‑color</a> <a href="command-line-options.php#magnify">‑magnify</a> <a href="command-line-options.php#map">‑map</a> <a href="command-line-options.php#map_stream_">‑map[stream]</a> <a href="command-line-options.php#mask">‑mask</a> <a href="command-line-options.php#mattecolor">‑mattecolor</a> <a href="command-line-options.php#median">‑median</a> <a href="command-line-options.php#mean-shift">‑mean‑shift</a> <a href="command-line-options.php#metric">‑metric</a> <a href="command-line-options.php#mode">‑mode</a> <a href="command-line-options.php#modulate">‑modulate</a> <a href="command-line-options.php#moments">‑moments</a> <a href="command-line-options.php#monitor">‑monitor</a> <a href="command-line-options.php#monochrome">‑monochrome</a> <a href="command-line-options.php#morph">‑morph</a> <a href="command-line-options.php#morphology">‑morphology</a> <a href="command-line-options.php#mosaic">‑mosaic</a> <a href="command-line-options.php#motion-blur">‑motion‑blur</a> <a href="command-line-options.php#name">‑name</a> <a href="command-line-options.php#negate">‑negate</a> <a href="command-line-options.php#noise">‑noise</a> <a href="command-line-options.php#normalize">‑normalize</a> <a href="command-line-options.php#opaque">‑opaque</a> <a href="command-line-options.php#ordered-dither">‑ordered‑dither</a> <a href="command-line-options.php#orient">‑orient</a> <a href="command-line-options.php#page">‑page</a> <a href="command-line-options.php#paint">‑paint</a> <a href="command-line-options.php#path">‑path</a> <a href="command-line-options.php#pause_animate_">‑pause[animate]</a> <a href="command-line-options.php#pause_import_">‑pause[import]</a> <a href="command-line-options.php#perceptible">‑perceptible</a> <a href="command-line-options.php#ping">‑ping</a> <a href="command-line-options.php#pointsize">‑pointsize</a> <a href="command-line-options.php#polaroid">‑polaroid</a> <a href="command-line-options.php#poly">‑poly</a> <a href="command-line-options.php#posterize">‑posterize</a> <a href="command-line-options.php#precision">‑precision</a> <a href="command-line-options.php#preview">‑preview</a> <a href="command-line-options.php#print">‑print</a> <a href="command-line-options.php#process">‑process</a> <a href="command-line-options.php#profile">‑profile</a> <a href="command-line-options.php#quality">‑quality</a> <a href="command-line-options.php#quantize">‑quantize</a> <a href="command-line-options.php#quiet">‑quiet</a> <a href="command-line-options.php#radial-blur">‑radial‑blur</a> <a href="command-line-options.php#raise">‑raise</a> <a href="command-line-options.php#random-threshold">‑random‑threshold</a> <a href="command-line-options.php#red-primary">‑red‑primary</a> <a href="command-line-options.php#regard-warnings">‑regard‑warnings</a> <a href="command-line-options.php#region">‑region</a> <a href="command-line-options.php#remap">‑remap</a> <a href="command-line-options.php#remote">‑remote</a> <a href="command-line-options.php#render">‑render</a> <a href="command-line-options.php#repage">‑repage</a> <a href="command-line-options.php#resample">‑resample</a> <a href="command-line-options.php#resize">‑resize</a> <a href="command-line-options.php#respect-parentheses">‑respect‑parentheses</a> <a href="command-line-options.php#reverse">‑reverse</a> <a href="command-line-options.php#roll">‑roll</a> <a href="command-line-options.php#rotate">‑rotate</a> <a href="command-line-options.php#sample">‑sample</a> <a href="command-line-options.php#sampling-factor">‑sampling‑factor</a> <a href="command-line-options.php#scale">‑scale</a> <a href="command-line-options.php#scene">‑scene</a> <a href="command-line-options.php#screen">‑screen</a> <a href="command-line-options.php#seed">‑seed</a> <a href="command-line-options.php#segment">‑segment</a> <a href="command-line-options.php#selective-blur">‑selective‑blur</a> <a href="command-line-options.php#separate">‑separate</a> <a href="command-line-options.php#sepia-tone">‑sepia‑tone</a> <a href="command-line-options.php#set">‑set</a> <a href="command-line-options.php#shade">‑shade</a> <a href="command-line-options.php#shadow">‑shadow</a> <a href="command-line-options.php#shared-memory">‑shared‑memory</a> <a href="command-line-options.php#sharpen">‑sharpen</a> <a href="command-line-options.php#shave">‑shave</a> <a href="command-line-options.php#shear">‑shear</a> <a href="command-line-options.php#sigmoidal-contrast">‑sigmoidal‑contrast</a> <a href="command-line-options.php#silent">‑silent</a> <a href="command-line-options.php#similarity-threshold">‑similarity‑threshold</a> <a href="command-line-options.php#size">‑size</a> <a href="command-line-options.php#sketch">‑sketch</a> <a href="command-line-options.php#smush">‑smush</a> <a href="command-line-options.php#snaps">‑snaps</a> <a href="command-line-options.php#solarize">‑solarize</a> <a href="command-line-options.php#sparse-color">‑sparse‑color</a> <a href="command-line-options.php#splice">‑splice</a> <a href="command-line-options.php#spread">‑spread</a> <a href="command-line-options.php#statistic">‑statistic</a> <a href="command-line-options.php#stegano">‑stegano</a> <a href="command-line-options.php#stereo">‑stereo</a> <a href="command-line-options.php#storage-type">‑storage‑type</a> <a href="command-line-options.php#stretch">‑stretch</a> <a href="command-line-options.php#strip">‑strip</a> <a href="command-line-options.php#stroke">‑stroke</a> <a href="command-line-options.php#strokewidth">‑strokewidth</a> <a href="command-line-options.php#style">‑style</a> <a href="command-line-options.php#subimage-search">‑subimage‑search</a> <a href="command-line-options.php#swap">‑swap</a> <a href="command-line-options.php#swirl">‑swirl</a> <a href="command-line-options.php#synchronize">‑synchronize</a> <a href="command-line-options.php#taint">‑taint</a> <a href="command-line-options.php#text-font">‑text‑font</a> <a href="command-line-options.php#texture">‑texture</a> <a href="command-line-options.php#threshold">‑threshold</a> <a href="command-line-options.php#thumbnail">‑thumbnail</a> <a href="command-line-options.php#tile">‑tile</a> <a href="command-line-options.php#tile-offset">‑tile‑offset</a> <a href="command-line-options.php#tint">‑tint</a> <a href="command-line-options.php#title">‑title</a> <a href="command-line-options.php#transform">‑transform</a> <a href="command-line-options.php#transparent">‑transparent</a> <a href="command-line-options.php#transparent-color">‑transparent‑color</a> <a href="command-line-options.php#transpose">‑transpose</a> <a href="command-line-options.php#transverse">‑transverse</a> <a href="command-line-options.php#treedepth">‑treedepth</a> <a href="command-line-options.php#trim">‑trim</a> <a href="command-line-options.php#type">‑type</a> <a href="command-line-options.php#undercolor">‑undercolor</a> <a href="command-line-options.php#unique-colors">‑unique‑colors</a> <a href="command-line-options.php#units">‑units</a> <a href="command-line-options.php#unsharp">‑unsharp</a> <a href="command-line-options.php#update">‑update</a> <a href="command-line-options.php#verbose">‑verbose</a> <a href="command-line-options.php#version">‑version</a> <a href="command-line-options.php#view">‑view</a> <a href="command-line-options.php#vignette">‑vignette</a> <a href="command-line-options.php#virtual-pixel">‑virtual‑pixel</a> <a href="command-line-options.php#visual">‑visual</a> <a href="command-line-options.php#watermark">‑watermark</a> <a href="command-line-options.php#wave">‑wave</a> <a href="command-line-options.php#weight">‑weight</a> <a href="command-line-options.php#white-point">‑white‑point</a> <a href="command-line-options.php#white-threshold">‑white‑threshold</a> <a href="command-line-options.php#window">‑window</a> <a href="command-line-options.php#window-group">‑window‑group</a> <a href="command-line-options.php#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.php">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.php">convert</a> and <a href="mogrify.php">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 66 defaults 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.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <a href="command-line-options.php#adaptive-resize">-adaptive-resize</a> 75 option defaults to data-dependent triangulation. Use the <a 76 href="command-line-options.php#filter">-filter</a> to choose a different resampling algorithm. 77 Offsets, if present in the geometry string, are ignored, and the <a 78 href="command-line-options.php#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 88 defaults 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 97 an image sequence into the given output file. However, some formats, such as 98 JPEG and PNG, do not support more than one image per file, and in that case 99 ImageMagick is forced to write each image as a separate file. As such, if 100 more than one image needs to be written, the filename given is modified by 101 adding a <a href="command-line-options.php#scene">-scene</a> number before the suffix, in order to 102 make distinct names for each image. </p> 103 104 <p>Use <a href="command-line-options.php#adjoin">+adjoin</a> to force each image to be written to 105 separate 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 109 automagically enable <a href="command-line-options.php#adjoin">+adjoin</a> and are used to specify 110 where the <a href="command-line-options.php#scene">-scene</a> number is placed in the filenames. These 111 strings, such as '<code>%d</code>' or '<code>%03d</code>', are familiar to those 112 who have used the standard <code>printf()</code>' C-library function. As an 113 example, the command</p> 114 115 <pre> 116 convert 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.php#morph">-morph</a>), named: my00morph.jpg, my01morph.jpg, 121 my02morph.jpg, ..., my16morph.jpg. </p> 122 123 <p>In summary, ImageMagick tries to write all images to one file, but will 124 save 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.php#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 141 href="command-line-options.php#draw">-draw</a> or <a href="command-line-options.php#transform">-transform</a> options. </p> 142 143 <p>The matrix entries are entered as comma-separated numeric values either in 144 quotes or without spaces. </p> 145 146 <p>Internally, the transformation matrix has 3x3 elements, but three of them 147 are omitted from the input because they are constant. The new (transformed) 148 coordinates (<var>x'</var>, <var>y'</var>) of a pixel at 149 position (<var>x</var>, <var>y</var>) in the original 150 image are calculated using the following matrix equation.</p> 151 152 <p class="text-center"><img class="img-thumbnail" alt="affine transformation" src="../image/affine.png"/> </p> 153 154 <p> The size of the resulting image is that of the smallest rectangle that 155 contains the transformed source image. The parameters 156 <var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> 157 subsequently shift the image pixels so that those that are moved out of the 158 image area are cut off.</p> 159 160 <p>The transformation matrix complies with the left-handed pixel coordinate 161 system: positive <var>x</var> and <var>y</var> directions 162 are 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, 166 four 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, 170 respectively, is accomplished with the following.</p> 171 172 <p>See <a href="command-line-options.php#transform">-transform</a>, and the <a 173 href="command-line-options.php#distort">-distort</a> method '<code>Affineprojection</code> for more 174 information </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.php#affine" >-affine</a> 196 transformations can be accomplished by instead by a single <a href="command-line-options.php#affine" 197 >-affine</a> operation using the matrix equal to the product of the matrices 198 of the individual transformations.</p> 199 200 <p>An attempt is made to detect near-singular transformation matrices. If the 201 matrix 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 210 channel 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 288 same as "<code><a href="command-line-options.php#alpha" >-alpha</a> Off</code>", the <code> 289 >-matte</code> operation was the same as "<code><a href="command-line-options.php#alpha" >-alpha</a> 290 Set</code>" and not "<code><a href="command-line-options.php#alpha" >-alpha</a> On</code>". </p> 291 292 293 <div style="margin: auto;"> 294 <h3 class="magick-header"><a id="annotate"></a> 295 -annotate <var>degrees</var> <var>text</var><br /> 296 -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> 297 </div> 298 299 <p class="magick-description">Annotate an image with text</p> 300 301 <p>This is a convenience for annotating an image with text. For more precise 302 control over text annotations, use <a href="command-line-options.php#draw">-draw</a>.</p> 303 304 305 <p>The values <var>Xdegrees</var> and <var>Ydegrees</var> 306 control 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.php#gravity" >-gravity</a> setting and defaults to the upper left corner of the image.</p> 307 308 <p>Using <a href="command-line-options.php#annotate">-annotate</a> <var>degrees</var> 309 or <a href="command-line-options.php#annotate">-annotate</a> <var>degrees</var>x<var>degrees</var> produces an unsheared rotation of the text. The 310 direction of the rotation is positive, which means a clockwise rotation if <var>degrees</var> is positive. (This conforms to the usual mathematical 311 convention once it is realized that the positive <var>y</var>direction is 312 conventionally considered to be <var>downward</var> for images.)</p> 313 314 <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 315 equation.</p> 316 317 <p class="text-center"><img class="img-thumbnail" alt="annotate transformation" src="../image/annotate.png"/></p> 318 319 <p>If <var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> are omitted, they default to 0. This makes the 320 bottom-left of the text becomes the upper-left corner of the image, which is 321 probably undesirable. Adding a <a href="command-line-options.php#gravity" >-gravity</a> option in this 322 case leads to nice results.</p> 323 324 <p>Text is any UTF-8 encoded character sequence. If <var>text</var> 325 is of the form '@mytext.txt', the text is read from the file 326 <code>mytext.txt</code>. Text in a file is taken literally; no embedded 327 formatting characters are recognized.</p> 328 329 <div style="margin: auto;"> 330 <h3 class="magick-header"><a id="antialias"></a>-antialias</h3> 331 </div> 332 333 <p class="magick-description">Enable/Disable of the rendering of anti-aliasing pixels when drawing fonts and lines.</p> 334 335 <p>By default, objects (e.g. text, lines, polygons, etc.) are antialiased when 336 drawn. Use <a href="command-line-options.php#antialias">+antialias</a> to disable the addition of 337 antialiasing edge pixels. This will then reduce the number of colors added to 338 an image to just the colors being directly drawn. That is, no mixed colors 339 are added when drawing such objects. </p> 340 341 <div style="margin: auto;"> 342 <h3 class="magick-header"><a id="append"></a>-append</h3> 343 </div> 344 345 <p class="magick-description">Join current images vertically or horizontally.</p> 346 347 <p>This option creates a single longer image, by joining all the current 348 images in sequence top-to-bottom. Use <a href="command-line-options.php#append">+append</a> to 349 stack images left-to-right. </p> 350 351 <p>If they are not of the same width, narrower images are padded with the 352 current <a href="command-line-options.php#background">-background</a> color setting, and their 353 position relative to each other can be controlled by the current <a 354 href="command-line-options.php#gravity">-gravity</a> setting. </p> 355 356 357 <div style="margin: auto;"> 358 <h3 class="magick-header"><a id="attenuate"></a>-attenuate <var>value</var></h3> 359 </div> 360 361 <p class="magick-description">Lessen (or intensify) when adding noise to an image.</p> 362 363 <p>If unset the value is equivalent to 1.0, or a maximum noise addition</p> 364 365 <div style="margin: auto;"> 366 <h3 class="magick-header"><a id="authenticate"></a>-authenticate <var>password</var></h3> 367 </div> 368 369 <p class="magick-description">Decrypt a PDF with a password.</p> 370 371 <p>Use this option to supply a <var>password</var> for decrypting 372 a PDF that has been encrypted using Microsoft Crypto API (MSC API). The 373 encrypting using the MSC API is not supported.</p> 374 375 <p>For a different encryption method, see <a href="command-line-options.php#encipher">-encipher</a> 376 and <a href="command-line-options.php#decipher">-decipher</a>. </p> 377 378 379 <div style="margin: auto;"> 380 <h3 class="magick-header"><a id="auto-gamma"></a>-auto-gamma</h3> 381 </div> 382 383 <p class="magick-description">Automagically adjust gamma level of image.</p> 384 385 <p>This calculates the mean values of an image, then applies a calculated <a 386 href="command-line-options.php#gamma" >-gamma</a> adjustment so that is the mean color exists in the 387 image it will get a have a value of 50%. </p> 388 389 <p>This means that any solid 'gray' image becomes 50% gray. </p> 390 391 <p>This works well for real-life images with little or no extreme dark and 392 light areas, but tend to fail for images with large amounts of bright sky or 393 dark shadows. It also does not work well for diagrams or cartoon like images. 394 </p> 395 396 <p>It uses the <a href="command-line-options.php#channel" >-channel</a> setting, (including the 397 '<var>sync</var>' flag for channel synchronization), to determine which color 398 values is used and modified. As the default <a href="command-line-options.php#channel" 399 >-channel</a> setting is '<var>RGB,sync</var>', channels are modified 400 together by the same gamma value, preserving colors. </p> 401 402 403 404 <div style="margin: auto;"> 405 <h3 class="magick-header"><a id="auto-level"></a>-auto-level</h3> 406 </div> 407 408 <p class="magick-description">Automagically adjust color levels of image.</p> 409 410 <p>This is a 'perfect' image normalization operator. It finds the exact 411 minimum and maximum color values in the image and then applies a <a 412 href="command-line-options.php#level" >-level</a> operator to stretch the values to the full range of 413 values. </p> 414 415 <p>The operator is not typically used for real-life images, image scans, or 416 JPEG format images, as a single 'out-rider' pixel can set a bad min/max values 417 for the <a href="command-line-options.php#level" >-level</a> operation. On the other hand it is the 418 right operator to use for color stretching gradient images being used to 419 generate Color lookup tables, distortion maps, or other 'mathematically' 420 defined images. </p> 421 422 <p>The operator is very similar to the <a href="command-line-options.php#normalize">-normalize</a>, <a 423 href="command-line-options.php#contrast-stretch" >-contrast-stretch</a>, and <a href="command-line-options.php#linear-stretch" 424 >-linear-stretch</a> operators, but without 'histogram binning' or 'clipping' 425 problems that these operators may have. That is <a href="command-line-options.php#auto-level" 426 >-auto-level</a> is the perfect or ideal version these operators. </p> 427 428 <p>It uses the <a href="command-line-options.php#channel" >-channel</a> setting, (including the 429 special '<var>sync</var>' flag for channel synchronization), to determine 430 which color values are used and modified. As the default <a 431 href="command-line-options.php#channel" >+channel</a> setting is '<var>RGB,sync</var>', the 432 '<var>sync</var>' ensures that the color channels will are modified 433 together by the same gamma value, preserving colors, and ignoring 434 transparency. </p> 435 436 437 <div style="margin: auto;"> 438 <h3 class="magick-header"><a id="auto-orient"></a>-auto-orient</h3> 439 </div> 440 441 <p class="magick-description">adjusts an image so that its orientation is suitable for viewing (i.e. top-left orientation).</p> 442 443 <p>This operator reads and resets the EXIF image profile setting 'Orientation' 444 and then performs the appropriate 90 degree rotation on the image to orient 445 the image, for correct viewing. </p> 446 447 <p>This EXIF profile setting is usually set using a gravity sensor in digital 448 camera, however photos taken directly downward or upward may not have an 449 appropriate value. Also images that have been orientation 'corrected' without 450 reseting this setting, may be 'corrected' again resulting in a incorrect 451 result. If the EXIF profile was previously stripped, the <a 452 href="command-line-options.php#auto-orient" >-auto-orient</a> operator will do nothing. </p> 453 454 455 <div style="margin: auto;"> 456 <h3 class="magick-header"><a id="average"></a>-average</h3> 457 </div> 458 459 <p class="magick-description">Average a set of images.</p> 460 461 <p>An error results if the images are not identically sized.</p> 462 463 464 <div style="margin: auto;"> 465 <h3 class="magick-header"><a id="backdrop"></a>-backdrop</h3> 466 </div> 467 468 <p class="magick-description">Display the image centered on a backdrop.</p> 469 470 <p>This backdrop covers the entire workstation screen and is useful for hiding 471 other X window activity while viewing the image. The color of the backdrop is 472 specified as the background color. The color is specified using the format 473 described under the <a href="command-line-options.php#fill">-fill</a> option.</p> 474 475 <div style="margin: auto;"> 476 <h3 class="magick-header"><a id="background"></a>-background <var>color</var></h3> 477 </div> 478 479 <p class="magick-description">Set the background color.</p> 480 481 <p>The color is specified using the format described under the <a 482 href="command-line-options.php#fill">-fill</a> option. The default background color (if none is 483 specified or found in the image) is white.</p> 484 485 <div style="margin: auto;"> 486 <h3 class="magick-header"><a id="bench"></a>-bench <var>iterations</var></h3> 487 </div> 488 489 <p class="magick-description">Measure performance.</p> 490 491 <p>Repeat the entire command for the given number of <var>iterations</var> and report the user-time and elapsed time. For instance, 492 consider the following command and its output. Modify the benchmark with the 493 -duration to run the benchmark for a fixed number of seconds and -concurrent 494 to run the benchmark in parallel (requires the OpenMP feature).</p> 495 496 <pre> 497 -> convert logo: -resize 1000% -bench 5 logo.png 498 Performance[4]: 5i 0.875657ips 6.880u 0:05.710 499 </pre> 500 501 <p>In this example, 5 iterations were completed at 0.875657 iterations per 502 second, using 4 threads and 6.88 seconds of the user's allotted time, for 503 a total elapsed time of 5.71 seconds.</p> 504 505 <div style="margin: auto;"> 506 <h3 class="magick-header"><a id="bias"></a>-bias <var>value</var>{<var>%</var>}</h3> 507 </div> 508 509 <p class="magick-description">Add bias when convolving an image.</p> 510 511 <p>This option shifts the output of <a href="command-line-options.php#convolve">‑convolve</a> so that 512 positive and negative results are relative to the specified bias value. </p> 513 514 <p>This is important for non-HDRI compilations of ImageMagick when dealing 515 with convolutions that contain negative as well as positive values. This is 516 especially the case with convolutions involving high pass filters or edge 517 detection. Without an output bias, the negative values are clipped at 518 zero.</p> 519 520 <p>When using an ImageMagick with the HDRI compile-time setting, <a href="command-line-options.php#bias">‑bias</a> is not needed, as ImageMagick is able to store/handle any 521 negative results without clipping to the color value range 522 (0..QuantumRange).</p> 523 524 <p>See the discussion on HDRI implementations of ImageMagick on the page <a 525 href="high-dynamic-range.php" >High Dynamic-Range Images</a>. For more 526 about HDRI go the ImageMagick <a 527 href="http://www.imagemagick.org/Usage/basics/#hdri" >Usage</a> pages or this 528 <a 529 href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> 530 entry. </p> 531 532 <div style="margin: auto;"> 533 <h3 class="magick-header"><a id="black-point-compensation"></a>-black-point-compensation</h3> 534 </div> 535 536 <p class="magick-description">Use black point compensation.</p> 537 538 <div style="margin: auto;"> 539 <h3 class="magick-header"><a id="black-threshold"></a>-black-threshold <var>value</var>{<var>%</var>}</h3> 540 </div> 541 542 <p class="magick-description">Force to black all pixels below the threshold while leaving all pixels at or above the threshold unchanged.</p> 543 544 <p> The threshold value can be given as a percentage or as an absolute integer 545 value within [0, <var>QuantumRange</var>] corresponding to the 546 desired <a href="command-line-options.php#channel">‑channel</a> value. See <a href="command-line-options.php#threshold">‑threshold</a>for more details on thresholds and resulting values. </p> 547 548 549 <div style="margin: auto;"> 550 <h3 class="magick-header"><a id="blend"></a>-blend <var>geometry</var></h3> 551 </div> 552 553 <p class="magick-description">blend an image into another by the given absolute value or percent.</p> 554 555 <p>Blend will average the images together ('plus') according to the 556 percentages given and each pixels transparency. If only a single percentage 557 value is given it sets the weight of the composite or 'source' image, while 558 the background image is weighted by the exact opposite amount. That is a 559 <code>-blend 30%</code> merges 30% of the 'source' image with 70% of the 560 'destination' image. Thus it is equivalent to <code>-blend 30x70%</code>.</p> 561 562 563 <div style="margin: auto;"> 564 <h3 class="magick-header"><a id="blue-primary"></a>-blue-primary <var>x</var>,<var>y</var></h3> 565 </div> 566 567 <p class="magick-description">Set the blue chromaticity primary point.</p> 568 569 <div style="margin: auto;"> 570 <h3 class="magick-header"><a id="blue-shift"></a>-blue-shift <var>factor</var></h3> 571 </div> 572 573 <p class="magick-description">simulate a scene at nighttime in the moonlight. Start with a factor of 1.5</p> 574 575 <div style="margin: auto;"> 576 577 <div style="margin: auto;"> 578 <h3 class="magick-header"><a id="blur"></a>-blur <var>radius</var><br />-blur <var>radius</var>x<var>sigma</var></h3> 579 </div> 580 581 <p class="magick-description">Reduce image noise and reduce detail levels.</p> 582 583 <p>Convolve the image with a Gaussian or normal distribution using the given 584 <var >Sigma</var> value. The formula is:</p> 585 586 <p class="text-center"><img class="img-thumbnail" alt="gaussian distribution" width="243px" height="42px" src="../image/gaussian-blur.png"/></p> 587 588 <p>The <var >Sigma</var> value is the important argument, and 589 determines the actual amount of blurring that will take place. </p> 590 591 <p>The <var >Radius</var> is only used to determine the size of the 592 array which will hold the calculated Gaussian distribution. It should be an 593 integer. If not given, or set to zero, IM will calculate the largest possible 594 radius that will provide meaningful results for the Gaussian distribution. 595 </p> 596 597 <p>The larger the <var >Radius</var> the slower the 598 operation is. However too small a <var >Radius</var>, and sever 599 aliasing effects may result. As a guideline, <var >Radius</var> 600 should be at least twice the <var >Sigma</var> value, though three 601 times will produce a more accurate result. </p> 602 603 <p>This option differs from <a href="command-line-options.php#gaussian-blur">-gaussian-blur</a> simply 604 by taking advantage of the separability properties of the distribution. Here 605 we apply a single-dimensional Gaussian matrix in the horizontal direction, 606 then repeat the process in the vertical direction.</p> 607 608 <p>The <a href="command-line-options.php#virtual-pixel">-virtual-pixel</a> setting will determine how 609 pixels which are outside the image proper are blurred into the final result. 610 </p> 611 612 613 <div style="margin: auto;"> 614 <h3 class="magick-header">-blur <var>Width</var>[x<var>Height</var>[+<var>Angle</var>]]</h3> 615 </div> 616 617 <p class="magick-description">Variably blur an image according to the overlay mapping.</p> 618 619 <p>Each pixel in the overlaid region is replaced with an Elliptical Weighted 620 Average (EWA) of the source image, scaled according to the grayscale 621 mapping. </p> 622 623 <p>The ellipse is weighted with sigma set to the given <var>Width</var> and <var >Height</var>. The <var >Height</var> 624 defaults to the <var >Width</var> for a normal circular Gaussian 625 weighting. The <var >Angle</var> will rotate the ellipse from 626 horizontal clock-wise. </p> 627 628 <p>The <a href="command-line-options.php#virtual-pixel">-virtual-pixel</a> setting will determine how 629 pixels which are outside the image proper are blurred into the final result. 630 </p> 631 632 633 <div style="margin: auto;"> 634 <h3 class="magick-header"><a id="border"></a>-border <var>geometry</var></h3> 635 </div> 636 637 <p class="magick-description">Surround the image with a border of color. </p> 638 639 <p>Set the width and height using the <var>size</var> portion of the 640 <var>geometry</var> argument. See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets are 641 ignored. </p> 642 643 <p>As of IM 6.7.8-8, the <var>geometry</var> arguments behave as follows:</p> 644 645 <dl class="dl-horizontal"> 646 <dt><var>value</var></dt> 647 <dd>value is added to both left/right and top/bottom</dd> 648 <dt><var>value-x</var><kbd>x</kbd></dt> 649 <dd>value-x is added only to left/right and top/bottom are unchanged</dd> 650 <dt><kbd>x</kbd><var>value-y</var></dt> 651 <dd>value-y is added only to top/bottom and left/right are unchanged</dd> 652 <dt><var>value-x</var><kbd>x</kbd><var>value-y</var></dt> 653 <dd>value-x is added to left/right and value-y added to top/bottom</dd> 654 <dt><var>value-x</var><kbd>x</kbd>0</dt> 655 <dd>value-x is added only to left/right and top/bottom are unchanged</dd> 656 <dt>0<kbd>x</kbd><var>value-y</var></dt> 657 <dd>value-y is added only to top/bottom and left/right are unchanged</dd> 658 <dt><var>value</var>%</dt> 659 <dd>value % of width is added to left/right and value % of height is added to top/bottom</dd> 660 <dt><var>value-x</var><kbd>x</kbd>%</dt> 661 <dd>value-x % of width is added to left/right and to top/bottom</dd> 662 <dt>x<var>value-y</var>%</dt> 663 <dd>value-y % of height is added to top/bottom and to left/right</dd> 664 <dt><var>value-x</var>%<kbd>x</kbd><var>value-y</var>%</dt> 665 <dd>value-x % of width is added to left/right and value-y % of height is added to top/bottom</dd> 666 <dt><var>value-x</var>%<kbd>x</kbd>0%</dt> 667 <dd>value-x % of width is added to left/right and top/bottom are unchanged</dd> 668 <dt>0%<kbd>x</kbd><var>value-y</var>%</dt> 669 <dd>value-y % of height is added to top/bottom and left/right are unchanged</dd> 670 </dl> 671 672 <p>Set the border color by preceding with the <a 673 href="command-line-options.php#bordercolor">-bordercolor</a> setting.</p> 674 675 <p>The <a href="command-line-options.php#border">-border</a> operation is affected by the current <a 676 href="command-line-options.php#compose">-compose</a> setting and assumes that this is using the default 677 '<code>Over</code>' composition method. It generates an image of the appropriate 678 size colors by the current <a href="command-line-options.php#bordercolor">-bordercolor</a> before 679 overlaying the original image in the center of this net image. This means that 680 with the default compose method of '<code>Over</code>' any transparent parts may 681 be replaced by the current <a href="command-line-options.php#bordercolor">-bordercolor</a> setting.</p> 682 <p>See also the <a href="command-line-options.php#frame">-frame</a> option, which has more 683 functionality.</p> 684 685 <div style="margin: auto;"> 686 <h3 class="magick-header"><a id="bordercolor"></a>-bordercolor <var>color</var></h3> 687 </div> 688 689 <p class="magick-description">Set the border color.</p> 690 691 <p>The color is specified using the format described under the <a href="command-line-options.php#fill">-fill</a> option.</p> 692 693 <p>The default border color is <code>#DFDFDF</code>, <span style="background-color: #dfdfdf;">this shade of gray</span>.</p> 694 695 <div style="margin: auto;"> 696 <h3 class="magick-header"><a id="borderwidth"></a>-borderwidth <var>geometry</var> </h3> 697 </div> 698 699 <p class="magick-description">Set the border width.</p> 700 701 <div style="margin: auto;"> 702 <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> 703 </div> 704 705 <p class="magick-description">Adjust the brightness and/or contrast of the image.</p> 706 707 <p>Brightness and Contrast values apply changes to the input image. They are 708 not absolute settings. A brightness or contrast value of zero means no change. 709 The range of values is -100 to +100 on each. Positive values increase the 710 brightness or contrast and negative values decrease the brightness or contrast. 711 To control only contrast, set the brightness=0. To control only brightness, 712 set contrast=0 or just leave it off.</p> 713 714 <p>You may also use <a href="command-line-options.php#fill">-channel</a> to control which channels to 715 apply the brightness and/or contrast change. The default is to apply the same 716 transformation to all channels.</p> 717 718 <p>Brightness and Contrast arguments are converted to offset and slope of a 719 linear transform and applied 720 using <a href="command-line-options.php#fill">-function polynomial "slope,offset"</a>.</p> 721 722 <p>The slope varies from 0 at contrast=-100 to almost vertical at 723 contrast=+100. For brightness=0 and contrast=-100, the result are totally 724 midgray. For brightness=0 and contrast=+100, the result will approach but 725 not quite reach a threshold at midgray; that is the linear transformation 726 is a very steep vertical line at mid gray.</p> 727 728 <p>Negative slopes, i.e. negating the image, are not possible with this 729 function. All achievable slopes are zero or positive.</p> 730 731 <p>The offset varies from -0.5 at brightness=-100 to 0 at brightness=0 to +0.5 732 at brightness=+100. Thus, when contrast=0 and brightness=100, the result is 733 totally white. Similarly, when contrast=0 and brightness=-100, the result is 734 totally black.</p> 735 736 <p>As the range of values for the arguments are -100 to +100, adding the '%' 737 symbol is no different than leaving it off.</p> 738 739 <div style="margin: auto;"> 740 <h3 class="magick-header"><a id="cache"></a>-cache <var>threshold</var></h3> 741 </div> 742 743 <p class="magick-description">(This option has been replaced by the <a href='command-line-options.php#limit'>-limit</a> option).</p> 744 745 <div style="margin: auto;"> 746 <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> 747 </div> 748 749 <p class="magick-description">Canny edge detector uses a multi-stage algorithm to detect a wide range of edges in the image.</p> 750 751 <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> 752 753 <div style="margin: auto;"> 754 <h3 class="magick-header"><a id="caption"></a>-caption <var>string</var></h3> 755 </div> 756 757 <p class="magick-description">Assign a caption to an image.</p> 758 759 <p>This option sets the caption meta-data of an image read in after this 760 option has been given. To modify a caption of images already in memory use 761 "<code><a href="command-line-options.php#set">-set</a> caption</code>". </p> 762 763 <p>The caption can contain special format characters listed in the <a 764 href="escape.php">Format and 765 Print Image Properties</a>. These attributes are expanded when the caption 766 is finally assigned to the individual images. </p> 767 768 <p>If the first character of <var>string</var> is <var>@</var>, the image caption is read from a file titled by the 769 remaining characters in the string. Comments read in from a file are literal; 770 no embedded formatting characters are recognized.</p> 771 772 <p>Caption meta-data is not visible on the image itself. To do that use the 773 <a href="command-line-options.php#annotate">-annotate</a> or <a href="command-line-options.php#draw">-draw</a> options 774 instead.</p> 775 776 <p>For example,</p> 777 778 <pre> 779 -caption "%m:%f %wx%h" bird.miff 780 </pre> 781 782 <p>produces an image caption of <code>MIFF:bird.miff 512x480</code> (assuming 783 that the image <code>bird.miff</code> has a width of 512 and a height of 784 480.</p> 785 786 787 <div style="margin: auto;"> 788 <h3 class="magick-header"><a id="cdl"></a>-cdl <var>filename</var></h3> 789 </div> 790 791 <p class="magick-description">color correct with a color decision list.</p> 792 793 <p>Here is an example color correction collection:</p> 794 795 <pre> 796 <?xml version="1.0" encoding="UTF-8"?> 797 <ColorCorrectionCollection xmlns="urn:ASC:CDL:v1.2"> 798 <ColorCorrection id="cc06668"> 799 <SOPNode> 800 <Slope> 0.9 1.2 0.5 </Slope> 801 <Offset> 0.4 -0.5 0.6 </Offset> 802 <Power> 1.0 0.8 1.5 </Power> 803 </SOPNode> 804 <SATNode> 805 <Saturation> 0.85 </Saturation> 806 </SATNode> 807 </ColorCorrection> 808 </ColorCorrectionCollection> 809 </pre> 810 811 <div style="margin: auto;"> 812 <h3 class="magick-header"><a id="channel"></a>-channel <var>type</var></h3> 813 </div> 814 815 <p class="magick-description">Specify those image color channels to which subsequent operators are limited.</p> 816 817 <p>Choose from: <code>Red</code>, <code>Green</code>, <code>Blue</code>, 818 <code>Alpha</code>, <code>Gray</code>, <code>Cyan</code>, <code>Magenta</code>, 819 <code>Yellow</code>, <code>Black</code>, <code>Opacity</code>, 820 <code>Index</code>, <code>RGB</code>, <code>RGBA</code>, <code>CMYK</code>, or 821 <code>CMYKA</code>.</p> 822 823 <p>The channels above can also be specified as a comma-separated list or can be 824 abbreviated as a concatenation of the letters '<code>R</code>', '<code>G</code>', 825 '<code>B</code>', '<code>A</code>', '<code>O</code>', '<code>C</code>', 826 '<code>M</code>', '<code>Y</code>', '<code>K</code>'. 827 828 For example, to only select the <code>Red</code> and <code>Blue</code> channels 829 you can either use </p> 830 <pre> 831 -channel Red,Blue 832 </pre> 833 <p>or you can use the short hand form</p> 834 <pre> 835 -channel RB 836 </pre> 837 838 <p>All the channels that are present in an image can be specified using the 839 special channel type <code>All</code>. Not all operators are 'channel capable', 840 but generally any operators that are generally 'grey-scale' image operators, 841 will understand this setting. See individual operator documentation. </p> 842 843 <br/> 844 845 <p>On top of the normal channel selection an extra flag can be specified, 846 '<code>Sync</code>'. This is turned on by default and if set means that 847 operators that understand this flag should perform: cross-channel 848 synchronization of the channels. If not specified, then most grey-scale 849 operators will apply their image processing operations to each individual 850 channel (as specified by the rest of the <a href="command-line-options.php#channel">-channel</a> 851 setting) completely independently from each other. </p> 852 853 <p>For example for operators such as <a href="command-line-options.php#auto-level">-auto-level</a> and 854 <a href="command-line-options.php#auto-gamma">-auto-gamma</a> the color channels are modified 855 together in exactly the same way so that colors will remain in-sync. Without 856 it being set, then each channel is modified separately and 857 independently, which may produce color distortion. </p> 858 859 <p>The <a href="command-line-options.php#morphology">-morphology</a> '<code>Convolve</code>' method 860 and the <a href="command-line-options.php#compose">-compose</a> mathematical methods, also understands 861 the '<code>Sync</code>' flag to modify the behavior of pixel colors according 862 to the alpha channel (if present). That is to say it will modify the image 863 processing with the understanding that fully-transparent colors should not 864 contribute to the final result. </p> 865 866 <p>Basically, by default, operators work with color channels in synchronous, and 867 treats transparency as special, unless the <a href="command-line-options.php#channel">-channel</a> 868 setting is modified so as to remove the effect of the '<code>Sync</code>' flag. 869 How each operator does this depends on that operators current implementation. 870 Not all operators understands this flag at this time, but that is changing. 871 </p> 872 873 <p>To print a complete list of channel types, use <a href="command-line-options.php#list">-list 874 channel</a>.</p> 875 876 <p>By default, ImageMagick sets <a href="command-line-options.php#channel">-channel</a> to the value 877 '<code>RGBK,sync</code>', which specifies that operators act on all color 878 channels except the transparency channel, and that all the color channels are 879 to be modified in exactly the same way, with an understanding of transparency 880 (depending on the operation being applied). The 'plus' form <a 881 href="command-line-options.php#channel" >+channel</a> will reset the value back to this default. </p> 882 883 <p>Options that are affected by the <a href="command-line-options.php#channel" >-channel</a> setting 884 include the following. 885 886 <a href="command-line-options.php#auto-gamma">-auto-gamma</a>, 887 <a href="command-line-options.php#auto-level">-auto-level</a>, 888 <a href="command-line-options.php#black-threshold">-black-threshold</a>, 889 <a href="command-line-options.php#blur">-blur</a>, 890 <a href="command-line-options.php#clamp">-clamp</a>, 891 <a href="command-line-options.php#clut">-clut</a>, 892 <a href="command-line-options.php#combine">-combine</a>, 893 <a href="command-line-options.php#composite">-composite</a> (Mathematical compose methods only), 894 <a href="command-line-options.php#convolve">-convolve</a>, 895 <a href="command-line-options.php#contrast-stretch">-contrast-stretch</a>, 896 <a href="command-line-options.php#evaluate">-evaluate</a>, 897 <a href="command-line-options.php#function">-function</a>, 898 <a href="command-line-options.php#fx">-fx</a>, 899 <a href="command-line-options.php#gaussian-blur">-gaussian-blur</a>, 900 <a href="command-line-options.php#hald-clut">-hald-clut</a>, 901 <a href="command-line-options.php#motion-blur">-motion-blur</a>, 902 <a href="command-line-options.php#morphology">-morphology</a>, 903 <a href="command-line-options.php#negate">-negate</a>, 904 <a href="command-line-options.php#normalize">-normalize</a>, 905 <a href="command-line-options.php#ordered-dither">-ordered-dither</a>, 906 <a href="command-line-options.php#radial-blur">-radial-blur</a>, 907 <a href="command-line-options.php#random-threshold">-random-threshold</a>, 908 <a href="command-line-options.php#separate">-separate</a>, 909 <a href="command-line-options.php#threshold">-threshold</a>, and 910 <a href="command-line-options.php#white-threshold">-white-threshold</a>. 911 </p> 912 913 <p>Warning, some operators behave differently when the <a href="command-line-options.php#channel" 914 >+channel</a> default setting is in effect, verses ANY user defined <a 915 href="command-line-options.php#channel" >-channel</a> setting (including the equivalent of the 916 default). These operators have yet to be made to understand the newer 'Sync' 917 flag. </p> 918 919 <p>For example <a href="command-line-options.php#threshold">-threshold</a> will by default grayscale 920 the image before thresholding, if no <a href="command-line-options.php#channel" >-channel</a> setting 921 has been defined. This is not 'Sync flag controlled, yet. </p> 922 923 <p>Also some operators such as <a href="command-line-options.php#blur">-blur</a>, <a 924 href="command-line-options.php#gaussian-blur">-gaussian-blur</a>, will modify their handling of the 925 color channels if the '<code>alpha</code>' channel is also enabled by <a 926 href="command-line-options.php#channel" >-channel</a>. Generally this done to ensure that 927 fully-transparent colors are treated as being fully-transparent, and thus any 928 underlying 'hidden' color has no effect on the final results. Typically 929 resulting in 'halo' effects. The newer <a href="command-line-options.php#morphology">-morphology</a> 930 convolution equivalents however does have a understanding of the 'Sync' flag 931 and will thus handle transparency correctly by default. </p> 932 933 <p>As a alpha channel is optional within images, some operators will read the 934 color channels of an image as a greyscale alpha mask, when the image has no 935 alpha channel present, and the <a href="command-line-options.php#channel" >-channel</a> setting tells 936 the operator to apply the operation using alpha channels. The <a 937 href="command-line-options.php#clut">-clut</a> operator is a good example of this. </p> 938 939 940 941 <div style="margin: auto;"> 942 <h3 class="magick-header"><a id="charcoal"></a>-charcoal <var>factor</var></h3> 943 </div> 944 945 <p class="magick-description">Simulate a charcoal drawing.</p> 946 947 <div style="margin: auto;"> 948 <h3 class="magick-header"><a id="chop"></a>-chop <var>geometry</var></h3> 949 </div> 950 951 <p class="magick-description">Remove pixels from the interior of an image.</p> 952 953 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <var>width</var> 954 and <var>height</var> given in the of the <var>size</var> 955 portion of the <var>geometry</var> argument give the number of 956 columns and rows to remove. The <var>offset</var> portion of 957 the <var>geometry</var> argument is influenced by 958 a <a href="command-line-options.php#gravity">-gravity</a> setting, if present.</p> 959 960 <p>The <a href="command-line-options.php#chop">-chop</a> option removes entire rows and columns, 961 and moves the remaining corner blocks leftward and upward to close the gaps.</p> 962 963 <p>While it can remove internal rows and columns of pixels, it is more 964 typically used with as <a href="command-line-options.php#gravity">-gravity</a> setting and zero 965 offsets so as to remove a single edge from an image. Compare this to <a 966 href="command-line-options.php#shave" >-shave</a> which removes equal numbers of pixels from opposite 967 sides of the image. </p> 968 969 <p>Using <a href="command-line-options.php#chop">-chop</a> effectively undoes the results of a <a 970 href="command-line-options.php#splice">-splice</a> that was given the same <var>geometry</var> and <a href="command-line-options.php#gravity">-gravity</a> settings. </p> 971 972 <div style="margin: auto;"> 973 <h3 class="magick-header"><a id="clamp"></a>-clamp</h3> 974 </div> 975 976 <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> 977 978 <div style="margin: auto;"> 979 <h3 class="magick-header"><a id="clip"></a>-clip</h3> 980 </div> 981 982 <p class="magick-description">Apply the clipping path if one is present.</p> 983 984 <p>If a clipping path is present, it is applied to subsequent operations.</p> 985 986 <p>For example, in the command</p> 987 988 <pre> 989 convert cockatoo.tif -clip -negate negated.tif 990 </pre> 991 992 <p>only the pixels within the clipping path are negated.</p> 993 994 <p>The <a href="command-line-options.php#clip">-clip</a> feature requires SVG support. If the SVG 995 delegate library is not present, the option is ignored.</p> 996 997 <p>Use <a href="command-line-options.php#clip">+clip</a> to disable clipping for subsequent operations.</p> 998 999 <div style="margin: auto;"> 1000 <h3 class="magick-header"><a id="clip-mask"></a>-clip-mask</h3> 1001 </div> 1002 1003 <p class="magick-description">Clip the image as defined by this mask.</p> 1004 1005 <p>Use the alpha channel of the current image as a mask. Any areas that is 1006 white is not modified by any of the 'image processing operators' that follow, 1007 until the mask is removed. Pixels in the black areas of the clip mask are 1008 modified per the requirements of the operator. </p> 1009 1010 <p>In some ways this is similar to (though not the same) as defining 1011 a rectangular <a href="command-line-options.php#region" >-region</a>, or using the negative of the 1012 mask (third) image in a three image <a href="command-line-options.php#composite" >-composite</a>, 1013 operation. </p> 1014 1015 <p>Use <a href="command-line-options.php#clip-mask">+clip-mask</a> to disable clipping for subsequent operations.</p> 1016 1017 <div style="margin: auto;"> 1018 <h3 class="magick-header"><a id="clip-path"></a>-clip-path <var>id</var></h3> 1019 </div> 1020 1021 <p class="magick-description">Clip along a named path from the 8BIM profile.</p> 1022 1023 <p>This is identical to <a href="command-line-options.php#clip">-clip</a> except choose a specific clip path in the event the image has more than one path available. </p> 1024 1025 <p>Use <a href="command-line-options.php#clip-path">+clip-path</a> to disable clipping for subsequent operations.</p> 1026 1027 <div style="margin: auto;"> 1028 <h3 class="magick-header"><a id="clone"></a>-clone <var>index(s)</var></h3> 1029 </div> 1030 1031 <p class="magick-description">make a clone of an image (or images).</p> 1032 1033 <p>Inside parenthesis (where the operator is normally used) it will make a 1034 clone of the images from the last 'pushed' image sequence, and adds them to 1035 the end of the current image sequence. Outside parenthesis 1036 (not recommended) it clones the images from the current image sequence. </p> 1037 1038 <p>Specify the image by its index in the sequence. The first image is index 1039 0. Negative indexes are relative to the end of the sequence; for 1040 example, <code>1</code> 1041 represents the last image of the sequence. Specify a range of images with a 1042 dash (e.g. <code>04</code>). Separate multiple indexes with commas but no 1043 spaces (e.g. <code>0,2,5</code>). A value of '<code>01</code> will 1044 effectively clone all the images. </p> 1045 1046 <p>The <a href="command-line-options.php#clone">+clone</a> will simply make a copy of the last image 1047 in the image sequence, and is thus equivalent to using a argument of 1048 '<code>1</code>'. </p> 1049 1050 <div style="margin: auto;"> 1051 <h3 class="magick-header"><a id="clut"></a>-clut</h3> 1052 </div> 1053 1054 <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> 1055 1056 <p>The second (LUT) image is ordinarily a gradient image containing the 1057 histogram mapping of how each channel should be modified. Typically it is a 1058 either a single row or column image of replacement color values. If larger 1059 than a single row or column, values are taken from a diagonal line from 1060 top-left to bottom-right corners.</p> 1061 1062 <p>The lookup is further controlled by the <a 1063 href="command-line-options.php#interpolate">-interpolate</a> setting, which is especially handy for an 1064 LUT which is not the full length needed by the ImageMagick installed Quality 1065 (Q) level. Good settings for this are the '<code>bilinear</code>' and 1066 '<code>bicubic</code>' interpolation settings, which give smooth color 1067 gradients, and the '<code>integer</code>' setting for a direct, unsmoothed 1068 lookup of color values. </p> 1069 1070 <p>This operator is especially suited to replacing a grayscale image with a 1071 specific color gradient from the CLUT image. </p> 1072 1073 <p>Only the channel values defined by the <a href="command-line-options.php#channel">-channel</a> 1074 setting will have their values replaced. In particular, since the default <a 1075 href="command-line-options.php#channel">-channel</a> setting is <code>RGB</code>, this means that 1076 transparency (alpha/matte channel) is not affected, unless the <a 1077 href="command-line-options.php#channel">-channel</a> setting is modified. When the alpha channel is 1078 set, it is treated by the <a href="command-line-options.php#clut" >-clut</a> operator in the same way 1079 as the other channels, implying that alpha/matte values are replaced using the 1080 alpha/matte values of the original image. </p> 1081 1082 <p>If either the image being modified, or the lookup image, contains no 1083 transparency (i.e. <a href="command-line-options.php#alpha" >-alpha</a> is turned 'off') but the <a 1084 href="command-line-options.php#channel">-channel</a> setting includes alpha replacement, then it is 1085 assumed that image represents a grayscale gradient which is used for the 1086 replacement alpha values. That is you can use a grayscale CLUT image to 1087 adjust a existing images alpha channel, or you can color a grayscale image 1088 using colors form CLUT containing the desired colors, including transparency. 1089 </p> 1090 1091 <p>See also <a href="command-line-options.php#hald-clut" >-hald-clut</a> which replaces colors 1092 according to the lookup of the full color RGB value from a 2D representation 1093 of a 3D color cube. </p> 1094 1095 1096 <div style="margin: auto;"> 1097 <h3 class="magick-header"><a id="coalesce"></a>-coalesce</h3> 1098 </div> 1099 1100 <p class="magick-description">Fully define the look of each frame of an GIF animation sequence, to form a 'film strip' animation.</p> 1101 1102 <p>Overlay each image in an image sequence according to 1103 its <a href="command-line-options.php#dispose">-dispose</a> meta-data, to reproduce the look of 1104 an animation at each point in the animation sequence. All images should be 1105 the same size, and are assigned appropriate GIF disposal settings for the 1106 animation to continue working as expected as a GIF animation. Such frames 1107 are more easily viewed and processed than the highly optimized GIF overlay 1108 images. </p> 1109 1110 <p>The animation can be re-optimized after processing using 1111 the <a href="command-line-options.php#layers">-layers</a> method '<code>optimize</code>', although 1112 there is no guarantee that the restored GIF animation optimization is 1113 better than the original. </p> 1114 1115 1116 <div style="margin: auto;"> 1117 <h3 class="magick-header"><a id="colorize"></a>-colorize <var>value</var></h3> 1118 </div> 1119 1120 <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.php#fill" >-fill</a> setting.</p> 1121 1122 <p>Specify the amount of colorization as a percentage. Separate colorization 1123 values can be applied to the red, green, and blue channels of the image with 1124 a comma-delimited list of colorization 1125 values (e.g., <code>-colorize 0,0,50</code>).</p> 1126 1127 <div style="margin: auto;"> 1128 <h3 class="magick-header"><a id="colormap"></a>-colormap <var>type</var></h3> 1129 </div> 1130 1131 <p class="magick-description">Define the colormap type.</p> 1132 1133 <p>The <var>type</var> can be <code>shared</code> or <code>private</code>.</p> 1134 1135 <p>This option only applies when the default X server visual 1136 is <code>PseudoColor</code> or <code>GrayScale</code>. Refer 1137 to <a href="command-line-options.php#visual">-visual</a> for more details. By default, 1138 a shared colormap is allocated. The image shares colors with 1139 other X clients. Some image colors could be approximated, 1140 therefore your image may look very different than intended. 1141 If <code>private</code> is chosen, the image colors appear exactly 1142 as they are defined. However, other clients may go <var>technicolor</var> 1143 when the image colormap is installed.</p> 1144 1145 <div style="margin: auto;"> 1146 <h3 class="magick-header"><a id="colors"></a>-colors <var>value</var></h3> 1147 </div> 1148 1149 <p class="magick-description">Set the preferred number of colors in the image.</p> 1150 1151 <p>The actual number of colors in the image may be less than your request, 1152 but never more. Note that this a color reduction option. Images with fewer 1153 unique colors than specified by <var>value</var> will have any 1154 duplicate or unused colors removed. The ordering of an existing color 1155 palette may be altered. When converting an image from color to grayscale, 1156 it is more efficient to convert the image to the gray colorspace before 1157 reducing the number of colors. Refer to 1158 the <a href="quantize.php"> 1159 color reduction algorithm</a> for more details.</p> 1160 1161 <div style="margin: auto;"> 1162 <h3 class="magick-header"><a id="color-matrix"></a>-color-matrix <var>matrix</var></h3> 1163 </div> 1164 1165 <p class="magick-description">apply color correction to the image.</p> 1166 1167 <p>This option permits saturation changes, hue rotation, luminance to alpha, 1168 and various other effects. Although variable-sized transformation matrices 1169 can be used, typically one uses a 5x5 matrix for an RGBA image and a 6x6 1170 for CMYKA (or RGBA with offsets). The matrix is similar to those used by 1171 Adobe Flash except offsets are in column 6 rather than 5 (in support of 1172 CMYKA images) and offsets are normalized (divide Flash offset by 255).</p> 1173 1174 <p>As an example, to add contrast to an image with offsets, try this command:</p> 1175 1176 <pre> 1177 convert kittens.jpg -color-matrix \ 1178 " 1.5 0.0 0.0 0.0, 0.0, -0.157 \ 1179 0.0 1.5 0.0 0.0, 0.0, -0.157 \ 1180 0.0 0.0 1.5 0.0, 0.0, -0.157 \ 1181 0.0 0.0 0.0 1.0, 0.0, 0.0 \ 1182 0.0 0.0 0.0 0.0, 1.0, 0.0 \ 1183 0.0 0.0 0.0 0.0, 0.0, 1.0" kittens.png 1184 </pre> 1185 <div style="margin: auto;"> 1186 <h3 class="magick-header"><a id="colorspace"></a>-colorspace <var>value</var></h3> 1187 </div> 1188 1189 <p class="magick-description">Set the image colorspace.</p> 1190 1191 <p>Choices are:</p> 1192 1193 <pre> 1194 CMY CMYK Gray HCL 1195 HCLp HSB HSI HSL 1196 HSV HWB Lab LCHab 1197 LCHuv LMS Log Luv 1198 OHTA Rec601YCbCr Rec709YCbCr RGB 1199 scRGB sRGB Transparent xyY 1200 XYZ YCbCr YCC YDbDr 1201 YIQ YPbPr YUV 1202 </pre> 1203 1204 <p>To print a complete list of colorspaces, use <a href="command-line-options.php#list">-list colorspace</a>.</p> 1205 1206 <p>For a more accurate color conversion to or from the linear RGB, CMYK, or grayscale colorspaces, use the <a href="command-line-options.php#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> 1207 1208 <table class="table table-condensed table-striped"> 1209 <caption>Conversion of RGB to Other Color Spaces</caption> 1210 <tr><th valign="middle">CMY</th></tr> 1211 <tr><td valign="middle">C=<var>QuantumRange</var>R</td></tr> 1212 <tr><td valign="middle">M=<var>QuantumRange</var>G</td></tr> 1213 <tr><td valign="middle">Y=<var>QuantumRange</var>B</td></tr> 1214 <tr><th valign="middle">CMYK starts with CMY from above</th></tr> 1215 <tr><td valign="middle">K=min(C,Y,M)</td></tr> 1216 <tr><td valign="middle">C=<var>QuantumRange</var>*(CK)/(<var>QuantumRange</var>K)</td></tr> 1217 <tr><td valign="middle">M=<var>QuantumRange</var>*(MK)/(<var>QuantumRange</var>K)</td></tr> 1218 <tr><td valign="middle">Y=<var>QuantumRange</var>*(YK)/(<var>QuantumRange</var>K)</td></tr> 1219 1220 <tr><th valign="middle">Gray</th></tr> 1221 <tr><td valign="middle">Gray = 0.298839*R+0.586811*G+0.114350*B</td></tr> 1222 1223 <tr><th valign="middle">HSB Hue, Saturation, Brightness; like a cone peak downward</th></tr> 1224 <tr><td valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr> 1225 <tr><td valign="middle">S=distance from axis outward</td></tr> 1226 <tr><td valign="middle">B=distance along axis from bottom upward; B=max(R,G,B); <var>intensity-like</var></td></tr> 1227 1228 <tr><th valign="middle">HSL Hue, Saturation, Lightness; like a double cone end-to-end with peaks at very top and bottom</th></tr> 1229 <tr><td valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr> 1230 <tr><td valign="middle">S=distance from axis outward</td></tr> 1231 <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> 1232 1233 <tr><th valign="middle">HWB Hue, Whiteness, Blackness</th></tr> 1234 <tr><td valign="middle">Hue (complicated equation)</td></tr> 1235 <tr><td valign="middle">Whiteness (complicated equation)</td></tr> 1236 <tr><td valign="middle">Blackness (complicated equation)</td></tr> 1237 1238 <tr><th valign="middle">LAB</th></tr> 1239 <tr><td valign="middle">L (complicated equation relating X,Y,Z)</td></tr> 1240 <tr><td valign="middle">A (complicated equation relating X,Y,Z)</td></tr> 1241 <tr><td valign="middle">B (complicated equation relating X,Y,Z)</td></tr> 1242 1243 <tr><th valign="middle">LOG</th></tr> 1244 <tr><td valign="middle">I1 (complicated equation involving logarithm of R)</td></tr> 1245 <tr><td valign="middle">I2 (complicated equation involving logarithm of G)</td></tr> 1246 <tr><td valign="middle">I3 (complicated equation involving logarithm of B)</td></tr> 1247 1248 <tr><th valign="middle">OHTA approximates principal components transformation</th></tr> 1249 <tr><td valign="middle">I1=0.33333*R+0.33334*G+0.33333*B; <var>intensity-like</var></td></tr> 1250 <tr><td valign="middle">I2=(0.50000*R+0.00000*G0.50000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1251 <tr><td valign="middle">I3=(0.25000*R+0.50000*G0.25000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1252 1253 <tr><th valign="middle">Rec601Luma</th></tr> 1254 <tr><td valign="middle">Gray = 0.298839*R+0.586811*G+0.114350*B</td></tr> 1255 1256 <tr><th valign="middle">Rec601YCbCr</th></tr> 1257 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1258 <tr><td valign="middle">Cb=(0.168736*R-0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1259 <tr><td valign="middle">Cr=(0.500000*R0.418688*G0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1260 1261 <tr><th valign="middle">Rec709Luma</th></tr> 1262 <tr><td valign="middle">Gray=0.212656*R+0.715158*G+0.072186*B</td></tr> 1263 1264 <tr><th valign="middle">Rec709YCbCr</th></tr> 1265 <tr><td valign="middle">Y=0.212656*R+0.715158*G+0.072186*B; <var>intensity-like</var></td></tr> 1266 <tr><td valign="middle">Cb=(0.114572*R0.385428*G+0.500000*B)+(<var>QuantumRange</var>+1)/2</td></tr> 1267 <tr><td valign="middle">Cr=(0.500000*R0.454153*G0.045847*B)+(<var>QuantumRange</var>+1)/2</td></tr> 1268 1269 <tr><th valign="middle">sRGB</th></tr> 1270 <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> 1271 <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> 1272 <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> 1273 1274 <tr><th valign="middle">XYZ</th></tr> 1275 <tr><td valign="middle">X=0.4124564*R+0.3575761*G+0.1804375*B</td></tr> 1276 <tr><td valign="middle">Y=0.2126729*R+0.7151522*G+0.0721750*B</td></tr> 1277 <tr><td valign="middle">Z=0.0193339*R+0.1191920*G+0.9503041*B</td></tr> 1278 1279 <tr><th valign="middle">YCC</th></tr> 1280 <tr><td valign="middle">Y=(0.298839*R+0.586811*G+0.114350*B) (with complicated scaling); <var>intensity-like</var></td></tr> 1281 <tr><td valign="middle">C1=(0.298839*R0.586811*G+0.88600*B) (with complicated scaling)</td></tr> 1282 <tr><td valign="middle">C2=(0.70100*R0.586811*G0.114350*B) (with complicated scaling)</td></tr> 1283 1284 <tr><th valign="middle">YCbCr</th></tr> 1285 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1286 <tr><td valign="middle">Cb=(0.168736*R0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1287 <tr><td valign="middle">Cr=(0.500000*R0.418688*G0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1288 1289 <tr><th valign="middle">YIQ</th></tr> 1290 <tr><td valign="middle">Y=0.298839*R+0.586811*G+0.114350*B; <var>intensity-like</var></td></tr> 1291 <tr><td valign="middle">I=(0.59600*R0.27400*G0.32200*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1292 <tr><td valign="middle">Q=(0.21100*R0.52300*G+0.31200*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1293 1294 <tr><th valign="middle">YPbPr</th></tr> 1295 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1296 <tr><td valign="middle">Pb=(0.168736*R0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1297 <tr><td valign="middle">Pr=(0.500000*R0.418688*G0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1298 1299 <tr><th valign="middle">YUV</th></tr> 1300 <tr><td valign="middle">Y=0.298839*R+0.586811*G+0.114350*B; <var>intensity-like</var></td></tr> 1301 <tr><td valign="middle">U=(0.14740*R0.28950*G+0.43690*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1302 <tr><td valign="middle">V=(0.61500*R0.51500*G0.10000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1303 </table> 1304 1305 <p>Note the scRGB colorspace requires HDRI support otherwise it behaves just like linear RGB.</p> 1306 1307 <div style="margin: auto;"> 1308 <h3 class="magick-header"><a id="combine"></a>-combine</h3> 1309 </div> 1310 1311 <p class="magick-description">Combine one or more images into a single image.</p> 1312 1313 <p>The channels (previously set by <a href="command-line-options.php#channel">-channel</a>) of the 1314 combined image are taken from the grayscale values of each image in the 1315 sequence, in order. For the default -channel setting of <code>RGB</code>, this 1316 means the first image is assigned to the <code>Red</code> channel, the second 1317 to the <code>Green</code> channel, the third to the <code>Blue</code>.</p> 1318 1319 <p>This option can be thought of as the inverse to <a 1320 href="command-line-options.php#separate">-separate</a>, so long as the channel settings are the same. 1321 Thus, in the following example, the final image should be a copy of the 1322 original. </p> 1323 1324 <pre> 1325 convert original.png -channel RGB -separate sepimage.png 1326 convert sepimage-0.png sepimage-1.png sepimage-2.png -channel RGB \ 1327 -combine imagecopy.png 1328 </pre> 1329 1330 <div style="margin: auto;"> 1331 <h3 class="magick-header"><a id="comment"></a>-comment <var>string</var></h3> 1332 </div> 1333 1334 <p class="magick-description">Embed a comment in an image.</p> 1335 1336 <p>This option sets the comment meta-data of an image read in after this 1337 option has been given. To modify a comment of images already in memory use 1338 "<code><a href="command-line-options.php#set">-set</a> comment</code>". </p> 1339 1340 <p>The comment can contain special format characters listed in the <a 1341 href="escape.php">Format and 1342 Print Image Properties</a>. These attributes are expanded when the comment 1343 is finally assigned to the individual images. </p> 1344 1345 <p>If the first character of <var>string</var> is <var>@</var>, the image comment is read from a file titled by the 1346 remaining characters in the string. Comments read in from a file are literal; 1347 no embedded formatting characters are recognized.</p> 1348 1349 <p>Comment meta-data are not visible on the image itself. To do that use the 1350 <a href="command-line-options.php#annotate">-annotate</a> or <a href="command-line-options.php#draw">-draw</a> options 1351 instead.</p> 1352 1353 <p>For example,</p> 1354 1355 <pre> 1356 -comment "%m:%f %wx%h" bird.miff 1357 </pre> 1358 1359 <p>produces an image comment of <code>MIFF:bird.miff 512x480</code> (assuming 1360 that the image <code>bird.miff</code> has a width of 512 and a height of 1361 480.</p> 1362 1363 <div style="margin: auto;"> 1364 <h3 class="magick-header"><a id="compare"></a>-compare</h3> 1365 </div> 1366 1367 <p class="magick-description">mathematically and visually annotate the difference between an image and its reconstruction</p> 1368 1369 <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> 1370 1371 <pre> 1372 convert image.png reference.png -metric RMSE -compare \ <br/> difference.png 1373 </pre> 1374 1375 <p>To get the metric value use the string format "%[distortion]".</p> 1376 1377 <pre> 1378 convert image.png reference.png -metric RMSE -compare -format \ 1379 "%[distortion]" info: 1380 </pre> 1381 1382 <div style="margin: auto;"> 1383 <h3 class="magick-header"><a id="complex"></a>-complex <var>operator</var></h3> 1384 </div> 1385 1386 <p class="magick-description">perform complex mathematics on an image sequence</p> 1387 1388 Choose from these operators: 1389 1390 <pre> 1391 add 1392 conjugate 1393 divide 1394 magnitude-phase 1395 multiply 1396 real-imaginary 1397 subtract 1398 </pre> 1399 1400 <p>Optionally specify the <code>divide</code> operator SNR with <code><a href="command-line-options.php#define">-define</a> complex:snr=float</code>.</p> 1401 1402 <div style="margin: auto;"> 1403 <h3 class="magick-header"><a id="compose"></a>-compose <var>operator</var></h3> 1404 </div> 1405 1406 <p class="magick-description">Set the type of image composition.</p> 1407 1408 <p>See <a href="compose.php">Alpha Compositing</a> for 1409 a detailed discussion of alpha compositing.</p> 1410 1411 <p>This setting effects image processing operators that merge two (or more) 1412 images together in some way. This includes the operators, 1413 <a href="command-line-options.php#composite">-compare</a>, 1414 <a href="command-line-options.php#composite">-composite</a>, 1415 <a href="command-line-options.php#layers">-layers</a> composite, 1416 <a href="command-line-options.php#flatten">-flatten</a>, 1417 <a href="command-line-options.php#mosaic">-mosaic</a>, 1418 <a href="command-line-options.php#layers">-layers</a> merge, 1419 <a href="command-line-options.php#border">-border</a>, 1420 <a href="command-line-options.php#frame">-frame</a>, 1421 and <a href="command-line-options.php#extent">-extent</a>. </p> 1422 1423 <p>It is also one of the primary options for the "<code>composite</code>" 1424 command. </p> 1425 1426 1427 <div style="margin: auto;"> 1428 <h3 class="magick-header"><a id="composite"></a>-composite</h3> 1429 </div> 1430 1431 <p class="magick-description">Perform alpha composition on two images and an optional mask</p> 1432 1433 <p>Take the first image 'destination' and overlay the second 'source' image 1434 according to the current <a href="command-line-options.php#compose">-compose</a> setting. The location 1435 of the 'source' or 'overlay' image is controlled according to <a 1436 href="command-line-options.php#gravity" >-gravity</a>, and <a href="command-line-options.php#geometry" >-geometry</a> 1437 settings. </p> 1438 1439 <p>If a third image is given this is treated as a grayscale blending 'mask' image 1440 relative to the first 'destination' image. This mask is blended with the 1441 source image. However for the '<code>displace</code>' compose method, the 1442 mask is used to provide a separate Y-displacement image instead. </p> 1443 1444 <p>If a <a href="command-line-options.php#compose">-compose</a> method requires extra numerical 1445 arguments or flags these can be provided by setting the <a 1446 href="command-line-options.php#set">-set</a> '<code>option:compose:args</code>' 1447 appropriately for the compose method. </p> 1448 1449 <p>Some <a href="command-line-options.php#compose">-compose</a> methods can modify the 'destination' 1450 image outside the overlay area. You can disable this by setting the special <a 1451 href="command-line-options.php#set">-set</a> '<code>option:compose:outside-overlay</code>' 1452 to '<code>false</code>'. </p> 1453 1454 <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.php#set">-set</a> '<code>option:compose:clamp=false</code></p> 1455 1456 1457 <div style="margin: auto;"> 1458 <h3 class="magick-header"><a id="compress"></a>-compress <var>type</var></h3> 1459 </div> 1460 1461 <p class="magick-description">Use pixel compression specified by <var>type</var> when writing the image.</p> 1462 1463 <p>Choices are: <code>None</code>, <code>BZip</code>, <code 1464 >Fax</code>, <code>Group4</code>, <code 1465 >JPEG</code>, <code>JPEG2000</code>, <code 1466 >Lossless</code>, <code>LZW</code>, <code 1467 >RLE</code> or <code>Zip</code>.</p> 1468 1469 <p>To print a complete list of compression types, use <a href="command-line-options.php#list">-list 1470 compress</a>.</p> 1471 1472 <p>Specify <a href="command-line-options.php#compress">+compress</a> to store the binary image in an 1473 uncompressed format. The default is the compression type of the specified 1474 image file.</p> 1475 1476 <p>If <code>LZW</code> compression is specified but LZW compression has not been 1477 enabled, the image data is written in an uncompressed LZW format that can be 1478 read by LZW decoders. This may result in larger-than-expected GIF files.</p> 1479 1480 <p><code>Lossless</code> refers to lossless JPEG, which is only available if the 1481 JPEG library has been patched to support it. Use of lossless JPEG is generally 1482 not recommended.</p> 1483 1484 <p> 1485 When writing an ICO file, you may request that the images be encoded in 1486 PNG format, by specifying <code>Zip</code> compression.</p> 1487 1488 <p> 1489 When writing a JNG file, specify <code>Zip</code> compression to request that 1490 the alpha channel be encoded in PNG "IDAT" format, or <code>JPEG</code> 1491 to request that it be encoded in JPG "JDAA" format.</p> 1492 1493 <p>Use the <a href="command-line-options.php#quality">-quality</a> option to set the compression level 1494 to be used by JPEG, PNG, MIFF, and MPEG encoders. 1495 Use the <a href="command-line-options.php#sampling-factor">-sampling-factor</a> option to set the 1496 sampling factor to be used by JPEG, MPEG, and YUV encoders for down-sampling 1497 the chroma channels.</p> 1498 1499 <div style="margin: auto;"> 1500 <h3 class="magick-header"><a id="connected-components"></a>-connected-components <var>connectivity</var></h3> 1501 </div> 1502 1503 <p class="magick-description"><a href="connected-components.php">connected-components</a> labeling detects connected regions in an image, choose from 4 or 8 way connectivity.</p> 1504 1505 <p>Use <code><a href="command-line-options.php#define" >-define</a> connected-components:verbose=true</code> to output statistics associated with each unique label.</p> 1506 1507 <div style="margin: auto;"> 1508 <h3 class="magick-header"><a id="contrast"></a>-contrast</h3> 1509 </div> 1510 1511 <p class="magick-description">Enhance or reduce the image contrast.</p> 1512 1513 <p>This option enhances the intensity differences between the lighter and 1514 darker elements of the image. Use <a href="command-line-options.php#contrast">-contrast</a> to enhance 1515 the image or <a href="command-line-options.php#contrast">+contrast</a> to reduce the image 1516 contrast.</p> 1517 1518 <p>For a more pronounced effect you can repeat the option:</p> 1519 1520 <pre> 1521 convert rose: -contrast -contrast rose_c2.png 1522 </pre> 1523 1524 <div style="margin: auto;"> 1525 <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> 1526 </div> 1527 1528 <p class="magick-description">Increase the contrast in an image by <var>stretching</var> the range of intensity values.</p> 1529 1530 <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 1531 <var >black-point %</var> pixels and white-out at most <var>white-point %</var> pixels.</p> 1532 1533 <p>Prior to ImageMagick 6.4.7-0, <a href="command-line-options.php#contrast-stretch" 1534 >-contrast-stretch</a> will black-out at most <var>black-point</var> pixels and white-out at most <var >total pixels 1535 minus 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> 1536 1537 <p>Note that <code>-contrast-stretch 0</code> will modify the image such that 1538 the 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 1539 clipping at either end. This is not the same as <a href="command-line-options.php#normalize" 1540 >-normalize</a>, which is equivalent to <code>-contrast-stretch 0.15x0.05%</code> (or 1541 prior to ImageMagick 6.4.7-0, <code>-contrast-stretch 2%x99%</code>).</p> 1542 1543 <p>Internally operator works by creating a histogram bin, and then uses that 1544 bin to modify the image. As such some colors may be merged together when they 1545 originally fell into the same 'bin'. </p> 1546 1547 <p>All the channels are normalized in concert by the same amount so as to 1548 preserve color integrity, when the default <a href="command-line-options.php#channel" >+channel</a> 1549 setting is in use. Specifying any other <a href="command-line-options.php#channel" >-channel</a> 1550 setting will normalize the RGB channels independently.</p> 1551 1552 <p>See also <a href="command-line-options.php#auto-level" >-auto-level</a> for a 'perfect' 1553 normalization of mathematical images. </p> 1554 1555 <p>This operator is under review for re-development. </p> 1556 1557 1558 <div style="margin: auto;"> 1559 <h3 class="magick-header"><a id="convolve"></a>-convolve <var>kernel</var></h3> 1560 </div> 1561 1562 <p class="magick-description">Convolve an image with a user-supplied convolution kernel.</p> 1563 1564 <p>The <var>kernel</var> is a matrix specified as 1565 a comma-separated list of integers (with no spaces), ordered left-to right, 1566 starting with the top row. Presently, only odd-dimensioned kernels are 1567 supported, and therefore the number of entries in the specified <var>kernel</var> must be 3<sup>2</sup>=9, 5<sup>2</sup>=25, 1568 7<sup>2</sup>=49, etc. </p> 1569 1570 <p>Note that the <a href="command-line-options.php#convolve">‑convolve</a> operator supports the <a href="command-line-options.php#bias">‑bias</a> setting. This option shifts the convolution so that 1571 positive and negative results are relative to a user-specified bias value. 1572 This is important for non-HDRI compilations of ImageMagick when dealing with 1573 convolutions that contain negative as well as positive values. This is 1574 especially the case with convolutions involving high pass filters or edge 1575 detection. Without an output bias, the negative values is clipped at zero. 1576 </p> 1577 1578 <p>When using an ImageMagick with the HDRI compile-time setting, <a href="command-line-options.php#bias">‑bias</a> is not needed, as ImageMagick is able to store/handle any 1579 negative results without clipping to the color value range (0..QuantumRange). 1580 See the discussion on HDRI implementations of ImageMagick on the page <a 1581 href="high-dynamic-range.php">High 1582 Dynamic-Range Images</a>. For more about HDRI go the ImageMagick <a 1583 href="http://www.imagemagick.org/Usage/basics/#hdri">Usage</a> pages or this 1584 <a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> 1585 entry. </p> 1586 1587 1588 <div style="margin: auto;"> 1589 <h3 class="magick-header"><a id="copy"></a>-copy <var>geometry</var> <var>offset</var></h3> 1590 </div> 1591 1592 <p class="magick-description">copy pixels from one area of an image to another.</p> 1593 1594 <div style="margin: auto;"> 1595 <h3 class="magick-header"><a id="crop"></a>-crop <var>geometry</var>{<var>@</var>}{<var>!</var>}</h3> 1596 </div> 1597 1598 <p class="magick-description">Cut out one or more rectangular regions of the image.</p> 1599 1600 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 1601 1602 <p>The <var>width</var> and <var>height</var> of the <var>geometry</var> argument give the size of the image that remains 1603 after cropping, and <var>x</var> and <var>y</var> in the 1604 <var>offset</var> (if present) gives the location of the top left 1605 corner of the cropped image with respect to the original image. To specify the 1606 amount to be removed, use <a href="command-line-options.php#shave">-shave</a> instead.</p> 1607 1608 <p>If the <var>x</var> and <var>y</var> offsets are 1609 present, a single image is generated, consisting of the pixels from the 1610 cropping region. The offsets specify the location of the upper left corner of 1611 the cropping region measured downward and rightward with respect to the upper 1612 left corner of the image. If the <a href="command-line-options.php#gravity">-gravity</a> option is 1613 present with <code>NorthEast</code>, <code>East</code>, or <code>SouthEast</code> 1614 gravity, it gives the distance leftward from the right edge of the image to 1615 the right edge of the cropping region. Similarly, if the <a 1616 href="command-line-options.php#gravity">-gravity</a> option is present with <code>SouthWest</code>, 1617 <code>South</code>, or <code>SouthEast</code> gravity, the distance is measured 1618 upward between the bottom edges.</p> 1619 1620 <p>If the <var>x</var> and <var>y</var> offsets are 1621 omitted, a set of tiles of the specified geometry, covering the entire input 1622 image, is generated. The rightmost tiles and the bottom tiles are smaller if 1623 the specified geometry extends beyond the dimensions of the input image.</p> 1624 1625 <p>You can add the <var>@</var> to the geometry argument to equally divide the image into the number of tiles generated.</p> 1626 1627 <p>By adding a exclamation character flag to the geometry argument, the 1628 cropped images virtual canvas page size and offset is set as if the 1629 geometry argument was a viewport or window. This means the canvas page size 1630 is set to exactly the same size you specified, the image offset set 1631 relative top left corner of the region cropped. </p> 1632 1633 <p>If the cropped image 'missed' the actual image on its virtual canvas, a 1634 special single pixel transparent 'missed' image is returned, and a 'crop 1635 missed' warning given. </p> 1636 1637 <p>It might be necessary to <a href="command-line-options.php#repage" >+repage</a> the image prior to 1638 cropping the image to ensure the crop coordinate frame is relocated to the 1639 upper-left corner of the visible image. 1640 1641 Similarly you may want to use <a href="command-line-options.php#repage" >+repage</a> after cropping to 1642 remove the page offset that will be left behind. This is especially true when 1643 you are going to write to an image format such as PNG that supports an image 1644 offset.</p> 1645 1646 <div style="margin: auto;"> 1647 <h3 class="magick-header"><a id="cycle"></a>-cycle <var>amount</var></h3> 1648 </div> 1649 1650 <p class="magick-description">displace image colormap by amount.</p> 1651 1652 <p><var>Amount</var> defines the number of positions each 1653 colormap entry is shifted.</p> 1654 1655 1656 <div style="margin: auto;"> 1657 <h3 class="magick-header"><a id="debug"></a>-debug <var>events</var></h3> 1658 </div> 1659 1660 <p class="magick-description">enable debug printout.</p> 1661 1662 <p>The <code>events</code> parameter specifies which events are to be logged. It 1663 can be either <code>None</code>, <code>All</code>, <code>Trace</code>, or 1664 a comma-separated list consisting of one or more of the following domains: 1665 <code>Accelerate</code>, <code>Annotate</code>, <code>Blob</code>, <code>Cache</code>, 1666 <code>Coder</code>, <code>Configure</code>, <code>Deprecate</code>, 1667 <code>Exception</code>, <code>Locale</code>, <code>Render</code>, 1668 <code>Resource</code>, <code>Security</code>, <code>TemporaryFile</code>, 1669 <code>Transform</code>, <code>X11</code>, or <code>User</code>. </p> 1670 1671 1672 <p>For example, to log cache and blob events, use.</p> 1673 1674 <pre> 1675 convert -debug "Cache,Blob" rose: rose.png 1676 </pre> 1677 1678 <p>The <code>User</code> domain is normally empty, but developers can log user 1679 events in their private copy of ImageMagick.</p> 1680 1681 <p>To print the complete list of debug methods, use <a href="command-line-options.php#list">-list 1682 debug</a>.</p> 1683 1684 <p>Use the <a href="command-line-options.php#log">-log</a> option to specify the format for debugging 1685 output.</p> 1686 1687 <p>Use <a href="command-line-options.php#debug">+debug</a> to turn off all logging.</p> 1688 1689 <p>Debugging may also be set using the <code>MAGICK_DEBUG</code> <a href="resources.php#environment" 1690 >environment variable</a>. The allowed values for the <code>MAGICK_DEBUG</code> 1691 environment variable are the same as for the <a href="command-line-options.php#debug">-debug</a> 1692 option.</p> 1693 1694 1695 <div style="margin: auto;"> 1696 <h3 class="magick-header"><a id="decipher"></a>-decipher <var>filename</var></h3> 1697 </div> 1698 1699 <p class="magick-description">Decipher and restore pixels that were previously transformed by <a href="command-line-options.php#encipher">-encipher</a>.</p> 1700 1701 <p>Get the passphrase from the file specified by <var>filename</var>.</p> 1702 1703 <p>For more information, see the webpage, <a 1704 href="http://www.imagemagick.org/www/cipher.html">ImageMagick: Encipher or 1705 Decipher an Image</a>.</p> 1706 1707 1708 <div style="margin: auto;"> 1709 <h3 class="magick-header"><a id="deconstruct"></a>-deconstruct</h3> 1710 </div> 1711 1712 <p class="magick-description">find areas that has changed between images </p> 1713 1714 <p>Given a sequence of images all the same size, such as produced by <a 1715 href="command-line-options.php#coalesce">-coalesce</a>, replace the second and later images, with 1716 a smaller image of just the area that changed relative to the previous image. 1717 </p> 1718 1719 <p>The resulting sequence of images can be used to optimize an animation 1720 sequence, though will not work correctly for GIF animations when parts of the 1721 animation can go from opaque to transparent. </p> 1722 1723 <p>This option is actually equivalent to the <a href="command-line-options.php#layers">-layers</a> 1724 method '<code>compare-any</code>'. </p> 1725 1726 1727 <div style="margin: auto;"> 1728 <h3 class="magick-header"><a id="define"></a>-define <var>key</var>{<var>=value</var>}<var>...</var></h3> 1729 </div> 1730 1731 <p class="magick-description">add specific global settings generally used to control coders and image processing operations.</p> 1732 1733 <p>This option creates one or more definitions for coders and decoders to use 1734 while reading and writing image data. Definitions are generally used to 1735 control image file format coder modules, and image processing operations, 1736 beyond what is provided by normal means. Defined settings are listed in <a 1737 href="command-line-options.php#verbose" >-verbose</a> information ("<code>info:</code>" output format) 1738 as "Artifacts". </p> 1739 1740 <p>If <var>value</var> is missing for a definition, an empty-valued 1741 definition of a flag is created with that name. This used to control on/off 1742 options. Use <a href="command-line-options.php#define">+define key</a> to remove definitions 1743 previously created. Use <a href="command-line-options.php#define">+define "*"</a> to remove all 1744 existing definitions.</p> 1745 1746 <p>The same 'artifact' settings can also be defined using the <a 1747 href="command-line-options.php#set" >-set "option:<var>key</var>" "<var>value</var>"</a> option, which also allows the use of <a href="escape.php" >Format and Print Image 1748 Properties</a> in the defined value. </p> 1749 1750 <p>The <var>option</var> and <var>key</var> are case-independent (they are 1751 converted to lowercase for use within the decoders) while the <var>value</var> 1752 is case-dependent.</p> 1753 1754 <p>Such settings are global in scope, and affect all images and operations. </p> 1755 1756 <p>The following definitions are just some of the artifacts that are 1757 available:</p> 1758 1759 <table class="table table-condensed table-striped"> 1760 <tr> 1761 <td>bmp:format=<var>value</var></td> 1762 <td> valid values are <var>bmp2</var>, <var>bmp3</var>, 1763 and <var>bmp4</var>. This option can be useful when the 1764 method of prepending "BMP2:" to the output filename is inconvenient or 1765 is not available, such as when using the <a href="mogrify.php">mogrify</a> utility.</td> 1766 </tr> 1767 1768 <tr> 1769 <td>colorspace:auto-grayscale=<var>on|off</var></td> 1770 <td>prevent automatic conversion to grayscale inside coders that support 1771 grayscale. This should be accompanied by -type truecolor. PNG and TIF do 1772 not need this define. With PNG, just use PNG24:image. With TIF, just use 1773 -type truecolor. JPG and PSD will need this define.</td> 1774 </tr> 1775 1776 <tr> 1777 <td>complex:snr=<var>value</var></td> 1778 <td>Set the divide SNR constant<a href="command-line-options.php#complex">-complex</a></td> 1779 </tr> 1780 1781 <tr> 1782 <td>compose:args=<var>arguments</var></td> 1783 <td>Sets certain compose argument values when using convert ... -compose ... 1784 -composite. See <a href="http://www.imagemagick.org/script/compose.php" 1785 >Image Composition</a></td> 1786 </tr> 1787 1788 <tr> 1789 <td>compose:clamp=<var>on|off</var></td> 1790 <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> 1791 </tr> 1792 1793 <tr> 1794 <td>connected-components:area-threshold=<var>value</var></td> 1795 <td>Merges any region with area smaller than <var>value</var> into its surrounding region or largest neighbor.</td> 1796 </tr> 1797 1798 <tr> 1799 <td>connected-components:keep=<var>list-of-ids</var></td> 1800 <td>Command and/or hyphenated list of id values to keep in the output. Supported in Imagemagick 6.9.3-0.</td> 1801 </tr> 1802 1803 <tr> 1804 <td>connected-components:mean-color=<var>true</var></td> 1805 <td>Changes the output image from id values to mean color values. Supported in Imagemagick 6.9.2-8.</td> 1806 </tr> 1807 1808 <tr> 1809 <td>connected-components:remove=<var>list-of-ids</var></td> 1810 <td>Command and/or hyphenated list of id values to remove from the output. Supported in Imagemagick 6.9.2-9.</td> 1811 </tr> 1812 1813 <tr> 1814 <td>connected-components:verbose=<var>true</var></td> 1815 <td>Lists id, bounding box, centroid, area, mean color for each region.</td> 1816 </tr> 1817 1818 <tr> 1819 <td>convolve:scale=<var>{kernel_scale}[!^] [,{origin_addition}] [%]</var></td> 1820 <td>Defines the kernel scaling. The special flag ! automatically scales to 1821 full dynamic range. The ! flag can be used in combination with a factor or 1822 percent. The factor or percent is then applied after the automatic scaling. 1823 An example is 50%!. This produces a result 50% darker than full dynamic 1824 range scaling. The ^ flag assures the kernel is 'zero-summing', for 1825 example when some values are positive and some are negative as in edge 1826 detection kernels. The origin addition adds that value to the center 1827 pixel of the kernel. This produces and effect that is like adding the image 1828 that many times to the result of the filtered image. The typical value 1829 is 1 so that the original image is added to the result of the convolution. 1830 The default is 0.</td> 1831 </tr> 1832 1833 <tr> 1834 <td>convolve:showkernel=<var>1</var></td> 1835 <td>Outputs (to 'standard error') all the information about a specified <a 1836 href="command-line-options.php#morphology" >-morphology convolve</a> kernel.</td> 1837 </tr> 1838 1839 <tr> 1840 <td>dcm:display-range=<var>reset</var></td> 1841 <td>Sets the display range to the minimum and maximum pixel values for the 1842 DCM image format.</td> 1843 </tr> 1844 1845 <tr> 1846 <td>dds:cluster-fit=<var>true|false</var></td> 1847 <td>Enables the dds cluster-fit.</td> 1848 </tr> 1849 1850 <tr> 1851 <td>dds:compression=<var>dxt1|dxt5|none</var></td> 1852 <td>Sets the dds compression.</td> 1853 </tr> 1854 1855 <tr> 1856 <td>dds:mipmaps=<var>value</var></td> 1857 <td>Sets the dds number of mipmaps.</td> 1858 </tr> 1859 1860 <tr> 1861 <td>dds:weight-by-alpha=<var>true|false</var></td> 1862 <td>Enables the dds alpha weighting.</td> 1863 </tr> 1864 1865 <tr> 1866 <td>delegate:bimodal=<var>true</var></td> 1867 <td>Specifies direct conversion from Postscript to PDF.</td> 1868 </tr> 1869 1870 <tr> 1871 <td>distort:scale=<var>value</var></td> 1872 <td>Sets the output scaling factor for use with <a href="command-line-options.php#distort" 1873 >-distort</a></td> 1874 </tr> 1875 1876 <tr> 1877 <td>distort:viewport=<var>WxH+X+Y</var></td> 1878 <td>Sets the viewport for use with <a href="command-line-options.php#distort">-distort</a></td> 1879 </tr> 1880 1881 <tr> 1882 <td>dot:layout-engine=<var>value</var></td> 1883 <td>Specifies the layout engine for the DOT image format (e.g. 1884 <code>neato</code>).</td> 1885 </tr> 1886 1887 <tr> 1888 <td>filter:option=<var>value</var></td> 1889 <td>Set a filter option for use with <a href="command-line-options.php#resize">-resize</a>. 1890 See <a href="command-line-options.php#filter">-filter</a> for details.</td> 1891 </tr> 1892 1893 <tr> 1894 <td>fourier:normalize=<var>inverse</var></td> 1895 <td>Sets the location for the FFT/IFT normalization as use by 1896 <a href="command-line-options.php#fft">+-fft</a> and <a href="command-line-options.php#ift">+-ift</a>. The default is 1897 <var>forward</var>.</td> 1898 </tr> 1899 1900 <tr> 1901 <td>h:format=<var>value</var></td> 1902 <td>Set the image encoding format use when writing a C-style header. 1903 <var>format</var> can be any output format supported by ImageMagick 1904 except for <var>h</var> and <var>magick</var></td>. If this 1905 option is omitted, the default is <var>GIF</var> for PseudoClass 1906 images and <var>PNM</var> for DirectClass images. 1907 </tr> 1908 1909 <tr> 1910 <td>icon:auto-resize</td> 1911 <td>Automatically stores multiple sizes when writing an ico image 1912 (requires a 256x256 input image).</td> 1913 </tr> 1914 1915 <tr> 1916 <td>jp2:layer-number=<var>value</var></td> 1917 <td>Sets the maximum number of quality layers to decode. Same for JPT, JC2, 1918 and J2K</td> 1919 </tr> 1920 1921 <tr> 1922 <td>jp2:number-resolutions=<var>value</var></td> 1923 <td>Sets the number of resolutions to encode.Same for JPT, JC2, and J2K</td> 1924 </tr> 1925 1926 <tr> 1927 <td>jp2:progression-order=<var>value</var></td> 1928 <td>choose from LRCP, RLCP, RPCL, PCRL or CPRL. Same for JPT, JC2, and 1929 J2K</td> 1930 </tr> 1931 1932 <tr> 1933 <td>jp2:quality=<var>value,value...</var></td> 1934 <td>Sets the quality layer PSNR, given in dB. The order is from left to 1935 right in ascending order. The default is a single lossless quality layer. 1936 Same for JPT, JC2, and J2K</td> 1937 </tr> 1938 1939 <tr> 1940 <td>jp2:rate=<var>value</var></td> 1941 <td>Specify the compression factor to use while writing JPEG-2000 files. The 1942 compression factor is the reciprocal of the compression ratio. The valid 1943 range is 0.0 to 1.0, with 1.0 indicating lossless compression. If defined, 1944 this value overrides the -quality setting. A quality setting of 75 1945 results in a rate value of 0.06641. Same for JPT, JC2, and J2K</td> 1946 </tr> 1947 1948 <tr> 1949 <td>jp2:reduce-factor=<var>value</var></td> 1950 <td>Sets the number of highest resolution levels to be discarded.Same for 1951 JPT, JC2, and J2K</td> 1952 </tr> 1953 1954 <tr> 1955 <td>jpeg:block-smoothing=<var>on|off</var></td> 1956 <td> </td> 1957 </tr> 1958 1959 <tr> 1960 <td>jpeg:colors=<var>value</var></td> 1961 <td>Set the desired number of colors and let the JPEG encoder do the 1962 quantizing.</td> 1963 </tr> 1964 1965 <tr> 1966 <td>jpeg:dct-method=<var>value</var></td> 1967 <td>Choose from <code>default</code>, <code>fastest</code>, 1968 <code>float</code>, <code>ifast</code>, and <code>islow</code>.</td> 1969 </tr> 1970 1971 <tr> 1972 <td>jpeg:extent=<var>value</var></td> 1973 <td>Restrict the maximum JPEG file size, for example <code>-define 1974 jpeg:extent=400KB</code>. The JPEG encoder will search for the highest 1975 compression quality level that results in an output file that does not 1976 exceed the value. The <code>-quality</code> option also will be respected 1977 starting with version 6.9.2-5. Between 6.9.1-0 and 6.9.2-4, add -quality 1978 100 in order for the jpeg:extent to work properly. Prior to 6.9.1-0, the 1979 -quality setting was ignored.</td> 1980 </tr> 1981 1982 <tr> 1983 <td>jpeg:fancy-upsampling=<var>on|off</var></td> 1984 <td> </td> 1985 </tr> 1986 1987 <tr> 1988 <td>jpeg:optimize-coding=<var>on|off</var></td> 1989 <td> </td> 1990 </tr> 1991 1992 <tr> 1993 <td>jpeg:q-table=<var>table</var></td> 1994 <td> </td> 1995 </tr> 1996 1997 <tr> 1998 <td>jpeg:sampling-factor=<var>sampling-factor-string</var></td> 1999 <td> </td> 2000 </tr> 2001 2002 <tr> 2003 <td>jpeg:size=<var>geometry</var></td> 2004 <td>Set the size hint of a JPEG image, for 2005 example, <code>-define jpeg:size=128x128</code>. 2006 It is most useful for increasing performance and reducing the memory 2007 requirements when reducing the size of a large JPEG image.</td> 2008 </tr> 2009 2010 <tr> 2011 <td>json:features</td> 2012 <td>includes features in verbose information</td> 2013 </tr> 2014 2015 <tr> 2016 <td>json:limit</td> 2017 <td> </td> 2018 </tr> 2019 2020 <tr> 2021 <td>json:locate</td> 2022 <td> </td> 2023 </tr> 2024 2025 <tr> 2026 <td>json:moments</td> 2027 <td>includes image moments in verbose information</td> 2028 </tr> 2029 2030 <tr> 2031 <td>magick:format=<var>value</var></td> 2032 <td>Set the image encoding format use when writing a C-style header. 2033 This is the same as "h:format=format" described above.</td>. 2034 </tr> 2035 2036 <tr> 2037 <td>mng:need-cacheoff</td> 2038 <td>turn playback caching off for streaming MNG.</td> 2039 </tr> 2040 2041 <tr> 2042 <td>morphology:compose=<var>compose-method</var></td> 2043 <td>Specifies how to merge results generated by multiple<a 2044 href="command-line-options.php#morphology" >-morphology</a> kernel. The default is none. One 2045 typical value is 'lighten' as used, for example, with the sobel edge 2046 kernels. </td> 2047 </tr> 2048 2049 <tr> 2050 <td>morphology:showkernel=<var>1</var></td> 2051 <td>Outputs (to 'standard error') all the information about a generated <a 2052 href="command-line-options.php#morphology" >-morphology</a> kernel.</td> 2053 </tr> 2054 2055 <tr> 2056 <td>pcl:fit-to-page=<var>true</var></td> 2057 2058 <tr> 2059 <td>pdf:fit-page=<var>geometry</var></td> 2060 <td> geometry specifies the scaling dimensions for resizing when the PDF is 2061 being read. The geometry is either WxH{%} or page size. No offsets are 2062 allowed. (introduced in IM 6.8.8-8)</td> 2063 </tr> 2064 2065 <tr> 2066 <td>pdf:fit-to-page=<var>true</var></td> 2067 <td> </td> 2068 </tr> 2069 2070 <tr> 2071 <td>pdf:use-cropbox=<var>true</var></td> 2072 <td> </td> 2073 </tr> 2074 2075 <tr> 2076 <td>pdf:use-trimbox=<var>true</var></td> 2077 <td> </td> 2078 </tr> 2079 2080 <tr> 2081 <td>png:bit-depth=<var>value</var></td> 2082 <td> </td> 2083 </tr> 2084 <tr> 2085 <td>png:color-type=<var>value</var></td> 2086 <td>desired bit-depth and color-type for PNG output. You can force the PNG 2087 encoder to use a different bit-depth and color-type than it would have 2088 normally selected, but only if this does not cause any loss of image 2089 quality. Any attempt to reduce image quality is treated as an error and no 2090 PNG file is written. E.g., if you have a 1-bit black-and-white image, you 2091 can use these "defines" to cause it to be written as an 8-bit grayscale, 2092 indexed, or even a 64-bit RGBA. But if you have a 16-million color image, 2093 you cannot force it to be written as a grayscale or indexed PNG. If you 2094 wish to do this, you must use the appropriate <a href="command-line-options.php#depth">-depth</a>, 2095 <a href="command-line-options.php#colors">-colors</a>, or <a href="command-line-options.php#type">-type</a> directives to 2096 reduce the image quality prior to using the PNG encoder. Note that in 2097 indexed PNG files, "bit-depth" refers to the number of bits per index, 2098 which can be 1, 2, 4, or 8. In such files, the color samples always have 2099 8-bit depth.</td> 2100 </tr> 2101 2102 <tr> 2103 <td>png:compression-filter=<var>value</var></td> 2104 <td> valid values are 0 through 9. 0-4 are the corresponding PNG filters, 2105 5 means adaptive filtering except for images with a colormap, 6 means 2106 adaptive filtering for all images, 7 means MNG "loco" compression, 8 means 2107 Z_RLE strategy with adaptive filtering, and 9 means Z_RLE strategy with no 2108 filtering.</td> 2109 </tr> 2110 2111 <tr> 2112 <td>png:compression-level=<var>value</var></td> 2113 <td> valid values are 0 through 9, with 0 providing the least but fastest 2114 compression and 9 usually providing the best and always the slowest.</td> 2115 </tr> 2116 2117 <tr> 2118 <td>png:compression-strategy=<var>value</var></td> 2119 <td> valid values are 0 through 4, meaning default, filtered, huffman_only, 2120 rle, and fixed ZLIB compression strategy. If you are using an old zlib 2121 that does not support Z_RLE (before 1.2.0) or Z_FIXED (before 1.2.2.2), 2122 values 3 and 4, respectively, will use the zlib default strategy 2123 instead.</td> 2124 </tr> 2125 2126 <tr> 2127 <td>png:format=<var>value</var></td> 2128 <td> valid values are <var>png8</var>, <var>png24</var>, 2129 <var>png32</var>, <var>png48</var>, 2130 <var>png64</var>, and <var>png00</var>. 2131 This property can be useful for specifying 2132 the specific PNG format to be used, when the usual method of prepending the 2133 format name to the output filename is inconvenient, such as when writing 2134 a PNG-encoded ICO file or when using <a href="mogrify.php">mogrify</a>. 2135 Value = <var>png8</var> reduces the number of colors to 256, 2136 only one of which may be fully transparent, if necessary. The other 2137 values do not force any reduction of quality; it is an error to request 2138 a format that cannot represent the image data without loss (except that 2139 it is allowed to reduce the bit-depth from 16 to 8 for all formats). 2140 Value = <var>png24</var> and <var>png48</var> 2141 allow transparency, only if a single color is fully transparent and that 2142 color does not also appear in an opaque pixel; such transparency is 2143 written in a PNG <code>tRNS</code> chunk. 2144 Value = <var>png00</var> causes the image to inherit its 2145 color-type and bit-depth from the input image, if the input was also 2146 a PNG.</td> 2147 </tr> 2148 2149 <tr> 2150 <td>png:exclude-chunk=<var>value</var></td> 2151 2152 <tr> 2153 <td>png:include-chunk=<var>value</var></td> 2154 <td>ancillary chunks to be excluded from or included in PNG output. 2155 2156 <p>The <var>value</var> can be the name of a PNG chunk-type such 2157 as <var>bKGD</var>, a comma-separated list of chunk-names 2158 (which can include the word <var>date</var>, the word 2159 <var>all</var>, or the word <var>none</var>). 2160 Although PNG chunk-names are case-dependent, you can use all lowercase 2161 names if you prefer.</p> 2162 2163 <p>The "include-chunk" and "exclude-chunk" lists only affect the behavior 2164 of the PNG encoder and have no effect on the PNG decoder.</p> 2165 2166 <p>As a special case, if the <code>sRGB</code> chunk is excluded and 2167 the <code>gAMA</code> chunk is included, the <code>gAMA</code> chunk will 2168 only be written if gamma is not 1/2.2, since most decoders assume 2169 sRGB and gamma=1/2.2 when no colorspace information is included in 2170 the PNG file. Because the list is processed from left to right, you 2171 can achieve this with a single define:</p> 2172 2173 <pre> 2174 -define png:include-chunk=none,gAMA 2175 </pre> 2176 2177 <p>As a special case, if the <code>sRGB</code> chunk is not excluded and 2178 the PNG encoder recognizes that the image contains the sRGB ICC profile, 2179 the PNG encoder will write the <code>sRGB</code> chunk instead of the 2180 entire ICC profile. To force the PNG encoder to write the sRGB 2181 profile as an <code>iCCP</code> chunk in the output PNG instead of the 2182 <code>sRGB</code> chunk, exclude the <code>sRGB</code> chunk.</p> 2183 2184 <p>The critical PNG chunks <code>IHDR</code>, <code>PLTE</code>, 2185 <code>IDAT</code>, and <code>IEND</code> cannot be excluded. Any such 2186 entries appearing in the list will be ignored.</p> 2187 2188 <p>If the ancillary PNG <code>tRNS</code> chunk is excluded and the 2189 image has transparency, the PNG colortype is forced to be 4 or 6 2190 (GRAY_ALPHA or RGBA). If the image is not transparent, then the 2191 <code>tRNS</code> chunk isn't written anyhow, and there is no effect 2192 on the PNG colortype of the output image.</p> 2193 2194 <p>The <a href="command-line-options.php#strip">-strip</a> option does the equivalent of the 2195 following for PNG output:</p> 2196 2197 <pre> 2198 -define png:exclude-chunk=EXIF,iCCP,iTXt,sRGB,tEXt,zCCP,zTXt,date 2199 </pre> 2200 2201 <p>The default behavior is to include all known PNG ancillary chunks 2202 plus ImageMagick's private <code>vpAg</code> ("virtual page") chunk, 2203 and to exclude all PNG chunks that are unknown to ImageMagick, 2204 regardless of their PNG "copy-safe" status as described in the 2205 PNG specification.</p> 2206 2207 <p>Any chunk names that are not known to ImageMagick are ignored 2208 if they appear in either the "include-chunk" or "exclude-chunk" list. 2209 The ancillary chunks currently known to ImageMagick are 2210 <code>bKGD</code>, <code>cHRM</code>, <code>gAMA</code>, <code>iCCP</code>, 2211 <code>oFFs</code>, <code>pHYs</code>, <code>sRGB</code>, <code>tEXt</code>, 2212 <code>tRNS</code>, <code>vpAg</code>, and <code>zTXt</code>.</p> 2213 2214 <p>You can also put <code>date</code> in the list to include or exclude 2215 the "Date:create" and "Date:modify" text chunks that ImageMagick normally 2216 inserts in the output PNG.</p></td> 2217 </tr> 2218 2219 <tr> 2220 <td>png:preserve-colormap[=<var>true</var>]</td> 2221 <td>Use the existing image->colormap. Normally the PNG encoder will 2222 try to optimize the palette, eliminating unused entries and putting 2223 the transparent colors first. If this flag is set, that behavior 2224 is suppressed.</td> 2225 </tr> 2226 2227 <tr> 2228 <td>png:preserve-iCCP[=<var>true</var>]</td> 2229 <td>By default, the PNG decoder and encoder examine any ICC profile 2230 that is present, either from an <code>iCCP</code> chunk in the PNG 2231 input or supplied via an option, and if the profile is recognized 2232 to be the sRGB profile, converts it to the <code>sRGB</code> chunk. 2233 You can use <code>-define png:preserve-iCCP</code> to prevent 2234 this from happening; in such cases the <code>iCCP</code> chunk 2235 will be read or written and no <code>sRGB</code> chunk will be 2236 written. There are some ICC profiles that claim to be sRGB but 2237 have various errors that cause them to be rejected by libpng16; such 2238 profiles are recognized anyhow and converted to the <code>sRGB</code> 2239 chunk, but are rejected if the <code>-define png:preserve-iCCP</code> 2240 is present. Note that not all "sRGB" ICC profiles are recognized 2241 yet; we will add them to the list as we encounter them.</td> 2242 </tr> 2243 2244 <tr> 2245 <td>png:swap-bytes[=<var>true</var>]</td> 2246 <td>The PNG specification requires that any multi-byte integers be stored in 2247 network byte order (MSB-LSB endian). This option allows you to 2248 fix any invalid PNG files that have 16-bit samples stored incorrectly 2249 in little-endian order (LSB-MSB). The "-define png:swap-bytes" option 2250 must appear before the input filename on the commandline. The swapping 2251 is done during the libpng decoding operation.</td> 2252 </tr> 2253 2254 <tr> 2255 <td>profile:skip=<var>name1,name2,...</var></td> 2256 <td>Skip the named profile[s] when reading the image. Use skip="*" to 2257 skip all named profiles in the image. Many named profiles exist, 2258 including ICC, EXIF, APP1, IPTC, XMP, and others.</td> 2259 </tr> 2260 2261 <tr> 2262 <td>ps:imagemask</td> 2263 <td>If the ps:imagemask flag is defined, the PS3 and EPS3 coders will 2264 create Postscript files that render bilevel images with the Postscript 2265 imagemask operator instead of the image operator.</td> 2266 </tr> 2267 2268 <tr> 2269 <td>psd:alpha-unblend=off</td> 2270 <td>Disables new automatic un-blending of transparency with the base image 2271 for the flattened layer 0 before adding the alpha channel to the output 2272 image. This define must be placed before the input psd image. (Available 2273 as of IM 6.9.2.5). The automatic un-blending is new to IM 6.9.2.5 and 2274 prevents the transparency from being applied twice in the output 2275 image.</td> 2276 </tr> 2277 2278 <tr> 2279 <td>quantum:format=<var>type</var></td> 2280 <td>Set the type to <code>floating-point</code> to specify a floating-point 2281 format for raw files (e.g. GRAY:) or for MIFF and TIFF images in HDRI mode 2282 to preserve negative values. If <a href="command-line-options.php#depth">-depth</a> 16 is 2283 included, the result is a single precision floating point format. 2284 If <a href="command-line-options.php#depth">-depth</a> 32 is included, the result is 2285 double precision floating point format.</td> 2286 </tr> 2287 2288 <tr> 2289 <td>quantum:polarity=<var>photometric-interpretation</var></td> 2290 <td>Set the photometric-interpretation of an image (typically for TIFF image 2291 file format) to either <code>min-is-black</code> (default) or 2292 <code>min-is-white</code>.</td> 2293 </tr> 2294 2295 <tr> 2296 <td>sample:offset=<var>geometry</var></td> 2297 <td>Location of the sampling point within the sub-region being sampled, 2298 expressed as percentages (see <a href="command-line-options.php#sample" >-sample</a>).</td> 2299 </tr> 2300 2301 <tr> 2302 <td>showkernel=<var>1</var></td> 2303 <td>Outputs (to 'standard error') all the information about a generated <a 2304 href="command-line-options.php#morphology" >-morphology</a> kernel.</td> 2305 </tr> 2306 2307 <tr> 2308 <td>stream:buffer-size=<var>value</var></td> 2309 <td>Set the stream buffer size. Select 0 for unbuffered I/O.</td> 2310 </tr> 2311 2312 <tr> 2313 <td>tiff:alpha=<var>associated|unassociated|unspecified</var></td> 2314 <td>Specify the alpha extra samples as associated, unassociated or unspecified </td> 2315 </tr> 2316 2317 <tr> 2318 <td>tiff:endian=<var>msb|lsb</var></td> 2319 <td> </td> 2320 </tr> 2321 2322 <tr> 2323 <td>tiff:exif-properties=<var>false</var></td> 2324 <td>Skips reading the EXIF properties.</td> 2325 </tr> 2326 2327 <tr> 2328 <td>tiff:fill-order=<var>msb|lsb</var></td> 2329 <td> </td> 2330 </tr> 2331 2332 <tr> 2333 <td>tiff:ignore-layers=<var>true</var></td> 2334 <td>Ignores the photoshop layers.</td> 2335 </tr> 2336 2337 <tr> 2338 <td>tiff:ignore-tags=<var>comma-separate-list-of-tag-IDs</var></td> 2339 <td>Allows one or more tag ID values to be ignored.</td> 2340 </tr> 2341 2342 <tr> 2343 <td>tiff:rows-per-strip=<var>value</var></td> 2344 <td>Sets the number of rows per strip</td> 2345 </tr> 2346 2347 <tr> 2348 <td>tiff:tile-geometry=<var>WxH</var></td> 2349 <td>Sets the tile size for pyramid tiffs. Requires the suffix 2350 PTIF: before the outputname</td> 2351 </tr> 2352 </table> 2353 2354 <p>For example, to create a postscript file that will render only the black 2355 pixels of a bilevel image, use:</p> 2356 2357 <pre> 2358 convert bilevel.tif -define ps:imagemask eps3:stencil.ps 2359 </pre> 2360 2361 <p>Set attributes of the image registry by prefixing the value with 2362 <code>registry:</code>. For example, to set a temporary path to put work files, 2363 use:</p> 2364 2365 <pre> 2366 -define registry:temporary-path=/data/tmp 2367 </pre> 2368 2369 <div style="margin: auto;"> 2370 <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> 2371 </div> 2372 2373 <p class="magick-description">display the next image after pausing.</p> 2374 2375 <p>This option is useful for regulating the animation of image sequences 2376 <var>ticks/ticks-per-second</var> seconds must expire before the display of the 2377 next image. The default is no delay between each showing of the image 2378 sequence. The default ticks-per-second is 100.</p> 2379 2380 <p>Use <code>></code> to change the image delay <var>only</var> if its current 2381 value exceeds the given delay. <code><</code> changes the image delay 2382 <var>only</var> if current value is less than the given delay. For example, if 2383 you specify <code>30></code> and the image delay is 20, the image delay does 2384 not change. However, if the image delay is 40 or 50, the delay it is changed 2385 to 30. Enclose the given delay in quotation marks to prevent the 2386 <code><</code> or <code>></code> from being interpreted by your shell as 2387 a file redirection.</p> 2388 2389 2390 <div style="margin: auto;"> 2391 <h3 class="magick-header"><a id="delete"></a>-delete <var>indexes</var></h3> 2392 </div> 2393 2394 <p class="magick-description">delete the images specified by index, from the image sequence.</p> 2395 2396 <p>Specify the image by its index in the sequence. The first image is index 2397 0. Negative indexes are relative to the end of the sequence, for example, -1 2398 represents the last image of the sequence. Specify a range of images with 2399 a dash (e.g. 0-4). Separate indexes with a comma (e.g. 0,2). Use 2400 <code>+delete</code> to delete the last image in the current image sequence.</p> 2401 2402 2403 <div style="margin: auto;"> 2404 <h3 class="magick-header"><a id="density"></a>-density <var>width</var><br />-density <var>width</var>x<var>height</var></h3> 2405 </div> 2406 2407 <p class="magick-description">Set the horizontal and vertical resolution of an image for rendering to devices.</p> 2408 2409 <p>This option specifies the image resolution to store while encoding a raster 2410 image or the canvas resolution while rendering (reading) vector formats such 2411 as Postscript, PDF, WMF, and SVG into a raster image. Image resolution 2412 provides the unit of measure to apply when rendering to an output device or 2413 raster image. The default unit of measure is in dots per inch (DPI). The <a 2414 href="command-line-options.php#units">-units</a> option may be used to select dots per centimeter 2415 instead.</p> 2416 2417 <p>The default resolution is 72 dots per inch, which is equivalent to one 2418 point per pixel (Macintosh and Postscript standard). Computer screens are 2419 normally 72 or 96 dots per inch, while printers typically support 150, 300, 2420 600, or 1200 dots per inch. To determine the resolution of your display, use 2421 a ruler to measure the width of your screen in inches, and divide by the 2422 number of horizontal pixels (1024 on a 1024x768 display).</p> 2423 2424 <p>If the file format supports it, this option may be used to update the 2425 stored image resolution. Note that Photoshop stores and obtains image 2426 resolution from a proprietary embedded profile. If this profile is not 2427 stripped from the image, then Photoshop will continue to treat the image using 2428 its former resolution, ignoring the image resolution specified in the standard 2429 file header.</p> 2430 2431 <p>The <a href="command-line-options.php#density">-density</a> option sets an <var>attribute</var> and 2432 does not alter the underlying raster image. It may be used to adjust the 2433 rendered size for desktop publishing purposes by adjusting the scale applied 2434 to the pixels. To resize the image so that it is the same size at a different 2435 resolution, use the <a href="command-line-options.php#resample">-resample</a> option.</p> 2436 2437 <div style="margin: auto;"> 2438 <h3 class="magick-header"><a id="depth"></a>-depth <var>value</var></h3> 2439 </div> 2440 2441 <p class="magick-description">depth of the image.</p> 2442 2443 <p>This the number of bits in a color sample within a pixel. Use this option 2444 to specify the depth of raw images whose depth is unknown such as GRAY, RGB, 2445 or CMYK, or to change the depth of any image after it has been read.</p> 2446 2447 <div style="margin: auto;"> 2448 <h3 class="magick-header"><a id="descend"></a>-descend</h3> 2449 </div> 2450 2451 <p class="magick-description">obtain image by descending window hierarchy.</p> 2452 2453 <div style="margin: auto;"> 2454 <h3 class="magick-header"><a id="deskew"></a>-deskew <var>threshold{%}</var></h3> 2455 </div> 2456 2457 <p class="magick-description">straighten an image. A threshold of 40% works for most images.</p> 2458 2459 <p>Use <a href="command-line-options.php#set">-set</a> <code>option:deskew:auto-crop 2460 <var>width</var></code> to auto crop the image. The set argument is the pixel 2461 width of the image background (e.g 40).</p> 2462 2463 <div style="margin: auto;"> 2464 <h3 class="magick-header"><a id="despeckle"></a>-despeckle</h3> 2465 </div> 2466 2467 <p class="magick-description">reduce the speckles within an image.</p> 2468 2469 <div style="margin: auto;"> 2470 <h3 class="magick-header"><a id="direction"></a>-direction <var>type</var></h3> 2471 </div> 2472 2473 <p class="magick-description">render text right-to-left or left-to-right.</p> 2474 2475 <div style="margin: auto;"> 2476 <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> 2477 </div> 2478 2479 <p class="magick-description">shift image pixels as defined by a displacement map.</p> 2480 2481 <p>With this option, the 'overlay' image, and optionally the 'mask' image, 2482 is used as a displacement map, which is used to displace the lookup of 2483 what part of the 'background' image is seen at each point of the overlaid 2484 area. Much like the displacement map is a 'lens' that redirects light shining 2485 through it so as to present a distorted view the original 'background' image 2486 behind it. </p> 2487 2488 <p>Any perfect grey areas of the displacement map produce a zero 2489 displacement of the image. Black areas produce the given maximum negative 2490 displacement of the lookup point, while white produce a maximum positive 2491 displacement of the lookup. </p> 2492 2493 <p>Note that it is the lookup of the 'background' that is displaced, not a 2494 displacement of the image itself. As such an area of the displacement map 2495 containing 'white' will have the lookup point 'shifted' by a positive amount, 2496 and thus generating a copy of the destination image to the right/downward from 2497 the correct position. That is the image will look like it may have been 2498 'shifted' in a negative left/upward direction. Understanding this is a very 2499 important in understanding how displacement maps work. </p> 2500 2501 <p>The given arguments define the maximum amount of displacement in pixels 2502 that a particular map can produce. If the displacement scale is large enough 2503 it is also possible to lookup parts of the 'background' image that lie well 2504 outside the bounds of the displacement map itself. That is you could very 2505 easily copy a section of the original image from outside the overlay area 2506 into the overlay area. </p> 2507 2508 <p>The '%' flag makes the displacement scale relative to the size of the 2509 overlay image (100% = half width/height of image). Using '!' switches 2510 percentage arguments to refer to the destination image size instead. 2511 these flags were added as of IM v6.5.3-5.</p> 2512 2513 <p>Normally a single grayscale displacement map is provided, which with the 2514 given scaling values will determine a single direction (vector) in which 2515 displacements can occur (positively or negatively). However, if you also 2516 specify a third image which is normally used as a <var>mask</var>, 2517 the <var>composite image</var> is used for horizontal X 2518 displacement, while the <var>mask image</var> is used for vertical Y 2519 displacement. This allows you to define completely different displacement 2520 values for the X and Y directions, and allowing you to lookup any point within 2521 the <var>scale</var> bounds. In other words each pixel can lookup 2522 any other nearby pixel, producing complex 2 dimensional displacements, rather 2523 than a simple 1 dimensional vector displacements. </p> 2524 2525 <p>Alternatively rather than supplying two separate images, as of IM v6.4.4-0, 2526 you can use the 'red' channel of the overlay image to specify the horizontal 2527 or X displacement, and the 'green' channel for the vertical or Y displacement. 2528 </p> 2529 2530 <p>As of IM v6.5.3-5 any alpha channel in the overlay image is used as a 2531 mask the transparency of the destination image. However areas outside the 2532 overlaid areas will not be effected. </p> 2533 2534 2535 <div style="margin: auto;"> 2536 <h3 class="magick-header"><a id="display"></a>-display <var>host:display[.screen]</var></h3> 2537 </div> 2538 2539 <p class="magick-description">Specifies the X server to contact.</p> 2540 2541 <p>This option is used with convert for obtaining image or font from this 2542 X server. See <var>X(1)</var>.</p> 2543 2544 <div style="margin: auto;"> 2545 <h3 class="magick-header"><a id="dispose"></a>-dispose <var>method</var></h3> 2546 </div> 2547 2548 <p class="magick-description">define the GIF disposal image setting for images that are being created or read in. </p> 2549 2550 <p>The layer disposal method defines the way each the displayed image is to be 2551 modified after the current 'frame' of an animation has finished being 2552 displayed (after its 'delay' period), but before the next frame on an 2553 animation is to be overlaid onto the display. </p> 2554 2555 <p>Here are the valid methods:</p> 2556 2557 <dl class="dl-horizontal"> 2558 <dt>Undefined</dt><dd>0: No disposal specified (equivalent to '<code>none</code>').</dd> 2559 <dt>None</dt><dd>1: Do not dispose, just overlay next frame image.</dd> 2560 <dt>Background</dt><dd>2: Clear the frame area with the background color.</dd> 2561 <dt>Previous</dt><dd>3: Clear to the image prior to this frames overlay.</dd> 2562 </dl> 2563 2564 <p>You can also use the numbers given above, which is what the GIF format 2565 uses internally to represent the above settings. </p> 2566 2567 <p>To print a complete list of dispose methods, use <a href="command-line-options.php#list">-list dispose</a>.</p> 2568 2569 <p>Use <a href="command-line-options.php#dispose" >+dispose</a>, turn off the setting and prevent 2570 resetting the layer disposal methods of images being read in. </p> 2571 2572 <p>Use <a href="command-line-options.php#set">-set</a> '<code>dispose</code>' method to set the image 2573 disposal method for images already in memory.</p> 2574 2575 <div style="margin: auto;"> 2576 <h3 class="magick-header"><a id="dissimilarity-threshold"></a>-dissimilarity-threshold <var>value</var></h3> 2577 </div> 2578 2579 <p class="magick-description">maximum RMSE for subimage match (default 0.2).</p> 2580 2581 2582 <div style="margin: auto;"> 2583 <h3 class="magick-header"><a id="dissolve"></a>-dissolve <var>src_percent</var>[x<var>dst_percent</var>]</h3> 2584 </div> 2585 2586 <p class="magick-description">dissolve an image into another by the given percent.</p> 2587 2588 <p>The opacity of the composite image is multiplied by the given percent, then 2589 it is composited 'over' the main image. If <var>src_percent</var> 2590 is greater than 100, start dissolving the main image so it becomes 2591 transparent at a value of '<code>200</code>'. If both percentages 2592 are given, each image are dissolved to the percentages given. </p> 2593 2594 <p>Note that dissolve percentages do not add, two opaque images dissolved 2595 '50,50', produce a 75% transparency. For a 50% + 50% blending of the two 2596 images, you would need to use dissolve values of '50,100'. </p> 2597 2598 <div style="margin: auto;"> 2599 <h3 class="magick-header"><a id="distort"></a>-distort <var>method arguments</var></h3> 2600 </div> 2601 2602 <p class="magick-description">distort an image, using the given <var>method</var> and its required <var>arguments</var>.</p> 2603 2604 <p>The <var>arguments</var> is a single string containing a list 2605 of floating point numbers separated by commas or spaces. The number of 2606 and meaning of the floating point values depends on the distortion <var>method</var> being used. </p> 2607 2608 <p>Choose from these distortion types:</p> 2609 2610 <table class="table table-condensed table-striped"> 2611 <tr> 2612 <th style="width: 8%">Method</th> 2613 <th>Description</th> 2614 </tr> 2615 2616 <tr> 2617 <td>ScaleRotateTranslate <br/> SRT</td> 2618 <td> 2619 Distort image by first scaling and rotating about a given 'center', 2620 before translating that 'center' to the new location, in that order. It 2621 is an alternative method of specifying a 'Affine' type of 2622 distortion, but without shearing effects. It also provides a good way 2623 of rotating and displacing a smaller image for tiling onto a larger 2624 background (IE 2-dimensional animations). <br/> 2625 2626 The number of arguments determine the specific meaning of each 2627 argument for the scales, rotation, and translation operations. <br/> 2628 2629 <dl class="dl-horizontal"> 2630 <dt>2:</dt><dd><var>Scale Angle</var></dd> 2631 <dt>3:</dt><dd><var>X,Y Angle</var></dd> 2632 <dt>4:</dt><dd><var>X,Y Scale Angle</var></dd> 2633 <dt>5:</dt> <dd><var>X,Y ScaleX,ScaleY Angle</var></dd> 2634 <dt>6:</dt> <dd><var>X,Y Scale Angle NewX,NewY</var></dd> 2635 <dt>7:</dt> <dd><var>X,Y ScaleX,ScaleY Angle NewX,NewY</var></dd> 2636 </dl> 2637 2638 This is actually an alternative way of specifying a 2 dimensional linear 2639 'Affine' or 'AffineProjection' distortion. </td> </tr> 2640 2641 <tr> 2642 <td>Affine</td> 2643 <td> 2644 Distort the image linearly by moving a list of at least 3 or more sets 2645 of control points (as defined below). Ideally 3 sets or 12 floating 2646 point values are given allowing the image to be linearly scaled, 2647 rotated, sheared, and translated, according to those three points. See 2648 also the related 'AffineProjection' and 'SRT' 2649 distortions. <br/> 2650 2651 More than 3 sets given control point pairs (12 numbers) is least 2652 squares fitted to best match a linear affine distortion. If only 2 2653 control point pairs (8 numbers) are given a two point image translation 2654 rotation and scaling is performed, without any possible shearing, 2655 flipping or changes in aspect ratio to the resulting image. If only one 2656 control point pair is provides the image is only translated, (which may 2657 be a floating point non-integer translation). <br/> 2658 2659 This distortion does not include any form of perspective distortion. 2660 </td> 2661 2662 </tr> 2663 2664 <tr> 2665 <td>AffineProjection</td> 2666 <td> 2667 Linearly distort an image using the given Affine Matrix of 6 2668 pre-calculated coefficients forming a set of Affine Equations to map 2669 the source image to the destination image. 2670 2671 <p class="text-center"><var> 2672 s<sub>x</sub>, r<sub>x</sub>, 2673 r<sub>y</sub>, s<sub>y</sub>, 2674 t<sub>x</sub>, t<sub>y</sub> 2675 </var></p> 2676 2677 See <a href="command-line-options.php#affine" >-affine</a> setting for more detail, and 2678 meanings of these coefficients. <br/> 2679 2680 The distortions 'Affine' and 'SRT' provide 2681 alternative methods of defining this distortion, with ImageMagick doing 2682 the calculations needed to generate the required coefficients. You can 2683 see the internally generated coefficients, by using a <a 2684 href="command-line-options.php#verbose" >-verbose</a> setting with those other variants. </td> 2685 2686 </tr> 2687 2688 <tr> 2689 <td>BilinearForward<br/> 2690 BilinearReverse</td> 2691 <td> 2692 Bilinear Distortion, given a minimum of 4 sets of coordinate pairs, or 2693 16 values (see below). Not that lines may not appear straight after 2694 distortion, though the distance between coordinates will remain 2695 consistent. <br/> 2696 2697 The 'BilinearForward' is used to map rectangles to any 2698 quadrilateral, while the 'BilinearReverse' form maps any 2699 quadrilateral to a rectangle, while preserving the straight line edges 2700 in each case. <br/> 2701 2702 Note that 'BilinearForward' can generate invalid pixels 2703 which will be colored using the <a href="command-line-options.php#mattecolor" >-mattecolor</a> 2704 color setting. Also if the quadrilateral becomes 'flipped' the image 2705 may disappear. <br/> 2706 2707 There are future plans to produce a true Bilinear distortion that will 2708 attempt to map any quadrilateral to any other quadrilateral, while 2709 preserving edges (and edge distance ratios). 2710 2711 </td> 2712 </tr> 2713 2714 <tr> 2715 <td>Perspective</td> 2716 <td> 2717 Perspective distort the images, using a list of 4 or more sets of 2718 control points (as defined below). More that 4 sets (16 numbers) of 2719 control points provide least squares fitting for more accurate 2720 distortions (for the purposes of image registration and panorama 2721 effects). Less than 4 sets will fall back to a 'Affine' 2722 linear distortion. <br/> 2723 2724 Perspective Distorted images ensures that straight lines remain 2725 straight, but the scale of the distorted image will vary. The horizon 2726 is anti-aliased, and the 'sky' color may be set using the 2727 <a href="command-line-options.php#mattecolor" >-mattecolor</a> setting. </td> 2728 </tr> 2729 2730 <tr> 2731 <td>PerspectiveProjection </td> 2732 <td> 2733 Do a 'Perspective' distortion biased on a set of 8 2734 pre-calculated coefficients. You can get these coefficients by looking 2735 at the <a href="command-line-options.php#verbose" >-verbose</a> output of a 2736 'Perspective' distortion, or by calculating them yourself. 2737 If the last two perspective scaling coefficients are zero, the 2738 remaining 6 represents a transposed 'Affine Matrix'. </td> 2739 2740 </tr> 2741 2742 <tr> 2743 <td>Arc</td> 2744 <td> 2745 Arc the image (variation of polar mapping) over the angle given around 2746 a circle. 2747 2748 <p><dl class="dl-horizontal"> 2749 <dt>arc_angle</dt> 2750 <dd>The angle over which to arc the image side-to-side</dd> 2751 <dt>rotate_angle</dt> 2752 <dd>Angle to rotate resulting image from vertical center</dd> 2753 <dt>top_radius</dt> 2754 <dd>Set top edge of source image at this radius</dd> 2755 <dt>bottom_radius </dt> 2756 <dd>Set bottom edge to this radius (radial scaling)</dd> 2757 </dl></p> 2758 2759 The resulting image is always resized to best fit the resulting image, 2760 (as if using <a href="command-line-options.php#distort" >+distort</a>) while attempting to 2761 preserve scale and aspect ratio of the original image as much as 2762 possible with the arguments given by the user. All four arguments will 2763 be needed to change the overall aspect ratio of an 'Arc'ed image. <br/> 2764 2765 This a variation of a polar distortion designed to try to preserve the 2766 aspect ratio of the image rather than direct Cartesian to Polar 2767 conversion. </td> 2768 </tr> 2769 2770 <tr> 2771 <td>Polar</td> 2772 <td> 2773 Like 'Arc' but do a complete Cartesian to Polar mapping of 2774 the image. that is the height of the input image is mapped to the 2775 radius limits, while the width is wrapped around between the 2776 angle limits. <br/> 2777 2778 Arguments: <var>Rmax,Rmin CenterX,CenterY, start,end_angle</var> <br/> 2779 2780 All arguments are optional. With <var>Rmin</var> defaulting to zero, the 2781 center to the center of the image, and the angles going from -180 (top) 2782 to +180 (top). If <var>Rmax</var> is given the special value of 2783 '0', the the distance from the center to the nearest edge 2784 is used for the radius of the output image, which will ensure the whole 2785 image is visible (though scaled smaller). However a special value of 2786 '-1' will use the distance from the center to the furthest 2787 corner, This may 'clip' the corners from the input rectangular image, 2788 but will generate the exact reverse of a 'DePolar' with 2789 the same arguments. <br/> 2790 2791 If the plus form of distort (<a href="command-line-options.php#distort" >+distort</a>) is used 2792 output image center will default to 0,0 of the virtual 2793 canvas, and the image size adjusted to ensure the whole input image is 2794 made visible in the output image on the virtual canvas. </td> 2795 2796 </tr> 2797 2798 <tr> 2799 <td>DePolar</td> 2800 <td> 2801 Uses the same arguments and meanings as a 'Polar' distortion 2802 but generates the reverse Polar to Cartesian distortion. <br/> 2803 2804 The special <var>Rmax</var> setting of '0' may however clip 2805 the corners of the input image. However using the special 2806 <var>Rmax</var> setting of '-1' (maximum center to corner 2807 distance) will ensure the whole distorted image is preserved in the 2808 generated result, so that the same argument to 'Polar' will 2809 reverse the distortion re-producing the original. 2810 2811 Note that as this distortion requires the area resampling of a circular 2812 arc, which can not be handled by the builtin EWA resampling function. 2813 As such the normal EWA filters are turned off. It is recommended some 2814 form of 'super-sampling' image processing technique be used to produce 2815 a high quality result. </td> 2816 2817 </tr> 2818 2819 <tr> 2820 <td>Barrel</td> 2821 <td> 2822 Given the four coefficients (A,B,C,D) as defined by <a 2823 href="http://wiki.panotools.org/Lens_correction_model" >Helmut 2824 Dersch</a>, perform a barrel or pin-cushion distortion appropriate to 2825 correct radial lens distortions. That is in photographs, make straight 2826 lines straight again. <br/> 2827 2828 <p class="text-center">Arguments: <var>A B C</var> [ <var>D</var> [ 2829 <var>X</var> , <var>Y</var> ] ] <br/> 2830 or <var>A<sub>x</sub> B<sub>x</sub> C<sub>x</sub> D<sub>x</sub> 2831 A<sub>y</sub> B<sub>y</sub> C<sub>y</sub> D<sub>y</sub></var> 2832 [ <var>X</var> , <var>Y</var> ] </p> 2833 So that it forms the function 2834 <p class="text-center">Rsrc = r * ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> + 2835 <var>C</var>*r + <var>D</var> )</p> 2836 2837 Where <var>X</var>,<var>Y</var> is the optional center of the distortion 2838 (defaulting to the center of the image). <br/> 2839 The second form is typically used to distort images, rather than 2840 correct lens distortions. <br/> 2841 </td> 2842 2843 </tr> 2844 2845 <tr> 2846 <td>BarrelInverse</td> 2847 <td> 2848 This is very similar to 'Barrel' with the same set of 2849 arguments, and argument handling. However it uses the inverse 2850 of the radial polynomial, 2851 so that it forms the function 2852 <p class="text-center">Rsrc = r / ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> + 2853 <var>C</var>*r + <var>D</var> )</p> 2854 Note that this is not the reverse of the 'Barrel' 2855 distortion, just a different barrel-like radial distortion method. 2856 2857 </td> 2858 </tr> 2859 2860 <tr> 2861 <td>Shepards</td> 2862 <td> 2863 Distort the given list control points (any number) using an Inverse 2864 Squared Distance Interpolation Method (<a 2865 href="http://en.wikipedia.org/wiki/Shepard%27s_method" >Shepards 2866 Method</a>). The control points in effect do 'localized' displacement 2867 of the image around the given control point (preserving the look and 2868 the rotation of the area near the control points. For best results 2869 extra control points should be added to 'lock' the positions of the 2870 corners, edges and other unchanging parts of the image, to prevent 2871 their movement. <br/> 2872 2873 The distortion has been likened to 'taffy pulling' using nails, or 2874 pins' stuck in a block of 'jelly' which is then moved to the new 2875 position, distorting the surface of the jelly. <br/> 2876 2877 Internally it is equivalent to generating a displacement map (see <a 2878 href="command-line-options.php#displace" >-displace</a>) for source image color look-up using 2879 the <a href="command-line-options.php#sparse-color" >-sparse-color</a> method of the same name. 2880 2881 </td> 2882 </tr> 2883 2884 </table> 2885 2886 <p>To print a complete list of distortion methods, use <a href="command-line-options.php#list">-list 2887 distort</a>.</p> 2888 2889 <p>Many of the above distortion methods such as '<code>Affine</code>', 2890 '<code>Perspective</code>', and '<code>Shepards</code>' use a list control points 2891 defining how these points in the given image should be distorted in the 2892 destination image. Each set of four floating point values represent a source 2893 image coordinate, followed immediately by the destination image coordinate. 2894 This produces a list of values such as...</p> 2895 <p class="text-center"><var> 2896 U<sub>1</sub>,V<sub>1</sub> X<sub>1</sub>,Y<sub>1</sub> 2897 U<sub>2</sub>,V<sub>2</sub> X<sub>2</sub>,Y<sub>2</sub> 2898 U<sub>3</sub>,V<sub>3</sub> X<sub>3</sub>,Y<sub>3</sub> 2899 ... 2900 U<sub>n</sub>,V<sub>n</sub> X<sub>n</sub>,Y<sub>n</sub> 2901 </var></p> 2902 <p>where <var>U,V</var> on the source image is mapped to <var>X,Y</var> on the 2903 destination image. </p> 2904 2905 <p>For example, to warp an image using '<code>perspective</code>' distortion, 2906 needs a list of at least 4 sets of coordinates, or 16 numbers. Here is the 2907 perspective distortion of the built-in "rose:" image. Note how spaces were 2908 used to group the 4 sets of coordinate pairs, to make it easier to read and 2909 understand.</p> 2910 2911 <pre> 2912 convert rose: -virtual-pixel black \ 2913 -distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35' \ 2914 rose_3d_rotated.gif" 2915 </pre> 2916 2917 <p>If more that the required number of coordinate pairs are given for 2918 a distortion, the distortion method is 'least squares' fitted to produce the 2919 best result for all the coordinate pairs given. If less than the ideal number 2920 of points are given, the distort will generally fall back to a simpler form of 2921 distortion that can handles the smaller number of coordinates (usually a linear 2922 '<code>Affine</code>' distortion). </p> 2923 2924 <p>By using more coordinates you can make use of image registration tool to 2925 find matching coordinate pairs in overlapping images, so as to improve the 2926 'fit' of the distortion. Of course a bad coordinate pair can also make the 2927 'fit' worse. Caution is always advised. </p> 2928 2929 <p>Colors are acquired from the source image according to a cylindrical 2930 resampling <a href="command-line-options.php#filter" >-filter</a>, using a special technique known as 2931 EWA resampling. This produces very high quality results, especially when 2932 images become smaller (minified) in the output, which is very common when 2933 using '<code>perspective</code>' distortion. For example here we view 2934 a infinitely tiled 'plane' all the way to the horizon. </p> 2935 2936 <pre> 2937 convert -size 90x90 pattern:checkerboard -normalize -virtual-pixel tile \ 2938 -distort perspective '0,0,5,45 89,0,45,46 0,89,0,89 89,89,89,89' \ 2939 checks_tiled.jpg 2940 </pre> 2941 2942 <p>Note that a infinitely tiled perspective images involving the horizon can 2943 be very slow, because of the number of pixels that are compressed to generate 2944 each individual pixel close to the 'horizon'. You can turn off EWA 2945 resampling, by specifying the special <a href="command-line-options.php#filter" >-filter</a> setting of 2946 '<code>point</code>' (recommended if you plan to use super-sampling instead). 2947 </p> 2948 2949 <p>If an image generates <i>invalid pixels</i>, such as the 'sky' in the last 2950 example, <a href="command-line-options.php#distort" >-distort</a> will use the current <a 2951 href="command-line-options.php#mattecolor" >-mattecolor</a> setting for these pixels. If you do not 2952 what these pixels to be visible, set the color to match the rest of the 2953 ground. </p> 2954 2955 <p>The output image size will by default be the same as the input image. This 2956 means that if the part of the distorted image falls outside the viewed area of 2957 the 'distorted space', those parts is clipped and lost. However if you use 2958 the plus form of the operator (<a href="command-line-options.php#distort" >+distort</a>) the operator 2959 will attempt (if possible) to show the whole of the distorted image, while 2960 retaining a correct 'virtual canvas' offset, for image layering. This offset 2961 may need to be removed using <a href="command-line-options.php#repage" >+repage</a>, to remove if it 2962 is unwanted. </p> 2963 2964 <p>Setting <a href="command-line-options.php#verbose" >-verbose</a> setting, will cause <a 2965 href="command-line-options.php#distort" >-distort</a> to attempt to output the internal coefficients, 2966 and the <a href="command-line-options.php#fx" >-fx</a> equivalent to the distortion, for expert study, 2967 and debugging purposes. This many not be available for all distorts. </p> 2968 2969 <p>You can alternatively specify a special "<code><a href="command-line-options.php#define" 2970 >-define</a> distort:viewport={geometry_string}</code>" setting which will 2971 specify the size and the offset of the generated 'viewport' image of the 2972 distorted image space.</p> 2973 2974 <p>Setting a "<code><a href="command-line-options.php#define" >-define</a> 2975 distort:scale=<var>scale_factor</var></code>" will scale the output image (viewport or 2976 otherwise) by that factor without changing the viewed contents of the 2977 distorted image. This can be used either for 'super-sampling' the image for 2978 a higher quality result, or for panning and zooming around the image (with 2979 appropriate viewport changes, or post-distort cropping and resizing). </p> 2980 2981 <p>Setting "<code><a href="command-line-options.php#define" >-define</a> resample:verbose=1</code>" 2982 will output the cylindrical filter lookup table created by the EWA (Elliptical 2983 Weighted Average) resampling algorithm. Note this table uses a squared radius 2984 lookup value. This is typically only used for debugging EWA resampling. </p> 2985 2986 2987 <div style="margin: auto;"> 2988 <h3 class="magick-header"><a id="distribute-cache"></a>-distribute-cache <var>port</var></h3> 2989 </div> 2990 2991 <p class="magick-description">launch a distributed pixel cache server. </p> 2992 2993 <div style="margin: auto;"> 2994 <h3 class="magick-header"><a id="dither"></a>-dither <var>method</var></h3> 2995 </div> 2996 2997 <p class="magick-description">Apply a Riemersma or Floyd-Steinberg error diffusion dither to 2998 images when general color reduction is applied via an option, or automagically 2999 when saving to specific formats. This enabled by default.</p> 3000 3001 <p>Dithering places two or more colors in neighboring pixels so that to the 3002 eye a closer approximation of the images original color is reproduced. This 3003 reduces the number of colors needed to reproduce the image but at the cost of 3004 a lower level pattern of colors. Error diffusion dithers can use any set of 3005 colors (generated or user defined) to an image. </p> 3006 3007 <p>Dithering is turned on by default, to turn it off use the plus form of the 3008 setting, <a href="command-line-options.php#dither">+dither</a>. This will also also render PostScript 3009 without text or graphic aliasing. Disabling dithering often (but not always) 3010 leads to faster process, a smaller number of colors, but more cartoon like 3011 image coloring. Generally resulting in 'color banding' effects in areas with 3012 color gradients. </p> 3013 3014 <p>The color reduction operators <a href="command-line-options.php#colors">-colors</a>, <a 3015 href="command-line-options.php#monochrome">-monochrome</a>, <a href="command-line-options.php#remap ">-remap</a>, and <a 3016 href="command-line-options.php#posterize">-posterize</a>, apply dithering to images using the reduced 3017 color set they created. These operators are also used as part of automatic 3018 color reduction when saving images to formats with limited color support, such 3019 as <code>GIF:</code>, <code>XBM:</code>, and others, so dithering may also be used 3020 in these cases. </p> 3021 3022 <p>Alternatively you can use <a href="command-line-options.php#random-threshold">-random-threshold</a> 3023 to generate purely random dither. Or use <a 3024 href="command-line-options.php#ordered-dither">-ordered-dither</a> to apply threshold mapped dither 3025 patterns, using uniform color maps, rather than specific color maps. </p> 3026 3027 3028 <div style="margin: auto;"> 3029 <h3 class="magick-header"><a id="draw"></a>-draw <var>string</var></h3> 3030 </div> 3031 3032 <p class="magick-description">Annotate an image with one or more graphic primitives.</p> 3033 3034 <p>Use this option to annotate or decorate an image with one or more graphic 3035 primitives. The primitives include shapes, text, transformations, and pixel 3036 operations.</p> 3037 3038 <p>The shape primitives:</p> 3039 3040 <dl class="dl-horizontal"> 3041 <dt>point</dt><dd> x,y</dd> 3042 <dt>line</dt><dd> x0,y0 x1,y1</dd> 3043 <dt>rectangle</dt><dd> x0,y0 x1,y1</dd> 3044 <dt>roundRectangle</dt><dd> x0,y0 x1,y1 wc,hc</dd> 3045 <dt>arc</dt><dd> x0,y0 x1,y1 a0,a1</dd> 3046 <dt>ellipse</dt><dd> x0,y0 rx,ry a0,a1</dd> 3047 <dt>circle</dt><dd> x0,y0 x1,y1</dd> 3048 <dt>polyline</dt><dd> x0,y0 ... xn,yn</dd> 3049 <dt>polygon</dt><dd> x0,y0 ... xn,yn</dd> 3050 <dt>bezier</dt><dd> x0,y0 ... xn,yn</dd> 3051 <dt>path</dt><dd>specification </dd> 3052 <dt>image</dt><dd> operator x0,y0 w,h filename</dd> 3053 </dl> 3054 3055 <p>The text primitive:</p> 3056 3057 <dl class="dl-horizontal"> 3058 <dt>text</dt><dd>x0,y0 string</dd> 3059 </dl> 3060 <p>The text gravity primitive:</p> 3061 3062 <dl class="dl-horizontal"> 3063 <dt>gravity</dt><dd>NorthWest, North, NorthEast, West, Center, East, SouthWest, South, or SouthEast</dd> 3064 </dl> 3065 3066 <p>The text gravity primitive only affects the placement of text and does not 3067 interact with the other primitives. It is equivalent to using the <a 3068 href="command-line-options.php#gravity">-gravity</a> command-line option, except that it is limited in 3069 scope to the <a href="command-line-options.php#draw">-draw</a> option in which it appears.</p> 3070 3071 <p>The transformation primitives:</p> 3072 3073 <dl class="dl-horizontal"> 3074 <dt>rotate</dt><dd>degrees</dd> 3075 <dt>translate</dt><dd>dx,dy</dd> 3076 <dt>scale</dt><dd>sx,sy</dd> 3077 <dt>skewX</dt><dd>degrees</dd> 3078 <dt>skewY</dt><dd>degrees</dd> 3079 </dl> 3080 3081 <p>The pixel operation primitives:</p> 3082 3083 <dl class="dl-horizontal"> 3084 <dt>color</dt><dd>x0,y0 method</dd> 3085 <dt>matte</dt><dd>x0,y0 method</dd> 3086 </dl> 3087 3088 <p>The shape primitives are drawn in the color specified by the preceding <a 3089 href="command-line-options.php#fill">-fill</a> setting. For unfilled shapes, use <a 3090 href="command-line-options.php#fill">-fill none</a>. You can optionally control the stroke (the 3091 "outline" of a shape) with the <a href="command-line-options.php#stroke">-stroke</a> and <a 3092 href="command-line-options.php#strokewidth">-strokewidth</a> settings.</p> 3093 3094 <p>A <code>point</code> primitive is specified by a single <var>point</var> in the 3095 pixel plane, that is, by an ordered pair of integer coordinates, 3096 <var>x</var>,<var>y</var>. (As it involves only a single pixel, a <code>point</code> 3097 primitive is not affected by <a href="command-line-options.php#stroke">-stroke</a> or <a 3098 href="command-line-options.php#strokewidth">-strokewidth</a>.)</p> 3099 3100 <p>A <code>line</code> primitive requires a start point and end point.</p> 3101 3102 <p>A <code>rectangle</code> primitive is specified by the pair of points at the 3103 upper left and lower right corners.</p> 3104 3105 <p>A <code>roundRectangle</code> primitive takes the same corner points as 3106 a <code>rectangle</code> followed by the width and height of the rounded corners 3107 to be removed.</p> 3108 3109 <p>The <code>circle</code> primitive makes a disk (filled) or circle (unfilled). 3110 Give the center and any point on the perimeter (boundary).</p> 3111 3112 <p>The <code>arc</code> primitive is used to inscribe an elliptical segment in 3113 to a given rectangle. An <code>arc</code> requires the two corners used for 3114 <code>rectangle</code> (see above) followed by the start and end angles of the 3115 arc of the segment segment (e.g. 130,30 200,100 45,90). The start and end 3116 points produced are then joined with a line segment and the resulting segment 3117 of an ellipse is filled.</p> 3118 3119 <p>Use <code>ellipse</code> to draw a partial (or whole) ellipse. Give the 3120 center point, the horizontal and vertical "radii" (the <var>semi-axes</var> of 3121 the ellipse) and start and end angles in degrees (e.g. 100,100 100,150 3122 0,360).</p> 3123 3124 <p>The <code>polyline</code> and <code>polygon</code> primitives require three or 3125 more points to define their perimeters. A <code>polyline</code> is simply 3126 a <code>polygon</code> in which the final point is not stroked to the start 3127 point. When unfilled, this is a <var>polygonal line</var>. If the <a 3128 href="command-line-options.php#stroke">-stroke</a> setting is <code>none</code> (the default), then 3129 a <code>polyline</code> is identical to a <code>polygon</code>. </p> 3130 3131 <p>A <var>coordinate</var> is a pair of integers separated by a space or 3132 optional comma. </p> 3133 3134 <p>As an example, to define a circle centered at 100,100 that extends to 3135 150,150 use:</p> 3136 3137 <pre> 3138 -draw 'circle 100,100 150,150' 3139 </pre> 3140 3141 <p>The <code>Bezier</code> primitive creates a spline curve and requires three 3142 or points to define its shape. The first and last points are the 3143 <var>knots</var> and these points are attained by the curve, while any 3144 intermediate coordinates are <var>control points</var>. If two control points 3145 are specified, the line between each end knot and its sequentially respective 3146 control point determines the tangent direction of the curve at that end. If 3147 one control point is specified, the lines from the end knots to the one 3148 control point determines the tangent directions of the curve at each end. If 3149 more than two control points are specified, then the additional control points 3150 act in combination to determine the intermediate shape of the curve. In order 3151 to draw complex curves, it is highly recommended either to use the 3152 <code>path</code> primitive or to draw multiple four-point bezier segments with 3153 the start and end knots of each successive segment repeated. For example:</p> 3154 3155 <pre> 3156 -draw 'bezier 20,50 45,100 45,0 70,50' 3157 -draw 'bezier 70,50 95,100 95,0 120,50' 3158 </pre> 3159 3160 <p>A <code>path</code> represents an outline of an object, defined in terms of 3161 moveto (set a new current point), lineto (draw a straight line), curveto (draw 3162 a Bezier curve), arc (elliptical or circular arc) and closepath (close the 3163 current shape by drawing a line to the last moveto) elements. Compound paths 3164 (i.e., a path with subpaths, each consisting of a single moveto followed by 3165 one or more line or curve operations) are possible to allow effects such as 3166 <var>donut holes</var> in objects. (See <a 3167 href="http://www.w3.org/TR/SVG/paths.html">Paths</a>.)</p> 3168 3169 <p>Use <code>image</code> to composite an image with another image. Follow the 3170 image keyword with the composite operator, image location, image size, and 3171 filename:</p> 3172 3173 <pre> 3174 -draw 'image SrcOver 100,100 225,225 image.jpg' 3175 </pre> 3176 3177 <p>You can use 0,0 for the image size, which means to use the actual 3178 dimensions found in the image header. Otherwise, it is scaled to the given 3179 dimensions. See <a href="compose.php">Alpha Compositing</a> for 3180 a detailed discussion of alpha composition methods that are available. </p> 3181 3182 <p>The "special augmented compose operators" such as "dissolve" that require 3183 arguments cannot be used at present with the <code>-draw image</code> option. 3184 </p> 3185 3186 <p>Use <code>text</code> to annotate an image with text. Follow the text 3187 coordinates with a string. If the string has embedded spaces, enclose it in 3188 single or double quotes.</p> 3189 3190 <p>For example, the following annotates the image with <code>Works like 3191 magick!</code> for an image titled <code>bird.miff</code>. </p> 3192 3193 <pre> 3194 -draw "text 100,100 'Works like magick!' " 3195 </pre> 3196 3197 <p>See the <a href="command-line-options.php#annotate">-annotate</a> option for another convenient way 3198 to annotate an image with text.</p> 3199 3200 <p>The <code>rotate</code> primitive rotates subsequent shape primitives and 3201 text primitives about the origin of the main image. If the <a 3202 href="command-line-options.php#region">-region</a> option precedes the <a href="command-line-options.php#draw">-draw</a> 3203 option, the origin for transformations is the upper left corner of the 3204 region.</p> 3205 3206 <p>The <code>translate</code> primitive translates subsequent shape and text 3207 primitives.</p> 3208 3209 <p>The <code>scale</code> primitive scales them.</p> 3210 3211 <p>The <code>skewX</code> and <code>skewY</code> primitives skew them with respect 3212 to the origin of the main image or the region.</p> 3213 3214 <p>The transformations modify the current affine matrix, which is initialized 3215 from the initial affine matrix defined by the <a href="command-line-options.php#affine">-affine</a> 3216 option. Transformations are cumulative within the <a href="command-line-options.php#draw">-draw</a> 3217 option. The initial affine matrix is not affected; that matrix is only changed 3218 by the appearance of another <a href="command-line-options.php#affine">-affine</a> option. If another 3219 <a href="command-line-options.php#draw">-draw</a> option appears, the current affine matrix is 3220 reinitialized from the initial affine matrix.</p> 3221 3222 <p>Use the <code>color</code> primitive to change the color of a pixel to the 3223 fill color (see <a href="command-line-options.php#fill">-fill</a>). Follow the pixel coordinate with 3224 a method:</p> 3225 3226 <pre> 3227 point 3228 replace 3229 floodfill 3230 filltoborder 3231 reset 3232 </pre> 3233 3234 <p>Consider the target pixel as that specified by your coordinate. The 3235 <code>point</code> method recolors the target pixel. The <code>replace</code> 3236 method recolors any pixel that matches the color of the target pixel. 3237 <code>Floodfill</code> recolors any pixel that matches the color of the target 3238 pixel and is a neighbor, whereas <code>filltoborder</code> recolors any neighbor 3239 pixel that is not the border color. Finally, <code>reset</code> recolors all 3240 pixels.</p> 3241 3242 <p>Use <code>matte</code> to the change the pixel matte value to transparent. 3243 Follow the pixel coordinate with a method (see the <code>color</code> primitive 3244 for a description of methods). The <code>point</code> method changes the matte 3245 value of the target pixel. The <code>replace</code> method changes the matte 3246 value of any pixel that matches the color of the target pixel. 3247 <code>Floodfill</code> changes the matte value of any pixel that matches the 3248 color of the target pixel and is a neighbor, whereas <code>filltoborder</code> 3249 changes the matte value of any neighbor pixel that is not the border color (<a 3250 href="command-line-options.php#bordercolor">-bordercolor</a>). Finally <code>reset</code> changes the 3251 matte value of all pixels.</p> 3252 3253 <p>You can set the primitive color, font, and font bounding box color with <a 3254 href="command-line-options.php#fill">-fill</a>, <a href="command-line-options.php#font">-font</a>, and <a href="command-line-options.php#box">-box</a> 3255 respectively. Options are processed in command line order so be sure to use 3256 these options <var>before</var> the <a href="command-line-options.php#draw">-draw</a> option.</p> 3257 3258 <p>Strings that begin with a number must be quoted (e.g. use '1.png' rather 3259 than 1.png).</p> 3260 3261 <p>Drawing primitives conform to the <a href="magick-vector-graphics.php" >Magick 3262 Vector Graphics</a> format.</p> 3263 3264 3265 <div style="margin: auto;"> 3266 <h3 class="magick-header"><a id="duplicate"></a>-duplicate <var>count,indexes</var></h3> 3267 </div> 3268 3269 <p class="magick-description">duplicate an image one or more times.</p> 3270 3271 <p>Specify the count and the image to duplicate by its index in the sequence. 3272 The first image is index 0. Negative indexes are relative to the end of the 3273 sequence, for example, -1 represents the last image of the sequence. Specify 3274 a range of images with a dash (e.g. 0-4). Separate indexes with a comma (e.g. 3275 0,2). Use <code>+duplicate</code> to duplicate the last image in the current 3276 image sequence.</p> 3277 3278 <div style="margin: auto;"> 3279 <h3 class="magick-header"><a id="edge"></a>-edge <var>radius</var></h3> 3280 </div> 3281 3282 <p class="magick-description">detect edges within an image.</p> 3283 3284 <div style="margin: auto;"> 3285 <h3 class="magick-header"><a id="emboss"></a>-emboss <var>radius</var></h3> 3286 </div> 3287 3288 <p class="magick-description">emboss an image.</p> 3289 3290 <div style="margin: auto;"> 3291 <h3 class="magick-header"><a id="encipher"></a>-encipher <var>filename</var></h3> 3292 </div> 3293 3294 <p class="magick-description">Encipher pixels for later deciphering by <a href="command-line-options.php#decipher">-decipher</a>.</p> 3295 3296 <p>Get the passphrase from the file specified by <var>filename</var>.</p> 3297 3298 <p>For more information, see the webpage, <a 3299 href="http://www.imagemagick.org/www/cipher.html">ImageMagick: Encipher or 3300 Decipher an Image</a>.</p> 3301 3302 3303 3304 <div style="margin: auto;"> 3305 <h3 class="magick-header"><a id="encoding"></a>-encoding <var>type</var></h3> 3306 </div> 3307 3308 <p class="magick-description">specify the text encoding.</p> 3309 3310 <p>Choose from</p> 3311 3312 <pre> 3313 AdobeCustom AdobeExpert 3314 AdobeStandard AppleRoman 3315 BIG5 GB2312 3316 Latin 2 None 3317 SJIScode Symbol 3318 Unicode Wansung 3319 </pre> 3320 3321 <div style="margin: auto;"> 3322 <h3 class="magick-header"><a id="endian"></a>-endian <var>type</var></h3> 3323 </div> 3324 3325 <p class="magick-description">Specify endianness (<code>MSB</code> or <code>LSB</code>) of the image.</p> 3326 3327 <p>To print a complete list of endian types, use the <a href="command-line-options.php#list">-list endian</a> option.</p> 3328 3329 <p>Use <a href="command-line-options.php#endian">+endian</a> to revert to unspecified endianness.</p> 3330 3331 3332 <div style="margin: auto;"> 3333 <h3 class="magick-header"><a id="enhance"></a>-enhance</h3> 3334 </div> 3335 3336 <p class="magick-description">Apply a digital filter to enhance a noisy image.</p> 3337 3338 3339 <div style="margin: auto;"> 3340 <h3 class="magick-header"><a id="equalize"></a>-equalize</h3> 3341 </div> 3342 3343 <p class="magick-description">perform histogram equalization on the image channel-by-channel.</p> 3344 3345 <p>To perform histogram equalization on all channels in concert, transform the 3346 image into some other color space, such as HSL, OHTA, YIQ or YUV, then 3347 equalize the appropriate intensity-like channel, then convert back to RGB.</p> 3348 3349 <p>For example using HSL, we have: ... <code>-colorspace HSL -channel lightness 3350 -equalize -colorspace RGB</code> ...</p> 3351 3352 <p>For YIQ, YUV and OHTA use the red channel. For example, OHTA is a principal 3353 components transformation that puts most of the information in the first 3354 channel. Here we have ... <code>-colorspace OHTA -channel red -equalize 3355 -colorspace RGB</code> ...</p> 3356 3357 <div style="margin: auto;"> 3358 <h3 class="magick-header"><a id="evaluate"></a>-evaluate <var>operator value</var></h3> 3359 </div> 3360 3361 <p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or logical expression.</p> 3362 3363 <p>(See the <a href="command-line-options.php#function" >-function</a> operator for some 3364 multi-parameter functions. See the <a href="command-line-options.php#fx" >-fx</a> operator if more 3365 elaborate calculations are needed.)</p> 3366 3367 <p>The behaviors of each <var>operator</var> are summarized in the 3368 following list. For brevity, the numerical value of a "pixel" referred to 3369 below is the value of the corresponding channel of that pixel, while 3370 a "normalized pixel" is that number divided by the maximum 3371 (installation-dependent) value <var>QuantumRange</var>. (If 3372 normalized pixels are used, they are restored, following the other 3373 calculations, to the full range by multiplying by <var>QuantumRange</var>.)</p> 3374 3375 <table class="table table-condensed table-striped"> 3376 <col width="25%" /> 3377 <col width="75%" /> 3378 <thead> 3379 <tr> 3380 <th><var>operator</var></th> 3381 <th>Summary (see further below for details)</th> 3382 </tr> 3383 </thead> 3384 <tbody> 3385 3386 <tr><td>Abs </td> <td>Add <var>value</var> to pixels and return absolute value. </td></tr> 3387 <tr><td>Add </td> <td>Add <var>value</var> to pixels. </td></tr> 3388 <tr><td>AddModulus </td> <td>Add <var>value</var> to pixels modulo <var>QuantumRange</var>.</td></tr> 3389 <tr><td>And </td> <td>Binary AND of pixels with <var>value</var>.</td></tr> 3390 <tr><td>Cos, Cosine </td> <td>Apply cosine to pixels with frequency <var>value</var> with 50% bias added.</td></tr> 3391 <tr><td>Divide </td> <td>Divide pixels by <var>value</var>.</td></tr> 3392 <tr><td>Exp </td> <td>base-e exponential function</td></tr> 3393 <tr><td>Exponential </td> <td>base-e exponential function</td></tr> 3394 <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> 3395 <tr><td>Log </td> <td>Apply scaled logarithm to normalized pixels.</td></tr> 3396 <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> 3397 <tr><td>Mean </td> <td>Add the <var>value</var> and divide by 2.</td></tr> 3398 <tr><td>Median </td> <td>Choose the median value from an image sequence.</td></tr> 3399 <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> 3400 <tr><td>Multiply </td> <td>Multiply pixels by <var>value</var>.</td></tr> 3401 <tr><td>Or </td> <td>Binary OR of pixels with <var>value</var>.</td></tr> 3402 <tr><td>Pow </td> <td>Raise normalized pixels to the power <var>value</var>.</td></tr> 3403 <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> 3404 <tr><td>RMS</td> <td>Square the pixel and add the <var>value</var>.</td></tr> 3405 <tr><td>RootMeanSquare</td> <td>Square the pixel and add the <var>value</var>.</td></tr> 3406 <tr><td>Set </td> <td>Set pixel equal to <var>value</var>.</td></tr> 3407 <tr><td>Sin, Sine </td> <td>Apply sine to pixels with frequency <var>value</var> with 50% bias added.</td></tr> 3408 <tr><td>Subtract </td> <td>Subtract <var>value</var> from pixels.</td></tr> 3409 <tr><td>Xor </td> <td>Binary XOR of pixels with <var>value.</var></td></tr> 3410 3411 <tr><td> </td><td> </td></tr> 3412 3413 <tr><td>Gaussian-noise</td><td> </td></tr> 3414 <tr><td>Impulse-noise</td><td> </td></tr> 3415 <tr><td>Laplacian-noise</td><td> </td></tr> 3416 <tr><td>Multiplicative-noise</td> <td>(These are equivalent to the corresponding <a href="command-line-options.php#noise" >-noise</a> operators.)</td></tr> 3417 <tr><td>PoissonNoise</td><td> </td></tr> 3418 <tr><td>Uniform-noise</td><td> </td></tr> 3419 3420 <tr><td> </td><td> </td></tr> 3421 3422 <tr><td>Threshold </td> <td>Threshold pixels larger than <var>value</var>.</td></tr> 3423 <tr><td>ThresholdBlack </td> <td>Threshold pixels to zero values equal to or below <var>value</var>.</td></tr> 3424 <tr><td>ThresholdWhite </td> <td>Threshold pixels to maximum values above <var>value</var>. </td></tr> 3425 </tbody> 3426 </table> 3427 3428 <p>The specified functions are applied only to each previously set <a 3429 href="command-line-options.php#channel" >-channel</a> in the image. If necessary, the results of the 3430 calculations are truncated (clipped) to fit in the interval [0, <var>QuantumRange</var>]. The transparency channel of the image is 3431 represented as a 'alpha' values (0 = fully transparent), so, for example, a 3432 <code>Divide</code> by 2 of the alpha channel will make the image 3433 semi-transparent. Append the percent symbol '<code>%</code>' to specify a value 3434 as a percentage of the <var>QuantumRange</var>.</p> 3435 3436 <p>To print a complete list of <a href="command-line-options.php#evaluate">-evaluate</a> operators, use 3437 <a href="command-line-options.php#list">-list evaluate</a>.</p> 3438 3439 <p>The results of the <code>Add</code>, <code>Subtract</code> and 3440 <code>Multiply</code> methods can also be achieved using either the <a 3441 href="command-line-options.php#level" >-level</a> or the <a href="command-line-options.php#level" >+level</a> operator, with 3442 appropriate argument, to linearly modify the overall range of color values. 3443 Please note, however, that <a href="command-line-options.php#level" >-level</a> treats transparency as 3444 'matte' values (0 = opaque), while <a href="command-line-options.php#level" >-evaluate</a> works with 3445 'alpha' values.</p> 3446 3447 <p><code>AddModulus</code> has been added as of ImageMagick 6.4.8-4 and provides 3448 addition modulo the <var>QuantumRange</var>. It is therefore 3449 equivalent to <code>Add</code> unless the resulting pixel value is outside the 3450 interval [0, <var>QuantumRange</var>]. </p> 3451 3452 <p><code>Exp or Exponential</code> has been added as of ImageMagick 6.6.5-1 and 3453 works on normalized pixel values. The <var>value</var> used with 3454 <code>Exp</code> should be negative so as to produce a decaying exponential 3455 function. Non-negative values will always produce results larger unity and 3456 thus outside the interval [0, <var>QuantumRange</var>]. The 3457 formula is expressed below. </p> 3458 3459 <p class="text-center"> 3460 exp(<var>value</var> <b><var>u</var></b>) 3461 </p> 3462 3463 <p> If the input image is squared, for example, using <a href="command-line-options.php#-function" 3464 >-function polynomial "2 0 0"</a>, then a decaying Gaussian function will be 3465 the result.</p> 3466 3467 <p><code>Log</code> has been added as of ImageMagick 6.4.2-1 and works on 3468 normalized pixel values. This a <var>scaled</var> log function. The <var>value</var> used with <code>Log</code> provides a <var>scaling 3469 factor</var> that adjusts the curvature in the graph of the log function. The 3470 formula applied to a normalized value <b><var>u</var></b> is below. </p> 3471 3472 <p class="text-center"> 3473 log(<var>value</var> <b><var>u</var></b> + 1) / log(<var>value</var> + 1) 3474 </p> 3475 3476 <p><code>Pow</code> has been added as of ImageMagick 6.4.1-9, and works on 3477 normalized pixel values. Note that <code>Pow</code> is related to the <a 3478 href="command-line-options.php#gamma" >-gamma</a> operator. For example, <b>-gamma 2</b> is equivalent 3479 to <b>-evaluate pow 0.5</b>, i.e., a 'square root' function. The value used 3480 with <a href="command-line-options.php#gamma" >-gamma</a> is simply the reciprocal of the value used 3481 with <code>Pow</code>.</p> 3482 3483 <p><code>Cosine</code> and <code>Sine</code> was added as of IM v6.4.8-8 and 3484 converts the image values into a value according to a (co)sine wave function. 3485 The synonyms <code>Cos</code> and <code>Sin</code> may also be used. The output 3486 is biased 50% and normalized by 50% so as to fit in the respective color value 3487 range. The <var>value</var> scaling of the <var>period</var> of the 3488 function (its frequency), and thus determines the number of 'waves' that will 3489 be 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, 3490 then the effective period is the <var>half</var> the <var>QuantumRange</var>.</p> 3491 3492 <p class="text-center"> 3493 0.5 + 0.5 cos(2 <b><var>u</var></b> <var>value</var>). 3494 </p> 3495 3496 <p>See also the <a href="command-line-options.php#function" >-function</a> operator, which is a 3497 multi-value version of evaluate. </p> 3498 3499 <div style="margin: auto;"> 3500 <h3 class="magick-header"><a id="evaluate-sequence"></a>-evaluate-sequence <var>operator</var></h3> 3501 </div> 3502 3503 <p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or 3504 logical expression over a sequence of images.</p> 3505 3506 <p>To print a complete list of <a 3507 href="command-line-options.php#evaluate-sequence">-evaluate-sequence</a> operators, use <a 3508 href="command-line-options.php#list">-list evaluate</a>.</p> 3509 3510 <div style="margin: auto;"> 3511 <h3 class="magick-header"><a id="extent"></a>-extent <var>geometry</var></h3> 3512 </div> 3513 3514 <p class="magick-description">Set the image size and offset.</p> 3515 3516 <p>If the image is enlarged, unfilled areas are set to the background color. 3517 To position the image, use offsets in the <var>geometry</var> 3518 specification or precede with a <a href="command-line-options.php#gravity">-gravity</a> setting. To 3519 specify how to compose the image with the background, use <a href="command-line-options.php#compose" 3520 >-compose</a>.</p> 3521 3522 <p>This command reduces or expands a JPEG image to fit on an 800x600 3523 display. If the aspect ratio of the input image isn't exactly 4:3, then the 3524 image is centered on an 800x600 black canvas: </p> 3525 3526 <pre> 3527 convert input.jpg -resize 800x600 -background black -compose Copy \ 3528 -gravity center -extent 800x600 -quality 92 output.jpg 3529 </pre> 3530 3531 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 3532 3533 <div style="margin: auto;"> 3534 <h3 class="magick-header"><a id="extract"></a>-extract <var>geometry</var></h3> 3535 </div> 3536 3537 <p class="magick-description">Extract the specified area from image.</p> 3538 3539 <p>This option is most useful for extracting a subregion of a very large raw 3540 image. Note that these two commands are equivalent:</p> 3541 3542 <pre> 3543 convert -size 16000x16000 -depth 8 -extract 640x480+1280+960 \ 3544 image.rgb image.png", 3545 convert -size 16000x16000 -depth 8 'image.rgb[640x480+1280+960]' \ 3546 image.rgb image.png" 3547 </pre> 3548 3549 <p>If you omit the offsets, as in</p> 3550 3551 <pre> 3552 convert -size 16000x16000 -depth 8 -extract 640x480 \ 3553 image.rgb image.png 3554 </pre> 3555 3556 <p>the image is <var>resized</var> to the specified dimensions instead, 3557 equivalent to:</p> 3558 3559 <pre> 3560 convert -size 16000x16000 -depth 8 -resize 640x480 image.rgb image.png 3561 </pre> 3562 3563 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 3564 3565 <div style="margin: auto;"> 3566 <h3 class="magick-header"><a id="family"></a>-family <var>fontFamily</var></h3> 3567 </div> 3568 3569 <p class="magick-description">Set a font family for text.</p> 3570 3571 <p>This setting suggests a font family that ImageMagick should try to use for 3572 rendering text. If the family can be found it is used; if not, a default font 3573 (e.g., "Arial") or a family known to be similar is substituted (e.g., 3574 "Courier" might be used if "System" is requested but not found). </p> 3575 3576 <p>For other settings that affect fonts, see the options <a 3577 href="command-line-options.php#font">-font</a>, <a href="command-line-options.php#stretch">-stretch</a>, <a 3578 href="command-line-options.php#style">-style</a>, and <a href="command-line-options.php#weight">-weight</a>. </p> 3579 3580 <div style="margin: auto;"> 3581 <h3 class="magick-header"><a id="features"></a>-features <var>distance</var></h3> 3582 </div> 3583 3584 <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> 3585 3586 <pre> 3587 Angular Second Moment Sum Entropy 3588 Contrast Entropy 3589 Correlation Difference Variance 3590 Sum of Squares Variance Difference Entropy 3591 Inverse Difference Moment Information Measure of Correlation 1 3592 Sum Average Information Measure of Correlation 2 3593 Sum Variance Maximum Correlation Coefficient 3594 </pre> 3595 3596 <div style="margin: auto;"> 3597 <h3 class="magick-header"><a id="fft"></a>-fft</h3> 3598 </div> 3599 3600 <p class="magick-description">implements the forward discrete Fourier transform (DFT).</p> 3601 3602 <p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows 3603 users in ImageMagick 6.6.0-9). It transforms an image from the normal 3604 (spatial) domain to the frequency domain. In the frequency domain, an image is 3605 represented as a superposition of complex sinusoidal waves of varying 3606 amplitudes. The image x and y coordinates are the possible frequencies along 3607 the x and y directions, respectively, and the pixel intensity values are 3608 complex numbers that correspond to the sinusoidal wave amplitudes. See for 3609 example, <a href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier 3610 Transform</a>, <a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier 3611 Transform</a> and <a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier 3612 Transform</a>.</p> 3613 3614 <p>A single image name is provided as output for this option. However, the 3615 output result will have two components. It is either a two-frame image or two 3616 separate images, depending upon whether the image format specified supports 3617 multi-frame images. The reason that we get a dual output result is because the 3618 frequency domain represents an image using complex numbers, which cannot be 3619 visualized directly. Therefore, the complex values are automagically separated 3620 into a two-component image representation. The first component is the 3621 magnitude of the complex number and the second is the phase of the complex 3622 number. See for example, <a 3623 href="http://en.wikipedia.org/wiki/Complex_numbers">Complex Numbers</a>.</p> 3624 3625 <p>The magnitude and phase component images must be specified using image 3626 formats that do not limit the color or compress the image. Thus, MIFF, TIF, 3627 PFM, EXR and PNG are the recommended image formats to use. All of these 3628 formats, except PNG support multi-frame images. So for example,</p> 3629 3630 <pre> 3631 convert image.png -fft fft_image.miff 3632 </pre> 3633 3634 <p>generates a magnitude image as <code>fft_image.miff[0]</code> and a phase 3635 image as <code>fft_image.miff[1]</code>. Similarly,</p> 3636 3637 <pre> 3638 convert image.png -fft fft_image.png 3639 </pre> 3640 3641 <p>generates a magnitude image as <code>fft_image-0.png</code> and a phase image 3642 as <code>fft_image-1.png</code>. If you prefer this representation, then you can 3643 force any of the other formats to produce two output images by including <a 3644 href="command-line-options.php#adjoin">+adjoin</a> following -fft in the command line.</p> 3645 3646 <p>The input image can be any size, but if not square and even-dimensioned, it 3647 is padded automagically to the larger of the width or height of the input 3648 image and to an even number of pixels. The padding will occur at the bottom 3649 and/or right sides of the input image. The resulting output magnitude and 3650 phase images is square at this size. The kind of padding relies on the <a 3651 href="command-line-options.php#virtual-pixel">-virtual-pixel</a> setting.</p> 3652 3653 <p>Both output components will have dynamic ranges that fit within 3654 [0, <var>QuantumRange</var>], so that HDRI need not be enabled. 3655 Phase values nominally range from 0 to 2*, but is scaled to span the full 3656 dynamic range. (The first few releases had non-HDRI scaled but HDRI not 3657 scaled). The magnitude image is not scaled and thus generally will contain 3658 very small values. As such, the image normally will appear totally black. In 3659 order to view any detail, the magnitude image typically is enhanced with a log 3660 function into what is usually called the spectrum. A log function is used to 3661 enhance the darker values more in comparison to the lighter values. This can 3662 be done, for example, as follows:</p> 3663 3664 <pre> 3665 convert fft_image.miff[0] -contrast-stretch 0 \ 3666 -evaluate log 1000 fft_image_spectrum.png" 3667 </pre> 3668 3669 <p>where either <a href="command-line-options.php#contrast-stretch">-contrast-stretch</a> 0 or <a 3670 href="command-line-options.php#auto-level">-auto-level</a> is used to scale the image to full dynamic 3671 range, first. The argument to the <a href="command-line-options.php#evaluate">-evaluate</a> log 3672 typically is specified between 100 and 10,000, depending upon the amount of 3673 detail that one wants to bring out in the spectrum. Larger values produce more 3674 visible detail. Too much detail, however, may hide the important features.</p> 3675 3676 <p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to 3677 use <a href="command-line-options.php#fft">-fft</a>.</p> 3678 3679 <p>Use <a href="command-line-options.php#fft">+fft</a> to produce two output images that are the real 3680 and imaginary components of the complex valued Fourier transform.</p> 3681 3682 <p>However, as the real and imaginary components can contain negative values, 3683 this requires that IM be configured with HDRI enabled. In this case, you must 3684 use either MIFF, TIF, PFM or MPC formats for the real and imaginary component 3685 results, since they are formats that preserve both negative and fractional 3686 values without clipping them or truncating the fractional part. With either 3687 MIFF or TIF, one should add -define quantum:format=32, to allow those image 3688 types to work properly in HDRI mode without clipping.</p> 3689 3690 <p>The real and imaginary component images resulting from <a 3691 href="command-line-options.php#fft">+fft</a> are also square, even dimensioned images due to the same 3692 padding that was discussed above for the magnitude and phase component 3693 images.</p> 3694 3695 <p>See the discussion on HDRI implementations of ImageMagick on the page <a 3696 href="high-dynamic-range.php" >High Dynamic-Range Images</a>. For more 3697 about HDRI go the ImageMagick <a 3698 href="http://www.imagemagick.org/Usage/basics/#hdri" >Usage</a> pages, <a 3699 href="http://www.fmwconcepts.com/imagemagick/fourier_transforms/fourier.html" 3700 >Fred's Fourier Processing With ImageMagick page</a> or this <a 3701 href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging" >Wikipedia</a> 3702 entry. </p> 3703 3704 <p>By default the FFT is normalized (and the IFT is not). Use "<code><a href="command-line-options.php#define" >-define</a> fourier:normalize=forward</code> to explicitly normalize the FFT and unnormalize the IFT.</p> 3705 3706 3707 <div style="margin: auto;"> 3708 <h3 class="magick-header"><a id="fill"></a>-fill <var>color</var></h3> 3709 </div> 3710 3711 <p class="magick-description">color to use when filling a graphic primitive.</p> 3712 3713 <p>This option accepts a color name, a hex color, or a numerical RGB, RGBA, 3714 HSL, HSLA, CMYK, or CMYKA specification. See <a href="color.php" >Color Names</a> for 3715 a description of how to properly specify the color argument.</p> 3716 3717 <p>Enclose the color specification in quotation marks to prevent the "#" or 3718 the parentheses from being interpreted by your shell.</p> 3719 3720 <p>For example,</p> 3721 3722 <pre> 3723 -fill blue 3724 -fill "#ddddff" 3725 -fill "rgb(255,255,255)" 3726 </pre> 3727 3728 <p>See <a href="command-line-options.php#draw">-draw</a> for further details.</p> 3729 3730 <p>To print a complete list of color names, use the <a href="command-line-options.php#list">-list color</a> option.</p> 3731 3732 <div style="margin: auto;"> 3733 <h3 class="magick-header"><a id="filter"></a>-filter <var>type</var></h3> 3734 </div> 3735 3736 <p class="magick-description">Use this <var>type</var> of filter when resizing or distorting an image.</p> 3737 3738 <p>Use this option to affect the resizing operation of an image during 3739 operations such as <a href="command-line-options.php#resize">-resize</a> and <a href="command-line-options.php#distort" 3740 >-distort</a>. For example you can use a simple resize filter such as:</p> 3741 3742 <pre> 3743 Point Hermite Cubic 3744 Box Gaussian Catrom 3745 Triangle Quadratic Mitchell 3746 </pre> 3747 3748 <p>The <code>Bessel</code> and <code>Sinc</code> filter is also provided (as well 3749 as a faster <code>SincFast</code> equivalent form). However these filters are 3750 generally useless on their own as they are infinite filters that are being 3751 clipped to the filters support size. Their direct use is not recommended 3752 except via expert settings (see below). </p> 3753 3754 <p>Instead these special filter functions are typically windowed by a windowing 3755 function that the <a href="command-line-options.php#filter" >-filter</a> setting defines. That is 3756 using these functions will define a 'Windowed' filter, appropriate to the 3757 operator involved. Windowed filters include: </p> 3758 3759 <pre> 3760 Lanczos Hamming Parzen 3761 Blackman Kaiser Welsh 3762 Hanning Bartlett Bohman 3763 </pre> 3764 3765 <p>Also one special self-windowing filter is also provided 3766 <code>Lagrange</code>, which will automagically re-adjust its function depending 3767 on the current 'support' or 'lobes' expert settings (see below).</p> 3768 3769 <p>If you do not select a filter with this option, the filter defaults to 3770 <code>Mitchell</code> for a colormapped image, an image with a matte channel, or 3771 if the image is enlarged. Otherwise the filter default to 3772 <code>Lanczos</code>.</p> 3773 3774 <p>To print a complete list of resize filters, use the <a href="command-line-options.php#list">-list 3775 filter</a> option.</p> 3776 3777 <p>You can modify how the filter behaves as it scales your image through the 3778 use of these expert settings (see also <a href="command-line-options.php#define" >-define</a> and <a 3779 href="command-line-options.php#set" >-set</a>):-</p> 3780 3781 <table class="table table-condensed table-striped"> 3782 <tr> 3783 <td>-define filter:blur=<var>factor</var></td> 3784 <td>Scale the X axis of the filter (and its window). Use > 1.0 for 3785 blurry or < 1.0 for sharp. This should only be used with Gaussian and 3786 Gaussian-like filters simple filters, or you may not get the expected 3787 results. </td> 3788 </tr> 3789 3790 <tr> 3791 <td>-define filter:support=<var>radius</var></td> 3792 <td>Set the filter support radius. Defines how large the filter should be and 3793 thus directly defines how slow the filtered resampling process is. All 3794 filters have a default 'preferred' support size. Some filters like 3795 <code>Lagrange</code> and windowed filters adjust themselves depending on 3796 this value. With simple filters this value either does nothing (but slow 3797 the resampling), or will clip the filter function in a detrimental way. 3798 </td> 3799 </tr> 3800 3801 <tr> 3802 <td>-define filter:lobes=<var>count</var></td> 3803 <td>Set the number of lobes to use for the Sinc/Bessel filter. This an 3804 alternative way of specifying the 'support' range of the filter, that is 3805 designed to be more suited to windowed filters, especially when used for 3806 image distorts.</td> 3807 </tr> 3808 3809 <tr> 3810 <td>-define filter:sigma=<var>value</var></td> 3811 <td>The 'sigma' value used to define the <code>Gaussian</code> filter. Default 3812 sigma value is '<code>0.5</code>'. It only effects <code>Gaussian</code> but 3813 does not shrink (but may enlarge) the filter's 'support'. It can be used 3814 to generate very small blurs but without the filter 'missing' pixels due 3815 to using a small support setting. A larger value of '<code>0.707</code>' 3816 (a value of '1/sqrt(2)') is another common setting. </td> 3817 </tr> 3818 3819 <tr> 3820 <td>-define filter:b=<var>b-spline_factor</var></td> 3821 <tr> 3822 <td>-define filter:c=<var>keys_alpha_factor</var></td> 3823 <td>Redefine the values used for cubic filters such as <code>Cubic</code>, 3824 <code>Catrom</code>, <code>Mitchel</code>, and <code>Hermite</code>, as well as 3825 the <code>Parzen</code> cubic windowing function. If only one of the values 3826 are defined, the other is set so as to generate a 'Cubic-Keys' filter. 3827 The values meaning was defined by a research paper by 3828 Mitchell-Netravali.</td> 3829 </tr> 3830 3831 <tr> 3832 <td>-define filter:kaiser-beta=<var>value</var></td> 3833 <td>The 'alpha' value used to as part of the Kaiser Windowing function. 3834 Default value is '6.5'. It only effects Kaiser windowing function, and 3835 does not effect any other attributes. 3836 Before ImageMagick v6.7.6-10, this option was known as "filter:alpha", (an 3837 inheritance from the very old "zoom" program). It was changed to bring the 3838 function in line with more modern academic research usage, and better 3839 assign it be more definitive. </td> 3840 </tr> 3841 3842 <tr> 3843 <td>-define filter:kaiser-alpha=<var>value</var></td> 3844 <td>This value when multiplied by 'PI' is equivalent to "kaiser-beta", and 3845 will override that setting. It only effects Kaiser windowing function, 3846 and does not effect any other attributes. </td> 3847 </tr> 3848 3849 <tr> 3850 <td>-define filter:filter=<var>filter_function</var></td> 3851 <td>Use this function directly as the weighting filter. This will allow 3852 you to directly use a windowing function such as <code>Blackman</code>, 3853 as a resampling filter, rather than as its normal usage as a windowing 3854 function. If defined, no windowing function also defined, the window function is set 3855 to <code>Box</code>). Directly specifying <code>Sinc</code> or <code>Jinc</code> 3856 as a filter will also do this. </td> 3857 </tr> 3858 3859 <tr> 3860 <td>-define filter:window=<var>filter_function</var></td> 3861 <td>The IIR (infinite impulse response) filters <code>Sinc</code> and 3862 <code>Jinc</code> are windowed (brought down to zero over the defined 3863 support range) with the given filter. This allows you to specify a filter 3864 function to be used as a windowing function for these IIR filters. 3865 Many of the defined filters are actually windowing functions for these IIR 3866 filters. A typical choices is <code>Box</code>, (which effectively turns 3867 off the windowing function). </td> 3868 </tr> 3869 3870 <tr> 3871 <td>-define filter:win-support=<var>radius</var></td> 3872 <td>Scale windowing function to this size instead. This causes the windowing 3873 (or self-windowing Lagrange filter) to act is if the support window is 3874 larger than what is actually supplied to the calling operator. The filter 3875 however is still clipped to the real support size given. If unset this 3876 will equal the normal filter support size. </td> 3877 </tr> 3878 3879 <tr> 3880 <td>-define filter:verbose=<var>1</var></td> 3881 <td>This causes IM to print information on the final internal filter 3882 selection to standard output. This includes a commented header on the 3883 filter settings being used, and data allowing the filter weights to be 3884 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 3885 a <code>SincFast</code> windowed <code>SincFast</code> filter, while 3886 <code>Mitchell</code> is defined as a general <code>Cubic</code> family filter 3887 with specific 'B' and 'C' settings. </td> 3888 </tr> 3889 3890 </table> 3891 3892 <p>For example, to get a 8 lobe jinc windowed sinc filter (Genseng filter?):</p> 3893 3894 <pre> 3895 convert image.png \ 3896 -filter sinc \ 3897 -set filter:window=jinc \ 3898 -set filter:lobes=8 \ 3899 -resize 150% image.jpg" 3900 </pre> 3901 3902 <p>Or a raw un-windowed Sinc filter with 4 lobes:</p> 3903 3904 <pre> 3905 convert image.png \ 3906 -set filter:filter=sinc \ 3907 -set filter:lobes=4 \ 3908 -resize 150% image.jpg" 3909 </pre> 3910 3911 <p>To extract the data for a raw windowing function, combine it with 3912 a '<code>Box</code>' filter. For example the '<code>Welch</code> parabolic 3913 windowing function. </p> 3914 3915 <pre> 3916 convert null: -define filter:filter=Box \ 3917 -define filter:window=Welch \ 3918 -define filter:support=1.0 \ 3919 -define filter:verbose=1 \ 3920 -resize 2 null: > window_welch.dat 3921 gnuplot 3922 set grid 3923 plot \"window_welch.dat\" with lines 3924 </pre> 3925 3926 <p>Note that the use of expert options is provided for image processing experts 3927 who have studied and understand how resize filters work. Without this 3928 knowledge, and an understanding of the definition of the actual filters 3929 involved, using expert settings are more likely to be detrimental to your image 3930 resizing.</p> 3931 3932 3933 <div style="margin: auto;"> 3934 <h3 class="magick-header"><a id="flatten"></a>-flatten</h3> 3935 </div> 3936 3937 <p class="magick-description">This is a simple alias for the <a href="command-line-options.php#layers" >-layers</a> method "flatten".</p> 3938 3939 3940 <div style="margin: auto;"> 3941 <h3 class="magick-header"><a id="flip"></a>-flip</h3> 3942 </div> 3943 3944 <p class="magick-description">create a <var>mirror image</var></p> 3945 3946 <p>reflect the scanlines in the vertical direction. The image will be mirrored 3947 upside-down. </p> 3948 3949 3950 <div style="margin: auto;"> 3951 <h3 class="magick-header"><a id="floodfill"></a>-floodfill {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var> <var>color</var></h3> 3952 </div> 3953 3954 <p class="magick-description">floodfill the image with color at the specified offset.</p> 3955 3956 <p>Flood fill starts from the given 'seed point' which is not gravity effected. 3957 Any color that matches within <a href="command-line-options.php#fuzz" >-fuzz</a> color distance of the 3958 given <var>color</var> argument, connected to that 'seed point' 3959 will be replaced with the current <a href="command-line-options.php#fill" >-fill</a> color. </p> 3960 3961 <p>Note that if the pixel at the 'seed point' does not itself match the given 3962 <var>color</var> (according to <a href="command-line-options.php#fuzz" >-fuzz</a>), then no 3963 action will be taken. </p> 3964 3965 <p>This operator works more like the <a href="command-line-options.php#opaque" >-opaque</a> option, than 3966 a more general flood fill that reads the matching color directly at the 'seed 3967 point'. For this form of flood fill, look at <a href="command-line-options.php#draw" >-draw</a> and 3968 its 'color floodfill' drawing method. </p> 3969 3970 3971 <div style="margin: auto;"> 3972 <h3 class="magick-header"><a id="flop"></a>-flop</h3> 3973 </div> 3974 3975 <p class="magick-description">create a <var>mirror image</var>.</p> 3976 3977 <p>Reflect the scanlines in the horizontal direction, just like the image in 3978 a vertical mirror. </p> 3979 3980 3981 <div style="margin: auto;"> 3982 <h3 class="magick-header"><a id="font"></a>-font <var>name</var></h3> 3983 </div> 3984 3985 <p class="magick-description">set the font to use when annotating images with text, or creating labels.</p> 3986 3987 <p>To print a complete list of fonts, use the <a href="command-line-options.php#list">-list font</a> 3988 option (for versions prior to 6.3.6, use 'type' instead of 'font').</p> 3989 3990 <p>In addition to the fonts specified by the above pre-defined list, you can 3991 also specify a font from a specific source. For example <code>Arial.ttf</code> 3992 is a TrueType font file, <code>ps:helvetica</code> is PostScript font, and 3993 <code>x:fixed</code> is X11 font.</p> 3994 3995 <p>For other settings that affect fonts, see the options <a 3996 href="command-line-options.php#family">-family</a>, <a href="command-line-options.php#stretch">-stretch</a>, <a 3997 href="command-line-options.php#style">-style</a>, and <a href="command-line-options.php#weight">-weight</a>. </p> 3998 3999 4000 <div style="margin: auto;"> 4001 <h3 class="magick-header"><a id="foreground"></a>-foreground <var>color</var></h3> 4002 </div> 4003 4004 <p class="magick-description">Define the foreground color for menus.", "display</p> 4005 4006 <p>The color is specified using the format described under the <a 4007 href="command-line-options.php#fill">-fill</a> option.</p> 4008 4009 <p>The default foreground color is black.</p> 4010 4011 <div style="margin: auto;"> 4012 <h3 class="magick-header"><a id="format"></a>-format <var>type</var></h3> 4013 </div> 4014 4015 <p class="magick-description">the image format type.</p> 4016 4017 <p>When used with the <code>mogrify</code> utility, this option converts any 4018 image to the image <a href="formats.php">format</a> you specify. 4019 For a list of image format types supported by ImageMagick, use <a 4020 href="command-line-options.php#list">-list format</a>.</p> 4021 4022 <p>By default the file is written to its original name. However, if the 4023 filename extension matches a supported format, the extension is replaced with 4024 the image format type specified with <a href="command-line-options.php#format">-format</a>. For 4025 example, if you specify <var>tiff</var> as the format type and the 4026 input image filename is <var>image.gif</var>, the output image 4027 filename becomes <var>image.tiff</var>.</p> 4028 4029 <div style="margin: auto;"> 4030 <h3 class="magick-header"><a id="format_identify_"></a>-format <var>string</var></h3> 4031 </div> 4032 4033 <p class="magick-description">output formatted image characteristics.</p> 4034 4035 <p>See <a href="escape.php">Format and Print Image 4036 Properties</a> for an explanation on how to specify the argument to this 4037 option.</p> 4038 4039 <div style="margin: auto;"> 4040 <h3 class="magick-header"><a id="frame"></a>-frame <var>geometry</var></h3> 4041 </div> 4042 4043 <p class="magick-description">Surround the image with a border or beveled frame.</p> 4044 4045 <p>The color of the border is specified with the <a href="command-line-options.php#mattecolor" 4046 >-mattecolor</a> command line option. </p> 4047 4048 <p>See <a href="command-line-processing.php#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 4049 height that is added to the dimensions of the image. If no offsets are given 4050 in the <var>geometry</var> argument, then the border added is 4051 a solid color. Offsets <var>x</var> and <var>y</var>, if present, specify that 4052 the width and height of the border is partitioned to form an outer bevel of 4053 thickness <var>x</var> pixels and an inner bevel of thickness 4054 <var>y</var> pixels. Negative offsets make no sense as frame arguments. 4055 </p> 4056 4057 <p>The <a href="command-line-options.php#frame">-frame</a> option is affected by the current <a 4058 href="command-line-options.php#compose">-compose</a> setting and assumes that this is using the default 4059 '<code>Over</code>' composition method. It generates an image of the appropriate 4060 size with the current <a href="command-line-options.php#bordercolor">-bordercolor</a> setting, and then 4061 draws the frame of four distinct colors close to the current <a 4062 href="command-line-options.php#mattecolor">-mattecolor</a>. The original image is then overlaid onto 4063 center of this image. This means that with the default compose method of 4064 '<code>Over</code>' any transparent parts may be replaced by the current <a 4065 href="command-line-options.php#bordercolor">-bordercolor</a> setting.</p> 4066 4067 <p>The image composition is not 4068 affected by the <a href="command-line-options.php#gravity">-gravity</a> option.</p> 4069 4070 4071 <div style="margin: auto;"> 4072 <h3 class="magick-header"><a id="frame_import_"></a>-frame</h3> 4073 </div> 4074 4075 <p class="magick-description">include the X window frame in the imported image. </p> 4076 <div style="margin: auto;"> 4077 <h3 class="magick-header"><a id="function"></a>-function <var>function</var> <var>parameters</var></h3> 4078 </div> 4079 4080 <p class="magick-description">Apply a function to channel values.</p> 4081 4082 <p>This operator performs calculations based on the given arguments to modify 4083 each of the color values for each previously set <a 4084 href="command-line-options.php#channel">-channel</a> in the image. See <a 4085 href="command-line-options.php#evaluate">-evaluate</a> for details concerning how the results of the 4086 calculations are handled.</p> 4087 4088 <p>This is can be considered a multi-argument version of the <a 4089 href="command-line-options.php#evaluate">-evaluate</a> operator. (Added in 4090 ImageMagick 6.4.88.)</p> 4091 4092 <p>Here, <var>parameters</var> is a comma-separated list of 4093 numerical values. The number of values varies depending on which <var>function</var> is selected. Choose the <var>function</var> from:</p> 4094 4095 <pre> 4096 Polynomial 4097 Sinusoid 4098 Arcsin 4099 Arctan 4100 </pre> 4101 4102 <p>To print a complete list of <a href="command-line-options.php#function">-function</a> operators, 4103 use <a href="command-line-options.php#list">-list function</a>. Descriptions follow.</p> 4104 4105 <dl class="dl-horizontal"> 4106 <dt>Polynomial</dt> 4107 <dd><p>The <code>Polynomial</code> function takes an arbitrary number of parameters, 4108 these being the coefficients of a polynomial, in decreasing order of degree. 4109 That is, entering</p> 4110 4111 <pre> 4112 -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> 4113 </pre> 4114 4115 <p>will invoke a polynomial function given by</p> 4116 4117 <pre> 4118 <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>, 4119 </pre> 4120 4121 <p>where <b><var>u</var></b> is pixel's original normalized channel value.</p> 4122 4123 <p>The <code>Polynomial</code> function can be used in place of <code>Set</code> 4124 (the <var>constant</var> polynomial) and <code>Add</code>, <code>Divide</code>, 4125 <code>Multiply</code>, and <code>Subtract</code> (some <var>linear</var> 4126 polynomials) of the <a href="command-line-options.php#evaluate">-evaluate</a> operator. The <a 4127 href="command-line-options.php#level">-level</a> operator also affects channels linearly. Some 4128 correspondences follow.</p> 4129 4130 <table class="table table-condensed table-striped"> 4131 <tr> 4132 <td>-evaluate Set <var>value</var> </td> 4133 <td>-function Polynomial <var>value</var></td> 4134 <td>(Constant functions; set <var>value</var>100% gray when channels are RGB.)</td> 4135 </tr> 4136 <tr> 4137 <td>-evaluate Add <var>value</var> </td> 4138 <td>-function Polynomial 1,<var>value</var></td> 4139 </tr> 4140 <tr> 4141 <td>-evaluate Subtract <var>value</var> </td> 4142 <td>-function Polynomial 1,<var>value</var></td> 4143 </tr> 4144 <tr> 4145 <td>-evaluate Multiply <var>value</var> </td> 4146 <td>-function Polynomial <var>value</var>,0</td> 4147 </tr> 4148 <tr> 4149 <td>+level black% x white%</td> 4150 <td>-function Polynomial A,B</td> 4151 <td>(Reduce contrast. Here, A=(white-black)/100 and B=black/100.)</td> 4152 </tr> 4153 </table> 4154 4155 <p>The <code>Polynomial</code> function gives great versatility, since 4156 polynomials can be used to fit any continuous curve to any degree of accuracy 4157 desired.</p> 4158 4159 </dd> 4160 <dt>Sinusoid</dt> 4161 <dd> 4162 <p>The <code>Sinusoid</code> function can be used to vary the channel values 4163 sinusoidally by setting frequency, phase shift, amplitude, and a bias. These 4164 values are given as one to four parameters, as follows,</p> 4165 4166 <pre> 4167 -function <code>Sinusoid</code> <var>freq</var>,[<var>phase</var>,[<var>amp</var>,[<var>bias</var>]]] 4168 </pre> 4169 4170 <p>where <var>phase</var> is in degrees. (The domain [0,1] of the function 4171 corresponds to 0 through <var>freq</var>360 degrees.) 4172 The result is that if a pixel's normalized channel value is originally 4173 <b><var>u</var></b>, its resulting normalized value is given by </p> 4174 4175 <pre> 4176 <var>amp</var> * sin(2** (<var>freq</var> * <b><var>u</var></b> + <var>phase</var> / 360)) + <var>bias</var> 4177 </pre> 4178 4179 <p> For example, the following generates a curve that starts and ends at 0.9 4180 (when <b><var>u</var></b>=0 and 1, resp.), oscillating three times between 4181 .7.2=.5 and .7+.2=.9. </p> 4182 4183 <pre> 4184 -function Sinusoid 3,-90,.2,.7 4185 </pre> 4186 4187 <p>The default values of <var>amp</var> and <var>bias</var> are both .5. The default for <var>phase</var> 4188 is 0.</p> 4189 4190 <p>The <code>Sinusoid</code> function generalizes <code>Sin</code> and 4191 <code>Cos</code> of the <a href="command-line-options.php#evaluate">-evaluate</a> operator by allowing 4192 varying amplitude, phase and bias. The correspondence is as follows.</p> 4193 4194 <table class="table table-condensed table-striped"> 4195 <tr> 4196 <td>-evaluate Sin <var>freq</var> </td> 4197 <td>-function Sinusoid <var>freq</var>,0 </td> 4198 </tr> 4199 <tr> 4200 <td>-evaluate Cos <var>freq</var> </td> 4201 <td>-function Sinusoid <var>freq</var>,90 </td> 4202 </tr> 4203 </table> 4204 </dd> 4205 <dt>ArcSin</dt> 4206 <dd> 4207 <p>The <code>ArcSin</code> function generates the inverse curve of a Sinusoid, 4208 and can be used to generate cylindrical distortion and displacement maps. 4209 The curve can be adjusted relative to both the input values and output range 4210 of values.</p> 4211 4212 <pre> 4213 -function <code>ArcSin</code> <var>width</var>,[<var>center</var>,[<var>range</var>,[<var>bias</var>]]] 4214 </pre> 4215 4216 <p>with all values given in terms of normalized color values (0.0 for black, 4217 1.0 for white). Defaulting to values covering the full range from 0.0 to 1.0 4218 for bout input (<var>width</var>), and output (<var>width</var>) values. '<code>1.0,0.5,1.0,0.5</code>' </p> 4219 4220 <pre> 4221 <var>range</var>/ * asin( 2/<var>width</var> * ( <b><var>u</var></b> - <var>center</var> ) ) + <var>bias</var> 4222 </pre> 4223 4224 </dd> 4225 <dt>ArcTan</dt> 4226 <dd> 4227 <p>The <code>ArcTan</code> function generates a curve that smooth crosses from 4228 limit values at infinities, though a center using the given slope value. 4229 All these values can be adjusted via the arguments.</p> 4230 4231 <pre> 4232 -function <code>ArcTan</code> <var>slope</var>,[<var>center</var>,[<var>range</var>,[<var>bias</var>]]] 4233 </pre> 4234 4235 <p>Defaulting to '<code>1.0,0.5,1.0,0.5</code>'. 4236 </p> 4237 4238 <pre> 4239 <var>range</var>/ * atan( <var>slope</var>* * ( <b><var>u</var></b> - <var>center</var> ) ) + <var>bias</var> 4240 </pre> 4241 </dd> 4242 </tr> 4243 </dl> 4244 4245 4246 4247 <div style="margin: auto;"> 4248 <h3 class="magick-header"><a id="fuzz"></a>-fuzz <var>distance</var>{<var>%</var>}</h3> 4249 </div> 4250 4251 <p class="magick-description">Colors within this <var>distance</var> are considered equal.</p> 4252 4253 <p>A number of algorithms search for a target color. By default the color must 4254 be exact. Use this option to match colors that are close to the target color 4255 in RGB space. For example, if you want to automagically trim the edges of an 4256 image with <a href="command-line-options.php#trim">-trim</a> but the image was scanned and the target 4257 background color may differ by a small amount. This option can account for 4258 these differences.</p> 4259 4260 <p>The <var>distance</var> can be in absolute intensity units or, by 4261 appending <code>%</code> as a percentage of the maximum possible intensity (255, 4262 65535, or 4294967295).</p> 4263 4264 <p>Use <a href="command-line-options.php#fuzz" >+fuzz</a> to reset the fuzz value to 0.</p> 4265 4266 4267 <div style="margin: auto;"> 4268 <h3 class="magick-header"><a id="fx"></a>-fx <var>expression</var></h3> 4269 </div> 4270 4271 <p class="magick-description">apply a mathematical expression to an image or image channels.</p> 4272 4273 <p>If the first character of <var>expression</var> is <code>@</code>, 4274 the expression is read from a file titled by the remaining characters in the 4275 string.</p> 4276 4277 <p>See <a href="fx.php">FX, 4278 The Special Effects Image Operator</a> for a detailed discussion of this 4279 option.</p> 4280 4281 4282 <div style="margin: auto;"> 4283 <h3 class="magick-header"><a id="gamma"></a>-gamma <var>value</var></h3> 4284 </div> 4285 4286 <p class="magick-description">level of gamma correction.</p> 4287 4288 <p>The same color image displayed on two different workstations may look 4289 different due to differences in the display monitor. Use gamma correction to 4290 adjust for this color difference. Reasonable values extend from 4291 <code>0.8</code> to <code>2.3</code>. Gamma less than 1.0 darkens the image and 4292 gamma greater than 1.0 lightens it. Large adjustments to image gamma may 4293 result in the loss of some image information if the pixel quantum size is only 4294 eight bits (quantum range 0 to 255).</p> 4295 4296 <p>Gamma adjusts the image's channel values pixel-by-pixel according to 4297 a power law, namely, pow(pixel,1/gamma) or pixel^(1/gamma), where pixel is the 4298 normalized or 0 to 1 color value. For example, using a value of gamma=2 is the 4299 same as taking the square root of the image.</p> 4300 4301 <p>You can apply separate gamma values to the red, green, and blue channels of 4302 the image with a gamma value list delimited with commas (e.g., 4303 <code>1.7,2.3,1.2</code>).</p> 4304 4305 <p>Use <a href="command-line-options.php#gamma">+gamma <var>value</var></a> to set the 4306 image gamma level without actually adjusting the image pixels. This option 4307 is useful if the image is of a known gamma but not set as an image attribute 4308 (e.g. PNG images). Write the "file gamma" which is the reciprocal of the 4309 display gamma; e.g., if your image is sRGB and you want to write a PNG gAMA 4310 chunk, use</p> 4311 4312 <pre> 4313 convert input.png +gamma .45455 output.png 4314 </pre> 4315 4316 <p>(0.45455 is 1/2.2)</p> 4317 4318 <p>Note that gamma adjustments are also available via the <a href="command-line-options.php#level">-level</a> operator.</p> 4319 4320 <div style="margin: auto;"> 4321 <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> 4322 </div> 4323 4324 <p class="magick-description">Blur the image with a Gaussian operator.</p> 4325 4326 <p>Convolve the image with a Gaussian or normal distribution using the given 4327 <var >Sigma</var> value. The formula is:</p> 4328 4329 <p class="text-center"><img class="img-thumbnail" alt="gaussian distribution" width="243px" height="42px" src="../image/gaussian-blur.png"/> </p> 4330 4331 <p>The <var >Sigma</var> value is the important argument, and 4332 determines the actual amount of blurring that will take place. </p> 4333 4334 <p>The <var >Radius</var> is only used to determine the size of the 4335 array which will hold the calculated Gaussian distribution. It should be an 4336 integer. If not given, or set to zero, IM will calculate the largest possible 4337 radius that will provide meaningful results for the Gaussian distribution. 4338 </p> 4339 4340 <p>The larger the <var >Radius</var> the radius the slower the 4341 operation is. However too small a <var >Radius</var>, and sever 4342 aliasing effects may result. As a guideline, <var >Radius</var> 4343 should be at least twice the <var >Sigma</var> value, though three 4344 times will produce a more accurate result. </p> 4345 4346 <p>This differs from the faster <a href="command-line-options.php#blur">-blur</a> operator in that a 4347 full 2-dimensional convolution is used to generate the weighted average of the 4348 neighboring pixels. </p> 4349 4350 <p>The <a href="command-line-options.php#virtual-pixel">-virtual-pixel</a> setting will determine how 4351 pixels which are outside the image proper are blurred into the final result. 4352 </p> 4353 4354 4355 <div style="margin: auto;"> 4356 <h3 class="magick-header"><a id="geometry"></a>-geometry <var>geometry</var></h3> 4357 </div> 4358 4359 <p class="magick-description">Set the preferred size and location of the image.</p> 4360 4361 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 4362 4363 <div style="margin: auto;"> 4364 <h3 class="magick-header"><a id="gravity"></a>-gravity <var>type</var></h3> 4365 </div> 4366 4367 <p class="magick-description">Sets the current gravity suggestion for various other settings and options.</p> 4368 4369 <p>Choices include: <code>NorthWest</code>, <code>North</code>, 4370 <code>NorthEast</code>, <code>West</code>, <code>Center</code>, <code>East</code>, 4371 <code>SouthWest</code>, <code>South</code>, <code>SouthEast</code>. Use <a 4372 href="command-line-options.php#list">-list gravity</a> to get a complete list of <a 4373 href="command-line-options.php#gravity">-gravity</a> settings available in your ImageMagick 4374 installation.</p> 4375 4376 <p>The direction you choose specifies where to position text or subimages. For 4377 example, a gravity of <code>Center</code> forces the text to be centered within 4378 the image. By default, the image gravity is <code>NorthWest</code>. See <a 4379 href="command-line-options.php#draw">-draw</a> for more details about graphic primitives. Only the 4380 text primitive of <a href="command-line-options.php#draw">-draw</a> is affected by the <a 4381 href="command-line-options.php#gravity">-gravity</a> option.</p> 4382 4383 <p>The <a href="command-line-options.php#gravity">-gravity</a> option is also used in concert with the 4384 <a href="command-line-options.php#geometry">-geometry</a> setting and other settings or options that 4385 take <var>geometry</var> as an argument, such as the <a 4386 href="command-line-options.php#crop">-crop</a> option. </p> 4387 4388 <p>If a <a href="command-line-options.php#gravity">-gravity</a> setting occurs before another option 4389 or setting having a <var>geometry</var> argument that specifies an 4390 offset, the offset is usually applied to the point within the image suggested 4391 by the <a href="command-line-options.php#gravity">-gravity</a> argument. Thus, in the following 4392 command, for example, suppose the file <code>image.png</code> has dimensions 4393 200x100. The offset specified by the argument to <a href="command-line-options.php#region">-region</a> 4394 is (40,+20). The argument to <a href="command-line-options.php#gravity">-gravity</a> is 4395 <code>Center</code>, which suggests the midpoint of the image, at the point 4396 (100,50). The offset (40,20) is applied to that point, giving 4397 (10040,50+20)=(60,70), so the specified 10x10 region is located at 4398 that point. (In addition, the <a href="command-line-options.php#gravity">-gravity</a> affects the 4399 region itself, which is <var>centered</var> at the pixel 4400 coordinate (60,70). (See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.)</p> 4401 4402 <pre> 4403 convert image.png -gravity Center -region 10x10-40+20 \ 4404 -negate output.png 4405 </pre> 4406 4407 <p>When used as an option to <a href="composite.php">composite</a>, <a 4408 href="command-line-options.php#gravity">-gravity</a> gives the direction that the image gravitates 4409 within the composite.</p> 4410 4411 <p>When used as an option to <a href="montage.php">montage</a>, <a 4412 href="command-line-options.php#gravity">-gravity</a> gives the direction that an image gravitates 4413 within a tile. The default gravity is <code>Center</code> for this purpose.</p> 4414 4415 4416 <div style="margin: auto;"> 4417 <h3 class="magick-header"><a id="grayscale"></a>-grayscale <var>method</var></h3> 4418 </div> 4419 4420 <p class="magick-description">convert image to grayscale.</p> 4421 4422 <p>This will use one of the <a href="command-line-options.php#intensity" >-intensity</a> methods to 4423 convert the given image into a linear-grayscale image. </p> 4424 4425 <p>For example, to convert an image to (linear) Rec709Luminance grayscale, type:</p> 4426 4427 <pre> 4428 convert in.png -grayscale Rec709Luminance out.png 4429 </pre> 4430 4431 <p>which is equivalent to:</p> 4432 4433 <pre> 4434 convert in.png -colorspace gray out.png 4435 </pre> 4436 4437 <p>Similarly, to convert an image to (non-linear) Rec709Luma grayscale, type:</p> 4438 4439 <pre> 4440 convert in.png -grayscale Rec709Luma out.png 4441 </pre> 4442 4443 <p>which is equivalent to:</p> 4444 4445 <pre> 4446 convert in.png -set colorspace RGB -colorspace gray out.png 4447 </pre> 4448 4449 <p>Note that a 'colorspace' intensity method will produce the same result 4450 regardless of the current colorpsace of the image. But a 'mathematical' 4451 intensity method will depend on the current colorspace the image is currently 4452 using. </p> 4453 4454 <p>While this operation uses an <a href="command-line-options.php#intensity" >-intensity</a> method, 4455 it does not use or set the <a href="command-line-options.php#intensity" >-intensity</a> setting, so 4456 will not effect other operations that may use that setting.</p> 4457 4458 4459 <div style="margin: auto;"> 4460 <h3 class="magick-header"><a id="green-primary"></a>-green-primary <var>x,y</var></h3> 4461 </div> 4462 4463 <p class="magick-description">green chromaticity primary point.</p> 4464 4465 4466 <div style="margin: auto;"> 4467 <h3 class="magick-header"><a id="hald-clut"></a>-hald-clut</h3> 4468 </div> 4469 4470 <p class="magick-description">apply a Hald color lookup table to the image.</p> 4471 4472 <p>A Hald color lookup table is a 3-dimensional color cube mapped to 2 4473 dimensions. Create it with the <code>HALD:</code> prefix (e.g. HALD:8). You 4474 can apply any color transformation to the Hald image and then use this option 4475 to apply the transform to the image. </p> 4476 4477 <pre> 4478 convert image.png hald.png -hald-clut transform.png 4479 </pre> 4480 4481 <p>This option provides a convenient method for you to use Gimp or Photoshop 4482 to make color corrections to the Hald CLUT image and subsequently apply them 4483 to multiple images using an ImageMagick script. </p> 4484 4485 <p>Note that the representation is only of the normal RGB color space and that 4486 the whole color value triplet is used for the interpolated lookup of the 4487 represented Hald color cube image. Because of this the operation is not <a 4488 href="command-line-options.php#channel" >-channel</a> setting effected, nor can it adjust or modify an 4489 images transparency or alpha/matte channel.</p> 4490 4491 <p>See also <a href="command-line-options.php#clut" >-clut</a> which provides color value replacement 4492 of the individual color channels, usually involving a simpler grayscale 4493 image. E.g: grayscale to color replacement, or modification by a histogram 4494 mapping. </p> 4495 4496 4497 <div style="margin: auto;"> 4498 <h3 class="magick-header"><a id="help"></a>-help</h3> 4499 </div> 4500 4501 <p class="magick-description">print usage instructions.</p> 4502 4503 <div style="margin: auto;"> 4504 <h3 class="magick-header"><a id="highlight-color"></a>-highlight-color <var>color</var></h3> 4505 </div> 4506 4507 <p class="magick-description">when comparing images, emphasize pixel differences with this color.</p> 4508 4509 <div style="margin: auto;"> 4510 <h3 class="magick-header"><a id="hough-lines"></a>-hough-lines <var>width</var>x<var>height</var>{<var>+threshold</var>}</h3> 4511 </div> 4512 4513 <p class="magick-description">identify straight lines in the image (e.g. -hough-lines 9x9+195).</p> 4514 4515 <p>Use the Hough line detector with any binary edge extracted image to locate and draw any straight lines that it finds.</p> 4516 4517 <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>. 4518 4519 <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> 4520 4521 <p>Use <code><a href="command-line-options.php#background" >-background</a></code> to specify the color of the background onto which the lines will be drawn. The default is black.</p> 4522 4523 <p>Use <code><a href="command-line-options.php#fill" >-fill</a></code> to specify the color of the lines. The default is black.</p> 4524 4525 <p>Use <code><a href="command-line-options.php#stroke" >-stroke</a></code> and <code><a href="command-line-options.php#strokewidth" >-strokewidth</a></code> to specify the thickness of the lines. The default is black and no strokewidth.</p> 4526 4527 <p>A text file listing the endpoints and counts may be created by using the suffix, .mvg, for the output image.</p> 4528 4529 <p>Use <code><a href="command-line-options.php#define" >-define</a> hough-lines:accumulator=true</code> to return the accumulator image in addition to the lines image.</p> 4530 4531 <div style="margin: auto;"> 4532 <h3 class="magick-header"><a id="iconGeometry"></a>-iconGeometry <var>geometry</var></h3> 4533 </div> 4534 4535 <p class="magick-description">specify the icon geometry.</p> 4536 4537 <p>Offsets, if present in the geometry specification, are handled in the same 4538 manner as the <a href="command-line-options.php#geometry">-geometry</a> option, using X11 style to 4539 handle negative offsets.</p> 4540 4541 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 4542 4543 <div style="margin: auto;"> 4544 <h3 class="magick-header"><a id="iconic"></a>-iconic</h3> 4545 </div> 4546 4547 <p class="magick-description">start in icon mode in X Windows", 'animate', 'display</p> 4548 4549 <div style="margin: auto;"> 4550 <h3 class="magick-header"><a id="identify"></a>-identify</h3> 4551 </div> 4552 4553 <p class="magick-description">identify the format and characteristics of the image.</p> 4554 4555 <p>This information is printed: image scene number; image name; image size; 4556 the image class (<var>DirectClass</var> or <var>PseudoClass</var>); the total number of unique colors; and the 4557 number of seconds to read and transform the image. Refer to <a href="miff.php">MIFF</a> for 4558 a description of the image class.</p> 4559 4560 <p>If <a href="command-line-options.php#colors">-colors</a> is also specified, the total unique colors 4561 in the image and color reduction error values are printed. Refer to <a 4562 href="quantize.php">color 4563 reduction algorithm</a> for a description of these values.</p> 4564 4565 <p>If <a href="command-line-options.php#verbose">-verbose</a> precedes this option, copious 4566 amounts of image properties are displayed including image statistics, profiles, 4567 image histogram, and others.</p> 4568 4569 <div style="margin: auto;"> 4570 <h3 class="magick-header"><a id="ift"></a>-ift</h3> 4571 </div> 4572 4573 <p class="magick-description">implements the inverse discrete Fourier transform (DFT).</p> 4574 4575 <p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows 4576 users in ImageMagick 6.6.0-9). It transforms a pair of magnitude and phase 4577 images from the frequency domain to a single image in the normal or spatial 4578 domain. See for example, <a 4579 href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier Transform</a>, 4580 <a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier Transform</a> and 4581 <a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier Transform</a>.</p> 4582 4583 <p>For example, depending upon the image format used to store the result of 4584 the <a href="command-line-options.php#fft">-fft</a>, one would use either</p> 4585 4586 <pre> 4587 convert fft_image.miff -ift fft_image_ift.png 4588 </pre> 4589 4590 <p>or</p> 4591 4592 <pre> 4593 convert fft_image-0.png fft_image-1.png -ift fft_image_ift.png 4594 </pre> 4595 4596 <p>The resulting image may need to be cropped due to padding introduced when 4597 the original image, prior to the <a href="command-line-options.php#fft">-fft</a> or <a 4598 href="command-line-options.php#fft">+fft</a>, was not square or even dimensioned. Any padding is at 4599 the right and/or bottom sides of the image.</p> 4600 4601 <p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to 4602 use <a href="command-line-options.php#ift">-ift</a>.</p> 4603 4604 <p>Use <a href="command-line-options.php#ift">+ift</a> (with HDRI enabled) to transform a pair of real 4605 and imaginary images from the frequency domain to a single image in the normal 4606 (spatial) domain.</p> 4607 4608 <p>By default the IFT is not normalized (and the FFT is). Use "<code><a href="command-line-options.php#define" >-define</a> fourier:normalize=inverse</code> to explicitly normalize the IFT and unnormalize the FFT.</p> 4609 4610 <div style="margin: auto;"> 4611 <h3 class="magick-header"><a id="immutable"></a>-immutable</h3> 4612 </div> 4613 4614 <p class="magick-description">make image immutable.</p> 4615 4616 <div style="margin: auto;"> 4617 <h3 class="magick-header"><a id="implode"></a>-implode <var>factor</var></h3> 4618 </div> 4619 4620 <p class="magick-description">implode image pixels about the center.</p> 4621 4622 <div style="margin: auto;"> 4623 <h3 class="magick-header"><a id="insert"></a>-insert <var>index</var></h3> 4624 </div> 4625 4626 <p class="magick-description">insert the last image into the image sequence.</p> 4627 4628 <p>This option takes last image in the current image sequence and inserts it 4629 at the given index. If a negative index is used, the insert position is 4630 calculated before the last image is removed from the sequence. As such 4631 <code>-insert -1</code> will result in no change to the image sequence.</p> 4632 4633 <p>The <code>+insert</code> option is equivalent to <code>-insert -1</code>. In 4634 other words, insert the last image, at the end of the current image sequence. 4635 Consequently this has no effect on the image sequence order.</p> 4636 4637 <div style="margin: auto;"> 4638 <h3 class="magick-header"><a id="intensity"></a>-intensity <var>method</var></h3> 4639 </div> 4640 4641 <p class="magick-description">method to generate intensity value from pixel.</p> 4642 4643 <p>ImageMagick provides a number of methods used in situations where an 4644 operator needs to determine a single grayscale value for some purpose, from 4645 an image with red, green, and blue pixel components. Typically the linear 4646 <code>Rec709Luminance</code> formula is used, which is the same formula used when 4647 converting images to <code>-colorspace gray</code>. </p> 4648 4649 <p>The following formulas are currently provided, and will first convert 4650 the pixel values to linear-RGB or non-linear sRGB colorspace before 4651 being applied to calculate the final greyscale value. </p> 4652 4653 <dl class="dl-horizontal"> 4654 <dt>Rec601Luma</dt><dd> 0.298839R' + 0.586811G'+ 0.114350B'</dd> 4655 <dt>Rec601Luminance</dt><dd> 0.298839R + 0.586811G + 0.114350B</dd> 4656 <dt>Rec709Luma</dt><dd> 0.212656R' + 0.715158G' + 0.072186B'</dd> 4657 <dt>Rec709Luminance</dt><dd> 0.212656R + 0.715158G + 0.072186B</dd> 4658 <dt>Brightness</dt><dd> max(R', G', B')</dd> 4659 <dt>Lightness</dt><dd> (min(R', G', B') + max(R', G', B')) / 2.0</dd> 4660 </dl> 4661 4662 <p>Note that the above R,G,B values is the image's linear-RGB values, while 4663 R',G',B' are sRGB non-linear values. </p> 4664 4665 <p>These intensity methods are mathematical in nature and will use the 4666 current value in the images respective R,G,B channel regardless of 4667 what that is, or what colorspace the image is currently using.</p> 4668 4669 <dl class="dl-horizontal"> 4670 <dt>Average</dt><dd>(R + G + B) / 3.0</dd> 4671 <dt>MS</dt><dd>(R^2 + G^2 + B^2) / 3.0</dd> 4672 <dt>RMS</dt><dd>sqrt( (R^2 + G^2 + B^2) / 3.0 )</dd> 4673 </dl> 4674 4675 <p>These methods are often used for other purposes, such as generating a 4676 grayscale difference image between two color images (using <a href="command-line-options.php#compose" 4677 >-compose</a> '<code>Difference</code>' composition. </p> 4678 4679 <p> For example The 'MS' (Mean Squared) setting is good for minimizing color 4680 error comparisions. While... The method 'RMS' (Root Mean Squared) for 4681 example is appropriate for calculating color vector distance, from a color 4682 difference image. This is equivalent to the color only component of the <a 4683 href="command-line-options.php#fuzz" >-fuzz</a> factor color compare setting. </p> 4684 4685 <p>See also <a href="command-line-options.php#grayscale" >-grayscale</a> which applies one of the above 4686 grayscaling formula directly to an image without setting the <a 4687 href="command-line-options.php#intensity" >-intensity</a> setting.</p> 4688 4689 <p>The <a href="command-line-options.php#colorspace" >-colorspace gray</a> image conversion also uses 4690 the current intensity setting, but will always convert the image to the 4691 appropriate sRGB or linear-RGB colorspace before appling the above 4692 function.</p> 4693 4694 <p>To print a complete list of possible pixel intensity setting methods, use <a href="command-line-options.php#list">-list intensity</a>.</p> 4695 4696 <p>Operators affected by the <a href="command-line-options.php#intensity" >-intensity</a> setting include:</p> 4697 4698 <pre> 4699 -adaptive-blur 4700 -adaptive-sharpen 4701 -black-threshold 4702 -clut (when mapping greyscale CLUT image to alpha channel if set by -channels) 4703 -colors for gray colorspace 4704 -compose {LightenIntensity, DarkenIntensity, CopyOpacity, CopyBlack} 4705 -contrast-stretch 4706 -distort {ErodeIntensity, DilateIntensity} 4707 -normalize 4708 -random-threshold 4709 -selective-blur 4710 -shade 4711 -threshold 4712 -tint 4713 -white-threshold 4714 </pre> 4715 4716 <div style="margin: auto;"> 4717 <h3 class="magick-header"><a id="intent"></a>-intent <var>type</var></h3> 4718 </div> 4719 4720 <p class="magick-description">use this type of rendering intent when managing the image color.</p> 4721 4722 <p>Use this option to affect the color management operation of an image (see 4723 <a href="command-line-options.php#profile">-profile</a>). Choose from these intents: <code>Absolute, 4724 Perceptual, Relative, Saturation</code>.</p> 4725 4726 <p>The default intent is Perceptual for the sRGB colorspace and undefined for the RGB and gray colorspaces.</p> 4727 4728 <p>To print a complete list of rendering intents, use <a href="command-line-options.php#list">-list intent</a>.</p> 4729 4730 <div style="margin: auto;"> 4731 <h3 class="magick-header"><a id="interlace"></a>-interlace <var>type</var></h3> 4732 </div> 4733 4734 <p class="magick-description">the type of interlacing scheme.</p> 4735 4736 <p>Choose from:</p> 4737 4738 <pre> 4739 none 4740 line 4741 plane 4742 partition 4743 JPEG 4744 GIF 4745 PNG 4746 </pre> 4747 4748 <p>This option is used to specify the type of interlacing scheme for raw image 4749 formats such as <code>RGB</code> or <code>YUV</code>.</p> 4750 4751 <p><code>None</code> means do not interlace (RGBRGBRGBRGBRGBRGB...),</p> 4752 4753 <p><code>Line</code> uses scanline interlacing (RRR...GGG...BBB...RRR...GGG...BBB...), and.</p> 4754 4755 <p><code>Plane</code> uses plane interlacing (RRRRRR...GGGGGG...BBBBBB...).</p> 4756 4757 <p><code>Partition</code> is like plane except the different planes are saved to 4758 individual files (e.g. image.R, image.G, and image.B).</p> 4759 4760 <p>Use <code>Line</code> or <code>Plane</code> to create an <code>interlaced 4761 PNG</code> or <code>GIF</code> or <code>progressive JPEG</code> image.</p> 4762 4763 <p>To print a complete list of interlacing schemes, use <a href="command-line-options.php#list">-list 4764 interlace</a>.</p> 4765 4766 <div style="margin: auto;"> 4767 <h3 class="magick-header"><a id="interpolate"></a>-interpolate <var>type</var></h3> 4768 </div> 4769 4770 <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> 4771 4772 <p>When looking up the color of a pixel using a non-integer floating point 4773 value, you typically fall in between the pixel colors defined by the source 4774 image. This setting determines how the color is determined from the colors of 4775 the pixels surrounding that point. That is how to determine the color of a 4776 point that falls between two, or even four different colored pixels. </p> 4777 4778 <dl class="dl-horizontal"> 4779 <dt>integer</dt> 4780 <dd>The color of the top-left pixel (floor function)</dd> 4781 <dt>nearest-neighbor</dt> 4782 <dd>The nearest pixel to the lookup point (rounded function)</dd> 4783 <dt>average</dt> 4784 <dd>The average color of the surrounding four pixels</dd> 4785 <dt>bilinear</dt> 4786 <dd>A double linear interpolation of pixels (the default)</dd> 4787 <dt>mesh</dt> 4788 <dd>Divide area into two flat triangular interpolations</dd> 4789 <dt>bicubic</dt> 4790 <dd>Fitted bicubic-spines of surrounding 16 pixels</dd> 4791 <dt>spline</dt> 4792 <dd>Direct spline curves (colors are blurred)</dd> 4793 <dt>filter</dt> 4794 <dd>Use resize <a href="command-line-options.php#filter">-filter</a> settings</dd> 4795 </dl> 4796 4797 <p>This most important for distortion operators such as <a href="command-line-options.php#distort" 4798 >-distort</a>, <a href="command-line-options.php#implode" >-implode</a>, <a href="command-line-options.php#transform" 4799 >-transform</a> and <a href="command-line-options.php#fx" >-fx</a>. </p> 4800 4801 <p>To print a complete list of interpolation methods, use <a href="command-line-options.php#list">-list interpolate</a>.</p> 4802 4803 <p>See also <a href="command-line-options.php#virtual-pixel" >-virtual-pixel</a>, for control of the 4804 lookup for positions outside the boundaries of the image. </p> 4805 4806 4807 <div style="margin: auto;"> 4808 <h3 class="magick-header"><a id="interline-spacing"></a>-interline-spacing <var>value</var></h3> 4809 </div> 4810 4811 <p class="magick-description">the space between two text lines.</p> 4812 4813 <div style="margin: auto;"> 4814 <h3 class="magick-header"><a id="interword-spacing"></a>-interword-spacing <var>value</var></h3> 4815 </div> 4816 4817 <p class="magick-description">the space between two words.</p> 4818 4819 <div style="margin: auto;"> 4820 <h3 class="magick-header"><a id="kerning"></a>-kerning <var>value</var></h3> 4821 </div> 4822 4823 <p class="magick-description">the space between two letters.</p> 4824 4825 <div style="margin: auto;"> 4826 <h3 class="magick-header"><a id="kuwahara"></a>-kuwahara <var>radius</var><br />-kuwahara <var>radius</var>x<var>sigma</var></h3> 4827 </div> 4828 4829 <p class="magick-description">edge preserving noise reduction filter.</p> 4830 4831 <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> 4832 4833 4834 <div style="margin: auto;"> 4835 <h3 class="magick-header"><a id="label"></a>-label <var>name</var></h3> 4836 </div> 4837 4838 <p class="magick-description">assign a label to an image.</p> 4839 4840 <p>Use this option to assign a specific label to the image, as it is read in 4841 or created. You can use the <a href="command-line-options.php#set" >-set</a> operation to re-assign 4842 a the labels of images already read in. Image formats such as TIFF, PNG, 4843 MIFF, supports saving the label information with the image.</p> 4844 4845 <p>When saving an image to a <var>PostScript</var> file, any label 4846 assigned to an image is used as a header string to print above the postscript 4847 image. </p> 4848 4849 <p>You can include the image filename, type, width, height, or other image 4850 attribute by embedding special format character. See <a href="escape.php">Format and Print Image 4851 Properties</a> for details of the percent escape codes.</p> 4852 4853 <p>For example,</p> 4854 4855 <pre> 4856 -label "%m:%f %wx%h" bird.miff 4857 </pre> 4858 4859 <p>assigns an image label of <code>MIFF:bird.miff 512x480</code> to the 4860 "<code>bird.miff</code>" image and whose width is 512 and height is 480, as it 4861 is read in. If a <a href="command-line-options.php#label">+label</a> option was used instead, any 4862 existing label present in the image would be used. You can remove all labels 4863 from an image by assigning the empty string. </p> 4864 4865 <p>A label is not drawn on the image, but is embedded in the image datastream 4866 via <var>Label</var> tag or similar mechanism. If you want the label to be 4867 visible on the image itself, use the <a href="command-line-options.php#draw">-draw</a> option, or 4868 during the final processing in the creation of an image montage.</p> 4869 4870 <p>If the first character of <var>string</var> is <var>@</var>, the image label is read from a file titled by the 4871 remaining characters in the string. Labels in a file are literal, no embedded 4872 formatting characters are recognized.</p> 4873 4874 4875 <div style="margin: auto;"> 4876 <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> 4877 </div> 4878 4879 <p class="magick-description">perform local adaptive threshold.</p> 4880 4881 <p>Adaptively threshold each pixel based on the value of pixels in a 4882 surrounding window. If the current pixel is lighter than this average plus 4883 the optional <code>offset</code>, then it is made white, otherwise it is made 4884 black. Small variations in pixel values such as found in scanned documents 4885 can be ignored if offset is positive. A negative offset will make it more 4886 sensitive to those small variations. </p> 4887 4888 <p>This is commonly used to threshold images with an uneven background. It is 4889 based on the assumption that average color of the small window is the 4890 the local background color, from which to separate the foreground color. </p> 4891 4892 4893 <div style="margin: auto;"> 4894 <h3 class="magick-header"><a id="layers"></a>-layers <var>method</var></h3> 4895 </div> 4896 4897 <p class="magick-description">handle multiple images forming a set of image layers or animation frames.</p> 4898 4899 <p>Perform various image operation methods to a ordered sequence of images 4900 which may represent either a set of overlaid 'image layers', a GIF disposal 4901 animation, or a fully-'coalesced' animation sequence. </p> 4902 4903 <table class="table table-condensed table-striped"> 4904 <tbody> 4905 <tr> 4906 <th style="width: 8%">Method</th> 4907 <th>Description</th> 4908 </tr> 4909 4910 <tr> 4911 <td>compare-any</td> 4912 <td>Crop the second and later frames to the smallest rectangle 4913 that contains all the differences between the two images. No GIF <a 4914 href="command-line-options.php#dispose" >-dispose</a> methods are taken into account. </td> 4915 </tr> 4916 4917 <tr><td></td><td>This exactly the same as the <a href="command-line-options.php#deconstruct" 4918 >-deconstruct</a> operator, and does not preserve animations normal 4919 working, especially when animation used layer disposal methods such as 4920 '<code>Previous</code>' or '<code>Background</code>'. </td> 4921 </tr> 4922 4923 <tr> 4924 <td>compare-clear</td> 4925 <td>As '<code>compare-any</code>' but crop to the bounds of any 4926 opaque pixels which become transparent in the second frame. That is the 4927 smallest image needed to mask or erase pixels for the next frame. </td> 4928 </tr> 4929 4930 <tr> 4931 <td>compare-overlay</td> 4932 <td>As '<code>compare-any</code>' but crop to pixels that add 4933 extra color to the next image, as a result of overlaying color pixels. 4934 That is the smallest single overlaid image to add or change colors. </td> 4935 </tr> 4936 4937 <tr><td></td><td>This can be used with the <a href="command-line-options.php#compose" >-compose</a> alpha 4938 composition method '<code>change-mask</code>', to reduce the image to 4939 just the pixels that need to be overlaid. </td> 4940 </tr> 4941 4942 <tr> 4943 <td>coalesce</td> 4944 <td>Equivalent to a call to the <a href="command-line-options.php#coalesce" 4945 >-coalesce</a> operator. Apply the layer disposal methods set in the 4946 current image sequence to form a fully defined animation sequence, as 4947 it should be displayed. Effectively converting a GIF animation into a 4948 'film strip'-like animation. </td> 4949 </tr> 4950 4951 <tr> 4952 <td>composite</td> 4953 <td>Alpha Composition of two image lists, separated by a 4954 "<code>null:</code>" image, with the destination image list first, and 4955 the source images last. An image from each list are composited 4956 together until one list is finished. The separator image and source 4957 image lists are removed. </td> 4958 </tr> 4959 4960 4961 <tr><td></td> 4962 <td>The <a href="command-line-options.php#geometry" >-geometry</a> offset is adjusted according 4963 to <a href="command-line-options.php#gravity" >-gravity</a> in accordance of the virtual 4964 canvas size of the first image in each list. Unlike a normal <a 4965 href="command-line-options.php#composite" >-composite</a> operation, the canvas offset is also 4966 added to the final composite positioning of each image. </td> </tr> 4967 4968 <tr><td></td> 4969 <td>If one of the image lists only contains one image, that image is 4970 applied to all the images in the other image list, regardless of which 4971 list it is. In this case it is the image meta-data of the list which 4972 preserved. </td> 4973 </tr> 4974 4975 4976 <tr> 4977 <td>dispose</td> 4978 <td>This like '<code>coalesce</code>' but shows the look of 4979 the animation after the layer disposal method has been applied, before 4980 the next sub-frame image is overlaid. That is the 'dispose' image that 4981 results from the application of the GIF <a href="command-line-options.php#dispose" 4982 >-dispose</a> method. This allows you to check what 4983 is going wrong with a particular animation you may be developing. 4984 </td> 4985 </tr> 4986 4987 <tr> 4988 <td>flatten</td> 4989 <td>Create a canvas the size of the first images virtual 4990 canvas using the current <a href="command-line-options.php#background" >-background</a> color, 4991 and <a href="command-line-options.php#compose" >-compose</a> each image in turn onto that 4992 canvas. Images falling outside that canvas is clipped. Final 4993 image will have a zero virtual canvas offset. </td> 4994 </tr> 4995 4996 <tr><td></td> 4997 <td>This usually used as one of the final 'image layering' operations 4998 overlaying all the prepared image layers into a final image. </td> 4999 </tr> 5000 5001 <tr><td></td> 5002 <td>For a single image this method can also be used to fillout a virtual 5003 canvas with real pixels, or to underlay an opaque color to remove 5004 transparency from an image.</td> 5005 </tr> 5006 5007 5008 <tr> 5009 <td>merge</td> 5010 <td>As 'flatten' method but merging all the given image 5011 layers to create a new layer image just large enough to hold all the 5012 image without clipping or extra space. The new images virtual offset 5013 will preserve the position of the new layer, even if this offset is 5014 negative. The virtual canvas size of the first image is preserved. 5015 </td> 5016 </tr> 5017 5018 <tr><td></td><td>Caution is advised when handling image layers with 5019 negative offsets as few image file formats handle them correctly. 5020 Following this operation method with <a href="command-line-options.php#repage" >+repage</a> 5021 will remove the layer offset, and create an image in which all the 5022 overlaid image positions relative to each other is preserved, though 5023 not necessarily exactly where you specified them. 5024 </td> 5025 </tr> 5026 5027 <tr><td></td><td>See also 'trim-bounds' below which is closely related but 5028 without doing the'flatten' to merge the images together. </td> 5029 </tr> 5030 5031 <tr> 5032 <td>mosaic</td> 5033 <td>As 'flatten' method but expanding the initial canvas size 5034 of the first image in a positive direction only so as to hold all the 5035 image layers. However as a virtual canvas is 'locked' to the origin, 5036 by its own definition, image layers with a negative offsets will still 5037 become clipped by the top and left edges. See 'merge' or 'trim-bounds' 5038 if this could be a problem. </td> 5039 5040 </tr> 5041 5042 <tr><td></td><td>This method is commonly used to layout individual image 5043 using various offset but without knowing the final canvas size. The 5044 resulting image will, like 'flatten' not have any virtual offset, so 5045 can be saved to any image file format. </td> 5046 </tr> 5047 5048 5049 <tr> 5050 <td>optimize</td> 5051 <td>Optimize a coalesced animation, into GIF animation using 5052 a number of general techniques. This currently a short cut to 5053 apply both the '<code>optimize-frame</code>', and 5054 '<code>optimize-transparency</code>' methods but may be expanded to 5055 include other optimization methods as they are developed. </td> 5056 </tr> 5057 5058 <tr> 5059 <td>optimize-frame</td> 5060 <td>Optimize a coalesced animation, into GIF animation by 5061 reducing the number of pixels per frame as much as possible by 5062 attempting to pick the best layer disposal method to use, while ensuring 5063 the result will continue to animate properly. </td> 5064 </tr> 5065 5066 <tr><td></td><td> There is no guarantee that the best optimization is found. 5067 But then no reasonably fast GIF optimization algorithm can do this. 5068 However this does seem to do better than most other GIF frame 5069 optimizers seen. </td> 5070 </tr> 5071 5072 <tr> 5073 <td>optimize-plus</td> 5074 <td>As '<code>optimize-frame</code>' but attempt to improve the 5075 overall optimization by adding extra frames to the animation, without 5076 changing the final look or timing of the animation. The frames are 5077 added to attempt to separate the clearing of pixels from the 5078 overlaying of new additional pixels from one animation frame to the 5079 next. If this does not improve the optimization (for the next frame 5080 only), it will fall back to the results of the previous normal 5081 '<code>optimize-frame</code>' technique. </td> 5082 </tr> 5083 5084 <tr><td></td><td>There is the possibility that the change in the disposal 5085 style will result in a worsening in the optimization of later frames, 5086 though this is unlikely. In other words there no guarantee that it is 5087 better than the normal '<code>optimize-frame</code>' technique. For some 5088 animations however you can get a vast improvement in the final 5089 animation size. </td> 5090 </tr> 5091 5092 <tr> 5093 <td>optimize-transparency</td> 5094 <td>Given a GIF animation, replace any pixel in the sub-frame 5095 overlay images with transparency, if it does not change the resulting 5096 animation by more than the current <a href="command-line-options.php#fuzz" >-fuzz</a> factor. 5097 </td> 5098 </tr> 5099 5100 <tr><td></td><td>This should allow a existing frame optimized GIF animation 5101 to compress into a smaller file size due to larger areas of one 5102 (transparent) color rather than a pattern of multiple colors repeating 5103 the current disposed image of the last frame. </td> 5104 </tr> 5105 5106 <tr> 5107 <td>remove-dups</td> 5108 <td>Remove (and merge time delays) of duplicate consecutive 5109 images, so as to simplify layer overlays of coalesced animations. 5110 </td> 5111 </tr> 5112 5113 <tr><td></td><td>Usually this a result of using a constant time delay 5114 across the whole animation, or after a larger animation was split into 5115 smaller sub-animations. The duplicate frames could also have been 5116 used as part of some frame optimization methods. </td> 5117 </tr> 5118 5119 <tr> 5120 <td>remove-zero</td> 5121 <td>Remove any image with a zero time delay, unless ALL the 5122 images have a zero time delay (and is not a proper timed animation, a 5123 warning is then issued). </td> 5124 </tr> 5125 5126 <tr><td></td><td>In a GIF animation, such images are usually frames which 5127 provide partial intermediary updates between the frames that are 5128 actually displayed to users. These frames are usually added for 5129 improved frame optimization in GIF animations. </td> 5130 </tr> 5131 5132 <tr> 5133 <td>trim-bounds</td> 5134 <td>Find the bounds of all the images in the current 5135 image sequence, then adjust the offsets so all images are contained on 5136 a minimal positive canvas. None of the image data is modified or 5137 merged, only the individual image virtual canvas size and offset. 5138 All the images is given the same canvas size, and and will have 5139 a positive offset, but will remain in the same position relative to 5140 each other. As a result of the minimal canvas size at least one image 5141 will touch every edge of that canvas. The image data touching those 5142 edges however may be transparent. </td> 5143 </tr> 5144 5145 <tr><td></td><td>The result is much like if you used 'merge' followed by a 5146 <a href="command-line-options.php#repage" >+repage</a> option, except that all the images 5147 have been kept separate. If 'flatten' is used after using 5148 'trim-bounds' you will get the same result. </td> 5149 </tr> 5150 5151 </tbody> 5152 </table> 5153 5154 <p>To print a complete list of layer types, use <a href="command-line-options.php#list">-list layers</a>.</p> 5155 5156 <p>The operators <a href="command-line-options.php#coalesce" >-coalesce</a>, <a href="command-line-options.php#deconstruct" 5157 >-deconstruct</a>, <a href="command-line-options.php#flatten" >-flatten</a>, and <a href="command-line-options.php#mosaic" 5158 >-mosaic</a> are only aliases for the above methods and may be depreciated in 5159 the future. Also see <a href="command-line-options.php#page" >-page</a>, <a href="command-line-options.php#repage" 5160 >-repage</a> operators, the <a href="command-line-options.php#compose" >-compose</a> setting, and the 5161 GIF <a href="command-line-options.php#dispose" >-dispose</a> and <a href="command-line-options.php#delay" >-delay</a> 5162 settings. </p> 5163 5164 5165 <div style="margin: auto;"> 5166 <h3 class="magick-header"><a id="level"></a>-level <var>black_point</var>{,<var>white_point</var>}{<var>%</var>}{,<var>gamma</var>}</h3> 5167 </div> 5168 5169 <p class="magick-description">adjust the level of image channels.</p> 5170 5171 <p>Given one, two or three values delimited with commas: black-point, 5172 white-point, gamma (for example: 10,250,1.0 or 2%,98%,0.5). The black and 5173 white points range from 0 to <var>QuantumRange</var>, or from 0 to 5174 100%; if the white point is omitted it is set to (<var>QuantumRange</var> - black_point), so as to center contrast changes. 5175 If a <code>%</code> sign is present anywhere in the string, both black and white 5176 points are percentages of the full color range. Gamma will do a <a 5177 href="command-line-options.php#gamma">-gamma</a> adjustment of the values. If it is omitted, the 5178 default of 1.0 (no gamma correction) is assumed.</p> 5179 5180 <p>In normal usage (<code>-level</code>) the image values are stretched so that 5181 the given '<code>black_point</code>' value in the original image is set to zero 5182 (or black), while the given '<code>white_point</code>' value is set to <var>QuantumRange</var> (or white). This provides you with direct 5183 contrast adjustments to the image. The '<code>gamma</code>' of the resulting 5184 image will then be adjusted. </p> 5185 5186 <p>From ImageMagick v6.4.1-9 using the plus form of the operator 5187 (<code>+level</code>) or adding the special '!' flag anywhere in the argument 5188 list, will cause the operator to do the reverse of the level adjustment. That 5189 is a zero, or <var>QuantumRange</var> value (black, and white, resp.) 5190 in the original image, is adjusted to the given level values, allowing you to 5191 de-contrast, or compress the channel values within the image. The 5192 '<code>gamma</code>' is adjusted before the level adjustment to de-contrast the 5193 image is made. </p> 5194 5195 <p>Only the channels defined by the current <a href="command-line-options.php#channel">-channel</a> 5196 setting are adjusted (defaults to RGB color channels only), allowing you to 5197 limit the effect of this operator. </p> 5198 5199 <p>Please note that the transparency channel is treated as 'matte' 5200 values (0 is opaque) and not as 'alpha' values (0 is transparent).</p> 5201 5202 5203 <div style="margin: auto;"> 5204 <h3 class="magick-header"><a id="level-colors"></a>-level-colors {<var>black_color</var>}{,}{<var>white_color</var>}</h3> 5205 </div> 5206 5207 <p class="magick-description">adjust the level of an image using the provided dash separated colors.</p> 5208 5209 <p>This function is exactly like <a href="command-line-options.php#level">-level</a>, except that the 5210 value value for each color channel is determined by the 5211 '<code>black_color</code>' and '<code>white_color</code>' colors given (as 5212 described under the <a href="command-line-options.php#fill">-fill</a> option). </p> 5213 5214 <p>This effectually means the colors provided to <code>-level-colors</code> 5215 is mapped to become 'black' and 'white' respectively, with all the other 5216 colors linearly adjusted (or clipped) to match that change. Each channel is 5217 adjusted separately using the channel values of the colors specified. </p> 5218 5219 <p>On the other hand the plus form of the operator (<code>+level-colors</code>) 5220 will map the image color 'black' and 'white' to the given colors 5221 respectively, resulting in a gradient (de-contrasting) tint of the image to 5222 those colors. This can also be used to convert a plain grayscale image into a 5223 one using the gradient of colors specified. </p> 5224 5225 <p>By supplying a single color with a comma separator either before or after 5226 that color, will just replace the respective 'black' or 'white' point 5227 respectively. But if no comma separator is provided, the given color is 5228 used for both the black and white color points, making the operator either 5229 threshold the images around that color (- form) or set all colors to that 5230 color (+ form). </p> 5231 5232 5233 <div style="margin: auto;"> 5234 <h3 class="magick-header"><a id="limit"></a>-limit <var>type value</var></h3> 5235 </div> 5236 5237 <p class="magick-description">Set the pixel cache resource limit.</p> 5238 5239 <p>Choose from: <code>area</code>, <code>disk</code>, <code>file</code>, 5240 <code>map</code>, <code>memory</code>, <code>thread</code>, or <code>time</code>.</p> 5241 5242 <p>The value for <code>file</code> is in number of files. The other limits are 5243 in bytes. Define arguments for the memory, map, area, and disk resource limits 5244 with SI prefixes (.e.g 100MB).</p> 5245 5246 <p>By default the limits are 768 files, 3GB of image area, 1.5GiB memory, 3GiB 5247 memory map, and 18.45EB of disk. These limits are adjusted relative to the 5248 available resources on your computer if this information is available. When 5249 any limit is reached, ImageMagick fails in some fashion but attempts to take 5250 compensating actions, if possible. For example, the following limits 5251 memory:</p> 5252 5253 <pre> 5254 -limit memory 32MiB -limit map 64MiB 5255 </pre> 5256 5257 <p>Use <a href="command-line-options.php#list">-list resource</a> to list the current limits. For example, our system shows these limits:</p> 5258 5259 <pre> 5260 -> identify -list resource 5261 Resource limits: 5262 Width: 100MP 5263 Height: 100MP 5264 Area: 25.181GB 5265 Memory: 11.726GiB 5266 Map: 23.452GiB 5267 Disk: unlimited 5268 File: 768 5269 Thread: 12 5270 Throttle: 0 5271 Time: unlimited 5272 </pre> 5273 5274 <p>Requests for pixel storage to keep intermediate images are satisfied by one 5275 of three resource categories: in-memory pool, memory-mapped files pool, and 5276 disk pool (in that order) depending on the <a href="command-line-options.php#limit">‑limit</a> settings 5277 and whether the system honors a resource request. If the total size of 5278 allocated pixel storage in the given pool reaches the corresponding limit, the 5279 request is passed to the next pool. Additionally, requests that exceed the 5280 <code>area</code> limit automagically are allocated on disk.</p> 5281 5282 <p>To illustrate how ImageMagick utilizes resource limits, consider a typical 5283 image resource request. First, ImageMagick tries to allocate the pixels in 5284 memory. The request might be denied if the resource request exceeds the 5285 <code>memory</code> limit or if the system does not honor the request. If 5286 a memory request is not honored, the pixels are allocated to disk and the file 5287 is memory-mapped. However, if the allocation request exceeds the 5288 <code>map</code> limit, the resource allocation goes to disk. In all cases, if 5289 the resource request exceeds the <code>area</code> limit, the pixels are 5290 automagically cached to disk. If the disk has a hard limit, the program 5291 fails.</p> 5292 5293 <p>In most cases you simply do not need to concern yourself with resource 5294 limits. ImageMagick chooses reasonable defaults and most images do not tax 5295 your computer resources. Where limits do come in handy is when you process 5296 images that are large or on shared systems where ImageMagick can consume all 5297 or most of the available memory. In this case, the ImageMagick workflow slows 5298 other processes or, in extreme cases, brings the system to a halt. Under 5299 these circumstances, setting limits give some assurances that the ImageMagick 5300 workflow will not interfere with other concurrent uses of the computer. For 5301 example, assume you have a web interface that processes images uploaded from 5302 the Internet. To assure ImageMagick does not exceed 10MiB of memory you can 5303 simply set the area limit to 10MiB:</p> 5304 5305 <pre> 5306 -limit area 10MB 5307 </pre> 5308 5309 <p>Now whenever a large image is processed, the pixels are automagically 5310 cached to disk instead of memory. This of course implies that large images 5311 typically process very slowly, simply because pixel processing in memory can 5312 be an order of magnitude faster than on disk. Because your web site users 5313 might inadvertently upload a huge image to process, you should set a disk 5314 limit as well:</p> 5315 5316 <pre> 5317 -limit area 10MB -limit disk 500MB 5318 </pre> 5319 5320 <p>Here ImageMagick stops processing if an image requires more than 500MB of disk storage.</p> 5321 5322 <p>In addition to command-line resource limit option, resources can be set 5323 with <a href="resources.php#environment" >environment variables</a>. Set the 5324 environment variables <code>MAGICK_AREA_LIMIT</code>, 5325 <code>MAGICK_DISK_LIMIT</code>, <code>MAGICK_FILE_LIMIT</code>, 5326 <code>MAGICK_MEMORY_LIMIT</code>, <code>MAGICK_MAP_LIMIT</code>, 5327 <code>MAGICK_THREAD_LIMIT</code>, <code>MAGICK_TIME_LIMIT</code> for limits of 5328 image area, disk space, open files, heap memory, memory map, number of threads 5329 of execution, and maximum elapsed time in seconds respectively.</p> 5330 5331 <p> Inquisitive users can try adding <a href="command-line-options.php#debug">-debug cache</a> to 5332 their commands and then scouring the generated output for references to the 5333 pixel cache, in order to determine how the pixel cache was allocated and how 5334 resources were consumed. Advanced Unix/Linux users can pipe that output 5335 through <code>grep memory|open|destroy|disk</code> for more readable sifting. 5336 </p> 5337 5338 <p>For more about ImageMagick's use of resources, see the section <b>Cache 5339 Storage and Resource Requirements</b> on the <a href="architecture.php#cache 5340 ">Architecture</a> page. </p> 5341 5342 <div style="margin: auto;"> 5343 <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> 5344 </div> 5345 5346 <p class="magick-description">Linear with saturation stretch.</p> 5347 5348 <p>This is very similar to <a href="command-line-options.php#contrast-stretch" >-contrast-stretch</a>, 5349 and uses a 'histogram bin' to determine the range of color values that needs to 5350 be stretched. However it then stretches those colors using the <a 5351 href="command-line-options.php#level" >-level</a> operator.</p> 5352 5353 <p>As such while the initial determination may have 'binning' round off 5354 effects, the image colors are stretched mathematically, rather than using the 5355 histogram bins. This makes the operator more accurate. </p> 5356 5357 <p>note however that a <a href="command-line-options.php#linear-stretch" >-linear-stretch</a> of 5358 '<code>0</code>' does nothing, while a value of '<code>1</code>' does a near 5359 perfect stretch of the color range. </p> 5360 5361 <p>See also <a href="command-line-options.php#auto-level" >-auto-level</a> for a 'perfect' 5362 normalization of mathematical images. </p> 5363 5364 <p>This operator is under review for re-development. </p> 5365 5366 5367 <div style="margin: auto;"> 5368 <h3 class="magick-header"><a id="linewidth"></a>-linewidth</h3> 5369 </div> 5370 5371 <p class="magick-description">the line width for subsequent draw operations.</p> 5372 5373 <div style="margin: auto;"> 5374 <h3 class="magick-header"><a id="liquid-rescale"></a>-liquid-rescale <var>geometry</var></h3> 5375 </div> 5376 5377 <p class="magick-description">rescale image with seam-carving.</p> 5378 5379 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 5380 5381 <div style="margin: auto;"> 5382 <h3 class="magick-header"><a id="list"></a>-list <var>type</var></h3> 5383 </div> 5384 5385 <p class="magick-description">Print a list of supported arguments for various options or settings. Choose from these list types:</p> 5386 5387 <pre class="pre-scrollable"> 5388 Align 5389 Alpha 5390 Boolean 5391 Cache 5392 Channel 5393 Class 5394 ClipPath 5395 Coder 5396 Color 5397 Colorspace 5398 Command 5399 Complex 5400 Compose 5401 Compress 5402 Configure 5403 DataType 5404 Debug 5405 Decoration 5406 Delegate 5407 Direction 5408 Dispose 5409 Distort 5410 Dither 5411 Endian 5412 Evaluate 5413 FillRule 5414 Filter 5415 Font 5416 Format 5417 Function 5418 Gravity 5419 Intensity 5420 Intent 5421 Interlace 5422 Interpolate 5423 Kernel 5424 Layers 5425 LineCap 5426 LineJoin 5427 List 5428 Locale 5429 LogEvent 5430 Log 5431 Magic 5432 Method 5433 Metric 5434 Mime 5435 Mode 5436 Morphology 5437 Module 5438 Noise 5439 Orientation 5440 PixelIntensity 5441 Policy 5442 PolicyDomain 5443 PolicyRights 5444 Preview 5445 Primitive 5446 QuantumFormat 5447 Resource 5448 SparseColor 5449 Statistic 5450 Storage 5451 Stretch 5452 Style 5453 Threshold 5454 Type 5455 Units 5456 Validate 5457 VirtualPixel 5458 </pre> 5459 5460 <p>These lists vary depending on your version of ImageMagick. Use "<code>-list 5461 list</code>" to get a complete listing of all the "<code>-list</code>" arguments 5462 available:</p> 5463 5464 <pre> 5465 identify -list list 5466 </pre> 5467 5468 <div style="margin: auto;"> 5469 <h3 class="magick-header"><a id="log"></a>-log <var>string</var></h3> 5470 </div> 5471 5472 <p class="magick-description">Specify format for debug log.</p> 5473 5474 <p>This option specifies the format for the log printed when the <a 5475 href="command-line-options.php#debug">-debug</a> option is active.</p> 5476 5477 <p>You can display the following components by embedding special format 5478 characters:</p> 5479 5480 <dl class="dl-horizontal"> 5481 <dt>%d</dt><dd>domain</dd> 5482 <dt>%e</dt><dd>event</dd> 5483 <dt>%f</dt><dd>function</dd> 5484 <dt>%l</dt><dd>line</dd> 5485 <dt>%m</dt><dd>module</dd> 5486 <dt>%p</dt><dd>process ID</dd> 5487 <dt>%r</dt><dd>real CPU time</dd> 5488 <dt>%t</dt><dd>wall clock time</dd> 5489 <dt>%u</dt><dd>user CPU time</dd> 5490 <dt>%%</dt><dd>percent sign</dd> 5491 <dt>\n</dt><dd>newline</dd> 5492 <dt>\r</dt><dd>carriage return</dd> 5493 </dl> 5494 5495 <p>For example:</p> 5496 5497 <pre> 5498 convert -debug coders -log "%u %m:%l %e" in.gif out.png 5499 </pre> 5500 5501 <p>The default behavior is to print all of the components.</p> 5502 5503 <div style="margin: auto;"> 5504 <h3 class="magick-header"><a id="loop"></a>-loop <var>iterations</var></h3> 5505 </div> 5506 5507 <p class="magick-description">add Netscape loop extension to your GIF animation.</p> 5508 5509 <p>Set iterations to zero to repeat the animation an infinite number of times, 5510 otherwise the animation repeats itself up to <var>iterations</var> 5511 times.</p> 5512 5513 <div style="margin: auto;"> 5514 <h3 class="magick-header"><a id="lowlight-color"></a>-lowlight-color <var>color</var></h3> 5515 </div> 5516 5517 <p class="magick-description">when comparing images, de-emphasize pixel differences with this color.</p> 5518 5519 <div style="margin: auto;"> 5520 <h3 class="magick-header"><a id="magnify"></a>-magnify</h3> 5521 </div> 5522 5523 <p class="magick-description">double the size of the image with pixel art scaling.</p> 5524 5525 5526 <div style="margin: auto;"> 5527 <h3 class="magick-header"><a id="map"></a>-map <var>type</var></h3> 5528 </div> 5529 5530 <p class="magick-description">Display image using this <var>type</var>.</p> 5531 5532 <p>Choose from these <var>Standard Colormap</var> types:</p> 5533 5534 <pre> 5535 best 5536 default 5537 gray 5538 red 5539 green 5540 blue 5541 </pre> 5542 5543 <p>The <var>X server</var> must support the <var>Standard 5544 Colormap</var> you choose, otherwise an error occurs. Use <code>list</code> as 5545 the type and <code>display</code> searches the list of colormap types in 5546 <code>top-to-bottom</code> order until one is located. See <var>xstdcmap(1)</var> for one way of creating Standard Colormaps.</p> 5547 5548 5549 <div style="margin: auto;"> 5550 <h3 class="magick-header"><a id="map_stream_"></a>-map <var>components</var></h3> 5551 </div> 5552 5553 <p class="magick-description">pixel map.</p> 5554 5555 <p>Here are the valid components of a map:</p> 5556 5557 <dl class="dl-horizontal"> 5558 <dt>r</dt><dd> red pixel component</dd> 5559 <dt>g</dt><dd> green pixel component</dd> 5560 <dt>b</dt><dd> blue pixel component</dd> 5561 <dt>a</dt><dd> alpha pixel component (0 is transparent)</dd> 5562 <dt>o</dt><dd> opacity pixel component (0 is opaque)</dd> 5563 <dt>i</dt><dd> grayscale intensity pixel component</dd> 5564 <dt>c</dt><dd> cyan pixel component</dd> 5565 <dt>m</dt><dd> magenta pixel component</dd> 5566 <dt>y</dt><dd> yellow pixel component</dd> 5567 <dt>k</dt><dd> black pixel component</dd> 5568 <dt>p</dt><dd> pad component (always 0)</dd> 5569 </dl> 5570 5571 <p>You can specify as many of these components as needed in any order (e.g. 5572 bgr). The components can repeat as well (e.g. rgbr).</p> 5573 5574 5575 <div style="margin: auto;"> 5576 <h3 class="magick-header"><a id="mask"></a>-mask 5577 <var>filename</var></h3> 5578 </div> 5579 5580 <p class="magick-description">Prevent updates to image pixels specified by the mask.</p> 5581 5582 <p>This the same as using a mask used for composite masking operations, with 5583 grayscale values causing blended updates of the image the mask is attached to. 5584 </p> 5585 5586 <p>Use <a href="command-line-options.php#mask">+mask</a> to remove the mask from images.</p> 5587 5588 <p>Also see <a href="command-line-options.php#clip-mask">-clip-mask</a> which work in the same way, 5589 but with strict boolean masking. </p> 5590 5591 <div style="margin: auto;"> 5592 <h3 class="magick-header"><a id="mattecolor"></a>-mattecolor <var>color</var></h3> 5593 </div> 5594 5595 <p class="magick-description">Specify the color to be used with the <a href="command-line-options.php#frame">-frame</a> option.</p> 5596 5597 <p>The color is specified using the format described under the <a href="command-line-options.php#fill">-fill</a> option.</p> 5598 5599 <p>The default matte color is <code>#BDBDBD</code>, <span 5600 style="background-color: #bdbdbd;">this shade of gray</span>.</p> 5601 5602 <div style="margin: auto;"> 5603 <h3 class="magick-header"><a id="maximum"></a>-maximum</h3> 5604 </div> 5605 5606 <p class="magick-description">return the maximum intensity of an image sequence.</p> 5607 5608 <p>Select the 'maximum' value from all the surrounding pixels. </p> 5609 5610 <p>This is legacy option from the <a href="command-line-options.php#statistic" >method</a> of the same 5611 name. </p> 5612 5613 <div style="margin: auto;"> 5614 <h3 class="magick-header"><a id="median"></a>-median <var>geometry</var></h3> 5615 </div> 5616 5617 <p class="magick-description">apply a median filter to the image.</p> 5618 5619 <p>Select the 'middle' value from all the surrounding pixels. </p> 5620 5621 <p>This is legacy option from the <a href="command-line-options.php#statistic" >method</a> of the same 5622 name. </p> 5623 5624 <div style="margin: auto;"> 5625 <h3 class="magick-header"><a id="mean-shift"></a>-mean-shift <var>width</var>x<var>height</var>{<var>+distance</var>{%}</h3> 5626 </div> 5627 5628 <p class="magick-description">image noise removal and color reduction/segmentation (e.g. -mean-shift 7x7+10%).</p> 5629 5630 <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> 5631 5632 <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> 5633 5634 <div style="margin: auto;"> 5635 <h3 class="magick-header"><a id="metric"></a>-metric <var>type</var></h3> 5636 </div> 5637 5638 <p class="magick-description">Output to STDERR a measure of the differences between images according to the <var>type</var> given metric.</p> 5639 5640 <p>Choose from:</p> 5641 5642 <dl class="dl-horizontal"> 5643 <dt>AE</dt><dd> absolute error count, number of different pixels (-fuzz effected)</dd> 5644 <dt>FUZZ</dt><dd> mean color distance</dd> 5645 <dt>MAE</dt><dd> mean absolute error (normalized), average channel error distance</dd> 5646 <dt>MEPP</dt><dd> mean error per pixel (normalized mean error, normalized peak error)</dd> 5647 <dt>MSE</dt><dd> mean error squared, average of the channel error squared</dd> 5648 <dt>NCC</dt><dd> normalized cross correlation</dd> 5649 <dt>PAE</dt><dd> peak absolute (normalized peak absolute)</dd> 5650 <dt>PHASH</dt><dd> perceptual hash</dd> 5651 <dt>PSNR</dt><dd> peak signal to noise ratio</dd> 5652 <dt>RMSE</dt><dd> root mean squared (normalized root mean squared)</dd> 5653 </dl> 5654 5655 <p>Control the '<code>AE</code>', or absolute count of pixels that are different, 5656 with the <a href="command-line-options.php#fuzz" >-fuzz</a> factor (ignore pixels which 5657 only changed by a small amount). Use '<code>PAE</code>' to find the 5658 size of the <a href="command-line-options.php#fuzz" >-fuzz</a> factor needed to make all pixels 5659 'similar', while '<code>MAE</code>' determines the factor needed 5660 for about half the pixels to be similar. </p> 5661 5662 <p>The '<code>MEPP</code>' metric returns three different metrics 5663 ('<code>MAE</code>', '<code>MAE</code>' normalized, and '<code>PAE</code>' 5664 normalized) from a single comparison run. </p> 5665 5666 <p>To print a complete list of metrics, use the <a href="command-line-options.php#list">-list 5667 metric</a> option.</p> 5668 5669 5670 <div style="margin: auto;"> 5671 <h3 class="magick-header"><a id="minimum"></a>-minimum</h3> 5672 </div> 5673 5674 <p class="magick-description">return the minimum intensity of an image sequence.</p> 5675 5676 <p>Select the 'minimal' value from all the surrounding pixels. </p> 5677 5678 <p>This is legacy option from the <a href="command-line-options.php#statistic" >method</a> of the same 5679 name. </p> 5680 5681 5682 5683 <div style="margin: auto;"> 5684 <h3 class="magick-header"><a id="mode"></a>-mode <var>geometry</var></h3> 5685 </div> 5686 5687 <p class="magick-description">make each pixel the \'predominant color\' of the neighborhood.'</p> 5688 5689 <div style="margin: auto;"> 5690 <h3 class="magick-header">-mode <var>value</var></h3> 5691 </div> 5692 5693 <p class="magick-description">Mode of operation.</p> 5694 5695 <p>Choose the <var>value</var> from these styles: <code>Frame, 5696 Unframe, or Concatenate</code></p> 5697 5698 <p>Use the <a href="command-line-options.php#list" >-list</a> option with a '<code>Mode</code>' argument 5699 for a list of <a href="command-line-options.php#mode" >-mode</a> arguments available in your 5700 ImageMagick installation.</p> 5701 5702 5703 <div style="margin: auto;"> 5704 <h3 class="magick-header"><a id="modulate"></a>-modulate <var>brightness</var>[,<var>saturation</var>,<var>hue</var>]</h3> 5705 </div> 5706 5707 <p class="magick-description">Vary the <var>brightness</var>, <var>saturation</var>, and <var>hue</var> of an image.</p> 5708 5709 <p>The arguments are given as a percentages of variation. A value of 100 means 5710 no change, and any missing values are taken to mean 100.</p> 5711 5712 <p>The <var>brightness</var> is a multiplier of the overall 5713 brightness of the image, so 0 means pure black, 50 is half as bright, 200 is 5714 twice as bright. To invert its meaning <a href="command-line-options.php#negate">-negate</a> the image 5715 before and after. </p> 5716 5717 <p>The <var>saturation</var> controls the amount of color in an 5718 image. For example, 0 produce a grayscale image, while a large value such as 5719 200 produce a very colorful, 'cartoonish' color.</p> 5720 5721 <p>The <var>hue</var> argument causes a "rotation" of the colors 5722 within the image by the amount specified. For example, 50 results in 5723 a counter-clockwise rotation of 90, mapping red shades to purple, and so on. 5724 A value of either 0 or 200 results in a complete 180 degree rotation of the 5725 image. Using a value of 300 is a 360 degree rotation resulting in no change to 5726 the original image. </p> 5727 5728 <p>For example, to increase the color brightness by 20% and decrease the color 5729 saturation by 10% and leave the hue unchanged, use <a 5730 href="command-line-options.php#modulate">-modulate 120,90</a>.</p> 5731 5732 <p>Use <a href="command-line-options.php#set">-set</a> attribute of '<code 5733 >option:modulate:colorspace</code>' to specify which colorspace to 5734 modulate. 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> 5735 5736 <pre> 5737 convert image.png -set option:modulate:colorspace hsb -modulate 120,90 modulate.png 5738 </pre> 5739 5740 <div style="margin: auto;"> 5741 <h3 class="magick-header"><a id="moments"></a>-moments</h3> 5742 </div> 5743 5744 <p class="magick-description">report image moments and perceptual hash.</p> 5745 5746 5747 <div style="margin: auto;"> 5748 <h3 class="magick-header"><a id="monitor"></a>-monitor</h3> 5749 </div> 5750 5751 <p class="magick-description">monitor progress.</p> 5752 5753 5754 <div style="margin: auto;"> 5755 <h3 class="magick-header"><a id="monochrome"></a>-monochrome</h3> 5756 </div> 5757 5758 <p class="magick-description">transform the image to black and white.</p> 5759 5760 <div style="margin: auto;"> 5761 <h3 class="magick-header"><a id="morph"></a>-morph <var>frames</var></h3> 5762 </div> 5763 5764 <p class="magick-description">morphs an image sequence.</p> 5765 5766 <p>Both the image pixels and size are linearly interpolated to give the 5767 appearance of a metamorphosis from one image to the next, over all the images 5768 in the current image list. The added images are the equivalent of a <a 5769 href="command-line-options.php#blend">-blend</a> composition. The <var>frames</var> 5770 argument determine how many images to interpolate between each image. </p> 5771 5772 5773 <div style="margin: auto;"> 5774 <h3 class="magick-header"><a id="morphology"></a>-morphology</h3> 5775 <h3 class="magick-header">-morphology <var>method</var> <var>kernel</var></h3> 5776 </div> 5777 5778 <p class="magick-description">apply a morphology method to the image.</p> 5779 5780 <p>Until I get around to writing an option summary for this, see <a 5781 href="http://www.imagemagick.org/Usage/morphology/" >IM Usage Examples, 5782 Morphology</a>. </p> 5783 5784 5785 <div style="margin: auto;"> 5786 <h3 class="magick-header"><a id="mosaic"></a>-mosaic</h3> 5787 </div> 5788 5789 <p class="magick-description">an simple alias for the <a href="command-line-options.php#layers" >-layers</a> method "mosaic"</p> 5790 5791 5792 <div style="margin: auto;"> 5793 <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> 5794 </div> 5795 5796 <p class="magick-description">simulate motion blur.</p> 5797 5798 <p>Blur with the given radius, standard deviation (sigma), and angle. The 5799 angle given is the angle toward which the image is blurred. That is the 5800 direction people would consider the object is coming from. </p> 5801 5802 <p>Note that the blur is not uniform distribution, giving the motion a 5803 definite sense of direction of movement. </p> 5804 5805 <p>The <a href="command-line-options.php#virtual-pixel">-virtual-pixel</a> setting will determine how 5806 pixels which are outside the image proper are blurred into the final result. 5807 </p> 5808 5809 <div style="margin: auto;"> 5810 <h3 class="magick-header"><a id="name"></a>-name</h3> 5811 </div> 5812 5813 <p class="magick-description">name an image.</p> 5814 <div style="margin: auto;"> 5815 <h3 class="magick-header"><a id="negate"></a>-negate</h3> 5816 </div> 5817 5818 <p class="magick-description">replace each pixel with its complementary color.</p> 5819 5820 <p>The red, green, and blue intensities of an image are negated. White becomes 5821 black, yellow becomes blue, etc. Use <a href="command-line-options.php#negate">+negate</a> to only 5822 negate the grayscale pixels of the image.</p> 5823 5824 <div style="margin: auto;"> 5825 <h3 class="magick-header"><a id="noise"></a>-noise <var>geometry</var><br/> 5826 +noise <var>type</var></h3> 5827 </div> 5828 5829 <p class="magick-description">Add or reduce noise in an image.</p> 5830 5831 <p>The principal function of noise peak elimination filter is to smooth the 5832 objects within an image without losing edge information and without creating 5833 undesired structures. The central idea of the algorithm is to replace a pixel 5834 with its next neighbor in value within a pixel window, if this pixel has been 5835 found to be noise. A pixel is defined as noise if and only if this pixel is 5836 a maximum or minimum within the pixel window.</p> 5837 5838 <p>Use <code><a href="command-line-options.php#noise">-noise</a> <var>radius</var></code> to 5839 specify the width of the neighborhood when reducing noise. This is equivalent 5840 to using a <code><a href="command-line-options.php#statistic" >-statistic</a> NonPeak</code> operation, 5841 which should be used in preference.</p> 5842 5843 <p>Use <a href="command-line-options.php#noise">+noise</a> followed by a noise <var>type</var> to add noise to an image. Choose from these noise 5844 types:</p> 5845 5846 <pre> 5847 Gaussian 5848 Impulse 5849 Laplacian 5850 Multiplicative 5851 Poisson 5852 Random 5853 Uniform 5854 </pre> 5855 5856 <p>The amount of noise added can be controlled by the <code><a 5857 href="command-line-options.php#attenuate" >-attenuate</a></code> setting. If unset the value is 5858 equivalent to 1.0, or a maximum noise addition.</p> 5859 5860 <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> 5861 5862 <p>To print a complete list of noises, use the <a href="command-line-options.php#list">-list noise</a> option.</p> 5863 5864 <p>Also see the <a href="command-line-options.php#evaluate">-evaluate</a> noise functions that allows 5865 the use of a controlling value to specify the amount of noise that should be 5866 added to an image. </p> 5867 5868 5869 <div style="margin: auto;"> 5870 <h3 class="magick-header"><a id="normalize"></a>-normalize</h3> 5871 </div> 5872 5873 <p class="magick-description">Increase the contrast in an image by <var>stretching</var> the range of intensity values.</p> 5874 5875 <p>The intensity values are stretched to cover the entire range of possible 5876 values. While doing so, black-out at most <var>2%</var> of the pixels and 5877 white-out at most <var>1%</var> of the pixels.</p> 5878 5879 <p>Note that as of ImageMagick 6.4.7-0, <a href="command-line-options.php#normalize" >-normalize</a> 5880 is equivalent to <a href="command-line-options.php#contrast-stretch" >-contrast-stretch 2%x1%</a>. 5881 (Before this version, it was equivalent to <a href="command-line-options.php#contrast-stretch" 5882 >-contrast-stretch 2%x99%</a>).</p> 5883 5884 <p>All the channels are normalized in concert by the same amount so as to 5885 preserve color integrity, when the default <a href="command-line-options.php#channel" >+channel</a> 5886 setting is in use. Specifying any other <a href="command-line-options.php#channel" >-channel</a> 5887 setting will normalize the RGB channels independently.</p> 5888 5889 <p>See <a href="command-line-options.php#contrast-stretch" >-contrast-stretch</a> for more details. 5890 Also see <a href="command-line-options.php#auto-level" >-auto-level</a> for a 'perfect' normalization 5891 that is better suited to mathematically generated images. </p> 5892 5893 <p>This operator is under review for re-development. </p> 5894 5895 5896 <div style="margin: auto;"> 5897 <h3 class="magick-header"><a id="opaque"></a>-opaque <var>color</var></h3> 5898 </div> 5899 5900 <p class="magick-description">change this color to the fill color within the image.</p> 5901 5902 <p>The <var>color</var> argument is defined using the format 5903 described under the <a href="command-line-options.php#fill" >-fill</a> option. The <a href="command-line-options.php#fuzz" 5904 >-fuzz</a> setting can be used to match and replace colors similar to the one 5905 given.</p> 5906 5907 <p>Use <a href="command-line-options.php#opaque">+opaque</a> to paint any pixel that does not match 5908 the target color. </p> 5909 5910 <p>The <a href="command-line-options.php#transparent">-transparent</a> operator is exactly the same 5911 as <a href="command-line-options.php#opaque" >-opaque</a> but replaces the matching color with 5912 transparency rather than the current <a href="command-line-options.php#fill">-fill</a> color setting. 5913 To ensure that it can do this it also ensures that the image has an alpha 5914 channel enabled, as per "<code><a href="command-line-options.php#alpha" >-alpha</a> set</code>", for 5915 the new transparent colors, and does not require you to modify the <a 5916 href="command-line-options.php#channel">-channel</a> to enable alpha channel handling. </p> 5917 5918 5919 <div style="margin: auto;"> 5920 <h3 class="magick-header"><a id="ordered-dither"></a>-ordered-dither <var>threshold_map</var>{,<var>level</var>...}</h3> 5921 </div> 5922 5923 <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 5924 given number of <var>levels</var> per color channel.</p> 5925 5926 <p>You can choose from these standard threshold maps:</p> 5927 5928 <pre class="pre-scrollable"> 5929 threshold 1x1 Threshold 1x1 (non-dither) 5930 checks 2x1 Checkerboard 2x1 (dither) 5931 o2x2 2x2 Ordered 2x2 (dispersed) 5932 o3x3 3x3 Ordered 3x3 (dispersed) 5933 o4x4 4x4 Ordered 4x4 (dispersed) 5934 o8x8 8x8 Ordered 8x8 (dispersed) 5935 h3x4a 4x1 Halftone 4x4 (angled) 5936 h6x6a 6x1 Halftone 6x6 (angled) 5937 h8x8a 8x1 Halftone 8x8 (angled) 5938 h3x4o Halftone 4x4 (orthogonal) 5939 h6x6o Halftone 6x6 (orthogonal) 5940 h8x8o Halftone 8x8 (orthogonal) 5941 h36x16o Halftone 16x16 (orthogonal) 5942 c5x5b c5x5 Circles 5x5 (black) 5943 c5x5w Circles 5x5 (white) 5944 c6x6b c6x6 Circles 6x6 (black) 5945 c6x6w Circles 6x6 (white) 5946 c7x7b c7x7 Circles 7x7 (black) 5947 c7x7w Circles 7x7 (white) 5948 </pre> 5949 5950 <p> The <code>threshold</code> generated a simple 50% threshold of the image. 5951 This could be used with <var >level</var> to do the equivalent of <a 5952 href="command-line-options.php#posterize" >-posterize</a> to reduce an image to basic primary colors. 5953 </p> 5954 5955 <p>The <code>checks</code> pattern produces a 3 level checkerboard dither 5956 pattern. That is a grayscale will become a pattern of solid black, solid 5957 white, and mid-tone colors into a checkerboard pattern of black and white. 5958 </p> 5959 5960 <p>You can define your own <var >threshold map</var> for ordered 5961 dithering and halftoning your images, in either personal or system 5962 <code>thresholds.xml</code> XML file. See <a href="resources.php" >Resources</a> 5963 for more details of configuration files. </p> 5964 5965 <p>To print a complete list of the thresholds that have been defined, use the 5966 <a href="command-line-options.php#list" >-list threshold</a> option.</p> 5967 5968 <p>Note that at this time the same threshold dithering map is used for all 5969 color channels, no attempt is made to offset or rotate the map for different 5970 channels is made, to create an offset printing effect. Also as the maps are 5971 simple threshold levels, the halftone and circle maps will create incomplete 5972 circles along the edges of a colored area. Also all the effects are purely 5973 on/off boolean effects, without anti-aliasing to make the circles smooth 5974 looking. Large dots can be made to look better with a small amount of blurring 5975 after being created. </p> 5976 5977 5978 <div style="margin: auto;"> 5979 <h3 class="magick-header"><a id="orient"></a>-orient <var>image orientation</var></h3> 5980 </div> 5981 5982 <p class="magick-description">specify orientation of a digital camera image.</p> 5983 5984 <p>Choose from these orientations:</p> 5985 5986 <pre> 5987 bottom-left right-top 5988 bottom-right top-left 5989 left-bottom top-right 5990 left-top undefined 5991 right-bottom 5992 </pre> 5993 5994 <p>To print a complete list of orientations, use the <a href="command-line-options.php#list" >-list 5995 orientation</a> option.</p> 5996 5997 5998 <div style="margin: auto;"> 5999 <h3 class="magick-header"><a id="page"></a>-page <var>geometry</var><br/> 6000 -page <var>media</var>[<var>offset</var>][{<var>^!<></var>}]<br/> 6001 +page 6002 </h3> 6003 </div> 6004 6005 <p class="magick-description">Set the size and location of an image on the larger virtual canvas.</p> 6006 6007 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6008 6009 <p>For convenience you can specify the page size using <var>media</var> (see below). Offsets can then be added as with other 6010 <var>geometry</var> arguments (e.g. <a 6011 href="command-line-options.php#page">-page</a> <code>Letter+43+43</code>).</p> 6012 6013 <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. 6014 The choices for a PostScript page are:</p> 6015 6016 <dl class="dl-horizontal"> 6017 <dt> 11x17 </dt> <dd> 792 x 1224</dd> 6018 <dt> Ledger </dt> <dd> 1224 x 792</dd> 6019 <dt> Legal </dt> <dd> 612 x 1008</dd> 6020 <dt> Letter </dt> <dd> 612 x 792</dd> 6021 <dt> LetterSmall</dt> <dd> 612 x 792</dd> 6022 <dt> ArchE </dt> <dd> 2592 x 3456</dd> 6023 <dt> ArchD </dt> <dd> 1728 x 2592</dd> 6024 <dt> ArchC </dt> <dd> 1296 x 1728</dd> 6025 <dt> ArchB </dt> <dd> 864 x 1296</dd> 6026 <dt> ArchA </dt> <dd> 648 x 864</dd> 6027 <dt> A0 </dt> <dd> 2380 x 3368</dd> 6028 <dt> A1 </dt> <dd> 1684 x 2380</dd> 6029 <dt> A2 </dt> <dd> 1190 x 1684</dd> 6030 <dt> A3 </dt> <dd> 842 x 1190</dd> 6031 <dt> A4 </dt> <dd> 595 x 842</dd> 6032 <dt> A4Small </dt> <dd> 595 x 842</dd> 6033 <dt> A5 </dt> <dd> 421 x 595</dd> 6034 <dt> A6 </dt> <dd> 297 x 421</dd> 6035 <dt> A7 </dt> <dd> 210 x 297</dd> 6036 <dt> A8 </dt> <dd> 148 x 210</dd> 6037 <dt> A9 </dt> <dd> 105 x 148</dd> 6038 <dt> A10 </dt> <dd> 74 x 105</dd> 6039 <dt> B0 </dt> <dd> 2836 x 4008</dd> 6040 <dt> B1 </dt> <dd> 2004 x 2836</dd> 6041 <dt> B2 </dt> <dd> 1418 x 2004</dd> 6042 <dt> B3 </dt> <dd> 1002 x 1418</dd> 6043 <dt> B4 </dt> <dd> 709 x 1002</dd> 6044 <dt> B5 </dt> <dd> 501 x 709</dd> 6045 <dt> C0 </dt> <dd> 2600 x 3677</dd> 6046 <dt> C1 </dt> <dd> 1837 x 2600</dd> 6047 <dt> C2 </dt> <dd> 1298 x 1837</dd> 6048 <dt> C3 </dt> <dd> 918 x 1298</dd> 6049 <dt> C4 </dt> <dd> 649 x 918</dd> 6050 <dt> C5 </dt> <dd> 459 x 649</dd> 6051 <dt> C6 </dt> <dd> 323 x 459</dd> 6052 <dt> Flsa </dt> <dd> 612 x 936</dd> 6053 <dt> Flse </dt> <dd> 612 x 936</dd> 6054 <dt> HalfLetter </dt> <dd> 396 x 612</dd> 6055 </dl> 6056 6057 <p>This option is also used to place subimages when writing to a multi-image 6058 format that supports offsets, such as GIF89 and MNG. When used for this 6059 purpose the offsets are always measured from the top left corner of the canvas 6060 and are not affected by the <a href="command-line-options.php#gravity">-gravity</a> option. To 6061 position a GIF or MNG image, use <a href="command-line-options.php#page">-page</a><var>{+-}x{+-}y</var> (e.g. -page +100+200). When writing to a MNG 6062 file, a <a href="command-line-options.php#page">-page</a> option appearing ahead of the first image in 6063 the sequence with nonzero width and height defines the width and height values 6064 that are written in the <code>MHDR</code> chunk. Otherwise, the MNG width and 6065 height are computed from the bounding box that contains all images in the 6066 sequence. When writing a GIF89 file, only the bounding box method is used to 6067 determine its dimensions.</p> 6068 6069 <p>For a PostScript page, the image is sized as in <a 6070 href="command-line-options.php#geometry">-geometry</a> but positioned relative to the <var>lower 6071 left-hand corner</var> of the page by {+-}<code>x</code><var>offset</var>{+-}<code>y</code> <var>offset</var>. Use <a 6072 href="command-line-options.php#page">-page 612x792</a>, for example, to center the image within the 6073 page. If the image size exceeds the PostScript page, it is reduced to fit the 6074 page. The default gravity for the <a href="command-line-options.php#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 6075 corner of the page, unless the <a href="command-line-options.php#gravity">-gravity</a> option is 6076 present with a value other than <var>NorthWest</var>.</p> 6077 6078 <p>The default page dimensions for a TEXT image is 612x792.</p> 6079 6080 <p>This option is used in concert with <a href="command-line-options.php#density">-density</a>.</p> 6081 6082 <p>Use <a href="command-line-options.php#page">+page</a> to remove the page settings for an image.</p> 6083 6084 <div style="margin: auto;"> 6085 <h3 class="magick-header"><a id="paint"></a>-paint <var>radius</var></h3> 6086 </div> 6087 6088 <p class="magick-description">simulate an oil painting.</p> 6089 6090 <p>Each pixel is replaced by the most frequent color in a circular 6091 neighborhood whose width is specified with <var>radius</var>.</p> 6092 6093 <div style="margin: auto;"> 6094 <h3 class="magick-header"><a id="path"></a>-path <var>path</var></h3></div> 6095 6096 <p class="magick-description">write images to this path on disk.</p> 6097 6098 <div style="margin: auto;"> 6099 <h3 class="magick-header"><a id="pause_animate_"></a>-pause <var>seconds</var></h3> 6100 </div> 6101 6102 <p class="magick-description">Pause between animation loops</p> 6103 6104 <p>Pause for the specified number of seconds before repeating the animation.</p> 6105 6106 <div style="margin: auto;"> 6107 <h3 class="magick-header"><a id="pause_import_"></a>-pause <var>seconds</var></h3> 6108 </div> 6109 6110 <p class="magick-description">Pause between snapshots.</p> 6111 6112 <p>Pause for the specified number of seconds before taking the next snapshot.</p> 6113 6114 <div style="margin: auto;"> 6115 <h3 class="magick-header"><a id="perceptible"></a>-perceptible <var>epsilon</var></h3> 6116 </div> 6117 6118 <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> 6119 6120 <div style="margin: auto;"> 6121 <h3 class="magick-header"><a id="ping"></a>-ping</h3> 6122 </div> 6123 6124 <p class="magick-description">efficiently determine image characteristics.</p> 6125 6126 <div style="margin: auto;"> 6127 <h3 class="magick-header"><a id="pointsize"></a>-pointsize <var>value</var></h3> 6128 </div> 6129 6130 <p class="magick-description">pointsize of the PostScript, OPTION1, or TrueType font.</p> 6131 6132 <div style="margin: auto;"> 6133 <h3 class="magick-header"><a id="polaroid"></a>-polaroid <var>angle</var></h3> 6134 </div> 6135 6136 <p class="magick-description">simulate a Polaroid picture.</p> 6137 6138 <p>Use <code>+polaroid</code> to rotate the image at a random angle between -15 and +15 degrees.</p> 6139 6140 <div style="margin: auto;"> 6141 <h3 class="magick-header"><a id="poly"></a>-poly <var>"wt,exp ..."</var></h3> 6142 </div> 6143 6144 <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> 6145 6146 <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> 6147 6148 <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> 6149 6150 <p>The format is: <var>output = wt1*image1^exp1 + wt2*image2^exp2 </var>...</p> 6151 6152 <p>Some simple uses are:</p> 6153 <ul> 6154 <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.php#profile">-evaluate-sequence</a> <var>mean</var>.</li> 6155 <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> 6156 </ul> 6157 6158 <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> 6159 6160 <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> 6161 6162 6163 <div style="margin: auto;"> 6164 <h3 class="magick-header"><a id="posterize"></a>-posterize <var>levels</var></h3> 6165 </div> 6166 6167 <p class="magick-description">reduce the image to a limited number of color levels per channel.</p> 6168 6169 <p>Very low values of <var>levels</var>, e.g., 2, 3, 4, have the most 6170 visible effect.</p> 6171 6172 <div style="margin: auto;"> 6173 <h3 class="magick-header"><a id="precision"></a>-precision <var>value</var></h3> 6174 </div> 6175 6176 <p class="magick-description">set the maximum number of significant digits to be printed.</p> 6177 6178 <div style="margin: auto;"> 6179 <h3 class="magick-header"><a id="preview"></a>-preview <var>type</var></h3> 6180 </div> 6181 6182 <p class="magick-description">image preview type.</p> 6183 6184 <p>Use this option to affect the preview operation of an image (e.g. 6185 <code>convert file.png -preview Gamma Preview:gamma.png</code>). Choose from 6186 these previews:</p> 6187 6188 <pre class="pre-scrollable"> 6189 AddNoise 6190 Blur 6191 Brightness 6192 Charcoal 6193 Despeckle 6194 Dull 6195 EdgeDetect 6196 Gamma 6197 Grayscale 6198 Hue 6199 Implode 6200 JPEG 6201 OilPaint 6202 Quantize 6203 Raise 6204 ReduceNoise 6205 Roll 6206 Rotate 6207 Saturation 6208 Segment 6209 Shade 6210 Sharpen 6211 Shear 6212 Solarize 6213 Spiff 6214 Spread 6215 Swirl 6216 Threshold 6217 Wave 6218 </pre> 6219 6220 <p>To print a complete list of previews, use the <a href="command-line-options.php#list">-list preview</a> option.</p> 6221 6222 <p>The default preview is <code>JPEG</code>.</p> 6223 6224 <div style="margin: auto;"> 6225 <h3 class="magick-header"><a id="print"></a>-print <var>string</var></h3> 6226 </div> 6227 6228 <p class="magick-description">interpret string and print to console.</p> 6229 6230 <div style="margin: auto;"> 6231 <h3 class="magick-header"><a id="process"></a>-process <var>command</var></h3> 6232 </div> 6233 6234 <p class="magick-description">process the image with a custom image filter.</p> 6235 6236 <p>The command arguments has the form <code>"module arg1 arg2 arg3 ... 6237 argN"</code> where <code>module</code> is the name of the module to invoke (e.g. 6238 "Analyze") and arg1 arg2 arg3 ... argN are an arbitrary number of arguments to 6239 pass to the process module.</p> 6240 6241 <div style="margin: auto;"> 6242 <h3 class="magick-header"><a id="profile"></a>-profile <var>filename</var><br/> 6243 +profile <var>profile_name</var></h3> 6244 </div> 6245 6246 <p class="magick-description">Manage ICM, IPTC, or generic profiles in an image.</p> 6247 6248 <p>Using <a href="command-line-options.php#profile">-profile</a> <var>filename</var> adds an 6249 ICM (ICC color management), IPTC (newswire information), or a generic profile 6250 to the image.</p> 6251 6252 <p>Use <a href="command-line-options.php#profile">+profile <var>profile_name</var></a> to 6253 remove the indicated profile. ImageMagick uses standard filename globbing, so 6254 wildcard expressions may be used to remove more than one profile. Here we 6255 remove all profiles from the image except for the XMP profile: <code>+profile 6256 "!xmp,*"</code>. </p> 6257 6258 <p>Use <code>identify -verbose</code> to find out which profiles are in the 6259 image file. Use <a href="command-line-options.php#strip">-strip</a> to remove all profiles (and 6260 comments).</p> 6261 6262 <p>To extract a profile, the <a href="command-line-options.php#profile">-profile</a> option is not 6263 used. Instead, simply write the file to an image format such as <var>APP1, 8BIM, ICM,</var> or <var>IPTC</var>.</p> 6264 6265 <p>For example, to extract the Exif data (which is stored in JPEG files in the 6266 <var>APP1</var> profile), use.</p> 6267 6268 <pre> 6269 convert cockatoo.jpg profile.exif 6270 </pre> 6271 6272 <p>It is important to note that results may depend on whether or not the 6273 original image already has an included profile. Also, keep in mind that <a 6274 href="command-line-options.php#profile">-profile</a> is an "operator" (as opposed to a "setting") and 6275 therefore a conversion is made each time it is encountered, in order, in the 6276 command-line. For instance, in the following example, if the original image is 6277 CMYK with profile, a CMYK-CMYK-RGB conversion results.</p> 6278 6279 <pre> 6280 convert CMYK.tif -profile "CMYK.icc" -profile "RGB.icc" RGB.tiff 6281 </pre> 6282 6283 <p>Furthermore, since ICC profiles are not necessarily symmetric, extra 6284 conversion steps can yield unwanted results. CMYK profiles are often very 6285 asymmetric since they involve 3>4 and 4>3 channel mapping. 6286 </p> 6287 6288 <div style="margin: auto;"> 6289 <h3 class="magick-header"><a id="quality"></a>-quality <var>value</var></h3> 6290 </div> 6291 6292 <p class="magick-description">JPEG/MIFF/PNG compression level.</p> 6293 6294 <p>For the JPEG and MPEG image formats, quality is 1 (lowest image quality and 6295 highest compression) to 100 (best quality but least effective compression). 6296 The default is to use the estimated quality of your input image if it can 6297 be determined, otherwise 92. When the quality is greater than 90, then the 6298 chroma channels are not downsampled. 6299 Use the <a href="command-line-options.php#sampling-factor">-sampling-factor</a> option to specify the 6300 factors for chroma downsampling.</p> 6301 6302 <p>For the JPEG-2000 image format, quality is mapped using a non-linear 6303 equation to the compression ratio required by the Jasper library. This 6304 non-linear equation is intended to loosely approximate the quality provided by 6305 the JPEG v1 format. The default quality value 100, a request for non-lossy 6306 compression. A quality of 75 results in a request for 16:1 compression.</p> 6307 6308 <p>For the MNG and PNG image formats, the quality value sets the zlib 6309 compression level (quality / 10) and filter-type (quality % 10). The default 6310 PNG "quality" is 75, which means compression level 7 with adaptive PNG 6311 filtering, unless the image has a color map, in which case it means 6312 compression level 7 with no PNG filtering.</p> 6313 6314 <p>For compression level 0 (quality value less than 10), the Huffman-only 6315 strategy is used, which is fastest but not necessarily the worst 6316 compression.</p> 6317 6318 <p>If filter-type is 4 or less, the specified PNG filter-type is used for 6319 all scanlines:</p> 6320 6321 <dl class="dl-horizontal"> 6322 <dt>0</dt><dd>none</dd> 6323 <dt>1</dt><dd>sub</dd> 6324 <dt>2</dt><dd>up</dd> 6325 <dt>3</dt><dd>average</dd> 6326 <dt>4</dt><dd>Paeth</dd> 6327 </dl> 6328 6329 <p>If filter-type is 5, adaptive filtering is used when quality is greater 6330 than 50 and the image does not have a color map, otherwise no filtering is 6331 used.</p> 6332 6333 <p>If filter-type is 6, adaptive filtering 6334 with <var>minimum-sum-of-absolute-values</var> is used.</p> 6335 6336 <p>Only if the output is MNG, if filter-type is 7, the LOCO color 6337 transformation (intrapixel differencing) and adaptive filtering 6338 with <var>minimum-sum-of-absolute-values</var> are used.</p> 6339 6340 <p>If the filter-type is 8 the zlib Z_RLE compression strategy (or the 6341 Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with 6342 adaptive PNG filtering.</p> 6343 6344 <p>If the filter-type is 9 the zlib Z_RLE compression strategy (or the 6345 Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with 6346 no PNG filtering.</p> 6347 6348 <p>The quality setting has no effect on the appearance or signature of PNG 6349 and MNG images, since the compression is always lossless.</p> 6350 6351 <p>Not all combinations of compression level, strategy, and PNG filter type 6352 can be obtained using the -quality option. For more precise control, 6353 you can use the PNG:compression-level=N, PNG:compression-strategy=N, and 6354 PNG:compression-filter=N defines, respectively, instead. 6355 See <a href="command-line-options.php#define">-define</a>. Values from the defines take precedence 6356 over values from the -quality option.</p> 6357 6358 <p>For further information, see 6359 the <a href="http://www.w3.org/pub/WWW/TR">PNG</a> specification.</p> 6360 6361 <p>For the MIFF and TIFF image formats, quality/10 is the <a href="command-line-options.php#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> 6362 6363 <p>For the BPG image format, quality/2 is the actual BPG compression level (range from 0 to 51).</p> 6364 6365 <div style="margin: auto;"> 6366 <h3 class="magick-header"><a id="quantize"></a>-quantize <var>colorspace</var></h3> 6367 </div> 6368 6369 <p class="magick-description">reduce colors using this colorspace.</p> 6370 6371 <p>This setting defines the colorspace used to sort out and reduce the number 6372 of colors needed by an image (for later dithering) by operators such as <a 6373 href="command-line-options.php#colors" >-colors</a>, Note that color reduction also happens 6374 automatically when saving images to color-limited image file formats, such as 6375 GIF, and PNG8.</p> 6376 6377 6378 <div style="margin: auto;"> 6379 <h3 class="magick-header"><a id="quiet"></a>-quiet</h3> 6380 </div> 6381 6382 <p class="magick-description">suppress all warning messages. Error messages are still reported.</p> 6383 6384 <div style="margin: auto;"> 6385 <h3 class="magick-header"><a id="radial-blur"></a>-radial-blur <var>angle</var></h3> 6386 </div> 6387 6388 <p class="magick-description">Blur around the center of the image.</p> 6389 6390 <p>Note that this is actually a rotational blur rather than a radial and as 6391 such actually mis-named. </p> 6392 6393 <p>The <a href="command-line-options.php#virtual-pixel">-virtual-pixel</a> setting will determine how 6394 pixels which are outside the image proper are blurred into the final result. 6395 </p> 6396 6397 6398 <div style="margin: auto;"> 6399 <h3 class="magick-header"><a id="raise"></a>-raise <var>thickness</var></h3> 6400 </div> 6401 6402 <p class="magick-description">Lighten or darken image edges.</p> 6403 6404 <p>This will create a 3-D effect. Use <a href="command-line-options.php#raise">-raise</a> to create 6405 a raised effect, otherwise use <a href="command-line-options.php#raise">+raise</a>. </p> 6406 6407 <p>Unlike the similar <a href="command-line-options.php#frame">-frame</a> option, <a 6408 href="command-line-options.php#raise">-raise</a> does not alter the dimensions of the image.</p> 6409 6410 <div style="margin: auto;"> 6411 <h3 class="magick-header"><a id="random-threshold"></a>-random-threshold <var>low</var>x<var>high</var></h3> 6412 </div> 6413 6414 <p class="magick-description">Apply a random threshold to the image.</p> 6415 6416 <div style="margin: auto;"> 6417 <h3 class="magick-header"><a id="red-primary"></a>-red-primary <var>x,y</var></h3> 6418 </div> 6419 6420 <p class="magick-description">Set the red chromaticity primary point.</p> 6421 6422 <div style="margin: auto;"> 6423 <h3 class="magick-header"><a id="regard-warnings"></a>-regard-warnings</h3> 6424 </div> 6425 6426 <p class="magick-description">Pay attention to warning messages.</p> 6427 6428 <p>This option causes some warnings in some image formats to be treated 6429 as errors. </p> 6430 6431 <div style="margin: auto;"> 6432 <h3 class="magick-header"><a id="remap"></a>-remap <var>filename</var></h3> 6433 </div> 6434 6435 <p class="magick-description">Reduce the number of colors in an image to the colors used by this image.</p> 6436 6437 <p>If the <a href="command-line-options.php#dither">-dither</a> setting is enabled (the default) then 6438 the given colors are dithered over the image as necessary, otherwise the closest 6439 color (in RGB colorspace) is selected to replace that pixel in the image. </p> 6440 6441 <p>As a side effect of applying a <a href="command-line-options.php#remap">-remap</a> of colors across all 6442 images in the current image sequence, all the images will have the same color 6443 table. That means that when saved to a file format such as GIF, it will use 6444 that color table as a single common or global color table, for all the images, 6445 without requiring extra local color tables. </p> 6446 6447 <p>Use <a href="command-line-options.php#remap">+remap</a> to reduce all images in the current image 6448 sequence to use a common color map over all the images. This equivalent to 6449 appending all the images together (without extra background colors) and color 6450 reducing those images using <a href="command-line-options.php#colors">-colors</a> with a 256 color 6451 limit, then <a href="command-line-options.php#remap">-remap</a> those colors over the original list of 6452 images. This ensures all the images follow a single color map. </p> 6453 6454 <p>If the number of colors over all the images is less than 256, then <a 6455 href="command-line-options.php#remap">+remap</a> should not perform any color reduction or dithering, as 6456 no color changes are needed. In that case, its only effect is to force the use 6457 of a global color table. This recommended after using either <a 6458 href="command-line-options.php#colors">-colors</a> or <a href="command-line-options.php#ordered-dither">-ordered-dither</a> to 6459 reduce the number of colors in an animated image sequence. </p> 6460 6461 <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> 6462 6463 <div style="margin: auto;"> 6464 <h3 class="magick-header"><a id="region"></a>-region <var>geometry</var></h3> 6465 </div> 6466 6467 <p class="magick-description">Set a region in which subsequent operations apply.</p> 6468 6469 <p>The <var>x</var> and <var>y</var> offsets are treated 6470 in the same manner as in <a href="command-line-options.php#crop">-crop</a>.</p> 6471 6472 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6473 6474 <p>Use <code>+region</code> to remove any previously set regions.</p> 6475 6476 <div style="margin: auto;"> 6477 <h3 class="magick-header"><a id="remote"></a>-remote</h3> 6478 </div> 6479 6480 <p class="magick-description">perform a remote operation.</p> 6481 6482 <p>The only command recognized is the name of an image file to load.</p> 6483 6484 <p>If you have more than one <a href="display.php">display</a> application 6485 running simultaneously, use the <a href="command-line-options.php#window"> window</a> option to 6486 specify which application to control.</p> 6487 6488 <div style="margin: auto;"> 6489 <h3 class="magick-header"><a id="render"></a>-render</h3> 6490 </div> 6491 6492 <p class="magick-description">render vector operations.</p> 6493 6494 <p>Use <a href="command-line-options.php#render">+render</a> to turn off rendering vector operations. 6495 This useful when saving the result to vector formats such as MVG or SVG.</p> 6496 6497 <div style="margin: auto;"> 6498 <h3 class="magick-header"><a id="repage"></a>-repage <var>geometry</var></h3> 6499 </div> 6500 6501 <p class="magick-description">Adjust the canvas and offset information of the image.</p> 6502 6503 <p>This option is like <a href="command-line-options.php#page">-page</a> but acts as an image operator 6504 rather than a setting. You can separately set the canvas size or the offset 6505 of the image on that canvas by only providing those components. </p> 6506 6507 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6508 6509 <p>If a <code>!</code> flag is given the offset given is added to the existing 6510 offset to move the image relative to its previous position. This useful for 6511 animation sequences. </p> 6512 6513 <p>A given a canvas size of zero such as '<code>0x0</code>' forces it to 6514 recalculate the canvas size so the image (at its current offset) will appear 6515 completely on that canvas (unless it has a negative offset).</p> 6516 6517 <p>Use <a href="command-line-options.php#repage">+repage</a> to completely remove/reset the virtual 6518 canvas meta-data from the images. </p> 6519 6520 <p>The <a href="command-line-options.php#set">-set</a> '<code>page</code>' option can be used to 6521 directly assign virtual canvas meta-data. </p> 6522 6523 6524 <div style="margin: auto;"> 6525 <h3 class="magick-header"><a id="resample"></a>-resample <var>horizontal</var>x<var>vertical</var></h3> 6526 </div> 6527 6528 <p class="magick-description">Resample image to specified horizontal and vertical resolution.</p> 6529 6530 <p>Resize the image so that its rendered size remains the same as the original 6531 at the specified target resolution. For example, if a 300 DPI image renders at 6532 3 inches by 2 inches on a 300 DPI device, when the image has been resampled to 6533 72 DPI, it will render at 3 inches by 2 inches on a 72 DPI device. Note that 6534 only a small number of image formats (e.g. JPEG, PNG, and TIFF) are capable of 6535 storing the image resolution. For formats which do not support an image 6536 resolution, the original resolution of the image must be specified via <a 6537 href="command-line-options.php#density">-density</a> on the command line prior to specifying the 6538 resample resolution.</p> 6539 6540 <p>Note that Photoshop stores and obtains image resolution from a proprietary 6541 embedded profile. If this profile exists in the image, then Photoshop will 6542 continue to treat the image using its former resolution, ignoring the image 6543 resolution specified in the standard file header.</p> 6544 6545 <div style="margin: auto;"> 6546 <h3 class="magick-header"><a id="resize"></a>-resize <var>geometry</var></h3> 6547 </div> 6548 6549 <p class="magick-description">Resize an image.</p> 6550 6551 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets, if present in the geometry string, are 6552 ignored, and the <a href="command-line-options.php#gravity">-gravity</a> option has no effect.</p> 6553 6554 <p>If the <a href="command-line-options.php#filter">-filter</a> option 6555 or <code>-define filter:option=value</code> precedes the <a 6556 href="command-line-options.php#resize">-resize</a> option, the image is resized with the specified 6557 filter.</p> 6558 6559 <p>Many image processing algorithms assume your image is in a linear-light 6560 coding. If your image is gamma-corrected, you can remove the nonlinear gamma 6561 correction, apply the transform, then restore it like this:</p> 6562 6563 <pre> 6564 convert portrait.jpg -gamma .45455 -resize 25% -gamma 2.2 \ 6565 -quality 92 passport.jpg 6566 </pre> 6567 6568 <div style="margin: auto;"> 6569 <h3 class="magick-header"><a id="respect-parentheses"></a>-respect-parentheses</h3> 6570 </div> 6571 6572 <p class="magick-description">settings remain in effect until parenthesis boundary.</p> 6573 6574 <div style="margin: auto;"> 6575 <h3 class="magick-header"><a id="reverse"></a>-reverse</h3> 6576 </div> 6577 6578 <p class="magick-description">Reverse the order of images in the current image list.</p> 6579 6580 6581 <div style="margin: auto;"> 6582 <h3 class="magick-header"><a id="roll"></a>-roll {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var></h3> 6583 </div> 6584 6585 <p class="magick-description">roll an image vertically or horizontally by the amount given.</p> 6586 6587 <p>A negative <var>x</var> offset rolls the image right-to-left. 6588 A negative <var>y</var> offset rolls the image bottom-to-top.</p> 6589 6590 6591 <div style="margin: auto;"> 6592 <h3 class="magick-header"><a id="rotate"></a>-rotate <var>degrees</var>{<var><</var>}{<var>></var>}</h3> 6593 </div> 6594 6595 <p class="magick-description">Apply Paeth image rotation (using shear operations) to the image.</p> 6596 6597 <p>Use <code>></code> to rotate the image only if its width exceeds the 6598 height. <code><</code> rotates the image <var>only</var> if its width is less 6599 than the height. For example, if you specify <code>-rotate "-90>"</code> and 6600 the image size is 480x640, the image is not rotated. However, if the image is 6601 640x480, it is rotated by -90 degrees. If you use <code>></code> or 6602 <code><</code>, enclose it in quotation marks to prevent it from being 6603 misinterpreted as a file redirection.</p> 6604 6605 <p>Empty triangles in the corners, left over from rotating the image, are 6606 filled with the <code>background</code> color. </p> 6607 6608 <p>See also the <a href="command-line-options.php#distort">-distort</a> operator and specifically the 6609 '<code>ScaleRotateTranslate</code>' distort method. </p> 6610 6611 6612 <div style="margin: auto;"> 6613 <h3 class="magick-header"><a id="sample"></a>-sample <var>geometry</var></h3> 6614 </div> 6615 6616 <p class="magick-description">minify / magnify the image with pixel subsampling and pixel replication, respectively.</p> 6617 6618 <p>Change the image size simply by directly sampling the pixels original 6619 from the image. When magnifying, pixels are replicated in blocks. When 6620 minifying, pixels are sub-sampled (i.e., some rows and columns are skipped 6621 over). </p> 6622 6623 <p>The results are thus equivalent to using <a href="command-line-options.php#resize">-resize</a> with 6624 a <a href="command-line-options.php#filter">-filter</a> setting of <code>point</code> (nearest 6625 neighbor), though <a href="command-line-options.php#sample">-sample</a> is a lot faster, as it 6626 avoids all the filter processing of the image. As such it completely ignores 6627 the current <a href="command-line-options.php#filter">-filter</a> setting. </p> 6628 6629 <p>The key feature of the <a href="command-line-options.php#sample">-sample</a> is that no new colors 6630 will be added to the resulting image, though some colors may disappear. </p> 6631 6632 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets, if present in the geometry string, are 6633 ignored, unlike <a href="command-line-options.php#resize">-resize</a>. </p> 6634 6635 6636 <p>The actual sampling point is the middle of the sub-region being sampled. 6637 As such a single pixel sampling of an image will take the middle pixel, (or 6638 top-left-middle if image has even dimensions). However the <a 6639 href="command-line-options.php#define">-define</a> '<code>sample:offset</code>' can be set to modify 6640 this position some other location within each sub-region being sampled, as 6641 a percentage offset.</p> 6642 6643 <p>By default this value is '<code>50</code>' for the midpoint, but could be set 6644 to '<code>0</code>' for top-left, '<code>100</code>' for bottom-right, or with 6645 separate X and Y offsets such as '<code>0x50</code>' for left-middle edge of 6646 sampling sub-region.</p> 6647 6648 6649 <div style="margin: auto;"> 6650 <h3 class="magick-header"><a id="sampling-factor"></a>-sampling-factor <var>horizontal-factor</var>x<var>vertical-factor</var></h3> 6651 </div> 6652 6653 <p class="magick-description">sampling factors used by JPEG or MPEG-2 encoder and YUV decoder/encoder.</p> 6654 6655 <p>This option specifies the sampling factors to be used by the JPEG encoder 6656 for chroma downsampling. If this option is omitted, the JPEG library will use 6657 its own default values. When reading or writing the YUV format and when 6658 writing the M2V (MPEG-2) format, use <a 6659 href="command-line-options.php#sampling-factor">-sampling-factor 2x1</a> or <a 6660 href="command-line-options.php#sampling-factor">-sampling-factor 4:2:2</a> to specify the 4:2:2 6661 downsampling method.</p> 6662 6663 <div style="margin: auto;"> 6664 <h3 class="magick-header"><a id="scale"></a>-scale <var>geometry</var></h3> 6665 </div> 6666 6667 <p class="magick-description">minify / magnify the image with pixel block averaging and pixel replication, respectively.</p> 6668 6669 <p>Change the image size simply by replacing pixels by averaging pixels 6670 together when minifying, or replacing pixels when magnifying. </p> 6671 6672 <p>The results are thus equivalent to using <a href="command-line-options.php#resize">-resize</a> with 6673 a <a href="command-line-options.php#filter">-filter</a> setting of <code>box</code>. Though it is a lot 6674 faster, as it avoids all the filter processing of the image. As such it 6675 completely ignores the current <a href="command-line-options.php#filter">-filter</a> setting. </p> 6676 6677 <p>If when shrinking (minifying) images the original image is some integer 6678 multiple of the new image size, the number of pixels averaged together to 6679 produce the new pixel color is the same across the whole image. This is 6680 a special case known as 'binning' and is often used as a method of reducing 6681 noise in image such as those generated by digital cameras, especially in low 6682 light conditions. </p> 6683 6684 6685 <div style="margin: auto;"> 6686 <h3 class="magick-header"><a id="scene"></a>-scene <var>value</var></h3> 6687 </div> 6688 6689 <p class="magick-description">set scene number.</p> 6690 6691 <p>This option sets the scene number of an image or the first image in an image sequence.</p> 6692 6693 <div style="margin: auto;"> 6694 <h3 class="magick-header"><a id="screen"></a>-screen</h3> 6695 </div> 6696 6697 <p class="magick-description">specify the screen to capture.</p> 6698 6699 <p>This option indicates that the GetImage request used to obtain the image 6700 should be done on the root window, rather than directly on the specified 6701 window. In this way, you can obtain pieces of other windows that overlap the 6702 specified window, and more importantly, you can capture menus or other popups 6703 that are independent windows but appear over the specified window.</p> 6704 6705 <div style="margin: auto;"> 6706 <h3 class="magick-header"><a id="seed"></a>-seed</h3> 6707 </div> 6708 6709 <p class="magick-description">seed a new sequence of pseudo-random numbers</p> 6710 6711 <div style="margin: auto;"> 6712 <h3 class="magick-header"><a id="segment"></a>-segment <var>cluster-threshold</var>x<var>smoothing-threshold</var></h3> 6713 </div> 6714 6715 <p class="magick-description">segment the colors of an image.</p> 6716 6717 <p>Segment an image by analyzing the histograms of the color components and 6718 identifying units that are homogeneous with the fuzzy c-means technique. This 6719 is part of the ImageMagick color quantization routines. </p> 6720 6721 <p>Specify <var>cluster threshold</var> as the number of pixels in 6722 each cluster that must exceed the cluster threshold to be considered valid. 6723 <var>Smoothing threshold</var> eliminates noise in the second 6724 derivative of the histogram. As the value is increased, you can expect 6725 a smoother second derivative. The default is 1.5.</p> 6726 6727 <p>If the <a href="command-line-options.php#verbose">-verbose</a> setting is defined, a detailed report 6728 of the color clusters is returned.</p> 6729 6730 6731 <div style="margin: auto;"> 6732 <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> 6733 </div> 6734 6735 <p class="magick-description">Selectively blur pixels within a contrast threshold.</p> 6736 6737 <p>Blurs those pixels that are less than or equal to the threshold in 6738 contrast. The threshold may be expressed as a fraction of <var>QuantumRange</var> or as a percentage.</p> 6739 6740 <div style="margin: auto;"> 6741 <h3 class="magick-header"><a id="separate"></a>-separate</h3> 6742 </div> 6743 6744 <p class="magick-description">separate an image channel into a grayscale image. Specify the channel with <a href="command-line-options.php#channel">-channel</a>.</p> 6745 6746 <div style="margin: auto;"> 6747 <h3 class="magick-header"><a id="sepia-tone"></a>-sepia-tone <var>percent-threshold</var></h3> 6748 </div> 6749 6750 <p class="magick-description">simulate a sepia-toned photo.</p> 6751 6752 <p>Specify <var>threshold</var> as the percent threshold of the intensity (0 - 99.9%).</p> 6753 6754 <p>This option applies a special effect to the image, similar to the effect 6755 achieved 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 6756 toning. A threshold of 80% is a good starting point for a reasonable 6757 tone.</p> 6758 6759 6760 6761 <div style="margin: auto;"> 6762 <h3 class="magick-header"><a id="set"></a>-set <var>key value</var></h3> 6763 <h3 class="magick-header">+set <var>key</var></h3> 6764 </div> 6765 6766 <p class="magick-description">sets image attributes and properties for images in the current image sequence.</p> 6767 6768 <p>This will assign (or modify) specific settings attached to all the images 6769 in the current image sequence. Using the <a href="command-line-options.php#set">+set</a> form of the 6770 option will either remove, or reset that setting to a default state, as 6771 appropriate. </p> 6772 6773 <p>For example, it will modify specific well known image meta-data 6774 'attributes' such as those normally overridden by: the options <a 6775 href="command-line-options.php#delay" >-delay</a>, <a href="command-line-options.php#dispose" >-dispose</a>, and <a 6776 href="command-line-options.php#page" >-page</a>, <a href="command-line-options.php#colorspace" >-colorspace</a>; generally 6777 assigned before the image is read in, by using a <var>key</var> of 6778 the same name. </p> 6779 6780 <p>If the given <var>key</var> does not match a specific known 6781 'attribute ', such as shown above, the setting is stored as a a free form 6782 'property' string. Such settings are listed in <a href="command-line-options.php#verbose" 6783 >-verbose</a> information ("<code>info:</code>" output format) as "Properties". 6784 </p> 6785 6786 <p>This includes string 'properties' that are set by and assigned to images 6787 using the options <a href="command-line-options.php#comment" >-comment</a>, <a href="command-line-options.php#label" 6788 >-label</a>, <a href="command-line-options.php#caption" >-caption</a>. These options actually assign 6789 a global 'artifact' which are automatically assigned (and any <a href="escape.php" >Format Percent 6790 Escapes</a> expanded) to images as they are read in. For example:</p> 6791 6792 <pre> 6793 -> convert rose: -set comment 'Rose is a rose is a rose is a rose' rose.png 6794 identify -format %c rose.png 6795 Rose is a rose is a rose is a rose 6796 </pre> 6797 6798 <p>The set value can also make use of <a href="escape.php" >Format and Print Image 6799 Properties</a> in the defined value. For example:</p> 6800 6801 <pre> 6802 -> convert rose: -set origsize '%wx%h' -resize 50% \ 6803 -format 'Old size = %[origsize] New size = %wx%h' info: 6804 Old size = 70x46 New size = 35x23 6805 </pre> 6806 6807 <p>Other well known 'properties' that are available include: 6808 '<code>date:create</code>' and '<code>date:modify</code>' and 6809 '<code>signature</code>'. </p> 6810 6811 <p>The <a href="command-line-options.php#repage">-repage</a> operator will also allow you to modify 6812 the '<code>page</code>' attribute of an image for images already in memory (also 6813 see <a href="command-line-options.php#repage">-page</a>). However it is designed to provide a finer 6814 control of the sub-parts of this 'attribute'. The <a href="command-line-options.php#set">-set page</a> 6815 option will only provide a direct, unmodified assignment of '<code>page</code>' 6816 attribute. </p> 6817 6818 <p>This option can also associate a colorspace or profile with your image. 6819 For example,</p> 6820 6821 <pre> 6822 convert image.psd -set profile ISOcoated_v2_eci.icc image-icc.psd 6823 </pre> 6824 6825 <p>Some 'properties' must be defined in a specific way to be used. For 6826 example only 'properties' prefixed with "<code>filename:</code>" can be used to 6827 modify the output filename of an image. For example</p> 6828 6829 <pre> 6830 convert rose: -set filename:mysize '%wx%h' 'rose_%[filename:mysize].png' 6831 </pre> 6832 6833 <p>If the setting value is prefixed with "<code>option:</code>" the setting will 6834 be saved as a global "Artifact" exactly as if it was set using the <a 6835 href="command-line-options.php#define" >-define</a> option. As such settings are global in scope, they 6836 can be used to pass 'attributes' and 'properties' of one specific image, 6837 in a way that allows you to use them in a completely different image, even if 6838 the original image has long since been modified or destroyed. For example: </p> 6839 6840 <pre> 6841 convert rose: -set option:rosesize '%wx%h' -delete 0 \ 6842 label:'%[rosesize]' label_size_of_rose.gif" 6843 </pre> 6844 6845 <p>Note that <a href="escape.php" >Format Percent Escapes</a> will only match 6846 a 'artifact' if the given <var>key</var> does not match an existing 6847 'attribute' or 'property'. </p> 6848 6849 <p>You can set the attributes of the image registry by prefixing the value 6850 with <code>registry:</code>.</p> 6851 6852 <p>The <a href="command-line-options.php#set">-set profile</a> option can also be used to inject 6853 previously-formatted ancillary chunks into the output PNG file, using 6854 the commandline option as shown below or by setting the profile via a 6855 programming interface:</p> 6856 6857 <pre> 6858 convert in.png -set profile PNG-chunk-x:<filename> out.png 6859 </pre> 6860 6861 <p>where <var>x</var> is a location flag and 6862 <var>filename</var> is a file containing the chunk 6863 name in the first 4 bytes, then a colon (":"), followed by the chunk data. 6864 This encoder will compute the chunk length and CRC, so those must not 6865 be included in the file.</p> 6866 6867 <p>"x" can be "b" (before PLTE), "m" (middle, i.e., between PLTE and IDAT), 6868 or "e" (end, i.e., after IDAT). If you want to write multiple chunks 6869 of the same type, then add a short unique string after the "x" to prevent 6870 subsequent profiles from overwriting the preceding ones, e.g.,</p> 6871 6872 6873 <pre> 6874 convert in.png -set profile PNG-chunk-b01:file01 \ 6875 -profile PNG-chunk-b02:file02 out.png 6876 </pre> 6877 6878 <div style="margin: auto;"> 6879 <h3 class="magick-header"><a id="shade"></a>-shade <var>azimuth</var>x<var>elevation</var></h3> 6880 </div> 6881 6882 <p class="magick-description">shade the image using a distant light source.</p> 6883 6884 <p>Specify <var>azimuth</var> and <var>elevation</var> as 6885 the position of the light source. Use <a href="command-line-options.php#shade">+shade</a> to return 6886 the shading results as a grayscale image.</p> 6887 6888 <div style="margin: auto;"> 6889 <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> 6890 </div> 6891 6892 <p class="magick-description">simulate an image shadow.</p> 6893 6894 <div style="margin: auto;"> 6895 <h3 class="magick-header"><a 6896 id="shared-memory"></a>-shared-memory</h3> 6897 </div> 6898 6899 <p class="magick-description">use shared memory.</p> 6900 6901 <p>This option specifies whether the utility should attempt to use shared 6902 memory for pixmaps. ImageMagick must be compiled with shared memory support, 6903 and the display must support the <var>MIT-SHM</var> extension. 6904 Otherwise, this option is ignored. The default is <code>True</code>.</p> 6905 6906 <div style="margin: auto;"> 6907 <h3 class="magick-header"><a id="sharpen"></a>-sharpen <var>radius</var><br />-sharpen <var>radius</var>x<var>sigma</var></h3> 6908 </div> 6909 6910 <p class="magick-description">sharpen the image.</p> 6911 6912 <p>Use a Gaussian operator of the given radius and standard deviation (sigma).</p> 6913 6914 <div style="margin: auto;"> 6915 <h3 class="magick-header"><a id="shave"></a>-shave <var>geometry</var></h3> 6916 </div> 6917 6918 <p class="magick-description">Shave pixels from the image edges.</p> 6919 6920 <p>The <var>size</var> portion of the <var>geometry</var> 6921 argument specifies the width of the region to be removed from both sides of 6922 the image and the height of the regions to be removed from top and bottom. 6923 Offsets are ignored.</p> 6924 6925 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6926 6927 <div style="margin: auto;"> 6928 <h3 class="magick-header"><a id="shear"></a>-shear <var>Xdegrees</var>[x<var>Ydegrees</var>]</h3> 6929 </div> 6930 6931 <p class="magick-description">Shear the image along the x-axis and/or y-axis.</p> 6932 6933 <p>The shear angles may be positive, negative, or zero. When <var>Ydegrees</var> is omitted it defaults to 0. When both angles are 6934 given, the horizontal component of the shear is performed before the vertical 6935 component.</p> 6936 6937 <p>Shearing slides one edge of an image along the x-axis or y-axis (i.e., 6938 horizontally or vertically, respectively),creating a parallelogram. The amount 6939 of each is controlled by the respective shear angle. For horizontal shears, 6940 <var>Xdegrees</var> is measured clockwise relative to "up" (the 6941 negative 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 6942 positive x-axis), sliding the right edge down when 0<<var>Ydegrees</var><90 and up when 90<<var>Ydegrees</var><180.</p> 6943 6944 <p>Empty triangles left over from shearing the image are filled with the color 6945 defined by the <a href="command-line-options.php#fill">-background</a> option. The color is specified 6946 using the format described under the <a href="command-line-options.php#fill">-fill</a> option.</p> 6947 6948 <p>The horizontal shear is performed before the vertical part. This is 6949 important to note, since horizontal and vertical shears do not 6950 <var>commute</var>, i.e., the order matters in a sequence of shears. For 6951 example, the following two commands are not equivalent.</p> 6952 6953 <pre> 6954 convert logo: -shear 20x0 -shear 0x60 logo-sheared.png 6955 convert logo: -shear 0x60 -shear 20x0 logo-sheared.png 6956 </pre> 6957 6958 <p>The first of the two commands above is equivalent to the following, except 6959 for the amount of empty space created; the command that follows generates 6960 a smaller image, and so is a better choice in terms of time and space.</p> 6961 6962 <pre> 6963 convert logo: -shear 20x60 logo-sheared.png 6964 </pre> 6965 6966 <div style="margin: auto;"> 6967 <h3 class="magick-header"><a id="sigmoidal-contrast"></a>-sigmoidal-contrast <var>contrast</var>x<var>mid-point</var></h3> 6968 </div> 6969 6970 <p class="magick-description">increase the contrast without saturating highlights or shadows.</p> 6971 6972 <p>Increase the contrast of the image using a sigmoidal transfer function 6973 without saturating highlights or shadows. <var>Contrast</var> 6974 indicates how much to increase the contrast. For example, 0 is none, 3 is 6975 typical and 20 is a lot. 6976 </p> 6977 6978 <p>The <var>mid-point</var> indicates where the maximum change 6979 'slope' in contrast should fall in the resultant image (0 is white; 50% is 6980 middle-gray; 100% is black). </p> 6981 6982 <p>By default the image contrast is increased, use <var>+sigmoidal-contrast</var> to decrease the contrast.</p> 6983 6984 <p>To achieve the equivalent of a sigmoidal brightness change (similar to 6985 a gamma adjustment), you would use <var>-sigmoidal-contrast 6986 {brightness}x0%</var> to increase brightness and <var>+sigmoidal-contrast {brightness}x0%</var> to decrease brightness. 6987 Note the use of '0' fo rthe mid-point of the sigmoidal curve. </p> 6988 6989 <p>Using a very high <var>contrast</var> will produce a sort of 6990 'smoothed thresholding' of the image. Not as sharp (with high aliasing 6991 effects) of a true threshold, but with tapered gray-levels around the threshold 6992 <var>mid-point</var>. </p> 6993 6994 <div style="margin: auto;"> 6995 <h3 class="magick-header"><a id="silent"></a>-silent</h3> 6996 </div> 6997 6998 <p class="magick-description">operate silently.</p> 6999 7000 <div style="margin: auto;"> 7001 <h3 class="magick-header"><a id="similarity-threshold"></a>-similarity-threshold <var>value</var></h3> 7002 </div> 7003 7004 <p class="magick-description">minimum RMSE for subimage match.</p> 7005 7006 <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> 7007 7008 <div style="margin: auto;"> 7009 <h3 class="magick-header"><a id="size"></a>-size <var>width</var>[x<var>height</var>][<var>+offset</var>]</h3> 7010 </div> 7011 7012 <p class="magick-description">set the width and height of the image.</p> 7013 7014 <p>Use this option to specify the width and height of raw images whose 7015 dimensions are unknown such as <code>GRAY</code>, <code>RGB</code>, or 7016 <code>CMYK</code>. In addition to width and height, use <a 7017 href="command-line-options.php#size">-size</a> with an offset to skip any header information in the 7018 image or tell the number of colors in a <code>MAP</code> image file, (e.g. -size 7019 640x512+256).</p> 7020 7021 <p>For Photo CD images, choose from these sizes:</p> 7022 7023 <pre> 7024 192x128 7025 384x256 7026 768x512 7027 1536x1024 7028 3072x2048 7029 </pre> 7030 7031 <div style="margin: auto;"> 7032 <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> 7033 </div> 7034 7035 <p class="magick-description">simulate a pencil sketch.</p> 7036 7037 <p>Sketch with the given radius, standard deviation (sigma), and angle. The 7038 angle given is the angle toward which the image is sketched. That is the 7039 direction people would consider the object is coming from. </p> 7040 7041 <div style="margin: auto;"> 7042 <h3 class="magick-header"><a id="smush"></a>-smush <var>offset</var></h3> 7043 </div> 7044 7045 <p class="magick-description">smush an image sequence together.</p> 7046 7047 <div style="margin: auto;"> 7048 <h3 class="magick-header"><a id="snaps"></a>-snaps <var>value</var></h3> 7049 </div> 7050 7051 <p class="magick-description">Set the number of screen snapshots.</p> 7052 7053 <p>Use this option to grab more than one image from the X server screen, to create an animation sequence.</p> 7054 7055 <div style="margin: auto;"> 7056 <h3 class="magick-header"><a id="solarize"></a>-solarize <var>percent-threshold</var></h3> 7057 </div> 7058 7059 <p class="magick-description">negate all pixels above the threshold level.</p> 7060 7061 <p>Specify <var>factor</var> as the percent threshold of the intensity (0 - 99.9%).</p> 7062 7063 <p>This option produces a <var>solarization</var> effect seen when 7064 exposing a photographic film to light during the development process.</p> 7065 7066 <div style="margin: auto;"> 7067 <h3 class="magick-header"><a id="sparse-color"></a>-sparse-color <var>method</var> '<var>x</var>,<var>y</var> <var>color</var> ...'</h3> 7068 </div> 7069 7070 <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> 7071 7072 7073 <dl class="dl-horizontal"> 7074 <dt>barycentric</dt> 7075 <dd>three point triangle of color given 3 points. 7076 Giving only 2 points will form a linear gradient between those points. 7077 The gradient generated extends beyond the triangle created by those 7078 3 points. </dd> 7079 <dt>bilinear</dt> 7080 <dd>Like barycentric but for 4 points. Less than 4 points 7081 fall back to barycentric. </dd> 7082 <dt>voronoi</dt> 7083 <dd>Simply map each pixel to the to nearest color point 7084 given. The result are polygonal 'cells' of solid color. </dd> 7085 <dt>manhatten</dt> 7086 <dd>Like voronoi, but resulting polygonal 'cells' are mapped to a fixed coordinate system.</dd> 7087 <dt>shepards</dt> 7088 <dd>Colors points biased on the ratio of inverse distance 7089 squared. Generating spots of color in a sea of the average of 7090 colors. </dd> 7091 <dt>inverse</dt> 7092 <dd>Colors points biased on the ratio of inverse distance. 7093 This generates sharper points of color rather than rounded spots of 7094 '<code>shepards</code>' Generating spots of color in a sea of the 7095 average of colors. </dd> 7096 </dl> 7097 7098 <p>The points are placed according to the images location on the virtual 7099 canvas (<a href="command-line-options.php#page" >-page</a> or <a href="command-line-options.php#repage" >-repage</a> 7100 offset), and do not actually have to exist on the given image, but may be 7101 some point beyond the edge of the image. All points are floating point values. 7102 </p> 7103 7104 <p>Only the color channels defined by the <a href="command-line-options.php#channel" >-channel</a> are 7105 modified, which means that by default matte/alpha transparency channel is not 7106 effected. Typically transparency channel is turned off either before or after 7107 the operation. </p> 7108 7109 <p>Of course if some color points are transparent to generate a transparent 7110 gradient, then the image also requires transparency enabled to store the 7111 values. </p> 7112 7113 <p>All the above methods when given a single point of color will replace all 7114 the colors in the image with the color given, regardless of the point. This is 7115 logical, and provides an alternative technique to recolor an image to some 7116 default value. </p> 7117 7118 7119 <div style="margin: auto;"> 7120 <h3 class="magick-header"><a id="splice"></a>-splice <var>geometry</var></h3> 7121 </div> 7122 7123 <p class="magick-description">Splice the current background color into the image.</p> 7124 7125 <p>This will add rows and columns of the current <a 7126 href="command-line-options.php#background">-background</a> color into the given image according to the 7127 given <a href="command-line-options.php#gravity">-gravity</a> geometry setting. See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Essentially <a href="command-line-options.php#splice">-splice</a> will divide the 7128 image into four quadrants, separating them by the inserted rows and columns. 7129 </p> 7130 7131 <p>If a dimension of geometry is zero no rows or columns will be added for that 7132 dimension. Similarly using a zero offset with the appropriate <a 7133 href="command-line-options.php#gravity">-gravity</a> setting will add rows and columns to the edges of 7134 the image, padding the image only along that one edge. Edge padding is what <a 7135 href="command-line-options.php#splice">-splice</a> is most commonly used for. </p> 7136 7137 <p>If the exact same <var>geometry</var> and <a 7138 href="command-line-options.php#gravity">-gravity</a> is later used with <a href="command-line-options.php#chop">-chop</a> the 7139 added added all splices removed. </p> 7140 7141 <div style="margin: auto;"> 7142 <h3 class="magick-header"><a id="spread"></a>-spread <var>amount</var></h3> 7143 </div> 7144 7145 <p class="magick-description">displace image pixels by a random amount.</p> 7146 7147 <p>The argument <var>amount</var> defines the size of the 7148 neighborhood around each pixel from which to choose a candidate pixel to 7149 blend.</p> 7150 7151 <p>The lookup is controlled by the <a href="command-line-options.php#interpolate">-interpolate</a> setting.</p> 7152 7153 <div style="margin: auto;"> 7154 <h3 class="magick-header"><a id="statistic"></a>-statistic <var>type</var> <var>geometry</var></h3> 7155 </div> 7156 7157 <p class="magick-description">replace each pixel with corresponding statistic from the neighborhood.</p> 7158 7159 <p>Choose from these statistic types:</p> 7160 <dl class="dl-horizontal"> 7161 <dt>Gradient</dt><dd>maximum difference (max - min) value in neighborhood</dd> 7162 <dt>Maximum</dt><dd>maximum value per channel in neighborhood</dd> 7163 <dt>Minimum</dt><dd>minimum value per channel in neighborhood</dd> 7164 <dt>Mean</dt><dd>average value per channel in neighborhood</dd> 7165 <dt>Median</dt><dd>median value per channel in neighborhood</dd> 7166 <dt>Mode</dt><dd>mode (most frequent) value per channel in neighborhood</dd> 7167 <dt>Nonpeak</dt><dd>value just before or after the median value per channel in neighborhood</dd> 7168 <dt>RMS</dt><dd>root mean square value per channel in neighborhood</dd> 7169 <dt>StandardDeviation</dt><dd> standard deviation value per channel in neighborhood</dd> 7170 </dl> 7171 7172 <div style="margin: auto;"> 7173 <h3 class="magick-header"><a id="stegano"></a>-stegano <var>offset</var></h3> 7174 </div> 7175 7176 <p class="magick-description">hide watermark within an image.</p> 7177 7178 <p>Use an offset to start the image hiding some number of pixels from the 7179 beginning of the image. Note this offset and the image size. You will need 7180 this information to recover the steganographic image (e.g. display -size 7181 320x256+35 stegano:image.png).</p> 7182 7183 <div style="margin: auto;"> 7184 <h3 class="magick-header"><a id="stereo"></a>-stereo <var>+x</var>{<var>+y</var>}</h3> 7185 </div> 7186 7187 <p class="magick-description">composite two images to create a red / cyan stereo anaglyph.</p> 7188 7189 <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> 7190 7191 <div style="margin: auto;"> 7192 <h3 class="magick-header"><a id="storage-type"></a>-storage-type <var>type</var></h3> 7193 </div> 7194 7195 <p class="magick-description">pixel storage type. Here are the valid types:</p> 7196 7197 <dl class="dl-horizontal"> 7198 <dt>char</dt><dd>unsigned characters</dd> 7199 <dt>double</dt><dd>doubles</dd> 7200 <dt>float</dt><dd>floats</dd> 7201 <dt>integer</dt><dd>integers</dd> 7202 <dt>long</dt><dd>longs</dd> 7203 <dt>quantum</dt><dd>pixels in the native depth of your ImageMagick distribution</dd> 7204 <dt>short</dt><dd>unsigned shorts</dd> 7205 </dl> 7206 7207 <p>Float and double types are normalized from 0.0 to 1.0 otherwise the pixels 7208 values range from 0 to the maximum value the storage type can support.</p> 7209 7210 <div style="margin: auto;"> 7211 <h3 class="magick-header"><a id="stretch"></a>-stretch <var>fontStretch</var></h3> 7212 </div> 7213 7214 <p class="magick-description">Set a type of stretch style for fonts.</p> 7215 7216 <p>This setting suggests a type of stretch that ImageMagick should try to 7217 apply to the currently selected font family. Select <var>fontStretch</var> from the following.</p> 7218 7219 <pre> 7220 Any 7221 Condensed 7222 Expanded 7223 ExtraCondensed 7224 ExtraExpanded 7225 Normal 7226 SemiCondensed 7227 SemiExpanded 7228 UltraCondensed 7229 UltraExpanded 7230 </pre> 7231 7232 <p>To print a complete list of stretch types, use <a href="command-line-options.php#list">-list 7233 stretch</a>.</p> 7234 7235 <p>For other settings that affect fonts, see the options <a 7236 href="command-line-options.php#font">-font</a>, <a href="command-line-options.php#family">-family</a>, <a 7237 href="command-line-options.php#style">-style</a>, and <a href="command-line-options.php#weight">-weight</a>. </p> 7238 7239 <div style="margin: auto;"> 7240 <h3 class="magick-header"><a id="strip"></a>-strip</h3> 7241 </div> 7242 7243 <p class="magick-description">strip the image of any profiles or comments.</p> 7244 7245 <div style="margin: auto;"> 7246 <h3 class="magick-header"><a id="stroke"></a>-stroke <var>color</var></h3> 7247 </div> 7248 7249 <p class="magick-description">color to use when stroking a graphic primitive.</p> 7250 7251 <p>The color is specified using the format described under the <a href="command-line-options.php#fill">-fill</a> option.</p> 7252 7253 <p>See <a href="command-line-options.php#draw">-draw</a> for further details.</p> 7254 7255 <div style="margin: auto;"> 7256 <h3 class="magick-header"><a id="strokewidth"></a>-strokewidth <var>value</var></h3> 7257 </div> 7258 7259 <p class="magick-description">set the stroke width.</p> 7260 7261 <p>See <a href="command-line-options.php#draw">-draw</a> for further details.</p> 7262 7263 <div style="margin: auto;"> 7264 <h3 class="magick-header"><a id="style"></a>-style <var>fontStyle</var></h3> 7265 </div> 7266 7267 <p class="magick-description">Set a font style for text.</p> 7268 7269 <p>This setting suggests a font style that ImageMagick should try to apply to 7270 the currently selected font family. Select <var>fontStyle</var> from 7271 the following.</p> 7272 7273 <pre> 7274 Any 7275 Italic 7276 Normal 7277 Oblique 7278 </pre> 7279 7280 <p>For other settings that affect fonts, see the options <a 7281 href="command-line-options.php#font">-font</a>, <a href="command-line-options.php#family">-family</a>, <a 7282 href="command-line-options.php#stretch">-stretch</a>, and <a href="command-line-options.php#weight">-weight</a>. </p> 7283 7284 <div style="margin: auto;"> 7285 <h3 class="magick-header"><a id="subimage-search"></a>-subimage-search</h3> 7286 </div> 7287 7288 <p class="magick-description">search for subimage.</p> 7289 7290 <p>This option is required to have compare search for the best match location 7291 of a small image within a larger image. This search will produce two images 7292 (or two frames). The first is the "difference" image and the second will 7293 be the "match score" image.</p> 7294 7295 <p>The "match-score" image is smaller containing a pixel for ever possible 7296 position of the top-left corner of the given sub-image. that is its size will 7297 be the size of the larger_image - sub_image + 1. The brightest location in 7298 this image is the location s the locate on the best match that is also 7299 reported. Note that this may or may not be a perfect match, and the actual 7300 brightness will reflect this. Other bright 'peaks' can be used to locate other 7301 possible matching locations. </p> 7302 7303 <p>Note that the search will try to compare the sub-image at every possible 7304 location in the larger image, as such it can be very slow. The smaller the 7305 sub-image the faster this search is. </p> 7306 7307 7308 <div style="margin: auto;"> 7309 <h3 class="magick-header"><a id="swap"></a>-swap <var>index,index</var></h3> 7310 </div> 7311 7312 <p class="magick-description">Swap the positions of two images in the image sequence.</p> 7313 7314 <p>For example, <a href="command-line-options.php#swap">-swap 0,2</a> swaps the first and the third 7315 images in the current image sequence. Use <a href="command-line-options.php#swap">+swap</a> to switch 7316 the last two images in the sequence.</p> 7317 7318 <div style="margin: auto;"> 7319 <h3 class="magick-header"><a id="swirl"></a>-swirl <var>degrees</var></h3> 7320 </div> 7321 7322 <p class="magick-description">swirl image pixels about the center.</p> 7323 7324 <p><var>Degrees</var> defines the tightness of the swirl.</p> 7325 7326 <div style="margin: auto;"> 7327 <h3 class="magick-header"><a id="synchronize"></a>-synchronize</h3> 7328 </div> 7329 7330 <p class="magick-description">synchronize image to storage device.</p> 7331 7332 <p>Set to "true" to ensure all image data is fully flushed and synchronized 7333 to disk. There is a performance penalty, but the benefits include ensuring a 7334 valid image file in the event of a system crash and early reporting if there 7335 is not enough disk space for the image pixel cache.</p> 7336 7337 <div style="margin: auto;"> 7338 <h3 class="magick-header"><a id="taint"></a>-taint</h3> 7339 </div> 7340 7341 <p class="magick-description">Mark the image as modified.</p> 7342 7343 <div style="margin: auto;"> 7344 <h3 class="magick-header"><a id="text-font"></a>-text-font <var>name</var></h3> 7345 </div> 7346 7347 <p class="magick-description">font for writing fixed-width text.</p> 7348 7349 <p>Specifies the name of the preferred font to use in fixed (typewriter style) 7350 formatted text. The default is 14 point <var>Courier</var>.</p> 7351 7352 <p>You can tag a font to specify whether it is a PostScript, TrueType, or 7353 OPTION1 font. For example, <code>Courier.ttf</code> is a TrueType font and 7354 <code>x:fixed</code> is OPTION1.</p> 7355 7356 <div style="margin: auto;"> 7357 <h3 class="magick-header"><a id="texture"></a>-texture <var>filename</var></h3> 7358 </div> 7359 7360 <p class="magick-description">name of texture to tile onto the image background.</p> 7361 7362 <div style="margin: auto;"> 7363 <h3 class="magick-header"><a id="threshold"></a>-threshold <var>value</var>{<var>%</var>}</h3> 7364 </div> 7365 7366 <!-- {<var>green,blue,opacity</var>} 7367 <p>If the green or blue value is omitted, these channels use the same value as 7368 the first one provided. If all three color values are the same, the result is 7369 a bi-level image. If the opacity threshold is omitted, OpaqueOpacity is used 7370 and any partially transparent pixel becomes fully transparent.</p> 7371 --> 7372 7373 <p class="magick-description">Apply simultaneous black/white threshold to the image.</p> 7374 7375 <p>Any pixel values (more specifically, those channels set using <a href="command-line-options.php#channel">‑channel</a>) that exceed the specified threshold are reassigned the 7376 maximum channel value, while all other values are assigned the minimum.</p> 7377 7378 <p> The threshold value can be given as a percentage or as an absolute integer 7379 value corresponding to the desired channel value. When given as an integer, 7380 the minimum attainable value is 0 (corresponding to black when all channels 7381 are affected), but the maximum value (corresponding to white) is that of the 7382 <code>quantum depth</code> of the particular build of ImageMagick, and is 7383 therefore dependent on the installation. For that reason, a reasonable 7384 recommendation for most applications is to specify the threshold values as 7385 a percentage. </p> 7386 7387 <p> The following would force pixels with red values above 50% to have 100% 7388 red values, while those at or below 50% red would be set to 0 in the red 7389 channel. The green, blue, and alpha channels (if present) would be unchanged. 7390 </p> 7391 7392 <pre> 7393 convert in.png -channel red -threshold 50% out.png 7394 </pre> 7395 7396 <p>As (possibly) impractical but instructive examples, the following would 7397 generate an all-black and an all-white image with the same dimensions as the 7398 input image.</p> 7399 7400 7401 <pre> 7402 convert in.png -threshold 100% black.png 7403 convert in.png -threshold -1 white.png 7404 </pre> 7405 7406 <p>Note that the values of the transparency channel is treated as 'matte' 7407 values (0 is opaque) and not as 'alpha' values (0 is transparent).</p> 7408 7409 <p> See also <a href="command-line-options.php#black-threshold">‑black‑threshold</a> and <a href="command-line-options.php#white-threshold">‑white‑threshold</a>. 7410 </p> 7411 7412 <div style="margin: auto;"> 7413 <h3 class="magick-header"><a id="thumbnail"></a>-thumbnail <var>geometry</var></h3> 7414 </div> 7415 7416 <p class="magick-description">Create a thumbnail of the image.</p> 7417 7418 <p>This is similar to <a href="command-line-options.php#resize">-resize</a>, except it is optimized 7419 for speed and any image profile, other than a color profile, is removed to 7420 reduce the thumbnail size. To strip the color profiles as well, add <a 7421 href="command-line-options.php#strip">-strip</a> just before of after this option.</p> 7422 7423 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 7424 7425 <div style="margin: auto;"> 7426 <h3 class="magick-header"><a id="tile"></a>-tile <var>filename</var></h3> 7427 </div> 7428 7429 <p class="magick-description">Set the tile image used for filling a subsequent graphic primitive.</p> 7430 7431 <div style="margin: auto;"> 7432 <h3 class="magick-header">-tile <var>geometry</var></h3> 7433 </div> 7434 7435 <p class="magick-description">Specify the layout of images.</p> 7436 7437 <p>See <a href="command-line-processing.php#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 7438 7439 <div style="margin: auto;"> 7440 <h3 class="magick-header">-tile</h3> 7441 </div> 7442 7443 <p class="magick-description">Specifies that a subsequent composite operation is repeated across and down image.</p> 7444 7445 <div style="margin: auto;"> 7446 <h3 class="magick-header"><a id="tile-offset"></a>-tile-offset {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var></h3> 7447 </div> 7448 7449 <p class="magick-description">Specify the offset for tile images, relative to the background image it is tiled on.</p> 7450 7451 <p>This should be set before the tiling image is set by <a href="command-line-options.php#tile" 7452 >-tile</a> or <a href="command-line-options.php#texture" >-texture</a>, or directly applied for 7453 creating a tiled canvas using <code>TILE:</code> or <code>PATTERN:</code> input 7454 formats. </p> 7455 7456 <p>Internally ImageMagick does a <a href="command-line-options.php#roll" >-roll</a> of the tile image 7457 by the arguments given when the tile image is set. </p> 7458 7459 <div style="margin: auto;"> 7460 <h3 class="magick-header"><a id="tint"></a>-tint <var>value</var></h3> 7461 </div> 7462 7463 <p class="magick-description">Tint the image with the fill color.</p> 7464 7465 <p>Tint the image with the fill color.</p> 7466 7467 <p>Specify the amount of tinting as a percentage. Pure colors like black, 7468 white red, yellow, will not be affected by -tint. Only mid-range colors such 7469 as the various shades of grey.</p> 7470 7471 <div style="margin: auto;"> 7472 <h3 class="magick-header"><a id="title"></a>-title <var>string</var></h3> 7473 </div> 7474 7475 <p class="magick-description">Assign a title to displayed image.", "animate", "display", "montage</p> 7476 7477 <p>Use this option to assign a specific title to the image. This assigned to 7478 the image window and is typically displayed in the window title bar. 7479 Optionally you can include the image filename, type, width, height, Exif data, 7480 or other image attribute by embedding special format characters described 7481 under the <a href="command-line-options.php#format">-format</a> option.</p> 7482 7483 <p>For example,</p> 7484 7485 <pre> 7486 -title "%m:%f %wx%h" 7487 </pre> 7488 7489 <p>produces an image title of <code>MIFF:bird.miff 512x480</code> for an image 7490 titled <code>bird.miff</code> and whose width is 512 and height is 480.</p> 7491 7492 7493 <div style="margin: auto;"> 7494 <h3 class="magick-header"><a id="transform"></a>-transform</h3> 7495 </div> 7496 7497 <p class="magick-description">transform the image.</p> 7498 7499 <p>This option applies the transformation matrix from a previous <a href="command-line-options.php#affine">-affine</a> option.</p> 7500 7501 <pre> 7502 convert -affine 2,2,-2,2,0,0 -transform bird.ppm bird.jpg 7503 </pre> 7504 7505 7506 <p>This operator has been now been superseded by the <a 7507 href="command-line-options.php#distort">-distort</a> '<code>AffineProjection</code>' method. </p> 7508 7509 7510 <div style="margin: auto;"> 7511 <h3 class="magick-header"><a id="transparent"></a>-transparent <var>color</var></h3> 7512 </div> 7513 7514 <p class="magick-description">Make this color transparent within the image.</p> 7515 7516 <p>The <var>color</var> argument is defined using the format 7517 described under the <a href="command-line-options.php#fill">-fill</a> option. The <a href="command-line-options.php#fuzz" 7518 >-fuzz</a> setting can be used to match and replace colors similar to the one 7519 given. </p> 7520 7521 <p>Use <a href="command-line-options.php#transparent" >+transparent</a> to invert the pixels matched. 7522 that is make all non-matching colors transparent. </p> 7523 7524 <p>The <a href="command-line-options.php#opaque">-opaque</a> operator is exactly the same as <a 7525 href="command-line-options.php#transparent" >-transparent</a> but replaces the matching color with the 7526 current <a href="command-line-options.php#fill">-fill</a> color setting, rather than transparent. 7527 However the <a href="command-line-options.php#transparent" >-transparent</a> operator also ensures 7528 that the image has an alpha channel enabled, as per "<code><a href="command-line-options.php#alpha" 7529 >-alpha</a> set</code>", and does not require you to modify the <a 7530 href="command-line-options.php#channel">-channel</a> to enable alpha channel handling. </p> 7531 7532 <p>Note that this does not define the color as being the 'transparency color' 7533 used for color-mapped image formats, such as GIF. For that use <a 7534 href="command-line-options.php#transparent-color" >-transparent-color</a> </p> 7535 7536 7537 <div style="margin: auto;"> 7538 <h3 class="magick-header"><a id="transparent-color"></a>-transparent-color <var>color</var></h3> 7539 </div> 7540 7541 <p class="magick-description">Set the transparent color.</p> 7542 7543 <p>Sometimes this is used for saving to image formats such as 7544 GIF and PNG8 which uses this color to represent boolean transparency. This 7545 does not make a color transparent, it only defines what color the transparent 7546 color is in the color palette of the saved image. Use <a 7547 href="command-line-options.php#transparent">-transparent</a> to make an opaque color transparent.</p> 7548 7549 <p>This option allows you to have both an opaque visible color, as well as a 7550 transparent color of the same color value without conflict. That is, you can 7551 use the same color for both the transparent and opaque color areas within an 7552 image. This, in turn, frees to you to select a transparent color that is 7553 appropriate when an image is displayed by an application that does not handle a 7554 transparent color index, while allowing ImageMagick to correctly handle images of this 7555 type. </p> 7556 7557 <p>The default transparent color is <code>#00000000</code>, which is fully transparent black.</p> 7558 7559 <div style="margin: auto;"> 7560 <h3 class="magick-header"><a id="transpose"></a>-transpose</h3> 7561 </div> 7562 7563 <p class="magick-description">Mirror the image along the top-left to bottom-right diagonal.</p> 7564 7565 <p> This option mathematically transposes the pixel array. It is equivalent to the sequence <code>-flip -rotate 90</code>. 7566 </p> 7567 7568 <div style="margin: auto;"> 7569 <h3 class="magick-header"><a id="transverse"></a>-transverse</h3> 7570 </div> 7571 7572 <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> 7573 7574 7575 <div style="margin: auto;"> 7576 <h3 class="magick-header"><a id="treedepth"></a>-treedepth <var>value</var></h3> 7577 </div> 7578 7579 <p class="magick-description">tree depth for the color reduction algorithm.</p> 7580 7581 <p>Normally, this integer value is zero or one. A value of zero or one causes 7582 the use of an optimal tree depth for the color reduction algorithm.</p> 7583 7584 <p>An optimal depth generally allows the best representation of the source 7585 image with the fastest computational speed and the least amount of memory. 7586 However, the default depth is inappropriate for some images. To assure the 7587 best representation, try values between 2 and 8 for this parameter. Refer to 7588 the <a href="quantize.php" 7589 >color reduction algorithm</a> for more details.</p> 7590 7591 <p>The <a href="command-line-options.php#colors">-colors</a> or <a href="command-line-options.php#monochrome">-monochrome</a> 7592 option, or writing to an image format which requires color reduction, is 7593 required for this option to take effect.</p> 7594 7595 <div style="margin: auto;"> 7596 <h3 class="magick-header"><a id="trim"></a>-trim</h3> 7597 </div> 7598 7599 <p class="magick-description">trim an image.</p> 7600 7601 <p>This option removes any edges that are exactly the same color as the corner 7602 pixels. Use <a href="command-line-options.php#fuzz">-fuzz</a> to make <a href="command-line-options.php#trim">-trim</a> remove 7603 edges that are nearly the same color as the corner pixels.</p> 7604 7605 <p>The page or virtual canvas information of the image is preserved allowing 7606 you to extract the result of the <a href="command-line-options.php#trim">-trim</a> operation from the 7607 image. Use a <a href="command-line-options.php#repage">+repage</a> to remove the virtual canvas page 7608 information if it is unwanted.</p> 7609 7610 <p>If the trimmed image 'disappears' an warning is produced, and a special 7611 single pixel transparent 'missed' image is returned, in the same way as when a 7612 <a href="command-line-options.php#crop">-crop</a> operation 'misses' the image proper. </p> 7613 7614 7615 <div style="margin: auto;"> 7616 <h3 class="magick-header"><a id="type"></a>-type <var>type</var></h3> 7617 </div> 7618 7619 <p class="magick-description">the image type.</p> <p>Choose from: <code>Bilevel</code>, 7620 <code>Grayscale</code>, <code>GrayscaleMatte</code>, <code>Palette</code>, 7621 <code>PaletteMatte</code>, <code>TrueColor</code>, <code>TrueColorMatte</code>, 7622 <code>ColorSeparation</code>, or <code>ColorSeparationMatte</code>.</p> 7623 7624 <p>Normally, when a format supports different subformats such as grayscale and 7625 truecolor, the encoder will try to choose an efficient subformat. The <a 7626 href="command-line-options.php#type">-type</a> option can be used to override this behavior. For 7627 example, to prevent a JPEG from being written in grayscale format even though 7628 only gray pixels are present, use.</p> 7629 7630 <pre> 7631 convert bird.png -type TrueColor bird.jpg 7632 </pre> 7633 7634 <p>Similarly, use <a href="command-line-options.php#type">-type TrueColorMatte</a> to force the 7635 encoder to write an alpha channel even though the image is opaque, if the 7636 output format supports transparency.</p> 7637 7638 <p>Use <a href="command-line-options.php#type">-type optimize</a> to ensure the image is written in the smallest possible file size.</p> 7639 7640 <div style="margin: auto;"> 7641 <h3 class="magick-header"><a id="undercolor"></a>-undercolor <var>color</var></h3> 7642 </div> 7643 7644 <p class="magick-description">set the color of the annotation bounding box.</p> 7645 7646 <p>The color is specified using the format described under the <a href="command-line-options.php#fill">-fill</a> option.</p> 7647 7648 <p>See <a href="command-line-options.php#draw">-draw</a> for further details.</p> 7649 7650 7651 <div style="margin: auto;"> 7652 <h3 class="magick-header"><a id="update"></a>-update <var>seconds</var></h3> 7653 </div> 7654 7655 <p class="magick-description">detect when image file is modified and redisplay.</p> 7656 7657 <p>Suppose that while you are displaying an image the file that is currently 7658 displayed is over-written. <code>display</code> will automagically detect that 7659 the input file has been changed and update the displayed image 7660 accordingly.</p> 7661 7662 7663 <div style="margin: auto;"> 7664 <h3 class="magick-header"><a id="unique-colors"></a>-unique-colors</h3> 7665 </div> 7666 7667 <p class="magick-description">discard all but one of any pixel color.</p> 7668 7669 7670 <div style="margin: auto;"> 7671 <h3 class="magick-header"><a id="units"></a>-units <var>type</var></h3> 7672 </div> 7673 7674 <p class="magick-description">the units of image resolution.</p> 7675 7676 <p>Choose from: <code>Undefined</code>, <code>PixelsPerInch</code>, or 7677 <code>PixelsPerCentimeter</code>. This option is normally used in conjunction 7678 with the <a href="command-line-options.php#density">-density</a> option.</p> 7679 7680 7681 <div style="margin: auto;"> 7682 <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> 7683 </div> 7684 7685 <p class="magick-description">sharpen the image with an unsharp mask operator.</p> 7686 7687 <p>The <a href="command-line-options.php#unsharp">-unsharp</a> option sharpens an image. The image is 7688 convolved with a Gaussian operator of the given radius and standard deviation 7689 (sigma). For reasonable results, radius should be larger than sigma. Use 7690 a radius of 0 to have the method select a suitable radius.</p> 7691 7692 <p>The parameters are:</p> 7693 7694 <dl class="dl-horizontal"> 7695 <dt>radius</dt> 7696 <dd>The radius of the Gaussian, in pixels, not counting the center pixel (default 0).</dd> 7697 <dt>sigma</dt> 7698 <dd>The standard deviation of the Gaussian, in pixels (default 1.0).</dd> 7699 <dt>gain</dt> 7700 <dd>The fraction of the difference between the original and the blur image that is added back into the original (default 1.0).</dd> 7701 <dt>threshold</dt> 7702 <dd>The threshold, as a fraction of <var>QuantumRange</var>, needed to apply the difference amount (default 0.05).</dd> 7703 </dl> 7704 7705 <div style="margin: auto;"> 7706 <h3 class="magick-header"><a id="verbose"></a>-verbose</h3> 7707 </div> 7708 7709 <p class="magick-description">print detailed information about the image when this option precedes the <a href="command-line-options.php#identify">-identify</a> option or <code>info:</code>.</p> 7710 7711 7712 <div style="margin: auto;"> 7713 <h3 class="magick-header"><a id="version"></a>-version</h3> 7714 </div> 7715 7716 <p class="magick-description">print ImageMagick version string and exit.</p> 7717 7718 7719 <div style="margin: auto;"> 7720 <h3 class="magick-header"><a id="view"></a>-view <var>string</var></h3> 7721 </div> 7722 7723 <p class="magick-description">FlashPix viewing parameters.</p> 7724 7725 7726 <div style="margin: auto;"> 7727 <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> 7728 </div> 7729 7730 <p class="magick-description">soften the edges of the image in vignette style.</p> 7731 7732 <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> 7733 7734 <div style="margin: auto;"> 7735 <h3 class="magick-header"><a id="virtual-pixel"></a>-virtual-pixel <var>method</var></h3> 7736 </div> 7737 7738 <p class="magick-description">Specify contents of <var>virtual pixels</var>.</p> 7739 7740 <p>This option defines what color source should be used if and when a color 7741 lookup completely 'misses' the source image. The color(s) that appear to 7742 surround the source image. Generally this color is derived from the source 7743 image, but could also be set to a specify background color. </p> 7744 7745 <p>Choose from these methods:</p> 7746 7747 <dl class="dl-horizontal"> 7748 <dt>background</dt><dd>the area surrounding the image is the background color</dd> 7749 <dt>black</dt><dd>the area surrounding the image is black</dd> 7750 <dt>checker-tile</dt><dd>alternate squares with image and background color</dd> 7751 <dt>dither</dt><dd>non-random 32x32 dithered pattern</dd> 7752 <dt>edge</dt><dd>extend the edge pixel toward infinity</dd> 7753 <dt>gray</dt><dd>the area surrounding the image is gray</dd> 7754 <dt>horizontal-tile</dt><dd>horizontally tile the image, background color above/below</dd> 7755 <dt>horizontal-tile-edge</dt><dd>horizontally tile the image and replicate the side edge pixels</dd> 7756 <dt>mirror</dt><dd>mirror tile the image</dd> 7757 <dt>random</dt><dd>choose a random pixel from the image</dd> 7758 <dt>tile</dt><dd>tile the image (default)</dd> 7759 <dt>transparent</dt><dd>the area surrounding the image is transparent blackness</dd> 7760 <dt>vertical-tile</dt><dd>vertically tile the image, sides are background color</dd> 7761 <dt>vertical-tile-edge</dt><dd>vertically tile the image and replicate the side edge pixels</dd> 7762 <dt>white</dt><dd>the area surrounding the image is white</dd> 7763 </dl> 7764 7765 <p>The default value is "edge".</p> 7766 7767 <p>This most important for distortion operators such as <a href="command-line-options.php#distort" 7768 >-distort</a>, <a href="command-line-options.php#implode" >-implode</a>, and <a href="command-line-options.php#fx" >-fx</a>. 7769 However it also effects operations that may access pixels just outside the 7770 image proper, such as <a href="command-line-options.php#convolve">-convolve</a>, <a 7771 href="command-line-options.php#blur">-blur</a>, and <a href="command-line-options.php#sharpen">-sharpen</a>. </p> 7772 7773 <p>To print a complete list of virtual pixel types, use the <a 7774 href="command-line-options.php#list">-list virtual-pixel</a> option.</p> 7775 7776 7777 <div style="margin: auto;"> 7778 <h3 class="magick-header"><a id="visual"></a>-visual <var>type</var></h3> 7779 </div> 7780 7781 <p class="magick-description">Animate images using this X visual type.", 'animate', 'display'</p> 7782 7783 <p>Choose from these visual classes:</p> 7784 7785 <pre> 7786 StaticGray TrueColor 7787 GrayScale DirectColor 7788 StaticColor default 7789 PseudoColor visual id 7790 </pre> 7791 7792 <p>The X server must support the visual you choose, otherwise an error occurs. 7793 If a visual is not specified, the visual class that can display the most 7794 simultaneous colors on the default screen is chosen.</p> 7795 7796 7797 <div style="margin: auto;"> 7798 <h3 class="magick-header"><a id="watermark"></a>-watermark <var>brightness</var>x<var>saturation</var></h3> 7799 </div> 7800 7801 <p class="magick-description">Watermark an image using the given percentages of brightness and saturation.</p> 7802 7803 <p>Take a grayscale image (with alpha mask) and modify the destination image's 7804 brightness according to watermark image's grayscale value and the 7805 <var>brightness</var> percentage. The destinations color saturation 7806 attribute is just direct modified by the <var>saturation</var> 7807 percentage, which defaults to 100 percent (no color change). </p> 7808 7809 7810 <div style="margin: auto;"> 7811 <h3 class="magick-header"><a id="wave"></a>-wave <var>amplitude</var><br />-wave <var>amplitude</var>x<var>wavelength</var></h3> 7812 </div> 7813 7814 <p class="magick-description">Shear the columns of an image into a sine wave.</p> 7815 7816 <p>Specify <var>amplitude</var> and <var>wavelength</var> 7817 of the wave.</p> 7818 7819 <div style="margin: auto;"> 7820 <h3 class="magick-header"><a id="weight"></a>-weight <var>fontWeight</var></h3> 7821 </div> 7822 7823 <p class="magick-description">Set a font weight for text.</p> 7824 7825 <p>This setting suggests a font weight that ImageMagick should try to apply to 7826 the currently selected font family. Use a positive integer for 7827 <var>fontWeight</var> or select from the following.</p> 7828 7829 <dl class="dl-horizontal"> 7830 <dt>Thin </dt> 7831 <dd>Same as <var>fontWeight</var> = 100.</dd> 7832 <dt>ExtraLight </dt> 7833 <dd>Same as <var>fontWeight</var> = 200.</dd> 7834 <dt>Light </dt> 7835 <dd>Same as <var>fontWeight</var> = 300.</dd> 7836 <dt>Normal </dt> 7837 <dd>Same as <var>fontWeight</var> = 400.</dd> 7838 <dt>Medium </dt> 7839 <dd>Same as <var>fontWeight</var> = 500.</dd> 7840 <dt>DemiBold </dt> 7841 <dd>Same as <var>fontWeight</var> = 600.</dd> 7842 <dt>Bold </dt> 7843 <dd>Same as <var>fontWeight</var> = 700.</dd> 7844 <dt>ExtraBold </dt> 7845 <dd>Same as <var>fontWeight</var> = 800.</dd> 7846 <dt>Heavy </dt> 7847 <dd>Same as <var>fontWeight</var> = 900.</dd> 7848 </dl> 7849 <br/> 7850 7851 <p>To print a complete list of weight types, use <a href="command-line-options.php#list">-list weight</a>.</p> 7852 7853 <p>For other settings that affect fonts, see the options <a 7854 href="command-line-options.php#font">-font</a>, <a href="command-line-options.php#family">-family</a>, <a 7855 href="command-line-options.php#stretch">-stretch</a>, and <a href="command-line-options.php#style">-style</a>. </p> 7856 7857 <div style="margin: auto;"> 7858 <h3 class="magick-header"><a id="white-point"></a>-white-point <var>x,y</var></h3> 7859 </div> 7860 7861 <p class="magick-description">chromaticity white point.</p> 7862 7863 <div style="margin: auto;"> 7864 <h3 class="magick-header"><a id="white-threshold"></a>-white-threshold <var>value</var>{<var>%</var>}</h3> 7865 </div> 7866 7867 <p class="magick-description">Force to white all pixels above the threshold while leaving all pixels at or below the threshold unchanged.</p> 7868 7869 <p> The threshold value can be given as a percentage or as an absolute integer 7870 value within [0, <var>QuantumRange</var>] corresponding to the 7871 desired <a href="command-line-options.php#channel">‑channel</a> value. See <a href="command-line-options.php#threshold">‑threshold</a>for more details on thresholds and resulting values. </p> 7872 7873 <div style="margin: auto;"> 7874 <h3 class="magick-header"><a id="window"></a>-window <var>id</var></h3> 7875 </div> 7876 7877 <p class="magick-description">Make the image the background of a window.", 'animate', 'display'</p> 7878 7879 <p><var>id</var> can be a window id or name. Specify <code>root</code> 7880 to select X's root window as the target window.</p> 7881 7882 <p>By default the image is tiled onto the background of the target window. If 7883 <code>backdrop</code> or <a href="command-line-options.php#geometry">-resize</a> are specified, the 7884 image is surrounded by the background color. Refer to <code>X RESOURCES</code> 7885 for details.</p> 7886 7887 <p>The image will not display on the root window if the image has more unique 7888 colors than the target window colormap allows. Use <a 7889 href="command-line-options.php#colors">-colors</a> to reduce the number of colors.</p> 7890 7891 <div style="margin: auto;"> 7892 <h3 class="magick-header"><a id="window-group"></a>-window-group</h3> 7893 </div> 7894 7895 <p class="magick-description">specify the window group.</p> 7896 7897 <div style="margin: auto;"> 7898 <h3 class="magick-header"><a id="write"></a>-write <var>filename</var></h3> 7899 </div> 7900 7901 <p class="magick-description">write an image sequence.</p> 7902 7903 <p>The image sequence preceding the <a href="command-line-options.php#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.php#write">+write</a> <var>filename</var> option.</p> 7904 7905 <p>Use <a href="command-line-options.php#compress">-compress</a> to specify the type of image compression.</p> 7906 </div> 7907 </div> 7908 7909 7910 7911 <footer class="magick-footer"> 7912 <p><a href="support.php">Donate</a> 7913 <a href="sitemap.php">Sitemap</a> 7914 <a href="links.php">Related</a> 7915 <a href="architecture.php">Architecture</a> 7916 </p> 7917 <p><a href="command-line-options.php#">Back to top</a> 7918 <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x89AB63D48277377A">Public Key</a> 7919 <a href="contact.php">Contact Us</a></p> 7920 <p><small> 1999-2016 ImageMagick Studio LLC</small></p> 7921 </footer> 7922 </div><!-- /.container --> 7923 7924 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> 7925 <script src="http://nextgen.imagemagick.org/js/magick.php"></script> 7926 </div> 7927 </body> 7928 </html> 7929
