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 94defaults 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> 103option defaults to data-dependent triangulation. Use the <a 104href="command-line-options.html#filter">-filter</a> to choose a different resampling algorithm. 105Offsets, if present in the geometry string, are ignored, and the <a 106href="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 116defaults 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 125an image sequence into the given output file. However, some formats, such as 126JPEG and PNG, do not support more than one image per file, and in that case 127ImageMagick is forced to write each image as a separate file. As such, if 128more than one image needs to be written, the filename given is modified by 129adding a <a href="command-line-options.html#scene">-scene</a> number before the suffix, in order to 130make 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 133separate 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 137automagically enable <a href="command-line-options.html#adjoin">+adjoin</a> and are used to specify 138where the <a href="command-line-options.html#scene">-scene</a> number is placed in the filenames. These 139strings, such as '<code>%d</code>' or '<code>%03d</code>', are familiar to those 140who have used the standard <code>printf()</code>' C-library function. As an 141example, 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, 148my02morph.jpg, ..., my16morph.jpg. </p> 149 150<p>In summary, ImageMagick tries to write all images to one file, but will 151save 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 168href="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 171quotes or without spaces. </p> 172 173<p>Internally, the transformation matrix has 3x3 elements, but three of them 174are omitted from the input because they are constant. The new (transformed) 175coordinates (<var>x'</var>, <var>y'</var>) of a pixel at 176position (<var>x</var>, <var>y</var>) in the original 177image 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 182contains the transformed source image. The parameters 183<var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> 184subsequently shift the image pixels so that those that are moved out of the 185image area are cut off.</p> 186 187<p>The transformation matrix complies with the left-handed pixel coordinate 188system: positive <var>x</var> and <var>y</var> directions 189are 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, 193four 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, 197respectively, is accomplished with the following.</p> 198 199<p>See <a href="command-line-options.html#transform">-transform</a>, and the <a 200href="command-line-options.html#distort">-distort</a> method '<code>Affineprojection</code> for more 201information </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> 220transformations 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 222of the individual transformations.</p> 223 224<p>An attempt is made to detect near-singular transformation matrices. If the 225matrix 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 234channel 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 312same 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> 314Set</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 325control 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> 329control 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> 332or <a href="command-line-options.html#annotate">-annotate</a> <var>degrees</var>x<var>degrees</var> produces an unsheared rotation of the text. The 333direction of the rotation is positive, which means a clockwise rotation if <var>degrees</var> is positive. (This conforms to the usual mathematical 334convention once it is realized that the positive <var>y</var>–direction is 335conventionally 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 338equation.</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 343bottom-left of the text becomes the upper-left corner of the image, which is 344probably undesirable. Adding a <a href="command-line-options.html#gravity" >-gravity</a> option in this 345case leads to nice results.</p> 346 347<p>Text is any UTF-8 encoded character sequence. If <var>text</var> 348is 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 350formatting 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 359drawn. Use <a href="command-line-options.html#antialias">+antialias</a> to disable the addition of 360antialiasing edge pixels. This will then reduce the number of colors added to 361an image to just the colors being directly drawn. That is, no mixed colors 362are 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 371images in sequence top-to-bottom. Use <a href="command-line-options.html#append">+append</a> to 372stack images left-to-right. </p> 373 374<p>If they are not of the same width, narrower images are padded with the 375current <a href="command-line-options.html#background">-background</a> color setting, and their 376position relative to each other can be controlled by the current <a 377href="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 395a PDF that has been encrypted using Microsoft Crypto API (MSC API). The 396encrypting 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> 399and <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 409href="command-line-options.html#gamma" >-gamma</a> adjustment so that the mean color in the 410image 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 415light areas, but tend to fail for images with large amounts of bright sky or 416dark 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 421values 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 423together 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 434minimum and maximum color values in the image and then applies a <a 435href="command-line-options.html#level" >-level</a> operator to stretch the values to the full range of 436values. </p> 437 438<p>The operator is not typically used for real-life images, image scans, or 439JPEG format images, as a single 'out-rider' pixel can set a bad min/max values 440for the <a href="command-line-options.html#level" >-level</a> operation. On the other hand it is the 441right operator to use for color stretching gradient images being used to 442generate Color lookup tables, distortion maps, or other 'mathematically' 443defined images. </p> 444 445<p>The operator is very similar to the <a href="command-line-options.html#normalize">-normalize</a>, <a 446href="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' 448problems 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 452special '<var>sync</var>' flag for channel synchronization), to determine 453which color values are used and modified. As the default <a 454href="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 456together by the same gamma value, preserving colors, and ignoring 457transparency. </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' 467and then performs the appropriate 90 degree rotation on the image to orient 468the image, for correct viewing. </p> 469 470<p>This EXIF profile setting is usually set using a gravity sensor in digital 471camera, however photos taken directly downward or upward may not have an 472appropriate value. Also images that have been orientation 'corrected' without 473reseting this setting, may be 'corrected' again resulting in a incorrect 474result. If the EXIF profile was previously stripped, the <a 475href="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 510other X window activity while viewing the image. The color of the backdrop is 511specified as the background color. The color is specified using the format 512described 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 521href="command-line-options.html#fill">-fill</a> option. The default background color (if none is 522specified 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, 531consider 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 533to run the benchmark in parallel (requires the OpenMP feature).</p> 534 535<pre class="highlight"><code>-> convert logo: -resize 200% -bench 5 logo.png 536Performance[1]: 5i 1.344ips 1.000e 3.710u 0:03.720 537Performance[2]: 5i 1.634ips 0.549e 3.890u 0:03.060 538Performance[3]: 5i 2.174ips 0.618e 3.190u 0:02.300 539Performance[4]: 5i 1.678ips 0.555e 3.810u 0:02.980 540Performance[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 544second, using 3 threads and 3.190 seconds of the user allotted time, for 545a 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 554positive 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 557with convolutions that contain negative as well as positive values. This is 558especially the case with convolutions involving high pass filters or edge 559detection. Without an output bias, the negative values are clipped at 560zero.</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 563negative 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 567href="high-dynamic-range.html" >High Dynamic-Range Images</a>. For more 568about HDRI go the ImageMagick <a 569href="../Usage/basics/#hdri" >Usage</a> pages or this 570<a 571href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> 572entry. </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 587value within [0, <var>QuantumRange</var>] corresponding to the 588desired <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 598percentages given and each pixels transparency. If only a single percentage 599value is given it sets the weight of the composite or 'source' image, while 600the 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 631determines 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 634array which will hold the calculated Gaussian distribution. It should be an 635integer. If not given, or set to zero, IM will calculate the largest possible 636radius that will provide meaningful results for the Gaussian distribution. 637</p> 638 639<p>The larger the <var >Radius</var> the slower the 640operation is. However too small a <var >Radius</var>, and severe 641aliasing effects may result. As a guideline, <var >Radius</var> 642should be at least twice the <var >Sigma</var> value, though three 643times 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 646by taking advantage of the separability properties of the distribution. Here 647we apply a single-dimensional Gaussian matrix in the horizontal direction, 648then 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 651pixels 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 663ignored. </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 695href="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 698href="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 700size colors by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> before 701overlaying the original image in the center of this net image. This means that 702with the default compose method of '<code>Over</code>' any transparent parts may 703be 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 705functionality.</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 730not absolute settings. A brightness or contrast value of zero means no change. 731The range of values is -100 to +100 on each. Positive values increase the 732brightness or contrast and negative values decrease the brightness or contrast. 733To control only contrast, set the brightness=0. To control only brightness, 734set 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 737apply the brightness and/or contrast change. The default is to apply the same 738transformation to all channels.</p> 739 740<p>Brightness and Contrast arguments are converted to offset and slope of a 741linear transform and applied 742using <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 745contrast=+100. For brightness=0 and contrast=-100, the result are totally 746midgray. For brightness=0 and contrast=+100, the result will approach but 747not quite reach a threshold at midgray; that is the linear transformation 748is a very steep vertical line at mid gray.</p> 749 750<p>Negative slopes, i.e. negating the image, are not possible with this 751function. 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 754at brightness=+100. Thus, when contrast=0 and brightness=100, the result is 755totally white. Similarly, when contrast=0 and brightness=-100, the result is 756totally black.</p> 757 758<p>As the range of values for the arguments are -100 to +100, adding the '%' 759symbol 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 782option 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 786href="../www/escape.html">Format and 787Print Image Properties</a>. These attributes are expanded when the caption 788is 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 791remaining characters in the string. Comments read in from a file are literal; 792no 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 796instead.</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 804that the image <code>bird.miff</code> has a width of 512 and a height of 805480.</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 844abbreviated 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 857you 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 866special channel type <code>All</code>. Not all operators are 'channel capable', 867but generally any operators that are generally 'grey-scale' image operators, 868will 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 874operators that understand this flag should perform: cross-channel 875synchronization of the channels. If not specified, then most grey-scale 876operators will apply their image processing operations to each individual 877channel (as specified by the rest of the <a href="command-line-options.html#channel">-channel</a> 878setting) 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 882together in exactly the same way so that colors will remain in-sync. Without 883it being set, then each channel is modified separately and 884independently, which may produce color distortion. </p> 885 886<p>The <a href="command-line-options.html#morphology">-morphology</a> '<code>Convolve</code>' method 887and the <a href="command-line-options.html#compose">-compose</a> mathematical methods, also understands 888the '<code>Sync</code>' flag to modify the behavior of pixel colors according 889to the alpha channel (if present). That is to say it will modify the image 890processing with the understanding that fully-transparent colors should not 891contribute to the final result. </p> 892 893<p>Basically, by default, operators work with color channels in synchronous, and 894treats transparency as special, unless the <a href="command-line-options.html#channel">-channel</a> 895setting is modified so as to remove the effect of the '<code>Sync</code>' flag. 896How each operator does this depends on that operators current implementation. 897Not 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 901channel</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 905channels except the transparency channel, and that all the color channels are 906to be modified in exactly the same way, with an understanding of transparency 907(depending on the operation being applied). The 'plus' form <a 908href="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 911include 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 943href="command-line-options.html#channel" >-channel</a> setting (including the equivalent of the 944default). These operators have yet to be made to understand the newer 'Sync' 945flag. </p> 946 947<p>For example <a href="command-line-options.html#threshold">-threshold</a> will by default grayscale 948the image before thresholding, if no <a href="command-line-options.html#channel" >-channel</a> setting 949has 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 952href="command-line-options.html#gaussian-blur">-gaussian-blur</a>, will modify their handling of the 953color channels if the '<code>alpha</code>' channel is also enabled by <a 954href="command-line-options.html#channel" >-channel</a>. Generally this done to ensure that 955fully-transparent colors are treated as being fully-transparent, and thus any 956underlying 'hidden' color has no effect on the final results. Typically 957resulting in 'halo' effects. The newer <a href="command-line-options.html#morphology">-morphology</a> 958convolution equivalents however does have a understanding of the 'Sync' flag 959and will thus handle transparency correctly by default. </p> 960 961<p>As a alpha channel is optional within images, some operators will read the 962color channels of an image as a greyscale alpha mask, when the image has no 963alpha channel present, and the <a href="command-line-options.html#channel" >-channel</a> setting tells 964the operator to apply the operation using alpha channels. The <a 965href="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> 1012and <var>height</var> given in the of the <var>size</var> 1013portion of the <var>geometry</var> argument give the number of 1014columns and rows to remove. The <var>offset</var> portion of 1015the <var>geometry</var> argument is influenced by 1016a <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, 1019and 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 1022typically used with as <a href="command-line-options.html#gravity">-gravity</a> setting and zero 1023offsets so as to remove a single edge from an image. Compare this to <a 1024href="command-line-options.html#shave" >-shave</a> which removes equal numbers of pixels from opposite 1025sides of the image. </p> 1026 1027<p>Using <a href="command-line-options.html#chop">-chop</a> effectively undoes the results of a <a 1028href="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 1059delegate 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 1070white is not modified by any of the 'image processing operators' that follow, 1071until the mask is removed. Pixels in the black areas of the clip mask are 1072modified per the requirements of the operator. </p> 1073 1074<p>In some ways this is similar to (though not the same) as defining 1075a rectangular <a href="command-line-options.html#region" >-region</a>, or using the negative of the 1076mask (third) image in a three image <a href="command-line-options.html#composite" >-composite</a>, 1077operation. </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 1098clone of the images from the last 'pushed' image sequence, and adds them to 1099the 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 11030. Negative indexes are relative to the end of the sequence; for 1104example, <code>−1</code> 1105represents the last image of the sequence. Specify a range of images with a 1106dash (e.g. <code>0−4</code>). Separate multiple indexes with commas but no 1107spaces (e.g. <code>0,2,5</code>). A value of '<code>0−−1</code> will 1108effectively 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 1111in 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 1121histogram mapping of how each channel should be modified. Typically it is a 1122either a single row or column image of replacement color values. If larger 1123than a single row or column, values are taken from a diagonal line from 1124top-left to bottom-right corners.</p> 1125 1126<p>The lookup is further controlled by the <a 1127href="command-line-options.html#interpolate">-interpolate</a> setting, which is especially handy for an 1128LUT 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 1131gradients, and the '<code>integer</code>' setting for a direct, unsmoothed 1132lookup of color values. </p> 1133 1134<p>This operator is especially suited to replacing a grayscale image with a 1135specific 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> 1138setting will have their values replaced. In particular, since the default <a 1139href="command-line-options.html#channel">-channel</a> setting is <code>RGB</code>, this means that 1140transparency (alpha/matte channel) is not affected, unless the <a 1141href="command-line-options.html#channel">-channel</a> setting is modified. When the alpha channel is 1142set, it is treated by the <a href="command-line-options.html#clut" >-clut</a> operator in the same way 1143as the other channels, implying that alpha/matte values are replaced using the 1144alpha/matte values of the original image. </p> 1145 1146<p>If either the image being modified, or the lookup image, contains no 1147transparency (i.e. <a href="command-line-options.html#alpha" >-alpha</a> is turned 'off') but the <a 1148href="command-line-options.html#channel">-channel</a> setting includes alpha replacement, then it is 1149assumed that image represents a grayscale gradient which is used for the 1150replacement alpha values. That is you can use a grayscale CLUT image to 1151adjust a existing images alpha channel, or you can color a grayscale image 1152using 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 1156according to the lookup of the full color RGB value from a 2D representation 1157of 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 1167its <a href="command-line-options.html#dispose">-dispose</a> meta-data, to reproduce the look of 1168an animation at each point in the animation sequence. All images should be 1169the same size, and are assigned appropriate GIF disposal settings for the 1170animation to continue working as expected as a GIF animation. Such frames 1171are more easily viewed and processed than the highly optimized GIF overlay 1172images. </p> 1173 1174<p>The animation can be re-optimized after processing using 1175the <a href="command-line-options.html#layers">-layers</a> method '<code>optimize</code>', although 1176there is no guarantee that the restored GIF animation optimization is 1177better 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 1187values can be applied to the red, green, and blue channels of the image with 1188a comma-delimited list of colorization 1189values (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 1200is <code>PseudoColor</code> or <code>GrayScale</code>. Refer 1201to <a href="command-line-options.html#visual">-visual</a> for more details. By default, 1202a shared colormap is allocated. The image shares colors with 1203other X clients. Some image colors could be approximated, 1204therefore your image may look very different than intended. 1205If <code>private</code> is chosen, the image colors appear exactly 1206as they are defined. However, other clients may go <var>technicolor</var> 1207when 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, 1216but never more. Note that this a color reduction option. Images with fewer 1217unique colors than specified by <var>value</var> will have any 1218duplicate or unused colors removed. The ordering of an existing color 1219palette may be altered. When converting an image from color to grayscale, 1220it is more efficient to convert the image to the gray colorspace before 1221reducing the number of colors. Refer to 1222the <a href="../www/quantize.html"> 1223color 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, 1232and various other effects. Although variable-sized transformation matrices 1233can be used, typically one uses a 5x5 matrix for an RGBA image and a 6x6 1234for CMYKA (or RGBA with offsets). The matrix is similar to those used by 1235Adobe Flash except offsets are in column 6 rather than 5 (in support of 1236CMYKA 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 1257HCLp HSB HSI HSL 1258HSV HWB Lab LCHab 1259LCHuv LMS Log Luv 1260OHTA Rec601YCbCr Rec709YCbCr RGB 1261scRGB sRGB Transparent xyY 1262XYZ YCbCr YCC YDbDr 1263YIQ 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>*(C−K)/(<var>QuantumRange</var>−K)</td></tr> 1279 <tr><td valign="middle">M=<var>QuantumRange</var>*(M−K)/(<var>QuantumRange</var>−K)</td></tr> 1280 <tr><td valign="middle">Y=<var>QuantumRange</var>*(Y−K)/(<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*G−0.50000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1315 <tr><td valign="middle">I3=(−0.25000*R+0.50000*G−0.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*R−0.418688*G−0.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*R−0.385428*G+0.500000*B)+(<var>QuantumRange</var>+1)/2</td></tr> 1331 <tr><td valign="middle">Cr=(0.500000*R−0.454153*G−0.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*R−0.586811*G+0.88600*B) (with complicated scaling)</td></tr> 1345 <tr><td valign="middle">C2=(0.70100*R−0.586811*G−0.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*R−0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1350 <tr><td valign="middle">Cr=(0.500000*R−0.418688*G−0.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*R−0.27400*G−0.32200*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1355 <tr><td valign="middle">Q=(0.21100*R−0.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*R−0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1360 <tr><td valign="middle">Pr=(0.500000*R−0.418688*G−0.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*R−0.28950*G+0.43690*B)*(<var>QuantumRange</var>+1)/2</td></tr> 1365 <tr><td valign="middle">V=(0.61500*R−0.51500*G−0.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 1380combined image are taken from the grayscale values of each image in the 1381sequence, in order. For the default -channel setting of <code>RGB</code>, this 1382means the first image is assigned to the <code>Red</code> channel, the second 1383to 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 1386href="command-line-options.html#separate">-separate</a>, so long as the channel settings are the same. 1387Thus, in the following example, the final image should be a copy of the 1388original. </p> 1389 1390<pre class="highlight"><code>convert original.png -channel RGB -separate sepimage.png 1391convert 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 1402option 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 1406href="../www/escape.html">Format and 1407Print Image Properties</a>. These attributes are expanded when the comment 1408is 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 1411remaining characters in the string. Comments read in from a file are literal; 1412no 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 1416instead.</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 1424that the image <code>bird.miff</code> has a width of 512 and a height of 1425480.</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 1450Choose from these operators: 1451 1452<pre class="highlight"><code>add 1453conjugate 1454divide 1455magnitude-phase 1456multiply 1457real-imaginary 1458subtract 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 1470a detailed discussion of alpha compositing.</p> 1471 1472<p>This setting affects image processing operators that merge two (or more) 1473images 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>, 1482and <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>" 1485command. </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 1495according to the current <a href="command-line-options.html#compose">-compose</a> setting. The location 1496of the 'source' or 'overlay' image is controlled according to <a 1497href="command-line-options.html#gravity" >-gravity</a>, and <a href="command-line-options.html#geometry" >-geometry</a> 1498settings. </p> 1499 1500<p>If a third image is given this is treated as a grayscale blending 'mask' image 1501relative to the first 'destination' image. This mask is blended with the 1502source image. However for the '<code>displace</code>' compose method, the 1503mask 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 1506arguments or flags these can be provided by setting the <a 1507href="command-line-options.html#set">-set</a> '<code>option:compose:args</code>' 1508appropriately for the compose method. </p> 1509 1510<p>Some <a href="command-line-options.html#compose">-compose</a> methods can modify the 'destination' 1511image 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 1529compress</a>.</p> 1530 1531<p>Specify <a href="command-line-options.html#compress">+compress</a> to store the binary image in an 1532uncompressed format. The default is the compression type of the specified 1533image file.</p> 1534 1535<p>If <code>LZW</code> compression is specified but LZW compression has not been 1536enabled, the image data is written in an uncompressed LZW format that can be 1537read 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 1540JPEG library has been patched to support it. Use of lossless JPEG is generally 1541not recommended.</p> 1542 1543<p> 1544When writing an ICO file, you may request that the images be encoded in 1545PNG format, by specifying <code>Zip</code> compression.</p> 1546 1547<p> 1548When writing a JNG file, specify <code>Zip</code> compression to request that 1549the alpha channel be encoded in PNG "IDAT" format, or <code>JPEG</code> 1550to 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 1553to be used by JPEG, PNG, MIFF, and MPEG encoders. 1554Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to set the 1555sampling factor to be used by JPEG, MPEG, and YUV encoders for down-sampling 1556the 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 1573darker elements of the image. Use <a href="command-line-options.html#contrast">-contrast</a> to enhance 1574the image or <a href="command-line-options.html#contrast">+contrast</a> to reduce the image 1575contrast.</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 1593minus 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 1596the 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 1597clipping 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 1599prior 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 1602bin to modify the image. As such some colors may be merged together when they 1603originally fell into the same 'bin'. </p> 1604 1605<p>All the channels are normalized in concert by the same amount so as to 1606preserve color integrity, when the default <a href="command-line-options.html#channel" >+channel</a> 1607setting is in use. Specifying any other <a href="command-line-options.html#channel" >-channel</a> 1608setting 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' 1611normalization 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 1623a comma-separated list of integers (with no spaces), ordered left-to right, 1624starting with the top row. Presently, only odd-dimensioned kernels are 1625supported, and therefore the number of entries in the specified <var>kernel</var> must be 3<sup>2</sup>=9, 5<sup>2</sup>=25, 16267<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 1629positive and negative results are relative to a user-specified bias value. 1630This is important for non-HDRI compilations of ImageMagick when dealing with 1631convolutions that contain negative as well as positive values. This is 1632especially the case with convolutions involving high pass filters or edge 1633detection. 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 1637negative results without clipping to the color value range (0..QuantumRange). 1638See the discussion on HDRI implementations of ImageMagick on the page <a 1639href="high-dynamic-range.html">High 1640Dynamic-Range Images</a>. For more about HDRI go the ImageMagick <a 1641href="../Usage/basics/#hdri">Usage</a> pages or this 1642<a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a> 1643entry. </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 1661after cropping, and <var>x</var> and <var>y</var> in the 1662<var>offset</var> (if present) gives the location of the top left 1663corner of the cropped image with respect to the original image. To specify the 1664amount 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 1667present, a single image is generated, consisting of the pixels from the 1668cropping region. The offsets specify the location of the upper left corner of 1669the cropping region measured downward and rightward with respect to the upper 1670left corner of the image. If the <a href="command-line-options.html#gravity">-gravity</a> option is 1671present with <code>NorthEast</code>, <code>East</code>, or <code>SouthEast</code> 1672gravity, it gives the distance leftward from the right edge of the image to 1673the right edge of the cropping region. Similarly, if the <a 1674href="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 1676upward between the bottom edges.</p> 1677 1678<p>If the <var>x</var> and <var>y</var> offsets are 1679omitted, a set of tiles of the specified geometry, covering the entire input 1680image, is generated. The rightmost tiles and the bottom tiles are smaller if 1681the 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 1686cropped images virtual canvas page size and offset is set as if the 1687geometry argument was a viewport or window. This means the canvas page size 1688is set to exactly the same size you specified, the image offset set 1689relative top left corner of the region cropped. </p> 1690 1691<p>If the cropped image 'missed' the actual image on its virtual canvas, a 1692special single pixel transparent 'missed' image is returned, and a 'crop 1693missed' warning given. </p> 1694 1695<p>It might be necessary to <a href="command-line-options.html#repage" >+repage</a> the image prior to 1696cropping the image to ensure the crop coordinate frame is relocated to the 1697upper-left corner of the visible image. 1698 1699Similarly you may want to use <a href="command-line-options.html#repage" >+repage</a> after cropping to 1700remove the page offset that will be left behind. This is especially true when 1701you are going to write to an image format such as PNG that supports an image 1702offset.</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 1711colormap 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 1721can be either <code>None</code>, <code>All</code>, <code>Trace</code>, or 1722a 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 1736events 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 1739debug</a>.</p> 1740 1741<p>Use the <a href="command-line-options.html#log">-log</a> option to specify the format for debugging 1742output.</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> 1748environment variable are the same as for the <a href="command-line-options.html#debug">-debug</a> 1749option.</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 1761href="../www/cipher.html">ImageMagick: Encipher or 1762Decipher 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 1772href="command-line-options.html#coalesce">-coalesce</a>, replace the second and later images, with 1773a 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 1777sequence, though will not work correctly for GIF animations when parts of the 1778animation 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> 1781method '<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 1791while reading and writing image data. Definitions are generally used to 1792control image file format coder modules, and image processing operations, 1793beyond what is provided by normal means. Defined settings are listed in <a 1794href="command-line-options.html#verbose" >-verbose</a> information ("<code>info:</code>" output format) 1795as "Artifacts". </p> 1796 1797<p>If <var>value</var> is missing for a definition, an empty-valued 1798definition of a flag is created with that name. This used to control on/off 1799options. Use <a href="command-line-options.html#define">+define key</a> to remove definitions 1800previously created. Use <a href="command-line-options.html#define">+define "*"</a> to remove all 1801existing definitions.</p> 1802 1803<p>The same 'artifact' settings can also be defined using the <a 1804href="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 1805Properties</a> in the defined value. </p> 1806 1807<p>The <var>option</var> and <var>key</var> are case-independent (they are 1808converted to lowercase for use within the decoders) while the <var>value</var> 1809is 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 1814available:</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 2564pixels 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, 2571use:</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 2584next image. The default is no delay between each showing of the image 2585sequence. 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 2588value 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 2590you specify <code>30></code> and the image delay is 20, the image delay does 2591not change. However, if the image delay is 40 or 50, the delay it is changed 2592to 30. Enclose the given delay in quotation marks to prevent the 2593<code><</code> or <code>></code> from being interpreted by your shell as 2594a 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 26040. Negative indexes are relative to the end of the sequence, for example, -1 2605represents the last image of the sequence. Specify a range of images with 2606a 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 2617image or the canvas resolution while rendering (reading) vector formats such 2618as Postscript, PDF, WMF, and SVG into a raster image. Image resolution 2619provides the unit of measure to apply when rendering to an output device or 2620raster image. The default unit of measure is in dots per inch (DPI). The <a 2621href="command-line-options.html#units">-units</a> option may be used to select dots per centimeter 2622instead.</p> 2623 2624<p>The default resolution is 72 dots per inch, which is equivalent to one 2625point per pixel (Macintosh and Postscript standard). Computer screens are 2626normally 72 or 96 dots per inch, while printers typically support 150, 300, 2627600, or 1200 dots per inch. To determine the resolution of your display, use 2628a ruler to measure the width of your screen in inches, and divide by the 2629number 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 2632stored image resolution. Note that Photoshop stores and obtains image 2633resolution from a proprietary embedded profile. If this profile is not 2634stripped from the image, then Photoshop will continue to treat the image using 2635its former resolution, ignoring the image resolution specified in the standard 2636file header.</p> 2637 2638<p>The <a href="command-line-options.html#density">-density</a> option sets an <var>attribute</var> and 2639does not alter the underlying raster image. It may be used to adjust the 2640rendered size for desktop publishing purposes by adjusting the scale applied 2641to the pixels. To resize the image so that it is the same size at a different 2642resolution, 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 2651to specify the depth of raw images whose depth is unknown such as GRAY, RGB, 2652or 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, 2690is used as a displacement map, which is used to displace the lookup of 2691what part of the 'background' image is seen at each point of the overlaid 2692area. Much like the displacement map is a 'lens' that redirects light shining 2693through it so as to present a distorted view the original 'background' image 2694behind it. </p> 2695 2696<p>Any perfect grey areas of the displacement map produce a zero 2697displacement of the image. Black areas produce the given maximum negative 2698displacement of the lookup point, while white produce a maximum positive 2699displacement of the lookup. </p> 2700 2701<p>Note that it is the lookup of the 'background' that is displaced, not a 2702displacement of the image itself. As such an area of the displacement map 2703containing 'white' will have the lookup point 'shifted' by a positive amount, 2704and thus generating a copy of the destination image to the right/downward from 2705the 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 2707important in understanding how displacement maps work. </p> 2708 2709<p>The given arguments define the maximum amount of displacement in pixels 2710that a particular map can produce. If the displacement scale is large enough 2711it is also possible to lookup parts of the 'background' image that lie well 2712outside the bounds of the displacement map itself. That is you could very 2713easily copy a section of the original image from outside the overlay area 2714into the overlay area. </p> 2715 2716<p>The '%' flag makes the displacement scale relative to the size of the 2717overlay image (100% = half width/height of image). Using '!' switches 2718percentage arguments to refer to the destination image size instead. 2719these 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 2722given scaling values will determine a single direction (vector) in which 2723displacements can occur (positively or negatively). However, if you also 2724specify a third image which is normally used as a <var>mask</var>, 2725the <var>composite image</var> is used for horizontal X 2726displacement, while the <var>mask image</var> is used for vertical Y 2727displacement. This allows you to define completely different displacement 2728values for the X and Y directions, and allowing you to lookup any point within 2729the <var>scale</var> bounds. In other words each pixel can lookup 2730any other nearby pixel, producing complex 2 dimensional displacements, rather 2731than a simple 1 dimensional vector displacements. </p> 2732 2733<p>Alternatively rather than supplying two separate images, as of IM v6.4.4-0, 2734you can use the 'red' channel of the overlay image to specify the horizontal 2735or 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 2739mask the transparency of the destination image. However areas outside the 2740overlaid 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 2750X 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 2759modified after the current 'frame' of an animation has finished being 2760displayed (after its 'delay' period), but before the next frame on an 2761animation 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 2773uses 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 2778resetting 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 2781disposal 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 2797it is composited 'over' the main image. If <var>src_percent</var> 2798is greater than 100, start dissolving the main image so it becomes 2799transparent at a value of '<code>200</code>'. If both percentages 2800are 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 2804images, 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 2813of floating point numbers separated by commas or spaces. The number of 2814and 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 3095distort</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 3099defining how these points in the given image should be distorted in the 3100destination image. Each set of four floating point values represent a source 3101image coordinate, followed immediately by the destination image coordinate. 3102This 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 3111destination image. </p> 3112 3113<p>For example, to warp an image using '<code>perspective</code>' distortion, 3114needs a list of at least 4 sets of coordinates, or 16 numbers. Here is the 3115perspective distortion of the built-in "rose:" image. Note how spaces were 3116used to group the 4 sets of coordinate pairs, to make it easier to read and 3117understand.</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 3125a distortion, the distortion method is 'least squares' fitted to produce the 3126best result for all the coordinate pairs given. If less than the ideal number 3127of points are given, the distort will generally fall back to a simpler form of 3128distortion 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 3132find 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 3137resampling <a href="command-line-options.html#filter" >-filter</a>, using a special technique known as 3138EWA resampling. This produces very high quality results, especially when 3139images become smaller (minified) in the output, which is very common when 3140using '<code>perspective</code>' distortion. For example here we view 3141a 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 3149be very slow, because of the number of pixels that are compressed to generate 3150each individual pixel close to the 'horizon'. You can turn off EWA 3151resampling, 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 3156example, <a href="command-line-options.html#distort" >-distort</a> will use the current <a 3157href="command-line-options.html#mattecolor" >-mattecolor</a> setting for these pixels. If you do not 3158what these pixels to be visible, set the color to match the rest of the 3159ground. </p> 3160 3161<p>The output image size will by default be the same as the input image. This 3162means that if the part of the distorted image falls outside the viewed area of 3163the 'distorted space', those parts is clipped and lost. However if you use 3164the plus form of the operator (<a href="command-line-options.html#distort" >+distort</a>) the operator 3165will attempt (if possible) to show the whole of the distorted image, while 3166retaining a correct 'virtual canvas' offset, for image layering. This offset 3167may need to be removed using <a href="command-line-options.html#repage" >+repage</a>, to remove if it 3168is unwanted. </p> 3169 3170<p>Setting <a href="command-line-options.html#verbose" >-verbose</a> setting, will cause <a 3171href="command-line-options.html#distort" >-distort</a> to attempt to output the internal coefficients, 3172and the <a href="command-line-options.html#fx" >-fx</a> equivalent to the distortion, for expert study, 3173and 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 3177specify the size and the offset of the generated 'viewport' image of the 3178distorted image space.</p> 3179 3180<p>Setting a "<code><a href="command-line-options.html#define" >-define</a> 3181distort:scale=<var>scale_factor</var></code>" will scale the output image (viewport or 3182otherwise) by that factor without changing the viewed contents of the 3183distorted image. This can be used either for 'super-sampling' the image for 3184a higher quality result, or for panning and zooming around the image (with 3185appropriate 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>" 3188will output the cylindrical filter lookup table created by the EWA (Elliptical 3189Weighted Average) resampling algorithm. Note this table uses a squared radius 3190lookup 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 3204images when general color reduction is applied via an option, or automagically 3205when 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 3208eye a closer approximation of the images original color is reproduced. This 3209reduces the number of colors needed to reproduce the image but at the cost of 3210a lower level pattern of colors. Error diffusion dithers can use any set of 3211colors (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 3214setting, <a href="command-line-options.html#dither">+dither</a>. This will also also render PostScript 3215without text or graphic aliasing. Disabling dithering often (but not always) 3216leads to faster process, a smaller number of colors, but more cartoon like 3217image coloring. Generally resulting in 'color banding' effects in areas with 3218color gradients. </p> 3219 3220<p>The color reduction operators <a href="command-line-options.html#colors">-colors</a>, <a 3221href="command-line-options.html#monochrome">-monochrome</a>, <a href="command-line-options.html#remap ">-remap</a>, and <a 3222href="command-line-options.html#posterize">-posterize</a>, apply dithering to images using the reduced 3223color set they created. These operators are also used as part of automatic 3224color reduction when saving images to formats with limited color support, such 3225as <code>GIF:</code>, <code>XBM:</code>, and others, so dithering may also be used 3226in these cases. </p> 3227 3228<p>Alternatively you can use <a href="command-line-options.html#random-threshold">-random-threshold</a> 3229to generate purely random dither. Or use <a 3230href="command-line-options.html#ordered-dither">-ordered-dither</a> to apply threshold mapped dither 3231patterns, 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 3242primitives. The primitives include shapes, text, transformations, and pixel 3243operations.</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 3274interact with the other primitives. It is equivalent to using the <a 3275href="command-line-options.html#gravity">-gravity</a> command-line option, except that it is limited in 3276scope 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 3296href="command-line-options.html#fill">-fill</a> setting. For unfilled shapes, use <a 3297href="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 3299href="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 3302pixel 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> 3304primitive is not affected by <a href="command-line-options.html#stroke">-stroke</a> or <a 3305href="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 3310upper left and lower right corners.</p> 3311 3312<p>A <code>roundRectangle</code> primitive takes the same corner points as 3313a <code>rectangle</code> followed by the width and height of the rounded corners 3314to be removed.</p> 3315 3316<p>The <code>circle</code> primitive makes a disk (filled) or circle (unfilled). 3317Give 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 3320to 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 3322arc of the segment segment (e.g. 130,30 200,100 45,90). The start and end 3323points produced are then joined with a line segment and the resulting segment 3324of an ellipse is filled.</p> 3325 3326<p>Use <code>ellipse</code> to draw a partial (or whole) ellipse. Give the 3327center point, the horizontal and vertical "radii" (the <var>semi-axes</var> of 3328the ellipse) and start and end angles in degrees (e.g. 100,100 100,150 33290,360).</p> 3330 3331<p>The <code>polyline</code> and <code>polygon</code> primitives require three or 3332more points to define their perimeters. A <code>polyline</code> is simply 3333a <code>polygon</code> in which the final point is not stroked to the start 3334point. When unfilled, this is a <var>polygonal line</var>. If the <a 3335href="command-line-options.html#stroke">-stroke</a> setting is <code>none</code> (the default), then 3336a <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 3339optional comma. </p> 3340 3341<p>As an example, to define a circle centered at 100,100 that extends to 3342150,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 3348or 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 3350intermediate coordinates are <var>control points</var>. If two control points 3351are specified, the line between each end knot and its sequentially respective 3352control point determines the tangent direction of the curve at that end. If 3353one control point is specified, the lines from the end knots to the one 3354control point determines the tangent directions of the curve at each end. If 3355more than two control points are specified, then the additional control points 3356act in combination to determine the intermediate shape of the curve. In order 3357to 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 3359the 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 3366moveto (set a new current point), lineto (draw a straight line), curveto (draw 3367a Bezier curve), arc (elliptical or circular arc) and closepath (close the 3368current 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 3370one or more line or curve operations) are possible to allow effects such as 3371<var>donut holes</var> in objects. (See <a 3372href="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 3375image keyword with the composite operator, image location, image size, and 3376filename:</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 3382dimensions found in the image header. Otherwise, it is scaled to the given 3383dimensions. See <a href="../www/compose.html">Alpha Compositing</a> for 3384a detailed discussion of alpha composition methods that are available. </p> 3385 3386<p>The "special augmented compose operators" such as "dissolve" that require 3387arguments 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 3391coordinates with a string. If the string has embedded spaces, enclose it in 3392single or double quotes.</p> 3393 3394<p>For example, the following annotates the image with <code>Works like 3395magick!</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 3401to annotate an image with text.</p> 3402 3403<p>The <code>rotate</code> primitive rotates subsequent shape primitives and 3404text primitives about the origin of the main image.</p> 3405 3406<p>The <code>translate</code> primitive translates subsequent shape and text 3407primitives.</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 3412to the origin of the main image or the region.</p> 3413 3414<p>The transformations modify the current affine matrix, which is initialized 3415from the initial affine matrix defined by the <a href="command-line-options.html#affine">-affine</a> 3416option. Transformations are cumulative within the <a href="command-line-options.html#draw">-draw</a> 3417option. The initial affine matrix is not affected; that matrix is only changed 3418by 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 3420reinitialized from the initial affine matrix.</p> 3421 3422<p>Use the <code>color</code> primitive to change the color of a pixel to the 3423fill color (see <a href="command-line-options.html#fill">-fill</a>). Follow the pixel coordinate with 3424a method:</p> 3425 3426<pre class="highlight"><code>point 3427replace 3428floodfill 3429filltoborder 3430reset 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> 3435method 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 3437pixel and is a neighbor, whereas <code>filltoborder</code> recolors any neighbor 3438pixel that is not the border color. Finally, <code>reset</code> recolors all 3439pixels.</p> 3440 3441<p>Use <code>matte</code> to the change the pixel matte value to transparent. 3442Follow the pixel coordinate with a method (see the <code>color</code> primitive 3443for a description of methods). The <code>point</code> method changes the matte 3444value of the target pixel. The <code>replace</code> method changes the matte 3445value 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 3447color of the target pixel and is a neighbor, whereas <code>filltoborder</code> 3448changes the matte value of any neighbor pixel that is not the border color (<a 3449href="command-line-options.html#bordercolor">-bordercolor</a>). Finally <code>reset</code> changes the 3450matte value of all pixels.</p> 3451 3452<p>You can set the primitive color, font, and font bounding box color with <a 3453href="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> 3454respectively. Options are processed in command line order so be sure to use 3455these 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 3458than 1.png).</p> 3459 3460<p>Drawing primitives conform to the <a href="magick-vector-graphics.html" >Magick 3461Vector 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. 3471The first image is index 0. Negative indexes are relative to the end of the 3472sequence, for example, -1 represents the last image of the sequence. Specify 3473a range of images with a dash (e.g. 0-4). Separate indexes with a comma (e.g. 34740,2). Use <code>+duplicate</code> to duplicate the last image in the current 3475image 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 3498href="../www/cipher.html">ImageMagick: Encipher or 3499Decipher 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 3512AdobeStandard AppleRoman 3513BIG5 GB2312 3514Latin 2 None 3515SJIScode Symbol 3516Unicode 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 3544image into some other color space, such as HSL, OHTA, YIQ or YUV, then 3545equalize 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 3551components transformation that puts most of the information in the first 3552channel. 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 3562multi-parameter functions. See the <a href="command-line-options.html#fx" >-fx</a> operator if more 3563elaborate calculations are needed.)</p> 3564 3565<p>The behaviors of each <var>operator</var> are summarized in the 3566following list. For brevity, the numerical value of a "pixel" referred to 3567below is the value of the corresponding channel of that pixel, while 3568a "normalized pixel" is that number divided by the maximum 3569(installation-dependent) value <var>QuantumRange</var>. (If 3570normalized pixels are used, they are restored, following the other 3571calculations, 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 3627href="command-line-options.html#channel" >-channel</a> in the image. If necessary, the results of the 3628calculations are truncated (clipped) to fit in the interval [0, <var>QuantumRange</var>]. The transparency channel of the image is 3629represented 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 3631semi-transparent. Append the percent symbol '<code>%</code>' to specify a value 3632as 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 3639href="command-line-options.html#level" >-level</a> or the <a href="command-line-options.html#level" >+level</a> operator, with 3640appropriate argument, to linearly modify the overall range of color values. 3641Please 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 3646addition modulo the <var>QuantumRange</var>. It is therefore 3647equivalent to <code>Add</code> unless the resulting pixel value is outside the 3648interval [0, <var>QuantumRange</var>]. </p> 3649 3650<p><code>Exp or Exponential</code> has been added as of ImageMagick 6.6.5-1 and 3651works on normalized pixel values. The <var>value</var> used with 3652<code>Exp</code> should be negative so as to produce a decaying exponential 3653function. Non-negative values will always produce results larger unity and 3654thus outside the interval [0, <var>QuantumRange</var>]. The 3655formula is expressed below. </p> 3656 3657<p class="text-center"> 3658exp(<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 3663the result.</p> 3664 3665<p><code>Log</code> has been added as of ImageMagick 6.4.2-1 and works on 3666normalized pixel values. This a <var>scaled</var> log function. The <var>value</var> used with <code>Log</code> provides a <var>scaling 3667factor</var> that adjusts the curvature in the graph of the log function. The 3668formula applied to a normalized value <b><var>u</var></b> is below. </p> 3669 3670<p class="text-center"> 3671log(<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 3675normalized pixel values. Note that <code>Pow</code> is related to the <a 3676href="command-line-options.html#gamma" >-gamma</a> operator. For example, <b>-gamma 2</b> is equivalent 3677to <b>-evaluate pow 0.5</b>, i.e., a 'square root' function. The value used 3678with <a href="command-line-options.html#gamma" >-gamma</a> is simply the reciprocal of the value used 3679with <code>Pow</code>.</p> 3680 3681<p><code>Cosine</code> and <code>Sine</code> was added as of IM v6.4.8-8 and 3682converts the image values into a value according to a (co)sine wave function. 3683The synonyms <code>Cos</code> and <code>Sin</code> may also be used. The output 3684is biased 50% and normalized by 50% so as to fit in the respective color value 3685range. The <var>value</var> scaling of the <var>period</var> of the 3686function (its frequency), and thus determines the number of 'waves' that will 3687be 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, 3688then the effective period is the <var>half</var> the <var>QuantumRange</var>.</p> 3689 3690<p class="text-center"> 36910.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 3695multi-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 3704href="command-line-options.html#evaluate-sequence">-evaluate-sequence</a> operators, use <a 3705href="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. 3714To position the image, use offsets in the <var>geometry</var> 3715specification or precede with a <a href="command-line-options.html#gravity">-gravity</a> setting. To 3716specify 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 3720display. If the aspect ratio of the input image isn't exactly 4:3, then the 3721image 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 3736image. 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", 3740convert -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, 3751equivalent 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 3765rendering 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 3770href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a 3771href="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 3780Contrast Entropy 3781Correlation Difference Variance 3782Sum of Squares Variance Difference Entropy 3783Inverse Difference Moment Information Measure of Correlation 1 3784Sum Average Information Measure of Correlation 2 3785Sum 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 3795users 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 3797represented as a superposition of complex sinusoidal waves of varying 3798amplitudes. The image x and y coordinates are the possible frequencies along 3799the x and y directions, respectively, and the pixel intensity values are 3800complex numbers that correspond to the sinusoidal wave amplitudes. See for 3801example, <a href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier 3802Transform</a>, <a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier 3803Transform</a> and <a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier 3804Transform</a>.</p> 3805 3806<p>A single image name is provided as output for this option. However, the 3807output result will have two components. It is either a two-frame image or two 3808separate images, depending upon whether the image format specified supports 3809multi-frame images. The reason that we get a dual output result is because the 3810frequency domain represents an image using complex numbers, which cannot be 3811visualized directly. Therefore, the complex values are automagically separated 3812into a two-component image representation. The first component is the 3813magnitude of the complex number and the second is the phase of the complex 3814number. See for example, <a 3815href="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 3818formats that do not limit the color or compress the image. Thus, MIFF, TIF, 3819PFM, EXR and PNG are the recommended image formats to use. All of these 3820formats, 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 3826image 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 3832as <code>fft_image-1.png</code>. If you prefer this representation, then you can 3833force any of the other formats to produce two output images by including <a 3834href="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 3837is padded automagically to the larger of the width or height of the input 3838image and to an even number of pixels. The padding will occur at the bottom 3839and/or right sides of the input image. The resulting output magnitude and 3840phase images is square at this size. The kind of padding relies on the <a 3841href="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. 3845Phase values nominally range from 0 to 2*π, but is scaled to span the full 3846dynamic range. (The first few releases had non-HDRI scaled but HDRI not 3847scaled). The magnitude image is not scaled and thus generally will contain 3848very small values. As such, the image normally will appear totally black. In 3849order to view any detail, the magnitude image typically is enhanced with a log 3850function into what is usually called the spectrum. A log function is used to 3851enhance the darker values more in comparison to the lighter values. This can 3852be 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 3859href="command-line-options.html#auto-level">-auto-level</a> is used to scale the image to full dynamic 3860range, first. The argument to the <a href="command-line-options.html#evaluate">-evaluate</a> log 3861typically is specified between 100 and 10,000, depending upon the amount of 3862detail that one wants to bring out in the spectrum. Larger values produce more 3863visible 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 3866use <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 3869and imaginary components of the complex valued Fourier transform.</p> 3870 3871<p>However, as the real and imaginary components can contain negative values, 3872this requires that IM be configured with HDRI enabled. In this case, you must 3873use either MIFF, TIF, PFM or MPC formats for the real and imaginary component 3874results, since they are formats that preserve both negative and fractional 3875values without clipping them or truncating the fractional part. With either 3876MIFF or TIF, one should add <code>-define quantum:format=32</code>, to allow those image 3877types to work properly in HDRI mode without clipping.</p> 3878 3879<p>The real and imaginary component images resulting from <a 3880href="command-line-options.html#fft">+fft</a> are also square, even dimensioned images due to the same 3881padding that was discussed above for the magnitude and phase component 3882images.</p> 3883 3884<p>See the discussion on HDRI implementations of ImageMagick on the page <a 3885href="high-dynamic-range.html" >High Dynamic-Range Images</a>. For more 3886about HDRI go the ImageMagick <a 3887href="../Usage/basics/#hdri" >Usage</a> pages, <a 3888href="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, 3903HSL, HSLA, CMYK, or CMYKA specification. See <a href="../www/color.html" >Color Names</a> for 3904a description of how to properly specify the color argument.</p> 3905 3906<p>Enclose the color specification in quotation marks to prevent the "#" or 3907the 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 3927operations 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 3931Box Gaussian Catrom 3932Triangle Quadratic Mitchell 3933CubicSpline 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 3939as a faster <code>SincFast</code> equivalent form). However these filters are 3940generally useless on their own as they are infinite filters that are being 3941clipped to the filters support size. Their direct use is not recommended 3942except via expert settings (see below). </p> 3943 3944<p>Instead these special filter functions are typically windowed by a windowing 3945function that the <a href="command-line-options.html#filter" >-filter</a> setting defines. That is 3946using these functions will define a 'Windowed' filter, appropriate to the 3947operator involved. Windowed filters include: </p> 3948 3949<pre class="highlight"><code>Lanczos Hamming Parzen 3950Blackman Kaiser Welsh 3951Hanning 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 3956on 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 3960if 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 3964filter</a> option.</p> 3965 3966<p>You can modify how the filter behaves as it scales your image through the 3967use of these expert settings (see also <a href="command-line-options.html#define" >-define</a> and <a 3968href="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 4101a '<code>Box</code>' filter. For example the '<code>Welch</code> parabolic 4102windowing 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 4109gnuplot 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 4115who have studied and understand how resize filters work. Without this 4116knowledge, and an understanding of the definition of the actual filters 4117involved, using expert settings are more likely to be detrimental to your image 4118resizing.</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 4135upside-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. 4145Any color that matches within <a href="command-line-options.html#fuzz" >-fuzz</a> color distance of the 4146given <var>color</var> argument, connected to that 'seed point' 4147will 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 4151action will be taken. </p> 4152 4153<p>This operator works more like the <a href="command-line-options.html#opaque" >-opaque</a> option, than 4154a more general flood fill that reads the matching color directly at the 'seed 4155point'. For this form of flood fill, look at <a href="command-line-options.html#draw" >-draw</a> and 4156its '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 4166a 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> 4176option (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 4179also specify a font from a specific source. For example <code>Arial.ttf</code> 4180is 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 4184href="command-line-options.html#family">-family</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a 4185href="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 4195href="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 4206image to the image <a href="formats.html">format</a> you specify. 4207For a list of image format types supported by ImageMagick, use <a 4208href="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 4211filename extension matches a supported format, the extension is replaced with 4212the image format type specified with <a href="command-line-options.html#format">-format</a>. For 4213example, if you specify <var>tiff</var> as the format type and the 4214input image filename is <var>image.gif</var>, the output image 4215filename 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 4224Properties</a> for an explanation on how to specify the argument to this 4225option.</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 4237height that is added to the dimensions of the image. If no offsets are given 4238in the <var>geometry</var> argument, then the border added is 4239a solid color. Offsets <var>x</var> and <var>y</var>, if present, specify that 4240the width and height of the border is partitioned to form an outer bevel of 4241thickness <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 4246href="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 4248size with the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting, and then 4249draws the frame of four distinct colors close to the current <a 4250href="command-line-options.html#mattecolor">-mattecolor</a>. The original image is then overlaid onto 4251center 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 4253href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p> 4254 4255<p>The image composition is not 4256affected 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 4271each of the color values for each previously set <a 4272href="command-line-options.html#channel">-channel</a> in the image. See <a 4273href="command-line-options.html#evaluate">-evaluate</a> for details concerning how the results of the 4274calculations are handled.</p> 4275 4276<p>This is can be considered a multi-argument version of the <a 4277href="command-line-options.html#evaluate">-evaluate</a> operator. (Added in 4278ImageMagick 6.4.8−8.)</p> 4279 4280<p>Here, <var>parameters</var> is a comma-separated list of 4281numerical 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 4284Sinusoid 4285Arcsin 4286Arctan 4287</code></pre> 4288 4289<p>To print a complete list of <a href="command-line-options.html#function">-function</a> operators, 4290use <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, 4295these being the coefficients of a polynomial, in decreasing order of degree. 4296That 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> 4311polynomials) of the <a href="command-line-options.html#evaluate">-evaluate</a> operator. The <a 4312href="command-line-options.html#level">-level</a> operator also affects channels linearly. Some 4313correspondences 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 4341polynomials can be used to fit any continuous curve to any degree of accuracy 4342desired.</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 4348sinusoidally by setting frequency, phase shift, amplitude, and a bias. These 4349values 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 4355corresponds to 0 through <var>freq</var>×360 degrees.) 4356The 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> 4370is 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 4374varying 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, 4390and can be used to generate cylindrical distortion and displacement maps. 4391The curve can be adjusted relative to both the input values and output range 4392of 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, 43981.0 for white). Defaulting to values covering the full range from 0.0 to 1.0 4399for 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 4408limit values at infinities, though a center using the given slope value. 4409All 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 4431be exact. Use this option to match colors that are close to the target color 4432in RGB space. For example, if you want to automagically trim the edges of an 4433image with <a href="command-line-options.html#trim">-trim</a> but the image was scanned and the target 4434background color may differ by a small amount. This option can account for 4435these differences.</p> 4436 4437<p>The <var>distance</var> can be in absolute intensity units or, by 4438appending <code>%</code> as a percentage of the maximum possible intensity (255, 443965535, 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>, 4451the expression is read from a file titled by the remaining characters in the 4452string.</p> 4453 4454<p>See <a href="../www/fx.html">FX, 4455The Special Effects Image Operator</a> for a detailed discussion of this 4456option.</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 4466different due to differences in the display monitor. Use gamma correction to 4467adjust 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 4469gamma greater than 1.0 lightens it. Large adjustments to image gamma may 4470result in the loss of some image information if the pixel quantum size is only 4471eight bits (quantum range 0 to 255).</p> 4472 4473<p>Gamma adjusts the image's channel values pixel-by-pixel according to 4474a power law, namely, pow(pixel,1/gamma) or pixel^(1/gamma), where pixel is the 4475normalized or 0 to 1 color value. For example, using a value of gamma=2 is the 4476same 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 4479image gamma level without actually adjusting the image pixels. This option 4480is 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 4482display gamma; e.g., if your image is sRGB and you want to write a PNG gAMA 4483chunk, 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 4504determines 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 4507array which will hold the calculated Gaussian distribution. It should be an 4508integer. If not given, or set to zero, IM will calculate the largest possible 4509radius 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 4513operation is. However too small a <var >Radius</var>, and severe 4514aliasing effects may result. As a guideline, <var >Radius</var> 4515should be at least twice the <var >Sigma</var> value, though three 4516times 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 4519full 2-dimensional convolution is used to generate the weighted average of the 4520neighboring pixels. </p> 4521 4522<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 4523pixels 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 4544href="command-line-options.html#list">-list gravity</a> to get a complete list of <a 4545href="command-line-options.html#gravity">-gravity</a> settings available in your ImageMagick 4546installation.</p> 4547 4548<p>The direction you choose specifies where to position text or subimages. For 4549example, a gravity of <code>Center</code> forces the text to be centered within 4550the image. By default, the image gravity is <code>undefined</code>. See <a 4551href="command-line-options.html#draw">-draw</a> for more details about graphic primitives. Only the 4552text primitive of <a href="command-line-options.html#draw">-draw</a> is affected by the <a 4553href="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 4557take <var>geometry</var> as an argument, such as the <a 4558href="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 4561or setting having a <var>geometry</var> argument that specifies an 4562offset, the offset is usually applied to the point within the image suggested 4563by the <a href="command-line-options.html#gravity">-gravity</a> argument. Thus, in the following 4564command, for example, suppose the file <code>image.png</code> has dimensions 4565200x100. The offset specified by the argument to <a href="command-line-options.html#region">-region</a> 4566is (−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(100−40,50+20)=(60,70), so the specified 10x10 region is located at 4570that point. (In addition, the <a href="command-line-options.html#gravity">-gravity</a> affects the 4571region itself, which is <var>centered</var> at the pixel 4572coordinate (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 4579href="command-line-options.html#gravity">-gravity</a> gives the direction that the image gravitates 4580within the composite.</p> 4581 4582<p>When used as an option to <a href="montage.html">montage</a>, <a 4583href="command-line-options.html#gravity">-gravity</a> gives the direction that an image gravitates 4584within 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 4596convert 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> 4607or 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 4624regardless of the current colorpsace of the image. But a 'mathematical' 4625intensity method depends on the current colorspace the image is currently 4626using. </p> 4627 4628<p>While this operation uses an <a href="command-line-options.html#intensity" >-intensity</a> method, 4629it does not use or set the <a href="command-line-options.html#intensity" >-intensity</a> setting, so 4630will 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 4647dimensions. Create it with the <code>HALD:</code> prefix (e.g. HALD:8). You 4648can apply any color transformation to the Hald image and then use this option 4649to 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 4655to make color corrections to the Hald CLUT image and subsequently apply them 4656to multiple images using an ImageMagick script. </p> 4657 4658<p>Note that the representation is only of the normal RGB color space and that 4659the whole color value triplet is used for the interpolated lookup of the 4660represented Hald color cube image. Because of this the operation is not <a 4661href="command-line-options.html#channel" >-channel</a> setting affected, nor can it adjust or modify an 4662images 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 4665of the individual color channels, usually involving a simpler grayscale 4666image. E.g: grayscale to color replacement, or modification by a histogram 4667mapping. </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 4711manner as the <a href="command-line-options.html#geometry">-geometry</a> option, using X11 style to 4712handle 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; 4729the image class (<var>DirectClass</var> or <var>PseudoClass</var>); the total number of unique colors; and the 4730number of seconds to read and transform the image. Refer to <a href="miff.html">MIFF</a> for 4731a 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 4734in the image and color reduction error values are printed. Refer to <a 4735href="../www/quantize.html">color 4736reduction 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 4739amounts of image properties are displayed including image statistics, profiles, 4740image 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 4749users in ImageMagick 6.6.0-9). It transforms a pair of magnitude and phase 4750images from the frequency domain to a single image in the normal or spatial 4751domain. See for example, <a 4752href="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 4757the <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 4768the original image, prior to the <a href="command-line-options.html#fft">-fft</a> or <a 4769href="command-line-options.html#fft">+fft</a>, was not square or even dimensioned. Any padding is at 4770the 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 4773use <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 4776and 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 4800at the given index. If a negative index is used, the insert position is 4801calculated 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 4805other words, insert the last image, at the end of the current image sequence. 4806Consequently 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 4815operator needs to determine a single grayscale value for some purpose, from 4816an 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 4820the pixel values to linear-RGB or non-linear sRGB colorspace before 4821being 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 4833R',G',B' are sRGB non-linear values. </p> 4834 4835<p>These intensity methods are mathematical in nature and will use the 4836current value in the images respective R,G,B channel regardless of 4837what 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 4846grayscale 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 4850error comparisions. While... The method 'RMS' (Root Mean Squared) for 4851example is appropriate for calculating color vector distance, from a color 4852difference image. This is equivalent to the color only component of the <a 4853href="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 4856grayscaling formula directly to an image without setting the <a 4857href="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 4860the current intensity setting, but will always convert the image to the 4861appropriate sRGB or linear-RGB colorspace before appling the above 4862function.</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, 4894Perceptual, 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 4909line 4910plane 4911partition 4912JPEG 4913GIF 4914PNG 4915</code></pre> 4916 4917<p>This option is used to specify the type of interlacing scheme for raw image 4918formats 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 4927individual 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 4930PNG</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 4933interlace</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 4942value, you typically fall in between the pixel colors defined by the source 4943image. This setting determines how the color is determined from the colors of 4944the pixels surrounding that point. That is how to determine the color of a 4945point 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 4981lookup 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 5018or created. You can use the <a href="command-line-options.html#set" >-set</a> operation to re-assign 5019a the labels of images already read in. Image formats such as TIFF, PNG, 5020MIFF, supports saving the label information with the image.</p> 5021 5022<p>When saving an image to a <var>PostScript</var> file, any label 5023assigned to an image is used as a header string to print above the postscript 5024image. </p> 5025 5026<p>You can include the image filename, type, width, height, or other image 5027attribute by embedding special format character. See <a href="../www/escape.html">Format and Print Image 5028Properties</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 5037is read in. If a <a href="command-line-options.html#label">+label</a> option was used instead, any 5038existing label present in the image would be used. You can remove all labels 5039from 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 5042via <var>Label</var> tag or similar mechanism. If you want the label to be 5043visible on the image itself, use the <a href="command-line-options.html#draw">-draw</a> option, or 5044during 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 5047remaining characters in the string. Labels in a file are literal, no embedded 5048formatting 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 5058surrounding window. If the current pixel is lighter than this average plus 5059the optional <code>offset</code>, then it is made white, otherwise it is made 5060black. Small variations in pixel values such as found in scanned documents 5061can be ignored if offset is positive. A negative offset will make it more 5062sensitive to those small variations. </p> 5063 5064<p>This is commonly used to threshold images with an uneven background. It is 5065based on the assumption that average color of the small window is the 5066the 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 5076which may represent either a set of overlaid 'image layers', a GIF disposal 5077animation, 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 5335the 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 5337GIF <a href="command-line-options.html#dispose" >-dispose</a> and <a href="command-line-options.html#delay" >-delay</a> 5338settings. </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, 5348white-point, gamma (for example: 10,250,1.0 or 2%,98%,0.5). The black and 5349white points range from 0 to <var>QuantumRange</var>, or from 0 to 5350100%; if the white point is omitted it is set to (<var>QuantumRange</var> - black_point), so as to center contrast changes. 5351If a <code>%</code> sign is present anywhere in the string, both black and white 5352points are percentages of the full color range. Gamma will do a <a 5353href="command-line-options.html#gamma">-gamma</a> adjustment of the values. If it is omitted, the 5354default 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 5357the 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 5359contrast adjustments to the image. The '<code>gamma</code>' of the resulting 5360image 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 5364list, will cause the operator to do the reverse of the level adjustment. That 5365is a zero, or <var>QuantumRange</var> value (black, and white, resp.) 5366in the original image, is adjusted to the given level values, allowing you to 5367de-contrast, or compress the channel values within the image. The 5368'<code>gamma</code>' is adjusted before the level adjustment to de-contrast the 5369image is made. </p> 5370 5371<p>Only the channels defined by the current <a href="command-line-options.html#channel">-channel</a> 5372setting are adjusted (defaults to RGB color channels only), allowing you to 5373limit the effect of this operator. </p> 5374 5375<p>Please note that the transparency channel is treated as 'matte' 5376values (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 5386value value for each color channel is determined by the 5387'<code>black_color</code>' and '<code>white_color</code>' colors given (as 5388described 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> 5391is mapped to become 'black' and 'white' respectively, with all the other 5392colors linearly adjusted (or clipped) to match that change. Each channel is 5393adjusted 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>) 5396will map the image color 'black' and 'white' to the given colors 5397respectively, resulting in a gradient (de-contrasting) tint of the image to 5398those colors. This can also be used to convert a plain grayscale image into a 5399one using the gradient of colors specified. </p> 5400 5401<p>By supplying a single color with a comma separator either before or after 5402that color, will just replace the respective 'black' or 'white' point 5403respectively. But if no comma separator is provided, the given color is 5404used for both the black and white color points, making the operator either 5405threshold the images around that color (- form) or set all colors to that 5406color (+ 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 5418in bytes. Define arguments for the memory, map, area, and disk resource limits 5419with SI prefixes (.e.g 100MB).</p> 5420 5421<p>By default the limits are 768 files, 3GB of image area, 1.5GiB memory, 3GiB 5422memory map, and 18.45EB of disk. These limits are adjusted relative to the 5423available resources on your computer if this information is available. When 5424any limit is reached, ImageMagick fails in some fashion but attempts to take 5425compensating actions, if possible. For example, the following limits 5426memory:</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 5434Resource 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 5448of three resource categories: in-memory pool, memory-mapped files pool, and 5449disk pool (in that order) depending on the <a href="command-line-options.html#limit">‑limit</a> settings 5450and whether the system honors a resource request. If the total size of 5451allocated pixel storage in the given pool reaches the corresponding limit, the 5452request 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 5456image resource request. First, ImageMagick tries to allocate the pixels in 5457memory. 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 5459a memory request is not honored, the pixels are allocated to disk and the file 5460is memory-mapped. However, if the allocation request exceeds the 5461<code>map</code> limit, the resource allocation goes to disk. In all cases, if 5462the resource request exceeds the <code>area</code> limit, the pixels are 5463automagically cached to disk. If the disk has a hard limit, the program 5464fails.</p> 5465 5466<p>In most cases you simply do not need to concern yourself with resource 5467limits. ImageMagick chooses reasonable defaults and most images do not tax 5468your computer resources. Where limits do come in handy is when you process 5469images that are large or on shared systems where ImageMagick can consume all 5470or most of the available memory. In this case, the ImageMagick workflow slows 5471other processes or, in extreme cases, brings the system to a halt. Under 5472these circumstances, setting limits give some assurances that the ImageMagick 5473workflow will not interfere with other concurrent uses of the computer. For 5474example, assume you have a web interface that processes images uploaded from 5475the Internet. To assure ImageMagick does not exceed 10MiB of memory you can 5476simply 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 5482cached to disk instead of memory. This of course implies that large images 5483typically process very slowly, simply because pixel processing in memory can 5484be an order of magnitude faster than on disk. Because your web site users 5485might inadvertently upload a huge image to process, you should set a disk 5486limit 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 5494with <a href="resources.html#environment" >environment variables</a>. Set the 5495environment 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 5499image area, disk space, open files, heap memory, memory map, number of threads 5500of 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 5503their commands and then scouring the generated output for references to the 5504pixel cache, in order to determine how the pixel cache was allocated and how 5505resources were consumed. Advanced Unix/Linux users can pipe that output 5506through <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 5510Storage 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>, 5520and uses a 'histogram bin' to determine the range of color values that needs to 5521be stretched. However it then stretches those colors using the <a 5522href="command-line-options.html#level" >-level</a> operator.</p> 5523 5524<p>As such while the initial determination may have 'binning' round off 5525effects, the image colors are stretched mathematically, rather than using the 5526histogram 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 5530perfect 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' 5533normalization 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> 5559Align 5560Alpha 5561Boolean 5562Cache 5563Channel 5564Class 5565ClipPath 5566Coder 5567Color 5568Colorspace 5569Command 5570Complex 5571Compose 5572Compress 5573Configure 5574DataType 5575Debug 5576Decoration 5577Delegate 5578Direction 5579Dispose 5580Distort 5581Dither 5582Endian 5583Evaluate 5584FillRule 5585Filter 5586Font 5587Format 5588Function 5589Gravity 5590Intensity 5591Intent 5592Interlace 5593Interpolate 5594Kernel 5595Layers 5596LineCap 5597LineJoin 5598List 5599Locale 5600LogEvent 5601Log 5602Magic 5603Method 5604Metric 5605Mime 5606Mode 5607Morphology 5608Module 5609Noise 5610Orientation 5611PixelIntensity 5612Policy 5613PolicyDomain 5614PolicyRights 5615Preview 5616Primitive 5617QuantumFormat 5618Resource 5619SparseColor 5620Statistic 5621Storage 5622Stretch 5623Style 5624Threshold 5625Type 5626Units 5627Validate 5628VirtualPixel 5629</code></pre> 5630 5631<p>These lists vary depending on your version of ImageMagick. Use "<code>-list 5632list</code>" to get a complete listing of all the "<code>-list</code>" arguments 5633available:</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 5645href="command-line-options.html#debug">-debug</a> option is active.</p> 5646 5647<p>You can display the following components by embedding special format 5648characters:</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, 5679otherwise the animation repeats itself up to <var>iterations</var> 5680times.</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 5704default 5705gray 5706red 5707green 5708blue 5709</code></pre> 5710 5711<p>The <var>X server</var> must support the <var>Standard 5712Colormap</var> you choose, otherwise an error occurs. Use <code>list</code> as 5713the 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. 5740bgr). 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 5752style="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 5763name. </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 5774name. </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, 5810with the <a href="command-line-options.html#fuzz" >-fuzz</a> factor (ignore pixels which 5811only changed by a small amount). Use '<code>PAE</code>' to find the 5812size 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 5814for 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>' 5818normalized) 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 5825metric</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 5837name. </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, 5854Unframe, 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 5857for a list of <a href="command-line-options.html#mode" >-mode</a> arguments available in your 5858ImageMagick 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 5868no change, and any missing values are taken to mean 100.</p> 5869 5870<p>The <var>brightness</var> is a multiplier of the overall 5871brightness of the image, so 0 means pure black, 50 is half as bright, 200 is 5872twice as bright. To invert its meaning <a href="command-line-options.html#negate">-negate</a> the image 5873before and after. </p> 5874 5875<p>The <var>saturation</var> controls the amount of color in an 5876image. For example, 0 produce a grayscale image, while a large value such as 5877200 produce a very colorful, 'cartoonish' color.</p> 5878 5879<p>The <var>hue</var> argument causes a "rotation" of the colors 5880within the image by the amount specified. For example, 50 results in 5881a counter-clockwise rotation of 90, mapping red shades to purple, and so on. 5882A value of either 0 or 200 results in a complete 180 degree rotation of the 5883image. Using a value of 300 is a 360 degree rotation resulting in no change to 5884the original image. </p> 5885 5886<p>For example, to increase the color brightness by 20% and decrease the color 5887saturation by 10% and leave the hue unchanged, use <a 5888href="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 5892modulate. 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 5924appearance of a metamorphosis from one image to the next, over all the images 5925in the current image list. The added images are the equivalent of a <a 5926href="command-line-options.html#blend">-blend</a> composition. The <var>frames</var> 5927argument 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 5938href="../Usage/morphology/" >IM Usage Examples, 5939Morphology</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 5956angle given is the angle toward which the image is blurred. That is the 5957direction people would consider the object is coming from. </p> 5958 5959<p>Note that the blur is not uniform distribution, giving the motion a 5960definite 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 5963pixels 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 5978black, yellow becomes blue, etc. Use <a href="command-line-options.html#negate">+negate</a> to only 5979negate 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 5989objects within an image without losing edge information and without creating 5990undesired structures. The central idea of the algorithm is to replace a pixel 5991with its next neighbor in value within a pixel window, if this pixel has been 5992found to be noise. A pixel is defined as noise if and only if this pixel is 5993a 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 5996specify the width of the neighborhood when reducing noise. This is equivalent 5997to using a <code><a href="command-line-options.html#statistic" >-statistic</a> NonPeak</code> operation, 5998which 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 6001types:</p> 6002 6003<pre class="highlight"><code>Gaussian 6004Impulse 6005Laplacian 6006Multiplicative 6007Poisson 6008Random 6009Uniform 6010</code></pre> 6011 6012<p>The amount of noise added can be controlled by the <code><a 6013href="command-line-options.html#attenuate" >-attenuate</a></code> setting. If unset the value is 6014equivalent 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 6021the use of a controlling value to specify the amount of noise that should be 6022added 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 6032values. While doing so, black-out at most <var>2%</var> of the pixels and 6033white-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> 6036is 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 6041preserve color integrity, when the default <a href="command-line-options.html#channel" >+channel</a> 6042setting is in use. Specifying any other <a href="command-line-options.html#channel" >-channel</a> 6043setting 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. 6046Also see <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' normalization 6047that 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 6059described 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 6061given.</p> 6062 6063<p>Use <a href="command-line-options.html#opaque">+opaque</a> to paint any pixel that does not match 6064the target color. </p> 6065 6066<p>The <a href="command-line-options.html#transparent">-transparent</a> operator is exactly the same 6067as <a href="command-line-options.html#opaque" >-opaque</a> but replaces the matching color with 6068transparency rather than the current <a href="command-line-options.html#fill">-fill</a> color setting. 6069To ensure that it can do this it also ensures that the image has an alpha 6070channel enabled, as per "<code><a href="command-line-options.html#alpha" >-alpha</a> set</code>", for 6071the new transparent colors, and does not require you to modify the <a 6072href="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 6080given 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> 6085threshold 1x1 Threshold 1x1 (non-dither) 6086checks 2x1 Checkerboard 2x1 (dither) 6087o2x2 2x2 Ordered 2x2 (dispersed) 6088o3x3 3x3 Ordered 3x3 (dispersed) 6089o4x4 4x4 Ordered 4x4 (dispersed) 6090o8x8 8x8 Ordered 8x8 (dispersed) 6091h3x4a 4x1 Halftone 4x4 (angled) 6092h6x6a 6x1 Halftone 6x6 (angled) 6093h8x8a 8x1 Halftone 8x8 (angled) 6094h3x4o Halftone 4x4 (orthogonal) 6095h6x6o Halftone 6x6 (orthogonal) 6096h8x8o Halftone 8x8 (orthogonal) 6097h36x16o Halftone 16x16 (orthogonal) 6098c5x5b c5x5 Circles 5x5 (black) 6099c5x5w Circles 5x5 (white) 6100c6x6b c6x6 Circles 6x6 (black) 6101c6x6w Circles 6x6 (white) 6102c7x7b c7x7 Circles 7x7 (black) 6103c7x7w Circles 7x7 (white) 6104</code></pre> 6105 6106<p> The <code>threshold</code> generated a simple 50% threshold of the image. 6107This could be used with <var >level</var> to do the equivalent of <a 6108href="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 6112pattern. That is a grayscale will become a pattern of solid black, solid 6113white, 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 6117dithering and halftoning your images, in either personal or system 6118<code>thresholds.xml</code> XML file. See <a href="resources.html" >Resources</a> 6119for 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 6125color channels, no attempt is made to offset or rotate the map for different 6126channels is made, to create an offset printing effect. Also as the maps are 6127simple threshold levels, the halftone and circle maps will create incomplete 6128circles along the edges of a colored area. Also all the effects are purely 6129on/off boolean effects, without anti-aliasing to make the circles smooth 6130looking. Large dots can be made to look better with a small amount of blurring 6131after 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 6143bottom-right top-left 6144left-bottom top-right 6145left-top undefined 6146right-bottom 6147</code></pre> 6148 6149<p>To print a complete list of orientations, use the <a href="command-line-options.html#list" >-list 6150orientation</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 6166href="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. 6169The 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 6213format that supports offsets, such as GIF89 and MNG. When used for this 6214purpose the offsets are always measured from the top left corner of the canvas 6215and are not affected by the <a href="command-line-options.html#gravity">-gravity</a> option. To 6216position 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 6217file, a <a href="command-line-options.html#page">-page</a> option appearing ahead of the first image in 6218the sequence with nonzero width and height defines the width and height values 6219that are written in the <code>MHDR</code> chunk. Otherwise, the MNG width and 6220height are computed from the bounding box that contains all images in the 6221sequence. When writing a GIF89 file, only the bounding box method is used to 6222determine its dimensions.</p> 6223 6224<p>For a PostScript page, the image is sized as in <a 6225href="command-line-options.html#geometry">-geometry</a> but positioned relative to the <var>lower 6226left-hand corner</var> of the page by {+-}<code>x</code><var>offset</var>{+-}<code>y</code> <var>offset</var>. Use <a 6227href="command-line-options.html#page">-page 612x792</a>, for example, to center the image within the 6228page. If the image size exceeds the PostScript page, it is reduced to fit the 6229page. 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 6230corner of the page, unless the <a href="command-line-options.html#gravity">-gravity</a> option is 6231present 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 6246neighborhood 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 6325visible 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 6341these previews:</p> 6342 6343<pre class="pre-scrollable"><code> 6344AddNoise 6345Blur 6346Brightness 6347Charcoal 6348Despeckle 6349Dull 6350EdgeDetect 6351Gamma 6352Grayscale 6353Hue 6354Implode 6355JPEG 6356OilPaint 6357Quantize 6358Raise 6359ReduceNoise 6360Roll 6361Rotate 6362Saturation 6363Segment 6364Shade 6365Sharpen 6366Shear 6367Solarize 6368Spiff 6369Spread 6370Swirl 6371Threshold 6372Wave 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 ... 6392argN"</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 6394pass 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 6404ICM (ICC color management), IPTC (newswire information), or a generic profile 6405to the image.</p> 6406 6407<p>Use <a href="command-line-options.html#profile">+profile <var>profile_name</var></a> to 6408remove the indicated profile. ImageMagick uses standard filename globbing, so 6409wildcard expressions may be used to remove more than one profile. Here we 6410remove 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 6414image file. Use <a href="command-line-options.html#strip">-strip</a> to remove all profiles (and 6415comments).</p> 6416 6417<p>To extract a profile, the <a href="command-line-options.html#profile">-profile</a> option is not 6418used. 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 6427original image already has an included profile. Also, keep in mind that <a 6428href="command-line-options.html#profile">-profile</a> is an "operator" (as opposed to a "setting") and 6429therefore a conversion is made each time it is encountered, in order, in the 6430command-line. For instance, in the following example, if the original image is 6431CMYK 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 6437conversion steps can yield unwanted results. CMYK profiles are often very 6438asymmetric 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 6448highest compression) to 100 (best quality but least effective compression). 6449The default is to use the estimated quality of your input image if it can 6450be determined, otherwise 92. When the quality is greater than 90, then the 6451chroma channels are not downsampled. 6452Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to specify the 6453factors for chroma downsampling.</p> 6454 6455<p>For the JPEG-2000 image format, quality is mapped using a non-linear 6456equation to the compression ratio required by the Jasper library. This 6457non-linear equation is intended to loosely approximate the quality provided by 6458the JPEG v1 format. The default quality value 100, a request for non-lossy 6459compression. 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 6462compression level (quality / 10) and filter-type (quality % 10). The default 6463PNG "quality" is 75, which means compression level 7 with adaptive PNG 6464filtering, unless the image has a color map, in which case it means 6465compression level 7 with no PNG filtering.</p> 6466 6467<p>For compression level 0 (quality value less than 10), the Huffman-only 6468strategy is used, which is fastest but not necessarily the worst 6469compression.</p> 6470 6471<p>If filter-type is 4 or less, the specified PNG filter-type is used for 6472all 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 6483than 50 and the image does not have a color map, otherwise no filtering is 6484used.</p> 6485 6486<p>If filter-type is 6, adaptive filtering 6487with <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 6490transformation (intrapixel differencing) and adaptive filtering 6491with <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 6494Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with 6495adaptive PNG filtering.</p> 6496 6497<p>If the filter-type is 9 the zlib Z_RLE compression strategy (or the 6498Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with 6499no PNG filtering.</p> 6500 6501<p>The quality setting has no effect on the appearance or signature of PNG 6502and MNG images, since the compression is always lossless.</p> 6503 6504<p>Not all combinations of compression level, strategy, and PNG filter type 6505can be obtained using the -quality option. For more precise control, 6506you can use the PNG:compression-level=N, PNG:compression-strategy=N, and 6507PNG:compression-filter=N defines, respectively, instead. 6508See <a href="command-line-options.html#define">-define</a>. Values from the defines take precedence 6509over values from the -quality option.</p> 6510 6511<p>For further information, see 6512the <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 6525of colors needed by an image (for later dithering) by operators such as <a 6526href="command-line-options.html#colors" >-colors</a>, Note that color reduction also happens 6527automatically when saving images to color-limited image file formats, such as 6528GIF, 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 6544such actually mis-named. </p> 6545 6546<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how 6547pixels 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 6558a 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 6561href="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 6583grayscale 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, 6589but 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 6604as 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 6613the given colors are dithered over the image as necessary, otherwise the closest 6614color (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 6617images in the current image sequence, all the images will have the same color 6618table. That means that when saved to a file format such as GIF, it will use 6619that color table as a single common or global color table, for all the images, 6620without 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 6623sequence to use a common color map over all the images. This equivalent to 6624appending all the images together (without extra background colors) and color 6625reducing those images using <a href="command-line-options.html#colors">-colors</a> with a 256 color 6626limit, then <a href="command-line-options.html#remap">-remap</a> those colors over the original list of 6627images. 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 6630href="command-line-options.html#remap">+remap</a> should not perform any color reduction or dithering, as 6631no color changes are needed. In that case, its only effect is to force the use 6632of a global color table. This recommended after using either <a 6633href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#ordered-dither">-ordered-dither</a> to 6634reduce 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 6645in 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 6660running simultaneously, use the <a href="command-line-options.html#window"> window</a> option to 6661specify 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. 6670This 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 6679rather than a setting. You can separately set the canvas size or the offset 6680of 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 6685offset to move the image relative to its previous position. This useful for 6686animation sequences. </p> 6687 6688<p>A given a canvas size of zero such as '<code>0x0</code>' forces it to 6689recalculate the canvas size so the image (at its current offset) will appear 6690completely 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 6693canvas 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 6696directly 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 6706at the specified target resolution. For example, if a 300 DPI image renders at 67073 inches by 2 inches on a 300 DPI device, when the image has been resampled to 670872 DPI, it will render at 3 inches by 2 inches on a 72 DPI device. Note that 6709only a small number of image formats (e.g. JPEG, PNG, and TIFF) are capable of 6710storing the image resolution. For formats which do not support an image 6711resolution, the original resolution of the image must be specified via <a 6712href="command-line-options.html#density">-density</a> on the command line prior to specifying the 6713resample resolution.</p> 6714 6715<p>Note that Photoshop stores and obtains image resolution from a proprietary 6716embedded profile. If this profile exists in the image, then Photoshop will 6717continue to treat the image using its former resolution, ignoring the image 6718resolution 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 6727ignored, 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 6730or <code>-define filter:option=value</code> precedes the <a 6731href="command-line-options.html#resize">-resize</a> option, the image is resized with the specified 6732filter.</p> 6733 6734<p>Many image processing algorithms assume your image is in a linear-light 6735coding. If your image is gamma-corrected, you can remove the nonlinear gamma 6736correction, 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. 6762A 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 6772height. <code><</code> rotates the image <var>only</var> if its width is less 6773than the height. For example, if you specify <code>-rotate "-90>"</code> and 6774the image size is 480x640, the image is not rotated. However, if the image is 6775640x480, 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 6777misinterpreted as a file redirection.</p> 6778 6779<p>Empty triangles in the corners, left over from rotating the image, are 6780filled 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 6793from the image. When magnifying, pixels are replicated in blocks. When 6794minifying, pixels are sub-sampled (i.e., some rows and columns are skipped 6795over). </p> 6796 6797<p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with 6798a <a href="command-line-options.html#filter">-filter</a> setting of <code>point</code> (nearest 6799neighbor), though <a href="command-line-options.html#sample">-sample</a> is a lot faster, as it 6800avoids all the filter processing of the image. As such it completely ignores 6801the 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 6804will 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 6807ignored, 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. 6811As such a single pixel sampling of an image will take the middle pixel, (or 6812top-left-middle if image has even dimensions). However the <a 6813href="command-line-options.html#define">-define</a> '<code>sample:offset</code>' can be set to modify 6814this position some other location within each sub-region being sampled, as 6815a percentage offset.</p> 6816 6817<p>By default this value is '<code>50</code>' for the midpoint, but could be set 6818to '<code>0</code>' for top-left, '<code>100</code>' for bottom-right, or with 6819separate X and Y offsets such as '<code>0x50</code>' for left-middle edge of 6820sampling 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 6830for chroma downsampling. If this option is omitted, the JPEG library will use 6831its own default values. When reading or writing the YUV format and when 6832writing the M2V (MPEG-2) format, use <a 6833href="command-line-options.html#sampling-factor">-sampling-factor 2x1</a> or <a 6834href="command-line-options.html#sampling-factor">-sampling-factor 4:2:2</a> to specify the 4:2:2 6835downsampling 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 6844together 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 6847a <a href="command-line-options.html#filter">-filter</a> setting of <code>box</code>. Though it is a lot 6848faster, as it avoids all the filter processing of the image. As such it 6849completely 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 6852multiple of the new image size, the number of pixels averaged together to 6853produce the new pixel color is the same across the whole image. This is 6854a special case known as 'binning' and is often used as a method of reducing 6855noise in image such as those generated by digital cameras, especially in low 6856light 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 6874should be done on the root window, rather than directly on the specified 6875window. In this way, you can obtain pieces of other windows that overlap the 6876specified window, and more importantly, you can capture menus or other popups 6877that 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 6892identifying units that are homogeneous with the fuzzy c-means technique. This 6893is part of the ImageMagick color quantization routines. </p> 6894 6895<p>Specify <var>cluster threshold</var> as the number of pixels in 6896each cluster that must exceed the cluster threshold to be considered valid. 6897<var>Smoothing threshold</var> eliminates noise in the second 6898derivative of the histogram. As the value is increased, you can expect 6899a 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 6902of 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 6912contrast. 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 6929achieved 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 6930toning. A threshold of 80% is a good starting point for a reasonable 6931tone.</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 6943in the current image sequence. Using the <a href="command-line-options.html#set">+set</a> form of the 6944option will either remove, or reset that setting to a default state, as 6945appropriate. </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 6949href="command-line-options.html#delay" >-delay</a>, <a href="command-line-options.html#dispose" >-dispose</a>, and <a 6950href="command-line-options.html#page" >-page</a>, <a href="command-line-options.html#colorspace" >-colorspace</a>; generally 6951assigned before the image is read in, by using a <var>key</var> of 6952the 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 6961using 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 6963a global 'artifact' which are automatically assigned (and any <a href="../www/escape.html" >Format Percent 6964Escapes</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 6967identify -format %c rose.png 6968Rose 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 6972Properties</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: 6976Old 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 6984the '<code>page</code>' attribute of an image for images already in memory (also 6985see <a href="command-line-options.html#repage">-page</a>). However it is designed to provide a finer 6986control of the sub-parts of this 'attribute'. The <a href="command-line-options.html#set">-set page</a> 6987option will only provide a direct, unmodified assignment of '<code>page</code>' 6988attribute. </p> 6989 6990<p>This option can also associate a colorspace or profile with your image. 6991For 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 6997example only 'properties' prefixed with "<code>filename:</code>" can be used to 6998modify 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 7004be saved as a global "Artifact" exactly as if it was set using the <a 7005href="command-line-options.html#define" >-define</a> option. As such settings are global in scope, they 7006can be used to pass 'attributes' and 'properties' of one specific image, 7007in a way that allows you to use them in a completely different image, even if 7008the 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 7015a '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 7019with <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 7022previously-formatted ancillary chunks into the output PNG file, using 7023the commandline option as shown below or by setting the profile via a 7024programming 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 7031name in the first 4 bytes, then a colon (":"), followed by the chunk data. 7032This encoder will compute the chunk length and CRC, so those must not 7033be included in the file.</p> 7034 7035<p>"x" can be "b" (before PLTE), "m" (middle, i.e., between PLTE and IDAT), 7036or "e" (end, i.e., after IDAT). If you want to write multiple chunks 7037of the same type, then add a short unique string after the "x" to prevent 7038subsequent 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 7052the position of the light source. Use <a href="command-line-options.html#shade">+shade</a> to return 7053the 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 7063id="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 7069memory for pixmaps. ImageMagick must be compiled with shared memory support, 7070and the display must support the <var>MIT-SHM</var> extension. 7071Otherwise, 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> 7088argument specifies the width of the region to be removed from both sides of 7089the image and the height of the regions to be removed from top and bottom. 7090Offsets 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 7101given, the horizontal component of the shear is performed before the vertical 7102component.</p> 7103 7104<p>Shearing slides one edge of an image along the x-axis or y-axis (i.e., 7105horizontally or vertically, respectively),creating a parallelogram. The amount 7106of each is controlled by the respective shear angle. For horizontal shears, 7107<var>Xdegrees</var> is measured clockwise relative to "up" (the 7108negative 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 7109positive 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 7112defined by the <a href="command-line-options.html#fill">-background</a> option. The color is specified 7113using 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 7116important to note, since horizontal and vertical shears do not 7117<var>commute</var>, i.e., the order matters in a sequence of shears. For 7118example, the following two commands are not equivalent.</p> 7119 7120<pre class="highlight"><code>convert logo: -shear 20x0 -shear 0x60 logo-sheared.png 7121convert 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 7125for the amount of empty space created; the command that follows generates 7126a 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 7138without saturating highlights or shadows. <var>Contrast</var> 7139indicates how much to increase the contrast. For example, 0 is none, 3 is 7140typical 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 7145middle-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 7150a 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. 7152Note 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 7156effects) 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 7166by 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 7183dimensions are unknown such as <code>GRAY</code>, <code>RGB</code>, or 7184<code>CMYK</code>. In addition to width and height, use <a 7185href="command-line-options.html#size">-size</a> with an offset to skip any header information in the 7186image or tell the number of colors in a <code>MAP</code> image file, (e.g. -size 7187640x512+256).</p> 7188 7189<p>For Photo CD images, choose from these sizes:</p> 7190 7191<pre class="highlight"><code>192x128 7192384x256 7193768x512 71941536x1024 71953072x2048 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 7205angle given is the angle toward which the image is sketched. That is the 7206direction 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 7239exposing 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 7274canvas (<a href="command-line-options.html#page" >-page</a> or <a href="command-line-options.html#repage" >-repage</a> 7275offset), and do not actually have to exist on the given image, but may be 7276some 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 7280modified, which means that by default matte/alpha transparency channel is not 7281affected. Typically transparency channel is turned off either before or after 7282the operation. </p> 7283 7284<p>Of course if some color points are transparent to generate a transparent 7285gradient, then the image also requires transparency enabled to store the 7286values. </p> 7287 7288<p>All the above methods when given a single point of color will replace all 7289the colors in the image with the color given, regardless of the point. This is 7290logical, and provides an alternative technique to recolor an image to some 7291default 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 7301href="command-line-options.html#background">-background</a> color into the given image according to the 7302given <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 7303image 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 7307dimension. Similarly using a zero offset with the appropriate <a 7308href="command-line-options.html#gravity">-gravity</a> setting will add rows and columns to the edges of 7309the image, padding the image only along that one edge. Edge padding is what <a 7310href="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 7313href="command-line-options.html#gravity">-gravity</a> is later used with <a href="command-line-options.html#chop">-chop</a> the 7314added 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 7323neighborhood around each pixel from which to choose a candidate pixel to 7324blend.</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 7354beginning of the image. Note this offset and the image size. You will need 7355this information to recover the steganographic image (e.g. display -size 7356320x256+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 7383values 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 7392apply to the currently selected font family. Select <var>fontStretch</var> from the following.</p> 7393 7394<pre class="highlight"><code>Any 7395Condensed 7396Expanded 7397ExtraCondensed 7398ExtraExpanded 7399Normal 7400SemiCondensed 7401SemiExpanded 7402UltraCondensed 7403UltraExpanded 7404</code></pre> 7405 7406<p>To print a complete list of stretch types, use <a href="command-line-options.html#list">-list 7407stretch</a>.</p> 7408 7409<p>For other settings that affect fonts, see the options <a 7410href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 7411href="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 7444the currently selected font family. Select <var>fontStyle</var> from 7445the following.</p> 7446 7447<pre class="highlight"><code>Any 7448Italic 7449Normal 7450Oblique 7451</code></pre> 7452 7453<p>For other settings that affect fonts, see the options <a 7454href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 7455href="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 7464of 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 7466be the "match score" image.</p> 7467 7468<p>The "match-score" image is smaller containing a pixel for ever possible 7469position of the top-left corner of the given sub-image. that is its size will 7470be the size of the larger_image - sub_image + 1. The brightest location in 7471this image is the location s the locate on the best match that is also 7472reported. Note that this may or may not be a perfect match, and the actual 7473brightness will reflect this. Other bright 'peaks' can be used to locate other 7474possible matching locations. </p> 7475 7476<p>Note that the search will try to compare the sub-image at every possible 7477location in the larger image, as such it can be very slow. The smaller the 7478sub-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 7488images in the current image sequence. Use <a href="command-line-options.html#swap">+swap</a> to switch 7489the 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 7506to disk. There is a performance penalty, but the benefits include ensuring a 7507valid image file in the event of a system crash and early reporting if there 7508is 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) 7523formatted 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 7526OPTION1 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 7541the first one provided. If all three color values are the same, the result is 7542a bi-level image. If the opacity threshold is omitted, OpaqueOpacity is used 7543and 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 7549maximum 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 7552value corresponding to the desired channel value. When given as an integer, 7553the minimum attainable value is 0 (corresponding to black when all channels 7554are 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 7556therefore dependent on the installation. For that reason, a reasonable 7557recommendation for most applications is to specify the threshold values as 7558a percentage. </p> 7559 7560<p> The following would force pixels with red values above 50% to have 100% 7561red values, while those at or below 50% red would be set to 0 in the red 7562channel. 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 7569generate an all-black and an all-white image with the same dimensions as the 7570input image.</p> 7571 7572 7573<pre class="highlight"><code>convert in.png -channel RGB -threshold 100% black.png 7574convert 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 7587for speed and any image profile, other than a color profile, is removed to 7588reduce the thumbnail size. To strip the color profiles as well, add <a 7589href="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 7621creating a tiled canvas using <code>TILE:</code> or <code>PATTERN:</code> input 7622formats. </p> 7623 7624<p>Internally ImageMagick does a <a href="command-line-options.html#roll" >-roll</a> of the tile image 7625by 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, 7636white red, yellow, will not be affected by -tint. Only mid-range colors such 7637as 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 7646the image window and is typically displayed in the window title bar. 7647Optionally you can include the image filename, type, width, height, Exif data, 7648or other image attribute by embedding special format characters described 7649under 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 7657titled <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 7673href="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 7683described 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 7685given. </p> 7686 7687<p>Use <a href="command-line-options.html#transparent" >+transparent</a> to invert the pixels matched. 7688that 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 7691href="command-line-options.html#transparent" >-transparent</a> but replaces the matching color with the 7692current <a href="command-line-options.html#fill">-fill</a> color setting, rather than transparent. 7693However the <a href="command-line-options.html#transparent" >-transparent</a> operator also ensures 7694that 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 7696href="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' 7699used for color-mapped image formats, such as GIF. For that use <a 7700href="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 7710GIF and PNG8 which uses this color to represent boolean transparency. This 7711does not make a color transparent, it only defines what color the transparent 7712color is in the color palette of the saved image. Use <a 7713href="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 7716transparent color of the same color value without conflict. That is, you can 7717use the same color for both the transparent and opaque color areas within an 7718image. This, in turn, frees to you to select a transparent color that is 7719appropriate when an image is displayed by an application that does not handle a 7720transparent color index, while allowing ImageMagick to correctly handle images of this 7721type. </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 7748the 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 7751image with the fastest computational speed and the least amount of memory. 7752However, the default depth is inappropriate for some images. To assure the 7753best representation, try values between 2 and 8 for this parameter. Refer to 7754the <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> 7758option, or writing to an image format which requires color reduction, is 7759required 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 7768pixels. Use <a href="command-line-options.html#fuzz">-fuzz</a> to make <a href="command-line-options.html#trim">-trim</a> remove 7769edges 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 7772you to extract the result of the <a href="command-line-options.html#trim">-trim</a> operation from the 7773image. Use a <a href="command-line-options.html#repage">+repage</a> to remove the virtual canvas page 7774information if it is unwanted.</p> 7775 7776<p>If the trimmed image 'disappears' an warning is produced, and a special 7777single 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 7791truecolor, the encoder will try to choose an efficient subformat. The <a 7792href="command-line-options.html#type">-type</a> option can be used to override this behavior. For 7793example, to prevent a JPEG from being written in grayscale format even though 7794only 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 7800encoder to write an alpha channel even though the image is opaque, if the 7801output 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 7823displayed is over-written. <code>display</code> will automagically detect that 7824the input file has been changed and update the displayed image 7825accordingly.</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 7843with 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 7853convolved with a Gaussian operator of the given radius and standard deviation 7854(sigma). For reasonable results, radius should be larger than sigma. Use 7855a 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 7906lookup completely 'misses' the source image. The color(s) that appear to 7907surround the source image. Generally this color is derived from the source 7908image, 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>. 7934However it also affects operations that may access pixels just outside the 7935image proper, such as <a href="command-line-options.html#convolve">-convolve</a>, <a 7936href="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 7939href="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 7951GrayScale DirectColor 7952StaticColor default 7953PseudoColor visual id 7954</code></pre> 7955 7956<p>The X server must support the visual you choose, otherwise an error occurs. 7957If a visual is not specified, the visual class that can display the most 7958simultaneous 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 7968brightness according to watermark image's grayscale value and the 7969<var>brightness</var> percentage. The destinations color saturation 7970attribute is just direct modified by the <var>saturation</var> 7971percentage, 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 7993the 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 8021href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a 8022href="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 8037value within [0, <var>QuantumRange</var>] corresponding to the 8038desired <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> 8047to 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 8051image is surrounded by the background color. Refer to <code>X RESOURCES</code> 8052for details.</p> 8053 8054<p>The image will not display on the root window if the image has more unique 8055colors than the target window colormap allows. Use <a 8056href="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 8081grayscale 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, 8087but 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 -->
