Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / ImageMagick / 82a2ff27ee83c3408dce06c0f129386bd13eb17f / . / www / command-line-options.html
blob: 8ab359e1f26cf9baa22d6577d856e9c937b14c29 [file] [log] [blame]
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1<!DOCTYPE html>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2<html lang="en">
cristyad41c0c2012-10-31 00:49:28 +0000[diff] [blame]3<head>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4 <meta charset="utf-8">
5 <meta http-equiv="X-UA-Compatible" content="IE=edge">
6 <meta name="viewport" content="width=device-width, initial-scale=1">
cristydcca3fa2010-12-29 21:50:07 +0000[diff] [blame]7 <title>ImageMagick: Command-line Options</title>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8 <meta http-equiv="content-language" content="en-US">
9 <meta http-equiv="content-type" content="text/html; charset=utf-8">
10 <meta http-equiv="reply-to" content="magick-users@imagemagick.org">
11 <meta name="application-name" content="ImageMagick">
12 <meta name="description" content="ImageMagick® is a software suite to create, edit, compose, or convert bitmap images. It can read and write images in a variety of formats (over 200) including PNG, JPEG, JPEG-2000, GIF, WebP, Postscript, PDF, and SVG. Use ImageMagick to resize, flip, mirror, rotate, distort, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves.">
13 <meta name="application-url" content="http://www.imagemagick.org">
14 <meta name="generator" content="PHP">
15 <meta name="keywords" content="command-line, options, ImageMagick, PerlMagick, image processing, image, photo, software, Magick++, OpenMP, convert">
16 <meta name="rating" content="GENERAL">
17 <meta name="robots" content="INDEX, FOLLOW">
18 <meta name="generator" content="ImageMagick Studio LLC">
19 <meta name="author" content="ImageMagick Studio LLC">
20 <meta name="revisit-after" content="2 DAYS">
21 <meta name="resource-type" content="document">
22 <meta name="copyright" content="Copyright (c) 1999-2015 ImageMagick Studio LLC">
23 <meta name="distribution" content="Global">
24 <meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1">
25 <link rel="icon" href="../images/wand.png">
26 <link rel="shortcut icon" href="../images/wand.ico" type="images/x-icon">
27 <link rel="stylesheet" href="css/bootstrap.min.css">
28 <link rel="stylesheet" href="css/magick.css">
cristyad41c0c2012-10-31 00:49:28 +0000[diff] [blame]29</head>
30
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]31<body>
cristyad41c0c2012-10-31 00:49:28 +0000[diff] [blame]32<div class="main">
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]33<div class="magick-masthead">
34 <div class="container">
35 <script type="text/javascript">
36 <!--
37 google_ad_client = "pub-3129977114552745";
38 google_ad_slot = "5439289906";
39 google_ad_width = 728;
40 google_ad_height = 90;
41 //-->
42 </script>
43 <center><script type="text/javascript" src="http://localhost/pagead/show_ads.js">
44 </script></center>
45 <nav class="magick-nav">
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]46 <a class="magick-nav-item " href="../index.html">Home</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]47 <a class="magick-nav-item " href="binary-releases.html">Downloads</a>
48 <a class="magick-nav-item " href="command-line-tools.html">Tools</a>
49 <a class="magick-nav-item active" href="command-line-options.html">Options</a>
50 <a class="magick-nav-item " href="api.html">Development</a>
cristy44443b92015-05-05 00:06:07 +0000[diff] [blame]51 <a class="magick-nav-item" href="http://www.imagemagick.org/discourse-server/">Community</a>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]52 <a class="magick-nav-item pull-right " href="http://www.imagemagick.org/script/search.php">Search</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]53 </nav>
54 </div>
55</div>
56<div class="container">
57<div class="magick-header">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]58<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#backdrop">‑backdrop</a> • <a href="command-line-options.html#background">‑background</a> • <a href="command-line-options.html#bench">‑bench</a> • <a href="command-line-options.html#bias">‑bias</a> • <a href="command-line-options.html#black-point-compensation">‑black‑point‑compensation</a> • <a href="command-line-options.html#black-threshold">‑black‑threshold</a> • <a href="command-line-options.html#blend">‑blend</a> • <a href="command-line-options.html#blue-primary">‑blue‑primary</a> • <a href="command-line-options.html#blue-shift">‑blue‑shift</a> • <a href="command-line-options.html#blur">‑blur</a> • <a href="command-line-options.html#border">‑border</a> • <a href="command-line-options.html#bordercolor">‑bordercolor</a> • <a href="command-line-options.html#borderwidth">‑borderwidth</a> • <a href="command-line-options.html#brightness-contrast">‑brightness‑contrast</a> • <a href="command-line-options.html#cache">‑cache</a> • <a href="command-line-options.html#canny">‑canny</a> • <a href="command-line-options.html#caption">‑caption</a> • <a href="command-line-options.html#cdl">‑cdl</a> • <a href="command-line-options.html#channel">‑channel</a> • <a href="command-line-options.html#charcoal">‑charcoal</a> • <a href="command-line-options.html#chop">‑chop</a> • <a href="command-line-options.html#clamp">‑clamp</a> • <a href="command-line-options.html#clip">‑clip</a> • <a href="command-line-options.html#clip-mask">‑clip‑mask</a> • <a href="command-line-options.html#clip-path">‑clip‑path</a> • <a href="command-line-options.html#clone">‑clone</a> • <a href="command-line-options.html#clut">‑clut</a> • <a href="command-line-options.html#coalesce">‑coalesce</a> • <a href="command-line-options.html#colorize">‑colorize</a> • <a href="command-line-options.html#colormap">‑colormap</a> • <a href="command-line-options.html#color-matrix">‑color‑matrix</a> • <a href="command-line-options.html#colors">‑colors</a> • <a href="command-line-options.html#colorspace">‑colorspace</a> • <a href="command-line-options.html#combine">‑combine</a> • <a href="command-line-options.html#comment">‑comment</a> • <a href="command-line-options.html#compare">‑compare</a> • <a href="command-line-options.html#complex">‑complex</a> • <a href="command-line-options.html#compose">‑compose</a> • <a href="command-line-options.html#composite">‑composite</a> • <a href="command-line-options.html#compress">‑compress</a> • <a href="command-line-options.html#connected-components">‑connected‑components</a> • <a href="command-line-options.html#contrast">‑contrast</a> • <a href="command-line-options.html#contrast-stretch">‑contrast‑stretch</a> • <a href="command-line-options.html#convolve">‑convolve</a> • <a href="command-line-options.html#crop">‑crop</a> • <a href="command-line-options.html#cycle">‑cycle</a> • <a href="command-line-options.html#debug">‑debug</a> • <a href="command-line-options.html#decipher">‑decipher</a> • <a href="command-line-options.html#deconstruct">‑deconstruct</a> • <a href="command-line-options.html#define">‑define</a> • <a href="command-line-options.html#delay">‑delay</a> • <a href="command-line-options.html#delete">‑delete</a> • <a href="command-line-options.html#density">‑density</a> • <a href="command-line-options.html#depth">‑depth</a> • <a href="command-line-options.html#descend">‑descend</a> • <a href="command-line-options.html#deskew">‑deskew</a> • <a href="command-line-options.html#despeckle">‑despeckle</a> • <a href="command-line-options.html#direction">‑direction</a> • <a href="command-line-options.html#displace">‑displace</a> • <a href="command-line-options.html#display">‑display</a> • <a href="command-line-options.html#dispose">‑dispose</a> • <a href="command-line-options.html#dissimilarity-threshold">‑dissimilarity‑threshold</a> • <a href="command-line-options.html#dissolve">‑dissolve</a> • <a href="command-line-options.html#distort">‑distort</a> • <a href="command-line-options.html#distribute-cache">‑distribute‑cache</a> • <a href="command-line-options.html#dither">‑dither</a> • <a href="command-line-options.html#draw">‑draw</a> • <a href="command-line-options.html#duplicate">‑duplicate</a> • <a href="command-line-options.html#edge">‑edge</a> • <a href="command-line-options.html#emboss">‑emboss</a> • <a href="command-line-options.html#encipher">‑encipher</a> • <a href="command-line-options.html#encoding">‑encoding</a> • <a href="command-line-options.html#endian">‑endian</a> • <a href="command-line-options.html#enhance">‑enhance</a> • <a href="command-line-options.html#equalize">‑equalize</a> • <a href="command-line-options.html#evaluate">‑evaluate</a> • <a href="command-line-options.html#evaluate-sequence">‑evaluate‑sequence</a> • <a href="command-line-options.html#extent">‑extent</a> • <a href="command-line-options.html#extract">‑extract</a> • <a href="command-line-options.html#family">‑family</a> • <a href="command-line-options.html#features">‑features</a> • <a href="command-line-options.html#fft">‑fft</a> • <a href="command-line-options.html#fill">‑fill</a> • <a href="command-line-options.html#filter">‑filter</a> • <a href="command-line-options.html#flatten">‑flatten</a> • <a href="command-line-options.html#flip">‑flip</a> • <a href="command-line-options.html#floodfill">‑floodfill</a> • <a href="command-line-options.html#flop">‑flop</a> • <a href="command-line-options.html#font">‑font</a> • <a href="command-line-options.html#foreground">‑foreground</a> • <a href="command-line-options.html#format">‑format</a> • <a href="command-line-options.html#format_identify_">‑format[identify]</a> • <a href="command-line-options.html#frame">‑frame</a> • <a href="command-line-options.html#frame_import_">‑frame[import]</a> • <a href="command-line-options.html#function">‑function</a> • <a href="command-line-options.html#fuzz">‑fuzz</a> • <a href="command-line-options.html#fx">‑fx</a> • <a href="command-line-options.html#gamma">‑gamma</a> • <a href="command-line-options.html#gaussian-blur">‑gaussian‑blur</a> • <a href="command-line-options.html#geometry">‑geometry</a> • <a href="command-line-options.html#gravity">‑gravity</a> • <a href="command-line-options.html#grayscale">‑grayscale</a> • <a href="command-line-options.html#green-primary">‑green‑primary</a> • <a href="command-line-options.html#hald-clut">‑hald‑clut</a> • <a href="command-line-options.html#help">‑help</a> • <a href="command-line-options.html#highlight-color">‑highlight‑color</a> • <a href="command-line-options.html#hough-lines">‑hough‑lines</a> • <a href="command-line-options.html#iconGeometry">‑iconGeometry</a> • <a href="command-line-options.html#iconic">‑iconic</a> • <a href="command-line-options.html#identify">‑identify</a> • <a href="command-line-options.html#ift">‑ift</a> • <a href="command-line-options.html#immutable">‑immutable</a> • <a href="command-line-options.html#implode">‑implode</a> • <a href="command-line-options.html#insert">‑insert</a> • <a href="command-line-options.html#intensity">‑intensity</a> • <a href="command-line-options.html#intent">‑intent</a> • <a href="command-line-options.html#interlace">‑interlace</a> • <a href="command-line-options.html#interpolate">‑interpolate</a> • <a href="command-line-options.html#interline-spacing">‑interline‑spacing</a> • <a href="command-line-options.html#interword-spacing">‑interword‑spacing</a> • <a href="command-line-options.html#kerning">‑kerning</a> • <a href="command-line-options.html#kuwahara">‑kuwahara</a> • <a href="command-line-options.html#label">‑label</a> • <a href="command-line-options.html#lat">‑lat</a> • <a href="command-line-options.html#layers">‑layers</a> • <a href="command-line-options.html#level">‑level</a> • <a href="command-line-options.html#level-colors">‑level‑colors</a> • <a href="command-line-options.html#limit">‑limit</a> • <a href="command-line-options.html#linear-stretch">‑linear‑stretch</a> • <a href="command-line-options.html#linewidth">‑linewidth</a> • <a href="command-line-options.html#liquid-rescale">‑liquid‑rescale</a> • <a href="command-line-options.html#list">‑list</a> • <a href="command-line-options.html#log">‑log</a> • <a href="command-line-options.html#loop">‑loop</a> • <a href="command-line-options.html#lowlight-color">‑lowlight‑color</a> • <a href="command-line-options.html#magnify">‑magnify</a> • <a href="command-line-options.html#map">‑map</a> • <a href="command-line-options.html#map_stream_">‑map[stream]</a> • <a href="command-line-options.html#mask">‑mask</a> • <a href="command-line-options.html#mattecolor">‑mattecolor</a> • <a href="command-line-options.html#median">‑median</a> • <a href="command-line-options.html#mean-shift">‑mean‑shift</a> • <a href="command-line-options.html#metric">‑metric</a> • <a href="command-line-options.html#mode">‑mode</a> • <a href="command-line-options.html#modulate">‑modulate</a> • <a href="command-line-options.html#moments">‑moments</a> • <a href="command-line-options.html#monitor">‑monitor</a> • <a href="command-line-options.html#monochrome">‑monochrome</a> • <a href="command-line-options.html#morph">‑morph</a> • <a href="command-line-options.html#morphology">‑morphology</a> • <a href="command-line-options.html#mosaic">‑mosaic</a> • <a href="command-line-options.html#motion-blur">‑motion‑blur</a> • <a href="command-line-options.html#name">‑name</a> • <a href="command-line-options.html#negate">‑negate</a> • <a href="command-line-options.html#noise">‑noise</a> • <a href="command-line-options.html#normalize">‑normalize</a> • <a href="command-line-options.html#opaque">‑opaque</a> • <a href="command-line-options.html#ordered-dither">‑ordered‑dither</a> • <a href="command-line-options.html#orient">‑orient</a> • <a href="command-line-options.html#page">‑page</a> • <a href="command-line-options.html#paint">‑paint</a> • <a href="command-line-options.html#path">‑path</a> • <a href="command-line-options.html#pause_animate_">‑pause[animate]</a> • <a href="command-line-options.html#pause_import_">‑pause[import]</a> • <a href="command-line-options.html#perceptible">‑perceptible</a> • <a href="command-line-options.html#ping">‑ping</a> • <a href="command-line-options.html#pointsize">‑pointsize</a> • <a href="command-line-options.html#polaroid">‑polaroid</a> • <a href="command-line-options.html#poly">‑poly</a> • <a href="command-line-options.html#posterize">‑posterize</a> • <a href="command-line-options.html#precision">‑precision</a> • <a href="command-line-options.html#preview">‑preview</a> • <a href="command-line-options.html#print">‑print</a> • <a href="command-line-options.html#process">‑process</a> • <a href="command-line-options.html#profile">‑profile</a> • <a href="command-line-options.html#quality">‑quality</a> • <a href="command-line-options.html#quantize">‑quantize</a> • <a href="command-line-options.html#quiet">‑quiet</a> • <a href="command-line-options.html#radial-blur">‑radial‑blur</a> • <a href="command-line-options.html#raise">‑raise</a> • <a href="command-line-options.html#random-threshold">‑random‑threshold</a> • <a href="command-line-options.html#red-primary">‑red‑primary</a> • <a href="command-line-options.html#regard-warnings">‑regard‑warnings</a> • <a href="command-line-options.html#region">‑region</a> • <a href="command-line-options.html#remap">‑remap</a> • <a href="command-line-options.html#remote">‑remote</a> • <a href="command-line-options.html#render">‑render</a> • <a href="command-line-options.html#repage">‑repage</a> • <a href="command-line-options.html#resample">‑resample</a> • <a href="command-line-options.html#resize">‑resize</a> • <a href="command-line-options.html#respect-parentheses">‑respect‑parentheses</a> • <a href="command-line-options.html#reverse">‑reverse</a> • <a href="command-line-options.html#roll">‑roll</a> • <a href="command-line-options.html#rotate">‑rotate</a> • <a href="command-line-options.html#sample">‑sample</a> • <a href="command-line-options.html#sampling-factor">‑sampling‑factor</a> • <a href="command-line-options.html#scale">‑scale</a> • <a href="command-line-options.html#scene">‑scene</a> • <a href="command-line-options.html#screen">‑screen</a> • <a href="command-line-options.html#seed">‑seed</a> • <a href="command-line-options.html#segment">‑segment</a> • <a href="command-line-options.html#selective-blur">‑selective‑blur</a> • <a href="command-line-options.html#separate">‑separate</a> • <a href="command-line-options.html#sepia-tone">‑sepia‑tone</a> • <a href="command-line-options.html#set">‑set</a> • <a href="command-line-options.html#shade">‑shade</a> • <a href="command-line-options.html#shadow">‑shadow</a> • <a href="command-line-options.html#shared-memory">‑shared‑memory</a> • <a href="command-line-options.html#sharpen">‑sharpen</a> • <a href="command-line-options.html#shave">‑shave</a> • <a href="command-line-options.html#shear">‑shear</a> • <a href="command-line-options.html#sigmoidal-contrast">‑sigmoidal‑contrast</a> • <a href="command-line-options.html#silent">‑silent</a> • <a href="command-line-options.html#similarity-threshold">‑similarity‑threshold</a> • <a href="command-line-options.html#size">‑size</a> • <a href="command-line-options.html#sketch">‑sketch</a> • <a href="command-line-options.html#smush">‑smush</a> • <a href="command-line-options.html#snaps">‑snaps</a> • <a href="command-line-options.html#solarize">‑solarize</a> • <a href="command-line-options.html#sparse-color">‑sparse‑color</a> • <a href="command-line-options.html#splice">‑splice</a> • <a href="command-line-options.html#spread">‑spread</a> • <a href="command-line-options.html#statistic">‑statistic</a> • <a href="command-line-options.html#stegano">‑stegano</a> • <a href="command-line-options.html#stereo">‑stereo</a> • <a href="command-line-options.html#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#weight">‑weight</a> • <a href="command-line-options.html#white-point">‑white‑point</a> • <a href="command-line-options.html#white-threshold">‑white‑threshold</a> • <a href="command-line-options.html#window">‑window</a> • <a href="command-line-options.html#window-group">‑window‑group</a> • <a href="command-line-options.html#write">‑write</a> </p>
cristyad41c0c2012-10-31 00:49:28 +0000[diff] [blame]59
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]60<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>
61
62<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]63 <h3 class="magick-header"><a id="adaptive-blur"></a>-adaptive-blur <var>radius</var>[x<var>sigma</var>]</h3>
cristyad41c0c2012-10-31 00:49:28 +0000[diff] [blame]64</div>
65
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]66<p class="magick-description">Adaptively blur pixels, with decreasing effect near edges.</p>
cristy8ee7f242013-06-20 16:08:44 +0000[diff] [blame]67
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]68<p>A Gaussian operator of the given radius and standard deviation (<var>sigma</var>) is used. If <var>sigma</var> is not given it
69defaults to 1.</p>
70
71<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]72 <h3 class="magick-header"><a id="adaptive-resize"></a>-adaptive-resize <var>geometry</var></h3>
cristy149d58c2013-08-07 19:44:54 +0000[diff] [blame]73</div>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]74
75<p class="magick-description">Resize the image using data-dependent triangulation.</p>
76
77<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>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]78option defaults to data-dependent triangulation. Use the <a href="command-line-options.html#filter">-filter</a> to choose a different resampling algorithm.
79Offsets, if present in the geometry string, are ignored, and the <a href="command-line-options.html#gravity">-gravity</a> option has no effect.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]80
81<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]82 <h3 class="magick-header"><a id="adaptive-sharpen"></a>-adaptive-sharpen <var>radius</var>[x<var>sigma</var>]</h3>
cristy149d58c2013-08-07 19:44:54 +0000[diff] [blame]83</div>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]84
85<p class="magick-description">Adaptively sharpen pixels, with increasing effect near edges.</p>
86
87<p>A Gaussian operator of the given radius and standard deviation
88(<var>sigma</var>) is used. If <var>sigma</var> is not given it
89defaults to 1.</p>
90
91<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]92 <h3 class="magick-header"><a id="adjoin"></a>-adjoin</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]93</div>
94
95<p class="magick-description">Join images into a single multi-image file.</p>
96
97<p>This option is enabled by default. An attempt is made to save all images of
98an image sequence into the given output file. However, some formats, such as
99JPEG and PNG, do not support more than one image per file, and in that case
100ImageMagick is forced to write each image as a separate file. As such, if
101more than one image needs to be written, the filename given is modified by
102adding a <a href="command-line-options.html#scene">-scene</a> number before the suffix, in order to
103make distinct names for each image. </p>
104
105<p>Use <a href="command-line-options.html#adjoin">+adjoin</a> to force each image to be written to
106separate files, whether or not the file format allows multiple images per file
107(for example, GIF, MIFF, and TIFF). </p>
108
109<p>Including a C-style integer format string in the output filename will
110automagically enable <a href="command-line-options.html#adjoin">+adjoin</a> and are used to specify
111where the <a href="command-line-options.html#scene">-scene</a> number is placed in the filenames. These
112strings, such as '<code>%d</code>' or '<code>%03d</code>', are familiar to those
113who have used the standard <code>printf()</code>' C-library function. As an
114example, the command</p>
115
116<pre>
117convert logo: rose: -morph 15 my%02dmorph.jpg
118</pre>
119
120<p>will create a sequence of 17 images (the two given plus 15 more created by
121<a href="command-line-options.html#morph">-morph</a>), named: my00morph.jpg, my01morph.jpg,
122my02morph.jpg, ..., my16morph.jpg. </p>
123
124<p>In summary, ImageMagick tries to write all images to one file, but will
125save to multiple files, if any of the following conditions exist...</p>
126<ol>
127<li>the output image's file format does not allow multi-image files,</li>
128<li>the <a href="command-line-options.html#adjoin">+adjoin</a> option is given, or</li>
129<li>a printf() integer format string (eg: "%d") is present in the output
130 filename.</li>
131</ol>
132
133
134<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]135 <h3 class="magick-header"><a id="affine"></a>-affine
136 <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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]137</div>
138
139<p class="magick-description">Set the drawing transformation matrix for combined rotating and scaling.</p>
140
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]141<p>This option sets a transformation matrix, for use by subsequent <a href="command-line-options.html#draw">-draw</a> or <a href="command-line-options.html#transform">-transform</a> options. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]142
143<p>The matrix entries are entered as comma-separated numeric values either in
144quotes or without spaces. </p>
145
146<p>Internally, the transformation matrix has 3x3 elements, but three of them
147are omitted from the input because they are constant. The new (transformed)
148coordinates (<var>x'</var>, <var>y'</var>) of a pixel at
149position (<var>x</var>, <var>y</var>) in the original
150image are calculated using the following matrix equation.</p>
151
152<div class="eqn">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]153<img alt="affine transformation" src="../images/affine.png">
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]154</div>
155
156<p> The size of the resulting image is that of the smallest rectangle that
157contains the transformed source image. The parameters
158<var>t<sub>x</sub></var> and <var>t<sub>y</sub></var>
159subsequently shift the image pixels so that those that are moved out of the
160image area are cut off.</p>
161
162<p>The transformation matrix complies with the left-handed pixel coordinate
163system: positive <var>x</var> and <var>y</var> directions
164are rightward and downward, resp.; positive rotation is clockwise.</p>
165
166<p> If the translation coefficients <var>t<sub>x</sub></var> and
167<var>t<sub>y</sub></var> are omitted they default to 0,0. Therefore,
168four parameters suffice for rotation and scaling without translation.</p>
169
170<p>Scaling by the factors <var>s<sub>x</sub></var> and
171<var>s<sub>y</sub></var> in the <var>x</var> and <var>y</var> directions,
172respectively, is accomplished with the following.</p>
173
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]174<p>See <a href="command-line-options.html#transform">-transform</a>, and the <a href="command-line-options.html#distort">-distort</a> method '<code>Affineprojection</code> for more
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]175information </p>
176
177
178<pre>
179-affine <var>s<sub>x</sub></var>,0,0,<var>s<sub>y</sub></var>
180</pre>
181
182<p>Translation by a displacement (<var>t<sub>x</sub></var>, <var>t<sub>y</sub></var>) is accomplished like so:</p>
183
184<pre>
185-affine 1,0,0,1,<var>t<sub>x</sub></var>,<var>t<sub>y</sub></var>
186</pre>
187
188<p>Rotate clockwise about the origin (the upper left-hand corner) by an angle
189<var>a</var> by letting <var>c</var> = cos(<var>a</var>), <var>s</var>
190= sin(<var>a</var>), and using the following.</p>
191
192<pre>
193-affine <var>c</var>,<var>s</var>,-<var>s</var>,<var>c</var>
194</pre>
195
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]196<p>The cumulative effect of a sequence of <a href="command-line-options.html#affine">-affine</a>
197transformations can be accomplished by instead by a single <a href="command-line-options.html#affine">-affine</a> operation using the matrix equal to the product of the matrices
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]198of the individual transformations.</p>
199
200<p>An attempt is made to detect near-singular transformation matrices. If the
201matrix determinant has a sufficiently small absolute value it is rejected.</p>
202
203<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]204 <h3 class="magick-header"><a id="alpha"></a>-alpha <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]205</div>
206
207<p class="magick-description">Gives control of the alpha/matte channel of an image.</p>
208
209<p>Used to set a flag on an image indicating whether or not to use existing alpha
210channel data, to create an alpha channel, or to perform other operations on the alpha channel. Choose the argument <var>type</var> from the list below.</p>
211
212
213<div class="table-responsive">
214<table class="table table-condensed table-striped">
215 <tbody>
216 <tr>
217 <th>Type</th>
218 <th>Description</th>
219 </tr>
220
221 <tr>
222 <td><code>Activate</code> or <code>On</code></td>
223 <td>
224 Enable the image's transparency channel. Note normally <code>Set</code>
225 should be used instead of this, unless you specifically need to
226 preserve existing (but specifically turned <code>Off</code>) transparency
227 channel. </td></tr>
228
229 <tr>
230 <td><code>Associate</code></td>
231 <td>
232 associate the alpha channel with the image.</td></tr>
233
234 <tr>
235 <td><code>Deactivate</code> or <code>Off</code></td>
236 <td>
237 Disables the image's transparency channel. Does not delete or change the
238 existing data, just turns off the use of that data.</td></tr>
239
240 <tr>
241 <td><code>Disassociate</code></td>
242 <td>
243 disassociate the alpha channel from the image.</td></tr>
244
245 <tr>
246 <td><code>Set</code></td>
247 <td>
248 Activates the alpha/matte channel. If it was previously turned off
249 then it also resets the channel to opaque. If the image already had
250 the alpha channel turned on, it will have no effect.</td></tr>
251
252 <tr>
253 <td><code>Opaque</code></td>
254 <td>
255 Enables the alpha/matte channel and forces it to be fully opaque.
256 </td></tr>
257
258 <tr>
259 <td><code>Transparent</code></td>
260 <td>
261 Activates the alpha/matte channel and forces it to be fully
262 transparent. This effectively creates a fully transparent image the
263 same size as the original and with all its original RGB data still
264 intact, but fully transparent. </td></tr>
265
266 <tr>
267 <td><code>Extract</code></td>
268 <td>
269 Copies the alpha channel values into all the color channels and turns
270 '<code>Off</code>' the the image's transparency, so as to generate
271 a gray-scale mask of the image's shape. The alpha channel data is left
272 intact just deactivated. This is the inverse of '<code>Copy</code>'.
273 </td></tr>
274
275 <tr>
276 <td><code>Copy</code></td>
277 <td>
278 Turns '<code>On</code>' the alpha/matte channel, then copies the
279 gray-scale intensity of the image, into the alpha channel, converting
280 a gray-scale mask into a transparent shaped mask ready to be colored
281 appropriately. The color channels are not modified. </td></tr>
282
283 <tr>
284 <td><code>Shape</code></td>
285 <td>
286 As per '<code>Copy</code>' but also colors the resulting shape mask with
287 the current background color. That is the RGB color channels is
288 replaced, with appropriate alpha shape.
289 </td></tr>
290
291 <tr>
292 <td><code>Remove</code></td>
293 <td>
294 Composite the image over the background color.
295 </td></tr>
296
297 <tr>
298 <td><code>Background</code></td>
299 <td>
300 Set any fully-transparent pixel to the background color, while leaving
301 it fully-transparent. This can make some image file formats, such as
302 PNG, smaller as the RGB values of transparent pixels are more uniform,
303 and thus can compress better.
304 </td></tr>
305 </tbody>
306</table>
307</div>
308
309<p>Note that while the obsolete <code>+matte</code> operation was the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]310same as "<code><a href="command-line-options.html#alpha">-alpha</a> Off</code>", the <code>
311&gt;-matte</code> operation was the same as "<code><a href="command-line-options.html#alpha">-alpha</a>
312Set</code>" and not "<code><a href="command-line-options.html#alpha">-alpha</a> On</code>". </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]313
314
315<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]316 <h3 class="magick-header"><a id="annotate"></a>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]317 -annotate <var>degrees</var> <var>text</var><br>
318 -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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]319</div>
320
321<p class="magick-description">Annotate an image with text</p>
322
323<p>This is a convenience for annotating an image with text. For more precise
324control over text annotations, use <a href="command-line-options.html#draw">-draw</a>.</p>
325
326
327<p>The values <var>Xdegrees</var> and <var>Ydegrees</var>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]328control 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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]329
330<p>Using <a href="command-line-options.html#annotate">-annotate</a> <var>degrees</var>
331or <a href="command-line-options.html#annotate">-annotate</a> <var>degrees</var>x<var>degrees</var> produces an unsheared rotation of the text. The
332direction of the rotation is positive, which means a clockwise rotation if <var>degrees</var> is positive. (This conforms to the usual mathematical
333convention once it is realized that the positive <var>y</var>–direction is
334conventionally considered to be <var>downward</var> for images.)</p>
335
336<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
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]337equation.</p> <div class="eqn"><img alt="annotate transformation" src="../images/annotate.png"></div>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]338
339<p>If <var>t<sub>x</sub></var> and <var>t<sub>y</sub></var> are omitted, they default to 0. This makes the
340bottom-left of the text becomes the upper-left corner of the image, which is
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]341probably undesirable. Adding a <a href="command-line-options.html#gravity">-gravity</a> option in this
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]342case leads to nice results.</p>
343
344<p>Text is any UTF-8 encoded character sequence. If <var>text</var>
345is of the form '@mytext.txt', the text is read from the file
346<code>mytext.txt</code>. Text in a file is taken literally; no embedded
347formatting characters are recognized.</p>
348
349<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]350 <h3 class="magick-header"><a id="antialias"></a>-antialias</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]351</div>
352
353<p class="magick-description">Enable/Disable of the rendering of anti-aliasing pixels when drawing fonts and lines.</p>
354
355<p>By default, objects (e.g. text, lines, polygons, etc.) are antialiased when
356drawn. Use <a href="command-line-options.html#antialias">+antialias</a> to disable the addition of
357antialiasing edge pixels. This will then reduce the number of colors added to
358an image to just the colors being directly drawn. That is, no mixed colors
359are added when drawing such objects. </p>
360
361<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]362 <h3 class="magick-header"><a id="append"></a>-append</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]363</div>
364
365<p class="magick-description">Join current images vertically or horizontally.</p>
366
367<p>This option creates a single longer image, by joining all the current
368images in sequence top-to-bottom. Use <a href="command-line-options.html#append">+append</a> to
369stack images left-to-right. </p>
370
371<p>If they are not of the same width, narrower images are padded with the
372current <a href="command-line-options.html#background">-background</a> color setting, and their
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]373position relative to each other can be controlled by the current <a href="command-line-options.html#gravity">-gravity</a> setting. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]374
375
376<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]377 <h3 class="magick-header"><a id="attenuate"></a>-attenuate <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]378</div>
379
380<p class="magick-description">Lessen (or intensify) when adding noise to an image.</p>
381
382<p>If unset the value is equivalent to 1.0, or a maximum noise addition</p>
383
384<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]385 <h3 class="magick-header"><a id="authenticate"></a>-authenticate <var>password</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]386</div>
387
388<p class="magick-description">Decrypt a PDF with a password.</p>
389
390<p>Use this option to supply a <var>password</var> for decrypting
391a PDF that has been encrypted using Microsoft Crypto API (MSC API). The
392encrypting using the MSC API is not supported.</p>
393
394<p>For a different encryption method, see <a href="command-line-options.html#encipher">-encipher</a>
395and <a href="command-line-options.html#decipher">-decipher</a>. </p>
396
397
398<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]399 <h3 class="magick-header"><a id="auto-gamma"></a>-auto-gamma</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]400</div>
401
402<p class="magick-description">Automagically adjust gamma level of image.</p>
403
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]404<p>This calculates the mean values of an image, then applies a calculated <a href="command-line-options.html#gamma">-gamma</a> adjustment so that is the mean color exists in the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]405image it will get a have a value of 50%. </p>
406
407<p>This means that any solid 'gray' image becomes 50% gray. </p>
408
409<p>This works well for real-life images with little or no extreme dark and
410light areas, but tend to fail for images with large amounts of bright sky or
411dark shadows. It also does not work well for diagrams or cartoon like images.
412</p>
413
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]414<p>It uses the <a href="command-line-options.html#channel">-channel</a> setting, (including the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]415'<var>sync</var>' flag for channel synchronization), to determine which color
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]416values is used and modified. As the default <a href="command-line-options.html#channel">-channel</a> setting is '<var>RGB,sync</var>', channels are modified
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]417together by the same gamma value, preserving colors. </p>
418
419
420
421<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]422 <h3 class="magick-header"><a id="auto-level"></a>-auto-level</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]423</div>
424
425<p class="magick-description">Automagically adjust color levels of image.</p>
426
427<p>This is a 'perfect' image normalization operator. It finds the exact
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]428minimum and maximum color values in the image and then applies a <a href="command-line-options.html#level">-level</a> operator to stretch the values to the full range of
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]429values. </p>
430
431<p>The operator is not typically used for real-life images, image scans, or
432JPEG format images, as a single 'out-rider' pixel can set a bad min/max values
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]433for the <a href="command-line-options.html#level">-level</a> operation. On the other hand it is the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]434right operator to use for color stretching gradient images being used to
435generate Color lookup tables, distortion maps, or other 'mathematically'
436defined images. </p>
437
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]438<p>The operator is very similar to the <a href="command-line-options.html#normalize">-normalize</a>, <a href="command-line-options.html#contrast-stretch">-contrast-stretch</a>, and <a href="command-line-options.html#linear-stretch">-linear-stretch</a> operators, but without 'histogram binning' or 'clipping'
439problems that these operators may have. That is <a href="command-line-options.html#auto-level">-auto-level</a> is the perfect or ideal version these operators. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]440
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]441<p>It uses the <a href="command-line-options.html#channel">-channel</a> setting, (including the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]442special '<var>sync</var>' flag for channel synchronization), to determine
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]443which color values are used and modified. As the default <a href="command-line-options.html#channel">+channel</a> setting is '<var>RGB,sync</var>', the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]444'<var>sync</var>' ensures that the color channels will are modified
445together by the same gamma value, preserving colors, and ignoring
446transparency. </p>
447
448
449<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]450 <h3 class="magick-header"><a id="auto-orient"></a>-auto-orient</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]451</div>
452
453<p class="magick-description">adjusts an image so that its orientation is suitable for viewing (i.e. top-left orientation).</p>
454
455<p>This operator reads and resets the EXIF image profile setting 'Orientation'
456and then performs the appropriate 90 degree rotation on the image to orient
457the image, for correct viewing. </p>
458
459<p>This EXIF profile setting is usually set using a gravity sensor in digital
460camera, however photos taken directly downward or upward may not have an
461appropriate value. Also images that have been orientation 'corrected' without
462reseting this setting, may be 'corrected' again resulting in a incorrect
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]463result. If the EXIF profile was previously stripped, the <a href="command-line-options.html#auto-orient">-auto-orient</a> operator will do nothing. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]464
465
466<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]467 <h3 class="magick-header"><a id="average"></a>-average</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]468</div>
469
470<p class="magick-description">Average a set of images.</p>
471
472<p>An error results if the images are not identically sized.</p>
473
474
475<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]476 <h3 class="magick-header"><a id="backdrop"></a>-backdrop</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]477</div>
478
479<p class="magick-description">Display the image centered on a backdrop.</p>
480
481<p>This backdrop covers the entire workstation screen and is useful for hiding
482other X window activity while viewing the image. The color of the backdrop is
483specified as the background color. The color is specified using the format
484described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
485
486<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]487 <h3 class="magick-header"><a id="background"></a>-background <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]488</div>
489
490<p class="magick-description">Set the background color.</p>
491
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]492<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option. The default background color (if none is
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]493specified or found in the image) is white.</p>
494
495<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]496 <h3 class="magick-header"><a id="bench"></a>-bench <var>iterations</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]497</div>
498
499<p class="magick-description">Measure performance.</p>
500
501<p>Repeat the entire command for the given number of <var>iterations</var> and report the user-time and elapsed time. For instance,
502consider the following command and its output. Modify the benchmark with the
503-duration to run the benchmark for a fixed number of seconds and -concurrent
504to run the benchmark in parallel (requires the OpenMP feature).</p>
505
506<pre>
507convert logo: -resize 1000% -bench 5 logo.png
508Performance[4]: 5i 0.875657ips 6.880u 0:05.710
509</pre>
510
511<p>In this example, 5 iterations were completed at 0.875657 iterations per
512second, using 4 threads and 6.88 seconds of the user's allotted time, for
513a total elapsed time of 5.71 seconds.</p>
514
515<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]516 <h3 class="magick-header"><a id="bias"></a>-bias <var>value</var>{<var>%</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]517</div>
518
519<p class="magick-description">Add bias when convolving an image.</p>
520
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]521<p>This option shifts the output of <a href="command-line-options.html#convolve">‑convolve</a> so that
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]522positive and negative results are relative to the specified bias value. </p>
523
524<p>This is important for non-HDRI compilations of ImageMagick when dealing
525with convolutions that contain negative as well as positive values. This is
526especially the case with convolutions involving high pass filters or edge
527detection. Without an output bias, the negative values are clipped at
528zero.</p>
529
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]530<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
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]531negative results without clipping to the color value range
532(0..QuantumRange).</p>
533
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]534<p>See the discussion on HDRI implementations of ImageMagick on the page <a href="high-dynamic-range.html">High Dynamic-Range Images</a>. For more
535about HDRI go the ImageMagick <a href="http://www.imagemagick.org/Usage/basics/#hdri">Usage</a> pages or this
536<a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]537entry. </p>
538
539<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]540 <h3 class="magick-header"><a id="black-point-compensation"></a>-black-point-compensation</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]541</div>
542
543<p class="magick-description">Use black point compensation.</p>
544
545<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]546 <h3 class="magick-header"><a id="black-threshold"></a>-black-threshold <var>value</var>{<var>%</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]547</div>
548
549<p class="magick-description">Force to black all pixels below the threshold while leaving all pixels at or above the threshold unchanged.</p>
550
551<p> The threshold value can be given as a percentage or as an absolute integer
552value within [0, <var>QuantumRange</var>] corresponding to the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]553desired <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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]554
555
556<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]557 <h3 class="magick-header"><a id="blend"></a>-blend <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]558</div>
559
560<p class="magick-description">blend an image into another by the given absolute value or percent.</p>
561
562<p>Blend will average the images together ('plus') according to the
563percentages given and each pixels transparency. If only a single percentage
564value is given it sets the weight of the composite or 'source' image, while
565the background image is weighted by the exact opposite amount. That is a
566<code>-blend 30%</code> merges 30% of the 'source' image with 70% of the
567'destination' image. Thus it is equivalent to <code>-blend 30x70%</code>.</p>
568
569
570<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]571 <h3 class="magick-header"><a id="blue-primary"></a>-blue-primary <var>x</var>,<var>y</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]572</div>
573
574<p class="magick-description">Set the blue chromaticity primary point.</p>
575
576<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]577 <h3 class="magick-header"><a id="blue-shift"></a>-blue-shift <var>factor</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]578</div>
579
580<p class="magick-description">simulate a scene at nighttime in the moonlight. Start with a factor of 1.5</p>
581
582<div style="margin: auto;">
583
584<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]585 <h3 class="magick-header"><a id="blur"></a>-blur <var>radius</var><br>-blur <var>radius</var>x<var>sigma</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]586</div>
587
588<p class="magick-description">Reduce image noise and reduce detail levels.</p>
589
590<p>Convolve the image with a Gaussian or normal distribution using the given
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]591<var>Sigma</var> value. The formula is:</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]592
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]593<div class="eqn"><img alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png">
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]594</div>
595
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]596<p>The <var>Sigma</var> value is the important argument, and
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]597determines the actual amount of blurring that will take place. </p>
598
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]599<p>The <var>Radius</var> is only used to determine the size of the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]600array which will hold the calculated Gaussian distribution. It should be an
601integer. If not given, or set to zero, IM will calculate the largest possible
602radius that will provide meaningful results for the Gaussian distribution.
603</p>
604
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]605<p>The larger the <var>Radius</var> the slower the
606operation is. However too small a <var>Radius</var>, and sever
607aliasing effects may result. As a guideline, <var>Radius</var>
608should be at least twice the <var>Sigma</var> value, though three
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]609times will produce a more accurate result. </p>
610
611<p>This option differs from <a href="command-line-options.html#gaussian-blur">-gaussian-blur</a> simply
612by taking advantage of the separability properties of the distribution. Here
613we apply a single-dimensional Gaussian matrix in the horizontal direction,
614then repeat the process in the vertical direction.</p>
615
616<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how
617pixels which are outside the image proper are blurred into the final result.
618</p>
619
620
621<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]622 <h3 class="magick-header">-blur <var>Width</var>[x<var>Height</var>[+<var>Angle</var>]]</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]623</div>
624
625<p class="magick-description">Variably blur an image according to the overlay mapping.</p>
626
627<p>Each pixel in the overlaid region is replaced with an Elliptical Weighted
628Average (EWA) of the source image, scaled according to the grayscale
629mapping. </p>
630
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]631<p>The ellipse is weighted with sigma set to the given <var>Width</var> and <var>Height</var>. The <var>Height</var>
632defaults to the <var>Width</var> for a normal circular Gaussian
633weighting. The <var>Angle</var> will rotate the ellipse from
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]634horizontal clock-wise. </p>
635
636<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how
637pixels which are outside the image proper are blurred into the final result.
638</p>
639
640
641<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]642 <h3 class="magick-header"><a id="border"></a>-border <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]643</div>
644
645<p class="magick-description">Surround the image with a border of color. </p>
646
647<p>Set the width and height using the <var>size</var> portion of the
648<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
649ignored. </p>
650
651<p>As of IM 6.7.8-8, the <var>geometry</var> arguments behave as follows:</p>
652
653<table id="borderTable">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]654 <col width="20%"> <col width="80%">
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]655 <thead>
656 <tr>
657 <th style="text-align:center"><var>size</var></th>
658 <th>General description</th>
659 </tr>
660 </thead>
661 <tbody>
662 <tr>
663 <td><var>value</var></td>
664 <td>value is added to both left/right and top/bottom</td>
665 </tr>
666 <tr>
667 <td><var>value-x</var>x</td>
668 <td>value-x is added only to left/right and top/bottom are unchanged</td>
669 </tr>
670 <tr>
671 <td>x<var>value-y</var></td>
672 <td>value-y is added only to top/bottom and left/right are unchanged</td>
673 </tr>
674 <tr>
675 <td><var>value-x</var>x<var>value-y</var></td>
676 <td>value-x is added to left/right and value-y added to top/bottom</td>
677 </tr>
678 <tr>
679 <td><var>value-x</var>x<code>0</code></td>
680 <td>value-x is added only to left/right and top/bottom are unchanged</td>
681 </tr>
682 <tr>
683 <td><code>0</code>x<var>value-y</var></td>
684 <td>value-y is added only to top/bottom and left/right are unchanged</td>
685 </tr>
686 <tr>
687 <td> </td>
688 <td> </td>
689 </tr>
690 <tr>
691 <td><var>value</var>%</td>
692 <td>value % of width is added to left/right and value % of height is added to top/bottom</td>
693 </tr>
694 <tr>
695 <td><var>value-x</var>x%</td>
696 <td>value-x % of width is added to left/right and to top/bottom</td>
697 </tr>
698 <tr>
699 <td>x<var>value-y</var>%</td>
700 <td>value-y % of height is added to top/bottom and to left/right</td>
701 </tr>
702 <tr>
703 <td><var>value-x</var>%x<var>value-y</var>%</td>
704 <td>value-x % of width is added to left/right and value-y % of height is added to top/bottom</td>
705 </tr>
706 <tr>
707 <td><var>value-x</var>%x<code>0</code>%</td>
708 <td>value-x % of width is added to left/right and top/bottom are unchanged</td>
709 </tr>
710 <tr>
711 <td><code>0</code>%x<var>value-y</var>%</td>
712 <td>value-y % of height is added to top/bottom and left/right are unchanged</td>
713 </tr>
714 </tbody>
715 </table>
716
717
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]718<p>Set the border color by preceding with the <a href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]719
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]720<p>The <a href="command-line-options.html#border">-border</a> operation is affected by the current <a href="command-line-options.html#compose">-compose</a> setting and assumes that this is using the default
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]721'<code>Over</code>' composition method. It generates an image of the appropriate
722size colors by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> before
723overlaying the original image in the center of this net image. This means that
724with the default compose method of '<code>Over</code>' any transparent parts may
725be replaced by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p>
726<p>See also the <a href="command-line-options.html#frame">-frame</a> option, which has more
727functionality.</p>
728
729<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]730 <h3 class="magick-header"><a id="bordercolor"></a>-bordercolor <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]731</div>
732
733<p class="magick-description">Set the border color.</p>
734
735<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
736
737<p>The default border color is <code>#DFDFDF</code>, <span style="background-color: #dfdfdf;">this shade of gray</span>.</p>
738
739<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]740 <h3 class="magick-header"><a id="borderwidth"></a>-borderwidth <var>geometry</var> </h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]741</div>
742
743<p class="magick-description">Set the border width.</p>
744
745<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]746 <h3 class="magick-header"><a id="brightness-contrast"></a>-brightness-contrast <var>brightness</var><br>-brightness-contrast <var>brightness</var>{x<var>contrast</var>}{<var>%</var>}}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]747</div>
748
749<p class="magick-description">Adjust the brightness and/or contrast of the image.</p>
750
751<p>Brightness and Contrast values apply changes to the input image. They are
752not absolute settings. A brightness or contrast value of zero means no change.
753The range of values is -100 to +100 on each. Positive values increase the
754brightness or contrast and negative values decrease the brightness or contrast.
755To control only contrast, set the brightness=0. To control only brightness,
756set contrast=0 or just leave it off.</p>
757
758<p>You may also use <a href="command-line-options.html#fill">-channel</a> to control which channels to
759apply the brightness and/or contrast change. The default is to apply the same
760transformation to all channels.</p>
761
762<p>Brightness and Contrast arguments are converted to offset and slope of a
763linear transform and applied
764using <a href="command-line-options.html#fill">-function polynomial "slope,offset"</a>.</p>
765
766<p>The slope varies from 0 at contrast=-100 to almost vertical at
767contrast=+100. For brightness=0 and contrast=-100, the result are totally
768midgray. For brightness=0 and contrast=+100, the result will approach but
769not quite reach a threshold at midgray; that is the linear transformation
770is a very steep vertical line at mid gray.</p>
771
772<p>Negative slopes, i.e. negating the image, are not possible with this
773function. All achievable slopes are zero or positive.</p>
774
775<p>The offset varies from -0.5 at brightness=-100 to 0 at brightness=0 to +0.5
776at brightness=+100. Thus, when contrast=0 and brightness=100, the result is
777totally white. Similarly, when contrast=0 and brightness=-100, the result is
778totally black.</p>
779
780<p>As the range of values for the arguments are -100 to +100, adding the '%'
781symbol is no different than leaving it off.</p>
782
783<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]784 <h3 class="magick-header"><a id="cache"></a>-cache <var>threshold</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]785</div>
786
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]787<p class="magick-description">(This option has been replaced by the <a href="command-line-options.html#limit">-limit</a> option).</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]788
789<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]790 <h3 class="magick-header"><a id="canny"></a>-canny <var>radius</var><br>-canny <var>radius</var>x<var>sigma</var>{<var>+lower-percent</var>}{<var>+upper-percent</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]791</div>
792
793<p class="magick-description">Canny edge detector uses a multi-stage algorithm to detect a wide range of edges in the image.</p>
794
795<p>The thresholds range from 0 to 100% (e.g. -canny 0x1+10%+30%) with {<var>+lower-percent</var>} &lt; {<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>
796
797<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]798 <h3 class="magick-header"><a id="caption"></a>-caption <var>string</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]799</div>
800
801<p class="magick-description">Assign a caption to an image.</p>
802
803<p>This option sets the caption meta-data of an image read in after this
804option has been given. To modify a caption of images already in memory use
805"<code><a href="command-line-options.html#set">-set</a> caption</code>". </p>
806
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]807<p>The caption can contain special format characters listed in the <a href="escape.html">Format and
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]808Print Image Properties</a>. These attributes are expanded when the caption
809is finally assigned to the individual images. </p>
810
811<p>If the first character of <var>string</var> is <var>@</var>, the image caption is read from a file titled by the
812remaining characters in the string. Comments read in from a file are literal;
813no embedded formatting characters are recognized.</p>
814
815<p>Caption meta-data is not visible on the image itself. To do that use the
816<a href="command-line-options.html#annotate">-annotate</a> or <a href="command-line-options.html#draw">-draw</a> options
817instead.</p>
818
819<p>For example,</p>
820
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]821<pre>
822-caption "%m:%f %wx%h" bird.miff
823</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]824
825<p>produces an image caption of <code>MIFF:bird.miff 512x480</code> (assuming
826that the image <code>bird.miff</code> has a width of 512 and a height of
827480.</p>
828
829
830<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]831 <h3 class="magick-header"><a id="cdl"></a>-cdl <var>filename</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]832</div>
833
834<p class="magick-description">color correct with a color decision list.</p>
835
836<p>Here is an example color correction collection:</p>
837
838<pre>
839&lt;?xml version="1.0" encoding="UTF-8"?&gt;
840&lt;ColorCorrectionCollection xmlns="urn:ASC:CDL:v1.2"&gt;
841 &lt;ColorCorrection id="cc06668"&gt;
842 &lt;SOPNode&gt;
843 &lt;Slope&gt; 0.9 1.2 0.5 &lt;/Slope&gt;
844 &lt;Offset&gt; 0.4 -0.5 0.6 &lt;/Offset&gt;
845 &lt;Power&gt; 1.0 0.8 1.5 &lt;/Power&gt;
846 &lt;/SOPNode&gt;
847 &lt;SATNode&gt;
848 &lt;Saturation&gt; 0.85 &lt;/Saturation&gt;
849 &lt;/SATNode&gt;
850 &lt;/ColorCorrection&gt;
851&lt;/ColorCorrectionCollection&gt;
852</pre>
853
854<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]855 <h3 class="magick-header"><a id="channel"></a>-channel <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]856</div>
857
858<p class="magick-description">Specify those image color channels to which subsequent operators are limited.</p>
859
860<p>Choose from: <code>Red</code>, <code>Green</code>, <code>Blue</code>,
861<code>Alpha</code>, <code>Gray</code>, <code>Cyan</code>, <code>Magenta</code>,
862<code>Yellow</code>, <code>Black</code>, <code>Opacity</code>,
863<code>Index</code>, <code>RGB</code>, <code>RGBA</code>, <code>CMYK</code>, or
864<code>CMYKA</code>.</p>
865
866<p>The channels above can also be specified as a comma-separated list or can be
867abbreviated as a concatenation of the letters '<code>R</code>', '<code>G</code>',
868'<code>B</code>', '<code>A</code>', '<code>O</code>', '<code>C</code>',
869'<code>M</code>', '<code>Y</code>', '<code>K</code>'.
870
871For example, to only select the <code>Red</code> and <code>Blue</code> channels
872you can either use </p>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]873<pre>
874-channel Red,Blue
875</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]876<p>or you can use the short hand form</p>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]877<pre>
878-channel RB
879</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]880
881<p>All the channels that are present in an image can be specified using the
882special channel type <code>All</code>. Not all operators are 'channel capable',
883but generally any operators that are generally 'grey-scale' image operators,
884will understand this setting. See individual operator documentation. </p>
885
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]886<br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]887
888<p>On top of the normal channel selection an extra flag can be specified,
889'<code>Sync</code>'. This is turned on by default and if set means that
890operators that understand this flag should perform: cross-channel
891synchronization of the channels. If not specified, then most grey-scale
892operators will apply their image processing operations to each individual
893channel (as specified by the rest of the <a href="command-line-options.html#channel">-channel</a>
894setting) completely independently from each other. </p>
895
896<p>For example for operators such as <a href="command-line-options.html#auto-level">-auto-level</a> and
897<a href="command-line-options.html#auto-gamma">-auto-gamma</a> the color channels are modified
898together in exactly the same way so that colors will remain in-sync. Without
899it being set, then each channel is modified separately and
900independently, which may produce color distortion. </p>
901
902<p>The <a href="command-line-options.html#morphology">-morphology</a> '<code>Convolve</code>' method
903and the <a href="command-line-options.html#compose">-compose</a> mathematical methods, also understands
904the '<code>Sync</code>' flag to modify the behaviour of pixel colors according
905to the alpha channel (if present). That is to say it will modify the image
906processing with the understanding that fully-transparent colors should not
907contribute to the final result. </p>
908
909<p>Basically, by default, operators work with color channels in synchronous, and
910treats transparency as special, unless the <a href="command-line-options.html#channel">-channel</a>
911setting is modified so as to remove the effect of the '<code>Sync</code>' flag.
912How each operator does this depends on that operators current implementation.
913Not all operators understands this flag at this time, but that is changing.
914</p>
915
916<p>To print a complete list of channel types, use <a href="command-line-options.html#list">-list
917channel</a>.</p>
918
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]919<br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]920
921<p>By default, ImageMagick sets <a href="command-line-options.html#channel">-channel</a> to the value
922'<code>RGBK,sync</code>', which specifies that operators act on all color
923channels except the transparency channel, and that all the color channels are
924to be modified in exactly the same way, with an understanding of transparency
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]925(depending on the operation being applied). The 'plus' form <a href="command-line-options.html#channel">+channel</a> will reset the value back to this default. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]926
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]927<p>Options that are affected by the <a href="command-line-options.html#channel">-channel</a> setting
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]928include the following.
929
930<a href="command-line-options.html#auto-gamma">-auto-gamma</a>,
931<a href="command-line-options.html#auto-level">-auto-level</a>,
932<a href="command-line-options.html#black-threshold">-black-threshold</a>,
933<a href="command-line-options.html#blur">-blur</a>,
934<a href="command-line-options.html#clamp">-clamp</a>,
935<a href="command-line-options.html#clut">-clut</a>,
936<a href="command-line-options.html#combine">-combine</a>,
937<a href="command-line-options.html#composite">-composite</a> (Mathematical compose methods only),
938<a href="command-line-options.html#convolve">-convolve</a>,
939<a href="command-line-options.html#contrast-stretch">-contrast-stretch</a>,
940<a href="command-line-options.html#evaluate">-evaluate</a>,
941<a href="command-line-options.html#function">-function</a>,
942<a href="command-line-options.html#fx">-fx</a>,
943<a href="command-line-options.html#gaussian-blur">-gaussian-blur</a>,
944<a href="command-line-options.html#hald-clut">-hald-clut</a>,
945<a href="command-line-options.html#motion-blur">-motion-blur</a>,
946<a href="command-line-options.html#morphology">-morphology</a>,
947<a href="command-line-options.html#negate">-negate</a>,
948<a href="command-line-options.html#normalize">-normalize</a>,
949<a href="command-line-options.html#ordered-dither">-ordered-dither</a>,
950<a href="command-line-options.html#radial-blur">-radial-blur</a>,
951<a href="command-line-options.html#random-threshold">-random-threshold</a>,
952<a href="command-line-options.html#separate">-separate</a>,
953<a href="command-line-options.html#threshold">-threshold</a>, and
954<a href="command-line-options.html#white-threshold">-white-threshold</a>.
955</p>
956
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]957<p>Warning, some operators behave differently when the <a href="command-line-options.html#channel">+channel</a> default setting is in effect, verses ANY user defined <a href="command-line-options.html#channel">-channel</a> setting (including the equivalent of the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]958default). These operators have yet to be made to understand the newer 'Sync'
959flag. </p>
960
961<p>For example <a href="command-line-options.html#threshold">-threshold</a> will by default gray-scale
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]962the image before thresholding, if no <a href="command-line-options.html#channel">-channel</a> setting
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]963has been defined. This is not 'Sync flag controlled, yet. </p>
964
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]965<p>Also some operators such as <a href="command-line-options.html#blur">-blur</a>, <a href="command-line-options.html#gaussian-blur">-gaussian-blur</a>, will modify their handling of the
966color channels if the '<code>alpha</code>' channel is also enabled by <a href="command-line-options.html#channel">-channel</a>. Generally this done to ensure that
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]967fully-transparent colors are treated as being fully-transparent, and thus any
968underlying 'hidden' color has no effect on the final results. Typically
969resulting in 'halo' effects. The newer <a href="command-line-options.html#morphology">-morphology</a>
970convolution equivalents however does have a understanding of the 'Sync' flag
971and will thus handle transparency correctly by default. </p>
972
973<p>As a alpha channel is optional within images, some operators will read the
974color channels of an image as a greyscale alpha mask, when the image has no
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]975alpha channel present, and the <a href="command-line-options.html#channel">-channel</a> setting tells
976the operator to apply the operation using alpha channels. The <a href="command-line-options.html#clut">-clut</a> operator is a good example of this. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]977
978
979
980<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]981 <h3 class="magick-header"><a id="charcoal"></a>-charcoal <var>factor</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]982</div>
983
984<p class="magick-description">Simulate a charcoal drawing.</p>
985
986<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]987 <h3 class="magick-header"><a id="chop"></a>-chop <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]988</div>
989
990<p class="magick-description">Remove pixels from the interior of an image.</p>
991
992<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>
993and <var>height</var> given in the of the <var>size</var>
994portion of the <var>geometry</var> argument give the number of
995columns and rows to remove. The <var>offset</var> portion of
996the <var>geometry</var> argument is influenced by
997a <a href="command-line-options.html#gravity">-gravity</a> setting, if present.</p>
998
999<p>The <a href="command-line-options.html#chop">-chop</a> option removes entire rows and columns,
1000and moves the remaining corner blocks leftward and upward to close the gaps.</p>
1001
1002<p>While it can remove internal rows and columns of pixels, it is more
1003typically used with as <a href="command-line-options.html#gravity">-gravity</a> setting and zero
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1004offsets so as to remove a single edge from an image. Compare this to <a href="command-line-options.html#shave">-shave</a> which removes equal numbers of pixels from oppisite
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1005sides of the image. </p>
1006
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1007<p>Using <a href="command-line-options.html#chop">-chop</a> effectively undoes the results of a <a href="command-line-options.html#splice">-splice</a> that was given the same <var>geometry</var> and <a href="command-line-options.html#gravity">-gravity</a> settings. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1008
1009<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1010 <h3 class="magick-header"><a id="clamp"></a>-clamp</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1011</div>
1012
1013<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>
1014
1015<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1016 <h3 class="magick-header"><a id="clip"></a>-clip</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1017</div>
1018
1019<p class="magick-description">Apply the clipping path if one is present.</p>
1020
1021<p>If a clipping path is present, it is applied to subsequent operations.</p>
1022
1023<p>For example, in the command</p>
1024
1025<pre>
1026convert cockatoo.tif -clip -negate negated.tif
1027</pre>
1028
1029<p>only the pixels within the clipping path are negated.</p>
1030
1031<p>The <a href="command-line-options.html#clip">-clip</a> feature requires SVG support. If the SVG
1032delegate library is not present, the option is ignored.</p>
1033
1034<p>Use <a href="command-line-options.html#clip">+clip</a> to disable clipping for subsequent operations.</p>
1035
1036<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1037 <h3 class="magick-header"><a id="clip-mask"></a>-clip-mask</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1038</div>
1039
1040<p class="magick-description">Clip the image as defined by this mask.</p>
1041
1042<p>Use the alpha channel of the current image as a mask. Any areas that is
1043white is not modified by any of the 'image processing operators' that follow,
1044until the mask is removed. Pixels in the black areas of the clip mask are
1045modified per the requirements of the operator. </p>
1046
1047<p>In some ways this is similar to (though not the same) as defining
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1048a rectangular <a href="command-line-options.html#region">-region</a>, or using the negative of the
1049mask (third) image in a three image <a href="command-line-options.html#composite">-composite</a>,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1050operation. </p>
1051
1052<p>Use <a href="command-line-options.html#clip-mask">+clip-mask</a> to disable clipping for subsequent operations.</p>
1053
1054<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1055 <h3 class="magick-header"><a id="clip-path"></a>-clip-path <var>id</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1056</div>
1057
1058<p class="magick-description">Clip along a named path from the 8BIM profile.</p>
1059
1060<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>
1061
1062<p>Use <a href="command-line-options.html#clip-path">+clip-path</a> to disable clipping for subsequent operations.</p>
1063
1064<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1065 <h3 class="magick-header"><a id="clone"></a>-clone <var>index(s)</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1066</div>
1067
1068<p class="magick-description">make a clone of an image (or images).</p>
1069
1070<p>Inside parenthesis (where the operator is normally used) it will make a
1071clone of the images from the last 'pushed' image sequence, and adds them to
1072the end of the current image sequence. Outside parenthesis
1073(not recommended) it clones the images from the current image sequence. </p>
1074
1075<p>Specify the image by its index in the sequence. The first image is index
10760. Negative indexes are relative to the end of the sequence; for
1077example, <code>−1</code>
1078represents the last image of the sequence. Specify a range of images with a
1079dash (e.g. <code>0−4</code>). Separate multiple indexes with commas but no
1080spaces (e.g. <code>0,2,5</code>). A value of '<code>0−−1</code> will
1081effectively clone all the images. </p>
1082
1083<p>The <a href="command-line-options.html#clone">+clone</a> will simply make a copy of the last image
1084in the image sequence, and is thus equivalent to using a argument of
1085'<code>−1</code>'. </p>
1086
1087<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1088 <h3 class="magick-header"><a id="clut"></a>-clut</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1089</div>
1090
1091<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>
1092
1093<p>The second (LUT) image is ordinarily a gradient image containing the
1094histogram mapping of how each channel should be modified. Typically it is a
1095either a single row or column image of replacement color values. If larger
1096than a single row or column, values are taken from a diagonal line from
1097top-left to bottom-right corners.</p>
1098
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1099<p>The lookup is further controlled by the <a href="command-line-options.html#interpolate">-interpolate</a> setting, which is especially handy for an
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1100LUT which is not the full length needed by the ImageMagick installed Quality
1101(Q) level. Good settings for this are the '<code>bilinear</code>' and
1102'<code>bicubic</code>' interpolation settings, which give smooth color
1103gradients, and the '<code>integer</code>' setting for a direct, unsmoothed
1104lookup of color values. </p>
1105
1106<p>This operator is especially suited to replacing a grayscale image with a
1107specific color gradient from the CLUT image. </p>
1108
1109<p>Only the channel values defined by the <a href="command-line-options.html#channel">-channel</a>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1110setting will have their values replaced. In particular, since the default <a href="command-line-options.html#channel">-channel</a> setting is <code>RGB</code>, this means that
1111transparency (alpha/matte channel) is not affected, unless the <a href="command-line-options.html#channel">-channel</a> setting is modified. When the alpha channel is
1112set, it is treated by the <a href="command-line-options.html#clut">-clut</a> operator in the same way
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1113as the other channels, implying that alpha/matte values are replaced using the
1114alpha/matte values of the original image. </p>
1115
1116<p>If either the image being modified, or the lookup image, contains no
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1117transparency (i.e. <a href="command-line-options.html#alpha">-alpha</a> is turned 'off') but the <a href="command-line-options.html#channel">-channel</a> setting includes alpha replacement, then it is
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1118assumed that image represents a gray-scale gradient which is used for the
1119replacement alpha values. That is you can use a gray-scale CLUT image to
1120adjust a existing images alpha channel, or you can color a gray-scale image
1121using colors form CLUT containing the desired colors, including transparency.
1122</p>
1123
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1124<p>See also <a href="command-line-options.html#hald-clut">-hald-clut</a> which replaces colors
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1125according to the lookup of the full color RGB value from a 2D representation
1126of a 3D color cube. </p>
1127
1128
1129<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1130 <h3 class="magick-header"><a id="coalesce"></a>-coalesce</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1131</div>
1132
1133<p class="magick-description">Fully define the look of each frame of an GIF animation sequence, to form a 'film strip' animation.</p>
1134
1135<p>Overlay each image in an image sequence according to
1136its <a href="command-line-options.html#dispose">-dispose</a> meta-data, to reproduce the look of
1137an animation at each point in the animation sequence. All images should be
1138the same size, and are assigned appropriate GIF disposal settings for the
1139animation to continue working as expected as a GIF animation. Such frames
1140are more easily viewed and processed than the highly optimized GIF overlay
1141images. </p>
1142
1143<p>The animation can be re-optimized after processing using
1144the <a href="command-line-options.html#layers">-layers</a> method '<code>optimize</code>', although
1145there is no guarantee that the restored GIF animation optimization is
1146better than the original. </p>
1147
1148
1149<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1150 <h3 class="magick-header"><a id="colorize"></a>-colorize <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1151</div>
1152
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1153<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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1154
1155<p>Specify the amount of colorization as a percentage. Separate colorization
1156values can be applied to the red, green, and blue channels of the image with
1157a comma-delimited list of colorization
1158values (e.g., <code>-colorize 0,0,50</code>).</p>
1159
1160<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1161 <h3 class="magick-header"><a id="colormap"></a>-colormap <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1162</div>
1163
1164<p class="magick-description">Define the colormap type.</p>
1165
1166<p>The <var>type</var> can be <code>shared</code> or <code>private</code>.</p>
1167
1168<p>This option only applies when the default X server visual
1169is <code>PseudoColor</code> or <code>GrayScale</code>. Refer
1170to <a href="command-line-options.html#visual">-visual</a> for more details. By default,
1171a shared colormap is allocated. The image shares colors with
1172other X clients. Some image colors could be approximated,
1173therefore your image may look very different than intended.
1174If <code>private</code> is chosen, the image colors appear exactly
1175as they are defined. However, other clients may go <var>technicolor</var>
1176when the image colormap is installed.</p>
1177
1178<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1179 <h3 class="magick-header"><a id="colors"></a>-colors <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1180</div>
1181
1182<p class="magick-description">Set the preferred number of colors in the image.</p>
1183
1184<p>The actual number of colors in the image may be less than your request,
1185but never more. Note that this a color reduction option. Images with fewer
1186unique colors than specified by <var>value</var> will have any
1187duplicate or unused colors removed. The ordering of an existing color
1188palette may be altered. When converting an image from color to grayscale,
1189it is more efficient to convert the image to the gray colorspace before
1190reducing the number of colors. Refer to
1191the <a href="quantize.html">
1192color reduction algorithm</a> for more details.</p>
1193
1194<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1195 <h3 class="magick-header"><a id="color-matrix"></a>-color-matrix <var>matrix</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1196</div>
1197
1198<p class="magick-description">apply color correction to the image.</p>
1199
1200<p>This option permits saturation changes, hue rotation, luminance to alpha,
1201and various other effects. Although variable-sized transformation matrices
1202can be used, typically one uses a 5x5 matrix for an RGBA image and a 6x6
1203for CMYKA (or RGBA with offsets). The matrix is similar to those used by
1204Adobe Flash except offsets are in column 6 rather than 5 (in support of
1205CMYKA images) and offsets are normalized (divide Flash offset by 255).</p>
1206
1207<p>As an example, to add contrast to an image with offsets, try this command:</p>
1208
1209<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1210convert kittens.jpg -color-matrix \
1211 " 1.5 0.0 0.0 0.0, 0.0, -0.157 \
1212 0.0 1.5 0.0 0.0, 0.0, -0.157 \
1213 0.0 0.0 1.5 0.0, 0.0, -0.157 \
1214 0.0 0.0 0.0 1.0, 0.0, 0.0 \
1215 0.0 0.0 0.0 0.0, 1.0, 0.0 \
1216 0.0 0.0 0.0 0.0, 0.0, 1.0" kittens.png
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1217</pre>
1218<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1219 <h3 class="magick-header"><a id="colorspace"></a>-colorspace <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1220</div>
1221
1222<p class="magick-description">Set the image colorspace.</p>
1223
1224<p>Choices are:</p>
1225
1226<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1227CMY CMYK Gray HCL
1228HCLp HSB HSI HSL
1229HSV HWB Lab LCHab
1230LCHuv LMS Log Luv
1231OHTA Rec601YCbCr Rec709YCbCr RGB
1232scRGB sRGB Transparent xyY
1233XYZ YCbCr YCC YDbDr
1234YIQ YPbPr YUV
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1235</pre>
1236
1237<p>To print a complete list of colorspaces, use <a href="command-line-options.html#list">-list colorspace</a>.</p>
1238
1239<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>
1240
1241<table class="table table-condensed table-striped">
1242 <caption>Conversion of RGB to Other Color Spaces</caption>
1243 <tr><th valign="middle">CMY</th></tr>
1244 <tr><td valign="middle">C=<var>QuantumRange</var>−R</td></tr>
1245 <tr><td valign="middle">M=<var>QuantumRange</var>−G</td></tr>
1246 <tr><td valign="middle">Y=<var>QuantumRange</var>−B</td></tr>
1247 <tr><th valign="middle">CMYK — starts with CMY from above</th></tr>
1248 <tr><td valign="middle">K=min(C,Y,M)</td></tr>
1249 <tr><td valign="middle">C=<var>QuantumRange</var>*(C−K)/(<var>QuantumRange</var>−K)</td></tr>
1250 <tr><td valign="middle">M=<var>QuantumRange</var>*(M−K)/(<var>QuantumRange</var>−K)</td></tr>
1251 <tr><td valign="middle">Y=<var>QuantumRange</var>*(Y−K)/(<var>QuantumRange</var>−K)</td></tr>
1252
1253 <tr><th valign="middle">Gray</th></tr>
1254 <tr><td valign="middle">Gray = 0.298839*R+0.586811*G+0.114350*B</td></tr>
1255
1256 <tr><th valign="middle">HSB — Hue, Saturation, Brightness; like a cone peak downward</th></tr>
1257 <tr><td valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr>
1258 <tr><td valign="middle">S=distance from axis outward</td></tr>
1259 <tr><td valign="middle">B=distance along axis from bottom upward; B=max(R,G,B); <var>intensity-like</var></td></tr>
1260
1261 <tr><th valign="middle">HSL — Hue, Saturation, Lightness; like a double cone end-to-end with peaks at very top and bottom</th></tr>
1262 <tr><td valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr>
1263 <tr><td valign="middle">S=distance from axis outward</td></tr>
1264 <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>
1265
1266 <tr><th valign="middle">HWB — Hue, Whiteness, Blackness</th></tr>
1267 <tr><td valign="middle">Hue (complicated equation)</td></tr>
1268 <tr><td valign="middle">Whiteness (complicated equation)</td></tr>
1269 <tr><td valign="middle">Blackness (complicated equation)</td></tr>
1270
1271 <tr><th valign="middle">LAB</th></tr>
1272 <tr><td valign="middle">L (complicated equation relating X,Y,Z)</td></tr>
1273 <tr><td valign="middle">A (complicated equation relating X,Y,Z)</td></tr>
1274 <tr><td valign="middle">B (complicated equation relating X,Y,Z)</td></tr>
1275
1276 <tr><th valign="middle">LOG</th></tr>
1277 <tr><td valign="middle">I1 (complicated equation involving logarithm of R)</td></tr>
1278 <tr><td valign="middle">I2 (complicated equation involving logarithm of G)</td></tr>
1279 <tr><td valign="middle">I3 (complicated equation involving logarithm of B)</td></tr>
1280
1281 <tr><th valign="middle">OHTA — approximates principal components transformation</th></tr>
1282 <tr><td valign="middle">I1=0.33333*R+0.33334*G+0.33333*B; <var>intensity-like</var></td></tr>
1283 <tr><td valign="middle">I2=(0.50000*R+0.00000*G−0.50000*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1284 <tr><td valign="middle">I3=(−0.25000*R+0.50000*G−0.25000*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1285
1286 <tr><th valign="middle">Rec601Luma</th></tr>
1287 <tr><td valign="middle">Gray = 0.298839*R+0.586811*G+0.114350*B</td></tr>
1288
1289 <tr><th valign="middle">Rec601YCbCr</th></tr>
1290 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr>
1291 <tr><td valign="middle">Cb=(−0.168736*R-0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1292 <tr><td valign="middle">Cr=(0.500000*R−0.418688*G−0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1293
1294 <tr><th valign="middle">Rec709Luma</th></tr>
1295 <tr><td valign="middle">Gray=0.212656*R+0.715158*G+0.072186*B</td></tr>
1296
1297 <tr><th valign="middle">Rec709YCbCr</th></tr>
1298 <tr><td valign="middle">Y=0.212656*R+0.715158*G+0.072186*B; <var>intensity-like</var></td></tr>
1299 <tr><td valign="middle">Cb=(−0.114572*R−0.385428*G+0.500000*B)+(<var>QuantumRange</var>+1)/2</td></tr>
1300 <tr><td valign="middle">Cr=(0.500000*R−0.454153*G−0.045847*B)+(<var>QuantumRange</var>+1)/2</td></tr>
1301
1302 <tr><th valign="middle">sRGB</th></tr>
1303 <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>
1304 <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>
1305 <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>
1306
1307 <tr><th valign="middle">XYZ</th></tr>
1308 <tr><td valign="middle">X=0.4124564*R+0.3575761*G+0.1804375*B</td></tr>
1309 <tr><td valign="middle">Y=0.2126729*R+0.7151522*G+0.0721750*B</td></tr>
1310 <tr><td valign="middle">Z=0.0193339*R+0.1191920*G+0.9503041*B</td></tr>
1311
1312 <tr><th valign="middle">YCC</th></tr>
1313 <tr><td valign="middle">Y=(0.298839*R+0.586811*G+0.114350*B) (with complicated scaling); <var>intensity-like</var></td></tr>
1314 <tr><td valign="middle">C1=(−0.298839*R−0.586811*G+0.88600*B) (with complicated scaling)</td></tr>
1315 <tr><td valign="middle">C2=(0.70100*R−0.586811*G−0.114350*B) (with complicated scaling)</td></tr>
1316
1317 <tr><th valign="middle">YCbCr</th></tr>
1318 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr>
1319 <tr><td valign="middle">Cb=(−0.168736*R−0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1320 <tr><td valign="middle">Cr=(0.500000*R−0.418688*G−0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1321
1322 <tr><th valign="middle">YIQ</th></tr>
1323 <tr><td valign="middle">Y=0.298839*R+0.586811*G+0.114350*B; <var>intensity-like</var></td></tr>
1324 <tr><td valign="middle">I=(0.59600*R−0.27400*G−0.32200*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1325 <tr><td valign="middle">Q=(0.21100*R−0.52300*G+0.31200*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1326
1327 <tr><th valign="middle">YPbPr</th></tr>
1328 <tr><td valign="middle">Y=0.2988390*R+0.5868110*G+0.1143500*B; <var>intensity-like</var></td></tr>
1329 <tr><td valign="middle">Pb=(−0.168736*R−0.331264*G+0.500000*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1330 <tr><td valign="middle">Pr=(0.500000*R−0.418688*G−0.081312*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1331
1332 <tr><th valign="middle">YUV</th></tr>
1333 <tr><td valign="middle">Y=0.298839*R+0.586811*G+0.114350*B; <var>intensity-like</var></td></tr>
1334 <tr><td valign="middle">U=(−0.14740*R−0.28950*G+0.43690*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1335 <tr><td valign="middle">V=(0.61500*R−0.51500*G−0.10000*B)*(<var>QuantumRange</var>+1)/2</td></tr>
1336</table>
1337
1338<p>Note the scRGB colorspace requires HDRI support otherwise it behaves just like linear RGB.</p>
1339
1340<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1341 <h3 class="magick-header"><a id="combine"></a>-combine</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1342</div>
1343
1344<p class="magick-description">Combine one or more images into a single image.</p>
1345
1346<p>The channels (previously set by <a href="command-line-options.html#channel">-channel</a>) of the
1347combined image are taken from the grayscale values of each image in the
1348sequence, in order. For the default -channel setting of <code>RGB</code>, this
1349means the first image is assigned to the <code>Red</code> channel, the second
1350to the <code>Green</code> channel, the third to the <code>Blue</code>.</p>
1351
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1352<p>This option can be thought of as the inverse to <a href="command-line-options.html#separate">-separate</a>, so long as the channel settings are the same.
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1353Thus, in the following example, the final image should be a copy of the
1354original. </p>
1355
1356<pre>
1357convert original.png -channel RGB -separate sepimage.png
1358convert sepimage-0.png sepimage-1.png sepimage-2.png -channel RGB \
1359 -combine imagecopy.png
1360</pre>
1361
1362<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1363 <h3 class="magick-header"><a id="comment"></a>-comment <var>string</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1364</div>
1365
1366<p class="magick-description">Embed a comment in an image.</p>
1367
1368<p>This option sets the comment meta-data of an image read in after this
1369option has been given. To modify a comment of images already in memory use
1370"<code><a href="command-line-options.html#set">-set</a> comment</code>". </p>
1371
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1372<p>The comment can contain special format characters listed in the <a href="escape.html">Format and
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1373Print Image Properties</a>. These attributes are expanded when the comment
1374is finally assigned to the individual images. </p>
1375
1376<p>If the first character of <var>string</var> is <var>@</var>, the image comment is read from a file titled by the
1377remaining characters in the string. Comments read in from a file are literal;
1378no embedded formatting characters are recognized.</p>
1379
1380<p>Comment meta-data are not visible on the image itself. To do that use the
1381<a href="command-line-options.html#annotate">-annotate</a> or <a href="command-line-options.html#draw">-draw</a> options
1382instead.</p>
1383
1384<p>For example,</p>
1385
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1386<pre>
1387-comment "%m:%f %wx%h" bird.miff
1388</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1389
1390<p>produces an image comment of <code>MIFF:bird.miff 512x480</code> (assuming
1391that the image <code>bird.miff</code> has a width of 512 and a height of
1392480.</p>
1393
1394<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1395 <h3 class="magick-header"><a id="compare"></a>-compare</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1396</div>
1397
1398<p class="magick-description">mathematically and visually annotate the difference between an image and its reconstruction</p>
1399
1400<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>
1401
1402<pre>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1403convert image.png reference.png -metric RMSE -compare \ <br> difference.png
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1404</pre>
1405
1406<p>To get the metric value use the string format "%[distortion]".</p>
1407
1408<pre>
1409convert image.png reference.png -metric RMSE -compare -format \
1410 "%[distortion]" info:
1411</pre>
1412
1413<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1414 <h3 class="magick-header"><a id="complex"></a>-complex <var>operator</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1415</div>
1416
1417<p class="magick-description">perform complex mathematics on an image sequence</p>
1418
1419Choose from these operators:
1420
1421<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1422add
1423conjugate
1424divide
1425magnuitude-phase
1426multiply
1427real-imaginary
1428subtract
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1429</pre>
1430
1431<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>
1432
1433<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1434 <h3 class="magick-header"><a id="compose"></a>-compose <var>operator</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1435</div>
1436
1437<p class="magick-description">Set the type of image composition.</p>
1438
1439<p>See <a href="compose.html">Alpha Compositing</a> for
1440a detailed discussion of alpha compositing.</p>
1441
1442<p>This setting effects image processing operators that merge two (or more)
1443images together in some way. This includes the operators,
1444<a href="command-line-options.html#composite">-compare</a>,
1445<a href="command-line-options.html#composite">-composite</a>,
1446<a href="command-line-options.html#layers">-layers</a> composite,
1447<a href="command-line-options.html#flatten">-flatten</a>,
1448<a href="command-line-options.html#mosaic">-mosaic</a>,
1449<a href="command-line-options.html#layers">-layers</a> merge,
1450<a href="command-line-options.html#border">-border</a>,
1451<a href="command-line-options.html#frame">-frame</a>,
1452and <a href="command-line-options.html#extent">-extent</a>. </p>
1453
1454<p>It is also one of the primary options for the "<code>composite</code>"
1455command. </p>
1456
1457
1458<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1459 <h3 class="magick-header"><a id="composite"></a>-composite</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1460</div>
1461
1462<p class="magick-description">Perform alpha composition on two images and an optional mask</p>
1463
1464<p>Take the first image 'destination' and overlay the second 'source' image
1465according to the current <a href="command-line-options.html#compose">-compose</a> setting. The location
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1466of the 'source' or 'overlay' image is controlled according to <a href="command-line-options.html#geometry">-geometry</a>, and <a href="command-line-options.html#geometry">-geometry</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1467settings. </p>
1468
1469<p>If a third image is given this is treated as a gray-scale blending 'mask' image
1470relative to the first 'destination' image. This mask is blended with the
1471source image. However for the '<code>displace</code>' compose method, the
1472mask is used to provide a separate Y-displacement image instead. </p>
1473
1474<p>If a <a href="command-line-options.html#compose">-compose</a> method requires extra numerical
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1475arguments or flags these can be provided by setting the <a href="command-line-options.html#set">-set</a> '<code>option:compose:args</code>'
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1476appropriately for the compose method. </p>
1477
1478<p>Some <a href="command-line-options.html#compose">-compose</a> methods can modify the 'destination'
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1479image outside the overlay area. You can disable this by setting the special <a href="command-line-options.html#set">-set</a> '<code>option:compose:outside-overlay</code>'
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1480to '<code>false</code>'. </p>
1481
1482<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>
1483
1484
1485<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1486 <h3 class="magick-header"><a id="compress"></a>-compress <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1487</div>
1488
1489<p class="magick-description">Use pixel compression specified by <var>type</var> when writing the image.</p>
1490
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1491<p>Choices are: <code>None</code>, <code>BZip</code>, <code>Fax</code>, <code>Group4</code>, <code>JPEG</code>, <code>JPEG2000</code>, <code>Lossless</code>, <code>LZW</code>, <code>RLE</code> or <code>Zip</code>.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1492
1493<p>To print a complete list of compression types, use <a href="command-line-options.html#list">-list
1494compress</a>.</p>
1495
1496<p>Specify <a href="command-line-options.html#compress">+compress</a> to store the binary image in an
1497uncompressed format. The default is the compression type of the specified
1498image file.</p>
1499
1500<p>If <code>LZW</code> compression is specified but LZW compression has not been
1501enabled, the image data is written in an uncompressed LZW format that can be
1502read by LZW decoders. This may result in larger-than-expected GIF files.</p>
1503
1504<p><code>Lossless</code> refers to lossless JPEG, which is only available if the
1505JPEG library has been patched to support it. Use of lossless JPEG is generally
1506not recommended.</p>
1507
1508<p>
1509When writing an ICO file, you may request that the images be encoded in
1510PNG format, by specifying <code>Zip</code> compression.</p>
1511
1512<p>
1513When writing a JNG file, specify <code>Zip</code> compression to request that
1514the alpha channel be encoded in PNG "IDAT" format, or <code>JPEG</code>
1515to request that it be encoded in JPG "JDAA" format.</p>
1516
1517<p>Use the <a href="command-line-options.html#quality">-quality</a> option to set the compression level
1518to be used by JPEG, PNG, MIFF, and MPEG encoders.
1519Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to set the
1520sampling factor to be used by JPEG, MPEG, and YUV encoders for down-sampling
1521the chroma channels.</p>
1522
1523<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1524 <h3 class="magick-header"><a id="connected-components"></a>-connected-components <var>connectivity</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1525</div>
1526
1527<p class="magick-description">connected-components uniquely labeled, choose from 4 or 8 way connectivity.</p>
1528
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1529<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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1530
1531<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1532 <h3 class="magick-header"><a id="contrast"></a>-contrast</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1533</div>
1534
1535<p class="magick-description">Enhance or reduce the image contrast.</p>
1536
1537<p>This option enhances the intensity differences between the lighter and
1538darker elements of the image. Use <a href="command-line-options.html#contrast">-contrast</a> to enhance
1539the image or <a href="command-line-options.html#contrast">+contrast</a> to reduce the image
1540contrast.</p>
1541
1542<p>For a more pronounced effect you can repeat the option:</p>
1543
1544<pre>
1545convert rose: -contrast -contrast rose_c2.png
1546</pre>
1547
1548<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1549 <h3 class="magick-header"><a id="contrast-stretch"></a>-contrast-stretch <var>black-point</var><br>-contrast-stretch <var>black-point</var>{x<var>white-point</var>}{<var>%</var>}}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1550</div>
1551
1552<p class="magick-description">Increase the contrast in an image by <var>stretching</var> the range of intensity values.</p>
1553
1554<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
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1555<var>black-point %</var> pixels and white-out at most <var>white-point %</var> pixels.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1556
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1557<p>Prior to ImageMagick 6.4.7-0, <a href="command-line-options.html#contrast-stretch">-contrast-stretch</a> will black-out at most <var>black-point</var> pixels and white-out at most <var>total pixels
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1558minus 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>
1559
1560<p>Note that <code>-contrast-stretch 0</code> will modify the image such that
1561the 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
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1562clipping at either end. This is not the same as <a href="command-line-options.html#normalize">-normalize</a>, which is equivalent to <code>-contrast-stretch 0.15x0.05%</code> (or
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1563prior to ImageMagick 6.4.7-0, <code>-contrast-stretch 2%x99%</code>).</p>
1564
1565<p>Internally operator works by creating a histogram bin, and then uses that
1566bin to modify the image. As such some colors may be merged together when they
1567originally fell into the same 'bin'. </p>
1568
1569<p>All the channels are normalized in concert by the came amount so as to
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1570preserve color integrity, when the default <a href="command-line-options.html#channel">+channel</a>
1571setting is in use. Specifying any other <a href="command-line-options.html#channel">-channel</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1572setting will normalize the RGB channels independently.</p>
1573
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1574<p>See also <a href="command-line-options.html#auto-level">-auto-level</a> for a 'perfect'
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1575normalization of mathematical images. </p>
1576
1577<p>This operator is under review for re-development. </p>
1578
1579
1580<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1581 <h3 class="magick-header"><a id="convolve"></a>-convolve <var>kernel</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1582</div>
1583
1584<p class="magick-description">Convolve an image with a user-supplied convolution kernel.</p>
1585
1586<p>The <var>kernel</var> is a matrix specified as
1587a comma-separated list of integers (with no spaces), ordered left-to right,
1588starting with the top row. Presently, only odd-dimensioned kernels are
1589supported, and therefore the number of entries in the specified <var>kernel</var> must be 3<sup>2</sup>=9, 5<sup>2</sup>=25,
15907<sup>2</sup>=49, etc. </p>
1591
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1592<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
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1593positive and negative results are relative to a user-specified bias value.
1594This is important for non-HDRI compilations of ImageMagick when dealing with
1595convolutions that contain negative as well as positive values. This is
1596especially the case with convolutions involving high pass filters or edge
1597detection. Without an output bias, the negative values is clipped at zero.
1598</p>
1599
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1600<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
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1601negative results without clipping to the color value range (0..QuantumRange).
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1602See the discussion on HDRI implementations of ImageMagick on the page <a href="high-dynamic-range.html">High
1603Dynamic-Range Images</a>. For more about HDRI go the ImageMagick <a href="http://www.imagemagick.org/Usage/basics/#hdri">Usage</a> pages or this
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1604<a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a>
1605entry. </p>
1606
1607
1608<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1609 <h3 class="magick-header"><a id="crop"></a>-crop <var>geometry</var>{<var>@</var>}{<var>!</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1610</div>
1611
1612<p class="magick-description">Cut out one or more rectangular regions of the image.</p>
1613
1614<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
1615
1616<p>The <var>width</var> and <var>height</var> of the <var>geometry</var> argument give the size of the image that remains
1617after cropping, and <var>x</var> and <var>y</var> in the
1618<var>offset</var> (if present) gives the location of the top left
1619corner of the cropped image with respect to the original image. To specify the
1620amount to be removed, use <a href="command-line-options.html#shave">-shave</a> instead.</p>
1621
1622<p>If the <var>x</var> and <var>y</var> offsets are
1623present, a single image is generated, consisting of the pixels from the
1624cropping region. The offsets specify the location of the upper left corner of
1625the cropping region measured downward and rightward with respect to the upper
1626left corner of the image. If the <a href="command-line-options.html#gravity">-gravity</a> option is
1627present with <code>NorthEast</code>, <code>East</code>, or <code>SouthEast</code>
1628gravity, it gives the distance leftward from the right edge of the image to
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1629the right edge of the cropping region. Similarly, if the <a href="command-line-options.html#gravity">-gravity</a> option is present with <code>SouthWest</code>,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1630<code>South</code>, or <code>SouthEast</code> gravity, the distance is measured
1631upward between the bottom edges.</p>
1632
1633<p>If the <var>x</var> and <var>y</var> offsets are
1634omitted, a set of tiles of the specified geometry, covering the entire input
1635image, is generated. The rightmost tiles and the bottom tiles are smaller if
1636the specified geometry extends beyond the dimensions of the input image.</p>
1637
1638<p>You can add the <var>@</var> to the geometry argument to equally divide the image into the number of tiles generated.</p>
1639
1640<p>By adding a exclamation character flag to the geometry argument, the
1641cropped images virtual canvas page size and offset is set as if the
1642geometry argument was a viewport or window. This means the canvas page size
1643is set to exactly the same size you specified, the image offset set
1644relative top left corner of the region cropped. </p>
1645
1646<p>If the cropped image 'missed' the actual image on its virtual canvas, a
1647special single pixel transparent 'missed' image is returned, and a 'crop
1648missed' warning given. </p>
1649
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1650<p>It might be necessary to <a href="command-line-options.html#repage">+repage</a> the image prior to
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1651cropping the image to ensure the crop coordinate frame is relocated to the
1652upper-left corner of the visible image.
1653
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1654Similarly you may want to use <a href="command-line-options.html#repage">+repage</a> after cropping to
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1655remove the page offset that will be left behind. This is especially true when
1656you are going to write to an image format such as PNG that supports an image
1657offset.</p>
1658
1659<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1660 <h3 class="magick-header"><a id="cycle"></a>-cycle <var>amount</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1661</div>
1662
1663<p class="magick-description">displace image colormap by amount.</p>
1664
1665<p><var>Amount</var> defines the number of positions each
1666colormap entry is shifted.</p>
1667
1668
1669<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1670 <h3 class="magick-header"><a id="debug"></a>-debug <var>events</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1671</div>
1672
1673<p class="magick-description">enable debug printout.</p>
1674
1675<p>The <code>events</code> parameter specifies which events are to be logged. It
1676can be either <code>None</code>, <code>All</code>, <code>Trace</code>, or
1677a comma-separated list consisting of one or more of the following domains:
1678<code>Accelerate</code>, <code>Annotate</code>, <code>Blob</code>, <code>Cache</code>,
1679<code>Coder</code>, <code>Configure</code>, <code>Deprecate</code>,
1680<code>Exception</code>, <code>Locale</code>, <code>Render</code>,
1681<code>Resource</code>, <code>Security</code>, <code>TemporaryFile</code>,
1682<code>Transform</code>, <code>X11</code>, or <code>User</code>. </p>
1683
1684
1685<p>For example, to log cache and blob events, use.</p>
1686
1687<pre>
1688convert -debug "Cache,Blob" rose: rose.png
1689</pre>
1690
1691<p>The <code>User</code> domain is normally empty, but developers can log user
1692events in their private copy of ImageMagick.</p>
1693
1694<p>To print the complete list of debug methods, use <a href="command-line-options.html#list">-list
1695debug</a>.</p>
1696
1697<p>Use the <a href="command-line-options.html#log">-log</a> option to specify the format for debugging
1698output.</p>
1699
1700<p>Use <a href="command-line-options.html#debug">+debug</a> to turn off all logging.</p>
1701
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1702<p>Debugging may also be set using the <code>MAGICK_DEBUG</code> <a href="resources.html#environment">environment variable</a>. The allowed values for the <code>MAGICK_DEBUG</code>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1703environment variable are the same as for the <a href="command-line-options.html#debug">-debug</a>
1704option.</p>
1705
1706
1707<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1708 <h3 class="magick-header"><a id="decipher"></a>-decipher <var>filename</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1709</div>
1710
1711<p class="magick-description">Decipher and restore pixels that were previously transformed by <a href="command-line-options.html#encipher">-encipher</a>.</p>
1712
1713<p>Get the passphrase from the file specified by <var>filename</var>.</p>
1714
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1715<p>For more information, see the webpage, <a href="http://www.imagemagick.org/www/cipher.html">ImageMagick: Encipher or
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1716Decipher an Image</a>.</p>
1717
1718
1719<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1720 <h3 class="magick-header"><a id="deconstruct"></a>-deconstruct</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1721</div>
1722
1723<p class="magick-description">find areas that has changed between images </p>
1724
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1725<p>Given a sequence of images all the same size, such as produced by <a href="command-line-options.html#coalesce">-coalesce</a>, replace the second and later images, with
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1726a smaller image of just the area that changed relative to the previous image.
1727</p>
1728
1729<p>The resulting sequence of images can be used to optimize an animation
1730sequence, though will not work correctly for GIF animations when parts of the
1731animation can go from opaque to transparent. </p>
1732
1733<p>This option is actually equivalent to the <a href="command-line-options.html#layers">-layers</a>
1734method '<code>compare-any</code>'. </p>
1735
1736
1737<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1738 <h3 class="magick-header"><a id="define"></a>-define <var>key</var>{<var>=value</var>}<var>...</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1739</div>
1740
1741<p class="magick-description">add specific global settings generally used to control coders and image processing operations.</p>
1742
1743<p>This option creates one or more definitions for coders and decoders to use
1744while reading and writing image data. Definitions are generally used to
1745control image file format coder modules, and image processing operations,
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1746beyond what is provided by normal means. Defined settings are listed in <a href="command-line-options.html#verbose">-verbose</a> information ("<code>info:</code>" output format)
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1747as "Artifacts". </p>
1748
1749<p>If <var>value</var> is missing for a definition, an empty-valued
1750definition of a flag is created with that name. This used to control on/off
1751options. Use <a href="command-line-options.html#define">+define key</a> to remove definitions
1752previously created. Use <a href="command-line-options.html#define">+define "*"</a> to remove all
1753existing definitions.</p>
1754
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1755<p>The same 'artifact' settings can also be defined using the <a href="command-line-options.html#set">-set "option:<var>key</var>" "<var>value</var>"</a> option, which also allows the use of <a href="escape.html">Format and Print Image
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1756Properties</a> in the defined value. </p>
1757
1758<p>The <var>option</var> and <var>key</var> are case-independent (they are
1759converted to lowercase for use within the decoders) while the <var>value</var>
1760is case-dependent.</p>
1761
1762<p>Such settings are global in scope, and affect all images and operations. </p>
1763
1764<p>The following definitions are just some of the artifacts that are
1765available:</p>
1766
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1767<table class="table table-condensed table-striped">
1768 <tr>
1769 <td>bmp:format=<var>value</var></td>
1770 <td> valid values are <var>bmp2</var>, <var>bmp3</var>,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1771 and <var>bmp4</var>. This option can be useful when the
1772 method of prepending "BMP2:" to the output filename is inconvenient or
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1773 is not available, such as when using the <a href="mogrify.html">mogrify</a> utility.</td>
1774 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1775
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1776 <tr>
1777 <td>complex:snr=<var>value</var></td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1778 <td>Set the divide SNR constant<a href="command-line-options.html#complex">-complex</a></td>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1779 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1780
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1781 <tr>
1782 <td>compose:args=<var>arguments</var></td>
1783 <td>Sets certain compose argument values when using convert ... -compose ...
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1784 -composite. See <a href="compose.html">Image Composition</a></td>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1785 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1786
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1787 <tr>
1788 <td>convolve:scale=<var>{kernel_scale}[!^] [,{origin_addition}] [%]</var></td>
1789 <td>Defines the kernel scaling. The special flag ! automatically scales to
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1790 full dynamic range. The ! flag can be used in combination with a factor or
1791 percent. The factor or percent is then applied after the automatic scaling.
1792 An example is 50%!. This produces a result 50% darker than full dynamic
1793 range scaling. The ^ flag assures the kernel is 'zero-summing', for
1794 example when some values are positive and some are negative as in edge
1795 detection kernels. The origin addition adds that value to the center
1796 pixel of the kernel. This produces and effect that is like adding the image
1797 that many times to the result of the filtered image. The typical value
1798 is 1 so that the original image is added to the result of the convolution.
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1799 The default is 0.</td>
1800 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1801
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1802 <tr>
1803 <td>convolve:showkernel=<var>1</var></td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1804 <td>Outputs (to 'standard error') all the information about a specified <a href="command-line-options.html#morphology">-morphology convolve</a> kernel.</td>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1805 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1806
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1807 <tr>
1808 <td>dcm:display-range=<var>reset</var></td>
1809 <td>Sets the display range to the minimum and maximum pixel values for the
1810 DCM image format.</td>
1811 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1812
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1813 <tr>
1814 <td>dds:cluster-fit=<var>true|false</var></td>
1815 <td>Enables the dds cluster-fit.</td>
1816 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1817
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1818 <tr>
1819 <td>dds:compression=<var>dxt1|dxt5|none</var></td>
1820 <td>Sets the dds compression.</td>
1821 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1822
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1823 <tr>
1824 <td>dds:mipmaps=<var>value</var></td>
1825 <td>Sets the dds number of mipmaps.</td>
1826 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1827
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1828 <tr>
1829 <td>dds:weight-by-alpha=<var>true|false</var></td>
1830 <td>Enables the dds alpha weighting.</td>
1831 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1832
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1833 <tr>
1834 <td>delegate:bimodal=<var>true</var></td>
1835 <td>Specifies direct conversion from Postscript to PDF.</td>
1836 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1837
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1838 <tr>
1839 <td>distort:scale=<var>value</var></td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1840 <td>Sets the output scaling factor for use with <a href="command-line-options.html#distort">-distort</a></td>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1841 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1842
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1843 <tr>
1844 <td>distort:viewport=<var>WxH+X+Y</var></td>
1845 <td>Sets the viewport for use with <a href="command-line-options.html#distort">-distort</a></td>
1846 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1847
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1848 <tr>
1849 <td>dot:layout-engine=<var>value</var></td>
1850 <td>Specifies the layout engine for the DOT image format (e.g.
1851 <code>neato</code>).</td>
1852 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1853
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1854 <tr>
1855 <td>filter:option=<var>value</var></td>
1856 <td>Set a filter option for use with <a href="command-line-options.html#resize">-resize</a>.
1857 See <a href="command-line-options.html#filter">-filter</a> for details.</td>
1858 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1859
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1860 <tr>
1861 <td>fourier:normalize=<var>inverse</var></td>
1862 <td>Sets the location for the FFT/IFT normalization as use by
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1863 <a href="command-line-options.html#fft">+-fft</a> and <a href="command-line-options.html#ift">+-ift</a>. The default is
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1864 forward.</td>
1865 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1866
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1867 <tr>
1868 <td>icon:auto-resize</td>
1869 <td>Automatically stores multiple sizes when writing an ico image
1870 (requires a 256x256 input image).</td>
1871 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1872
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1873 <tr>
1874 <td>jp2:layer-number=<var>value</var></td>
1875 <td>Sets the maximum number of quality layers to decode. Same for JPT, JC2,
1876 and J2K</td>
1877 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1878
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1879 <tr>
1880 <td>jp2:number-resolutions=<var>value</var></td>
1881 <td>Sets the number of resolutions to encode.Same for JPT, JC2, and J2K</td>
1882 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1883
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1884 <tr>
1885 <td>jp2:progression-order=<var>value</var></td>
1886 <td>choose from LRCP, RLCP, RPCL, PCRL or CPRL. Same for JPT, JC2, and
1887 J2K</td>
1888 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1889
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1890 <tr>
1891 <td>jp2:quality=<var>value,value...</var></td>
1892 <td>Sets the quality layer PSNR, given in dB. The order is from left to
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1893 right in ascending order. The default is a single lossless quality layer.
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1894 Same for JPT, JC2, and J2K</td>
1895 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1896
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1897 <tr>
1898 <td>jp2:rate=<var>value</var></td>
1899 <td>Specify the compression factor to use while writing JPEG-2000 files. The
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1900 compression factor is the reciprocal of the compression ratio. The valid
1901 range is 0.0 to 1.0, with 1.0 indicating lossless compression. If defined,
1902 this value overrides the -quality setting. A quality setting of 75
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1903 results in a rate value of 0.06641. Same for JPT, JC2, and J2K</td>
1904 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1905
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1906 <tr>
1907 <td>jp2:reduce-factor=<var>value</var></td>
1908 <td>Sets the number of highest resolution levels to be discarded.Same for
1909 JPT, JC2, and J2K</td>
1910 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1911
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1912 <tr>
1913 <td>jpeg:block-smoothing=<var>on|off</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1914
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1915 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1916 <td>jpeg:colors=<var>value</var></td>
1917 <td>Set the desired number of colors and let the JPEG encoder do the
1918 quantizing.</td>
1919 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1920
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1921 <tr>
1922 <td>jpeg:dct-method=<var>value</var></td>
1923 <td>Choose from <code>default</code>, <code>fastest</code>,
1924 <code>float</code>, <code>ifast</code>, and <code>islow</code>.</td>
1925 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1926
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1927 <tr>
1928 <td>jpeg:extent=<var>value</var></td>
1929 <td>Restrict the maximum JPEG file size, for example <code>-define
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1930 jpeg:extent=400KB</code>. The JPEG encoder will search for the highest
1931 compression quality level that results in an output file that does not
1932 exceed the value. The <code>-quality</code> option is ignored if it
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1933 is also present.</td>
1934 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1935
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1936 <tr>
1937 <td>jpeg:fancy-upsampling=<var>on|off</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1938
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1939 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1940 <td>jpeg:optimize-coding=<var>on|off</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1941
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1942 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1943 <td>jpeg:q-table=<var>table</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1944
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1945 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1946 <td>jpeg:sampling-factor=<var>sampling-factor-string</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1947
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1948 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1949 <td>jpeg:size=<var>geometry</var></td>
1950 <td>Set the size hint of a JPEG image, for
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1951 example, <code>-define jpeg:size=128x128</code>.
1952 It is most useful for increasing performance and reducing the memory
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1953 requirements when reducing the size of a large JPEG image.</td>
1954 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1955
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1956 <tr>
1957 <td>json:features</td>
1958 <td>includes features in verbose information</td>
1959 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1960
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1961 <tr>
1962 <td>json:limit</td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1963
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1964 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1965 <td>json:locate</td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1966
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1967 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1968 <td>json:moments</td>
1969 <td>includes image moments in verbose information</td>
1970 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1971
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1972 <tr>
1973 <td>mng:need-cacheoff</td>
1974 <td>turn playback caching off for streaming MNG.</td>
1975 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1976
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1977 <tr>
1978 <td>morphology:compose=<var>compose-method</var></td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1979 <td>Specifies how to merge results generated by multiple<a href="command-line-options.html#morphology">-morphology</a> kernel. The default is none. One
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1980 typical value is 'lighten' as used, for example, with the sobel edge
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1981 kernels. </td>
1982 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1983
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1984 <tr>
1985 <td>morphology:showkernel=<var>1</var></td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1986 <td>Outputs (to 'standard error') all the information about a generated <a href="command-line-options.html#morphology">-morphology</a> kernel.</td>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1987 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1988
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1989 <tr>
1990 <td>pcl:fit-to-page=<var>true</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1991
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]1992 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1993 <td>pdf:fit-page=<var>geometry</var></td>
1994 <td> geometry specifies the scaling dimensions for resizing when the PDF is
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1995 being read. The geometry is either WxH{%} or page size. No offsets are
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1996 allowed. (introduced in IM 6.8.8-8)</td>
1997 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]1998
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]1999 <tr>
2000 <td>pdf:fit-to-page=<var>true</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2001
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2002 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2003 <td>pdf:use-cropbox=<var>true</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2004
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2005 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2006 <td>pdf:use-trimbox=<var>true</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2007
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2008 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2009 <td>png:bit-depth=<var>value</var></td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2010 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2011 <td>png:color-type=<var>value</var></td>
2012 <td>desired bit-depth and color-type for PNG output. You can force the PNG
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2013 encoder to use a different bit-depth and color-type than it would have
2014 normally selected, but only if this does not cause any loss of image
2015 quality. Any attempt to reduce image quality is treated as an error and no
2016 PNG file is written. E.g., if you have a 1-bit black-and-white image, you
2017 can use these "defines" to cause it to be written as an 8-bit grayscale,
2018 indexed, or even a 64-bit RGBA. But if you have a 16-million color image,
2019 you cannot force it to be written as a grayscale or indexed PNG. If you
2020 wish to do this, you must use the appropriate <a href="command-line-options.html#depth">-depth</a>,
2021 <a href="command-line-options.html#colors">-colors</a>, or <a href="command-line-options.html#type">-type</a> directives to
2022 reduce the image quality prior to using the PNG encoder. Note that in
2023 indexed PNG files, "bit-depth" refers to the number of bits per index,
2024 which can be 1, 2, 4, or 8. In such files, the color samples always have
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2025 8-bit depth.</td>
2026 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2027
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2028 <tr>
2029 <td>png:compression-filter=<var>value</var></td>
2030 <td> valid values are 0 through 9. 0-4 are the corresponding PNG filters,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2031 5 means adaptive filtering except for images with a colormap, 6 means
2032 adaptive filtering for all images, 7 means MNG "loco" compression, 8 means
2033 Z_RLE strategy with adaptive filtering, and 9 means Z_RLE strategy with no
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2034 filtering.</td>
2035 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2036
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2037 <tr>
2038 <td>png:compression-level=<var>value</var></td>
2039 <td> valid values are 0 through 9, with 0 providing the least but fastest
2040 compression and 9 usually providing the best and always the slowest.</td>
2041 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2042
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2043 <tr>
2044 <td>png:compression-strategy=<var>value</var></td>
2045 <td> valid values are 0 through 4, meaning default, filtered, huffman_only,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2046 rle, and fixed ZLIB compression strategy. If you are using an old zlib
2047 that does not support Z_RLE (before 1.2.0) or Z_FIXED (before 1.2.2.2),
2048 values 3 and 4, respectively, will use the zlib default strategy
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2049 instead.</td>
2050 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2051
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2052 <tr>
2053 <td>png:format=<var>value</var></td>
2054 <td> valid values are <var>png8</var>, <var>png24</var>,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2055 <var>png32</var>, <var>png48</var>,
2056 <var>png64</var>, and <var>png00</var>.
2057 This property can be useful for specifying
2058 the specific PNG format to be used, when the usual method of prepending the
2059 format name to the output filename is inconvenient, such as when writing
2060 a PNG-encoded ICO file or when using <a href="mogrify.html">mogrify</a>.
2061 Value = <var>png8</var> reduces the number of colors to 256,
2062 only one of which may be fully transparent, if necessary. The other
2063 values do not force any reduction of quality; it is an error to request
2064 a format that cannot represent the image data without loss (except that
2065 it is allowed to reduce the bit-depth from 16 to 8 for all formats).
2066 Value = <var>png24</var> and <var>png48</var>
2067 allow transparency, only if a single color is fully transparent and that
2068 color does not also appear in an opaque pixel; such transparency is
2069 written in a PNG <code>tRNS</code> chunk.
2070 Value = <var>png00</var> causes the image to inherit its
2071 color-type and bit-depth from the input image, if the input was also
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2072 a PNG.</td>
2073 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2074
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2075 <tr>
2076 <td>png:exclude-chunk=<var>value</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2077
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2078 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2079 <td>png:include-chunk=<var>value</var></td>
2080 <td>ancillary chunks to be excluded from or included in PNG output.
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2081
2082 <p>The <var>value</var> can be the name of a PNG chunk-type such
2083 as <var>bKGD</var>, a comma-separated list of chunk-names
2084 (which can include the word <var>date</var>, the word
2085 <var>all</var>, or the word <var>none</var>).
2086 Although PNG chunk-names are case-dependent, you can use all lowercase
2087 names if you prefer.</p>
2088
2089 <p>The "include-chunk" and "exclude-chunk" lists only affect the behavior
2090 of the PNG encoder and have no effect on the PNG decoder.</p>
2091
2092 <p>As a special case, if the <code>sRGB</code> chunk is excluded and
2093 the <code>gAMA</code> chunk is included, the <code>gAMA</code> chunk will
2094 only be written if gamma is not 1/2.2, since most decoders assume
2095 sRGB and gamma=1/2.2 when no colorspace information is included in
2096 the PNG file. Because the list is processed from left to right, you
2097 can achieve this with a single define:</p>
2098
2099<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2100-define png:include-chunk=none,gAMA
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2101</pre>
2102
2103 <p>As a special case, if the <code>sRGB</code> chunk is not excluded and
2104 the PNG encoder recognizes that the image contains the sRGB ICC profile,
2105 the PNG encoder will write the <code>sRGB</code> chunk instead of the
2106 entire ICC profile. To force the PNG encoder to write the sRGB
2107 profile as an <code>iCCP</code> chunk in the output PNG instead of the
2108 <code>sRGB</code> chunk, exclude the <code>sRGB</code> chunk.</p>
2109
2110 <p>The critical PNG chunks <code>IHDR</code>, <code>PLTE</code>,
2111 <code>IDAT</code>, and <code>IEND</code> cannot be excluded. Any such
2112 entries appearing in the list will be ignored.</p>
2113
2114 <p>If the ancillary PNG <code>tRNS</code> chunk is excluded and the
2115 image has transparency, the PNG colortype is forced to be 4 or 6
2116 (GRAY_ALPHA or RGBA). If the image is not transparent, then the
2117 <code>tRNS</code> chunk isn't written anyhow, and there is no effect
2118 on the PNG colortype of the output image.</p>
2119
2120 <p>The <a href="command-line-options.html#strip">-strip</a> option does the equivalent of the
2121 following for PNG output:</p>
2122
2123<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2124-define png:exclude-chunk=EXIF,iCCP,iTXt,sRGB,tEXt,zCCP,zTXt,date
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2125</pre>
2126
2127 <p>The default behavior is to include all known PNG ancillary chunks
2128 plus ImageMagick's private <code>vpAg</code> ("virtual page") chunk,
2129 and to exclude all PNG chunks that are unknown to ImageMagick,
2130 regardless of their PNG "copy-safe" status as described in the
2131 PNG specification.</p>
2132
2133 <p>Any chunk names that are not known to ImageMagick are ignored
2134 if they appear in either the "include-chunk" or "exclude-chunk" list.
2135 The ancillary chunks currently known to ImageMagick are
2136 <code>bKGD</code>, <code>cHRM</code>, <code>gAMA</code>, <code>iCCP</code>,
2137 <code>oFFs</code>, <code>pHYs</code>, <code>sRGB</code>, <code>tEXt</code>,
2138 <code>tRNS</code>, <code>vpAg</code>, and <code>zTXt</code>.</p>
2139
2140 <p>You can also put <code>date</code> in the list to include or exclude
2141 the "Date:create" and "Date:modify" text chunks that ImageMagick normally
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2142 inserts in the output PNG.</p></td>
2143 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2144
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2145 <tr>
2146 <td>png:preserve-colormap[=<var>true</var>]</td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2147 <td>Use the existing image-&gt;colormap. Normally the PNG encoder will
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2148 try to optimize the palette, eliminating unused entries and putting
2149 the transparent colors first. If this flag is set, that behavior
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2150 is suppressed.</td>
2151 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2152
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2153 <tr>
2154 <td>png:preserve-iCCP[=<var>true</var>]</td>
2155 <td>By default, the PNG decoder and encoder examine any ICC profile
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2156 that is present, either from an <code>iCCP</code> chunk in the PNG
2157 input or supplied via an option, and if the profile is recognized
2158 to be the sRGB profile, converts it to the <code>sRGB</code> chunk.
2159 You can use <code>-define png:preserve-iCCP</code> to prevent
2160 this from happening; in such cases the <code>iCCP</code> chunk
2161 will be read or written and no <code>sRGB</code> chunk will be
2162 written. There are some ICC profiles that claim to be sRGB but
2163 have various errors that cause them to be rejected by libpng16; such
2164 profiles are recognized anyhow and converted to the <code>sRGB</code>
2165 chunk, but are rejected if the <code>-define png:preserve-iCCP</code>
2166 is present. Note that not all "sRGB" ICC profiles are recognized
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2167 yet; we will add them to the list as we encounter them.</td>
2168 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2169
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2170 <tr>
2171 <td>png:swap-bytes[=<var>true</var>]</td>
2172 <td>The PNG specification requires that any multi-byte integers be stored in
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2173 network byte order (MSB-LSB endian). This option allows you to
2174 fix any invalid PNG files that have 16-bit samples stored incorrectly
2175 in little-endian order (LSB-MSB). The "-define png:swap-bytes" option
2176 must appear before the input filename on the commandline. The swapping
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2177 is done during the libpng decoding operation.</td>
2178 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2179
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2180 <tr>
2181 <td>profile:skip=<var>name1,name2,...</var></td>
2182 <td>Skip the named profile[s] when reading the image. Use skip="*" to
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2183 skip all named profiles in the image. Many named profiles exist,
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2184 including ICC, EXIF, APP1, IPTC, XMP, and others.</td>
2185 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2186
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2187 <tr>
2188 <td>ps:imagemask</td>
2189 <td>If the ps:imagemask flag is defined, the PS3 and EPS3 coders will create
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2190 Postscript files that render bilevel images with the Postscript imagemask
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2191 operator instead of the image operator.</td>
2192 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2193
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2194 <tr>
2195 <td>quantum:format=<var>type</var></td>
2196 <td>Set the type to <code>floating-point</code> to specify a floating-point
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2197 format for raw files (e.g. GRAY:) or for MIFF and TIFF images in HDRI mode
2198 to preserve negative values. If <a href="command-line-options.html#depth">-depth</a> 16 is
2199 included, the result is a single precision floating point format.
2200 If <a href="command-line-options.html#depth">-depth</a> 32 is included, the result is
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2201 double precision floating point format.</td>
2202 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2203
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2204 <tr>
2205 <td>quantum:polarity=<var>photometric-interpretation</var></td>
2206 <td>Set the photometric-interpretation of an image (typically for TIFF image
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2207 file format) to either <code>min-is-black</code> (default) or
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2208 <code>min-is-white</code>.</td>
2209 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2210
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2211 <tr>
2212 <td>sample:offset=<var>geometry</var></td>
2213 <td>Location of the sampling point within the sub-region being sampled,
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2214 expressed as percentages (see <a href="command-line-options.html#sample">-sample</a>).</td>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2215 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2216
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2217 <tr>
2218 <td>showkernel=<var>1</var></td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2219 <td>Outputs (to 'standard error') all the information about a generated <a href="command-line-options.html#morphology">-morphology</a> kernel.</td>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2220 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2221
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2222 <tr>
2223 <td>stream:buffer-size=<var>value</var></td>
2224 <td>Set the stream buffer size. Select 0 for unbuffered I/O.</td>
2225 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2226
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2227 <tr>
2228 <td>tiff:alpha=<var>associated|unassociated|unspecified</var></td>
2229 <td>Specify the alpha extra samples as associated, unassociated or unspecified </td>
2230 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2231
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2232 <tr>
2233 <td>tiff:endian=<var>msb|lsb</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2234
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2235 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2236 <td>tiff:exif-properties=<var>false</var></td>
2237 <td>Skips reading the EXIF properties.</td>
2238 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2239
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2240 <tr>
2241 <td>tiff:fill-order=<var>msb|lsb</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2242
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2243 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2244 <td>tiff:ignore-tags=<var>comma-separate-list-of-tag-IDs</var></td>
2245 <td>Allows one or more tag ID values to be ignored.</td>
2246 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2247
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2248 <tr>
2249 <td>tiff:rows-per-strip=<var>value</var></td>
2250 <td>Sets the number of rows per strip</td>
2251 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2252
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2253 <tr>
2254 <td>tiff:tile-geometry=<var>WxH</var></td>
2255 <td>Sets the tile size for pyramid tiffs. Requires the suffix
2256 PTIF: before the outputname</td>
2257 </tr>
2258</table>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2259
2260<p>For example, to create a postscript file that will render only the black
2261pixels of a bilevel image, use:</p>
2262
2263<pre>
2264convert bilevel.tif -define ps:imagemask eps3:stencil.ps
2265</pre>
2266
2267<p>Set attributes of the image registry by prefixing the value with
2268<code>registry:</code>. For example, to set a temporary path to put work files,
2269use:</p>
2270
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2271<pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2272-define registry:temporary-path=/data/tmp
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2273</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2274
2275<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2276 <h3 class="magick-header"><a id="delay"></a>-delay <var>ticks</var> <br>-delay <var>ticks</var>x<var>ticks-per-second</var> {<var>&lt;</var>} {<var>&gt;</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2277</div>
2278
2279<p class="magick-description">display the next image after pausing.</p>
2280
2281<p>This option is useful for regulating the animation of image sequences
2282<var>ticks/ticks-per-second</var> seconds must expire before the display of the
2283next image. The default is no delay between each showing of the image
2284sequence. The default ticks-per-second is 100.</p>
2285
2286<p>Use <code>&gt;</code> to change the image delay <var>only</var> if its current
2287value exceeds the given delay. <code>&lt;</code> changes the image delay
2288<var>only</var> if current value is less than the given delay. For example, if
2289you specify <code>30&gt;</code> and the image delay is 20, the image delay does
2290not change. However, if the image delay is 40 or 50, the delay it is changed
2291to 30. Enclose the given delay in quotation marks to prevent the
2292<code>&lt;</code> or <code>&gt;</code> from being interpreted by your shell as
2293a file redirection.</p>
2294
2295
2296<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2297 <h3 class="magick-header"><a id="delete"></a>-delete <var>indexes</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2298</div>
2299
2300<p class="magick-description">delete the images specified by index, from the image sequence.</p>
2301
2302<p>Specify the image by its index in the sequence. The first image is index
23030. Negative indexes are relative to the end of the sequence, for example, -1
2304represents the last image of the sequence. Specify a range of images with
2305a dash (e.g. 0-4). Separate indexes with a comma (e.g. 0,2). Use
2306<code>+delete</code> to delete the last image in the current image sequence.</p>
2307
2308
2309<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2310 <h3 class="magick-header"><a id="density"></a>-density <var>width</var><br>-density <var>width</var>x<var>height</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2311</div>
2312
2313<p class="magick-description">Set the horizontal and vertical resolution of an image for rendering to devices.</p>
2314
2315<p>This option specifies the image resolution to store while encoding a raster
2316image or the canvas resolution while rendering (reading) vector formats such
2317as Postscript, PDF, WMF, and SVG into a raster image. Image resolution
2318provides the unit of measure to apply when rendering to an output device or
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2319raster image. The default unit of measure is in dots per inch (DPI). The <a href="command-line-options.html#units">-units</a> option may be used to select dots per centimeter
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2320instead.</p>
2321
2322<p>The default resolution is 72 dots per inch, which is equivalent to one
2323point per pixel (Macintosh and Postscript standard). Computer screens are
2324normally 72 or 96 dots per inch, while printers typically support 150, 300,
2325600, or 1200 dots per inch. To determine the resolution of your display, use
2326a ruler to measure the width of your screen in inches, and divide by the
2327number of horizontal pixels (1024 on a 1024x768 display).</p>
2328
2329<p>If the file format supports it, this option may be used to update the
2330stored image resolution. Note that Photoshop stores and obtains image
2331resolution from a proprietary embedded profile. If this profile is not
2332stripped from the image, then Photoshop will continue to treat the image using
2333its former resolution, ignoring the image resolution specified in the standard
2334file header.</p>
2335
2336<p>The <a href="command-line-options.html#density">-density</a> option sets an <var>attribute</var> and
2337does not alter the underlying raster image. It may be used to adjust the
2338rendered size for desktop publishing purposes by adjusting the scale applied
2339to the pixels. To resize the image so that it is the same size at a different
2340resolution, use the <a href="command-line-options.html#resample">-resample</a> option.</p>
2341
2342<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2343 <h3 class="magick-header"><a id="depth"></a>-depth <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2344</div>
2345
2346<p class="magick-description">depth of the image.</p>
2347
2348<p>This the number of bits in a color sample within a pixel. Use this option
2349to specify the depth of raw images whose depth is unknown such as GRAY, RGB,
2350or CMYK, or to change the depth of any image after it has been read.</p>
2351
2352<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2353 <h3 class="magick-header"><a id="descend"></a>-descend</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2354</div>
2355
2356<p class="magick-description">obtain image by descending window hierarchy.</p>
2357
2358<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2359 <h3 class="magick-header"><a id="deskew"></a>-deskew <var>threshold</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2360</div>
2361
2362<p class="magick-description">straighten an image. A threshold of 40% works for most images.</p>
2363
2364<p>Use <a href="command-line-options.html#set">-set</a> <code>option:deskew:auto-crop
2365<var>width</var></code> to auto crop the image. The set argument is the pixel
2366width of the image background (e.g 40).</p>
2367
2368<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2369 <h3 class="magick-header"><a id="despeckle"></a>-despeckle</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2370</div>
2371
2372<p class="magick-description">reduce the speckles within an image.</p>
2373
2374<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2375 <h3 class="magick-header"><a id="direction"></a>-direction <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2376</div>
2377
2378<p class="magick-description">render text right-to-left or left-to-right.</p>
2379
2380<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2381 <h3 class="magick-header"><a id="displace"></a>-displace <var>horizontal-scale</var><br>-displace <var>horizontal-scale</var>x<var>vertical-scale</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2382</div>
2383
2384<p class="magick-description">shift image pixels as defined by a displacement map.</p>
2385
2386<p>With this option, the 'overlay' image, and optionally the 'mask' image,
2387is used as a displacement map, which is used to displace the lookup of
2388what part of the 'background' image is seen at each point of the overlaid
2389area. Much like the displacement map is a 'lens' that redirects light shining
2390through it so as to present a distorted view the original 'background' image
2391behind it. </p>
2392
2393<p>Any perfect grey areas of the displacement map produce a zero
2394displacement of the image. Black areas produce the given maximum negative
2395displacement of the lookup point, while white produce a maximum positive
2396displacement of the lookup. </p>
2397
2398<p>Note that it is the lookup of the 'background' that is displaced, not a
2399displacement of the image itself. As such an area of the displacement map
2400containing 'white' will have the lookup point 'shifted' by a positive amount,
2401and thus generating a copy of the destination image to the right/downward from
2402the correct position. That is the image will look like it may have been
2403'shifted' in a negative left/upward direction. Understanding this is a very
2404important in understanding how displacement maps work. </p>
2405
2406<p>The given arguments define the maximum amount of displacement in pixels
2407that a particular map can produce. If the displacement scale is large enough
2408it is also possible to lookup parts of the 'background' image that lie well
2409outside the bounds of the displacement map itself. That is you could very
2410easily copy a section of the original image from outside the overlay area
2411into the overlay area. </p>
2412
2413<p>The '%' flag makes the displacement scale relative to the size of the
2414overlay image (100% = half width/height of image). Using '!' switches
2415percentage arguments to refer to the destination image size instead.
2416these flags were added as of IM v6.5.3-5.</p>
2417
2418<p>Normally a single grayscale displacement map is provided, which with the
2419given scaling values will determine a single direction (vector) in which
2420displacements can occur (positively or negatively). However, if you also
2421specify a third image which is normally used as a <var>mask</var>,
2422the <var>composite image</var> is used for horizontal X
2423displacement, while the <var>mask image</var> is used for vertical Y
2424displacement. This allows you to define completely different displacement
2425values for the X and Y directions, and allowing you to lookup any point within
2426the <var>scale</var> bounds. In other words each pixel can lookup
2427any other nearby pixel, producing complex 2 dimensional displacements, rather
2428than a simple 1 dimensional vector displacements. </p>
2429
2430<p>Alternatively rather than supplying two separate images, as of IM v6.4.4-0,
2431you can use the 'red' channel of the overlay image to specify the horizontal
2432or X displacement, and the 'green' channel for the vertical or Y displacement.
2433</p>
2434
2435<p>As of IM v6.5.3-5 any alpha channel in the overlay image is used as a
2436mask the transparency of the destination image. However areas outside the
2437overlaid areas will not be effected. </p>
2438
2439
2440<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2441 <h3 class="magick-header"><a id="display"></a>-display <var>host:display[.screen]</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2442</div>
2443
2444<p class="magick-description">Specifies the X server to contact.</p>
2445
2446<p>This option is used with convert for obtaining image or font from this
2447X server. See <var>X(1)</var>.</p>
2448
2449<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2450 <h3 class="magick-header"><a id="dispose"></a>-dispose <var>method</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2451</div>
2452
2453<p class="magick-description">define the GIF disposal image setting for images that are being created or read in. </p>
2454
2455<p>The layer disposal method defines the way each the displayed image is to be
2456modified after the current 'frame' of an animation has finished being
2457displayed (after its 'delay' period), but before the next frame on an
2458animation is to be overlaid onto the display. </p>
2459
2460<p>Here are the valid methods:</p>
2461
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2462<dl class="dl-horizontal">
2463<dt>Undefined</dt><dd>0: No disposal specified (equivalent to '<code>none</code>').</dd>
2464<dt>None</dt><dd>1: Do not dispose, just overlay next frame image.</dd>
2465<dt>Background</dt><dd>2: Clear the frame area with the background color.</dd>
2466<dt>Previous</dt><dd>3: Clear to the image prior to this frames overlay.</dd>
2467</dl>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2468
2469<p>You can also use the numbers given above, which is what the GIF format
2470uses internally to represent the above settings. </p>
2471
2472<p>To print a complete list of dispose methods, use <a href="command-line-options.html#list">-list dispose</a>.</p>
2473
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2474<p>Use <a href="command-line-options.html#dispose">+dispose</a>, turn off the setting and prevent
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2475resetting the layer disposal methods of images being read in. </p>
2476
2477<p>Use <a href="command-line-options.html#set">-set</a> '<code>dispose</code>' method to set the image
2478disposal method for images already in memory.</p>
2479
2480<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2481 <h3 class="magick-header"><a id="dissimilarity-threshold"></a>-dissimilarity-threshold <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2482</div>
2483
2484<p class="magick-description">maximum RMSE for subimage match (default 0.2).</p>
2485
2486
2487<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2488 <h3 class="magick-header"><a id="dissolve"></a>-dissolve <var>src_percent</var>[x<var>dst_percent</var>]</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2489</div>
2490
2491<p class="magick-description">dissolve an image into another by the given percent.</p>
2492
2493<p>The opacity of the composite image is multiplied by the given percent, then
2494it is composited 'over' the main image. If <var>src_percent</var>
2495is greater than 100, start dissolving the main image so it becomes
2496transparent at a value of '<code>200</code>'. If both percentages
2497are given, each image are dissolved to the percentages given. </p>
2498
2499<p>Note that dissolve percentages do not add, two opaque images dissolved
2500'50,50', produce a 75% transparency. For a 50% + 50% blending of the two
2501images, you would need to use dissolve values of '50,100'. </p>
2502
2503<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2504 <h3 class="magick-header"><a id="distort"></a>-distort <var>method arguments</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2505</div>
2506
2507<p class="magick-description">distort an image, using the given <var>method</var> and its required <var>arguments</var>.</p>
2508
2509<p>The <var>arguments</var> is a single string containing a list
2510of floating point numbers separated by commas or spaces. The number of
2511and meaning of the floating point values depends on the distortion <var>method</var> being used. </p>
2512
2513<p>Choose from these distortion types:</p>
2514
2515<table class="table table-condensed table-striped">
2516 <tr>
2517 <th style="width: 8%">Method</th>
2518 <th>Description</th>
2519 </tr>
2520
2521 <tr>
2522 <td><code>ScaleRotateTranslate</code>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2523 <br>or <code>SRT</code></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2524 <td>
2525 Distort image by first scaling and rotating about a given 'center',
2526 before translating that 'center' to the new location, in that order. It
2527 is an alternative method of specifying a '<code>Affine</code>' type of
2528 distortion, but without shearing effects. It also provides a good way
2529 of rotating and displacing a smaller image for tiling onto a larger
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2530 background (IE 2-dimensional animations). <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2531
2532 The number of arguments determine the specific meaning of each
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2533 argument for the scales, rotation, and translation operations. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2534
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2535 <table class="table table-condensed table-striped">
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2536 <tr><td>2:</td><td><var>Scale Angle</var></td></tr>
2537 <tr><td>3:</td><td><var>X,Y Angle</var></td></tr>
2538 <tr><td>4:</td><td><var>X,Y Scale Angle</var></td></tr>
2539 <tr><td>5:</td>
2540 <td><var>X,Y ScaleX,ScaleY Angle</var></td></tr>
2541 <tr><td>6:</td>
2542 <td><var>X,Y Scale Angle NewX,NewY</var></td></tr>
2543 <tr><td>7:</td>
2544 <td><var>X,Y ScaleX,ScaleY Angle
2545 NewX,NewY</var></td></tr>
2546 </table>
2547
2548 This is actually an alternative way of specifying a 2 dimensional linear
2549 '<code>Affine</code>' or '<code>AffineProjection</code>' distortion. </td> </tr>
2550
2551 <tr>
2552 <td><code>Affine</code></td>
2553 <td>
2554 Distort the image linearly by moving a list of at least 3 or more sets
2555 of control points (as defined below). Ideally 3 sets or 12 floating
2556 point values are given allowing the image to be linearly scaled,
2557 rotated, sheared, and translated, according to those three points. See
2558 also the related '<code>AffineProjection</code>' and '<code>SRT</code>'
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2559 distortions. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2560
2561 More than 3 sets given control point pairs (12 numbers) is least
2562 squares fitted to best match a linear affine distortion. If only 2
2563 control point pairs (8 numbers) are given a two point image translation
2564 rotation and scaling is performed, without any possible shearing,
2565 flipping or changes in aspect ratio to the resulting image. If only one
2566 control point pair is provides the image is only translated, (which may
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2567 be a floating point non-integer translation). <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2568
2569 This distortion does not include any form of perspective distortion.
2570 </td>
2571
2572 </tr>
2573
2574 <tr>
2575 <td><code>AffineProjection</code></td>
2576 <td>
2577 Linearly distort an image using the given Affine Matrix of 6
2578 pre-calculated coefficients forming a set of Affine Equations to map
2579 the source image to the destination image.
2580
2581 <div style="text-align: center"><var>
2582 s<sub>x</sub>, r<sub>x</sub>,
2583 r<sub>y</sub>, s<sub>y</sub>,
2584 t<sub>x</sub>, t<sub>y</sub>
2585 </var></div>
2586
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2587 See <a href="command-line-options.html#affine">-affine</a> setting for more detail, and
2588 meanings of these coefficients. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2589
2590 The distortions '<code>Affine</code>' and '<code>SRT</code>' provide
2591 alternative methods of defining this distortion, with ImageMagick doing
2592 the calculations needed to generate the required coefficients. You can
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2593 see the internally generated coefficients, by using a <a href="command-line-options.html#verbose">-verbose</a> setting with those other variants. </td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2594
2595 </tr>
2596
2597 <tr>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2598 <td><code>BilinearForward</code><br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2599 <code>BilinearReverse</code></td>
2600 <td>
2601 Bilinear Distortion, given a minimum of 4 sets of coordinate pairs, or
2602 16 values (see below). Not that lines may not appear straight after
2603 distortion, though the distance between coordinates will remain
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2604 consistent. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2605
2606 The '<code>BilinearForward</code>' is used to map rectangles to any
2607 quadrilateral, while the '<code>BilinearReverse</code>' form maps any
2608 quadrilateral to a rectangle, while preserving the straight line edges
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2609 in each case. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2610
2611 Note that '<code>BilinearForward</code>' can generate invalid pixels
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2612 which will be colored using the <a href="command-line-options.html#mattecolor">-mattecolor</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2613 color setting. Also if the quadrilateral becomes 'flipped' the image
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2614 may disappear. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2615
2616 There are future plans to produce a true Bilinear distortion that will
2617 attempt to map any quadrilateral to any other quadrilateral, while
2618 preserving edges (and edge distance ratios).
2619
2620 </td>
2621 </tr>
2622
2623 <tr>
2624 <td><code>Perspective</code></td>
2625 <td>
2626 Perspective distort the images, using a list of 4 or more sets of
2627 control points (as defined below). More that 4 sets (16 numbers) of
2628 control points provide least squares fitting for more accurate
2629 distortions (for the purposes of image registration and panorama
2630 effects). Less than 4 sets will fall back to a '<code>Affine</code>'
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2631 linear distortion. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2632
2633 Perspective Distorted images ensures that straight lines remain
2634 straight, but the scale of the distorted image will vary. The horizon
2635 is anti-aliased, and the 'sky' color may be set using the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2636 <a href="command-line-options.html#mattecolor">-mattecolor</a> setting. </td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2637 </tr>
2638
2639 <tr>
2640 <td><code>PerspectiveProjection</code> </td>
2641 <td>
2642 Do a '<code>Perspective</code>' distortion biased on a set of 8
2643 pre-calculated coefficients. You can get these coefficients by looking
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2644 at the <a href="command-line-options.html#verbose">-verbose</a> output of a
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2645 '<code>Perspective</code>' distortion, or by calculating them yourself.
2646 If the last two perspective scaling coefficients are zero, the
2647 remaining 6 represents a transposed 'Affine Matrix'. </td>
2648
2649 </tr>
2650
2651 <tr>
2652 <td><code>Arc</code></td>
2653 <td>
2654 Arc the image (variation of polar mapping) over the angle given around
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2655 a circle. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2656 <table class="table table-condensed table-striped">
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2657 <tr><td>Argument</td>
2658 <td>Meaning</td></tr>
2659 <tr><td><var>arc_angle</var></td>
2660 <td>The angle over which to arc the image side-to-side</td></tr>
2661 <tr><td><var>rotate_angle</var></td>
2662 <td>Angle to rotate resulting image from vertical center</td></tr>
2663 <tr><td><var>top_radius</var></td>
2664 <td>Set top edge of source image at this radius</td></tr>
2665 <tr><td><var>bottom_radius</var> </td>
2666 <td>Set bottom edge to this radius (radial scaling)</td></tr>
2667 </table>
2668
2669 The resulting image is always resized to best fit the resulting image,
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2670 (as if using <a href="command-line-options.html#distort">+distort</a>) while attempting to
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2671 preserve scale and aspect ratio of the original image as much as
2672 possible with the arguments given by the user. All four arguments will
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2673 be needed to change the overall aspect ratio of an 'Arc'ed image. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2674
2675 This a variation of a polar distortion designed to try to preserve the
2676 aspect ratio of the image rather than direct Cartesian to Polar
2677 conversion. </td>
2678 </tr>
2679
2680 <tr>
2681 <td><code>Polar</code></td>
2682 <td>
2683 Like '<code>Arc</code>' but do a complete Cartesian to Polar mapping of
2684 the image. that is the height of the input image is mapped to the
2685 radius limits, while the width is wrapped around between the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2686 angle limits. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2687
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2688 Arguments: <var>Rmax,Rmin CenterX,CenterY, start,end_angle</var> <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2689
2690 All arguments are optional. With <var>Rmin</var> defaulting to zero, the
2691 center to the center of the image, and the angles going from -180 (top)
2692 to +180 (top). If <var>Rmax</var> is given the special value of
2693 '<code>0</code>', the the distance from the center to the nearest edge
2694 is used for the radius of the output image, which will ensure the whole
2695 image is visible (though scaled smaller). However a special value of
2696 '<code>-1</code>' will use the distance from the center to the furthest
2697 corner, This may 'clip' the corners from the input rectangular image,
2698 but will generate the exact reverse of a '<code>DePolar</code>' with
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2699 the same arguments. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2700
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2701 If the plus form of distort (<a href="command-line-options.html#distort">+distort</a>) is used
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2702 output image center will default to <code>0,0</code> of the virtual
2703 canvas, and the image size adjusted to ensure the whole input image is
2704 made visible in the output image on the virtual canvas. </td>
2705
2706 </tr>
2707
2708 <tr>
2709 <td><code>DePolar</code></td>
2710 <td>
2711 Uses the same arguments and meanings as a '<code>Polar</code>' distortion
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2712 but generates the reverse Polar to Cartesian distortion. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2713
2714 The special <var>Rmax</var> setting of '<code>0</code>' may however clip
2715 the corners of the input image. However using the special
2716 <var>Rmax</var> setting of '<code>-1</code>' (maximum center to corner
2717 distance) will ensure the whole distorted image is preserved in the
2718 generated result, so that the same argument to '<code>Polar</code>' will
2719 reverse the distortion re-producing the original.
2720
2721 Note that as this distortion requires the area resampling of a circular
2722 arc, which can not be handled by the builtin EWA resampling function.
2723 As such the normal EWA filters are turned off. It is recommended some
2724 form of 'super-sampling' image processing technique be used to produce
2725 a high quality result. </td>
2726
2727 </tr>
2728
2729 <tr>
2730 <td><code>Barrel</code></td>
2731 <td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2732 Given the four coefficients (A,B,C,D) as defined by <a href="http://wiki.panotools.org/Lens_correction_model">Helmut
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2733 Dersch</a>, perform a barrel or pin-cushion distortion appropriate to
2734 correct radial lens distortions. That is in photographs, make straight
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2735 lines straight again. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2736
2737 Arguments: <var>A B C</var> [ <var>D</var> [
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2738 <var>X</var> , <var>Y</var> ] ] <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2739 or <var>A<sub>x</sub> B<sub>x</sub> C<sub>x</sub> D<sub>x</sub>
2740 A<sub>y</sub> B<sub>y</sub> C<sub>y</sub> D<sub>y</sub></var>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2741 [ <var>X</var> , <var>Y</var> ] <br>
2742 So that it forms the function <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2743 Rsrc = r * ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> +
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2744 <var>C</var>*r + <var>D</var> )<br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2745
2746 Where <var>X</var>,<var>Y</var> is the optional center of the distortion
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2747 (defaulting to the center of the image). <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2748 The second form is typically used to distort images, rather than
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2749 correct lens distortions. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2750 </td>
2751
2752 </tr>
2753
2754 <tr>
2755 <td><code>BarrelInverse</code></td>
2756 <td>
2757 This is very similar to '<code>Barrel</code>' with the same set of
2758 arguments, and argument handling. However it uses the inverse
2759 of the radial polynomial,
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2760 so that it forms the function <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2761 Rsrc = r / ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> +
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2762 <var>C</var>*r + <var>D</var> )<br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2763 Note that this is not the reverse of the '<code>Barrel</code>'
2764 distortion, just a different barrel-like radial distortion method.
2765
2766 </td>
2767 </tr>
2768
2769 <tr>
2770 <td><code>Shepards</code></td>
2771 <td>
2772 Distort the given list control points (any number) using an Inverse
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2773 Squared Distance Interpolation Method (<a href="http://en.wikipedia.org/wiki/Shepard%27s_method">Shepards
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2774 Method</a>). The control points in effect do 'localized' displacement
2775 of the image around the given control point (preserving the look and
2776 the rotation of the area near the control points. For best results
2777 extra control points should be added to 'lock' the positions of the
2778 corners, edges and other unchanging parts of the image, to prevent
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2779 their movement. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2780
2781 The distortion has been likened to 'taffy pulling' using nails, or
2782 pins' stuck in a block of 'jelly' which is then moved to the new
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2783 position, distorting the surface of the jelly. <br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2784
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2785 Internally it is equivalent to generating a displacement map (see <a href="command-line-options.html#displace">-displace</a>) for source image color look-up using
2786 the <a href="command-line-options.html#sparse-color">-sparse-color</a> method of the same name.
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2787
2788 </td>
2789 </tr>
2790
2791</table>
2792
2793<p>To print a complete list of distortion methods, use <a href="command-line-options.html#list">-list
2794distort</a>.</p>
2795
2796<p>Many of the above distortion methods such as '<code>Affine</code>',
2797'<code>Perspective</code>', and '<code>Shepards</code>' use a list control points
2798defining how these points in the given image should be distorted in the
2799destination image. Each set of four floating point values represent a source
2800image coordinate, followed immediately by the destination image coordinate.
2801This produces a list of values such as...</p>
2802<div style="text-align: center"><var>
2803 U<sub>1</sub>,V<sub>1</sub> X<sub>1</sub>,Y<sub>1</sub>
2804 U<sub>2</sub>,V<sub>2</sub> X<sub>2</sub>,Y<sub>2</sub>
2805 U<sub>3</sub>,V<sub>3</sub> X<sub>3</sub>,Y<sub>3</sub>
2806 ...
2807 U<sub>n</sub>,V<sub>n</sub> X<sub>n</sub>,Y<sub>n</sub>
2808</var></div>
2809<p>where <var>U,V</var> on the source image is mapped to <var>X,Y</var> on the
2810destination image. </p>
2811
2812<p>For example, to warp an image using '<code>perspective</code>' distortion,
2813needs a list of at least 4 sets of coordinates, or 16 numbers. Here is the
2814perspective distortion of the built-in "rose:" image. Note how spaces were
2815used to group the 4 sets of coordinate pairs, to make it easier to read and
2816understand.</p>
2817
2818<pre>
2819convert rose: -virtual-pixel black \
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2820 -distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35' \
2821 rose_3d_rotated.gif"
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2822</pre>
2823
2824<p>If more that the required number of coordinate pairs are given for
2825a distortion, the distortion method is 'least squares' fitted to produce the
2826best result for all the coordinate pairs given. If less than the ideal number
2827of points are given, the distort will generally fall back to a simpler form of
2828distortion that can handles the smaller number of coordinates (usually a linear
2829'<code>Affine</code>' distortion). </p>
2830
2831<p>By using more coordinates you can make use of image registration tool to
2832find matching coordinate pairs in overlapping images, so as to improve the
2833'fit' of the distortion. Of course a bad coordinate pair can also make the
2834'fit' worse. Caution is always advised. </p>
2835
2836<p>Colors are acquired from the source image according to a cylindrical
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2837resampling <a href="command-line-options.html#filter">-filter</a>, using a special technique known as
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2838EWA resampling. This produces very high quality results, especially when
2839images become smaller (minified) in the output, which is very common when
2840using '<code>perspective</code>' distortion. For example here we view
2841a infinitely tiled 'plane' all the way to the horizon. </p>
2842
2843<pre>
2844convert -size 90x90 pattern:checkerboard -normalize -virtual-pixel tile \
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2845 -distort perspective '0,0,5,45 89,0,45,46 0,89,0,89 89,89,89,89' \
2846 checks_tiled.jpg
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2847</pre>
2848
2849<p>Note that a infinitely tiled perspective images involving the horizon can
2850be very slow, because of the number of pixels that are compressed to generate
2851each individual pixel close to the 'horizon'. You can turn off EWA
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2852resampling, by specifing the special <a href="command-line-options.html#filter">-filter</a> setting of
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2853'<code>point</code>' (recommended if you plan to use super-sampling instead).
2854</p>
2855
2856<p>If an image generates <i>invalid pixels</i>, such as the 'sky' in the last
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2857example, <a href="command-line-options.html#distort">-distort</a> will use the current <a href="command-line-options.html#mattecolor">-mattecolor</a> setting for these pixels. If you do not
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2858what these pixels to be visible, set the color to match the rest of the
2859ground. </p>
2860
2861<p>The output image size will by default be the same as the input image. This
2862means that if the part of the distorted image falls outside the viewed area of
2863the 'distorted space', those parts is clipped and lost. However if you use
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2864the plus form of the operator (<a href="command-line-options.html#distort">+distort</a>) the operator
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2865will attempt (if possible) to show the whole of the distorted image, while
2866retaining a correct 'virtual canvas' offset, for image layering. This offset
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2867may need to be removed using <a href="command-line-options.html#repage">+repage</a>, to remove if it
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2868is unwanted. </p>
2869
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2870<p>Setting <a href="command-line-options.html#verbose">-verbose</a> setting, will cause <a href="command-line-options.html#distort">-distort</a> to attempt to output the internal coefficients,
2871and the <a href="command-line-options.html#fx">-fx</a> equivalent to the distortion, for expert study,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2872and debugging purposes. This many not be available for all distorts. </p>
2873
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2874<p>You can alternatively specify a special "<code><a href="command-line-options.html#define">-define</a> distort:viewport={geometry_string}</code>" setting which will
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2875specify the size and the offset of the generated 'viewport' image of the
2876distorted image space.</p>
2877
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2878<p>Setting a "<code><a href="command-line-options.html#define">-define</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2879distort:scale={scale_factor}</code>" will scale the output image (viewport or
2880otherwise) by that factor without changing the viewed contents of the
2881distorted image. This can be used either for 'super-sampling' the image for
2882a higher quality result, or for panning and zooming around the image (with
2883appropriate viewport changes, or post-distort cropping and resizing). </p>
2884
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2885<p>Setting "<code><a href="command-line-options.html#define">-define</a> resample:verbose=1</code>"
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2886will output the cylindrical filter lookup table created by the EWA (Elliptical
2887Weighted Average) resampling algorithm. Note this table uses a squared radius
2888lookup value. This is typically only used for debugging EWA resampling. </p>
2889
2890
2891<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2892 <h3 class="magick-header"><a id="distribute-cache"></a>-distribute-cache <var>port</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2893</div>
2894
2895<p class="magick-description">launch a distributed pixel cache server. </p>
2896
2897<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2898 <h3 class="magick-header"><a id="dither"></a>-dither <var>method</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2899</div>
2900
2901<p class="magick-description">Apply a Riemersma or Floyd-Steinberg error diffusion dither to
2902images when general color reduction is applied via an option, or automagically
2903when saving to specific formats. This enabled by default.</p>
2904
2905<p>Dithering places two or more colors in neighboring pixels so that to the
2906eye a closer approximation of the images original color is reproduced. This
2907reduces the number of colors needed to reproduce the image but at the cost of
2908a lower level pattern of colors. Error diffusion dithers can use any set of
2909colors (generated or user defined) to an image. </p>
2910
2911<p>Dithering is turned on by default, to turn it off use the plus form of the
2912setting, <a href="command-line-options.html#dither">+dither</a>. This will also also render PostScript
2913without text or graphic aliasing. Disabling dithering often (but not always)
2914leads to faster process, a smaller number of colors, but more cartoon like
2915image coloring. Generally resulting in 'color banding' effects in areas with
2916color gradients. </p>
2917
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2918<p>The color reduction operators <a href="command-line-options.html#colors">-colors</a>, <a href="command-line-options.html#monochrome">-monochrome</a>, <a href="command-line-options.html#remap%20">-remap</a>, and <a href="command-line-options.html#posterize">-posterize</a>, apply dithering to images using the reduced
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2919color set they created. These operators are also used as part of automatic
2920color reduction when saving images to formats with limited color support, such
2921as <code>GIF:</code>, <code>XBM:</code>, and others, so dithering may also be used
2922in these cases. </p>
2923
2924<p>Alternatively you can use <a href="command-line-options.html#random-threshold">-random-threshold</a>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2925to generate purely random dither. Or use <a href="command-line-options.html#ordered-dither">-ordered-dither</a> to apply threshold mapped dither
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2926patterns, using uniform color maps, rather than specific color maps. </p>
2927
2928
2929<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2930 <h3 class="magick-header"><a id="draw"></a>-draw <var>string</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2931</div>
2932
2933<p class="magick-description">Annotate an image with one or more graphic primitives.</p>
2934
2935<p>Use this option to annotate or decorate an image with one or more graphic
2936primitives. The primitives include shapes, text, transformations, and pixel
2937operations.</p>
2938
2939<p>The shape primitives:</p>
2940
2941<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2942point x,y
2943line x0,y0 x1,y1
2944rectangle x0,y0 x1,y1
2945roundRectangle x0,y0 x1,y1 wc,hc
2946arc x0,y0 x1,y1 a0,a1
2947ellipse x0,y0 rx,ry a0,a1
2948circle x0,y0 x1,y1
2949polyline x0,y0 ... xn,yn
2950polygon x0,y0 ... xn,yn
2951bezier x0,y0 ... xn,yn
2952path specification
2953image operator x0,y0 w,h filename
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2954</pre>
2955
2956<p>The text primitive:</p>
2957
2958<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2959text x0,y0 string
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2960</pre>
2961<p>The text gravity primitive:</p>
2962
2963<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2964gravity NorthWest, North, NorthEast, West, Center,
2965 East, SouthWest, South, or SouthEast
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2966</pre>
2967
2968<p>The text gravity primitive only affects the placement of text and does not
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2969interact with the other primitives. It is equivalent to using the <a href="command-line-options.html#gravity">-gravity</a> command-line option, except that it is limited in
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2970scope to the <a href="command-line-options.html#draw">-draw</a> option in which it appears.</p>
2971
2972<p>The transformation primitives:</p>
2973
2974<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2975rotate degrees
2976translate dx,dy
2977scale sx,sy
2978skewX degrees
2979skewY degrees
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2980</pre>
2981
2982<p>The pixel operation primitives:</p>
2983
2984<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]2985color x0,y0 method
2986matte x0,y0 method
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2987</pre>
2988
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2989<p>The shape primitives are drawn in the color specified by the preceding <a href="command-line-options.html#fill">-fill</a> setting. For unfilled shapes, use <a href="command-line-options.html#fill">-fill none</a>. You can optionally control the stroke (the
2990"outline" of a shape) with the <a href="command-line-options.html#stroke">-stroke</a> and <a href="command-line-options.html#strokewidth">-strokewidth</a> settings.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2991
2992<p>A <code>point</code> primitive is specified by a single <var>point</var> in the
2993pixel plane, that is, by an ordered pair of integer coordinates,
2994<var>x</var>,<var>y</var>. (As it involves only a single pixel, a <code>point</code>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]2995primitive is not affected by <a href="command-line-options.html#stroke">-stroke</a> or <a href="command-line-options.html#strokewidth">-strokewidth</a>.)</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]2996
2997<p>A <code>line</code> primitive requires a start point and end point.</p>
2998
2999<p>A <code>rectangle</code> primitive is specified by the pair of points at the
3000upper left and lower right corners.</p>
3001
3002<p>A <code>roundRectangle</code> primitive takes the same corner points as
3003a <code>rectangle</code> followed by the width and height of the rounded corners
3004to be removed.</p>
3005
3006<p>The <code>circle</code> primitive makes a disk (filled) or circle (unfilled).
3007Give the center and any point on the perimeter (boundary).</p>
3008
3009<p>The <code>arc</code> primitive is used to inscribe an elliptical segment in
3010to a given rectangle. An <code>arc</code> requires the two corners used for
3011<code>rectangle</code> (see above) followed by the start and end angles of the
3012arc of the segment segment (e.g. 130,30 200,100 45,90). The start and end
3013points produced are then joined with a line segment and the resulting segment
3014of an ellipse is filled.</p>
3015
3016<p>Use <code>ellipse</code> to draw a partial (or whole) ellipse. Give the
3017center point, the horizontal and vertical "radii" (the <var>semi-axes</var> of
3018the ellipse) and start and end angles in degrees (e.g. 100,100 100,150
30190,360).</p>
3020
3021<p>The <code>polyline</code> and <code>polygon</code> primitives require three or
3022more points to define their perimeters. A <code>polyline</code> is simply
3023a <code>polygon</code> in which the final point is not stroked to the start
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3024point. When unfilled, this is a <var>polygonal line</var>. If the <a href="command-line-options.html#stroke">-stroke</a> setting is <code>none</code> (the default), then
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3025a <code>polyline</code> is identical to a <code>polygon</code>. </p>
3026
3027<p>A <var>coordinate</var> is a pair of integers separated by a space or
3028optional comma. </p>
3029
3030<p>As an example, to define a circle centered at 100,100 that extends to
3031150,150 use:</p>
3032
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3033<pre>
3034-draw 'circle 100,100 150,150'
3035</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3036
3037<p>The <code>Bezier</code> primitive creates a spline curve and requires three
3038or points to define its shape. The first and last points are the
3039<var>knots</var> and these points are attained by the curve, while any
3040intermediate coordinates are <var>control points</var>. If two control points
3041are specified, the line between each end knot and its sequentially respective
3042control point determines the tangent direction of the curve at that end. If
3043one control point is specified, the lines from the end knots to the one
3044control point determines the tangent directions of the curve at each end. If
3045more than two control points are specified, then the additional control points
3046act in combination to determine the intermediate shape of the curve. In order
3047to draw complex curves, it is highly recommended either to use the
3048<code>path</code> primitive or to draw multiple four-point bezier segments with
3049the start and end knots of each successive segment repeated. For example:</p>
3050
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3051<pre>
3052-draw 'bezier 20,50 45,100 45,0 70,50'
3053-draw 'bezier 70,50 95,100 95,0 120,50'
3054</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3055
3056<p>A <code>path</code> represents an outline of an object, defined in terms of
3057moveto (set a new current point), lineto (draw a straight line), curveto (draw
3058a Bezier curve), arc (elliptical or circular arc) and closepath (close the
3059current shape by drawing a line to the last moveto) elements. Compound paths
3060(i.e., a path with subpaths, each consisting of a single moveto followed by
3061one or more line or curve operations) are possible to allow effects such as
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3062<var>donut holes</var> in objects. (See <a href="http://www.w3.org/TR/SVG/paths.html">Paths</a>.)</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3063
3064<p>Use <code>image</code> to composite an image with another image. Follow the
3065image keyword with the composite operator, image location, image size, and
3066filename:</p>
3067
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3068<pre>
3069-draw 'image SrcOver 100,100 225,225 image.jpg'
3070</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3071
3072<p>You can use 0,0 for the image size, which means to use the actual
3073dimensions found in the image header. Otherwise, it is scaled to the given
3074dimensions. See <a href="compose.html">Alpha Compositing</a> for
3075a detailed discussion of alpha composition methods that are available. </p>
3076
3077<p>The "special augmented compose operators" such as "dissolve" that require
3078arguments cannot be used at present with the <code>-draw image</code> option.
3079 </p>
3080
3081<p>Use <code>text</code> to annotate an image with text. Follow the text
3082coordinates with a string. If the string has embedded spaces, enclose it in
3083single or double quotes.</p>
3084
3085<p>For example, the following annotates the image with <code>Works like
3086magick!</code> for an image titled <code>bird.miff</code>. </p>
3087
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3088<pre>
3089-draw "text 100,100 'Works like magick!' "
3090</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3091
3092<p>See the <a href="command-line-options.html#annotate">-annotate</a> option for another convenient way
3093to annotate an image with text.</p>
3094
3095<p>The <code>rotate</code> primitive rotates subsequent shape primitives and
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3096text primitives about the origin of the main image. If the <a href="command-line-options.html#region">-region</a> option precedes the <a href="command-line-options.html#draw">-draw</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3097option, the origin for transformations is the upper left corner of the
3098region.</p>
3099
3100<p>The <code>translate</code> primitive translates subsequent shape and text
3101primitives.</p>
3102
3103<p>The <code>scale</code> primitive scales them.</p>
3104
3105<p>The <code>skewX</code> and <code>skewY</code> primitives skew them with respect
3106to the origin of the main image or the region.</p>
3107
3108<p>The transformations modify the current affine matrix, which is initialized
3109from the initial affine matrix defined by the <a href="command-line-options.html#affine">-affine</a>
3110option. Transformations are cumulative within the <a href="command-line-options.html#draw">-draw</a>
3111option. The initial affine matrix is not affected; that matrix is only changed
3112by the appearance of another <a href="command-line-options.html#affine">-affine</a> option. If another
3113<a href="command-line-options.html#draw">-draw</a> option appears, the current affine matrix is
3114reinitialized from the initial affine matrix.</p>
3115
3116<p>Use the <code>color</code> primitive to change the color of a pixel to the
3117fill color (see <a href="command-line-options.html#fill">-fill</a>). Follow the pixel coordinate with
3118a method:</p>
3119
3120<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3121point
3122replace
3123floodfill
3124filltoborder
3125reset
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3126</pre>
3127
3128<p>Consider the target pixel as that specified by your coordinate. The
3129<code>point</code> method recolors the target pixel. The <code>replace</code>
3130method recolors any pixel that matches the color of the target pixel.
3131<code>Floodfill</code> recolors any pixel that matches the color of the target
3132pixel and is a neighbor, whereas <code>filltoborder</code> recolors any neighbor
3133pixel that is not the border color. Finally, <code>reset</code> recolors all
3134pixels.</p>
3135
3136<p>Use <code>matte</code> to the change the pixel matte value to transparent.
3137Follow the pixel coordinate with a method (see the <code>color</code> primitive
3138for a description of methods). The <code>point</code> method changes the matte
3139value of the target pixel. The <code>replace</code> method changes the matte
3140value of any pixel that matches the color of the target pixel.
3141<code>Floodfill</code> changes the matte value of any pixel that matches the
3142color of the target pixel and is a neighbor, whereas <code>filltoborder</code>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3143changes the matte value of any neighbor pixel that is not the border color (<a href="command-line-options.html#bordercolor">-bordercolor</a>). Finally <code>reset</code> changes the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3144matte value of all pixels.</p>
3145
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3146<p>You can set the primitive color, font, and font bounding box color with <a href="command-line-options.html#fill">-fill</a>, <a href="command-line-options.html#font">-font</a>, and <a href="command-line-options.html#box">-box</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3147respectively. Options are processed in command line order so be sure to use
3148these options <var>before</var> the <a href="command-line-options.html#draw">-draw</a> option.</p>
3149
3150<p>Strings that begin with a number must be quoted (e.g. use '1.png' rather
3151than 1.png).</p>
3152
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3153<p>Drawing primitives conform to the <a href="magick-vector-graphics.html">Magick
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3154Vector Graphics</a> format.</p>
3155
3156
3157<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3158 <h3 class="magick-header"><a id="duplicate"></a>-duplicate <var>count,indexes</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3159</div>
3160
3161<p class="magick-description">duplicate an image one or more times.</p>
3162
3163<p>Specify the count and the image to duplicate by its index in the sequence.
3164The first image is index 0. Negative indexes are relative to the end of the
3165sequence, for example, -1 represents the last image of the sequence. Specify
3166a range of images with a dash (e.g. 0-4). Separate indexes with a comma (e.g.
31670,2). Use <code>+duplicate</code> to duplicate the last image in the current
3168image sequence.</p>
3169
3170<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3171 <h3 class="magick-header"><a id="edge"></a>-edge <var>radius</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3172</div>
3173
3174<p class="magick-description">detect edges within an image.</p>
3175
3176<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3177 <h3 class="magick-header"><a id="emboss"></a>-emboss <var>radius</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3178</div>
3179
3180<p class="magick-description">emboss an image.</p>
3181
3182<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3183 <h3 class="magick-header"><a id="encipher"></a>-encipher <var>filename</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3184</div>
3185
3186<p class="magick-description">Encipher pixels for later deciphering by <a href="command-line-options.html#decipher">-decipher</a>.</p>
3187
3188<p>Get the passphrase from the file specified by <var>filename</var>.</p>
3189
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3190<p>For more information, see the webpage, <a href="http://www.imagemagick.org/www/cipher.html">ImageMagick: Encipher or
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3191Decipher an Image</a>.</p>
3192
3193
3194
3195<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3196 <h3 class="magick-header"><a id="encoding"></a>-encoding <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3197</div>
3198
3199<p class="magick-description">specify the text encoding.</p>
3200
3201<p>Choose from <code>AdobeCustom</code>, <code>AdobeExpert</code>,
3202<code>AdobeStandard</code>, <code>AppleRoman</code>, <code>BIG5</code>,
3203<code>GB2312</code>, <code>Latin 2</code>, <code>None</code>, <code>SJIScode</code>,
3204<code>Symbol</code>, <code>Unicode</code>, <code>Wansung</code>.</p>
3205
3206<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3207 <h3 class="magick-header"><a id="endian"></a>-endian <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3208</div>
3209
3210<p class="magick-description">Specify endianness (<code>MSB</code> or <code>LSB</code>) of the image.</p>
3211
3212<p>To print a complete list of endian types, use the <a href="command-line-options.html#list">-list endian</a> option.</p>
3213
3214<p>Use <a href="command-line-options.html#endian">+endian</a> to revert to unspecified endianness.</p>
3215
3216
3217<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3218 <h3 class="magick-header"><a id="enhance"></a>-enhance</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3219</div>
3220
3221<p class="magick-description">Apply a digital filter to enhance a noisy image.</p>
3222
3223
3224<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3225 <h3 class="magick-header"><a id="equalize"></a>-equalize</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3226</div>
3227
3228<p class="magick-description">perform histogram equalization on the image channel-by-channel.</p>
3229
3230<p>To perform histogram equalization on all channels in concert, transform the
3231image into some other color space, such as HSL, OHTA, YIQ or YUV, then
3232equalize the appropriate intensity-like channel, then convert back to RGB.</p>
3233
3234<p>For example using HSL, we have: ... <code>-colorspace HSL -channel lightness
3235-equalize -colorspace RGB</code> ...</p>
3236
3237<p>For YIQ, YUV and OHTA use the red channel. For example, OHTA is a principal
3238components transformation that puts most of the information in the first
3239channel. Here we have ... <code>-colorspace OHTA -channel red -equalize
3240-colorspace RGB</code> ...</p>
3241
3242<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3243 <h3 class="magick-header"><a id="evaluate"></a>-evaluate <var>operator value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3244</div>
3245
3246<p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or logical expression.</p>
3247
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3248<p>(See the <a href="command-line-options.html#function">-function</a> operator for some
3249multi-parameter functions. See the <a href="command-line-options.html#fx">-fx</a> operator if more
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3250elaborate calculations are needed.)</p>
3251
3252<p>The behaviors of each <var>operator</var> are summarized in the
3253following list. For brevity, the numerical value of a "pixel" referred to
3254below is the value of the corresponding channel of that pixel, while
3255a "normalized pixel" is that number divided by the maximum
3256(installation-dependent) value <var>QuantumRange</var>. (If
3257normalized pixels are used, they are restored, following the other
3258calculations, to the full range by multiplying by <var>QuantumRange</var>.)</p>
3259
3260<table class="table table-condensed table-striped">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3261 <tr><td># </td><td>arguments meaning</td></tr>
3262 <tr><td>1:</td><td><var>Angle_of_Rotation</var></td></tr>
3263 <tr><td>2:</td><td><var>Scale Angle</var></td></tr>
3264 <tr><td>3:</td><td><var>X,Y Angle</var></td></tr>
3265 <tr><td>4:</td><td><var>X,Y Scale Angle</var></td></tr>
3266 <tr><td>5:</td>
3267 <td><var>X,Y ScaleX,ScaleY Angle</var></td></tr>
3268 <tr><td>6:</td>
3269 <td><var>X,Y Scale Angle NewX,NewY</var></td></tr>
3270 <tr><td>7:</td>
3271 <td><var>X,Y ScaleX,ScaleY Angle
3272 NewX,NewY</var></td></tr>
3273 </table>
3274
3275 This is actually an alternative way of specifying a 2 dimensional linear
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3276 '<code>Affine</code>' or '<code>AffineProjection</code>' distortion.
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3277
3278 <tr>
3279 <td><code>Affine</code></td>
3280 <td>
3281 Distort the image linearly by moving a list of at least 3 or more sets
3282 of control points (as defined below). Ideally 3 sets or 12 floating
3283 point values are given allowing the image to be linearly scaled,
3284 rotated, sheared, and translated, according to those three points. See
3285 also the related '<code>AffineProjection</code>' and '<code>SRT</code>'
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3286 distortions. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3287
3288 More than 3 sets given control point pairs (12 numbers) is least
3289 squares fitted to best match a linear affine distortion. If only 2
3290 control point pairs (8 numbers) are given a two point image translation
3291 rotation and scaling is performed, without any possible shearing,
3292 flipping or changes in aspect ratio to the resulting image. If only one
3293 control point pair is provides the image is only translated, (which may
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3294 be a floating point non-integer translation). <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3295
3296 This distortion does not include any form of perspective distortion.
3297 </td>
3298
3299 </tr>
3300
3301 <tr>
3302 <td><code>AffineProjection</code></td>
3303 <td>
3304 Linearly distort an image using the given Affine Matrix of 6
3305 pre-calculated coefficients forming a set of Affine Equations to map
3306 the source image to the destination image.
3307
3308 <div style="text-align: center"><var>
3309 s<sub>x</sub>, r<sub>x</sub>,
3310 r<sub>y</sub>, s<sub>y</sub>,
3311 t<sub>x</sub>, t<sub>y</sub>
3312 </var></div>
3313
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3314 See <a href="command-line-options.html#affine">-affine</a> setting for more detail, and
3315 meanings of these coefficients. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3316
3317 The distortions '<code>Affine</code>' and '<code>SRT</code>' provide
3318 alternative methods of defining this distortion, with ImageMagick doing
3319 the calculations needed to generate the required coefficients. You can
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3320 see the internally generated coefficients, by using a <a href="command-line-options.html#verbose">-verbose</a> setting with those other variants. </td>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3321
3322 </tr>
3323
3324 <tr>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3325 <td><code>BilinearForward</code><br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3326 <code>BilinearReverse</code></td>
3327 <td>
3328 Bilinear Distortion, given a minimum of 4 sets of coordinate pairs, or
3329 16 values (see below). Not that lines may not appear straight after
3330 distortion, though the distance between coordinates will remain
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3331 consistent. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3332
3333 The '<code>BilinearForward</code>' is used to map rectangles to any
3334 quadrilateral, while the '<code>BilinearReverse</code>' form maps any
3335 quadrilateral to a rectangle, while preserving the straight line edges
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3336 in each case. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3337
3338 Note that '<code>BilinearForward</code>' can generate invalid pixels
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3339 which will be colored using the <a href="command-line-options.html#mattecolor">-mattecolor</a>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3340 color setting. Also if the quadrilateral becomes 'flipped' the image
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3341 may disappear. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3342
3343 There are future plans to produce a true Bilinear distortion that will
3344 attempt to map any quadrilateral to any other quadrilateral, while
3345 preserving edges (and edge distance ratios).
3346
3347 </td>
3348 </tr>
3349
3350 <tr>
3351 <td><code>Perspective</code></td>
3352 <td>
3353 Perspective distort the images, using a list of 4 or more sets of
3354 control points (as defined below). More that 4 sets (16 numbers) of
3355 control points provide least squares fitting for more accurate
3356 distortions (for the purposes of image registration and panorama
3357 effects). Less than 4 sets will fall back to a '<code>Affine</code>'
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3358 linear distortion. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3359
3360 Perspective Distorted images ensures that straight lines remain
3361 straight, but the scale of the distorted image will vary. The horizon
3362 is anti-aliased, and the 'sky' color may be set using the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3363 <a href="command-line-options.html#mattecolor">-mattecolor</a> setting. </td>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3364 </tr>
3365
3366 <tr>
3367 <td><code>PerspectiveProjection</code> </td>
3368 <td>
3369 Do a '<code>Perspective</code>' distortion biased on a set of 8
3370 pre-calculated coefficients. You can get these coefficients by looking
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3371 at the <a href="command-line-options.html#verbose">-verbose</a> output of a
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3372 '<code>Perspective</code>' distortion, or by calculating them yourself.
3373 If the last two perspective scaling coefficients are zero, the
3374 remaining 6 represents a transposed 'Affine Matrix'. </td>
3375
3376 </tr>
3377
3378 <tr>
3379 <td><code>Arc</code></td>
3380 <td>
3381 Arc the image (variation of polar mapping) over the angle given around
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3382 a circle. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3383 <table class="table table-condensed table-striped">
3384 <tr><td>Argument</td>
3385 <td>Meaning</td></tr>
3386 <tr><td><var>arc_angle</var></td>
3387 <td>The angle over which to arc the image side-to-side</td></tr>
3388 <tr><td><var>rotate_angle</var></td>
3389 <td>Angle to rotate resulting image from vertical center</td></tr>
3390 <tr><td><var>top_radius</var></td>
3391 <td>Set top edge of source image at this radius</td></tr>
3392 <tr><td><var>bottom_radius</var> </td>
3393 <td>Set bottom edge to this radius (radial scaling)</td></tr>
3394 </table>
3395
3396 The resulting image is always resized to best fit the resulting image,
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3397 (as if using <a href="command-line-options.html#distort">+distort</a>) while attempting to
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3398 preserve scale and aspect ratio of the original image as much as
3399 possible with the arguments given by the user. All four arguments will
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3400 be needed to change the overall aspect ratio of an 'Arc'ed image. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3401
3402 This a variation of a polar distortion designed to try to preserve the
3403 aspect ratio of the image rather than direct Cartesian to Polar
3404 conversion. </td>
3405 </tr>
3406
3407 <tr>
3408 <td><code>Polar</code></td>
3409 <td>
3410 Like '<code>Arc</code>' but do a complete Cartesian to Polar mapping of
3411 the image. that is the height of the input image is mapped to the
3412 radius limits, while the width is wrapped around between the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3413 angle limits. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3414
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3415 Arguments: <var>Rmax,Rmin CenterX,CenterY, start,end_angle</var> <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3416
3417 All arguments are optional. With <var>Rmin</var> defaulting to zero, the
3418 center to the center of the image, and the angles going from -180 (top)
3419 to +180 (top). If <var>Rmax</var> is given the special value of
3420 '<code>0</code>', the the distance from the center to the nearest edge
3421 is used for the radius of the output image, which will ensure the whole
3422 image is visible (though scaled smaller). However a special value of
3423 '<code>-1</code>' will use the distance from the center to the furthest
3424 corner, This may 'clip' the corners from the input rectangular image,
3425 but will generate the exact reverse of a '<code>DePolar</code>' with
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3426 the same arguments. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3427
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3428 If the plus form of distort (<a href="command-line-options.html#distort">+distort</a>) is used
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3429 output image center will default to <code>0,0</code> of the virtual
3430 canvas, and the image size adjusted to ensure the whole input image is
3431 made visible in the output image on the virtual canvas. </td>
3432
3433 </tr>
3434
3435 <tr>
3436 <td><code>DePolar</code></td>
3437 <td>
3438 Uses the same arguments and meanings as a '<code>Polar</code>' distortion
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3439 but generates the reverse Polar to Cartesian distortion. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3440
3441 The special <var>Rmax</var> setting of '<code>0</code>' may however clip
3442 the corners of the input image. However using the special
3443 <var>Rmax</var> setting of '<code>-1</code>' (maximum center to corner
3444 distance) will ensure the whole distorted image is preserved in the
3445 generated result, so that the same argument to '<code>Polar</code>' will
3446 reverse the distortion re-producing the original.
3447
3448 Note that as this distortion requires the area resampling of a circular
3449 arc, which can not be handled by the builtin EWA resampling function.
3450 As such the normal EWA filters are turned off. It is recommended some
3451 form of 'super-sampling' image processing technique be used to produce
3452 a high quality result. </td>
3453
3454 </tr>
3455
3456 <tr>
3457 <td><code>Barrel</code></td>
3458 <td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3459 Given the four coefficients (A,B,C,D) as defined by <a href="http://wiki.panotools.org/Lens_correction_model">Helmut
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3460 Dersch</a>, perform a barrel or pin-cushion distortion appropriate to
3461 correct radial lens distortions. That is in photographs, make straight
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3462 lines straight again. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3463
3464 Arguments: <var>A B C</var> [ <var>D</var> [
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3465 <var>X</var> , <var>Y</var> ] ] <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3466 or <var>A<sub>x</sub> B<sub>x</sub> C<sub>x</sub> D<sub>x</sub>
3467 A<sub>y</sub> B<sub>y</sub> C<sub>y</sub> D<sub>y</sub></var>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3468 [ <var>X</var> , <var>Y</var> ] <br>
3469 So that it forms the function <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3470 Rsrc = r * ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> +
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3471 <var>C</var>*r + <var>D</var> )<br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3472
3473 Where <var>X</var>,<var>Y</var> is the optional center of the distortion
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3474 (defaulting to the center of the image). <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3475 The second form is typically used to distort images, rather than
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3476 correct lens distortions. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3477 </td>
3478
3479 </tr>
3480
3481 <tr>
3482 <td><code>BarrelInverse</code></td>
3483 <td>
3484 This is very similar to '<code>Barrel</code>' with the same set of
3485 arguments, and argument handling. However it uses the inverse
3486 of the radial polynomial,
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3487 so that it forms the function <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3488 Rsrc = r / ( <var>A</var>*r<sup>3</sup> + <var>B</var>*r<sup>2</sup> +
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3489 <var>C</var>*r + <var>D</var> )<br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3490 Note that this is not the reverse of the '<code>Barrel</code>'
3491 distortion, just a different barrel-like radial distortion method.
3492
3493 </td>
3494 </tr>
3495
3496 <tr>
3497 <td><code>Shepards</code></td>
3498 <td>
3499 Distort the given list control points (any number) using an Inverse
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3500 Squared Distance Interpolation Method (<a href="http://en.wikipedia.org/wiki/Shepard%27s_method">Shepards
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3501 Method</a>). The control points in effect do 'localized' displacement
3502 of the image around the given control point (preserving the look and
3503 the rotation of the area near the control points. For best results
3504 extra control points should be added to 'lock' the positions of the
3505 corners, edges and other unchanging parts of the image, to prevent
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3506 their movement. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3507
3508 The distortion has been likened to 'taffy pulling' using nails, or
3509 pins' stuck in a block of 'jelly' which is then moved to the new
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3510 position, distorting the surface of the jelly. <br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3511
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3512 Internally it is equivalent to generating a displacement map (see <a href="command-line-options.html#displace">-displace</a>) for source image color look-up using
3513 the <a href="command-line-options.html#sparse-color">-sparse-color</a> method of the same name.
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3514
3515 </td>
3516 </tr>
3517
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3518
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3519
3520<p>To print a complete list of distortion methods, use <a href="command-line-options.html#list">-list
3521distort</a>.</p>
3522
3523<p>Many of the above distortion methods such as '<code>Affine</code>',
3524'<code>Perspective</code>', and '<code>Shepards</code>' use a list control points
3525defining how these points in the given image should be distorted in the
3526destination image. Each set of four floating point values represent a source
3527image coordinate, followed immediately by the destination image coordinate.
3528This produces a list of values such as...</p>
3529<div style="text-align: center"><var>
3530 U<sub>1</sub>,V<sub>1</sub> X<sub>1</sub>,Y<sub>1</sub>
3531 U<sub>2</sub>,V<sub>2</sub> X<sub>2</sub>,Y<sub>2</sub>
3532 U<sub>3</sub>,V<sub>3</sub> X<sub>3</sub>,Y<sub>3</sub>
3533 ...
3534 U<sub>n</sub>,V<sub>n</sub> X<sub>n</sub>,Y<sub>n</sub>
3535</var></div>
3536<p>where <var>U,V</var> on the source image is mapped to <var>X,Y</var> on the
3537destination image. </p>
3538
3539<p>For example, to warp an image using '<code>perspective</code>' distortion,
3540needs a list of at least 4 sets of coordinates, or 16 numbers. Here is the
3541perspective distortion of the built-in "rose:" image. Note how spaces were
3542used to group the 4 sets of coordinate pairs, to make it easier to read and
3543understand.</p>
3544
3545<pre>
3546convert rose: -virtual-pixel black \
3547 -distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35' \
3548 rose_3d_rotated.gif"
3549</pre>
3550
3551<p>If more that the required number of coordinate pairs are given for
3552a distortion, the distortion method is 'least squares' fitted to produce the
3553best result for all the coordinate pairs given. If less than the ideal number
3554of points are given, the distort will generally fall back to a simpler form of
3555distortion that can handles the smaller number of coordinates (usually a linear
3556'<code>Affine</code>' distortion). </p>
3557
3558<p>By using more coordinates you can make use of image registration tool to
3559find matching coordinate pairs in overlapping images, so as to improve the
3560'fit' of the distortion. Of course a bad coordinate pair can also make the
3561'fit' worse. Caution is always advised. </p>
3562
3563<p>Colors are acquired from the source image according to a cylindrical
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3564resampling <a href="command-line-options.html#filter">-filter</a>, using a special technique known as
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3565EWA resampling. This produces very high quality results, especially when
3566images become smaller (minified) in the output, which is very common when
3567using '<code>perspective</code>' distortion. For example here we view
3568a infinitely tiled 'plane' all the way to the horizon. </p>
3569
3570<pre>
3571convert -size 90x90 pattern:checkerboard -normalize -virtual-pixel tile \
3572 -distort perspective '0,0,5,45 89,0,45,46 0,89,0,89 89,89,89,89' \
3573 checks_tiled.jpg
3574</pre>
3575
3576<p>Note that a infinitely tiled perspective images involving the horizon can
3577be very slow, because of the number of pixels that are compressed to generate
3578each individual pixel close to the 'horizon'. You can turn off EWA
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3579resampling, by specifing the special <a href="command-line-options.html#filter">-filter</a> setting of
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3580'<code>point</code>' (recommended if you plan to use super-sampling instead).
3581</p>
3582
3583<p>If an image generates <i>invalid pixels</i>, such as the 'sky' in the last
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3584example, <a href="command-line-options.html#distort">-distort</a> will use the current <a href="command-line-options.html#mattecolor">-mattecolor</a> setting for these pixels. If you do not
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3585what these pixels to be visible, set the color to match the rest of the
3586ground. </p>
3587
3588<p>The output image size will by default be the same as the input image. This
3589means that if the part of the distorted image falls outside the viewed area of
3590the 'distorted space', those parts is clipped and lost. However if you use
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3591the plus form of the operator (<a href="command-line-options.html#distort">+distort</a>) the operator
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3592will attempt (if possible) to show the whole of the distorted image, while
3593retaining a correct 'virtual canvas' offset, for image layering. This offset
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3594may need to be removed using <a href="command-line-options.html#repage">+repage</a>, to remove if it
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3595is unwanted. </p>
3596
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3597<p>Setting <a href="command-line-options.html#verbose">-verbose</a> setting, will cause <a href="command-line-options.html#distort">-distort</a> to attempt to output the internal coefficients,
3598and the <a href="command-line-options.html#fx">-fx</a> equivalent to the distortion, for expert study,
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3599and debugging purposes. This many not be available for all distorts. </p>
3600
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3601<p>You can alternatively specify a special "<code><a href="command-line-options.html#define">-define</a> distort:viewport={geometry_string}</code>" setting which will
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3602specify the size and the offset of the generated 'viewport' image of the
3603distorted image space.</p>
3604
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3605<p>Setting a "<code><a href="command-line-options.html#define">-define</a>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3606distort:scale={scale_factor}</code>" will scale the output image (viewport or
3607otherwise) by that factor without changing the viewed contents of the
3608distorted image. This can be used either for 'super-sampling' the image for
3609a higher quality result, or for panning and zooming around the image (with
3610appropriate viewport changes, or post-distort cropping and resizing). </p>
3611
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3612<p>Setting "<code><a href="command-line-options.html#define">-define</a> resample:verbose=1</code>"
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3613will output the cylindrical filter lookup table created by the EWA (Elliptical
3614Weighted Average) resampling algorithm. Note this table uses a squared radius
3615lookup value. This is typically only used for debugging EWA resampling. </p>
3616
3617
3618<div style="margin: auto;">
3619 <h3 class="magick-header"><a id="distribute-cache"></a>-distribute-cache <var>port</var></h3>
3620</div>
3621
3622<p class="magick-description">launch a distributed pixel cache server. </p>
3623
3624<div style="margin: auto;">
3625 <h3 class="magick-header"><a id="dither"></a>-dither <var>method</var></h3>
3626</div>
3627
3628<p class="magick-description">Apply a Riemersma or Floyd-Steinberg error diffusion dither to
3629images when general color reduction is applied via an option, or automagically
3630when saving to specific formats. This enabled by default.</p>
3631
3632<p>Dithering places two or more colors in neighboring pixels so that to the
3633eye a closer approximation of the images original color is reproduced. This
3634reduces the number of colors needed to reproduce the image but at the cost of
3635a lower level pattern of colors. Error diffusion dithers can use any set of
3636colors (generated or user defined) to an image. </p>
3637
3638<p>Dithering is turned on by default, to turn it off use the plus form of the
3639setting, <a href="command-line-options.html#dither">+dither</a>. This will also also render PostScript
3640without text or graphic aliasing. Disabling dithering often (but not always)
3641leads to faster process, a smaller number of colors, but more cartoon like
3642image coloring. Generally resulting in 'color banding' effects in areas with
3643color gradients. </p>
3644
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3645<p>The color reduction operators <a href="command-line-options.html#colors">-colors</a>, <a href="command-line-options.html#monochrome">-monochrome</a>, <a href="command-line-options.html#remap%20">-remap</a>, and <a href="command-line-options.html#posterize">-posterize</a>, apply dithering to images using the reduced
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3646color set they created. These operators are also used as part of automatic
3647color reduction when saving images to formats with limited color support, such
3648as <code>GIF:</code>, <code>XBM:</code>, and others, so dithering may also be used
3649in these cases. </p>
3650
3651<p>Alternatively you can use <a href="command-line-options.html#random-threshold">-random-threshold</a>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3652to generate purely random dither. Or use <a href="command-line-options.html#ordered-dither">-ordered-dither</a> to apply threshold mapped dither
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3653patterns, using uniform color maps, rather than specific color maps. </p>
3654
3655
3656<div style="margin: auto;">
3657 <h3 class="magick-header"><a id="draw"></a>-draw <var>string</var></h3>
3658</div>
3659
3660<p class="magick-description">Annotate an image with one or more graphic primitives.</p>
3661
3662<p>Use this option to annotate or decorate an image with one or more graphic
3663primitives. The primitives include shapes, text, transformations, and pixel
3664operations.</p>
3665
3666<p>The shape primitives:</p>
3667
3668<pre>
3669point x,y
3670line x0,y0 x1,y1
3671rectangle x0,y0 x1,y1
3672roundRectangle x0,y0 x1,y1 wc,hc
3673arc x0,y0 x1,y1 a0,a1
3674ellipse x0,y0 rx,ry a0,a1
3675circle x0,y0 x1,y1
3676polyline x0,y0 ... xn,yn
3677polygon x0,y0 ... xn,yn
3678bezier x0,y0 ... xn,yn
3679path specification
3680image operator x0,y0 w,h filename
3681</pre>
3682
3683<p>The text primitive:</p>
3684
3685<pre>
3686text x0,y0 string
3687</pre>
3688<p>The text gravity primitive:</p>
3689
3690<pre>
3691gravity NorthWest, North, NorthEast, West, Center,
3692 East, SouthWest, South, or SouthEast
3693</pre>
3694
3695<p>The text gravity primitive only affects the placement of text and does not
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3696interact with the other primitives. It is equivalent to using the <a href="command-line-options.html#gravity">-gravity</a> command-line option, except that it is limited in
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3697scope to the <a href="command-line-options.html#draw">-draw</a> option in which it appears.</p>
3698
3699<p>The transformation primitives:</p>
3700
3701<pre>
3702rotate degrees
3703translate dx,dy
3704scale sx,sy
3705skewX degrees
3706skewY degrees
3707</pre>
3708
3709<p>The pixel operation primitives:</p>
3710
3711<pre>
3712color x0,y0 method
3713matte x0,y0 method
3714</pre>
3715
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3716<p>The shape primitives are drawn in the color specified by the preceding <a href="command-line-options.html#fill">-fill</a> setting. For unfilled shapes, use <a href="command-line-options.html#fill">-fill none</a>. You can optionally control the stroke (the
3717"outline" of a shape) with the <a href="command-line-options.html#stroke">-stroke</a> and <a href="command-line-options.html#strokewidth">-strokewidth</a> settings.</p>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3718
3719<p>A <code>point</code> primitive is specified by a single <var>point</var> in the
3720pixel plane, that is, by an ordered pair of integer coordinates,
3721<var>x</var>,<var>y</var>. (As it involves only a single pixel, a <code>point</code>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3722primitive is not affected by <a href="command-line-options.html#stroke">-stroke</a> or <a href="command-line-options.html#strokewidth">-strokewidth</a>.)</p>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3723
3724<p>A <code>line</code> primitive requires a start point and end point.</p>
3725
3726<p>A <code>rectangle</code> primitive is specified by the pair of points at the
3727upper left and lower right corners.</p>
3728
3729<p>A <code>roundRectangle</code> primitive takes the same corner points as
3730a <code>rectangle</code> followed by the width and height of the rounded corners
3731to be removed.</p>
3732
3733<p>The <code>circle</code> primitive makes a disk (filled) or circle (unfilled).
3734Give the center and any point on the perimeter (boundary).</p>
3735
3736<p>The <code>arc</code> primitive is used to inscribe an elliptical segment in
3737to a given rectangle. An <code>arc</code> requires the two corners used for
3738<code>rectangle</code> (see above) followed by the start and end angles of the
3739arc of the segment segment (e.g. 130,30 200,100 45,90). The start and end
3740points produced are then joined with a line segment and the resulting segment
3741of an ellipse is filled.</p>
3742
3743<p>Use <code>ellipse</code> to draw a partial (or whole) ellipse. Give the
3744center point, the horizontal and vertical "radii" (the <var>semi-axes</var> of
3745the ellipse) and start and end angles in degrees (e.g. 100,100 100,150
37460,360).</p>
3747
3748<p>The <code>polyline</code> and <code>polygon</code> primitives require three or
3749more points to define their perimeters. A <code>polyline</code> is simply
3750a <code>polygon</code> in which the final point is not stroked to the start
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3751point. When unfilled, this is a <var>polygonal line</var>. If the <a href="command-line-options.html#stroke">-stroke</a> setting is <code>none</code> (the default), then
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3752a <code>polyline</code> is identical to a <code>polygon</code>. </p>
3753
3754<p>A <var>coordinate</var> is a pair of integers separated by a space or
3755optional comma. </p>
3756
3757<p>As an example, to define a circle centered at 100,100 that extends to
3758150,150 use:</p>
3759
3760<pre>
3761-draw 'circle 100,100 150,150'
3762</pre>
3763
3764<p>The <code>Bezier</code> primitive creates a spline curve and requires three
3765or points to define its shape. The first and last points are the
3766<var>knots</var> and these points are attained by the curve, while any
3767intermediate coordinates are <var>control points</var>. If two control points
3768are specified, the line between each end knot and its sequentially respective
3769control point determines the tangent direction of the curve at that end. If
3770one control point is specified, the lines from the end knots to the one
3771control point determines the tangent directions of the curve at each end. If
3772more than two control points are specified, then the additional control points
3773act in combination to determine the intermediate shape of the curve. In order
3774to draw complex curves, it is highly recommended either to use the
3775<code>path</code> primitive or to draw multiple four-point bezier segments with
3776the start and end knots of each successive segment repeated. For example:</p>
3777
3778<pre>
3779-draw 'bezier 20,50 45,100 45,0 70,50'
3780-draw 'bezier 70,50 95,100 95,0 120,50'
3781</pre>
3782
3783
3784<p>A <code>path</code> represents an outline of an object, defined in terms of
3785moveto (set a new current point), lineto (draw a straight line), curveto (draw
3786a Bezier curve), arc (elliptical or circular arc) and closepath (close the
3787current shape by drawing a line to the last moveto) elements. Compound paths
3788(i.e., a path with subpaths, each consisting of a single moveto followed by
3789one or more line or curve operations) are possible to allow effects such as
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3790<var>donut holes</var> in objects. (See <a href="http://www.w3.org/TR/SVG/paths.html">Paths</a>.)</p>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3791
3792<p>Use <code>image</code> to composite an image with another image. Follow the
3793image keyword with the composite operator, image location, image size, and
3794filename:</p>
3795
3796<pre>
3797-draw 'image SrcOver 100,100 225,225 image.jpg'
3798</pre>
3799
3800<p>You can use 0,0 for the image size, which means to use the actual
3801dimensions found in the image header. Otherwise, it is scaled to the given
3802dimensions. See <a href="compose.html">Alpha Compositing</a> for
3803a detailed discussion of alpha composition methods that are available. </p>
3804
3805<p>The "special augmented compose operators" such as "dissolve" that require
3806arguments cannot be used at present with the <code>-draw image</code> option.
3807 </p>
3808
3809<p>Use <code>text</code> to annotate an image with text. Follow the text
3810coordinates with a string. If the string has embedded spaces, enclose it in
3811single or double quotes.</p>
3812
3813<p>For example, the following annotates the image with <code>Works like
3814magick!</code> for an image titled <code>bird.miff</code>. </p>
3815
3816<pre>
3817-draw "text 100,100 'Works like magick!' "
3818</pre>
3819
3820<p>See the <a href="command-line-options.html#annotate">-annotate</a> option for another convenient way
3821to annotate an image with text.</p>
3822
3823<p>The <code>rotate</code> primitive rotates subsequent shape primitives and
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3824text primitives about the origin of the main image. If the <a href="command-line-options.html#region">-region</a> option precedes the <a href="command-line-options.html#draw">-draw</a>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3825option, the origin for transformations is the upper left corner of the
3826region.</p>
3827
3828<p>The <code>translate</code> primitive translates subsequent shape and text
3829primitives.</p>
3830
3831<p>The <code>scale</code> primitive scales them.</p>
3832
3833<p>The <code>skewX</code> and <code>skewY</code> primitives skew them with respect
3834to the origin of the main image or the region.</p>
3835
3836<p>The transformations modify the current affine matrix, which is initialized
3837from the initial affine matrix defined by the <a href="command-line-options.html#affine">-affine</a>
3838option. Transformations are cumulative within the <a href="command-line-options.html#draw">-draw</a>
3839option. The initial affine matrix is not affected; that matrix is only changed
3840by the appearance of another <a href="command-line-options.html#affine">-affine</a> option. If another
3841<a href="command-line-options.html#draw">-draw</a> option appears, the current affine matrix is
3842reinitialized from the initial affine matrix.</p>
3843
3844<p>Use the <code>color</code> primitive to change the color of a pixel to the
3845fill color (see <a href="command-line-options.html#fill">-fill</a>). Follow the pixel coordinate with
3846a method:</p>
3847
3848<pre>
3849point
3850replace
3851floodfill
3852filltoborder
3853reset
3854</pre>
3855
3856<p>Consider the target pixel as that specified by your coordinate. The
3857<code>point</code> method recolors the target pixel. The <code>replace</code>
3858method recolors any pixel that matches the color of the target pixel.
3859<code>Floodfill</code> recolors any pixel that matches the color of the target
3860pixel and is a neighbor, whereas <code>filltoborder</code> recolors any neighbor
3861pixel that is not the border color. Finally, <code>reset</code> recolors all
3862pixels.</p>
3863
3864<p>Use <code>matte</code> to the change the pixel matte value to transparent.
3865Follow the pixel coordinate with a method (see the <code>color</code> primitive
3866for a description of methods). The <code>point</code> method changes the matte
3867value of the target pixel. The <code>replace</code> method changes the matte
3868value of any pixel that matches the color of the target pixel.
3869<code>Floodfill</code> changes the matte value of any pixel that matches the
3870color of the target pixel and is a neighbor, whereas <code>filltoborder</code>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3871changes the matte value of any neighbor pixel that is not the border color (<a href="command-line-options.html#bordercolor">-bordercolor</a>). Finally <code>reset</code> changes the
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3872matte value of all pixels.</p>
3873
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3874<p>You can set the primitive color, font, and font bounding box color with <a href="command-line-options.html#fill">-fill</a>, <a href="command-line-options.html#font">-font</a>, and <a href="command-line-options.html#box">-box</a>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3875respectively. Options are processed in command line order so be sure to use
3876these options <var>before</var> the <a href="command-line-options.html#draw">-draw</a> option.</p>
3877
3878<p>Strings that begin with a number must be quoted (e.g. use '1.png' rather
3879than 1.png).</p>
3880
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3881<p>Drawing primitives conform to the <a href="magick-vector-graphics.html">Magick
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3882Vector Graphics</a> format.</p>
3883
3884
3885<div style="margin: auto;">
3886 <h3 class="magick-header"><a id="duplicate"></a>-duplicate <var>count,indexes</var></h3>
3887</div>
3888
3889<p class="magick-description">duplicate an image one or more times.</p>
3890
3891<p>Specify the count and the image to duplicate by its index in the sequence.
3892The first image is index 0. Negative indexes are relative to the end of the
3893sequence, for example, -1 represents the last image of the sequence. Specify
3894a range of images with a dash (e.g. 0-4). Separate indexes with a comma (e.g.
38950,2). Use <code>+duplicate</code> to duplicate the last image in the current
3896image sequence.</p>
3897
3898<div style="margin: auto;">
3899 <h3 class="magick-header"><a id="edge"></a>-edge <var>radius</var></h3>
3900</div>
3901
3902<p class="magick-description">detect edges within an image.</p>
3903
3904<div style="margin: auto;">
3905 <h3 class="magick-header"><a id="emboss"></a>-emboss <var>radius</var></h3>
3906</div>
3907
3908<p class="magick-description">emboss an image.</p>
3909
3910<div style="margin: auto;">
3911 <h3 class="magick-header"><a id="encipher"></a>-encipher <var>filename</var></h3>
3912</div>
3913
3914<p class="magick-description">Encipher pixels for later deciphering by <a href="command-line-options.html#decipher">-decipher</a>.</p>
3915
3916<p>Get the passphrase from the file specified by <var>filename</var>.</p>
3917
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3918<p>For more information, see the webpage, <a href="http://www.imagemagick.org/www/cipher.html">ImageMagick: Encipher or
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3919Decipher an Image</a>.</p>
3920
3921
3922
3923<div style="margin: auto;">
3924 <h3 class="magick-header"><a id="encoding"></a>-encoding <var>type</var></h3>
3925</div>
3926
3927<p class="magick-description">specify the text encoding.</p>
3928
3929<p>Choose from <code>AdobeCustom</code>, <code>AdobeExpert</code>,
3930<code>AdobeStandard</code>, <code>AppleRoman</code>, <code>BIG5</code>,
3931<code>GB2312</code>, <code>Latin 2</code>, <code>None</code>, <code>SJIScode</code>,
3932<code>Symbol</code>, <code>Unicode</code>, <code>Wansung</code>.</p>
3933
3934<div style="margin: auto;">
3935 <h3 class="magick-header"><a id="endian"></a>-endian <var>type</var></h3>
3936</div>
3937
3938<p class="magick-description">Specify endianness (<code>MSB</code> or <code>LSB</code>) of the image.</p>
3939
3940<p>To print a complete list of endian types, use the <a href="command-line-options.html#list">-list endian</a> option.</p>
3941
3942<p>Use <a href="command-line-options.html#endian">+endian</a> to revert to unspecified endianness.</p>
3943
3944
3945<div style="margin: auto;">
3946 <h3 class="magick-header"><a id="enhance"></a>-enhance</h3>
3947</div>
3948
3949<p class="magick-description">Apply a digital filter to enhance a noisy image.</p>
3950
3951
3952<div style="margin: auto;">
3953 <h3 class="magick-header"><a id="equalize"></a>-equalize</h3>
3954</div>
3955
3956<p class="magick-description">perform histogram equalization on the image channel-by-channel.</p>
3957
3958<p>To perform histogram equalization on all channels in concert, transform the
3959image into some other color space, such as HSL, OHTA, YIQ or YUV, then
3960equalize the appropriate intensity-like channel, then convert back to RGB.</p>
3961
3962<p>For example using HSL, we have: ... <code>-colorspace HSL -channel lightness
3963-equalize -colorspace RGB</code> ...</p>
3964
3965<p>For YIQ, YUV and OHTA use the red channel. For example, OHTA is a principal
3966components transformation that puts most of the information in the first
3967channel. Here we have ... <code>-colorspace OHTA -channel red -equalize
3968-colorspace RGB</code> ...</p>
3969
3970<div style="margin: auto;">
3971 <h3 class="magick-header"><a id="evaluate"></a>-evaluate <var>operator value</var></h3>
3972</div>
3973
3974<p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or logical expression.</p>
3975
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3976<p>(See the <a href="command-line-options.html#function">-function</a> operator for some
3977multi-parameter functions. See the <a href="command-line-options.html#fx">-fx</a> operator if more
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]3978elaborate calculations are needed.)</p>
3979
3980<p>The behaviors of each <var>operator</var> are summarized in the
3981following list. For brevity, the numerical value of a "pixel" referred to
3982below is the value of the corresponding channel of that pixel, while
3983a "normalized pixel" is that number divided by the maximum
3984(installation-dependent) value <var>QuantumRange</var>. (If
3985normalized pixels are used, they are restored, following the other
3986calculations, to the full range by multiplying by <var>QuantumRange</var>.)</p>
3987
3988<table class="table table-condensed table-striped">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]3989 <col width="25%">
3990 <col width="75%">
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]3991 <thead>
3992 <tr>
3993 <th><var>operator</var></th>
3994 <th>Summary (see further below for details)</th>
3995 </tr>
3996 </thead>
3997 <tbody>
3998
3999 <tr><td>Abs </td> <td>Add <var>value</var> to pixels and return absolute value. </td></tr>
4000 <tr><td>Add </td> <td>Add <var>value</var> to pixels. </td></tr>
4001 <tr><td>AddModulus </td> <td>Add <var>value</var> to pixels modulo <var>QuantumRange</var>.</td></tr>
4002 <tr><td>And </td> <td>Binary AND of pixels with <var>value</var>.</td></tr>
4003 <tr><td>Cos, Cosine </td> <td>Apply cosine to pixels with frequency <var>value</var> with 50% bias added.</td></tr>
4004 <tr><td>Divide </td> <td>Divide pixels by <var>value</var>.</td></tr>
4005 <tr><td>Exp </td> <td>base-e exponential function</td></tr>
4006 <tr><td>Exponential </td> <td>base-e exponential function</td></tr>
4007 <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>
4008 <tr><td>Log </td> <td>Apply scaled logarithm to normalized pixels.</td></tr>
4009 <tr><td>Max </td> <td>Clip pixels at lower bound <var>value</var>.</td></tr>
4010 <tr><td>Mean </td> <td>Add the <var>value</var> and divide by 2.</td></tr>
4011 <tr><td>Median </td> <td>Choose the median value from an image sequence.</td></tr>
4012 <tr><td>Min </td> <td>Clip pixels at upper bound <var>value</var>.</td></tr>
4013 <tr><td>Multiply </td> <td>Multiply pixels by <var>value</var>.</td></tr>
4014 <tr><td>Or </td> <td>Binary OR of pixels with <var>value</var>.</td></tr>
4015 <tr><td>Pow </td> <td>Raise normalized pixels to the power <var>value</var>.</td></tr>
4016 <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>
4017 <tr><td>RMS</td> <td>Square the pixel and add the <var>value</var>.</td></tr>
4018 <tr><td>RootMeanSquare</td> <td>Square the pixel and add the <var>value</var>.</td></tr>
4019 <tr><td>Set </td> <td>Set pixel equal to <var>value</var>.</td></tr>
4020 <tr><td>Sin, Sine </td> <td>Apply sine to pixels with frequency <var>value</var> with 50% bias added.</td></tr>
4021 <tr><td>Subtract </td> <td>Subtract <var>value</var> from pixels.</td></tr>
4022 <tr><td>Xor </td> <td>Binary XOR of pixels with <var>value.</var></td></tr>
4023
4024 <tr><td> </td></tr>
4025
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4026 <tr><td>Gaussian-noise</td><td> </td></tr>
4027 <tr><td>Impulse-noise</td><td> </td></tr>
4028 <tr><td>Laplacian-noise</td><td> </td></tr>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4029 <tr><td>Multiplicative-noise</td> <td>(These are equivalent to the corresponding <a href="command-line-options.html#noise">-noise</a> operators.)</td></tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4030 <tr><td>PoissonNoise</td><td> </td></tr>
4031 <tr><td>Uniform-noise</td><td> </td></tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4032
4033 <tr><td> </td></tr>
4034
4035 <tr><td>Threshold </td> <td>Threshold pixels larger than <var>value</var>.</td></tr>
4036 <tr><td>ThresholdBlack </td> <td>Threshold pixels to zero values equal to or below <var>value</var>.</td></tr>
4037 <tr><td>ThresholdWhite </td> <td>Threshold pixels to maximum values above <var>value</var>. </td></tr>
4038 </tbody>
4039 </table>
4040
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4041<p>The specified functions are applied only to each previously set <a href="command-line-options.html#channel">-channel</a> in the image. If necessary, the results of the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4042calculations are truncated (clipped) to fit in the interval [0, <var>QuantumRange</var>]. The transparency channel of the image is
4043represented as a 'alpha' values (0 = fully transparent), so, for example, a
4044<code>Divide</code> by 2 of the alpha channel will make the image
4045semi-transparent. Append the percent symbol '<code>%</code>' to specify a value
4046as a percentage of the <var>QuantumRange</var>.</p>
4047
4048<p>To print a complete list of <a href="command-line-options.html#evaluate">-evaluate</a> operators, use
4049<a href="command-line-options.html#list">-list evaluate</a>.</p>
4050
4051<p>The results of the <code>Add</code>, <code>Subtract</code> and
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4052<code>Multiply</code> methods can also be achieved using either the <a href="command-line-options.html#level">-level</a> or the <a href="command-line-options.html#level">+level</a> operator, with
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4053appropriate argument, to linearly modify the overall range of color values.
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4054Please note, however, that <a href="command-line-options.html#level">-level</a> treats transparency as
4055'matte' values (0 = opaque), while <a href="command-line-options.html#level">-evaluate</a> works with
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4056'alpha' values.</p>
4057
4058<p><code>AddModulus</code> has been added as of ImageMagick 6.4.8-4 and provides
4059addition modulo the <var>QuantumRange</var>. It is therefore
4060equivalent to <code>Add</code> unless the resulting pixel value is outside the
4061interval [0, <var>QuantumRange</var>]. </p>
4062
4063<p><code>Exp or Exponential</code> has been added as of ImageMagick 6.6.5-1 and
4064works on normalized pixel values. The <var>value</var> used with
4065<code>Exp</code> should be negative so as to produce a decaying exponential
4066function. Non-negative values will always produce results larger unity and
4067thus outside the interval [0, <var>QuantumRange</var>]. The
4068formula is expressed below. </p>
4069
4070 <div style="text-align:center;">
4071 exp(<var>value</var> × <b><var>u</var></b>)
4072 </div>
4073
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4074<p> If the input image is squared, for example, using <a href="command-line-options.html#-function">-function polynomial "2 0 0"</a>, then a decaying Gaussian function will be
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4075the result.</p>
4076
4077<p><code>Log</code> has been added as of ImageMagick 6.4.2-1 and works on
4078normalized pixel values. This a <var>scaled</var> log function. The <var>value</var> used with <code>Log</code> provides a <var>scaling
4079factor</var> that adjusts the curvature in the graph of the log function. The
4080formula applied to a normalized value <b><var>u</var></b> is below. </p>
4081
4082 <div style="text-align:center;">
4083 log(<var>value</var> × <b><var>u</var></b> + 1) / log(<var>value</var> + 1)
4084 </div>
4085
4086<p><code>Pow</code> has been added as of ImageMagick 6.4.1-9, and works on
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4087normalized pixel values. Note that <code>Pow</code> is related to the <a href="command-line-options.html#gamma">-gamma</a> operator. For example, <b>-gamma 2</b> is equivalent
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4088to <b>-evaluate pow 0.5</b>, i.e., a 'square root' function. The value used
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4089with <a href="command-line-options.html#gamma">-gamma</a> is simply the reciprocal of the value used
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4090with <code>Pow</code>.</p>
4091
4092<p><code>Cosine</code> and <code>Sine</code> was added as of IM v6.4.8-8 and
4093converts the image values into a value according to a (co)sine wave function.
4094The synonyms <code>Cos</code> and <code>Sin</code> may also be used. The output
4095is biased 50% and normalized by 50% so as to fit in the respective color value
4096range. The <var>value</var> scaling of the <var>period</var> of the
4097function (its frequency), and thus determines the number of 'waves' that will
4098be 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,
4099then the effective period is the <var>half</var> the <var>QuantumRange</var>.</p>
4100
4101 <div style="text-align:center;">
4102 0.5 + 0.5 × cos(2 π <b><var>u</var></b> × <var>value</var>).
4103 </div>
4104
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4105<p>See also the <a href="command-line-options.html#function">-function</a> operator, which is a
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4106multi-value version of evaluate. </p>
4107
4108<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4109 <h3 class="magick-header"><a id="evaluate-sequence"></a>-evaluate-sequence <var>operator</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4110</div>
4111
4112<p class="magick-description">Alter channel pixels by evaluating an arithmetic, relational, or
4113logical expression over a sequence of images.</p>
4114
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4115<p>To print a complete list of <a href="command-line-options.html#evaluate-sequence">-evaluate-sequence</a> operators, use <a href="command-line-options.html#list">-list evaluate</a>.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4116
4117<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4118 <h3 class="magick-header"><a id="extent"></a>-extent <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4119</div>
4120
4121<p class="magick-description">Set the image size and offset.</p>
4122
4123<p>If the image is enlarged, unfilled areas are set to the background color.
4124To position the image, use offsets in the <var>geometry</var>
4125specification or precede with a <a href="command-line-options.html#gravity">-gravity</a> setting. To
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4126specify how to compose the image with the background, use <a href="command-line-options.html#compose">-compose</a>.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4127
4128<p>This command reduces or expands a JPEG image to fit on an 800x600
4129display. If the aspect ratio of the input image isn't exactly 4:3, then the
4130image is centered on an 800x600 black canvas: </p>
4131
4132<pre>
4133convert input.jpg -resize 800x600 -background black -compose Copy \
4134 -gravity center -extent 800x600 -quality 92 output.jpg
4135</pre>
4136
4137<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
4138
4139<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4140 <h3 class="magick-header"><a id="extract"></a>-extract <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4141</div>
4142
4143<p class="magick-description">Extract the specified area from image.</p>
4144
4145<p>This option is most useful for extracting a subregion of a very large raw
4146image. Note that these two commands are equivalent:</p>
4147
4148<pre>
4149convert -size 16000x16000 -depth 8 -extract 640x480+1280+960 \
4150 image.rgb image.png",
4151convert -size 16000x16000 -depth 8 'image.rgb[640x480+1280+960]' \
4152 image.rgb image.png"
4153</pre>
4154
4155<p>If you omit the offsets, as in</p>
4156
4157<pre>
4158convert -size 16000x16000 -depth 8 -extract 640x480 \
4159 image.rgb image.png
4160</pre>
4161
4162<p>the image is <var>resized</var> to the specified dimensions instead,
4163equivalent to:</p>
4164
4165<pre>
4166convert -size 16000x16000 -depth 8 -resize 640x480 image.rgb image.png
4167</pre>
4168
4169<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
4170
4171<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4172 <h3 class="magick-header"><a id="family"></a>-family <var>fontFamily</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4173</div>
4174
4175<p class="magick-description">Set a font family for text.</p>
4176
4177<p>This setting suggests a font family that ImageMagick should try to use for
4178rendering text. If the family can be found it is used; if not, a default font
4179(e.g., "Arial") or a family known to be similar is substituted (e.g.,
4180"Courier" might be used if "System" is requested but not found). </p>
4181
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4182<p>For other settings that affect fonts, see the options <a href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4183
4184<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4185 <h3 class="magick-header"><a id="features"></a>-features <var>distance</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4186</div>
4187
4188<p class="magick-description">display (cooccurrence 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>
4189
4190<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4191Angular Second Moment
4192Contrast
4193Correlation
4194Sum of Squares Variance
4195Inverse Difference Moment
4196Sum Average
4197Sum Variance
4198Sum Entropy
4199Entropy
4200Difference Variance
4201Difference Entropy
4202Information Measure of Correlation 1
4203Information Measure of Correlation 2
4204Maximum Correlation Coefficient
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4205</pre>
4206
4207
4208<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4209 <h3 class="magick-header"><a id="fft"></a>-fft</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4210</div>
4211
4212<p class="magick-description">implements the forward discrete Fourier transform (DFT).</p>
4213
4214<p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows
4215users in ImageMagick 6.6.0-9). It transforms an image from the normal
4216(spatial) domain to the frequency domain. In the frequency domain, an image is
4217represented as a superposition of complex sinusoidal waves of varying
4218amplitudes. The image x and y coordinates are the possible frequencies along
4219the x and y directions, respectively, and the pixel intensity values are
4220complex numbers that correspond to the sinusoidal wave amplitudes. See for
4221example, <a href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier
4222Transform</a>, <a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier
4223Transform</a> and <a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier
4224Transform</a>.</p>
4225
4226<p>A single image name is provided as output for this option. However, the
4227output result will have two components. It is either a two-frame image or two
4228separate images, depending upon whether the image format specified supports
4229multi-frame images. The reason that we get a dual output result is because the
4230frequency domain represents an image using complex numbers, which cannot be
4231visualized directly. Therefore, the complex values are automagically separated
4232into a two-component image representation. The first component is the
4233magnitude of the complex number and the second is the phase of the complex
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4234number. See for example, <a href="http://en.wikipedia.org/wiki/Complex_numbers">Complex Numbers</a>.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4235
4236<p>The magnitude and phase component images must be specified using image
4237formats that do not limit the color or compress the image. Thus, MIFF, TIF,
4238PFM, EXR and PNG are the recommended image formats to use. All of these
4239formats, except PNG support multi-frame images. So for example,</p>
4240
4241<pre>
4242convert image.png -fft fft_image.miff
4243</pre>
4244
4245<p>generates a magnitude image as <code>fft_image.miff[0]</code> and a phase
4246image as <code>fft_image.miff[1]</code>. Similarly,</p>
4247
4248<pre>
4249convert image.png -fft fft_image.png
4250</pre>
4251
4252<p>generates a magnitude image as <code>fft_image-0.png</code> and a phase image
4253as <code>fft_image-1.png</code>. If you prefer this representation, then you can
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4254force any of the other formats to produce two output images by including <a href="command-line-options.html#adjoin">+adjoin</a> following -fft in the command line.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4255
4256<p>The input image can be any size, but if not square and even-dimensioned, it
4257is padded automagically to the larger of the width or height of the input
4258image and to an even number of pixels. The padding will occur at the bottom
4259and/or right sides of the input image. The resulting output magnitude and
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4260phase images is square at this size. The kind of padding relies on the <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4261
4262<p>Both output components will have dynamic ranges that fit within
4263[0, <var>QuantumRange</var>], so that HDRI need not be enabled.
4264Phase values nominally range from 0 to 2*π, but is scaled to span the full
4265dynamic range. (The first few releases had non-HDRI scaled but HDRI not
4266scaled). The magnitude image is not scaled and thus generally will contain
4267very small values. As such, the image normally will appear totally black. In
4268order to view any detail, the magnitude image typically is enhanced with a log
4269function into what is usually called the spectrum. A log function is used to
4270enhance the darker values more in comparison to the lighter values. This can
4271be done, for example, as follows:</p>
4272
4273<pre>
4274convert fft_image.miff[0] -contrast-stretch 0 \
4275 -evaluate log 1000 fft_image_spectrum.png"
4276</pre>
4277
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4278<p>where either <a href="command-line-options.html#contrast-stretch">-contrast-stretch</a> 0 or <a href="command-line-options.html#auto-level">-auto-level</a> is used to scale the image to full dynamic
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4279range, first. The argument to the <a href="command-line-options.html#evaluate">-evaluate</a> log
4280typically is specified between 100 and 10,000, depending upon the amount of
4281detail that one wants to bring out in the spectrum. Larger values produce more
4282visible detail. Too much detail, however, may hide the important features.</p>
4283
4284<p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to
4285use <a href="command-line-options.html#fft">-fft</a>.</p>
4286
4287<p>Use <a href="command-line-options.html#fft">+fft</a> to produce two output images that are the real
4288and imaginary components of the complex valued Fourier transform.</p>
4289
4290<p>However, as the real and imaginary components can contain negative values,
4291this requires that IM be configured with HDRI enabled. In this case, you must
4292use either MIFF, TIF, PFM or MPC formats for the real and imaginary component
4293results, since they are formats that preserve both negative and fractional
4294values without clipping them or truncating the fractional part. With either
4295MIFF or TIF, one should add -define quantum:format=32, to allow those image
4296types to work properly in HDRI mode without clipping.</p>
4297
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4298<p>The real and imaginary component images resulting from <a href="command-line-options.html#fft">+fft</a> are also square, even dimensioned images due to the same
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4299padding that was discussed above for the magnitude and phase component
4300images.</p>
4301
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4302<p>See the discussion on HDRI implementations of ImageMagick on the page <a href="high-dynamic-range.html">High Dynamic-Range Images</a>. For more
4303about HDRI go the ImageMagick <a href="http://www.imagemagick.org/Usage/basics/#hdri">Usage</a> pages, <a href="http://www.fmwconcepts.com/imagemagick/fourier_transforms/fourier.html">Fred's Fourier Processing With ImageMagick page</a> or this <a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4304 entry. </p>
4305
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4306<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 explicityly normalize the FFT and unnormalize the IFT.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4307
4308
4309<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4310 <h3 class="magick-header"><a id="fill"></a>-fill <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4311</div>
4312
4313<p class="magick-description">color to use when filling a graphic primitive.</p>
4314
4315<p>This option accepts a color name, a hex color, or a numerical RGB, RGBA,
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4316HSL, HSLA, CMYK, or CMYKA specification. See <a href="color.html">Color Names</a> for
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4317a description of how to properly specify the color argument.</p>
4318
4319<p>Enclose the color specification in quotation marks to prevent the "#" or
4320the parentheses from being interpreted by your shell.</p>
4321
4322<p>For example,</p>
4323
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4324<pre>
4325-fill blue
4326-fill "#ddddff"
4327-fill "rgb(255,255,255)"
4328</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4329
4330<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p>
4331
4332<p>To print a complete list of color names, use the <a href="command-line-options.html#list">-list color</a> option.</p>
4333
4334<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4335 <h3 class="magick-header"><a id="filter"></a>-filter <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4336</div>
4337
4338<p class="magick-description">Use this <var>type</var> of filter when resizing or distorting an image.</p>
4339
4340<p>Use this option to affect the resizing operation of an image during
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4341operations such as <a href="command-line-options.html#resize">-resize</a> and <a href="command-line-options.html#distort">-distort</a>. For example you can use a simple resize filter such as:</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4342
4343<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4344Point Hermite Cubic
4345Box Gaussian Catrom
4346Triangle Quadratic Mitchell
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4347</pre>
4348
4349<p>The <code>Bessel</code> and <code>Sinc</code> filter is also provided (as well
4350as a faster <code>SincFast</code> equivalent form). However these filters are
4351generally useless on their own as they are infinite filters that are being
4352clipped to the filters support size. Their direct use is not recommended
4353except via expert settings (see below). </p>
4354
4355<p>Instead these special filter functions are typically windowed by a windowing
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4356function that the <a href="command-line-options.html#filter">-filter</a> setting defines. That is
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4357using these functions will define a 'Windowed' filter, appropriate to the
4358operator involved. Windowed filters include: </p>
4359
4360<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4361Lanczos Hamming Parzen
4362Blackman Kaiser Welsh
4363Hanning Bartlett Bohman
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4364</pre>
4365
4366<p>Also one special self-windowing filter is also provided
4367<code>Lagrange</code>, which will automagically re-adjust its function depending
4368on the current 'support' or 'lobes' expert settings (see below).</p>
4369
4370<p>If you do not select a filter with this option, the filter defaults to
4371<code>Mitchell</code> for a colormapped image, an image with a matte channel, or
4372if the image is enlarged. Otherwise the filter default to
4373<code>Lanczos</code>.</p>
4374
4375<p>To print a complete list of resize filters, use the <a href="command-line-options.html#list">-list
4376filter</a> option.</p>
4377
4378<p>You can modify how the filter behaves as it scales your image through the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4379use of these expert settings (see also <a href="command-line-options.html#define">-define</a> and <a href="command-line-options.html#set">-set</a>):-</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4380
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4381<table class="table table-condensed table-striped">
4382 <tr>
4383 <td>-define filter:blur=<var>factor</var></td>
4384 <td>Scale the X axis of the filter (and its window). Use &gt; 1.0 for
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4385 blurry or &lt; 1.0 for sharp. This should only be used with Gaussian and
4386 Gaussian-like filters simple filters, or you may not get the expected
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4387 results. </td>
4388 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4389
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4390 <tr>
4391 <td>-define filter:support=<var>radius</var></td>
4392 <td>Set the filter support radius. Defines how large the filter should be and
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4393 thus directly defines how slow the filtered resampling process is. All
4394 filters have a default 'prefered' support size. Some filters like
4395 <code>Lagrange</code> and windowed filters adjust themselves depending on
4396 this value. With simple filters this value either does nothing (but slow
4397 the resampling), or will clip the filter function in a detrimental way.
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4398 </td>
4399 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4400
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4401 <tr>
4402 <td>-define filter:lobes=<var>count</var></td>
4403 <td>Set the number of lobes to use for the Sinc/Bessel filter. This an
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4404 alternative way of specifying the 'support' range of the filter, that is
4405 designed to be more suited to windowed filters, especially when used for
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4406 image distorts.</td>
4407 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4408
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4409 <tr>
4410 <td>-define filter:sigma=<var>value</var></td>
4411 <td>The 'sigma' value used to define the <code>Gaussian</code> filter. Default
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4412 sigma value is '<code>0.5</code>'. It only effects <code>Gaussian</code> but
4413 does not shrink (but may enlarge) the filter's 'support'. It can be used
4414 to generate very small blurs but without the filter 'missing' pixels due
4415 to using a small support setting. A larger value of '<code>0.707</code>'
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4416 (a value of '1/sqrt(2)') is another common setting. </td>
4417 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4418
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4419 <tr>
4420 <td>-define filter:b=<var>b-spline_factor</var></td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4421 </tr><tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4422 <td>-define filter:c=<var>keys_alpha_factor</var></td>
4423 <td>Redefine the values used for cubic filters such as <code>Cubic</code>,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4424 <code>Catrom</code>, <code>Mitchel</code>, and <code>Hermite</code>, as well as
4425 the <code>Parzen</code> cubic windowing function. If only one of the values
4426 are defined, the other is set so as to generate a 'Cubic-Keys' filter.
4427 The values meaning was defined by a research paper by
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4428 Mitchell-Netravali.</td>
4429 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4430
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4431 <tr>
4432 <td>-define filter:kaiser-beta=<var>value</var></td>
4433 <td>The 'alpha' value used to as part of the Kaiser Windowing function.
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4434 Default value is '6.5'. It only effects Kaiser windowing function, and
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4435 does not effect any other attributes.
4436 Before ImageMagick v6.7.6-10, this option was known as "filter:alpha", (an
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4437 inheritance from the very old "zoom" program). It was changed to bring the
4438 function in line with more modern academic research usage, and better
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4439 assign it be more definitive. </td>
4440 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4441
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4442 <tr>
4443 <td>-define filter:kaiser-alpha=<var>value</var></td>
4444 <td>This value when multiplied by 'PI' is equivalent to "kaiser-beta", and
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4445 will override that setting. It only effects Kaiser windowing function,
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4446 and does not effect any other attributes. </td>
4447 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4448
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4449 <tr>
4450 <td>-define filter:filter=<var>filter_function</var></td>
4451 <td>Use this function directly as the weighting filter. This will allow
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4452 you to directly use a windowing function such as <code>Blackman</code>,
4453 as a resampling filter, rather than as its normal usage as a windowing
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4454 function. If defined, no windowing function also defined, the window function is set
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4455 to <code>Box</code>). Directly specifying <code>Sinc</code> or <code>Jinc</code>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4456 as a filter will also do this. </td>
4457 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4458
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4459 <tr>
4460 <td>-define filter:window=<var>filter_function</var></td>
4461 <td>The IIR (infinite impulse response) filters <code>Sinc</code> and
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4462 <code>Jinc</code> are windowed (brought down to zero over the defined
4463 support range) with the given filter. This allows you to specify a filter
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4464 function to be used as a windowing function for these IIR filters.
4465 Many of the defined filters are actually windowing functions for these IIR
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4466 filters. A typical choices is <code>Box</code>, (which effectively turns
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4467 off the windowing function). </td>
4468 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4469
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4470 <tr>
4471 <td>-define filter:win-support=<var>radius</var></td>
4472 <td>Scale windowing function to this size instead. This causes the windowing
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4473 (or self-windowing Lagrange filter) to act is if the support window is
4474 larger than what is actually supplied to the calling operator. The filter
4475 however is still clipped to the real support size given. If unset this
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4476 will equal the normal filter support size. </td>
4477 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4478
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4479 <tr>
4480 <td>-define filter:verbose=<var>1</var></td>
4481 <td>This causes IM to print information on the final internal filter
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4482 selection to standard output. This includes a commented header on the
4483 filter settings being used, and data allowing the filter weights to be
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4484 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
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4485 a <code>SincFast</code> windowed <code>SincFast</code> filter, while
4486 <code>Mitchell</code> is defined as a general <code>Cubic</code> family filter
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4487 with specific 'B' and 'C' settings. </td>
4488 </tr>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4489
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4490</table>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4491
4492<p>For example, to get a 8 lobe jinc windowed sinc filter (Genseng filter?):</p>
4493
4494<pre>
4495convert image.png \
4496 -filter sinc \
4497 -set filter:window=jinc \
4498 -set filter:lobes=8 \
4499 -resize 150% image.jpg"
4500</pre>
4501
4502<p>Or a raw un-windowed Sinc filter with 4 lobes:</p>
4503
4504<pre>
4505convert image.png \
4506 -set filter:filter=sinc \
4507 -set filter:lobes=4 \
4508 -resize 150% image.jpg"
4509</pre>
4510
4511<p>To extract the data for a raw windowing function, combine it with
4512a '<code>Box</code>' filter. For example the '<code>Welch</code> parabolic
4513windowing function. </p>
4514
4515<pre>
4516convert null: -define filter:filter=Box \
4517 -define filter:window=Welch \
4518 -define filter:support=1.0 \
4519 -define filter:verbose=1 \
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4520 -resize 2 null: &gt; window_welch.dat
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4521gnuplot
4522 set grid
4523 plot \"window_welch.dat\" with lines
4524</pre>
4525
4526<p>Note that the use of expert options is provided for image processing experts
4527who have studied and understand how resize filters work. Without this
4528knowledge, and an understanding of the definition of the actual filters
4529involved, using expert settings are more likely to be detrimental to your image
4530resizing.</p>
4531
4532
4533<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4534 <h3 class="magick-header"><a id="flatten"></a>-flatten</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4535</div>
4536
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4537<p class="magick-description">This is a simple alias for the <a href="command-line-options.html#layers">-layers</a> method "flatten".</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4538
4539
4540<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4541 <h3 class="magick-header"><a id="flip"></a>-flip</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4542</div>
4543
4544<p class="magick-description">create a <var>mirror image</var></p>
4545
4546<p>reflect the scanlines in the vertical direction. The image will be mirrored
4547upside-down. </p>
4548
4549
4550<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4551 <h3 class="magick-header"><a id="floodfill"></a>-floodfill {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var> <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4552</div>
4553
4554<p class="magick-description">floodfill the image with color at the specified offset.</p>
4555
4556<p>Flood fill starts from the given 'seed point' which is not gravity effected.
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4557Any color that matches within <a href="command-line-options.html#fuzz">-fuzz</a> color distance of the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4558given <var>color</var> argument, connected to that 'seed point'
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4559will be replaced with the current <a href="command-line-options.html#fill">-fill</a> color. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4560
4561<p>Note that if the pixel at the 'seed point' does not itself match the given
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4562<var>color</var> (according to <a href="command-line-options.html#fuzz">-fuzz</a>), then no
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4563action will be taken. </p>
4564
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4565<p>This operator works more like the <a href="command-line-options.html#opaque">-opaque</a> option, than
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4566a more general flood fill that reads the matching color directly at the 'seed
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4567point'. For this form of flood fill, look at <a href="command-line-options.html#draw">-draw</a> and
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4568its 'color floodfill' drawing method. </p>
4569
4570
4571<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4572 <h3 class="magick-header"><a id="flop"></a>-flop</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4573</div>
4574
4575<p class="magick-description">create a <var>mirror image</var>.</p>
4576
4577<p>Reflect the scanlines in the horizontal direction, just like the image in
4578a vertical mirror. </p>
4579
4580
4581<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4582 <h3 class="magick-header"><a id="font"></a>-font <var>name</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4583</div>
4584
4585<p class="magick-description">set the font to use when annotating images with text, or creating labels.</p>
4586
4587<p>To print a complete list of fonts, use the <a href="command-line-options.html#list">-list font</a>
4588option (for versions prior to 6.3.6, use 'type' instead of 'font').</p>
4589
4590<p>In addition to the fonts specified by the above pre-defined list, you can
4591also specify a font from a specific source. For example <code>Arial.ttf</code>
4592is a TrueType font file, <code>ps:helvetica</code> is PostScript font, and
4593<code>x:fixed</code> is X11 font.</p>
4594
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4595<p>For other settings that affect fonts, see the options <a href="command-line-options.html#family">-family</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4596
4597
4598<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4599 <h3 class="magick-header"><a id="foreground"></a>-foreground <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4600</div>
4601
4602<p class="magick-description">Define the foreground color for menus.", "display</p>
4603
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4604<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4605
4606<p>The default foreground color is black.</p>
4607
4608<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4609 <h3 class="magick-header"><a id="format"></a>-format <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4610</div>
4611
4612<p class="magick-description">the image format type.</p>
4613
4614<p>When used with the <code>mogrify</code> utility, this option converts any
4615image to the image <a href="formats.html">format</a> you specify.
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4616For a list of image format types supported by ImageMagick, use <a href="command-line-options.html#list">-list format</a>.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4617
4618<p>By default the file is written to its original name. However, if the
4619filename extension matches a supported format, the extension is replaced with
4620the image format type specified with <a href="command-line-options.html#format">-format</a>. For
4621example, if you specify <var>tiff</var> as the format type and the
4622input image filename is <var>image.gif</var>, the output image
4623filename becomes <var>image.tiff</var>.</p>
4624
4625<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4626 <h3 class="magick-header"><a id="format_identify_"></a>-format <var>string</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4627</div>
4628
4629<p class="magick-description">output formatted image characteristics.</p>
4630
4631<p>See <a href="escape.html">Format and Print Image
4632Properties</a> for an explanation on how to specify the argument to this
4633option.</p>
4634
4635<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4636 <h3 class="magick-header"><a id="frame"></a>-frame <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4637</div>
4638
4639<p class="magick-description">Surround the image with a border or beveled frame.</p>
4640
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4641<p>The color of the border is specified with the <a href="command-line-options.html#mattecolor">-mattecolor</a> command line option. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4642
4643<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
4644height that is added to the dimensions of the image. If no offsets are given
4645in the <var>geometry</var> argument, then the border added is
4646a solid color. Offsets <var>x</var> and <var>y</var>, if present, specify that
4647the width and height of the border is partitioned to form an outer bevel of
4648thickness <var>x</var> pixels and an inner bevel of thickness
4649<var>y</var> pixels. Negative offsets make no sense as frame arguments.
4650</p>
4651
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4652<p>The <a href="command-line-options.html#frame">-frame</a> option is affected by the current <a href="command-line-options.html#compose">-compose</a> setting and assumes that this is using the default
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4653'<code>Over</code>' composition method. It generates an image of the appropriate
4654size with the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting, and then
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4655draws the frame of four distinct colors close to the current <a href="command-line-options.html#mattecolor">-mattecolor</a>. The original image is then overlaid onto
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4656center of this image. This means that with the default compose method of
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4657'<code>Over</code>' any transparent parts may be replaced by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4658
4659<p>The image composition is not
4660affected by the <a href="command-line-options.html#gravity">-gravity</a> option.</p>
4661
4662
4663<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4664 <h3 class="magick-header"><a id="frame_import_"></a>-frame</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4665</div>
4666
4667<p class="magick-description">include the X window frame in the imported image. </p>
4668<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4669 <h3 class="magick-header"><a id="function"></a>-function <var>function</var> <var>parameters</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4670</div>
4671
4672<p class="magick-description">Apply a function to channel values.</p>
4673
4674<p>This operator performs calculations based on the given arguments to modify
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4675each of the color values for each previously set <a href="command-line-options.html#channel">-channel</a> in the image. See <a href="command-line-options.html#evaluate">-evaluate</a> for details concerning how the results of the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4676calculations are handled.</p>
4677
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4678<p>This is can be considered a multi-argument version of the <a href="command-line-options.html#evaluate">-evaluate</a> operator. (Added in
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4679ImageMagick 6.4.8−8.)</p>
4680
4681<p>Here, <var>parameters</var> is a comma-separated list of
4682numerical values. The number of values varies depending on which <var>function</var> is selected. Choose the <var>function</var> from:</p>
4683
4684<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4685Polynomial
4686Sinusoid
4687Arcsin
4688Arctan
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4689</pre>
4690
4691<p>To print a complete list of <a href="command-line-options.html#function">-function</a> operators,
4692use <a href="command-line-options.html#list">-list function</a>. Descriptions follow.</p>
4693
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4694<dl class="dl-horizontal">
4695 <dt>Polynomial</dt>
4696 <dd><p>The <code>Polynomial</code> function takes an arbitrary number of parameters,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4697these being the coefficients of a polynomial, in decreasing order of degree.
4698That is, entering</p>
4699
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4700<pre>
4701-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>
4702</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4703
4704<p>will invoke a polynomial function given by</p>
4705
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4706<pre>
4707<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>,
4708</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4709
4710<p>where <b><var>u</var></b> is pixel's original normalized channel value.</p>
4711
4712<p>The <code>Polynomial</code> function can be used in place of <code>Set</code>
4713(the <var>constant</var> polynomial) and <code>Add</code>, <code>Divide</code>,
4714<code>Multiply</code>, and <code>Subtract</code> (some <var>linear</var>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4715polynomials) of the <a href="command-line-options.html#evaluate">-evaluate</a> operator. The <a href="command-line-options.html#level">-level</a> operator also affects channels linearly. Some
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4716correspondences follow.</p>
4717
4718<table class="table table-condensed table-striped">
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4719 <tr>
4720 <td>-evaluate Set <var>value</var> </td>
4721 <td>-function Polynomial <var>value</var></td>
4722 <td>(Constant functions; set <var>value</var>×100% gray when channels are RGB.)</td>
4723 </tr>
4724 <tr>
4725 <td>-evaluate Add <var>value</var> </td>
4726 <td>-function Polynomial 1,<var>value</var></td>
4727 </tr>
4728 <tr>
4729 <td>-evaluate Subtract <var>value</var> </td>
4730 <td>-function Polynomial 1,−<var>value</var></td>
4731 </tr>
4732 <tr>
4733 <td>-evaluate Multiply <var>value</var> </td>
4734 <td>-function Polynomial <var>value</var>,0</td>
4735 </tr>
4736 <tr>
4737 <td>+level black% x white%</td>
4738 <td>-function Polynomial A,B</td>
4739 <td>(Reduce contrast. Here, A=(white-black)/100 and B=black/100.)</td>
4740 </tr>
4741</table>
4742
4743<p>The <code>Polynomial</code> function gives great versatility, since
4744polynomials can be used to fit any continuous curve to any degree of accuracy
4745desired.</p>
4746
4747</dd>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4748<dt>Sinusoid</dt>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4749<dd>
4750<p>The <code>Sinusoid</code> function can be used to vary the channel values
4751sinusoidally by setting frequency, phase shift, amplitude, and a bias. These
4752values are given as one to four parameters, as follows,</p>
4753
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4754<pre>
4755-function <code>Sinusoid</code> <var>freq</var>,[<var>phase</var>,[<var>amp</var>,[<var>bias</var>]]]
4756</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4757
4758<p>where <var>phase</var> is in degrees. (The domain [0,1] of the function
4759corresponds to 0 through <var>freq</var>×360 degrees.)
4760The result is that if a pixel's normalized channel value is originally
4761<b><var>u</var></b>, its resulting normalized value is given by </p>
4762
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4763<pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4764<var>amp</var> * sin(2*π* (<var>freq</var> * <b><var>u</var></b> + <var>phase</var> / 360)) + <var>bias</var>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4765</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4766
4767<p> For example, the following generates a curve that starts and ends at 0.9
4768(when <b><var>u</var></b>=0 and 1, resp.), oscillating three times between
4769.7−.2=.5 and .7+.2=.9. </p>
4770
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4771<pre>
4772-function Sinusoid 3,-90,.2,.7
4773</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4774
4775<p>The default values of <var>amp</var> and <var>bias</var> are both .5. The default for <var>phase</var>
4776is 0.</p>
4777
4778<p>The <code>Sinusoid</code> function generalizes <code>Sin</code> and
4779<code>Cos</code> of the <a href="command-line-options.html#evaluate">-evaluate</a> operator by allowing
4780varying amplitude, phase and bias. The correspondence is as follows.</p>
4781
4782<table class="table table-condensed table-striped">
4783 <tr>
4784 <td>-evaluate Sin <var>freq</var> </td>
4785 <td>-function Sinusoid <var>freq</var>,0 </td>
4786 </tr>
4787 <tr>
4788 <td>-evaluate Cos <var>freq</var> </td>
4789 <td>-function Sinusoid <var>freq</var>,90 </td>
4790 </tr>
4791</table>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4792 </dd>
4793<dt>ArcSin</dt>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4794<dd>
4795<p>The <code>ArcSin</code> function generates the inverse curve of a Sinusoid,
4796and can be used to generate cylindrical distortion and displacement maps.
4797The curve can be adjusted relative to both the input values and output range
4798of values.</p>
4799
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4800<pre>
4801-function <code>ArcSin</code> <var>width</var>,[<var>center</var>,[<var>range</var>,[<var>bias</var>]]]
4802</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4803
4804<p>with all values given in terms of normalized color values (0.0 for black,
48051.0 for white). Defaulting to values covering the full range from 0.0 to 1.0
4806for bout input (<var>width</var>), and output (<var>width</var>) values. '<code>1.0,0.5,1.0,0.5</code>' </p>
4807
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4808<pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4809<var>range</var>/π * asin( 2/<var>width</var> * ( <b><var>u</var></b> - <var>center</var> ) ) + <var>bias</var>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4810</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4811
4812</dd>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4813<dt>ArcTan</dt>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4814<dd>
4815<p>The <code>ArcTan</code> function generates a curve that smooth crosses from
4816limit values at infinities, though a center using the given slope value.
4817All these values can be adjusted via the arguments.</p>
4818
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4819<pre>
4820-function <code>ArcTan</code> <var>slope</var>,[<var>center</var>,[<var>range</var>,[<var>bias</var>]]]
4821</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4822
4823<p>Defaulting to '<code>1.0,0.5,1.0,0.5</code>'.
4824</p>
4825
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4826<pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4827<var>range</var>/π * atan( <var>slope</var>*π * ( <b><var>u</var></b> - <var>center</var> ) ) + <var>bias</var>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4828</pre>
4829 </dd>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4830
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4831</dl>
4832
4833
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4834
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4835<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4836 <h3 class="magick-header"><a id="fuzz"></a>-fuzz <var>distance</var>{<var>%</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4837</div>
4838
4839<p class="magick-description">Colors within this <var>distance</var> are considered equal.</p>
4840
4841<p>A number of algorithms search for a target color. By default the color must
4842be exact. Use this option to match colors that are close to the target color
4843in RGB space. For example, if you want to automagically trim the edges of an
4844image with <a href="command-line-options.html#trim">-trim</a> but the image was scanned and the target
4845background color may differ by a small amount. This option can account for
4846these differences.</p>
4847
4848<p>The <var>distance</var> can be in absolute intensity units or, by
4849appending <code>%</code> as a percentage of the maximum possible intensity (255,
485065535, or 4294967295).</p>
4851
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4852<p>Use <a href="command-line-options.html#fuzz">+fuzz</a> to reset the fuzz value to 0.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4853
4854
4855<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4856 <h3 class="magick-header"><a id="fx"></a>-fx <var>expression</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4857</div>
4858
4859<p class="magick-description">apply a mathematical expression to an image or image channels.</p>
4860
4861<p>If the first character of <var>expression</var> is <code>@</code>,
4862the expression is read from a file titled by the remaining characters in the
4863string.</p>
4864
4865<p>See <a href="fx.html">FX,
4866The Special Effects Image Operator</a> for a detailed discussion of this
4867option.</p>
4868
4869
4870<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4871 <h3 class="magick-header"><a id="gamma"></a>-gamma <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4872</div>
4873
4874<p class="magick-description">level of gamma correction.</p>
4875
4876<p>The same color image displayed on two different workstations may look
4877different due to differences in the display monitor. Use gamma correction to
4878adjust for this color difference. Reasonable values extend from
4879<code>0.8</code> to <code>2.3</code>. Gamma less than 1.0 darkens the image and
4880gamma greater than 1.0 lightens it. Large adjustments to image gamma may
4881result in the loss of some image information if the pixel quantum size is only
4882eight bits (quantum range 0 to 255).</p>
4883
4884<p>Gamma adjusts the image's channel values pixel-by-pixel according to
4885a power law, namely, pow(pixel,1/gamma) or pixel^(1/gamma), where pixel is the
4886normalized or 0 to 1 color value. For example, using a value of gamma=2 is the
4887same as taking the square root of the image.</p>
4888
4889<p>You can apply separate gamma values to the red, green, and blue channels of
4890the image with a gamma value list delimited with commas (e.g.,
4891<code>1.7,2.3,1.2</code>).</p>
4892
4893<p>Use <a href="command-line-options.html#gamma">+gamma <var>value</var></a> to set the
4894image gamma level without actually adjusting the image pixels. This option
4895is useful if the image is of a known gamma but not set as an image attribute
4896(e.g. PNG images). Write the "file gamma" which is the reciprocal of the
4897display gamma; e.g., if your image is sRGB and you want to write a PNG gAMA
4898chunk, use</p>
4899
4900<pre>
4901convert input.png +gamma .45455 output.png
4902</pre>
4903
4904<p>(0.45455 is 1/2.2)</p>
4905
4906<p>Note that gamma adjustments are also available via the <a href="command-line-options.html#level">-level</a> operator.</p>
4907
4908<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4909 <h3 class="magick-header"><a id="gaussian-blur"></a>-gaussian-blur <var>radius</var><br>-gaussian-blur <var>radius</var>x<var>sigma</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4910</div>
4911
4912<p class="magick-description">Blur the image with a Gaussian operator.</p>
4913
4914<p>Convolve the image with a Gaussian or normal distribution using the given
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4915<var>Sigma</var> value. The formula is:</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4916
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4917<div class="eqn"><img alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png">
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4918</div>
4919
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4920<p>The <var>Sigma</var> value is the important argument, and
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4921determines the actual amount of blurring that will take place. </p>
4922
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4923<p>The <var>Radius</var> is only used to determine the size of the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4924array which will hold the calculated Gaussian distribution. It should be an
4925integer. If not given, or set to zero, IM will calculate the largest possible
4926radius that will provide meaningful results for the Gaussian distribution.
4927</p>
4928
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4929<p>The larger the <var>Radius</var> the radius the slower the
4930operation is. However too small a <var>Radius</var>, and sever
4931aliasing effects may result. As a guideline, <var>Radius</var>
4932should be at least twice the <var>Sigma</var> value, though three
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4933times will produce a more accurate result. </p>
4934
4935<p>This differs from the faster <a href="command-line-options.html#blur">-blur</a> operator in that a
4936full 2-dimensional convolution is used to generate the weighted average of the
4937neighboring pixels. </p>
4938
4939<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how
4940pixels which are outside the image proper are blurred into the final result.
4941</p>
4942
4943
4944<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4945 <h3 class="magick-header"><a id="geometry"></a>-geometry <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4946</div>
4947
4948<p class="magick-description">Set the preferred size and location of the image.</p>
4949
4950<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
4951
4952<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4953 <h3 class="magick-header"><a id="gravity"></a>-gravity <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4954</div>
4955
4956<p class="magick-description">Sets the current gravity suggestion for various other settings and options.</p>
4957
4958<p>Choices include: <code>NorthWest</code>, <code>North</code>,
4959<code>NorthEast</code>, <code>West</code>, <code>Center</code>, <code>East</code>,
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4960<code>SouthWest</code>, <code>South</code>, <code>SouthEast</code>. Use <a href="command-line-options.html#list">-list gravity</a> to get a complete list of <a href="command-line-options.html#gravity">-gravity</a> settings available in your ImageMagick
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4961installation.</p>
4962
4963<p>The direction you choose specifies where to position text or subimages. For
4964example, a gravity of <code>Center</code> forces the text to be centered within
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4965the image. By default, the image gravity is <code>NorthWest</code>. See <a href="command-line-options.html#draw">-draw</a> for more details about graphic primitives. Only the
4966text primitive of <a href="command-line-options.html#draw">-draw</a> is affected by the <a href="command-line-options.html#gravity">-gravity</a> option.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4967
4968<p>The <a href="command-line-options.html#gravity">-gravity</a> option is also used in concert with the
4969<a href="command-line-options.html#geometry">-geometry</a> setting and other settings or options that
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4970take <var>geometry</var> as an argument, such as the <a href="command-line-options.html#crop">-crop</a> option. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4971
4972<p>If a <a href="command-line-options.html#gravity">-gravity</a> setting occurs before another option
4973or setting having a <var>geometry</var> argument that specifies an
4974offset, the offset is usually applied to the point within the image suggested
4975by the <a href="command-line-options.html#gravity">-gravity</a> argument. Thus, in the following
4976command, for example, suppose the file <code>image.png</code> has dimensions
4977200x100. The offset specified by the argument to <a href="command-line-options.html#region">-region</a>
4978is (−40,+20). The argument to <a href="command-line-options.html#gravity">-gravity</a> is
4979<code>Center</code>, which suggests the midpoint of the image, at the point
4980(100,50). The offset (−40,20) is applied to that point, giving
4981(100−40,50+20)=(60,70), so the specified 10x10 region is located at
4982that point. (In addition, the <a href="command-line-options.html#gravity">-gravity</a> affects the
4983region itself, which is <var>centered</var> at the pixel
4984coordinate (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>
4985
4986<pre>
4987convert image.png -gravity Center -region 10x10-40+20 \
4988 -negate output.png
4989</pre>
4990
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4991<p>When used as an option to <a href="composite.html">composite</a>, <a href="command-line-options.html#gravity">-gravity</a> gives the direction that the image gravitates
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4992within the composite.</p>
4993
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]4994<p>When used as an option to <a href="montage.html">montage</a>, <a href="command-line-options.html#gravity">-gravity</a> gives the direction that an image gravitates
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]4995within a tile. The default gravity is <code>Center</code> for this purpose.</p>
4996
4997
4998<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]4999 <h3 class="magick-header"><a id="grayscale"></a>-grayscale <var>method</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5000</div>
5001
5002<p class="magick-description">convert image to grayscale.</p>
5003
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5004<p>This will use one of the <a href="command-line-options.html#intensity">-intensity</a> methods to
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5005convert the given image into a linear-grayscale image. </p>
5006
5007<p>For example, to convert an image to (linear) Rec709Luminance grayscale, type:</p>
5008
5009<pre>
5010convert in.png -grayscale Rec709Luminance out.png
5011</pre>
5012
5013<p>which is equivalent to:</p>
5014
5015<pre>
5016convert in.png -colorspace gray out.png
5017</pre>
5018
5019<p>Similarly, to convert an image to (non-linear) Rec709Luma grayscale, type:</p>
5020
5021<pre>
5022convert in.png -grayscale Rec709Luma out.png
5023</pre>
5024
5025<p>which is equivalent to:</p>
5026
5027<pre>
5028convert in.png -set colorspace RGB -colorspace gray out.png
5029</pre>
5030
5031<p>Note that a 'colorspace' intensity method will produce the same result
5032regardless of the current colorpsace of the image. But a 'mathematical'
5033intensity method will depend on the current colorspace the image is currently
5034using. </p>
5035
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5036<p>While this operation uses an <a href="command-line-options.html#intensity">-intensity</a> method,
5037it does not use or set the <a href="command-line-options.html#intensity">-intensity</a> setting, so
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5038will not effect other operations that may use that setting.</p>
5039
5040
5041<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5042 <h3 class="magick-header"><a id="green-primary"></a>-green-primary <var>x,y</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5043</div>
5044
5045<p class="magick-description">green chromaticity primary point.</p>
5046
5047
5048<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5049 <h3 class="magick-header"><a id="hald-clut"></a>-hald-clut</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5050</div>
5051
5052<p class="magick-description">apply a Hald color lookup table to the image.</p>
5053
5054<p>A Hald color lookup table is a 3-dimensional color cube mapped to 2
5055dimensions. Create it with the <code>HALD:</code> prefix (e.g. HALD:8). You
5056can apply any color transformation to the Hald image and then use this option
5057to apply the transform to the image. </p>
5058
5059<pre>
5060convert image.png hald.png -hald-clut transform.png
5061</pre>
5062
5063<p>This option provides a convenient method for you to use Gimp or Photoshop
5064to make color corrections to the Hald CLUT image and subsequently apply them
5065to multiple images using an ImageMagick script. </p>
5066
5067<p>Note that the representation is only of the normal RGB color space and that
5068the whole color value triplet is used for the interpolated lookup of the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5069represented Hald color cube image. Because of this the operation is not <a href="command-line-options.html#channel">-channel</a> setting effected, nor can it adjust or modify an
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5070images transparency or alpha/matte channel.</p>
5071
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5072<p>See also <a href="command-line-options.html#clut">-clut</a> which provides color value replacement
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5073of the individual color channels, usually involving a simpler gray-scale
5074image. E.g: gray-scale to color replacement, or modification by a histogram
5075mapping. </p>
5076
5077
5078<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5079 <h3 class="magick-header"><a id="help"></a>-help</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5080</div>
5081
5082<p class="magick-description">print usage instructions.</p>
5083
5084<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5085 <h3 class="magick-header"><a id="highlight-color"></a>-highlight-color <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5086</div>
5087
5088<p class="magick-description">when comparing images, emphasize pixel differences with this color.</p>
5089
5090<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5091 <h3 class="magick-header"><a id="hough-lines"></a>-hough-lines <var>width</var>x<var>height</var>{<var>+threshold</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5092</div>
5093
5094<p class="magick-description">identify straight lines in the image (e.g. -hough-lines 9x9+195).</p>
5095
5096<p>Use the Hough line detector with any binary edge extracted image to locate and draw any straight lines that it finds.</p>
5097
5098<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>.
5099
5100<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>
5101
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5102<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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5103
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5104<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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5105
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5106<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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5107
5108<p>A text file listing the endpoints and counts may be created by using the suffix, .mvg, for the output image.</p>
5109
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5110<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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5111
5112<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5113 <h3 class="magick-header"><a id="iconGeometry"></a>-iconGeometry <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5114</div>
5115
5116<p class="magick-description">specify the icon geometry.</p>
5117
5118<p>Offsets, if present in the geometry specification, are handled in the same
5119manner as the <a href="command-line-options.html#geometry">-geometry</a> option, using X11 style to
5120handle negative offsets.</p>
5121
5122<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
5123
5124<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5125 <h3 class="magick-header"><a id="iconic"></a>-iconic</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5126</div>
5127
5128<p class="magick-description">start in icon mode in X Windows", 'animate', 'display</p>
5129
5130<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5131 <h3 class="magick-header"><a id="identify"></a>-identify</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5132</div>
5133
5134<p class="magick-description">identify the format and characteristics of the image.</p>
5135
5136<p>This information is printed: image scene number; image name; image size;
5137the image class (<var>DirectClass</var> or <var>PseudoClass</var>); the total number of unique colors; and the
5138number of seconds to read and transform the image. Refer to <a href="miff.html">MIFF</a> for
5139a description of the image class.</p>
5140
5141<p>If <a href="command-line-options.html#colors">-colors</a> is also specified, the total unique colors
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5142in the image and color reduction error values are printed. Refer to <a href="quantize.html">color
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5143reduction algorithm</a> for a description of these values.</p>
5144
5145<p>If <a href="command-line-options.html#verbose">-verbose</a> precedes this option, copious
5146amounts of image properties are displayed including image statistics, profiles,
5147image histogram, and others.</p>
5148
5149<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5150 <h3 class="magick-header"><a id="ift"></a>-ift</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5151</div>
5152
5153<p class="magick-description">implements the inverse discrete Fourier transform (DFT).</p>
5154
5155<p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows
5156users in ImageMagick 6.6.0-9). It transforms a pair of magnitude and phase
5157images from the frequency domain to a single image in the normal or spatial
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5158domain. See for example, <a href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier Transform</a>,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5159<a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier Transform</a> and
5160<a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier Transform</a>.</p>
5161
5162<p>For example, depending upon the image format used to store the result of
5163the <a href="command-line-options.html#fft">-fft</a>, one would use either</p>
5164
5165<pre>
5166convert fft_image.miff -ift fft_image_ift.png
5167</pre>
5168
5169<p>or</p>
5170
5171<pre>
5172convert fft_image-0.png fft_image-1.png -ift fft_image_ift.png
5173</pre>
5174
5175<p>The resulting image may need to be cropped due to padding introduced when
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5176the original image, prior to the <a href="command-line-options.html#fft">-fft</a> or <a href="command-line-options.html#fft">+fft</a>, was not square or even dimensioned. Any padding is at
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5177the right and/or bottom sides of the image.</p>
5178
5179<p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to
5180use <a href="command-line-options.html#ift">-ift</a>.</p>
5181
5182<p>Use <a href="command-line-options.html#ift">+ift</a> (with HDRI enabled) to transform a pair of real
5183and imaginary images from the frequency domain to a single image in the normal
5184(spatial) domain.</p>
5185
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5186<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 explictly normalize the IFT and unnormalize the FFT.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5187
5188<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5189 <h3 class="magick-header"><a id="immutable"></a>-immutable</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5190</div>
5191
5192<p class="magick-description">make image immutable.</p>
5193
5194<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5195 <h3 class="magick-header"><a id="implode"></a>-implode <var>factor</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5196</div>
5197
5198<p class="magick-description">implode image pixels about the center.</p>
5199
5200<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5201 <h3 class="magick-header"><a id="insert"></a>-insert <var>index</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5202</div>
5203
5204<p class="magick-description">insert the last image into the image sequence.</p>
5205
5206<p>This option takes last image in the current image sequence and inserts it
5207at the given index. If a negative index is used, the insert position is
5208calculated before the last image is removed from the sequence. As such
5209<code>-insert -1</code> will result in no change to the image sequence.</p>
5210
5211<p>The <code>+insert</code> option is equivalent to <code>-insert -1</code>. In
5212other words, insert the last image, at the end of the current image sequence.
5213Consequently this has no effect on the image sequence order.</p>
5214
5215<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5216 <h3 class="magick-header"><a id="intensity"></a>-intensity <var>method</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5217</div>
5218
5219<p class="magick-description">method to generate intensity value from pixel.</p>
5220
5221<p>ImageMagick provides a number of methods used in situations where an
5222operatory needs to determine a single grayscale value for some purpose, from
5223an image with red, green, and blue pixel components. Typically the linear
5224<code>Rec709Luminance</code> formula is used, which is the same formula used when
5225converting images to <code>-colorspace gray</code>. </p>
5226
5227<p>The following formulas are currently provided, and will first convert
5228the pixel values to linear-RGB or non-linear sRGB colorspace before
5229being applied to calulate the final greyscale value. </p>
5230
5231<pre>
5232 Rec601Luma 0.298839R' + 0.586811G'+ 0.114350B'
5233 Rec601Luminance 0.298839R + 0.586811G + 0.114350B
5234 Rec709Luma 0.212656R' + 0.715158G' + 0.072186B'
5235 Rec709Luminance 0.212656R + 0.715158G + 0.072186B
5236 Brightness max(R', G', B')
5237 Lightness (min(R', G', B') + max(R', G', B')) / 2.0
5238</pre>
5239<p>Note that the above R,G,B values is the image's linear-RGB values, while
5240R',G',B' are sRGB non-linear values. </p>
5241
5242<p>These intensity methods are mathematical in nature and will use the
5243current value in the images respective R,G,B channel regardless of
5244what that is, or what colorspace the image is currently using.</p>
5245
5246<pre>
5247 Average (R + G + B) / 3.0
5248 MS (R^2 + G^2 + B^2) / 3.0
5249 RMS sqrt( (R^2 + G^2 + B^2) / 3.0 )
5250</pre>
5251
5252<p>These methods are often used for other purposes, such as generating a
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5253grayscale difference image between two color images (using <a href="command-line-options.html#compose">-compose</a> '<code>Difference</code>' composition. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5254
5255<p> For example The 'MS' (Mean Squared) setting is good for minimizing color
5256error comparisions. While... The method 'RMS' (Root Mean Squared) for
5257example is appropriate for calculating color vector distance, from a color
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5258difference image. This is equivalent to the color only component of the <a href="command-line-options.html#fuzz">-fuzz</a> factor color compare setting. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5259
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5260<p>See also <a href="command-line-options.html#grayscale">-grayscale</a> which applies one of the above
5261grayscaling formula directly to an image without setting the <a href="command-line-options.html#intensity">-intensity</a> setting.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5262
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5263<p>The <a href="command-line-options.html#colorspace">-colorspace gray</a> image conversion also uses
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5264the current intensity setting, but will always convert the image to the
5265appropriate sRGB or linear-RGB colorspace before appling the above
5266function.</p>
5267
5268<p>To print a complete list of posible pixel intensity setting methods, use <a href="command-line-options.html#list">-list intensity</a>.</p>
5269
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5270<p>Operators affected by the <a href="command-line-options.html#intensity">-intensity</a> setting include:</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5271
5272<pre>
5273-adaptive-blur
5274-adaptive-sharpen
5275-black-threshold
5276-clut (when mapping greyscale CLUT image to alpha channel if set by -channels)
5277-colors for gray colorspace
5278-compose {LightenIntensity, DarkenIntensity, CopyOpacity, CopyBlack}
5279-contrast-stretch
5280-distort {ErodeIntensity, DilateIntensity}
5281-normalize
5282-random-threshold
5283-selective-blur
5284-shade
5285-threshold
5286-tint
5287-white-threshold
5288</pre>
5289
5290<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5291 <h3 class="magick-header"><a id="intent"></a>-intent <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5292</div>
5293
5294<p class="magick-description">use this type of rendering intent when managing the image color.</p>
5295
5296<p>Use this option to affect the color management operation of an image (see
5297<a href="command-line-options.html#profile">-profile</a>). Choose from these intents: <code>Absolute,
5298Perceptual, Relative, Saturation</code>.</p>
5299
5300<p>The default intent is Perceptual for the sRGB colorspace and undefined for the RGB and gray colorspaces.</p>
5301
5302<p>To print a complete list of rendering intents, use <a href="command-line-options.html#list">-list intent</a>.</p>
5303
5304<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5305 <h3 class="magick-header"><a id="interlace"></a>-interlace <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5306</div>
5307
5308<p class="magick-description">the type of interlacing scheme.</p>
5309
5310<p>Choose from:</p>
5311
5312<pre>
5313 none
5314 line
5315 plane
5316 partition
5317 JPEG
5318 GIF
5319 PNG
5320</pre>
5321
5322<p>This option is used to specify the type of interlacing scheme for raw image
5323formats such as <code>RGB</code> or <code>YUV</code>.</p>
5324
5325<p><code>None</code> means do not interlace (RGBRGBRGBRGBRGBRGB...),</p>
5326
5327<p><code>Line</code> uses scanline interlacing (RRR...GGG...BBB...RRR...GGG...BBB...), and.</p>
5328
5329<p><code>Plane</code> uses plane interlacing (RRRRRR...GGGGGG...BBBBBB...).</p>
5330
5331<p><code>Partition</code> is like plane except the different planes are saved to
5332individual files (e.g. image.R, image.G, and image.B).</p>
5333
5334<p>Use <code>Line</code> or <code>Plane</code> to create an <code>interlaced
5335PNG</code> or <code>GIF</code> or <code>progressive JPEG</code> image.</p>
5336
5337<p>To print a complete list of interlacing schemes, use <a href="command-line-options.html#list">-list
5338interlace</a>.</p>
5339
5340<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5341 <h3 class="magick-header"><a id="interpolate"></a>-interpolate <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5342</div>
5343
5344<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>
5345
5346<p>When looking up the color of a pixel using a non-integer floating point
5347value, you typically fall in between the pixel colors defined by the source
5348image. This setting determines how the color is determined from the colors of
5349the pixels surrounding that point. That is how to determine the color of a
5350point that falls between two, or even four different colored pixels. </p>
5351
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5352<dl class="dl-horizontal">
5353 <dt>integer</dt>
5354 <dd>The color of the top-left pixel (floor function)</dd>
5355 <dt>nearest-neighbor</dt>
5356 <dd>The nearest pixel to the lookup point (rounded function)</dd>
5357 <dt>average</dt>
5358 <dd>The average color of the surrounding four pixels</dd>
5359 <dt>bilinear</dt>
5360 <dd>A double linear interpolation of pixels (the default)</dd>
5361 <dt>mesh</dt>
5362 <dd>Divide area into two flat triangular interpolations</dd>
5363 <dt>bicubic</dt>
5364 <dd>Fitted bicubic-spines of surrounding 16 pixels</dd>
5365 <dt>spline</dt>
5366 <dd>Direct spline curves (colors are blurred)</dd>
5367 <dt>filter</dt>
5368 <dd>Use resize <a href="command-line-options.html#filter">-filter</a> settings</dd>
5369</dl>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5370
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5371<p>This most important for distortion operators such as <a href="command-line-options.html#distort">-distort</a>, <a href="command-line-options.html#implode">-implode</a>, <a href="command-line-options.html#transform">-transform</a> and <a href="command-line-options.html#fx">-fx</a>. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5372
5373<p>To print a complete list of interpolation methods, use <a href="command-line-options.html#list">-list interpolate</a>.</p>
5374
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5375<p>See also <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a>, for control of the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5376lookup for positions outside the boundaries of the image. </p>
5377
5378
5379<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5380 <h3 class="magick-header"><a id="interline-spacing"></a>-interline-spacing <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5381</div>
5382
5383<p class="magick-description">the space between two text lines.</p>
5384
5385<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5386 <h3 class="magick-header"><a id="interword-spacing"></a>-interword-spacing <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5387</div>
5388
5389<p class="magick-description">the space between two words.</p>
5390
5391<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5392 <h3 class="magick-header"><a id="kerning"></a>-kerning <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5393</div>
5394
5395<p class="magick-description">the space between two letters.</p>
5396
5397<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5398 <h3 class="magick-header"><a id="kuwahara"></a>-kuwahara <var>radius</var><br>-kuwahara <var>radius</var>x<var>sigma</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5399</div>
5400
5401<p class="magick-description">edge preserving noise reduction filter.</p>
5402
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5403<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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5404
5405
5406<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5407 <h3 class="magick-header"><a id="label"></a>-label <var>name</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5408</div>
5409
5410<p class="magick-description">assign a label to an image.</p>
5411
5412<p>Use this option to assign a specific label to the image, as it is read in
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5413or created. You can use the <a href="command-line-options.html#set">-set</a> operation to re-assign
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5414a the labels of images already read in. Image formats such as TIFF, PNG,
5415MIFF, supports saving the label information with the image.</p>
5416
5417<p>When saving an image to a <var>PostScript</var> file, any label
5418assigned to an image is used as a header string to print above the postscript
5419image. </p>
5420
5421<p>You can include the image filename, type, width, height, or other image
5422attribute by embedding special format character. See <a href="escape.html">Format and Print Image
5423Properties</a> for details of the percent escape codes.</p>
5424
5425<p>For example,</p>
5426
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5427<pre>
5428-label "%m:%f %wx%h" bird.miff
5429</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5430
5431<p>assigns an image label of <code>MIFF:bird.miff 512x480</code> to the
5432"<code>bird.miff</code>" image and whose width is 512 and height is 480, as it
5433is read in. If a <a href="command-line-options.html#label">+label</a> option was used instead, any
5434existing label present in the image would be used. You can remove all labels
5435from an image by assigning the empty string. </p>
5436
5437<p>A label is not drawn on the image, but is embedded in the image datastream
5438via <var>Label</var> tag or similar mechanism. If you want the label to be
5439visible on the image itself, use the <a href="command-line-options.html#draw">-draw</a> option, or
5440during the final processing in the creation of an image montage.</p>
5441
5442<p>If the first character of <var>string</var> is <var>@</var>, the image label is read from a file titled by the
5443remaining characters in the string. Labels in a file are literal, no embedded
5444formatting characters are recognized.</p>
5445
5446
5447<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5448 <h3 class="magick-header"><a id="lat"></a>-lat <var>width</var><br>-lat <var>width</var>x<var>height</var>{<var>+-</var>}<var>offset</var>{<var>%</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5449</div>
5450
5451<p class="magick-description">perform local adaptive threshold.</p>
5452
5453<p>Adaptively threshold each pixel based on the value of pixels in a
5454surrounding window. If the current pixel is lighter than this average plus
5455the optional <code>offset</code>, then it is made white, otherwise it is made
5456black. Small variations in pixel values such as found in scanned documents
5457can be ignored if offset is positive. A negative offset will make it more
5458sensitive to those small variations. </p>
5459
5460<p>This is commonly used to threshold images with an uneven background. It is
5461based on the assumption that average color of the small window is the
5462the local background color, from which to separate the foreground color. </p>
5463
5464
5465<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5466 <h3 class="magick-header"><a id="layers"></a>-layers <var>method</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5467</div>
5468
5469<p class="magick-description">handle multiple images forming a set of image layers or animation frames.</p>
5470
5471<p>Perform various image operation methods to a ordered sequence of images
5472which may represent either a set of overlaid 'image layers', a GIF disposal
5473animation, or a fully-'coalesced' animation sequence. </p>
5474
5475<table class="table table-condensed table-striped">
5476 <tbody>
5477 <tr>
5478 <th style="width: 8%">Method</th>
5479 <th>Description</th>
5480 </tr>
5481
5482 <tr>
5483 <td>compare-any</td>
5484 <td>Crop the second and later frames to the smallest rectangle
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5485 that contains all the differences between the two images. No GIF <a href="command-line-options.html#dispose">-dispose</a> methods are taken into account. </td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5486 </tr>
5487
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5488 <tr><td></td><td>This exactly the same as the <a href="command-line-options.html#deconstruct">-deconstruct</a> operator, and does not preserve animations normal
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5489 working, especially when animation used layer disposal methods such as
5490 '<code>Previous</code>' or '<code>Background</code>'. </td>
5491 </tr>
5492
5493 <tr>
5494 <td>compare-clear</td>
5495 <td>As '<code>compare-any</code>' but crop to the bounds of any
5496 opaque pixels which become transparent in the second frame. That is the
5497 smallest image needed to mask or erase pixels for the next frame. </td>
5498 </tr>
5499
5500 <tr>
5501 <td>compare-overlay</td>
5502 <td>As '<code>compare-any</code>' but crop to pixels that add
5503 extra color to the next image, as a result of overlaying color pixels.
5504 That is the smallest single overlaid image to add or change colors. </td>
5505 </tr>
5506
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5507 <tr><td></td><td>This can be used with the <a href="command-line-options.html#compose">-compose</a> alpha
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5508 composition method '<code>change-mask</code>', to reduce the image to
5509 just the pixels that need to be overlaid. </td>
5510 </tr>
5511
5512 <tr>
5513 <td>coalesce</td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5514 <td>Equivalent to a call to the <a href="command-line-options.html#coalesce">-coalesce</a> operator. Apply the layer disposal methods set in the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5515 current image sequence to form a fully defined animation sequence, as
5516 it should be displayed. Effectively converting a GIF animation into a
5517 'film strip'-like animation. </td>
5518 </tr>
5519
5520 <tr>
5521 <td>composite</td>
5522 <td>Alpha Composition of two image lists, separated by a
5523 "<code>null:</code>" image, with the destination image list first, and
5524 the source images last. An image from each list are composited
5525 together until one list is finished. The separator image and source
5526 image lists are removed. </td>
5527 </tr>
5528
5529
5530 <tr><td></td>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5531 <td>The <a href="command-line-options.html#geometry">-geometry</a> offset is adjusted according
5532 to <a href="command-line-options.html#gravity">-gravity</a> in accordance of the virtual
5533 canvas size of the first image in each list. Unlike a normal <a href="command-line-options.html#composite">-composite</a> operation, the canvas offset is also
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5534 added to the final composite positioning of each image. </td> </tr>
5535
5536 <tr><td></td>
5537 <td>If one of the image lists only contains one image, that image is
5538 applied to all the images in the other image list, regardless of which
5539 list it is. In this case it is the image meta-data of the list which
5540 preserved. </td>
5541 </tr>
5542
5543
5544 <tr>
5545 <td>dispose</td>
5546 <td>This like '<code>coalesce</code>' but shows the look of
5547 the animation after the layer disposal method has been applied, before
5548 the next sub-frame image is overlaid. That is the 'dispose' image that
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5549 results from the application of the GIF <a href="command-line-options.html#dispose">-dispose</a> method. This allows you to check what
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5550 is going wrong with a particular animation you may be developing.
5551 </td>
5552 </tr>
5553
5554 <tr>
5555 <td>flatten</td>
5556 <td>Create a canvas the size of the first images virtual
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5557 canvas using the current <a href="command-line-options.html#background">-background</a> color,
5558 and <a href="command-line-options.html#compose">-compose</a> each image in turn onto that
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5559 canvas. Images falling outside that canvas is clipped. Final
5560 image will have a zero virtual canvas offset. </td>
5561 </tr>
5562
5563 <tr><td></td>
5564 <td>This usually used as one of the final 'image layering' operations
5565 overlaying all the prepared image layers into a final image. </td>
5566 </tr>
5567
5568 <tr><td></td>
5569 <td>For a single image this method can also be used to fillout a virtual
5570 canvas with real pixels, or to underlay an opaque color to remove
5571 transparency from an image.</td>
5572 </tr>
5573
5574
5575 <tr>
5576 <td>merge</td>
5577 <td>As 'flatten' method but merging all the given image
5578 layers to create a new layer image just large enough to hold all the
5579 image without clipping or extra space. The new images virtual offset
5580 will preserve the position of the new layer, even if this offset is
5581 negative. The virtual canvas size of the first image is preserved.
5582 </td>
5583 </tr>
5584
5585 <tr><td></td><td>Caution is advised when handling image layers with
5586 negative offsets as few image file formats handle them correctly.
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5587 Following this operation method with <a href="command-line-options.html#repage">+repage</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5588 will remove the layer offset, and create an image in which all the
5589 overlaid image positions relative to each other is preserved, though
5590 not necessarily exactly where you specified them.
5591 </td>
5592 </tr>
5593
5594 <tr><td></td><td>See also 'trim-bounds' below which is closely related but
5595 without doing the'flatten' to merge the images together. </td>
5596 </tr>
5597
5598 <tr>
5599 <td>mosaic</td>
5600 <td>As 'flatten' method but expanding the initial canvas size
5601 of the first image in a positive direction only so as to hold all the
5602 image layers. However as a virtual canvas is 'locked' to the origin,
5603 by its own definition, image layers with a negative offsets will still
5604 become clipped by the top and left edges. See 'merge' or 'trim-bounds'
5605 if this could be a problem. </td>
5606
5607 </tr>
5608
5609 <tr><td></td><td>This method is commonly used to layout individual image
5610 using various offset but without knowing the final canvas size. The
5611 resulting image will, like 'flatten' not have any virtual offset, so
5612 can be saved to any image file format. </td>
5613 </tr>
5614
5615
5616 <tr>
5617 <td>optimize</td>
5618 <td>Optimize a coalesced animation, into GIF animation using
5619 a number of general techniques. This currently a short cut to
5620 apply both the '<code>optimize-frame</code>', and
5621 '<code>optimize-transparency</code>' methods but may be expanded to
5622 include other optimization methods as they are developed. </td>
5623 </tr>
5624
5625 <tr>
5626 <td>optimize-frame</td>
5627 <td>Optimize a coalesced animation, into GIF animation by
5628 reducing the number of pixels per frame as much as possible by
5629 attempting to pick the best layer disposal method to use, while ensuring
5630 the result will continue to animate properly. </td>
5631 </tr>
5632
5633 <tr><td></td><td> There is no guarantee that the best optimization is found.
5634 But then no reasonably fast GIF optimization algorithm can do this.
5635 However this does seem to do better than most other GIF frame
5636 optimizers seen. </td>
5637 </tr>
5638
5639 <tr>
5640 <td>optimize-plus</td>
5641 <td>As '<code>optimize-frame</code>' but attempt to improve the
5642 overall optimization by adding extra frames to the animation, without
5643 changing the final look or timing of the animation. The frames are
5644 added to attempt to separate the clearing of pixels from the
5645 overlaying of new additional pixels from one animation frame to the
5646 next. If this does not improve the optimization (for the next frame
5647 only), it will fall back to the results of the previous normal
5648 '<code>optimize-frame</code>' technique. </td>
5649 </tr>
5650
5651 <tr><td></td><td>There is the possibility that the change in the disposal
5652 style will result in a worsening in the optimization of later frames,
5653 though this is unlikely. In other words there no guarantee that it is
5654 better than the normal '<code>optimize-frame</code>' technique. For some
5655 animations however you can get a vast improvement in the final
5656 animation size. </td>
5657 </tr>
5658
5659 <tr>
5660 <td>optimize-transparency</td>
5661 <td>Given a GIF animation, replace any pixel in the sub-frame
5662 overlay images with transparency, if it does not change the resulting
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5663 animation by more than the current <a href="command-line-options.html#fuzz">-fuzz</a> factor.
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5664 </td>
5665 </tr>
5666
5667 <tr><td></td><td>This should allow a existing frame optimized GIF animation
5668 to compress into a smaller file size due to larger areas of one
5669 (transparent) color rather than a pattern of multiple colors repeating
5670 the current disposed image of the last frame. </td>
5671 </tr>
5672
5673 <tr>
5674 <td>remove-dups</td>
5675 <td>Remove (and merge time delays) of duplicate consecutive
5676 images, so as to simplify layer overlays of coalesced animations.
5677 </td>
5678 </tr>
5679
5680 <tr><td></td><td>Usually this a result of using a constant time delay
5681 across the whole animation, or after a larger animation was split into
5682 smaller sub-animations. The duplicate frames could also have been
5683 used as part of some frame optimization methods. </td>
5684 </tr>
5685
5686 <tr>
5687 <td>remove-zero</td>
5688 <td>Remove any image with a zero time delay, unless ALL the
5689 images have a zero time delay (and is not a proper timed animation, a
5690 warning is then issued). </td>
5691 </tr>
5692
5693 <tr><td></td><td>In a GIF animation, such images are usually frames which
5694 provide partial intermediary updates between the frames that are
5695 actually displayed to users. These frames are usually added for
5696 improved frame optimization in GIF animations. </td>
5697 </tr>
5698
5699 <tr>
5700 <td>trim-bounds</td>
5701 <td>Find the bounds of all the images in the current
5702 image sequence, then adjust the offsets so all images are contained on
5703 a minimal positive canvas. None of the image data is modified or
5704 merged, only the individual image virtual canvas size and offset.
5705 All the images is given the same canvas size, and and will have
5706 a positive offset, but will remain in the same position relative to
5707 each other. As a result of the minimal canvas size at least one image
5708 will touch every edge of that canvas. The image data touching those
5709 edges however may be transparent. </td>
5710 </tr>
5711
5712 <tr><td></td><td>The result is much like if you used 'merge' followed by a
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5713 <a href="command-line-options.html#repage">+repage</a> option, except that all the images
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5714 have been kept separate. If 'flatten' is used after using
5715 'trim-bounds' you will get the same result. </td>
5716 </tr>
5717
5718 </tbody>
5719</table>
5720
5721<p>To print a complete list of layer types, use <a href="command-line-options.html#list">-list layers</a>.</p>
5722
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5723<p>The operators <a href="command-line-options.html#coalesce">-coalesce</a>, <a href="command-line-options.html#deconstruct">-deconstruct</a>, <a href="command-line-options.html#flatten">-flatten</a>, and <a href="command-line-options.html#mosaic">-mosaic</a> are only aliases for the above methods and may be depreciated in
5724the future. Also see <a href="command-line-options.html#page">-page</a>, <a href="command-line-options.html#repage">-repage</a> operators, the <a href="command-line-options.html#compose">-compose</a> setting, and the
5725GIF <a href="command-line-options.html#dispose">-dispose</a> and <a href="command-line-options.html#delay">-delay</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5726settings. </p>
5727
5728
5729<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5730 <h3 class="magick-header"><a id="level"></a>-level <var>black_point</var>{,<var>white_point</var>}{<var>%</var>}{,<var>gamma</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5731</div>
5732
5733<p class="magick-description">adjust the level of image channels.</p>
5734
5735<p>Given one, two or three values delimited with commas: black-point,
5736white-point, gamma (for example: 10,250,1.0 or 2%,98%,0.5). The black and
5737white points range from 0 to <var>QuantumRange</var>, or from 0 to
5738100%; if the white point is omitted it is set to (<var>QuantumRange</var> - black_point), so as to center contrast changes.
5739If a <code>%</code> sign is present anywhere in the string, both black and white
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5740points are percentages of the full color range. Gamma will do a <a href="command-line-options.html#gamma">-gamma</a> adjustment of the values. If it is omitted, the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5741default of 1.0 (no gamma correction) is assumed.</p>
5742
5743<p>In normal usage (<code>-level</code>) the image values are stretched so that
5744the given '<code>black_point</code>' value in the original image is set to zero
5745(or black), while the given '<code>white_point</code>' value is set to <var>QuantumRange</var> (or white). This provides you with direct
5746contrast adjustments to the image. The '<code>gamma</code>' of the resulting
5747image will then be adjusted. </p>
5748
5749<p>From ImageMagick v6.4.1-9 using the plus form of the operator
5750(<code>+level</code>) or adding the special '!' flag anywhere in the argument
5751list, will cause the operator to do the reverse of the level adjustment. That
5752is a zero, or <var>QuantumRange</var> value (black, and white, resp.)
5753in the original image, is adjusted to the given level values, allowing you to
5754de-contrast, or compress the channel values within the image. The
5755'<code>gamma</code>' is adjusted before the level adjustment to de-contrast the
5756image is made. </p>
5757
5758<p>Only the channels defined by the current <a href="command-line-options.html#channel">-channel</a>
5759setting are adjusted (defaults to RGB color channels only), allowing you to
5760limit the effect of this operator. </p>
5761
5762<p>Please note that the transparency channel is treated as 'matte'
5763values (0 is opaque) and not as 'alpha' values (0 is transparent).</p>
5764
5765
5766<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5767 <h3 class="magick-header"><a id="level-colors"></a>-level-colors {<var>black_color</var>}{,}{<var>white_color</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5768</div>
5769
5770<p class="magick-description">adjust the level of an image using the provided dash separated colors.</p>
5771
5772<p>This function is exactly like <a href="command-line-options.html#level">-level</a>, except that the
5773value value for each color channel is determined by the
5774'<code>black_color</code>' and '<code>white_color</code>' colors given (as
5775described under the <a href="command-line-options.html#fill">-fill</a> option). </p>
5776
5777<p>This effectually means the colors provided to <code>-level-colors</code>
5778is mapped to become 'black' and 'white' respectively, with all the other
5779colors linearly adjusted (or clipped) to match that change. Each channel is
5780adjusted separately using the channel values of the colors specified. </p>
5781
5782<p>On the other hand the plus form of the operator (<code>+level-colors</code>)
5783will map the image color 'black' and 'white' to the given colors
5784respectively, resulting in a gradient (de-contrasting) tint of the image to
5785those colors. This can also be used to convert a plain gray-scale image into a
5786one using the gradient of colors specified. </p>
5787
5788<p>By supplying a single color with a comma separator either before or after
5789that color, will just replace the respective 'black' or 'white' point
5790respectively. But if no comma separator is provided, the given color is
5791used for both the black and white color points, making the operator either
5792threshold the images around that color (- form) or set all colors to that
5793color (+ form). </p>
5794
5795
5796<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5797 <h3 class="magick-header"><a id="limit"></a>-limit <var>type value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5798</div>
5799
5800<p class="magick-description">Set the pixel cache resource limit.</p>
5801
5802<p>Choose from: <code>area</code>, <code>disk</code>, <code>file</code>,
5803<code>map</code>, <code>memory</code>, <code>thread</code>, or <code>time</code>.</p>
5804
5805<p>The value for <code>file</code> is in number of files. The other limits are
5806in bytes. Define arguments for the memory, map, area, and disk resource limits
5807with SI prefixes (.e.g 100MB).</p>
5808
5809<p>By default the limits are 768 files, 3GB of image area, 1.5GiB memory, 3GiB
5810memory map, and 18.45EB of disk. These limits are adjusted relative to the
5811available resources on your computer if this information is available. When
5812any limit is reached, ImageMagick fails in some fashion but attempts to take
5813compensating actions, if possible. For example, the following limits
5814memory:</p>
5815
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5816<pre>
5817-limit memory 32MiB -limit map 64MiB
5818</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5819
5820<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>
5821
5822<pre>
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5823-&gt; identify -list resource
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5824Resource limits:
5825 Width: 100MP
5826 Height: 100MP
5827 Area: 25.181GB
5828 Memory: 11.726GiB
5829 Map: 23.452GiB
5830 Disk: unlimited
5831 File: 768
5832 Thread: 12
5833 Throttle: 0
5834 Time: unlimited
5835</pre>
5836
5837<p>Requests for pixel storage to keep intermediate images are satisfied by one
5838of three resource categories: in-memory pool, memory-mapped files pool, and
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5839disk pool (in that order) depending on the <a href="command-line-options.html#limit">‑limit</a> settings
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5840and whether the system honors a resource request. If the total size of
5841allocated pixel storage in the given pool reaches the corresponding limit, the
5842request is passed to the next pool. Additionally, requests that exceed the
5843<code>area</code> limit automagically are allocated on disk.</p>
5844
5845<p>To illustrate how ImageMagick utilizes resource limits, consider a typical
5846image resource request. First, ImageMagick tries to allocate the pixels in
5847memory. The request might be denied if the resource request exceeds the
5848<code>memory</code> limit or if the system does not honor the request. If
5849a memory request is not honored, the pixels are allocated to disk and the file
5850is memory-mapped. However, if the allocation request exceeds the
5851<code>map</code> limit, the resource allocation goes to disk. In all cases, if
5852the resource request exceeds the <code>area</code> limit, the pixels are
5853automagically cached to disk. If the disk has a hard limit, the program
5854fails.</p>
5855
5856<p>In most cases you simply do not need to concern yourself with resource
5857limits. ImageMagick chooses reasonable defaults and most images do not tax
5858your computer resources. Where limits do come in handy is when you process
5859images that are large or on shared systems where ImageMagick can consume all
5860or most of the available memory. In this case, the ImageMagick workflow slows
5861other processes or, in extreme cases, brings the system to a halt. Under
5862these circumstances, setting limits give some assurances that the ImageMagick
5863workflow will not interfere with other concurrent uses of the computer. For
5864example, assume you have a web interface that processes images uploaded from
5865the Internet. To assure ImageMagick does not exceed 10MiB of memory you can
5866simply set the area limit to 10MiB:</p>
5867
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5868<pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5869-limit area 10MB
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5870</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5871
5872<p>Now whenever a large image is processed, the pixels are automagically
5873cached to disk instead of memory. This of course implies that large images
5874typically process very slowly, simply because pixel processing in memory can
5875be an order of magnitude faster than on disk. Because your web site users
5876might inadvertently upload a huge image to process, you should set a disk
5877limit as well:</p>
5878
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5879<pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5880-limit area 10MB -limit disk 500MB
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5881</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5882
5883<p>Here ImageMagick stops processing if an image requires more than 500MB of disk storage.</p>
5884
5885<p>In addition to command-line resource limit option, resources can be set
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5886with <a href="resources.html#environment">environment variables</a>. Set the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5887environment variables <code>MAGICK_AREA_LIMIT</code>,
5888<code>MAGICK_DISK_LIMIT</code>, <code>MAGICK_FILE_LIMIT</code>,
5889<code>MAGICK_MEMORY_LIMIT</code>, <code>MAGICK_MAP_LIMIT</code>,
5890<code>MAGICK_THREAD_LIMIT</code>, <code>MAGICK_TIME_LIMIT</code> for limits of
5891image area, disk space, open files, heap memory, memory map, number of threads
5892of execution, and maximum elapsed time in seconds respectively.</p>
5893
5894<p> Inquisitive users can try adding <a href="command-line-options.html#debug">-debug cache</a> to
5895their commands and then scouring the generated output for references to the
5896pixel cache, in order to determine how the pixel cache was allocated and how
5897resources were consumed. Advanced Unix/Linux users can pipe that output
5898through <code>grep memory|open|destroy|disk</code> for more readable sifting.
5899</p>
5900
5901<p>For more about ImageMagick's use of resources, see the section <b>Cache
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5902Storage and Resource Requirements</b> on the <a href="architecture.html#cache%0A">Architecture</a> page. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5903
5904<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5905 <h3 class="magick-header"><a id="linear-stretch"></a>-linear-stretch <var>black-point</var><br>-linear-stretch <var>black-point</var>{x<var>white-point</var>}{<var>%</var>}}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5906</div>
5907
5908<p class="magick-description">Linear with saturation stretch.</p>
5909
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5910<p>This is very similar to <a href="command-line-options.html#contrast-stretch">-contrast-stretch</a>,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5911and uses a 'histogram bin' to determine the range of color values that needs to
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5912be stretched. However it then stretches those colors using the <a href="command-line-options.html#level">-level</a> operator.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5913
5914<p>As such while the initial determination may have 'binning' round off
5915effects, the image colors are stretched mathematically, rather than using the
5916histogram bins. This makes the operator more accurate. </p>
5917
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5918<p>note however that a <a href="command-line-options.html#linear-stretch">-linear-stretch</a> of
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5919'<code>0</code>' does nothing, while a value of '<code>1</code>' does a near
5920perfect stretch of the color range. </p>
5921
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5922<p>See also <a href="command-line-options.html#auto-level">-auto-level</a> for a 'perfect'
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5923normalization of mathematical images. </p>
5924
5925<p>This operator is under review for re-development. </p>
5926
5927
5928<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5929 <h3 class="magick-header"><a id="linewidth"></a>-linewidth</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5930</div>
5931
5932<p class="magick-description">the line width for subsequent draw operations.</p>
5933
5934<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5935 <h3 class="magick-header"><a id="liquid-rescale"></a>-liquid-rescale <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5936</div>
5937
5938<p class="magick-description">rescale image with seam-carving.</p>
5939
5940<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
5941
5942<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5943 <h3 class="magick-header"><a id="list"></a>-list <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5944</div>
5945
5946<p class="magick-description">Print a list of supported arguments for various options or settings. Choose from these list types:</p>
5947
5948<pre>
5949 Align Alpha Boolean Channel
5950 Class ClipPath Coder Color
5951 Colorspace Command Compose Compress
5952 Configure DataType Debug Decoration
5953 Delegate Direction Dispose Distort
5954 Dither Endian Evaluate FillRule
5955 Filter Font Format Function
5956 Gravity ImageList Intent Interlace
5957 Interpolate Kernel Layers LineCap
5958 LineJoin List Locale LogEvent
5959 Log Magic Method Metric
5960 Mime Mode Morphology Module
5961 Noise Orientation Policy PolicyDomain
5962 PolicyRights Preview Primitive QuantumFormat
5963 Resource SparseColor Storage Stretch
5964 Style Threshold Type Units
5965 Validate VirtualPixel
5966</pre>
5967
5968<p>These lists vary depending on your version of ImageMagick. Use "<code>-list
5969list</code>" to get a complete listing of all the "<code>-list</code>" arguments
5970available:</p>
5971
5972<pre>
5973identify -list list
5974</pre>
5975
5976<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5977 <h3 class="magick-header"><a id="log"></a>-log <var>string</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5978</div>
5979
5980<p class="magick-description">Specify format for debug log.</p>
5981
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]5982<p>This option specifies the format for the log printed when the <a href="command-line-options.html#debug">-debug</a> option is active.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]5983
5984<p>You can display the following components by embedding special format
5985characters:</p>
5986
5987<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]5988%d domain
5989%e event
5990%f function
5991%l line
5992%m module
5993%p process ID
5994%r real CPU time
5995%t wall clock time
5996%u user CPU time
5997%% percent sign
5998\n newline
5999\r carriage return
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6000</pre>
6001
6002<p>For example:</p>
6003
6004<pre>
6005convert -debug coders -log "%u %m:%l %e" in.gif out.png
6006</pre>
6007
6008<p>The default behavior is to print all of the components.</p>
6009
6010<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6011 <h3 class="magick-header"><a id="loop"></a>-loop <var>iterations</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6012</div>
6013
6014<p class="magick-description">add Netscape loop extension to your GIF animation.</p>
6015
6016<p>Set iterations to zero to repeat the animation an infinite number of times,
6017otherwise the animation repeats itself up to <var>iterations</var>
6018times.</p>
6019
6020<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6021 <h3 class="magick-header"><a id="lowlight-color"></a>-lowlight-color <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6022</div>
6023
6024<p class="magick-description">when comparing images, de-emphasize pixel differences with this color.</p>
6025
6026<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6027 <h3 class="magick-header"><a id="magnify"></a>-magnify</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6028</div>
6029
6030<p class="magick-description">double the size of the image with pixel art scaling.</p>
6031
6032
6033<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6034 <h3 class="magick-header"><a id="map"></a>-map <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6035</div>
6036
6037<p class="magick-description">Display image using this <var>type</var>.</p>
6038
6039<p>Choose from these <var>Standard Colormap</var> types:</p>
6040
6041<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6042best
6043default
6044gray
6045red
6046green
6047blue
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6048</pre>
6049
6050<p>The <var>X server</var> must support the <var>Standard
6051Colormap</var> you choose, otherwise an error occurs. Use <code>list</code> as
6052the type and <code>display</code> searches the list of colormap types in
6053<code>top-to-bottom</code> order until one is located. See <var>xstdcmap(1)</var> for one way of creating Standard Colormaps.</p>
6054
6055
6056<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6057 <h3 class="magick-header"><a id="map_stream_"></a>-map <var>components</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6058</div>
6059
6060<p class="magick-description">pixel map.</p>
6061
6062<p>Here are the valid components of a map:</p>
6063
6064<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6065r red pixel component
6066g green pixel component
6067b blue pixel component
6068a alpha pixel component (0 is transparent)
6069o opacity pixel component (0 is opaque)
6070i grayscale intensity pixel component
6071c cyan pixel component
6072m magenta pixel component
6073y yellow pixel component
6074k black pixel component
6075p pad component (always 0)
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6076</pre>
6077
6078<p>You can specify as many of these components as needed in any order (e.g.
6079bgr). The components can repeat as well (e.g. rgbr).</p>
6080
6081
6082<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6083 <h3 class="magick-header"><a id="mask"></a>-mask
6084<var>filename</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6085</div>
6086
6087<p class="magick-description">Prevent updates to image pixels specified by the mask.</p>
6088
6089<p>This the same as using a mask used for composite masking operations, with
6090grayscale values causing blended updates of the image the mask is attached to.
6091</p>
6092
6093<p>Use <a href="command-line-options.html#mask">+mask</a> to remove the mask from images.</p>
6094
6095<p>Also see <a href="command-line-options.html#clip-mask">-clip-mask</a> which work in the same way,
6096but with strict boolean masking. </p>
6097
6098<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6099 <h3 class="magick-header"><a id="mattecolor"></a>-mattecolor <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6100</div>
6101
6102<p class="magick-description">Specify the color to be used with the <a href="command-line-options.html#frame">-frame</a> option.</p>
6103
6104<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
6105
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6106<p>The default matte color is <code>#BDBDBD</code>, <span style="background-color: #bdbdbd;">this shade of gray</span>.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6107
6108<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6109 <h3 class="magick-header"><a id="maximum"></a>-maximum</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6110</div>
6111
6112<p class="magick-description">return the maximum intensity of an image sequence.</p>
6113
6114<p>Select the 'maximum' value from all the surrounding pixels. </p>
6115
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6116<p>This is legacy option from the <a href="command-line-options.html#statistic">method</a> of the same
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6117name. </p>
6118
6119<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6120 <h3 class="magick-header"><a id="median"></a>-median <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6121</div>
6122
6123<p class="magick-description">apply a median filter to the image.</p>
6124
6125<p>Select the 'middle' value from all the surrounding pixels. </p>
6126
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6127<p>This is legacy option from the <a href="command-line-options.html#statistic">method</a> of the same
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6128name. </p>
6129
6130<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6131 <h3 class="magick-header"><a id="mean-shift"></a>-mean-shift <var>width</var>x<var>height</var>{<var>+distance</var>{%}}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6132</div>
6133
6134<p class="magick-description">image noise removal and color reduction/segmentation (e.g. -mean-shift 7x7+10%).</p>
6135
6136<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>
6137
6138<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 radius=sqrt((width-1)(height-1)/4) 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>
6139
6140<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6141 <h3 class="magick-header"><a id="metric"></a>-metric <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6142</div>
6143
6144<p class="magick-description">Output to STDERR a measure of the differences between images according to the <var>type</var> given metric.</p>
6145
6146<p>Choose from:</p>
6147
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6148<dl class="dl-horizontal">
6149<dt>AE</dt><dd> absolute error count, number of different pixels (-fuzz effected)</dd>
6150<dt>FUZZ</dt><dd> mean color distance</dd>
6151<dt>MAE</dt><dd> mean absolute error (normalized), average channel error distance</dd>
6152<dt>MEPP</dt><dd> mean error per pixel (normalized mean error, normalized peak error)</dd>
6153<dt>MSE</dt><dd> mean error squared, average of the channel error squared</dd>
6154<dt>NCC</dt><dd> normalized cross correlation</dd>
6155<dt>PAE</dt><dd> peak absolute (normalized peak absolute)</dd>
6156<dt>PHASH</dt><dd> perceptual hash</dd>
6157<dt>PSNR</dt><dd> peak signal to noise ratio</dd>
6158<dt>RMSE</dt><dd> root mean squared (normalized root mean squared)</dd>
6159</dl>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6160
6161<p>Control the '<code>AE</code>', or absolute count of pixels that are different,
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6162with the <a href="command-line-options.html#fuzz">-fuzz</a> factor (ignore pixels which
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6163only changed by a small amount). Use '<code>PAE</code>' to find the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6164size of the <a href="command-line-options.html#fuzz">-fuzz</a> factor needed to make all pixels
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6165'similar', while '<code>MAE</code>' determines the factor needed
6166for about half the pixels to be similar. </p>
6167
6168<p>The '<code>MEPP</code>' metric returns three different metrics
6169('<code>MAE</code>', '<code>MAE</code>' normalized, and '<code>PAE</code>'
6170normalized) from a single comparison run. </p>
6171
6172<p>To print a complete list of metrics, use the <a href="command-line-options.html#list">-list
6173metric</a> option.</p>
6174
6175
6176<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6177 <h3 class="magick-header"><a id="minimum"></a>-minimum</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6178</div>
6179
6180<p class="magick-description">return the minimum intensity of an image sequence.</p>
6181
6182<p>Select the 'minimal' value from all the surrounding pixels. </p>
6183
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6184<p>This is legacy option from the <a href="command-line-options.html#statistic">method</a> of the same
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6185name. </p>
6186
6187
6188
6189<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6190 <h3 class="magick-header"><a id="mode"></a>-mode <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6191</div>
6192
6193<p class="magick-description">make each pixel the \'predominant color\' of the neighborhood.'</p>
6194
6195<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6196 <h3 class="magick-header">-mode <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6197</div>
6198
6199<p class="magick-description">Mode of operation.</p>
6200
6201<p>Choose the <var>value</var> from these styles: <code>Frame,
6202Unframe, or Concatenate</code></p>
6203
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6204<p>Use the <a href="command-line-options.html#list">-list</a> option with a '<code>Mode</code>' argument
6205for a list of <a href="command-line-options.html#mode">-mode</a> arguments available in your
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6206ImageMagick installation.</p>
6207
6208
6209<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6210 <h3 class="magick-header"><a id="modulate"></a>-modulate <var>brightness</var>[,<var>saturation</var>,<var>hue</var>]</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6211</div>
6212
6213<p class="magick-description">Vary the <var>brightness</var>, <var>saturation</var>, and <var>hue</var> of an image.</p>
6214
6215<p>The arguments are given as a percentages of variation. A value of 100 means
6216no change, and any missing values are taken to mean 100.</p>
6217
6218<p>The <var>brightness</var> is a multiplier of the overall
6219brightness of the image, so 0 means pure black, 50 is half as bright, 200 is
6220twice as bright. To invert its meaning <a href="command-line-options.html#negate">-negate</a> the image
6221before and after. </p>
6222
6223<p>The <var>saturation</var> controls the amount of color in an
6224image. For example, 0 produce a grayscale image, while a large value such as
6225200 produce a very colorful, 'cartoonish' color.</p>
6226
6227<p>The <var>hue</var> argument causes a "rotation" of the colors
6228within the image by the amount specified. For example, 50 results in
6229a counter-clockwise rotation of 90, mapping red shades to purple, and so on.
6230A value of either 0 or 200 results in a complete 180 degree rotation of the
6231image. Using a value of 300 is a 360 degree rotation resulting in no change to
6232the original image. </p>
6233
6234<p>For example, to increase the color brightness by 20% and decrease the color
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6235saturation by 10% and leave the hue unchanged, use <a href="command-line-options.html#modulate">-modulate 120,90</a>.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6236
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6237<p>Use <a href="command-line-options.html#set">-set</a> attribute of '<code>option:modulate:colorspace</code>' to specify which colorspace to
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6238modulate. 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>
6239
6240<pre>
6241convert image.png -set option:modulate:colorspace hsb -modulate 120,90 modulate.png
6242</pre>
6243
6244<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6245 <h3 class="magick-header"><a id="moments"></a>-moments</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6246</div>
6247
6248<p class="magick-description">report image moments and perceptual hash.</p>
6249
6250
6251<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6252 <h3 class="magick-header"><a id="monitor"></a>-monitor</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6253</div>
6254
6255<p class="magick-description">monitor progress.</p>
6256
6257
6258<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6259 <h3 class="magick-header"><a id="monochrome"></a>-monochrome</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6260</div>
6261
6262<p class="magick-description">transform the image to black and white.</p>
6263
6264<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6265 <h3 class="magick-header"><a id="morph"></a>-morph <var>frames</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6266</div>
6267
6268<p class="magick-description">morphs an image sequence.</p>
6269
6270<p>Both the image pixels and size are linearly interpolated to give the
6271appearance of a metamorphosis from one image to the next, over all the images
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6272in the current image list. The added images are the equivalent of a <a href="command-line-options.html#blend">-blend</a> composition. The <var>frames</var>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6273argument determine how many images to interpolate between each image. </p>
6274
6275
6276<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6277 <h3 class="magick-header"><a id="morphology"></a>-morphology</h3>
6278 <h3 class="magick-header">-morphology <var>method</var> <var>kernel</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6279</div>
6280
6281<p class="magick-description">apply a morphology method to the image.</p>
6282
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6283<p>Until I get around to writing an option summary for this, see <a href="http://www.imagemagick.org/Usage/morphology/">IM Usage Examples,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6284Morphology</a>. </p>
6285
6286
6287<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6288 <h3 class="magick-header"><a id="mosaic"></a>-mosaic</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6289</div>
6290
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6291<p class="magick-description">an simple alias for the <a href="command-line-options.html#layers">-layers</a> method "mosaic"</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6292
6293
6294<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6295 <h3 class="magick-header"><a id="motion-blur"></a>-motion-blur <var>radius</var><br>-motion-blur <var>radius</var>x<var>sigma</var>+<var>angle</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6296</div>
6297
6298<p class="magick-description">simulate motion blur.</p>
6299
6300<p>Blur with the given radius, standard deviation (sigma), and angle. The
6301angle given is the angle toward which the image is blurred. That is the
6302direction people would consider the object is coming from. </p>
6303
6304<p>Note that the blur is not uniform distribution, giving the motion a
6305definite sense of direction of movement. </p>
6306
6307<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how
6308pixels which are outside the image proper are blurred into the final result.
6309</p>
6310
6311<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6312 <h3 class="magick-header"><a id="name"></a>-name</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6313</div>
6314
6315<p class="magick-description">name an image.</p>
6316<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6317 <h3 class="magick-header"><a id="negate"></a>-negate</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6318</div>
6319
6320<p class="magick-description">replace each pixel with its complementary color.</p>
6321
6322<p>The red, green, and blue intensities of an image are negated. White becomes
6323black, yellow becomes blue, etc. Use <a href="command-line-options.html#negate">+negate</a> to only
6324negate the grayscale pixels of the image.</p>
6325
6326<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6327 <h3 class="magick-header"><a id="noise"></a>-noise <var>geometry</var><br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6328 +noise <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6329</div>
6330
6331<p class="magick-description">Add or reduce noise in an image.</p>
6332
6333<p>The principal function of noise peak elimination filter is to smooth the
6334objects within an image without losing edge information and without creating
6335undesired structures. The central idea of the algorithm is to replace a pixel
6336with its next neighbor in value within a pixel window, if this pixel has been
6337found to be noise. A pixel is defined as noise if and only if this pixel is
6338a maximum or minimum within the pixel window.</p>
6339
6340<p>Use <code><a href="command-line-options.html#noise">-noise</a> <var>radius</var></code> to
6341specify the width of the neighborhood when reducing noise. This is equivalent
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6342to using a <code><a href="command-line-options.html#statistic">-statistic</a> NonPeak</code> operation,
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6343which should be used in preference.</p>
6344
6345<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
6346types:</p>
6347
6348<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6349Gaussian
6350Impulse
6351Laplacian
6352Multiplicative
6353Poisson
6354Random
6355Uniform
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6356</pre>
6357
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6358<p>The amount of noise added can be controled by the <code><a href="command-line-options.html#attunuuate">-attenuate</a></code> setting. If unset the value is
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6359equivalent to 1.0, or a maximum noise addition.</p>
6360
6361<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>
6362
6363<p>To print a complete list of noises, use the <a href="command-line-options.html#list">-list noise</a> option.</p>
6364
6365<p>Also see the <a href="command-line-options.html#evaluate">-evaluate</a> noise functions that allows
6366the use of a controlling value to specify the amount of noise that should be
6367added to an image. </p>
6368
6369
6370<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6371 <h3 class="magick-header"><a id="normalize"></a>-normalize</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6372</div>
6373
6374<p class="magick-description">Increase the contrast in an image by <var>stretching</var> the range of intensity values.</p>
6375
6376<p>The intensity values are stretched to cover the entire range of possible
6377values. While doing so, black-out at most <var>2%</var> of the pixels and
6378white-out at most <var>1%</var> of the pixels.</p>
6379
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6380<p>Note that as of ImageMagick 6.4.7-0, <a href="command-line-options.html#normalize">-normalize</a>
6381is equivalent to <a href="command-line-options.html#contrast-stretch">-contrast-stretch 2%x1%</a>.
6382(Before this version, it was equivalent to <a href="command-line-options.html#contrast-stretch">-contrast-stretch 2%x99%</a>).</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6383
6384<p>All the channels are normalized in concert by the came amount so as to
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6385preserve color integrity, when the default <a href="command-line-options.html#channel">+channel</a>
6386setting is in use. Specifying any other <a href="command-line-options.html#channel">-channel</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6387setting will normalize the RGB channels independently.</p>
6388
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6389<p>See <a href="command-line-options.html#contrast-stretch">-contrast-stretch</a> for more details.
6390Also see <a href="command-line-options.html#auto-level">-auto-level</a> for a 'perfect' normalization
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6391that is better suited to mathematically generated images. </p>
6392
6393<p>This operator is under review for re-development. </p>
6394
6395
6396<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6397 <h3 class="magick-header"><a id="opaque"></a>-opaque <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6398</div>
6399
6400<p class="magick-description">change this color to the fill color within the image.</p>
6401
6402<p>The <var>color</var> argument is defined using the format
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6403described under the <a href="command-line-options.html#fill">-fill</a> option. The <a href="command-line-options.html#fuzz">-fuzz</a> setting can be used to match and replace colors similar to the one
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6404given.</p>
6405
6406<p>Use <a href="command-line-options.html#opaque">+opaque</a> to paint any pixel that does not match
6407the target color. </p>
6408
6409<p>The <a href="command-line-options.html#transparent">-transparent</a> operator is exactly the same
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6410as <a href="command-line-options.html#opaque">-opaque</a> but replaces the matching color with
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6411transparency rather than the current <a href="command-line-options.html#fill">-fill</a> color setting.
6412To ensure that it can do this it also ensures that the image has an alpha
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6413channel enabled, as per "<code><a href="command-line-options.html#alpha">-alpha</a> set</code>", for
6414the new transparent colors, and does not require you to modify the <a href="command-line-options.html#channel">-channel</a> to enable alpha channel handling. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6415
6416
6417<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6418 <h3 class="magick-header"><a id="ordered-dither"></a>-ordered-dither <var>threshold_map</var>{,<var>level</var>...}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6419</div>
6420
6421<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
6422given number of <var>levels</var> per color channel.</p>
6423
6424<p>You can choose from these standard threshold maps:</p>
6425
6426<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6427threshold 1x1 Threshold 1x1 (non-dither)
6428checks 2x1 Checkerboard 2x1 (dither)
6429o2x2 2x2 Ordered 2x2 (dispersed)
6430o3x3 3x3 Ordered 3x3 (dispersed)
6431o4x4 4x4 Ordered 4x4 (dispersed)
6432o8x8 8x8 Ordered 8x8 (dispersed)
6433h3x4a 4x1 Halftone 4x4 (angled)
6434h6x6a 6x1 Halftone 6x6 (angled)
6435h8x8a 8x1 Halftone 8x8 (angled)
6436h3x4o Halftone 4x4 (orthogonal)
6437h6x6o Halftone 6x6 (orthogonal)
6438h8x8o Halftone 8x8 (orthogonal)
6439h36x16o Halftone 16x16 (orthogonal)
6440c5x5b c5x5 Circles 5x5 (black)
6441c5x5w Circles 5x5 (white)
6442c6x6b c6x6 Circles 6x6 (black)
6443c6x6w Circles 6x6 (white)
6444c7x7b c7x7 Circles 7x7 (black)
6445c7x7w Circles 7x7 (white)
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6446</pre>
6447
6448<p> The <code>threshold</code> generated a simple 50% threshold of the image.
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6449This could be used with <var>level</var> to do the equivalent of <a href="command-line-options.html#posterize">-posterize</a> to reduce an image to basic primary colors.
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6450</p>
6451
6452<p>The <code>checks</code> pattern produces a 3 level checkerboard dither
6453pattern. That is a grayscale will become a pattern of solid black, solid
6454white, and mid-tone colors into a checkerboard pattern of black and white.
6455</p>
6456
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6457<p>You can define your own <var>threshold map</var> for ordered
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6458dithering and halftoning your images, in either personal or system
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6459<code>thresholds.xml</code> XML file. See <a href="resources.html">Resources</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6460for more details of configuration files. </p>
6461
6462<p>To print a complete list of the thresholds that have been defined, use the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6463<a href="command-line-options.html#list">-list threshold</a> option.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6464
6465<p>Note that at this time the same threshold dithering map is used for all
6466color channels, no attempt is made to offset or rotate the map for different
6467channels is made, to create an offset printing effect. Also as the maps are
6468simple threshold levels, the halftone and circle maps will create incomplete
6469circles along the edges of a colored area. Also all the effects are purely
6470on/off boolean effects, without anti-aliasing to make the circles smooth
6471looking. Large dots can be made to look better with a small amount of blurring
6472after being created. </p>
6473
6474
6475<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6476 <h3 class="magick-header"><a id="orient"></a>-orient <var>image orientation</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6477</div>
6478
6479<p class="magick-description">specify orientation of a digital camera image.</p>
6480
6481<p>Choose from these orientations:</p>
6482
6483<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6484bottom-left
6485bottom-right
6486left-bottom
6487left-top
6488right-bottom
6489right-top
6490top-left
6491top-right
6492undefined
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6493</pre>
6494
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6495<p>To print a complete list of orientations, use the <a href="command-line-options.html#list">-list
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6496orientation</a> option.</p>
6497
6498
6499<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6500 <h3 class="magick-header"><a id="page"></a>-page <var>geometry</var><br>
6501 -page <var>media</var>[<var>offset</var>][{<var>^!&lt;&gt;</var>}]<br>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6502 +page
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6503 </h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6504</div>
6505
6506<p class="magick-description">Set the size and location of an image on the larger virtual canvas.</p>
6507
6508<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
6509
6510<p>For convenience you can specify the page size using <var>media</var> (see below). Offsets can then be added as with other
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6511<var>geometry</var> arguments (e.g. <a href="command-line-options.html#page">-page</a> <code>Letter+43+43</code>).</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6512
6513<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.
6514The choices for a PostScript page are:</p>
6515
6516<div class="table-responsive">
6517<table class="table table-condensed table-striped">
6518 <tr>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6519 <td><var>Media</var></td>
6520 <td align="right"><var>Width</var></td>
6521 <td align="right"><var>Height</var></td>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6522 </tr>
6523<tr><td> 11x17 </td> <td align="right"> 792</td> <td align="right"> 1224</td> </tr>
6524<tr><td> Ledger </td> <td align="right"> 1224</td> <td align="right"> 792</td> </tr>
6525<tr><td> Legal </td> <td align="right"> 612</td> <td align="right"> 1008</td> </tr>
6526<tr><td> Letter </td> <td align="right"> 612</td> <td align="right"> 792</td> </tr>
6527<tr><td> LetterSmall</td> <td align="right"> 612</td> <td align="right"> 792</td> </tr>
6528<tr><td> ArchE </td> <td align="right"> 2592</td> <td align="right"> 3456</td> </tr>
6529<tr><td> ArchD </td> <td align="right"> 1728</td> <td align="right"> 2592</td> </tr>
6530<tr><td> ArchC </td> <td align="right"> 1296</td> <td align="right"> 1728</td> </tr>
6531<tr><td> ArchB </td> <td align="right"> 864</td> <td align="right"> 1296</td> </tr>
6532<tr><td> ArchA </td> <td align="right"> 648</td> <td align="right"> 864</td> </tr>
6533<tr><td> A0 </td> <td align="right"> 2380</td> <td align="right"> 3368</td> </tr>
6534<tr><td> A1 </td> <td align="right"> 1684</td> <td align="right"> 2380</td> </tr>
6535<tr><td> A2 </td> <td align="right"> 1190</td> <td align="right"> 1684</td> </tr>
6536<tr><td> A3 </td> <td align="right"> 842</td> <td align="right"> 1190</td> </tr>
6537<tr><td> A4 </td> <td align="right"> 595</td> <td align="right"> 842</td> </tr>
6538<tr><td> A4Small </td> <td align="right"> 595</td> <td align="right"> 842</td> </tr>
6539<tr><td> A5 </td> <td align="right"> 421</td> <td align="right"> 595</td> </tr>
6540<tr><td> A6 </td> <td align="right"> 297</td> <td align="right"> 421</td> </tr>
6541<tr><td> A7 </td> <td align="right"> 210</td> <td align="right"> 297</td> </tr>
6542<tr><td> A8 </td> <td align="right"> 148</td> <td align="right"> 210</td> </tr>
6543<tr><td> A9 </td> <td align="right"> 105</td> <td align="right"> 148</td> </tr>
6544<tr><td> A10 </td> <td align="right"> 74</td> <td align="right"> 105</td> </tr>
6545<tr><td> B0 </td> <td align="right"> 2836</td> <td align="right"> 4008</td> </tr>
6546<tr><td> B1 </td> <td align="right"> 2004</td> <td align="right"> 2836</td> </tr>
6547<tr><td> B2 </td> <td align="right"> 1418</td> <td align="right"> 2004</td> </tr>
6548<tr><td> B3 </td> <td align="right"> 1002</td> <td align="right"> 1418</td> </tr>
6549<tr><td> B4 </td> <td align="right"> 709</td> <td align="right"> 1002</td> </tr>
6550<tr><td> B5 </td> <td align="right"> 501</td> <td align="right"> 709</td> </tr>
6551<tr><td> C0 </td> <td align="right"> 2600</td> <td align="right"> 3677</td> </tr>
6552<tr><td> C1 </td> <td align="right"> 1837</td> <td align="right"> 2600</td> </tr>
6553<tr><td> C2 </td> <td align="right"> 1298</td> <td align="right"> 1837</td> </tr>
6554<tr><td> C3 </td> <td align="right"> 918</td> <td align="right"> 1298</td> </tr>
6555<tr><td> C4 </td> <td align="right"> 649</td> <td align="right"> 918</td> </tr>
6556<tr><td> C5 </td> <td align="right"> 459</td> <td align="right"> 649</td> </tr>
6557<tr><td> C6 </td> <td align="right"> 323</td> <td align="right"> 459</td> </tr>
6558<tr><td> Flsa </td> <td align="right"> 612</td> <td align="right"> 936</td> </tr>
6559<tr><td> Flse </td> <td align="right"> 612</td> <td align="right"> 936</td> </tr>
6560<tr><td> HalfLetter </td> <td align="right"> 396</td> <td align="right"> 612</td> </tr>
6561</table></div>
6562
6563<p>This option is also used to place subimages when writing to a multi-image
6564format that supports offsets, such as GIF89 and MNG. When used for this
6565purpose the offsets are always measured from the top left corner of the canvas
6566and are not affected by the <a href="command-line-options.html#gravity">-gravity</a> option. To
6567position 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
6568file, a <a href="command-line-options.html#page">-page</a> option appearing ahead of the first image in
6569the sequence with nonzero width and height defines the width and height values
6570that are written in the <code>MHDR</code> chunk. Otherwise, the MNG width and
6571height are computed from the bounding box that contains all images in the
6572sequence. When writing a GIF89 file, only the bounding box method is used to
6573determine its dimensions.</p>
6574
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6575<p>For a PostScript page, the image is sized as in <a href="command-line-options.html#geometry">-geometry</a> but positioned relative to the <var>lower
6576left-hand corner</var> of the page by {+-}<code>x</code><var>offset</var>{+-}<code>y</code> <var>offset</var>. Use <a href="command-line-options.html#page">-page 612x792</a>, for example, to center the image within the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6577page. If the image size exceeds the PostScript page, it is reduced to fit the
6578page. 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
6579corner of the page, unless the <a href="command-line-options.html#gravity">-gravity</a> option is
6580present with a value other than <var>NorthWest</var>.</p>
6581
6582<p>The default page dimensions for a TEXT image is 612x792.</p>
6583
6584<p>This option is used in concert with <a href="command-line-options.html#density">-density</a>.</p>
6585
6586<p>Use <a href="command-line-options.html#page">+page</a> to remove the page settings for an image.</p>
6587
6588<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6589 <h3 class="magick-header"><a id="paint"></a>-paint <var>radius</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6590</div>
6591
6592<p class="magick-description">simulate an oil painting.</p>
6593
6594<p>Each pixel is replaced by the most frequent color in a circular
6595neighborhood whose width is specified with <var>radius</var>.</p>
6596
6597<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6598 <h3 class="magick-header"><a id="path"></a>-path <var>path</var></h3></div>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6599
6600<p class="magick-description">write images to this path on disk.</p>
6601
6602<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6603 <h3 class="magick-header"><a id="pause_animate_"></a>-pause <var>seconds</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6604</div>
6605
6606<p class="magick-description">Pause between animation loops</p>
6607
6608<p>Pause for the specified number of seconds before repeating the animation.</p>
6609
6610<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6611 <h3 class="magick-header"><a id="pause_import_"></a>-pause <var>seconds</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6612</div>
6613
6614<p class="magick-description">Pause between snapshots.</p>
6615
6616<p>Pause for the specified number of seconds before taking the next snapshot.</p>
6617
6618<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6619 <h3 class="magick-header"><a id="perceptible"></a>-perceptible <var>epsilon</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6620</div>
6621
6622<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>
6623
6624<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6625 <h3 class="magick-header"><a id="ping"></a>-ping</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6626</div>
6627
6628<p class="magick-description">efficiently determine image characteristics.</p>
6629
6630<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6631 <h3 class="magick-header"><a id="pointsize"></a>-pointsize <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6632</div>
6633
6634<p class="magick-description">pointsize of the PostScript, OPTION1, or TrueType font.</p>
6635
6636<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6637 <h3 class="magick-header"><a id="polaroid"></a>-polaroid <var>angle</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6638</div>
6639
6640<p class="magick-description">simulate a Polaroid picture.</p>
6641
6642<p>Use <code>+polaroid</code> to rotate the image at a random angle between -15 and +15 degrees.</p>
6643
6644<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6645 <h3 class="magick-header"><a id="poly"></a>-poly <var>"wt,exp ..."</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6646</div>
6647
6648<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>
6649
6650<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>
6651
6652<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>
6653
6654<p>The format is: output = wt1*image1^exp1 + wt2*image2^exp2 ...</p>
6655
6656<p>Some simple uses are:</p>
6657<ul>
6658<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>
6659<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>
6660</ul>
6661
6662<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>
6663
6664<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>
6665
6666
6667<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6668 <h3 class="magick-header"><a id="posterize"></a>-posterize <var>levels</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6669</div>
6670
6671<p class="magick-description">reduce the image to a limited number of color levels per channel.</p>
6672
6673<p>Very low values of <var>levels</var>, e.g., 2, 3, 4, have the most
6674visible effect.</p>
6675
6676<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6677 <h3 class="magick-header"><a id="precision"></a>-precision <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6678</div>
6679
6680<p class="magick-description">set the maximum number of significant digits to be printed.</p>
6681
6682<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6683 <h3 class="magick-header"><a id="preview"></a>-preview <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6684</div>
6685
6686<p class="magick-description">image preview type.</p>
6687
6688<p>Use this option to affect the preview operation of an image (e.g.
6689<code>convert file.png -preview Gamma Preview:gamma.png</code>). Choose from
6690these previews:</p>
6691
6692<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6693Rotate Shear Roll Hue
6694Saturation Brightness Gamma Spiff
6695Dull Grayscale Quantize Despeckle
6696ReduceNoise Add Noise Sharpen Blur
6697Threshold EdgeDetect Spread Shade
6698Raise Segment Solarize Swirl
6699Implode Wave OilPaint CharcoalDrawing
6700JPEG
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6701</pre>
6702
6703<p>To print a complete list of previews, use the <a href="command-line-options.html#list">-list preview</a> option.</p>
6704
6705<p>The default preview is <code>JPEG</code>.</p>
6706
6707<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6708 <h3 class="magick-header"><a id="print"></a>-print <var>string</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6709</div>
6710
6711<p class="magick-description">interpret string and print to console.</p>
6712
6713<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6714 <h3 class="magick-header"><a id="process"></a>-process <var>command</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6715</div>
6716
6717<p class="magick-description">process the image with a custom image filter.</p>
6718
6719<p>The command arguments has the form <code>"module arg1 arg2 arg3 ...
6720argN"</code> where <code>module</code> is the name of the module to invoke (e.g.
6721"Analyze") and arg1 arg2 arg3 ... argN are an arbitrary number of arguments to
6722pass to the process module.</p>
6723
6724<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6725 <h3 class="magick-header"><a id="profile"></a>-profile <var>filename</var><br>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6726 +profile <var>profile_name</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6727</div>
6728
6729<p class="magick-description">Manage ICM, IPTC, or generic profiles in an image.</p>
6730
6731<p>Using <a href="command-line-options.html#profile">-profile</a> <var>filename</var> adds an
6732ICM (ICC color management), IPTC (newswire information), or a generic profile
6733to the image.</p>
6734
6735<p>Use <a href="command-line-options.html#profile">+profile <var>profile_name</var></a> to
6736remove the indicated profile. ImageMagick uses standard filename globbing, so
6737wildcard expressions may be used to remove more than one profile. Here we
6738remove all profiles from the image except for the XMP profile: <code>+profile
6739"!xmp,*"</code>. </p>
6740
6741<p>Use <code>identify -verbose</code> to find out which profiles are in the
6742image file. Use <a href="command-line-options.html#strip">-strip</a> to remove all profiles (and
6743comments).</p>
6744
6745<p>To extract a profile, the <a href="command-line-options.html#profile">-profile</a> option is not
6746used. Instead, simply write the file to an image format such as <var>APP1, 8BIM, ICM,</var> or <var>IPTC</var>.</p>
6747
6748<p>For example, to extract the Exif data (which is stored in JPEG files in the
6749<var>APP1</var> profile), use.</p>
6750
6751<pre>
6752convert cockatoo.jpg profile.exif
6753</pre>
6754
6755<p>It is important to note that results may depend on whether or not the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6756original image already has an included profile. Also, keep in mind that <a href="command-line-options.html#profile">-profile</a> is an "operator" (as opposed to a "setting") and
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6757therefore a conversion is made each time it is encountered, in order, in the
6758command-line. For instance, in the following example, if the original image is
6759CMYK with profile, a CMYK-CMYK-RGB conversion results.</p>
6760
6761<pre>
6762convert CMYK.tif -profile "CMYK.icc" -profile "RGB.icc" RGB.tiff
6763</pre>
6764
6765<p>Furthermore, since ICC profiles are not necessarily symmetric, extra
6766conversion steps can yield unwanted results. CMYK profiles are often very
6767asymmetric since they involve 3−&gt;4 and 4−&gt;3 channel mapping.
6768</p>
6769
6770<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6771 <h3 class="magick-header"><a id="quality"></a>-quality <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6772</div>
6773
6774<p class="magick-description">JPEG/MIFF/PNG compression level.</p>
6775
6776<p>For the JPEG and MPEG image formats, quality is 1 (lowest image quality and
6777highest compression) to 100 (best quality but least effective compression).
6778The default is to use the estimated quality of your input image if it can
6779be determined, otherwise 92. When the quality is greater than 90, then the
6780chroma channels are not downsampled.
6781Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to specify the
6782factors for chroma downsampling.</p>
6783
6784<p>For the MIFF image format, quality/10 is the zlib compression level, which
6785is 0 (worst but fastest compression) to 9 (best but slowest). It has no effect
6786on the image appearance, since the compression is always lossless.</p>
6787
6788<p>For the JPEG-2000 image format, quality is mapped using a non-linear
6789equation to the compression ratio required by the Jasper library. This
6790non-linear equation is intended to loosely approximate the quality provided by
6791the JPEG v1 format. The default quality value 100, a request for non-lossy
6792compression. A quality of 75 results in a request for 16:1 compression.</p>
6793
6794<p>For the MNG and PNG image formats, the quality value sets the zlib
6795compression level (quality / 10) and filter-type (quality % 10). The default
6796PNG "quality" is 75, which means compression level 7 with adaptive PNG
6797filtering, unless the image has a color map, in which case it means
6798compression level 7 with no PNG filtering.</p>
6799
6800<p>For compression level 0 (quality value less than 10), the Huffman-only
6801strategy is used, which is fastest but not necessarily the worst
6802compression.</p>
6803
6804<p>If filter-type is 4 or less, the specified PNG filter-type is used for
6805all scanlines:</p>
6806
6807<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]68080: none
68091: sub
68102: up
68113: average
68124: Paeth
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6813</pre>
6814
6815<p>If filter-type is 5, adaptive filtering is used when quality is greater
6816than 50 and the image does not have a color map, otherwise no filtering is
6817used.</p>
6818
6819<p>If filter-type is 6, adaptive filtering
6820with <var>minimum-sum-of-absolute-values</var> is used.</p>
6821
6822<p>Only if the output is MNG, if filter-type is 7, the LOCO color
6823transformation (intrapixel differencing) and adaptive filtering
6824with <var>minimum-sum-of-absolute-values</var> are used.</p>
6825
6826<p>If the filter-type is 8 the zlib Z_RLE compression strategy (or the
6827Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with
6828adaptive PNG filtering.</p>
6829
6830<p>If the filter-type is 9 the zlib Z_RLE compression strategy (or the
6831Z_HUFFMAN_ONLY strategy, when compression level is 0) is used with
6832no PNG filtering.</p>
6833
6834<p>The quality setting has no effect on the appearance or signature of PNG
6835and MNG images, since the compression is always lossless.</p>
6836
6837<p>Not all combinations of compression level, strategy, and PNG filter type
6838can be obtained using the -quality option. For more precise control,
6839you can use the PNG:compression-level=N, PNG:compression-strategy=N, and
6840PNG:compression-filter=N defines, respectively, instead.
6841See <a href="command-line-options.html#define">-define</a>. Values from the defines take precedence
6842over values from the -quality option.</p>
6843
6844<p>For further information, see
6845the <a href="http://www.w3.org/pub/WWW/TR">PNG</a> specification.</p>
6846
6847<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6848 <h3 class="magick-header"><a id="quantize"></a>-quantize <var>colorspace</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6849</div>
6850
6851<p class="magick-description">reduce colors using this colorspace.</p>
6852
6853<p>This setting defines the colorspace used to sort out and reduce the number
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6854of colors needed by an image (for later dithering) by operators such as <a href="command-line-options.html#colors">-colors</a>, Note that color reduction also happens
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6855automatically when saving images to color-limited image file formats, such as
6856GIF, and PNG8.</p>
6857
6858
6859<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6860 <h3 class="magick-header"><a id="quiet"></a>-quiet</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6861</div>
6862
6863<p class="magick-description">suppress all warning messages. Error messages are still reported.</p>
6864
6865<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6866 <h3 class="magick-header"><a id="radial-blur"></a>-radial-blur <var>angle</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6867</div>
6868
6869<p class="magick-description">Blur around the center of the image.</p>
6870
6871<p>Note that this is actually a rotational blur rather than a radial and as
6872such actually mis-named. </p>
6873
6874<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how
6875pixels which are outside the image proper are blurred into the final result.
6876</p>
6877
6878
6879<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6880 <h3 class="magick-header"><a id="raise"></a>-raise <var>thickness</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6881</div>
6882
6883<p class="magick-description">Lighten or darken image edges.</p>
6884
6885<p>This will create a 3-D effect. Use <a href="command-line-options.html#raise">-raise</a> to create
6886a raised effect, otherwise use <a href="command-line-options.html#raise">+raise</a>. </p>
6887
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6888<p>Unlike the similar <a href="command-line-options.html#frame">-frame</a> option, <a href="command-line-options.html#raise">-raise</a> does not alter the dimensions of the image.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6889
6890<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6891 <h3 class="magick-header"><a id="random-threshold"></a>-random-threshold <var>low</var>x<var>high</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6892</div>
6893
6894<p class="magick-description">Apply a random threshold to the image.</p>
6895
6896<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6897 <h3 class="magick-header"><a id="red-primary"></a>-red-primary <var>x,y</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6898</div>
6899
6900<p class="magick-description">Set the red chromaticity primary point.</p>
6901
6902<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6903 <h3 class="magick-header"><a id="regard-warnings"></a>-regard-warnings</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6904</div>
6905
6906<p class="magick-description">Pay attention to warning messages.</p>
6907
6908<p>This option causes some warnings in some image formats to be treated
6909as errors. </p>
6910
6911<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6912 <h3 class="magick-header"><a id="remap"></a>-remap <var>filename</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6913</div>
6914
6915<p class="magick-description">Reduce the number of colors in an image to the colors used by this image.</p>
6916
6917<p>If the <a href="command-line-options.html#dither">-dither</a> setting is enabled (the default) then
6918the given colors are dithered over the image as necessary, otherwise the closest
6919color (in RGB colorspace) is selected to replace that pixel in the image. </p>
6920
6921<p>As a side effect of applying a <a href="command-line-options.html#remap">-remap</a> of colors across all
6922images in the current image sequence, all the images will have the same color
6923table. That means that when saved to a file format such as GIF, it will use
6924that color table as a single common or global color table, for all the images,
6925without requiring extra local color tables. </p>
6926
6927<p>Use <a href="command-line-options.html#remap">+remap</a> to reduce all images in the current image
6928sequence to use a common color map over all the images. This equivalent to
6929appending all the images together (without extra background colors) and color
6930reducing those images using <a href="command-line-options.html#colors">-colors</a> with a 256 color
6931limit, then <a href="command-line-options.html#remap">-remap</a> those colors over the original list of
6932images. This ensures all the images follow a single color map. </p>
6933
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6934<p>If the number of colors over all the images is less than 256, then <a href="command-line-options.html#remap">+remap</a> should not perform any color reduction or dithering, as
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6935no color changes are needed. In that case, its only effect is to force the use
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]6936of a global color table. This recommended after using either <a href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#ordered-dither">-ordered-dither</a> to
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6937reduce the number of colors in an animated image sequence. </p>
6938
6939<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>
6940
6941<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6942 <h3 class="magick-header"><a id="region"></a>-region <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6943</div>
6944
6945<p class="magick-description">Set a region in which subsequent operations apply.</p>
6946
6947<p>The <var>x</var> and <var>y</var> offsets are treated
6948in the same manner as in <a href="command-line-options.html#crop">-crop</a>.</p>
6949
6950<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
6951
6952<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6953 <h3 class="magick-header"><a id="remote"></a>-remote</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6954</div>
6955
6956<p class="magick-description">perform a remote operation.</p>
6957
6958<p>The only command recognized is the name of an image file to load.</p>
6959
6960<p>If you have more than one <a href="display.html">display</a> application
6961running simultaneously, use the <a href="command-line-options.html#window"> window</a> option to
6962specify which application to control.</p>
6963
6964<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6965 <h3 class="magick-header"><a id="render"></a>-render</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6966</div>
6967
6968<p class="magick-description">render vector operations.</p>
6969
6970<p>Use <a href="command-line-options.html#render">+render</a> to turn off rendering vector operations.
6971This useful when saving the result to vector formats such as MVG or SVG.</p>
6972
6973<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]6974<h3 class="magick-header"><a id="repage"></a>-repage <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]6975</div>
6976
6977<p class="magick-description">Adjust the canvas and offset information of the image.</p>
6978
6979<p>This option is like <a href="command-line-options.html#page">-page</a> but acts as an image operator
6980rather than a setting. You can separately set the canvas size or the offset
6981of the image on that canvas by only providing those components. </p>
6982
6983<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
6984
6985<p>If a <code>!</code> flag is given the offset given is added to the existing
6986offset to move the image relative to its previous position. This useful for
6987animation sequences. </p>
6988
6989<p>A given a canvas size of zero such as '<code>0x0</code>' forces it to
6990recalculate the canvas size so the image (at its current offset) will appear
6991completely on that canvas (unless it has a negative offset).</p>
6992
6993<p>Use <a href="command-line-options.html#repage">+repage</a> to completely remove/reset the virtual
6994canvas meta-data from the images. </p>
6995
6996<p>The <a href="command-line-options.html#set">-set</a> '<code>page</code>' option can be used to
6997directly assign virtual canvas meta-data. </p>
6998
6999
7000<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7001 <h3 class="magick-header"><a id="resample"></a>-resample <var>horizontal</var>x<var>vertical</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7002</div>
7003
7004<p class="magick-description">Resample image to specified horizontal and vertical resolution.</p>
7005
7006<p>Resize the image so that its rendered size remains the same as the original
7007at the specified target resolution. For example, if a 300 DPI image renders at
70083 inches by 2 inches on a 300 DPI device, when the image has been resampled to
700972 DPI, it will render at 3 inches by 2 inches on a 72 DPI device. Note that
7010only a small number of image formats (e.g. JPEG, PNG, and TIFF) are capable of
7011storing the image resolution. For formats which do not support an image
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7012resolution, the original resolution of the image must be specified via <a href="command-line-options.html#density">-density</a> on the command line prior to specifying the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7013resample resolution.</p>
7014
7015<p>Note that Photoshop stores and obtains image resolution from a proprietary
7016embedded profile. If this profile exists in the image, then Photoshop will
7017continue to treat the image using its former resolution, ignoring the image
7018resolution specified in the standard file header.</p>
7019
7020<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7021 <h3 class="magick-header"><a id="resize"></a>-resize <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7022</div>
7023
7024<p class="magick-description">Resize an image.</p>
7025
7026<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
7027ignored, and the <a href="command-line-options.html#gravity">-gravity</a> option has no effect.</p>
7028
7029<p>If the <a href="command-line-options.html#filter">-filter</a> option
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7030or <code>-define filter:option=value</code> precedes the <a href="command-line-options.html#resize">-resize</a> option, the image is resized with the specified
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7031filter.</p>
7032
7033<p>Many image processing algorithms assume your image is in a linear-light
7034coding. If your image is gamma-corrected, you can remove the nonlinear gamma
7035correction, apply the transform, then restore it like this:</p>
7036
7037<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7038convert portrait.jpg -gamma .45455 -resize 25% -gamma 2.2 \
7039 -quality 92 passport.jpg
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7040</pre>
7041
7042<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7043 <h3 class="magick-header"><a id="respect-parentheses"></a>-respect-parentheses</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7044</div>
7045
7046<p class="magick-description">settings remain in effect until parenthesis boundary.</p>
7047
7048<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7049 <h3 class="magick-header"><a id="reverse"></a>-reverse</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7050</div>
7051
7052<p class="magick-description">Reverse the order of images in the current image list.</p>
7053
7054
7055<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7056 <h3 class="magick-header"><a id="roll"></a>-roll {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7057</div>
7058
7059<p class="magick-description">roll an image vertically or horizontally by the amount given.</p>
7060
7061<p>A negative <var>x</var> offset rolls the image right-to-left.
7062A negative <var>y</var> offset rolls the image bottom-to-top.</p>
7063
7064
7065<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7066 <h3 class="magick-header"><a id="rotate"></a>-rotate <var>degrees</var>{<var>&lt;</var>}{<var>&gt;</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7067</div>
7068
7069<p class="magick-description">Apply Paeth image rotation (using shear operations) to the image.</p>
7070
7071<p>Use <code>&gt;</code> to rotate the image only if its width exceeds the
7072height. <code>&lt;</code> rotates the image <var>only</var> if its width is less
7073than the height. For example, if you specify <code>-rotate "-90&gt;"</code> and
7074the image size is 480x640, the image is not rotated. However, if the image is
7075640x480, it is rotated by -90 degrees. If you use <code>&gt;</code> or
7076<code>&lt;</code>, enclose it in quotation marks to prevent it from being
7077misinterpreted as a file redirection.</p>
7078
7079<p>Empty triangles in the corners, left over from rotating the image, are
7080filled with the <code>background</code> color. </p>
7081
7082<p>See also the <a href="command-line-options.html#distort">-distort</a> operator and specifically the
7083'<code>ScaleRotateTranslate</code>' distort method. </p>
7084
7085
7086<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7087 <h3 class="magick-header"><a id="sample"></a>-sample <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7088</div>
7089
7090<p class="magick-description">minify / magnify the image with pixel subsampling and pixel replication, respectively.</p>
7091
7092<p>Change the image size simply by directly sampling the pixels original
7093from the image. When magnifying, pixels are replicated in blocks. When
7094minifying, pixels are sub-sampled (i.e., some rows and columns are skipped
7095over). </p>
7096
7097<p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with
7098a <a href="command-line-options.html#filter">-filter</a> setting of <code>point</code> (nearest
7099neighbour), though <a href="command-line-options.html#sample">-sample</a> is a lot faster, as it
7100avoids all the filter processing of the image. As such it completely ignores
7101the current <a href="command-line-options.html#filter">-filter</a> setting. </p>
7102
7103<p>The key feature of the <a href="command-line-options.html#sample">-sample</a> is that no new colors
7104will be added to the resulting image, though some colors may disappear. </p>
7105
7106<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
7107ignored, unlike <a href="command-line-options.html#resize">-resize</a>. </p>
7108
7109
7110<p>The actual sampling point is the middle of the sub-region being sampled.
7111As such a single pixel sampling of an image will take the middle pixel, (or
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7112top-left-middle if image has even dimensions). However the <a href="command-line-options.html#define">-define</a> '<code>sample:offset</code>' can be set to modify
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7113this position some other location within each sub-region being sampled, as
7114a percentage offset.</p>
7115
7116<p>By default this value is '<code>50</code>' for the midpoint, but could be set
7117to '<code>0</code>' for top-left, '<code>100</code>' for bottom-right, or with
7118separate X and Y offsets such as '<code>0x50</code>' for left-middle edge of
7119sampling sub-region.</p>
7120
7121
7122<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7123 <h3 class="magick-header"><a id="sampling-factor"></a>-sampling-factor <var>horizontal-factor</var>x<var>vertical-factor</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7124</div>
7125
7126<p class="magick-description">sampling factors used by JPEG or MPEG-2 encoder and YUV decoder/encoder.</p>
7127
7128<p>This option specifies the sampling factors to be used by the JPEG encoder
7129for chroma downsampling. If this option is omitted, the JPEG library will use
7130its own default values. When reading or writing the YUV format and when
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7131writing the M2V (MPEG-2) format, use <a href="command-line-options.html#sampling-factor">-sampling-factor 2x1</a> or <a href="command-line-options.html#sampling-factor">-sampling-factor 4:2:2</a> to specify the 4:2:2
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7132downsampling method.</p>
7133
7134<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7135 <h3 class="magick-header"><a id="scale"></a>-scale <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7136</div>
7137
7138<p class="magick-description">minify / magnify the image with pixel block averaging and pixel replication, respectively.</p>
7139
7140<p>Change the image size simply by replacing pixels by averaging pixels
7141together when minifying, or replacing pixels when magnifying. </p>
7142
7143<p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with
7144a <a href="command-line-options.html#filter">-filter</a> setting of <code>box</code>. Though it is a lot
7145faster, as it avoids all the filter processing of the image. As such it
7146completely ignores the current <a href="command-line-options.html#filter">-filter</a> setting. </p>
7147
7148<p>If when shrinking (minifying) images the original image is some integer
7149multiple of the new image size, the number of pixels averaged together to
7150produce the new pixel color is the same across the whole image. This is
7151a special case known as 'binning' and is often used as a method of reducing
7152noise in image such as those generated by digital cameras, especially in low
7153light conditions. </p>
7154
7155
7156<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7157 <h3 class="magick-header"><a id="scene"></a>-scene <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7158</div>
7159
7160<p class="magick-description">set scene number.</p>
7161
7162<p>This option sets the scene number of an image or the first image in an image sequence.</p>
7163
7164<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7165 <h3 class="magick-header"><a id="screen"></a>-screen</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7166</div>
7167
7168<p class="magick-description">specify the screen to capture.</p>
7169
7170<p>This option indicates that the GetImage request used to obtain the image
7171should be done on the root window, rather than directly on the specified
7172window. In this way, you can obtain pieces of other windows that overlap the
7173specified window, and more importantly, you can capture menus or other popups
7174that are independent windows but appear over the specified window.</p>
7175
7176<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7177 <h3 class="magick-header"><a id="seed"></a>-seed</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7178</div>
7179
7180<p class="magick-description">seed a new sequence of pseudo-random numbers</p>
7181
7182<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7183 <h3 class="magick-header"><a id="segment"></a>-segment <var>cluster-threshold</var>x<var>smoothing-threshold</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7184</div>
7185
7186<p class="magick-description">segment the colors of an image.</p>
7187
7188<p>Segment an image by analyzing the histograms of the color components and
7189identifying units that are homogeneous with the fuzzy c-means technique. This
7190is part of the ImageMagick color quantization routines. </p>
7191
7192<p>Specify <var>cluster threshold</var> as the number of pixels in
7193each cluster that must exceed the cluster threshold to be considered valid.
7194<var>Smoothing threshold</var> eliminates noise in the second
7195derivative of the histogram. As the value is increased, you can expect
7196a smoother second derivative. The default is 1.5.</p>
7197
7198<p>If the <a href="command-line-options.html#verbose">-verbose</a> setting is defined, a detailed report
7199of the color clusters is returned.</p>
7200
7201
7202<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7203 <h3 class="magick-header"><a id="selective-blur"></a>-selective-blur <var>radius</var><br>-selective-blur <var>radius</var>x<var>sigma</var>{<var>+threshold</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7204</div>
7205
7206<p class="magick-description">Selectively blur pixels within a contrast threshold.</p>
7207
7208<p>Blurs those pixels that are less than or equal to the threshold in
7209contrast. The threshold may be expressed as a fraction of <var>QuantumRange</var> or as a percentage.</p>
7210
7211<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7212 <h3 class="magick-header"><a id="separate"></a>-separate</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7213</div>
7214
7215<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>
7216
7217<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7218 <h3 class="magick-header"><a id="sepia-tone"></a>-sepia-tone <var>threshold</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7219</div>
7220
7221<p class="magick-description">simulate a sepia-toned photo.</p>
7222
7223<p>Specify <var>threshold</var> as the percent threshold of the intensity (0 - 99.9%).</p>
7224
7225<p>This option applies a special effect to the image, similar to the effect
7226achieved 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
7227toning. A threshold of 80% is a good starting point for a reasonable
7228tone.</p>
7229
7230
7231
7232<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7233 <h3 class="magick-header"><a id="set"></a>-set <var>key value</var></h3>
7234 <h3 class="magick-header">+set <var>key</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7235</div>
7236
7237<p class="magick-description">sets image attributes and properties for images in the current image sequence.</p>
7238
7239<p>This will assign (or modify) specific settings attached to all the images
7240in the current image sequence. Using the <a href="command-line-options.html#set">+set</a> form of the
7241option will either remove, or reset that setting to a default state, as
7242appropriate. </p>
7243
7244<p>For example, it will modify specific well known image meta-data
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7245'attributes' such as those normally overridden by: the options <a href="command-line-options.html#delay">-delay</a>, <a href="command-line-options.html#dispose">-dispose</a>, and <a href="command-line-options.html#page">-page</a>, <a href="command-line-options.html#colorspace">-colorspace</a>; generally
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7246assigned before the image is read in, by using a <var>key</var> of
7247the same name. </p>
7248
7249<p>If the given <var>key</var> does not match a specific known
7250'attribute ', such as shown above, the setting is stored as a a free form
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7251'property' string. Such settings are listed in <a href="command-line-options.html#verbose">-verbose</a> information ("<code>info:</code>" output format) as "Properties".
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7252</p>
7253
7254<p>This includes string 'properties' that are set by and assigned to images
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7255using the options <a href="command-line-options.html#comment">-comment</a>, <a href="command-line-options.html#label">-label</a>, <a href="command-line-options.html#caption">-caption</a>. These options actually assign
7256a global 'artifact' which are automatically assigned (and any <a href="escape.html">Format Percent
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7257Escapes</a> expanded) to images as they are read in. For example:</p>
7258
7259<pre>
7260convert rose: -set comment 'Rose is a rose is a rose is a rose' rose.png
7261identify -format %c rose.png
7262Rose is a rose is a rose is a rose
7263</pre>
7264
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7265<p>The set value can also make use of <a href="escape.html">Format and Print Image
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7266Properties</a> in the defined value. For example:</p>
7267
7268<pre>
7269convert rose: -set origsize '%wx%h' -resize 50% \
7270 -format 'Old size = %[origsize] New size = %wx%h' info:
7271Old size = 70x46 New size = 35x23
7272</pre>
7273
7274<p>Other well known 'properties' that are availible include:
7275'<code>date:create</code>' and '<code>date:modify</code>' and
7276'<code>signature</code>'. </p>
7277
7278<p>The <a href="command-line-options.html#repage">-repage</a> operator will also allow you to modify
7279the '<code>page</code>' attribute of an image for images already in memory (also
7280see <a href="command-line-options.html#repage">-page</a>). However it is designed to provide a finer
7281control of the sub-parts of this 'attribute'. The <a href="command-line-options.html#set">-set page</a>
7282option will only provide a direct, unmodified assignment of '<code>page</code>'
7283attribute. </p>
7284
7285<p>This option can also associate a colorspace or profile with your image.
7286For example,</p>
7287
7288<pre>
7289convert image.psd -set profile ISOcoated_v2_eci.icc image-icc.psd
7290</pre>
7291
7292<p>Some 'properties' must be defined in a specific way to be used. For
7293example only 'properties' prefixed with "<code>filename:</code>" can be used to
7294modify the output filename of an image. For example</p>
7295
7296<pre>
7297convert rose: -set filename:mysize '%wx%h' 'rose_%[filename:mysize].png'
7298</pre>
7299
7300<p>If the setting value is prefixed with "<code>option:</code>" the setting will
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7301be saved as a global "Artifact" exactly as if it was set using the <a href="command-line-options.html#define">-define</a> option. As such settings are global in scope, they
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7302can be used to pass 'attributes' and 'properties' of one specific image,
7303in a way that allows you to use them in a completely different image, even if
7304the original image has long since been modified or destroyed. For example: </p>
7305
7306<pre>
7307convert rose: -set option:rosesize '%wx%h' -delete 0 \
7308 label:'%[rosesize]' label_size_of_rose.gif"
7309</pre>
7310
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7311<p>Note that <a href="escape.html">Format Percent Escapes</a> will only match
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7312a 'artifact' if the given <var>key</var> does not match an existing
7313'attribute' or 'property'. </p>
7314
7315<p>You can set the attributes of the image registry by prefixing the value
7316with <code>registry:</code>.</p>
7317
7318<p>The <a href="command-line-options.html#set">-set profile</a> option can also be used to inject
7319previously-formatted ancillary chunks into the output PNG file, using
7320the commandline option as shown below or by setting the profile via a
7321programming interface:</p>
7322
7323<pre>
7324convert in.png -set profile PNG-chunk-x:&lt;filename&gt; out.png
7325</pre>
7326
7327<p>where <var>x</var> is a location flag and
7328<var>filename</var> is a file containing the chunk
7329name in the first 4 bytes, then a colon (":"), followed by the chunk data.
7330This encoder will compute the chunk length and CRC, so those must not
7331be included in the file.</p>
7332
7333<p>"x" can be "b" (before PLTE), "m" (middle, i.e., between PLTE and IDAT),
7334or "e" (end, i.e., after IDAT). If you want to write multiple chunks
7335of the same type, then add a short unique string after the "x" to prevent
7336subsequent profiles from overwriting the preceding ones, e.g.,</p>
7337
7338
7339<pre>
7340convert in.png -set profile PNG-chunk-b01:file01 \
7341 -profile PNG-chunk-b02:file02 out.png
7342</pre>
7343
7344<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7345 <h3 class="magick-header"><a id="shade"></a>-shade <var>azimuth</var>x<var>elevation</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7346</div>
7347
7348<p class="magick-description">shade the image using a distant light source.</p>
7349
7350<p>Specify <var>azimuth</var> and <var>elevation</var> as
7351the position of the light source. Use <a href="command-line-options.html#shade">+shade</a> to return
7352the shading results as a grayscale image.</p>
7353
7354<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7355 <h3 class="magick-header"><a id="shadow"></a>-shadow <var>percent-opacity</var>{x<var>sigma</var>}{<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var>{<var>%</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7356</div>
7357
7358<p class="magick-description">simulate an image shadow.</p>
7359
7360<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7361 <h3 class="magick-header"><a id="shared-memory"></a>-shared-memory</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7362</div>
7363
7364<p class="magick-description">use shared memory.</p>
7365
7366<p>This option specifies whether the utility should attempt to use shared
7367memory for pixmaps. ImageMagick must be compiled with shared memory support,
7368and the display must support the <var>MIT-SHM</var> extension.
7369Otherwise, this option is ignored. The default is <code>True</code>.</p>
7370
7371<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7372 <h3 class="magick-header"><a id="sharpen"></a>-sharpen <var>radius</var><br>-sharpen <var>radius</var>x<var>sigma</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7373</div>
7374
7375<p class="magick-description">sharpen the image.</p>
7376
7377<p>Use a Gaussian operator of the given radius and standard deviation (sigma).</p>
7378
7379<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7380 <h3 class="magick-header"><a id="shave"></a>-shave <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7381</div>
7382
7383<p class="magick-description">Shave pixels from the image edges.</p>
7384
7385<p>The <var>size</var> portion of the <var>geometry</var>
7386argument specifies the width of the region to be removed from both sides of
7387the image and the height of the regions to be removed from top and bottom.
7388Offsets are ignored.</p>
7389
7390<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
7391
7392<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7393 <h3 class="magick-header"><a id="shear"></a>-shear <var>Xdegrees</var>[x<var>Ydegrees</var>]</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7394</div>
7395
7396<p class="magick-description">Shear the image along the x-axis and/or y-axis.</p>
7397
7398<p>The shear angles may be positive, negative, or zero. When <var>Ydegrees</var> is omitted it defaults to 0. When both angles are
7399given, the horizontal component of the shear is performed before the vertical
7400component.</p>
7401
7402<p>Shearing slides one edge of an image along the x-axis or y-axis (i.e.,
7403horizontally or vertically, respectively),creating a parallelogram. The amount
7404of each is controlled by the respective shear angle. For horizontal shears,
7405<var>Xdegrees</var> is measured clockwise relative to "up" (the
7406negative y-axis), sliding the top edge to the right when 0°&lt;<var>Xdegrees</var>&lt;90° and to the left when 90°&lt;<var>Xdegrees</var>&lt;180°. For vertical shears <var>Ydegrees</var> is measured clockwise relative to "right" (the
7407positive x-axis), sliding the right edge down when 0°&lt;<var>Ydegrees</var>&lt;90° and up when 90°&lt;<var>Ydegrees</var>&lt;180°.</p>
7408
7409<p>Empty triangles left over from shearing the image are filled with the color
7410defined by the <a href="command-line-options.html#fill">-background</a> option. The color is specified
7411using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
7412
7413<p>The horizontal shear is performed before the vertical part. This is
7414important to note, since horizontal and vertical shears do not
7415<var>commute</var>, i.e., the order matters in a sequence of shears. For
7416example, the following two commands are not equivalent.</p>
7417
7418<pre>
7419convert logo: -shear 20x0 -shear 0x60 logo-sheared.png
7420convert logo: -shear 0x60 -shear 20x0 logo-sheared.png
7421</pre>
7422
7423<p>The first of the two commands above is equivalent to the following, except
7424for the amount of empty space created; the command that follows generates
7425a smaller image, and so is a better choice in terms of time and space.</p>
7426
7427<pre>
7428convert logo: -shear 20x60 logo-sheared.png
7429</pre>
7430
7431<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7432 <h3 class="magick-header"><a id="sigmoidal-contrast"></a>-sigmoidal-contrast <var>contrast</var>x<var>mid-point</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7433</div>
7434
7435<p class="magick-description">increase the contrast without saturating highlights or shadows.</p>
7436
7437<p>Increase the contrast of the image using a sigmoidal transfer function
7438without saturating highlights or shadows. <var>Contrast</var>
7439indicates how much to increase the contrast. For example, 0 is none, 3 is
7440typical and 20 is a lot.
7441</p>
7442
7443<p>The <var>mid-point</var> indicates where the maximum change
7444'slope' in contrast should fall in the resultant image (0 is white; 50% is
7445middle-gray; 100% is black). </p>
7446
7447<p>By default the image contrast is increased, use <var>+sigmoidal-contrast</var> to decrease the contrast.</p>
7448
7449<p>To achieve the equivalent of a sigmoidal brightness change (similar to
7450a gamma adjustment), you would use <var>-sigmoidal-contrast
7451{brightness}x0%</var> to increase brightness and <var>+sigmoidal-contrast {brightness}x0%</var> to decrease brightness.
7452Note the use of '0' fo rthe mid-point of the sigmoidal curve. </p>
7453
7454<p>Using a very high <var>contrast</var> will produce a sort of
7455'smoothed thresholding' of the image. Not as sharp (with high aliasing
7456effects) of a true threshold, but with tapered gray-levels around the threshold
7457<var>mid-point</var>. </p>
7458
7459<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7460 <h3 class="magick-header"><a id="silent"></a>-silent</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7461</div>
7462
7463<p class="magick-description">operate silently.</p>
7464
7465<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7466 <h3 class="magick-header"><a id="similarity-threshold"></a>-similarity-threshold <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7467</div>
7468
7469<p class="magick-description">minimum RMSE for subimage match.</p>
7470
7471<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>
7472
7473<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7474 <h3 class="magick-header"><a id="size"></a>-size <var>width</var>[x<var>height</var>][<var>+offset</var>]</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7475</div>
7476
7477<p class="magick-description">set the width and height of the image.</p>
7478
7479<p>Use this option to specify the width and height of raw images whose
7480dimensions are unknown such as <code>GRAY</code>, <code>RGB</code>, or
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7481<code>CMYK</code>. In addition to width and height, use <a href="command-line-options.html#size">-size</a> with an offset to skip any header information in the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7482image or tell the number of colors in a <code>MAP</code> image file, (e.g. -size
7483640x512+256).</p>
7484
7485<p>For Photo CD images, choose from these sizes:</p>
7486
7487<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7488192x128
7489384x256
7490768x512
74911536x1024
74923072x2048
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7493</pre>
7494
7495<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7496 <h3 class="magick-header"><a id="sketch"></a>-sketch <var>radius</var><br>-sketch <var>radius</var>x<var>sigma</var>+<var>angle</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7497</div>
7498
7499<p class="magick-description">simulate a pencil sketch.</p>
7500
7501<p>Sketch with the given radius, standard deviation (sigma), and angle. The
7502angle given is the angle toward which the image is sketched. That is the
7503direction people would consider the object is coming from. </p>
7504
7505<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7506 <h3 class="magick-header"><a id="smush"></a>-smush <var>offset</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7507</div>
7508
7509<p class="magick-description">smush an image sequence together.</p>
7510
7511<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7512 <h3 class="magick-header"><a id="snaps"></a>-snaps <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7513</div>
7514
7515<p class="magick-description">Set the number of screen snapshots.</p>
7516
7517<p>Use this option to grab more than one image from the X server screen, to create an animation sequence.</p>
7518
7519<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7520 <h3 class="magick-header"><a id="solarize"></a>-solarize <var>threshold</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7521</div>
7522
7523<p class="magick-description">negate all pixels above the threshold level.</p>
7524
7525<p>Specify <var>factor</var> as the percent threshold of the intensity (0 - 99.9%).</p>
7526
7527<p>This option produces a <var>solarization</var> effect seen when
7528exposing a photographic film to light during the development process.</p>
7529
7530<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7531 <h3 class="magick-header"><a id="sparse-color"></a>-sparse-color <var>method</var> '<var>x</var>,<var>y</var> <var>color</var> ...'</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7532</div>
7533
7534<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>
7535
7536
7537<table class="table table-condensed table-striped">
7538 <tbody>
7539 <tr>
7540 <th style="width: 8%">Method</th>
7541 <th>Description</th>
7542 </tr>
7543
7544 <tr>
7545 <td>barycentric</td>
7546 <td>three point triangle of color given 3 points.
7547 Giving only 2 points will form a linear gradient between those points.
7548 The gradient generated extends beyond the triangle created by those
7549 3 points. </td>
7550 </tr>
7551
7552 <tr>
7553 <td>bilinear</td>
7554 <td>Like barycentric but for 4 points. Less than 4 points
7555 fall back to barycentric. </td>
7556 </tr>
7557 <tr>
7558 <td>voronoi</td>
7559 <td>Simply map each pixel to the to nearest color point
7560 given. The result are polygonal 'cells' of solid color. </td>
7561 </tr>
7562
7563 <tr>
7564 <td>shepards</td>
7565 <td>Colors points biased on the ratio of inverse distance
7566 squared. Generating spots of color in a sea of the average of
7567 colors. </td>
7568 </tr>
7569
7570 <tr>
7571 <td>inverse</td>
7572 <td>Colors points biased on the ratio of inverse distance.
7573 This generates sharper points of color rather than rounded spots of
7574 '<code>shepards</code>' Generating spots of color in a sea of the
7575 average of colors. </td>
7576 </tr>
7577
7578 </tbody>
7579</table>
7580
7581<p>The points are placed according to the images location on the virtual
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7582canvas (<a href="command-line-options.html#page">-page</a> or <a href="command-line-options.html#repage">-repage</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7583offset), and do not actually have to exist on the given image, but may be
7584some point beyond the edge of the image. All points are floating point values.
7585</p>
7586
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7587<p>Only the color channels defined by the <a href="command-line-options.html#channel">-channel</a> are
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7588modified, which means that by default matte/alpha transparency channel is not
7589effected. Typically transparency channel is turned off either before or after
7590the operation. </p>
7591
7592<p>Of course if some color points are transparent to generate a transparent
7593gradient, then the image also requires transparency enabled to store the
7594values. </p>
7595
7596<p>All the above methods when given a single point of color will replace all
7597the colors in the image with the color given, regardless of the point. This is
7598logical, and provides an alternative technique to recolor an image to some
7599default value. </p>
7600
7601
7602<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7603 <h3 class="magick-header"><a id="splice"></a>-splice <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7604</div>
7605
7606<p class="magick-description">Splice the current background color into the image.</p>
7607
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7608<p>This will add rows and columns of the current <a href="command-line-options.html#background">-background</a> color into the given image according to the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7609given <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
7610image into four quadrants, separating them by the inserted rows and columns.
7611</p>
7612
7613<p>If a dimension of geometry is zero no rows or columns will be added for that
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7614dimension. Similarly using a zero offset with the appropriate <a href="command-line-options.html#gravity">-gravity</a> setting will add rows and columns to the edges of
7615the image, padding the image only along that one edge. Edge padding is what <a href="command-line-options.html#splice">-splice</a> is most commonly used for. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7616
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7617<p>If the exact same <var>geometry</var> and <a href="command-line-options.html#gravity">-gravity</a> is later used with <a href="command-line-options.html#chop">-chop</a> the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7618added added all splices removed. </p>
7619
7620<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7621 <h3 class="magick-header"><a id="spread"></a>-spread <var>amount</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7622</div>
7623
7624<p class="magick-description">displace image pixels by a random amount.</p>
7625
7626<p>The argument <var>amount</var> defines the size of the
7627neighborhood around each pixel from which to choose a candidate pixel to
7628swap.</p>
7629
7630<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7631 <h3 class="magick-header"><a id="statistic"></a>-statistic <var>type</var> <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7632</div>
7633
7634<p class="magick-description">replace each pixel with corresponding statistic from the neighborhood.</p>
7635
7636<p>Choose from these statistic types:</p>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7637<dl class="dl-horizontal">
7638<dt>Gradient</dt><dd>maximum difference (max - min) value in neighborhood</dd>
7639<dt>Maximum</dt><dd>maximum value per channel in neighborhood</dd>
7640<dt>Minimum</dt><dd>minimum value per channel in neighborhood</dd>
7641<dt>Mean</dt><dd>average value per channel in neighborhood</dd>
7642<dt>Median</dt><dd>median value per channel in neighborhood</dd>
7643<dt>Mode</dt><dd>mode (most frequent) value per channel in neighborhood</dd>
7644<dt>Nonpeak</dt><dd>value just before or after the median value per channel in neighborhood</dd>
7645<dt>RMS</dt><dd>root mean square value per channel in neighborhood</dd>
7646<dt>StandardDeviation</dt><dd> standard deviation value per channel in neighborhood</dd>
7647</dl>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7648
7649<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7650 <h3 class="magick-header"><a id="stegano"></a>-stegano <var>offset</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7651</div>
7652
7653<p class="magick-description">hide watermark within an image.</p>
7654
7655<p>Use an offset to start the image hiding some number of pixels from the
7656beginning of the image. Note this offset and the image size. You will need
7657this information to recover the steganographic image (e.g. display -size
7658320x256+35 stegano:image.png).</p>
7659
7660<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7661 <h3 class="magick-header"><a id="stereo"></a>-stereo <var>+x</var>{<var>+y</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7662</div>
7663
7664<p class="magick-description">composite two images to create a red / cyan stereo anaglyph.</p>
7665
7666<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>
7667
7668<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7669 <h3 class="magick-header"><a id="storage-type"></a>-storage-type <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7670</div>
7671
7672<p class="magick-description">pixel storage type. Here are the valid types:</p>
7673
7674<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7675char unsigned characters
7676double doubles
7677float floats
7678integer integers
7679long longs
7680quantum pixels in the native depth of your ImageMagick distribution
7681short unsigned shorts
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7682</pre>
7683
7684<p>Float and double types are normalized from 0.0 to 1.0 otherwise the pixels
7685values range from 0 to the maximum value the storage type can support.</p>
7686
7687<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7688 <h3 class="magick-header"><a id="stretch"></a>-stretch <var>fontStretch</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7689</div>
7690
7691<p class="magick-description">Set a type of stretch style for fonts.</p>
7692
7693<p>This setting suggests a type of stretch that ImageMagick should try to
7694apply to the currently selected font family. Select <var>fontStretch</var> from the following.</p>
7695
7696<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7697Any
7698Condensed
7699Expanded
7700ExtraCondensed
7701ExtraExpanded
7702Normal
7703SemiCondensed
7704SemiExpanded
7705UltraCondensed
7706UltraExpanded
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7707</pre>
7708
7709<p>To print a complete list of stretch types, use <a href="command-line-options.html#list">-list
7710stretch</a>.</p>
7711
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7712<p>For other settings that affect fonts, see the options <a href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7713
7714<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7715 <h3 class="magick-header"><a id="strip"></a>-strip</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7716</div>
7717
7718<p class="magick-description">strip the image of any profiles or comments.</p>
7719
7720<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7721 <h3 class="magick-header"><a id="stroke"></a>-stroke <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7722</div>
7723
7724<p class="magick-description">color to use when stroking a graphic primitive.</p>
7725
7726<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
7727
7728<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p>
7729
7730<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7731 <h3 class="magick-header"><a id="strokewidth"></a>-strokewidth <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7732</div>
7733
7734<p class="magick-description">set the stroke width.</p>
7735
7736<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p>
7737
7738<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7739 <h3 class="magick-header"><a id="style"></a>-style <var>fontStyle</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7740</div>
7741
7742<p class="magick-description">Set a font style for text.</p>
7743
7744<p>This setting suggests a font style that ImageMagick should try to apply to
7745the currently selected font family. Select <var>fontStyle</var> from
7746the following.</p>
7747
7748<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7749Any
7750Italic
7751Normal
7752Oblique
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7753</pre>
7754
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7755<p>For other settings that affect fonts, see the options <a href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a href="command-line-options.html#stretch">-stretch</a>, and <a href="command-line-options.html#weight">-weight</a>. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7756
7757<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7758 <h3 class="magick-header"><a id="subimage-search"></a>-subimage-search</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7759</div>
7760
7761<p class="magick-description">search for subimage.</p>
7762
7763<p>This option is required to have compare search for the best match location
7764of a small image within a larger image. This search will produce two images
7765(or two frames). The first is the "difference" image and the second will
7766be the "match score" image.</p>
7767
7768<p>The "match-score" image is smaller containing a pixel for ever possible
7769position of the top-left corner of the given sub-image. that is its size will
7770be the size of the larger_image - sub_image + 1. The brightest location in
7771this image is the location s the locate on the best match that is also
7772reported. Note that this may or may not be a perfect match, and the actual
7773brightness will reflect this. Other bright 'peaks' can be used to locate other
7774possible matching locations. </p>
7775
7776<p>Note that the search will try to compare the sub-image at every possible
7777location in the larger image, as such it can be very slow. The smaller the
7778sub-image the faster this search is. </p>
7779
7780
7781<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7782 <h3 class="magick-header"><a id="swap"></a>-swap <var>index,index</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7783</div>
7784
7785<p class="magick-description">Swap the positions of two images in the image sequence.</p>
7786
7787<p>For example, <a href="command-line-options.html#swap">-swap 0,2</a> swaps the first and the third
7788images in the current image sequence. Use <a href="command-line-options.html#swap">+swap</a> to switch
7789the last two images in the sequence.</p>
7790
7791<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7792 <h3 class="magick-header"><a id="swirl"></a>-swirl <var>degrees</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7793</div>
7794
7795<p class="magick-description">swirl image pixels about the center.</p>
7796
7797<p><var>Degrees</var> defines the tightness of the swirl.</p>
7798
7799<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7800 <h3 class="magick-header"><a id="synchronize"></a>-synchronize</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7801</div>
7802
7803<p class="magick-description">synchronize image to storage device.</p>
7804
7805<p>Set to "true" to ensure all image data is fully flushed and synchronized
7806to disk. There is a performance penalty, but the benefits include ensuring a
7807valid image file in the event of a system crash and early reporting if there
7808is not enough disk space for the image pixel cache.</p>
7809
7810<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7811 <h3 class="magick-header"><a id="taint"></a>-taint</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7812</div>
7813
7814<p class="magick-description">Mark the image as modified.</p>
7815
7816<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7817 <h3 class="magick-header"><a id="text-font"></a>-text-font <var>name</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7818</div>
7819
7820<p class="magick-description">font for writing fixed-width text.</p>
7821
7822<p>Specifies the name of the preferred font to use in fixed (typewriter style)
7823formatted text. The default is 14 point <var>Courier</var>.</p>
7824
7825<p>You can tag a font to specify whether it is a PostScript, TrueType, or
7826OPTION1 font. For example, <code>Courier.ttf</code> is a TrueType font and
7827<code>x:fixed</code> is OPTION1.</p>
7828
7829<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7830 <h3 class="magick-header"><a id="texture"></a>-texture <var>filename</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7831</div>
7832
7833<p class="magick-description">name of texture to tile onto the image background.</p>
7834
7835<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7836 <h3 class="magick-header"><a id="threshold"></a>-threshold <var>value</var>{<var>%</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7837</div>
7838
7839<!-- {<var>green,blue,opacity</var>}
7840<p>If the green or blue value is omitted, these channels use the same value as
7841the first one provided. If all three color values are the same, the result is
7842a bi-level image. If the opacity threshold is omitted, OpaqueOpacity is used
7843and any partially transparent pixel becomes fully transparent.</p>
7844-->
7845
7846<p class="magick-description">Apply simultaneous black/white threshold to the image.</p>
7847
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7848<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
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7849maximum channel value, while all other values are assigned the minimum.</p>
7850
7851<p> The threshold value can be given as a percentage or as an absolute integer
7852value corresponding to the desired channel value. When given as an integer,
7853the minimum attainable value is 0 (corresponding to black when all channels
7854are affected), but the maximum value (corresponding to white) is that of the
7855<code>quantum depth</code> of the particular build of ImageMagick, and is
7856therefore dependent on the installation. For that reason, a reasonable
7857recommendation for most applications is to specify the threshold values as
7858a percentage. </p>
7859
7860<p> The following would force pixels with red values above 50% to have 100%
7861red values, while those at or below 50% red would be set to 0 in the red
7862channel. The green, blue, and alpha channels (if present) would be unchanged.
7863</p>
7864
7865<pre>
7866convert in.png -channel red -threshold 50% out.png
7867</pre>
7868
7869<p>As (possibly) impractical but instructive examples, the following would
7870generate an all-black and an all-white image with the same dimensions as the
7871input image.</p>
7872
7873
7874<pre>
7875convert in.png -threshold 100% black.png
7876convert in.png -threshold -1 white.png
7877</pre>
7878
7879<p>Note that the values of the transparency channel is treated as 'matte'
7880values (0 is opaque) and not as 'alpha' values (0 is transparent).</p>
7881
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7882<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>.
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7883</p>
7884
7885<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7886 <h3 class="magick-header"><a id="thumbnail"></a>-thumbnail <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7887</div>
7888
7889<p class="magick-description">Create a thumbnail of the image.</p>
7890
7891<p>This is similar to <a href="command-line-options.html#resize">-resize</a>, except it is optimized
7892for speed and any image profile, other than a color profile, is removed to
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7893reduce the thumbnail size. To strip the color profiles as well, add <a href="command-line-options.html#strip">-strip</a> just before of after this option.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7894
7895<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
7896
7897<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7898 <h3 class="magick-header"><a id="tile"></a>-tile <var>filename</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7899</div>
7900
7901<p class="magick-description">Set the tile image used for filling a subsequent graphic primitive.</p>
7902
7903<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7904 <h3 class="magick-header">-tile <var>geometry</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7905</div>
7906
7907<p class="magick-description">Specify the layout of images.</p>
7908
7909<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
7910
7911<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7912 <h3 class="magick-header">-tile</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7913</div>
7914
7915<p class="magick-description">Specifies that a subsequent composite operation is repeated across and down image.</p>
7916
7917<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7918 <h3 class="magick-header"><a id="tile-offset"></a>-tile-offset {<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7919</div>
7920
7921<p class="magick-description">Specify the offset for tile images, relative to the background image it is tiled on.</p>
7922
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7923<p>This should be set before the tiling image is set by <a href="command-line-options.html#tile">-tile</a> or <a href="command-line-options.html#texture">-texture</a>, or directly applied for
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7924creating a tiled canvas using <code>TILE:</code> or <code>PATTERN:</code> input
7925formats. </p>
7926
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7927<p>Internally ImageMagick does a <a href="command-line-options.html#roll">-roll</a> of the tile image
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7928by the arguments given when the tile image is set. </p>
7929
7930<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7931 <h3 class="magick-header"><a id="tint"></a>-tint <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7932</div>
7933
7934<p class="magick-description">Tint the image with the fill color.</p>
7935
7936<p>Tint the image with the fill color.</p>
7937
7938<p>Specify the amount of tinting as a percentage. Pure colors like black,
7939white red, yellow, will not be affected by -tint. Only mid-range colors such
7940as the various shades of grey.</p>
7941
7942<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7943 <h3 class="magick-header"><a id="title"></a>-title <var>string</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7944</div>
7945
7946<p class="magick-description">Assign a title to displayed image.", "animate", "display", "montage</p>
7947
7948<p>Use this option to assign a specific title to the image. This assigned to
7949the image window and is typically displayed in the window title bar.
7950Optionally you can include the image filename, type, width, height, Exif data,
7951or other image attribute by embedding special format characters described
7952under the <a href="command-line-options.html#format">-format</a> option.</p>
7953
7954<p>For example,</p>
7955
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7956<pre>
7957-title "%m:%f %wx%h"
7958</pre>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7959
7960<p>produces an image title of <code>MIFF:bird.miff 512x480</code> for an image
7961titled <code>bird.miff</code> and whose width is 512 and height is 480.</p>
7962
7963
7964<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7965 <h3 class="magick-header"><a id="transform"></a>-transform</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7966</div>
7967
7968<p class="magick-description">transform the image.</p>
7969
7970<p>This option applies the transformation matrix from a previous <a href="command-line-options.html#affine">-affine</a> option.</p>
7971
7972<pre>
7973convert -affine 2,2,-2,2,0,0 -transform bird.ppm bird.jpg
7974</pre>
7975
7976
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7977<p>This operator has been now been superseded by the <a href="command-line-options.html#distort">-distort</a> '<code>AffineProjection</code>' method. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7978
7979
7980<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]7981 <h3 class="magick-header"><a id="transparent"></a>-transparent <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7982</div>
7983
7984<p class="magick-description">Make this color transparent within the image.</p>
7985
7986<p>The <var>color</var> argument is defined using the format
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7987described under the <a href="command-line-options.html#fill">-fill</a> option. The <a href="command-line-options.html#fuzz">-fuzz</a> setting can be used to match and replace colors similar to the one
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7988given. </p>
7989
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7990<p>Use <a href="command-line-options.html#transparent">+transparent</a> to invert the pixels matched.
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7991that is make all non-matching colors transparent. </p>
7992
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7993<p>The <a href="command-line-options.html#opaque">-opaque</a> operator is exactly the same as <a href="command-line-options.html#transparent">-transparent</a> but replaces the matching color with the
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7994current <a href="command-line-options.html#fill">-fill</a> color setting, rather than transparent.
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7995However the <a href="command-line-options.html#transparent">-transparent</a> operator also ensures
7996that the image has an alpha channel enabled, as per "<code><a href="command-line-options.html#alpha">-alpha</a> set</code>", and does not require you to modify the <a href="command-line-options.html#channel">-channel</a> to enable alpha channel handling. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]7997
7998<p>Note that this does not define the color as being the 'transparency color'
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]7999used for color-mapped image formats, such as GIF. For that use <a href="command-line-options.html#transparent-color">-transparent-color</a> </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8000
8001
8002<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8003 <h3 class="magick-header"><a id="transparent-color"></a>-transparent-color <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8004</div>
8005
8006<p class="magick-description">Set the transparent color.</p>
8007
8008<p>Sometimes this is used for saving to image formats such as
8009GIF and PNG8 which uses this color to represent boolean transparency. This
8010does not make a color transparent, it only defines what color the transparent
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8011color is in the color palette of the saved image. Use <a href="command-line-options.html#transparent">-transparent</a> to make an opaque color transparent.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8012
8013<p>This option allows you to have both an opaque visible color, as well as a
8014transparent color of the same color value without conflict. That is, you can
8015use the same color for both the transparent and opaque color areas within an
8016image. This, in turn, frees to you to select a transparent color that is
8017appropriate when an image is displayed by an application that does not handle a
8018transparent color index, while allowing ImageMagick to correctly handle images of this
8019type. </p>
8020
8021<p>The default transparent color is <code>#00000000</code>, which is fully transparent black.</p>
8022
8023<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8024 <h3 class="magick-header"><a id="transpose"></a>-transpose</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8025</div>
8026
8027<p class="magick-description">Mirror the image along the top-left to bottom-right diagonal.</p>
8028
8029<p> This option mathematically transposes the pixel array. It is equivalent to the sequence <code>-flip -rotate 90</code>.
8030</p>
8031
8032<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8033 <h3 class="magick-header"><a id="transverse"></a>-transverse</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8034</div>
8035
8036<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>
8037
8038
8039<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8040 <h3 class="magick-header"><a id="treedepth"></a>-treedepth <var>value</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8041</div>
8042
8043<p class="magick-description">tree depth for the color reduction algorithm.</p>
8044
8045<p>Normally, this integer value is zero or one. A value of zero or one causes
8046the use of an optimal tree depth for the color reduction algorithm.</p>
8047
8048<p>An optimal depth generally allows the best representation of the source
8049image with the fastest computational speed and the least amount of memory.
8050However, the default depth is inappropriate for some images. To assure the
8051best representation, try values between 2 and 8 for this parameter. Refer to
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8052the <a href="quantize.html">color reduction algorithm</a> for more details.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8053
8054<p>The <a href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#monochrome">-monochrome</a>
8055option, or writing to an image format which requires color reduction, is
8056required for this option to take effect.</p>
8057
8058<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8059 <h3 class="magick-header"><a id="trim"></a>-trim</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8060</div>
8061
8062<p class="magick-description">trim an image.</p>
8063
8064<p>This option removes any edges that are exactly the same color as the corner
8065pixels. Use <a href="command-line-options.html#fuzz">-fuzz</a> to make <a href="command-line-options.html#trim">-trim</a> remove
8066edges that are nearly the same color as the corner pixels.</p>
8067
8068<p>The page or virtual canvas information of the image is preserved allowing
8069you to extract the result of the <a href="command-line-options.html#trim">-trim</a> operation from the
8070image. Use a <a href="command-line-options.html#repage">+repage</a> to remove the virtual canvas page
8071information if it is unwanted.</p>
8072
8073<p>If the trimmed image 'disappears' an warning is produced, and a special
8074single pixel transparent 'missed' image is returned, in the same way as when a
8075<a href="command-line-options.html#crop">-crop</a> operation 'misses' the image proper. </p>
8076
8077
8078<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8079 <h3 class="magick-header"><a id="type"></a>-type <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8080</div>
8081
8082<p class="magick-description">the image type.</p> <p>Choose from: <code>Bilevel</code>,
8083<code>Grayscale</code>, <code>GrayscaleMatte</code>, <code>Palette</code>,
8084<code>PaletteMatte</code>, <code>TrueColor</code>, <code>TrueColorMatte</code>,
8085<code>ColorSeparation</code>, or <code>ColorSeparationMatte</code>.</p>
8086
8087<p>Normally, when a format supports different subformats such as grayscale and
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8088truecolor, the encoder will try to choose an efficient subformat. The <a href="command-line-options.html#type">-type</a> option can be used to override this behavior. For
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8089example, to prevent a JPEG from being written in grayscale format even though
8090only gray pixels are present, use.</p>
8091
8092<pre>
8093convert bird.png -type TrueColor bird.jpg
8094</pre>
8095
8096<p>Similarly, use <a href="command-line-options.html#type">-type TrueColorMatte</a> to force the
8097encoder to write an alpha channel even though the image is opaque, if the
8098output format supports transparency.</p>
8099
8100<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>
8101
8102<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8103 <h3 class="magick-header"><a id="undercolor"></a>-undercolor <var>color</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8104</div>
8105
8106<p class="magick-description">set the color of the annotation bounding box.</p>
8107
8108<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
8109
8110<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p>
8111
8112
8113<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8114 <h3 class="magick-header"><a id="update"></a>-update <var>seconds</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8115</div>
8116
8117<p class="magick-description">detect when image file is modified and redisplay.</p>
8118
8119<p>Suppose that while you are displaying an image the file that is currently
8120displayed is over-written. <code>display</code> will automagically detect that
8121the input file has been changed and update the displayed image
8122accordingly.</p>
8123
8124
8125<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8126 <h3 class="magick-header"><a id="unique-colors"></a>-unique-colors</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8127</div>
8128
8129<p class="magick-description">discard all but one of any pixel color.</p>
8130
8131
8132<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8133 <h3 class="magick-header"><a id="units"></a>-units <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8134</div>
8135
8136<p class="magick-description">the units of image resolution.</p>
8137
8138<p>Choose from: <code>Undefined</code>, <code>PixelsPerInch</code>, or
8139<code>PixelsPerCentimeter</code>. This option is normally used in conjunction
8140with the <a href="command-line-options.html#density">-density</a> option.</p>
8141
8142
8143<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8144 <h3 class="magick-header"><a id="unsharp"></a>-unsharp <var>radius</var><br>-unsharp <var>radius</var>x<var>sigma</var>{<var>+gain</var>}{<var>+threshold</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8145</div>
8146
8147<p class="magick-description">sharpen the image with an unsharp mask operator.</p>
8148
8149<p>The <a href="command-line-options.html#unsharp">-unsharp</a> option sharpens an image. The image is
8150convolved with a Gaussian operator of the given radius and standard deviation
8151(sigma). For reasonable results, radius should be larger than sigma. Use
8152a radius of 0 to have the method select a suitable radius.</p>
8153
8154<p>The parameters are:</p>
8155
8156<pre>
8157 radius The radius of the Gaussian, in pixels, not counting the center
8158 pixel (default 0).
8159 sigma The standard deviation of the Gaussian, in pixels (default 1.0).
8160 gain The fraction of the difference between the original and the blur
8161 image that is added back into the original (default 1.0).
8162 threshold The threshold, as a fraction of <var>QuantumRange</var>, needed to apply the
8163 difference amount (default 0.05).
8164</pre>
8165
8166
8167<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8168 <h3 class="magick-header"><a id="verbose"></a>-verbose</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8169</div>
8170
8171<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>
8172
8173
8174<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8175 <h3 class="magick-header"><a id="version"></a>-version</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8176</div>
8177
8178<p class="magick-description">print ImageMagick version string and exit.</p>
8179
8180
8181<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8182 <h3 class="magick-header"><a id="view"></a>-view <var>string</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8183</div>
8184
8185<p class="magick-description">FlashPix viewing parameters.</p>
8186
8187
8188<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8189 <h3 class="magick-header"><a id="vignette"></a>-vignette <var>radius</var>{x<var>sigma</var>}{<var>+-</var>}<var>x</var>{<var>+-</var>}<var>y</var>{<var>%</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8190</div>
8191
8192<p class="magick-description">soften the edges of the image in vignette style.</p>
8193
8194<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>
8195
8196<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8197 <h3 class="magick-header"><a id="virtual-pixel"></a>-virtual-pixel <var>method</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8198</div>
8199
8200<p class="magick-description">Specify contents of <var>virtual pixels</var>.</p>
8201
8202<p>This option defines what color source should be used if and when a color
8203lookup completely 'misses' the source image. The color(s) that appear to
8204surround the source image. Generally this color is derived from the source
8205image, but could also be set to a specify background color. </p>
8206
8207<p>Choose from these methods:</p>
8208
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8209<dl class="dl-horizontal">
8210<dt>background</dt><dd>the area surrounding the image is the background color</dd>
8211<dt>black</dt><dd>the area surrounding the image is black</dd>
8212<dt>checker-tile</dt><dd>alternate squares with image and background color</dd>
8213<dt>dither</dt><dd>non-random 32x32 dithered pattern</dd>
8214<dt>edge</dt><dd>extend the edge pixel toward infinity</dd>
8215<dt>gray</dt><dd>the area surrounding the image is gray</dd>
8216<dt>horizontal-tile</dt><dd>horizontally tile the image, background color above/below</dd>
8217<dt>horizontal-tile-edge</dt><dd>horizontally tile the image and replicate the side edge pixels</dd>
8218<dt>mirror</dt><dd>mirror tile the image</dd>
8219<dt>random</dt><dd>choose a random pixel from the image</dd>
8220<dt>tile</dt><dd>tile the image (default)</dd>
8221<dt>transparent</dt><dd>the area surrounding the image is transparent blackness</dd>
8222<dt>vertical-tile</dt><dd>vertically tile the image, sides are background color</dd>
8223<dt>vertical-tile-edge</dt><dd>vertically tile the image and replicate the side edge pixels</dd>
8224<dt>white</dt><dd>the area surrounding the image is white</dd>
8225</dl>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8226
8227<p>The default value is "edge".</p>
8228
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8229<p>This most important for distortion operators such as <a href="command-line-options.html#distort">-distort</a>, <a href="command-line-options.html#implode">-implode</a>, and <a href="command-line-options.html#fx">-fx</a>.
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8230However it also effects operations that may access pixels just outside the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8231image proper, such as <a href="command-line-options.html#convolve">-convolve</a>, <a href="command-line-options.html#blur">-blur</a>, and <a href="command-line-options.html#sharpen">-sharpen</a>. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8232
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8233<p>To print a complete list of virtual pixel types, use the <a href="command-line-options.html#list">-list virtual-pixel</a> option.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8234
8235
8236<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8237 <h3 class="magick-header"><a id="visual"></a>-visual <var>type</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8238</div>
8239
8240<p class="magick-description">Animate images using this X visual type.", 'animate', 'display'</p>
8241
8242<p>Choose from these visual classes:</p>
8243
8244<pre>
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8245StaticGray
8246GrayScale
8247StaticColor
8248PseudoColor
8249TrueColor
8250DirectColor
8251default
8252visual id
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8253</pre>
8254
8255<p>The X server must support the visual you choose, otherwise an error occurs.
8256If a visual is not specified, the visual class that can display the most
8257simultaneous colors on the default screen is chosen.</p>
8258
8259
8260<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8261 <h3 class="magick-header"><a id="watermark"></a>-watermark <var>brightness</var>x<var>saturation</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8262</div>
8263
8264<p class="magick-description">Watermark an image using the given percentages of brightness and saturation.</p>
8265
8266<p>Take a grayscale image (with alpha mask) and modify the destination image's
8267brightness according to watermark image's grayscale value and the
8268<var>brightness</var> percentage. The destinations color saturation
8269attribute is just direct modified by the <var>saturation</var>
8270percentage, which defaults to 100 percent (no color change). </p>
8271
8272
8273<div style="margin: auto;">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8274 <h3 class="magick-header"><a id="wave"></a>-wave <var>amplitude</var><br>-wave <var>amplitude</var>x<var>wavelength</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8275</div>
8276
8277<p class="magick-description">Shear the columns of an image into a sine wave.</p>
8278
8279<p>Specify <var>amplitude</var> and <var>wavelength</var>
8280of the wave.</p>
8281
8282<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8283 <h3 class="magick-header"><a id="weight"></a>-weight <var>fontWeight</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8284</div>
8285
8286<p class="magick-description">Set a font weight for text.</p>
8287
8288<p>This setting suggests a font weight that ImageMagick should try to apply to
8289the currently selected font family. Use a positive integer for
8290<var>fontWeight</var> or select from the following.</p>
8291
8292<table class="table table-condensed table-striped">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8293 <col width="25%">
8294 <col width="75%">
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8295 <thead>
8296 <tr>
8297 <th><var>fontWeight</var></th>
8298 <th>Description</th>
8299 </tr>
8300 </thead>
8301 <tbody>
8302 <tr><td>All </td>
8303 <td>No effect. </td></tr>
8304 <tr><td>Bold </td>
8305 <td>Same as <var>fontWeight</var> = 700.</td></tr>
8306 <tr><td>Bolder </td>
8307 <td>Add 100 to font weight if currently ≤ 800.</td></tr>
8308 <tr><td>Lighter </td>
8309 <td>Subtract 100 to font weight if currently ≤ 100.</td></tr>
8310 <tr><td>Normal </td>
8311 <td>Same as <var>fontWeight</var> = 400.</td></tr>
8312 </tbody>
8313 </table>
8314
8315<p>To print a complete list of weight types, use <a href="command-line-options.html#list">-list
8316weight</a>.</p>
8317
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8318<p>For other settings that affect fonts, see the options <a href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a href="command-line-options.html#stretch">-stretch</a>, and <a href="command-line-options.html#style">-style</a>. </p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8319
8320<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8321 <h3 class="magick-header"><a id="white-point"></a>-white-point <var>x,y</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8322</div>
8323
8324<p class="magick-description">chromaticity white point.</p>
8325
8326<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8327 <h3 class="magick-header"><a id="white-threshold"></a>-white-threshold <var>value</var>{<var>%</var>}</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8328</div>
8329
8330<p class="magick-description">Force to white all pixels above the threshold while leaving all pixels at or below the threshold unchanged.</p>
8331
8332<p> The threshold value can be given as a percentage or as an absolute integer
8333value within [0, <var>QuantumRange</var>] corresponding to the
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8334desired <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>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8335
8336<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8337 <h3 class="magick-header"><a id="window"></a>-window <var>id</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8338</div>
8339
8340<p class="magick-description">Make the image the background of a window.", 'animate', 'display'</p>
8341
8342<p><var>id</var> can be a window id or name. Specify <code>root</code>
8343to select X's root window as the target window.</p>
8344
8345<p>By default the image is tiled onto the background of the target window. If
8346<code>backdrop</code> or <a href="command-line-options.html#geometry">-resize</a> are specified, the
8347image is surrounded by the background color. Refer to <code>X RESOURCES</code>
8348for details.</p>
8349
8350<p>The image will not display on the root window if the image has more unique
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8351colors than the target window colormap allows. Use <a href="command-line-options.html#colors">-colors</a> to reduce the number of colors.</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8352
8353<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8354 <h3 class="magick-header"><a id="window-group"></a>-window-group</h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8355</div>
8356
8357<p class="magick-description">specify the window group.</p>
8358
8359<div style="margin: auto;">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8360 <h3 class="magick-header"><a id="write"></a>-write <var>filename</var></h3>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8361</div>
8362
8363<p class="magick-description">write an image sequence.</p>
8364
8365<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>
8366
8367<p>Use <a href="command-line-options.html#compress">-compress</a> to specify the type of image compression.</p>
8368</div>
8369</div>
8370 <footer class="magick-footer">
cristy82a2ff22015-05-12 16:41:32 +0000[diff] [blame^]8371 <div class="magick-nav-item pull-left">
cristy85893d32015-05-06 13:44:09 +0000[diff] [blame]8372 <a href="support.html">Donate</a>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8373 </div>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8374 <p><a href="sitemap.html">Sitemap</a> •
8375 <a href="links.html">Related</a> •
8376 <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Image Studio</a> •
8377 <a href="http://jqmagick.imagemagick.org/">JqMagick</a> •
8378 <a href="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a>
8379</p>
8380 <p><a href="command-line-options.html#">Back to top</a> •
cristy85893d32015-05-06 13:44:09 +0000[diff] [blame]8381 <a href="http://www.imagemagick.org/script/contact.php">Contact Us</a></p>
cristy2f563d42015-05-06 23:36:51 +0000[diff] [blame]8382 <p class="small">© 1999-2015 ImageMagick Studio LLC</p>
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8383 </footer>
8384</div><!-- /.container -->
8385
8386 <script src="https://localhost/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
8387 <script src="../js/bootstrap.min.js"></script>
8388 <script type="text/javascript">
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8389 /* <![CDATA[ */
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8390 (function() {
8391 var s = document.createElement('offline-script'), t = document.getElementsByTagName('offline-script')[0];
8392 s.type = 'text/javascript';
8393 s.async = true;
8394 s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
8395 t.parentNode.insertBefore(s, t);
8396 })();
cristy29dc8652015-05-12 16:26:21 +0000[diff] [blame]8397 /* ]]> */
cristyd2432012015-05-04 23:15:15 +0000[diff] [blame]8398 </script>
8399</div>
cristyad41c0c2012-10-31 00:49:28 +0000[diff] [blame]8400</body>
cristy5a367e42015-05-05 12:39:18 +0000[diff] [blame]8401</html>