1 2 3 4 5 <!DOCTYPE html> 6 <html lang="en"> 7 <head> 8 <meta charset="utf-8" /> 9 <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1,shrink-to-fit=no" /> 10 <title>Command-line Options @ ImageMagick</title> 11 <meta name="application-name" content="ImageMagick" /> 12 <meta name="description" content="Use ImageMagick to create, edit, compose, or convert bitmap images. You can resize your image, crop it, change its shades and colors, add captions, among other operations." /> 13 <meta name="application-url" content="https://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-2019 ImageMagick Studio LLC" /> 23 <meta name="distribution" content="Global" /> 24 <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1" /> 25 <meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" /> 26 <link href="../www/command-line-options.html" rel="canonical" /> 27 <link href="../images/wand.png" rel="icon" /> 28 <link href="../images/wand.ico" rel="shortcut icon" /> 29 <link href="assets/magick.css" rel="stylesheet" /> 30 </head> 31 <body> 32 <header> 33 <nav class="navbar navbar-expand-md navbar-dark fixed-top bg-dark"> 34 <a class="navbar-brand" href="../index.html"><img class="d-block" id="icon" alt="ImageMagick" width="32" height="32" src="../images/wand.ico"/></a> 35 <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarsMagick" aria-controls="navbarsMagick" aria-expanded="false" aria-label="Toggle navigation"> 36 <span class="navbar-toggler-icon"></span> 37 </button> 38 39 <div class="navbar-collapse collapse" id="navbarsMagick" style=""> 40 <ul class="navbar-nav mr-auto"> 41 <li class="nav-item "> 42 <a class="nav-link" href="../index.html">Home <span class="sr-only">(current)</span></a> 43 </li> 44 <li class="nav-item "> 45 <a class="nav-link" href="download.html">Download</a> 46 </li> 47 <li class="nav-item "> 48 <a class="nav-link" href="command-line-tools.html">Tools</a> 49 </li> 50 <li class="nav-item "> 51 <a class="nav-link" href="command-line-processing.html">Command-line</a> 52 </li> 53 <li class="nav-item "> 54 <a class="nav-link" href="resources.html">Resources</a> 55 </li> 56 <li class="nav-item "> 57 <a class="nav-link" href="develop.html">Develop</a> 58 </li> 59 <li class="nav-item"> 60 <a class="nav-link" target="_blank" href="https://imagemagick.org/discourse-server/">Community</a> 61 </li> 62 </ul> 63 <form class="form-inline my-2 my-lg-0" action="https://imagemagick.org/script/search.php"> 64 <input class="form-control mr-sm-2" type="text" name="q" placeholder="Search" aria-label="Search"> 65 <button class="btn btn-outline-success my-2 my-sm-0" type="submit" name="sa">Search</button> 66 </form> 67 </div> 68 </nav> 69 <div class="container"> 70 <script async="async" src="http://localhost/pagead/js/adsbygoogle.js"></script> <ins class="adsbygoogle" 71 style="display:block" 72 data-ad-client="ca-pub-3129977114552745" 73 data-ad-slot="6345125851" 74 data-ad-format="auto"></ins> 75 <script> 76 (adsbygoogle = window.adsbygoogle || []).push({}); 77 </script> 78 79 </div> 80 </header> 81 <main class="container"> 82 <div class="magick-template"> 83 <div class="magick-header"> 84 <p class="text-center"><a href="command-line-options.html#adaptive-blur">‑adaptive‑blur</a> <a href="command-line-options.html#adaptive-resize">‑adaptive‑resize</a> <a href="command-line-options.html#adaptive-sharpen">‑adaptive‑sharpen</a> <a href="command-line-options.html#adjoin">‑adjoin</a> <a href="command-line-options.html#affine">‑affine</a> <a href="command-line-options.html#alpha">‑alpha</a> <a href="command-line-options.html#annotate">‑annotate</a> <a href="command-line-options.html#antialias">‑antialias</a> <a href="command-line-options.html#append">‑append</a> <a href="command-line-options.html#attenuate">‑attenuate</a> <a href="command-line-options.html#authenticate">‑authenticate</a> <a href="command-line-options.html#auto-gamma">‑auto‑gamma</a> <a href="command-line-options.html#auto-level">‑auto‑level</a> <a href="command-line-options.html#auto-orient">‑auto‑orient</a> <a href="command-line-options.html#auto-threshold">‑auto‑threshold</a> <a href="command-line-options.html#backdrop">‑backdrop</a> <a href="command-line-options.html#background">‑background</a> <a href="command-line-options.html#bench">‑bench</a> <a href="command-line-options.html#bias">‑bias</a> <a href="command-line-options.html#black-point-compensation">‑black‑point‑compensation</a> <a href="command-line-options.html#black-threshold">‑black‑threshold</a> <a href="command-line-options.html#blend">‑blend</a> <a href="command-line-options.html#blue-primary">‑blue‑primary</a> <a href="command-line-options.html#blue-shift">‑blue‑shift</a> <a href="command-line-options.html#blur">‑blur</a> <a href="command-line-options.html#border">‑border</a> <a href="command-line-options.html#bordercolor">‑bordercolor</a> <a href="command-line-options.html#borderwidth">‑borderwidth</a> <a href="command-line-options.html#brightness-contrast">‑brightness‑contrast</a> <a href="command-line-options.html#cache">‑cache</a> <a href="command-line-options.html#canny">‑canny</a> <a href="command-line-options.html#caption">‑caption</a> <a href="command-line-options.html#cdl">‑cdl</a> <a href="command-line-options.html#channel">‑channel</a> <a href="command-line-options.html#charcoal">‑charcoal</a> <a href="command-line-options.html#channel-fx">‑channel‑fx</a> <a href="command-line-options.html#chop">‑chop</a> <a href="command-line-options.html#clahe">‑clahe</a> <a href="command-line-options.html#clamp">‑clamp</a> <a href="command-line-options.html#clip">‑clip</a> <a href="command-line-options.html#clip-mask">‑clip‑mask</a> <a href="command-line-options.html#clip-path">‑clip‑path</a> <a href="command-line-options.html#clone">‑clone</a> <a href="command-line-options.html#clut">‑clut</a> <a href="command-line-options.html#coalesce">‑coalesce</a> <a href="command-line-options.html#colorize">‑colorize</a> <a href="command-line-options.html#colormap">‑colormap</a> <a href="command-line-options.html#color-matrix">‑color‑matrix</a> <a href="command-line-options.html#colors">‑colors</a> <a href="command-line-options.html#colorspace">‑colorspace</a> <a href="command-line-options.html#combine">‑combine</a> <a href="command-line-options.html#comment">‑comment</a> <a href="command-line-options.html#compare">‑compare</a> <a href="command-line-options.html#complex">‑complex</a> <a href="command-line-options.html#compose">‑compose</a> <a href="command-line-options.html#composite">‑composite</a> <a href="command-line-options.html#compress">‑compress</a> <a href="command-line-options.html#connected-components">‑connected‑components</a> <a href="command-line-options.html#contrast">‑contrast</a> <a href="command-line-options.html#contrast-stretch">‑contrast‑stretch</a> <a href="command-line-options.html#convolve">‑convolve</a> <a href="command-line-options.html#copy">‑copy</a> <a href="command-line-options.html#crop">‑crop</a> <a href="command-line-options.html#cycle">‑cycle</a> <a href="command-line-options.html#debug">‑debug</a> <a href="command-line-options.html#decipher">‑decipher</a> <a href="command-line-options.html#deconstruct">‑deconstruct</a> <a href="command-line-options.html#define">‑define</a> <a href="command-line-options.html#delay">‑delay</a> <a href="command-line-options.html#delete">‑delete</a> <a href="command-line-options.html#density">‑density</a> <a href="command-line-options.html#depth">‑depth</a> <a href="command-line-options.html#descend">‑descend</a> <a href="command-line-options.html#deskew">‑deskew</a> <a href="command-line-options.html#despeckle">‑despeckle</a> <a href="command-line-options.html#direction">‑direction</a> <a href="command-line-options.html#displace">‑displace</a> <a href="command-line-options.html#display">‑display</a> <a href="command-line-options.html#dispose">‑dispose</a> <a href="command-line-options.html#dissimilarity-threshold">‑dissimilarity‑threshold</a> <a href="command-line-options.html#dissolve">‑dissolve</a> <a href="command-line-options.html#distort">‑distort</a> <a href="command-line-options.html#distribute-cache">‑distribute‑cache</a> <a href="command-line-options.html#dither">‑dither</a> <a href="command-line-options.html#draw">‑draw</a> <a href="command-line-options.html#duplicate">‑duplicate</a> <a href="command-line-options.html#edge">‑edge</a> <a href="command-line-options.html#emboss">‑emboss</a> <a href="command-line-options.html#encipher">‑encipher</a> <a href="command-line-options.html#encoding">‑encoding</a> <a href="command-line-options.html#endian">‑endian</a> <a href="command-line-options.html#enhance">‑enhance</a> <a href="command-line-options.html#equalize">‑equalize</a> <a href="command-line-options.html#evaluate">‑evaluate</a> <a href="command-line-options.html#evaluate-sequence">‑evaluate‑sequence</a> <a href="command-line-options.html#extent">‑extent</a> <a href="command-line-options.html#extract">‑extract</a> <a href="command-line-options.html#family">‑family</a> <a href="command-line-options.html#features">‑features</a> <a href="command-line-options.html#fft">‑fft</a> <a href="command-line-options.html#fill">‑fill</a> <a href="command-line-options.html#filter">‑filter</a> <a href="command-line-options.html#flatten">‑flatten</a> <a href="command-line-options.html#flip">‑flip</a> <a href="command-line-options.html#floodfill">‑floodfill</a> <a href="command-line-options.html#flop">‑flop</a> <a href="command-line-options.html#font">‑font</a> <a href="command-line-options.html#foreground">‑foreground</a> <a href="command-line-options.html#format">‑format</a> <a href="command-line-options.html#format_identify_">‑format[identify]</a> <a href="command-line-options.html#frame">‑frame</a> <a href="command-line-options.html#frame_import_">‑frame[import]</a> <a href="command-line-options.html#function">‑function</a> <a href="command-line-options.html#fuzz">‑fuzz</a> <a href="command-line-options.html#fx">‑fx</a> <a href="command-line-options.html#gamma">‑gamma</a> <a href="command-line-options.html#gaussian-blur">‑gaussian‑blur</a> <a href="command-line-options.html#geometry">‑geometry</a> <a href="command-line-options.html#gravity">‑gravity</a> <a href="command-line-options.html#grayscale">‑grayscale</a> <a href="command-line-options.html#green-primary">‑green‑primary</a> <a href="command-line-options.html#hald-clut">‑hald‑clut</a> <a href="command-line-options.html#help">‑help</a> <a href="command-line-options.html#highlight-color">‑highlight‑color</a> <a href="command-line-options.html#hough-lines">‑hough‑lines</a> <a href="command-line-options.html#iconGeometry">‑iconGeometry</a> <a href="command-line-options.html#iconic">‑iconic</a> <a href="command-line-options.html#identify">‑identify</a> <a href="command-line-options.html#ift">‑ift</a> <a href="command-line-options.html#immutable">‑immutable</a> <a href="command-line-options.html#implode">‑implode</a> <a href="command-line-options.html#insert">‑insert</a> <a href="command-line-options.html#intensity">‑intensity</a> <a href="command-line-options.html#intent">‑intent</a> <a href="command-line-options.html#interlace">‑interlace</a> <a href="command-line-options.html#interpolate">‑interpolate</a> <a href="command-line-options.html#interline-spacing">‑interline‑spacing</a> <a href="command-line-options.html#interword-spacing">‑interword‑spacing</a> <a href="command-line-options.html#kerning">‑kerning</a> <a href="command-line-options.html#kuwahara">‑kuwahara</a> <a href="command-line-options.html#label">‑label</a> <a href="command-line-options.html#lat">‑lat</a> <a href="command-line-options.html#layers">‑layers</a> <a href="command-line-options.html#level">‑level</a> <a href="command-line-options.html#level-colors">‑level‑colors</a> <a href="command-line-options.html#limit">‑limit</a> <a href="command-line-options.html#linear-stretch">‑linear‑stretch</a> <a href="command-line-options.html#linewidth">‑linewidth</a> <a href="command-line-options.html#liquid-rescale">‑liquid‑rescale</a> <a href="command-line-options.html#list">‑list</a> <a href="command-line-options.html#log">‑log</a> <a href="command-line-options.html#loop">‑loop</a> <a href="command-line-options.html#lowlight-color">‑lowlight‑color</a> <a href="command-line-options.html#magnify">‑magnify</a> <a href="command-line-options.html#map">‑map</a> <a href="command-line-options.html#map_stream_">‑map[stream]</a> <a href="command-line-options.html#mattecolor">‑mattecolor</a> <a href="command-line-options.html#median">‑median</a> <a href="command-line-options.html#mean-shift">‑mean‑shift</a> <a href="command-line-options.html#metric">‑metric</a> <a href="command-line-options.html#mode">‑mode</a> <a href="command-line-options.html#modulate">‑modulate</a> <a href="command-line-options.html#moments">‑moments</a> <a href="command-line-options.html#monitor">‑monitor</a> <a href="command-line-options.html#monochrome">‑monochrome</a> <a href="command-line-options.html#morph">‑morph</a> <a href="command-line-options.html#morphology">‑morphology</a> <a href="command-line-options.html#mosaic">‑mosaic</a> <a href="command-line-options.html#motion-blur">‑motion‑blur</a> <a href="command-line-options.html#name">‑name</a> <a href="command-line-options.html#negate">‑negate</a> <a href="command-line-options.html#noise">‑noise</a> <a href="command-line-options.html#normalize">‑normalize</a> <a href="command-line-options.html#opaque">‑opaque</a> <a href="command-line-options.html#ordered-dither">‑ordered‑dither</a> <a href="command-line-options.html#orient">‑orient</a> <a href="command-line-options.html#page">‑page</a> <a href="command-line-options.html#paint">‑paint</a> <a href="command-line-options.html#path">‑path</a> <a href="command-line-options.html#pause_animate_">‑pause[animate]</a> <a href="command-line-options.html#pause_import_">‑pause[import]</a> <a href="command-line-options.html#perceptible">‑perceptible</a> <a href="command-line-options.html#ping">‑ping</a> <a href="command-line-options.html#pointsize">‑pointsize</a> <a href="command-line-options.html#polaroid">‑polaroid</a> <a href="command-line-options.html#poly">‑poly</a> <a href="command-line-options.html#posterize">‑posterize</a> <a href="command-line-options.html#precision">‑precision</a> <a href="command-line-options.html#preview">‑preview</a> <a href="command-line-options.html#print">‑print</a> <a href="command-line-options.html#process">‑process</a> <a href="command-line-options.html#profile">‑profile</a> <a href="command-line-options.html#quality">‑quality</a> <a href="command-line-options.html#quantize">‑quantize</a> <a href="command-line-options.html#quiet">‑quiet</a> <a href="command-line-options.html#radial-blur">‑radial‑blur</a> <a href="command-line-options.html#raise">‑raise</a> <a href="command-line-options.html#random-threshold">‑random‑threshold</a> <a href="command-line-options.html#range-threshold">‑range‑threshold</a> <a href="command-line-options.html#read-mask">‑read‑mask</a> <a href="command-line-options.html#red-primary">‑red‑primary</a> <a href="command-line-options.html#regard-warnings">‑regard‑warnings</a> <a href="command-line-options.html#region">‑region</a> <a href="command-line-options.html#remap">‑remap</a> <a href="command-line-options.html#remote">‑remote</a> <a href="command-line-options.html#render">‑render</a> <a href="command-line-options.html#repage">‑repage</a> <a href="command-line-options.html#resample">‑resample</a> <a href="command-line-options.html#resize">‑resize</a> <a href="command-line-options.html#respect-parentheses">‑respect‑parentheses</a> <a href="command-line-options.html#reverse">‑reverse</a> <a href="command-line-options.html#roll">‑roll</a> <a href="command-line-options.html#rotate">‑rotate</a> <a href="command-line-options.html#sample">‑sample</a> <a href="command-line-options.html#sampling-factor">‑sampling‑factor</a> <a href="command-line-options.html#scale">‑scale</a> <a href="command-line-options.html#scene">‑scene</a> <a href="command-line-options.html#screen">‑screen</a> <a href="command-line-options.html#seed">‑seed</a> <a href="command-line-options.html#segment">‑segment</a> <a href="command-line-options.html#selective-blur">‑selective‑blur</a> <a href="command-line-options.html#separate">‑separate</a> <a href="command-line-options.html#sepia-tone">‑sepia‑tone</a> <a href="command-line-options.html#set">‑set</a> <a href="command-line-options.html#shade">‑shade</a> <a href="command-line-options.html#shadow">‑shadow</a> <a href="command-line-options.html#shared-memory">‑shared‑memory</a> <a href="command-line-options.html#sharpen">‑sharpen</a> <a href="command-line-options.html#shave">‑shave</a> <a href="command-line-options.html#shear">‑shear</a> <a href="command-line-options.html#sigmoidal-contrast">‑sigmoidal‑contrast</a> <a href="command-line-options.html#silent">‑silent</a> <a href="command-line-options.html#similarity-threshold">‑similarity‑threshold</a> <a href="command-line-options.html#size">‑size</a> <a href="command-line-options.html#sketch">‑sketch</a> <a href="command-line-options.html#smush">‑smush</a> <a href="command-line-options.html#snaps">‑snaps</a> <a href="command-line-options.html#solarize">‑solarize</a> <a href="command-line-options.html#sparse-color">‑sparse‑color</a> <a href="command-line-options.html#splice">‑splice</a> <a href="command-line-options.html#spread">‑spread</a> <a href="command-line-options.html#statistic">‑statistic</a> <a href="command-line-options.html#stegano">‑stegano</a> <a href="command-line-options.html#stereo">‑stereo</a> <a href="command-line-options.html#storage-type">‑storage‑type</a> <a href="command-line-options.html#stretch">‑stretch</a> <a href="command-line-options.html#strip">‑strip</a> <a href="command-line-options.html#stroke">‑stroke</a> <a href="command-line-options.html#strokewidth">‑strokewidth</a> <a href="command-line-options.html#style">‑style</a> <a href="command-line-options.html#subimage-search">‑subimage‑search</a> <a href="command-line-options.html#swap">‑swap</a> <a href="command-line-options.html#swirl">‑swirl</a> <a href="command-line-options.html#synchronize">‑synchronize</a> <a href="command-line-options.html#taint">‑taint</a> <a href="command-line-options.html#text-font">‑text‑font</a> <a href="command-line-options.html#texture">‑texture</a> <a href="command-line-options.html#threshold">‑threshold</a> <a href="command-line-options.html#thumbnail">‑thumbnail</a> <a href="command-line-options.html#tile">‑tile</a> <a href="command-line-options.html#tile-offset">‑tile‑offset</a> <a href="command-line-options.html#tint">‑tint</a> <a href="command-line-options.html#title">‑title</a> <a href="command-line-options.html#transform">‑transform</a> <a href="command-line-options.html#transparent">‑transparent</a> <a href="command-line-options.html#transparent-color">‑transparent‑color</a> <a href="command-line-options.html#transpose">‑transpose</a> <a href="command-line-options.html#transverse">‑transverse</a> <a href="command-line-options.html#treedepth">‑treedepth</a> <a href="command-line-options.html#trim">‑trim</a> <a href="command-line-options.html#type">‑type</a> <a href="command-line-options.html#undercolor">‑undercolor</a> <a href="command-line-options.html#unique-colors">‑unique‑colors</a> <a href="command-line-options.html#units">‑units</a> <a href="command-line-options.html#unsharp">‑unsharp</a> <a href="command-line-options.html#update">‑update</a> <a href="command-line-options.html#verbose">‑verbose</a> <a href="command-line-options.html#version">‑version</a> <a href="command-line-options.html#view">‑view</a> <a href="command-line-options.html#vignette">‑vignette</a> <a href="command-line-options.html#virtual-pixel">‑virtual‑pixel</a> <a href="command-line-options.html#visual">‑visual</a> <a href="command-line-options.html#watermark">‑watermark</a> <a href="command-line-options.html#wave">‑wave</a> <a href="command-line-options.html#wavelet-denoise">‑wavelet‑denoise</a> <a href="command-line-options.html#weight">‑weight</a> <a href="command-line-options.html#white-point">‑white‑point</a> <a href="command-line-options.html#white-threshold">‑white‑threshold</a> <a href="command-line-options.html#window">‑window</a> <a href="command-line-options.html#window-group">‑window‑group</a> <a href="command-line-options.html#write">‑write</a> <a href="command-line-options.html#write-mask">‑write‑mask</a> </p> 85 <p class="lead magick-description">Below is list of command-line options recognized by the ImageMagick <a href="command-line-tools.html">command-line tools</a>. If you want a description of a particular option, click on the option name in the navigation bar above and you will go right to it. Unless otherwise noted, each option is recognized by the commands: <a href="convert.html">convert</a> and <a href="mogrify.html">mogrify</a>.</p> 86 87 <div style="margin: auto;"> 88 <h3><a class="anchor" id="adaptive-blur"></a>-adaptive-blur <var>radius</var>[x<var>sigma</var>]</h3> 89 </div> 90 91 <p class="magick-description">Adaptively blur pixels, with decreasing effect near edges.</p> 92 93 <p>A Gaussian operator of the given radius and standard deviation (<var>sigma</var>) is used. If <var>sigma</var> is not given it 94 defaults to 1.</p> 95 96 <div style="margin: auto;"> 97 <h3><a class="anchor" id="adaptive-resize"></a>-adaptive-resize <var>geometry</var></h3> 98 </div> 99 100 <p class="magick-description">Resize the image using data-dependent triangulation.</p> 101 102 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <a href="command-line-options.html#adaptive-resize">-adaptive-resize</a> 103 option defaults to data-dependent triangulation. Use the <a 104 href="command-line-options.html#filter">-filter</a> to choose a different resampling algorithm. 105 Offsets, if present in the geometry string, are ignored, and the <a 106 href="command-line-options.html#gravity">-gravity</a> option has no effect.</p> 107 108 <div style="margin: auto;"> 109 <h3><a class="anchor" id="adaptive-sharpen"></a>-adaptive-sharpen <var>radius</var>[x<var>sigma</var>]</h3> 110 </div> 111 112 <p class="magick-description">Adaptively sharpen pixels, with increasing effect near edges.</p> 113 114 <p>A Gaussian operator of the given radius and standard deviation 115 (<var>sigma</var>) is used. If <var>sigma</var> is not given it 116 defaults to 1.</p> 117 118 <div style="margin: auto;"> 119 <h3><a class="anchor" id="adjoin"></a>-adjoin</h3> 120 </div> 121 122 <p class="magick-description">Join images into a single multi-image file.</p> 123 124 <p>This option is enabled by default. An attempt is made to save all images of 125 an image sequence into the given output file. However, some formats, such as 126 JPEG and PNG, do not support more than one image per file, and in that case 127 ImageMagick is forced to write each image as a separate file. As such, if 128 more than one image needs to be written, the filename given is modified by 129 adding a <a href="command-line-options.html#scene">-scene</a> number before the suffix, in order to 130 make distinct names for each image. </p> 131 132 <p>Use <a href="command-line-options.html#adjoin">+adjoin</a> to force each image to be written to 133 separate files, whether or not the file format allows multiple images per file 134 (for example, GIF, MIFF, and TIFF). </p> 135 136 <p>Including a C-style integer format string in the output filename will 137 automagically enable <a href="command-line-options.html#adjoin">+adjoin</a> and are used to specify 138 where the <a href="command-line-options.html#scene">-scene</a> number is placed in the filenames. These 139 strings, such as '<code>%d</code>' or '<code>%03d</code>', are familiar to those 140 who have used the standard <code>printf()</code>' C-library function. As an 141 example, the command</p> 142 143 <pre class="highlight"><code>convert logo: rose: -morph 15 my%02dmorph.jpg 144 </code></pre> 145 146 <p>will create a sequence of 17 images (the two given plus 15 more created by 147 <a href="command-line-options.html#morph">-morph</a>), named: my00morph.jpg, my01morph.jpg, 148 my02morph.jpg, ..., my16morph.jpg. </p> 149 150 <p>In summary, ImageMagick tries to write all images to one file, but will 151 save to multiple files, if any of the following conditions exist...</p> 152 <ol> 153 <li>the output image's file format does not allow multi-image files,</li> 154 <li>the <a href="command-line-options.html#adjoin">+adjoin</a> option is given, or</li> 155 <li>a printf() integer format string (eg: "%d") is present in the output 156 filename.</li> 157 </ol> 158 159 160 <div style="margin: auto;"> 161 <h3><a class="anchor" id="affine"></a>-affine 162 <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> 163 </div> 164 165 <p class="magick-description">Set the drawing transformation matrix for combined rotating and scaling.</p> 166 167 <p>This option sets a transformation matrix, for use by subsequent <a 168 href="command-line-options.html#draw">-draw</a> or <a href="command-line-options.html#transform">-transform</a> options. </p> 169 170 <p>The matrix entries are entered as comma-separated numeric values either in 171 quotes or without spaces. </p> 172 173 <p>Internally, the transformation matrix has 3x3 elements, but three of them 174 are omitted from the input because they are constant. The new (transformed) 175 coordinates (<var>x'</var>, <var>y'</var>) of a pixel at 176 position (<var>x</var>, <var>y</var>) in the original 177 image are calculated using the following matrix equation.</p> 178 179 <p class="text-center"><img class="img-thumbnail" alt="affine transformation" src="../images/affine.png"/> </p> 180 181 <p> The size of the resulting image is that of the smallest rectangle that 182 contains the transformed source image. The parameters 183 <var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> 184 subsequently shift the image pixels so that those that are moved out of the 185 image area are cut off.</p> 186 187 <p>The transformation matrix complies with the left-handed pixel coordinate 188 system: positive <var>x</var> and <var>y</var> directions 189 are rightward and downward, resp.; positive rotation is clockwise.</p> 190 191 <p> If the translation coefficients <var>t<sub>x</sub></var> and 192 <var>t<sub>y</sub></var> are omitted they default to 0,0. Therefore, 193 four parameters suffice for rotation and scaling without translation.</p> 194 195 <p>Scaling by the factors <var>s<sub>x</sub></var> and 196 <var>s<sub>y</sub></var> in the <var>x</var> and <var>y</var> directions, 197 respectively, is accomplished with the following.</p> 198 199 <p>See <a href="command-line-options.html#transform">-transform</a>, and the <a 200 href="command-line-options.html#distort">-distort</a> method '<code>Affineprojection</code> for more 201 information </p> 202 203 204 <pre class="highlight"><code>-affine <var>s<sub>x</sub></var>,0,0,<var>s<sub>y</sub></var> 205 </code></pre> 206 207 <p>Translation by a displacement (<var>t<sub>x</sub></var>, <var>t<sub>y</sub></var>) is accomplished like so:</p> 208 209 <pre class="highlight"><code>-affine 1,0,0,1,<var>t<sub>x</sub></var>,<var>t<sub>y</sub></var> 210 </code></pre> 211 212 <p>Rotate clockwise about the origin (the upper left-hand corner) by an angle 213 <var>a</var> by letting <var>c</var> = cos(<var>a</var>), <var>s</var> 214 = sin(<var>a</var>), and using the following.</p> 215 216 <pre class="highlight"><code>-affine <var>c</var>,<var>s</var>,-<var>s</var>,<var>c</var> 217 </code></pre> 218 219 <p>The cumulative effect of a sequence of <a href="command-line-options.html#affine" >-affine</a> 220 transformations can be accomplished by instead by a single <a href="command-line-options.html#affine" 221 >-affine</a> operation using the matrix equal to the product of the matrices 222 of the individual transformations.</p> 223 224 <p>An attempt is made to detect near-singular transformation matrices. If the 225 matrix determinant has a sufficiently small absolute value it is rejected.</p> 226 227 <div style="margin: auto;"> 228 <h3><a class="anchor" id="alpha"></a>-alpha <var>type</var></h3> 229 </div> 230 231 <p class="magick-description">Gives control of the alpha/matte channel of an image.</p> 232 233 <p>Used to set a flag on an image indicating whether or not to use existing alpha 234 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> 235 236 <dl class="row"> 237 <dt class="col-md-4">Activate</dt> 238 <dd class="col-md-8"> 239 Enable the image's transparency channel. Note normally Set 240 should be used instead of this, unless you specifically need to 241 preserve existing (but specifically turned Off) transparency 242 channel. </dd> 243 244 <dt class="col-md-4">Associate</dt> 245 <dd class="col-md-8"> 246 associate the alpha channel with the image.</dd> 247 248 <dt class="col-md-4">Deactivate</dt> 249 <dd class="col-md-8"> 250 Disables the image's transparency channel. Does not delete or change the 251 existing data, just turns off the use of that data.</dd> 252 253 <dt class="col-md-4">Disassociate</dt> 254 <dd class="col-md-8"> 255 disassociate the alpha channel from the image.</dd> 256 257 <dt class="col-md-4">Set</dt> 258 <dd class="col-md-8"> 259 Activates the alpha/matte channel. If it was previously turned off 260 then it also resets the channel to opaque. If the image already had 261 the alpha channel turned on, it will have no effect.</dd> 262 263 <dt class="col-md-4">Opaque</dt> 264 <dd class="col-md-8"> 265 Enables the alpha/matte channel and forces it to be fully opaque. 266 </dd> 267 268 <dt class="col-md-4">Transparent</dt> 269 <dd class="col-md-8"> 270 Activates the alpha/matte channel and forces it to be fully 271 transparent. This effectively creates a fully transparent image the 272 same size as the original and with all its original RGB data still 273 intact, but fully transparent. </dd> 274 275 <dt class="col-md-4">Extract</dt> 276 <dd class="col-md-8"> 277 Copies the alpha channel values into all the color channels and turns 278 'Off' the the image's transparency, so as to generate 279 a grayscale mask of the image's shape. The alpha channel data is left 280 intact just deactivated. This is the inverse of 'Copy'. 281 </dd> 282 283 <dt class="col-md-4">Copy</dt> 284 <dd class="col-md-8"> 285 Turns 'On' the alpha/matte channel, then copies the 286 grayscale intensity of the image, into the alpha channel, converting 287 a grayscale mask into a transparent shaped mask ready to be colored 288 appropriately. The color channels are not modified. </dd> 289 290 <dt class="col-md-4">Shape</dt> 291 <dd class="col-md-8"> 292 As per 'Copy' but also colors the resulting shape mask with 293 the current background color. That is the RGB color channels is 294 replaced, with appropriate alpha shape. 295 </dd> 296 297 <dt class="col-md-4">Remove</dt> 298 <dd class="col-md-8"> 299 Composite the image over the background color. 300 </dd> 301 302 <dt class="col-md-4">Background</dt> 303 <dd class="col-md-8"> 304 Set any fully-transparent pixel to the background color, while leaving 305 it fully-transparent. This can make some image file formats, such as 306 PNG, smaller as the RGB values of transparent pixels are more uniform, 307 and thus can compress better. 308 </dd> 309 </dl> 310 311 <p>Note that while the obsolete <code>+matte</code> operation was the 312 same as "<code><a href="command-line-options.html#alpha" >-alpha</a> Off</code>", the <code> 313 >-matte</code> operation was the same as "<code><a href="command-line-options.html#alpha" >-alpha</a> 314 Set</code>" and not "<code><a href="command-line-options.html#alpha" >-alpha</a> On</code>". </p> 315 316 <div style="margin: auto;"> 317 <h3><a class="anchor" id="annotate"></a> 318 -annotate <var>degrees</var> <var>text</var><br /> 319 -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> 320 </div> 321 322 <p class="magick-description">Annotate an image with text</p> 323 324 <p>This is a convenience for annotating an image with text. For more precise 325 control over text annotations, use <a href="command-line-options.html#draw">-draw</a>.</p> 326 327 328 <p>The values <var>Xdegrees</var> and <var>Ydegrees</var> 329 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.html#gravity" >-gravity</a> setting and defaults to the upper left corner of the image.</p> 330 331 <p>Using <a href="command-line-options.html#annotate">-annotate</a> <var>degrees</var> 332 or <a href="command-line-options.html#annotate">-annotate</a> <var>degrees</var>x<var>degrees</var> produces an unsheared rotation of the text. The 333 direction of the rotation is positive, which means a clockwise rotation if <var>degrees</var> is positive. (This conforms to the usual mathematical 334 convention once it is realized that the positive <var>y</var>direction is 335 conventionally considered to be <var>downward</var> for images.)</p> 336 337 <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 338 equation.</p> 339 340 <p class="text-center"><img class="img-thumbnail" alt="annotate transformation" src="../images/annotate.png"/></p> 341 342 <p>If <var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> are omitted, they default to 0. This makes the 343 bottom-left of the text becomes the upper-left corner of the image, which is 344 probably undesirable. Adding a <a href="command-line-options.html#gravity" >-gravity</a> option in this 345 case leads to nice results.</p> 346 347 <p>Text is any UTF-8 encoded character sequence. If <var>text</var> 348 is of the form '@mytext.txt', the text is read from the file 349 <code>mytext.txt</code>. Text in a file is taken literally; no embedded 350 formatting characters are recognized.</p> 351 352 <div style="margin: auto;"> 353 <h3><a class="anchor" id="antialias"></a>-antialias</h3> 354 </div> 355 356 <p class="magick-description">Enable/Disable of the rendering of anti-aliasing pixels when drawing fonts and lines.</p> 357 358 <p>By default, objects (e.g. text, lines, polygons, etc.) are antialiased when 359 drawn. Use <a href="command-line-options.html#antialias">+antialias</a> to disable the addition of 360 antialiasing edge pixels. This will then reduce the number of colors added to 361 an image to just the colors being directly drawn. That is, no mixed colors 362 are added when drawing such objects. </p> 363 364 <div style="margin: auto;"> 365 <h3><a class="anchor" id="append"></a>-append</h3> 366 </div> 367 368 <p class="magick-description">Join current images vertically or horizontally.</p> 369 370 <p>This option creates a single longer image, by joining all the current 371 images in sequence top-to-bottom. Use <a href="command-line-options.html#append">+append</a> to 372 stack images left-to-right. </p> 373 374 <p>If they are not of the same width, narrower images are padded with the 375 current <a href="command-line-options.html#background">-background</a> color setting, and their 376 position relative to each other can be controlled by the current <a 377 href="command-line-options.html#gravity">-gravity</a> setting. </p> 378 379 380 <div style="margin: auto;"> 381 <h3><a class="anchor" id="attenuate"></a>-attenuate <var>value</var></h3> 382 </div> 383 384 <p class="magick-description">Lessen (or intensify) when adding noise to an image.</p> 385 386 <p>If unset the value is equivalent to 1.0, or a maximum noise addition</p> 387 388 <div style="margin: auto;"> 389 <h3><a class="anchor" id="authenticate"></a>-authenticate <var>password</var></h3> 390 </div> 391 392 <p class="magick-description">Decrypt a PDF with a password.</p> 393 394 <p>Use this option to supply a <var>password</var> for decrypting 395 a PDF that has been encrypted using Microsoft Crypto API (MSC API). The 396 encrypting using the MSC API is not supported.</p> 397 398 <p>For a different encryption method, see <a href="command-line-options.html#encipher">-encipher</a> 399 and <a href="command-line-options.html#decipher">-decipher</a>. </p> 400 401 402 <div style="margin: auto;"> 403 <h3><a class="anchor" id="auto-gamma"></a>-auto-gamma</h3> 404 </div> 405 406 <p class="magick-description">Automagically adjust gamma level of image.</p> 407 408 <p>This calculates the mean values of an image, then applies a calculated <a 409 href="command-line-options.html#gamma" >-gamma</a> adjustment so that the mean color in the 410 image will get a value of 50%. </p> 411 412 <p>This means that any solid 'gray' image becomes 50% gray. </p> 413 414 <p>This works well for real-life images with little or no extreme dark and 415 light areas, but tend to fail for images with large amounts of bright sky or 416 dark shadows. It also does not work well for diagrams or cartoon like images. 417 </p> 418 419 <p>It uses the <a href="command-line-options.html#channel" >-channel</a> setting, (including the 420 '<var>sync</var>' flag for channel synchronization), to determine which color 421 values is used and modified. As the default <a href="command-line-options.html#channel" 422 >-channel</a> setting is '<var>RGB,sync</var>', channels are modified 423 together by the same gamma value, preserving colors. </p> 424 425 426 427 <div style="margin: auto;"> 428 <h3><a class="anchor" id="auto-level"></a>-auto-level</h3> 429 </div> 430 431 <p class="magick-description">Automagically adjust color levels of image.</p> 432 433 <p>This is a 'perfect' image normalization operator. It finds the exact 434 minimum and maximum color values in the image and then applies a <a 435 href="command-line-options.html#level" >-level</a> operator to stretch the values to the full range of 436 values. </p> 437 438 <p>The operator is not typically used for real-life images, image scans, or 439 JPEG format images, as a single 'out-rider' pixel can set a bad min/max values 440 for the <a href="command-line-options.html#level" >-level</a> operation. On the other hand it is the 441 right operator to use for color stretching gradient images being used to 442 generate Color lookup tables, distortion maps, or other 'mathematically' 443 defined images. </p> 444 445 <p>The operator is very similar to the <a href="command-line-options.html#normalize">-normalize</a>, <a 446 href="command-line-options.html#contrast-stretch" >-contrast-stretch</a>, and <a href="command-line-options.html#linear-stretch" 447 >-linear-stretch</a> operators, but without 'histogram binning' or 'clipping' 448 problems that these operators may have. That is <a href="command-line-options.html#auto-level" 449 >-auto-level</a> is the perfect or ideal version these operators. </p> 450 451 <p>It uses the <a href="command-line-options.html#channel" >-channel</a> setting, (including the 452 special '<var>sync</var>' flag for channel synchronization), to determine 453 which color values are used and modified. As the default <a 454 href="command-line-options.html#channel" >+channel</a> setting is '<var>RGB,sync</var>', the 455 '<var>sync</var>' ensures that the color channels will are modified 456 together by the same gamma value, preserving colors, and ignoring 457 transparency. </p> 458 459 460 <div style="margin: auto;"> 461 <h3><a class="anchor" id="auto-orient"></a>-auto-orient</h3> 462 </div> 463 464 <p class="magick-description">adjusts an image so that its orientation is suitable for viewing (i.e. top-left orientation).</p> 465 466 <p>This operator reads and resets the EXIF image profile setting 'Orientation' 467 and then performs the appropriate 90 degree rotation on the image to orient 468 the image, for correct viewing. </p> 469 470 <p>This EXIF profile setting is usually set using a gravity sensor in digital 471 camera, however photos taken directly downward or upward may not have an 472 appropriate value. Also images that have been orientation 'corrected' without 473 reseting this setting, may be 'corrected' again resulting in a incorrect 474 result. If the EXIF profile was previously stripped, the <a 475 href="command-line-options.html#auto-orient" >-auto-orient</a> operator will do nothing. </p> 476 477 <div style="margin: auto;"> 478 <h3><a class="anchor" id="auto-threshold"></a>-auto-threshold <var>method</var></h3> 479 </div> 480 481 <p class="magick-description">automatically perform image thresholding.</p> 482 483 <p>Here are the valid methods:</p> 484 485 <dl class="row"> 486 <dt class="col-md-4">Undefined</dt><dd class="col-md-8">0: No method specified (equivalent to '<code>OTSU</code>').</dd> 487 <dt class="col-md-4">Kapur</dt><dd class="col-md-8">maximum entropy thresholding.</dd> 488 <dt class="col-md-4">OTSU</dt><dd class="col-md-8">cluster-based image thresholding.</dd> 489 <dt class="col-md-4">Triangle</dt><dd class="col-md-8">a geometric thresholding method.</dd> 490 </dl> 491 492 <p>The computed threshold is returned as the <kbd>auto-threshold:threshold</kbd> image property.</p> 493 494 <div style="margin: auto;"> 495 <h3><a class="anchor" id="average"></a>-average</h3> 496 </div> 497 498 <p class="magick-description">Average a set of images.</p> 499 500 <p>An error results if the images are not identically sized.</p> 501 502 503 <div style="margin: auto;"> 504 <h3><a class="anchor" id="backdrop"></a>-backdrop</h3> 505 </div> 506 507 <p class="magick-description">Display the image centered on a backdrop.</p> 508 509 <p>This backdrop covers the entire workstation screen and is useful for hiding 510 other X window activity while viewing the image. The color of the backdrop is 511 specified as the background color. The color is specified using the format 512 described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 513 514 <div style="margin: auto;"> 515 <h3><a class="anchor" id="background"></a>-background <var>color</var></h3> 516 </div> 517 518 <p class="magick-description">Set the background color.</p> 519 520 <p>The color is specified using the format described under the <a 521 href="command-line-options.html#fill">-fill</a> option. The default background color (if none is 522 specified or found in the image) is white.</p> 523 524 <div style="margin: auto;"> 525 <h3><a class="anchor" id="bench"></a>-bench <var>iterations</var></h3> 526 </div> 527 528 <p class="magick-description">Measure performance.</p> 529 530 <p>Repeat the entire command for the given number of <var>iterations</var> and report the user-time and elapsed time. For instance, 531 consider the following command and its output. Modify the benchmark with the 532 -duration to run the benchmark for a fixed number of seconds and -concurrent 533 to run the benchmark in parallel (requires the OpenMP feature).</p> 534 535 <pre class="highlight"><code>-> convert logo: -resize 200% -bench 5 logo.png 536 Performance[1]: 5i 1.344ips 1.000e 3.710u 0:03.720 537 Performance[2]: 5i 1.634ips 0.549e 3.890u 0:03.060 538 Performance[3]: 5i 2.174ips 0.618e 3.190u 0:02.300 539 Performance[4]: 5i 1.678ips 0.555e 3.810u 0:02.980 540 Performance[4]: 5i 0.875657ips 6.880u 0:05.710 541 </code></pre> 542 543 <p>In this example, 5 iterations were completed at 2.174 iterations per 544 second, using 3 threads and 3.190 seconds of the user allotted time, for 545 a total elapsed time of 2.300 seconds.</p> 546 547 <div style="margin: auto;"> 548 <h3><a class="anchor" id="bias"></a>-bias <var>value</var>{<var>%</var>}</h3> 549 </div> 550 551 <p class="magick-description">Add bias when convolving an image.</p> 552 553 <p>This option shifts the output of <a href="command-line-options.html#convolve">‑convolve</a> so that 554 positive and negative results are relative to the specified bias value. </p> 555 556 <p>This is important for non-HDRI compilations of ImageMagick when dealing 557 with convolutions that contain negative as well as positive values. This is 558 especially the case with convolutions involving high pass filters or edge 559 detection. Without an output bias, the negative values are clipped at 560 zero.</p> 561 562 <p>When using an ImageMagick with the HDRI compile-time setting, <a href="command-line-options.html#bias">‑bias</a> is not needed, as ImageMagick is able to store/handle any 563 negative results without clipping to the color value range 564 (0..QuantumRange).</p> 565 566 <p>See the discussion on HDRI implementations of ImageMagick on the page <a 567 href="high-dynamic-range.html" >High Dynamic-Range Images</a>. For more 568 about HDRI go the ImageMagick <a 569 href="../Usage/basics/#hdri" >Usage</a> pages or this 570 <a 571 href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> 572 entry. </p> 573 574 <div style="margin: auto;"> 575 <h3><a class="anchor" id="black-point-compensation"></a>-black-point-compensation</h3> 576 </div> 577 578 <p class="magick-description">Use black point compensation.</p> 579 580 <div style="margin: auto;"> 581 <h3><a class="anchor" id="black-threshold"></a>-black-threshold <var>value</var>{<var>%</var>}</h3> 582 </div> 583 584 <p class="magick-description">Force to black all pixels below the threshold while leaving all pixels at or above the threshold unchanged.</p> 585 586 <p> The threshold value can be given as a percentage or as an absolute integer 587 value within [0, <var>QuantumRange</var>] corresponding to the 588 desired <a href="command-line-options.html#channel">‑channel</a> value. See <a href="command-line-options.html#threshold">‑threshold</a>for more details on thresholds and resulting values. </p> 589 590 591 <div style="margin: auto;"> 592 <h3><a class="anchor" id="blend"></a>-blend <var>geometry</var></h3> 593 </div> 594 595 <p class="magick-description">blend an image into another by the given absolute value or percent.</p> 596 597 <p>Blend will average the images together ('plus') according to the 598 percentages given and each pixels transparency. If only a single percentage 599 value is given it sets the weight of the composite or 'source' image, while 600 the background image is weighted by the exact opposite amount. That is a 601 <code>-blend 30%</code> merges 30% of the 'source' image with 70% of the 602 'destination' image. Thus it is equivalent to <code>-blend 30x70%</code>.</p> 603 604 605 <div style="margin: auto;"> 606 <h3><a class="anchor" id="blue-primary"></a>-blue-primary <var>x</var>,<var>y</var></h3> 607 </div> 608 609 <p class="magick-description">Set the blue chromaticity primary point.</p> 610 611 <div style="margin: auto;"> 612 <h3><a class="anchor" id="blue-shift"></a>-blue-shift <var>factor</var></h3> 613 </div> 614 615 <p class="magick-description">simulate a scene at nighttime in the moonlight. Start with a factor of 1.5</p> 616 617 <div style="margin: auto;"> 618 619 <div style="margin: auto;"> 620 <h3><a class="anchor" id="blur"></a>-blur <var>radius</var><br />-blur <var>radius</var>x<var>sigma</var></h3> 621 </div> 622 623 <p class="magick-description">Reduce image noise and reduce detail levels.</p> 624 625 <p>Convolve the image with a Gaussian or normal distribution using the given 626 <var >Sigma</var> value. The formula is:</p> 627 628 <p class="text-center"><img class="img-thumbnail" alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png"/></p> 629 630 <p>The <var >Sigma</var> value is the important argument, and 631 determines the actual amount of blurring that will take place. </p> 632 633 <p>The <var >Radius</var> is only used to determine the size of the 634 array which will hold the calculated Gaussian distribution. It should be an 635 integer. If not given, or set to zero, IM will calculate the largest possible 636 radius that will provide meaningful results for the Gaussian distribution. 637 </p> 638 639 <p>The larger the <var >Radius</var> the slower the 640 operation is. However too small a <var >Radius</var>, and severe 641 aliasing effects may result. As a guideline, <var >Radius</var> 642 should be at least twice the <var >Sigma</var> value, though three 643 times will produce a more accurate result. </p> 644 645 <p>This option differs from <a href="command-line-options.html#gaussian-blur">-gaussian-blur</a> simply 646 by taking advantage of the separability properties of the distribution. Here 647 we apply a single-dimensional Gaussian matrix in the horizontal direction, 648 then repeat the process in the vertical direction.</p> 649 650 <p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 651 pixels which are outside the image proper are blurred into the final result. 652 </p> 653 654 655 <div style="margin: auto;"> 656 <h3><a class="anchor" id="border"></a>-border <var>geometry</var></h3> 657 </div> 658 659 <p class="magick-description">Surround the image with a border of color. </p> 660 661 <p>Set the width and height using the <var>size</var> portion of the 662 <var>geometry</var> argument. See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets are 663 ignored. </p> 664 665 <p>As of IM 6.7.8-8, the <var>geometry</var> arguments behave as follows:</p> 666 667 <dl class="row"> 668 <dt class="col-md-4"><var>value</var></dt> 669 <dd class="col-md-8">value is added to both left/right and top/bottom</dd> 670 <dt class="col-md-4"><var>value-x</var><code>x</code></dt> 671 <dd class="col-md-8">value-x is added only to left/right and top/bottom are unchanged</dd> 672 <dt class="col-md-4"><code>x</code><var>value-y</var></dt> 673 <dd class="col-md-8">value-y is added only to top/bottom and left/right are unchanged</dd> 674 <dt class="col-md-4"><var>value-x</var><code>x</code><var>value-y</var></dt> 675 <dd class="col-md-8">value-x is added to left/right and value-y added to top/bottom</dd> 676 <dt class="col-md-4"><var>value-x</var><code>x</code>0</dt> 677 <dd class="col-md-8">value-x is added only to left/right and top/bottom are unchanged</dd> 678 <dt class="col-md-4">0<code>x</code><var>value-y</var></dt> 679 <dd class="col-md-8">value-y is added only to top/bottom and left/right are unchanged</dd> 680 <dt class="col-md-4"><var>value</var>%</dt> 681 <dd class="col-md-8">value % of width is added to left/right and value % of height is added to top/bottom</dd> 682 <dt class="col-md-4"><var>value-x</var><code>x</code>%</dt> 683 <dd class="col-md-8">value-x % of width is added to left/right and to top/bottom</dd> 684 <dt class="col-md-4">x<var>value-y</var>%</dt> 685 <dd class="col-md-8">value-y % of height is added to top/bottom and to left/right</dd> 686 <dt class="col-md-4"><var>value-x</var>%<code>x</code><var>value-y</var>%</dt> 687 <dd class="col-md-8">value-x % of width is added to left/right and value-y % of height is added to top/bottom</dd> 688 <dt class="col-md-4"><var>value-x</var>%<code>x</code>0%</dt> 689 <dd class="col-md-8">value-x % of width is added to left/right and top/bottom are unchanged</dd> 690 <dt class="col-md-4">0%<code>x</code><var>value-y</var>%</dt> 691 <dd class="col-md-8">value-y % of height is added to top/bottom and left/right are unchanged</dd> 692 </dl> 693 694 <p>Set the border color by preceding with the <a 695 href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p> 696 697 <p>The <a href="command-line-options.html#border">-border</a> operation is affected by the current <a 698 href="command-line-options.html#compose">-compose</a> setting and assumes that this is using the default 699 '<code>Over</code>' composition method. It generates an image of the appropriate 700 size colors by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> before 701 overlaying the original image in the center of this net image. This means that 702 with the default compose method of '<code>Over</code>' any transparent parts may 703 be replaced by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p> 704 <p>See also the <a href="command-line-options.html#frame">-frame</a> option, which has more 705 functionality.</p> 706 707 <div style="margin: auto;"> 708 <h3><a class="anchor" id="bordercolor"></a>-bordercolor <var>color</var></h3> 709 </div> 710 711 <p class="magick-description">Set the border color.</p> 712 713 <p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 714 715 <p>The default border color is <code>#DFDFDF</code>, <span style="background-color: #dfdfdf;">this shade of gray</span>.</p> 716 717 <div style="margin: auto;"> 718 <h3><a class="anchor" id="borderwidth"></a>-borderwidth <var>geometry</var> </h3> 719 </div> 720 721 <p class="magick-description">Set the border width.</p> 722 723 <div style="margin: auto;"> 724 <h3><a class="anchor" id="brightness-contrast"></a>-brightness-contrast <var>brightness</var><br />-brightness-contrast <var>brightness</var>{x<var>contrast</var>}{<var>%</var>}</h3> 725 </div> 726 727 <p class="magick-description">Adjust the brightness and/or contrast of the image.</p> 728 729 <p>Brightness and Contrast values apply changes to the input image. They are 730 not absolute settings. A brightness or contrast value of zero means no change. 731 The range of values is -100 to +100 on each. Positive values increase the 732 brightness or contrast and negative values decrease the brightness or contrast. 733 To control only contrast, set the brightness=0. To control only brightness, 734 set contrast=0 or just leave it off.</p> 735 736 <p>You may also use <a href="command-line-options.html#fill">-channel</a> to control which channels to 737 apply the brightness and/or contrast change. The default is to apply the same 738 transformation to all channels.</p> 739 740 <p>Brightness and Contrast arguments are converted to offset and slope of a 741 linear transform and applied 742 using <a href="command-line-options.html#fill">-function polynomial "slope,offset"</a>.</p> 743 744 <p>The slope varies from 0 at contrast=-100 to almost vertical at 745 contrast=+100. For brightness=0 and contrast=-100, the result are totally 746 midgray. For brightness=0 and contrast=+100, the result will approach but 747 not quite reach a threshold at midgray; that is the linear transformation 748 is a very steep vertical line at mid gray.</p> 749 750 <p>Negative slopes, i.e. negating the image, are not possible with this 751 function. All achievable slopes are zero or positive.</p> 752 753 <p>The offset varies from -0.5 at brightness=-100 to 0 at brightness=0 to +0.5 754 at brightness=+100. Thus, when contrast=0 and brightness=100, the result is 755 totally white. Similarly, when contrast=0 and brightness=-100, the result is 756 totally black.</p> 757 758 <p>As the range of values for the arguments are -100 to +100, adding the '%' 759 symbol is no different than leaving it off.</p> 760 761 <div style="margin: auto;"> 762 <h3><a class="anchor" id="cache"></a>-cache <var>threshold</var></h3> 763 </div> 764 765 <p class="magick-description">(This option has been replaced by the <a href='command-line-options.html#limit'>-limit</a> option).</p> 766 767 <div style="margin: auto;"> 768 <h3><a class="anchor" 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> 769 </div> 770 771 <p class="magick-description">Canny edge detector uses a multi-stage algorithm to detect a wide range of edges in the image.</p> 772 773 <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> 774 775 <div style="margin: auto;"> 776 <h3><a class="anchor" id="caption"></a>-caption <var>string</var></h3> 777 </div> 778 779 <p class="magick-description">Assign a caption to an image.</p> 780 781 <p>This option sets the caption meta-data of an image read in after this 782 option has been given. To modify a caption of images already in memory use 783 "<code><a href="command-line-options.html#set">-set</a> caption</code>". </p> 784 785 <p>The caption can contain special format characters listed in the <a 786 href="../www/escape.html">Format and 787 Print Image Properties</a>. These attributes are expanded when the caption 788 is finally assigned to the individual images. </p> 789 790 <p>If the first character of <var>string</var> is <var>@</var>, the image caption is read from a file titled by the 791 remaining characters in the string. Comments read in from a file are literal; 792 no embedded formatting characters are recognized.</p> 793 794 <p>Caption meta-data is not visible on the image itself. To do that use the 795 <a href="command-line-options.html#annotate">-annotate</a> or <a href="command-line-options.html#draw">-draw</a> options 796 instead.</p> 797 798 <p>For example,</p> 799 800 <pre class="highlight"><code>-caption "%m:%f %wx%h" bird.miff 801 </code></pre> 802 803 <p>produces an image caption of <code>MIFF:bird.miff 512x480</code> (assuming 804 that the image <code>bird.miff</code> has a width of 512 and a height of 805 480.</p> 806 807 808 <div style="margin: auto;"> 809 <h3><a class="anchor" id="cdl"></a>-cdl <var>filename</var></h3> 810 </div> 811 812 <p class="magick-description">color correct with a color decision list.</p> 813 814 <p>Here is an example color correction collection:</p> 815 816 <pre class="highlight"><code><?xml version="1.0" encoding="UTF-8"?> 817 <ColorCorrectionCollection xmlns="urn:ASC:CDL:v1.2"> 818 <ColorCorrection id="cc06668"> 819 <SOPNode> 820 <Slope> 0.9 1.2 0.5 </Slope> 821 <Offset> 0.4 -0.5 0.6 </Offset> 822 <Power> 1.0 0.8 1.5 </Power> 823 </SOPNode> 824 <SATNode> 825 <Saturation> 0.85 </Saturation> 826 </SATNode> 827 </ColorCorrection> 828 </ColorCorrectionCollection> 829 </code></pre> 830 831 <div style="margin: auto;"> 832 <h3><a class="anchor" id="channel"></a>-channel <var>type</var></h3> 833 </div> 834 835 <p class="magick-description">Specify those image color channels to which subsequent operators are limited.</p> 836 837 <p>Choose from: <code>Red</code>, <code>Green</code>, <code>Blue</code>, 838 <code>Alpha</code>, <code>Gray</code>, <code>Cyan</code>, <code>Magenta</code>, 839 <code>Yellow</code>, <code>Black</code>, <code>Opacity</code>, 840 <code>Index</code>, <code>RGB</code>, <code>RGBA</code>, <code>CMYK</code>, or 841 <code>CMYKA</code>.</p> 842 843 <p>The channels above can also be specified as a comma-separated list or can be 844 abbreviated as a concatenation of the letters '<code>R</code>', '<code>G</code>', 845 '<code>B</code>', '<code>A</code>', '<code>O</code>', '<code>C</code>', 846 '<code>M</code>', '<code>Y</code>', '<code>K</code>'.</p> 847 848 <p>The numerals 0 to 31 may also be used to specify channels, where 0 to 5 are: <br /> 849 '<code>0</code>' equals <code>Red</code> or <code>Cyan</code> <br /> 850 '<code>1</code>' equals <code>Green</code> or <code>Magenta</code> <br /> 851 '<code>2</code>' equals <code>Blue</code> or <code>Yellow</code> <br /> 852 '<code>3</code>' equals <code>Black</code> <br /> 853 '<code>4</code>' equals <code>Alpha</code> or <code>Opacity</code> <br /> 854 '<code>5</code>' equals <code>Index</code></p> 855 856 <p>For example, to only select the <code>Red</code> and <code>Blue</code> channels 857 you can use any of the following:</p> 858 <pre class="highlight"> 859 <code>-channel Red,Blue</code> 860 <code>-channel R,B</code> 861 <code>-channel RB</code> 862 <code>-channel 0,2</code> 863 </pre> 864 865 <p>All the channels that are present in an image can be specified using the 866 special channel type <code>All</code>. Not all operators are 'channel capable', 867 but generally any operators that are generally 'grey-scale' image operators, 868 will understand this setting. See individual operator documentation. </p> 869 870 <br/> 871 872 <p>On top of the normal channel selection an extra flag can be specified, 873 '<code>Sync</code>'. This is turned on by default and if set means that 874 operators that understand this flag should perform: cross-channel 875 synchronization of the channels. If not specified, then most grey-scale 876 operators will apply their image processing operations to each individual 877 channel (as specified by the rest of the <a href="command-line-options.html#channel">-channel</a> 878 setting) completely independently from each other. </p> 879 880 <p>For example for operators such as <a href="command-line-options.html#auto-level">-auto-level</a> and 881 <a href="command-line-options.html#auto-gamma">-auto-gamma</a> the color channels are modified 882 together in exactly the same way so that colors will remain in-sync. Without 883 it being set, then each channel is modified separately and 884 independently, which may produce color distortion. </p> 885 886 <p>The <a href="command-line-options.html#morphology">-morphology</a> '<code>Convolve</code>' method 887 and the <a href="command-line-options.html#compose">-compose</a> mathematical methods, also understands 888 the '<code>Sync</code>' flag to modify the behavior of pixel colors according 889 to the alpha channel (if present). That is to say it will modify the image 890 processing with the understanding that fully-transparent colors should not 891 contribute to the final result. </p> 892 893 <p>Basically, by default, operators work with color channels in synchronous, and 894 treats transparency as special, unless the <a href="command-line-options.html#channel">-channel</a> 895 setting is modified so as to remove the effect of the '<code>Sync</code>' flag. 896 How each operator does this depends on that operators current implementation. 897 Not all operators understands this flag at this time, but that is changing. 898 </p> 899 900 <p>To print a complete list of channel types, use <a href="command-line-options.html#list">-list 901 channel</a>.</p> 902 903 <p>By default, ImageMagick sets <a href="command-line-options.html#channel">-channel</a> to the value 904 '<code>RGBK,sync</code>', which specifies that operators act on all color 905 channels except the transparency channel, and that all the color channels are 906 to be modified in exactly the same way, with an understanding of transparency 907 (depending on the operation being applied). The 'plus' form <a 908 href="command-line-options.html#channel" >+channel</a> will reset the value back to this default. </p> 909 910 <p>Options that are affected by the <a href="command-line-options.html#channel" >-channel</a> setting 911 include the following. 912 913 <a href="command-line-options.html#auto-gamma">-auto-gamma</a>, 914 <a href="command-line-options.html#auto-level">-auto-level</a>, 915 <a href="command-line-options.html#black-threshold">-black-threshold</a>, 916 <a href="command-line-options.html#blur">-blur</a>, 917 <a href="command-line-options.html#clamp">-clamp</a>, 918 <a href="command-line-options.html#clut">-clut</a>, 919 <a href="command-line-options.html#combine">-combine</a>, 920 <a href="command-line-options.html#composite">-composite</a> (Mathematical compose methods only), 921 <a href="command-line-options.html#convolve">-convolve</a>, 922 <a href="command-line-options.html#contrast-stretch">-contrast-stretch</a>, 923 <a href="command-line-options.html#evaluate">-evaluate</a>, 924 <a href="command-line-options.html#function">-function</a>, 925 <a href="command-line-options.html#fx">-fx</a>, 926 <a href="command-line-options.html#gaussian-blur">-gaussian-blur</a>, 927 <a href="command-line-options.html#hald-clut">-hald-clut</a>, 928 <a href="command-line-options.html#motion-blur">-motion-blur</a>, 929 <a href="command-line-options.html#morphology">-morphology</a>, 930 <a href="command-line-options.html#negate">-negate</a>, 931 <a href="command-line-options.html#normalize">-normalize</a>, 932 <a href="command-line-options.html#ordered-dither">-ordered-dither</a>, 933 <a href="command-line-options.html#radial-blur">-radial-blur</a>, 934 <a href="command-line-options.html#random-threshold">-random-threshold</a>, 935 <a href="command-line-options.html#range-threshold">-range-threshold</a>, 936 <a href="command-line-options.html#separate">-separate</a>, 937 <a href="command-line-options.html#threshold">-threshold</a>, and 938 <a href="command-line-options.html#white-threshold">-white-threshold</a>. 939 </p> 940 941 <p>Warning, some operators behave differently when the <a href="command-line-options.html#channel" 942 >+channel</a> default setting is in effect, verses ANY user defined <a 943 href="command-line-options.html#channel" >-channel</a> setting (including the equivalent of the 944 default). These operators have yet to be made to understand the newer 'Sync' 945 flag. </p> 946 947 <p>For example <a href="command-line-options.html#threshold">-threshold</a> will by default grayscale 948 the image before thresholding, if no <a href="command-line-options.html#channel" >-channel</a> setting 949 has been defined. This is not 'Sync flag controlled, yet. </p> 950 951 <p>Also some operators such as <a href="command-line-options.html#blur">-blur</a>, <a 952 href="command-line-options.html#gaussian-blur">-gaussian-blur</a>, will modify their handling of the 953 color channels if the '<code>alpha</code>' channel is also enabled by <a 954 href="command-line-options.html#channel" >-channel</a>. Generally this done to ensure that 955 fully-transparent colors are treated as being fully-transparent, and thus any 956 underlying 'hidden' color has no effect on the final results. Typically 957 resulting in 'halo' effects. The newer <a href="command-line-options.html#morphology">-morphology</a> 958 convolution equivalents however does have a understanding of the 'Sync' flag 959 and will thus handle transparency correctly by default. </p> 960 961 <p>As a alpha channel is optional within images, some operators will read the 962 color channels of an image as a greyscale alpha mask, when the image has no 963 alpha channel present, and the <a href="command-line-options.html#channel" >-channel</a> setting tells 964 the operator to apply the operation using alpha channels. The <a 965 href="command-line-options.html#clut">-clut</a> operator is a good example of this. </p> 966 967 <div style="margin: auto;"> 968 <h3><a class="anchor" id="channel-fx"></a>-channel-fx <var>expression</var></h3> 969 </div> 970 971 <p class="magick-description">exchange, extract, or copy one or more image channels.</p> 972 973 <p>The expression consists of one or more channels, either mnemonic or numeric (e.g. red or 0, green or 1, etc.), separated by certain operation symbols as follows:</p> 974 975 <pre class="highlight"><code><=> exchange two channels (e.g. red<=>blue) 976 => copy one channel to another channel (e.g. red=>green) 977 = assign a constant value to a channel (e.g. red=50%) 978 , write new image with channels in the specified order (e.g. red, green) 979 ; add a new output image for the next set of channel operations (e.g. red; green; blue) 980 | move to the next input image for the source of channel data (e.g. | gray=>alpha) 981 </code></pre> 982 983 <p>For example, to create 3 grayscale images from the red, green, and blue channels of an image, use:</p> 984 985 <pre class="highlight"><code>-channel-fx "red; green; blue" 986 </code></pre> 987 988 <p>A channel without an operation symbol implies separate (i.e, semicolon).</p> 989 990 <p>Here we take an sRGB image and a grayscale image and inject the grayscale image into the alpha channel:</p> 991 <pre class="highlight"><code>convert wizard.png mask.pgm -channel-fx '| gray=>alpha' wizard-alpha.png 992 </code></pre> 993 <p>Use a similar command to define a read mask:</p> 994 <pre class="highlight"><code>convert wizard.png mask.pgm -channel-fx '| gray=>read-mask' wizard-mask.png 995 </code></pre> 996 997 <p>Add <code>-debug pixel</code> prior to the <code>-channel-fx</code> option to track the channel morphology.</p> 998 999 <div style="margin: auto;"> 1000 <h3><a class="anchor" id="charcoal"></a>-charcoal <var>factor</var></h3> 1001 </div> 1002 1003 <p class="magick-description">Simulate a charcoal drawing.</p> 1004 1005 <div style="margin: auto;"> 1006 <h3><a class="anchor" id="chop"></a>-chop <var>geometry</var></h3> 1007 </div> 1008 1009 <p class="magick-description">Remove pixels from the interior of an image.</p> 1010 1011 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <var>width</var> 1012 and <var>height</var> given in the of the <var>size</var> 1013 portion of the <var>geometry</var> argument give the number of 1014 columns and rows to remove. The <var>offset</var> portion of 1015 the <var>geometry</var> argument is influenced by 1016 a <a href="command-line-options.html#gravity">-gravity</a> setting, if present.</p> 1017 1018 <p>The <a href="command-line-options.html#chop">-chop</a> option removes entire rows and columns, 1019 and moves the remaining corner blocks leftward and upward to close the gaps.</p> 1020 1021 <p>While it can remove internal rows and columns of pixels, it is more 1022 typically used with as <a href="command-line-options.html#gravity">-gravity</a> setting and zero 1023 offsets so as to remove a single edge from an image. Compare this to <a 1024 href="command-line-options.html#shave" >-shave</a> which removes equal numbers of pixels from opposite 1025 sides of the image. </p> 1026 1027 <p>Using <a href="command-line-options.html#chop">-chop</a> effectively undoes the results of a <a 1028 href="command-line-options.html#splice">-splice</a> that was given the same <var>geometry</var> and <a href="command-line-options.html#gravity">-gravity</a> settings. </p> 1029 1030 <div style="margin: auto;"> 1031 <h3><a class="anchor" id="clahe"></a>-clahe <var>width</var>x<var>height</var>{%}{+}<var>number-bins</var>{+}<var>clip-limit</var>{!}</h3> 1032 </div> 1033 1034 <p class="magick-description">contrast limited adaptive histogram equalization. The image is divided into tiles of <var>width</var> and <var>height</var> pixels. The tile size should be larger than the size of features to be preserved and respects the aspect ratio of the image. Add <code>!</code> to force an exact tile width and height. <var>number-bins</var> is the number of histogram bins per tile (min 2, max 65536). The number of histogram bins should be smaller than the number of pixels in a single tile. <var>clip-limit</var> is the contrast limit for localised changes in contrast. A clip-limit of 2 to 3 is a good starting place (e.g. -clahe 50x50%+128+3). Very large values will let the histogram equalization do whatever it wants to do, that is result in maximal local contrast. The value 1 will result in the original image. Note if number of bins and the clip-limit are ommitted, they default to 128 and no clipping respectively.</p> 1035 1036 1037 <div style="margin: auto;"> 1038 <h3><a class="anchor" id="clamp"></a>-clamp</h3> 1039 </div> 1040 1041 <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> 1042 1043 <div style="margin: auto;"> 1044 <h3><a class="anchor" id="clip"></a>-clip</h3> 1045 </div> 1046 1047 <p class="magick-description">Apply the clipping path if one is present.</p> 1048 1049 <p>If a clipping path is present, it is applied to subsequent operations.</p> 1050 1051 <p>For example, in the command</p> 1052 1053 <pre class="highlight"><code>convert cockatoo.tif -clip -negate negated.tif 1054 </code></pre> 1055 1056 <p>only the pixels within the clipping path are negated.</p> 1057 1058 <p>The <a href="command-line-options.html#clip">-clip</a> feature requires SVG support. If the SVG 1059 delegate library is not present, the option is ignored.</p> 1060 1061 <p>Use <a href="command-line-options.html#clip">+clip</a> to disable clipping for subsequent operations.</p> 1062 1063 <div style="margin: auto;"> 1064 <h3><a class="anchor" id="clip-mask"></a>-clip-mask</h3> 1065 </div> 1066 1067 <p class="magick-description">Clip the image as defined by this mask.</p> 1068 1069 <p>Use the alpha channel of the current image as a mask. Any areas that is 1070 white is not modified by any of the 'image processing operators' that follow, 1071 until the mask is removed. Pixels in the black areas of the clip mask are 1072 modified per the requirements of the operator. </p> 1073 1074 <p>In some ways this is similar to (though not the same) as defining 1075 a rectangular <a href="command-line-options.html#region" >-region</a>, or using the negative of the 1076 mask (third) image in a three image <a href="command-line-options.html#composite" >-composite</a>, 1077 operation. </p> 1078 1079 <p>Use <a href="command-line-options.html#clip-mask">+clip-mask</a> to disable clipping for subsequent operations.</p> 1080 1081 <div style="margin: auto;"> 1082 <h3><a class="anchor" id="clip-path"></a>-clip-path <var>id</var></h3> 1083 </div> 1084 1085 <p class="magick-description">Clip along a named path from the 8BIM profile.</p> 1086 1087 <p>This is identical to <a href="command-line-options.html#clip">-clip</a> except choose a specific clip path in the event the image has more than one path available. </p> 1088 1089 <p>Use <a href="command-line-options.html#clip-path">+clip-path</a> to disable clipping for subsequent operations.</p> 1090 1091 <div style="margin: auto;"> 1092 <h3><a class="anchor" id="clone"></a>-clone <var>index(s)</var></h3> 1093 </div> 1094 1095 <p class="magick-description">make a clone of an image (or images).</p> 1096 1097 <p>Inside parenthesis (where the operator is normally used) it will make a 1098 clone of the images from the last 'pushed' image sequence, and adds them to 1099 the end of the current image sequence. Outside parenthesis 1100 (not recommended) it clones the images from the current image sequence. </p> 1101 1102 <p>Specify the image by its index in the sequence. The first image is index 1103 0. Negative indexes are relative to the end of the sequence; for 1104 example, <code>1</code> 1105 represents the last image of the sequence. Specify a range of images with a 1106 dash (e.g. <code>04</code>). Separate multiple indexes with commas but no 1107 spaces (e.g. <code>0,2,5</code>). A value of '<code>01</code> will 1108 effectively clone all the images. </p> 1109 1110 <p>The <a href="command-line-options.html#clone">+clone</a> will simply make a copy of the last image 1111 in the image sequence, and is thus equivalent to using a argument of 1112 '<code>1</code>'. </p> 1113 1114 <div style="margin: auto;"> 1115 <h3><a class="anchor" id="clut"></a>-clut</h3> 1116 </div> 1117 1118 <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> 1119 1120 <p>The second (LUT) image is ordinarily a gradient image containing the 1121 histogram mapping of how each channel should be modified. Typically it is a 1122 either a single row or column image of replacement color values. If larger 1123 than a single row or column, values are taken from a diagonal line from 1124 top-left to bottom-right corners.</p> 1125 1126 <p>The lookup is further controlled by the <a 1127 href="command-line-options.html#interpolate">-interpolate</a> setting, which is especially handy for an 1128 LUT which is not the full length needed by the ImageMagick installed Quality 1129 (Q) level. Good settings for this are the '<code>bilinear</code>' and 1130 '<code>bicubic</code>' interpolation settings, which give smooth color 1131 gradients, and the '<code>integer</code>' setting for a direct, unsmoothed 1132 lookup of color values. </p> 1133 1134 <p>This operator is especially suited to replacing a grayscale image with a 1135 specific color gradient from the CLUT image. </p> 1136 1137 <p>Only the channel values defined by the <a href="command-line-options.html#channel">-channel</a> 1138 setting will have their values replaced. In particular, since the default <a 1139 href="command-line-options.html#channel">-channel</a> setting is <code>RGB</code>, this means that 1140 transparency (alpha/matte channel) is not affected, unless the <a 1141 href="command-line-options.html#channel">-channel</a> setting is modified. When the alpha channel is 1142 set, it is treated by the <a href="command-line-options.html#clut" >-clut</a> operator in the same way 1143 as the other channels, implying that alpha/matte values are replaced using the 1144 alpha/matte values of the original image. </p> 1145 1146 <p>If either the image being modified, or the lookup image, contains no 1147 transparency (i.e. <a href="command-line-options.html#alpha" >-alpha</a> is turned 'off') but the <a 1148 href="command-line-options.html#channel">-channel</a> setting includes alpha replacement, then it is 1149 assumed that image represents a grayscale gradient which is used for the 1150 replacement alpha values. That is you can use a grayscale CLUT image to 1151 adjust a existing images alpha channel, or you can color a grayscale image 1152 using colors form CLUT containing the desired colors, including transparency. 1153 </p> 1154 1155 <p>See also <a href="command-line-options.html#hald-clut" >-hald-clut</a> which replaces colors 1156 according to the lookup of the full color RGB value from a 2D representation 1157 of a 3D color cube. </p> 1158 1159 1160 <div style="margin: auto;"> 1161 <h3><a class="anchor" id="coalesce"></a>-coalesce</h3> 1162 </div> 1163 1164 <p class="magick-description">Fully define the look of each frame of an GIF animation sequence, to form a 'film strip' animation.</p> 1165 1166 <p>Overlay each image in an image sequence according to 1167 its <a href="command-line-options.html#dispose">-dispose</a> meta-data, to reproduce the look of 1168 an animation at each point in the animation sequence. All images should be 1169 the same size, and are assigned appropriate GIF disposal settings for the 1170 animation to continue working as expected as a GIF animation. Such frames 1171 are more easily viewed and processed than the highly optimized GIF overlay 1172 images. </p> 1173 1174 <p>The animation can be re-optimized after processing using 1175 the <a href="command-line-options.html#layers">-layers</a> method '<code>optimize</code>', although 1176 there is no guarantee that the restored GIF animation optimization is 1177 better than the original. </p> 1178 1179 1180 <div style="margin: auto;"> 1181 <h3><a class="anchor" id="colorize"></a>-colorize <var>value</var></h3> 1182 </div> 1183 1184 <p class="magick-description">Colorize the image by an amount specified by <var>value</var> using the color specified by the most recent <a href="command-line-options.html#fill" >-fill</a> setting.</p> 1185 1186 <p>Specify the amount of colorization as a percentage. Separate colorization 1187 values can be applied to the red, green, and blue channels of the image with 1188 a comma-delimited list of colorization 1189 values (e.g., <code>-colorize 0,0,50</code>).</p> 1190 1191 <div style="margin: auto;"> 1192 <h3><a class="anchor" id="colormap"></a>-colormap <var>type</var></h3> 1193 </div> 1194 1195 <p class="magick-description">Define the colormap type.</p> 1196 1197 <p>The <var>type</var> can be <code>shared</code> or <code>private</code>.</p> 1198 1199 <p>This option only applies when the default X server visual 1200 is <code>PseudoColor</code> or <code>GrayScale</code>. Refer 1201 to <a href="command-line-options.html#visual">-visual</a> for more details. By default, 1202 a shared colormap is allocated. The image shares colors with 1203 other X clients. Some image colors could be approximated, 1204 therefore your image may look very different than intended. 1205 If <code>private</code> is chosen, the image colors appear exactly 1206 as they are defined. However, other clients may go <var>technicolor</var> 1207 when the image colormap is installed.</p> 1208 1209 <div style="margin: auto;"> 1210 <h3><a class="anchor" id="colors"></a>-colors <var>value</var></h3> 1211 </div> 1212 1213 <p class="magick-description">Set the preferred number of colors in the image.</p> 1214 1215 <p>The actual number of colors in the image may be less than your request, 1216 but never more. Note that this a color reduction option. Images with fewer 1217 unique colors than specified by <var>value</var> will have any 1218 duplicate or unused colors removed. The ordering of an existing color 1219 palette may be altered. When converting an image from color to grayscale, 1220 it is more efficient to convert the image to the gray colorspace before 1221 reducing the number of colors. Refer to 1222 the <a href="../www/quantize.html"> 1223 color reduction algorithm</a> for more details.</p> 1224 1225 <div style="margin: auto;"> 1226 <h3><a class="anchor" id="color-matrix"></a>-color-matrix <var>matrix</var></h3> 1227 </div> 1228 1229 <p class="magick-description">apply color correction to the image.</p> 1230 1231 <p>This option permits saturation changes, hue rotation, luminance to alpha, 1232 and various other effects. Although variable-sized transformation matrices 1233 can be used, typically one uses a 5x5 matrix for an RGBA image and a 6x6 1234 for CMYKA (or RGBA with offsets). The matrix is similar to those used by 1235 Adobe Flash except offsets are in column 6 rather than 5 (in support of 1236 CMYKA images) and offsets are normalized (divide Flash offset by 255).</p> 1237 1238 <p>As an example, to add contrast to an image with offsets, try this command:</p> 1239 1240 <pre class="highlight"><code>convert kittens.jpg -color-matrix \ 1241 " 1.5 0.0 0.0 0.0, 0.0, -0.157 \ 1242 0.0 1.5 0.0 0.0, 0.0, -0.157 \ 1243 0.0 0.0 1.5 0.0, 0.0, -0.157 \ 1244 0.0 0.0 0.0 1.0, 0.0, 0.0 \ 1245 0.0 0.0 0.0 0.0, 1.0, 0.0 \ 1246 0.0 0.0 0.0 0.0, 0.0, 1.0" kittens.png 1247 </code></pre> 1248 <div style="margin: auto;"> 1249 <h3><a class="anchor" id="colorspace"></a>-colorspace <var>value</var></h3> 1250 </div> 1251 1252 <p class="magick-description">Set the image colorspace.</p> 1253 1254 <p>Choices are:</p> 1255 1256 <pre class="highlight"><code>CMY CMYK Gray HCL 1257 HCLp HSB HSI HSL 1258 HSV HWB Lab LCHab 1259 LCHuv LMS Log Luv 1260 OHTA Rec601YCbCr Rec709YCbCr RGB 1261 scRGB sRGB Transparent xyY 1262 XYZ YCbCr YCC YDbDr 1263 YIQ YPbPr YUV Undefined 1264 </code></pre> 1265 1266 <p>To print a complete list of colorspaces, use <a href="command-line-options.html#list">-list colorspace</a>.</p> 1267 1268 <p>For a more accurate color conversion to or from the linear RGB, CMYK, or grayscale colorspaces, use the <a href="command-line-options.html#profile">-profile</a> option. Note, ImageMagick assumes the sRGB colorspace if the image format does not indicate otherwise. For colorspace conversion, the gamma function is first removed to produce linear RGB.</p> 1269 1270 <table class="table table-sm table-striped"> 1271 <caption>Conversion of RGB to Other Color Spaces</caption> 1272 <tr><th valign="middle">CMY</th></tr> 1273 <tr><td valign="middle">C=<var>QuantumRange</var>R</td></tr> 1274 <tr><td valign="middle">M=<var>QuantumRange</var>G</td></tr> 1275 <tr><td valign="middle">Y=<var>QuantumRange</var>B</td></tr> 1276 <tr><th valign="middle">CMYK starts with CMY from above</th></tr> 1277 <tr><td valign="middle">K=min(C,Y,M)</td></tr> 1278 <tr><td valign="middle">C=<var>QuantumRange</var>*(CK)/(<var>QuantumRange</var>K)</td></tr> 1279 <tr><td valign="middle">M=<var>QuantumRange</var>*(MK)/(<var>QuantumRange</var>K)</td></tr> 1280 <tr><td valign="middle">Y=<var>QuantumRange</var>*(YK)/(<var>QuantumRange</var>K)</td></tr> 1281 1282 <tr><th valign="middle">Gray</th></tr> 1283 <tr><td valign="middle">Gray = 0.212656*R+0.715158*G+0.072186*B</td></tr> 1284 1285 <tr><th valign="middle">HSB Hue, Saturation, Brightness; like a cone peak downward</th></tr> 1286 <tr><td valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr> 1287 <tr><td valign="middle">S=distance from axis outward</td></tr> 1288 <tr><td valign="middle">B=distance along axis from bottom upward; B=max(R,G,B); <var>intensity-like</var></td></tr> 1289 1290 <tr><th valign="middle">HSL Hue, Saturation, Lightness; like a double cone end-to-end with peaks at very top and bottom</th></tr> 1291 <tr><td valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr> 1292 <tr><td valign="middle">S=distance from axis outward</td></tr> 1293 <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> 1294 1295 <tr><th valign="middle">HWB Hue, Whiteness, Blackness</th></tr> 1296 <tr><td valign="middle">Hue (complicated equation)</td></tr> 1297 <tr><td valign="middle">Whiteness (complicated equation)</td></tr> 1298 <tr><td valign="middle">Blackness (complicated equation)</td></tr> 1299 1300 <tr><th valign="middle">LAB</th></tr> 1301 <tr><td valign="middle">L (complicated equation relating X,Y,Z)</td></tr> 1302 <tr><td valign="middle">A (complicated equation relating X,Y,Z)</td></tr> 1303 <tr><td valign="middle">B (complicated equation relating X,Y,Z)</td></tr> 1304 <tr><th valign="middle">LinearGray</th></tr> 1305 <tr><td valign="middle">LinearGray = 0.298839*R+0.586811*G+0.114350*B</td></tr> 1306 1307 <tr><th valign="middle">LOG</th></tr> 1308 <tr><td valign="middle">I1 (complicated equation involving logarithm of R)</td></tr> 1309 <tr><td valign="middle">I2 (complicated equation involving logarithm of G)</td></tr> 1310 <tr><td valign="middle">I3 (complicated equation involving logarithm of B)</td></tr> 1311 1312 <tr><th valign="middle">OHTA approximates principal components transformation</th></tr> 1313 <tr><td valign="middle">I1=0.33333*R+0.33334*G+0.33333*B; <var>intensity-like</var></td></tr> 1314 <tr><td valign="middle">I2=(0.50000*R+0.00000*G0.50000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1315 <tr><td valign="middle">I3=(0.25000*R+0.50000*G0.25000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1316 1317 <tr><th valign="middle">Rec601Luma</th></tr> 1318 <tr><td valign="middle">Gray = 0.298839*R+0.586811*G+0.114350*B</td></tr> 1319 1320 <tr><th valign="middle">Rec601YCbCr</th></tr> 1321 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1322 <tr><td valign="middle">Cb=(0.168736*R-0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1323 <tr><td valign="middle">Cr=(0.500000*R0.418688*G0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1324 1325 <tr><th valign="middle">Rec709Luma</th></tr> 1326 <tr><td valign="middle">Gray=0.212656*R+0.715158*G+0.072186*B</td></tr> 1327 1328 <tr><th valign="middle">Rec709YCbCr</th></tr> 1329 <tr><td valign="middle">Y=0.212656*R+0.715158*G+0.072186*B; <var>intensity-like</var></td></tr> 1330 <tr><td valign="middle">Cb=(0.114572*R0.385428*G+0.500000*B)+(<var>QuantumRange</var>+1)/2</td></tr> 1331 <tr><td valign="middle">Cr=(0.500000*R0.454153*G0.045847*B)+(<var>QuantumRange</var>+1)/2</td></tr> 1332 <tr><th valign="middle">sRGB</th></tr> 1333 <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> 1334 <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> 1335 <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> 1336 1337 <tr><th valign="middle">XYZ</th></tr> 1338 <tr><td valign="middle">X=0.4124564*R+0.3575761*G+0.1804375*B</td></tr> 1339 <tr><td valign="middle">Y=0.2126729*R+0.7151522*G+0.0721750*B</td></tr> 1340 <tr><td valign="middle">Z=0.0193339*R+0.1191920*G+0.9503041*B</td></tr> 1341 1342 <tr><th valign="middle">YCC</th></tr> 1343 <tr><td valign="middle">Y=(0.298839*R+0.586811*G+0.114350*B) (with complicated scaling); <var>intensity-like</var></td></tr> 1344 <tr><td valign="middle">C1=(0.298839*R0.586811*G+0.88600*B) (with complicated scaling)</td></tr> 1345 <tr><td valign="middle">C2=(0.70100*R0.586811*G0.114350*B) (with complicated scaling)</td></tr> 1346 1347 <tr><th valign="middle">YCbCr</th></tr> 1348 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1349 <tr><td valign="middle">Cb=(0.168736*R0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1350 <tr><td valign="middle">Cr=(0.500000*R0.418688*G0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1351 1352 <tr><th valign="middle">YIQ</th></tr> 1353 <tr><td valign="middle">Y=0.298839*R+0.586811*G+0.114350*B; <var>intensity-like</var></td></tr> 1354 <tr><td valign="middle">I=(0.59600*R0.27400*G0.32200*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1355 <tr><td valign="middle">Q=(0.21100*R0.52300*G+0.31200*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1356 1357 <tr><th valign="middle">YPbPr</th></tr> 1358 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr> 1359 <tr><td valign="middle">Pb=(0.168736*R0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1360 <tr><td valign="middle">Pr=(0.500000*R0.418688*G0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1361 1362 <tr><th valign="middle">YUV</th></tr> 1363 <tr><td valign="middle">Y=0.298839*R+0.586811*G+0.114350*B; <var>intensity-like</var></td></tr> 1364 <tr><td valign="middle">U=(0.14740*R0.28950*G+0.43690*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1365 <tr><td valign="middle">V=(0.61500*R0.51500*G0.10000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1366 </table> 1367 1368 <p>Note the scRGB colorspace requires HDRI support otherwise it behaves just like linear RGB.</p> 1369 1370 <p>Use the <code>Undefined</code> colorspace to identify multi-spectral images.</p> 1371 1372 <div style="margin: auto;"> 1373 <h3><a class="anchor" id="combine"></a>-combine</h3> 1374 <h3>+combine <var>colorspace</var></h3> 1375 </div> 1376 1377 <p class="magick-description">Combine one or more images into a single image.</p> 1378 1379 <p>The channels (previously set by <a href="command-line-options.html#channel">-channel</a>) of the 1380 combined image are taken from the grayscale values of each image in the 1381 sequence, in order. For the default -channel setting of <code>RGB</code>, this 1382 means the first image is assigned to the <code>Red</code> channel, the second 1383 to the <code>Green</code> channel, the third to the <code>Blue</code>.</p> 1384 1385 <p>This option can be thought of as the inverse to <a 1386 href="command-line-options.html#separate">-separate</a>, so long as the channel settings are the same. 1387 Thus, in the following example, the final image should be a copy of the 1388 original. </p> 1389 1390 <pre class="highlight"><code>convert original.png -channel RGB -separate sepimage.png 1391 convert sepimage-0.png sepimage-1.png sepimage-2.png -channel RGB \ 1392 -combine imagecopy.png 1393 </code></pre> 1394 1395 <div style="margin: auto;"> 1396 <h3><a class="anchor" id="comment"></a>-comment <var>string</var></h3> 1397 </div> 1398 1399 <p class="magick-description">Embed a comment in an image.</p> 1400 1401 <p>This option sets the comment meta-data of an image read in after this 1402 option has been given. To modify a comment of images already in memory use 1403 "<code><a href="command-line-options.html#set">-set</a> comment</code>". </p> 1404 1405 <p>The comment can contain special format characters listed in the <a 1406 href="../www/escape.html">Format and 1407 Print Image Properties</a>. These attributes are expanded when the comment 1408 is finally assigned to the individual images. </p> 1409 1410 <p>If the first character of <var>string</var> is <var>@</var>, the image comment is read from a file titled by the 1411 remaining characters in the string. Comments read in from a file are literal; 1412 no embedded formatting characters are recognized.</p> 1413 1414 <p>Comment meta-data are not visible on the image itself. To do that use the 1415 <a href="command-line-options.html#annotate">-annotate</a> or <a href="command-line-options.html#draw">-draw</a> options 1416 instead.</p> 1417 1418 <p>For example,</p> 1419 1420 <pre class="highlight"><code>-comment "%m:%f %wx%h" bird.miff 1421 </code></pre> 1422 1423 <p>produces an image comment of <code>MIFF:bird.miff 512x480</code> (assuming 1424 that the image <code>bird.miff</code> has a width of 512 and a height of 1425 480.</p> 1426 1427 <div style="margin: auto;"> 1428 <h3><a class="anchor" id="compare"></a>-compare</h3> 1429 </div> 1430 1431 <p class="magick-description">mathematically and visually annotate the difference between an image and its reconstruction</p> 1432 1433 <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> 1434 1435 <pre class="highlight"><code>convert image.png reference.png -metric RMSE -compare \ <br/> difference.png 1436 </code></pre> 1437 1438 <p>To get the metric value use the string format "%[distortion]".</p> 1439 1440 <pre class="highlight"><code>convert image.png reference.png -metric RMSE -compare -format \ 1441 "%[distortion]" info: 1442 </code></pre> 1443 1444 <div style="margin: auto;"> 1445 <h3><a class="anchor" id="complex"></a>-complex <var>operator</var></h3> 1446 </div> 1447 1448 <p class="magick-description">perform complex mathematics on an image sequence</p> 1449 1450 Choose from these operators: 1451 1452 <pre class="highlight"><code>add 1453 conjugate 1454 divide 1455 magnitude-phase 1456 multiply 1457 real-imaginary 1458 subtract 1459 </code></pre> 1460 1461 <p>Optionally specify the <code>divide</code> operator SNR with <code><a href="command-line-options.html#define">-define</a> complex:snr=float</code>.</p> 1462 1463 <div style="margin: auto;"> 1464 <h3><a class="anchor" id="compose"></a>-compose <var>operator</var></h3> 1465 </div> 1466 1467 <p class="magick-description">Set the type of image composition.</p> 1468 1469 <p>See <a href="../www/compose.html">Alpha Compositing</a> for 1470 a detailed discussion of alpha compositing.</p> 1471 1472 <p>This setting affects image processing operators that merge two (or more) 1473 images together in some way. This includes the operators, 1474 <a href="command-line-options.html#composite">-compare</a>, 1475 <a href="command-line-options.html#composite">-composite</a>, 1476 <a href="command-line-options.html#layers">-layers</a> composite, 1477 <a href="command-line-options.html#flatten">-flatten</a>, 1478 <a href="command-line-options.html#mosaic">-mosaic</a>, 1479 <a href="command-line-options.html#layers">-layers</a> merge, 1480 <a href="command-line-options.html#border">-border</a>, 1481 <a href="command-line-options.html#frame">-frame</a>, 1482 and <a href="command-line-options.html#extent">-extent</a>. </p> 1483 1484 <p>It is also one of the primary options for the "<code>composite</code>" 1485 command. </p> 1486 1487 1488 <div style="margin: auto;"> 1489 <h3><a class="anchor" id="composite"></a>-composite</h3> 1490 </div> 1491 1492 <p class="magick-description">Perform alpha composition on two images and an optional mask</p> 1493 1494 <p>Take the first image 'destination' and overlay the second 'source' image 1495 according to the current <a href="command-line-options.html#compose">-compose</a> setting. The location 1496 of the 'source' or 'overlay' image is controlled according to <a 1497 href="command-line-options.html#gravity" >-gravity</a>, and <a href="command-line-options.html#geometry" >-geometry</a> 1498 settings. </p> 1499 1500 <p>If a third image is given this is treated as a grayscale blending 'mask' image 1501 relative to the first 'destination' image. This mask is blended with the 1502 source image. However for the '<code>displace</code>' compose method, the 1503 mask is used to provide a separate Y-displacement image instead. </p> 1504 1505 <p>If a <a href="command-line-options.html#compose">-compose</a> method requires extra numerical 1506 arguments or flags these can be provided by setting the <a 1507 href="command-line-options.html#set">-set</a> '<code>option:compose:args</code>' 1508 appropriately for the compose method. </p> 1509 1510 <p>Some <a href="command-line-options.html#compose">-compose</a> methods can modify the 'destination' 1511 image outside the overlay area. It is disabled by default. You can enable this by setting the this define: <a href="command-line-options.html#define">-define</a> '<code>compose:clip-to-self=true</code>'.</p> 1512 1513 <p>The SVG compositing specification requires that color and opacity values range between zero and QuantumRange inclusive. You can permit values outside this range with this option: <a href="command-line-options.html#set">-set</a> '<code>option:compose:clamp=false</code></p> 1514 1515 1516 <div style="margin: auto;"> 1517 <h3><a class="anchor" id="compress"></a>-compress <var>type</var></h3> 1518 </div> 1519 1520 <p class="magick-description">Use pixel compression specified by <var>type</var> when writing the image.</p> 1521 1522 <p>Choices are: <code>None</code>, <code>BZip</code>, <code 1523 >Fax</code>, <code>Group4</code>, <code 1524 >JPEG</code>, <code>JPEG2000</code>, <code 1525 >Lossless</code>, <code>LZW</code>, <code 1526 >RLE</code> or <code>Zip</code>.</p> 1527 1528 <p>To print a complete list of compression types, use <a href="command-line-options.html#list">-list 1529 compress</a>.</p> 1530 1531 <p>Specify <a href="command-line-options.html#compress">+compress</a> to store the binary image in an 1532 uncompressed format. The default is the compression type of the specified 1533 image file.</p> 1534 1535 <p>If <code>LZW</code> compression is specified but LZW compression has not been 1536 enabled, the image data is written in an uncompressed LZW format that can be 1537 read by LZW decoders. This may result in larger-than-expected GIF files.</p> 1538 1539 <p><code>Lossless</code> refers to lossless JPEG, which is only available if the 1540 JPEG library has been patched to support it. Use of lossless JPEG is generally 1541 not recommended.</p> 1542 1543 <p> 1544 When writing an ICO file, you may request that the images be encoded in 1545 PNG format, by specifying <code>Zip</code> compression.</p> 1546 1547 <p> 1548 When writing a JNG file, specify <code>Zip</code> compression to request that 1549 the alpha channel be encoded in PNG "IDAT" format, or <code>JPEG</code> 1550 to request that it be encoded in JPG "JDAA" format.</p> 1551 1552 <p>Use the <a href="command-line-options.html#quality">-quality</a> option to set the compression level 1553 to be used by JPEG, PNG, MIFF, and MPEG encoders. 1554 Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to set the 1555 sampling factor to be used by JPEG, MPEG, and YUV encoders for down-sampling 1556 the chroma channels.</p> 1557 1558 <div style="margin: auto;"> 1559 <h3><a class="anchor" id="connected-components"></a>-connected-components <var>connectivity</var></h3> 1560 </div> 1561 1562 <p class="magick-description"><a href="../www/connected-components.html">connected-components</a> labeling detects connected regions in an image, choose from 4 or 8 way connectivity.</p> 1563 1564 <p>Use <code><a href="command-line-options.html#define" >-define</a> connected-components:verbose=true</code> to output statistics associated with each unique label.</p> 1565 1566 <div style="margin: auto;"> 1567 <h3><a class="anchor" id="contrast"></a>-contrast</h3> 1568 </div> 1569 1570 <p class="magick-description">Enhance or reduce the image contrast.</p> 1571 1572 <p>This option enhances the intensity differences between the lighter and 1573 darker elements of the image. Use <a href="command-line-options.html#contrast">-contrast</a> to enhance 1574 the image or <a href="command-line-options.html#contrast">+contrast</a> to reduce the image 1575 contrast.</p> 1576 1577 <p>For a more pronounced effect you can repeat the option:</p> 1578 1579 <pre class="highlight"><code>convert rose: -contrast -contrast rose_c2.png 1580 </code></pre> 1581 1582 <div style="margin: auto;"> 1583 <h3><a class="anchor" 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> 1584 </div> 1585 1586 <p class="magick-description">Increase the contrast in an image by <var>stretching</var> the range of intensity values.</p> 1587 1588 <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 1589 <var >black-point %</var> pixels and white-out at most <var>white-point %</var> pixels.</p> 1590 1591 <p>Prior to ImageMagick 6.4.7-0, <a href="command-line-options.html#contrast-stretch" 1592 >-contrast-stretch</a> will black-out at most <var>black-point</var> pixels and white-out at most <var >total pixels 1593 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> 1594 1595 <p>Note that <code>-contrast-stretch 0</code> will modify the image such that 1596 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 1597 clipping at either end. This is not the same as <a href="command-line-options.html#normalize" 1598 >-normalize</a>, which is equivalent to <code>-contrast-stretch 0.15x0.05%</code> (or 1599 prior to ImageMagick 6.4.7-0, <code>-contrast-stretch 2%x99%</code>).</p> 1600 1601 <p>Internally operator works by creating a histogram bin, and then uses that 1602 bin to modify the image. As such some colors may be merged together when they 1603 originally fell into the same 'bin'. </p> 1604 1605 <p>All the channels are normalized in concert by the same amount so as to 1606 preserve color integrity, when the default <a href="command-line-options.html#channel" >+channel</a> 1607 setting is in use. Specifying any other <a href="command-line-options.html#channel" >-channel</a> 1608 setting will normalize the RGB channels independently.</p> 1609 1610 <p>See also <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' 1611 normalization of mathematical images. </p> 1612 1613 <p>This operator is under review for re-development. </p> 1614 1615 1616 <div style="margin: auto;"> 1617 <h3><a class="anchor" id="convolve"></a>-convolve <var>kernel</var></h3> 1618 </div> 1619 1620 <p class="magick-description">Convolve an image with a user-supplied convolution kernel.</p> 1621 1622 <p>The <var>kernel</var> is a matrix specified as 1623 a comma-separated list of integers (with no spaces), ordered left-to right, 1624 starting with the top row. Presently, only odd-dimensioned kernels are 1625 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, 1626 7<sup>2</sup>=49, etc. </p> 1627 1628 <p>Note that the <a href="command-line-options.html#convolve">‑convolve</a> operator supports the <a href="command-line-options.html#bias">‑bias</a> setting. This option shifts the convolution so that 1629 positive and negative results are relative to a user-specified bias value. 1630 This is important for non-HDRI compilations of ImageMagick when dealing with 1631 convolutions that contain negative as well as positive values. This is 1632 especially the case with convolutions involving high pass filters or edge 1633 detection. Without an output bias, the negative values is clipped at zero. 1634 </p> 1635 1636 <p>When using an ImageMagick with the HDRI compile-time setting, <a href="command-line-options.html#bias">‑bias</a> is not needed, as ImageMagick is able to store/handle any 1637 negative results without clipping to the color value range (0..QuantumRange). 1638 See the discussion on HDRI implementations of ImageMagick on the page <a 1639 href="high-dynamic-range.html">High 1640 Dynamic-Range Images</a>. For more about HDRI go the ImageMagick <a 1641 href="../Usage/basics/#hdri">Usage</a> pages or this 1642 <a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> 1643 entry. </p> 1644 1645 1646 <div style="margin: auto;"> 1647 <h3><a class="anchor" id="copy"></a>-copy <var>geometry</var> <var>offset</var></h3> 1648 </div> 1649 1650 <p class="magick-description">copy pixels from one area of an image to another.</p> 1651 1652 <div style="margin: auto;"> 1653 <h3><a class="anchor" id="crop"></a>-crop <var>geometry</var>{<var>@</var>}{<var>!</var>}</h3> 1654 </div> 1655 1656 <p class="magick-description">Cut out one or more rectangular regions of the image.</p> 1657 1658 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 1659 1660 <p>The <var>width</var> and <var>height</var> of the <var>geometry</var> argument give the size of the image that remains 1661 after cropping, and <var>x</var> and <var>y</var> in the 1662 <var>offset</var> (if present) gives the location of the top left 1663 corner of the cropped image with respect to the original image. To specify the 1664 amount to be removed, use <a href="command-line-options.html#shave">-shave</a> instead.</p> 1665 1666 <p>If the <var>x</var> and <var>y</var> offsets are 1667 present, a single image is generated, consisting of the pixels from the 1668 cropping region. The offsets specify the location of the upper left corner of 1669 the cropping region measured downward and rightward with respect to the upper 1670 left corner of the image. If the <a href="command-line-options.html#gravity">-gravity</a> option is 1671 present with <code>NorthEast</code>, <code>East</code>, or <code>SouthEast</code> 1672 gravity, it gives the distance leftward from the right edge of the image to 1673 the right edge of the cropping region. Similarly, if the <a 1674 href="command-line-options.html#gravity">-gravity</a> option is present with <code>SouthWest</code>, 1675 <code>South</code>, or <code>SouthEast</code> gravity, the distance is measured 1676 upward between the bottom edges.</p> 1677 1678 <p>If the <var>x</var> and <var>y</var> offsets are 1679 omitted, a set of tiles of the specified geometry, covering the entire input 1680 image, is generated. The rightmost tiles and the bottom tiles are smaller if 1681 the specified geometry extends beyond the dimensions of the input image.</p> 1682 1683 <p>You can add the <var>@</var> to the geometry argument to equally divide the image into the number of tiles generated.</p> 1684 1685 <p>By adding a exclamation character flag to the geometry argument, the 1686 cropped images virtual canvas page size and offset is set as if the 1687 geometry argument was a viewport or window. This means the canvas page size 1688 is set to exactly the same size you specified, the image offset set 1689 relative top left corner of the region cropped. </p> 1690 1691 <p>If the cropped image 'missed' the actual image on its virtual canvas, a 1692 special single pixel transparent 'missed' image is returned, and a 'crop 1693 missed' warning given. </p> 1694 1695 <p>It might be necessary to <a href="command-line-options.html#repage" >+repage</a> the image prior to 1696 cropping the image to ensure the crop coordinate frame is relocated to the 1697 upper-left corner of the visible image. 1698 1699 Similarly you may want to use <a href="command-line-options.html#repage" >+repage</a> after cropping to 1700 remove the page offset that will be left behind. This is especially true when 1701 you are going to write to an image format such as PNG that supports an image 1702 offset.</p> 1703 1704 <div style="margin: auto;"> 1705 <h3><a class="anchor" id="cycle"></a>-cycle <var>amount</var></h3> 1706 </div> 1707 1708 <p class="magick-description">displace image colormap by amount.</p> 1709 1710 <p><var>Amount</var> defines the number of positions each 1711 colormap entry is shifted.</p> 1712 1713 1714 <div style="margin: auto;"> 1715 <h3><a class="anchor" id="debug"></a>-debug <var>events</var></h3> 1716 </div> 1717 1718 <p class="magick-description">enable debug printout.</p> 1719 1720 <p>The <code>events</code> parameter specifies which events are to be logged. It 1721 can be either <code>None</code>, <code>All</code>, <code>Trace</code>, or 1722 a comma-separated list consisting of one or more of the following domains: 1723 <code>Accelerate</code>, <code>Annotate</code>, <code>Blob</code>, <code>Cache</code>, 1724 <code>Coder</code>, <code>Configure</code>, <code>Deprecate</code>, 1725 <code>Exception</code>, <code>Locale</code>, <code>Render</code>, 1726 <code>Resource</code>, <code>Security</code>, <code>TemporaryFile</code>, 1727 <code>Transform</code>, <code>X11</code>, or <code>User</code>. </p> 1728 1729 1730 <p>For example, to log cache and blob events, use.</p> 1731 1732 <pre class="highlight"><code>convert -debug "Cache,Blob" rose: rose.png 1733 </code></pre> 1734 1735 <p>The <code>User</code> domain is normally empty, but developers can log user 1736 events in their private copy of ImageMagick.</p> 1737 1738 <p>To print the complete list of debug methods, use <a href="command-line-options.html#list">-list 1739 debug</a>.</p> 1740 1741 <p>Use the <a href="command-line-options.html#log">-log</a> option to specify the format for debugging 1742 output.</p> 1743 1744 <p>Use <a href="command-line-options.html#debug">+debug</a> to turn off all logging.</p> 1745 1746 <p>Debugging may also be set using the <code>MAGICK_DEBUG</code> <a href="resources.html#environment" 1747 >environment variable</a>. The allowed values for the <code>MAGICK_DEBUG</code> 1748 environment variable are the same as for the <a href="command-line-options.html#debug">-debug</a> 1749 option.</p> 1750 1751 1752 <div style="margin: auto;"> 1753 <h3><a class="anchor" id="decipher"></a>-decipher <var>filename</var></h3> 1754 </div> 1755 1756 <p class="magick-description">Decipher and restore pixels that were previously transformed by <a href="command-line-options.html#encipher">-encipher</a>.</p> 1757 1758 <p>Get the passphrase from the file specified by <var>filename</var>.</p> 1759 1760 <p>For more information, see the webpage, <a 1761 href="../www/cipher.html">ImageMagick: Encipher or 1762 Decipher an Image</a>.</p> 1763 1764 1765 <div style="margin: auto;"> 1766 <h3><a class="anchor" id="deconstruct"></a>-deconstruct</h3> 1767 </div> 1768 1769 <p class="magick-description">find areas that has changed between images </p> 1770 1771 <p>Given a sequence of images all the same size, such as produced by <a 1772 href="command-line-options.html#coalesce">-coalesce</a>, replace the second and later images, with 1773 a smaller image of just the area that changed relative to the previous image. 1774 </p> 1775 1776 <p>The resulting sequence of images can be used to optimize an animation 1777 sequence, though will not work correctly for GIF animations when parts of the 1778 animation can go from opaque to transparent. </p> 1779 1780 <p>This option is actually equivalent to the <a href="command-line-options.html#layers">-layers</a> 1781 method '<code>compare-any</code>'. </p> 1782 1783 1784 <div style="margin: auto;"> 1785 <h3><a class="anchor" id="define"></a>-define <var>key</var>{<var>=value</var>}<var>...</var></h3> 1786 </div> 1787 1788 <p class="magick-description">add specific global settings generally used to control coders and image processing operations.</p> 1789 1790 <p>This option creates one or more definitions for coders and decoders to use 1791 while reading and writing image data. Definitions are generally used to 1792 control image file format coder modules, and image processing operations, 1793 beyond what is provided by normal means. Defined settings are listed in <a 1794 href="command-line-options.html#verbose" >-verbose</a> information ("<code>info:</code>" output format) 1795 as "Artifacts". </p> 1796 1797 <p>If <var>value</var> is missing for a definition, an empty-valued 1798 definition of a flag is created with that name. This used to control on/off 1799 options. Use <a href="command-line-options.html#define">+define key</a> to remove definitions 1800 previously created. Use <a href="command-line-options.html#define">+define "*"</a> to remove all 1801 existing definitions.</p> 1802 1803 <p>The same 'artifact' settings can also be defined using the <a 1804 href="command-line-options.html#set" >-set "option:<var>key</var>" "<var>value</var>"</a> option, which also allows the use of <a href="../www/escape.html" >Format and Print Image 1805 Properties</a> in the defined value. </p> 1806 1807 <p>The <var>option</var> and <var>key</var> are case-independent (they are 1808 converted to lowercase for use within the decoders) while the <var>value</var> 1809 is case-dependent.</p> 1810 1811 <p>Such settings are global in scope, and affect all images and operations. </p> 1812 1813 <p>The following definitions are just some of the artifacts that are 1814 available:</p> 1815 1816 <table class="table table-sm table-striped"> 1817 <tr> 1818 <td>bmp3:alpha=<var>true|false</var></td> 1819 <td>include any alpha channel when writing in the BMP image format.</td> 1820 </tr> 1821 1822 <tr> 1823 <td>bmp:format=<var>value</var></td> 1824 <td> valid values are <var>bmp2</var>, <var>bmp3</var>, 1825 and <var>bmp4</var>. This option can be useful when the 1826 method of prepending "BMP2:" to the output filename is inconvenient or 1827 is not available, such as when using the <a href="mogrify.html">mogrify</a> utility.</td> 1828 </tr> 1829 1830 <tr> 1831 <td>bmp:subtype=<var>RGB555|RGB565|ARGB4444|ARGB1555</var></td> 1832 <td>BMP channel depth subtypes. Only support in BMP (BMP4). BMP3 and BMP2 do not 1833 contain header fields to support these options.</td> 1834 </tr> 1835 1836 <tr> 1837 <td>colorspace:auto-grayscale=<var>on|off</var></td> 1838 <td>prevent automatic conversion to grayscale inside coders that support 1839 grayscale. This should be accompanied by -type truecolor. PNG and TIF do 1840 not need this define. With PNG, just use PNG24:image. With TIF, just use 1841 -type truecolor. JPG and PSD will need this define.</td> 1842 </tr> 1843 1844 <tr> 1845 <td>complex:snr=<var>value</var></td> 1846 <td>Set the divide SNR constant<a href="command-line-options.html#complex">-complex</a>.</td> 1847 </tr> 1848 1849 <tr> 1850 <td>compose:args=<var>arguments</var></td> 1851 <td>Sets certain compose argument values when using convert ... -compose ... 1852 -composite. See <a href="compose.html" 1853 >Image Composition</a>.</td> 1854 </tr> 1855 1856 <tr> 1857 <td>compose:clip-to-self=<var>true|false</var></td> 1858 <td>Some <a href="command-line-options.html#compose" >-compose</a> methods can modify the 'destination' image outside the overlay area. It is disabled by default.</td> 1859 </tr> 1860 1861 <tr> 1862 <td>compose:clamp=<var>on|off</var></td> 1863 <td>set each pixel whose value is below zero to zero and any the pixel 1864 whose value is above the quantum range to the quantum range (e.g. 65535) 1865 otherwise the pixel value remains unchanged. Define supported in 1866 ImageMagick 6.9.1-3 and above.</td> 1867 </tr> 1868 1869 <tr> 1870 <td>connected-components:area-threshold=<var>value</var></td> 1871 <td>Merges any region with area smaller than <var>value</var> into its surrounding region or largest neighbor.</td> 1872 </tr> 1873 1874 <tr> 1875 <td>connected-components:keep=<var>list-of-ids</var></td> 1876 <td>Comma and/or hyphenated list of id values to keep in the output. 1877 Supported in Imagemagick 6.9.3-0.</td> 1878 </tr> 1879 1880 <tr> 1881 <td>connected-components:mean-color=<var>true</var></td> 1882 <td>Changes the output image from id values to mean color values. Supported 1883 in Imagemagick 6.9.2-8.</td> 1884 </tr> 1885 1886 <tr> 1887 <td>connected-components:remove=<var>list-of-ids</var></td> 1888 <td>Comma and/or hyphenated list of id values to remove from the output. 1889 Supported in Imagemagick 6.9.2-9.</td> 1890 </tr> 1891 1892 <tr> 1893 <td>connected-components:verbose=<var>true</var></td> 1894 <td>Lists id, bounding box, centroid, area, mean color for each region.</td> 1895 </tr> 1896 1897 <tr> 1898 <td>convolve:scale=<var>{kernel_scale}[!^] [,{origin_addition}] [%]</var></td> 1899 <td>Defines the kernel scaling. The special flag ! automatically scales to 1900 full dynamic range. The ! flag can be used in combination with a factor or 1901 percent. The factor or percent is then applied after the automatic scaling. 1902 An example is 50%!. This produces a result 50% darker than full dynamic 1903 range scaling. The ^ flag assures the kernel is 'zero-summing', for 1904 example when some values are positive and some are negative as in edge 1905 detection kernels. The origin addition adds that value to the center 1906 pixel of the kernel. This produces an effect that is like adding the image 1907 that many times to the result of the filtered image. The typical value 1908 is 1 so that the original image is added to the result of the convolution. 1909 The default is 0.</td> 1910 </tr> 1911 1912 <tr> 1913 <td>morphology:showKernel=<var>1</var></td> 1914 <td>Outputs (to 'standard error') all the information about a specified <a 1915 href="command-line-options.html#morphology" >-morphology convolve</a> kernel.</td> 1916 </tr> 1917 1918 <tr> 1919 <td>dcm:display-range=<var>reset</var></td> 1920 <td>Sets the display range to the minimum and maximum pixel values for the 1921 DCM image format.</td> 1922 </tr> 1923 1924 <tr> 1925 <td>dds:cluster-fit=<var>true|false</var></td> 1926 <td>Enables the dds cluster-fit.</td> 1927 </tr> 1928 1929 <tr> 1930 <td>dds:compression=<var>dxt1|dxt5|none</var></td> 1931 <td>Sets the dds compression.</td> 1932 </tr> 1933 1934 <tr> 1935 <td>dds:mipmaps=<var>value</var></td> 1936 <td>Sets the dds number of mipmaps.</td> 1937 </tr> 1938 1939 <tr> 1940 <td>dds:weight-by-alpha=<var>true|false</var></td> 1941 <td>Enables the dds alpha weighting.</td> 1942 </tr> 1943 1944 <tr> 1945 <td>deskew:auto-crop=<var>true</var></td> 1946 <td>auto crop the image after deskewing.</td> 1947 </tr> 1948 1949 <tr> 1950 <td>delegate:bimodal=<var>true</var></td> 1951 <td>Specifies direct conversion from Postscript to PDF.</td> 1952 </tr> 1953 1954 <tr> 1955 <td>distort:scale=<var>value</var></td> 1956 <td>Sets the output scaling factor for use with <a href="command-line-options.html#distort" 1957 >-distort</a>.</td> 1958 </tr> 1959 1960 <tr> 1961 <td>distort:viewport=<var>WxH+X+Y</var></td> 1962 <td>Sets the viewport for use with <a href="command-line-options.html#distort">-distort</a>.</td> 1963 </tr> 1964 1965 <tr> 1966 <td>dot:layout-engine=<var>value</var></td> 1967 <td>Specifies the layout engine for the DOT image format (e.g. 1968 <code>neato</code>).</td> 1969 </tr> 1970 1971 <tr> 1972 <td>exr:color-type=<var>value</var></td> 1973 <td>Specifies the color type for the EXR format: RGB, RGBA, YC, YCA, Y, YA, R, G, B, A).</td> 1974 </tr> 1975 1976 <tr> 1977 <td>filter:option=<var>value</var></td> 1978 <td>Set a filter option for use with <a href="command-line-options.html#resize">-resize</a>. 1979 See <a href="command-line-options.html#filter">-filter</a> for details.</td> 1980 </tr> 1981 1982 <tr> 1983 <td>fourier:normalize=<var>inverse</var></td> 1984 <td>Sets the location for the FFT/IFT normalization as use by 1985 <a href="command-line-options.html#fft">+-fft</a> and <a href="command-line-options.html#ift">+-ift</a>. The default is 1986 <var>forward</var>.</td> 1987 </tr> 1988 1989 <tr> 1990 <td>h:format=<var>value</var></td> 1991 <td>Set the image encoding format use when writing a C-style header. 1992 <var>format</var> can be any output format supported by ImageMagick 1993 except for <var>h</var> and <var>magick</var>. If this 1994 option is omitted, the default is <var>GIF</var> for PseudoClass 1995 images and <var>PNM</var> for DirectClass images. 1996 </td> 1997 </tr> 1998 1999 <tr> 2000 <td>hough-lines:accumulator=true</td> 2001 <td>Returns the accumulator image in addition to the lines image.</td> 2002 </tr> 2003 2004 <tr> 2005 <td>heic:preserve-orientation</td> 2006 <td>Preserve the original EXIF orientation during HEIC decoding and rotate the pixels accordingly. 2007 By default, EXIF orientation is reset to "1" to match the actual orientation of pixels in HEIC. 2008 </td> 2009 </tr> 2010 2011 <tr> 2012 <td>icon:auto-resize</td> 2013 <td>Automatically stores multiple sizes when writing an ico image 2014 (requires a 256x256 input image).</td> 2015 </tr> 2016 2017 <tr> 2018 <td>identify:locate=<var>minimum|maximum</var></td> 2019 <td>Locates the coordinates of one or more image minimum or maximum.</td> 2020 </tr> 2021 2022 <tr> 2023 <td>identify:limit=<var>number</var></td> 2024 <td>Locates the coordinates for the number of minima or maxima specified.</td> 2025 </tr> 2026 2027 <tr> 2028 <td>jp2:layer-number=<var>value</var></td> 2029 <td>Sets the maximum number of quality layers to decode. Same for JPT, JC2, 2030 and J2K.</td> 2031 </tr> 2032 2033 <tr> 2034 <td>jp2:number-resolutions=<var>value</var></td> 2035 <td>Sets the number of resolutions to encode.Same for JPT, JC2, and 2036 J2K.</td> 2037 </tr> 2038 2039 <tr> 2040 <td>jp2:progression-order=<var>value</var></td> 2041 <td>choose from LRCP, RLCP, RPCL, PCRL or CPRL. Same for JPT, JC2, and 2042 J2K.</td> 2043 </tr> 2044 2045 <tr> 2046 <td>jp2:quality=<var>value,value...</var></td> 2047 <td>Sets the quality layer PSNR, given in dB. The order is from left to 2048 right in ascending order. The default is a single lossless quality layer. 2049 Same for JPT, JC2, and J2K.</td> 2050 </tr> 2051 2052 <tr> 2053 <td>jp2:rate=<var>value</var></td> 2054 <td>Specify the compression factor to use while writing JPEG-2000 files. 2055 The compression factor is the reciprocal of the compression ratio. The 2056 valid range is 0.0 to 1.0, with 1.0 indicating lossless compression. If 2057 defined, this value overrides the -quality setting. A quality setting 2058 of 75 results in a rate value of 0.06641. Same for JPT, JC2, and J2K.</td> 2059 </tr> 2060 2061 <tr> 2062 <td>jp2:reduce-factor=<var>value</var></td> 2063 <td>Sets the number of highest resolution levels to be discarded.Same for 2064 JPT, JC2, and J2K.</td> 2065 </tr> 2066 2067 <tr> 2068 <td>jpeg:block-smoothing=<var>on|off</var></td> 2069 <td> </td> 2070 </tr> 2071 2072 <tr> 2073 <td>jpeg:colors=<var>value</var></td> 2074 <td>Set the desired number of colors and let the JPEG encoder do the 2075 quantizing.</td> 2076 </tr> 2077 2078 <tr> 2079 <td>jpeg:dct-method=<var>value</var></td> 2080 <td>Choose from <code>default</code>, <code>fastest</code>, 2081 <code>float</code>, <code>ifast</code>, and <code>islow</code>.</td> 2082 </tr> 2083 2084 <tr> 2085 <td>jpeg:extent=<var>value</var></td> 2086 <td>Restrict the maximum JPEG file size, for example <code>-define 2087 jpeg:extent=400KB</code>. The JPEG encoder will search for the highest 2088 compression quality level that results in an output file that does not 2089 exceed the value. The <code>-quality</code> option also will be respected 2090 starting with version 6.9.2-5. Between 6.9.1-0 and 6.9.2-4, add -quality 2091 100 in order for the jpeg:extent to work properly. Prior to 6.9.1-0, the 2092 -quality setting was ignored.</td> 2093 </tr> 2094 2095 <tr> 2096 <td>jpeg:fancy-upsampling=<var>on|off</var></td> 2097 <td> </td> 2098 </tr> 2099 2100 <tr> 2101 <td>jpeg:optimize-coding=<var>on|off</var></td> 2102 <td> </td> 2103 </tr> 2104 2105 <tr> 2106 <td>jpeg:q-table=<var>table</var></td> 2107 <td> </td> 2108 </tr> 2109 2110 <tr> 2111 <td>jpeg:sampling-factor=<var>sampling-factor-string</var></td> 2112 <td> </td> 2113 </tr> 2114 2115 <tr> 2116 <td>jpeg:size=<var>geometry</var></td> 2117 <td>Set the size hint of a JPEG image, for 2118 example, <code>-define jpeg:size=128x128</code>. 2119 It is most useful for increasing performance and reducing the memory 2120 requirements when reducing the size of a large JPEG image.</td> 2121 </tr> 2122 2123 <tr> 2124 <td>json:features</td> 2125 <td>includes features in verbose information.</td> 2126 </tr> 2127 2128 <tr> 2129 <td>json:limit</td> 2130 <td> </td> 2131 </tr> 2132 2133 <tr> 2134 <td>json:locate</td> 2135 <td> </td> 2136 </tr> 2137 2138 <tr> 2139 <td>json:moments</td> 2140 <td>includes image moments in verbose information.</td> 2141 </tr> 2142 2143 <tr> 2144 <td>magick:format=<var>value</var></td> 2145 <td>Set the image encoding format use when writing a C-style header. 2146 This is the same as "h:format=format" described above.</td> 2147 </tr> 2148 2149 <tr> 2150 <td>mng:need-cacheoff</td> 2151 <td>turn playback caching off for streaming MNG.</td> 2152 </tr> 2153 2154 <tr> 2155 <td>morphology:compose=<var>compose-method</var></td> 2156 <td>Specifies how to merge results generated by multiple<a 2157 href="command-line-options.html#morphology" >-morphology</a> kernel. The default is none. One 2158 typical value is 'lighten' as used, for example, with the sobel edge 2159 kernels. </td> 2160 </tr> 2161 2162 <tr> 2163 <td>morphology:showKernel=<var>1</var></td> 2164 <td>Outputs (to 'standard error') all the information about a generated <a 2165 href="command-line-options.html#morphology" >-morphology</a> kernel.</td> 2166 </tr> 2167 2168 <tr> 2169 <td>pcl:fit-to-page=<var>true</var></td> 2170 </tr> 2171 2172 <tr> 2173 <td>pdf:fit-page=<var>geometry</var></td> 2174 <td> geometry specifies the scaling dimensions for resizing when the PDF is 2175 being read. The geometry is either WxH{%} or page size. No offsets are 2176 allowed. (introduced in IM 6.8.8-8)</td> 2177 </tr> 2178 2179 <tr> 2180 <td>pdf:fit-to-page=<var>true</var></td> 2181 <td> </td> 2182 </tr> 2183 2184 <tr> 2185 <td>pdf:use-cropbox=<var>true</var></td> 2186 <td> </td> 2187 </tr> 2188 2189 <tr> 2190 <td>pdf:use-trimbox=<var>true</var></td> 2191 <td> </td> 2192 </tr> 2193 2194 <tr> 2195 <td>pdf:stop-on-error=<var>true</var></td> 2196 <td> </td> 2197 </tr> 2198 2199 <tr> 2200 <td>pdf:pdf:page-direction=<var>right-to-left</var></td> 2201 <td> </td> 2202 </tr> 2203 2204 <tr> 2205 <td>phash:colorspaces=<var>colorspace,colorspace,...</var></td> 2206 <td>the perceptual hash defaults to the sRGB and HCLp colorspaces. When 2207 using this define, you can specify up to six alternative colorspaces. (as 2208 of IM 7.0.3-8)</td> 2209 </tr> 2210 2211 <tr> 2212 <td>phash:normalize=<var>true</var></td> 2213 <td>normalizes the phash metric by dividing by the number of channels 2214 specified by <code>-define phash:colorspaces</code> when using compare 2215 -metric phash. (as of IM 7.0.3-8)</td> 2216 </tr> 2217 2218 <tr> 2219 <td>png:bit-depth=<var>value</var></td> 2220 <td> </td> 2221 </tr> 2222 2223 <tr> 2224 <td>png:color-type=<var>value</var></td> 2225 <td>desired bit-depth and color-type for PNG output. You can force the PNG 2226 encoder to use a different bit-depth and color-type than it would have 2227 normally selected, but only if this does not cause any loss of image 2228 quality. Any attempt to reduce image quality is treated as an error and no 2229 PNG file is written. E.g., if you have a 1-bit black-and-white image, you 2230 can use these "defines" to cause it to be written as an 8-bit grayscale, 2231 indexed, or even a 64-bit RGBA. But if you have a 16-million color image, 2232 you cannot force it to be written as a grayscale or indexed PNG. If you 2233 wish to do this, you must use the appropriate <a href="command-line-options.html#depth">-depth</a>, 2234 <a href="command-line-options.html#colors">-colors</a>, or <a href="command-line-options.html#type">-type</a> directives to 2235 reduce the image quality prior to using the PNG encoder. Note that in 2236 indexed PNG files, "bit-depth" refers to the number of bits per index, 2237 which can be 1, 2, 4, or 8. In such files, the color samples always have 2238 8-bit depth.</td> 2239 </tr> 2240 2241 <tr> 2242 <td>png:compression-filter=<var>value</var></td> 2243 <td> valid values are 0 through 9. 0-4 are the corresponding PNG filters, 2244 5 means adaptive filtering except for images with a colormap, 6 means 2245 adaptive filtering for all images, 7 means MNG "loco" compression, 8 means 2246 Z_RLE strategy with adaptive filtering, and 9 means Z_RLE strategy with no 2247 filtering.</td> 2248 </tr> 2249 2250 <tr> 2251 <td>png:compression-level=<var>value</var></td> 2252 <td> valid values are 0 through 9, with 0 providing the least but fastest 2253 compression and 9 usually providing the best and always the slowest.</td> 2254 </tr> 2255 2256 <tr> 2257 <td>png:compression-strategy=<var>value</var></td> 2258 <td> valid values are 0 through 4, meaning default, filtered, huffman_only, 2259 rle, and fixed ZLIB compression strategy. If you are using an old zlib 2260 that does not support Z_RLE (before 1.2.0) or Z_FIXED (before 1.2.2.2), 2261 values 3 and 4, respectively, will use the zlib default strategy 2262 instead.</td> 2263 </tr> 2264 2265 <tr> 2266 <td>png:format=<var>value</var></td> 2267 <td> valid values are <var>png8</var>, <var>png24</var>, 2268 <var>png32</var>, <var>png48</var>, 2269 <var>png64</var>, and <var>png00</var>. 2270 This property can be useful for specifying 2271 the specific PNG format to be used, when the usual method of prepending the 2272 format name to the output filename is inconvenient, such as when writing 2273 a PNG-encoded ICO file or when using <a href="mogrify.html">mogrify</a>. 2274 Value = <var>png8</var> reduces the number of colors to 256, 2275 only one of which may be fully transparent, if necessary. The other 2276 values do not force any reduction of quality; it is an error to request 2277 a format that cannot represent the image data without loss (except that 2278 it is allowed to reduce the bit-depth from 16 to 8 for all formats). 2279 Value = <var>png24</var> and <var>png48</var> 2280 allow transparency, only if a single color is fully transparent and that 2281 color does not also appear in an opaque pixel; such transparency is 2282 written in a PNG <code>tRNS</code> chunk. 2283 Value = <var>png00</var> causes the image to inherit its 2284 color-type and bit-depth from the input image, if the input was also 2285 a PNG.</td> 2286 </tr> 2287 2288 <tr> 2289 <td>png:exclude-chunk=<var>value</var></td> 2290 2291 <tr> 2292 <td>png:include-chunk=<var>value</var></td> 2293 <td>ancillary chunks to be excluded from or included in PNG output. 2294 2295 <p>The <var>value</var> can be the name of a PNG chunk-type such 2296 as <var>bKGD</var>, a comma-separated list of chunk-names 2297 (which can include the word <var>date</var>, the word 2298 <var>all</var>, or the word <var>none</var>). 2299 Although PNG chunk-names are case-dependent, you can use all lowercase 2300 names if you prefer.</p> 2301 2302 <p>The "include-chunk" and "exclude-chunk" lists only affect the behavior 2303 of the PNG encoder and have no effect on the PNG decoder.</p> 2304 2305 <p>As a special case, if the <code>sRGB</code> chunk is excluded and 2306 the <code>gAMA</code> chunk is included, the <code>gAMA</code> chunk will 2307 only be written if gamma is not 1/2.2, since most decoders assume 2308 sRGB and gamma=1/2.2 when no colorspace information is included in 2309 the PNG file. Because the list is processed from left to right, you 2310 can achieve this with a single define:</p> 2311 2312 <pre class="highlight"><code>-define png:include-chunk=none,gAMA 2313 </code></pre> 2314 2315 <p>As a special case, if the <code>sRGB</code> chunk is not excluded and 2316 the PNG encoder recognizes that the image contains the sRGB ICC profile, 2317 the PNG encoder will write the <code>sRGB</code> chunk instead of the 2318 entire ICC profile. To force the PNG encoder to write the sRGB 2319 profile as an <code>iCCP</code> chunk in the output PNG instead of the 2320 <code>sRGB</code> chunk, exclude the <code>sRGB</code> chunk.</p> 2321 2322 <p>The critical PNG chunks <code>IHDR</code>, <code>PLTE</code>, 2323 <code>IDAT</code>, and <code>IEND</code> cannot be excluded. Any such 2324 entries appearing in the list will be ignored.</p> 2325 2326 <p>If the ancillary PNG <code>tRNS</code> chunk is excluded and the 2327 image has transparency, the PNG colortype is forced to be 4 or 6 2328 (GRAY_ALPHA or RGBA). If the image is not transparent, then the 2329 <code>tRNS</code> chunk isn't written anyhow, and there is no effect 2330 on the PNG colortype of the output image.</p> 2331 2332 <p>The <a href="command-line-options.html#strip">-strip</a> option does the equivalent of the 2333 following for PNG output:</p> 2334 2335 <pre class="highlight"><code>-define png:exclude-chunk=EXIF,iCCP,iTXt,sRGB,tEXt,zCCP,zTXt,date 2336 </code></pre> 2337 2338 <p>The default behavior is to include all known PNG ancillary chunks 2339 plus ImageMagick's private <code>vpAg</code> ("virtual page") chunk, 2340 and to exclude all PNG chunks that are unknown to ImageMagick, 2341 regardless of their PNG "copy-safe" status as described in the 2342 PNG specification.</p> 2343 2344 <p>Any chunk names that are not known to ImageMagick are ignored 2345 if they appear in either the "include-chunk" or "exclude-chunk" list. 2346 The ancillary chunks currently known to ImageMagick are 2347 <code>bKGD</code>, <code>cHRM</code>, <code>gAMA</code>, <code>iCCP</code>, 2348 <code>oFFs</code>, <code>pHYs</code>, <code>sRGB</code>, <code>tEXt</code>, 2349 <code>tRNS</code>, <code>vpAg</code>, and <code>zTXt</code>.</p> 2350 2351 <p>You can also put <code>date</code> in the list to include or exclude 2352 the "Date:create" and "Date:modify" text chunks that ImageMagick normally 2353 inserts in the output PNG.</p></td> 2354 </tr> 2355 2356 <tr> 2357 <td>png:ignore-crc[=<var>true</var>]</td> 2358 <td>When you know your image has no CRC or ADLER32 errors, this can speed up 2359 decoding. It is also helpful in debugging bug reports from "fuzzers".</td> 2360 </tr> 2361 2362 <tr> 2363 <td>png:preserve-colormap[=<var>true</var>]</td> 2364 <td>Use the existing image->colormap. Normally the PNG encoder will 2365 try to optimize the palette, eliminating unused entries and putting 2366 the transparent colors first. If this flag is set, that behavior 2367 is suppressed.</td> 2368 </tr> 2369 2370 <tr> 2371 <td>png:preserve-iCCP[=<var>true</var>]</td> 2372 <td>By default, the PNG decoder and encoder examine any ICC profile 2373 that is present, either from an <code>iCCP</code> chunk in the PNG 2374 input or supplied via an option, and if the profile is recognized 2375 to be the sRGB profile, converts it to the <code>sRGB</code> chunk. 2376 You can use <code>-define png:preserve-iCCP</code> to prevent 2377 this from happening; in such cases the <code>iCCP</code> chunk 2378 will be read or written and no <code>sRGB</code> chunk will be 2379 written. There are some ICC profiles that claim to be sRGB but 2380 have various errors that cause them to be rejected by libpng16; such 2381 profiles are recognized anyhow and converted to the <code>sRGB</code> 2382 chunk, but are rejected if the <code>-define png:preserve-iCCP</code> 2383 is present. Note that not all "sRGB" ICC profiles are recognized 2384 yet; we will add them to the list as we encounter them.</td> 2385 </tr> 2386 2387 <tr> 2388 <td>png:swap-bytes[=<var>true</var>]</td> 2389 <td>The PNG specification requires that any multi-byte integers be stored in 2390 network byte order (MSB-LSB endian). This option allows you to 2391 fix any invalid PNG files that have 16-bit samples stored incorrectly 2392 in little-endian order (LSB-MSB). The "-define png:swap-bytes" option 2393 must appear before the input filename on the commandline. The swapping 2394 is done during the libpng decoding operation.</td> 2395 </tr> 2396 2397 <tr> 2398 <td>profile:skip=<var>name1,name2,...</var></td> 2399 <td>Skip the named profile[s] when reading the image. Use skip="*" to 2400 skip all named profiles in the image. Many named profiles exist, 2401 including ICC, EXIF, APP1, IPTC, XMP, and others.</td> 2402 </tr> 2403 2404 <tr> 2405 <td>ps:imagemask</td> 2406 <td>If the ps:imagemask flag is defined, the PS3 and EPS3 coders will 2407 create Postscript files that render bilevel images with the Postscript 2408 imagemask operator instead of the image operator.</td> 2409 </tr> 2410 2411 <tr> 2412 <td>psd:additional-info=all|selective</td> 2413 <td>This option should only be used when converting from a PSD file to 2414 another PSD file. This should be placed after the image is read. The two 2415 options are 'all' and 'selective'. The 'selective' option will preserve 2416 all additional information that is not related to the geometry of the 2417 image. The 'all' option should only be used when the geometry of the 2418 image has not been changed. This option is helpful when transferring 2419 non-simple layers, such as adjustment layers from the input PSD file to 2420 the output PSD file. If this option is not used, the additional 2421 information will not be preserved. This define is available as of 2422 Imagemagick version 6.9.5-8. 2423 </td> 2424 </tr> 2425 2426 <tr> 2427 <td>psd:alpha-unblend=off</td> 2428 <td>Disables new automatic un-blending of transparency with the base image 2429 for the flattened layer 0 before adding the alpha channel to the output 2430 image. This define must be placed before the input psd image. (Available 2431 as of IM 6.9.2.5). The automatic un-blending is new to IM 6.9.2.5 and 2432 prevents the transparency from being applied twice in the output 2433 image. This option should be set before reading the image.</td> 2434 </tr> 2435 2436 <tr> 2437 <td>psd:preserve-opacity-mask=true</td> 2438 <td>This option should only be used when converting from a PSD file to 2439 another PSD file. It will preserve the opacity mask of a layer and add it 2440 back to the layer when the image is saved. Setting this to 'true' will 2441 enable this feature. This define is available as of Imagemagick version 2442 6.9.5-10. 2443 </td> 2444 </tr> 2445 2446 <tr> 2447 <td>preserve-timestamp=<var>{True, False}</var></td> 2448 <td>Preserve file timestamp (<code>mogrify</code> only).</td> 2449 </tr> 2450 2451 <tr> 2452 <td>q-table=<var>quantization-table.xml</var></td> 2453 <td>Custom JPEG quantization tables.</td> 2454 </tr> 2455 2456 <tr> 2457 <td>quantum:format=<var>type</var></td> 2458 <td>Set the type to <code>floating-point</code> to specify a floating-point 2459 format for raw files (e.g. GRAY:) or for MIFF and TIFF images in HDRI mode 2460 to preserve negative values. If <a href="command-line-options.html#depth">-depth</a> 16 is 2461 included, the result is a single precision floating point format. 2462 If <a href="command-line-options.html#depth">-depth</a> 32 is included, the result is 2463 double precision floating point format.</td> 2464 </tr> 2465 2466 <tr> 2467 <td>quantum:polarity=<var>photometric-interpretation</var></td> 2468 <td>Set the photometric-interpretation of an image (typically for TIFF 2469 image file format) to either <code>min-is-black</code> (default) or 2470 <code>min-is-white</code>.</td> 2471 </tr> 2472 2473 <tr> 2474 <td>sample:offset=<var>geometry</var></td> 2475 <td>Location of the sampling point within the sub-region being sampled, 2476 expressed as percentages (see <a href="command-line-options.html#sample" >-sample</a>).</td> 2477 </tr> 2478 2479 <tr> 2480 <td>morphology:showKernel=<var>1</var></td> 2481 <td>Outputs (to 'standard error') all the information about a generated <a 2482 href="command-line-options.html#morphology" >-morphology</a> kernel.</td> 2483 </tr> 2484 2485 <tr> 2486 <td>stream:buffer-size=<var>value</var></td> 2487 <td>Set the stream buffer size. Select 0 for unbuffered I/O.</td> 2488 </tr> 2489 2490 <tr> 2491 <td>tiff:alpha=<var>associated|unassociated|unspecified</var></td> 2492 <td>Specify the alpha extra samples as associated, unassociated or 2493 unspecified.</td> 2494 </tr> 2495 2496 <tr> 2497 <td>tiff:endian=<var>msb|lsb</var></td> 2498 <td> </td> 2499 </tr> 2500 2501 <tr> 2502 <td>tiff:exif-properties=<var>true</var></td> 2503 <td>Enables reading the EXIF properties.</td> 2504 </tr> 2505 2506 <tr> 2507 <td>tiff:fill-order=<var>msb|lsb</var></td> 2508 <td> </td> 2509 </tr> 2510 2511 <tr> 2512 <td>tiff:ignore-layers=<var>true</var></td> 2513 <td>Ignores the photoshop layers.</td> 2514 </tr> 2515 2516 <tr> 2517 <td>tiff:ignore-tags=<var>comma-separate-list-of-tag-IDs</var></td> 2518 <td>Allows one or more tag ID values to be ignored.</td> 2519 </tr> 2520 2521 <tr> 2522 <td>tiff:predictor=<var>[1, 2 or 3]</var></td> 2523 <td>A mathematical operator that is applied to the image data before an encoding scheme is applied. The general idea is that subsequent pixels of an image resemble each other. Thus, substracting the information from a pixel that is already contained in previous one is likely to reduce its information density considerably and aid subsequent compression. 1 = No prediction scheme used before coding. 2 = Horizontal differencing. 3 = Floating point horizontal differencing.</td> 2524 </tr> 2525 2526 <tr> 2527 <td>tiff:rows-per-strip=<var>value</var></td> 2528 <td>Sets the number of rows per strip.</td> 2529 </tr> 2530 2531 <tr> 2532 <td>tiff:tile-geometry=<var>WxH</var></td> 2533 <td>Sets the tile size for pyramid tiffs. Requires the suffix 2534 PTIF: before the outputname.</td> 2535 </tr> 2536 2537 <tr> 2538 <td>type:features=<var>string</var></td> 2539 <td> </td> 2540 </tr> 2541 2542 <tr> 2543 <td>type:hinting=<var>off</var></td> 2544 <td> </td> 2545 </tr> 2546 2547 <tr> 2548 <td>txt:compliance=<var>css</var></td> 2549 <td>The first argument of a hsl() color is integer, not percentage.</td> 2550 </tr> 2551 2552 <tr> 2553 <td>x:screen=<var>true</var></td> 2554 <td>Obtains the image from the root window.</td> 2555 </tr> 2556 2557 <tr> 2558 <td>x:silent=<var>true</var></td> 2559 <td>Turns off the beep when importing an image.</td> 2560 </tr> 2561 </table> 2562 2563 <p>For example, to create a postscript file that will render only the black 2564 pixels of a bilevel image, use:</p> 2565 2566 <pre class="highlight"><code>convert bilevel.tif -define ps:imagemask eps3:stencil.ps 2567 </code></pre> 2568 2569 <p>Set attributes of the image registry by prefixing the value with 2570 <code>registry:</code>. For example, to set a temporary path to put work files, 2571 use:</p> 2572 2573 <pre class="highlight"><code>-define registry:temporary-path=/data/tmp 2574 </code></pre> 2575 2576 <div style="margin: auto;"> 2577 <h3><a class="anchor" id="delay"></a>-delay <var>ticks</var> <br />-delay <var>ticks</var>x<var>ticks-per-second</var> {<var><</var>} {<var>></var>}</h3> 2578 </div> 2579 2580 <p class="magick-description">display the next image after pausing.</p> 2581 2582 <p>This option is useful for regulating the animation of image sequences 2583 <var>ticks/ticks-per-second</var> seconds must expire before the display of the 2584 next image. The default is no delay between each showing of the image 2585 sequence. The default ticks-per-second is 100.</p> 2586 2587 <p>Use <code>></code> to change the image delay <var>only</var> if its current 2588 value exceeds the given delay. <code><</code> changes the image delay 2589 <var>only</var> if current value is less than the given delay. For example, if 2590 you specify <code>30></code> and the image delay is 20, the image delay does 2591 not change. However, if the image delay is 40 or 50, the delay it is changed 2592 to 30. Enclose the given delay in quotation marks to prevent the 2593 <code><</code> or <code>></code> from being interpreted by your shell as 2594 a file redirection.</p> 2595 2596 2597 <div style="margin: auto;"> 2598 <h3><a class="anchor" id="delete"></a>-delete <var>indexes</var></h3> 2599 </div> 2600 2601 <p class="magick-description">delete the images specified by index, from the image sequence.</p> 2602 2603 <p>Specify the image by its index in the sequence. The first image is index 2604 0. Negative indexes are relative to the end of the sequence, for example, -1 2605 represents the last image of the sequence. Specify a range of images with 2606 a dash (e.g. 0-4). Separate indexes with a comma (e.g. 0,2). Use 2607 <code>+delete</code> to delete the last image in the current image sequence. Use <code>-delete 0--1</code> to delete the entire image sequence.</p> 2608 2609 2610 <div style="margin: auto;"> 2611 <h3><a class="anchor" id="density"></a>-density <var>width</var><br />-density <var>width</var>x<var>height</var></h3> 2612 </div> 2613 2614 <p class="magick-description">Set the horizontal and vertical resolution of an image for rendering to devices.</p> 2615 2616 <p>This option specifies the image resolution to store while encoding a raster 2617 image or the canvas resolution while rendering (reading) vector formats such 2618 as Postscript, PDF, WMF, and SVG into a raster image. Image resolution 2619 provides the unit of measure to apply when rendering to an output device or 2620 raster image. The default unit of measure is in dots per inch (DPI). The <a 2621 href="command-line-options.html#units">-units</a> option may be used to select dots per centimeter 2622 instead.</p> 2623 2624 <p>The default resolution is 72 dots per inch, which is equivalent to one 2625 point per pixel (Macintosh and Postscript standard). Computer screens are 2626 normally 72 or 96 dots per inch, while printers typically support 150, 300, 2627 600, or 1200 dots per inch. To determine the resolution of your display, use 2628 a ruler to measure the width of your screen in inches, and divide by the 2629 number of horizontal pixels (1024 on a 1024x768 display).</p> 2630 2631 <p>If the file format supports it, this option may be used to update the 2632 stored image resolution. Note that Photoshop stores and obtains image 2633 resolution from a proprietary embedded profile. If this profile is not 2634 stripped from the image, then Photoshop will continue to treat the image using 2635 its former resolution, ignoring the image resolution specified in the standard 2636 file header.</p> 2637 2638 <p>The <a href="command-line-options.html#density">-density</a> option sets an <var>attribute</var> and 2639 does not alter the underlying raster image. It may be used to adjust the 2640 rendered size for desktop publishing purposes by adjusting the scale applied 2641 to the pixels. To resize the image so that it is the same size at a different 2642 resolution, use the <a href="command-line-options.html#resample">-resample</a> option.</p> 2643 2644 <div style="margin: auto;"> 2645 <h3><a class="anchor" id="depth"></a>-depth <var>value</var></h3> 2646 </div> 2647 2648 <p class="magick-description">depth of the image.</p> 2649 2650 <p>This the number of bits in a color sample within a pixel. Use this option 2651 to specify the depth of raw images whose depth is unknown such as GRAY, RGB, 2652 or CMYK, or to change the depth of any image after it has been read.</p> 2653 2654 <p>Use <a href="command-line-options.html#depth">+depth</a> to return depth to its default value.</p> 2655 2656 <div style="margin: auto;"> 2657 <h3><a class="anchor" id="descend"></a>-descend</h3> 2658 </div> 2659 2660 <p class="magick-description">obtain image by descending window hierarchy.</p> 2661 2662 <div style="margin: auto;"> 2663 <h3><a class="anchor" id="deskew"></a>-deskew <var>threshold{%}</var></h3> 2664 </div> 2665 2666 <p class="magick-description">straighten an image. A threshold of 40% works for most images.</p> 2667 2668 <p>Use <a href="command-line-options.html#set">-set</a> <code>option:deskew:auto-crop 2669 <var>true | false</var></code> to auto crop the image.</p> 2670 2671 <div style="margin: auto;"> 2672 <h3><a class="anchor" id="despeckle"></a>-despeckle</h3> 2673 </div> 2674 2675 <p class="magick-description">reduce the speckles within an image.</p> 2676 2677 <div style="margin: auto;"> 2678 <h3><a class="anchor" id="direction"></a>-direction <var>type</var></h3> 2679 </div> 2680 2681 <p class="magick-description">render text right-to-left or left-to-right. Requires the <a href="https://github.com/HOST-Oman/libraqm">RAQM</a> delegate library and <a href="https://en.wikipedia.org/wiki/Complex_text_layout">complex text layout</a>.</p> 2682 2683 <div style="margin: auto;"> 2684 <h3><a class="anchor" id="displace"></a>-displace <var>horizontal-scale</var>{%}{!}<br />-displace <var>horizontal-scale</var>x<var>vertical-scale</var>{%}{!}</h3> 2685 </div> 2686 2687 <p class="magick-description">shift image pixels as defined by a displacement map.</p> 2688 2689 <p>With this option, the 'overlay' image, and optionally the 'mask' image, 2690 is used as a displacement map, which is used to displace the lookup of 2691 what part of the 'background' image is seen at each point of the overlaid 2692 area. Much like the displacement map is a 'lens' that redirects light shining 2693 through it so as to present a distorted view the original 'background' image 2694 behind it. </p> 2695 2696 <p>Any perfect grey areas of the displacement map produce a zero 2697 displacement of the image. Black areas produce the given maximum negative 2698 displacement of the lookup point, while white produce a maximum positive 2699 displacement of the lookup. </p> 2700 2701 <p>Note that it is the lookup of the 'background' that is displaced, not a 2702 displacement of the image itself. As such an area of the displacement map 2703 containing 'white' will have the lookup point 'shifted' by a positive amount, 2704 and thus generating a copy of the destination image to the right/downward from 2705 the correct position. That is the image will look like it may have been 2706 'shifted' in a negative left/upward direction. Understanding this is a very 2707 important in understanding how displacement maps work. </p> 2708 2709 <p>The given arguments define the maximum amount of displacement in pixels 2710 that a particular map can produce. If the displacement scale is large enough 2711 it is also possible to lookup parts of the 'background' image that lie well 2712 outside the bounds of the displacement map itself. That is you could very 2713 easily copy a section of the original image from outside the overlay area 2714 into the overlay area. </p> 2715 2716 <p>The '%' flag makes the displacement scale relative to the size of the 2717 overlay image (100% = half width/height of image). Using '!' switches 2718 percentage arguments to refer to the destination image size instead. 2719 these flags were added as of IM v6.5.3-5.</p> 2720 2721 <p>Normally a single grayscale displacement map is provided, which with the 2722 given scaling values will determine a single direction (vector) in which 2723 displacements can occur (positively or negatively). However, if you also 2724 specify a third image which is normally used as a <var>mask</var>, 2725 the <var>composite image</var> is used for horizontal X 2726 displacement, while the <var>mask image</var> is used for vertical Y 2727 displacement. This allows you to define completely different displacement 2728 values for the X and Y directions, and allowing you to lookup any point within 2729 the <var>scale</var> bounds. In other words each pixel can lookup 2730 any other nearby pixel, producing complex 2 dimensional displacements, rather 2731 than a simple 1 dimensional vector displacements. </p> 2732 2733 <p>Alternatively rather than supplying two separate images, as of IM v6.4.4-0, 2734 you can use the 'red' channel of the overlay image to specify the horizontal 2735 or X displacement, and the 'green' channel for the vertical or Y displacement. 2736 </p> 2737 2738 <p>As of IM v6.5.3-5 any alpha channel in the overlay image is used as a 2739 mask the transparency of the destination image. However areas outside the 2740 overlaid areas will not be affected. </p> 2741 2742 2743 <div style="margin: auto;"> 2744 <h3><a class="anchor" id="display"></a>-display <var>host:display[.screen]</var></h3> 2745 </div> 2746 2747 <p class="magick-description">Specifies the X server to contact.</p> 2748 2749 <p>This option is used with convert for obtaining image or font from this 2750 X server. See <var>X(1)</var>.</p> 2751 2752 <div style="margin: auto;"> 2753 <h3><a class="anchor" id="dispose"></a>-dispose <var>method</var></h3> 2754 </div> 2755 2756 <p class="magick-description">define the GIF disposal image setting for images that are being created or read in. </p> 2757 2758 <p>The layer disposal method defines the way each the displayed image is to be 2759 modified after the current 'frame' of an animation has finished being 2760 displayed (after its 'delay' period), but before the next frame on an 2761 animation is to be overlaid onto the display. </p> 2762 2763 <p>Here are the valid methods:</p> 2764 2765 <dl class="row"> 2766 <dt class="col-md-4">Undefined</dt><dd class="col-md-8">0: No disposal specified (equivalent to '<code>none</code>').</dd> 2767 <dt class="col-md-4">None</dt><dd class="col-md-8">1: Do not dispose, just overlay next frame image.</dd> 2768 <dt class="col-md-4">Background</dt><dd class="col-md-8">2: Clear the frame area with the background color.</dd> 2769 <dt class="col-md-4">Previous</dt><dd class="col-md-8">3: Clear to the image prior to this frames overlay.</dd> 2770 </dl> 2771 2772 <p>You can also use the numbers given above, which is what the GIF format 2773 uses internally to represent the above settings. </p> 2774 2775 <p>To print a complete list of dispose methods, use <a href="command-line-options.html#list">-list dispose</a>.</p> 2776 2777 <p>Use <a href="command-line-options.html#dispose" >+dispose</a>, turn off the setting and prevent 2778 resetting the layer disposal methods of images being read in. </p> 2779 2780 <p>Use <a href="command-line-options.html#set">-set</a> '<code>dispose</code>' method to set the image 2781 disposal method for images already in memory.</p> 2782 2783 <div style="margin: auto;"> 2784 <h3><a class="anchor" id="dissimilarity-threshold"></a>-dissimilarity-threshold <var>value</var></h3> 2785 </div> 2786 2787 <p class="magick-description">maximum RMSE for subimage match (default 0.2).</p> 2788 2789 2790 <div style="margin: auto;"> 2791 <h3><a class="anchor" id="dissolve"></a>-dissolve <var>src_percent</var>[x<var>dst_percent</var>]</h3> 2792 </div> 2793 2794 <p class="magick-description">dissolve an image into another by the given percent.</p> 2795 2796 <p>The opacity of the composite image is multiplied by the given percent, then 2797 it is composited 'over' the main image. If <var>src_percent</var> 2798 is greater than 100, start dissolving the main image so it becomes 2799 transparent at a value of '<code>200</code>'. If both percentages 2800 are given, each image are dissolved to the percentages given. </p> 2801 2802 <p>Note that dissolve percentages do not add, two opaque images dissolved 2803 '50,50', produce a 75% transparency. For a 50% + 50% blending of the two 2804 images, you would need to use dissolve values of '50,100'. </p> 2805 2806 <div style="margin: auto;"> 2807 <h3><a class="anchor" id="distort"></a>-distort <var>method arguments</var></h3> 2808 </div> 2809 2810 <p class="magick-description">distort an image, using the given <var>method</var> and its required <var>arguments</var>.</p> 2811 2812 <p>The <var>arguments</var> is a single string containing a list 2813 of floating point numbers separated by commas or spaces. The number of 2814 and meaning of the floating point values depends on the distortion <var>method</var> being used. </p> 2815 2816 <p>Choose from these distortion types:</p> 2817 2818 <table class="table table-sm table-striped"> 2819 <tr> 2820 <th style="width: 8%">Method</th> 2821 <th>Description</th> 2822 </tr> 2823 2824 <tr> 2825 <td>ScaleRotateTranslate <br/> SRT</td> 2826 <td> 2827 Distort image by first scaling and rotating about a given 'center', 2828 before translating that 'center' to the new location, in that order. It 2829 is an alternative method of specifying a 'Affine' type of 2830 distortion, but without shearing effects. It also provides a good way 2831 of rotating and displacing a smaller image for tiling onto a larger 2832 background (IE 2-dimensional animations). <br/> 2833 2834 The number of arguments determine the specific meaning of each 2835 argument for the scales, rotation, and translation operations. <br/> 2836 2837 <dl class="row"> 2838 <dt class="col-md-4">2:</dt><dd class="col-md-8"><var>Scale Angle</var></dd> 2839 <dt class="col-md-4">3:</dt><dd class="col-md-8"><var>X,Y Angle</var></dd> 2840 <dt class="col-md-4">4:</dt><dd class="col-md-8"><var>X,Y Scale Angle</var></dd> 2841 <dt class="col-md-4">5:</dt> <dd class="col-md-8"><var>X,Y ScaleX,ScaleY Angle</var></dd> 2842 <dt class="col-md-4">6:</dt> <dd class="col-md-8"><var>X,Y Scale Angle NewX,NewY</var></dd> 2843 <dt class="col-md-4">7:</dt> <dd class="col-md-8"><var>X,Y ScaleX,ScaleY Angle NewX,NewY</var></dd> 2844 </dl> 2845 2846 This is actually an alternative way of specifying a 2 dimensional linear 2847 'Affine' or 'AffineProjection' distortion. </td> </tr> 2848 2849 <tr> 2850 <td>Affine</td> 2851 <td> 2852 Distort the image linearly by moving a list of at least 3 or more sets 2853 of control points (as defined below). Ideally 3 sets or 12 floating 2854 point values are given allowing the image to be linearly scaled, 2855 rotated, sheared, and translated, according to those three points. See 2856 also the related 'AffineProjection' and 'SRT' 2857 distortions. <br/> 2858 2859 More than 3 sets given control point pairs (12 numbers) is least 2860 squares fitted to best match a linear affine distortion. If only 2 2861 control point pairs (8 numbers) are given a two point image translation 2862 rotation and scaling is performed, without any possible shearing, 2863 flipping or changes in aspect ratio to the resulting image. If only one 2864 control point pair is provides the image is only translated, (which may 2865 be a floating point non-integer translation). <br/> 2866 2867 This distortion does not include any form of perspective distortion. 2868 </td> 2869 2870 </tr> 2871 2872 <tr> 2873 <td>AffineProjection</td> 2874 <td> 2875 Linearly distort an image using the given Affine Matrix of 6 2876 pre-calculated coefficients forming a set of Affine Equations to map 2877 the source image to the destination image. 2878 2879 <p class="text-center"><var> 2880 s<sub>x</sub>, r<sub>x</sub>, 2881 r<sub>y</sub>, s<sub>y</sub>, 2882 t<sub>x</sub>, t<sub>y</sub> 2883 </var></p> 2884 2885 See <a href="command-line-options.html#affine" >-affine</a> setting for more detail, and 2886 meanings of these coefficients. <br/> 2887 2888 The distortions 'Affine' and 'SRT' provide 2889 alternative methods of defining this distortion, with ImageMagick doing 2890 the calculations needed to generate the required coefficients. You can 2891 see the internally generated coefficients, by using a <a 2892 href="command-line-options.html#verbose" >-verbose</a> setting with those other variants. </td> 2893 2894 </tr> 2895 2896 <tr> 2897 <td>BilinearForward<br/> 2898 BilinearReverse</td> 2899 <td> 2900 Bilinear Distortion, given a minimum of 4 sets of coordinate pairs, or 2901 16 values (see below). Not that lines may not appear straight after 2902 distortion, though the distance between coordinates will remain 2903 consistent. <br/> 2904 2905 The 'BilinearForward' is used to map rectangles to any 2906 quadrilateral, while the 'BilinearReverse' form maps any 2907 quadrilateral to a rectangle, while preserving the straight line edges 2908 in each case. <br/> 2909 2910 Note that 'BilinearForward' can generate invalid pixels 2911 which will be colored using the <a href="command-line-options.html#mattecolor" >-mattecolor</a> 2912 color setting. Also if the quadrilateral becomes 'flipped' the image 2913 may disappear. <br/> 2914 2915 There are future plans to produce a true Bilinear distortion that will 2916 attempt to map any quadrilateral to any other quadrilateral, while 2917 preserving edges (and edge distance ratios). 2918 2919 </td> 2920 </tr> 2921 2922 <tr> 2923 <td>Perspective</td> 2924 <td> 2925 Perspective distort the images, using a list of 4 or more sets of 2926 control points (as defined below). More that 4 sets (16 numbers) of 2927 control points provide least squares fitting for more accurate 2928 distortions (for the purposes of image registration and panorama 2929 effects). Less than 4 sets will fall back to a 'Affine' 2930 linear distortion. <br/> 2931 2932 Perspective Distorted images ensures that straight lines remain 2933 straight, but the scale of the distorted image will vary. The horizon 2934 is anti-aliased, and the 'sky' color may be set using the 2935 <a href="command-line-options.html#mattecolor" >-mattecolor</a> setting. </td> 2936 </tr> 2937 2938 <tr> 2939 <td>PerspectiveProjection </td> 2940 <td> 2941 Do a 'Perspective' distortion biased on a set of 8 2942 pre-calculated coefficients. You can get these coefficients by looking 2943 at the <a href="command-line-options.html#verbose" >-verbose</a> output of a 2944 'Perspective' distortion, or by calculating them yourself. 2945 If the last two perspective scaling coefficients are zero, the 2946 remaining 6 represents a transposed 'Affine Matrix'. </td> 2947 2948 </tr> 2949 2950 <tr> 2951 <td>Arc</td> 2952 <td> 2953 Arc the image (variation of polar mapping) over the angle given around 2954 a circle. 2955 2956 <dl class="row"> 2957 <dt class="col-md-4">arc_angle</dt> 2958 <dd class="col-md-8">The angle over which to arc the image side-to-side</dd> 2959 <dt class="col-md-4">rotate_angle</dt> 2960 <dd class="col-md-8">Angle to rotate resulting image from vertical center</dd> 2961 <dt class="col-md-4">top_radius</dt> 2962 <dd class="col-md-8">Set top edge of source image at this radius</dd> 2963 <dt class="col-md-4">bottom_radius </dt> 2964 <dd class="col-md-8">Set bottom edge to this radius (radial scaling)</dd> 2965 </dl> 2966 2967 The resulting image is always resized to best fit the resulting image, 2968 (as if using <a href="command-line-options.html#distort" >+distort</a>) while attempting to 2969 preserve scale and aspect ratio of the original image as much as 2970 possible with the arguments given by the user. All four arguments will 2971 be needed to change the overall aspect ratio of an 'Arc'ed image. <br/> 2972 2973 This a variation of a polar distortion designed to try to preserve the 2974 aspect ratio of the image rather than direct Cartesian to Polar 2975 conversion. </td> 2976 </tr> 2977 2978 <tr> 2979 <td>Polar</td> 2980 <td> 2981 Like 'Arc' but do a complete Cartesian to Polar mapping of 2982 the image. that is the height of the input image is mapped to the 2983 radius limits, while the width is wrapped around between the 2984 angle limits. <br/> 2985 2986 Arguments: <var>Rmax,Rmin CenterX,CenterY, start,end_angle</var> <br/> 2987 2988 All arguments are optional. With <var>Rmin</var> defaulting to zero, the 2989 center to the center of the image, and the angles going from -180 (top) 2990 to +180 (top). If <var>Rmax</var> is given the special value of 2991 '0', the the distance from the center to the nearest edge 2992 is used for the radius of the output image, which will ensure the whole 2993 image is visible (though scaled smaller). However a special value of 2994 '-1' will use the distance from the center to the furthest 2995 corner, This may 'clip' the corners from the input rectangular image, 2996 but will generate the exact reverse of a 'DePolar' with 2997 the same arguments. <br/> 2998 2999 If the plus form of distort (<a href="command-line-options.html#distort" >+distort</a>) is used 3000 output image center will default to 0,0 of the virtual 3001 canvas, and the image size adjusted to ensure the whole input image is 3002 made visible in the output image on the virtual canvas. </td> 3003 3004 </tr> 3005 3006 <tr> 3007 <td>DePolar</td> 3008 <td> 3009 Uses the same arguments and meanings as a 'Polar' distortion 3010 but generates the reverse Polar to Cartesian distortion. <br/> 3011 3012 The special <var>Rmax</var> setting of '0' may however clip 3013 the corners of the input image. However using the special 3014 <var>Rmax</var> setting of '-1' (maximum center to corner 3015 distance) will ensure the whole distorted image is preserved in the 3016 generated result, so that the same argument to 'Polar' will 3017 reverse the distortion re-producing the original. 3018 3019 Note that as this distortion requires the area resampling of a circular 3020 arc, which can not be handled by the builtin EWA resampling function. 3021 As such the normal EWA filters are turned off. It is recommended some 3022 form of 'super-sampling' image processing technique be used to produce 3023 a high quality result. </td> 3024 3025 </tr> 3026 3027 <tr> 3028 <td>Barrel</td> 3029 <td> 3030 Given the four coefficients (A,B,C,D) as defined by <a 3031 href="http://wiki.panotools.org/Lens_correction_model" >Helmut 3032 Dersch</a>, perform a barrel or pin-cushion distortion appropriate to 3033 correct radial lens distortions. That is in photographs, make straight 3034 lines straight again. <br/> 3035 3036 <p class="text-center">Arguments: <var>A B C</var> [ <var>D</var> [ 3037 <var>X</var> , <var>Y</var> ] ] <br/> 3038 or <var>A<sub>x</sub> B<sub>x</sub> C<sub>x</sub> D<sub>x</sub> 3039 A<sub>y</sub> B<sub>y</sub> C<sub>y</sub> D<sub>y</sub></var> 3040 [ <var>X</var> , <var>Y</var> ] </p> 3041 So that it forms the function 3042 <p class="text-center">Rsrc = r * ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> + 3043 <var>C</var>*r + <var>D</var> )</p> 3044 3045 Where <var>X</var>,<var>Y</var> is the optional center of the distortion 3046 (defaulting to the center of the image). <br/> 3047 The second form is typically used to distort images, rather than 3048 correct lens distortions. <br/> 3049 </td> 3050 3051 </tr> 3052 3053 <tr> 3054 <td>BarrelInverse</td> 3055 <td> 3056 This is very similar to 'Barrel' with the same set of 3057 arguments, and argument handling. However it uses the inverse 3058 of the radial polynomial, 3059 so that it forms the function 3060 <p class="text-center">Rsrc = r / ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> + 3061 <var>C</var>*r + <var>D</var> )</p> 3062 Note that this is not the reverse of the 'Barrel' 3063 distortion, just a different barrel-like radial distortion method. 3064 3065 </td> 3066 </tr> 3067 3068 <tr> 3069 <td>Shepards</td> 3070 <td> 3071 Distort the given list control points (any number) using an Inverse 3072 Squared Distance Interpolation Method (<a 3073 href="http://en.wikipedia.org/wiki/Shepard%27s_method" >Shepards 3074 Method</a>). The control points in effect do 'localized' displacement 3075 of the image around the given control point (preserving the look and 3076 the rotation of the area near the control points. For best results 3077 extra control points should be added to 'lock' the positions of the 3078 corners, edges and other unchanging parts of the image, to prevent 3079 their movement. <br/> 3080 3081 The distortion has been likened to 'taffy pulling' using nails, or 3082 pins' stuck in a block of 'jelly' which is then moved to the new 3083 position, distorting the surface of the jelly. <br/> 3084 3085 Internally it is equivalent to generating a displacement map (see <a 3086 href="command-line-options.html#displace" >-displace</a>) for source image color look-up using 3087 the <a href="command-line-options.html#sparse-color" >-sparse-color</a> method of the same name. 3088 3089 </td> 3090 </tr> 3091 3092 </table> 3093 3094 <p>To print a complete list of distortion methods, use <a href="command-line-options.html#list">-list 3095 distort</a>.</p> 3096 3097 <p>Many of the above distortion methods such as '<code>Affine</code>', 3098 '<code>Perspective</code>', and '<code>Shepards</code>' use a list control points 3099 defining how these points in the given image should be distorted in the 3100 destination image. Each set of four floating point values represent a source 3101 image coordinate, followed immediately by the destination image coordinate. 3102 This produces a list of values such as...</p> 3103 <p class="text-center"><var> 3104 U<sub>1</sub>,V<sub>1</sub> X<sub>1</sub>,Y<sub>1</sub> 3105 U<sub>2</sub>,V<sub>2</sub> X<sub>2</sub>,Y<sub>2</sub> 3106 U<sub>3</sub>,V<sub>3</sub> X<sub>3</sub>,Y<sub>3</sub> 3107 ... 3108 U<sub>n</sub>,V<sub>n</sub> X<sub>n</sub>,Y<sub>n</sub> 3109 </var></p> 3110 <p>where <var>U,V</var> on the source image is mapped to <var>X,Y</var> on the 3111 destination image. </p> 3112 3113 <p>For example, to warp an image using '<code>perspective</code>' distortion, 3114 needs a list of at least 4 sets of coordinates, or 16 numbers. Here is the 3115 perspective distortion of the built-in "rose:" image. Note how spaces were 3116 used to group the 4 sets of coordinate pairs, to make it easier to read and 3117 understand.</p> 3118 3119 <pre class="highlight"><code>convert rose: -virtual-pixel black \ 3120 -distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35' \ 3121 rose_3d_rotated.gif" 3122 </code></pre> 3123 3124 <p>If more that the required number of coordinate pairs are given for 3125 a distortion, the distortion method is 'least squares' fitted to produce the 3126 best result for all the coordinate pairs given. If less than the ideal number 3127 of points are given, the distort will generally fall back to a simpler form of 3128 distortion that can handles the smaller number of coordinates (usually a linear 3129 '<code>Affine</code>' distortion). </p> 3130 3131 <p>By using more coordinates you can make use of image registration tool to 3132 find matching coordinate pairs in overlapping images, so as to improve the 3133 'fit' of the distortion. Of course a bad coordinate pair can also make the 3134 'fit' worse. Caution is always advised. </p> 3135 3136 <p>Colors are acquired from the source image according to a cylindrical 3137 resampling <a href="command-line-options.html#filter" >-filter</a>, using a special technique known as 3138 EWA resampling. This produces very high quality results, especially when 3139 images become smaller (minified) in the output, which is very common when 3140 using '<code>perspective</code>' distortion. For example here we view 3141 a infinitely tiled 'plane' all the way to the horizon. </p> 3142 3143 <pre class="highlight"><code>convert -size 90x90 pattern:checkerboard -normalize -virtual-pixel tile \ 3144 -distort perspective '0,0,5,45 89,0,45,46 0,89,0,89 89,89,89,89' \ 3145 checks_tiled.jpg 3146 </code></pre> 3147 3148 <p>Note that a infinitely tiled perspective images involving the horizon can 3149 be very slow, because of the number of pixels that are compressed to generate 3150 each individual pixel close to the 'horizon'. You can turn off EWA 3151 resampling, by specifying the special <a href="command-line-options.html#filter" >-filter</a> setting of 3152 '<code>point</code>' (recommended if you plan to use super-sampling instead). 3153 </p> 3154 3155 <p>If an image generates <i>invalid pixels</i>, such as the 'sky' in the last 3156 example, <a href="command-line-options.html#distort" >-distort</a> will use the current <a 3157 href="command-line-options.html#mattecolor" >-mattecolor</a> setting for these pixels. If you do not 3158 what these pixels to be visible, set the color to match the rest of the 3159 ground. </p> 3160 3161 <p>The output image size will by default be the same as the input image. This 3162 means that if the part of the distorted image falls outside the viewed area of 3163 the 'distorted space', those parts is clipped and lost. However if you use 3164 the plus form of the operator (<a href="command-line-options.html#distort" >+distort</a>) the operator 3165 will attempt (if possible) to show the whole of the distorted image, while 3166 retaining a correct 'virtual canvas' offset, for image layering. This offset 3167 may need to be removed using <a href="command-line-options.html#repage" >+repage</a>, to remove if it 3168 is unwanted. </p> 3169 3170 <p>Setting <a href="command-line-options.html#verbose" >-verbose</a> setting, will cause <a 3171 href="command-line-options.html#distort" >-distort</a> to attempt to output the internal coefficients, 3172 and the <a href="command-line-options.html#fx" >-fx</a> equivalent to the distortion, for expert study, 3173 and debugging purposes. This many not be available for all distorts. </p> 3174 3175 <p>You can alternatively specify a special "<code><a href="command-line-options.html#define" 3176 >-define</a> distort:viewport={geometry_string}</code>" setting which will 3177 specify the size and the offset of the generated 'viewport' image of the 3178 distorted image space.</p> 3179 3180 <p>Setting a "<code><a href="command-line-options.html#define" >-define</a> 3181 distort:scale=<var>scale_factor</var></code>" will scale the output image (viewport or 3182 otherwise) by that factor without changing the viewed contents of the 3183 distorted image. This can be used either for 'super-sampling' the image for 3184 a higher quality result, or for panning and zooming around the image (with 3185 appropriate viewport changes, or post-distort cropping and resizing). </p> 3186 3187 <p>Setting "<code><a href="command-line-options.html#define" >-define</a> resample:verbose=1</code>" 3188 will output the cylindrical filter lookup table created by the EWA (Elliptical 3189 Weighted Average) resampling algorithm. Note this table uses a squared radius 3190 lookup value. This is typically only used for debugging EWA resampling. </p> 3191 3192 3193 <div style="margin: auto;"> 3194 <h3><a class="anchor" id="distribute-cache"></a>-distribute-cache <var>port</var></h3> 3195 </div> 3196 3197 <p class="magick-description">launch a distributed pixel cache server. </p> 3198 3199 <div style="margin: auto;"> 3200 <h3><a class="anchor" id="dither"></a>-dither <var>method</var></h3> 3201 </div> 3202 3203 <p class="magick-description">Apply a Riemersma or Floyd-Steinberg error diffusion dither to 3204 images when general color reduction is applied via an option, or automagically 3205 when saving to specific formats. This enabled by default.</p> 3206 3207 <p>Dithering places two or more colors in neighboring pixels so that to the 3208 eye a closer approximation of the images original color is reproduced. This 3209 reduces the number of colors needed to reproduce the image but at the cost of 3210 a lower level pattern of colors. Error diffusion dithers can use any set of 3211 colors (generated or user defined) to an image. </p> 3212 3213 <p>Dithering is turned on by default, to turn it off use the plus form of the 3214 setting, <a href="command-line-options.html#dither">+dither</a>. This will also also render PostScript 3215 without text or graphic aliasing. Disabling dithering often (but not always) 3216 leads to faster process, a smaller number of colors, but more cartoon like 3217 image coloring. Generally resulting in 'color banding' effects in areas with 3218 color gradients. </p> 3219 3220 <p>The color reduction operators <a href="command-line-options.html#colors">-colors</a>, <a 3221 href="command-line-options.html#monochrome">-monochrome</a>, <a href="command-line-options.html#remap ">-remap</a>, and <a 3222 href="command-line-options.html#posterize">-posterize</a>, apply dithering to images using the reduced 3223 color set they created. These operators are also used as part of automatic 3224 color reduction when saving images to formats with limited color support, such 3225 as <code>GIF:</code>, <code>XBM:</code>, and others, so dithering may also be used 3226 in these cases. </p> 3227 3228 <p>Alternatively you can use <a href="command-line-options.html#random-threshold">-random-threshold</a> 3229 to generate purely random dither. Or use <a 3230 href="command-line-options.html#ordered-dither">-ordered-dither</a> to apply threshold mapped dither 3231 patterns, using uniform color maps, rather than specific color maps. </p> 3232 <p>Use "<code><a href="command-line-options.html#define" >-define</a> dither:diffusion-amount=35%</code>, for example, to control the amount of Floyd-Steinberg dither.</p> 3233 3234 3235 <div style="margin: auto;"> 3236 <h3><a class="anchor" id="draw"></a>-draw <var>string</var></h3> 3237 </div> 3238 3239 <p class="magick-description">Annotate an image with one or more graphic primitives.</p> 3240 3241 <p>Use this option to annotate or decorate an image with one or more graphic 3242 primitives. The primitives include shapes, text, transformations, and pixel 3243 operations.</p> 3244 3245 <p>The shape primitives:</p> 3246 3247 <dl class="row"> 3248 <dt class="col-md-4">point</dt><dd class="col-md-8"> x,y</dd> 3249 <dt class="col-md-4">line</dt><dd class="col-md-8"> x0,y0 x1,y1</dd> 3250 <dt class="col-md-4">rectangle</dt><dd class="col-md-8"> x0,y0 x1,y1</dd> 3251 <dt class="col-md-4">roundRectangle</dt><dd class="col-md-8"> x0,y0 x1,y1 wc,hc</dd> 3252 <dt class="col-md-4">arc</dt><dd class="col-md-8"> x0,y0 x1,y1 a0,a1</dd> 3253 <dt class="col-md-4">ellipse</dt><dd class="col-md-8"> x0,y0 rx,ry a0,a1</dd> 3254 <dt class="col-md-4">circle</dt><dd class="col-md-8"> x0,y0 x1,y1</dd> 3255 <dt class="col-md-4">polyline</dt><dd class="col-md-8"> x0,y0 ... xn,yn</dd> 3256 <dt class="col-md-4">polygon</dt><dd class="col-md-8"> x0,y0 ... xn,yn</dd> 3257 <dt class="col-md-4">bezier</dt><dd class="col-md-8"> x0,y0 ... xn,yn</dd> 3258 <dt class="col-md-4">path</dt><dd class="col-md-8">specification </dd> 3259 <dt class="col-md-4">image</dt><dd class="col-md-8"> operator x0,y0 w,h filename</dd> 3260 </dl> 3261 3262 <p>The text primitive:</p> 3263 3264 <dl class="row"> 3265 <dt class="col-md-4">text</dt><dd class="col-md-8">x0,y0 string</dd> 3266 </dl> 3267 <p>The text gravity primitive:</p> 3268 3269 <dl class="row"> 3270 <dt class="col-md-4">gravity</dt><dd class="col-md-8">NorthWest, North, NorthEast, West, Center, East, SouthWest, South, or SouthEast</dd> 3271 </dl> 3272 3273 <p>The text gravity primitive only affects the placement of text and does not 3274 interact with the other primitives. It is equivalent to using the <a 3275 href="command-line-options.html#gravity">-gravity</a> command-line option, except that it is limited in 3276 scope to the <a href="command-line-options.html#draw">-draw</a> option in which it appears.</p> 3277 3278 <p>The transformation primitives:</p> 3279 3280 <dl class="row"> 3281 <dt class="col-md-4">rotate</dt><dd class="col-md-8">degrees</dd> 3282 <dt class="col-md-4">translate</dt><dd class="col-md-8">dx,dy</dd> 3283 <dt class="col-md-4">scale</dt><dd class="col-md-8">sx,sy</dd> 3284 <dt class="col-md-4">skewX</dt><dd class="col-md-8">degrees</dd> 3285 <dt class="col-md-4">skewY</dt><dd class="col-md-8">degrees</dd> 3286 </dl> 3287 3288 <p>The pixel operation primitives:</p> 3289 3290 <dl class="row"> 3291 <dt class="col-md-4">color</dt><dd class="col-md-8">x0,y0 method</dd> 3292 <dt class="col-md-4">matte</dt><dd class="col-md-8">x0,y0 method</dd> 3293 </dl> 3294 3295 <p>The shape primitives are drawn in the color specified by the preceding <a 3296 href="command-line-options.html#fill">-fill</a> setting. For unfilled shapes, use <a 3297 href="command-line-options.html#fill">-fill none</a>. You can optionally control the stroke (the 3298 "outline" of a shape) with the <a href="command-line-options.html#stroke">-stroke</a> and <a 3299 href="command-line-options.html#strokewidth">-strokewidth</a> settings.</p> 3300 3301 <p>A <code>point</code> primitive is specified by a single <var>point</var> in the 3302 pixel plane, that is, by an ordered pair of integer coordinates, 3303 <var>x</var>,<var>y</var>. (As it involves only a single pixel, a <code>point</code> 3304 primitive is not affected by <a href="command-line-options.html#stroke">-stroke</a> or <a 3305 href="command-line-options.html#strokewidth">-strokewidth</a>.)</p> 3306 3307 <p>A <code>line</code> primitive requires a start point and end point.</p> 3308 3309 <p>A <code>rectangle</code> primitive is specified by the pair of points at the 3310 upper left and lower right corners.</p> 3311 3312 <p>A <code>roundRectangle</code> primitive takes the same corner points as 3313 a <code>rectangle</code> followed by the width and height of the rounded corners 3314 to be removed.</p> 3315 3316 <p>The <code>circle</code> primitive makes a disk (filled) or circle (unfilled). 3317 Give the center and any point on the perimeter (boundary).</p> 3318 3319 <p>The <code>arc</code> primitive is used to inscribe an elliptical segment in 3320 to a given rectangle. An <code>arc</code> requires the two corners used for 3321 <code>rectangle</code> (see above) followed by the start and end angles of the 3322 arc of the segment segment (e.g. 130,30 200,100 45,90). The start and end 3323 points produced are then joined with a line segment and the resulting segment 3324 of an ellipse is filled.</p> 3325 3326 <p>Use <code>ellipse</code> to draw a partial (or whole) ellipse. Give the 3327 center point, the horizontal and vertical "radii" (the <var>semi-axes</var> of 3328 the ellipse) and start and end angles in degrees (e.g. 100,100 100,150 3329 0,360).</p> 3330 3331 <p>The <code>polyline</code> and <code>polygon</code> primitives require three or 3332 more points to define their perimeters. A <code>polyline</code> is simply 3333 a <code>polygon</code> in which the final point is not stroked to the start 3334 point. When unfilled, this is a <var>polygonal line</var>. If the <a 3335 href="command-line-options.html#stroke">-stroke</a> setting is <code>none</code> (the default), then 3336 a <code>polyline</code> is identical to a <code>polygon</code>. </p> 3337 3338 <p>A <var>coordinate</var> is a pair of integers separated by a space or 3339 optional comma. </p> 3340 3341 <p>As an example, to define a circle centered at 100,100 that extends to 3342 150,150 use:</p> 3343 3344 <pre class="highlight"><code>-draw 'circle 100,100 150,150' 3345 </code></pre> 3346 3347 <p>The <code>Bezier</code> primitive creates a spline curve and requires three 3348 or points to define its shape. The first and last points are the 3349 <var>knots</var> and these points are attained by the curve, while any 3350 intermediate coordinates are <var>control points</var>. If two control points 3351 are specified, the line between each end knot and its sequentially respective 3352 control point determines the tangent direction of the curve at that end. If 3353 one control point is specified, the lines from the end knots to the one 3354 control point determines the tangent directions of the curve at each end. If 3355 more than two control points are specified, then the additional control points 3356 act in combination to determine the intermediate shape of the curve. In order 3357 to draw complex curves, it is highly recommended either to use the 3358 <code>path</code> primitive or to draw multiple four-point bezier segments with 3359 the start and end knots of each successive segment repeated. For example:</p> 3360 3361 <pre class="highlight"><code>-draw 'bezier 20,50 45,100 45,0 70,50' 3362 -draw 'bezier 70,50 95,100 95,0 120,50' 3363 </code></pre> 3364 3365 <p>A <code>path</code> represents an outline of an object, defined in terms of 3366 moveto (set a new current point), lineto (draw a straight line), curveto (draw 3367 a Bezier curve), arc (elliptical or circular arc) and closepath (close the 3368 current shape by drawing a line to the last moveto) elements. Compound paths 3369 (i.e., a path with subpaths, each consisting of a single moveto followed by 3370 one or more line or curve operations) are possible to allow effects such as 3371 <var>donut holes</var> in objects. (See <a 3372 href="http://www.w3.org/TR/SVG/paths.html">Paths</a>.)</p> 3373 3374 <p>Use <code>image</code> to composite an image with another image. Follow the 3375 image keyword with the composite operator, image location, image size, and 3376 filename:</p> 3377 3378 <pre class="highlight"><code>-draw 'image SrcOver 100,100 225,225 image.jpg' 3379 </code></pre> 3380 3381 <p>You can use 0,0 for the image size, which means to use the actual 3382 dimensions found in the image header. Otherwise, it is scaled to the given 3383 dimensions. See <a href="../www/compose.html">Alpha Compositing</a> for 3384 a detailed discussion of alpha composition methods that are available. </p> 3385 3386 <p>The "special augmented compose operators" such as "dissolve" that require 3387 arguments cannot be used at present with the <code>-draw image</code> option. 3388 </p> 3389 3390 <p>Use <code>text</code> to annotate an image with text. Follow the text 3391 coordinates with a string. If the string has embedded spaces, enclose it in 3392 single or double quotes.</p> 3393 3394 <p>For example, the following annotates the image with <code>Works like 3395 magick!</code> for an image titled <code>bird.miff</code>. </p> 3396 3397 <pre class="highlight"><code>-draw "text 100,100 'Works like magick!' " 3398 </code></pre> 3399 3400 <p>See the <a href="command-line-options.html#annotate">-annotate</a> option for another convenient way 3401 to annotate an image with text.</p> 3402 3403 <p>The <code>rotate</code> primitive rotates subsequent shape primitives and 3404 text primitives about the origin of the main image.</p> 3405 3406 <p>The <code>translate</code> primitive translates subsequent shape and text 3407 primitives.</p> 3408 3409 <p>The <code>scale</code> primitive scales them.</p> 3410 3411 <p>The <code>skewX</code> and <code>skewY</code> primitives skew them with respect 3412 to the origin of the main image or the region.</p> 3413 3414 <p>The transformations modify the current affine matrix, which is initialized 3415 from the initial affine matrix defined by the <a href="command-line-options.html#affine">-affine</a> 3416 option. Transformations are cumulative within the <a href="command-line-options.html#draw">-draw</a> 3417 option. The initial affine matrix is not affected; that matrix is only changed 3418 by the appearance of another <a href="command-line-options.html#affine">-affine</a> option. If another 3419 <a href="command-line-options.html#draw">-draw</a> option appears, the current affine matrix is 3420 reinitialized from the initial affine matrix.</p> 3421 3422 <p>Use the <code>color</code> primitive to change the color of a pixel to the 3423 fill color (see <a href="command-line-options.html#fill">-fill</a>). Follow the pixel coordinate with 3424 a method:</p> 3425 3426 <pre class="highlight"><code>point 3427 replace 3428 floodfill 3429 filltoborder 3430 reset 3431 </code></pre> 3432 3433 <p>Consider the target pixel as that specified by your coordinate. The 3434 <code>point</code> method recolors the target pixel. The <code>replace</code> 3435 method recolors any pixel that matches the color of the target pixel. 3436 <code>Floodfill</code> recolors any pixel that matches the color of the target 3437 pixel and is a neighbor, whereas <code>filltoborder</code> recolors any neighbor 3438 pixel that is not the border color. Finally, <code>reset</code> recolors all 3439 pixels.</p> 3440 3441 <p>Use <code>matte</code> to the change the pixel matte value to transparent. 3442 Follow the pixel coordinate with a method (see the <code>color</code> primitive 3443 for a description of methods). The <code>point</code> method changes the matte 3444 value of the target pixel. The <code>replace</code> method changes the matte 3445 value of any pixel that matches the color of the target pixel. 3446 <code>Floodfill</code> changes the matte value of any pixel that matches the 3447 color of the target pixel and is a neighbor, whereas <code>filltoborder</code> 3448 changes the matte value of any neighbor pixel that is not the border color (<a 3449 href="command-line-options.html#bordercolor">-bordercolor</a>). Finally <code>reset</code> changes the 3450 matte value of all pixels.</p> 3451 3452 <p>You can set the primitive color, font, and font bounding box color with <a 3453 href="command-line-options.html#fill">-fill</a>, <a href="command-line-options.html#font">-font</a>, and <a href="command-line-options.html#box">-box</a> 3454 respectively. Options are processed in command line order so be sure to use 3455 these options <var>before</var> the <a href="command-line-options.html#draw">-draw</a> option.</p> 3456 3457 <p>Strings that begin with a number must be quoted (e.g. use '1.png' rather 3458 than 1.png).</p> 3459 3460 <p>Drawing primitives conform to the <a href="magick-vector-graphics.html" >Magick 3461 Vector Graphics</a> format.</p> 3462 3463 3464 <div style="margin: auto;"> 3465 <h3><a class="anchor" id="duplicate"></a>-duplicate <var>count,indexes</var></h3> 3466 </div> 3467 3468 <p class="magick-description">duplicate an image one or more times.</p> 3469 3470 <p>Specify the count and the image to duplicate by its index in the sequence. 3471 The first image is index 0. Negative indexes are relative to the end of the 3472 sequence, for example, -1 represents the last image of the sequence. Specify 3473 a range of images with a dash (e.g. 0-4). Separate indexes with a comma (e.g. 3474 0,2). Use <code>+duplicate</code> to duplicate the last image in the current 3475 image sequence.</p> 3476 3477 <div style="margin: auto;"> 3478 <h3><a class="anchor" id="edge"></a>-edge <var>radius</var></h3> 3479 </div> 3480 3481 <p class="magick-description">detect edges within an image.</p> 3482 3483 <div style="margin: auto;"> 3484 <h3><a class="anchor" id="emboss"></a>-emboss <var>radius</var></h3> 3485 </div> 3486 3487 <p class="magick-description">emboss an image.</p> 3488 3489 <div style="margin: auto;"> 3490 <h3><a class="anchor" id="encipher"></a>-encipher <var>filename</var></h3> 3491 </div> 3492 3493 <p class="magick-description">Encipher pixels for later deciphering by <a href="command-line-options.html#decipher">-decipher</a>.</p> 3494 3495 <p>Get the passphrase from the file specified by <var>filename</var>.</p> 3496 3497 <p>For more information, see the webpage, <a 3498 href="../www/cipher.html">ImageMagick: Encipher or 3499 Decipher an Image</a>.</p> 3500 3501 3502 3503 <div style="margin: auto;"> 3504 <h3><a class="anchor" id="encoding"></a>-encoding <var>type</var></h3> 3505 </div> 3506 3507 <p class="magick-description">specify the text encoding.</p> 3508 3509 <p>Choose from</p> 3510 3511 <pre class="highlight"><code>AdobeCustom AdobeExpert 3512 AdobeStandard AppleRoman 3513 BIG5 GB2312 3514 Latin 2 None 3515 SJIScode Symbol 3516 Unicode Wansung 3517 </code></pre> 3518 3519 <div style="margin: auto;"> 3520 <h3><a class="anchor" id="endian"></a>-endian <var>type</var></h3> 3521 </div> 3522 3523 <p class="magick-description">Specify endianness (<code>MSB</code> or <code>LSB</code>) of the image.</p> 3524 3525 <p>To print a complete list of endian types, use the <a href="command-line-options.html#list">-list endian</a> option.</p> 3526 3527 <p>Use <a href="command-line-options.html#endian">+endian</a> to revert to unspecified endianness.</p> 3528 3529 3530 <div style="margin: auto;"> 3531 <h3><a class="anchor" id="enhance"></a>-enhance</h3> 3532 </div> 3533 3534 <p class="magick-description">Apply a digital filter to enhance a noisy image.</p> 3535 3536 3537 <div style="margin: auto;"> 3538 <h3><a class="anchor" id="equalize"></a>-equalize</h3> 3539 </div> 3540 3541 <p class="magick-description">perform histogram equalization on the image channel-by-channel.</p> 3542 3543 <p>To perform histogram equalization on all channels in concert, transform the 3544 image into some other color space, such as HSL, OHTA, YIQ or YUV, then 3545 equalize the appropriate intensity-like channel, then convert back to RGB.</p> 3546 3547 <p>For example using HSL, we have: ... <code>-colorspace HSL -channel lightness 3548 -equalize -colorspace RGB</code> ...</p> 3549 3550 <p>For YIQ, YUV and OHTA use the red channel. For example, OHTA is a principal 3551 components transformation that puts most of the information in the first 3552 channel. Here we have ... <code>-colorspace OHTA -channel red -equalize 3553 -colorspace RGB</code> ...</p> 3554 3555 <div style="margin: auto;"> 3556 <h3><a class="anchor" id="evaluate"></a>-evaluate <var>operator value</var></h3> 3557 </div> 3558 3559 <p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or logical expression.</p> 3560 3561 <p>(See the <a href="command-line-options.html#function" >-function</a> operator for some 3562 multi-parameter functions. See the <a href="command-line-options.html#fx" >-fx</a> operator if more 3563 elaborate calculations are needed.)</p> 3564 3565 <p>The behaviors of each <var>operator</var> are summarized in the 3566 following list. For brevity, the numerical value of a "pixel" referred to 3567 below is the value of the corresponding channel of that pixel, while 3568 a "normalized pixel" is that number divided by the maximum 3569 (installation-dependent) value <var>QuantumRange</var>. (If 3570 normalized pixels are used, they are restored, following the other 3571 calculations, to the full range by multiplying by <var>QuantumRange</var>.)</p> 3572 3573 <table class="table table-sm table-striped"> 3574 <col width="25%" /> 3575 <col width="75%" /> 3576 <thead> 3577 <tr> 3578 <th><var>operator</var></th> 3579 <th>Summary (see further below for details)</th> 3580 </tr> 3581 </thead> 3582 <tbody> 3583 3584 <tr><td>Abs </td> <td>Add <var>value</var> to pixels and return absolute value. </td></tr> 3585 <tr><td>Add </td> <td>Add <var>value</var> to pixels. </td></tr> 3586 <tr><td>AddModulus </td> <td>Add <var>value</var> to pixels modulo <var>QuantumRange</var>.</td></tr> 3587 <tr><td>And </td> <td>Binary AND of pixels with <var>value</var>.</td></tr> 3588 <tr><td>Cos, Cosine </td> <td>Apply cosine to pixels with frequency <var>value</var> with 50% bias added.</td></tr> 3589 <tr><td>Divide </td> <td>Divide pixels by <var>value</var>.</td></tr> 3590 <tr><td>Exp </td> <td>base-e exponential function</td></tr> 3591 <tr><td>Exponential </td> <td>base-e exponential function</td></tr> 3592 <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> 3593 <tr><td>Log </td> <td>Apply scaled logarithm to normalized pixels.</td></tr> 3594 <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> 3595 <tr><td>Mean </td> <td>Add the <var>value</var> and divide by 2.</td></tr> 3596 <tr><td>Median </td> <td>Choose the median value from an image sequence.</td></tr> 3597 <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> 3598 <tr><td>Multiply </td> <td>Multiply pixels by <var>value</var>.</td></tr> 3599 <tr><td>Or </td> <td>Binary OR of pixels with <var>value</var>.</td></tr> 3600 <tr><td>Pow </td> <td>Raise normalized pixels to the power <var>value</var>.</td></tr> 3601 <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> 3602 <tr><td>RMS</td> <td>Square the pixel and add the <var>value</var>.</td></tr> 3603 <tr><td>RootMeanSquare</td> <td>Square the pixel and add the <var>value</var>.</td></tr> 3604 <tr><td>Set </td> <td>Set pixel equal to <var>value</var>.</td></tr> 3605 <tr><td>Sin, Sine </td> <td>Apply sine to pixels with frequency <var>value</var> with 50% bias added.</td></tr> 3606 <tr><td>Subtract </td> <td>Subtract <var>value</var> from pixels.</td></tr> 3607 <tr><td>Xor </td> <td>Binary XOR of pixels with <var>value.</var></td></tr> 3608 3609 <tr><td> </td><td> </td></tr> 3610 3611 <tr><td>Gaussian-noise</td><td> </td></tr> 3612 <tr><td>Impulse-noise</td><td> </td></tr> 3613 <tr><td>Laplacian-noise</td><td> </td></tr> 3614 <tr><td>Multiplicative-noise</td> <td>(These are equivalent to the corresponding <a href="command-line-options.html#noise" >-noise</a> operators.)</td></tr> 3615 <tr><td>PoissonNoise</td><td> </td></tr> 3616 <tr><td>Uniform-noise</td><td> </td></tr> 3617 3618 <tr><td> </td><td> </td></tr> 3619 3620 <tr><td>Threshold </td> <td>Threshold pixels larger than <var>value</var>.</td></tr> 3621 <tr><td>ThresholdBlack </td> <td>Threshold pixels to zero values equal to or below <var>value</var>.</td></tr> 3622 <tr><td>ThresholdWhite </td> <td>Threshold pixels to maximum values above <var>value</var>. </td></tr> 3623 </tbody> 3624 </table> 3625 3626 <p>The specified functions are applied only to each previously set <a 3627 href="command-line-options.html#channel" >-channel</a> in the image. If necessary, the results of the 3628 calculations are truncated (clipped) to fit in the interval [0, <var>QuantumRange</var>]. The transparency channel of the image is 3629 represented as a 'alpha' values (0 = fully transparent), so, for example, a 3630 <code>Divide</code> by 2 of the alpha channel will make the image 3631 semi-transparent. Append the percent symbol '<code>%</code>' to specify a value 3632 as a percentage of the <var>QuantumRange</var>.</p> 3633 3634 <p>To print a complete list of <a href="command-line-options.html#evaluate">-evaluate</a> operators, use 3635 <a href="command-line-options.html#list">-list evaluate</a>.</p> 3636 3637 <p>The results of the <code>Add</code>, <code>Subtract</code> and 3638 <code>Multiply</code> methods can also be achieved using either the <a 3639 href="command-line-options.html#level" >-level</a> or the <a href="command-line-options.html#level" >+level</a> operator, with 3640 appropriate argument, to linearly modify the overall range of color values. 3641 Please note, however, that <a href="command-line-options.html#level" >-level</a> treats transparency as 3642 'matte' values (0 = opaque), while <a href="command-line-options.html#level" >-evaluate</a> works with 3643 'alpha' values.</p> 3644 3645 <p><code>AddModulus</code> has been added as of ImageMagick 6.4.8-4 and provides 3646 addition modulo the <var>QuantumRange</var>. It is therefore 3647 equivalent to <code>Add</code> unless the resulting pixel value is outside the 3648 interval [0, <var>QuantumRange</var>]. </p> 3649 3650 <p><code>Exp or Exponential</code> has been added as of ImageMagick 6.6.5-1 and 3651 works on normalized pixel values. The <var>value</var> used with 3652 <code>Exp</code> should be negative so as to produce a decaying exponential 3653 function. Non-negative values will always produce results larger unity and 3654 thus outside the interval [0, <var>QuantumRange</var>]. The 3655 formula is expressed below. </p> 3656 3657 <p class="text-center"> 3658 exp(<var>value</var> <b><var>u</var></b>) 3659 </p> 3660 3661 <p> If the input image is squared, for example, using <a href="command-line-options.html#-function" 3662 >-function polynomial "2 0 0"</a>, then a decaying Gaussian function will be 3663 the result.</p> 3664 3665 <p><code>Log</code> has been added as of ImageMagick 6.4.2-1 and works on 3666 normalized pixel values. This a <var>scaled</var> log function. The <var>value</var> used with <code>Log</code> provides a <var>scaling 3667 factor</var> that adjusts the curvature in the graph of the log function. The 3668 formula applied to a normalized value <b><var>u</var></b> is below. </p> 3669 3670 <p class="text-center"> 3671 log(<var>value</var> <b><var>u</var></b> + 1) / log(<var>value</var> + 1) 3672 </p> 3673 3674 <p><code>Pow</code> has been added as of ImageMagick 6.4.1-9, and works on 3675 normalized pixel values. Note that <code>Pow</code> is related to the <a 3676 href="command-line-options.html#gamma" >-gamma</a> operator. For example, <b>-gamma 2</b> is equivalent 3677 to <b>-evaluate pow 0.5</b>, i.e., a 'square root' function. The value used 3678 with <a href="command-line-options.html#gamma" >-gamma</a> is simply the reciprocal of the value used 3679 with <code>Pow</code>.</p> 3680 3681 <p><code>Cosine</code> and <code>Sine</code> was added as of IM v6.4.8-8 and 3682 converts the image values into a value according to a (co)sine wave function. 3683 The synonyms <code>Cos</code> and <code>Sin</code> may also be used. The output 3684 is biased 50% and normalized by 50% so as to fit in the respective color value 3685 range. The <var>value</var> scaling of the <var>period</var> of the 3686 function (its frequency), and thus determines the number of 'waves' that will 3687 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, 3688 then the effective period is the <var>half</var> the <var>QuantumRange</var>.</p> 3689 3690 <p class="text-center"> 3691 0.5 + 0.5 cos(2 <b><var>u</var></b> <var>value</var>). 3692 </p> 3693 3694 <p>See also the <a href="command-line-options.html#function" >-function</a> operator, which is a 3695 multi-value version of evaluate. </p> 3696 3697 <div style="margin: auto;"> 3698 <h3><a class="anchor" id="evaluate-sequence"></a>-evaluate-sequence <var>operator</var></h3> 3699 </div> 3700 3701 <p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or logical expression over a sequence of images. Ensure all the images in the sequence are in the same colorspace, otherwise you may get unexpected results, e.g. add <a href="command-line-options.html#colorspace" >-colorspace sRGB</a> to your command-line.</p> 3702 3703 <p>To print a complete list of <a 3704 href="command-line-options.html#evaluate-sequence">-evaluate-sequence</a> operators, use <a 3705 href="command-line-options.html#list">-list evaluate</a>.</p> 3706 3707 <div style="margin: auto;"> 3708 <h3><a class="anchor" id="extent"></a>-extent <var>geometry</var></h3> 3709 </div> 3710 3711 <p class="magick-description">Set the image size and offset.</p> 3712 3713 <p>If the image is enlarged, unfilled areas are set to the background color. 3714 To position the image, use offsets in the <var>geometry</var> 3715 specification or precede with a <a href="command-line-options.html#gravity">-gravity</a> setting. To 3716 specify how to compose the image with the background, use <a href="command-line-options.html#compose" 3717 >-compose</a>.</p> 3718 3719 <p>This command reduces or expands a JPEG image to fit on an 800x600 3720 display. If the aspect ratio of the input image isn't exactly 4:3, then the 3721 image is centered on an 800x600 black canvas: </p> 3722 3723 <pre class="highlight"><code>convert input.jpg -resize 800x600 -background black -compose Copy \ 3724 -gravity center -extent 800x600 -quality 92 output.jpg 3725 </code></pre> 3726 3727 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 3728 3729 <div style="margin: auto;"> 3730 <h3><a class="anchor" id="extract"></a>-extract <var>geometry</var></h3> 3731 </div> 3732 3733 <p class="magick-description">Extract the specified area from image.</p> 3734 3735 <p>This option is most useful for extracting a subregion of a very large raw 3736 image. Note that these two commands are equivalent:</p> 3737 3738 <pre class="highlight"><code>convert -size 16000x16000 -depth 8 -extract 640x480+1280+960 \ 3739 image.rgb image.png", 3740 convert -size 16000x16000 -depth 8 'image.rgb[640x480+1280+960]' \ 3741 image.rgb image.png" 3742 </code></pre> 3743 3744 <p>If you omit the offsets, as in</p> 3745 3746 <pre class="highlight"><code>convert -size 16000x16000 -depth 8 -extract 640x480 \ 3747 image.rgb image.png 3748 </code></pre> 3749 3750 <p>the image is <var>resized</var> to the specified dimensions instead, 3751 equivalent to:</p> 3752 3753 <pre class="highlight"><code>convert -size 16000x16000 -depth 8 -resize 640x480 image.rgb image.png 3754 </code></pre> 3755 3756 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 3757 3758 <div style="margin: auto;"> 3759 <h3><a class="anchor" id="family"></a>-family <var>fontFamily</var></h3> 3760 </div> 3761 3762 <p class="magick-description">Set a font family for text.</p> 3763 3764 <p>This setting suggests a font family that ImageMagick should try to use for 3765 rendering text. If the family can be found it is used; if not, a default font 3766 (e.g., "Arial") or a family known to be similar is substituted (e.g., 3767 "Courier" might be used if "System" is requested but not found). </p> 3768 3769 <p>For other settings that affect fonts, see the options <a 3770 href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a 3771 href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 3772 3773 <div style="margin: auto;"> 3774 <h3><a class="anchor" id="features"></a>-features <var>distance</var></h3> 3775 </div> 3776 3777 <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> 3778 3779 <pre class="highlight"><code>Angular Second Moment Sum Entropy 3780 Contrast Entropy 3781 Correlation Difference Variance 3782 Sum of Squares Variance Difference Entropy 3783 Inverse Difference Moment Information Measure of Correlation 1 3784 Sum Average Information Measure of Correlation 2 3785 Sum Variance Maximum Correlation Coefficient 3786 </code></pre> 3787 3788 <div style="margin: auto;"> 3789 <h3><a class="anchor" id="fft"></a>-fft</h3> 3790 </div> 3791 3792 <p class="magick-description">implements the forward discrete Fourier transform (DFT).</p> 3793 3794 <p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows 3795 users in ImageMagick 6.6.0-9). It transforms an image from the normal 3796 (spatial) domain to the frequency domain. In the frequency domain, an image is 3797 represented as a superposition of complex sinusoidal waves of varying 3798 amplitudes. The image x and y coordinates are the possible frequencies along 3799 the x and y directions, respectively, and the pixel intensity values are 3800 complex numbers that correspond to the sinusoidal wave amplitudes. See for 3801 example, <a href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier 3802 Transform</a>, <a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier 3803 Transform</a> and <a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier 3804 Transform</a>.</p> 3805 3806 <p>A single image name is provided as output for this option. However, the 3807 output result will have two components. It is either a two-frame image or two 3808 separate images, depending upon whether the image format specified supports 3809 multi-frame images. The reason that we get a dual output result is because the 3810 frequency domain represents an image using complex numbers, which cannot be 3811 visualized directly. Therefore, the complex values are automagically separated 3812 into a two-component image representation. The first component is the 3813 magnitude of the complex number and the second is the phase of the complex 3814 number. See for example, <a 3815 href="http://en.wikipedia.org/wiki/Complex_numbers">Complex Numbers</a>.</p> 3816 3817 <p>The magnitude and phase component images must be specified using image 3818 formats that do not limit the color or compress the image. Thus, MIFF, TIF, 3819 PFM, EXR and PNG are the recommended image formats to use. All of these 3820 formats, except PNG support multi-frame images. So for example,</p> 3821 3822 <pre class="highlight"><code>convert image.png -fft fft_image.miff 3823 </code></pre> 3824 3825 <p>generates a magnitude image as <code>fft_image.miff[0]</code> and a phase 3826 image as <code>fft_image.miff[1]</code>. Similarly,</p> 3827 3828 <pre class="highlight"><code>convert image.png -fft fft_image.png 3829 </code></pre> 3830 3831 <p>generates a magnitude image as <code>fft_image-0.png</code> and a phase image 3832 as <code>fft_image-1.png</code>. If you prefer this representation, then you can 3833 force any of the other formats to produce two output images by including <a 3834 href="command-line-options.html#adjoin">+adjoin</a> following -fft in the command line.</p> 3835 3836 <p>The input image can be any size, but if not square and even-dimensioned, it 3837 is padded automagically to the larger of the width or height of the input 3838 image and to an even number of pixels. The padding will occur at the bottom 3839 and/or right sides of the input image. The resulting output magnitude and 3840 phase images is square at this size. The kind of padding relies on the <a 3841 href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting.</p> 3842 3843 <p>Both output components will have dynamic ranges that fit within 3844 [0, <var>QuantumRange</var>], so that HDRI need not be enabled. 3845 Phase values nominally range from 0 to 2*, but is scaled to span the full 3846 dynamic range. (The first few releases had non-HDRI scaled but HDRI not 3847 scaled). The magnitude image is not scaled and thus generally will contain 3848 very small values. As such, the image normally will appear totally black. In 3849 order to view any detail, the magnitude image typically is enhanced with a log 3850 function into what is usually called the spectrum. A log function is used to 3851 enhance the darker values more in comparison to the lighter values. This can 3852 be done, for example, as follows:</p> 3853 3854 <pre class="highlight"><code>convert fft_image.miff[0] -contrast-stretch 0 \ 3855 -evaluate log 1000 fft_image_spectrum.png" 3856 </code></pre> 3857 3858 <p>where either <a href="command-line-options.html#contrast-stretch">-contrast-stretch</a> 0 or <a 3859 href="command-line-options.html#auto-level">-auto-level</a> is used to scale the image to full dynamic 3860 range, first. The argument to the <a href="command-line-options.html#evaluate">-evaluate</a> log 3861 typically is specified between 100 and 10,000, depending upon the amount of 3862 detail that one wants to bring out in the spectrum. Larger values produce more 3863 visible detail. Too much detail, however, may hide the important features.</p> 3864 3865 <p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to 3866 use <a href="command-line-options.html#fft">-fft</a>.</p> 3867 3868 <p>Use <a href="command-line-options.html#fft">+fft</a> to produce two output images that are the real 3869 and imaginary components of the complex valued Fourier transform.</p> 3870 3871 <p>However, as the real and imaginary components can contain negative values, 3872 this requires that IM be configured with HDRI enabled. In this case, you must 3873 use either MIFF, TIF, PFM or MPC formats for the real and imaginary component 3874 results, since they are formats that preserve both negative and fractional 3875 values without clipping them or truncating the fractional part. With either 3876 MIFF or TIF, one should add <code>-define quantum:format=32</code>, to allow those image 3877 types to work properly in HDRI mode without clipping.</p> 3878 3879 <p>The real and imaginary component images resulting from <a 3880 href="command-line-options.html#fft">+fft</a> are also square, even dimensioned images due to the same 3881 padding that was discussed above for the magnitude and phase component 3882 images.</p> 3883 3884 <p>See the discussion on HDRI implementations of ImageMagick on the page <a 3885 href="high-dynamic-range.html" >High Dynamic-Range Images</a>. For more 3886 about HDRI go the ImageMagick <a 3887 href="../Usage/basics/#hdri" >Usage</a> pages, <a 3888 href="http://www.fmwconcepts.com/imagemagick/fourier_transforms/fourier.html" 3889 >Fred's Fourier Processing With ImageMagick page</a> or this <a 3890 href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging" >Wikipedia</a> 3891 entry. </p> 3892 3893 <p>By default the FFT is normalized (and the IFT is not). Use "<code><a href="command-line-options.html#define" >-define</a> fourier:normalize=forward</code> to explicitly normalize the FFT and unnormalize the IFT.</p> 3894 3895 3896 <div style="margin: auto;"> 3897 <h3><a class="anchor" id="fill"></a>-fill <var>color</var></h3> 3898 </div> 3899 3900 <p class="magick-description">color to use when filling a graphic primitive.</p> 3901 3902 <p>This option accepts a color name, a hex color, or a numerical RGB, RGBA, 3903 HSL, HSLA, CMYK, or CMYKA specification. See <a href="../www/color.html" >Color Names</a> for 3904 a description of how to properly specify the color argument.</p> 3905 3906 <p>Enclose the color specification in quotation marks to prevent the "#" or 3907 the parentheses from being interpreted by your shell.</p> 3908 3909 <p>For example,</p> 3910 3911 <pre class="highlight"><code>-fill blue 3912 -fill "#ddddff" 3913 -fill "rgb(255,255,255)" 3914 </code></pre> 3915 3916 <p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 3917 3918 <p>To print a complete list of color names, use the <a href="command-line-options.html#list">-list color</a> option.</p> 3919 3920 <div style="margin: auto;"> 3921 <h3><a class="anchor" id="filter"></a>-filter <var>type</var></h3> 3922 </div> 3923 3924 <p class="magick-description">Use this <var>type</var> of filter when resizing or distorting an image.</p> 3925 3926 <p>Use this option to affect the resizing operation of an image during 3927 operations such as <a href="command-line-options.html#resize">-resize</a> and <a href="command-line-options.html#distort" 3928 >-distort</a>. For example you can use a simple resize filter such as:</p> 3929 3930 <pre class="highlight"><code>Point Hermite Cubic 3931 Box Gaussian Catrom 3932 Triangle Quadratic Mitchell 3933 CubicSpline 3934 </code></pre> 3935 3936 <p>Use <code>-define filter:lobes={2,3,4}</code> to specify the support size for filtering for the <code>CubicSpline</code> filter.</p> 3937 3938 <p>The <code>Bessel</code> and <code>Sinc</code> filter is also provided (as well 3939 as a faster <code>SincFast</code> equivalent form). However these filters are 3940 generally useless on their own as they are infinite filters that are being 3941 clipped to the filters support size. Their direct use is not recommended 3942 except via expert settings (see below). </p> 3943 3944 <p>Instead these special filter functions are typically windowed by a windowing 3945 function that the <a href="command-line-options.html#filter" >-filter</a> setting defines. That is 3946 using these functions will define a 'Windowed' filter, appropriate to the 3947 operator involved. Windowed filters include: </p> 3948 3949 <pre class="highlight"><code>Lanczos Hamming Parzen 3950 Blackman Kaiser Welsh 3951 Hanning Bartlett Bohman 3952 </code></pre> 3953 3954 <p>Also one special self-windowing filter is also provided 3955 <code>Lagrange</code>, which will automagically re-adjust its function depending 3956 on the current 'support' or 'lobes' expert settings (see below).</p> 3957 3958 <p>If you do not select a filter with this option, the filter defaults to 3959 <code>Mitchell</code> for a colormapped image, an image with a matte channel, or 3960 if the image is enlarged. Otherwise the filter default to 3961 <code>Lanczos</code>.</p> 3962 3963 <p>To print a complete list of resize filters, use the <a href="command-line-options.html#list">-list 3964 filter</a> option.</p> 3965 3966 <p>You can modify how the filter behaves as it scales your image through the 3967 use of these expert settings (see also <a href="command-line-options.html#define" >-define</a> and <a 3968 href="command-line-options.html#set" >-set</a>):-</p> 3969 3970 <table class="table table-sm table-striped"> 3971 <tr> 3972 <td>-define filter:blur=<var>factor</var></td> 3973 <td>Scale the X axis of the filter (and its window). Use > 1.0 for 3974 blurry or < 1.0 for sharp. This should only be used with Gaussian and 3975 Gaussian-like filters simple filters, or you may not get the expected 3976 results. </td> 3977 </tr> 3978 3979 <tr> 3980 <td>-define filter:support=<var>radius</var></td> 3981 <td>Set the filter support radius. Defines how large the filter should be and 3982 thus directly defines how slow the filtered resampling process is. All 3983 filters have a default 'preferred' support size. Some filters like 3984 <code>Lagrange</code> and windowed filters adjust themselves depending on 3985 this value. With simple filters this value either does nothing (but slow 3986 the resampling), or will clip the filter function in a detrimental way. 3987 </td> 3988 </tr> 3989 3990 <tr> 3991 <td>-define filter:lobes=<var>count</var></td> 3992 <td>Set the number of lobes to use for the Sinc/Bessel filter. This an 3993 alternative way of specifying the 'support' range of the filter, that is 3994 designed to be more suited to windowed filters, especially when used for 3995 image distorts.</td> 3996 </tr> 3997 3998 <tr> 3999 <td>-define filter:sigma=<var>value</var></td> 4000 <td>The 'sigma' value used to define the <code>Gaussian</code> filter. Default 4001 sigma value is '<code>0.5</code>'. It only affects <code>Gaussian</code> but 4002 does not shrink (but may enlarge) the filter's 'support'. It can be used 4003 to generate very small blurs but without the filter 'missing' pixels due 4004 to using a small support setting. A larger value of '<code>0.707</code>' 4005 (a value of '1/sqrt(2)') is another common setting. </td> 4006 </tr> 4007 4008 <tr> 4009 <td>-define filter:b=<var>b-spline_factor</var></td> 4010 </tr> 4011 4012 <tr> 4013 <td>-define filter:c=<var>keys_alpha_factor</var></td> 4014 <td>Redefine the values used for cubic filters such as <code>Cubic</code>, 4015 <code>Catrom</code>, <code>Mitchel</code>, and <code>Hermite</code>, as well as 4016 the <code>Parzen</code> cubic windowing function. If only one of the values 4017 are defined, the other is set so as to generate a 'Cubic-Keys' filter. 4018 The values meaning was defined by a research paper by 4019 Mitchell-Netravali.</td> 4020 </tr> 4021 4022 <tr> 4023 <td>-define filter:kaiser-beta=<var>value</var></td> 4024 <td>The 'alpha' value used to as part of the Kaiser Windowing function. 4025 Default value is '6.5'. It only affects Kaiser windowing function, and 4026 does not affect any other attributes. 4027 Before ImageMagick v6.7.6-10, this option was known as "filter:alpha", (an 4028 inheritance from the very old "zoom" program). It was changed to bring the 4029 function in line with more modern academic research usage, and better 4030 assign it be more definitive. </td> 4031 </tr> 4032 4033 <tr> 4034 <td>-define filter:kaiser-alpha=<var>value</var></td> 4035 <td>This value when multiplied by 'PI' is equivalent to "kaiser-beta", and 4036 will override that setting. It only affects Kaiser windowing function, 4037 and does not affect any other attributes. </td> 4038 </tr> 4039 4040 <tr> 4041 <td>-define filter:filter=<var>filter_function</var></td> 4042 <td>Use this function directly as the weighting filter. This will allow 4043 you to directly use a windowing function such as <code>Blackman</code>, 4044 as a resampling filter, rather than as its normal usage as a windowing 4045 function. If defined, no windowing function also defined, the window function is set 4046 to <code>Box</code>). Directly specifying <code>Sinc</code> or <code>Jinc</code> 4047 as a filter will also do this. </td> 4048 </tr> 4049 4050 <tr> 4051 <td>-define filter:window=<var>filter_function</var></td> 4052 <td>The IIR (infinite impulse response) filters <code>Sinc</code> and 4053 <code>Jinc</code> are windowed (brought down to zero over the defined 4054 support range) with the given filter. This allows you to specify a filter 4055 function to be used as a windowing function for these IIR filters. 4056 Many of the defined filters are actually windowing functions for these IIR 4057 filters. A typical choices is <code>Box</code>, (which effectively turns 4058 off the windowing function). </td> 4059 </tr> 4060 4061 <tr> 4062 <td>-define filter:win-support=<var>radius</var></td> 4063 <td>Scale windowing function to this size instead. This causes the windowing 4064 (or self-windowing Lagrange filter) to act is if the support window is 4065 larger than what is actually supplied to the calling operator. The filter 4066 however is still clipped to the real support size given. If unset this 4067 will equal the normal filter support size. </td> 4068 </tr> 4069 4070 <tr> 4071 <td>-define filter:verbose=<var>1</var></td> 4072 <td>This causes IM to print information on the final internal filter 4073 selection to standard output. This includes a commented header on the 4074 filter settings being used, and data allowing the filter weights to be 4075 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 4076 a <code>SincFast</code> windowed <code>SincFast</code> filter, while 4077 <code>Mitchell</code> is defined as a general <code>Cubic</code> family filter 4078 with specific 'B' and 'C' settings. </td> 4079 </tr> 4080 4081 </table> 4082 4083 <p>For example, to get a 8 lobe jinc windowed sinc filter (Genseng filter?):</p> 4084 4085 <pre class="highlight"><code>convert image.png \ 4086 -filter sinc \ 4087 -set filter:window=jinc \ 4088 -set filter:lobes=8 \ 4089 -resize 150% image.jpg" 4090 </code></pre> 4091 4092 <p>Or a raw un-windowed Sinc filter with 4 lobes:</p> 4093 4094 <pre class="highlight"><code>convert image.png \ 4095 -set filter:filter=sinc \ 4096 -set filter:lobes=4 \ 4097 -resize 150% image.jpg" 4098 </code></pre> 4099 4100 <p>To extract the data for a raw windowing function, combine it with 4101 a '<code>Box</code>' filter. For example the '<code>Welch</code> parabolic 4102 windowing function. </p> 4103 4104 <pre class="highlight"><code>convert null: -define filter:filter=Box \ 4105 -define filter:window=Welch \ 4106 -define filter:support=1.0 \ 4107 -define filter:verbose=1 \ 4108 -resize 2 null: > window_welch.dat 4109 gnuplot 4110 set grid 4111 plot \"window_welch.dat\" with lines 4112 </code></pre> 4113 4114 <p>Note that the use of expert options is provided for image processing experts 4115 who have studied and understand how resize filters work. Without this 4116 knowledge, and an understanding of the definition of the actual filters 4117 involved, using expert settings are more likely to be detrimental to your image 4118 resizing.</p> 4119 4120 4121 <div style="margin: auto;"> 4122 <h3><a class="anchor" id="flatten"></a>-flatten</h3> 4123 </div> 4124 4125 <p class="magick-description">This is a simple alias for the <a href="command-line-options.html#layers" >-layers</a> method "flatten".</p> 4126 4127 4128 <div style="margin: auto;"> 4129 <h3><a class="anchor" id="flip"></a>-flip</h3> 4130 </div> 4131 4132 <p class="magick-description">create a <var>mirror image</var></p> 4133 4134 <p>reflect the scanlines in the vertical direction. The image will be mirrored 4135 upside-down. </p> 4136 4137 4138 <div style="margin: auto;"> 4139 <h3><a class="anchor" id="floodfill"></a>-floodfill {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var> <var>color</var></h3> 4140 </div> 4141 4142 <p class="magick-description">floodfill the image with color at the specified offset.</p> 4143 4144 <p>Flood fill starts from the given 'seed point' which is not gravity affected. 4145 Any color that matches within <a href="command-line-options.html#fuzz" >-fuzz</a> color distance of the 4146 given <var>color</var> argument, connected to that 'seed point' 4147 will be replaced with the current <a href="command-line-options.html#fill" >-fill</a> color. </p> 4148 4149 <p>Note that if the pixel at the 'seed point' does not itself match the given 4150 <var>color</var> (according to <a href="command-line-options.html#fuzz" >-fuzz</a>), then no 4151 action will be taken. </p> 4152 4153 <p>This operator works more like the <a href="command-line-options.html#opaque" >-opaque</a> option, than 4154 a more general flood fill that reads the matching color directly at the 'seed 4155 point'. For this form of flood fill, look at <a href="command-line-options.html#draw" >-draw</a> and 4156 its 'color floodfill' drawing method. </p> 4157 4158 4159 <div style="margin: auto;"> 4160 <h3><a class="anchor" id="flop"></a>-flop</h3> 4161 </div> 4162 4163 <p class="magick-description">create a <var>mirror image</var>.</p> 4164 4165 <p>Reflect the scanlines in the horizontal direction, just like the image in 4166 a vertical mirror. </p> 4167 4168 4169 <div style="margin: auto;"> 4170 <h3><a class="anchor" id="font"></a>-font <var>name</var></h3> 4171 </div> 4172 4173 <p class="magick-description">set the font to use when annotating images with text, or creating labels.</p> 4174 4175 <p>To print a complete list of fonts, use the <a href="command-line-options.html#list">-list font</a> 4176 option (for versions prior to 6.3.6, use 'type' instead of 'font').</p> 4177 4178 <p>In addition to the fonts specified by the above pre-defined list, you can 4179 also specify a font from a specific source. For example <code>Arial.ttf</code> 4180 is a TrueType font file, <code>ps:helvetica</code> is PostScript font, and 4181 <code>x:fixed</code> is X11 font.</p> 4182 4183 <p>For other settings that affect fonts, see the options <a 4184 href="command-line-options.html#family">-family</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a 4185 href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 4186 4187 4188 <div style="margin: auto;"> 4189 <h3><a class="anchor" id="foreground"></a>-foreground <var>color</var></h3> 4190 </div> 4191 4192 <p class="magick-description">Define the foreground color for menus.", "display</p> 4193 4194 <p>The color is specified using the format described under the <a 4195 href="command-line-options.html#fill">-fill</a> option.</p> 4196 4197 <p>The default foreground color is black.</p> 4198 4199 <div style="margin: auto;"> 4200 <h3><a class="anchor" id="format"></a>-format <var>type</var></h3> 4201 </div> 4202 4203 <p class="magick-description">the image format type.</p> 4204 4205 <p>When used with the <code>mogrify</code> utility, this option converts any 4206 image to the image <a href="formats.html">format</a> you specify. 4207 For a list of image format types supported by ImageMagick, use <a 4208 href="command-line-options.html#list">-list format</a>.</p> 4209 4210 <p>By default the file is written to its original name. However, if the 4211 filename extension matches a supported format, the extension is replaced with 4212 the image format type specified with <a href="command-line-options.html#format">-format</a>. For 4213 example, if you specify <var>tiff</var> as the format type and the 4214 input image filename is <var>image.gif</var>, the output image 4215 filename becomes <var>image.tiff</var>.</p> 4216 4217 <div style="margin: auto;"> 4218 <h3><a class="anchor" id="format_identify_"></a>-format <var>string</var></h3> 4219 </div> 4220 4221 <p class="magick-description">output formatted image characteristics.</p> 4222 4223 <p>See <a href="../www/escape.html">Format and Print Image 4224 Properties</a> for an explanation on how to specify the argument to this 4225 option.</p> 4226 4227 <div style="margin: auto;"> 4228 <h3><a class="anchor" id="frame"></a>-frame <var>geometry</var></h3> 4229 </div> 4230 4231 <p class="magick-description">Surround the image with a border or beveled frame.</p> 4232 4233 <p>The color of the border is specified with the <a href="command-line-options.html#mattecolor" 4234 >-mattecolor</a> command line option. </p> 4235 4236 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <var>size</var> portion of the <var>geometry</var> argument indicates the amount of extra width and 4237 height that is added to the dimensions of the image. If no offsets are given 4238 in the <var>geometry</var> argument, then the border added is 4239 a solid color. Offsets <var>x</var> and <var>y</var>, if present, specify that 4240 the width and height of the border is partitioned to form an outer bevel of 4241 thickness <var>x</var> pixels and an inner bevel of thickness 4242 <var>y</var> pixels. Negative offsets make no sense as frame arguments. 4243 </p> 4244 4245 <p>The <a href="command-line-options.html#frame">-frame</a> option is affected by the current <a 4246 href="command-line-options.html#compose">-compose</a> setting and assumes that this is using the default 4247 '<code>Over</code>' composition method. It generates an image of the appropriate 4248 size with the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting, and then 4249 draws the frame of four distinct colors close to the current <a 4250 href="command-line-options.html#mattecolor">-mattecolor</a>. The original image is then overlaid onto 4251 center of this image. This means that with the default compose method of 4252 '<code>Over</code>' any transparent parts may be replaced by the current <a 4253 href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p> 4254 4255 <p>The image composition is not 4256 affected by the <a href="command-line-options.html#gravity">-gravity</a> option.</p> 4257 4258 4259 <div style="margin: auto;"> 4260 <h3><a class="anchor" id="frame_import_"></a>-frame</h3> 4261 </div> 4262 4263 <p class="magick-description">include the X window frame in the imported image. </p> 4264 <div style="margin: auto;"> 4265 <h3><a class="anchor" id="function"></a>-function <var>function</var> <var>parameters</var></h3> 4266 </div> 4267 4268 <p class="magick-description">Apply a function to channel values.</p> 4269 4270 <p>This operator performs calculations based on the given arguments to modify 4271 each of the color values for each previously set <a 4272 href="command-line-options.html#channel">-channel</a> in the image. See <a 4273 href="command-line-options.html#evaluate">-evaluate</a> for details concerning how the results of the 4274 calculations are handled.</p> 4275 4276 <p>This is can be considered a multi-argument version of the <a 4277 href="command-line-options.html#evaluate">-evaluate</a> operator. (Added in 4278 ImageMagick 6.4.88.)</p> 4279 4280 <p>Here, <var>parameters</var> is a comma-separated list of 4281 numerical values. The number of values varies depending on which <var>function</var> is selected. Choose the <var>function</var> from:</p> 4282 4283 <pre class="highlight"><code>Polynomial 4284 Sinusoid 4285 Arcsin 4286 Arctan 4287 </code></pre> 4288 4289 <p>To print a complete list of <a href="command-line-options.html#function">-function</a> operators, 4290 use <a href="command-line-options.html#list">-list function</a>. Descriptions follow.</p> 4291 4292 <dl class="row"> 4293 <dt class="col-md-4">Polynomial</dt> 4294 <dd class="col-md-8"><p>The <code>Polynomial</code> function takes an arbitrary number of parameters, 4295 these being the coefficients of a polynomial, in decreasing order of degree. 4296 That is, entering</p> 4297 4298 <pre class="highlight"><code>-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> 4299 </code></pre> 4300 4301 <p>will invoke a polynomial function given by</p> 4302 4303 <pre class="highlight"><code><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>, 4304 </code></pre> 4305 4306 <p>where <b><var>u</var></b> is pixel's original normalized channel value.</p> 4307 4308 <p>The <code>Polynomial</code> function can be used in place of <code>Set</code> 4309 (the <var>constant</var> polynomial) and <code>Add</code>, <code>Divide</code>, 4310 <code>Multiply</code>, and <code>Subtract</code> (some <var>linear</var> 4311 polynomials) of the <a href="command-line-options.html#evaluate">-evaluate</a> operator. The <a 4312 href="command-line-options.html#level">-level</a> operator also affects channels linearly. Some 4313 correspondences follow.</p> 4314 4315 <table class="table table-sm table-striped"> 4316 <tr> 4317 <td>-evaluate Set <var>value</var> </td> 4318 <td>-function Polynomial <var>value</var></td> 4319 <td>(Constant functions; set <var>value</var>100% gray when channels are RGB.)</td> 4320 </tr> 4321 <tr> 4322 <td>-evaluate Add <var>value</var> </td> 4323 <td>-function Polynomial 1,<var>value</var></td> 4324 </tr> 4325 <tr> 4326 <td>-evaluate Subtract <var>value</var> </td> 4327 <td>-function Polynomial 1,<var>value</var></td> 4328 </tr> 4329 <tr> 4330 <td>-evaluate Multiply <var>value</var> </td> 4331 <td>-function Polynomial <var>value</var>,0</td> 4332 </tr> 4333 <tr> 4334 <td>+level black% x white%</td> 4335 <td>-function Polynomial A,B</td> 4336 <td>(Reduce contrast. Here, A=(white-black)/100 and B=black/100.)</td> 4337 </tr> 4338 </table> 4339 4340 <p>The <code>Polynomial</code> function gives great versatility, since 4341 polynomials can be used to fit any continuous curve to any degree of accuracy 4342 desired.</p> 4343 4344 </dd> 4345 <dt class="col-md-4">Sinusoid</dt> 4346 <dd class="col-md-8"> 4347 <p>The <code>Sinusoid</code> function can be used to vary the channel values 4348 sinusoidally by setting frequency, phase shift, amplitude, and a bias. These 4349 values are given as one to four parameters, as follows,</p> 4350 4351 <pre class="highlight"><code>-function <code>Sinusoid</code> <var>freq</var>,[<var>phase</var>,[<var>amp</var>,[<var>bias</var>]]] 4352 </code></pre> 4353 4354 <p>where <var>phase</var> is in degrees. (The domain [0,1] of the function 4355 corresponds to 0 through <var>freq</var>360 degrees.) 4356 The result is that if a pixel's normalized channel value is originally 4357 <b><var>u</var></b>, its resulting normalized value is given by </p> 4358 4359 <pre class="highlight"><code><var>amp</var> * sin(2** (<var>freq</var> * <b><var>u</var></b> + <var>phase</var> / 360)) + <var>bias</var> 4360 </code></pre> 4361 4362 <p> For example, the following generates a curve that starts and ends at 0.9 4363 (when <b><var>u</var></b>=0 and 1, resp.), oscillating three times between 4364 .7.2=.5 and .7+.2=.9. </p> 4365 4366 <pre class="highlight"><code>-function Sinusoid 3,-90,.2,.7 4367 </code></pre> 4368 4369 <p>The default values of <var>amp</var> and <var>bias</var> are both .5. The default for <var>phase</var> 4370 is 0.</p> 4371 4372 <p>The <code>Sinusoid</code> function generalizes <code>Sin</code> and 4373 <code>Cos</code> of the <a href="command-line-options.html#evaluate">-evaluate</a> operator by allowing 4374 varying amplitude, phase and bias. The correspondence is as follows.</p> 4375 4376 <table class="table table-sm table-striped"> 4377 <tr> 4378 <td>-evaluate Sin <var>freq</var> </td> 4379 <td>-function Sinusoid <var>freq</var>,0 </td> 4380 </tr> 4381 <tr> 4382 <td>-evaluate Cos <var>freq</var> </td> 4383 <td>-function Sinusoid <var>freq</var>,90 </td> 4384 </tr> 4385 </table> 4386 </dd> 4387 <dt class="col-md-4">ArcSin</dt> 4388 <dd class="col-md-8"> 4389 <p>The <code>ArcSin</code> function generates the inverse curve of a Sinusoid, 4390 and can be used to generate cylindrical distortion and displacement maps. 4391 The curve can be adjusted relative to both the input values and output range 4392 of values.</p> 4393 4394 <pre class="highlight"><code>-function <code>ArcSin</code> <var>width</var>,[<var>center</var>,[<var>range</var>,[<var>bias</var>]]] 4395 </code></pre> 4396 4397 <p>with all values given in terms of normalized color values (0.0 for black, 4398 1.0 for white). Defaulting to values covering the full range from 0.0 to 1.0 4399 for bout input (<var>width</var>), and output (<var>width</var>) values. '<code>1.0,0.5,1.0,0.5</code>' </p> 4400 4401 <pre class="highlight"><code><var>range</var>/ * asin( 2/<var>width</var> * ( <b><var>u</var></b> - <var>center</var> ) ) + <var>bias</var> 4402 </code></pre> 4403 4404 </dd> 4405 <dt class="col-md-4">ArcTan</dt> 4406 <dd class="col-md-8"> 4407 <p>The <code>ArcTan</code> function generates a curve that smooth crosses from 4408 limit values at infinities, though a center using the given slope value. 4409 All these values can be adjusted via the arguments.</p> 4410 4411 <pre class="highlight"><code>-function <code>ArcTan</code> <var>slope</var>,[<var>center</var>,[<var>range</var>,[<var>bias</var>]]] 4412 </code></pre> 4413 4414 <p>Defaulting to '<code>1.0,0.5,1.0,0.5</code>'. 4415 </p> 4416 4417 <pre class="highlight"><code><var>range</var>/ * atan( <var>slope</var>* * ( <b><var>u</var></b> - <var>center</var> ) ) + <var>bias</var> 4418 </code></pre> 4419 </dd> 4420 </dl> 4421 4422 4423 4424 <div style="margin: auto;"> 4425 <h3><a class="anchor" id="fuzz"></a>-fuzz <var>distance</var>{<var>%</var>}</h3> 4426 </div> 4427 4428 <p class="magick-description">Colors within this <var>distance</var> are considered equal.</p> 4429 4430 <p>A number of algorithms search for a target color. By default the color must 4431 be exact. Use this option to match colors that are close to the target color 4432 in RGB space. For example, if you want to automagically trim the edges of an 4433 image with <a href="command-line-options.html#trim">-trim</a> but the image was scanned and the target 4434 background color may differ by a small amount. This option can account for 4435 these differences.</p> 4436 4437 <p>The <var>distance</var> can be in absolute intensity units or, by 4438 appending <code>%</code> as a percentage of the maximum possible intensity (255, 4439 65535, or 4294967295).</p> 4440 4441 <p>Use <a href="command-line-options.html#fuzz" >+fuzz</a> to reset the fuzz value to 0.</p> 4442 4443 4444 <div style="margin: auto;"> 4445 <h3><a class="anchor" id="fx"></a>-fx <var>expression</var></h3> 4446 </div> 4447 4448 <p class="magick-description">apply a mathematical expression to an image or image channels.</p> 4449 4450 <p>If the first character of <var>expression</var> is <code>@</code>, 4451 the expression is read from a file titled by the remaining characters in the 4452 string.</p> 4453 4454 <p>See <a href="../www/fx.html">FX, 4455 The Special Effects Image Operator</a> for a detailed discussion of this 4456 option.</p> 4457 4458 4459 <div style="margin: auto;"> 4460 <h3><a class="anchor" id="gamma"></a>-gamma <var>value</var></h3> 4461 </div> 4462 4463 <p class="magick-description">level of gamma correction.</p> 4464 4465 <p>The same color image displayed on two different workstations may look 4466 different due to differences in the display monitor. Use gamma correction to 4467 adjust for this color difference. Reasonable values extend from 4468 <code>0.8</code> to <code>2.3</code>. Gamma less than 1.0 darkens the image and 4469 gamma greater than 1.0 lightens it. Large adjustments to image gamma may 4470 result in the loss of some image information if the pixel quantum size is only 4471 eight bits (quantum range 0 to 255).</p> 4472 4473 <p>Gamma adjusts the image's channel values pixel-by-pixel according to 4474 a power law, namely, pow(pixel,1/gamma) or pixel^(1/gamma), where pixel is the 4475 normalized or 0 to 1 color value. For example, using a value of gamma=2 is the 4476 same as taking the square root of the image.</p> 4477 4478 <p>Use <a href="command-line-options.html#gamma">+gamma <var>value</var></a> to set the 4479 image gamma level without actually adjusting the image pixels. This option 4480 is useful if the image is of a known gamma but not set as an image attribute 4481 (e.g. PNG images). Write the "file gamma" which is the reciprocal of the 4482 display gamma; e.g., if your image is sRGB and you want to write a PNG gAMA 4483 chunk, use</p> 4484 4485 <pre class="highlight"><code>convert input.png +gamma .45455 output.png 4486 </code></pre> 4487 4488 <p>(0.45455 is 1/2.2)</p> 4489 4490 <p>Note that gamma adjustments are also available via the <a href="command-line-options.html#level">-level</a> operator.</p> 4491 4492 <div style="margin: auto;"> 4493 <h3><a class="anchor" id="gaussian-blur"></a>-gaussian-blur <var>radius</var><br />-gaussian-blur <var>radius</var>x<var>sigma</var></h3> 4494 </div> 4495 4496 <p class="magick-description">Blur the image with a Gaussian operator.</p> 4497 4498 <p>Convolve the image with a Gaussian or normal distribution using the given 4499 <var >Sigma</var> value. The formula is:</p> 4500 4501 <p class="text-center"><img class="img-thumbnail" alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png"/> </p> 4502 4503 <p>The <var >Sigma</var> value is the important argument, and 4504 determines the actual amount of blurring that will take place. </p> 4505 4506 <p>The <var >Radius</var> is only used to determine the size of the 4507 array which will hold the calculated Gaussian distribution. It should be an 4508 integer. If not given, or set to zero, IM will calculate the largest possible 4509 radius that will provide meaningful results for the Gaussian distribution. 4510 </p> 4511 4512 <p>The larger the <var >Radius</var> the radius the slower the 4513 operation is. However too small a <var >Radius</var>, and severe 4514 aliasing effects may result. As a guideline, <var >Radius</var> 4515 should be at least twice the <var >Sigma</var> value, though three 4516 times will produce a more accurate result. </p> 4517 4518 <p>This differs from the faster <a href="command-line-options.html#blur">-blur</a> operator in that a 4519 full 2-dimensional convolution is used to generate the weighted average of the 4520 neighboring pixels. </p> 4521 4522 <p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 4523 pixels which are outside the image proper are blurred into the final result. 4524 </p> 4525 4526 4527 <div style="margin: auto;"> 4528 <h3><a class="anchor" id="geometry"></a>-geometry <var>geometry</var></h3> 4529 </div> 4530 4531 <p class="magick-description">Set the preferred size and location of the image.</p> 4532 4533 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 4534 4535 <div style="margin: auto;"> 4536 <h3><a class="anchor" id="gravity"></a>-gravity <var>type</var></h3> 4537 </div> 4538 4539 <p class="magick-description">Sets the current gravity suggestion for various other settings and options.</p> 4540 4541 <p>Choices include: <code>NorthWest</code>, <code>North</code>, 4542 <code>NorthEast</code>, <code>West</code>, <code>Center</code>, <code>East</code>, 4543 <code>SouthWest</code>, <code>South</code>, <code>SouthEast</code>. Use <a 4544 href="command-line-options.html#list">-list gravity</a> to get a complete list of <a 4545 href="command-line-options.html#gravity">-gravity</a> settings available in your ImageMagick 4546 installation.</p> 4547 4548 <p>The direction you choose specifies where to position text or subimages. For 4549 example, a gravity of <code>Center</code> forces the text to be centered within 4550 the image. By default, the image gravity is <code>undefined</code>. See <a 4551 href="command-line-options.html#draw">-draw</a> for more details about graphic primitives. Only the 4552 text primitive of <a href="command-line-options.html#draw">-draw</a> is affected by the <a 4553 href="command-line-options.html#gravity">-gravity</a> option.</p> 4554 4555 <p>The <a href="command-line-options.html#gravity">-gravity</a> option is also used in concert with the 4556 <a href="command-line-options.html#geometry">-geometry</a> setting and other settings or options that 4557 take <var>geometry</var> as an argument, such as the <a 4558 href="command-line-options.html#crop">-crop</a> option. </p> 4559 4560 <p>If a <a href="command-line-options.html#gravity">-gravity</a> setting occurs before another option 4561 or setting having a <var>geometry</var> argument that specifies an 4562 offset, the offset is usually applied to the point within the image suggested 4563 by the <a href="command-line-options.html#gravity">-gravity</a> argument. Thus, in the following 4564 command, for example, suppose the file <code>image.png</code> has dimensions 4565 200x100. The offset specified by the argument to <a href="command-line-options.html#region">-region</a> 4566 is (40,+20). The argument to <a href="command-line-options.html#gravity">-gravity</a> is 4567 <code>Center</code>, which suggests the midpoint of the image, at the point 4568 (100,50). The offset (40,20) is applied to that point, giving 4569 (10040,50+20)=(60,70), so the specified 10x10 region is located at 4570 that point. (In addition, the <a href="command-line-options.html#gravity">-gravity</a> affects the 4571 region itself, which is <var>centered</var> at the pixel 4572 coordinate (60,70). (See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.)</p> 4573 4574 <pre class="highlight"><code>convert image.png -gravity Center -region 10x10-40+20 \ 4575 -negate output.png 4576 </code></pre> 4577 4578 <p>When used as an option to <a href="../www/composite.html">composite</a>, <a 4579 href="command-line-options.html#gravity">-gravity</a> gives the direction that the image gravitates 4580 within the composite.</p> 4581 4582 <p>When used as an option to <a href="montage.html">montage</a>, <a 4583 href="command-line-options.html#gravity">-gravity</a> gives the direction that an image gravitates 4584 within a tile. The default gravity is <code>Center</code> for this purpose.</p> 4585 4586 <p>Use <a href="command-line-options.html#gravity">+gravity</a> to return gravity to its default value.</p> 4587 4588 4589 <div style="margin: auto;"> 4590 <h3><a class="anchor" id="grayscale"></a>-grayscale <var>method</var></h3> 4591 </div> 4592 4593 <p class="magick-description">convert image to grayscale.</p> 4594 4595 <p>This will use one of the <a href="command-line-options.html#intensity" >-intensity</a> methods to 4596 convert the given image into a grayscale image. </p> 4597 4598 <p>For example, to convert an image to (linear) Rec709Luminance grayscale, type:</p> 4599 4600 <pre class="highlight"><code>convert in.png -grayscale Rec709Luminance out.png 4601 </code></pre> 4602 4603 <p>which is equivalent to:</p> 4604 4605 <pre class="highlight"> 4606 <code>convert in.png -colorspace RGB -colorspace Gray out.png</code> 4607 or 4608 <code>convert in.png -colorspace LinearGray out.png</code> 4609 </pre> 4610 4611 <p>Note that LinearGray is new as of Imagemagick 6.9.9-29 and 7.0.7-17.</p> 4612 4613 <p>Similarly, to convert an image to (non-linear) Rec709Luma grayscale, type:</p> 4614 4615 <pre class="highlight"><code>convert in.png -grayscale Rec709Luma out.png 4616 </code></pre> 4617 4618 <p>which is equivalent to:</p> 4619 4620 <pre class="highlight"><code>convert in.png -colorspace Gray out.png 4621 </code></pre> 4622 4623 <p>Note that a 'colorspace' intensity method will produce the same result 4624 regardless of the current colorpsace of the image. But a 'mathematical' 4625 intensity method depends on the current colorspace the image is currently 4626 using. </p> 4627 4628 <p>While this operation uses an <a href="command-line-options.html#intensity" >-intensity</a> method, 4629 it does not use or set the <a href="command-line-options.html#intensity" >-intensity</a> setting, so 4630 will not affect other operations that may use that setting.</p> 4631 4632 4633 <div style="margin: auto;"> 4634 <h3><a class="anchor" id="green-primary"></a>-green-primary <var>x,y</var></h3> 4635 </div> 4636 4637 <p class="magick-description">green chromaticity primary point.</p> 4638 4639 4640 <div style="margin: auto;"> 4641 <h3><a class="anchor" id="hald-clut"></a>-hald-clut</h3> 4642 </div> 4643 4644 <p class="magick-description">apply a Hald color lookup table to the image.</p> 4645 4646 <p>A Hald color lookup table is a 3-dimensional color cube mapped to 2 4647 dimensions. Create it with the <code>HALD:</code> prefix (e.g. HALD:8). You 4648 can apply any color transformation to the Hald image and then use this option 4649 to apply the transform to the image. </p> 4650 4651 <pre class="highlight"><code>convert image.png hald.png -hald-clut transform.png 4652 </code></pre> 4653 4654 <p>This option provides a convenient method for you to use Gimp or Photoshop 4655 to make color corrections to the Hald CLUT image and subsequently apply them 4656 to multiple images using an ImageMagick script. </p> 4657 4658 <p>Note that the representation is only of the normal RGB color space and that 4659 the whole color value triplet is used for the interpolated lookup of the 4660 represented Hald color cube image. Because of this the operation is not <a 4661 href="command-line-options.html#channel" >-channel</a> setting affected, nor can it adjust or modify an 4662 images transparency or alpha/matte channel.</p> 4663 4664 <p>See also <a href="command-line-options.html#clut" >-clut</a> which provides color value replacement 4665 of the individual color channels, usually involving a simpler grayscale 4666 image. E.g: grayscale to color replacement, or modification by a histogram 4667 mapping. </p> 4668 4669 4670 <div style="margin: auto;"> 4671 <h3><a class="anchor" id="help"></a>-help</h3> 4672 </div> 4673 4674 <p class="magick-description">print usage instructions.</p> 4675 4676 <div style="margin: auto;"> 4677 <h3><a class="anchor" id="highlight-color"></a>-highlight-color <var>color</var></h3> 4678 </div> 4679 4680 <p class="magick-description">when comparing images, emphasize pixel differences with this color.</p> 4681 4682 <div style="margin: auto;"> 4683 <h3><a class="anchor" id="hough-lines"></a>-hough-lines <var>width</var>x<var>height</var>{<var>+threshold</var>}</h3> 4684 </div> 4685 4686 <p class="magick-description">identify straight lines in the image (e.g. -hough-lines 9x9+195).</p> 4687 4688 <p>Use the Hough line detector with any binary edge extracted image to locate and draw any straight lines that it finds.</p> 4689 4690 <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>. 4691 4692 <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> 4693 4694 <p>Use <code><a href="command-line-options.html#background" >-background</a></code> to specify the color of the background onto which the lines will be drawn. The default is black.</p> 4695 4696 <p>Use <code><a href="command-line-options.html#fill" >-fill</a></code> to specify the color of the lines. The default is black.</p> 4697 4698 <p>Use <code><a href="command-line-options.html#stroke" >-stroke</a></code> and <code><a href="command-line-options.html#strokewidth" >-strokewidth</a></code> to specify the thickness of the lines. The default is black and no strokewidth.</p> 4699 4700 <p>A text file listing the endpoints and counts may be created by using the suffix, .mvg, for the output image.</p> 4701 4702 <p>Use <code><a href="command-line-options.html#define" >-define</a> hough-lines:accumulator=true</code> to return the accumulator image in addition to the lines image.</p> 4703 4704 <div style="margin: auto;"> 4705 <h3><a class="anchor" id="iconGeometry"></a>-iconGeometry <var>geometry</var></h3> 4706 </div> 4707 4708 <p class="magick-description">specify the icon geometry.</p> 4709 4710 <p>Offsets, if present in the geometry specification, are handled in the same 4711 manner as the <a href="command-line-options.html#geometry">-geometry</a> option, using X11 style to 4712 handle negative offsets.</p> 4713 4714 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 4715 4716 <div style="margin: auto;"> 4717 <h3><a class="anchor" id="iconic"></a>-iconic</h3> 4718 </div> 4719 4720 <p class="magick-description">start in icon mode in X Windows", 'animate', 'display</p> 4721 4722 <div style="margin: auto;"> 4723 <h3><a class="anchor" id="identify"></a>-identify</h3> 4724 </div> 4725 4726 <p class="magick-description">identify the format and characteristics of the image.</p> 4727 4728 <p>This information is printed: image scene number; image name; image size; 4729 the image class (<var>DirectClass</var> or <var>PseudoClass</var>); the total number of unique colors; and the 4730 number of seconds to read and transform the image. Refer to <a href="miff.html">MIFF</a> for 4731 a description of the image class.</p> 4732 4733 <p>If <a href="command-line-options.html#colors">-colors</a> is also specified, the total unique colors 4734 in the image and color reduction error values are printed. Refer to <a 4735 href="../www/quantize.html">color 4736 reduction algorithm</a> for a description of these values.</p> 4737 4738 <p>If <a href="command-line-options.html#verbose">-verbose</a> precedes this option, copious 4739 amounts of image properties are displayed including image statistics, profiles, 4740 image histogram, and others.</p> 4741 4742 <div style="margin: auto;"> 4743 <h3><a class="anchor" id="ift"></a>-ift</h3> 4744 </div> 4745 4746 <p class="magick-description">implements the inverse discrete Fourier transform (DFT).</p> 4747 4748 <p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows 4749 users in ImageMagick 6.6.0-9). It transforms a pair of magnitude and phase 4750 images from the frequency domain to a single image in the normal or spatial 4751 domain. See for example, <a 4752 href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier Transform</a>, 4753 <a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier Transform</a> and 4754 <a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier Transform</a>.</p> 4755 4756 <p>For example, depending upon the image format used to store the result of 4757 the <a href="command-line-options.html#fft">-fft</a>, one would use either</p> 4758 4759 <pre class="highlight"><code>convert fft_image.miff -ift fft_image_ift.png 4760 </code></pre> 4761 4762 <p>or</p> 4763 4764 <pre class="highlight"><code>convert fft_image-0.png fft_image-1.png -ift fft_image_ift.png 4765 </code></pre> 4766 4767 <p>The resulting image may need to be cropped due to padding introduced when 4768 the original image, prior to the <a href="command-line-options.html#fft">-fft</a> or <a 4769 href="command-line-options.html#fft">+fft</a>, was not square or even dimensioned. Any padding is at 4770 the right and/or bottom sides of the image.</p> 4771 4772 <p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to 4773 use <a href="command-line-options.html#ift">-ift</a>.</p> 4774 4775 <p>Use <a href="command-line-options.html#ift">+ift</a> (with HDRI enabled) to transform a pair of real 4776 and imaginary images from the frequency domain to a single image in the normal 4777 (spatial) domain.</p> 4778 4779 <p>By default the IFT is not normalized (and the FFT is). Use "<code><a href="command-line-options.html#define" >-define</a> fourier:normalize=inverse</code> to explicitly normalize the IFT and unnormalize the FFT.</p> 4780 4781 <div style="margin: auto;"> 4782 <h3><a class="anchor" id="immutable"></a>-immutable</h3> 4783 </div> 4784 4785 <p class="magick-description">make image immutable.</p> 4786 4787 <div style="margin: auto;"> 4788 <h3><a class="anchor" id="implode"></a>-implode <var>factor</var></h3> 4789 </div> 4790 4791 <p class="magick-description">implode image pixels about the center.</p> 4792 4793 <div style="margin: auto;"> 4794 <h3><a class="anchor" id="insert"></a>-insert <var>index</var></h3> 4795 </div> 4796 4797 <p class="magick-description">insert the last image into the image sequence.</p> 4798 4799 <p>This option takes last image in the current image sequence and inserts it 4800 at the given index. If a negative index is used, the insert position is 4801 calculated before the last image is removed from the sequence. As such 4802 <code>-insert -1</code> will result in no change to the image sequence.</p> 4803 4804 <p>The <code>+insert</code> option is equivalent to <code>-insert -1</code>. In 4805 other words, insert the last image, at the end of the current image sequence. 4806 Consequently this has no effect on the image sequence order.</p> 4807 4808 <div style="margin: auto;"> 4809 <h3><a class="anchor" id="intensity"></a>-intensity <var>method</var></h3> 4810 </div> 4811 4812 <p class="magick-description">method to generate intensity value from pixel.</p> 4813 4814 <p>ImageMagick provides a number of methods used in situations where an 4815 operator needs to determine a single grayscale value for some purpose, from 4816 an image with red, green, and blue pixel components. Typically the 4817 <code>Rec709Luma</code> formula is used, which is the same formula used when converting images to <code>-colorspace gray</code>. </p> 4818 4819 <p>The following formulas are currently provided, and will first convert 4820 the pixel values to linear-RGB or non-linear sRGB colorspace before 4821 being applied to calculate the final greyscale value. </p> 4822 4823 <dl class="row"> 4824 <dt class="col-md-4">Rec601Luma</dt><dd class="col-md-8"> 0.298839R' + 0.586811G'+ 0.114350B'</dd> 4825 <dt class="col-md-4">Rec601Luminance</dt><dd class="col-md-8"> 0.298839R + 0.586811G + 0.114350B</dd> 4826 <dt class="col-md-4">Rec709Luma</dt><dd class="col-md-8"> 0.212656R' + 0.715158G' + 0.072186B'</dd> 4827 <dt class="col-md-4">Rec709Luminance</dt><dd class="col-md-8"> 0.212656R + 0.715158G + 0.072186B</dd> 4828 <dt class="col-md-4">Brightness</dt><dd class="col-md-8"> max(R', G', B')</dd> 4829 <dt class="col-md-4">Lightness</dt><dd class="col-md-8"> (min(R', G', B') + max(R', G', B')) / 2.0</dd> 4830 </dl> 4831 4832 <p>Note that the above R,G,B values is the image's linear-RGB values, while 4833 R',G',B' are sRGB non-linear values. </p> 4834 4835 <p>These intensity methods are mathematical in nature and will use the 4836 current value in the images respective R,G,B channel regardless of 4837 what that is, or what colorspace the image is currently using.</p> 4838 4839 <dl class="row"> 4840 <dt class="col-md-4">Average</dt><dd class="col-md-8">(R' + G' + B') / 3.0</dd> 4841 <dt class="col-md-4">MS</dt><dd class="col-md-8">(R'^2 + G'^2 + B'^2) / 3.0</dd> 4842 <dt class="col-md-4">RMS</dt><dd class="col-md-8">sqrt( (R'^2 + G'^2 + B'^2) / 3.0 )</dd> 4843 </dl> 4844 4845 <p>These methods are often used for other purposes, such as generating a 4846 grayscale difference image between two color images (using <a href="command-line-options.html#compose" 4847 >-compose</a> '<code>Difference</code>' composition. </p> 4848 4849 <p> For example The 'MS' (Mean Squared) setting is good for minimizing color 4850 error comparisions. While... The method 'RMS' (Root Mean Squared) for 4851 example is appropriate for calculating color vector distance, from a color 4852 difference image. This is equivalent to the color only component of the <a 4853 href="command-line-options.html#fuzz" >-fuzz</a> factor color compare setting. </p> 4854 4855 <p>See also <a href="command-line-options.html#grayscale" >-grayscale</a> which applies one of the above 4856 grayscaling formula directly to an image without setting the <a 4857 href="command-line-options.html#intensity" >-intensity</a> setting.</p> 4858 4859 <p>The <a href="command-line-options.html#colorspace" >-colorspace gray</a> image conversion also uses 4860 the current intensity setting, but will always convert the image to the 4861 appropriate sRGB or linear-RGB colorspace before appling the above 4862 function.</p> 4863 4864 <p>To print a complete list of possible pixel intensity setting methods, use <a href="command-line-options.html#list">-list intensity</a>.</p> 4865 4866 <p>Operators affected by the <a href="command-line-options.html#intensity" >-intensity</a> setting include:</p> 4867 4868 <pre class="highlight"><code>-adaptive-blur 4869 -adaptive-sharpen 4870 -black-threshold 4871 -clut (when mapping greyscale CLUT image to alpha channel if set by -channels) 4872 -colors for gray colorspace 4873 -compose {LightenIntensity, DarkenIntensity, CopyOpacity, CopyBlack} 4874 -contrast-stretch 4875 -distort {ErodeIntensity, DilateIntensity} 4876 -normalize 4877 -random-threshold 4878 -range-threshold 4879 -selective-blur 4880 -shade 4881 -threshold 4882 -tint 4883 -white-threshold 4884 </code></pre> 4885 4886 <div style="margin: auto;"> 4887 <h3><a class="anchor" id="intent"></a>-intent <var>type</var></h3> 4888 </div> 4889 4890 <p class="magick-description">use this type of rendering intent when managing the image color.</p> 4891 4892 <p>Use this option to affect the color management operation of an image (see 4893 <a href="command-line-options.html#profile">-profile</a>). Choose from these intents: <code>Absolute, 4894 Perceptual, Relative, Saturation</code>.</p> 4895 4896 <p>The default intent is Perceptual for the sRGB colorspace and undefined for the RGB and gray colorspaces.</p> 4897 4898 <p>To print a complete list of rendering intents, use <a href="command-line-options.html#list">-list intent</a>.</p> 4899 4900 <div style="margin: auto;"> 4901 <h3><a class="anchor" id="interlace"></a>-interlace <var>type</var></h3> 4902 </div> 4903 4904 <p class="magick-description">the type of interlacing scheme.</p> 4905 4906 <p>Choose from:</p> 4907 4908 <pre class="highlight"><code>none 4909 line 4910 plane 4911 partition 4912 JPEG 4913 GIF 4914 PNG 4915 </code></pre> 4916 4917 <p>This option is used to specify the type of interlacing scheme for raw image 4918 formats such as <code>RGB</code> or <code>YUV</code>.</p> 4919 4920 <p><code>None</code> means do not interlace (RGBRGBRGBRGBRGBRGB...),</p> 4921 4922 <p><code>Line</code> uses scanline interlacing (RRR...GGG...BBB...RRR...GGG...BBB...), and.</p> 4923 4924 <p><code>Plane</code> uses plane interlacing (RRRRRR...GGGGGG...BBBBBB...).</p> 4925 4926 <p><code>Partition</code> is like plane except the different planes are saved to 4927 individual files (e.g. image.R, image.G, and image.B).</p> 4928 4929 <p>Use <code>Line</code> or <code>Plane</code> to create an <code>interlaced 4930 PNG</code> or <code>GIF</code> or <code>progressive JPEG</code> image.</p> 4931 4932 <p>To print a complete list of interlacing schemes, use <a href="command-line-options.html#list">-list 4933 interlace</a>.</p> 4934 4935 <div style="margin: auto;"> 4936 <h3><a class="anchor" id="interpolate"></a>-interpolate <var>type</var></h3> 4937 </div> 4938 4939 <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> 4940 4941 <p>When looking up the color of a pixel using a non-integer floating point 4942 value, you typically fall in between the pixel colors defined by the source 4943 image. This setting determines how the color is determined from the colors of 4944 the pixels surrounding that point. That is how to determine the color of a 4945 point that falls between two, or even four different colored pixels. </p> 4946 4947 <dl class="row"> 4948 <dt class="col-md-4">average</dt> 4949 <dd class="col-md-8">The average color of the surrounding four pixels</dd> 4950 <dt class="col-md-4">average4</dt> 4951 <dd class="col-md-8">The average color of the surrounding four pixels</dd> 4952 <dt class="col-md-4">average9</dt> 4953 <dd class="col-md-8">The average color of the surrounding nine pixels</dd> 4954 <dt class="col-md-4">average16</dt> 4955 <dd class="col-md-8">The average color of the surrounding sixteen pixels</dd> 4956 <dt class="col-md-4">background</dt> 4957 <dd class="col-md-8"> </dd> 4958 <dt class="col-md-4">bilinear</dt> 4959 <dd class="col-md-8">A double linear interpolation of pixels (the default)</dd> 4960 <dt class="col-md-4">blend</dt> 4961 <dd class="col-md-8"> </dd> 4962 <dt class="col-md-4">catrom</dt> 4963 <dd class="col-md-8">Fitted bicubic-spines of surrounding 16 pixels</dd> 4964 <dt class="col-md-4">integer</dt> 4965 <dd class="col-md-8">The color of the top-left pixel (floor function)</dd> 4966 <dt class="col-md-4">mesh</dt> 4967 <dd class="col-md-8">Divide area into two flat triangular interpolations</dd> 4968 <dt class="col-md-4">nearest-neighbor</dt> 4969 <dd class="col-md-8">The nearest pixel to the lookup point (rounded function)</dd> 4970 <dt class="col-md-4">spline</dt> 4971 <dd class="col-md-8">Direct spline curves (colors are blurred)</dd> 4972 </dl> 4973 4974 <p>This most important for distortion operators such as <a href="command-line-options.html#distort" 4975 >-distort</a>, <a href="command-line-options.html#implode" >-implode</a>, <a href="command-line-options.html#transform" 4976 >-transform</a> and <a href="command-line-options.html#fx" >-fx</a>. </p> 4977 4978 <p>To print a complete list of interpolation methods, use <a href="command-line-options.html#list">-list interpolate</a>.</p> 4979 4980 <p>See also <a href="command-line-options.html#virtual-pixel" >-virtual-pixel</a>, for control of the 4981 lookup for positions outside the boundaries of the image. </p> 4982 4983 4984 <div style="margin: auto;"> 4985 <h3><a class="anchor" id="interline-spacing"></a>-interline-spacing <var>value</var></h3> 4986 </div> 4987 4988 <p class="magick-description">the space between two text lines.</p> 4989 4990 <div style="margin: auto;"> 4991 <h3><a class="anchor" id="interword-spacing"></a>-interword-spacing <var>value</var></h3> 4992 </div> 4993 4994 <p class="magick-description">the space between two words.</p> 4995 4996 <div style="margin: auto;"> 4997 <h3><a class="anchor" id="kerning"></a>-kerning <var>value</var></h3> 4998 </div> 4999 5000 <p class="magick-description">the space between two letters.</p> 5001 5002 <div style="margin: auto;"> 5003 <h3><a class="anchor" id="kuwahara"></a>-kuwahara <var>radius</var><br />-kuwahara <var>radius</var>x<var>sigma</var></h3> 5004 </div> 5005 5006 <p class="magick-description">edge preserving noise reduction filter.</p> 5007 5008 <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> 5009 5010 5011 <div style="margin: auto;"> 5012 <h3><a class="anchor" id="label"></a>-label <var>name</var></h3> 5013 </div> 5014 5015 <p class="magick-description">assign a label to an image.</p> 5016 5017 <p>Use this option to assign a specific label to the image, as it is read in 5018 or created. You can use the <a href="command-line-options.html#set" >-set</a> operation to re-assign 5019 a the labels of images already read in. Image formats such as TIFF, PNG, 5020 MIFF, supports saving the label information with the image.</p> 5021 5022 <p>When saving an image to a <var>PostScript</var> file, any label 5023 assigned to an image is used as a header string to print above the postscript 5024 image. </p> 5025 5026 <p>You can include the image filename, type, width, height, or other image 5027 attribute by embedding special format character. See <a href="../www/escape.html">Format and Print Image 5028 Properties</a> for details of the percent escape codes.</p> 5029 5030 <p>For example,</p> 5031 5032 <pre class="highlight"><code>-label "%m:%f %wx%h" bird.miff 5033 </code></pre> 5034 5035 <p>assigns an image label of <code>MIFF:bird.miff 512x480</code> to the 5036 "<code>bird.miff</code>" image and whose width is 512 and height is 480, as it 5037 is read in. If a <a href="command-line-options.html#label">+label</a> option was used instead, any 5038 existing label present in the image would be used. You can remove all labels 5039 from an image by assigning the empty string. </p> 5040 5041 <p>A label is not drawn on the image, but is embedded in the image datastream 5042 via <var>Label</var> tag or similar mechanism. If you want the label to be 5043 visible on the image itself, use the <a href="command-line-options.html#draw">-draw</a> option, or 5044 during the final processing in the creation of an image montage.</p> 5045 5046 <p>If the first character of <var>string</var> is <var>@</var>, the image label is read from a file titled by the 5047 remaining characters in the string. Labels in a file are literal, no embedded 5048 formatting characters are recognized.</p> 5049 5050 5051 <div style="margin: auto;"> 5052 <h3><a class="anchor" id="lat"></a>-lat <var>width</var><br />-lat <var>width</var>x<var>height</var>{<var>+-</var>}<var>offset</var>{<var>%</var>}</h3> 5053 </div> 5054 5055 <p class="magick-description">perform local adaptive threshold.</p> 5056 5057 <p>Adaptively threshold each pixel based on the value of pixels in a 5058 surrounding window. If the current pixel is lighter than this average plus 5059 the optional <code>offset</code>, then it is made white, otherwise it is made 5060 black. Small variations in pixel values such as found in scanned documents 5061 can be ignored if offset is positive. A negative offset will make it more 5062 sensitive to those small variations. </p> 5063 5064 <p>This is commonly used to threshold images with an uneven background. It is 5065 based on the assumption that average color of the small window is the 5066 the local background color, from which to separate the foreground color. </p> 5067 5068 5069 <div style="margin: auto;"> 5070 <h3><a class="anchor" id="layers"></a>-layers <var>method</var></h3> 5071 </div> 5072 5073 <p class="magick-description">handle multiple images forming a set of image layers or animation frames.</p> 5074 5075 <p>Perform various image operation methods to a ordered sequence of images 5076 which may represent either a set of overlaid 'image layers', a GIF disposal 5077 animation, or a fully-'coalesced' animation sequence. </p> 5078 5079 <table class="table table-sm table-striped"> 5080 <tbody> 5081 <tr> 5082 <th style="width: 8%">Method</th> 5083 <th>Description</th> 5084 </tr> 5085 5086 <tr> 5087 <td>compare-any</td> 5088 <td>Crop the second and later frames to the smallest rectangle 5089 that contains all the differences between the two images. No GIF <a 5090 href="command-line-options.html#dispose" >-dispose</a> methods are taken into account. </td> 5091 </tr> 5092 5093 <tr><td></td><td>This exactly the same as the <a href="command-line-options.html#deconstruct" 5094 >-deconstruct</a> operator, and does not preserve animations normal 5095 working, especially when animation used layer disposal methods such as 5096 '<code>Previous</code>' or '<code>Background</code>'. </td> 5097 </tr> 5098 5099 <tr> 5100 <td>compare-clear</td> 5101 <td>As '<code>compare-any</code>' but crop to the bounds of any 5102 opaque pixels which become transparent in the second frame. That is the 5103 smallest image needed to mask or erase pixels for the next frame. </td> 5104 </tr> 5105 5106 <tr> 5107 <td>compare-overlay</td> 5108 <td>As '<code>compare-any</code>' but crop to pixels that add 5109 extra color to the next image, as a result of overlaying color pixels. 5110 That is the smallest single overlaid image to add or change colors. </td> 5111 </tr> 5112 5113 <tr><td></td><td>This can be used with the <a href="command-line-options.html#compose" >-compose</a> alpha 5114 composition method '<code>change-mask</code>', to reduce the image to 5115 just the pixels that need to be overlaid. </td> 5116 </tr> 5117 5118 <tr> 5119 <td>coalesce</td> 5120 <td>Equivalent to a call to the <a href="command-line-options.html#coalesce" 5121 >-coalesce</a> operator. Apply the layer disposal methods set in the 5122 current image sequence to form a fully defined animation sequence, as 5123 it should be displayed. Effectively converting a GIF animation into a 5124 'film strip'-like animation. </td> 5125 </tr> 5126 5127 <tr> 5128 <td>composite</td> 5129 <td>Alpha Composition of two image lists, separated by a 5130 "<code>null:</code>" image, with the destination image list first, and 5131 the source images last. An image from each list are composited 5132 together until one list is finished. The separator image and source 5133 image lists are removed. </td> 5134 </tr> 5135 5136 5137 <tr><td></td> 5138 <td>The <a href="command-line-options.html#geometry" >-geometry</a> offset is adjusted according 5139 to <a href="command-line-options.html#gravity" >-gravity</a> in accordance of the virtual 5140 canvas size of the first image in each list. Unlike a normal <a 5141 href="command-line-options.html#composite" >-composite</a> operation, the canvas offset is also 5142 added to the final composite positioning of each image. </td> </tr> 5143 5144 <tr><td></td> 5145 <td>If one of the image lists only contains one image, that image is 5146 applied to all the images in the other image list, regardless of which 5147 list it is. In this case it is the image meta-data of the list which 5148 preserved. </td> 5149 </tr> 5150 5151 5152 <tr> 5153 <td>dispose</td> 5154 <td>This like '<code>coalesce</code>' but shows the look of 5155 the animation after the layer disposal method has been applied, before 5156 the next sub-frame image is overlaid. That is the 'dispose' image that 5157 results from the application of the GIF <a href="command-line-options.html#dispose" 5158 >-dispose</a> method. This allows you to check what 5159 is going wrong with a particular animation you may be developing. 5160 </td> 5161 </tr> 5162 5163 <tr> 5164 <td>flatten</td> 5165 <td>Create a canvas the size of the first images virtual 5166 canvas using the current <a href="command-line-options.html#background" >-background</a> color, 5167 and <a href="command-line-options.html#compose" >-compose</a> each image in turn onto that 5168 canvas. Images falling outside that canvas is clipped. Final 5169 image will have a zero virtual canvas offset. </td> 5170 </tr> 5171 5172 <tr><td></td> 5173 <td>This usually used as one of the final 'image layering' operations 5174 overlaying all the prepared image layers into a final image. </td> 5175 </tr> 5176 5177 <tr><td></td> 5178 <td>For a single image this method can also be used to fillout a virtual 5179 canvas with real pixels, or to underlay an opaque color to remove 5180 transparency from an image.</td> 5181 </tr> 5182 5183 5184 <tr> 5185 <td>merge</td> 5186 <td>As 'flatten' method but merging all the given image 5187 layers to create a new layer image just large enough to hold all the 5188 image without clipping or extra space. The new images virtual offset 5189 will preserve the position of the new layer, even if this offset is 5190 negative. The virtual canvas size of the first image is preserved. 5191 </td> 5192 </tr> 5193 5194 <tr><td></td><td>Caution is advised when handling image layers with 5195 negative offsets as few image file formats handle them correctly. 5196 Following this operation method with <a href="command-line-options.html#repage" >+repage</a> 5197 will remove the layer offset, and create an image in which all the 5198 overlaid image positions relative to each other is preserved, though 5199 not necessarily exactly where you specified them. 5200 </td> 5201 </tr> 5202 5203 <tr><td></td><td>See also 'trim-bounds' below which is closely related but 5204 without doing the'flatten' to merge the images together. </td> 5205 </tr> 5206 5207 <tr> 5208 <td>mosaic</td> 5209 <td>As 'flatten' method but expanding the initial canvas size 5210 of the first image in a positive direction only so as to hold all the 5211 image layers. However as a virtual canvas is 'locked' to the origin, 5212 by its own definition, image layers with a negative offsets will still 5213 become clipped by the top and left edges. See 'merge' or 'trim-bounds' 5214 if this could be a problem. </td> 5215 5216 </tr> 5217 5218 <tr><td></td><td>This method is commonly used to layout individual image 5219 using various offset but without knowing the final canvas size. The 5220 resulting image will, like 'flatten' not have any virtual offset, so 5221 can be saved to any image file format. </td> 5222 </tr> 5223 5224 5225 <tr> 5226 <td>optimize</td> 5227 <td>Optimize a coalesced animation, into GIF animation using 5228 a number of general techniques. This currently a short cut to 5229 apply both the '<code>optimize-frame</code>', and 5230 '<code>optimize-transparency</code>' methods but may be expanded to 5231 include other optimization methods as they are developed. </td> 5232 </tr> 5233 5234 <tr> 5235 <td>optimize-frame</td> 5236 <td>Optimize a coalesced animation, into GIF animation by 5237 reducing the number of pixels per frame as much as possible by 5238 attempting to pick the best layer disposal method to use, while ensuring 5239 the result will continue to animate properly. </td> 5240 </tr> 5241 5242 <tr><td></td><td> There is no guarantee that the best optimization is found. 5243 But then no reasonably fast GIF optimization algorithm can do this. 5244 However this does seem to do better than most other GIF frame 5245 optimizers seen. </td> 5246 </tr> 5247 5248 <tr> 5249 <td>optimize-plus</td> 5250 <td>As '<code>optimize-frame</code>' but attempt to improve the 5251 overall optimization by adding extra frames to the animation, without 5252 changing the final look or timing of the animation. The frames are 5253 added to attempt to separate the clearing of pixels from the 5254 overlaying of new additional pixels from one animation frame to the 5255 next. If this does not improve the optimization (for the next frame 5256 only), it will fall back to the results of the previous normal 5257 '<code>optimize-frame</code>' technique. </td> 5258 </tr> 5259 5260 <tr><td></td><td>There is the possibility that the change in the disposal 5261 style will result in a worsening in the optimization of later frames, 5262 though this is unlikely. In other words there no guarantee that it is 5263 better than the normal '<code>optimize-frame</code>' technique. For some 5264 animations however you can get a vast improvement in the final 5265 animation size. </td> 5266 </tr> 5267 5268 <tr> 5269 <td>optimize-transparency</td> 5270 <td>Given a GIF animation, replace any pixel in the sub-frame 5271 overlay images with transparency, if it does not change the resulting 5272 animation by more than the current <a href="command-line-options.html#fuzz" >-fuzz</a> factor. 5273 </td> 5274 </tr> 5275 5276 <tr><td></td><td>This should allow a existing frame optimized GIF animation 5277 to compress into a smaller file size due to larger areas of one 5278 (transparent) color rather than a pattern of multiple colors repeating 5279 the current disposed image of the last frame. </td> 5280 </tr> 5281 5282 <tr> 5283 <td>remove-dups</td> 5284 <td>Remove (and merge time delays) of duplicate consecutive 5285 images, so as to simplify layer overlays of coalesced animations. 5286 </td> 5287 </tr> 5288 5289 <tr><td></td><td>Usually this a result of using a constant time delay 5290 across the whole animation, or after a larger animation was split into 5291 smaller sub-animations. The duplicate frames could also have been 5292 used as part of some frame optimization methods. </td> 5293 </tr> 5294 5295 <tr> 5296 <td>remove-zero</td> 5297 <td>Remove any image with a zero time delay, unless ALL the 5298 images have a zero time delay (and is not a proper timed animation, a 5299 warning is then issued). </td> 5300 </tr> 5301 5302 <tr><td></td><td>In a GIF animation, such images are usually frames which 5303 provide partial intermediary updates between the frames that are 5304 actually displayed to users. These frames are usually added for 5305 improved frame optimization in GIF animations. </td> 5306 </tr> 5307 5308 <tr> 5309 <td>trim-bounds</td> 5310 <td>Find the bounds of all the images in the current 5311 image sequence, then adjust the offsets so all images are contained on 5312 a minimal positive canvas. None of the image data is modified or 5313 merged, only the individual image virtual canvas size and offset. 5314 All the images is given the same canvas size, and and will have 5315 a positive offset, but will remain in the same position relative to 5316 each other. As a result of the minimal canvas size at least one image 5317 will touch every edge of that canvas. The image data touching those 5318 edges however may be transparent. </td> 5319 </tr> 5320 5321 <tr><td></td><td>The result is much like if you used 'merge' followed by a 5322 <a href="command-line-options.html#repage" >+repage</a> option, except that all the images 5323 have been kept separate. If 'flatten' is used after using 5324 'trim-bounds' you will get the same result. </td> 5325 </tr> 5326 5327 </tbody> 5328 </table> 5329 5330 <p>To print a complete list of layer types, use <a href="command-line-options.html#list">-list layers</a>.</p> 5331 5332 <p>The operators <a href="command-line-options.html#coalesce" >-coalesce</a>, <a href="command-line-options.html#deconstruct" 5333 >-deconstruct</a>, <a href="command-line-options.html#flatten" >-flatten</a>, and <a href="command-line-options.html#mosaic" 5334 >-mosaic</a> are only aliases for the above methods and may be depreciated in 5335 the future. Also see <a href="command-line-options.html#page" >-page</a>, <a href="command-line-options.html#repage" 5336 >-repage</a> operators, the <a href="command-line-options.html#compose" >-compose</a> setting, and the 5337 GIF <a href="command-line-options.html#dispose" >-dispose</a> and <a href="command-line-options.html#delay" >-delay</a> 5338 settings. </p> 5339 5340 5341 <div style="margin: auto;"> 5342 <h3><a class="anchor" id="level"></a>-level <var>black_point</var>{,<var>white_point</var>}{<var>%</var>}{,<var>gamma</var>}</h3> 5343 </div> 5344 5345 <p class="magick-description">adjust the level of image channels.</p> 5346 5347 <p>Given one, two or three values delimited with commas: black-point, 5348 white-point, gamma (for example: 10,250,1.0 or 2%,98%,0.5). The black and 5349 white points range from 0 to <var>QuantumRange</var>, or from 0 to 5350 100%; if the white point is omitted it is set to (<var>QuantumRange</var> - black_point), so as to center contrast changes. 5351 If a <code>%</code> sign is present anywhere in the string, both black and white 5352 points are percentages of the full color range. Gamma will do a <a 5353 href="command-line-options.html#gamma">-gamma</a> adjustment of the values. If it is omitted, the 5354 default of 1.0 (no gamma correction) is assumed.</p> 5355 5356 <p>In normal usage (<code>-level</code>) the image values are stretched so that 5357 the given '<code>black_point</code>' value in the original image is set to zero 5358 (or black), while the given '<code>white_point</code>' value is set to <var>QuantumRange</var> (or white). This provides you with direct 5359 contrast adjustments to the image. The '<code>gamma</code>' of the resulting 5360 image will then be adjusted. </p> 5361 5362 <p>From ImageMagick v6.4.1-9 using the plus form of the operator 5363 (<code>+level</code>) or adding the special '!' flag anywhere in the argument 5364 list, will cause the operator to do the reverse of the level adjustment. That 5365 is a zero, or <var>QuantumRange</var> value (black, and white, resp.) 5366 in the original image, is adjusted to the given level values, allowing you to 5367 de-contrast, or compress the channel values within the image. The 5368 '<code>gamma</code>' is adjusted before the level adjustment to de-contrast the 5369 image is made. </p> 5370 5371 <p>Only the channels defined by the current <a href="command-line-options.html#channel">-channel</a> 5372 setting are adjusted (defaults to RGB color channels only), allowing you to 5373 limit the effect of this operator. </p> 5374 5375 <p>Please note that the transparency channel is treated as 'matte' 5376 values (0 is opaque) and not as 'alpha' values (0 is transparent).</p> 5377 5378 5379 <div style="margin: auto;"> 5380 <h3><a class="anchor" id="level-colors"></a>-level-colors {<var>black_color</var>}{,}{<var>white_color</var>}</h3> 5381 </div> 5382 5383 <p class="magick-description">adjust the level of an image using the provided dash separated colors.</p> 5384 5385 <p>This function is exactly like <a href="command-line-options.html#level">-level</a>, except that the 5386 value value for each color channel is determined by the 5387 '<code>black_color</code>' and '<code>white_color</code>' colors given (as 5388 described under the <a href="command-line-options.html#fill">-fill</a> option). </p> 5389 5390 <p>This effectively means the colors provided to <code>-level-colors</code> 5391 is mapped to become 'black' and 'white' respectively, with all the other 5392 colors linearly adjusted (or clipped) to match that change. Each channel is 5393 adjusted separately using the channel values of the colors specified. </p> 5394 5395 <p>On the other hand the plus form of the operator (<code>+level-colors</code>) 5396 will map the image color 'black' and 'white' to the given colors 5397 respectively, resulting in a gradient (de-contrasting) tint of the image to 5398 those colors. This can also be used to convert a plain grayscale image into a 5399 one using the gradient of colors specified. </p> 5400 5401 <p>By supplying a single color with a comma separator either before or after 5402 that color, will just replace the respective 'black' or 'white' point 5403 respectively. But if no comma separator is provided, the given color is 5404 used for both the black and white color points, making the operator either 5405 threshold the images around that color (- form) or set all colors to that 5406 color (+ form). </p> 5407 5408 5409 <div style="margin: auto;"> 5410 <h3><a class="anchor" id="limit"></a>-limit <var>type value</var></h3> 5411 </div> 5412 5413 <p class="magick-description">Set the pixel cache resource limit.</p> 5414 5415 <p>Choose from: <code>width</code>, <code>height</code>, <code>area</code>, <code>memory</code>, <code>map</code>, <code>disk</code>, <code>file</code>, <code>thread</code>, <code>throttle</code>, or <code>time</code>.</p> 5416 5417 <p>The value for <code>file</code> is in number of files. The other limits are 5418 in bytes. Define arguments for the memory, map, area, and disk resource limits 5419 with SI prefixes (.e.g 100MB).</p> 5420 5421 <p>By default the limits are 768 files, 3GB of image area, 1.5GiB memory, 3GiB 5422 memory map, and 18.45EB of disk. These limits are adjusted relative to the 5423 available resources on your computer if this information is available. When 5424 any limit is reached, ImageMagick fails in some fashion but attempts to take 5425 compensating actions, if possible. For example, the following limits 5426 memory:</p> 5427 5428 <pre class="highlight"><code>-limit memory 32MiB -limit map 64MiB 5429 </code></pre> 5430 5431 <p>Use <a href="command-line-options.html#list">-list resource</a> to list the current limits. For example, our system shows these limits:</p> 5432 5433 <pre class="highlight"><code>-> identify -list resource 5434 Resource limits: 5435 Width: 100MP 5436 Height: 100MP 5437 Area: 25.181GB 5438 Memory: 11.726GiB 5439 Map: 23.452GiB 5440 Disk: unlimited 5441 File: 768 5442 Thread: 12 5443 Throttle: 0 5444 Time: unlimited 5445 </code></pre> 5446 5447 <p>Requests for pixel storage to keep intermediate images are satisfied by one 5448 of three resource categories: in-memory pool, memory-mapped files pool, and 5449 disk pool (in that order) depending on the <a href="command-line-options.html#limit">‑limit</a> settings 5450 and whether the system honors a resource request. If the total size of 5451 allocated pixel storage in the given pool reaches the corresponding limit, the 5452 request is passed to the next pool. Additionally, requests that exceed the 5453 <code>area</code> limit automagically are allocated on disk.</p> 5454 5455 <p>To illustrate how ImageMagick utilizes resource limits, consider a typical 5456 image resource request. First, ImageMagick tries to allocate the pixels in 5457 memory. The request might be denied if the resource request exceeds the 5458 <code>memory</code> limit or if the system does not honor the request. If 5459 a memory request is not honored, the pixels are allocated to disk and the file 5460 is memory-mapped. However, if the allocation request exceeds the 5461 <code>map</code> limit, the resource allocation goes to disk. In all cases, if 5462 the resource request exceeds the <code>area</code> limit, the pixels are 5463 automagically cached to disk. If the disk has a hard limit, the program 5464 fails.</p> 5465 5466 <p>In most cases you simply do not need to concern yourself with resource 5467 limits. ImageMagick chooses reasonable defaults and most images do not tax 5468 your computer resources. Where limits do come in handy is when you process 5469 images that are large or on shared systems where ImageMagick can consume all 5470 or most of the available memory. In this case, the ImageMagick workflow slows 5471 other processes or, in extreme cases, brings the system to a halt. Under 5472 these circumstances, setting limits give some assurances that the ImageMagick 5473 workflow will not interfere with other concurrent uses of the computer. For 5474 example, assume you have a web interface that processes images uploaded from 5475 the Internet. To assure ImageMagick does not exceed 10MiB of memory you can 5476 simply set the area limit to 10MiB:</p> 5477 5478 <pre class="highlight"><code>-limit area 10MB 5479 </code></pre> 5480 5481 <p>Now whenever a large image is processed, the pixels are automagically 5482 cached to disk instead of memory. This of course implies that large images 5483 typically process very slowly, simply because pixel processing in memory can 5484 be an order of magnitude faster than on disk. Because your web site users 5485 might inadvertently upload a huge image to process, you should set a disk 5486 limit as well:</p> 5487 5488 <pre class="highlight"><code>-limit area 10MB -limit disk 500MB 5489 </code></pre> 5490 5491 <p>Here ImageMagick stops processing if an image requires more than 500MB of disk storage.</p> 5492 5493 <p>In addition to command-line resource limit option, resources can be set 5494 with <a href="resources.html#environment" >environment variables</a>. Set the 5495 environment variables <code>MAGICK_AREA_LIMIT</code>, 5496 <code>MAGICK_DISK_LIMIT</code>, <code>MAGICK_FILE_LIMIT</code>, 5497 <code>MAGICK_MEMORY_LIMIT</code>, <code>MAGICK_MAP_LIMIT</code>, 5498 <code>MAGICK_THREAD_LIMIT</code>, <code>MAGICK_TIME_LIMIT</code> for limits of 5499 image area, disk space, open files, heap memory, memory map, number of threads 5500 of execution, and maximum elapsed time in seconds respectively.</p> 5501 5502 <p> Inquisitive users can try adding <a href="command-line-options.html#debug">-debug cache</a> to 5503 their commands and then scouring the generated output for references to the 5504 pixel cache, in order to determine how the pixel cache was allocated and how 5505 resources were consumed. Advanced Unix/Linux users can pipe that output 5506 through <code>grep memory|open|destroy|disk</code> for more readable sifting. 5507 </p> 5508 5509 <p>For more about ImageMagick's use of resources, see the section <b>Cache 5510 Storage and Resource Requirements</b> on the <a href="architecture.html#cache 5511 ">Architecture</a> page. </p> 5512 5513 <div style="margin: auto;"> 5514 <h3><a class="anchor" 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> 5515 </div> 5516 5517 <p class="magick-description">Linear with saturation stretch.</p> 5518 5519 <p>This is very similar to <a href="command-line-options.html#contrast-stretch" >-contrast-stretch</a>, 5520 and uses a 'histogram bin' to determine the range of color values that needs to 5521 be stretched. However it then stretches those colors using the <a 5522 href="command-line-options.html#level" >-level</a> operator.</p> 5523 5524 <p>As such while the initial determination may have 'binning' round off 5525 effects, the image colors are stretched mathematically, rather than using the 5526 histogram bins. This makes the operator more accurate. </p> 5527 5528 <p>note however that a <a href="command-line-options.html#linear-stretch" >-linear-stretch</a> of 5529 '<code>0</code>' does nothing, while a value of '<code>1</code>' does a near 5530 perfect stretch of the color range. </p> 5531 5532 <p>See also <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' 5533 normalization of mathematical images. </p> 5534 5535 <p>This operator is under review for re-development. </p> 5536 5537 5538 <div style="margin: auto;"> 5539 <h3><a class="anchor" id="linewidth"></a>-linewidth</h3> 5540 </div> 5541 5542 <p class="magick-description">the line width for subsequent draw operations.</p> 5543 5544 <div style="margin: auto;"> 5545 <h3><a class="anchor" id="liquid-rescale"></a>-liquid-rescale <var>geometry</var></h3> 5546 </div> 5547 5548 <p class="magick-description">rescale image with seam-carving.</p> 5549 5550 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 5551 5552 <div style="margin: auto;"> 5553 <h3><a class="anchor" id="list"></a>-list <var>type</var></h3> 5554 </div> 5555 5556 <p class="magick-description">Print a list of supported arguments for various options or settings. Choose from these list types:</p> 5557 5558 <pre class="pre-scrollable"><code> 5559 Align 5560 Alpha 5561 Boolean 5562 Cache 5563 Channel 5564 Class 5565 ClipPath 5566 Coder 5567 Color 5568 Colorspace 5569 Command 5570 Complex 5571 Compose 5572 Compress 5573 Configure 5574 DataType 5575 Debug 5576 Decoration 5577 Delegate 5578 Direction 5579 Dispose 5580 Distort 5581 Dither 5582 Endian 5583 Evaluate 5584 FillRule 5585 Filter 5586 Font 5587 Format 5588 Function 5589 Gravity 5590 Intensity 5591 Intent 5592 Interlace 5593 Interpolate 5594 Kernel 5595 Layers 5596 LineCap 5597 LineJoin 5598 List 5599 Locale 5600 LogEvent 5601 Log 5602 Magic 5603 Method 5604 Metric 5605 Mime 5606 Mode 5607 Morphology 5608 Module 5609 Noise 5610 Orientation 5611 PixelIntensity 5612 Policy 5613 PolicyDomain 5614 PolicyRights 5615 Preview 5616 Primitive 5617 QuantumFormat 5618 Resource 5619 SparseColor 5620 Statistic 5621 Storage 5622 Stretch 5623 Style 5624 Threshold 5625 Type 5626 Units 5627 Validate 5628 VirtualPixel 5629 </code></pre> 5630 5631 <p>These lists vary depending on your version of ImageMagick. Use "<code>-list 5632 list</code>" to get a complete listing of all the "<code>-list</code>" arguments 5633 available:</p> 5634 5635 <pre class="highlight"><code>identify -list list 5636 </code></pre> 5637 5638 <div style="margin: auto;"> 5639 <h3><a class="anchor" id="log"></a>-log <var>string</var></h3> 5640 </div> 5641 5642 <p class="magick-description">Specify format for debug log.</p> 5643 5644 <p>This option specifies the format for the log printed when the <a 5645 href="command-line-options.html#debug">-debug</a> option is active.</p> 5646 5647 <p>You can display the following components by embedding special format 5648 characters:</p> 5649 5650 <dl class="row"> 5651 <dt class="col-md-4">%d</dt><dd class="col-md-8">domain</dd> 5652 <dt class="col-md-4">%e</dt><dd class="col-md-8">event</dd> 5653 <dt class="col-md-4">%f</dt><dd class="col-md-8">function</dd> 5654 <dt class="col-md-4">%l</dt><dd class="col-md-8">line</dd> 5655 <dt class="col-md-4">%m</dt><dd class="col-md-8">module</dd> 5656 <dt class="col-md-4">%p</dt><dd class="col-md-8">process ID</dd> 5657 <dt class="col-md-4">%r</dt><dd class="col-md-8">real CPU time</dd> 5658 <dt class="col-md-4">%t</dt><dd class="col-md-8">wall clock time</dd> 5659 <dt class="col-md-4">%u</dt><dd class="col-md-8">user CPU time</dd> 5660 <dt class="col-md-4">%%</dt><dd class="col-md-8">percent sign</dd> 5661 <dt class="col-md-4">\n</dt><dd class="col-md-8">newline</dd> 5662 <dt class="col-md-4">\r</dt><dd class="col-md-8">carriage return</dd> 5663 </dl> 5664 5665 <p>For example:</p> 5666 5667 <pre class="highlight"><code>convert -debug coders -log "%u %m:%l %e" in.gif out.png 5668 </code></pre> 5669 5670 <p>The default behavior is to print all of the components.</p> 5671 5672 <div style="margin: auto;"> 5673 <h3><a class="anchor" id="loop"></a>-loop <var>iterations</var></h3> 5674 </div> 5675 5676 <p class="magick-description">add Netscape loop extension to your GIF animation.</p> 5677 5678 <p>Set iterations to zero to repeat the animation an infinite number of times, 5679 otherwise the animation repeats itself up to <var>iterations</var> 5680 times.</p> 5681 5682 <div style="margin: auto;"> 5683 <h3><a class="anchor" id="lowlight-color"></a>-lowlight-color <var>color</var></h3> 5684 </div> 5685 5686 <p class="magick-description">when comparing images, de-emphasize pixel differences with this color.</p> 5687 5688 <div style="margin: auto;"> 5689 <h3><a class="anchor" id="magnify"></a>-magnify</h3> 5690 </div> 5691 5692 <p class="magick-description">double the size of the image with pixel art scaling.</p> 5693 5694 5695 <div style="margin: auto;"> 5696 <h3><a class="anchor" id="map"></a>-map <var>type</var></h3> 5697 </div> 5698 5699 <p class="magick-description">Display image using this <var>type</var>.</p> 5700 5701 <p>Choose from these <var>Standard Colormap</var> types:</p> 5702 5703 <pre class="highlight"><code>best 5704 default 5705 gray 5706 red 5707 green 5708 blue 5709 </code></pre> 5710 5711 <p>The <var>X server</var> must support the <var>Standard 5712 Colormap</var> you choose, otherwise an error occurs. Use <code>list</code> as 5713 the type and <code>display</code> searches the list of colormap types in 5714 <code>top-to-bottom</code> order until one is located. See <var>xstdcmap(1)</var> for one way of creating Standard Colormaps.</p> 5715 5716 5717 <div style="margin: auto;"> 5718 <h3><a class="anchor" id="map_stream_"></a>-map <var>components</var></h3> 5719 </div> 5720 5721 <p class="magick-description">pixel map.</p> 5722 5723 <p>Here are the valid components of a map:</p> 5724 5725 <dl class="row"> 5726 <dt class="col-md-4">r</dt><dd class="col-md-8"> red pixel component</dd> 5727 <dt class="col-md-4">g</dt><dd class="col-md-8"> green pixel component</dd> 5728 <dt class="col-md-4">b</dt><dd class="col-md-8"> blue pixel component</dd> 5729 <dt class="col-md-4">a</dt><dd class="col-md-8"> alpha pixel component (0 is transparent)</dd> 5730 <dt class="col-md-4">o</dt><dd class="col-md-8"> opacity pixel component (0 is opaque)</dd> 5731 <dt class="col-md-4">i</dt><dd class="col-md-8"> grayscale intensity pixel component</dd> 5732 <dt class="col-md-4">c</dt><dd class="col-md-8"> cyan pixel component</dd> 5733 <dt class="col-md-4">m</dt><dd class="col-md-8"> magenta pixel component</dd> 5734 <dt class="col-md-4">y</dt><dd class="col-md-8"> yellow pixel component</dd> 5735 <dt class="col-md-4">k</dt><dd class="col-md-8"> black pixel component</dd> 5736 <dt class="col-md-4">p</dt><dd class="col-md-8"> pad component (always 0)</dd> 5737 </dl> 5738 5739 <p>You can specify as many of these components as needed in any order (e.g. 5740 bgr). The components can repeat as well (e.g. rgbr).</p> 5741 5742 5743 <div style="margin: auto;"> 5744 <h3><a class="anchor" id="mattecolor"></a>-mattecolor <var>color</var></h3> 5745 </div> 5746 5747 <p class="magick-description">Specify the color to be used with the <a href="command-line-options.html#frame">-frame</a> option.</p> 5748 5749 <p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 5750 5751 <p>The default matte color is <code>#BDBDBD</code>, <span 5752 style="background-color: #bdbdbd;">this shade of gray</span>.</p> 5753 5754 <div style="margin: auto;"> 5755 <h3><a class="anchor" id="maximum"></a>-maximum</h3> 5756 </div> 5757 5758 <p class="magick-description">return the maximum intensity of an image sequence.</p> 5759 5760 <p>Select the 'maximum' value from all the surrounding pixels. </p> 5761 5762 <p>This is legacy option from the <a href="command-line-options.html#statistic" >method</a> of the same 5763 name. </p> 5764 5765 <div style="margin: auto;"> 5766 <h3><a class="anchor" id="median"></a>-median <var>geometry</var></h3> 5767 </div> 5768 5769 <p class="magick-description">apply a median filter to the image.</p> 5770 5771 <p>Select the 'middle' value from all the surrounding pixels. </p> 5772 5773 <p>This is legacy option from the <a href="command-line-options.html#statistic" >method</a> of the same 5774 name. </p> 5775 5776 <div style="margin: auto;"> 5777 <h3><a class="anchor" id="mean-shift"></a>-mean-shift <var>width</var>x<var>height</var>{<var>+distance</var>{%}</h3> 5778 </div> 5779 5780 <p class="magick-description">image noise removal and color reduction/segmentation (e.g. -mean-shift 7x7+10%).</p> 5781 5782 <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> 5783 5784 <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> 5785 5786 <div style="margin: auto;"> 5787 <h3><a class="anchor" id="metric"></a>-metric <var>type</var></h3> 5788 </div> 5789 5790 <p class="magick-description">Output to STDERR a measure of the differences between images according to the <var>type</var> given metric.</p> 5791 5792 <p>Choose from:</p> 5793 5794 <dl class="row"> 5795 <dt class="col-md-4">AE</dt><dd class="col-md-8"> absolute error count, number of different pixels (-fuzz affected)</dd> 5796 <dt class="col-md-4">DSSIM</dt><dd class="col-md-8"> structural dissimilarity index</dd> 5797 <dt class="col-md-4">FUZZ</dt><dd class="col-md-8"> mean color distance</dd> 5798 <dt class="col-md-4">MAE</dt><dd class="col-md-8"> mean absolute error (normalized), average channel error distance</dd> 5799 <dt class="col-md-4">MEPP</dt><dd class="col-md-8"> mean error per pixel (normalized mean error, normalized peak error)</dd> 5800 <dt class="col-md-4">MSE</dt><dd class="col-md-8"> mean error squared, average of the channel error squared</dd> 5801 <dt class="col-md-4">NCC</dt><dd class="col-md-8"> normalized cross correlation</dd> 5802 <dt class="col-md-4">PAE</dt><dd class="col-md-8"> peak absolute (normalized peak absolute)</dd> 5803 <dt class="col-md-4">PHASH</dt><dd class="col-md-8"> perceptual hash for the sRGB and HCLp colorspaces. Specify an alternative colorspace with <code>-define phash:colorspaces=<var>colorspace,colorspace,...</var></code></dd> 5804 <dt class="col-md-4">PSNR</dt><dd class="col-md-8"> peak signal to noise ratio</dd> 5805 <dt class="col-md-4">RMSE</dt><dd class="col-md-8"> root mean squared (normalized root mean squared)</dd> 5806 <dt class="col-md-4">SSIM</dt><dd class="col-md-8"> structural similarity index</dd> 5807 </dl> 5808 5809 <p>Control the '<code>AE</code>', or absolute count of pixels that are different, 5810 with the <a href="command-line-options.html#fuzz" >-fuzz</a> factor (ignore pixels which 5811 only changed by a small amount). Use '<code>PAE</code>' to find the 5812 size of the <a href="command-line-options.html#fuzz" >-fuzz</a> factor needed to make all pixels 5813 'similar', while '<code>MAE</code>' determines the factor needed 5814 for about half the pixels to be similar. </p> 5815 5816 <p>The <code>MEPP</code> metric returns three different metrics 5817 ('<code>MAE</code>', '<code>MAE</code>' normalized, and '<code>PAE</code>' 5818 normalized) from a single comparison run. </p> 5819 5820 <p>The <code>SSIM</code> and <code>DSSIM</code> metrics respect these defines: 5821 <code>-define compare:ssim-radius</code>, <code>-define compare:ssim-sigma</code>, 5822 <code>-define compare:ssim-k1</code>, and <code>-define compare:ssim-k2</code>.</p> 5823 5824 <p>To print a complete list of metrics, use the <a href="command-line-options.html#list">-list 5825 metric</a> option.</p> 5826 5827 5828 <div style="margin: auto;"> 5829 <h3><a class="anchor" id="minimum"></a>-minimum</h3> 5830 </div> 5831 5832 <p class="magick-description">return the minimum intensity of an image sequence.</p> 5833 5834 <p>Select the 'minimal' value from all the surrounding pixels. </p> 5835 5836 <p>This is legacy option from the <a href="command-line-options.html#statistic" >method</a> of the same 5837 name. </p> 5838 5839 5840 5841 <div style="margin: auto;"> 5842 <h3><a class="anchor" id="mode"></a>-mode <var>geometry</var></h3> 5843 </div> 5844 5845 <p class="magick-description">make each pixel the \'predominant color\' of the neighborhood.'</p> 5846 5847 <div style="margin: auto;"> 5848 <h3>-mode <var>value</var></h3> 5849 </div> 5850 5851 <p class="magick-description">Mode of operation.</p> 5852 5853 <p>Choose the <var>value</var> from these styles: <code>Frame, 5854 Unframe, or Concatenate</code></p> 5855 5856 <p>Use the <a href="command-line-options.html#list" >-list</a> option with a '<code>Mode</code>' argument 5857 for a list of <a href="command-line-options.html#mode" >-mode</a> arguments available in your 5858 ImageMagick installation.</p> 5859 5860 5861 <div style="margin: auto;"> 5862 <h3><a class="anchor" id="modulate"></a>-modulate <var>brightness</var>[,<var>saturation</var>,<var>hue</var>]</h3> 5863 </div> 5864 5865 <p class="magick-description">Vary the <var>brightness</var>, <var>saturation</var>, and <var>hue</var> of an image.</p> 5866 5867 <p>The arguments are given as a percentages of variation. A value of 100 means 5868 no change, and any missing values are taken to mean 100.</p> 5869 5870 <p>The <var>brightness</var> is a multiplier of the overall 5871 brightness of the image, so 0 means pure black, 50 is half as bright, 200 is 5872 twice as bright. To invert its meaning <a href="command-line-options.html#negate">-negate</a> the image 5873 before and after. </p> 5874 5875 <p>The <var>saturation</var> controls the amount of color in an 5876 image. For example, 0 produce a grayscale image, while a large value such as 5877 200 produce a very colorful, 'cartoonish' color.</p> 5878 5879 <p>The <var>hue</var> argument causes a "rotation" of the colors 5880 within the image by the amount specified. For example, 50 results in 5881 a counter-clockwise rotation of 90, mapping red shades to purple, and so on. 5882 A value of either 0 or 200 results in a complete 180 degree rotation of the 5883 image. Using a value of 300 is a 360 degree rotation resulting in no change to 5884 the original image. </p> 5885 5886 <p>For example, to increase the color brightness by 20% and decrease the color 5887 saturation by 10% and leave the hue unchanged, use <a 5888 href="command-line-options.html#modulate">-modulate 120,90</a>.</p> 5889 5890 <p>Use <a href="command-line-options.html#set">-set</a> attribute of '<code 5891 >option:modulate:colorspace</code>' to specify which colorspace to 5892 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> 5893 5894 <pre class="highlight"><code>convert image.png -set option:modulate:colorspace hsb -modulate 120,90 modulate.png 5895 </code></pre> 5896 5897 <div style="margin: auto;"> 5898 <h3><a class="anchor" id="moments"></a>-moments</h3> 5899 </div> 5900 5901 <p class="magick-description">report image moments and perceptual hash.</p> 5902 5903 5904 <div style="margin: auto;"> 5905 <h3><a class="anchor" id="monitor"></a>-monitor</h3> 5906 </div> 5907 5908 <p class="magick-description">monitor progress.</p> 5909 5910 5911 <div style="margin: auto;"> 5912 <h3><a class="anchor" id="monochrome"></a>-monochrome</h3> 5913 </div> 5914 5915 <p class="magick-description">transform the image to black and white.</p> 5916 5917 <div style="margin: auto;"> 5918 <h3><a class="anchor" id="morph"></a>-morph <var>frames</var></h3> 5919 </div> 5920 5921 <p class="magick-description">morphs an image sequence.</p> 5922 5923 <p>Both the image pixels and size are linearly interpolated to give the 5924 appearance of a metamorphosis from one image to the next, over all the images 5925 in the current image list. The added images are the equivalent of a <a 5926 href="command-line-options.html#blend">-blend</a> composition. The <var>frames</var> 5927 argument determine how many images to interpolate between each image. </p> 5928 5929 5930 <div style="margin: auto;"> 5931 <h3><a class="anchor" id="morphology"></a>-morphology</h3> 5932 <h3>-morphology <var>method</var> <var>kernel</var></h3> 5933 </div> 5934 5935 <p class="magick-description">apply a morphology method to the image.</p> 5936 5937 <p>Until I get around to writing an option summary for this, see <a 5938 href="../Usage/morphology/" >IM Usage Examples, 5939 Morphology</a>. </p> 5940 5941 5942 <div style="margin: auto;"> 5943 <h3><a class="anchor" id="mosaic"></a>-mosaic</h3> 5944 </div> 5945 5946 <p class="magick-description">an simple alias for the <a href="command-line-options.html#layers" >-layers</a> method "mosaic"</p> 5947 5948 5949 <div style="margin: auto;"> 5950 <h3><a class="anchor" id="motion-blur"></a>-motion-blur <var>radius</var><br />-motion-blur <var>radius</var>x<var>sigma</var>+<var>angle</var></h3> 5951 </div> 5952 5953 <p class="magick-description">simulate motion blur.</p> 5954 5955 <p>Blur with the given radius, standard deviation (sigma), and angle. The 5956 angle given is the angle toward which the image is blurred. That is the 5957 direction people would consider the object is coming from. </p> 5958 5959 <p>Note that the blur is not uniform distribution, giving the motion a 5960 definite sense of direction of movement. </p> 5961 5962 <p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 5963 pixels which are outside the image proper are blurred into the final result. 5964 </p> 5965 5966 <div style="margin: auto;"> 5967 <h3><a class="anchor" id="name"></a>-name</h3> 5968 </div> 5969 5970 <p class="magick-description">name an image.</p> 5971 <div style="margin: auto;"> 5972 <h3><a class="anchor" id="negate"></a>-negate</h3> 5973 </div> 5974 5975 <p class="magick-description">replace each pixel with its complementary color.</p> 5976 5977 <p>The red, green, and blue intensities of an image are negated. White becomes 5978 black, yellow becomes blue, etc. Use <a href="command-line-options.html#negate">+negate</a> to only 5979 negate the grayscale pixels of the image.</p> 5980 5981 <div style="margin: auto;"> 5982 <h3><a class="anchor" id="noise"></a>-noise <var>geometry</var><br/> 5983 +noise <var>type</var></h3> 5984 </div> 5985 5986 <p class="magick-description">Add or reduce noise in an image.</p> 5987 5988 <p>The principal function of noise peak elimination filter is to smooth the 5989 objects within an image without losing edge information and without creating 5990 undesired structures. The central idea of the algorithm is to replace a pixel 5991 with its next neighbor in value within a pixel window, if this pixel has been 5992 found to be noise. A pixel is defined as noise if and only if this pixel is 5993 a maximum or minimum within the pixel window.</p> 5994 5995 <p>Use <code><a href="command-line-options.html#noise">-noise</a> <var>radius</var></code> to 5996 specify the width of the neighborhood when reducing noise. This is equivalent 5997 to using a <code><a href="command-line-options.html#statistic" >-statistic</a> NonPeak</code> operation, 5998 which should be used in preference.</p> 5999 6000 <p>Use <a href="command-line-options.html#noise">+noise</a> followed by a noise <var>type</var> to add noise to an image. Choose from these noise 6001 types:</p> 6002 6003 <pre class="highlight"><code>Gaussian 6004 Impulse 6005 Laplacian 6006 Multiplicative 6007 Poisson 6008 Random 6009 Uniform 6010 </code></pre> 6011 6012 <p>The amount of noise added can be controlled by the <code><a 6013 href="command-line-options.html#attenuate" >-attenuate</a></code> setting. If unset the value is 6014 equivalent to 1.0, or a maximum noise addition.</p> 6015 6016 <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> 6017 6018 <p>To print a complete list of noises, use the <a href="command-line-options.html#list">-list noise</a> option.</p> 6019 6020 <p>Also see the <a href="command-line-options.html#evaluate">-evaluate</a> noise functions that allows 6021 the use of a controlling value to specify the amount of noise that should be 6022 added to an image. </p> 6023 6024 6025 <div style="margin: auto;"> 6026 <h3><a class="anchor" id="normalize"></a>-normalize</h3> 6027 </div> 6028 6029 <p class="magick-description">Increase the contrast in an image by <var>stretching</var> the range of intensity values.</p> 6030 6031 <p>The intensity values are stretched to cover the entire range of possible 6032 values. While doing so, black-out at most <var>2%</var> of the pixels and 6033 white-out at most <var>1%</var> of the pixels.</p> 6034 6035 <p>Note that as of ImageMagick 6.4.7-0, <a href="command-line-options.html#normalize" >-normalize</a> 6036 is equivalent to <a href="command-line-options.html#contrast-stretch" >-contrast-stretch 2%x1%</a>. 6037 (Before this version, it was equivalent to <a href="command-line-options.html#contrast-stretch" 6038 >-contrast-stretch 2%x99%</a>).</p> 6039 6040 <p>All the channels are normalized in concert by the same amount so as to 6041 preserve color integrity, when the default <a href="command-line-options.html#channel" >+channel</a> 6042 setting is in use. Specifying any other <a href="command-line-options.html#channel" >-channel</a> 6043 setting will normalize the RGB channels independently.</p> 6044 6045 <p>See <a href="command-line-options.html#contrast-stretch" >-contrast-stretch</a> for more details. 6046 Also see <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' normalization 6047 that is better suited to mathematically generated images. </p> 6048 6049 <p>This operator is under review for re-development. </p> 6050 6051 6052 <div style="margin: auto;"> 6053 <h3><a class="anchor" id="opaque"></a>-opaque <var>color</var></h3> 6054 </div> 6055 6056 <p class="magick-description">change this color to the fill color within the image.</p> 6057 6058 <p>The <var>color</var> argument is defined using the format 6059 described under the <a href="command-line-options.html#fill" >-fill</a> option. The <a href="command-line-options.html#fuzz" 6060 >-fuzz</a> setting can be used to match and replace colors similar to the one 6061 given.</p> 6062 6063 <p>Use <a href="command-line-options.html#opaque">+opaque</a> to paint any pixel that does not match 6064 the target color. </p> 6065 6066 <p>The <a href="command-line-options.html#transparent">-transparent</a> operator is exactly the same 6067 as <a href="command-line-options.html#opaque" >-opaque</a> but replaces the matching color with 6068 transparency rather than the current <a href="command-line-options.html#fill">-fill</a> color setting. 6069 To ensure that it can do this it also ensures that the image has an alpha 6070 channel enabled, as per "<code><a href="command-line-options.html#alpha" >-alpha</a> set</code>", for 6071 the new transparent colors, and does not require you to modify the <a 6072 href="command-line-options.html#channel">-channel</a> to enable alpha channel handling. </p> 6073 6074 6075 <div style="margin: auto;"> 6076 <h3><a class="anchor" id="ordered-dither"></a>-ordered-dither <var>threshold_map</var>{,<var>level</var>...}</h3> 6077 </div> 6078 6079 <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 6080 given number of <var>levels</var> per color channel.</p> 6081 6082 <p>You can choose from these standard threshold maps:</p> 6083 6084 <pre class="pre-scrollable"><code> 6085 threshold 1x1 Threshold 1x1 (non-dither) 6086 checks 2x1 Checkerboard 2x1 (dither) 6087 o2x2 2x2 Ordered 2x2 (dispersed) 6088 o3x3 3x3 Ordered 3x3 (dispersed) 6089 o4x4 4x4 Ordered 4x4 (dispersed) 6090 o8x8 8x8 Ordered 8x8 (dispersed) 6091 h3x4a 4x1 Halftone 4x4 (angled) 6092 h6x6a 6x1 Halftone 6x6 (angled) 6093 h8x8a 8x1 Halftone 8x8 (angled) 6094 h3x4o Halftone 4x4 (orthogonal) 6095 h6x6o Halftone 6x6 (orthogonal) 6096 h8x8o Halftone 8x8 (orthogonal) 6097 h36x16o Halftone 16x16 (orthogonal) 6098 c5x5b c5x5 Circles 5x5 (black) 6099 c5x5w Circles 5x5 (white) 6100 c6x6b c6x6 Circles 6x6 (black) 6101 c6x6w Circles 6x6 (white) 6102 c7x7b c7x7 Circles 7x7 (black) 6103 c7x7w Circles 7x7 (white) 6104 </code></pre> 6105 6106 <p> The <code>threshold</code> generated a simple 50% threshold of the image. 6107 This could be used with <var >level</var> to do the equivalent of <a 6108 href="command-line-options.html#posterize" >-posterize</a> to reduce an image to basic primary colors. 6109 </p> 6110 6111 <p>The <code>checks</code> pattern produces a 3 level checkerboard dither 6112 pattern. That is a grayscale will become a pattern of solid black, solid 6113 white, and mid-tone colors into a checkerboard pattern of black and white. 6114 </p> 6115 6116 <p>You can define your own <var >threshold map</var> for ordered 6117 dithering and halftoning your images, in either personal or system 6118 <code>thresholds.xml</code> XML file. See <a href="resources.html" >Resources</a> 6119 for more details of configuration files. </p> 6120 6121 <p>To print a complete list of the thresholds that have been defined, use the 6122 <a href="command-line-options.html#list" >-list threshold</a> option.</p> 6123 6124 <p>Note that at this time the same threshold dithering map is used for all 6125 color channels, no attempt is made to offset or rotate the map for different 6126 channels is made, to create an offset printing effect. Also as the maps are 6127 simple threshold levels, the halftone and circle maps will create incomplete 6128 circles along the edges of a colored area. Also all the effects are purely 6129 on/off boolean effects, without anti-aliasing to make the circles smooth 6130 looking. Large dots can be made to look better with a small amount of blurring 6131 after being created. </p> 6132 6133 6134 <div style="margin: auto;"> 6135 <h3><a class="anchor" id="orient"></a>-orient <var>image orientation</var></h3> 6136 </div> 6137 6138 <p class="magick-description">specify orientation of a digital camera image.</p> 6139 6140 <p>Choose from these orientations:</p> 6141 6142 <pre class="highlight"><code>bottom-left right-top 6143 bottom-right top-left 6144 left-bottom top-right 6145 left-top undefined 6146 right-bottom 6147 </code></pre> 6148 6149 <p>To print a complete list of orientations, use the <a href="command-line-options.html#list" >-list 6150 orientation</a> option.</p> 6151 6152 6153 <div style="margin: auto;"> 6154 <h3><a class="anchor" id="page"></a>-page <var>geometry</var><br/> 6155 -page <var>media</var>[<var>offset</var>][{<var>^!<></var>}]<br/> 6156 +page 6157 </h3> 6158 </div> 6159 6160 <p class="magick-description">Set the size and location of an image on the larger virtual canvas.</p> 6161 6162 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6163 6164 <p>For convenience you can specify the page size using <var>media</var> (see below). Offsets can then be added as with other 6165 <var>geometry</var> arguments (e.g. <a 6166 href="command-line-options.html#page">-page</a> <code>Letter+43+43</code>).</p> 6167 6168 <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. 6169 The choices for a PostScript page are:</p> 6170 6171 <dl class="row"> 6172 <dt class="col-md-4"> 11x17 </dt> <dd class="col-md-8"> 792 x 1224</dd> 6173 <dt class="col-md-4"> Ledger </dt> <dd class="col-md-8"> 1224 x 792</dd> 6174 <dt class="col-md-4"> Legal </dt> <dd class="col-md-8"> 612 x 1008</dd> 6175 <dt class="col-md-4"> Letter </dt> <dd class="col-md-8"> 612 x 792</dd> 6176 <dt class="col-md-4"> LetterSmall</dt> <dd class="col-md-8"> 612 x 792</dd> 6177 <dt class="col-md-4"> ArchE </dt> <dd class="col-md-8"> 2592 x 3456</dd> 6178 <dt class="col-md-4"> ArchD </dt> <dd class="col-md-8"> 1728 x 2592</dd> 6179 <dt class="col-md-4"> ArchC </dt> <dd class="col-md-8"> 1296 x 1728</dd> 6180 <dt class="col-md-4"> ArchB </dt> <dd class="col-md-8"> 864 x 1296</dd> 6181 <dt class="col-md-4"> ArchA </dt> <dd class="col-md-8"> 648 x 864</dd> 6182 <dt class="col-md-4"> A0 </dt> <dd class="col-md-8"> 2380 x 3368</dd> 6183 <dt class="col-md-4"> A1 </dt> <dd class="col-md-8"> 1684 x 2380</dd> 6184 <dt class="col-md-4"> A2 </dt> <dd class="col-md-8"> 1190 x 1684</dd> 6185 <dt class="col-md-4"> A3 </dt> <dd class="col-md-8"> 842 x 1190</dd> 6186 <dt class="col-md-4"> A4 </dt> <dd class="col-md-8"> 595 x 842</dd> 6187 <dt class="col-md-4"> A4Small </dt> <dd class="col-md-8"> 595 x 842</dd> 6188 <dt class="col-md-4"> A5 </dt> <dd class="col-md-8"> 421 x 595</dd> 6189 <dt class="col-md-4"> A6 </dt> <dd class="col-md-8"> 297 x 421</dd> 6190 <dt class="col-md-4"> A7 </dt> <dd class="col-md-8"> 210 x 297</dd> 6191 <dt class="col-md-4"> A8 </dt> <dd class="col-md-8"> 148 x 210</dd> 6192 <dt class="col-md-4"> A9 </dt> <dd class="col-md-8"> 105 x 148</dd> 6193 <dt class="col-md-4"> A10 </dt> <dd class="col-md-8"> 74 x 105</dd> 6194 <dt class="col-md-4"> B0 </dt> <dd class="col-md-8"> 2836 x 4008</dd> 6195 <dt class="col-md-4"> B1 </dt> <dd class="col-md-8"> 2004 x 2836</dd> 6196 <dt class="col-md-4"> B2 </dt> <dd class="col-md-8"> 1418 x 2004</dd> 6197 <dt class="col-md-4"> B3 </dt> <dd class="col-md-8"> 1002 x 1418</dd> 6198 <dt class="col-md-4"> B4 </dt> <dd class="col-md-8"> 709 x 1002</dd> 6199 <dt class="col-md-4"> B5 </dt> <dd class="col-md-8"> 501 x 709</dd> 6200 <dt class="col-md-4"> C0 </dt> <dd class="col-md-8"> 2600 x 3677</dd> 6201 <dt class="col-md-4"> C1 </dt> <dd class="col-md-8"> 1837 x 2600</dd> 6202 <dt class="col-md-4"> C2 </dt> <dd class="col-md-8"> 1298 x 1837</dd> 6203 <dt class="col-md-4"> C3 </dt> <dd class="col-md-8"> 918 x 1298</dd> 6204 <dt class="col-md-4"> C4 </dt> <dd class="col-md-8"> 649 x 918</dd> 6205 <dt class="col-md-4"> C5 </dt> <dd class="col-md-8"> 459 x 649</dd> 6206 <dt class="col-md-4"> C6 </dt> <dd class="col-md-8"> 323 x 459</dd> 6207 <dt class="col-md-4"> Flsa </dt> <dd class="col-md-8"> 612 x 936</dd> 6208 <dt class="col-md-4"> Flse </dt> <dd class="col-md-8"> 612 x 936</dd> 6209 <dt class="col-md-4"> HalfLetter </dt> <dd class="col-md-8"> 396 x 612</dd> 6210 </dl> 6211 6212 <p>This option is also used to place subimages when writing to a multi-image 6213 format that supports offsets, such as GIF89 and MNG. When used for this 6214 purpose the offsets are always measured from the top left corner of the canvas 6215 and are not affected by the <a href="command-line-options.html#gravity">-gravity</a> option. To 6216 position a GIF or MNG image, use <a href="command-line-options.html#page">-page</a><var>{+-}x{+-}y</var> (e.g. -page +100+200). When writing to a MNG 6217 file, a <a href="command-line-options.html#page">-page</a> option appearing ahead of the first image in 6218 the sequence with nonzero width and height defines the width and height values 6219 that are written in the <code>MHDR</code> chunk. Otherwise, the MNG width and 6220 height are computed from the bounding box that contains all images in the 6221 sequence. When writing a GIF89 file, only the bounding box method is used to 6222 determine its dimensions.</p> 6223 6224 <p>For a PostScript page, the image is sized as in <a 6225 href="command-line-options.html#geometry">-geometry</a> but positioned relative to the <var>lower 6226 left-hand corner</var> of the page by {+-}<code>x</code><var>offset</var>{+-}<code>y</code> <var>offset</var>. Use <a 6227 href="command-line-options.html#page">-page 612x792</a>, for example, to center the image within the 6228 page. If the image size exceeds the PostScript page, it is reduced to fit the 6229 page. The default gravity for the <a href="command-line-options.html#page">-page</a> option is <var>NorthWest</var>, i.e., positive <code>x</code> and <code>y</code> <var>offset</var> are measured rightward and downward from the top left 6230 corner of the page, unless the <a href="command-line-options.html#gravity">-gravity</a> option is 6231 present with a value other than <var>NorthWest</var>.</p> 6232 6233 <p>The default page dimensions for a TEXT image is 612x792.</p> 6234 6235 <p>This option is used in concert with <a href="command-line-options.html#density">-density</a>.</p> 6236 6237 <p>Use <a href="command-line-options.html#page">+page</a> to remove the page settings for an image.</p> 6238 6239 <div style="margin: auto;"> 6240 <h3><a class="anchor" id="paint"></a>-paint <var>radius</var></h3> 6241 </div> 6242 6243 <p class="magick-description">simulate an oil painting.</p> 6244 6245 <p>Each pixel is replaced by the most frequent color in a circular 6246 neighborhood whose width is specified with <var>radius</var>.</p> 6247 6248 <div style="margin: auto;"> 6249 <h3><a class="anchor" id="path"></a>-path <var>path</var></h3></div> 6250 6251 <p class="magick-description">write images to this path on disk.</p> 6252 6253 <div style="margin: auto;"> 6254 <h3><a class="anchor" id="pause_animate_"></a>-pause <var>seconds</var></h3> 6255 </div> 6256 6257 <p class="magick-description">Pause between animation loops</p> 6258 6259 <p>Pause for the specified number of seconds before repeating the animation.</p> 6260 6261 <div style="margin: auto;"> 6262 <h3><a class="anchor" id="pause_import_"></a>-pause <var>seconds</var></h3> 6263 </div> 6264 6265 <p class="magick-description">Pause between snapshots.</p> 6266 6267 <p>Pause for the specified number of seconds before taking the next snapshot.</p> 6268 6269 <div style="margin: auto;"> 6270 <h3><a class="anchor" id="perceptible"></a>-perceptible <var>epsilon</var></h3> 6271 </div> 6272 6273 <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> 6274 6275 <div style="margin: auto;"> 6276 <h3><a class="anchor" id="ping"></a>-ping</h3> 6277 </div> 6278 6279 <p class="magick-description">efficiently determine image characteristics.</p> 6280 6281 <div style="margin: auto;"> 6282 <h3><a class="anchor" id="pointsize"></a>-pointsize <var>value</var></h3> 6283 </div> 6284 6285 <p class="magick-description">pointsize of the PostScript, OPTION1, or TrueType font.</p> 6286 6287 <div style="margin: auto;"> 6288 <h3><a class="anchor" id="polaroid"></a>-polaroid <var>angle</var></h3> 6289 </div> 6290 6291 <p class="magick-description">simulate a Polaroid picture.</p> 6292 6293 <p>Use <code>+polaroid</code> to rotate the image at a random angle between -15 and +15 degrees.</p> 6294 6295 <div style="margin: auto;"> 6296 <h3><a class="anchor" id="poly"></a>-poly <var>"wt,exp ..."</var></h3> 6297 </div> 6298 6299 <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> 6300 6301 <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> 6302 6303 <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> 6304 6305 <p>The format is: <var>output = wt1*image1^exp1 + wt2*image2^exp2 </var>...</p> 6306 6307 <p>Some simple uses are:</p> 6308 <ul> 6309 <li>A weighted sum of each image provided all weights add to unity and all exponents=1. If the the weights are all equal to 1/(number of images), then this is equivalent to <a href="command-line-options.html#profile">-evaluate-sequence</a> <var>mean</var>.</li> 6310 <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> 6311 </ul> 6312 6313 <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> 6314 6315 <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> 6316 6317 6318 <div style="margin: auto;"> 6319 <h3><a class="anchor" id="posterize"></a>-posterize <var>levels</var></h3> 6320 </div> 6321 6322 <p class="magick-description">reduce the image to a limited number of color levels per channel.</p> 6323 6324 <p>Very low values of <var>levels</var>, e.g., 2, 3, 4, have the most 6325 visible effect.</p> 6326 6327 <div style="margin: auto;"> 6328 <h3><a class="anchor" id="precision"></a>-precision <var>value</var></h3> 6329 </div> 6330 6331 <p class="magick-description">set the maximum number of significant digits to be printed.</p> 6332 6333 <div style="margin: auto;"> 6334 <h3><a class="anchor" id="preview"></a>-preview <var>type</var></h3> 6335 </div> 6336 6337 <p class="magick-description">image preview type.</p> 6338 6339 <p>Use this option to affect the preview operation of an image (e.g. 6340 <code>convert file.png -preview Gamma Preview:gamma.png</code>). Choose from 6341 these previews:</p> 6342 6343 <pre class="pre-scrollable"><code> 6344 AddNoise 6345 Blur 6346 Brightness 6347 Charcoal 6348 Despeckle 6349 Dull 6350 EdgeDetect 6351 Gamma 6352 Grayscale 6353 Hue 6354 Implode 6355 JPEG 6356 OilPaint 6357 Quantize 6358 Raise 6359 ReduceNoise 6360 Roll 6361 Rotate 6362 Saturation 6363 Segment 6364 Shade 6365 Sharpen 6366 Shear 6367 Solarize 6368 Spiff 6369 Spread 6370 Swirl 6371 Threshold 6372 Wave 6373 </code></pre> 6374 6375 <p>To print a complete list of previews, use the <a href="command-line-options.html#list">-list preview</a> option.</p> 6376 6377 <p>The default preview is <code>JPEG</code>.</p> 6378 6379 <div style="margin: auto;"> 6380 <h3><a class="anchor" id="print"></a>-print <var>string</var></h3> 6381 </div> 6382 6383 <p class="magick-description">interpret string and print to console.</p> 6384 6385 <div style="margin: auto;"> 6386 <h3><a class="anchor" id="process"></a>-process <var>command</var></h3> 6387 </div> 6388 6389 <p class="magick-description">process the image with a custom image filter.</p> 6390 6391 <p>The command arguments has the form <code>"module arg1 arg2 arg3 ... 6392 argN"</code> where <code>module</code> is the name of the module to invoke (e.g. 6393 "Analyze") and arg1 arg2 arg3 ... argN are an arbitrary number of arguments to 6394 pass to the process module.</p> 6395 6396 <div style="margin: auto;"> 6397 <h3><a class="anchor" id="profile"></a>-profile <var>filename</var><br/> 6398 +profile <var>profile_name</var></h3> 6399 </div> 6400 6401 <p class="magick-description">Manage ICM, IPTC, or generic profiles in an image.</p> 6402 6403 <p>Using <a href="command-line-options.html#profile">-profile</a> <var>filename</var> adds an 6404 ICM (ICC color management), IPTC (newswire information), or a generic profile 6405 to the image.</p> 6406 6407 <p>Use <a href="command-line-options.html#profile">+profile <var>profile_name</var></a> to 6408 remove the indicated profile. ImageMagick uses standard filename globbing, so 6409 wildcard expressions may be used to remove more than one profile. Here we 6410 remove all profiles from the image except for the XMP profile: <code>+profile 6411 "!xmp,*"</code>. </p> 6412 6413 <p>Use <code>identify -verbose</code> to find out which profiles are in the 6414 image file. Use <a href="command-line-options.html#strip">-strip</a> to remove all profiles (and 6415 comments).</p> 6416 6417 <p>To extract a profile, the <a href="command-line-options.html#profile">-profile</a> option is not 6418 used. Instead, simply write the file to an image format such as <var>APP1, 8BIM, ICM,</var> or <var>IPTC</var>.</p> 6419 6420 <p>For example, to extract the Exif data (which is stored in JPEG files in the 6421 <var>APP1</var> profile), use.</p> 6422 6423 <pre class="highlight"><code>convert cockatoo.jpg profile.exif 6424 </code></pre> 6425 6426 <p>It is important to note that results may depend on whether or not the 6427 original image already has an included profile. Also, keep in mind that <a 6428 href="command-line-options.html#profile">-profile</a> is an "operator" (as opposed to a "setting") and 6429 therefore a conversion is made each time it is encountered, in order, in the 6430 command-line. For instance, in the following example, if the original image is 6431 CMYK with profile, a CMYK-CMYK-RGB conversion results.</p> 6432 6433 <pre class="highlight"><code>convert CMYK.tif -profile "CMYK.icc" -profile "RGB.icc" RGB.tiff 6434 </code></pre> 6435 6436 <p>Furthermore, since ICC profiles are not necessarily symmetric, extra 6437 conversion steps can yield unwanted results. CMYK profiles are often very 6438 asymmetric since they involve 3>4 and 4>3 channel mapping. 6439 </p> 6440 6441 <div style="margin: auto;"> 6442 <h3><a class="anchor" id="quality"></a>-quality <var>value</var></h3> 6443 </div> 6444 6445 <p class="magick-description">JPEG/MIFF/PNG compression level.</p> 6446 6447 <p>For the JPEG and MPEG image formats, quality is 1 (lowest image quality and 6448 highest compression) to 100 (best quality but least effective compression). 6449 The default is to use the estimated quality of your input image if it can 6450 be determined, otherwise 92. When the quality is greater than 90, then the 6451 chroma channels are not downsampled. 6452 Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to specify the 6453 factors for chroma downsampling.</p> 6454 6455 <p>For the JPEG-2000 image format, quality is mapped using a non-linear 6456 equation to the compression ratio required by the Jasper library. This 6457 non-linear equation is intended to loosely approximate the quality provided by 6458 the JPEG v1 format. The default quality value 100, a request for non-lossy 6459 compression. A quality of 75 results in a request for 16:1 compression.</p> 6460 6461 <p>For the MNG and PNG image formats, the quality value sets the zlib 6462 compression level (quality / 10) and filter-type (quality % 10). The default 6463 PNG "quality" is 75, which means compression level 7 with adaptive PNG 6464 filtering, unless the image has a color map, in which case it means 6465 compression level 7 with no PNG filtering.</p> 6466 6467 <p>For compression level 0 (quality value less than 10), the Huffman-only 6468 strategy is used, which is fastest but not necessarily the worst 6469 compression.</p> 6470 6471 <p>If filter-type is 4 or less, the specified PNG filter-type is used for 6472 all scanlines:</p> 6473 6474 <dl class="row"> 6475 <dt class="col-md-4">0</dt><dd class="col-md-8">none</dd> 6476 <dt class="col-md-4">1</dt><dd class="col-md-8">sub</dd> 6477 <dt class="col-md-4">2</dt><dd class="col-md-8">up</dd> 6478 <dt class="col-md-4">3</dt><dd class="col-md-8">average</dd> 6479 <dt class="col-md-4">4</dt><dd class="col-md-8">Paeth</dd> 6480 </dl> 6481 6482 <p>If filter-type is 5, adaptive filtering is used when quality is greater 6483 than 50 and the image does not have a color map, otherwise no filtering is 6484 used.</p> 6485 6486 <p>If filter-type is 6, adaptive filtering 6487 with <var>minimum-sum-of-absolute-values</var> is used.</p> 6488 6489 <p>Only if the output is MNG, if filter-type is 7, the LOCO color 6490 transformation (intrapixel differencing) and adaptive filtering 6491 with <var>minimum-sum-of-absolute-values</var> are used.</p> 6492 6493 <p>If the filter-type is 8 the zlib Z_RLE compression strategy (or the 6494 Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with 6495 adaptive PNG filtering.</p> 6496 6497 <p>If the filter-type is 9 the zlib Z_RLE compression strategy (or the 6498 Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with 6499 no PNG filtering.</p> 6500 6501 <p>The quality setting has no effect on the appearance or signature of PNG 6502 and MNG images, since the compression is always lossless.</p> 6503 6504 <p>Not all combinations of compression level, strategy, and PNG filter type 6505 can be obtained using the -quality option. For more precise control, 6506 you can use the PNG:compression-level=N, PNG:compression-strategy=N, and 6507 PNG:compression-filter=N defines, respectively, instead. 6508 See <a href="command-line-options.html#define">-define</a>. Values from the defines take precedence 6509 over values from the -quality option.</p> 6510 6511 <p>For further information, see 6512 the <a href="http://www.w3.org/pub/WWW/TR">PNG</a> specification.</p> 6513 6514 <p>For the MIFF and TIFF image formats, quality/10 is the <a href="command-line-options.html#compress">Zip/BZip</a> compression level, which is 0 (worst but fastest compression) to 9 (best but slowest). It has no effect on the image appearance, since the compression is always lossless.</p> 6515 6516 <p>For the BPG image format, quality/2 is the actual BPG compression level (range from 0 to 51).</p> 6517 6518 <div style="margin: auto;"> 6519 <h3><a class="anchor" id="quantize"></a>-quantize <var>colorspace</var></h3> 6520 </div> 6521 6522 <p class="magick-description">reduce colors using this colorspace.</p> 6523 6524 <p>This setting defines the colorspace used to sort out and reduce the number 6525 of colors needed by an image (for later dithering) by operators such as <a 6526 href="command-line-options.html#colors" >-colors</a>, Note that color reduction also happens 6527 automatically when saving images to color-limited image file formats, such as 6528 GIF, and PNG8.</p> 6529 6530 6531 <div style="margin: auto;"> 6532 <h3><a class="anchor" id="quiet"></a>-quiet</h3> 6533 </div> 6534 6535 <p class="magick-description">suppress all warning messages. Error messages are still reported.</p> 6536 6537 <div style="margin: auto;"> 6538 <h3><a class="anchor" id="radial-blur"></a>-radial-blur <var>angle</var></h3> 6539 </div> 6540 6541 <p class="magick-description">Blur around the center of the image.</p> 6542 6543 <p>Note that this is actually a rotational blur rather than a radial and as 6544 such actually mis-named. </p> 6545 6546 <p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 6547 pixels which are outside the image proper are blurred into the final result. 6548 </p> 6549 6550 6551 <div style="margin: auto;"> 6552 <h3><a class="anchor" id="raise"></a>-raise <var>thickness</var></h3> 6553 </div> 6554 6555 <p class="magick-description">Lighten or darken image edges.</p> 6556 6557 <p>This will create a 3-D effect. Use <a href="command-line-options.html#raise">-raise</a> to create 6558 a raised effect, otherwise use <a href="command-line-options.html#raise">+raise</a>. </p> 6559 6560 <p>Unlike the similar <a href="command-line-options.html#frame">-frame</a> option, <a 6561 href="command-line-options.html#raise">-raise</a> does not alter the dimensions of the image.</p> 6562 6563 <div style="margin: auto;"> 6564 <h3><a class="anchor" id="random-threshold"></a>-random-threshold <var>low</var>x<var>high</var></h3> 6565 </div> 6566 6567 <p class="magick-description">Apply a random threshold to the image.</p> 6568 6569 <div style="margin: auto;"> 6570 <h3><a class="anchor" id="range-threshold"></a>-range-threshold <var>low-black</var>,<var>low-white</var>,<var>high-white</var>,<var>high-black</var></h3> 6571 </div> 6572 6573 <p class="magick-description">Perform either hard or soft thresholding within some range of values in an image.</p> 6574 6575 <div style="margin: auto;"> 6576 <h3><a class="anchor" id="read-mask"></a>-read-mask 6577 <var>filename</var></h3> 6578 </div> 6579 6580 <p class="magick-description">Prevent updates to image pixels specified by the mask.</p> 6581 6582 <p>This the same as using a mask used for composite masking operations, with 6583 grayscale values causing blended updates of the image the mask is attached to. 6584 </p> 6585 6586 <p>Use <a href="command-line-options.html#read-mask">+read-mask</a> to remove the mask from images.</p> 6587 6588 <p>Also see <a href="command-line-options.html#clip-mask">-clip-mask</a> which work in the same way, 6589 but with strict boolean masking. </p> 6590 6591 <div style="margin: auto;"> 6592 <h3><a class="anchor" id="red-primary"></a>-red-primary <var>x,y</var></h3> 6593 </div> 6594 6595 <p class="magick-description">Set the red chromaticity primary point.</p> 6596 6597 <div style="margin: auto;"> 6598 <h3><a class="anchor" id="regard-warnings"></a>-regard-warnings</h3> 6599 </div> 6600 6601 <p class="magick-description">Pay attention to warning messages.</p> 6602 6603 <p>This option causes some warnings in some image formats to be treated 6604 as errors. </p> 6605 6606 <div style="margin: auto;"> 6607 <h3><a class="anchor" id="remap"></a>-remap <var>filename</var></h3> 6608 </div> 6609 6610 <p class="magick-description">Reduce the number of colors in an image to the colors used by this image.</p> 6611 6612 <p>If the <a href="command-line-options.html#dither">-dither</a> setting is enabled (the default) then 6613 the given colors are dithered over the image as necessary, otherwise the closest 6614 color (in RGB colorspace) is selected to replace that pixel in the image. </p> 6615 6616 <p>As a side effect of applying a <a href="command-line-options.html#remap">-remap</a> of colors across all 6617 images in the current image sequence, all the images will have the same color 6618 table. That means that when saved to a file format such as GIF, it will use 6619 that color table as a single common or global color table, for all the images, 6620 without requiring extra local color tables. </p> 6621 6622 <p>Use <a href="command-line-options.html#remap">+remap</a> to reduce all images in the current image 6623 sequence to use a common color map over all the images. This equivalent to 6624 appending all the images together (without extra background colors) and color 6625 reducing those images using <a href="command-line-options.html#colors">-colors</a> with a 256 color 6626 limit, then <a href="command-line-options.html#remap">-remap</a> those colors over the original list of 6627 images. This ensures all the images follow a single color map. </p> 6628 6629 <p>If the number of colors over all the images is less than 256, then <a 6630 href="command-line-options.html#remap">+remap</a> should not perform any color reduction or dithering, as 6631 no color changes are needed. In that case, its only effect is to force the use 6632 of a global color table. This recommended after using either <a 6633 href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#ordered-dither">-ordered-dither</a> to 6634 reduce the number of colors in an animated image sequence. </p> 6635 6636 <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> 6637 6638 <div style="margin: auto;"> 6639 <h3><a class="anchor" id="region"></a>-region <var>geometry</var></h3> 6640 </div> 6641 6642 <p class="magick-description">Set a region in which subsequent operations apply.</p> 6643 6644 <p>The <var>x</var> and <var>y</var> offsets are treated 6645 in the same manner as in <a href="command-line-options.html#crop">-crop</a>.</p> 6646 6647 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6648 6649 <p>Use <code>+region</code> to remove any previously set regions.</p> 6650 6651 <div style="margin: auto;"> 6652 <h3><a class="anchor" id="remote"></a>-remote</h3> 6653 </div> 6654 6655 <p class="magick-description">perform a remote operation.</p> 6656 6657 <p>The only command recognized is the name of an image file to load.</p> 6658 6659 <p>If you have more than one <a href="display.html">display</a> application 6660 running simultaneously, use the <a href="command-line-options.html#window"> window</a> option to 6661 specify which application to control.</p> 6662 6663 <div style="margin: auto;"> 6664 <h3><a class="anchor" id="render"></a>-render</h3> 6665 </div> 6666 6667 <p class="magick-description">render vector operations.</p> 6668 6669 <p>Use <a href="command-line-options.html#render">+render</a> to turn off rendering vector operations. 6670 This useful when saving the result to vector formats such as MVG or SVG.</p> 6671 6672 <div style="margin: auto;"> 6673 <h3><a class="anchor" id="repage"></a>-repage <var>geometry</var></h3> 6674 </div> 6675 6676 <p class="magick-description">Adjust the canvas and offset information of the image.</p> 6677 6678 <p>This option is like <a href="command-line-options.html#page">-page</a> but acts as an image operator 6679 rather than a setting. You can separately set the canvas size or the offset 6680 of the image on that canvas by only providing those components. </p> 6681 6682 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 6683 6684 <p>If a <code>!</code> flag is given the offset given is added to the existing 6685 offset to move the image relative to its previous position. This useful for 6686 animation sequences. </p> 6687 6688 <p>A given a canvas size of zero such as '<code>0x0</code>' forces it to 6689 recalculate the canvas size so the image (at its current offset) will appear 6690 completely on that canvas (unless it has a negative offset).</p> 6691 6692 <p>Use <a href="command-line-options.html#repage">+repage</a> to completely remove/reset the virtual 6693 canvas meta-data from the images. </p> 6694 6695 <p>The <a href="command-line-options.html#set">-set</a> '<code>page</code>' option can be used to 6696 directly assign virtual canvas meta-data. </p> 6697 6698 6699 <div style="margin: auto;"> 6700 <h3><a class="anchor" id="resample"></a>-resample <var>horizontal</var>x<var>vertical</var></h3> 6701 </div> 6702 6703 <p class="magick-description">Resample image to specified horizontal and vertical resolution.</p> 6704 6705 <p>Resize the image so that its rendered size remains the same as the original 6706 at the specified target resolution. For example, if a 300 DPI image renders at 6707 3 inches by 2 inches on a 300 DPI device, when the image has been resampled to 6708 72 DPI, it will render at 3 inches by 2 inches on a 72 DPI device. Note that 6709 only a small number of image formats (e.g. JPEG, PNG, and TIFF) are capable of 6710 storing the image resolution. For formats which do not support an image 6711 resolution, the original resolution of the image must be specified via <a 6712 href="command-line-options.html#density">-density</a> on the command line prior to specifying the 6713 resample resolution.</p> 6714 6715 <p>Note that Photoshop stores and obtains image resolution from a proprietary 6716 embedded profile. If this profile exists in the image, then Photoshop will 6717 continue to treat the image using its former resolution, ignoring the image 6718 resolution specified in the standard file header.</p> 6719 6720 <div style="margin: auto;"> 6721 <h3><a class="anchor" id="resize"></a>-resize <var>geometry</var></h3> 6722 </div> 6723 6724 <p class="magick-description">Resize an image.</p> 6725 6726 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets, if present in the geometry string, are 6727 ignored, and the <a href="command-line-options.html#gravity">-gravity</a> option has no effect.</p> 6728 6729 <p>If the <a href="command-line-options.html#filter">-filter</a> option 6730 or <code>-define filter:option=value</code> precedes the <a 6731 href="command-line-options.html#resize">-resize</a> option, the image is resized with the specified 6732 filter.</p> 6733 6734 <p>Many image processing algorithms assume your image is in a linear-light 6735 coding. If your image is gamma-corrected, you can remove the nonlinear gamma 6736 correction, apply the transform, then restore it like this:</p> 6737 6738 <pre class="highlight"><code>convert portrait.jpg -gamma .45455 -resize 25% -gamma 2.2 \ 6739 -quality 92 passport.jpg 6740 </code></pre> 6741 6742 <div style="margin: auto;"> 6743 <h3><a class="anchor" id="respect-parentheses"></a>-respect-parentheses</h3> 6744 </div> 6745 6746 <p class="magick-description">settings remain in effect until parenthesis boundary.</p> 6747 6748 <div style="margin: auto;"> 6749 <h3><a class="anchor" id="reverse"></a>-reverse</h3> 6750 </div> 6751 6752 <p class="magick-description">Reverse the order of images in the current image list.</p> 6753 6754 6755 <div style="margin: auto;"> 6756 <h3><a class="anchor" id="roll"></a>-roll {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var></h3> 6757 </div> 6758 6759 <p class="magick-description">roll an image vertically or horizontally by the amount given.</p> 6760 6761 <p>A negative <var>x</var> offset rolls the image right-to-left. 6762 A negative <var>y</var> offset rolls the image bottom-to-top.</p> 6763 6764 6765 <div style="margin: auto;"> 6766 <h3><a class="anchor" id="rotate"></a>-rotate <var>degrees</var>{<var><</var>}{<var>></var>}</h3> 6767 </div> 6768 6769 <p class="magick-description">Apply Paeth image rotation (using shear operations) to the image.</p> 6770 6771 <p>Use <code>></code> to rotate the image only if its width exceeds the 6772 height. <code><</code> rotates the image <var>only</var> if its width is less 6773 than the height. For example, if you specify <code>-rotate "-90>"</code> and 6774 the image size is 480x640, the image is not rotated. However, if the image is 6775 640x480, it is rotated by -90 degrees. If you use <code>></code> or 6776 <code><</code>, enclose it in quotation marks to prevent it from being 6777 misinterpreted as a file redirection.</p> 6778 6779 <p>Empty triangles in the corners, left over from rotating the image, are 6780 filled with the <code>background</code> color. </p> 6781 6782 <p>See also the <a href="command-line-options.html#distort">-distort</a> operator and specifically the 6783 '<code>ScaleRotateTranslate</code>' distort method. </p> 6784 6785 6786 <div style="margin: auto;"> 6787 <h3><a class="anchor" id="sample"></a>-sample <var>geometry</var></h3> 6788 </div> 6789 6790 <p class="magick-description">minify / magnify the image with pixel subsampling and pixel replication, respectively.</p> 6791 6792 <p>Change the image size simply by directly sampling the pixels original 6793 from the image. When magnifying, pixels are replicated in blocks. When 6794 minifying, pixels are sub-sampled (i.e., some rows and columns are skipped 6795 over). </p> 6796 6797 <p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with 6798 a <a href="command-line-options.html#filter">-filter</a> setting of <code>point</code> (nearest 6799 neighbor), though <a href="command-line-options.html#sample">-sample</a> is a lot faster, as it 6800 avoids all the filter processing of the image. As such it completely ignores 6801 the current <a href="command-line-options.html#filter">-filter</a> setting. </p> 6802 6803 <p>The key feature of the <a href="command-line-options.html#sample">-sample</a> is that no new colors 6804 will be added to the resulting image, though some colors may disappear. </p> 6805 6806 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Offsets, if present in the geometry string, are 6807 ignored, unlike <a href="command-line-options.html#resize">-resize</a>. </p> 6808 6809 6810 <p>The actual sampling point is the middle of the sub-region being sampled. 6811 As such a single pixel sampling of an image will take the middle pixel, (or 6812 top-left-middle if image has even dimensions). However the <a 6813 href="command-line-options.html#define">-define</a> '<code>sample:offset</code>' can be set to modify 6814 this position some other location within each sub-region being sampled, as 6815 a percentage offset.</p> 6816 6817 <p>By default this value is '<code>50</code>' for the midpoint, but could be set 6818 to '<code>0</code>' for top-left, '<code>100</code>' for bottom-right, or with 6819 separate X and Y offsets such as '<code>0x50</code>' for left-middle edge of 6820 sampling sub-region.</p> 6821 6822 6823 <div style="margin: auto;"> 6824 <h3><a class="anchor" id="sampling-factor"></a>-sampling-factor <var>horizontal-factor</var>x<var>vertical-factor</var></h3> 6825 </div> 6826 6827 <p class="magick-description">sampling factors used by JPEG or MPEG-2 encoder and YUV decoder/encoder.</p> 6828 6829 <p>This option specifies the sampling factors to be used by the JPEG encoder 6830 for chroma downsampling. If this option is omitted, the JPEG library will use 6831 its own default values. When reading or writing the YUV format and when 6832 writing the M2V (MPEG-2) format, use <a 6833 href="command-line-options.html#sampling-factor">-sampling-factor 2x1</a> or <a 6834 href="command-line-options.html#sampling-factor">-sampling-factor 4:2:2</a> to specify the 4:2:2 6835 downsampling method.</p> 6836 6837 <div style="margin: auto;"> 6838 <h3><a class="anchor" id="scale"></a>-scale <var>geometry</var></h3> 6839 </div> 6840 6841 <p class="magick-description">minify / magnify the image with pixel block averaging and pixel replication, respectively.</p> 6842 6843 <p>Change the image size simply by replacing pixels by averaging pixels 6844 together when minifying, or replacing pixels when magnifying. </p> 6845 6846 <p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with 6847 a <a href="command-line-options.html#filter">-filter</a> setting of <code>box</code>. Though it is a lot 6848 faster, as it avoids all the filter processing of the image. As such it 6849 completely ignores the current <a href="command-line-options.html#filter">-filter</a> setting. </p> 6850 6851 <p>If when shrinking (minifying) images the original image is some integer 6852 multiple of the new image size, the number of pixels averaged together to 6853 produce the new pixel color is the same across the whole image. This is 6854 a special case known as 'binning' and is often used as a method of reducing 6855 noise in image such as those generated by digital cameras, especially in low 6856 light conditions. </p> 6857 6858 6859 <div style="margin: auto;"> 6860 <h3><a class="anchor" id="scene"></a>-scene <var>value</var></h3> 6861 </div> 6862 6863 <p class="magick-description">set scene number.</p> 6864 6865 <p>This option sets the scene number of an image or the first image in an image sequence.</p> 6866 6867 <div style="margin: auto;"> 6868 <h3><a class="anchor" id="screen"></a>-screen</h3> 6869 </div> 6870 6871 <p class="magick-description">specify the screen to capture.</p> 6872 6873 <p>This option indicates that the GetImage request used to obtain the image 6874 should be done on the root window, rather than directly on the specified 6875 window. In this way, you can obtain pieces of other windows that overlap the 6876 specified window, and more importantly, you can capture menus or other popups 6877 that are independent windows but appear over the specified window.</p> 6878 6879 <div style="margin: auto;"> 6880 <h3><a class="anchor" id="seed"></a>-seed</h3> 6881 </div> 6882 6883 <p class="magick-description">seed a new sequence of pseudo-random numbers</p> 6884 6885 <div style="margin: auto;"> 6886 <h3><a class="anchor" id="segment"></a>-segment <var>cluster-threshold</var>x<var>smoothing-threshold</var></h3> 6887 </div> 6888 6889 <p class="magick-description">segment the colors of an image.</p> 6890 6891 <p>Segment an image by analyzing the histograms of the color components and 6892 identifying units that are homogeneous with the fuzzy c-means technique. This 6893 is part of the ImageMagick color quantization routines. </p> 6894 6895 <p>Specify <var>cluster threshold</var> as the number of pixels in 6896 each cluster that must exceed the cluster threshold to be considered valid. 6897 <var>Smoothing threshold</var> eliminates noise in the second 6898 derivative of the histogram. As the value is increased, you can expect 6899 a smoother second derivative. The default is 1.5.</p> 6900 6901 <p>If the <a href="command-line-options.html#verbose">-verbose</a> setting is defined, a detailed report 6902 of the color clusters is returned.</p> 6903 6904 6905 <div style="margin: auto;"> 6906 <h3><a class="anchor" id="selective-blur"></a>-selective-blur <var>radius</var><br />-selective-blur <var>radius</var>x<var>sigma</var>{<var>+threshold</var>}</h3> 6907 </div> 6908 6909 <p class="magick-description">Selectively blur pixels within a contrast threshold.</p> 6910 6911 <p>Blurs those pixels that are less than or equal to the threshold in 6912 contrast. The threshold may be expressed as a fraction of <var>QuantumRange</var> or as a percentage.</p> 6913 6914 <div style="margin: auto;"> 6915 <h3><a class="anchor" id="separate"></a>-separate</h3> 6916 </div> 6917 6918 <p class="magick-description">separate an image channel into a grayscale image. Specify the channel with <a href="command-line-options.html#channel">-channel</a>.</p> 6919 6920 <div style="margin: auto;"> 6921 <h3><a class="anchor" id="sepia-tone"></a>-sepia-tone <var>percent-threshold</var></h3> 6922 </div> 6923 6924 <p class="magick-description">simulate a sepia-toned photo.</p> 6925 6926 <p>Specify <var>threshold</var> as the percent threshold of the intensity (0 - 99.9%).</p> 6927 6928 <p>This option applies a special effect to the image, similar to the effect 6929 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 6930 toning. A threshold of 80% is a good starting point for a reasonable 6931 tone.</p> 6932 6933 6934 6935 <div style="margin: auto;"> 6936 <h3><a class="anchor" id="set"></a>-set <var>key value</var></h3> 6937 <h3>+set <var>key</var></h3> 6938 </div> 6939 6940 <p class="magick-description">sets image attributes and properties for images in the current image sequence.</p> 6941 6942 <p>This will assign (or modify) specific settings attached to all the images 6943 in the current image sequence. Using the <a href="command-line-options.html#set">+set</a> form of the 6944 option will either remove, or reset that setting to a default state, as 6945 appropriate. </p> 6946 6947 <p>For example, it will modify specific well known image meta-data 6948 'attributes' such as those normally overridden by: the options <a 6949 href="command-line-options.html#delay" >-delay</a>, <a href="command-line-options.html#dispose" >-dispose</a>, and <a 6950 href="command-line-options.html#page" >-page</a>, <a href="command-line-options.html#colorspace" >-colorspace</a>; generally 6951 assigned before the image is read in, by using a <var>key</var> of 6952 the same name. </p> 6953 6954 <p>If the given <var>key</var> does not match a specific known 6955 'attribute ', such as shown above, the setting is stored as a a free form 6956 'property' string. Such settings are listed in <a href="command-line-options.html#verbose" 6957 >-verbose</a> information ("<code>info:</code>" output format) as "Properties". 6958 </p> 6959 6960 <p>This includes string 'properties' that are set by and assigned to images 6961 using the options <a href="command-line-options.html#comment" >-comment</a>, <a href="command-line-options.html#label" 6962 >-label</a>, <a href="command-line-options.html#caption" >-caption</a>. These options actually assign 6963 a global 'artifact' which are automatically assigned (and any <a href="../www/escape.html" >Format Percent 6964 Escapes</a> expanded) to images as they are read in. For example:</p> 6965 6966 <pre class="highlight"><code>-> convert rose: -set comment 'Rose is a rose is a rose is a rose' rose.png 6967 identify -format %c rose.png 6968 Rose is a rose is a rose is a rose 6969 </code></pre> 6970 6971 <p>The set value can also make use of <a href="../www/escape.html" >Format and Print Image 6972 Properties</a> in the defined value. For example:</p> 6973 6974 <pre class="highlight"><code>-> convert rose: -set origsize '%wx%h' -resize 50% \ 6975 -format 'Old size = %[origsize] New size = %wx%h' info: 6976 Old size = 70x46 New size = 35x23 6977 </code></pre> 6978 6979 <p>Other well known 'properties' that are available include: 6980 '<code>date:create</code>' and '<code>date:modify</code>' and 6981 '<code>signature</code>'. </p> 6982 6983 <p>The <a href="command-line-options.html#repage">-repage</a> operator will also allow you to modify 6984 the '<code>page</code>' attribute of an image for images already in memory (also 6985 see <a href="command-line-options.html#repage">-page</a>). However it is designed to provide a finer 6986 control of the sub-parts of this 'attribute'. The <a href="command-line-options.html#set">-set page</a> 6987 option will only provide a direct, unmodified assignment of '<code>page</code>' 6988 attribute. </p> 6989 6990 <p>This option can also associate a colorspace or profile with your image. 6991 For example,</p> 6992 6993 <pre class="highlight"><code>convert image.psd -set profile ISOcoated_v2_eci.icc image-icc.psd 6994 </code></pre> 6995 6996 <p>Some 'properties' must be defined in a specific way to be used. For 6997 example only 'properties' prefixed with "<code>filename:</code>" can be used to 6998 modify the output filename of an image. For example</p> 6999 7000 <pre class="highlight"><code>convert rose: -set filename:mysize '%wx%h' 'rose_%[filename:mysize].png' 7001 </code></pre> 7002 7003 <p>If the setting value is prefixed with "<code>option:</code>" the setting will 7004 be saved as a global "Artifact" exactly as if it was set using the <a 7005 href="command-line-options.html#define" >-define</a> option. As such settings are global in scope, they 7006 can be used to pass 'attributes' and 'properties' of one specific image, 7007 in a way that allows you to use them in a completely different image, even if 7008 the original image has long since been modified or destroyed. For example: </p> 7009 7010 <pre class="highlight"><code>convert rose: -set option:rosesize '%wx%h' -delete 0 \ 7011 label:'%[rosesize]' label_size_of_rose.gif" 7012 </code></pre> 7013 7014 <p>Note that <a href="../www/escape.html" >Format Percent Escapes</a> will only match 7015 a 'artifact' if the given <var>key</var> does not match an existing 7016 'attribute' or 'property'. </p> 7017 7018 <p>You can set the attributes of the image registry by prefixing the value 7019 with <code>registry:</code>.</p> 7020 7021 <p>The <a href="command-line-options.html#set">-set profile</a> option can also be used to inject 7022 previously-formatted ancillary chunks into the output PNG file, using 7023 the commandline option as shown below or by setting the profile via a 7024 programming interface:</p> 7025 7026 <pre class="highlight"><code>convert in.png -set profile PNG-chunk-x:<filename> out.png 7027 </code></pre> 7028 7029 <p>where <var>x</var> is a location flag and 7030 <var>filename</var> is a file containing the chunk 7031 name in the first 4 bytes, then a colon (":"), followed by the chunk data. 7032 This encoder will compute the chunk length and CRC, so those must not 7033 be included in the file.</p> 7034 7035 <p>"x" can be "b" (before PLTE), "m" (middle, i.e., between PLTE and IDAT), 7036 or "e" (end, i.e., after IDAT). If you want to write multiple chunks 7037 of the same type, then add a short unique string after the "x" to prevent 7038 subsequent profiles from overwriting the preceding ones, e.g.,</p> 7039 7040 7041 <pre class="highlight"><code>convert in.png -set profile PNG-chunk-b01:file01 \ 7042 -profile PNG-chunk-b02:file02 out.png 7043 </code></pre> 7044 7045 <div style="margin: auto;"> 7046 <h3><a class="anchor" id="shade"></a>-shade <var>azimuth</var>x<var>elevation</var></h3> 7047 </div> 7048 7049 <p class="magick-description">shade the image using a distant light source.</p> 7050 7051 <p>Specify <var>azimuth</var> and <var>elevation</var> as 7052 the position of the light source. Use <a href="command-line-options.html#shade">+shade</a> to return 7053 the shading results as a grayscale image.</p> 7054 7055 <div style="margin: auto;"> 7056 <h3><a class="anchor" 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> 7057 </div> 7058 7059 <p class="magick-description">simulate an image shadow.</p> 7060 7061 <div style="margin: auto;"> 7062 <h3><a 7063 id="shared-memory"></a>-shared-memory</h3> 7064 </div> 7065 7066 <p class="magick-description">use shared memory.</p> 7067 7068 <p>This option specifies whether the utility should attempt to use shared 7069 memory for pixmaps. ImageMagick must be compiled with shared memory support, 7070 and the display must support the <var>MIT-SHM</var> extension. 7071 Otherwise, this option is ignored. The default is <code>True</code>.</p> 7072 7073 <div style="margin: auto;"> 7074 <h3><a class="anchor" id="sharpen"></a>-sharpen <var>radius</var><br />-sharpen <var>radius</var>x<var>sigma</var></h3> 7075 </div> 7076 7077 <p class="magick-description">sharpen the image.</p> 7078 7079 <p>Use a Gaussian operator of the given radius and standard deviation (sigma).</p> 7080 7081 <div style="margin: auto;"> 7082 <h3><a class="anchor" id="shave"></a>-shave <var>geometry</var></h3> 7083 </div> 7084 7085 <p class="magick-description">Shave pixels from the image edges.</p> 7086 7087 <p>The <var>size</var> portion of the <var>geometry</var> 7088 argument specifies the width of the region to be removed from both sides of 7089 the image and the height of the regions to be removed from top and bottom. 7090 Offsets are ignored.</p> 7091 7092 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 7093 7094 <div style="margin: auto;"> 7095 <h3><a class="anchor" id="shear"></a>-shear <var>Xdegrees</var>[x<var>Ydegrees</var>]</h3> 7096 </div> 7097 7098 <p class="magick-description">Shear the image along the x-axis and/or y-axis.</p> 7099 7100 <p>The shear angles may be positive, negative, or zero. When <var>Ydegrees</var> is omitted it defaults to 0. When both angles are 7101 given, the horizontal component of the shear is performed before the vertical 7102 component.</p> 7103 7104 <p>Shearing slides one edge of an image along the x-axis or y-axis (i.e., 7105 horizontally or vertically, respectively),creating a parallelogram. The amount 7106 of each is controlled by the respective shear angle. For horizontal shears, 7107 <var>Xdegrees</var> is measured clockwise relative to "up" (the 7108 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 7109 positive x-axis), sliding the right edge down when 0<<var>Ydegrees</var><90 and up when 90<<var>Ydegrees</var><180.</p> 7110 7111 <p>Empty triangles left over from shearing the image are filled with the color 7112 defined by the <a href="command-line-options.html#fill">-background</a> option. The color is specified 7113 using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 7114 7115 <p>The horizontal shear is performed before the vertical part. This is 7116 important to note, since horizontal and vertical shears do not 7117 <var>commute</var>, i.e., the order matters in a sequence of shears. For 7118 example, the following two commands are not equivalent.</p> 7119 7120 <pre class="highlight"><code>convert logo: -shear 20x0 -shear 0x60 logo-sheared.png 7121 convert logo: -shear 0x60 -shear 20x0 logo-sheared.png 7122 </code></pre> 7123 7124 <p>The first of the two commands above is equivalent to the following, except 7125 for the amount of empty space created; the command that follows generates 7126 a smaller image, and so is a better choice in terms of time and space.</p> 7127 7128 <pre class="highlight"><code>convert logo: -shear 20x60 logo-sheared.png 7129 </code></pre> 7130 7131 <div style="margin: auto;"> 7132 <h3><a class="anchor" id="sigmoidal-contrast"></a>-sigmoidal-contrast <var>contrast</var>x<var>mid-point</var></h3> 7133 </div> 7134 7135 <p class="magick-description">increase the contrast without saturating highlights or shadows.</p> 7136 7137 <p>Increase the contrast of the image using a sigmoidal transfer function 7138 without saturating highlights or shadows. <var>Contrast</var> 7139 indicates how much to increase the contrast. For example, 0 is none, 3 is 7140 typical and 20 is a lot. 7141 </p> 7142 7143 <p>The <var>mid-point</var> indicates where the maximum change 7144 'slope' in contrast should fall in the resultant image (0 is white; 50% is 7145 middle-gray; 100% is black). </p> 7146 7147 <p>By default the image contrast is increased, use <var>+sigmoidal-contrast</var> to decrease the contrast.</p> 7148 7149 <p>To achieve the equivalent of a sigmoidal brightness change (similar to 7150 a gamma adjustment), you would use <var>-sigmoidal-contrast 7151 {brightness}x0%</var> to increase brightness and <var>+sigmoidal-contrast {brightness}x0%</var> to decrease brightness. 7152 Note the use of '0' fo rthe mid-point of the sigmoidal curve. </p> 7153 7154 <p>Using a very high <var>contrast</var> will produce a sort of 7155 'smoothed thresholding' of the image. Not as sharp (with high aliasing 7156 effects) of a true threshold, but with tapered gray-levels around the threshold 7157 <var>mid-point</var>. </p> 7158 7159 <div style="margin: auto;"> 7160 <h3><a class="anchor" id="silent"></a>-silent</h3> 7161 7162 7163 </div> 7164 7165 <p class="magick-description">operate silently. This option is only used 7166 by the <a href="import.html">import</a> tool.</p> 7167 7168 <div style="margin: auto;"> 7169 <h3><a class="anchor" id="similarity-threshold"></a>-similarity-threshold <var>value</var></h3> 7170 </div> 7171 7172 <p class="magick-description">minimum RMSE for subimage match.</p> 7173 7174 <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> 7175 7176 <div style="margin: auto;"> 7177 <h3><a class="anchor" id="size"></a>-size <var>width</var>[x<var>height</var>][<var>+offset</var>]</h3> 7178 </div> 7179 7180 <p class="magick-description">set the width and height of the image.</p> 7181 7182 <p>Use this option to specify the width and height of raw images whose 7183 dimensions are unknown such as <code>GRAY</code>, <code>RGB</code>, or 7184 <code>CMYK</code>. In addition to width and height, use <a 7185 href="command-line-options.html#size">-size</a> with an offset to skip any header information in the 7186 image or tell the number of colors in a <code>MAP</code> image file, (e.g. -size 7187 640x512+256).</p> 7188 7189 <p>For Photo CD images, choose from these sizes:</p> 7190 7191 <pre class="highlight"><code>192x128 7192 384x256 7193 768x512 7194 1536x1024 7195 3072x2048 7196 </code></pre> 7197 7198 <div style="margin: auto;"> 7199 <h3><a class="anchor" id="sketch"></a>-sketch <var>radius</var><br />-sketch <var>radius</var>x<var>sigma</var>+<var>angle</var></h3> 7200 </div> 7201 7202 <p class="magick-description">simulate a pencil sketch.</p> 7203 7204 <p>Sketch with the given radius, standard deviation (sigma), and angle. The 7205 angle given is the angle toward which the image is sketched. That is the 7206 direction people would consider the object is coming from. </p> 7207 7208 <div style="margin: auto;"> 7209 <h3><a class="anchor" id="smush"></a>-smush <var>offset</var></h3> 7210 </div> 7211 7212 <p class="magick-description">appends an image sequence together ignoring transparency.</p> 7213 7214 <p>Smush is a more flexible version of <a href="command-line-options.html#append">-append</a>, joining the images in the sequence top-to-bottom (<a href="command-line-options.html#smush">-smush</a>) or left-to-right (<a href="command-line-options.html#smush">+smush</a>), with a gap between images according to the specified offset.</p> 7215 7216 <p>If the offset is negative, images will overlap by that amount.</p> 7217 7218 <p><a href="command-line-options.html#smush">-smush</a> respects <a href="command-line-options.html#gravity">-gravity</a>. Any empty space will be filled with the <a href="command-line-options.html#background">-background</a> color.</p> 7219 7220 <p>For zero offset and transparent images, the non-transparent parts of the two images will be aligned as close as possible without overlapping.</p> 7221 7222 <div style="margin: auto;"> 7223 <h3><a class="anchor" id="snaps"></a>-snaps <var>value</var></h3> 7224 </div> 7225 7226 <p class="magick-description">Set the number of screen snapshots.</p> 7227 7228 <p>Use this option to grab more than one image from the X server screen, to create an animation sequence.</p> 7229 7230 <div style="margin: auto;"> 7231 <h3><a class="anchor" id="solarize"></a>-solarize <var>percent-threshold</var></h3> 7232 </div> 7233 7234 <p class="magick-description">negate all pixels above the threshold level.</p> 7235 7236 <p>Specify <var>factor</var> as the percent threshold of the intensity (0 - 99.9%).</p> 7237 7238 <p>This option produces a <var>solarization</var> effect seen when 7239 exposing a photographic film to light during the development process.</p> 7240 7241 <div style="margin: auto;"> 7242 <h3><a class="anchor" id="sparse-color"></a>-sparse-color <var>method</var> '<var>x</var>,<var>y</var> <var>color</var> ...'</h3> 7243 </div> 7244 7245 <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> 7246 7247 7248 <dl class="row"> 7249 <dt class="col-md-4">barycentric</dt> 7250 <dd class="col-md-8">three point triangle of color given 3 points. 7251 Giving only 2 points will form a linear gradient between those points. 7252 The gradient generated extends beyond the triangle created by those 7253 3 points. </dd> 7254 <dt class="col-md-4">bilinear</dt> 7255 <dd class="col-md-8">Like barycentric but for 4 points. Less than 4 points 7256 fall back to barycentric. </dd> 7257 <dt class="col-md-4">voronoi</dt> 7258 <dd class="col-md-8">Simply map each pixel to the to nearest color point 7259 given. The result are polygonal 'cells' of solid color. </dd> 7260 <dt class="col-md-4">manhattan</dt> 7261 <dd class="col-md-8">Like voronoi, but resulting polygonal 'cells' are mapped to a fixed coordinate system.</dd> 7262 <dt class="col-md-4">shepards</dt> 7263 <dd class="col-md-8">Colors points biased on the ratio of inverse distance 7264 squared. Generating spots of color in a sea of the average of 7265 colors. </dd> 7266 <dt class="col-md-4">inverse</dt> 7267 <dd class="col-md-8">Colors points biased on the ratio of inverse distance. 7268 This generates sharper points of color rather than rounded spots of 7269 '<code>shepards</code>' Generating spots of color in a sea of the 7270 average of colors. </dd> 7271 </dl> 7272 7273 <p>The points are placed according to the images location on the virtual 7274 canvas (<a href="command-line-options.html#page" >-page</a> or <a href="command-line-options.html#repage" >-repage</a> 7275 offset), and do not actually have to exist on the given image, but may be 7276 some point beyond the edge of the image. All points are floating point values. 7277 </p> 7278 7279 <p>Only the color channels defined by the <a href="command-line-options.html#channel" >-channel</a> are 7280 modified, which means that by default matte/alpha transparency channel is not 7281 affected. Typically transparency channel is turned off either before or after 7282 the operation. </p> 7283 7284 <p>Of course if some color points are transparent to generate a transparent 7285 gradient, then the image also requires transparency enabled to store the 7286 values. </p> 7287 7288 <p>All the above methods when given a single point of color will replace all 7289 the colors in the image with the color given, regardless of the point. This is 7290 logical, and provides an alternative technique to recolor an image to some 7291 default value. </p> 7292 7293 7294 <div style="margin: auto;"> 7295 <h3><a class="anchor" id="splice"></a>-splice <var>geometry</var></h3> 7296 </div> 7297 7298 <p class="magick-description">Splice the current background color into the image.</p> 7299 7300 <p>This will add rows and columns of the current <a 7301 href="command-line-options.html#background">-background</a> color into the given image according to the 7302 given <a href="command-line-options.html#gravity">-gravity</a> geometry setting. See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Essentially <a href="command-line-options.html#splice">-splice</a> will divide the 7303 image into four quadrants, separating them by the inserted rows and columns. 7304 </p> 7305 7306 <p>If a dimension of geometry is zero no rows or columns will be added for that 7307 dimension. Similarly using a zero offset with the appropriate <a 7308 href="command-line-options.html#gravity">-gravity</a> setting will add rows and columns to the edges of 7309 the image, padding the image only along that one edge. Edge padding is what <a 7310 href="command-line-options.html#splice">-splice</a> is most commonly used for. </p> 7311 7312 <p>If the exact same <var>geometry</var> and <a 7313 href="command-line-options.html#gravity">-gravity</a> is later used with <a href="command-line-options.html#chop">-chop</a> the 7314 added added all splices removed. </p> 7315 7316 <div style="margin: auto;"> 7317 <h3><a class="anchor" id="spread"></a>-spread <var>amount</var></h3> 7318 </div> 7319 7320 <p class="magick-description">displace image pixels by a random amount.</p> 7321 7322 <p>The argument <var>amount</var> defines the size of the 7323 neighborhood around each pixel from which to choose a candidate pixel to 7324 blend.</p> 7325 7326 <p>The lookup is controlled by the <a href="command-line-options.html#interpolate">-interpolate</a> setting.</p> 7327 7328 <div style="margin: auto;"> 7329 <h3><a class="anchor" id="statistic"></a>-statistic <var>type</var> <var>geometry</var></h3> 7330 </div> 7331 7332 <p class="magick-description">replace each pixel with corresponding statistic from the neighborhood.</p> 7333 7334 <p>Choose from these statistic types:</p> 7335 <dl class="row"> 7336 <dt class="col-md-4">Gradient</dt><dd class="col-md-8">maximum difference (max - min) value in neighborhood</dd> 7337 <dt class="col-md-4">Maximum</dt><dd class="col-md-8">maximum value per channel in neighborhood</dd> 7338 <dt class="col-md-4">Minimum</dt><dd class="col-md-8">minimum value per channel in neighborhood</dd> 7339 <dt class="col-md-4">Mean</dt><dd class="col-md-8">average value per channel in neighborhood</dd> 7340 <dt class="col-md-4">Median</dt><dd class="col-md-8">median value per channel in neighborhood</dd> 7341 <dt class="col-md-4">Mode</dt><dd class="col-md-8">mode (most frequent) value per channel in neighborhood</dd> 7342 <dt class="col-md-4">Nonpeak</dt><dd class="col-md-8">value just before or after the median value per channel in neighborhood</dd> 7343 <dt class="col-md-4">RMS</dt><dd class="col-md-8">root mean square value per channel in neighborhood</dd> 7344 <dt class="col-md-4">StandardDeviation</dt><dd class="col-md-8"> standard deviation value per channel in neighborhood</dd> 7345 </dl> 7346 7347 <div style="margin: auto;"> 7348 <h3><a class="anchor" id="stegano"></a>-stegano <var>offset</var></h3> 7349 </div> 7350 7351 <p class="magick-description">hide watermark within an image.</p> 7352 7353 <p>Use an offset to start the image hiding some number of pixels from the 7354 beginning of the image. Note this offset and the image size. You will need 7355 this information to recover the steganographic image (e.g. display -size 7356 320x256+35 stegano:image.png).</p> 7357 7358 <div style="margin: auto;"> 7359 <h3><a class="anchor" id="stereo"></a>-stereo <var>+x</var>{<var>+y</var>}</h3> 7360 </div> 7361 7362 <p class="magick-description">composite two images to create a red / cyan stereo anaglyph.</p> 7363 7364 <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> 7365 7366 <div style="margin: auto;"> 7367 <h3><a class="anchor" id="storage-type"></a>-storage-type <var>type</var></h3> 7368 </div> 7369 7370 <p class="magick-description">pixel storage type. Here are the valid types:</p> 7371 7372 <dl class="row"> 7373 <dt class="col-md-4">char</dt><dd class="col-md-8">unsigned characters</dd> 7374 <dt class="col-md-4">double</dt><dd class="col-md-8">doubles</dd> 7375 <dt class="col-md-4">float</dt><dd class="col-md-8">floats</dd> 7376 <dt class="col-md-4">integer</dt><dd class="col-md-8">integers</dd> 7377 <dt class="col-md-4">long</dt><dd class="col-md-8">longs</dd> 7378 <dt class="col-md-4">quantum</dt><dd class="col-md-8">pixels in the native depth of your ImageMagick distribution</dd> 7379 <dt class="col-md-4">short</dt><dd class="col-md-8">unsigned shorts</dd> 7380 </dl> 7381 7382 <p>Float and double types are normalized from 0.0 to 1.0 otherwise the pixels 7383 values range from 0 to the maximum value the storage type can support.</p> 7384 7385 <div style="margin: auto;"> 7386 <h3><a class="anchor" id="stretch"></a>-stretch <var>fontStretch</var></h3> 7387 </div> 7388 7389 <p class="magick-description">Set a type of stretch style for fonts.</p> 7390 7391 <p>This setting suggests a type of stretch that ImageMagick should try to 7392 apply to the currently selected font family. Select <var>fontStretch</var> from the following.</p> 7393 7394 <pre class="highlight"><code>Any 7395 Condensed 7396 Expanded 7397 ExtraCondensed 7398 ExtraExpanded 7399 Normal 7400 SemiCondensed 7401 SemiExpanded 7402 UltraCondensed 7403 UltraExpanded 7404 </code></pre> 7405 7406 <p>To print a complete list of stretch types, use <a href="command-line-options.html#list">-list 7407 stretch</a>.</p> 7408 7409 <p>For other settings that affect fonts, see the options <a 7410 href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 7411 href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 7412 7413 <div style="margin: auto;"> 7414 <h3><a class="anchor" id="strip"></a>-strip</h3> 7415 </div> 7416 7417 <p class="magick-description">strip the image of any profiles, comments or these PNG chunks: bKGD,cHRM,EXIF,gAMA,iCCP,iTXt,sRGB,tEXt,zCCP,zTXt,date.</p> 7418 7419 <div style="margin: auto;"> 7420 <h3><a class="anchor" id="stroke"></a>-stroke <var>color</var></h3> 7421 </div> 7422 7423 <p class="magick-description">color to use when stroking a graphic primitive.</p> 7424 7425 <p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 7426 7427 <p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 7428 7429 <div style="margin: auto;"> 7430 <h3><a class="anchor" id="strokewidth"></a>-strokewidth <var>value</var></h3> 7431 </div> 7432 7433 <p class="magick-description">set the stroke width.</p> 7434 7435 <p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 7436 7437 <div style="margin: auto;"> 7438 <h3><a class="anchor" id="style"></a>-style <var>fontStyle</var></h3> 7439 </div> 7440 7441 <p class="magick-description">Set a font style for text.</p> 7442 7443 <p>This setting suggests a font style that ImageMagick should try to apply to 7444 the currently selected font family. Select <var>fontStyle</var> from 7445 the following.</p> 7446 7447 <pre class="highlight"><code>Any 7448 Italic 7449 Normal 7450 Oblique 7451 </code></pre> 7452 7453 <p>For other settings that affect fonts, see the options <a 7454 href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 7455 href="command-line-options.html#stretch">-stretch</a>, and <a href="command-line-options.html#weight">-weight</a>. </p> 7456 7457 <div style="margin: auto;"> 7458 <h3><a class="anchor" id="subimage-search"></a>-subimage-search</h3> 7459 </div> 7460 7461 <p class="magick-description">search for subimage.</p> 7462 7463 <p>This option is required to have compare search for the best match location 7464 of a small image within a larger image. This search will produce two images 7465 (or two frames). The first is the "difference" image and the second will 7466 be the "match score" image.</p> 7467 7468 <p>The "match-score" image is smaller containing a pixel for ever possible 7469 position of the top-left corner of the given sub-image. that is its size will 7470 be the size of the larger_image - sub_image + 1. The brightest location in 7471 this image is the location s the locate on the best match that is also 7472 reported. Note that this may or may not be a perfect match, and the actual 7473 brightness will reflect this. Other bright 'peaks' can be used to locate other 7474 possible matching locations. </p> 7475 7476 <p>Note that the search will try to compare the sub-image at every possible 7477 location in the larger image, as such it can be very slow. The smaller the 7478 sub-image the faster this search is. </p> 7479 7480 7481 <div style="margin: auto;"> 7482 <h3><a class="anchor" id="swap"></a>-swap <var>index,index</var></h3> 7483 </div> 7484 7485 <p class="magick-description">Swap the positions of two images in the image sequence.</p> 7486 7487 <p>For example, <a href="command-line-options.html#swap">-swap 0,2</a> swaps the first and the third 7488 images in the current image sequence. Use <a href="command-line-options.html#swap">+swap</a> to switch 7489 the last two images in the sequence.</p> 7490 7491 <div style="margin: auto;"> 7492 <h3><a class="anchor" id="swirl"></a>-swirl <var>degrees</var></h3> 7493 </div> 7494 7495 <p class="magick-description">swirl image pixels about the center.</p> 7496 7497 <p><var>Degrees</var> defines the tightness of the swirl.</p> 7498 7499 <div style="margin: auto;"> 7500 <h3><a class="anchor" id="synchronize"></a>-synchronize</h3> 7501 </div> 7502 7503 <p class="magick-description">synchronize image to storage device.</p> 7504 7505 <p>Set to "true" to ensure all image data is fully flushed and synchronized 7506 to disk. There is a performance penalty, but the benefits include ensuring a 7507 valid image file in the event of a system crash and early reporting if there 7508 is not enough disk space for the image pixel cache.</p> 7509 7510 <div style="margin: auto;"> 7511 <h3><a class="anchor" id="taint"></a>-taint</h3> 7512 </div> 7513 7514 <p class="magick-description">Mark the image as modified.</p> 7515 7516 <div style="margin: auto;"> 7517 <h3><a class="anchor" id="text-font"></a>-text-font <var>name</var></h3> 7518 </div> 7519 7520 <p class="magick-description">font for writing fixed-width text.</p> 7521 7522 <p>Specifies the name of the preferred font to use in fixed (typewriter style) 7523 formatted text. The default is 14 point <var>Courier</var>.</p> 7524 7525 <p>You can tag a font to specify whether it is a PostScript, TrueType, or 7526 OPTION1 font. For example, <code>Courier.ttf</code> is a TrueType font and 7527 <code>x:fixed</code> is OPTION1.</p> 7528 7529 <div style="margin: auto;"> 7530 <h3><a class="anchor" id="texture"></a>-texture <var>filename</var></h3> 7531 </div> 7532 7533 <p class="magick-description">name of texture to tile onto the image background.</p> 7534 7535 <div style="margin: auto;"> 7536 <h3><a class="anchor" id="threshold"></a>-threshold <var>value</var>{<var>%</var>}</h3> 7537 </div> 7538 7539 <!-- {<var>green,blue,opacity</var>} 7540 <p>If the green or blue value is omitted, these channels use the same value as 7541 the first one provided. If all three color values are the same, the result is 7542 a bi-level image. If the opacity threshold is omitted, OpaqueOpacity is used 7543 and any partially transparent pixel becomes fully transparent.</p> 7544 --> 7545 7546 <p class="magick-description">Apply simultaneous black/white threshold to the image.</p> 7547 7548 <p>Any pixel values (more specifically, those channels set using <a href="command-line-options.html#channel">‑channel</a>) that exceed the specified threshold are reassigned the 7549 maximum channel value, while all other values are assigned the minimum.</p> 7550 7551 <p> The threshold value can be given as a percentage or as an absolute integer 7552 value corresponding to the desired channel value. When given as an integer, 7553 the minimum attainable value is 0 (corresponding to black when all channels 7554 are affected), but the maximum value (corresponding to white) is that of the 7555 <code>quantum depth</code> of the particular build of ImageMagick, and is 7556 therefore dependent on the installation. For that reason, a reasonable 7557 recommendation for most applications is to specify the threshold values as 7558 a percentage. </p> 7559 7560 <p> The following would force pixels with red values above 50% to have 100% 7561 red values, while those at or below 50% red would be set to 0 in the red 7562 channel. The green, blue, and alpha channels (if present) would be unchanged. 7563 </p> 7564 7565 <pre class="highlight"><code>convert in.png -channel red -threshold 50% out.png 7566 </code></pre> 7567 7568 <p>As (possibly) impractical but instructive examples, the following would 7569 generate an all-black and an all-white image with the same dimensions as the 7570 input image.</p> 7571 7572 7573 <pre class="highlight"><code>convert in.png -channel RGB -threshold 100% black.png 7574 convert in.png -channel RGB -threshold -1 white.png 7575 </code></pre> 7576 7577 <p> See also <a href="command-line-options.html#black-threshold">‑black‑threshold</a> and <a href="command-line-options.html#white-threshold">‑white‑threshold</a>. 7578 </p> 7579 7580 <div style="margin: auto;"> 7581 <h3><a class="anchor" id="thumbnail"></a>-thumbnail <var>geometry</var></h3> 7582 </div> 7583 7584 <p class="magick-description">Create a thumbnail of the image.</p> 7585 7586 <p>This is similar to <a href="command-line-options.html#resize">-resize</a>, except it is optimized 7587 for speed and any image profile, other than a color profile, is removed to 7588 reduce the thumbnail size. To strip the color profiles as well, add <a 7589 href="command-line-options.html#strip">-strip</a> just before of after this option.</p> 7590 7591 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 7592 7593 <div style="margin: auto;"> 7594 <h3><a class="anchor" id="tile"></a>-tile <var>filename</var></h3> 7595 </div> 7596 7597 <p class="magick-description">Set the tile image used for filling a subsequent graphic primitive.</p> 7598 7599 <div style="margin: auto;"> 7600 <h3>-tile <var>geometry</var></h3> 7601 </div> 7602 7603 <p class="magick-description">Specify the layout of images.</p> 7604 7605 <p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p> 7606 7607 <div style="margin: auto;"> 7608 <h3>-tile</h3> 7609 </div> 7610 7611 <p class="magick-description">Specifies that a subsequent composite operation is repeated across and down image.</p> 7612 7613 <div style="margin: auto;"> 7614 <h3><a class="anchor" id="tile-offset"></a>-tile-offset {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var></h3> 7615 </div> 7616 7617 <p class="magick-description">Specify the offset for tile images, relative to the background image it is tiled on.</p> 7618 7619 <p>This should be set before the tiling image is set by <a href="command-line-options.html#tile" 7620 >-tile</a> or <a href="command-line-options.html#texture" >-texture</a>, or directly applied for 7621 creating a tiled canvas using <code>TILE:</code> or <code>PATTERN:</code> input 7622 formats. </p> 7623 7624 <p>Internally ImageMagick does a <a href="command-line-options.html#roll" >-roll</a> of the tile image 7625 by the arguments given when the tile image is set. </p> 7626 7627 <div style="margin: auto;"> 7628 <h3><a class="anchor" id="tint"></a>-tint <var>value</var></h3> 7629 </div> 7630 7631 <p class="magick-description">Tint the image with the fill color.</p> 7632 7633 <p>Tint the image with the fill color.</p> 7634 7635 <p>Specify the amount of tinting as a percentage. Pure colors like black, 7636 white red, yellow, will not be affected by -tint. Only mid-range colors such 7637 as the various shades of grey.</p> 7638 7639 <div style="margin: auto;"> 7640 <h3><a class="anchor" id="title"></a>-title <var>string</var></h3> 7641 </div> 7642 7643 <p class="magick-description">Assign a title to displayed image.", "animate", "display", "montage</p> 7644 7645 <p>Use this option to assign a specific title to the image. This assigned to 7646 the image window and is typically displayed in the window title bar. 7647 Optionally you can include the image filename, type, width, height, Exif data, 7648 or other image attribute by embedding special format characters described 7649 under the <a href="command-line-options.html#format">-format</a> option.</p> 7650 7651 <p>For example,</p> 7652 7653 <pre class="highlight"><code>-title "%m:%f %wx%h" 7654 </code></pre> 7655 7656 <p>produces an image title of <code>MIFF:bird.miff 512x480</code> for an image 7657 titled <code>bird.miff</code> and whose width is 512 and height is 480.</p> 7658 7659 7660 <div style="margin: auto;"> 7661 <h3><a class="anchor" id="transform"></a>-transform</h3> 7662 </div> 7663 7664 <p class="magick-description">transform the image.</p> 7665 7666 <p>This option applies the transformation matrix from a previous <a href="command-line-options.html#affine">-affine</a> option.</p> 7667 7668 <pre class="highlight"><code>convert -affine 2,2,-2,2,0,0 -transform bird.ppm bird.jpg 7669 </code></pre> 7670 7671 7672 <p>This operator has been now been superseded by the <a 7673 href="command-line-options.html#distort">-distort</a> '<code>AffineProjection</code>' method. </p> 7674 7675 7676 <div style="margin: auto;"> 7677 <h3><a class="anchor" id="transparent"></a>-transparent <var>color</var></h3> 7678 </div> 7679 7680 <p class="magick-description">Make this color transparent within the image.</p> 7681 7682 <p>The <var>color</var> argument is defined using the format 7683 described under the <a href="command-line-options.html#fill">-fill</a> option. The <a href="command-line-options.html#fuzz" 7684 >-fuzz</a> setting can be used to match and replace colors similar to the one 7685 given. </p> 7686 7687 <p>Use <a href="command-line-options.html#transparent" >+transparent</a> to invert the pixels matched. 7688 that is make all non-matching colors transparent. </p> 7689 7690 <p>The <a href="command-line-options.html#opaque">-opaque</a> operator is exactly the same as <a 7691 href="command-line-options.html#transparent" >-transparent</a> but replaces the matching color with the 7692 current <a href="command-line-options.html#fill">-fill</a> color setting, rather than transparent. 7693 However the <a href="command-line-options.html#transparent" >-transparent</a> operator also ensures 7694 that the image has an alpha channel enabled, as per "<code><a href="command-line-options.html#alpha" 7695 >-alpha</a> set</code>", and does not require you to modify the <a 7696 href="command-line-options.html#channel">-channel</a> to enable alpha channel handling. </p> 7697 7698 <p>Note that this does not define the color as being the 'transparency color' 7699 used for color-mapped image formats, such as GIF. For that use <a 7700 href="command-line-options.html#transparent-color" >-transparent-color</a> </p> 7701 7702 7703 <div style="margin: auto;"> 7704 <h3><a class="anchor" id="transparent-color"></a>-transparent-color <var>color</var></h3> 7705 </div> 7706 7707 <p class="magick-description">Set the transparent color.</p> 7708 7709 <p>Sometimes this is used for saving to image formats such as 7710 GIF and PNG8 which uses this color to represent boolean transparency. This 7711 does not make a color transparent, it only defines what color the transparent 7712 color is in the color palette of the saved image. Use <a 7713 href="command-line-options.html#transparent">-transparent</a> to make an opaque color transparent.</p> 7714 7715 <p>This option allows you to have both an opaque visible color, as well as a 7716 transparent color of the same color value without conflict. That is, you can 7717 use the same color for both the transparent and opaque color areas within an 7718 image. This, in turn, frees to you to select a transparent color that is 7719 appropriate when an image is displayed by an application that does not handle a 7720 transparent color index, while allowing ImageMagick to correctly handle images of this 7721 type. </p> 7722 7723 <p>The default transparent color is <code>#00000000</code>, which is fully transparent black.</p> 7724 7725 <div style="margin: auto;"> 7726 <h3><a class="anchor" id="transpose"></a>-transpose</h3> 7727 </div> 7728 7729 <p class="magick-description">Mirror the image along the top-left to bottom-right diagonal.</p> 7730 7731 <p> This option mathematically transposes the pixel array. It is equivalent to the sequence <code>-flip -rotate 90</code>. 7732 </p> 7733 7734 <div style="margin: auto;"> 7735 <h3><a class="anchor" id="transverse"></a>-transverse</h3> 7736 </div> 7737 7738 <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> 7739 7740 7741 <div style="margin: auto;"> 7742 <h3><a class="anchor" id="treedepth"></a>-treedepth <var>value</var></h3> 7743 </div> 7744 7745 <p class="magick-description">tree depth for the color reduction algorithm.</p> 7746 7747 <p>Normally, this integer value is zero or one. A value of zero or one causes 7748 the use of an optimal tree depth for the color reduction algorithm.</p> 7749 7750 <p>An optimal depth generally allows the best representation of the source 7751 image with the fastest computational speed and the least amount of memory. 7752 However, the default depth is inappropriate for some images. To assure the 7753 best representation, try values between 2 and 8 for this parameter. Refer to 7754 the <a href="../www/quantize.html" 7755 >color reduction algorithm</a> for more details.</p> 7756 7757 <p>The <a href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#monochrome">-monochrome</a> 7758 option, or writing to an image format which requires color reduction, is 7759 required for this option to take effect.</p> 7760 7761 <div style="margin: auto;"> 7762 <h3><a class="anchor" id="trim"></a>-trim</h3> 7763 </div> 7764 7765 <p class="magick-description">trim an image.</p> 7766 7767 <p>This option removes any edges that are exactly the same color as the corner 7768 pixels. Use <a href="command-line-options.html#fuzz">-fuzz</a> to make <a href="command-line-options.html#trim">-trim</a> remove 7769 edges that are nearly the same color as the corner pixels.</p> 7770 7771 <p>The page or virtual canvas information of the image is preserved allowing 7772 you to extract the result of the <a href="command-line-options.html#trim">-trim</a> operation from the 7773 image. Use a <a href="command-line-options.html#repage">+repage</a> to remove the virtual canvas page 7774 information if it is unwanted.</p> 7775 7776 <p>If the trimmed image 'disappears' an warning is produced, and a special 7777 single pixel transparent 'missed' image is returned, in the same way as when a 7778 <a href="command-line-options.html#crop">-crop</a> operation 'misses' the image proper. </p> 7779 7780 7781 <div style="margin: auto;"> 7782 <h3><a class="anchor" id="type"></a>-type <var>type</var></h3> 7783 </div> 7784 7785 <p class="magick-description">the image type.</p> <p>Choose from: <code>Bilevel</code>, 7786 <code>Grayscale</code>, <code>GrayscaleAlpha</code>, <code>Palette</code>, 7787 <code>PaletteAlpha</code>, <code>TrueColor</code>, <code>TrueColorAlpha</code>, 7788 <code>ColorSeparation</code>, or <code>ColorSeparationAlpha</code>.</p> 7789 7790 <p>Normally, when a format supports different subformats such as grayscale and 7791 truecolor, the encoder will try to choose an efficient subformat. The <a 7792 href="command-line-options.html#type">-type</a> option can be used to override this behavior. For 7793 example, to prevent a JPEG from being written in grayscale format even though 7794 only gray pixels are present, use.</p> 7795 7796 <pre class="highlight"><code>convert bird.png -type TrueColor bird.jpg 7797 </code></pre> 7798 7799 <p>Similarly, use <a href="command-line-options.html#type">-type TrueColorAlpha</a> to force the 7800 encoder to write an alpha channel even though the image is opaque, if the 7801 output format supports transparency.</p> 7802 7803 <p>Use <a href="command-line-options.html#type">-type optimize</a> to ensure the image is written in the smallest possible file size.</p> 7804 7805 <div style="margin: auto;"> 7806 <h3><a class="anchor" id="undercolor"></a>-undercolor <var>color</var></h3> 7807 </div> 7808 7809 <p class="magick-description">set the color of the annotation bounding box.</p> 7810 7811 <p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p> 7812 7813 <p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p> 7814 7815 7816 <div style="margin: auto;"> 7817 <h3><a class="anchor" id="update"></a>-update <var>seconds</var></h3> 7818 </div> 7819 7820 <p class="magick-description">detect when image file is modified and redisplay.</p> 7821 7822 <p>Suppose that while you are displaying an image the file that is currently 7823 displayed is over-written. <code>display</code> will automagically detect that 7824 the input file has been changed and update the displayed image 7825 accordingly.</p> 7826 7827 7828 <div style="margin: auto;"> 7829 <h3><a class="anchor" id="unique-colors"></a>-unique-colors</h3> 7830 </div> 7831 7832 <p class="magick-description">discard all but one of any pixel color.</p> 7833 7834 7835 <div style="margin: auto;"> 7836 <h3><a class="anchor" id="units"></a>-units <var>type</var></h3> 7837 </div> 7838 7839 <p class="magick-description">the units of image resolution.</p> 7840 7841 <p>Choose from: <code>Undefined</code>, <code>PixelsPerInch</code>, or 7842 <code>PixelsPerCentimeter</code>. This option is normally used in conjunction 7843 with the <a href="command-line-options.html#density">-density</a> option.</p> 7844 7845 7846 <div style="margin: auto;"> 7847 <h3><a class="anchor" id="unsharp"></a>-unsharp <var>radius</var><br />-unsharp <var>radius</var>x<var>sigma</var>{<var>+gain</var>}{<var>+threshold</var>}</h3> 7848 </div> 7849 7850 <p class="magick-description">sharpen the image with an unsharp mask operator.</p> 7851 7852 <p>The <a href="command-line-options.html#unsharp">-unsharp</a> option sharpens an image. The image is 7853 convolved with a Gaussian operator of the given radius and standard deviation 7854 (sigma). For reasonable results, radius should be larger than sigma. Use 7855 a radius of 0 to have the method select a suitable radius.</p> 7856 7857 <p>The parameters are:</p> 7858 7859 <dl class="row"> 7860 <dt class="col-md-4">radius</dt> 7861 <dd class="col-md-8">The radius of the Gaussian, in pixels, not counting the center pixel (default 0).</dd> 7862 <dt class="col-md-4">sigma</dt> 7863 <dd class="col-md-8">The standard deviation of the Gaussian, in pixels (default 1.0).</dd> 7864 <dt class="col-md-4">gain</dt> 7865 <dd class="col-md-8">The fraction of the difference between the original and the blur image that is added back into the original (default 1.0).</dd> 7866 <dt class="col-md-4">threshold</dt> 7867 <dd class="col-md-8">The threshold, as a fraction of <var>QuantumRange</var>, needed to apply the difference amount (default 0.05).</dd> 7868 </dl> 7869 7870 <div style="margin: auto;"> 7871 <h3><a class="anchor" id="verbose"></a>-verbose</h3> 7872 </div> 7873 7874 <p class="magick-description">print detailed information about the image when this option precedes the <a href="command-line-options.html#identify">-identify</a> option or <code>info:</code>.</p> 7875 7876 7877 <div style="margin: auto;"> 7878 <h3><a class="anchor" id="version"></a>-version</h3> 7879 </div> 7880 7881 <p class="magick-description">print ImageMagick version string and exit.</p> 7882 7883 7884 <div style="margin: auto;"> 7885 <h3><a class="anchor" id="view"></a>-view <var>string</var></h3> 7886 </div> 7887 7888 <p class="magick-description">FlashPix viewing parameters.</p> 7889 7890 7891 <div style="margin: auto;"> 7892 <h3><a class="anchor" id="vignette"></a>-vignette <var>radius</var>{x<var>sigma</var>}{<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var>{<var>%</var>}</h3> 7893 </div> 7894 7895 <p class="magick-description">soften the edges of the image in vignette style.</p> 7896 7897 <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> 7898 7899 <div style="margin: auto;"> 7900 <h3><a class="anchor" id="virtual-pixel"></a>-virtual-pixel <var>method</var></h3> 7901 </div> 7902 7903 <p class="magick-description">Specify contents of <var>virtual pixels</var>.</p> 7904 7905 <p>This option defines what color source should be used if and when a color 7906 lookup completely 'misses' the source image. The color(s) that appear to 7907 surround the source image. Generally this color is derived from the source 7908 image, but could also be set to a specify background color. </p> 7909 7910 <p>Choose from these methods:</p> 7911 7912 <dl class="row"> 7913 <dt class="col-md-4">background</dt><dd class="col-md-8">the area surrounding the image is the background color</dd> 7914 <dt class="col-md-4">black</dt><dd class="col-md-8">the area surrounding the image is black</dd> 7915 <dt class="col-md-4">checker-tile</dt><dd class="col-md-8">alternate squares with image and background color</dd> 7916 <dt class="col-md-4">dither</dt><dd class="col-md-8">non-random 32x32 dithered pattern</dd> 7917 <dt class="col-md-4">edge</dt><dd class="col-md-8">extend the edge pixel toward infinity</dd> 7918 <dt class="col-md-4">gray</dt><dd class="col-md-8">the area surrounding the image is gray</dd> 7919 <dt class="col-md-4">horizontal-tile</dt><dd class="col-md-8">horizontally tile the image, background color above/below</dd> 7920 <dt class="col-md-4">horizontal-tile-edge</dt><dd class="col-md-8">horizontally tile the image and replicate the side edge pixels</dd> 7921 <dt class="col-md-4">mirror</dt><dd class="col-md-8">mirror tile the image</dd> 7922 <dt class="col-md-4">random</dt><dd class="col-md-8">choose a random pixel from the image</dd> 7923 <dt class="col-md-4">tile</dt><dd class="col-md-8">tile the image (default)</dd> 7924 <dt class="col-md-4">transparent</dt><dd class="col-md-8">the area surrounding the image is transparent blackness</dd> 7925 <dt class="col-md-4">vertical-tile</dt><dd class="col-md-8">vertically tile the image, sides are background color</dd> 7926 <dt class="col-md-4">vertical-tile-edge</dt><dd class="col-md-8">vertically tile the image and replicate the side edge pixels</dd> 7927 <dt class="col-md-4">white</dt><dd class="col-md-8">the area surrounding the image is white</dd> 7928 </dl> 7929 7930 <p>The default value is "edge".</p> 7931 7932 <p>This most important for distortion operators such as <a href="command-line-options.html#distort" 7933 >-distort</a>, <a href="command-line-options.html#implode" >-implode</a>, and <a href="command-line-options.html#fx" >-fx</a>. 7934 However it also affects operations that may access pixels just outside the 7935 image proper, such as <a href="command-line-options.html#convolve">-convolve</a>, <a 7936 href="command-line-options.html#blur">-blur</a>, and <a href="command-line-options.html#sharpen">-sharpen</a>. </p> 7937 7938 <p>To print a complete list of virtual pixel types, use the <a 7939 href="command-line-options.html#list">-list virtual-pixel</a> option.</p> 7940 7941 7942 <div style="margin: auto;"> 7943 <h3><a class="anchor" id="visual"></a>-visual <var>type</var></h3> 7944 </div> 7945 7946 <p class="magick-description">Animate images using this X visual type.", 'animate', 'display'</p> 7947 7948 <p>Choose from these visual classes:</p> 7949 7950 <pre class="highlight"><code>StaticGray TrueColor 7951 GrayScale DirectColor 7952 StaticColor default 7953 PseudoColor visual id 7954 </code></pre> 7955 7956 <p>The X server must support the visual you choose, otherwise an error occurs. 7957 If a visual is not specified, the visual class that can display the most 7958 simultaneous colors on the default screen is chosen.</p> 7959 7960 7961 <div style="margin: auto;"> 7962 <h3><a class="anchor" id="watermark"></a>-watermark <var>brightness</var>x<var>saturation</var></h3> 7963 </div> 7964 7965 <p class="magick-description">Watermark an image using the given percentages of brightness and saturation.</p> 7966 7967 <p>Take a grayscale image (with alpha mask) and modify the destination image's 7968 brightness according to watermark image's grayscale value and the 7969 <var>brightness</var> percentage. The destinations color saturation 7970 attribute is just direct modified by the <var>saturation</var> 7971 percentage, which defaults to 100 percent (no color change). </p> 7972 7973 7974 <div style="margin: auto;"> 7975 <h3><a class="anchor" id="wave"></a>-wave <var>amplitude</var><br />-wave <var>amplitude</var>x<var>wavelength</var></h3> 7976 </div> 7977 7978 <p class="magick-description">Shear the columns of an image into a sine wave.</p> 7979 7980 <div style="margin: auto;"> 7981 <h3><a class="anchor" id="wavelet-denoise"></a>-wavelet-denoise <var>threshold</var><br />-wavelet-denoise <var>threshold</var>x<var>softness</var></h3> 7982 </div> 7983 7984 <p class="magick-description">removes noise from the image using a wavelet transform. The threshold is the value below which everything is considered noise and ranges from 0.0 (none) to QuantumRange or use percent (e.g. 5%). Softness attenuates the threshold and typically ranges from 0.0 (none) to 1.0. The higher the value the more noise that remains in the image.</p> 7985 7986 <div style="margin: auto;"> 7987 <h3><a class="anchor" id="weight"></a>-weight <var>fontWeight</var></h3> 7988 </div> 7989 7990 <p class="magick-description">Set a font weight for text.</p> 7991 7992 <p>This setting suggests a font weight that ImageMagick should try to apply to 7993 the currently selected font family. Use a positive integer for 7994 <var>fontWeight</var> or select from the following.</p> 7995 7996 <dl class="row"> 7997 <dt class="col-md-4">Thin </dt> 7998 <dd class="col-md-8">Same as <var>fontWeight</var> = 100.</dd> 7999 <dt class="col-md-4">ExtraLight </dt> 8000 <dd class="col-md-8">Same as <var>fontWeight</var> = 200.</dd> 8001 <dt class="col-md-4">Light </dt> 8002 <dd class="col-md-8">Same as <var>fontWeight</var> = 300.</dd> 8003 <dt class="col-md-4">Normal </dt> 8004 <dd class="col-md-8">Same as <var>fontWeight</var> = 400.</dd> 8005 <dt class="col-md-4">Medium </dt> 8006 <dd class="col-md-8">Same as <var>fontWeight</var> = 500.</dd> 8007 <dt class="col-md-4">DemiBold </dt> 8008 <dd class="col-md-8">Same as <var>fontWeight</var> = 600.</dd> 8009 <dt class="col-md-4">Bold </dt> 8010 <dd class="col-md-8">Same as <var>fontWeight</var> = 700.</dd> 8011 <dt class="col-md-4">ExtraBold </dt> 8012 <dd class="col-md-8">Same as <var>fontWeight</var> = 800.</dd> 8013 <dt class="col-md-4">Heavy </dt> 8014 <dd class="col-md-8">Same as <var>fontWeight</var> = 900.</dd> 8015 </dl> 8016 <br/> 8017 8018 <p>To print a complete list of weight types, use <a href="command-line-options.html#list">-list weight</a>.</p> 8019 8020 <p>For other settings that affect fonts, see the options <a 8021 href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 8022 href="command-line-options.html#stretch">-stretch</a>, and <a href="command-line-options.html#style">-style</a>. </p> 8023 8024 <div style="margin: auto;"> 8025 <h3><a class="anchor" id="white-point"></a>-white-point <var>x,y</var></h3> 8026 </div> 8027 8028 <p class="magick-description">chromaticity white point.</p> 8029 8030 <div style="margin: auto;"> 8031 <h3><a class="anchor" id="white-threshold"></a>-white-threshold <var>value</var>{<var>%</var>}</h3> 8032 </div> 8033 8034 <p class="magick-description">Force to white all pixels above the threshold while leaving all pixels at or below the threshold unchanged.</p> 8035 8036 <p> The threshold value can be given as a percentage or as an absolute integer 8037 value within [0, <var>QuantumRange</var>] corresponding to the 8038 desired <a href="command-line-options.html#channel">‑channel</a> value. See <a href="command-line-options.html#threshold">‑threshold</a>for more details on thresholds and resulting values. </p> 8039 8040 <div style="margin: auto;"> 8041 <h3><a class="anchor" id="window"></a>-window <var>id</var></h3> 8042 </div> 8043 8044 <p class="magick-description">Make the image the background of a window.", 'animate', 'display'</p> 8045 8046 <p><var>id</var> can be a window id or name. Specify <code>root</code> 8047 to select X's root window as the target window.</p> 8048 8049 <p>By default the image is tiled onto the background of the target window. If 8050 <code>backdrop</code> or <a href="command-line-options.html#geometry">-resize</a> are specified, the 8051 image is surrounded by the background color. Refer to <code>X RESOURCES</code> 8052 for details.</p> 8053 8054 <p>The image will not display on the root window if the image has more unique 8055 colors than the target window colormap allows. Use <a 8056 href="command-line-options.html#colors">-colors</a> to reduce the number of colors.</p> 8057 8058 <div style="margin: auto;"> 8059 <h3><a class="anchor" id="window-group"></a>-window-group</h3> 8060 </div> 8061 8062 <p class="magick-description">specify the window group.</p> 8063 8064 <div style="margin: auto;"> 8065 <h3><a class="anchor" id="write"></a>-write <var>filename</var></h3> 8066 </div> 8067 8068 <p class="magick-description">write an image sequence.</p> 8069 8070 <p>The image sequence preceding the <a href="command-line-options.html#write">-write</a> <var>filename</var> option is written out, and processing continues with the same image in its current state if there are additional options. To restore the image to its original state after writing it, use the <a href="command-line-options.html#write">+write</a> <var>filename</var> option.</p> 8071 8072 <p>Use <a href="command-line-options.html#compress">-compress</a> to specify the type of image compression.</p> 8073 8074 <div style="margin: auto;"> 8075 <h3><a class="anchor" id="write-mask"></a>-write-mask <var>filename</var></h3> 8076 </div> 8077 8078 <p class="magick-description">Prevent updates to image pixels specified by the mask.</p> 8079 8080 <p>This the same as using a mask used for composite masking operations, with 8081 grayscale values causing blended updates of the image the mask is attached to. 8082 </p> 8083 8084 <p>Use <a href="command-line-options.html#write-mask">+write-mask</a> to remove the mask from images.</p> 8085 8086 <p>Also see <a href="command-line-options.html#clip-mask">-clip-mask</a> which work in the same way, 8087 but with strict boolean masking. </p> 8088 </div> 8089 </div> 8090 </div> 8091 </main><!-- /.container --> 8092 <footer class="magick-footer"> 8093 <p><a href="security-policy.html">Security</a> 8094 <a href="architecture.html">Architecture</a> 8095 <a href="links.html">Related</a> 8096 <a href="sitemap.html">Sitemap</a> 8097 8098 <a href="command-line-options.html#"><img class="d-inline" id="wand" alt="And Now a Touch of Magick" width="16" height="16" src="../images/wand.ico"/></a> 8099 8100 <a href="http://pgp.mit.edu/pks/lookup?op=get&search=0x89AB63D48277377A">Public Key</a> 8101 <a href="support.html">Donate</a> 8102 <a href="https://imagemagick.org/script/contact.php">Contact Us</a> 8103 <br/> 8104 <small> 1999-2019 ImageMagick Studio LLC</small></p> 8105 </footer> 8106 8107 <!-- Javascript assets --> 8108 <script src="assets/magick.js" crossorigin="anonymous"></script> 8109 <script>window.jQuery || document.write('<script src="https://localhost/ajax/libs/jquery/3.3.1/jquery.min.js"><\/script>')</script> 8110 </body> 8111 </html> 8112 <!-- Magick Cache 5th January 2019 11:43 -->
