Blame - www/command-line-options.html - platform/external/ImageMagick

blob: 739fe148adb1b61298e81ed753031a7285798758 [file] [log] [blame]

cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	1
				2
				3
				4
				5	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
				6	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
				7	<html version="-//W3C//DTD XHTML 1.1//EN"
				8	xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
				9	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
				10	xsi:schemaLocation="http://www.w3.org/1999/xhtml
				11	http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd">
				12	<head>
				13	<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	14	<meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4"/>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	15	<title>ImageMagick: Command-line Options</title>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	16	<meta http-equiv="content-language" content="en-US"/>
				17	<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
				18	<meta http-equiv="reply-to" content="magick-users@imagemagick.org"/>
				19	<meta name="application-name" content="ImageMagick"/>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	20	<meta name="description" content="Use ImageMagick to convert, edit, or compose bitmap images in a variety of formats. In addition, resize, rotate, shear, distort or transform images automagically."/>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	21	<meta name="application-url" content="http://www.imagemagick.org"/>
				22	<meta name="generator" content="PHP"/>
				23	<meta name="keywords" content="command-line, options, ImageMagick, PerlMagick, image processing, OpenMP, software development library, image, photo, software, Magick++, MagickWand"/>
				24	<meta name="rating" content="GENERAL"/>
				25	<meta name="robots" content="INDEX, FOLLOW"/>
				26	<meta name="generator" content="ImageMagick Studio LLC"/>
				27	<meta name="author" content="ImageMagick Studio LLC"/>
				28	<meta name="revisit-after" content="2 DAYS"/>
				29	<meta name="resource-type" content="document"/>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	30	<meta name="copyright" content="Copyright (c) 1999-2012 ImageMagick Studio LLC"/>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	31	<meta name="distribution" content="Global"/>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	32	<link rel="icon" href="../images/wand.png"/>
cristy	3c98a4f	2010-08-13 20:09:41 +0000	[diff] [blame]	33	<link rel="shortcut icon" href="../images/wand.ico" type="images/x-icon"/>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	34	<link rel="canonical" href="http://www.imagemagick.org" />
				35	<link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	36
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	37	<!-- Add jQuery library -->
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	38	<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.min.js"></script>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	39
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	40	<!-- Add mousewheel plugin (this is optional) -->
				41	<script type="text/javascript" src="http://www.imagemagick.org/fancybox/lib/jquery.mousewheel-3.0.6.pack.js"></script>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	42
				43	<!-- Add fancyBox -->
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	44	<link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/jquery.fancybox.css?v=2.0.6" type="text/css" media="screen" />
				45	<script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/jquery.fancybox.pack.js?v=2.0.6"></script>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	46
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	47	<!-- Optionally add helpers - button, thumbnail and/or media -->
				48	<link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-buttons.css?v=1.0.2" type="text/css" media="screen" />
				49	<script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-buttons.js?v=1.0.2"></script>
				50	<script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-media.js?v=1.0.0"></script>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	51
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	52	<link rel="stylesheet" href="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-thumbs.css?v=2.0.6" type="text/css" media="screen" />
				53	<script type="text/javascript" src="http://www.imagemagick.org/fancybox/source/helpers/jquery.fancybox-thumbs.js?v=2.0.6"></script>
				54
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	55	<script type="text/javascript">
				56	$(document).ready(function() {
				57	$(".fancybox").fancybox();
				58	});
				59	</script>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	60
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	61	<!-- ImageMagick style -->
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	62	<style type="text/css" media="all">
				63	@import url("../www/magick.css");
				64	</style>
				65	</head>
				66
				67	<body id="www-imagemagick-org">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	68
				69	<script>
				70	(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]\|\|function(){
				71	(i[r].q=i[r].q\|\|[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
				72	m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
				73	})(window,document,'offline-script','//127.0.0.1/analytics.js','ga');
				74
				75	ga('create', 'UA-40133312-1', 'imagemagick.org');
				76	ga('send', 'pageview');
				77	</script>
				78
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	79	<div class="titlebar">
				80	<div style="margin: 17px auto; float: left;">
				81	<script type="text/javascript">
				82	<!--
				83	google_ad_client = "pub-3129977114552745";
				84	google_ad_slot = "5439289906";
				85	google_ad_width = 728;
				86	google_ad_height = 90;
				87	//-->
				88	</script>
				89	<script type="text/javascript"
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	90	src="http://127.0.0.1/pagead/show_ads.js">
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	91	</script>
				92	</div>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	93	<a href="http://www.imagemagick.org/discourse-server/">
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	94	<img src="../images/logo.jpg"
				95	alt="ImageMagick Logo"
				96	style="width: 123px; height: 118px; border: 0px; float: right;" /></a>
				97	<a href="../index.html">
				98	<img src="../images/sprite.jpg"
				99	alt="ImageMagick Sprite"
				100	style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
				101	</div>
				102
				103	<div class="westbar">
				104
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	105	<div class="menu">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	106	<a title="About ImageMagick" href="../index.html">About ImageMagick</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	107	</div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	108	<div class="menu">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	109	<a title="Binary Releases" href="binary-releases.html">Binary Releases</a>
cristy	bb50337	2010-05-27 20:51:26 +0000	[diff] [blame]	110	</div>
				111	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	112	<a title="Binary Release: Unix" href="binary-releases.html#unix">Unix</a>
cristy	bb50337	2010-05-27 20:51:26 +0000	[diff] [blame]	113	</div>
				114	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	115	<a title="Binary Release: MacOS X" href="binary-releases.html#macosx">Mac OS X</a>
cristy	bb50337	2010-05-27 20:51:26 +0000	[diff] [blame]	116	</div>
				117	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	118	<a title="Binary Release: iOS" href="binary-releases.html#iOS">iOS</a>
cristy	da16f16	2011-02-19 23:52:17 +0000	[diff] [blame]	119	</div>
				120	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	121	<a title="Binary Release: Windows" href="binary-releases.html#windows">Windows</a>
cristy	bb50337	2010-05-27 20:51:26 +0000	[diff] [blame]	122	</div>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	123	<div class="sep"></div>
cristy	bb50337	2010-05-27 20:51:26 +0000	[diff] [blame]	124	<div class="menu">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	125	<a title="Command-line Tools" href="command-line-tools.html">Command-line Tools</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	126	</div>
				127	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	128	<a title="Command-line Tools: Processing" href="command-line-processing.html">Processing</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	129	</div>
				130	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	131	<a title="Command-line Tools: Options" href="command-line-options.html">Options</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	132	</div>
				133	<div class="sub">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	134	<a title="Command-line Tools: Usage" href="http://www.imagemagick.org/Usage/">Usage</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	135	</div>
				136	<div class="menu">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	137	<a title="Program Interfaces" href="api.html">Program Interfaces</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	138	</div>
				139	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	140	<a title="Program Interface: MagickWand" href="magick-wand.html">MagickWand</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	141	</div>
				142	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	143	<a title="Program Interface: MagickCore" href="magick-core.html">MagickCore</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	144	</div>
				145	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	146	<a title="Program Interface: PerlMagick" href="perl-magick.html">PerlMagick</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	147	</div>
				148	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	149	<a title="Program Interface: Magick++" href="magick++.html">Magick++</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	150	</div>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	151	<div class="sep"></div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	152	<div class="menu">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	153	<a title="Install from Source" href="install-source.html">Install from Source</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	154	</div>
				155	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	156	<a title="Install from Source: Unix" href="install-source.html#unix">Unix</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	157	</div>
				158	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	159	<a title="Install from Source: Windows" href="install-source.html#windows">Windows</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	160	</div>
				161	<div class="menu">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	162	<a title="Resources" href="resources.html">Resources</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	163	</div>
cristy	bb50337	2010-05-27 20:51:26 +0000	[diff] [blame]	164	<div class="menu">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	165	<a title="Architecture" href="architecture.html">Architecture</a>
cristy	bb50337	2010-05-27 20:51:26 +0000	[diff] [blame]	166	</div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	167	<div class="menu">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	168	<a title="Download" href="download.html">Download</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	169	</div>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	170	<div class="sep"></div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	171	<div class="menu">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	172	<a title="Search" href="search.html">Search</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	173	</div>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	174	<div class="sep"></div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	175	<div class="menu">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	176	<a title="Site Map" href="sitemap.html">Site Map</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	177	</div>
				178	<div class="sub">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	179	<a title="Site Map: Links" href="links.html">Links</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	180	</div>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	181	<div class="sep"></div>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	182	<div class="menu">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	183	<a title="Support ImageMagick Development" href="support.html">Support ImageMagick Development</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	184	</div>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	185	</div>
				186
				187	<div class="eastbar">
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	188	<script type="text/javascript">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	189	/* <![CDATA[ */
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	190	(function() {
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	191	var po = document.createElement('offline-script'), t = document.getElementsByTagName('offline-script')[0];
				192	po.type = 'text/javascript';
				193	po.async = true;
				194	po.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
				195	var script = document.getElementsByTagName('offline-script')[0];
				196	script.parentNode.insertBefore(po, script);
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	197	})();
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	198	/* ]]> */
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	199	</script>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	200	<div> <a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="http://www.imagemagick.org/"></a></div>
				201	<noscript>
				202	<a href="http://flattr.com/thing/947300/Convert-Edit-And-Compose-Images" target="_blank">
				203	<img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" width="93" height="20" border="0" /></a>
				204	</noscript>
				205	<div class="g-plusone" id="gplusone"></div>
				206	<script type="text/javascript">
				207	/* <![CDATA[ */
				208	window.___gcfg = {
				209	lang: 'en-US'
				210	};
				211
				212	(function() {
				213	var po = document.createElement('offline-script');
				214	po.type = 'text/javascript';
				215	po.async = true;
				216	po.src = 'https://127.0.0.1/js/plusone.js';
				217	var script = document.getElementsByTagName('offline-script')[0];
				218	script.parentNode.insertBefore(po, script);
				219	})();
				220	var gplusone = document.getElementById("gplusone");
				221	gplusone.setAttribute("data-size","medium");
				222	gplusone.setAttribute("data-count","true");
				223	/* ]]> */
				224	</script>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	225	</div>
				226
				227	<div class="main">
				228
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	229	<h1>Command-line Options</h1>
cristy	5cadd61	2009-09-21 19:33:41 +0000	[diff] [blame]	230	<p class="navigation-index">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	231	[ <a href="command-line-options.html#adaptive-blur">‑adaptive‑blur</a> <span class='bull'> • </span> <a href="command-line-options.html#adaptive-resize">‑adaptive‑resize</a> <span class='bull'> • </span> <a href="command-line-options.html#adaptive-sharpen">‑adaptive‑sharpen</a> <span class='bull'> • </span> <a href="command-line-options.html#adjoin">‑adjoin</a> <span class='bull'> • </span> <a href="command-line-options.html#affine">‑affine</a> <span class='bull'> • </span> <a href="command-line-options.html#alpha">‑alpha</a> <span class='bull'> • </span> <a href="command-line-options.html#annotate">‑annotate</a> <span class='bull'> • </span> <a href="command-line-options.html#antialias">‑antialias</a> <span class='bull'> • </span> <a href="command-line-options.html#append">‑append</a> <span class='bull'> • </span> <a href="command-line-options.html#attenuate">‑attenuate</a> <span class='bull'> • </span> <a href="command-line-options.html#authenticate">‑authenticate</a> <span class='bull'> • </span> <a href="command-line-options.html#auto-gamma">‑auto‑gamma</a> <span class='bull'> • </span> <a href="command-line-options.html#auto-level">‑auto‑level</a> <span class='bull'> • </span> <a href="command-line-options.html#auto-orient">‑auto‑orient</a> <span class='bull'> • </span> <a href="command-line-options.html#backdrop">‑backdrop</a> <span class='bull'> • </span> <a href="command-line-options.html#background">‑background</a> <span class='bull'> • </span> <a href="command-line-options.html#bench">‑bench</a> <span class='bull'> • </span> <a href="command-line-options.html#bias">‑bias</a> <span class='bull'> • </span> <a href="command-line-options.html#black-point-compensation">‑black‑point‑compensation</a> <span class='bull'> • </span> <a href="command-line-options.html#black-threshold">‑black‑threshold</a> <span class='bull'> • </span> <a href="command-line-options.html#blend">‑blend</a> <span class='bull'> • </span> <a href="command-line-options.html#blue-primary">‑blue‑primary</a> <span class='bull'> • </span> <a href="command-line-options.html#blue-shift">‑blue‑shift</a> <span class='bull'> • </span> <a href="command-line-options.html#blur">‑blur</a> <span class='bull'> • </span> <a href="command-line-options.html#border">‑border</a> <span class='bull'> • </span> <a href="command-line-options.html#bordercolor">‑bordercolor</a> <span class='bull'> • </span> <a href="command-line-options.html#borderwidth">‑borderwidth</a> <span class='bull'> • </span> <a href="command-line-options.html#brightness-contrast">‑brightness‑contrast</a> <span class='bull'> • </span> <a href="command-line-options.html#cache">‑cache</a> <span class='bull'> • </span> <a href="command-line-options.html#caption">‑caption</a> <span class='bull'> • </span> <a href="command-line-options.html#cdl">‑cdl</a> <span class='bull'> • </span> <a href="command-line-options.html#channel">‑channel</a> <span class='bull'> • </span> <a href="command-line-options.html#charcoal">‑charcoal</a> <span class='bull'> • </span> <a href="command-line-options.html#chop">‑chop</a> <span class='bull'> • </span> <a href="command-line-options.html#clamp">‑clamp</a> <span class='bull'> • </span> <a href="command-line-options.html#clip">‑clip</a> <span class='bull'> • </span> <a href="command-line-options.html#clip-mask">‑clip‑mask</a> <span class='bull'> • </span> <a href="command-line-options.html#clip-path">‑clip‑path</a> <span class='bull'> • </span> <a href="command-line-options.html#clone">‑clone</a> <span class='bull'> • </span> <a href="command-line-options.html#clut">‑clut</a> <span class='bull'> • </span> <a href="command-line-options.html#coalesce">‑coalesce</a> <span class='bull'> • </span> <a href="command-line-options.html#colorize">‑colorize</a> <span class='bull'> • </span> <a href="command-line-options.html#colormap">‑colormap</a> <span class='bull'> • </span> <a href="command-line-options.html#color-matrix">‑color‑matrix</a> <span class='bull'> • </span> <a href="command-line-options.html#colors">‑colors</a> <span class='bull'> • </span> <a href="command-line-options.html#colorspace">‑colorspace</a> <span class='bull'> • </span> <a href="command-line-options.html#combine">‑combine</a> <span class='bull'> • </span> <a href="command-line-options.html#comment">‑comment</a> <span class='bull'> • </span> <a href="command-line-options.html#compose">‑compose</a> <span class='bull'> • </span> <a href="command-line-options.html#composite">‑composite</a> <span class='bull'> • </span> <a href="command-line-options.html#compress">‑compress</a> <span class='bull'> • </span> <a href="command-line-options.html#contrast">‑contrast</a> <span class='bull'> • </span> <a href="command-line-options.html#contrast-stretch">‑contrast‑stretch</a> <span class='bull'> • </span> <a href="command-line-options.html#convolve">‑convolve</a> <span class='bull'> • </span> <a href="command-line-options.html#crop">‑crop</a> <span class='bull'> • </span> <a href="command-line-options.html#cycle">‑cycle</a> <span class='bull'> • </span> <a href="command-line-options.html#debug">‑debug</a> <span class='bull'> • </span> <a href="command-line-options.html#decipher">‑decipher</a> <span class='bull'> • </span> <a href="command-line-options.html#deconstruct">‑deconstruct</a> <span class='bull'> • </span> <a href="command-line-options.html#define">‑define</a> <span class='bull'> • </span> <a href="command-line-options.html#delay">‑delay</a> <span class='bull'> • </span> <a href="command-line-options.html#delete">‑delete</a> <span class='bull'> • </span> <a href="command-line-options.html#density">‑density</a> <span class='bull'> • </span> <a href="command-line-options.html#depth">‑depth</a> <span class='bull'> • </span> <a href="command-line-options.html#descend">‑descend</a> <span class='bull'> • </span> <a href="command-line-options.html#deskew">‑deskew</a> <span class='bull'> • </span> <a href="command-line-options.html#despeckle">‑despeckle</a> <span class='bull'> • </span> <a href="command-line-options.html#direction">‑direction</a> <span class='bull'> • </span> <a href="command-line-options.html#displace">‑displace</a> <span class='bull'> • </span> <a href="command-line-options.html#display">‑display</a> <span class='bull'> • </span> <a href="command-line-options.html#dispose">‑dispose</a> <span class='bull'> • </span> <a href="command-line-options.html#dissimilarity-threshold">‑dissimilarity‑threshold</a> <span class='bull'> • </span> <a href="command-line-options.html#dissolve">‑dissolve</a> <span class='bull'> • </span> <a href="command-line-options.html#distort">‑distort</a> <span class='bull'> • </span> <a href="command-line-options.html#distribute-cache">‑distribute‑cache</a> <span class='bull'> • </span> <a href="command-line-options.html#dither">‑dither</a> <span class='bull'> • </span> <a href="command-line-options.html#draw">‑draw</a> <span class='bull'> • </span> <a href="command-line-options.html#duplicate">‑duplicate</a> <span class='bull'> • </span> <a href="command-line-options.html#edge">‑edge</a> <span class='bull'> • </span> <a href="command-line-options.html#emboss">‑emboss</a> <span class='bull'> • </span> <a href="command-line-options.html#encipher">‑encipher</a> <span class='bull'> • </span> <a href="command-line-options.html#encoding">‑encoding</a> <span class='bull'> • </span> <a href="command-line-options.html#endian">‑endian</a> <span class='bull'> • </span> <a href="command-line-options.html#enhance">‑enhance</a> <span class='bull'> • </span> <a href="command-line-options.html#equalize">‑equalize</a> <span class='bull'> • </span> <a href="command-line-options.html#evaluate">‑evaluate</a> <span class='bull'> • </span> <a href="command-line-options.html#evaluate-sequence">‑evaluate‑sequence</a> <span class='bull'> • </span> <a href="command-line-options.html#extent">‑extent</a> <span class='bull'> • </span> <a href="command-line-options.html#extract">‑extract</a> <span class='bull'> • </span> <a href="command-line-options.html#family">‑family</a> <span class='bull'> • </span> <a href="command-line-options.html#features">‑features</a> <span class='bull'> • </span> <a href="command-line-options.html#fft">‑fft</a> <span class='bull'> • </span> <a href="command-line-options.html#fill">‑fill</a> <span class='bull'> • </span> <a href="command-line-options.html#filter">‑filter</a> <span class='bull'> • </span> <a href="command-line-options.html#flatten">‑flatten</a> <span class='bull'> • </span> <a href="command-line-options.html#flip">‑flip</a> <span class='bull'> • </span> <a href="command-line-options.html#floodfill">‑floodfill</a> <span class='bull'> • </span> <a href="command-line-options.html#flop">‑flop</a> <span class='bull'> • </span> <a href="command-line-options.html#font">‑font</a> <span class='bull'> • </span> <a href="command-line-options.html#foreground">‑foreground</a> <span class='bull'> • </span> <a href="command-line-options.html#format">‑format</a> <span class='bull'> • </span> <a href="command-line-options.html#format_identify_">‑format[identify]</a> <span class='bull'> • </span> <a href="command-line-options.html#frame">‑frame</a> <span class='bull'> • </span> <a href="command-line-options.html#frame_import_">‑frame[import]</a> <span class='bull'> • </span> <a href="command-line-options.html#function">‑function</a> <span class='bull'> • </span> <a href="command-line-options.html#fuzz">‑fuzz</a> <span class='bull'> • </span> <a href="command-line-options.html#fx">‑fx</a> <span class='bull'> • </span> <a href="command-line-options.html#gamma">‑gamma</a> <span class='bull'> • </span> <a href="command-line-options.html#gaussian-blur">‑gaussian‑blur</a> <span class='bull'> • </span> <a href="command-line-options.html#geometry">‑geometry</a> <span class='bull'> • </span> <a href="command-line-options.html#gravity">‑gravity</a> <span class='bull'> • </span> <a href="command-line-options.html#grayscale">‑grayscale</a> <span class='bull'> • </span> <a href="command-line-options.html#green-primary">‑green‑primary</a> <span class='bull'> • </span> <a href="command-line-options.html#hald-clut">‑hald‑clut</a> <span class='bull'> • </span> <a href="command-line-options.html#help">‑help</a> <span class='bull'> • </span> <a href="command-line-options.html#highlight-color">‑highlight‑color</a> <span class='bull'> • </span> <a href="command-line-options.html#iconGeometry">‑iconGeometry</a> <span class='bull'> • </span> <a href="command-line-options.html#iconic">‑iconic</a> <span class='bull'> • </span> <a href="command-line-options.html#identify">‑identify</a> <span class='bull'> • </span> <a href="command-line-options.html#ift">‑ift</a> <span class='bull'> • </span> <a href="command-line-options.html#immutable">‑immutable</a> <span class='bull'> • </span> <a href="command-line-options.html#implode">‑implode</a> <span class='bull'> • </span> <a href="command-line-options.html#insert">‑insert</a> <span class='bull'> • </span> <a href="command-line-options.html#intensity">‑intensity</a> <span class='bull'> • </span> <a href="command-line-options.html#intent">‑intent</a> <span class='bull'> • </span> <a href="command-line-options.html#interlace">‑interlace</a> <span class='bull'> • </span> <a href="command-line-options.html#interpolate">‑interpolate</a> <span class='bull'> • </span> <a href="command-line-options.html#interline-spacing">‑interline‑spacing</a> <span class='bull'> • </span> <a href="command-line-options.html#interword-spacing">‑interword‑spacing</a> <span class='bull'> • </span> <a href="command-line-options.html#kerning">‑kerning</a> <span class='bull'> • </span> <a href="command-line-options.html#label">‑label</a> <span class='bull'> • </span> <a href="command-line-options.html#lat">‑lat</a> <span class='bull'> • </span> <a href="command-line-options.html#layers">‑layers</a> <span class='bull'> • </span> <a href="command-line-options.html#level">‑level</a> <span class='bull'> • </span> <a href="command-line-options.html#level-colors">‑level‑colors</a> <span class='bull'> • </span> <a href="command-line-options.html#limit">‑limit</a> <span class='bull'> • </span> <a href="command-line-options.html#linear-stretch">‑linear‑stretch</a> <span class='bull'> • </span> <a href="command-line-options.html#linewidth">‑linewidth</a> <span class='bull'> • </span> <a href="command-line-options.html#liquid-rescale">‑liquid‑rescale</a> <span class='bull'> • </span> <a href="command-line-options.html#list">‑list</a> <span class='bull'> • </span> <a href="command-line-options.html#log">‑log</a> <span class='bull'> • </span> <a href="command-line-options.html#loop">‑loop</a> <span class='bull'> • </span> <a href="command-line-options.html#lowlight-color">‑lowlight‑color</a> <span class='bull'> • </span> <a href="command-line-options.html#magnify">‑magnify</a> <span class='bull'> • </span> <a href="command-line-options.html#map">‑map</a> <span class='bull'> • </span> <a href="command-line-options.html#map_stream_">‑map[stream]</a> <span class='bull'> • </span> <a href="command-line-options.html#mask">‑mask</a> <span class='bull'> • </span> <a href="command-line-options.html#mattecolor">‑mattecolor</a> <span class='bull'> • </span> <a href="command-line-options.html#median">‑median</a> <span class='bull'> • </span> <a href="command-line-options.html#metric">‑metric</a> <span class='bull'> • </span> <a href="command-line-options.html#mode">‑mode</a> <span class='bull'> • </span> <a href="command-line-options.html#modulate">‑modulate</a> <span class='bull'> • </span> <a href="command-line-options.html#monitor">‑monitor</a> <span class='bull'> • </span> <a href="command-line-options.html#monochrome">‑monochrome</a> <span class='bull'> • </span> <a href="command-line-options.html#morph">‑morph</a> <span class='bull'> • </span> <a href="command-line-options.html#morphology">‑morphology</a> <span class='bull'> • </span> <a href="command-line-options.html#mosaic">‑mosaic</a> <span class='bull'> • </span> <a href="command-line-options.html#motion-blur">‑motion‑blur</a> <span class='bull'> • </span> <a href="command-line-options.html#name">‑name</a> <span class='bull'> • </span> <a href="command-line-options.html#negate">‑negate</a> <span class='bull'> • </span> <a href="command-line-options.html#noise">‑noise</a> <span class='bull'> • </span> <a href="command-line-options.html#normalize">‑normalize</a> <span class='bull'> • </span> <a href="command-line-options.html#opaque">‑opaque</a> <span class='bull'> • </span> <a href="command-line-options.html#ordered-dither">‑ordered‑dither</a> <span class='bull'> • </span> <a href="command-line-options.html#orient">‑orient</a> <span class='bull'> • </span> <a href="command-line-options.html#page">‑page</a> <span class='bull'> • </span> <a href="command-line-options.html#paint">‑paint</a> <span class='bull'> • </span> <a href="command-line-options.html#path">‑path</a> <span class='bull'> • </span> <a href="command-line-options.html#pause_animate_">‑pause[animate]</a> <span class='bull'> • </span> <a href="command-line-options.html#pause_import_">‑pause[import]</a> <span class='bull'> • </span> <a href="command-line-options.html#pen">‑pen</a> <span class='bull'> • </span> <a href="command-line-options.html#perceptible">‑perceptible</a> <span class='bull'> • </span> <a href="command-line-options.html#ping">‑ping</a> <span class='bull'> • </span> <a href="command-line-options.html#pointsize">‑pointsize</a> <span class='bull'> • </span> <a href="command-line-options.html#polaroid">‑polaroid</a> <span class='bull'> • </span> <a href="command-line-options.html#poly">‑poly</a> <span class='bull'> • </span> <a href="command-line-options.html#posterize">‑posterize</a> <span class='bull'> • </span> <a href="command-line-options.html#precision">‑precision</a> <span class='bull'> • </span> <a href="command-line-options.html#preview">‑preview</a> <span class='bull'> • </span> <a href="command-line-options.html#print">‑print</a> <span class='bull'> • </span> <a href="command-line-options.html#process">‑process</a> <span class='bull'> • </span> <a href="command-line-options.html#profile">‑profile</a> <span class='bull'> • </span> <a href="command-line-options.html#quality">‑quality</a> <span class='bull'> • </span> <a href="command-line-options.html#quantize">‑quantize</a> <span class='bull'> • </span> <a href="command-line-options.html#quiet">‑quiet</a> <span class='bull'> • </span> <a href="command-line-options.html#radial-blur">‑radial‑blur</a> <span class='bull'> • </span> <a href="command-line-options.html#raise">‑raise</a> <span class='bull'> • </span> <a href="command-line-options.html#random-threshold">‑random‑threshold</a> <span class='bull'> • </span> <a href="command-line-options.html#red-primary">‑red‑primary</a> <span class='bull'> • </span> <a href="command-line-options.html#regard-warnings">‑regard‑warnings</a> <span class='bull'> • </span> <a href="command-line-options.html#region">‑region</a> <span class='bull'> • </span> <a href="command-line-options.html#remap">‑remap</a> <span class='bull'> • </span> <a href="command-line-options.html#remote">‑remote</a> <span class='bull'> • </span> <a href="command-line-options.html#render">‑render</a> <span class='bull'> • </span> <a href="command-line-options.html#repage">‑repage</a> <span class='bull'> • </span> <a href="command-line-options.html#resample">‑resample</a> <span class='bull'> • </span> <a href="command-line-options.html#resize">‑resize</a> <span class='bull'> • </span> <a href="command-line-options.html#respect-parentheses">‑respect‑parentheses</a> <span class='bull'> • </span> <a href="command-line-options.html#reverse">‑reverse</a> <span class='bull'> • </span> <a href="command-line-options.html#roll">‑roll</a> <span class='bull'> • </span> <a href="command-line-options.html#rotate">‑rotate</a> <span class='bull'> • </span> <a href="command-line-options.html#sample">‑sample</a> <span class='bull'> • </span> <a href="command-line-options.html#sampling-factor">‑sampling‑factor</a> <span class='bull'> • </span> <a href="command-line-options.html#scale">‑scale</a> <span class='bull'> • </span> <a href="command-line-options.html#scene">‑scene</a> <span class='bull'> • </span> <a href="command-line-options.html#screen">‑screen</a> <span class='bull'> • </span> <a href="command-line-options.html#seed">‑seed</a> <span class='bull'> • </span> <a href="command-line-options.html#segment">‑segment</a> <span class='bull'> • </span> <a href="command-line-options.html#selective-blur">‑selective‑blur</a> <span class='bull'> • </span> <a href="command-line-options.html#separate">‑separate</a> <span class='bull'> • </span> <a href="command-line-options.html#sepia-tone">‑sepia‑tone</a> <span class='bull'> • </span> <a href="command-line-options.html#set">‑set</a> <span class='bull'> • </span> <a href="command-line-options.html#shade">‑shade</a> <span class='bull'> • </span> <a href="command-line-options.html#shadow">‑shadow</a> <span class='bull'> • </span> <a href="command-line-options.html#shared-memory">‑shared‑memory</a> <span class='bull'> • </span> <a href="command-line-options.html#sharpen">‑sharpen</a> <span class='bull'> • </span> <a href="command-line-options.html#shave">‑shave</a> <span class='bull'> • </span> <a href="command-line-options.html#shear">‑shear</a> <span class='bull'> • </span> <a href="command-line-options.html#sigmoidal-contrast">‑sigmoidal‑contrast</a> <span class='bull'> • </span> <a href="command-line-options.html#silent">‑silent</a> <span class='bull'> • </span> <a href="command-line-options.html#size">‑size</a> <span class='bull'> • </span> <a href="command-line-options.html#sketch">‑sketch</a> <span class='bull'> • </span> <a href="command-line-options.html#smush">‑smush</a> <span class='bull'> • </span> <a href="command-line-options.html#snaps">‑snaps</a> <span class='bull'> • </span> <a href="command-line-options.html#solarize">‑solarize</a> <span class='bull'> • </span> <a href="command-line-options.html#sparse-color">‑sparse‑color</a> <span class='bull'> • </span> <a href="command-line-options.html#splice">‑splice</a> <span class='bull'> • </span> <a href="command-line-options.html#spread">‑spread</a> <span class='bull'> • </span> <a href="command-line-options.html#statistic">‑statistic</a> <span class='bull'> • </span> <a href="command-line-options.html#stegano">‑stegano</a> <span class='bull'> • </span> <a href="command-line-options.html#stereo">‑stereo</a> <span class='bull'> • </span> <a href="command-line-options.html#stretch">‑stretch</a> <span class='bull'> • </span> <a href="command-line-options.html#strip">‑strip</a> <span class='bull'> • </span> <a href="command-line-options.html#stroke">‑stroke</a> <span class='bull'> • </span> <a href="command-line-options.html#strokewidth">‑strokewidth</a> <span class='bull'> • </span> <a href="command-line-options.html#style">‑style</a> <span class='bull'> • </span> <a href="command-line-options.html#subimage-search">‑subimage‑search</a> <span class='bull'> • </span> <a href="command-line-options.html#swap">‑swap</a> <span class='bull'> • </span> <a href="command-line-options.html#swirl">‑swirl</a> <span class='bull'> • </span> <a href="command-line-options.html#synchronize">‑synchronize</a> <span class='bull'> • </span> <a href="command-line-options.html#taint">‑taint</a> <span class='bull'> • </span> <a href="command-line-options.html#text-font">‑text‑font</a> <span class='bull'> • </span> <a href="command-line-options.html#texture">‑texture</a> <span class='bull'> • </span> <a href="command-line-options.html#threshold">‑threshold</a> <span class='bull'> • </span> <a href="command-line-options.html#thumbnail">‑thumbnail</a> <span class='bull'> • </span> <a href="command-line-options.html#tile">‑tile</a> <span class='bull'> • </span> <a href="command-line-options.html#tile-offset">‑tile‑offset</a> <span class='bull'> • </span> <a href="command-line-options.html#tint">‑tint</a> <span class='bull'> • </span> <a href="command-line-options.html#title">‑title</a> <span class='bull'> • </span> <a href="command-line-options.html#transform">‑transform</a> <span class='bull'> • </span> <a href="command-line-options.html#transparent">‑transparent</a> <span class='bull'> • </span> <a href="command-line-options.html#transparent-color">‑transparent‑color</a> <span class='bull'> • </span> <a href="command-line-options.html#transpose">‑transpose</a> <span class='bull'> • </span> <a href="command-line-options.html#transverse">‑transverse</a> <span class='bull'> • </span> <a href="command-line-options.html#treedepth">‑treedepth</a> <span class='bull'> • </span> <a href="command-line-options.html#trim">‑trim</a> <span class='bull'> • </span> <a href="command-line-options.html#type">‑type</a> <span class='bull'> • </span> <a href="command-line-options.html#undercolor">‑undercolor</a> <span class='bull'> • </span> <a href="command-line-options.html#unique-colors">‑unique‑colors</a> <span class='bull'> • </span> <a href="command-line-options.html#units">‑units</a> <span class='bull'> • </span> <a href="command-line-options.html#unsharp">‑unsharp</a> <span class='bull'> • </span> <a href="command-line-options.html#update">‑update</a> <span class='bull'> • </span> <a href="command-line-options.html#verbose">‑verbose</a> <span class='bull'> • </span> <a href="command-line-options.html#version">‑version</a> <span class='bull'> • </span> <a href="command-line-options.html#view">‑view</a> <span class='bull'> • </span> <a href="command-line-options.html#vignette">‑vignette</a> <span class='bull'> • </span> <a href="command-line-options.html#virtual-pixel">‑virtual‑pixel</a> <span class='bull'> • </span> <a href="command-line-options.html#visual">‑visual</a> <span class='bull'> • </span> <a href="command-line-options.html#watermark">‑watermark</a> <span class='bull'> • </span> <a href="command-line-options.html#wave">‑wave</a> <span class='bull'> • </span> <a href="command-line-options.html#weight">‑weight</a> <span class='bull'> • </span> <a href="command-line-options.html#white-point">‑white‑point</a> <span class='bull'> • </span> <a href="command-line-options.html#white-threshold">‑white‑threshold</a> <span class='bull'> • </span> <a href="command-line-options.html#window">‑window</a> <span class='bull'> • </span> <a href="command-line-options.html#window-group">‑window‑group</a> <span class='bull'> • </span> <a href="command-line-options.html#write">‑write</a> ] </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	232
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	233	<div class="doc-section">
				234
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	235	<p>Below is list of command-line options recognized by the ImageMagick <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	236	href="command-line-tools.html">command-line
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	237	tools</a>. If you want a description of a particular option, click on the
				238	option name in the navigation bar above and you will go right to it. Unless
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	239	otherwise noted, each option is recognized by the commands <a href="convert.html">convert</a>, <a href="mogrify.html">mogrify</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	240
				241	<div style="margin: auto;">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	242	<h4><a id="adaptive-blur"></a>-adaptive-blur <em class="arg">radius</em>[x<em class="arg">sigma</em>]</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	243	</div>
				244
				245	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Adaptively blur pixels, with decreasing effect near edges.</td><td style='text-align:right;'></td></tr></table>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	246
				247	<p>A Gaussian operator of the given radius and standard deviation (<em
				248	class="arg">sigma</em>) is used. If <em class="arg">sigma</em> is not given it
				249	defaults to 1.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	250
				251	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	252	<h4><a id="adaptive-resize"></a>-adaptive-resize <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	253	</div>
				254
				255	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Resize the image using data-dependent triangulation.</td><td style='text-align:right;'></td></tr></table>
				256
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	257	<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>
				258	option defaults to data-dependent triangulation. Use the <a
				259	href="command-line-options.html#filter">-filter</a> to choose a different resampling algorithm.
				260	Offsets, if present in the geometry string, are ignored, and the <a
				261	href="command-line-options.html#gravity">-gravity</a> option has no effect.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	262
				263	<div style="margin: auto;">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	264	<h4><a id="adaptive-sharpen"></a>-adaptive-sharpen <em class="arg">radius</em>[x<em class="arg">sigma</em>]</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	265	</div>
				266
				267	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Adaptively sharpen pixels, with increasing effect near edges.</td><td style='text-align:right;'></td></tr></table>
				268
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	269	<p>A Gaussian operator of the given radius and standard deviation (<em
				270	class="arg">sigma</em>) is used. If <em class="arg">sigma</em> is not given it
				271	defaults to 1.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	272
				273	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	274	<h4><a id="adjoin"></a>-adjoin</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	275	</div>
				276
				277	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Join images into a single multi-image file.</td><td style='text-align:right;'></td></tr></table>
				278
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	279	<p>This option is enabled by default. An attempt is made to save all images of
				280	an image sequence into the given output file. However, some formats, such as
				281	JPEG and PNG, do not support more than one image per file, and in that case
				282	ImageMagick is forced to write each image as a separate file. As such, if
				283	more than one image needs to be written, the filename given is modified by
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	284	adding a <a href="command-line-options.html#scene">-scene</a> number before the suffix, in order to
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	285	make distinct names for each image. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	286
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	287	<p>Use <a href="command-line-options.html#adjoin">+adjoin</a> to force each image to be written to
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	288	separate files, whether or not the file format allows multiple images per file
				289	(for example, GIF, MIFF, and TIFF). </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	290
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	291	<p>Including a C-style integer format string in the output filename will
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	292	automagically enable <a href="command-line-options.html#adjoin">+adjoin</a> and are used to specify
				293	where the <a href="command-line-options.html#scene">-scene</a> number is placed in the filenames. These
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	294	strings, such as '<code>%d</code>' or '<code>%03d</code>', are familiar to those
				295	who have used the standard <code>printf()</code>' C-library function. As an
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	296	example, the command</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	297
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	298	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert logo: rose: -morph 15 my%02dmorph.jpg</span></p>
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	299	<p>will create a sequence of 17 images (the two given plus 15 more created by
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	300	<a href="command-line-options.html#morph">-morph</a>), named: my00morph.jpg, my01morph.jpg,
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	301	my02morph.jpg, ..., my16morph.jpg. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	302
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	303	<p>In summary, ImageMagick tries to write all images to one file, but will
				304	save to multiple files, if any of the following conditions exist...
				305	<ol>
				306	<li>the output image's file format does not allow multi-image files,
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	307	<li>the <a href="command-line-options.html#adjoin">+adjoin</a> option is given, or
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	308	<li>a printf() integer format string (eg: "%d") is present in the output
				309	filename.
				310	</ol></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	311
				312
				313	<div style="margin: auto;">
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	314	<h4><a id="affine"></a>-affine
				315	<em class="arg">s<sub>x</sub></em>,<em class="arg">r<sub>x</sub></em>,<em
				316	class="arg">r<sub>y</sub></em>,<em class="arg">s<sub>y</sub></em>[,<em
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	317	class="arg">t<sub>x</sub></em>,<em class="arg">t<sub>y</sub></em>]</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	318	</div>
				319
				320	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the drawing transformation matrix for combined rotating and scaling.</td><td style='text-align:right;'></td></tr></table>
				321
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	322	<p>This option sets a transformation matrix, for use by subsequent <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	323	href="command-line-options.html#draw">-draw</a> or <a href="command-line-options.html#transform">-transform</a> options. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	324
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	325	<p>The matrix entries are entered as comma-separated numeric values either in
				326	quotes or without spaces. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	327
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	328	<p>Internally, the transformation matrix has 3x3 elements, but three of them
				329	are omitted from the input because they are constant. The new (transformed)
				330	coordinates (<em class="arg">x'</em>, <em class="arg">y'</em>) of a pixel at
				331	position (<em class="arg">x</em>, <em class="arg">y</em>) in the original
				332	image are calculated using the following matrix equation.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	333
				334	<div class="eqn">
				335	<img alt="affine transformation" src="../images/affine.png"/>
				336	</div>
				337
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	338	<p> The size of the resulting image is that of the smallest rectangle that
				339	contains the transformed source image. The parameters <em
				340	class="arg">t<sub>x</sub></em> and <em class="arg">t<sub>y</sub></em>
				341	subsequently shift the image pixels so that those that are moved out of the
				342	image area are cut off.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	343
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	344	<p>The transformation matrix complies with the left-handed pixel coordinate
				345	system: positive <em class="arg">x</em> and <em class="arg">y</em> directions
				346	are rightward and downward, resp.; positive rotation is clockwise.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	347
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	348	<p> If the translation coefficients <em class="arg">t<sub>x</sub></em> and <em
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	349	class="arg">t<sub>y</sub></em> are omitted they default to 0,0. Therefore,
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	350	four parameters suffice for rotation and scaling without translation.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	351
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	352	<p>Scaling by the factors <em class="arg">s<sub>x</sub></em> and <em
				353	class="arg">s<sub>y</sub></em> in the <em>x</em> and <em>y</em> directions,
				354	respectively, is accomplished with the following.</p>
				355
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	356	<p>See <a href="command-line-options.html#transform">-transform</a>, and the <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	357	href="command-line-options.html#distort">-distort</a> method '<code>Affineprojection</code> for more
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	358	information </p>
				359
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	360
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	361	<p class="crtsnip"> -affine <em class="arg">s<sub>x</sub></em>,0,0,<em
				362	class="arg">s<sub>y</sub></em> </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	363
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	364	<p>Translation by a displacement (<em class="arg">t<sub>x</sub></em>, <em
				365	class="arg">t<sub>y</sub></em>) is accomplished like so:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	366
				367	<p class="crtsnip">
				368	-affine 1,0,0,1,<em class="arg">t<sub>x</sub></em>,<em class="arg">t<sub>y</sub></em>
				369	</p>
				370
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	371	<p>Rotate clockwise about the origin (the upper left-hand corner) by an angle
				372	<em>a</em> by letting <em>c</em> = cos(<em>a</em>), <em>s</em>
				373	= sin(<em>a</em>), and using the following.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	374
				375	<p class="crtsnip">
				376	-affine <em>c</em>,<em>s</em>,-<em>s</em>,<em>c</em>
				377	</p>
				378
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	379	<p>The cumulative effect of a sequence of <a href="command-line-options.html#affine" >-affine</a>
				380	transformations can be accomplished by instead by a single <a href="command-line-options.html#affine"
				381	>-affine</a> operation using the matrix equal to the product of the matrices
				382	of the individual transformations.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	383
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	384	<p>An attempt is made to detect near-singular transformation matrices. If the
				385	matrix determinant has a sufficiently small absolute value it is rejected.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	386
				387	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	388	<h4><a id="alpha"></a>-alpha <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	389	</div>
				390
				391	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Gives control of the alpha/matte channel of an image.</td><td style='text-align:right;'></td></tr></table>
				392
				393	<p>Used to set a flag on an image indicating whether or not to use existing alpha
				394	channel data, to create an alpha channel, or to perform other operations on the alpha channel. Choose the argument <em class="arg">type</em> from the list below.</p>
				395
				396
				397	<table class="doc">
				398	<tbody>
				399	<tr valign="top">
				400	<th align="left" style="width: 8%">type</th>
				401	<th align="left">Description</th>
				402	</tr>
				403
				404	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	405	<td valign="top"><code>Activate</code> or <code>On</code></td>
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	406	<td valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	407	Enable the image's transparency channel. Note normally <code>Set</code>
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	408	should be used instead of this, unless you specifically need to
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	409	preserve existing (but specifically turned <code>Off</code>) transparency
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	410	channel. </td></tr>
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	411
				412	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	413	<td valign="top"><code>Deactivate</code> or <code>Off</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	414	<td valign="top">
				415	Disables the image's transparency channel. Does not delete or change the
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	416	existing data, just turns off the use of that data.</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	417
				418	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	419	<td valign="top"><code>Set</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	420	<td valign="top">
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	421	Activates the alpha/matte channel. If it was previously turned off
				422	then it also resets the channel to opaque. If the image already had
				423	the alpha channel turned on, it will have no effect.</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	424
				425	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	426	<td valign="top"><code>Opaque</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	427	<td valign="top">
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	428	Enables the alpha/matte channel and forces it to be fully opaque.
				429	</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	430
				431	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	432	<td valign="top"><code>Transparent</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	433	<td valign="top">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	434	Activates the alpha/matte channel and forces it to be fully
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	435	transparent. This effectively creates a fully transparent image the
				436	same size as the original and with all its original RGB data still
				437	intact, but fully transparent. </td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	438
				439	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	440	<td valign="top"><code>Extract</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	441	<td valign="top">
				442	Copies the alpha channel values into all the color channels and turns
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	443	'<code>Off</code>' the the image's transparency, so as to generate
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	444	a gray-scale mask of the image's shape. The alpha channel data is left
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	445	intact just deactivated. This is the inverse of '<code>Copy</code>'.
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	446	</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	447
				448	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	449	<td valign="top"><code>Copy</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	450	<td valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	451	Turns '<code>On</code>' the alpha/matte channel, then copies the
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	452	gray-scale intensity of the image, into the alpha channel, converting
				453	a gray-scale mask into a transparent shaped mask ready to be colored
				454	appropriately. The color channels are not modified. </td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	455
				456	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	457	<td valign="top"><code>Shape</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	458	<td valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	459	As per '<code>Copy</code>' but also colors the resulting shape mask with
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	460	the current background color. That is the RGB color channels is
				461	replaced, with appropriate alpha shape.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	462	</td></tr>
				463
				464	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	465	<td valign="top"><code>Remove</code></td>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	466	<td valign="top">
				467	Composite the image over the background color.
				468	</td></tr>
				469
				470	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	471	<td valign="top"><code>Background</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	472	<td valign="top">
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	473	Set any fully-transparent pixel to the background color, while leaving
				474	it fully-transparent. This can make some image file formats, such as
				475	PNG, smaller as the RGB values of transparent pixels are more uniform,
				476	and thus can compress better.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	477	</td></tr>
				478	</tbody>
				479	</table>
				480
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	481	<p>Note that while the obsolete <code>+matte</code> operation was the
				482	same as "<code><a href="command-line-options.html#alpha" >-alpha</a> Off</code>", the <code>
				483	>-matte</code> operation was the same as "<code><a href="command-line-options.html#alpha" >-alpha</a>
				484	Set</code>" and not "<code><a href="command-line-options.html#alpha" >-alpha</a> On</code>". </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	485
				486
				487	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	488	<h4><a id="annotate"></a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	489	-annotate <em class="arg">degrees</em> <em class="arg">text</em><br />
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	490	-annotate <em class="arg">Xdegrees</em>x<em class="arg">Ydegrees</em> <em
				491	class="arg">text</em><br /> -annotate <em class="arg">Xdegrees</em>x<em
				492	class="arg">Ydegrees</em> {+-}<em class="arg">t<sub>x</sub></em>{+-}<em
				493	class="arg">t<sub>y</sub></em> <em class="arg">text</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	494	</div>
				495
				496	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Annotate an image with text.</td><td style='text-align:right;'></td></tr></table>
				497
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	498	<p>This is a convenience for annotating an image with text. For more precise
				499	control over text annotations, use <a href="command-line-options.html#draw">-draw</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	500
				501
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	502	<p>The values <em class="arg">Xdegrees</em> and <em class="arg">Ydegrees</em>
				503	control the shears with respect to the , respectively, applied to the text,
				504	while <em class="arg">t<sub>x</sub></em> and <em
				505	class="arg">t<sub>y</sub></em> are offsets that give the location of the text
				506	relative to the upper left corner of the image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	507
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	508	<p>Using <a href="command-line-options.html#annotate">-annotate</a> <em class="arg">degrees</em>
				509	or <a href="command-line-options.html#annotate">-annotate</a> <em class="arg">degrees</em>x<em
				510	class="arg">degrees</em> produces an unsheared rotation of the text. The
				511	direction of the rotation is positive, which means a clockwise rotation if <em
				512	class="arg">degrees</em> is positive. (This conforms to the usual mathematical
				513	convention once it is realized that the positive <em>y</em>–direction is
				514	conventionally considered to be <em>downward</em> for images.)</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	515
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	516	<p>The new (transformed) coordinates (<em class="arg">x'</em>, <em
				517	class="arg">y'</em>) of a pixel at position (<em class="arg">x</em>, <em
				518	class="arg">y</em>) in the image are calculated using the following matrix
				519	equation.</p> <div class="eqn"><img alt="annotate transformation" src="../images/annotate.png"/></div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	520
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	521	<p>If <em class="arg">t<sub>x</sub></em> and <em
				522	class="arg">t<sub>y</sub></em> are omitted, they default to 0. This makes the
				523	bottom-left of the text becomes the upper-left corner of the image, which is
				524	probably undesirable. Adding a <a href="command-line-options.html#gravity" >-gravity</a> option in this
				525	case leads to nice results.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	526
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	527	<p>Text is any UTF-8 encoded character sequence. If <em class="arg">text</em>
				528	is of the form '@mytext.txt', the text is read from the file
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	529	<code>mytext.txt</code>. Text in a file is taken literally; no embedded
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	530	formatting characters are recognized.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	531
				532	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	533	<h4><a id="antialias"></a>-antialias</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	534	</div>
				535
				536	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Enable/Disable of the rendering of anti-aliasing pixels when
				537	drawing fonts and lines.</td><td style='text-align:right;'></td></tr></table>
				538
				539	<p>By default, objects (e.g. text, lines, polygons, etc.) are antialiased when
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	540	drawn. Use <a href="command-line-options.html#antialias">+antialias</a> to disable the addition of
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	541	antialiasing edge pixels. This will then reduce the number of colors added to
				542	an image to just the colors being directly drawn. That is, no mixed colors
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	543	are added when drawing such objects. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	544
				545	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	546	<h4><a id="append"></a>-append</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	547	</div>
				548
				549	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Join current images vertically or horizontally.</td><td style='text-align:right;'></td></tr></table>
				550
				551	<p>This option creates a single longer image image, by joining all the current
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	552	images in sequence top-to-bottom. Use <a href="command-line-options.html#append">+append</a> to
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	553	stack images left-to-right. </p>
				554
				555	<p>If they are not of the same width, narrower images are padded with the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	556	current <a href="command-line-options.html#background">-background</a> color setting, and their
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	557	position relative to each other can be controlled by the current <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	558	href="command-line-options.html#gravity">-gravity</a> setting. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	559
				560
				561	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	562	<h4><a id="attenuate"></a>-attenuate <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	563	</div>
				564
				565	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Lessen (or intensify) when adding noise to an image.</td><td style='text-align:right;'></td></tr></table>
				566
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	567	<p>If unset the value is equivelent to 1.0, or a maximum noise addition</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	568
				569	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	570	<h4><a id="authenticate"></a>-authenticate <em class="arg">password</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	571	</div>
				572
				573	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Decrypt a PDF with a password.</td><td style='text-align:right;'></td></tr></table>
				574
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	575	<p>Use this option to supply a <em class="arg">password</em> for decrypting
				576	a PDF that has been encrypted using Microsoft Crypto API (MSC API). The
				577	encrypting using the MSC API is not supported.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	578
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	579	<p>For a different encryption method, see <a href="command-line-options.html#encipher">-encipher</a>
				580	and <a href="command-line-options.html#decipher">-decipher</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	581
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	582
				583
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	584	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	585	<h4><a id="auto-gamma"></a>-auto-gamma</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	586	</div>
				587
				588	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Automagically adjust gamma level of image.</td><td style='text-align:right;'></td></tr></table>
				589
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	590	<p>This calculates the mean values of an image, then applies a calculated <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	591	href="command-line-options.html#gamma" >-gamma</a> adjustment so that is the mean color exists in the
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	592	image it will get a have a value of 50%. </p>
				593
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	594	<p>This means that any solid 'gray' image becomes 50% gray. </p>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	595
				596	<p>This works well for real-life images with little or no extreme dark and
				597	light areas, but tend to fail for images with large amounts of bright sky or
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	598	dark shadows. It also does not work well for diagrams or cartoon like images.
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	599	</p>
				600
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	601	<p>It uses the <a href="command-line-options.html#channel" >-channel</a> setting, (including the
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	602	'<em>sync</em>' flag for channel synchronization), to determine which color
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	603	values is used and modified. As the default <a href="command-line-options.html#channel"
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	604	>-channel</a> setting is '<em>RGB,sync</em>', channels are modified
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	605	together by the same gamma value, preserving colors. </p>
				606
				607
				608
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	609	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	610	<h4><a id="auto-level"></a>-auto-level</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	611	</div>
				612
				613	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Automagically adjust color levels of image.</td><td style='text-align:right;'></td></tr></table>
				614
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	615	<p>This is a 'perfect' image normalization operator. It finds the exact
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	616	minimum and maximum color values in the image and then applies a <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	617	href="command-line-options.html#level" >-level</a> operator to stretch the values to the full range of
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	618	values. </p>
				619
cristy	8354396	2009-10-16 19:04:28 +0000	[diff] [blame]	620	<p>The operator is not typically used for real-life images, image scans, or
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	621	JPEG format images, as a single 'out-rider' pixel can set a bad min/max values
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	622	for the <a href="command-line-options.html#level" >-level</a> operation. On the other hand it is the
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	623	right operator to use for color stretching gradient images being used to
				624	generate Color lookup tables, distortion maps, or other 'mathematically'
				625	defined images. </p>
				626
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	627	<p>The operator is very similar to the <a href="command-line-options.html#normalize">-normalize</a>, <a
				628	href="command-line-options.html#contrast-stretch" >-contrast-stretch</a>, and <a href="command-line-options.html#linear-stretch"
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	629	>-linear-stretch</a> operators, but without 'histogram binning' or 'clipping'
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	630	problems that these operators may have. That is <a href="command-line-options.html#auto-level"
cristy	8354396	2009-10-16 19:04:28 +0000	[diff] [blame]	631	>-auto-level</a> is the perfect or ideal version these operators. </p>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	632
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	633	<p>It uses the <a href="command-line-options.html#channel" >-channel</a> setting, (including the
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	634	special '<em>sync</em>' flag for channel synchronization), to determine
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	635	which color values are used and modified. As the default <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	636	href="command-line-options.html#channel" >+channel</a> setting is '<em>RGB,sync</em>', the
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	637	'<em>sync</em>' ensures that the color channels will are modified
cristy	8354396	2009-10-16 19:04:28 +0000	[diff] [blame]	638	together by the same gamma value, preserving colors, and ignoring
				639	transparency. </p>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	640
				641
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	642	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	643	<h4><a id="auto-orient"></a>-auto-orient</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	644	</div>
				645
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	646	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>adjusts an image so that its orientation is suitable for viewing (i.e. top-left orientation).</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	647
cristy	8354396	2009-10-16 19:04:28 +0000	[diff] [blame]	648	<p>This operator reads and resets the EXIF image profile setting 'Orientation'
				649	and then performs the appropriate 90 degree rotation on the image to orient
				650	the image, for correct viewing. </p>
				651
				652	<p>This EXIF profile setting is usually set using a gravity sensor in digital
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	653	camera, however photos taken directly downward or upward may not have an
cristy	8354396	2009-10-16 19:04:28 +0000	[diff] [blame]	654	appropriate value. Also images that have been orientation 'corrected' without
				655	reseting this setting, may be 'corrected' again resulting in a incorrect
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	656	result. If the EXIF profile was previously stripped, the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	657	href="command-line-options.html#auto-orient" >-auto-orient</a> operator will do nothing. </p>
cristy	8354396	2009-10-16 19:04:28 +0000	[diff] [blame]	658
				659
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	660	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	661	<h4><a id="average"></a>-average</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	662	</div>
				663
				664	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Average a set of images.</td><td style='text-align:right;'></td></tr></table>
				665
				666	<p>An error results if the images are not identically sized.</p>
				667
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	668
				669	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	670	<h4><a id="backdrop"></a>-backdrop</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	671	</div>
				672
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	673	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Display the image centered on a backdrop.</td><td style='text-align:right;'>[<a href="animate.html">animate</a>, <a href="display.html">display</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	674
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	675	<p>This backdrop covers the entire workstation screen and is useful for hiding
				676	other X window activity while viewing the image. The color of the backdrop is
				677	specified as the background color. The color is specified using the format
				678	described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	679
				680	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	681	<h4><a id="background"></a>-background <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	682	</div>
				683
				684	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the background color.</td><td style='text-align:right;'></td></tr></table>
				685
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	686	<p>The color is specified using the format described under the <a
				687	href="command-line-options.html#fill">-fill</a> option. The default background color (if none is
				688	specified or found in the image) is white.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	689
				690	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	691	<h4><a id="bench"></a>-bench <em class="arg">iterations</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	692	</div>
				693
				694	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Measure performance.</td><td style='text-align:right;'></td></tr></table>
				695
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	696	<p>Repeat the entire command for the given number of <em class="arg"
				697	>iterations</em> and report the user-time and elapsed time. For instance,
				698	consider the following command and its output. Modify the benchmark with the
				699	-duration to run the benchmark for a fixed number of seconds and -concurrent
				700	to run the benchmark in parallel (requires the OpenMP feature).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	701
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	702	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert logo: -resize 1000% -bench 5 logo.png</span><span class='crtout'>Performance[4]: 5i 0.875657ips 6.880u 0:05.710</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	703	<p>In this example, 5 iterations were completed at 0.875657 iterations per
				704	second, using 4 threads and 6.88 seconds of the user's allotted time, for
				705	a total elapsed time of 5.71 seconds.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	706
				707	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	708	<h4><a id="bias"></a>-bias <em class="arg">value</em>{<em class="arg">%</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	709	</div>
				710
				711	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Add bias when convolving an image.</td><td style='text-align:right;'></td></tr></table>
				712
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	713	<p>This option shifts the output of <a href="command-line-options.html#convolve">‑convolve</a> so that
				714	positive and negative results are relative to the specified bias value. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	715
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	716	<p>This is important for non-HDRI compilations of ImageMagick when dealing
				717	with convolutions that contain negative as well as positive values. This is
				718	especially the case with convolutions involving high pass filters or edge
				719	detection. Without an output bias, the negative values are clipped at
				720	zero.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	721
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	722	<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
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	723	negative results without clipping to the color value range
				724	(0..QuantumRange).</p>
				725
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	726	<p>See the discussion on HDRI implementations of ImageMagick on the page <a
				727	href="high-dynamic-range.html" >High Dynamic-Range Images</a>. For more
				728	about HDRI go the ImageMagick <a
				729	href="http://www.imagemagick.org/Usage/basics/#hdri" >Usage</a> pages or this
				730	<a
				731	href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a>
				732	entry. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	733
				734	<div style="margin: auto;">
cristy	37e0dfd	2011-03-06 16:35:34 +0000	[diff] [blame]	735	<h4><a id="black-point-compensation"></a>-black-point-compensation</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	736	</div>
				737
				738	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Use black point compensation.</td><td style='text-align:right;'></td></tr></table>
				739
				740	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	741	<h4><a id="black-threshold"></a>-black-threshold <em class="arg">value</em>{<em class="arg">%</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	742	</div>
				743
cristy	5cadd61	2009-09-21 19:33:41 +0000	[diff] [blame]	744	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Force to black all pixels below the threshold while leaving all pixels at or above the threshold unchanged.</td><td style='text-align:right;'></td></tr></table>
				745
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	746	<p> The threshold value can be given as a percentage or as an absolute integer
				747	value within [0, <em class="QR">QuantumRange</em>] corresponding to the
				748	desired <a href="command-line-options.html#channel">‑channel</a> value. See <a href="command-line-options.html#threshold">‑threshold</a>for more details on thresholds and resulting values. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	749
				750
				751	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	752	<h4><a id="blend"></a>-blend <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	753	</div>
				754
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	755	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>blend an image into another by the given absolute value or percent.</td><td style='text-align:right;'>[<a href="composite.html">composite</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	756
				757	<p>Blend will average the images together ('plus') according to the
				758	percentages given and each pixels transparency. If only a single percentage
				759	value is given it sets the weight of the composite or 'source' image, while
				760	the background image is weighted by the exact opposite amount. That is a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	761	<code>-blend 30%</code> merges 30% of the 'source' image with 70% of the
				762	'destination' image. Thus it is equivalent to <code>-blend 30x70%</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	763
				764
				765	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	766	<h4><a id="blue-primary"></a>-blue-primary <em class="arg">x</em>,<em class="arg">y</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	767	</div>
				768
				769	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the blue chromaticity primary point.</td><td style='text-align:right;'></td></tr></table>
				770
				771	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	772	<h4><a id="blue-shift"></a>-blue-shift <em class="arg">factor</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	773	</div>
				774
				775	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>simulate a scene at nighttime in the moonlight. Start with a factor of 1.5</td><td style='text-align:right;'></td></tr></table>
				776
				777	<div style="margin: auto;">
				778
				779	<div style="margin: auto;">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	780	<h4><a id="blur"></a>-blur <em class="arg">radius</em><br />-blur <em class="arg">radius</em>x<em class="arg">sigma</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	781	</div>
				782
				783	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Reduce image noise and reduce detail levels.</td><td style='text-align:right;'></td></tr></table>
				784
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	785	<p>Convolve the image with a Gaussian or normal distribution using the given
				786	<em class="arg" >Sigma</em> value. The formula is:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	787
				788	<div class="eqn"><img alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png"/>
				789	</div>
				790
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	791	<p>The <em class="arg" >Sigma</em> value is the important argument, and
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	792	determines the actual amount of blurring that will take place. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	793
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	794	<p>The <em class="arg" >Radius</em> is only used to determine the size of the
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	795	array which will hold the calculated Gaussian distribution. It should be an
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	796	integer. If not given, or set to zero, IM will calculate the largest possible
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	797	radius that will provide meaningful results for the Gaussian distribution.
				798	</p>
				799
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	800	<p>The larger the <em class="arg" >Radius</em> the slower the
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	801	operation is. However too small a <em class="arg" >Radius</em>, and sever
				802	aliasing effects may result. As a guideline, <em class="arg" >Radius</em>
				803	should be at least twice the <em class="arg" >Sigma</em> value, though three
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	804	times will produce a more accurate result. </p>
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	805
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	806	<p>This option differs from <a href="command-line-options.html#gaussian-blur">-gaussian-blur</a> simply
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	807	by taking advantage of the separability properties of the distribution. Here
				808	we apply a single-dimensional Gaussian matrix in the horizontal direction,
				809	then repeat the process in the vertical direction.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	810
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	811	<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	812	pixels which are outside the image proper are blurred into the final result.
				813	</p>
				814
				815
				816	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	817	<h4>-blur <em class="arg">Width</em>[x<em class="arg">Height</em>[+<em class="arg">Angle</em>]]</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	818	</div>
				819
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	820	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Variably blur and image according to the overlay mapping.</td><td style='text-align:right;'>[<a href="composite.html">composite</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	821
				822	<p>Each pixel in the overlaid region is replaced with an Elliptical Weighted
				823	Average (EWA) of the source image, scaled according to the grayscale
				824	mapping. </p>
				825
				826	<p>The ellipse is weighted with sigma set to the given <em class="arg"
				827	>Width</em> and <em class="arg" >Height</em>. The <em class="arg" >Height</em>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	828	defaults to the <em class="arg" >Width</em> for a normal circular Gaussian
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	829	weighting. The <em class="arg" >Angle</em> will rotate the ellipse from
				830	horizontal clock-wise. </p>
				831
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	832	<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	833	pixels which are outside the image proper are blurred into the final result.
				834	</p>
				835
				836
				837	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	838	<h4><a id="border"></a>-border <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	839	</div>
				840
				841	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Surround the image with a border of color. </td><td style='text-align:right;'></td></tr></table>
				842
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	843	<p>Set the width and height using the <em class="arg">size</em> portion of the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	844	<em class="arg">geometry</em> 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
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	845	ignored. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	846
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	847	<p>As of IM 6.7.8-8, the <em class="arg">geometry</em> arguments behave as follows:</p>
				848
				849	<table id="borderTable" class="doc">
				850	<col width="20%"/> <col width="80%"/>
				851	<thead>
				852	<tr valign="top">
				853	<th style="text-align:center"><em class="arg">size</em></th>
				854	<th>General description</th>
				855	</tr>
				856	</thead>
				857	<tbody>
				858	<tr valign="top">
				859	<td><em class="arg">value</em></td>
				860	<td>value is added to both left/right and top/bottom</td>
				861	</tr>
				862	<tr valign="top">
				863	<td><em class="arg">value-x</em>x</td>
				864	<td>value-x is added only to left/right and top/bottom are unchanged</td>
				865	</tr>
				866	<tr valign="top">
				867	<td>x<em class="arg">value-y</em></td>
				868	<td>value-y is added only to top/bottom and left/right are unchanged</td>
				869	</tr>
				870	<tr valign="top">
				871	<td><em class="arg">value-x</em>x<em class="arg">value-y</em></td>
				872	<td>value-x is added to left/right and value-y added to top/bottom</td>
				873	</tr>
				874	<tr valign="top">
				875	<td><em class="arg">value-x</em>x<code>0</code></td>
				876	<td>value-x is added only to left/right and top/bottom are unchanged</td>
				877	</tr>
				878	<tr valign="top">
				879	<td><code>0</code>x<em class="arg">value-y</em></td>
				880	<td>value-y is added only to top/bottom and left/right are unchanged</td>
				881	</tr>
				882	<tr valign="top">
				883	<td> </td>
				884	<td> </td>
				885	</tr>
				886	<tr valign="top">
				887	<td><em class="arg">value</em>%</td>
				888	<td>value % of width is added to left/right and value % of height is added to top/bottom</td>
				889	</tr>
				890	<tr valign="top">
				891	<td><em class="arg">value-x</em>x%</td>
				892	<td>value-x % of width is added to left/right and to top/bottom</td>
				893	</tr>
				894	<tr valign="top">
				895	<td>x<em class="arg">value-y</em>%</td>
				896	<td>value-y % of height is added to top/bottom and to left/right</td>
				897	</tr>
				898	<tr valign="top">
				899	<td><em class="arg">value-x</em>%x<em class="arg">value-y</em>%</td>
				900	<td>value-x % of width is added to left/right and value-y % of height is added to top/bottom</td>
				901	</tr>
				902	<tr valign="top">
				903	<td><em class="arg">value-x</em>%x<code>0</code>%</td>
				904	<td>value-x % of width is added to left/right and top/bottom are unchanged</td>
				905	</tr>
				906	<tr valign="top">
				907	<td><code>0</code>%xvalue-y</em>%</td>
				908	<td>value-y % of height is added to top/bottom and left/right are unchanged</td>
				909	</tr>
				910	</tbody>
				911	</table>
				912
				913
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	914	<p>Set the border color by preceding with the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	915	href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	916
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	917	<p>The <a href="command-line-options.html#border">-border</a> operation is affected by the current <a
				918	href="command-line-options.html#compose">-compose</a> setting and assumes that this is using the default
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	919	'<code>Over</code>' composition method. It generates an image of the appropriate
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	920	size colors by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> before
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	921	overlaying the original image in the center of this net image. This means that
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	922	with the default compose method of '<code>Over</code>' any transparent parts may
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	923	be replaced by the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p>
				924	<p>See also the <a href="command-line-options.html#frame">-frame</a> option, which has more
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	925	functionality.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	926
				927	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	928	<h4><a id="bordercolor"></a>-bordercolor <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	929	</div>
				930
				931	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the border color.</td><td style='text-align:right;'></td></tr></table>
				932
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	933	<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	934
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	935	<p>The default border color is <code>#DFDFDF</code>, <span style="background-color: #dfdfdf;">this shade of gray</span>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	936
				937	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	938	<h4><a id="borderwidth"></a>-borderwidth <em class="arg">geometry</em> </h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	939	</div>
				940
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	941	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the border width.</td><td style='text-align:right;'>[<a href="animate.html">animate</a>, <a href="display.html">display</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	942
				943	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	944	<h4><a id="brightness-contrast"></a>-brightness-contrast <em class="arg">brightness</em><br />-brightness-contrast <em class="arg">brightness</em>{x<em class="arg">contrast</em>}{<em class="arg">%</em>}}</h4>
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	945	</div>
				946
				947	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Adjust the brightness and/or contrast of the image.</td><td style='text-align:right;'></td></tr></table>
				948
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	949	<p>Brightness and Contrast values apply changes to the input image. They are
				950	not absolute settings. A brightness or contrast value of zero means no change.
				951	The range of values is -100 to +100 on each. Positive values increase the
				952	brightness or contrast and negative values decrease the brightness or contrast.
				953	To control only contrast, set the brightness=0. To control only brightness,
				954	set contrast=0 or just leave it off.</p>
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	955
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	956	<p>You may also use <a href="command-line-options.html#fill">-channel</a> to control which channels to
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	957	apply the brightness and/or contrast change. The default is to apply the same
				958	transformation to all channels.</p>
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	959
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	960	<p>Brightness and Contrast arguments are converted to offset and slope of a
				961	linear transform and applied
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	962	using <a href="command-line-options.html#fill">-function polynomial "slope,offset"</a>.</p>
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	963
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	964	<p>The slope varies from 0 at contrast=-100 to almost vertical at
				965	contrast=+100. For brightness=0 and contrast=-100, the result are totally
				966	midgray. For brightness=0 and contrast=+100, the result will approach but
				967	not quite reach a threshold at midgray; that is the linear transformation
				968	is a very steep vertical line at mid gray.</p>
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	969
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	970	<p>Negative slopes, i.e. negating the image, are not possible with this
				971	function. All achievable slopes are zero or positive.</p>
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	972
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	973	<p>The offset varies from -0.5 at brightness=-100 to 0 at brightness=0 to +0.5
				974	at brightness=+100. Thus, when contrast=0 and brightness=100, the result is
				975	totally white. Similarly, when contrast=0 and brightness=-100, the result is
				976	totally black.</p>
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	977
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	978	<p>As the range of values for the arguments are -100 to +100, adding the '%'
				979	symbol is no different than leaving it off.</p>
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	980
				981	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	982	<h4><a id="cache"></a>-cache <em class="arg">threshold</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	983	</div>
				984
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	985	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>(This option has been replaced by the <a href='command-line-options.html#limit'>-limit</a> option.)</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	986
				987	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	988	<h4><a id="caption"></a>-caption <em class="arg">string</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	989	</div>
				990
				991	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Assign a caption to an image.</td><td style='text-align:right;'></td></tr></table>
				992
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	993	<p>This option sets the caption meta-data of an image read in after this
				994	option has been given. To modify a caption of images already in memory use
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	995	"<code><a href="command-line-options.html#set">-set</a> caption</code>". </p>
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	996
				997	<p>The caption can contain special format characters listed in the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	998	href="escape.html">Format and
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	999	Print Image Properties</a>. These attributes are expanded when the caption
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	1000	is finally assigned to the individual images. </p>
				1001
				1002	<p>If the first character of <em class="arg">string</em> is <em
				1003	class="arg">@</em>, the image caption is read from a file titled by the
				1004	remaining characters in the string. Comments read in from a file are literal;
				1005	no embedded formatting characters are recognized.</p>
				1006
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1007	<p>Caption meta-data is not visible on the image itself. To do that use the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1008	<a href="command-line-options.html#annotate">-annotate</a> or <a href="command-line-options.html#draw">-draw</a> options
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	1009	instead.</p>
				1010
				1011	<p>For example,</p>
				1012
				1013	<p class="crtsnip">
				1014	-caption "%m:%f %wx%h" bird.miff
				1015	</p>
				1016
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1017	<p>produces an image caption of <code>MIFF:bird.miff 512x480</code> (assuming
				1018	that the image <code>bird.miff</code> has a width of 512 and a height of
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	1019	480.</p>
				1020
				1021
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1022	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1023	<h4><a id="cdl"></a>-cdl <em class="arg">filename</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1024	</div>
				1025
				1026	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>color correct with a color decision list.</td><td style='text-align:right;'></td></tr></table>
				1027
				1028	<p>Here is an example color correction collection:</p>
				1029
				1030	<pre class="text">
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1031	<?xml version="1.0" encoding="UTF-8"?>
				1032	<ColorCorrectionCollection xmlns="urn:ASC:CDL:v1.2">
				1033	<ColorCorrection id="cc06668">
				1034	<SOPNode>
				1035	<Slope> 0.9 1.2 0.5 </Slope>
				1036	<Offset> 0.4 -0.5 0.6 </Offset>
				1037	<Power> 1.0 0.8 1.5 </Power>
				1038	</SOPNode>
				1039	<SATNode>
				1040	<Saturation> 0.85 </Saturation>
				1041	</SATNode>
				1042	</ColorCorrection>
				1043	</ColorCorrectionCollection>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1044	</pre>
				1045
				1046	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1047	<h4><a id="channel"></a>-channel <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1048	</div>
				1049
				1050	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specify those image color channels to which subsequent operators are limited.</td><td style='text-align:right;'></td></tr></table>
				1051
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1052	<p>Choose from: <code>Red</code>, <code>Green</code>, <code>Blue</code>,
				1053	<code>Alpha</code>, <code>Cyan</code>, <code>Magenta</code>, <code>Yellow</code>,
				1054	<code>Black</code>, <code>Opacity</code>, <code>Index</code>, <code>RGB</code>,
				1055	<code>RGBA</code>, <code>CMYK</code>, or <code>CMYKA</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1056
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	1057	<p>The channels above can also be specified as a comma-separated list or can be
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1058	abbreviated as a concatenation of the letters '<code>R</code>', '<code>G</code>',
				1059	'<code>B</code>', '<code>A</code>', '<code>O</code>', '<code>C</code>',
				1060	'<code>M</code>', '<code>Y</code>', '<code>K</code>'.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1061
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1062	For example, to only select the <code>Red</code> and <code>Blue</code> channels
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	1063	you can either use </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1064	<p class="crtsnip">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	1065	-channel Red,Blue
				1066	</p>
				1067	<p>or you can use the short hand form</p>
				1068	<p class="crtsnip">
				1069	-channel RB
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1070	</p>
				1071
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	1072	<p>All the channels that are present in an image can be specified using the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1073	special channel type <code>All</code>. Not all operators are 'channel capable',
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1074	but generally any operators that are generally 'grey-scale' image operators,
				1075	will understand this setting. See individual operator documentation. </p>
				1076
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1077	<br />
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	1078
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	1079	<p>On top of the normal channel selection an extra flag can be specified,
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1080	'<code>Sync</code>'. This is turned on by default and if set means that
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1081	operators that understand this flag should perform: cross-channel
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	1082	synchronization of the channels. If not specified, then most grey-scale
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1083	operators will apply their image processing operations to each individual
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1084	channel (as specified by the rest of the <a href="command-line-options.html#channel">-channel</a>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1085	setting) completely independently from each other. </p>
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	1086
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1087	<p>For example for operators such as <a href="command-line-options.html#auto-level">-auto-level</a> and
				1088	<a href="command-line-options.html#auto-gamma">-auto-gamma</a> the color channels are modified
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	1089	together in exactly the same way so that colors will remain in-sync. Without
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	1090	it being set, then each channel is modified separately and
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1091	independently, which may produce color distortion. </p>
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	1092
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1093	<p>The <a href="command-line-options.html#morphology">-morphology</a> '<code>Convolve</code>' method
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1094	and the <a href="command-line-options.html#compose">-compose</a> mathematical methods, also understands
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1095	the '<code>Sync</code>' flag to modify the behaviour of pixel colors according
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1096	to the alpha channel (if present). That is to say it will modify the image
				1097	processing with the understanding that fully-transparent colors should not
				1098	contribute to the final result. </p>
				1099
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	1100	<p>Basically, by default, operators work with color channels in synchronous, and
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1101	treats transparency as special, unless the <a href="command-line-options.html#channel">-channel</a>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1102	setting is modified so as to remove the effect of the '<code>Sync</code>' flag.
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1103	How each operator does this depends on that operators current implementation.
				1104	Not all operators understands this flag at this time, but that is changing.
				1105	</p>
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	1106
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1107	<p>To print a complete list of channel types, use <a href="command-line-options.html#list">-list
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	1108	channel</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1109
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1110	<br />
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1111
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1112	<p>By default, ImageMagick sets <a href="command-line-options.html#channel">-channel</a> to the value
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1113	'<code>RGBK,sync</code>', which specifies that operators act on all color
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1114	channels except the transparency channel, and that all the color channels are
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1115	to be modified in exactly the same way, with an understanding of transparency
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1116	(depending on the operation being applied). The 'plus' form <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1117	href="command-line-options.html#channel" >+channel</a> will reset the value back to this default. </p>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1118
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1119	<p>Options that are affected by the <a href="command-line-options.html#channel" >-channel</a> setting
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1120	include the following.
				1121
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1122	<a href="command-line-options.html#auto-gamma">-auto-gamma</a>,
				1123	<a href="command-line-options.html#auto-level">-auto-level</a>,
				1124	<a href="command-line-options.html#black-threshold">-black-threshold</a>,
				1125	<a href="command-line-options.html#blur">-blur</a>,
				1126	<a href="command-line-options.html#clamp">-clamp</a>,
				1127	<a href="command-line-options.html#clut">-clut</a>,
				1128	<a href="command-line-options.html#combine">-combine</a>,
				1129	<a href="command-line-options.html#composite">-composite</a> (Mathematical compose methods only),
				1130	<a href="command-line-options.html#convolve">-convolve</a>,
				1131	<a href="command-line-options.html#contrast-stretch">-contrast-stretch</a>,
				1132	<a href="command-line-options.html#evaluate">-evaluate</a>,
				1133	<a href="command-line-options.html#function">-function</a>,
				1134	<a href="command-line-options.html#fx">-fx</a>,
				1135	<a href="command-line-options.html#gaussian-blur">-gaussian-blur</a>,
				1136	<a href="command-line-options.html#hald-clut">-hald-clut</a>,
				1137	<a href="command-line-options.html#motion-blur">-motion-blur</a>,
				1138	<a href="command-line-options.html#morphology">-morphology</a>,
				1139	<a href="command-line-options.html#negate">-negate</a>,
				1140	<a href="command-line-options.html#normalize">-normalize</a>,
				1141	<a href="command-line-options.html#ordered-dither">-ordered-dither</a>,
				1142	<a href="command-line-options.html#radial-blur">-radial-blur</a>,
				1143	<a href="command-line-options.html#random-threshold">-random-threshold</a>,
				1144	<a href="command-line-options.html#separate">-separate</a>,
				1145	<a href="command-line-options.html#threshold">-threshold</a>, and
				1146	<a href="command-line-options.html#white-threshold">-white-threshold</a>.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1147	</p>
				1148
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1149	<p>Warning, some operators behave differently when the <a href="command-line-options.html#channel"
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1150	>+channel</a> default setting is in effect, verses ANY user defined <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1151	href="command-line-options.html#channel" >-channel</a> setting (including the equivalent of the
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	1152	default). These operators have yet to be made to understand the newer 'Sync'
				1153	flag. </p>
				1154
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1155	<p>For example <a href="command-line-options.html#threshold">-threshold</a> will by default gray-scale
				1156	the image before thresholding, if no <a href="command-line-options.html#channel" >-channel</a> setting
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1157	has been defined. This is not 'Sync flag controlled, yet. </p>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1158
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1159	<p>Also some operators such as <a href="command-line-options.html#blur">-blur</a>, <a
				1160	href="command-line-options.html#gaussian-blur">-gaussian-blur</a>, will modify their handling of the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1161	color channels if the '<code>alpha</code>' channel is also enabled by <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1162	href="command-line-options.html#channel" >-channel</a>. Generally this done to ensure that
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1163	fully-transparent colors are treated as being fully-transparent, and thus any
				1164	underlying 'hidden' color has no effect on the final results. Typically
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1165	resulting in 'halo' effects. The newer <a href="command-line-options.html#morphology">-morphology</a>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1166	convolution equivalents however does have a understanding of the 'Sync' flag
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1167	and will thus handle transparency correctly by default. </p>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1168
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1169	<p>As a alpha channel is optional within images, some operators will read the
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1170	color channels of an image as a greyscale alpha mask, when the image has no
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1171	alpha channel present, and the <a href="command-line-options.html#channel" >-channel</a> setting tells
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	1172	the operator to apply the operation using alpha channels. The <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1173	href="command-line-options.html#clut">-clut</a> operator is a good example of this. </p>
				1174
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1175
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1176
				1177	<div style="margin: auto;">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1178	<h4><a id="charcoal"></a>-charcoal <em class="arg">factor</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1179	</div>
				1180
				1181	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Simulate a charcoal drawing.</td><td style='text-align:right;'></td></tr></table>
				1182
				1183	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1184	<h4><a id="chop"></a>-chop <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1185	</div>
				1186
				1187	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Remove pixels from the interior of an image.</td><td style='text-align:right;'></td></tr></table>
				1188
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1189	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <em class="arg">width</em>
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1190	and <em class="arg">height</em> given in the of the <em class="arg">size</em>
				1191	portion of the <em class="arg">geometry</em> argument give the number of
				1192	columns and rows to remove. The <em class="arg">offset</em> portion of
				1193	the <em class="arg">geometry</em> argument is influenced by
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1194	a <a href="command-line-options.html#gravity">-gravity</a> setting, if present.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1195
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1196	<p>The <a href="command-line-options.html#chop">-chop</a> option removes entire rows and columns,
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1197	and moves the remaining corner blocks leftward and upward to close the gaps.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1198
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	1199	<p>While it can remove internal rows and columns of pixels, it is more
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1200	typically used with as <a href="command-line-options.html#gravity">-gravity</a> setting and zero
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	1201	offsets so as to remove a single edge from an image. Compare this to <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1202	href="command-line-options.html#shave" >-shave</a> which removes equal numbers of pixels from oppisite
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	1203	sides of the image. </p>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1204
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1205	<p>Using <a href="command-line-options.html#chop">-chop</a> effectively undoes the results of a <a
				1206	href="command-line-options.html#splice">-splice</a> that was given the same <em
				1207	class="arg">geometry</em> and <a href="command-line-options.html#gravity">-gravity</a> settings. </p>
				1208
				1209	<div style="margin: auto;">
				1210	<h4><a id="clamp"></a>-clamp</h4>
				1211	</div>
				1212
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1213	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>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.</td><td style='text-align:right;'></td></tr></table>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1214
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1215	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1216	<h4><a id="clip"></a>-clip</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1217	</div>
				1218
				1219	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply the clipping path if one is present.</td><td style='text-align:right;'></td></tr></table>
				1220
				1221	<p>If a clipping path is present, it is applied to subsequent operations.</p>
				1222
				1223	<p>For example, in the command</p>
				1224
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1225	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert cockatoo.tif -clip -negate negated.tif</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1226	<p>only the pixels within the clipping path are negated.</p>
				1227
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1228	<p>The <a href="command-line-options.html#clip">-clip</a> feature requires SVG support. If the SVG
				1229	delegate library is not present, the option is ignored.</p>
				1230
				1231	<p>Use <a href="command-line-options.html#clip">+clip</a> to disable clipping for subsequent operations.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1232
				1233	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1234	<h4><a id="clip-mask"></a>-clip-mask</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1235	</div>
				1236
				1237	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Clip the image as defined by this mask.</td><td style='text-align:right;'></td></tr></table>
				1238
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1239	<p>Use the alpha channel of the current image as a mask. Any areas that is
				1240	white is not modified by any of the 'image processing operators' that follow,
				1241	until the mask is removed. Pixels in the black areas of the clip mask are
				1242	modified per the requirements of the operator. </p>
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	1243
				1244	<p>In some ways this is similar to (though not the same) as defining
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1245	a rectangular <a href="command-line-options.html#region" >-region</a>, or using the negative of the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1246	mask (third) image in a three image <a href="command-line-options.html#composite" >-composite</a>,
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	1247	operation. </p>
				1248
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1249	<p>Use <a href="command-line-options.html#clip-mask">+clip-mask</a> to disable clipping for subsequent operations.</p>
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	1250
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1251	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1252	<h4><a id="clip-path"></a>-clip-path <em class="arg">id</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1253	</div>
				1254
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1255	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Clip along a named path from the 8BIM profile.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1256
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1257	<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>
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	1258
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1259	<p>Use <a href="command-line-options.html#clip-path">+clip-path</a> to disable clipping for subsequent operations.</p>
cristy	3009279	2011-02-22 02:06:14 +0000	[diff] [blame]	1260
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1261	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1262	<h4><a id="clone"></a>-clone <em class="arg">index(s)</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1263	</div>
				1264
cristy	8b9dd95	2011-03-21 22:56:18 +0000	[diff] [blame]	1265	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>make a clone of an image (or images).</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1266
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1267	<p>Inside parenthesis (where the operator is normally used) it will make a
				1268	clone of the images from the last 'pushed' image sequence, and adds them to
				1269	the end of the current image sequence. Outside parenthesis
				1270	(not recommended) it clones the images from the current image sequence. </p>
				1271
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1272	<p>Specify the image by its index in the sequence. The first image is index
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1273	0. Negative indexes are relative to the end of the sequence; for
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1274	example, <code>−1</code>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1275	represents the last image of the sequence. Specify a range of images with a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1276	dash (e.g. <code>0−4</code>). Separate multiple indexes with commas but no
				1277	spaces (e.g. <code>0,2,5</code>). A value of '<code>0−−1</code> will
cristy	8b9dd95	2011-03-21 22:56:18 +0000	[diff] [blame]	1278	effectively clone all the images. </p>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1279
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1280	<p>The <a href="command-line-options.html#clone">+clone</a> will simply make a copy of the last image
cristy	baacd17	2011-04-30 23:11:03 +0000	[diff] [blame]	1281	in the image sequence, and is thus equivalent to using a argument of
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1282	'<code>−1</code>'. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1283
				1284	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1285	<h4><a id="clut"></a>-clut</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1286	</div>
				1287
				1288	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Replace the channel values in the first image using each
				1289	corresponding channel in the second image as a <b>c</b>olor
				1290	<b>l</b>ook<b>u</b>p <b>t</b>able.</td><td style='text-align:right;'></td></tr></table>
				1291
				1292	<p>The second (LUT) image is ordinarily a gradient image containing the
				1293	histogram mapping of how each channel should be modified. Typically it is a
				1294	either a single row or column image of replacement color values. If larger
				1295	than a single row or column, values are taken from a diagonal line from
				1296	top-left to bottom-right corners.</p>
				1297
				1298	<p>The lookup is further controlled by the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1299	href="command-line-options.html#interpolate">-interpolate</a> setting, which is especially handy for an
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1300	LUT which is not the full length needed by the ImageMagick installed Quality
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1301	(Q) level. Good settings for this are the '<code>bilinear</code>' and
				1302	'<code>bicubic</code>' interpolation settings, which give smooth color
				1303	gradients, and the '<code>integer</code>' setting for a direct, unsmoothed
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1304	lookup of color values. </p>
				1305
				1306	<p>This operator is especially suited to replacing a grayscale image with a
				1307	specific color gradient from the CLUT image. </p>
				1308
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1309	<p>Only the channel values defined by the <a href="command-line-options.html#channel">-channel</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1310	setting will have their values replaced. In particular, since the default <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1311	href="command-line-options.html#channel">-channel</a> setting is <code>RGB</code>, this means that
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1312	transparency (alpha/matte channel) is not affected, unless the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1313	href="command-line-options.html#channel">-channel</a> setting is modified. When the alpha channel is
				1314	set, it is treated by the <a href="command-line-options.html#clut" >-clut</a> operator in the same way
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1315	as the other channels, implying that alpha/matte values are replaced using the
				1316	alpha/matte values of the original image. </p>
				1317
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1318	<p>If either the image being modified, or the lookup image, contains no
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1319	transparency (i.e. <a href="command-line-options.html#alpha" >-alpha</a> is turned 'off') but the <a
				1320	href="command-line-options.html#channel">-channel</a> setting includes alpha replacement, then it is
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	1321	assumed that image represents a gray-scale gradient which is used for the
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1322	replacement alpha values. That is you can use a gray-scale CLUT image to
				1323	adjust a existing images alpha channel, or you can color a gray-scale image
				1324	using colors form CLUT containing the desired colors, including transparency.
				1325	</p>
				1326
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1327	<p>See also <a href="command-line-options.html#hald-clut" >-hald-clut</a> which replaces colors
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1328	according to the lookup of the full color RGB value from a 2D representation
				1329	of a 3D color cube. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1330
				1331
				1332	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1333	<h4><a id="coalesce"></a>-coalesce</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1334	</div>
				1335
				1336	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Fully define the look of each frame of an GIF animation sequence, to form a 'film strip' animation.</td><td style='text-align:right;'></td></tr></table>
				1337
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1338	<p>Overlay each image in an image sequence according to
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1339	its <a href="command-line-options.html#dispose">-dispose</a> meta-data, to reproduce the look of
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1340	an animation at each point in the animation sequence. All images should be
				1341	the same size, and are assigned appropriate GIF disposal settings for the
				1342	animation to continue working as expected as a GIF animation. Such frames
				1343	are more easily viewed and processed than the highly optimized GIF overlay
				1344	images. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1345
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1346	<p>The animation can be re-optimized after processing using
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1347	the <a href="command-line-options.html#layers">-layers</a> method '<code>optimize</code>', although
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1348	there is no guarantee that the restored GIF animation optimization is
				1349	better than the original. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1350
				1351
				1352	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1353	<h4><a id="colorize"></a>-colorize <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1354	</div>
				1355
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1356	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Colorize the image by an amount specified by <em class="arg">value</em> using the color specified by the most recent <a href="command-line-options.html#fill" >-fill</a> setting.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1357
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1358	<p>Specify the amount of colorization as a percentage. Separate colorization
				1359	values can be applied to the red, green, and blue channels of the image with
				1360	a comma-delimited list of colorization
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1361	values (e.g., <code>-colorize 0,0,50</code>).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1362
				1363	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1364	<h4><a id="colormap"></a>-colormap <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1365	</div>
				1366
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1367	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Define the colormap type.</td><td style='text-align:right;'>[<a href="animate.html">animate</a>, <a href="display.html">display</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1368
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1369	<p>The <em class="arg">type</em> can be <code>shared</code> or <code>private</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1370
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1371	<p>This option only applies when the default X server visual
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1372	is <code>PseudoColor</code> or <code>GrayScale</code>. Refer
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1373	to <a href="command-line-options.html#visual">-visual</a> for more details. By default,
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1374	a shared colormap is allocated. The image shares colors with
				1375	other X clients. Some image colors could be approximated,
				1376	therefore your image may look very different than intended.
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1377	If <code>private</code> is chosen, the image colors appear exactly
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1378	as they are defined. However, other clients may go <em>technicolor</em>
				1379	when the image colormap is installed.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1380
				1381	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1382	<h4><a id="colors"></a>-colors <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1383	</div>
				1384
				1385	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the preferred number of colors in the image.</td><td style='text-align:right;'></td></tr></table>
				1386
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1387	<p>The actual number of colors in the image may be less than your request,
				1388	but never more. Note that this a color reduction option. Images with fewer
				1389	unique colors than specified by <em class="arg">value</em> will have any
				1390	duplicate or unused colors removed. The ordering of an existing color
				1391	palette may be altered. When converting an image from color to grayscale,
				1392	it is more efficient to convert the image to the gray colorspace before
				1393	reducing the number of colors. Refer to
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1394	the <a href="quantize.html">
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1395	color reduction algorithm</a> for more details.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1396
				1397	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1398	<h4><a id="color-matrix"></a>-color-matrix <em class="arg">matrix</em></h4>
cristy	2c83960	2010-04-03 02:32:08 +0000	[diff] [blame]	1399	</div>
				1400
				1401	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>apply color correction to the image.</td><td style='text-align:right;'></td></tr></table>
				1402
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1403	<p>This option permits saturation changes, hue rotation, luminance to alpha,
				1404	and various other effects. Although variable-sized transformation matrices
				1405	can be used, typically one uses a 5x5 matrix for an RGBA image and a 6x6
				1406	for CMYKA (or RGBA with offsets). The matrix is similar to those used by
				1407	Adobe Flash except offsets are in column 6 rather than 5 (in support of
				1408	CMYKA images) and offsets are normalized (divide Flash offset by 255).</p>
cristy	2c83960	2010-04-03 02:32:08 +0000	[diff] [blame]	1409
				1410	<p>As an example, to add contrast to an image with offsets, try this command:</p>
				1411
				1412	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	1413	convert kittens.jpg -color-matrix \
				1414	" 1.5 0.0 0.0 0.0, 0.0, -0.157 \
				1415	0.0 1.5 0.0 0.0, 0.0, -0.157 \
				1416	0.0 0.0 1.5 0.0, 0.0, -0.157 \
				1417	0.0 0.0 0.0 1.0, 0.0, 0.0 \
				1418	0.0 0.0 0.0 0.0, 1.0, 0.0 \
				1419	0.0 0.0 0.0 0.0, 0.0, 1.0" kittens.png
cristy	2c83960	2010-04-03 02:32:08 +0000	[diff] [blame]	1420	</pre>
				1421	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1422	<h4><a id="colorspace"></a>-colorspace <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1423	</div>
				1424
				1425	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the image colorspace.</td><td style='text-align:right;'></td></tr></table>
				1426
				1427	<p>Choices are:</p>
				1428
				1429	<pre class="text">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1430	CMY CMYK Gray HCL
				1431	HCLp HSB HSI HSL
				1432	HSV HWB Lab LCHab
				1433	LCHuv LMS Log Luv
				1434	OHTA Rec601YCbCr Rec709YCbCr RGB
				1435	scRGB sRGB Transparent XYZ
				1436	YCbCr YCC YDbDr YIQ
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	1437	YPbPr YUV
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1438	</pre>
				1439
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1440	<p>To print a complete list of colorspaces, use <a href="command-line-options.html#list">-list colorspace</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1441
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1442	<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>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1443
				1444	<table class="doc">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1445	<caption>Conversion of RGB to Other Color Spaces</caption>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1446	<tr><th align="left" valign="middle">CMY</th></tr>
				1447	<tr><td align="left" valign="middle">C=<em class="QR">QuantumRange</em>−R</td></tr>
				1448	<tr><td align="left" valign="middle">M=<em class="QR">QuantumRange</em>−G</td></tr>
				1449	<tr><td align="left" valign="middle">Y=<em class="QR">QuantumRange</em>−B</td></tr>
				1450	<tr><th align="left" valign="middle">CMYK — starts with CMY from above</th></tr>
				1451	<tr><td align="left" valign="middle">K=min(C,Y,M)</td></tr>
				1452	<tr><td align="left" valign="middle">C=<em class="QR">QuantumRange</em>*(C−K)/(<em class="QR">QuantumRange</em>−K)</td></tr>
				1453	<tr><td align="left" valign="middle">M=<em class="QR">QuantumRange</em>*(M−K)/(<em class="QR">QuantumRange</em>−K)</td></tr>
				1454	<tr><td align="left" valign="middle">Y=<em class="QR">QuantumRange</em>*(Y−K)/(<em class="QR">QuantumRange</em>−K)</td></tr>
				1455
				1456	<tr><th align="left" valign="middle">Gray</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1457	<tr><td align="left" valign="middle">Gray = 0.298839R+0.586811G+0.114350*B</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1458
				1459	<tr><th align="left" valign="middle">HSB — Hue, Saturation, Brightness; like a cone peak downward</th></tr>
				1460	<tr><td align="left" valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr>
				1461	<tr><td align="left" valign="middle">S=distance from axis outward</td></tr>
				1462	<tr><td align="left" valign="middle">B=distance along axis from bottom upward; B=max(R,G,B); <em>intensity-like</em></td></tr>
				1463
				1464	<tr><th align="left" valign="middle">HSL — Hue, Saturation, Lightness; like a double cone end-to-end with peaks at very top and bottom</th></tr>
				1465	<tr><td align="left" valign="middle">H=angle around perimeter (0 to 360 deg); H=0 is red; increasing angles toward green</td></tr>
				1466	<tr><td align="left" valign="middle">S=distance from axis outward</td></tr>
				1467	<tr><td align="left" valign="middle">L=distance along axis from bottom upward; L=0.5max(R,G,B) + 0.5min(R,G,B); <em>intensity-like</em></td></tr>
				1468
				1469	<tr><th align="left" valign="middle">HWB — Hue, Whiteness, Blackness</th></tr>
				1470	<tr><td align="left" valign="middle">Hue (complicated equation)</td></tr>
				1471	<tr><td align="left" valign="middle">Whiteness (complicated equation)</td></tr>
				1472	<tr><td align="left" valign="middle">Blackness (complicated equation)</td></tr>
				1473
				1474	<tr><th align="left" valign="middle">LAB</th></tr>
				1475	<tr><td align="left" valign="middle">L (complicated equation relating X,Y,Z)</td></tr>
				1476	<tr><td align="left" valign="middle">A (complicated equation relating X,Y,Z)</td></tr>
				1477	<tr><td align="left" valign="middle">B (complicated equation relating X,Y,Z)</td></tr>
				1478
				1479	<tr><th align="left" valign="middle">LOG</th></tr>
				1480	<tr><td align="left" valign="middle">I1 (complicated equation involving logarithm of R)</td></tr>
				1481	<tr><td align="left" valign="middle">I2 (complicated equation involving logarithm of G)</td></tr>
				1482	<tr><td align="left" valign="middle">I3 (complicated equation involving logarithm of B)</td></tr>
				1483
				1484	<tr><th align="left" valign="middle">OHTA — approximates principal components transformation</th></tr>
				1485	<tr><td align="left" valign="middle">I1=0.33333R+0.33334G+0.33333*B; <em>intensity-like</em></td></tr>
				1486	<tr><td align="left" valign="middle">I2=(0.50000R+0.00000G−0.50000B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1487	<tr><td align="left" valign="middle">I3=(−0.25000R+0.50000G−0.25000B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1488
				1489	<tr><th align="left" valign="middle">Rec601Luma</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1490	<tr><td align="left" valign="middle">Gray = 0.298839R+0.586811G+0.114350*B</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1491
				1492	<tr><th align="left" valign="middle">Rec601YCbCr</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1493	<tr><td align="left" valign="middle">Y=0.2988390R+0.5868110G+0.1143500*B; <em>intensity-like</em></td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1494	<tr><td align="left" valign="middle">Cb=(−0.168736R-0.331264G+0.500000B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1495	<tr><td align="left" valign="middle">Cr=(0.500000R−0.418688G−0.081312B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1496
				1497	<tr><th align="left" valign="middle">Rec709Luma</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1498	<tr><td align="left" valign="middle">Gray=0.212656R+0.715158G+0.072186*B</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1499
				1500	<tr><th align="left" valign="middle">Rec709YCbCr</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1501	<tr><td align="left" valign="middle">Y=0.212656R+0.715158G+0.072186*B; <em>intensity-like</em></td></tr>
				1502	<tr><td align="left" valign="middle">Cb=(−0.114572R−0.385428G+0.500000*B)+(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1503	<tr><td align="left" valign="middle">Cr=(0.500000R−0.454153G−0.045847*B)+(<em class="QR">QuantumRange</em>+1)/2</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1504
				1505	<tr><th align="left" valign="middle">sRGB</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1506	<tr><td align="left" valign="middle">if R ≤ .0.0031308 then Rs=R/12.92 else Rs=1.055 R ^ (1.0 / 2.4) ? 0.055</td></tr>
				1507	<tr><td align="left" valign="middle">if G ≤ .0.0031308 then Gs=B/12.92 else Gs=1.055 R ^ (1.0 / 2.4) ? 0.055</td></tr>
				1508	<tr><td align="left" valign="middle">if B ≤ .0.0031308 then Bs=B/12.92 else Bs=1.055 R ^ (1.0 / 2.4) ? 0.055</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1509
				1510	<tr><th align="left" valign="middle">XYZ</th></tr>
				1511	<tr><td align="left" valign="middle">X=0.4124240R+0.3575790G+0.1804640*B</td></tr>
cristy	bf2eb89	2013-06-07 00:33:05 +0000	[diff] [blame]	1512	<tr><td align="left" valign="middle">Y=0.212656R+0.715158G+0.0721856*B</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1513	<tr><td align="left" valign="middle">Z=0.0193324R+0.1191930G+0.9504440*B</td></tr>
				1514
				1515	<tr><th align="left" valign="middle">YCC</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1516	<tr><td align="left" valign="middle">Y=(0.298839R+0.586811G+0.114350*B) (with complicated scaling); <em>intensity-like</em></td></tr>
				1517	<tr><td align="left" valign="middle">C1=(−0.298839R−0.586811G+0.88600*B) (with complicated scaling)</td></tr>
				1518	<tr><td align="left" valign="middle">C2=(0.70100R−0.586811G−0.114350*B) (with complicated scaling)</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1519
				1520	<tr><th align="left" valign="middle">YCbCr</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1521	<tr><td align="left" valign="middle">Y=0.2988390R+0.5868110G+0.1143500*B; <em>intensity-like</em></td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1522	<tr><td align="left" valign="middle">Cb=(−0.168736R−0.331264G+0.500000B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1523	<tr><td align="left" valign="middle">Cr=(0.500000R−0.418688G−0.081312B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1524
				1525	<tr><th align="left" valign="middle">YIQ</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1526	<tr><td align="left" valign="middle">Y=0.298839R+0.586811G+0.114350*B; <em>intensity-like</em></td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1527	<tr><td align="left" valign="middle">I=(0.59600R−0.27400G−0.32200B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1528	<tr><td align="left" valign="middle">Q=(0.21100R−0.52300G+0.31200B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1529
				1530	<tr><th align="left" valign="middle">YPbPr</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1531	<tr><td align="left" valign="middle">Y=0.2988390R+0.5868110G+0.1143500*B; <em>intensity-like</em></td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1532	<tr><td align="left" valign="middle">Pb=(−0.168736R−0.331264G+0.500000B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1533	<tr><td align="left" valign="middle">Pr=(0.500000R−0.418688G−0.081312B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1534
				1535	<tr><th align="left" valign="middle">YUV</th></tr>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1536	<tr><td align="left" valign="middle">Y=0.298839R+0.586811G+0.114350*B; <em>intensity-like</em></td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1537	<tr><td align="left" valign="middle">U=(−0.14740R−0.28950G+0.43690B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1538	<tr><td align="left" valign="middle">V=(0.61500R−0.51500G−0.10000B)(<em class="QR">QuantumRange</em>+1)/2</td></tr>
				1539	</table>
				1540
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1541	<p>Note the scRGB colorspace requires HDRI support otherwise it behaves just like linear RGB.</p>
				1542
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1543	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1544	<h4><a id="combine"></a>-combine</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1545	</div>
				1546
				1547	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Combine one or more images into a single image.</td><td style='text-align:right;'></td></tr></table>
				1548
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1549	<p>The channels (previously set by <a href="command-line-options.html#channel">-channel</a>) of the
				1550	combined image are taken from the grayscale values of each image in the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1551	sequence, in order. For the default -channel setting of <code>RGB</code>, this
				1552	means the first image is assigned to the <code>Red</code> channel, the second
				1553	to the <code>Green</code> channel, the third to the <code>Blue</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1554
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1555	<p>This option can be thought of as the inverse to <a
				1556	href="command-line-options.html#separate">-separate</a>, so long as the channel settings are the same.
				1557	Thus, in the following example, the final image should be a copy of the
				1558	original. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1559
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1560	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert original.png -channel RGB -separate sepimage.png</span><span class='crtout'></span><span class="crtprompt"> $ </span><span class='crtin'>convert sepimage-0.png sepimage-1.png sepimage-2.png -channel RGB \ <br/> -combine imagecopy.png</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1561	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1562	<h4><a id="comment"></a>-comment <em class="arg">string</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1563	</div>
				1564
				1565	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Embed a comment in an image.</td><td style='text-align:right;'></td></tr></table>
				1566
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1567	<p>This option sets the comment meta-data of an image read in after this
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	1568	option has been given. To modify a comment of images already in memory use
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1569	"<code><a href="command-line-options.html#set">-set</a> comment</code>". </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1570
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	1571	<p>The comment can contain special format characters listed in the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1572	href="escape.html">Format and
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	1573	Print Image Properties</a>. These attributes are expanded when the comment
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	1574	is finally assigned to the individual images. </p>
				1575
				1576	<p>If the first character of <em class="arg">string</em> is <em
				1577	class="arg">@</em>, the image comment is read from a file titled by the
				1578	remaining characters in the string. Comments read in from a file are literal;
				1579	no embedded formatting characters are recognized.</p>
				1580
				1581	<p>Comment meta-data are not visible on the image itself. To do that use the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1582	<a href="command-line-options.html#annotate">-annotate</a> or <a href="command-line-options.html#draw">-draw</a> options
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	1583	instead.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1584
				1585	<p>For example,</p>
				1586
				1587	<p class="crtsnip">
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	1588	-comment "%m:%f %wx%h" bird.miff
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1589	</p>
				1590
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1591	<p>produces an image comment of <code>MIFF:bird.miff 512x480</code> (assuming
				1592	that the image <code>bird.miff</code> has a width of 512 and a height of
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	1593	480.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1594
				1595	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1596	<h4><a id="compose"></a>-compose <em class="arg">operator</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1597	</div>
				1598
				1599	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the type of image composition.</td><td style='text-align:right;'></td></tr></table>
				1600
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1601	<p>See <a href="compose.html">Alpha Compositing</a> for
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	1602	a detailed discussion of alpha compositing.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1603
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	1604	<p>This setting effects image processing operators that merge two (or more)
				1605	images together in some way. This includes the operators,
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1606	<a href="command-line-options.html#composite">-composite</a>,
				1607	<a href="command-line-options.html#layers">-layers</a> composite,
				1608	<a href="command-line-options.html#flatten">-flatten</a>,
				1609	<a href="command-line-options.html#mosaic">-mosaic</a>,
				1610	<a href="command-line-options.html#layers">-layers</a> merge,
				1611	<a href="command-line-options.html#border">-border</a>,
				1612	<a href="command-line-options.html#frame">-frame</a>,
				1613	and <a href="command-line-options.html#extent">-extent</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1614
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1615	<p>It is also one of the primary options for the "<code>composite</code>"
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	1616	command. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1617
				1618
				1619	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1620	<h4><a id="composite"></a>-composite</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1621	</div>
				1622
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	1623	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Perform alpha composition on two images and an optional mask</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1624
				1625	<p>Take the first image 'destination' and overlay the second 'source' image
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1626	according to the current <a href="command-line-options.html#compose">-compose</a> setting. The location
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1627	of the 'source' or 'overlay' image is controlled according to <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1628	href="command-line-options.html#geometry" >-geometry</a>, and <a href="command-line-options.html#geometry" >-geometry</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1629	settings. </p>
				1630
				1631	<p>If a third image is given this is treated as a gray-scale 'mask' image
				1632	relative to the first 'destination' image. This mask will limit what parts of
				1633	the destination can be modified by the image composition. However for the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1634	'<code>displace</code>' compose method, the mask is used to provide a separate
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1635	Y-displacement image instead. </p>
				1636
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1637	<p>If a <a href="command-line-options.html#compose">-compose</a> method requires extra numerical
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1638	arguments or flags these can be provided by setting the <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1639	href="command-line-options.html#set">-set</a> '<code class="arg">option:compose:args</code>'
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1640	appropriately for the compose method. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1641
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1642	<p>Some <a href="command-line-options.html#compose">-compose</a> methods can modify the 'destination'
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1643	image outside the overlay area. You can disable this by setting the special <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1644	href="command-line-options.html#set">-set</a> '<code class="arg">option:compose:outside-overlay</code>'
				1645	to '<code>false</code>'. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1646
				1647
				1648	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1649	<h4><a id="compress"></a>-compress <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1650	</div>
				1651
				1652	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Use pixel compression specified by <em class="arg">type</em> when writing the image.</td><td style='text-align:right;'></td></tr></table>
				1653
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1654	<p>Choices are: <code class="arg">None</code>, <code class="arg">BZip</code>, <code
				1655	class="arg">Fax</code>, <code class="arg">Group4</code>, <code
				1656	class="arg">JPEG</code>, <code class="arg">JPEG2000</code>, <code
				1657	class="arg">Lossless</code>, <code class="arg">LZW</code>, <code
				1658	class="arg">RLE</code> or <code class="arg">Zip</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1659
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1660	<p>To print a complete list of compression types, use <a href="command-line-options.html#list">-list
				1661	compress</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1662
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1663	<p>Specify <a href="command-line-options.html#compress">+compress</a> to store the binary image in an
				1664	uncompressed format. The default is the compression type of the specified
				1665	image file.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1666
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1667	<p>If <code>LZW</code> compression is specified but LZW compression has not been
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1668	enabled, the image data is written in an uncompressed LZW format that can be
				1669	read by LZW decoders. This may result in larger-than-expected GIF files.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1670
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1671	<p><code>Lossless</code> refers to lossless JPEG, which is only available if the
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1672	JPEG library has been patched to support it. Use of lossless JPEG is generally
				1673	not recommended.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1674
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1675	<p>
				1676	When writing an ICO file, you may request that the images be encoded in
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1677	PNG format, by specifying <code>Zip</code> compression.</p>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1678
				1679	<p>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1680	When writing a JNG file, specify <code>Zip</code> compression to request that
				1681	the alpha channel be encoded in PNG "IDAT" format, or <code>JPEG</code>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1682	to request that it be encoded in JPG "JDAA" format.</p>
				1683
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1684	<p>Use the <a href="command-line-options.html#quality">-quality</a> option to set the compression level
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1685	to be used by JPEG, PNG, MIFF, and MPEG encoders.
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1686	Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to set the
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1687	sampling factor to be used by JPEG, MPEG, and YUV encoders for down-sampling
				1688	the chroma channels.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1689
				1690	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1691	<h4><a id="contrast"></a>-contrast</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1692	</div>
				1693
				1694	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Enhance or reduce the image contrast.</td><td style='text-align:right;'></td></tr></table>
				1695
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1696	<p>This option enhances the intensity differences between the lighter and
				1697	darker elements of the image. Use <a href="command-line-options.html#contrast">-contrast</a> to enhance
				1698	the image or <a href="command-line-options.html#contrast">+contrast</a> to reduce the image
				1699	contrast.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1700
				1701	<p>For a more pronounced effect you can repeat the option:</p>
				1702
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1703	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert rose: -contrast -contrast rose_c2.png</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1704	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1705	<h4><a id="contrast-stretch"></a>-contrast-stretch <em class="arg">black-point</em><br />-contrast-stretch <em class="arg">black-point</em>{x<em class="arg">white-point</em>}{<em class="arg">%</em>}}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1706	</div>
				1707
				1708	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Increase the contrast in an image by <em>stretching</em> the range of intensity values.</td><td style='text-align:right;'></td></tr></table>
				1709
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1710	<p>While performing the stretch, black-out at most <em
				1711	class="arg" >black-point</em> pixels and white-out at most <em
				1712	class="arg" >white-point</em> pixels. Or, if percent is used, black-out at most
				1713	<em class="arg" >black-point %</em> pixels and white-out at most <em
				1714	class="arg" >white-point %</em> pixels.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1715
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1716	<p>Prior to ImageMagick 6.4.7-0, <a href="command-line-options.html#contrast-stretch"
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1717	>-contrast-stretch</a> will black-out at most <em class="arg"
				1718	>black-point</em> pixels and white-out at most <em class="arg" >total pixels
				1719	minus white-point</em> pixels. Or, if percent is used, black-out at most <em
				1720	class="arg">black-point %</em> pixels and white-out at most <em class="arg"
				1721	>100% minus white-point %</em> pixels.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1722
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1723	<p>Note that <code>-contrast-stretch 0</code> will modify the image such that
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1724	the image's min and max values are stretched to 0 and <em class="QR"
				1725	>QuantumRange</em>, respectively, without any loss of data due to burn-out or
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1726	clipping at either end. This is not the same as <a href="command-line-options.html#normalize"
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1727	>-normalize</a>, which is equivalent to <code>-contrast-stretch 0.15x0.05%</code> (or
				1728	prior to ImageMagick 6.4.7-0, <code>-contrast-stretch 2%x99%</code>).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1729
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1730	<p>Internally operator works by creating a histogram bin, and then uses that
				1731	bin to modify the image. As such some colors may be merged together when they
				1732	originally fell into the same 'bin'. </p>
				1733
				1734	<p>All the channels are normalized in concert by the came amount so as to
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1735	preserve color integrity, when the default <a href="command-line-options.html#channel" >+channel</a>
				1736	setting is in use. Specifying any other <a href="command-line-options.html#channel" >-channel</a>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1737	setting will normalize the RGB channels independently.</p>
				1738
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1739	<p>See also <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect'
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1740	normalization of mathematical images. </p>
				1741
				1742	<p>This operator is under review for re-development. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1743
				1744
				1745	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1746	<h4><a id="convolve"></a>-convolve <em class="arg">kernel</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1747	</div>
				1748
				1749	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Convolve an image with a user-supplied convolution kernel.</td><td style='text-align:right;'></td></tr></table>
				1750
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	1751	<p>The <em class="arg">kernel</em> is a matrix specified as
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1752	a comma-separated list of integers (with no spaces), ordered left-to right,
				1753	starting with the top row. Presently, only odd-dimensioned kernels are
				1754	supported, and therefore the number of entries in the specified <em
				1755	class="arg">kernel</em> must be 3<sup>2</sup>=9, 5<sup>2</sup>=25,
				1756	7<sup>2</sup>=49, etc. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1757
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1758	<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
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1759	positive and negative results are relative to a user-specified bias value.
				1760	This is important for non-HDRI compilations of ImageMagick when dealing with
				1761	convolutions that contain negative as well as positive values. This is
				1762	especially the case with convolutions involving high pass filters or edge
				1763	detection. Without an output bias, the negative values is clipped at zero.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1764	</p>
				1765
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1766	<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
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1767	negative results without clipping to the color value range (0..QuantumRange).
				1768	See the discussion on HDRI implementations of ImageMagick on the page <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1769	href="high-dynamic-range.html">High
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	1770	Dynamic-Range Images</a>. For more about HDRI go the ImageMagick <a
				1771	href="http://www.imagemagick.org/Usage/basics/#hdri">Usage</a> pages or this
				1772	<a href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging">Wikipedia</a>
				1773	entry. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1774
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1775
				1776	<div style="margin: auto;">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1777	<h4><a id="crop"></a>-crop <em class="arg">geometry</em>{<em class="arg">@</em>}{<em class="arg">!</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1778	</div>
				1779
				1780	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Cut out one or more rectangular regions of the image.</td><td style='text-align:right;'></td></tr></table>
				1781
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1782	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1783
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1784	<p>The <em class="arg">width</em> and <em class="arg">height</em> of the <em
				1785	class="arg">geometry</em> argument give the size of the image that remains
				1786	after cropping, and <em class="arg">x</em> and <em class="arg">y</em> in the
				1787	<em class="arg">offset</em> (if present) gives the location of the top left
				1788	corner of the cropped image with respect to the original image. To specify the
				1789	amount to be removed, use <a href="command-line-options.html#shave">-shave</a> instead.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1790
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1791	<p>If the <em class="arg">x</em> and <em class="arg">y</em> offsets are
				1792	present, a single image is generated, consisting of the pixels from the
				1793	cropping region. The offsets specify the location of the upper left corner of
				1794	the cropping region measured downward and rightward with respect to the upper
				1795	left corner of the image. If the <a href="command-line-options.html#gravity">-gravity</a> option is
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1796	present with <code>NorthEast</code>, <code>East</code>, or <code>SouthEast</code>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1797	gravity, it gives the distance leftward from the right edge of the image to
				1798	the right edge of the cropping region. Similarly, if the <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1799	href="command-line-options.html#gravity">-gravity</a> option is present with <code>SouthWest</code>,
				1800	<code>South</code>, or <code>SouthEast</code> gravity, the distance is measured
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1801	upward between the bottom edges.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1802
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1803	<p>If the <em class="arg">x</em> and <em class="arg">y</em> offsets are
				1804	omitted, a set of tiles of the specified geometry, covering the entire input
				1805	image, is generated. The rightmost tiles and the bottom tiles are smaller if
				1806	the specified geometry extends beyond the dimensions of the input image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1807
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1808	<p>You can add the <em class="arg">@</em> to the geometry argument to equally divide the image into the number of tiles generated.</p>
				1809
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1810	<p>By adding a exclamation character flag to the geometry argument, the
				1811	cropped images virtual canvas page size and offset is set as if the
				1812	geometry argument was a viewport or window. This means the canvas page size
				1813	is set to exactly the same size you specified, the image offset set
				1814	relative top left corner of the region cropped. </p>
				1815
				1816	<p>If the cropped image 'missed' the actual image on its virtual canvas, a
				1817	special single pixel transparent 'missed' image is returned, and a 'crop
				1818	missed' warning given. </p>
				1819
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1820	<p>It might be necessary to <a href="command-line-options.html#repage" >+repage</a> the image prior to
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1821	cropping the image to ensure the crop coordinate frame is relocated to the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1822	upper-left corner of the visible image.
				1823
				1824	Similarly you may want to use <a href="command-line-options.html#repage" >+repage</a> after cropping to
				1825	remove the page offset that will be left behind. This is especially true when
				1826	you are going to write to an image format such as PNG that supports an image
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1827	offset.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1828
				1829	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1830	<h4><a id="cycle"></a>-cycle <em class="arg">amount</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1831	</div>
				1832
				1833	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>displace image colormap by amount.</td><td style='text-align:right;'></td></tr></table>
				1834
				1835	<p><em class="arg">Amount</em> defines the number of positions each
				1836	colormap entry is shifted.</p>
				1837
				1838
				1839	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1840	<h4><a id="debug"></a>-debug <em class="arg">events</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1841	</div>
				1842
				1843	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>enable debug printout.</td><td style='text-align:right;'></td></tr></table>
				1844
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1845	<p>The <code>events</code> parameter specifies which events are to be logged. It
				1846	can be either <code>None</code>, <code>All</code>, <code>Trace</code>, or
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1847	a comma-separated list consisting of one or more of the following domains:
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1848	<code>Accelerate</code>, <code>Annotate</code>, <code>Blob</code>, <code>Cache</code>,
				1849	<code>Coder</code>, <code>Configure</code>, <code>Deprecate</code>,
				1850	<code>Exception</code>, <code>Locale</code>, <code>Render</code>,
				1851	<code>Resource</code>, <code>Security</code>, <code>TemporaryFile</code>,
				1852	<code>Transform</code>, <code>X11</code>, or <code>User</code>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1853
				1854
				1855	<p>For example, to log cache and blob events, use.</p>
				1856
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1857	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert -debug "Cache,Blob" rose: rose.png</span></p>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1858	<p>The <code>User</code> domain is normally empty, but developers can log user
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1859	events in their private copy of ImageMagick.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1860
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1861	<p>To print the complete list of debug methods, use <a href="command-line-options.html#list">-list
				1862	debug</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1863
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1864	<p>Use the <a href="command-line-options.html#log">-log</a> option to specify the format for debugging
				1865	output.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1866
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1867	<p>Use <a href="command-line-options.html#debug">+debug</a> to turn off all logging.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1868
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1869	<p>Debugging may also be set using the <code>MAGICK_DEBUG</code> <a href="resources.html#environment"
				1870	>environment variable</a>. The allowed values for the <code>MAGICK_DEBUG</code>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1871	environment variable are the same as for the <a href="command-line-options.html#debug">-debug</a>
				1872	option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1873
				1874
				1875	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1876	<h4><a id="decipher"></a>-decipher <em class="arg">filename</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1877	</div>
				1878
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1879	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Decipher and restore pixels that were previously transformed by
				1880	<a href="command-line-options.html#encipher">-encipher</a>.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1881
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1882	<p>Get the passphrase from the file specified by <em
				1883	class="arg">filename</em>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1884
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1885	<p>For more information, see the webpage, <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1886	href="http://www.imagemagick.org/www/cipher.html">ImageMagick: Encipher or
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1887	Decipher an Image</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1888
				1889
				1890	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1891	<h4><a id="deconstruct"></a>-deconstruct</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1892	</div>
				1893
				1894	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>find areas that has changed between images </td><td style='text-align:right;'></td></tr></table>
				1895
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1896	<p>Given a sequence of images all the same size, such as produced by <a
				1897	href="command-line-options.html#coalesce">-coalesce</a>, replace the second and later images, with
				1898	a smaller image of just the area that changed relative to the previous image.
				1899	</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1900
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1901	<p>The resulting sequence of images can be used to optimize an animation
				1902	sequence, though will not work correctly for GIF animations when parts of the
				1903	animation can go from opaque to transparent. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1904
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1905	<p>This option is actually equivalent to the <a href="command-line-options.html#layers">-layers</a>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1906	method '<code>compare-any</code>'. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1907
				1908
				1909	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1910	<h4><a id="define"></a>-define <em class="arg">key</em>{<em class="arg">=value</em>}<em class="arg">...</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1911	</div>
				1912
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	1913	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>add specific global settings generally used to control
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1914	coders and image processing operations.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1915
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1916	<p>This option creates one or more definitions for coders and decoders to use
				1917	while reading and writing image data. Definitions are generally used to
				1918	control image file format coder modules, and image processing operations,
				1919	beyond what is provided by normal means. Defined settings are listed in <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1920	href="command-line-options.html#verbose" >-verbose</a> information ("<code>info:</code>" output format)
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1921	as "Artifacts". </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1922
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1923	<p>If <em class="arg">value</em> is missing for a definition, an empty-valued
				1924	definition of a flag is created with that name. This used to control on/off
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1925	options. Use <a href="command-line-options.html#define">+define key</a> to remove definitions
				1926	previously created. Use <a href="command-line-options.html#define">+define "*"</a> to remove all
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1927	existing definitions.</p>
				1928
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	1929	<p>The same 'artifact' settings can also be defined using the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1930	href="command-line-options.html#set" >-set "option:<em class="arg">key</em>" "<em class="arg"
				1931	>value</em>"</a> option, which also allows the use of <a href="escape.html" >Format and Print Image
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1932	Properties</a> in the defined value. </p>
				1933
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1934	<p>The <em>option</em> and <em>key</em> are case-independent (they are
				1935	converted to lowercase for use within the decoders) while the <em>value</em>
				1936	is case-dependent.</p>
				1937
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1938	<p>Such settings are global in scope, and affect all images and operations. </p>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1939
				1940	<p>The following definitions are just some of the artifacts that are
				1941	available:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1942
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1943	<dl>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1944
				1945	<dt>compose:args=<em class="arg">arguments</em></dt>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1946	<dd>Sets certain compose argument values when using convert ... -compose ...
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1947	-composite. See <a href="http://www.imagemagick.org/www/compose.html"
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1948	>Image Composition</a></dd>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1949
				1950	<dt>distort:scale=<em class="arg">value</em></dt>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1951	<dd>Sets the output scaling factor for use with <a href="command-line-options.html#distort"
				1952	>-distort</a></dd>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1953
				1954	<dt>distort:viewport=WxH+X+Y</dt>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	1955	<dd>Sets the viewport for use with <a href="command-line-options.html#distort">-distort</a></dd>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	1956
cristy	045bd90	2010-01-30 18:56:24 +0000	[diff] [blame]	1957	<dt>dcm:display-range=reset</dt>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1958	<dd>Set the display range to the minimum and maximum pixel values for the
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1959	DCM image format.</dd>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1960
cristy	045bd90	2010-01-30 18:56:24 +0000	[diff] [blame]	1961	<dt>dot:layout-engine=<em class="arg">value</em></dt>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1962	<dd>Set the specify the layout engine for the DOT image format (e.g.
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1963	<code>neato</code>).</dd>
				1964
				1965	<dt>jpeg:colors=<em class="arg">value</em></dt>
				1966	<dd>Set the desired number of colors and let the JPEG encoder do the
				1967	quantizing.</dd>
				1968
				1969	<dt>jpeg:block-smoothing=<em class="arg">on\|off</em></dt>
				1970
				1971	<dt>jpeg:dct-method=<em class="arg">value</em></dt>
				1972	<dd>Choose from <code>default</code>, <code>fastest</code>, <code>float</code>,
				1973	<code>ifast</code>, and <code>islow</code>.</dd>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1974
cristy	045bd90	2010-01-30 18:56:24 +0000	[diff] [blame]	1975	<dt>jpeg:extent=<em class="arg">value</em></dt>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1976	<dd>Restrict the maximum JPEG file size, for example <code>-define
				1977	jpeg:extent=400kb</code>. The JPEG encoder will search for the highest
				1978	compression quality level that results in an output file that does not
				1979	exceed the value. The <code>-quality</code> option is ignored if it
				1980	is also present.</dd>
				1981
				1982	<dt>jpeg:fancy-upsampling=<em class="arg">on\|off</em></dt>
				1983
				1984	<dt>jpeg:optimize-coding=<em class="arg">on\|off</em></dt>
				1985
				1986	<dt>jpeg:q-table=<em class="arg">table</em></dt>
				1987
				1988	<dt>jpeg:sampling-factor=<em class="arg">sampling-factor-string</em></dt>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1989
cristy	045bd90	2010-01-30 18:56:24 +0000	[diff] [blame]	1990	<dt>jpeg:size=<em class="arg">geometry</em></dt>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	1991	<dd>Set the size hint of a JPEG image, for
				1992	example, <code>-define jpeg:size=128x128</code>.
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1993	It is most useful for increasing performance and reducing the memory
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	1994	requirements when reducing the size of a large JPEG image.</dd>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1995
cristy	045bd90	2010-01-30 18:56:24 +0000	[diff] [blame]	1996	<dt>jp2:rate=<em class="arg">value</em></dt>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	1997	<dd>Specify the compression factor to use while writing JPEG-2000 files. The
				1998	compression factor is the reciprocal of the compression ratio. The valid
				1999	range is 0.0 to 1.0, with 1.0 indicating lossless compression. If defined,
				2000	this value overrides the -quality setting. A quality setting of 75
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2001	results in a rate value of 0.06641.</dd>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2002
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2003	<dt>mng:need-cacheoff</dt>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2004	<dd>turn playback caching off for streaming MNG.</dd>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2005
cristy	045bd90	2010-01-30 18:56:24 +0000	[diff] [blame]	2006	<dt>png:bit-depth=<em class="arg">value</em></dt>
				2007	<dt>png:color-type=<em class="arg">value</em></dt>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2008	<dd>desired bit-depth and color-type for PNG output. You can force the PNG
				2009	encoder to use a different bit-depth and color-type than it would have
				2010	normally selected, but only if this does not cause any loss of image
				2011	quality. Any attempt to reduce image quality is treated as an error and no
				2012	PNG file is written. E.g., if you have a 1-bit black-and-white image, you
				2013	can use these "defines" to cause it to be written as an 8-bit grayscale,
				2014	indexed, or even a 64-bit RGBA. But if you have a 16-million color image,
				2015	you cannot force it to be written as a grayscale or indexed PNG. If you
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2016	wish to do this, you must use the appropriate <a href="command-line-options.html#depth">-depth</a>,
				2017	<a href="command-line-options.html#colors">-colors</a>, or <a href="command-line-options.html#type">-type</a> directives to
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2018	reduce the image quality prior to using the PNG encoder. Note that in
				2019	indexed PNG files, "bit-depth" refers to the number of bits per index,
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	2020	which can be 1, 2, 4, or 8. In such files, the color samples always have
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2021	8-bit depth.</dd>
				2022
cristy	a4dfb12	2011-07-07 19:01:57 +0000	[diff] [blame]	2023	<dt>png:compression-filter=<em class="arg">value</em></dt>
				2024	<dd> valid values are 0 through 7. 0-4 are the corresponding PNG filters,
				2025	5 means adaptive filtering except for images with a colormap, 6 means
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2026	adaptive filtering for all images, 7 means MNG "loco" compression.</dd>
cristy	a4dfb12	2011-07-07 19:01:57 +0000	[diff] [blame]	2027
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	2028	<dt>png:compression-level=<em class="arg">value</em></dt>
				2029	<dd> valid values are 0 through 9, with 0 providing the least but fastest
				2030	compression and 9 usually providing the best and always the slowest.</dd>
				2031
				2032	<dt>png:compression-strategy=<em class="arg">value</em></dt>
				2033	<dd> valid values are 0 through 4, meaning default, filtered, huffman_only,
cristy	a4dfb12	2011-07-07 19:01:57 +0000	[diff] [blame]	2034	rle, and fixed ZLIB compression strategy. If you are using an old zlib
				2035	that does not support Z_RLE (before 1.2.0) or Z_FIXED (before 1.2.2.2),
				2036	values 3 and 4, respectively, will use the zlib default strategy
				2037	instead.</dd>
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	2038
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2039	<dt>png:format=<em class="arg">value</em></dt>
				2040	<dd> valid values are <em class="arg">png8</em>, <em class="arg">png24</em>,
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2041	<em class="arg">png32</em>, <em class="arg">png48</em>,
				2042	<em class="arg">png64</em>, and <em class="arg">png00</em>.
				2043	This property can be useful for specifying
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2044	the specific PNG format to be used, when the usual method of prepending the
				2045	format name to the output filename is inconvenient, such as when writing
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2046	a PNG-encoded ICO file.
				2047	Value = <em class="arg">png8</em> reduces the number of colors to 256,
				2048	only one of which may be fully transparent, if necessary. The other
				2049	values do not force any reduction of quality; it is an error to request
				2050	a format that cannot represent the image data without loss (except that
				2051	it is allowed to reduce the bit-depth from 16 to 8 for all formats).
				2052	Value = <em class="arg">png24</em> and <em class="arg">png48</em>
				2053	allow transparency, only if a single color is fully transparent and that
				2054	color does not also appear in an opaque pixel; such transparency is
				2055	written in a PNG <code>tRNS</code> chunk.
				2056	Value = <em class="arg">png00</em> causes the image to inherit its
				2057	color-type and bit-depth from the input image, if the input was also
				2058	a PNG.</dd>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2059
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2060	<dt>png:exclude-chunk=<em class="arg">value</em></dt>
				2061	<dt>png:include-chunk=<em class="arg">value</em></dt>
				2062	<dd>ancillary chunks to be excluded from or included in PNG output.
				2063
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2064	<p>The <em class="arg">value</em> can be the name of a PNG chunk-type such
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2065	as <em class="arg">bKGD</em>, a comma-separated list of chunk-types,
				2066	or the word <em class="arg">all</em> or
				2067	the word <em class="arg">none</em>. There must be no spaces in the
				2068	list. Although PNG chunk-names are case-dependent, you can use
				2069	all lowercase names if you prefer.</p>
				2070
cristy	d241f44	2011-03-29 13:50:49 +0000	[diff] [blame]	2071	<p>The "include-chunk" and "exclude-chunk" lists only affect the behavior
				2072	of the PNG encoder and have no effect on the PNG decoder.</p>
				2073
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2074	<p>As a special case, if the <code>sRGB</code> chunk is excluded and
				2075	the <code>gAMA</code> chunk is included, the <code>gAMA</code> chunk will
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2076	only be written if gamma is not 1/2.2, since most decoders assume
				2077	sRGB and gamma=1/2.2 when no colorspace information is included in
				2078	the PNG file. Because the list is processed from left to right, you
				2079	can achieve this with a single define:</p>
				2080
				2081	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	2082	-define png:include-chunk=none,gAMA
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2083	</pre>
				2084
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2085	<p>As a special case, if the <code>sRGB</code> chunk is not excluded and
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2086	the PNG encoder recognizes that the image contains the sRGB ICC profile,
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2087	the PNG encoder will write the <code>sRGB</code> chunk instead of the entire
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2088	3144-byte ICC profile. To force the PNG encoder to write the sRGB
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2089	profile as an <code>iCCP</code> chunk in the output PNG instead of the
				2090	<code>sRGB</code> chunk, exclude the <code>sRGB</code> chunk.</p>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2091
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2092	<p>The critical PNG chunks <code>IHDR</code>, <code>PLTE</code>,
				2093	<code>IDAT</code>, and <code>IEND</code> cannot be excluded. Any such
cristy	a4dfb12	2011-07-07 19:01:57 +0000	[diff] [blame]	2094	entries appearing in the list will be ignored.</p>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2095
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2096	<p>If the ancillary PNG <code>tRNS</code> chunk is excluded and the
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2097	image has transparency, the PNG colortype is forced to be 4 or 6
				2098	(GRAY_ALPHA or RGBA). If the image is not transparent, then the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2099	<code>tRNS</code> chunk isn't written anyhow, and there is no effect
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2100	on the PNG colortype of the output image.</p>
				2101
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2102	<p>The <a href="command-line-options.html#strip">-strip</a> option does the equivalent of the
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2103	following for PNG output:</p>
				2104
				2105	<pre class="text">
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2106	-define png:include-chunk=none,trns,gama
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2107	</pre>
				2108
				2109	<p>The default behavior is to include all known PNG ancillary chunks
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2110	plus ImageMagick's private <code>vpAg</code> ("virtual page") chunk,
cristy	f796427	2011-01-30 03:49:12 +0000	[diff] [blame]	2111	and to exclude all PNG chunks that are unknown to ImageMagick,
				2112	regardless of their PNG "copy-safe" status as described in the
				2113	PNG specification.</p>
cristy	d241f44	2011-03-29 13:50:49 +0000	[diff] [blame]	2114
				2115	<p>Any chunk names that are not known to ImageMagick are ignored
				2116	if they appear in either the "include-chunk" or "exclude-chunk" list.
				2117	The ancillary chunks currently known to ImageMagick are
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2118	<code>bKGD</code>, <code>cHRM</code>, <code>gAMA</code>, <code>iCCP</code>,
				2119	<code>oFFs</code>, <code>pHYs</code>, <code>sRGB</code>, <code>tEXt</code>,
				2120	<code>tRNS</code>, <code>vpAg</code>, and <code>zTXt</code>.</p>
cristy	d241f44	2011-03-29 13:50:49 +0000	[diff] [blame]	2121
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2122	<p>You can also put <code>date</code> in the list to include or exclude
cristy	f9a6c46	2011-04-24 14:01:11 +0000	[diff] [blame]	2123	the "Date:create" and "Date:modify" text chunks that ImageMagick normally
				2124	inserts in the output PNG.</p>
				2125
				2126	</dd>
				2127
				2128	<dt>png:preserve-colormap</dt>
				2129	<dd>Use the existing image->colormap. Normally the PNG encoder will
				2130	try to optimize the palette, eliminating unused entries and putting
				2131	the transparent colors first. If this flag is set, that behavior
				2132	is suppressed.</dd>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2133
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2134	<dt>png:preserve-iCCP</dt>
				2135	<dd>By default, the PNG decoder and encoder examine any ICC profile
				2136	that is present, either from an <code>iCCP</code> chunk in the PNG
				2137	input or supplied via an option, and if the profile is recognized
				2138	to be the sRGB profile, converts it to the <code>sRGB</code> chunk.
				2139	You can use <code>-define png:preserve-iCCP</code> to prevent
				2140	this from happening; in such cases the <code>iCCP</code> chunk
				2141	will be read or written and no <code>sRGB</code> chunk will be
				2142	written. There are some ICC profiles that claim to be sRGB but
				2143	have various errors that cause them to be rejected by libpng16; such
				2144	profiles are recognized anyhow and converted to the <code>sRGB</code>
				2145	chunk, but are rejected if the <code>-define png:preserve-iCCP</code>
				2146	is present. Note that not all "sRGB" ICC profiles are recognized
				2147	yet; we will add them to the list as we encounter them.</dd>
				2148
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2149	<dt>ps:imagemask</dt>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2150	<dd>If the ps:imagemask flag is defined, the PS3 and EPS3 coders will create
				2151	Postscript files that render bilevel images with the Postscript imagemask
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2152	operator instead of the image operator.</dd>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2153
cristy	045bd90	2010-01-30 18:56:24 +0000	[diff] [blame]	2154	<dt>quantum:format=<em class="arg">type</em></dt>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2155	<dd>Set the type to <code>floating-point</code> to specify a floating-point
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2156	format for raw files (e.g. GRAY:) or for MIFF and TIFF images in HDRI mode
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2157	to preserve negative values. If <a href="command-line-options.html#depth">-depth</a> 16 is
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2158	included, the result is a single precision floating point format.
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2159	If <a href="command-line-options.html#depth">-depth</a> 32 is included, the result is
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2160	double precision floating point format.</dd>
				2161
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2162	<dt>quantum:polarity=<em class="arg">photometric-interpretation</em></dt>
				2163	<dd>Set the photometric-interpretation of an image (typically for TIFF image
				2164	file format) to either <code>min-is-black</code> (default) or
				2165	<code>min-is-white</code>.</dd>
				2166
				2167	<dt>sample:offset=<em class="arg">geometry</em></dt>
				2168	<dd>Location of the sampling point within the sub-region being sampled,
				2169	expressed as percentages (see <a href="command-line-options.html#sample" >-sample</a>).</dd>
				2170
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2171	<dt>showkernel=1</em></dt>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2172	<dd>Outputs (to 'standard error') all the information about a generated <a
				2173	href="command-line-options.html#morphology" >-morphology</a> kernel.</dd>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2174
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2175	<dt>tiff:rows-per-strip=<em class="arg">value</em></dt>
				2176	<dd>Sets the number of rows per strip</dd>
				2177
				2178	<dt>tiff:tile-geometry=<em class="arg">WxH</em></dt>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2179	<dd>Sets the tile size for pyramid tiffs. Requires the suffix PTIF: before the
				2180	outputname</dd>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2181
				2182
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2183	</dl>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2184
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2185	<p>For example, to create a postscript file that will render only the black
				2186	pixels of a bilevel image, use:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2187
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2188	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert bilevel.tif -define ps:imagemask eps3:stencil.ps</span></p>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2189	<p>Set attributes of the image registry by prefixing the value with
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2190	<code>registry:</code>. For example, to set a temporary path to put work files,
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2191	use:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2192
				2193	<p class="crtsnip">
				2194	-define registry:temporary-path=/data/tmp
				2195	</p>
				2196
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2197	<p>If you want to keep the temporary files ImageMagick creates private, overwrite them with zeros or random data before they are removed. On the first pass, the file is zeroed. For subsequent passes, random data is written. For example, to specify two passes:</p>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2198
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2199	<p class="crtsnip">
				2200	-define registry:shred-passes=2
				2201	</p>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2202
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2203	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2204	<h4><a id="delay"></a>-delay <em class="arg">ticks</em> <br />-delay <em class="arg">ticks</em>x<em class="arg">ticks-per-second</em> {<em class="arg"><</em>} {<em class="arg">></em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2205	</div>
				2206
				2207	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>display the next image after pausing.</td><td style='text-align:right;'></td></tr></table>
				2208
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2209	<p>This option is useful for regulating the animation of image sequences
				2210	<em>ticks/ticks-per-second</em> seconds must expire before the display of the
				2211	next image. The default is no delay between each showing of the image
				2212	sequence. The default ticks-per-second is 100.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2213
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2214	<p>Use <code>></code> to change the image delay <em>only</em> if its current
				2215	value exceeds the given delay. <code><</code> changes the image delay
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2216	<em>only</em> if current value is less than the given delay. For example, if
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2217	you specify <code>30></code> and the image delay is 20, the image delay does
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2218	not change. However, if the image delay is 40 or 50, the delay it is changed
				2219	to 30. Enclose the given delay in quotation marks to prevent the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2220	<code><</code> or <code>></code> from being interpreted by your shell as
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2221	a file redirection.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2222
				2223
				2224	<div style="margin: auto;">
cristy	323f35b	2011-03-24 23:05:13 +0000	[diff] [blame]	2225	<h4><a id="delete"></a>-delete <em class="arg">indexes</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2226	</div>
				2227
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2228	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>delete the images specified by index, from the image sequence.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2229
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2230	<p>Specify the image by its index in the sequence. The first image is index
				2231	0. Negative indexes are relative to the end of the sequence, for example, -1
				2232	represents the last image of the sequence. Specify a range of images with
				2233	a dash (e.g. 0-4). Separate indexes with a comma (e.g. 0,2). Use
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2234	<code>+delete</code> to delete the last image in the current image sequence.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2235
				2236
				2237	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2238	<h4><a id="density"></a>-density <em class="arg">width</em><br />-density <em class="arg">width</em>x<em class="arg">height</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2239	</div>
				2240
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2241	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the horizontal and vertical resolution of an image for
				2242	rendering to devices.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2243
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2244	<p>This option specifies the image resolution to store while encoding a raster
				2245	image or the canvas resolution while rendering (reading) vector formats such
				2246	as Postscript, PDF, WMF, and SVG into a raster image. Image resolution
				2247	provides the unit of measure to apply when rendering to an output device or
				2248	raster image. The default unit of measure is in dots per inch (DPI). The <a
				2249	href="command-line-options.html#units">-units</a> option may be used to select dots per centimeter
				2250	instead.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2251
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2252	<p>The default resolution is 72 dots per inch, which is equivalent to one
				2253	point per pixel (Macintosh and Postscript standard). Computer screens are
				2254	normally 72 or 96 dots per inch, while printers typically support 150, 300,
				2255	600, or 1200 dots per inch. To determine the resolution of your display, use
				2256	a ruler to measure the width of your screen in inches, and divide by the
				2257	number of horizontal pixels (1024 on a 1024x768 display).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2258
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2259	<p>If the file format supports it, this option may be used to update the
				2260	stored image resolution. Note that Photoshop stores and obtains image
				2261	resolution from a proprietary embedded profile. If this profile is not
				2262	stripped from the image, then Photoshop will continue to treat the image using
				2263	its former resolution, ignoring the image resolution specified in the standard
				2264	file header.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2265
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2266	<p>The <a href="command-line-options.html#density">-density</a> option sets an <em>attribute</em> and
				2267	does not alter the underlying raster image. It may be used to adjust the
				2268	rendered size for desktop publishing purposes by adjusting the scale applied
				2269	to the pixels. To resize the image so that it is the same size at a different
				2270	resolution, use the <a href="command-line-options.html#resample">-resample</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2271
				2272	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2273	<h4><a id="depth"></a>-depth <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2274	</div>
				2275
				2276	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>depth of the image.</td><td style='text-align:right;'></td></tr></table>
				2277
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2278	<p>This the number of bits in a color sample within a pixel. Use this option
				2279	to specify the depth of raw images whose depth is unknown such as GRAY, RGB,
				2280	or CMYK, or to change the depth of any image after it has been read.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2281
				2282	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2283	<h4><a id="descend"></a>-descend</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2284	</div>
				2285
				2286	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>obtain image by descending window hierarchy.</td><td style='text-align:right;'></td></tr></table>
				2287
				2288	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2289	<h4><a id="deskew"></a>-deskew <em class="arg">threshold</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2290	</div>
				2291
				2292	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>straighten an image. A threshold of 40% works for most images.</td><td style='text-align:right;'></td></tr></table>
				2293
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2294	<p>Use <a href="command-line-options.html#set">-set</a> <code>option:deskew:auto-crop
				2295	<em>width</em></code> to auto crop the image. The set argument is the pixel
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2296	width of the image background (e.g 40).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2297
				2298	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2299	<h4><a id="despeckle"></a>-despeckle</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2300	</div>
				2301
				2302	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>reduce the speckles within an image.</td><td style='text-align:right;'></td></tr></table>
				2303
				2304	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2305	<h4><a id="direction"></a>-direction <em class="arg">type</em></h4>
cristy	2c83960	2010-04-03 02:32:08 +0000	[diff] [blame]	2306	</div>
				2307
				2308	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>render text right-to-left or left-to-right.</td><td style='text-align:right;'></td></tr></table>
				2309
				2310	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2311	<h4><a id="displace"></a>-displace <em class="arg">horizontal-scale</em><br />-displace <em class="arg">horizontal-scale</em>x<em class="arg">vertical-scale</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2312	</div>
				2313
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2314	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>shift image pixels as defined by a displacement map.</td><td style='text-align:right;'>[<a href="composite.html">composite</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2315
				2316	<p>With this option, the 'overlay' image, and optionally the 'mask' image,
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2317	is used as a displacement map, which is used to displace the lookup of
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2318	what part of the 'background' image is seen at each point of the overlaid
				2319	area. Much like the displacement map is a 'lens' that redirects light shining
				2320	through it so as to present a distorted view the original 'background' image
				2321	behind it. </p>
				2322
				2323	<p>Any perfect grey areas of the displacement map produce a zero
				2324	displacement of the image. Black areas produce the given maximum negative
				2325	displacement of the lookup point, while white produce a maximum positive
				2326	displacement of the lookup. </p>
				2327
				2328	<p>Note that it is the lookup of the 'background' that is displaced, not a
				2329	displacement of the image itself. As such an area of the displacement map
				2330	containing 'white' will have the lookup point 'shifted' by a positive amount,
				2331	and thus generating a copy of the destination image to the right/downward from
				2332	the correct position. That is the image will look like it may have been
				2333	'shifted' in a negative left/upward direction. Understanding this is a very
				2334	important in understanding how displacement maps work. </p>
				2335
				2336	<p>The given arguments define the maximum amount of displacement in pixels
				2337	that a particular map can produce. If the displacement scale is large enough
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2338	it is also possible to lookup parts of the 'background' image that lie well
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2339	outside the bounds of the displacement map itself. That is you could very
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2340	easily copy a section of the original image from outside the overlay area
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2341	into the overlay area. </p>
				2342
				2343	<p>The '%' flag makes the displacement scale relative to the size of the
				2344	overlay image (100% = half width/height of image). Using '!' switches
				2345	percentage arguments to refer to the destination image size instead.
				2346	these flags were added as of IM v6.5.3-5.</p>
				2347
				2348	<p>Normally a single grayscale displacement map is provided, which with the
				2349	given scaling values will determine a single direction (vector) in which
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2350	displacements can occur (positively or negatively). However, if you also
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2351	specify a third image which is normally used as a <em class="arg">mask</em>,
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2352	the <em class="arg">composite image</em> is used for horizontal X
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2353	displacement, while the <em class="arg">mask image</em> is used for vertical Y
				2354	displacement. This allows you to define completely different displacement
				2355	values for the X and Y directions, and allowing you to lookup any point within
				2356	the <em class="arg">scale</em> bounds. In other words each pixel can lookup
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2357	any other nearby pixel, producing complex 2 dimensional displacements, rather
				2358	than a simple 1 dimensional vector displacements. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2359
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2360	<p>Alternatively rather than supplying two separate images, as of IM v6.4.4-0,
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2361	you can use the 'red' channel of the overlay image to specify the horizontal
				2362	or X displacement, and the 'green' channel for the vertical or Y displacement.
				2363	</p>
				2364
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2365	<p>As of IM v6.5.3-5 any alpha channel in the overlay image is used as a
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2366	mask the transparency of the destination image. However areas outside the
				2367	overlaid areas will not be effected. </p>
				2368
				2369
				2370	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2371	<h4><a id="display"></a>-display <em class="arg">host:display[.screen]</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2372	</div>
				2373
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2374	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specifies the X server to contact.</td><td style='text-align:right;'>[<a href="animate.html">animate</a>, <a href="display.html">display</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2375
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2376	<p>This option is used with convert for obtaining image or font from this
				2377	X server. See <em class="arg">X(1)</em>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2378
				2379	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2380	<h4><a id="dispose"></a>-dispose <em class="arg">method</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2381	</div>
				2382
				2383	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>define the GIF disposal image setting for images that are being created or read in. </td><td style='text-align:right;'></td></tr></table>
				2384
				2385	<p>The layer disposal method defines the way each the displayed image is to be
				2386	modified after the current 'frame' of an animation has finished being
				2387	displayed (after its 'delay' period), but before the next frame on an
				2388	animation is to be overlaid onto the display. </p>
				2389
				2390	<p>Here are the valid methods:</p>
				2391
				2392	<pre class="text">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2393	Undefined 0 No disposal specified (equivalent to '<code>none</code>').
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	2394	None 1 Do not dispose, just overlay next frame image.
				2395	Background 2 Clear the frame area with the background color.
				2396	Previous 3 Clear to the image prior to this frames overlay.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2397	</pre>
				2398
				2399	<p>You can also use the numbers given above, which is what the GIF format
				2400	uses internally to represent the above settings. </p>
				2401
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2402	<p>To print a complete list of dispose methods, use <a href="command-line-options.html#list">-list dispose</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2403
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2404	<p>Use <a href="command-line-options.html#dispose" >+dispose</a>, turn off the setting and prevent
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2405	resetting the layer disposal methods of images being read in. </p>
				2406
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2407	<p>Use <a href="command-line-options.html#set">-set</a> '<code>dispose</code>' method to set the image
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2408	disposal method for images already in memory.</p>
				2409
				2410	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2411	<h4><a id="dissimilarity-threshold"></a>-dissimilarity-threshold <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2412	</div>
				2413
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2414	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>maximum RMSE for subimage match (default 0.2).</td><td style='text-align:right;'>[<a href="compare.html">compare</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2415
				2416
				2417	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2418	<h4><a id="dissolve"></a>-dissolve <em class="arg">src_percent</em>[x<em class="arg">dst_percent</em>]</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2419	</div>
				2420
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2421	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>dissolve an image into another by the given percent.</td><td style='text-align:right;'>[<a href="composite.html">composite</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2422
				2423	<p>The opacity of the composite image is multiplied by the given percent, then
				2424	it is composited 'over' the main image. If <em class="arg">src_percent</em>
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2425	is greater than 100, start dissolving the main image so it becomes
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2426	transparent at a value of '<code class="arg">200</code>'. If both percentages
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2427	are given, each image are dissolved to the percentages given. </p>
				2428
				2429	<p>Note that dissolve percentages do not add, two opaque images dissolved
				2430	'50,50', produce a 75% transparency. For a 50% + 50% blending of the two
				2431	images, you would need to use dissolve values of '50,100'. </p>
				2432
				2433	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2434	<h4><a id="distort"></a>-distort <em class="arg">method arguments</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2435	</div>
				2436
				2437	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>distort an image, using the given <em class="arg">method</em> and its required <em class="arg">arguments</em>.</td><td style='text-align:right;'></td></tr></table>
				2438
				2439	<p>The <em class="arg">arguments</em> is a single string containing a list
				2440	of floating point numbers separated by commas or spaces. The number of
				2441	and meaning of the floating point values depends on the distortion <em
				2442	class="arg">method</em> being used. </p>
				2443
				2444	<p>Choose from these distortion types:</p>
				2445
				2446	<table class="doc">
				2447	<tr valign="top">
				2448	<th align="left" style="width: 8%">Method</th>
				2449	<th align="left">Description</th>
				2450	</tr>
				2451
				2452	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2453	<td valign="top"><code>ScaleRotateTranslate</code>
				2454	<br/>or   <code>SRT</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2455	<td valign="top">
				2456	Distort image by first scaling and rotating about a given 'center',
				2457	before translating that 'center' to the new location, in that order. It
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2458	is an alternative method of specifying a '<code>Affine</code>' type of
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2459	distortion, but without shearing effects. It also provides a good way
				2460	of rotating and displacing a smaller image for tiling onto a larger
				2461	background (IE 2-dimensional animations). <br/>
				2462
				2463	The number of arguments determine the specific meaning of each
				2464	argument for the scales, rotation, and translation operations. <br/>
				2465
				2466	<table style="margin-left:auto; margin-right:auto;">
				2467	<tr><td>#  </td><td>arguments meaning</td></tr>
				2468	<tr><td>1:</td><td><em>Angle_of_Rotation</em></td></tr>
				2469	<tr><td>2:</td><td><em>Scale   Angle</em></td></tr>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2470	<tr><td>3:</td><td><em>X,Y     Angle</em></td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2471	<tr><td>4:</td><td><em>X,Y   Scale   Angle</em></td></tr>
				2472	<tr><td>5:</td>
				2473	<td><em>X,Y   ScaleX,ScaleY   Angle</em></td></tr>
				2474	<tr><td>6:</td>
				2475	<td><em>X,Y   Scale   Angle   NewX,NewY</em></td></tr>
				2476	<tr><td>7:</td>
				2477	<td><em>X,Y   ScaleX,ScaleY   Angle
				2478	NewX,NewY</em></td></tr>
				2479	</table>
				2480
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2481	This is actually an alternative way of specifying a 2 dimensional linear
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2482	'<code>Affine</code>' or '<code>AffineProjection</code>' distortion. </td> </tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2483
				2484	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2485	<td valign="top"><code>Affine</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2486	<td valign="top">
				2487	Distort the image linearly by moving a list of at least 3 or more sets
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2488	of control points (as defined below). Ideally 3 sets or 12 floating
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2489	point values are given allowing the image to be linearly scaled,
				2490	rotated, sheared, and translated, according to those three points. See
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2491	also the related '<code>AffineProjection</code>' and '<code>SRT</code>'
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2492	distortions. <br/>
				2493
				2494	More than 3 sets given control point pairs (12 numbers) is least
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2495	squares fitted to best match a linear affine distortion. If only 2
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2496	control point pairs (8 numbers) are given a two point image translation
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2497	rotation and scaling is performed, without any possible shearing,
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2498	flipping or changes in aspect ratio to the resulting image. If only one
				2499	control point pair is provides the image is only translated, (which may
				2500	be a floating point non-integer translation). <br/>
				2501
				2502	This distortion does not include any form of perspective distortion.
				2503	</td>
				2504
				2505	</tr>
				2506
				2507	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2508	<td valign="top"><code>AffineProjection</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2509	<td valign="top">
				2510	Linearly distort an image using the given Affine Matrix of 6
				2511	pre-calculated coefficients forming a set of Affine Equations to map
				2512	the source image to the destination image.
				2513
				2514	<div style="text-align: center"><em>
				2515	s<sub>x</sub>, r<sub>x</sub>,
				2516	r<sub>y</sub>, s<sub>y</sub>,
				2517	t<sub>x</sub>, t<sub>y</sub>
				2518	</em></div>
				2519
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2520	See <a href="command-line-options.html#affine" >-affine</a> setting for more detail, and
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2521	meanings of these coefficients. <br/>
				2522
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2523	The distortions '<code>Affine</code>' and '<code>SRT</code>' provide
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2524	alternative methods of defining this distortion, with ImageMagick doing
				2525	the calculations needed to generate the required coefficients. You can
				2526	see the internally generated coefficients, by using a <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2527	href="command-line-options.html#verbose" >-verbose</a> setting with those other variants. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2528
				2529	</tr>
				2530
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2531	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2532	<td valign="top"><code>BilinearForward</code><br/>
				2533	<code>BilinearReverse</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2534	<td valign="top">
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2535	Bilinear Distortion, given a minimum of 4 sets of coordinate pairs, or
				2536	16 values (see below). Not that lines may not appear straight after
				2537	distortion, though the distance between coordinates will remain
				2538	consistent. <br/>
				2539
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2540	The '<code>BilinearForward</code>' is used to map rectangles to any
				2541	quadrilateral, while the '<code>BilinearReverse</code>' form maps any
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2542	quadrilateral to a rectangle, while preserving the straight line edges
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2543	in each case. <br/>
				2544
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2545	Note that '<code>BilinearForward</code>' can generate invalid pixels
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2546	which will be colored using the <a href="command-line-options.html#mattecolor" >-mattecolor</a>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2547	color setting. Also if the quadrilateral becomes 'flipped' the image
				2548	may disappear. <br/>
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2549
				2550	There are future plans to produce a true Bilinear distortion that will
				2551	attempt to map any quadrilateral to any other quadrilateral, while
				2552	preserving edges (and edge distance ratios).
				2553
				2554	</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2555	</tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2556
				2557	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2558	<td valign="top"><code>Perspective</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2559	<td valign="top">
				2560	Perspective distort the images, using a list of 4 or more sets of
				2561	control points (as defined below). More that 4 sets (16 numbers) of
				2562	control points provide least squares fitting for more accurate
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2563	distortions (for the purposes of image registration and panorama
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2564	effects). Less than 4 sets will fall back to a '<code>Affine</code>'
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2565	linear distortion. <br/>
				2566
				2567	Perspective Distorted images ensures that straight lines remain
				2568	straight, but the scale of the distorted image will vary. The horizon
				2569	is anti-aliased, and the 'sky' color may be set using the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2570	<a href="command-line-options.html#mattecolor" >-mattecolor</a> setting. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2571	</tr>
				2572
				2573	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2574	<td valign="top"><code>PerspectiveProjection</code>  </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2575	<td valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2576	Do a '<code>Perspective</code>' distortion biased on a set of 8
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2577	pre-calculated coefficients. You can get these coefficients by looking
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2578	at the <a href="command-line-options.html#verbose" >-verbose</a> output of a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2579	'<code>Perspective</code>' distortion, or by calculating them yourself.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2580	If the last two perspective scaling coefficients are zero, the
				2581	remaining 6 represents a transposed 'Affine Matrix'. </td>
				2582
				2583	</tr>
				2584
				2585	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2586	<td valign="top"><code>Arc</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2587	<td valign="top">
				2588	Arc the image (variation of polar mapping) over the angle given around
				2589	a circle. <br/>
				2590	<table width="90%" style = "margin-left: auto; margin-right: auto;">
				2591	<tr valign="top"><td>Argument</td>
				2592	<td>Meaning</td></tr>
				2593	<tr valign="top"><td><em>arc_angle</em></td>
				2594	<td>The angle over which to arc the image side-to-side</td></tr>
				2595	<tr valign="top"><td><em>rotate_angle</em></td>
				2596	<td>Angle to rotate resulting image from vertical center</td></tr>
				2597	<tr valign="top"><td><em>top_radius</em></td>
				2598	<td>Set top edge of source image at this radius</td></tr>
				2599	<tr valign="top"><td><em>bottom_radius</em> </td>
				2600	<td>Set bottom edge to this radius (radial scaling)</td></tr>
				2601	</table>
				2602
				2603	The resulting image is always resized to best fit the resulting image,
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2604	(as if using <a href="command-line-options.html#distort" >+distort</a>) while attempting to
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2605	preserve scale and aspect ratio of the original image as much as
				2606	possible with the arguments given by the user. All four arguments will
				2607	be needed to change the overall aspect ratio of an 'Arc'ed image. <br/>
				2608
				2609	This a variation of a polar distortion designed to try to preserve the
				2610	aspect ratio of the image rather than direct Cartesian to Polar
				2611	conversion. </td>
				2612	</tr>
				2613
				2614	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2615	<td valign="top"><code>Polar</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2616	<td valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2617	Like '<code>Arc</code>' but do a complete Cartesian to Polar mapping of
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2618	the image. that is the height of the input image is mapped to the
				2619	radius limits, while the width is wrapped around between the
				2620	angle limits. <br/>
				2621
				2622	Arguments: <em>Rmax,Rmin CenterX,CenterY, start,end_angle</em> <br/>
				2623
				2624	All arguments are optional. With <em>Rmin</em> defaulting to zero, the
				2625	center to the center of the image, and the angles going from -180 (top)
				2626	to +180 (top). If <em>Rmax</em> is given the special value of
				2627	'<code>0</code>', the the distance from the center to the nearest edge
				2628	is used for the radius of the output image, which will ensure the whole
				2629	image is visible (though scaled smaller). However a special value of
				2630	'<code>-1</code>' will use the distance from the center to the furthest
				2631	corner, This may 'clip' the corners from the input rectangular image,
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2632	but will generate the exact reverse of a '<code>DePolar</code>' with
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2633	the same arguments. <br/>
				2634
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2635	If the plus form of distort (<a href="command-line-options.html#distort" >+distort</a>) is used
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2636	output image center will default to <code>0,0</code> of the virtual
				2637	canvas, and the image size adjusted to ensure the whole input image is
				2638	made visible in the output image on the virtual canvas. </td>
				2639
				2640	</tr>
				2641
				2642	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2643	<td valign="top"><code>DePolar</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2644	<td valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2645	Uses the same arguments and meanings as a '<code>Polar</code>' distortion
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2646	but generates the reverse Polar to Cartesian distortion. <br/>
				2647
				2648	The special <em>Rmax</em> setting of '<code>0</code>' may however clip
				2649	the corners of the input image. However using the special
				2650	<em>Rmax</em> setting of '<code>-1</code>' (maximum center to corner
				2651	distance) will ensure the whole distorted image is preserved in the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2652	generated result, so that the same argument to '<code>Polar</code>' will
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2653	reverse the distortion re-producing the original.
				2654
				2655	Note that as this distortion requires the area resampling of a circular
				2656	arc, which can not be handled by the builtin EWA resampling function.
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2657	As such the normal EWA filters are turned off. It is recommended some
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2658	form of 'super-sampling' image processing technique be used to produce
				2659	a high quality result. </td>
				2660
				2661	</tr>
				2662
				2663	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2664	<td valign="top"><code>Barrel</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2665	<td valign="top">
				2666	Given the four coefficients (A,B,C,D) as defined by <a
cristy	6bcf48e	2011-02-15 19:09:04 +0000	[diff] [blame]	2667	href="http://wiki.panotools.org/Lens_correction_model" >Helmut
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2668	Dersch</a>, perform a barrel or pin-cushion distortion appropriate to
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2669	correct radial lens distortions. That is in photographs, make straight
				2670	lines straight again. <br/>
				2671
				2672	Arguments: <em>A   B   C</em>   [ <em>D</em>   [
				2673	<em>X</em> , <em>Y</em> ] ] <br/>
				2674	or <em>A<sub>x</sub> B<sub>x</sub> C<sub>x</sub> D<sub>x</sub>
				2675	A<sub>y</sub> B<sub>y</sub> C<sub>y</sub> D<sub>y</sub></em>
				2676	[ <em>X</em> , <em>Y</em> ] <br/>
				2677	So that it forms the function <br/>
				2678	Rsrc = r * ( <em>A</em>r<sup>3</sup> + <em>B</em>r<sup>2</sup> +
				2679	<em>C</em>*r + <em>D</em> )<br/>
				2680
				2681	Where <em>X</em>,<em>Y</em> is the optional center of the distortion
				2682	(defaulting to the center of the image). <br/>
				2683	The second form is typically used to distort images, rather than
				2684	correct lens distortions. <br/>
				2685	</td>
				2686
				2687	</tr>
				2688
				2689	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2690	<td valign="top"><code>BarrelInverse</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2691	<td valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2692	This is very similar to '<code>Barrel</code>' with the same set of
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2693	arguments, and argument handling. However it uses the inverse
				2694	of the radial polynomial,
				2695	so that it forms the function <br/>
				2696	Rsrc = r / ( <em>A</em>r<sup>3</sup> + <em>B</em>r<sup>2</sup> +
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2697	<em>C</em>*r + <em>D</em> )<br/>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2698	Note that this is not the reverse of the '<code>Barrel</code>'
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2699	distortion, just a different barrel-like radial distortion method.
				2700
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2701	</td>
				2702	</tr>
				2703
				2704	<tr valign="top">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2705	<td valign="top"><code>Shepards</code></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2706	<td valign="top">
				2707	Distort the given list control points (any number) using an Inverse
				2708	Squared Distance Interpolation Method (<a
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2709	href="http://en.wikipedia.org/wiki/Shepard%27s_method" >Shepards
				2710	Method</a>). The control points in effect do 'localized' displacement
				2711	of the image around the given control point (preserving the look and
				2712	the rotation of the area near the control points. For best results
				2713	extra control points should be added to 'lock' the positions of the
				2714	corners, edges and other unchanging parts of the image, to prevent
				2715	their movement. <br/>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2716
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2717	The distortion has been likened to 'taffy pulling' using nails, or
				2718	pins' stuck in a block of 'jelly' which is then moved to the new
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2719	position, distorting the surface of the jelly. <br/>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2720
cristy	baacd17	2011-04-30 23:11:03 +0000	[diff] [blame]	2721	Internally it is equivalent to generating a displacement map (see <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2722	href="command-line-options.html#displace" >-displace</a>) for source image color look-up using
				2723	the <a href="command-line-options.html#sparse-color" >-sparse-color</a> method of the same name.
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2724
				2725	</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2726	</tr>
				2727
				2728	</table>
				2729
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2730	<p>To print a complete list of distortion methods, use <a href="command-line-options.html#list">-list
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2731	distort</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2732
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2733	<p>Many of the above distortion methods such as '<code>Affine</code>',
				2734	'<code>Perspective</code>', and '<code>Shepards</code>' use a list control points
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2735	defining how these points in the given image should be distorted in the
				2736	destination image. Each set of four floating point values represent a source
				2737	image coordinate, followed immediately by the destination image coordinate.
				2738	This produces a list of values such as...</p>
				2739	<div style="text-align: center"><em>
				2740	U<sub>1</sub>,V<sub>1</sub> X<sub>1</sub>,Y<sub>1</sub>
				2741	U<sub>2</sub>,V<sub>2</sub> X<sub>2</sub>,Y<sub>2</sub>
				2742	U<sub>3</sub>,V<sub>3</sub> X<sub>3</sub>,Y<sub>3</sub>
				2743	...
				2744	U<sub>n</sub>,V<sub>n</sub> X<sub>n</sub>,Y<sub>n</sub>
				2745	</em></div>
				2746	<p>where <em>U,V</em> on the source image is mapped to <em>X,Y</em> on the
				2747	destination image. </p>
				2748
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2749	<p>For example, to warp an image using '<code>perspective</code>' distortion,
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2750	needs a list of at least 4 sets of coordinates, or 16 numbers. Here is the
				2751	perspective distortion of the built-in "rose:" image. Note how spaces were
				2752	used to group the 4 sets of coordinate pairs, to make it easier to read and
				2753	understand.</p>
				2754
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2755	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2756	convert rose: -virtual-pixel black \<br/>
				2757	-distort Perspective '0,0,0,0 0,45,0,45 69,0,60,10 69,45,60,35' \<br/>
				2758	rose_3d_rotated.gif</span></p>
				2759	<p>If more that the required number of coordinate pairs are given for
				2760	a distortion, the distortion method is 'least squares' fitted to produce the
				2761	best result for all the coordinate pairs given. If less than the ideal number
				2762	of points are given, the distort will generally fall back to a simpler form of
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2763	distortion that can handles the smaller number of coordinates (usually a linear
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2764	'<code>Affine</code>' distortion). </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2765
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	2766	<p>By using more coordinates you can make use of image registration tool to
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2767	find matching coordinate pairs in overlapping images, so as to improve the
				2768	'fit' of the distortion. Of course a bad coordinate pair can also make the
				2769	'fit' worse. Caution is always advised. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2770
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2771	<p>Colors are acquired from the source image according to a cylindrical
				2772	resampling <a href="command-line-options.html#filter" >-filter</a>, using a special technique known as
				2773	EWA resampling. This produces very high quality results, especially when
				2774	images become smaller (minified) in the output, which is very common when
				2775	using '<code>perspective</code>' distortion. For example here we view
				2776	a infinitely tiled 'plane' all the way to the horizon. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2777
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	2778	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2779	convert -size 90x90 pattern:checkerboard -normalize -virtual-pixel tile \<br/>
				2780	-distort perspective '0,0,5,45 89,0,45,46 0,89,0,89 89,89,89,89' \<br/>
				2781	checks_tiled.jpg</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2782	<p>Note that a infinitely tiled perspective images involving the horizon can
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2783	be very slow, because of the number of pixels that are compressed to generate
				2784	each individual pixel close to the 'horizon'. You can turn off EWA
				2785	resampling, by specifing the special <a href="command-line-options.html#filter" >-filter</a> setting of
				2786	'<code>point</code>' (recommended if you plan to use super-sampling instead).
				2787	</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2788
				2789	<p>If an image generates <i>invalid pixels</i>, such as the 'sky' in the last
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2790	example, <a href="command-line-options.html#distort" >-distort</a> will use the current <a
				2791	href="command-line-options.html#mattecolor" >-mattecolor</a> setting for these pixels. If you do not
				2792	what these pixels to be visible, set the color to match the rest of the
				2793	ground. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2794
				2795	<p>The output image size will by default be the same as the input image. This
				2796	means that if the part of the distorted image falls outside the viewed area of
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2797	the 'distorted space', those parts is clipped and lost. However if you use
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2798	the plus form of the operator (<a href="command-line-options.html#distort" >+distort</a>) the operator
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2799	will attempt (if possible) to show the whole of the distorted image, while
				2800	retaining a correct 'virtual canvas' offset, for image layering. This offset
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2801	may need to be removed using <a href="command-line-options.html#repage" >+repage</a>, to remove if it
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	2802	is unwanted. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2803
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2804	<p>Setting <a href="command-line-options.html#verbose" >-verbose</a> setting, will cause <a
				2805	href="command-line-options.html#distort" >-distort</a> to attempt to output the internal coefficients,
				2806	and the <a href="command-line-options.html#fx" >-fx</a> equivalent to the distortion, for expert study,
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2807	and debugging purposes. This many not be available for all distorts. </p>
				2808
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2809	<p>You can alternatively specify a special "<code><a href="command-line-options.html#define"
				2810	>-define</a> distort:viewport={geometry_string}</code>" setting which will
				2811	specify the size and the offset of the generated 'viewport' image of the
				2812	distorted image space.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2813
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2814	<p>Setting a "<code><a href="command-line-options.html#define" >-define</a>
				2815	distort:scale={scale_factor}</code>" will scale the output image (viewport or
				2816	otherwise) by that factor without changing the viewed contents of the
				2817	distorted image. This can be used either for 'super-sampling' the image for
				2818	a higher quality result, or for panning and zooming around the image (with
				2819	appropriate viewport changes, or post-distort cropping and resizing). </p>
				2820
				2821	<p>Setting "<code><a href="command-line-options.html#define" >-define</a> resample:verbose=1</code>"
				2822	will output the cylindrical filter lookup table created by the EWA (Elliptical
				2823	Weighted Average) resampling algorithm. Note this table uses a squared radius
				2824	lookup value. This is typically only used for debugging EWA resampling. </p>
				2825
				2826
				2827	<div style="margin: auto;">
				2828	<h4><a id="distribute-cache"></a>-distribute-cache <em class="arg">port</em></h4>
				2829	</div>
				2830
				2831	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>launch a distributed pixel cache server. </td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2832
				2833	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2834	<h4><a id="dither"></a>-dither <em class="arg">method</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2835	</div>
				2836
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2837	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply a Riemersma or Floyd-Steinberg error diffusion dither to
				2838	images when general color reduction is applied via an option, or automagically
				2839	when saving to specific formats. This enabled by default. </td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2840
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2841	<p>Dithering places two or more colors in neighboring pixels so that to the
				2842	eye a closer approximation of the images original color is reproduced. This
				2843	reduces the number of colors needed to reproduce the image but at the cost of
				2844	a lower level pattern of colors. Error diffusion dithers can use any set of
				2845	colors (generated or user defined) to an image. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2846
				2847	<p>Dithering is turned on by default, to turn it off use the plus form of the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2848	setting, <a href="command-line-options.html#dither">+dither</a>. This will also also render PostScript
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2849	without text or graphic aliasing. Disabling dithering often (but not always)
				2850	leads to faster process, a smaller number of colors, but more cartoon like
				2851	image coloring. Generally resulting in 'color banding' effects in areas with
				2852	color gradients. </p>
				2853
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2854	<p>The color reduction operators <a href="command-line-options.html#colors">-colors</a>, <a
				2855	href="command-line-options.html#monochrome">-monochrome</a>, <a href="command-line-options.html#remap ">-remap</a>, and <a
				2856	href="command-line-options.html#posterize">-posterize</a>, apply dithering to images using the reduced
				2857	color set they created. These operators are also used as part of automatic
				2858	color reduction when saving images to formats with limited color support, such
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2859	as <code>GIF:</code>, <code>XBM:</code>, and others, so dithering may also be used
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2860	in these cases. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2861
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2862	<p>Alternatively you can use <a href="command-line-options.html#random-threshold">-random-threshold</a>
				2863	to generate purely random dither. Or use <a
				2864	href="command-line-options.html#ordered-dither">-ordered-dither</a> to apply threshold mapped dither
				2865	patterns, using uniform color maps, rather than specific color maps. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2866
				2867
				2868	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	2869	<h4><a id="draw"></a>-draw <em class="arg">string</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2870	</div>
				2871
				2872	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Annotate an image with one or more graphic primitives.</td><td style='text-align:right;'></td></tr></table>
				2873
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2874	<p>Use this option to annotate or decorate an image with one or more graphic
				2875	primitives. The primitives include shapes, text, transformations, and pixel
				2876	operations.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2877
				2878	<p>The shape primitives:</p>
				2879
				2880	<pre class="text">
				2881	point x,y
				2882	line x0,y0 x1,y1
				2883	rectangle x0,y0 x1,y1
				2884	roundRectangle x0,y0 x1,y1 wc,hc
				2885	arc x0,y0 x1,y1 a0,a1
				2886	ellipse x0,y0 rx,ry a0,a1
				2887	circle x0,y0 x1,y1
				2888	polyline x0,y0 ... xn,yn
				2889	polygon x0,y0 ... xn,yn
				2890	bezier x0,y0 ... xn,yn
				2891	path path specification
				2892	image operator x0,y0 w,h filename
				2893	</pre>
				2894
				2895	<p>The text primitive:</p>
				2896
				2897	<pre class="text">
				2898	text x0,y0 string
				2899	</pre>
				2900	<p>The text gravity primitive:</p>
				2901
				2902	<pre class="text">
				2903	gravity NorthWest, North, NorthEast, West, Center,
				2904	East, SouthWest, South, or SouthEast
				2905	</pre>
				2906
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2907	<p>The text gravity primitive only affects the placement of text and does not
				2908	interact with the other primitives. It is equivalent to using the <a
				2909	href="command-line-options.html#gravity">-gravity</a> command-line option, except that it is limited in
				2910	scope to the <a href="command-line-options.html#draw">-draw</a> option in which it appears.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2911
				2912	<p>The transformation primitives:</p>
				2913
				2914	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	2915	rotate degrees
				2916	translate dx,dy
				2917	scale sx,sy
				2918	skewX degrees
				2919	skewY degrees
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2920	</pre>
				2921
				2922	<p>The pixel operation primitives:</p>
				2923
				2924	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	2925	color x0,y0 method
				2926	matte x0,y0 method
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2927	</pre>
				2928
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2929	<p>The shape primitives are drawn in the color specified by the preceding <a
				2930	href="command-line-options.html#fill">-fill</a> setting. For unfilled shapes, use <a
				2931	href="command-line-options.html#fill">-fill none</a>. You can optionally control the stroke (the
				2932	"outline" of a shape) with the <a href="command-line-options.html#stroke">-stroke</a> and <a
				2933	href="command-line-options.html#strokewidth">-strokewidth</a> settings.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2934
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2935	<p>A <code>point</code> primitive is specified by a single <em>point</em> in the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2936	pixel plane, that is, by an ordered pair of integer coordinates,
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2937	<em>x</em>,<em>y</em>. (As it involves only a single pixel, a <code>point</code>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2938	primitive is not affected by <a href="command-line-options.html#stroke">-stroke</a> or <a
				2939	href="command-line-options.html#strokewidth">-strokewidth</a>.)</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2940
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2941	<p>A <code>line</code> primitive requires a start point and end point.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2942
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2943	<p>A <code>rectangle</code> primitive is specified by the pair of points at the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2944	upper left and lower right corners.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2945
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2946	<p>A <code>roundRectangle</code> primitive takes the same corner points as
				2947	a <code>rectangle</code> followed by the width and height of the rounded corners
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2948	to be removed.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2949
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2950	<p>The <code>circle</code> primitive makes a disk (filled) or circle (unfilled).
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2951	Give the center and any point on the perimeter (boundary).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2952
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2953	<p>The <code>arc</code> primitive is used to inscribe an elliptical segment in
				2954	to a given rectangle. An <code>arc</code> requires the two corners used for
				2955	<code>rectangle</code> (see above) followed by the start and end angles of the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2956	arc of the segment segment (e.g. 130,30 200,100 45,90). The start and end
				2957	points produced are then joined with a line segment and the resulting segment
				2958	of an ellipse is filled.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2959
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2960	<p>Use <code>ellipse</code> to draw a partial (or whole) ellipse. Give the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2961	center point, the horizontal and vertical "radii" (the <em>semi-axes</em> of
				2962	the ellipse) and start and end angles in degrees (e.g. 100,100 100,150
				2963	0,360).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2964
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2965	<p>The <code>polyline</code> and <code>polygon</code> primitives require three or
				2966	more points to define their perimeters. A <code>polyline</code> is simply
				2967	a <code>polygon</code> in which the final point is not stroked to the start
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2968	point. When unfilled, this is a <em>polygonal line</em>. If the <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2969	href="command-line-options.html#stroke">-stroke</a> setting is <code>none</code> (the default), then
				2970	a <code>polyline</code> is identical to a <code>polygon</code>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2971
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2972	<p>A <em>coordinate</em> is a pair of integers separated by a space or
				2973	optional comma. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2974
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2975	<p>As an example, to define a circle centered at 100,100 that extends to
				2976	150,150 use:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2977
				2978	<p class="crtsnip">
				2979	-draw 'circle 100,100 150,150'
				2980	</p>
				2981
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2982	<p>The <code>Bezier</code> primitive creates a spline curve and requires three
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2983	or points to define its shape. The first and last points are the
				2984	<em>knots</em> and these points are attained by the curve, while any
				2985	intermediate coordinates are <em>control points</em>. If two control points
				2986	are specified, the line between each end knot and its sequentially respective
				2987	control point determines the tangent direction of the curve at that end. If
				2988	one control point is specified, the lines from the end knots to the one
				2989	control point determines the tangent directions of the curve at each end. If
				2990	more than two control points are specified, then the additional control points
				2991	act in combination to determine the intermediate shape of the curve. In order
				2992	to draw complex curves, it is highly recommended either to use the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	2993	<code>path</code> primitive or to draw multiple four-point bezier segments with
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	2994	the start and end knots of each successive segment repeated. For example:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2995
				2996	<p class="crtsnip">
				2997	-draw 'bezier 20,50 45,100 45,0 70,50'
				2998	</p>
				2999	<p class="crtsnip">
				3000	-draw 'bezier 70,50 95,100 95,0 120,50'
				3001	</p>
				3002
				3003
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3004	<p>A <code>path</code> represents an outline of an object, defined in terms of
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3005	moveto (set a new current point), lineto (draw a straight line), curveto (draw
				3006	a Bezier curve), arc (elliptical or circular arc) and closepath (close the
				3007	current shape by drawing a line to the last moveto) elements. Compound paths
				3008	(i.e., a path with subpaths, each consisting of a single moveto followed by
				3009	one or more line or curve operations) are possible to allow effects such as
				3010	<em>donut holes</em> in objects. (See <a
				3011	href="http://www.w3.org/TR/SVG/paths.html">Paths</a>.)</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3012
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3013	<p>Use <code>image</code> to composite an image with another image. Follow the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3014	image keyword with the composite operator, image location, image size, and
				3015	filename:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3016
				3017	<p class="crtsnip">
				3018	-draw 'image SrcOver 100,100 225,225 image.jpg'
				3019	</p>
				3020
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	3021	<p>You can use 0,0 for the image size, which means to use the actual
				3022	dimensions found in the image header. Otherwise, it is scaled to the given
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3023	dimensions. See <a href="compose.html">Alpha Compositing</a> for
				3024	a detailed discussion of alpha composition methods that are available. </p>
				3025
cristy	29c5c99	2011-06-25 13:58:49 +0000	[diff] [blame]	3026	The "special augmented compose operators" such as "dissolve" that require
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3027	arguments cannot be used at present with the <code>-draw image</code> option.
cristy	29c5c99	2011-06-25 13:58:49 +0000	[diff] [blame]	3028	</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3029
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3030	<p>Use <code>text</code> to annotate an image with text. Follow the text
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3031	coordinates with a string. If the string has embedded spaces, enclose it in
				3032	single or double quotes.</p>
				3033
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3034	<p>For example, the following annotates the image with <code>Works like
				3035	magick!</code> for an image titled <code>bird.miff</code>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3036
				3037	<p class="crtsnip">
cristy	4bf6e23	2011-05-21 01:43:33 +0000	[diff] [blame]	3038	-draw "text 100,100 'Works like magick!' "
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3039	</p>
				3040
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3041	<p>See the <a href="command-line-options.html#annotate">-annotate</a> option for another convenient way
				3042	to annotate an image with text.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3043
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3044	<p>The <code>rotate</code> primitive rotates subsequent shape primitives and
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3045	text primitives about the origin of the main image. If the <a
				3046	href="command-line-options.html#region">-region</a> option precedes the <a href="command-line-options.html#draw">-draw</a>
				3047	option, the origin for transformations is the upper left corner of the
				3048	region.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3049
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3050	<p>The <code>translate</code> primitive translates subsequent shape and text
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3051	primitives.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3052
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3053	<p>The <code>scale</code> primitive scales them.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3054
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3055	<p>The <code>skewX</code> and <code>skewY</code> primitives skew them with respect
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3056	to the origin of the main image or the region.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3057
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3058	<p>The transformations modify the current affine matrix, which is initialized
				3059	from the initial affine matrix defined by the <a href="command-line-options.html#affine">-affine</a>
				3060	option. Transformations are cumulative within the <a href="command-line-options.html#draw">-draw</a>
				3061	option. The initial affine matrix is not affected; that matrix is only changed
				3062	by the appearance of another <a href="command-line-options.html#affine">-affine</a> option. If another
				3063	<a href="command-line-options.html#draw">-draw</a> option appears, the current affine matrix is
				3064	reinitialized from the initial affine matrix.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3065
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3066	<p>Use the <code>color</code> primitive to change the color of a pixel to the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3067	fill color (see <a href="command-line-options.html#fill">-fill</a>). Follow the pixel coordinate with
				3068	a method:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3069
				3070	<pre class="text">
				3071	point
				3072	replace
				3073	floodfill
				3074	filltoborder
				3075	reset
				3076	</pre>
				3077
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3078	<p>Consider the target pixel as that specified by your coordinate. The
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3079	<code>point</code> method recolors the target pixel. The <code>replace</code>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3080	method recolors any pixel that matches the color of the target pixel.
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3081	<code>Floodfill</code> recolors any pixel that matches the color of the target
				3082	pixel and is a neighbor, whereas <code>filltoborder</code> recolors any neighbor
				3083	pixel that is not the border color. Finally, <code>reset</code> recolors all
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3084	pixels.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3085
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3086	<p>Use <code>matte</code> to the change the pixel matte value to transparent.
				3087	Follow the pixel coordinate with a method (see the <code>color</code> primitive
				3088	for a description of methods). The <code>point</code> method changes the matte
				3089	value of the target pixel. The <code>replace</code> method changes the matte
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3090	value of any pixel that matches the color of the target pixel.
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3091	<code>Floodfill</code> changes the matte value of any pixel that matches the
				3092	color of the target pixel and is a neighbor, whereas <code>filltoborder</code>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3093	changes the matte value of any neighbor pixel that is not the border color (<a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3094	href="command-line-options.html#bordercolor">-bordercolor</a>). Finally <code>reset</code> changes the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3095	matte value of all pixels.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3096
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3097	<p>You can set the primitive color, font, and font bounding box color with <a
				3098	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>
				3099	respectively. Options are processed in command line order so be sure to use
				3100	these options <em>before</em> the <a href="command-line-options.html#draw">-draw</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3101
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3102	<p>Strings that begin with a number must be quoted (e.g. use '1.png' rather
				3103	than 1.png).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3104
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3105	<p>Drawing primitives conform to the <a href="magick-vector-graphics.html" >Magick
				3106	Vector Graphics</a> format.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3107
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	3108
cristy	8b9dd95	2011-03-21 22:56:18 +0000	[diff] [blame]	3109	<div style="margin: auto;">
cristy	323f35b	2011-03-24 23:05:13 +0000	[diff] [blame]	3110	<h4><a id="duplicate"></a>-duplicate <em class="arg">count,indexes</em></h4>
cristy	8b9dd95	2011-03-21 22:56:18 +0000	[diff] [blame]	3111	</div>
				3112
cristy	323f35b	2011-03-24 23:05:13 +0000	[diff] [blame]	3113	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>duplicate an image one or more times.</td><td style='text-align:right;'></td></tr></table>
cristy	8b9dd95	2011-03-21 22:56:18 +0000	[diff] [blame]	3114
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3115	<p>Specify the count and the image to duplicate by its index in the sequence.
				3116	The first image is index 0. Negative indexes are relative to the end of the
				3117	sequence, for example, -1 represents the last image of the sequence. Specify
				3118	a range of images with a dash (e.g. 0-4). Separate indexes with a comma (e.g.
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3119	0,2). Use <code>+duplicate</code> to duplicate the last image in the current
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3120	image sequence.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3121
				3122	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3123	<h4><a id="edge"></a>-edge <em class="arg">radius</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3124	</div>
				3125
				3126	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>detect edges within an image.</td><td style='text-align:right;'></td></tr></table>
				3127
				3128	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3129	<h4><a id="emboss"></a>-emboss <em class="arg">radius</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3130	</div>
				3131
				3132	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>emboss an image.</td><td style='text-align:right;'></td></tr></table>
				3133
				3134	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3135	<h4><a id="encipher"></a>-encipher <em class="arg">filename</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3136	</div>
				3137
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3138	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Encipher pixels for later deciphering by <a href="command-line-options.html#decipher">-decipher</a>.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3139
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3140	<p>Get the passphrase from the file specified by <em class="arg"
				3141	>filename</em>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3142
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3143	<p>For more information, see the webpage, <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3144	href="http://www.imagemagick.org/www/cipher.html">ImageMagick: Encipher or
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3145	Decipher an Image</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3146
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3147
				3148
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3149	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3150	<h4><a id="encoding"></a>-encoding <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3151	</div>
				3152
				3153	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>specify the text encoding.</td><td style='text-align:right;'></td></tr></table>
				3154
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3155	<p>Choose from <code>AdobeCustom</code>, <code>AdobeExpert</code>,
				3156	<code>AdobeStandard</code>, <code>AppleRoman</code>, <code>BIG5</code>,
				3157	<code>GB2312</code>, <code>Latin 2</code>, <code>None</code>, <code>SJIScode</code>,
				3158	<code>Symbol</code>, <code>Unicode</code>, <code>Wansung</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3159
				3160	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3161	<h4><a id="endian"></a>-endian <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3162	</div>
				3163
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3164	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specify endianness (<code>MSB</code> or <code>LSB</code>) of the image.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3165
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3166	<p>To print a complete list of endian types, use the <a href="command-line-options.html#list">-list endian</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3167
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3168	<p>Use <a href="command-line-options.html#endian">+endian</a> to revert to unspecified endianness.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3169
				3170
				3171	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3172	<h4><a id="enhance"></a>-enhance</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3173	</div>
				3174
				3175	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply a digital filter to enhance a noisy image.</td><td style='text-align:right;'></td></tr></table>
				3176
				3177
				3178	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3179	<h4><a id="equalize"></a>-equalize</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3180	</div>
				3181
				3182	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>perform histogram equalization on the image channel-by-channel.</td><td style='text-align:right;'></td></tr></table>
				3183
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3184	<p>To perform histogram equalization on all channels in concert, transform the
				3185	image into some other color space, such as HSL, OHTA, YIQ or YUV, then
				3186	equalize the appropriate intensity-like channel, then convert back to RGB.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3187
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3188	<p>For example using HSL, we have: ... <code>-colorspace HSL -channel lightness
				3189	-equalize -colorspace RGB</code> ...</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3190
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3191	<p>For YIQ, YUV and OHTA use the red channel. For example, OHTA is a principal
				3192	components transformation that puts most of the information in the first
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3193	channel. Here we have ... <code>-colorspace OHTA -channel red -equalize
				3194	-colorspace RGB</code> ...</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3195
				3196	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3197	<h4><a id="evaluate"></a>-evaluate <em class="arg">operator value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3198	</div>
				3199
				3200	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Alter channel pixels by evaluating an arithmetic, relational, or logical expression.</td><td style='text-align:right;'></td></tr></table>
				3201
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3202	<p>(See the <a href="command-line-options.html#function" >-function</a> operator for some
				3203	multi-parameter functions. See the <a href="command-line-options.html#fx" >-fx</a> operator if more
				3204	elaborate calculations are needed.)</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3205
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3206	<p>The behaviors of each <em class="arg">operator</em> are summarized in the
				3207	following list. For brevity, the numerical value of a "pixel" referred to
				3208	below is the value of the corresponding channel of that pixel, while
				3209	a "normalized pixel" is that number divided by the maximum
				3210	(installation-dependent) value <em class="QR">QuantumRange</em>. (If
				3211	normalized pixels are used, they are restored, following the other
				3212	calculations, to the full range by multiplying by <em
				3213	class="QR">QuantumRange</em>.)</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3214
				3215	<table class="doc">
				3216	<col width="25%" />
				3217	<col width="75%" />
				3218	<thead>
				3219	<tr>
				3220	<th><em class="arg">operator</em></th>
				3221	<th>Summary (see further below for details)</th>
				3222	</tr>
				3223	</thead>
				3224	<tbody>
				3225
cristy	3c98a4f	2010-08-13 20:09:41 +0000	[diff] [blame]	3226	<tr><td>Abs </td> <td>Add <em class="arg">value</em> to pixels and return absolute value. </td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3227	<tr><td>Add </td> <td>Add <em class="arg">value</em> to pixels. </td></tr>
				3228	<tr><td>AddModulus </td> <td>Add <em class="arg">value</em> to pixels modulo <em class="QR">QuantumRange</em>.</td></tr>
				3229	<tr><td>And </td> <td>Binary AND of pixels with <em class="arg">value</em>.</td></tr>
				3230	<tr><td>Cos, Cosine </td> <td>Apply cosine to pixels with frequency <em class="arg">value</em> with 50% bias added.</td></tr>
				3231	<tr><td>Divide </td> <td>Divide pixels by <em class="arg">value</em>.</td></tr>
cristy	5063d81	2010-10-19 16:28:10 +0000	[diff] [blame]	3232	<tr><td>Exp </td> <td>base-e exponential function</td></tr>
				3233	<tr><td>Exponential </td> <td>base-e exponential function</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3234	<tr><td>LeftShift </td> <td>Shift the pixel values left by <em class="arg">value</em> bits (i.e., multiply pixels by 2<sup><em class="arg">value</em></sup>).</td></tr>
				3235	<tr><td>Log </td> <td>Apply scaled logarithm to normalized pixels.</td></tr>
				3236	<tr><td>Max </td> <td>Clip pixels at lower bound <em class="arg">value</em>.</td></tr>
cristy	63fed27	2010-03-07 19:08:45 +0000	[diff] [blame]	3237	<tr><td>Mean </td> <td>Add the <em class="arg">value</em> and divide by 2.</td></tr>
cristy	61365ad	2010-11-28 02:38:34 +0000	[diff] [blame]	3238	<tr><td>Median </td> <td>Choose the median value from an image sequence.</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3239	<tr><td>Min </td> <td>Clip pixels at upper bound <em class="arg">value</em>.</td></tr>
				3240	<tr><td>Multiply </td> <td>Multiply pixels by <em class="arg">value</em>.</td></tr>
				3241	<tr><td>Or </td> <td>Binary OR of pixels with <em class="arg">value</em>.</td></tr>
				3242	<tr><td>Pow </td> <td>Raise normalized pixels to the power <em class="arg">value</em>.</td></tr>
				3243	<tr><td>RightShift </td> <td>Shift the pixel values right by <em class="arg">value</em> bits (i.e., divide pixels by 2<sup><em class="arg">value</em></sup>).</td></tr>
				3244	<tr><td>Set </td> <td>Set pixel equal to <em class="arg">value</em>.</td></tr>
				3245	<tr><td>Sin, Sine </td> <td>Apply sine to pixels with frequency <em class="arg">value</em> with 50% bias added.</td></tr>
				3246	<tr><td>Subtract </td> <td>Subtract <em class="arg">value</em> from pixels.</td></tr>
				3247	<tr><td>Xor </td> <td>Binary XOR of pixels with <em class="arg">value.</em></td></tr>
				3248
				3249	<tr><td> </td></tr>
				3250
				3251	<tr><td>Gaussian-noise</td></tr>
				3252	<tr><td>Impulse-noise</td></tr>
				3253	<tr><td>Laplacian-noise</td></tr>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3254	<tr><td>Multiplicative-noise</td> <td>(These are equivalent to the corresponding <a href="command-line-options.html#noise" >-noise</a> operators.)</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3255	<tr><td>PoissonNoise</td></tr>
				3256	<tr><td>Uniform-noise</td></tr>
				3257
				3258	<tr><td> </td></tr>
				3259
				3260	<tr><td>Threshold </td> <td>Threshold pixels larger than <em class="arg">value</em>.</td></tr>
				3261	<tr><td>ThresholdBlack </td> <td>Threshold pixels to zero values equal to or below <em class="arg">value</em>.</td></tr>
				3262	<tr><td>ThresholdWhite </td> <td>Threshold pixels to maximum values above <em class="arg">value</em>. </td></tr>
				3263	</tbody>
				3264	</table>
				3265
				3266	<p>The specified functions are applied only to each previously set <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3267	href="command-line-options.html#channel" >-channel</a> in the image. If necessary, the results of the
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3268	calculations are truncated (clipped) to fit in the interval [0, <em
				3269	class="QR">QuantumRange</em>]. The transparency channel of the image is
				3270	represented as a 'alpha' values (0 = fully transparent), so, for example, a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3271	<code>Divide</code> by 2 of the alpha channel will make the image
				3272	semi-transparent. Append the percent symbol '<code>%</code>' to specify a value
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3273	as a percentage of the <em class="QR">QuantumRange</em>.</p>
				3274
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3275	<p>To print a complete list of <a href="command-line-options.html#evaluate">-evaluate</a> operators, use
				3276	<a href="command-line-options.html#list">-list evaluate</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3277
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3278	<p>The results of the <code>Add</code>, <code>Subtract</code> and
				3279	<code>Multiply</code> methods can also be achieved using either the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3280	href="command-line-options.html#level" >-level</a> or the <a href="command-line-options.html#level" >+level</a> operator, with
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3281	appropriate argument, to linearly modify the overall range of color values.
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3282	Please note, however, that <a href="command-line-options.html#level" >-level</a> treats transparency as
				3283	'matte' values (0 = opaque), while <a href="command-line-options.html#level" >-evaluate</a> works with
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3284	'alpha' values.</p>
				3285
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3286	<p><code>AddModulus</code> has been added as of ImageMagick 6.4.8-4 and provides
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3287	addition modulo the <em class="QR">QuantumRange</em>. It is therefore
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3288	equivalent to <code>Add</code> unless the resulting pixel value is outside the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3289	interval [0, <em class="QR">QuantumRange</em>]. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3290
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3291	<p><code>Exp or Exponential</code> has been added as of ImageMagick 6.6.5-1 and
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3292	works on normalized pixel values. The <em class="arg">value</em> used with
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3293	<code>Exp</code> should be negative so as to produce a decaying exponential
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3294	function. Non-negative values will always produce results larger unity and
				3295	thus outside the interval [0, <em class="QR">QuantumRange</em>]. The
				3296	formula is expressed below. </p>
cristy	ce66ab1	2010-10-21 23:36:32 +0000	[diff] [blame]	3297
				3298	<div style="text-align:center;">
				3299	exp(<em class="arg">value</em> × <b><em>u</em></b>)
				3300	</div>
				3301
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3302	<p> If the input image is squared, for example, using <a href="command-line-options.html#-function"
				3303	>-function polynomial "2 0 0"</a>, then a decaying Gaussian function will be
				3304	the result.</p>
cristy	ce66ab1	2010-10-21 23:36:32 +0000	[diff] [blame]	3305
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3306	<p><code>Log</code> has been added as of ImageMagick 6.4.2-1 and works on
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3307	normalized pixel values. This a <em>scaled</em> log function. The <em
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3308	class="arg">value</em> used with <code>Log</code> provides a <em>scaling
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3309	factor</em> that adjusts the curvature in the graph of the log function. The
				3310	formula applied to a normalized value <b><em>u</em></b> is below. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3311
				3312	<div style="text-align:center;">
				3313	log(<em class="arg">value</em> × <b><em>u</em></b> + 1) / log(<em class="arg">value</em> + 1)
				3314	</div>
				3315
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3316	<p><code>Pow</code> has been added as of ImageMagick 6.4.1-9, and works on
				3317	normalized pixel values. Note that <code>Pow</code> is related to the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3318	href="command-line-options.html#gamma" >-gamma</a> operator. For example, <b>-gamma 2</b> is equivalent
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3319	to <b>-evaluate pow 0.5</b>, i.e., a 'square root' function. The value used
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3320	with <a href="command-line-options.html#gamma" >-gamma</a> is simply the reciprocal of the value used
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3321	with <code>Pow</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3322
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3323	<p><code>Cosine</code> and <code>Sine</code> was added as of IM v6.4.8-8 and
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3324	converts the image values into a value according to a (co)sine wave function.
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3325	The synonyms <code>Cos</code> and <code>Sin</code> may also be used. The output
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3326	is biased 50% and normalized by 50% so as to fit in the respective color value
				3327	range. The <em class="arg">value</em> scaling of the <em>period</em> of the
				3328	function (its frequency), and thus determines the number of 'waves' that will
				3329	be generated over the input color range. For example, if the <em
				3330	class="arg">value</em> is 1, the effective period is simply the <em
				3331	class="QR">QuantumRange</em>; but if the <em class="arg">value</em> is 2,
				3332	then the effective period is the <em>half</em> the <em
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3333	class="QR">QuantumRange</em>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3334
				3335	<div style="text-align:center;">
				3336	0.5 + 0.5 × cos(2 π <b><em>u</em></b> × <em class="arg">value</em>).
				3337	</div>
				3338
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3339	<p>See also the <a href="command-line-options.html#function" >-function</a> operator, which is a
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3340	multi-value version of evaluate. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3341
cristy	63fed27	2010-03-07 19:08:45 +0000	[diff] [blame]	3342	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3343	<h4><a id="evaluate-sequence"></a>-evaluate-sequence <em class="arg">operator</em></h4>
cristy	63fed27	2010-03-07 19:08:45 +0000	[diff] [blame]	3344	</div>
				3345
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3346	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Alter channel pixels by evaluating an arithmetic, relational, or
				3347	logical expression over a sequence of images.</td><td style='text-align:right;'></td></tr></table>
				3348
				3349	<p>To print a complete list of <a
				3350	href="command-line-options.html#evaluate-sequence">-evaluate-sequence</a> operators, use <a
				3351	href="command-line-options.html#list">-list evaluate</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3352
				3353	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3354	<h4><a id="extent"></a>-extent <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3355	</div>
				3356
				3357	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the image size and offset.</td><td style='text-align:right;'></td></tr></table>
				3358
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3359	<p>If the image is enlarged, unfilled areas are set to the background color.
				3360	To position the image, use offsets in the <em class="arg">geometry</em>
				3361	specification or precede with a <a href="command-line-options.html#gravity">-gravity</a> setting. To
				3362	specify how to compose the image with the background, use <a href="command-line-options.html#compose"
				3363	>-compose</a>.</p>
				3364
cristy	549177c	2010-11-11 13:51:21 +0000	[diff] [blame]	3365	<p>This command reduces or expands a JPEG image to fit on an 800x600
				3366	display. If the aspect ratio of the input image isn't exactly 4:3, then the
				3367	image is centered on an 800x600 black canvas: </p>
				3368
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	3369	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert input.jpg -resize 800x600 -background black -compose Copy \ <br /> -gravity center -extent 800x600 -quality 92 output.jpg</span></p>
cristy	549177c	2010-11-11 13:51:21 +0000	[diff] [blame]	3370
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3371
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3372	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3373
				3374	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3375	<h4><a id="extract"></a>-extract <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3376	</div>
				3377
				3378	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Extract the specified area from image.</td><td style='text-align:right;'></td></tr></table>
				3379
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3380	<p>This option is most useful for extracting a subregion of a very large raw
				3381	image. Note that these two commands are equivalent:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3382
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	3383	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert -size 16000x16000 -depth 8 -extract 640x480+1280+960 \ <br/> image.rgb image.png</span><span class='crtout'></span><span class="crtprompt"> $ </span><span class='crtin'>convert -size 16000x16000 -depth 8 'image.rgb[640x480+1280+960]' \ <br/> image.rgb image.png</span></p><p>If you omit the offsets, as in</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3384
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	3385	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert -size 16000x16000 -depth 8 -extract 640x480 \ <br/> image.rgb image.png</span></p>
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	3386	<p>the image is <em>resized</em> to the specified dimensions instead,
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3387	equivalent to:</p>
				3388
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	3389	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert -size 16000x16000 -depth 8 -resize 640x480 image.rgb image.png</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3390	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3391
				3392	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3393	<h4><a id="family"></a>-family <em class="arg">fontFamily</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3394	</div>
				3395
				3396	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set a font family for text.</td><td style='text-align:right;'></td></tr></table>
				3397
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3398	<p>This setting suggests a font family that ImageMagick should try to use for
				3399	rendering text. If the family can be found it is used; if not, a default font
				3400	(e.g., "Arial") or a family known to be similar is substituted (e.g.,
				3401	"Courier" might be used if "System" is requested but not found). </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3402
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3403	<p>For other settings that affect fonts, see the options <a
				3404	href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a
				3405	href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3406
				3407	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3408	<h4><a id="features"></a>-features <em class="arg">distance</em></h4>
cristy	7396d88	2010-01-27 02:37:56 +0000	[diff] [blame]	3409	</div>
				3410
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3411	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>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.</td><td style='text-align:right;'>[<a href="identify.html">identify</a>]</td></tr></table>
				3412
				3413	<pre class="text">
				3414	Angular Second Moment
				3415	Contrast
				3416	Correlation
				3417	Sum of Squares Variance
				3418	Inverse Difference Moment
				3419	Sum Average
				3420	Sum Variance
				3421	Sum Entropy
				3422	Entropy
				3423	Difference Variance
				3424	Difference Entropy
				3425	Information Measure of Correlation 1
				3426	Information Measure of Correlation 2
				3427	Maximum Correlation Coefficient
				3428	</pre>
				3429
cristy	7396d88	2010-01-27 02:37:56 +0000	[diff] [blame]	3430
				3431	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3432	<h4><a id="fft"></a>-fft</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3433	</div>
				3434
				3435	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>implements the forward discrete Fourier transform (DFT).</td><td style='text-align:right;'></td></tr></table>
				3436
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3437	<p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows
				3438	users in ImageMagick 6.6.0-9). It transforms an image from the normal
				3439	(spatial) domain to the frequency domain. In the frequency domain, an image is
				3440	represented as a superposition of complex sinusoidal waves of varying
				3441	amplitudes. The image x and y coordinates are the possible frequencies along
				3442	the x and y directions, respectively, and the pixel intensity values are
				3443	complex numbers that correspond to the sinusoidal wave amplitudes. See for
				3444	example, <a href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier
				3445	Transform</a>, <a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier
				3446	Transform</a> and <a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier
				3447	Transform</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3448
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3449	<p>A single image name is provided as output for this option. However, the
				3450	output result will have two components. It is either a two-frame image or two
				3451	separate images, depending upon whether the image format specified supports
				3452	multi-frame images. The reason that we get a dual output result is because the
				3453	frequency domain represents an image using complex numbers, which cannot be
				3454	visualized directly. Therefore, the complex values are automagically separated
				3455	into a two-component image representation. The first component is the
				3456	magnitude of the complex number and the second is the phase of the complex
				3457	number. See for example, <a
				3458	href="http://en.wikipedia.org/wiki/Complex_numbers">Complex Numbers</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3459
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3460	<p>The magnitude and phase component images must be specified using image
				3461	formats that do not limit the color or compress the image. Thus, MIFF, TIF,
				3462	PFM, EXR and PNG are the recommended image formats to use. All of these
				3463	formats, except PNG support multi-frame images. So for example,</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3464
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	3465	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert image.png -fft fft_image.miff</span></p>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3466	<p>generates a magnitude image as <code>fft_image.miff[0]</code> and a phase
				3467	image as <code>fft_image.miff[1]</code>. Similarly,</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3468
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	3469	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert image.png -fft fft_image.png</span></p>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3470	<p>generates a magnitude image as <code>fft_image-0.png</code> and a phase image
				3471	as <code>fft_image-1.png</code>. If you prefer this representation, then you can
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3472	force any of the other formats to produce two output images by including <a
				3473	href="command-line-options.html#adjoin">+adjoin</a> following -fft in the command line.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3474
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3475	<p>The input image can be any size, but if not square and even-dimensioned, it
				3476	is padded automagically to the larger of the width or height of the input
				3477	image and to an even number of pixels. The padding will occur at the bottom
				3478	and/or right sides of the input image. The resulting output magnitude and
				3479	phase images is square at this size. The kind of padding relies on the <a
				3480	href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3481
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3482	<p>Both output components will have dynamic ranges that fit within
				3483	[0, <em class="QR">QuantumRange</em>], so that HDRI need not be enabled.
				3484	Phase values nominally range from 0 to 2*π, but is scaled to span the full
				3485	dynamic range. (The first few releases had non-HDRI scaled but HDRI not
				3486	scaled). The magnitude image is not scaled and thus generally will contain
				3487	very small values. As such, the image normally will appear totally black. In
				3488	order to view any detail, the magnitude image typically is enhanced with a log
				3489	function into what is usually called the spectrum. A log function is used to
				3490	enhance the darker values more in comparison to the lighter values. This can
				3491	be done, for example, as follows:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3492
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	3493	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert fft_image.miff[0] -contrast-stretch 0 \ <br />
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3494	-evaluate log 1000 fft_image_spectrum.png</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3495	<p>where either <a href="command-line-options.html#contrast-stretch">-contrast-stretch</a> 0 or <a
				3496	href="command-line-options.html#auto-level">-auto-level</a> is used to scale the image to full dynamic
				3497	range, first. The argument to the <a href="command-line-options.html#evaluate">-evaluate</a> log
				3498	typically is specified between 100 and 10,000, depending upon the amount of
				3499	detail that one wants to bring out in the spectrum. Larger values produce more
				3500	visible detail. Too much detail, however, may hide the important features.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3501
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3502	<p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to
				3503	use <a href="command-line-options.html#fft">-fft</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3504
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3505	<p>Use <a href="command-line-options.html#fft">+fft</a> to produce two output images that are the real
				3506	and imaginary components of the complex valued Fourier transform.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3507
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3508	<p>However, as the real and imaginary components can contain negative values,
				3509	this requires that IM be configured with HDRI enabled. In this case, you must
				3510	use either MIFF, TIF, PFM or MPC formats for the real and imaginary component
				3511	results, since they are formats that preserve both negative and fractional
				3512	values without clipping them or truncating the fractional part. With either
				3513	MIFF or TIF, one should add -define quantum:format=32, to allow those image
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	3514	types to work properly in HDRI mode without clipping.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3515
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3516	<p>The real and imaginary component images resulting from <a
				3517	href="command-line-options.html#fft">+fft</a> are also square, even dimensioned images due to the same
				3518	padding that was discussed above for the magnitude and phase component
				3519	images.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3520
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3521	<p>See the discussion on HDRI implementations of ImageMagick on the page <a
				3522	href="high-dynamic-range.html" >High Dynamic-Range Images</a>. For more
				3523	about HDRI go the ImageMagick <a
				3524	href="http://www.imagemagick.org/Usage/basics/#hdri" >Usage</a> pages, <a
				3525	href="http://www.fmwconcepts.com/imagemagick/fourier_transforms/fourier.html"
				3526	>Fred's Fourier Processing With ImageMagick page</a> or this <a
				3527	href="http://en.wikipedia.org/wiki/High_dynamic_range_imaging" >Wikipedia</a>
				3528	entry. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3529
				3530
				3531	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3532	<h4><a id="fill"></a>-fill <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3533	</div>
				3534
				3535	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>color to use when filling a graphic primitive.</td><td style='text-align:right;'></td></tr></table>
				3536
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3537	<p>This option accepts a color name, a hex color, or a numerical RGB, RGBA,
				3538	HSL, HSLA, CMYK, or CMYKA specification. See <a href="color.html" >Color Names</a> for
				3539	a description of how to properly specify the color argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3540
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3541	<p>Enclose the color specification in quotation marks to prevent the "#" or
				3542	the parentheses from being interpreted by your shell.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3543
				3544	<p>For example,</p>
				3545
				3546	<p class="crtsnip">
				3547	-fill blue
				3548	</p>
				3549	<p class="crtsnip">
				3550	-fill "#ddddff"
				3551	</p>
				3552	<p class="crtsnip">
				3553	-fill "rgb(255,255,255)"
				3554	</p>
				3555
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3556	<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3557
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3558	<p>To print a complete list of color names, use the <a href="command-line-options.html#list">-list color</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3559
				3560	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3561	<h4><a id="filter"></a>-filter <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3562	</div>
				3563
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3564	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Use this <em class="arg">type</em> of filter when resizing or
				3565	distorting an image.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3566
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3567	<p>Use this option to affect the resizing operation of an image during
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3568	operations such as <a href="command-line-options.html#resize">-resize</a> and <a href="command-line-options.html#distort"
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3569	>-distort</a>. For example you can use a simple resize filter such as:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3570
				3571	<pre class="text">
				3572	Point Hermite Cubic
				3573	Box Gaussian Catrom
				3574	Triangle Quadratic Mitchell
				3575	</pre>
				3576
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3577	<p>The <code>Bessel</code> and <code>Sinc</code> filter is also provided (as well
				3578	as a faster <code>SincFast</code> equivalent form). However these filters are
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	3579	generally useless on their own as they are infinite filters that are being
				3580	clipped to the filters support size. Their direct use is not recommended
				3581	except via expert settings (see below). </p>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3582
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3583	<p>Instead these special filter functions are typically windowed by a windowing
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3584	function that the <a href="command-line-options.html#filter" >-filter</a> setting defines. That is
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3585	using these functions will define a 'Windowed' filter, appropriate to the
				3586	operator involved. Windowed filters include: </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3587
				3588	<pre class="text">
				3589	Lanczos Hamming Parzen
				3590	Blackman Kaiser Welsh
				3591	Hanning Bartlett Bohman
				3592	</pre>
				3593
				3594	<p>Also one special self-windowing filter is also provided
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3595	<code>Lagrange</code>, which will automagically re-adjust its function depending
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3596	on the current 'support' or 'lobes' expert settings (see below).</p>
				3597
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3598	<p>If you do not select a filter with this option, the filter defaults to
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3599	<code>Mitchell</code> for a colormapped image, an image with a matte channel, or
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3600	if the image is enlarged. Otherwise the filter default to
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3601	<code>Lanczos</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3602
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3603	<p>To print a complete list of resize filters, use the <a href="command-line-options.html#list">-list
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3604	filter</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3605
				3606	<p>You can modify how the filter behaves as it scales your image through the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3607	use of these expert settings (see also <a href="command-line-options.html#define" >-define</a> and <a
				3608	href="command-line-options.html#set" >-set</a>):-</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3609
				3610	<dl class="doc">
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3611	<dt>-define filter:blur=<em>factor</em></dt>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3612	<dd>Scale the X axis of the filter (and its window). Use > 1.0 for
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3613	blurry or < 1.0 for sharp. This should only be used with Gaussian and
				3614	Gaussian-like filters simple filters, or you may not get the expected
				3615	results. </dd>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3616
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3617	<dt>-define filter:support=<em>radius</em></dt>
				3618	<dd>Set the filter support radius. Defines how large the filter should be and
				3619	thus directly defines how slow the filtered resampling process is. All
				3620	filters have a default 'prefered' support size. Some filters like
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3621	<code>Lagrange</code> and windowed filters adjust themselves depending on
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3622	this value. With simple filters this value either does nothing (but slow
				3623	the resampling), or will clip the filter function in a detrimental way.
				3624	</dd>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3625
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3626	<dt>-define filter:lobes=<em>count</em></dt>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3627	<dd>Set the number of lobes to use for the Sinc/Bessel filter. This an
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3628	alternative way of specifying the 'support' range of the filter, that is
				3629	designed to be more suited to windowed filters, especially when used for
				3630	image distorts.</dd>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3631
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3632	<dt>-define filter:sigma=<em>value</em></dt>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3633	<dd>The 'sigma' value used to define the <code>Gaussian</code> filter. Default
				3634	sigma value is '<code>0.5</code>'. It only effects <code>Gaussian</code> but
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3635	does not shrink (but may enlarge) the filter's 'support'. It can be used
				3636	to generate very small blurs but without the filter 'missing' pixels due
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3637	to using a small support setting. A larger value of '<code>0.707</code>'
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3638	(a value of '1/sqrt(2)') is another common setting. </dd>
				3639
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3640	<dt>-define filter:b=<em>b-spline_factor</em></dt>
				3641	<dt>-define filter:c=<em>keys_alpha_factor</em></dt>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3642	<dd>Redefine the values used for cubic filters such as <code>Cubic</code>,
				3643	<code>Catrom</code>, <code>Mitchel</code>, and <code>Hermite</code>, as well as
				3644	the <code>Parzen</code> cubic windowing function. If only one of the values
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3645	are defined, the other is set so as to generate a 'Cubic-Keys' filter.
				3646	The values meaning was defined by a research paper by
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3647	Mitchell-Netravali.</dd>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3648
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3649	<dt>-define filter:kaiser-beta=<em>value</em></dt>
				3650	<dd>The 'alpha' value used to as part of the Kaiser Windowing function.
				3651	Default value is '6.5'. It only effects Kaiser windowing function, and
				3652	does not effect any other attributes.</dd>
				3653
				3654	<dd>Before IM v6.7.6-10, this option was known as "filter:alpha", (an
				3655	inheritance from the very old "zoom" program). It was changed to bring the
				3656	function in line with more modern academic research usage, and better
				3657	assign it be more definitive. </dd>
				3658
				3659	<dt>-define filter:kaiser-alpha=<em>value</em></dt>
				3660	<dd>This value when multiplied by 'PI' is equivelent to "kaiser-beta", and
				3661	will override that setting. It only effects Kaiser windowing function,
				3662	and does not effect any other attributes. </dd>
				3663
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3664	<dt>-define filter:filter=<em>filter_function</em></dt>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3665	<dd>Use this function directly as the weighting filter. This will allow
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3666	you to directly use a windowing function such as <code>Blackman</code>,
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3667	as a resampling filter, rather than as its normal usage as a windowing
				3668	function. </dd>
				3669
				3670	<dd>If defined, no windowing function also defined, the window function is set
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3671	to <code>Box</code>). Directly specifying <code>Sinc</code> or <code>Jinc</code>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3672	as a filter will also do this. </dd>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3673
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3674	<dt>-define filter:window=<em>filter_function</em></dt>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3675	<dd>The IIR (infinite impulse response) filters <code>Sinc</code> and
				3676	<code>Jinc</code> are windowed (brought down to zero over the defined
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3677	support range) with the given filter. This allows you to specify a filter
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3678	function to be used as a windowing function for these IIR filters. </dd>
				3679
				3680	<dd>Many of the defined filters are actually windowing functions for these IIR
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3681	filters. A typical choices is <code>Box</code>, (which effectively turns
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3682	off the windowing function). </dd>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3683
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3684	<dt>-define filter:win-support=<em>radius</em></dt>
				3685	<dd>Scale windowing function to this size instead. This causes the windowing
				3686	(or self-windowing Lagrange filter) to act is if the support window is
				3687	larger than what is actually supplied to the calling operator. The filter
				3688	however is still clipped to the real support size given. If unset this
				3689	will equal the normal filter support size. </dd>
				3690
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	3691	<dt>-define filter:verbose=<em>1</em></dt>
				3692	<dd>This causes IM to print information on the final internal filter
				3693	selection to standard output. This includes a commented header on the
				3694	filter settings being used, and data allowing the filter weights to be
				3695	easily graphed. </dd>
				3696
				3697	<dd>Note however that some filters are internally defined in terms of other
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3698	filters. The <code>Lanczos</code> filter for example is defined in terms of
				3699	a <code>SincFast</code> windowed <code>SincFast</code> filter, while
				3700	<code>Mitchell</code> is defined as a general <code>Cubic</code> family filter
				3701	with specific 'B' and 'C' settings. </dd>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3702
				3703	</dl>
				3704
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3705	<p>For example, to get a 8 lobe jinc windowed sinc filter (Genseng filter?):</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3706
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3707	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert image.png \<br/>
				3708	-filter sinc \<br/>
				3709	-set filter:window=jinc \<br/>
				3710	-set filter:lobes=8 \<br/>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3711	-resize 150% image.jpg</span></p>
				3712	<p>Or a raw un-windowed Sinc filter with 4 lobes:</p>
				3713
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3714	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert image.png \<br/>
				3715	-set filter:filter=sinc \<br/>
				3716	-set filter:lobes=4 \<br/>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3717	-resize 150% image.jpg</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3718	<p>To extract the data for a raw windowing function, combine it with
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3719	a '<code>Box</code>' filter. For example the '<code>Welch</code> parabolic
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3720	windowing function. </p>
				3721
				3722	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert null: -define filter:filter=Box \<br/>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3723	-define filter:window=Welch \<br/>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3724	-define filter:support=1.0 \<br/>
				3725	-define filter:verbose=1 \<br/>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3726	-resize 2 null: > window_welch.dat<br/>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3727	gnuplot<br/>
				3728	set grid<br/>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3729	plot "window_welch.dat" with lines</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3730	<p>Note that the use of expert options is provided for image processing experts
				3731	who have studied and understand how resize filters work. Without this
				3732	knowledge, and an understanding of the definition of the actual filters
				3733	involved, using expert settings are more likely to be detrimental to your image
				3734	resizing.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3735
				3736
				3737	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3738	<h4><a id="flatten"></a>-flatten</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3739	</div>
				3740
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3741	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>This is a simple alias for the <a href="command-line-options.html#layers" >-layers</a> method "flatten".</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3742
				3743
				3744	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3745	<h4><a id="flip"></a>-flip</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3746	</div>
				3747
				3748	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>create a <em>mirror image</em>.</td><td style='text-align:right;'></td></tr></table>
				3749
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	3750	<p>reflect the scanlines in the vertical direction. The image will be mirrored
				3751	upside-down. </p>
				3752
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3753
				3754	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3755	<h4><a id="floodfill"></a>-floodfill {<em class="arg">+-</em>}<em class="arg">x</em>{<em class="arg">+-</em>}<em class="arg">y</em> <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3756	</div>
				3757
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	3758	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>floodfill the image with color at the specified offset.</td><td style='text-align:right;'></td></tr></table>
				3759
				3760	<p>Flood fill starts from the given 'seed point' which is not gravity effected.
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3761	Any color that matches within <a href="command-line-options.html#fuzz" >-fuzz</a> color distance of the
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	3762	given <em class="arg">color</em> argument, connected to that 'seed point'
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3763	will be replaced with the current <a href="command-line-options.html#fill" >-fill</a> color. </p>
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	3764
				3765	<p>Note that if the pixel at the 'seed point' does not itself match the given
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3766	<em class="arg">color</em> (according to <a href="command-line-options.html#fuzz" >-fuzz</a>), then no
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	3767	action will be taken. </p>
				3768
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3769	<p>This operator works more like the <a href="command-line-options.html#opaque" >-opaque</A> option, than
				3770	a more general flood fill that reads the matching color directly at the 'seed
				3771	point'. For this form of flood fill, look at <a href="command-line-options.html#draw" >-draw</a> and
				3772	its 'color floodfill' drawing method. </p>
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	3773
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3774
				3775	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3776	<h4><a id="flop"></a>-flop</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3777	</div>
				3778
				3779	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>create a <em>mirror image</em>.</td><td style='text-align:right;'></td></tr></table>
				3780
cristy	2dcd682	2011-06-13 16:21:20 +0000	[diff] [blame]	3781	<p>Reflect the scanlines in the horizontal direction, just like the image in
				3782	a vertical mirror. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3783
				3784
				3785	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3786	<h4><a id="font"></a>-font <em class="arg">name</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3787	</div>
				3788
				3789	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>set the font to use when annotating images with text, or creating labels.</td><td style='text-align:right;'></td></tr></table>
				3790
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3791	<p>To print a complete list of fonts, use the <a href="command-line-options.html#list">-list font</a>
				3792	option (for versions prior to 6.3.6, use 'type' instead of 'font').</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3793
				3794	<p>In addition to the fonts specified by the above pre-defined list, you can
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3795	also specify a font from a specific source. For example <code>Arial.ttf</code>
				3796	is a TrueType font file, <code>ps:helvetica</code> is PostScript font, and
				3797	<code>x:fixed</code> is X11 font.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3798
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3799	<p>For other settings that affect fonts, see the options <a
				3800	href="command-line-options.html#family">-family</a>, <a href="command-line-options.html#stretch">-stretch</a>, <a
				3801	href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3802
				3803
				3804	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3805	<h4><a id="foreground"></a>-foreground <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3806	</div>
				3807
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3808	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Define the foreground color for menus.</td><td style='text-align:right;'>[<a href="display.html">display</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3809
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3810	<p>The color is specified using the format described under the <a
				3811	href="command-line-options.html#fill">-fill</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3812
				3813	<p>The default foreground color is black.</p>
				3814
				3815	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3816	<h4><a id="format"></a>-format <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3817	</div>
				3818
				3819	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>the image format type.</td><td style='text-align:right;'></td></tr></table>
				3820
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3821	<p>When used with the <code>mogrify</code> utility, this option converts any
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3822	image to the image <a href="formats.html">format</a> you specify.
				3823	For a list of image format types supported by ImageMagick, use <a
				3824	href="command-line-options.html#list">-list format</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3825
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3826	<p>By default the file is written to its original name. However, if the
				3827	filename extension matches a supported format, the extension is replaced with
				3828	the image format type specified with <a href="command-line-options.html#format">-format</a>. For
				3829	example, if you specify <em class="arg">tiff</em> as the format type and the
				3830	input image filename is <em class="arg">image.gif</em>, the output image
				3831	filename becomes <em class="arg">image.tiff</em>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3832
				3833	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3834	<h4><a id="format_identify_"></a>-format <em class="arg">string</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3835	</div>
				3836
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3837	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>output formatted image characteristics.</td><td style='text-align:right;'>[<a href="identify.html">identify</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3838
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3839	<p>See <a href="escape.html">Format and Print Image
				3840	Properties</a> for an explanation on how to specify the argument to this
				3841	option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3842
				3843	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3844	<h4><a id="frame"></a>-frame <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3845	</div>
				3846
				3847	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Surround the image with a border or beveled frame.</td><td style='text-align:right;'></td></tr></table>
				3848
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3849	<p>The color of the border is specified with the <a href="command-line-options.html#mattecolor"
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	3850	>-mattecolor</a> command line option. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3851
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3852	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. The <em class="arg">size</em> portion of the <em
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	3853	class="arg">geometry</em> argument indicates the amount of extra width and
				3854	height that is added to the dimensions of the image. If no offsets are given
				3855	in the <em class="arg">geometry</em> argument, then the border added is
				3856	a solid color. Offsets <em>x</em> and <em>y</em>, if present, specify that
				3857	the width and height of the border is partitioned to form an outer bevel of
				3858	thickness <em>x</em> pixels and an inner bevel of thickness
				3859	<em>y</em> pixels. Negative offsets make no sense as frame arguments.
				3860	</p>
				3861
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3862	<p>The <a href="command-line-options.html#frame">-frame</a> option is affected by the current <a
				3863	href="command-line-options.html#compose">-compose</a> setting and assumes that this is using the default
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3864	'<code>Over</code>' composition method. It generates an image of the appropriate
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3865	size with the current <a href="command-line-options.html#bordercolor">-bordercolor</a> setting, and then
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	3866	draws the frame of four distinct colors close to the current <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3867	href="command-line-options.html#mattecolor">-mattecolor</a>. The original image is then overlaid onto
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	3868	center of this image. This means that with the default compose method of
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3869	'<code>Over</code>' any transparent parts may be replaced by the current <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3870	href="command-line-options.html#bordercolor">-bordercolor</a> setting.</p>
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	3871
				3872	<p>The image composition is not
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3873	affected by the <a href="command-line-options.html#gravity">-gravity</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3874
				3875
				3876	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3877	<h4><a id="frame_import_"></a>-frame</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3878	</div>
				3879
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3880	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>include the X window frame in the imported image.</td><td style='text-align:right;'>[<a href="import.html">import</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3881
				3882	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	3883	<h4><a id="function"></a>-function <em class="arg">function</em> <em class="arg">parameters</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3884	</div>
				3885
				3886	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply a function to channel values.</td><td style='text-align:right;'></td></tr></table>
				3887
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3888	<p>This operator performs calculations based on the given arguments to modify
				3889	each of the color values for each previously set <a
				3890	href="command-line-options.html#channel">-channel</a> in the image. See <a
				3891	href="command-line-options.html#evaluate">-evaluate</a> for details concerning how the results of the
				3892	calculations are handled.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3893
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3894	<p>This is can be considered a multi-argument version of the <a
				3895	href="command-line-options.html#evaluate">-evaluate</a> operator. (Added in
				3896	ImageMagick 6.4.8−8.)</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3897
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3898	<p>Here, <em class="arg">parameters</em> is a comma-separated list of
				3899	numerical values. The number of values varies depending on which <em
				3900	class="arg">function</em> is selected. Choose the <em
				3901	class="arg">function</em> from:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3902
				3903	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	3904	Polynomial
				3905	Sinusoid
				3906	Arcsin
				3907	Arctan
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3908	</pre>
				3909
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3910	<p>To print a complete list of <a href="command-line-options.html#function">-function</a> operators,
				3911	use <a href="command-line-options.html#list">-list function</a>. Descriptions follow.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3912
				3913	<dl class="doc">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3914	<dt><code>Polynomial</code></dt>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3915	<dd>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3916
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3917	<p>The <code>Polynomial</code> function takes an arbitrary number of parameters,
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3918	these being the coefficients of a polynomial, in decreasing order of degree.
				3919	That is, entering</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3920
				3921	<div style="text-align: center">
				3922	-function Polynomial <em>a</em><sub><em>n</em></sub>,<em>a</em><sub><em>n</em>-1</sub>,...<em>a</em><sub>1</sub>,<em>a</em><sub>0</sub>
				3923	</div>
				3924
				3925	<p>will invoke a polynomial function given by</p>
				3926
				3927	<div style="text-align: center">
				3928	<em>a</em><sub><em>n</em></sub> <b><em>u</em></b><sup><em>n</em></sup> +
				3929	<em>a</em><sub><em>n</em>-1</sub> <b><em>u</em></b><sup><em>n</em>-1</sup> +
				3930	··· <em>a</em><sub>1</sub> <b><em>u</em></b> + <em>a</em><sub>0</sub>,
				3931	</div>
				3932
				3933	<p>where <b><em>u</em></b> is pixel's original normalized channel value.</p>
				3934
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3935	<p>The <code>Polynomial</code> function can be used in place of <code>Set</code>
				3936	(the <em>constant</em> polynomial) and <code>Add</code>, <code>Divide</code>,
				3937	<code>Multiply</code>, and <code>Subtract</code> (some <em>linear</em>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3938	polynomials) of the <a href="command-line-options.html#evaluate">-evaluate</a> operator. The <a
				3939	href="command-line-options.html#level">-level</a> operator also affects channels linearly. Some
				3940	correspondences follow.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3941
				3942	<table class="doc">
				3943	<col width="35%" />
				3944	<col width="35%" />
				3945	<col width="30%" />
				3946	<tr>
				3947	<td>-evaluate Set <em class="arg">value</em> </td>
				3948	<td>-function Polynomial <em class="arg">value</em></td>
				3949	<td>(Constant functions; set <em class="arg">value</em>×100% gray when channels are RGB.)</td>
				3950	</tr>
				3951	<tr>
				3952	<td>-evaluate Add <em class="arg">value</em> </td>
				3953	<td>-function Polynomial 1,<em class="arg">value</em></td>
				3954	</tr>
				3955	<tr>
				3956	<td>-evaluate Subtract <em class="arg">value</em> </td>
				3957	<td>-function Polynomial 1,−<em class="arg">value</em></td>
				3958	</tr>
				3959	<tr>
				3960	<td>-evaluate Multiply <em class="arg">value</em> </td>
				3961	<td>-function Polynomial <em class="arg">value</em>,0</td>
				3962	</tr>
				3963	<tr>
				3964	<td>+level black% x white%</td>
				3965	<td>-function Polynomial A,B</td>
				3966	<td>(Reduce contrast. Here, A=(white-black)/100 and B=black/100.)</td>
				3967	</tr>
				3968	</table>
				3969
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3970	<p>The <code>Polynomial</code> function gives great versatility, since
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3971	polynomials can be used to fit any continuous curve to any degree of accuracy
				3972	desired.</p>
				3973
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3974	</dd>
				3975
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3976	<dt><code>Sinusoid</code></dt>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3977	<dd>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3978	<p>The <code>Sinusoid</code> function can be used to vary the channel values
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3979	sinusoidally by setting frequency, phase shift, amplitude, and a bias. These
				3980	values are given as one to four parameters, as follows,</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3981
				3982	<div style="text-align: center">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	3983	-function <code>Sinusoid</code> <em class="arg">freq</em>,[<em class="arg">phase</em>,[<em class="arg">amp</em>,[<em class="arg">bias</em>]]]
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3984	</div>
				3985
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3986	<p>where <em>phase</em> is in degrees. (The domain [0,1] of the function
				3987	corresponds to 0 through <em class="arg">freq</em>×360 degrees.)
				3988	The result is that if a pixel's normalized channel value is originally
				3989	<b><em>u</em></b>, its resulting normalized value is given by </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3990
				3991	<div style="text-align: center">
				3992	<em class="arg">amp</em> * sin(2π (<em class="arg">freq</em> * <b><em>u</em></b> + <em class="arg">phase</em> / 360)) + <em class="arg">bias</em>
				3993	</div>
				3994
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	3995	<p> For example, the following generates a curve that starts and ends at 0.9
				3996	(when <b><em>u</em></b>=0 and 1, resp.), oscillating three times between
				3997	.7−.2=.5 and .7+.2=.9. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	3998
				3999	<p class="crtsnip">
				4000	-function Sinusoid 3,-90,.2,.7
				4001	</p>
				4002
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4003	<p>The default values of <em class="arg">amp</em> and <em
				4004	class="arg">bias</em> are both .5. The default for <em class="arg">phase</em>
				4005	is 0.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4006
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4007	<p>The <code>Sinusoid</code> function generalizes <code>Sin</code> and
				4008	<code>Cos</code> of the <a href="command-line-options.html#evaluate">-evaluate</a> operator by allowing
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4009	varying amplitude, phase and bias. The correspondence is as follows.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4010
				4011	<table class="doc">
				4012	<tr>
				4013	<td>-evaluate Sin <em class="arg">freq</em> </td>
				4014	<td>-function Sinusoid <em class="arg">freq</em>,0 </td>
				4015	</tr>
				4016	<tr>
				4017	<td>-evaluate Cos <em class="arg">freq</em> </td>
				4018	<td>-function Sinusoid <em class="arg">freq</em>,90 </td>
				4019	</tr>
				4020	</table>
				4021	</dd>
				4022
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4023	<dt><code>ArcSin</code></dt>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4024	<dd>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4025	<p>The <code>ArcSin</code> function generates the inverse curve of a Sinusoid,
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4026	and can be used to generate cylindrical distortion and displacement maps.
				4027	The curve can be adjusted relative to both the input values and output range
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4028	of values.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4029
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4030	<p style="text-align: center">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4031	-function <code>ArcSin</code> <em class="arg">width</em>,[<em class="arg">center</em>,[<em class="arg">range</em>,[<em class="arg">bias</em>]]]
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4032	</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4033
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4034	<p>with all values given in terms of normalized color values (0.0 for black,
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4035	1.0 for white). Defaulting to values covering the full range from 0.0 to 1.0
				4036	for bout input (<em class="arg">width</em>), and output (<em
				4037	class="arg">width</em>) values. '<code>1.0,0.5,1.0,0.5</code>' </p>
				4038
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4039	<p style="text-align: center">
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4040	<em class="arg">range</em>/π * asin( 2/<em class="arg">width</em> * ( <b><em>u</em></b> - <em class="arg">center</em> ) ) + <em class="arg">bias</em>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4041	</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4042
				4043	</dd>
				4044
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4045	<dt><code>ArcTan</code></dt>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4046	<dd>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4047	<p>The <code>ArcTan</code> function generates a curve that smooth crosses from
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4048	limit values at infinities, though a center using the given slope value.
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4049	All these values can be adjusted via the arguments.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4050
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4051	<p style="text-align: center">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4052	-function <code>ArcTan</code> <em class="arg">slope</em>,[<em class="arg">center</em>,[<em class="arg">range</em>,[<em class="arg">bias</em>]]]
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4053	</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4054
				4055	<p>Defaulting to '<code>1.0,0.5,1.0,0.5</code>'.
				4056	</p>
				4057
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4058	<p style="text-align: center">
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4059	<em class="arg">range</em>/π * atan( <em class="arg">slope</em>π ( <b><em>u</em></b> - <em class="arg">center</em> ) ) + <em class="arg">bias</em>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4060	</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4061
				4062	</dd>
				4063
				4064	</dl>
				4065
				4066
				4067	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4068	<h4><a id="fuzz"></a>-fuzz <em class="arg">distance</em>{<em class="arg">%</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4069	</div>
				4070
				4071	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Colors within this <em class="arg">distance</em> are considered equal.</td><td style='text-align:right;'></td></tr></table>
				4072
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4073	<p>A number of algorithms search for a target color. By default the color must
				4074	be exact. Use this option to match colors that are close to the target color
				4075	in RGB space. For example, if you want to automagically trim the edges of an
				4076	image with <a href="command-line-options.html#trim">-trim</a> but the image was scanned and the target
				4077	background color may differ by a small amount. This option can account for
				4078	these differences.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4079
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4080	<p>The <em class="arg">distance</em> can be in absolute intensity units or, by
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4081	appending <code>%</code> as a percentage of the maximum possible intensity (255,
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4082	65535, or 4294967295).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4083
				4084
				4085	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4086	<h4><a id="fx"></a>-fx <em class="arg">expression</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4087	</div>
				4088
				4089	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>apply a mathematical expression to an image or image channels.</td><td style='text-align:right;'></td></tr></table>
				4090
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4091	<p>If the first character of <em class="arg">expression</em> is <code>@</code>,
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4092	the expression is read from a file titled by the remaining characters in the
				4093	string.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4094
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4095	<p>See <a href="fx.html">FX,
				4096	The Special Effects Image Operator</a> for a detailed discussion of this
				4097	option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4098
				4099
				4100	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4101	<h4><a id="gamma"></a>-gamma <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4102	</div>
				4103
				4104	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>level of gamma correction.</td><td style='text-align:right;'></td></tr></table>
				4105
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4106	<p>The same color image displayed on two different workstations may look
				4107	different due to differences in the display monitor. Use gamma correction to
				4108	adjust for this color difference. Reasonable values extend from
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4109	<code>0.8</code> to <code>2.3</code>. Gamma less than 1.0 darkens the image and
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4110	gamma greater than 1.0 lightens it. Large adjustments to image gamma may
				4111	result in the loss of some image information if the pixel quantum size is only
				4112	eight bits (quantum range 0 to 255).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4113
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4114	<p>Gamma adjusts the image's channel values pixel-by-pixel according to
				4115	a power law, namely, pow(pixel,1/gamma) or pixel^(1/gamma), where pixel is the
				4116	normalized or 0 to 1 color value. For example, using a value of gamma=2 is the
				4117	same as taking the square root of the image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4118
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4119	<p>You can apply separate gamma values to the red, green, and blue channels of
				4120	the image with a gamma value list delimited with commas (e.g.,
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4121	<code>1.7,2.3,1.2</code>).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4122
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4123	<p>Use <a href="command-line-options.html#gamma">+gamma <em class="arg">value</em></a> to set the
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4124	image gamma level without actually adjusting the image pixels. This option
				4125	is useful if the image is of a known gamma but not set as an image attribute
				4126	(e.g. PNG images). Write the "file gamma" which is the reciprocal of the
				4127	display gamma; e.g., if your image is sRGB and you want to write a PNG gAMA
				4128	chunk, use
				4129	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert input.png +gamma .45455 output.png</span></p>(0.45455 is 1/2.2)</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4130
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4131	<p>Note that gamma adjustments are also available via the <a href="command-line-options.html#level">-level</a> operator.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4132
				4133	<div style="margin: auto;">
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4134	<h4><a id="gaussian-blur"></a>-gaussian-blur <em class="arg">radius</em><br />-gaussian-blur <em class="arg">radius</em>x<em class="arg">sigma</em>+<em class="arg">bias</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4135	</div>
				4136
				4137	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Blur the image with a Gaussian operator.</td><td style='text-align:right;'></td></tr></table>
				4138
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	4139	<p>Convolve the image with a Gaussian or normal distribution using the given
				4140	<em class="arg" >Sigma</em> value. The formula is:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4141
				4142	<div class="eqn"><img alt="gaussian distribution" width="243px" height="42px" src="../images/gaussian-blur.png"/>
				4143	</div>
				4144
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	4145	<p>The <em class="arg" >Sigma</em> value is the important argument, and
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	4146	determines the actual amount of blurring that will take place. </p>
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	4147
				4148	<p>The <em class="arg" >Radius</em> is only used to determine the size of the
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	4149	array which will hold the calculated Gaussian distribution. It should be an
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	4150	integer. If not given, or set to zero, IM will calculate the largest possible
cristy	b15553d	2010-07-03 22:53:14 +0000	[diff] [blame]	4151	radius that will provide meaningful results for the Gaussian distribution.
				4152	</p>
				4153
				4154	<p>The larger the <em class="arg" >Radius</em> the radius the slower the
				4155	operation is. However too small a <em class="arg" >Radius</em>, and sever
				4156	aliasing effects may result. As a guideline, <em class="arg" >Radius</em>
				4157	should be at least twice the <em class="arg" >Sigma</em> value, though three
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4158	times will produce a more accurate result. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4159
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4160	<p>This differs from the faster <a href="command-line-options.html#blur">-blur</a> operator in that a
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	4161	full 2-dimensional convolution is used to generate the weighted average of the
				4162	neighboring pixels. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4163
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4164	<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4165	pixels which are outside the image proper are blurred into the final result.
				4166	</p>
				4167
				4168
				4169	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4170	<h4><a id="geometry"></a>-geometry <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4171	</div>
				4172
				4173	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the preferred size and location of the image.</td><td style='text-align:right;'></td></tr></table>
				4174
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4175	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4176
				4177	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4178	<h4><a id="gravity"></a>-gravity <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4179	</div>
				4180
				4181	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Sets the current gravity suggestion for various other settings and options.</td><td style='text-align:right;'></td></tr></table>
				4182
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4183	<p>Choices include: <code>NorthWest</code>, <code>North</code>,
				4184	<code>NorthEast</code>, <code>West</code>, <code>Center</code>, <code>East</code>,
				4185	<code>SouthWest</code>, <code>South</code>, <code>SouthEast</code>. Use <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4186	href="command-line-options.html#list">-list gravity</a> to get a complete list of <a
				4187	href="command-line-options.html#gravity">-gravity</a> settings available in your ImageMagick
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4188	installation.</p>
				4189
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4190	<p>The direction you choose specifies where to position text or subimages. For
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4191	example, a gravity of <code>Center</code> forces the text to be centered within
				4192	the image. By default, the image gravity is <code>NorthWest</code>. See <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4193	href="command-line-options.html#draw">-draw</a> for more details about graphic primitives. Only the
				4194	text primitive of <a href="command-line-options.html#draw">-draw</a> is affected by the <a
				4195	href="command-line-options.html#gravity">-gravity</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4196
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4197	<p>The <a href="command-line-options.html#gravity">-gravity</a> option is also used in concert with the
				4198	<a href="command-line-options.html#geometry">-geometry</a> setting and other settings or options that
				4199	take <em class="arg">geometry</em> as an argument, such as the <a
				4200	href="command-line-options.html#crop">-crop</a> option. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4201
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4202	<p>If a <a href="command-line-options.html#gravity">-gravity</a> setting occurs before another option
				4203	or setting having a <em class="arg">geometry</em> argument that specifies an
				4204	offset, the offset is usually applied to the point within the image suggested
				4205	by the <a href="command-line-options.html#gravity">-gravity</a> argument. Thus, in the following
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4206	command, for example, suppose the file <code>image.png</code> has dimensions
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4207	200x100. The offset specified by the argument to <a href="command-line-options.html#region">-region</a>
				4208	is (−40,+20). The argument to <a href="command-line-options.html#gravity">-gravity</a> is
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4209	<code>Center</code>, which suggests the midpoint of the image, at the point
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4210	(100,50). The offset (−40,20) is applied to that point, giving
				4211	(100−40,50+20)=(60,70), so the specified 10x10 region is located at
				4212	that point. (In addition, the <a href="command-line-options.html#gravity">-gravity</a> affects the
				4213	region itself, which is <em>centered</em> at the pixel
				4214	coordinate (60,70). (See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.)</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4215
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4216	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert image.png -gravity Center -region 10x10-40+20 \ <br/> -negate output.png</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4217	<p>When used as an option to <a href="composite.html">composite</a>, <a
				4218	href="command-line-options.html#gravity">-gravity</a> gives the direction that the image gravitates
				4219	within the composite.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4220
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4221	<p>When used as an option to <a href="montage.html">montage</a>, <a
				4222	href="command-line-options.html#gravity">-gravity</a> gives the direction that an image gravitates
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4223	within a tile. The default gravity is <code>Center</code> for this purpose.</p>
				4224
				4225
				4226	<div style="margin: auto;">
				4227	<h4><a id="grayscale"></a>-grayscale <em class="arg">method</em></h4>
				4228	</div>
				4229
				4230	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>convert image to grayscale.</td><td style='text-align:right;'></td></tr></table>
				4231
				4232	</p>This will use one of the <a href="command-line-options.html#intensity" >-intensity</a> methods to
				4233	convert the given image into a linear-grayscale image. </p>
				4234
				4235	<p>For example, to convert an image to (linear) Rec709Luminance grayscale, type:</p>
				4236
				4237	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert in.png -grayscale Rec709Luminance out.png</span></p>
				4238	<p>which is equivalent to:</p>
				4239
				4240	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert in.png -colorspace gray out.png</span></p>
				4241	<p>Similarly, to convert an image to (non-linear) Rec709Luma grayscale, type:</p>
				4242
				4243	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert in.png -grayscale Rec709Luma out.png</span></p>
				4244	<p>which is equivalent to:</p>
				4245
				4246	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert in.png -set colorspace RGB -colorspace gray out.png</span></p>
				4247	<p>Note that a 'colorspace' intensity method will produce the same result
				4248	regardless of the current colorpsace of the image. But a 'mathematical'
				4249	intensity method will depend on the current colorspace the image is currently
				4250	using. </p>
				4251
				4252	<p>While this operation uses an <a href="command-line-options.html#intensity" >-intensity</a> method,
				4253	it does not use or set the <a href="command-line-options.html#intensity" >-intensity</a> setting, so
				4254	will not effect other operations that may use that setting.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4255
				4256
				4257	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4258	<h4><a id="green-primary"></a>-green-primary <em class="arg">x,y</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4259	</div>
				4260
				4261	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>green chromaticity primary point.</td><td style='text-align:right;'></td></tr></table>
				4262
				4263
				4264	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4265	<h4><a id="hald-clut"></a>-hald-clut</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4266	</div>
				4267
				4268	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>apply a Hald color lookup table to the image.</td><td style='text-align:right;'></td></tr></table>
				4269
				4270	<p>A Hald color lookup table is a 3-dimensional color cube mapped to 2
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4271	dimensions. Create it with the <code>HALD:</code> prefix (e.g. HALD:8). You
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4272	can apply any color transformation to the Hald image and then use this option
				4273	to apply the transform to the image. </p>
				4274
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4275	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert image.png hald.png -hald-clut transform.png</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4276	<p>This option provides a convenient method for you to use Gimp or Photoshop
				4277	to make color corrections to the Hald CLUT image and subsequently apply them
				4278	to multiple images using an ImageMagick script. </p>
				4279
				4280	<p>Note that the representation is only of the normal RGB color space and that
				4281	the whole color value triplet is used for the interpolated lookup of the
				4282	represented Hald color cube image. Because of this the operation is not <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4283	href="command-line-options.html#channel" >-channel</a> setting effected, nor can it adjust or modify an
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4284	images transparency or alpha/matte channel.</p>
				4285
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4286	<p>See also <a href="command-line-options.html#clut" >-clut</a> which provides color value replacement
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4287	of the individual color channels, usually involving a simpler gray-scale
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4288	image. E.g: gray-scale to color replacement, or modification by a histogram
				4289	mapping. </p>
				4290
				4291
				4292	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4293	<h4><a id="help"></a>-help</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4294	</div>
				4295
				4296	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>print usage instructions.</td><td style='text-align:right;'></td></tr></table>
				4297
				4298	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4299	<h4><a id="highlight-color"></a>-highlight-color <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4300	</div>
				4301
				4302	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>when comparing images, emphasize pixel differences with this color.</td><td style='text-align:right;'></td></tr></table>
				4303
				4304	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4305	<h4><a id="iconGeometry"></a>-iconGeometry <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4306	</div>
				4307
				4308	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>specify the icon geometry.</td><td style='text-align:right;'></td></tr></table>
				4309
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4310	<p>Offsets, if present in the geometry specification, are handled in the same
				4311	manner as the <a href="command-line-options.html#geometry">-geometry</a> option, using X11 style to
				4312	handle negative offsets.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4313
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4314	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4315
				4316	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4317	<h4><a id="iconic"></a>-iconic</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4318	</div>
				4319
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4320	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>start in icon mode in X Windows</td><td style='text-align:right;'>[<a href="animate.html">animate</a>, <a href="display.html">display</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4321
				4322	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4323	<h4><a id="identify"></a>-identify</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4324	</div>
				4325
				4326	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>identify the format and characteristics of the image.</td><td style='text-align:right;'></td></tr></table>
				4327
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4328	<p>This information is printed: image scene number; image name; image size;
				4329	the image class (<em class="arg">DirectClass</em> or <em
				4330	class="arg">PseudoClass</em>); the total number of unique colors; and the
				4331	number of seconds to read and transform the image. Refer to <a href="miff.html">MIFF</a> for
				4332	a description of the image class.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4333
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4334	<p>If <a href="command-line-options.html#colors">-colors</a> is also specified, the total unique colors
				4335	in the image and color reduction error values are printed. Refer to <a
				4336	href="quantize.html">color
				4337	reduction algorithm</a> for a description of these values.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4338
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4339	<p>If <a href="command-line-options.html#verbose">-verbose</a> precedes this option, copious
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4340	amounts of image properties are displayed including image statistics, profiles,
				4341	image histogram, and others.</p>
				4342
				4343	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4344	<h4><a id="ift"></a>-ift</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4345	</div>
				4346
				4347	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>implements the inverse discrete Fourier transform (DFT).</td><td style='text-align:right;'></td></tr></table>
				4348
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4349	<p>This option is new as of ImageMagick 6.5.4-3 (and now working for Windows
				4350	users in ImageMagick 6.6.0-9). It transforms a pair of magnitude and phase
				4351	images from the frequency domain to a single image in the normal or spatial
				4352	domain. See for example, <a
				4353	href="http://en.wikipedia.org/wiki/Fourier_transform">Fourier Transform</a>,
				4354	<a href="http://en.wikipedia.org/wiki/DFT">Discrete Fourier Transform</a> and
				4355	<a href="http://en.wikipedia.org/wiki/FFT">Fast Fourier Transform</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4356
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4357	<p>For example, depending upon the image format used to store the result of
				4358	the <a href="command-line-options.html#fft">-fft</a>, one would use either</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4359
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4360	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert fft_image.miff -ift fft_image_ift.png</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4361	<p>or</p>
				4362
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4363	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert fft_image-0.png fft_image-1.png -ift fft_image_ift.png</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4364
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4365	<p>The resulting image may need to be cropped due to padding introduced when
				4366	the original image, prior to the <a href="command-line-options.html#fft">-fft</a> or <a
				4367	href="command-line-options.html#fft">+fft</a>, was not square or even dimensioned. Any padding is at
				4368	the right and/or bottom sides of the image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4369
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4370	<p>The <a href="http://www.fftw.org/">FFTW</a> delegate library is required to
				4371	use <a href="command-line-options.html#ift">-ift</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4372
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4373	<p>Use <a href="command-line-options.html#ift">+ift</a> (with HDRI enabled) to transform a pair of real
				4374	and imaginary images from the frequency domain to a single image in the normal
				4375	(spatial) domain.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4376
				4377	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4378	<h4><a id="immutable"></a>-immutable</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4379	</div>
				4380
				4381	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>make image immutable.</td><td style='text-align:right;'></td></tr></table>
				4382
				4383	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4384	<h4><a id="implode"></a>-implode <em class="arg">factor</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4385	</div>
				4386
				4387	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>implode image pixels about the center.</td><td style='text-align:right;'></td></tr></table>
				4388
				4389	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4390	<h4><a id="insert"></a>-insert <em class="arg">index</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4391	</div>
				4392
				4393	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>insert the last image into the image sequence.</td><td style='text-align:right;'></td></tr></table>
				4394
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4395	<p>This option takes last image in the current image sequence and inserts it
				4396	at the given index. If a negative index is used, the insert position is
				4397	calculated before the last image is removed from the sequence. As such
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4398	<code>-insert -1</code> will result in no change to the image sequence.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4399
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4400	<p>The <code>+insert</code> option is equivalent to <code>-insert -1</code>. In
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4401	other words, insert the last image, at the end of the current image sequence.
				4402	Consequently this has no effect on the image sequence order.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4403
				4404	<div style="margin: auto;">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4405	<h4><a id="intensity"></a>-intensity <em class="arg">method</em></h4>
				4406	</div>
				4407
				4408	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>method to generate intensity value from pixel.</td><td style='text-align:right;'></td></tr></table>
				4409
				4410	<p>ImageMagick provides a number of methods used in situations where an
				4411	operatory needs to determine a single grayscale value for some purpose, from
				4412	an image with red, green, and blue pixel components. Typically the linear
				4413	<code>Rec709Luminance</code> formula is used, which is the same formula used when
				4414	converting images to <code>-colorspace gray</code>. </p>
				4415
				4416	<p>The following formulas are currently provided, and will first convert
				4417	the pixel values to linear-RGB or non-linear sRGB colorspace before
				4418	being applied to calulate the final greyscale value. </p>
				4419
				4420	<pre class="text">
				4421	Rec601Luma 0.298839R' + 0.586811G'+ 0.114350B'
				4422	Rec601Luminance 0.298839R + 0.586811G + 0.114350B
				4423	Rec709Luma 0.212656R' + 0.715158G' + 0.072186B'
				4424	Rec709Luminance 0.212656R + 0.715158G + 0.072186B
				4425	Brightness max(R', G', B')
				4426	Lightness (min(R', G', B') + max(R', G', B')) / 2.0
				4427	</pre>
				4428	<p>Note that the above R,G,B values is the image's linear-RGB values, while
				4429	R',G',B' are sRGB non-linear values. </p>
				4430
				4431	<p>These intensity methods are mathematical in nature and will use the
				4432	current value in the images respective R,G,B channel regardless of
				4433	what that is, or what colorspace the image is currently using.</p>
				4434
				4435	<pre class="text">
				4436	Average (R + G + B) / 3.0
				4437	MS (R^2 + G^2 + B^2) / 3.0
				4438	RMS sqrt( (R^2 + G^2 + B^2) / 3.0 )
				4439	</pre>
				4440
				4441	<p>These methods are often used for other purposes, such as generating a
				4442	grayscale difference image between two color images (using <a href="command-line-options.html#compose"
				4443	>-compose</a> '<code>Difference</code>' composition. </p>
				4444
				4445	<p> For example The 'MS' (Mean Squared) setting is good for minimizing color
				4446	error comparisions. While... The method 'RMS' (Root Mean Squared) for
				4447	example is appropriate for calculating color vector distance, from a color
				4448	difference image. This is equivelent to the color only component of the <a
				4449	href="command-line-options.html#fuzz" >-fuzz</a> factor color compare setting. </p>
				4450
				4451	<p>See also <a href="command-line-options.html#grayscale" >-grayscale</a> which applies one of the above
				4452	grayscaling formula directly to an image without setting the <a
				4453	href="command-line-options.html#intensity" >-intensity</a> setting.</p>
				4454
				4455	<p>The <a href="command-line-options.html#colorspace" >-colorspace gray</a> image conversion also uses
				4456	the current intensity setting, but will always convert the image to the
				4457	appropriate sRGB or linear-RGB colorspace before appling the above
				4458	function.</p>
				4459
				4460	<p>To print a complete list of posible pixel intensity setting methods, use <a href="command-line-options.html#list">-list intensity</a>.</p>
				4461
				4462	<p>Operators affected by the <a href="command-line-options.html#intensity" >-intensity</a> setting include:</p>
				4463
				4464	<pre class="text">
				4465	-adaptive-blur
				4466	-adaptive-sharpen
				4467	-black-threshold
				4468	-clut (when mapping greyscale CLUT image to alpha channel if set by -channels)
				4469	-colors for gray colorspace
				4470	-compose {LightenIntensity, DarkenIntensity, CopyOpacity, CopyBlack}
				4471	-contrast-stretch
				4472	-distort {ErodeIntensity, DilateIntensity}
				4473	-normalize
				4474	-random-threshold
				4475	-selective-blur
				4476	-shade
				4477	-threshold
				4478	-tint
				4479	-white-threshold
				4480	</pre>
				4481
				4482	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4483	<h4><a id="intent"></a>-intent <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4484	</div>
				4485
				4486	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>use this type of rendering intent when managing the image color.</td><td style='text-align:right;'></td></tr></table>
				4487
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4488	<p>Use this option to affect the color management operation of an image (see
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4489	<a href="command-line-options.html#profile">-profile</a>). Choose from these intents: <code>Absolute,
				4490	Perceptual, Relative, Saturation</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4491
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4492	<p>The default intent is Perceptual for the sRGB colorspace and undefined for the RGB and gray colorspaces.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4493
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4494	<p>To print a complete list of rendering intents, use <a href="command-line-options.html#list">-list intent</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4495
				4496	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4497	<h4><a id="interlace"></a>-interlace <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4498	</div>
				4499
				4500	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>the type of interlacing scheme.</td><td style='text-align:right;'></td></tr></table>
				4501
				4502	<p>Choose from:</p>
				4503
				4504	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	4505	none
				4506	line
				4507	plane
				4508	partition
				4509	JPEG
				4510	GIF
				4511	PNG
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4512	</pre>
				4513
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4514	<p>This option is used to specify the type of interlacing scheme for raw image
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4515	formats such as <code>RGB</code> or <code>YUV</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4516
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4517	<p><code>None</code> means do not interlace (RGBRGBRGBRGBRGBRGB...),</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4518
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4519	<p><code>Line</code> uses scanline interlacing (RRR...GGG...BBB...RRR...GGG...BBB...), and.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4520
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4521	<p><code>Plane</code> uses plane interlacing (RRRRRR...GGGGGG...BBBBBB...).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4522
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4523	<p><code>Partition</code> is like plane except the different planes are saved to
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4524	individual files (e.g. image.R, image.G, and image.B).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4525
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4526	<p>Use <code>Line</code> or <code>Plane</code> to create an <code>interlaced
				4527	PNG</code> or <code>GIF</code> or <code>progressive JPEG</code> image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4528
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4529	<p>To print a complete list of interlacing schemes, use <a href="command-line-options.html#list">-list
				4530	interlace</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4531
				4532	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4533	<h4><a id="interpolate"></a>-interpolate <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4534	</div>
				4535
				4536	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the pixel color interpolation method to use when looking up a color based on a floating point or real value.</td><td style='text-align:right;'></td></tr></table>
				4537
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	4538	<p>When looking up the color of a pixel using a non-integer floating point
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4539	value, you typically fall in between the pixel colors defined by the source
				4540	image. This setting determines how the color is determined from the colors of
				4541	the pixels surrounding that point. That is how to determine the color of a
				4542	point that falls between two, or even four different colored pixels. </p>
				4543
				4544	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	4545	integer The color of the top-left pixel (floor function)
				4546	nearest-neighbor The nearest pixel to the lookup point (rounded function)
				4547	average The average color of the surrounding four pixels
				4548	bilinear A double linear interpolation of pixels (the default)
				4549	mesh Divide area into two flat triangular interpolations
				4550	bicubic Fitted bicubic-spines of surrounding 16 pixels
				4551	spline Direct spline curves (colors are blurred)
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4552	filter Use resize <a href="command-line-options.html#filter">-filter</a> settings
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4553	</pre>
				4554
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4555	<p>This most important for distortion operators such as <a href="command-line-options.html#distort"
				4556	>-distort</a>, <a href="command-line-options.html#implode" >-implode</a>, <a href="command-line-options.html#transform"
				4557	>-transform</a> and <a href="command-line-options.html#fx" >-fx</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4558
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4559	<p>To print a complete list of interpolation methods, use <a href="command-line-options.html#list">-list interpolate</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4560
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4561	<p>See also <a href="command-line-options.html#virtual-pixel" >-virtual-pixel</a>, for control of the
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4562	lookup for positions outside the boundaries of the image. </p>
				4563
				4564
				4565	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4566	<h4><a id="interline-spacing"></a>-interline-spacing <em class="arg">value</em></h4>
cristy	f3bb478	2009-09-08 13:10:04 +0000	[diff] [blame]	4567	</div>
				4568
				4569	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>the space between two text lines.</td><td style='text-align:right;'></td></tr></table>
				4570
				4571	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4572	<h4><a id="interword-spacing"></a>-interword-spacing <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4573	</div>
				4574
				4575	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>the space between two words.</td><td style='text-align:right;'></td></tr></table>
				4576
				4577	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4578	<h4><a id="kerning"></a>-kerning <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4579	</div>
				4580
				4581	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>the space between two letters.</td><td style='text-align:right;'></td></tr></table>
				4582
				4583	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4584	<h4><a id="label"></a>-label <em class="arg">name</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4585	</div>
				4586
				4587	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>assign a label to an image.</td><td style='text-align:right;'></td></tr></table>
				4588
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	4589	<p>Use this option to assign a specific label to the image, as it is read in
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4590	or created. You can use the <a href="command-line-options.html#set" >-set</a> operation to re-assign
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	4591	a the labels of images already read in. Image formats such as TIFF, PNG,
				4592	MIFF, supports saving the label information with the image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4593
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	4594	<p>When saving an image to a <em class="arg">PostScript</em> file, any label
				4595	assigned to an image is used as a header string to print above the postscript
				4596	image. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4597
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	4598	<p>You can include the image filename, type, width, height, or other image
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4599	attribute by embedding special format character. See <a href="escape.html">Format and Print Image
cristy	bc9539a	2010-08-16 18:06:20 +0000	[diff] [blame]	4600	Properties</a> for details of the percent escape codes.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4601
				4602	<p>For example,</p>
				4603
				4604	<p class="crtsnip">
				4605	-label "%m:%f %wx%h" bird.miff
				4606	</p>
				4607
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4608	<p>assigns an image label of <code>MIFF:bird.miff 512x480</code> to the
				4609	"<code>bird.miff</code>" image and whose width is 512 and height is 480, as it
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4610	is read in. If a <a href="command-line-options.html#label">+label</a> option was used instead, any
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	4611	existing label present in the image would be used. You can remove all labels
				4612	from an image by assigning the empty string. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4613
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	4614	<p>A label is not drawn on the image, but is embedded in the image datastream
				4615	via <em>Label</em> tag or similar mechanism. If you want the label to be
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4616	visible on the image itself, use the <a href="command-line-options.html#draw">-draw</a> option, or
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4617	during the final processing in the creation of an image montage.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4618
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	4619	<p>If the first character of <em class="arg">string</em> is <em
				4620	class="arg">@</em>, the image label is read from a file titled by the
				4621	remaining characters in the string. Labels in a file are literal, no embedded
				4622	formatting characters are recognized.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4623
				4624
				4625	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4626	<h4><a id="lat"></a>-lat <em class="arg">width</em><br />-lat <em class="arg">width</em>x<em class="arg">height</em>{<em class="arg">+-</em>}<em class="arg">offset</em>{<em class="arg">%</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4627	</div>
				4628
				4629	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>perform local adaptive threshold.</td><td style='text-align:right;'></td></tr></table>
				4630
				4631	<p>Adaptively threshold each pixel based on the value of pixels in a
				4632	surrounding window. If the current pixel is lighter than this average plus
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4633	the optional <code>offset</code>, then it is made white, otherwise it is made
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4634	black. Small variations in pixel values such as found in scanned documents
				4635	can be ignored if offset is positive. A negative offset will make it more
				4636	sensitive to those small variations. </p>
				4637
				4638	<p>This is commonly used to threshold images with an uneven background. It is
				4639	based on the assumption that average color of the small window is the
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4640	the local background color, from which to separate the foreground color. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4641
				4642
				4643	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4644	<h4><a id="layers"></a>-layers <em class="arg">method</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4645	</div>
				4646
				4647	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>handle multiple images forming a set of image layers or animation frames.</td><td style='text-align:right;'></td></tr></table>
				4648
				4649	<p>Perform various image operation methods to a ordered sequence of images
				4650	which may represent either a set of overlaid 'image layers', a GIF disposal
				4651	animation, or a fully-'coalesced' animation sequence. </p>
				4652
				4653	<table class="doc">
				4654	<tbody>
				4655	<tr valign="top">
				4656	<th align="left" style="width: 8%">Method</th>
				4657	<th align="left">Description</th>
				4658	</tr>
				4659
				4660	<tr valign="top">
				4661	<td valign="top">compare-any</td>
				4662	<td valign="top">Crop the second and later frames to the smallest rectangle
				4663	that contains all the differences between the two images. No GIF <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4664	href="command-line-options.html#dispose" >-dispose</a> methods are taken into account. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4665	</tr>
				4666
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4667	<tr><td></td><td>This exactly the same as the <a href="command-line-options.html#deconstruct"
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4668	>-deconstruct</a> operator, and does not preserve animations normal
				4669	working, especially when animation used layer disposal methods such as
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4670	'<code>Previous</code>' or '<code>Background</code>'. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4671	</tr>
				4672
				4673	<tr valign="top">
				4674	<td valign="top">compare-clear</td>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4675	<td valign="top">As '<code>compare-any</code>' but crop to the bounds of any
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4676	opaque pixels which become transparent in the second frame. That is the
				4677	smallest image needed to mask or erase pixels for the next frame. </td>
				4678	</tr>
				4679
				4680	<tr valign="top">
				4681	<td valign="top">compare-overlay</td>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4682	<td valign="top">As '<code>compare-any</code>' but crop to pixels that add
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4683	extra color to the next image, as a result of overlaying color pixels.
				4684	That is the smallest single overlaid image to add or change colors. </td>
				4685	</tr>
				4686
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4687	<tr><td></td><td>This can be used with the <a href="command-line-options.html#compose" >-compose</a> alpha
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4688	composition method '<code>change-mask</code>', to reduce the image to
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4689	just the pixels that need to be overlaid. </td>
				4690	</tr>
				4691
				4692	<tr valign="top">
				4693	<td valign="top">coalesce</td>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4694	<td valign="top">Equivalent to a call to the <a href="command-line-options.html#coalesce"
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4695	>-coalesce</a> operator. Apply the layer disposal methods set in the
				4696	current image sequence to form a fully defined animation sequence, as
				4697	it should be displayed. Effectively converting a GIF animation into a
				4698	'film strip'-like animation. </td>
				4699	</tr>
				4700
				4701	<tr valign="top">
				4702	<td valign="top">composite</td>
				4703	<td valign="top">Alpha Composition of two image lists, separated by a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4704	"<code>null:</code>" image, with the destination image list first, and
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4705	the source images last. An image from each list are composited
				4706	together until one list is finished. The separator image and source
				4707	image lists are removed. </td>
				4708	</tr>
				4709
				4710
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	4711	<tr><td></td>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4712	<td>The <a href="command-line-options.html#geometry" >-geometry</a> offset is adjusted according
				4713	to <a href="command-line-options.html#gravity" >-gravity</a> in accordance of the virtual
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	4714	canvas size of the first image in each list. Unlike a normal <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4715	href="command-line-options.html#composite" >-composite</a> operation, the canvas offset is also
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	4716	added to the final composite positioning of each image. </td> </tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4717
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	4718	<tr><td></td>
				4719	<td>If one of the image lists only contains one image, that image is
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4720	applied to all the images in the other image list, regardless of which
				4721	list it is. In this case it is the image meta-data of the list which
				4722	preserved. </td>
				4723	</tr>
				4724
				4725
				4726	<tr valign="top">
				4727	<td valign="top">dispose</td>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4728	<td valign="top">This like '<code>coalesce</code>' but shows the look of
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4729	the animation after the layer disposal method has been applied, before
				4730	the next sub-frame image is overlaid. That is the 'dispose' image that
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4731	results from the application of the GIF <a href="command-line-options.html#dispose"
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4732	>-dispose</a> method. This allows you to check what
				4733	is going wrong with a particular animation you may be developing.
				4734	</td>
				4735	</tr>
				4736
				4737	<tr valign="top">
				4738	<td valign="top">flatten</td>
				4739	<td valign="top">Create a canvas the size of the first images virtual
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4740	canvas using the current <a href="command-line-options.html#background" >-background</a> color,
				4741	and <a href="command-line-options.html#compose" >-compose</a> each image in turn onto that
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4742	canvas. Images falling outside that canvas is clipped. Final
				4743	image will have a zero virtual canvas offset. </td>
				4744	</tr>
				4745
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	4746	<tr><td></td>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4747	<td>This usually used as one of the final 'image layering' operations
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4748	overlaying all the prepared image layers into a final image. </td>
				4749	</tr>
				4750
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	4751	<tr><td></td>
				4752	<td>For a single image this method can also be used to fillout a virtual
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4753	canvas with real pixels, or to underlay an opaque color to remove
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4754	transparency from an image.</td>
				4755	</tr>
				4756
				4757
				4758	<tr valign="top">
				4759	<td valign="top">merge</td>
				4760	<td valign="top">As 'flatten' method but merging all the given image
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4761	layers to create a new layer image just large enough to hold all the
				4762	image without clipping or extra space. The new images virtual offset
				4763	will preserve the position of the new layer, even if this offset is
				4764	negative. The virtual canvas size of the first image is preserved.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4765	</td>
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4766	</tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4767
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4768	<tr><td></td><td>Caution is advised when handling image layers with
				4769	negative offsets as few image file formats handle them correctly.
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4770	Following this operation method with <a href="command-line-options.html#repage" >+repage</a>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4771	will remove the layer offset, and create an image in which all the
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4772	overlaid image positions relative to each other is preserved, though
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4773	not necessarily exactly where you specified them.
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4774	</td>
				4775	</tr>
				4776
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4777	<tr><td></td><td>See also 'trim-bounds' below which is closely related but
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4778	without doing the'flatten' to merge the images together. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4779	</tr>
				4780
				4781	<tr valign="top">
				4782	<td valign="top">mosaic</td>
				4783	<td valign="top">As 'flatten' method but expanding the initial canvas size
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4784	of the first image in a positive direction only so as to hold all the
				4785	image layers. However as a virtual canvas is 'locked' to the origin,
				4786	by its own definition, image layers with a negative offsets will still
				4787	become clipped by the top and left edges. See 'merge' or 'trim-bounds'
				4788	if this could be a problem. </td>
				4789
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4790	</tr>
				4791
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4792	<tr><td></td><td>This method is commonly used to layout individual image
				4793	using various offset but without knowing the final canvas size. The
				4794	resulting image will, like 'flatten' not have any virtual offset, so
				4795	can be saved to any image file format. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4796	</tr>
				4797
				4798
				4799	<tr valign="top">
				4800	<td valign="top">optimize</td>
				4801	<td valign="top">Optimize a coalesced animation, into GIF animation using
				4802	a number of general techniques. This currently a short cut to
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4803	apply both the '<code>optimize-frame</code>', and
				4804	'<code>optimize-transparency</code>' methods but may be expanded to
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4805	include other optimization methods as they are developed. </td>
				4806	</tr>
				4807
				4808	<tr valign="top">
				4809	<td valign="top">optimize-frame</td>
				4810	<td valign="top">Optimize a coalesced animation, into GIF animation by
				4811	reducing the number of pixels per frame as much as possible by
				4812	attempting to pick the best layer disposal method to use, while ensuring
				4813	the result will continue to animate properly. </td>
				4814	</tr>
				4815
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4816	<tr><td></td><td> There is no guarantee that the best optimization is found.
				4817	But then no reasonably fast GIF optimization algorithm can do this.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4818	However this does seem to do better than most other GIF frame
				4819	optimizers seen. </td>
				4820	</tr>
				4821
				4822	<tr valign="top">
				4823	<td valign="top">optimize-plus</td>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4824	<td valign="top">As '<code>optimize-frame</code>' but attempt to improve the
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4825	overall optimization by adding extra frames to the animation, without
				4826	changing the final look or timing of the animation. The frames are
				4827	added to attempt to separate the clearing of pixels from the
				4828	overlaying of new additional pixels from one animation frame to the
				4829	next. If this does not improve the optimization (for the next frame
				4830	only), it will fall back to the results of the previous normal
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4831	'<code>optimize-frame</code>' technique. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4832	</tr>
				4833
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4834	<tr><td></td><td>There is the possibility that the change in the disposal
				4835	style will result in a worsening in the optimization of later frames,
				4836	though this is unlikely. In other words there no guarantee that it is
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4837	better than the normal '<code>optimize-frame</code>' technique. For some
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4838	animations however you can get a vast improvement in the final
				4839	animation size. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4840	</tr>
				4841
				4842	<tr valign="top">
				4843	<td valign="top">optimize-transparency</td>
				4844	<td valign="top">Given a GIF animation, replace any pixel in the sub-frame
				4845	overlay images with transparency, if it does not change the resulting
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4846	animation by more than the current <a href="command-line-options.html#fuzz" >-fuzz</a> factor.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4847	</td>
				4848	</tr>
				4849
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4850	<tr><td></td><td>This should allow a existing frame optimized GIF animation
				4851	to compress into a smaller file size due to larger areas of one
				4852	(transparent) color rather than a pattern of multiple colors repeating
				4853	the current disposed image of the last frame. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4854	</tr>
				4855
				4856	<tr valign="top">
				4857	<td valign="top">remove-dups</td>
				4858	<td valign="top">Remove (and merge time delays) of duplicate consecutive
				4859	images, so as to simplify layer overlays of coalesced animations.
				4860	</td>
				4861	</tr>
				4862
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4863	<tr><td></td><td>Usually this a result of using a constant time delay
				4864	across the whole animation, or after a larger animation was split into
				4865	smaller sub-animations. The duplicate frames could also have been
				4866	used as part of some frame optimization methods. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4867	</tr>
				4868
				4869	<tr valign="top">
				4870	<td valign="top">remove-zero</td>
				4871	<td valign="top">Remove any image with a zero time delay, unless ALL the
				4872	images have a zero time delay (and is not a proper timed animation, a
				4873	warning is then issued). </td>
				4874	</tr>
				4875
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4876	<tr><td></td><td>In a GIF animation, such images are usually frames which
				4877	provide partial intermediary updates between the frames that are
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	4878	actually displayed to users. These frames are usually added for
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4879	improved frame optimization in GIF animations. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4880	</tr>
				4881
				4882	<tr valign="top">
				4883	<td valign="top">trim-bounds</td>
				4884	<td valign="top">Find the bounds of all the images in the current
				4885	image sequence, then adjust the offsets so all images are contained on
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4886	a minimal positive canvas. None of the image data is modified or
				4887	merged, only the individual image virtual canvas size and offset.
				4888	All the images is given the same canvas size, and and will have
				4889	a positive offset, but will remain in the same position relative to
				4890	each other. As a result of the minimal canvas size at least one image
				4891	will touch every edge of that canvas. The image data touching those
				4892	edges however may be transparent. </td>
				4893	</tr>
				4894
				4895	<tr><td></td><td>The result is much like if you used 'merge' followed by a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4896	<a href="command-line-options.html#repage" >+repage</a> option, except that all the images
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4897	have been kept separate. If 'flatten' is used after using
				4898	'trim-bounds' you will get the same result. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4899	</tr>
				4900
				4901	</tbody>
				4902	</table>
				4903
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4904	<p>To print a complete list of layer types, use <a href="command-line-options.html#list">-list layers</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4905
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4906	<p>The operators <a href="command-line-options.html#coalesce" >-coalesce</a>, <a href="command-line-options.html#deconstruct"
				4907	>-deconstruct</a>, <a href="command-line-options.html#flatten" >-flatten</a>, and <a href="command-line-options.html#mosaic"
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4908	>-mosaic</a> are only aliases for the above methods and may be depreciated in
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4909	the future. Also see <a href="command-line-options.html#page" >-page</a>, <a href="command-line-options.html#repage"
				4910	>-repage</a> operators, the <a href="command-line-options.html#compose" >-compose</a> setting, and the
				4911	GIF <a href="command-line-options.html#dispose" >-dispose</a> and <a href="command-line-options.html#delay" >-delay</a>
cristy	10549a1	2011-05-15 19:04:46 +0000	[diff] [blame]	4912	settings. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4913
				4914
				4915	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4916	<h4><a id="level"></a>-level <em class="arg">black_point</em>{,<em class="arg">white_point</em>}{<em class="arg">%</em>}{,<em class="arg">gamma</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4917	</div>
				4918
				4919	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>adjust the level of image channels.</td><td style='text-align:right;'></td></tr></table>
				4920
				4921	<p>Given one, two or three values delimited with commas: black-point,
				4922	white-point, gamma (for example: 10,250,1.0 or 2%,98%,0.5). The black and
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4923	white points range from 0 to <em class="QR">QuantumRange</em>, or from 0 to
				4924	100%; if the white point is omitted it is set to (<em
				4925	class="QR">QuantumRange</em> - black_point), so as to center contrast changes.
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4926	If a <code>%</code> sign is present anywhere in the string, both black and white
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4927	points are percentages of the full color range. Gamma will do a <a
				4928	href="command-line-options.html#gamma">-gamma</a> adjustment of the values. If it is omitted, the
				4929	default of 1.0 (no gamma correction) is assumed.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4930
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4931	<p>In normal usage (<code>-level</code>) the image values are stretched so that
				4932	the given '<code>black_point</code>' value in the original image is set to zero
				4933	(or black), while the given '<code>white_point</code>' value is set to <em
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4934	class="QR">QuantumRange</em> (or white). This provides you with direct
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4935	contrast adjustments to the image. The '<code>gamma</code>' of the resulting
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4936	image will then be adjusted. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4937
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4938	<p>From ImageMagick v6.4.1-9 using the plus form of the operator
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4939	(<code>+level</code>) or adding the special '!' flag anywhere in the argument
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4940	list, will cause the operator to do the reverse of the level adjustment. That
				4941	is a zero, or <em class="QR">QuantumRange</em> value (black, and white, resp.)
				4942	in the original image, is adjusted to the given level values, allowing you to
				4943	de-contrast, or compress the channel values within the image. The
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4944	'<code>gamma</code>' is adjusted before the level adjustment to de-contrast the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4945	image is made. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4946
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4947	<p>Only the channels defined by the current <a href="command-line-options.html#channel">-channel</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4948	setting are adjusted (defaults to RGB color channels only), allowing you to
				4949	limit the effect of this operator. </p>
				4950
				4951	<p>Please note that the transparency channel is treated as 'matte'
				4952	values (0 is opaque) and not as 'alpha' values (0 is transparent).</p>
				4953
				4954
				4955	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4956	<h4><a id="level-colors"></a>-level-colors {<em
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4957	class="arg">black_color</em>}{,}{<em class="arg">white_color</em>}</h4>
				4958	</div>
				4959
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	4960	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>adjust the level of an image using the provided dash separated colors.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4961
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4962	<p>This function is exactly like <a href="command-line-options.html#level">-level</a>, except that the
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4963	value value for each color channel is determined by the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4964	'<code>black_color</code>' and '<code>white_color</code>' colors given (as
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4965	described under the <a href="command-line-options.html#fill">-fill</a> option). </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4966
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4967	<p>This effectually means the colors provided to <code>-level-colors</code>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	4968	is mapped to become 'black' and 'white' respectively, with all the other
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4969	colors linearly adjusted (or clipped) to match that change. Each channel is
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	4970	adjusted separately using the channel values of the colors specified. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4971
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4972	<p>On the other hand the plus form of the operator (<code>+level-colors</code>)
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4973	will map the image color 'black' and 'white' to the given colors
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	4974	respectively, resulting in a gradient (de-contrasting) tint of the image to
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4975	those colors. This can also be used to convert a plain gray-scale image into a
				4976	one using the gradient of colors specified. </p>
				4977
				4978	<p>By supplying a single color with a comma separator either before or after
				4979	that color, will just replace the respective 'black' or 'white' point
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	4980	respectively. But if no comma separator is provided, the given color is
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4981	used for both the black and white color points, making the operator either
				4982	threshold the images around that color (- form) or set all colors to that
				4983	color (+ form). </p>
				4984
				4985
				4986	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	4987	<h4><a id="limit"></a>-limit <em class="arg">type value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4988	</div>
				4989
				4990	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the pixel cache resource limit.</td><td style='text-align:right;'></td></tr></table>
				4991
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4992	<p>Choose from: <code>area</code>, <code>disk</code>, <code>file</code>,
				4993	<code>map</code>, <code>memory</code>, <code>threads</code>, or <code>time</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	4994
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4995	<p>The value for <code>file</code> is in number of files. The other limits are
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	4996	in bytes. Define arguments for the memory, map, area, and disk resource limits
				4997	with SI prefixes (.e.g 100MB).<p>
				4998
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	4999	<p>By default the limits are 768 files, 3GB of image area, 1.5GiB memory, 3GiB
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5000	memory map, and 18.45EB of disk. These limits are adjusted relative to the
				5001	available resources on your computer if this information is available. When
				5002	any limit is reached, ImageMagick fails in some fashion but attempts to take
				5003	compensating actions, if possible. For example, the following limits
				5004	memory:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5005
				5006	<p class="crtsnip">
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5007	-limit memory 32MiB -limit map 64MiB
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5008	</p>
				5009
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5010	<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>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5011
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	5012	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>identify -list resource</span><span class='crtout'></span></p><pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5013	File Area Memory Map Disk Thread Time
				5014	------------------------------------------------------------------------------
				5015	768 12.404GB 8.6642GiB 23.104GiB 18.446744EB 8 unlimited
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5016	</pre>
				5017
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5018	<p>Requests for pixel storage to keep intermediate images are satisfied by one
				5019	of three resource categories: in-memory pool, memory-mapped files pool, and
				5020	disk pool (in that order) depending on the <a href="command-line-options.html#limit">‑limit</a> settings
				5021	and whether the system honors a resource request. If the total size of
				5022	allocated pixel storage in the given pool reaches the corresponding limit, the
				5023	request is passed to the next pool. Additionally, requests that exceed the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5024	<code>area</code> limit automagically are allocated on disk.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5025
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5026	<p>To illustrate how ImageMagick utilizes resource limits, consider a typical
				5027	image resource request. First, ImageMagick tries to allocate the pixels in
				5028	memory. The request might be denied if the resource request exceeds the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5029	<code>memory</code> limit or if the system does not honor the request. If
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5030	a memory request is not honored, the pixels are allocated to disk and the file
				5031	is memory-mapped. However, if the allocation request exceeds the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5032	<code>map</code> limit, the resource allocation goes to disk. In all cases, if
				5033	the resource request exceeds the <code>area</code> limit, the pixels are
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5034	automagically cached to disk. If the disk has a hard limit, the program
				5035	fails.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5036
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5037	<p>In most cases you simply do not need to concern yourself with resource
				5038	limits. ImageMagick chooses reasonable defaults and most images do not tax
				5039	your computer resources. Where limits do come in handy is when you process
				5040	images that are large or on shared systems where ImageMagick can consume all
				5041	or most of the available memory. In this case, the ImageMagick workflow slows
				5042	other processes or, in extreme cases, brings the system to a halt. Under
				5043	these circumstances, setting limits give some assurances that the ImageMagick
				5044	workflow will not interfere with other concurrent uses of the computer. For
				5045	example, assume you have a web interface that processes images uploaded from
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5046	the Internet. To assure ImageMagick does not exceed 10MiB of memory you can
				5047	simply set the area limit to 10MiB:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5048
				5049	<p class="crtsnip">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5050	-limit area 10MB
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5051	</p>
				5052
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5053	<p>Now whenever a large image is processed, the pixels are automagically
				5054	cached to disk instead of memory. This of course implies that large images
				5055	typically process very slowly, simply because pixel processing in memory can
				5056	be an order of magnitude faster than on disk. Because your web site users
				5057	might inadvertently upload a huge image to process, you should set a disk
				5058	limit as well:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5059
				5060	<p class="crtsnip">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5061	-limit area 10MB -limit disk 500MB
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5062	</p>
				5063
				5064	<p>Here ImageMagick stops processing if an image requires more than 500MB of disk storage.</p>
				5065
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5066	<p>In addition to command-line resource limit option, resources can be set
				5067	with <a href="resources.html#environment" >environment variables</a>. Set the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5068	environment variables <code>MAGICK_AREA_LIMIT</code>,
				5069	<code>MAGICK_DISK_LIMIT</code>, <code>MAGICK_FILE_LIMIT</code>,
				5070	<code>MAGICK_MEMORY_LIMIT</code>, <code>MAGICK_MAP_LIMIT</code>,
				5071	<code>MAGICK_THREAD_LIMIT</code>, <code>MAGICK_TIME_LIMIT</code> for limits of
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5072	image area, disk space, open files, heap memory, memory map, number of threads
				5073	of execution, and maximum elapsed time in seconds respectively.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5074
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5075	<p> Inquisitive users can try adding <a href="command-line-options.html#debug">-debug cache</a> to
				5076	their commands and then scouring the generated output for references to the
				5077	pixel cache, in order to determine how the pixel cache was allocated and how
				5078	resources were consumed. Advanced Unix/Linux users can pipe that output
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5079	through <code>grep memory\|open\|destroy\|disk</code> for more readable sifting.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5080	</p>
				5081
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5082	<p>For more about ImageMagick's use of resources, see the section <b>Cache
				5083	Storage and Resource Requirements</b> on the <a href="architecture.html#cache
				5084	">Architecture</a> page. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5085
				5086	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5087	<h4><a id="linear-stretch"></a>-linear-stretch <em class="arg">black-point</em><br />-linear-stretch <em class="arg">black-point</em>{x<em class="arg">white-point</em>}{<em class="arg">%</em>}}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5088	</div>
				5089
				5090	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Linear with saturation stretch.</td><td style='text-align:right;'></td></tr></table>
				5091
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5092	<p>This is very similar to <a href="command-line-options.html#contrast-stretch" >-contrast-stretch</a>,
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5093	and uses a 'histogram bin' to determine the range of color values that needs to
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	5094	be stretched. However it then stretches those colors using the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5095	href="command-line-options.html#level" >-level</a> operator.</p>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5096
				5097	<p>As such while the initial determination may have 'binning' round off
				5098	effects, the image colors are stretched mathematically, rather than using the
				5099	histogram bins. This makes the operator more accurate. </p>
				5100
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5101	<p>note however that a <a href="command-line-options.html#linear-stretch" >-linear-stretch</a> of
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5102	'<code>0</code>' does nothing, while a value of '<code>1</code>' does a near
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5103	perfect stretch of the color range. </p>
				5104
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5105	<p>See also <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect'
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5106	normalization of mathematical images. </p>
				5107
				5108	<p>This operator is under review for re-development. </p>
				5109
				5110
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5111	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5112	<h4><a id="linewidth"></a>-linewidth</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5113	</div>
				5114
				5115	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>the line width for subsequent draw operations.</td><td style='text-align:right;'></td></tr></table>
				5116
				5117	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5118	<h4><a id="liquid-rescale"></a>-liquid-rescale <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5119	</div>
				5120
				5121	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>rescale image with seam-carving.</td><td style='text-align:right;'></td></tr></table>
				5122
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5123	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5124
				5125	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5126	<h4><a id="list"></a>-list <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5127	</div>
				5128
				5129	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Print a list of supported arguments for various options or settings. Choose from these list types:</td><td style='text-align:right;'></td></tr></table>
				5130
				5131	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5132	Align Alpha Boolean Channel
				5133	Class ClipPath Coder Color
				5134	Colorspace Command Compose Compress
				5135	Configure DataType Debug Decoration
				5136	Delegate Direction Dispose Distort
				5137	Dither Endian Evaluate FillRule
				5138	Filter Font Format Function
				5139	Gravity ImageList Intent Interlace
				5140	Interpolate Kernel Layers LineCap
				5141	LineJoin List Locale LogEvent
				5142	Log Magic Method Metric
				5143	Mime Mode Morphology Module
				5144	Noise Orientation Policy PolicyDomain
				5145	PolicyRights Preview Primitive QuantumFormat
				5146	Resource SparseColor Storage Stretch
				5147	Style Threshold Type Units
				5148	Validate VirtualPixel
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5149	</pre>
				5150
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5151	<p>These lists vary depending on your version of ImageMagick. Use "<code>-list
				5152	list</code>" to get a complete listing of all the "<code>-list</code>" arguments
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5153	available:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5154
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	5155	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>identify -list list</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5156	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5157	<h4><a id="log"></a>-log <em class="arg">string</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5158	</div>
				5159
				5160	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specify format for debug log.</td><td style='text-align:right;'></td></tr></table>
				5161
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5162	<p>This option specifies the format for the log printed when the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5163	href="command-line-options.html#debug">-debug</a> option is active.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5164
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5165	<p>You can display the following components by embedding special format
				5166	characters:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5167
				5168	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5169	%d domain
				5170	%e event
				5171	%f function
				5172	%l line
				5173	%m module
				5174	%p process ID
				5175	%r real CPU time
				5176	%t wall clock time
				5177	%u user CPU time
				5178	%% percent sign
				5179	\n newline
				5180	\r carriage return
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5181	</pre>
				5182
				5183	<p>For example:</p>
				5184
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	5185	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert -debug coders -log "%u %m:%l %e" in.gif out.png</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5186	<p>The default behavior is to print all of the components.</p>
				5187
				5188	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5189	<h4><a id="loop"></a>-loop <em class="arg">iterations</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5190	</div>
				5191
				5192	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>add Netscape loop extension to your GIF animation.</td><td style='text-align:right;'></td></tr></table>
				5193
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5194	<p>Set iterations to zero to repeat the animation an infinite number of times,
				5195	otherwise the animation repeats itself up to <em class="arg">iterations</em>
				5196	times.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5197
				5198	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5199	<h4><a id="lowlight-color"></a>-lowlight-color <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5200	</div>
				5201
				5202	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>when comparing images, de-emphasize pixel differences with this color.</td><td style='text-align:right;'></td></tr></table>
				5203
				5204	<div style="margin: auto;">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5205	<h4><a id="magnify"></a>-magnify</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5206	</div>
				5207
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5208	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>double the size of the image with pixel art scaling.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5209
				5210
				5211	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5212	<h4><a id="map"></a>-map <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5213	</div>
				5214
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5215	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Display image using this <em class="arg">type</em>.</td><td style='text-align:right;'>[<a href="animate.html">animate</a>, <a href="display.html">display</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5216
				5217	<p>Choose from these <em class="arg">Standard Colormap</em> types:</p>
				5218
				5219	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5220	best
				5221	default
				5222	gray
				5223	red
				5224	green
				5225	blue
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5226	</pre>
				5227
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5228	<p>The <em class="arg">X server</em> must support the <em class="arg">Standard
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5229	Colormap</em> you choose, otherwise an error occurs. Use <code>list</code> as
				5230	the type and <code>display</code> searches the list of colormap types in
				5231	<code>top-to-bottom</code> order until one is located. See <em
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5232	class="arg">xstdcmap(1)</em> for one way of creating Standard Colormaps.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5233
				5234
				5235	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5236	<h4><a id="map_stream_"></a>-map <em class="arg">components</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5237	</div>
				5238
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5239	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>pixel map.</td><td style='text-align:right;'>[<a href="stream.html">stream</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5240
				5241	<p>Here are the valid components of a map:</p>
				5242
				5243	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5244	r red pixel component
				5245	g green pixel component
				5246	b blue pixel component
				5247	a alpha pixel component (0 is transparent)
				5248	o opacity pixel component (0 is opaque)
				5249	i grayscale intensity pixel component
				5250	c cyan pixel component
				5251	m magenta pixel component
				5252	y yellow pixel component
				5253	k black pixel component
				5254	p pad component (always 0)
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5255	</pre>
				5256
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5257	<p>You can specify as many of these components as needed in any order (e.g.
				5258	bgr). The components can repeat as well (e.g. rgbr).</p>
				5259
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5260
				5261	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5262	<h4><a id="mask"></a>-mask
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5263	<em class="arg">filename</em></h4>
				5264	</div>
				5265
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	5266	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Prevent updates to image pixels specified by the mask.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5267
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	5268	<p>This the same as using a mask used for composite masking operations, with
				5269	grayscale values causing blended updates of the image the mask is attached to.
				5270	</P>
				5271
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5272	<p>Use <a href="command-line-options.html#mask">+mask</a> to remove the mask from images.</p>
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	5273
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5274	<p>Also see <a href="command-line-options.html#clip-mask">-clip-mask</a> which work in the same way,
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	5275	but with strict boolean masking. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5276
				5277	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5278	<h4><a id="mattecolor"></a>-mattecolor <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5279	</div>
				5280
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5281	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specify the color to be used with the <a href="command-line-options.html#frame">-frame</a> option.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5282
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5283	<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5284
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5285	<p>The default matte color is <code>#BDBDBD</code>, <span
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5286	style="background-color: #bdbdbd;">this shade of gray</span>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5287
				5288	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5289	<h4><a id="maximum"></a>-maximum</h4>
cristy	d2baf7d	2010-03-06 04:26:44 +0000	[diff] [blame]	5290	</div>
				5291
				5292	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>return the maximum intensity of an image sequence.</td><td style='text-align:right;'></td></tr></table>
				5293
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	5294	<p>Select the 'maximum' value from all the surrounding pixels. </p>
				5295
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5296	<p>This is legacy option from the <a href="command-line-options.html#statistic" >method</A> of the same
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	5297	name. </p>
				5298
cristy	d2baf7d	2010-03-06 04:26:44 +0000	[diff] [blame]	5299	<div style="margin: auto;">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5300	<h4><a id="median"></a>-median <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5301	</div>
				5302
				5303	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>apply a median filter to the image.</td><td style='text-align:right;'></td></tr></table>
				5304
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	5305	<p>Select the 'middle' value from all the surrounding pixels. </p>
				5306
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5307	<p>This is legacy option from the <a href="command-line-options.html#statistic" >method</A> of the same
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	5308	name. </p>
				5309
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5310	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5311	<h4><a id="metric"></a>-metric <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5312	</div>
				5313
				5314	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Output to STDERR a measure of the differences between images according to the <em class="arg">type</em> given metric.</td><td style='text-align:right;'></td></tr></table>
				5315
				5316	<p>Choose from:</p>
				5317
				5318	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5319	AE absolute error count, number of different pixels (-fuzz effected)
				5320	FUZZ mean color distance
				5321	MAE mean absolute error (normalized), average channel error distance
				5322	MEPP mean error per pixel (normalized mean error, normalized peak error)
				5323	MSE mean error squared, average of the channel error squared
				5324	NCC normalized cross correlation
				5325	PAE peak absolute (normalize peak absolute)
				5326	PSNR peak signal to noise ratio
				5327	RMSE root mean squared (normalized root mean squared)
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5328	</pre>
				5329
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5330	<p>Control the '<code>AE</code>', or absolute count of pixels that are different,
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5331	with the <a href="command-line-options.html#fuzz" >-fuzz</a> factor (ignore pixels which
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5332	only changed by a small amount). Use '<code>PAE</code>' to find the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5333	size of the <a href="command-line-options.html#fuzz" >-fuzz</a> factor needed to make all pixels
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5334	'similar', while '<code>MAE</code>' determines the factor needed
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5335	for about half the pixels to be similar. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5336
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5337	<p>The '<code>MEPP</code>' metric returns three different metrics
				5338	('<code>MAE</code>', '<code>MAE</code>' normalized, and '<code>PAE</code>'
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	5339	normalized) from a single comparison run. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5340
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5341	<p>To print a complete list of metrics, use the <a href="command-line-options.html#list">-list
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5342	metrics</a> option.</p>
				5343
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5344
cristy	d2baf7d	2010-03-06 04:26:44 +0000	[diff] [blame]	5345	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5346	<h4><a id="minimum"></a>-minimum</h4>
cristy	d2baf7d	2010-03-06 04:26:44 +0000	[diff] [blame]	5347	</div>
				5348
				5349	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>return the minimum intensity of an image sequence.</td><td style='text-align:right;'></td></tr></table>
				5350
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	5351	<p>Select the 'minimal' value from all the surrounding pixels. </p>
				5352
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5353	<p>This is legacy option from the <a href="command-line-options.html#statistic" >method</A> of the same
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	5354	name. </p>
				5355
				5356
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5357
				5358	<div style="margin: auto;">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5359	<h4><a id="mode"></a>-mode <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5360	</div>
				5361
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5362	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>make each pixel the 'predominant color' of the neighborhood.</td><td style='text-align:right;'>[<a href="convert.html">convert</a>, <a href="mogrify.html">mogrify</a>]</td></tr></table>
cristy	be3c5be	2011-03-05 17:35:07 +0000	[diff] [blame]	5363
				5364	<div style="margin: auto;">
				5365	<h4>-mode <em class="arg">value</em></h4>
				5366	</div>
				5367
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5368	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Mode of operation.</td><td style='text-align:right;'>[<a href="montage.html">montage</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5369
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5370	<p>Choose the <em class="arg">value</em> from these styles: <code>Frame,
				5371	Unframe, or Concatenate</code></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5372
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5373	<p>Use the <a href="command-line-options.html#list" >-list</a> option with a '<code>Mode</code>' argument
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5374	for a list of <a href="command-line-options.html#mode" >-mode</a> arguments available in your
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5375	ImageMagick installation.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5376
				5377
				5378	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5379	<h4><a id="modulate"></a>-modulate <em class="arg">brightness</em>[,<em class="arg">saturation</em>,<em class="arg">hue</em>]</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5380	</div>
				5381
cristy	bac7a16	2010-06-15 19:57:29 +0000	[diff] [blame]	5382	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Vary the <em class="arg">brightness</em>, <em
				5383	class="arg">saturation</em>, and <em class="arg">hue</em> of an image.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5384
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	5385	<p>The arguments are given as a percentages of variation. A value of 100 means
				5386	no change, and any missing values are taken to mean 100.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5387
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	5388	<p>The <em class="arg">brightness</em> is a multiplier of the overall
				5389	brightness of the image, so 0 means pure black, 50 is half as bright, 200 is
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5390	twice as bright. To invert its meaning <a href="command-line-options.html#negate">-negate</a> the image
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	5391	before and after. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5392
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	5393	<p>The <em class="arg">saturation</em> controls the amount of color in an
				5394	image. For example, 0 produce a grayscale image, while a large value such as
				5395	200 produce a very colorful, 'cartoonish' color.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5396
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	5397	<p>The <em class="arg">hue</em> argument causes a "rotation" of the colors
				5398	within the image by the amount specified. For example, 50 results in
				5399	a counter-clockwise rotation of 90, mapping red shades to purple, and so on.
				5400	A value of either 0 or 200 results in a complete 180 degree rotation of the
				5401	image. Using a value of 300 is a 360 degree rotation resulting in no change to
				5402	the original image. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5403
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	5404	<p>For example, to increase the color brightness by 20% and decrease the color
				5405	saturation by 10% and leave the hue unchanged, use <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5406	href="command-line-options.html#modulate">-modulate 120,90</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5407
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5408	<p>Use <a href="command-line-options.html#set">-set</a> attribute of '<code
				5409	class="arg">option:modulate:colorspace</code>' to specify which colorspace to
				5410	modulate. Choose from <code>HCL</code>, <code>HCLp</code>, <code>HSB</code>, <code>HSI</code>, <code>HSL</code> (the default), <code>HSV</code>, <code>HWB</code>, or <code>LCH</code> (LCHuv). For example,</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5411
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	5412	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert image.png -set option:modulate:colorspace hsb -modulate 120,90 modulate.png</span></p>
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	5413
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5414	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5415	<h4><a id="monitor"></a>-monitor</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5416	</div>
				5417
				5418	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>monitor progress.</td><td style='text-align:right;'></td></tr></table>
				5419
				5420
				5421	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5422	<h4><a id="monochrome"></a>-monochrome</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5423	</div>
				5424
				5425	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>transform the image to black and white.</td><td style='text-align:right;'></td></tr></table>
				5426
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5427	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5428	<h4><a id="morph"></a>-morph <em class="arg">frames</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5429	</div>
				5430
				5431	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>morphs an image sequence.</td><td style='text-align:right;'></td></tr></table>
				5432
				5433	<p>Both the image pixels and size are linearly interpolated to give the
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	5434	appearance of a metamorphosis from one image to the next, over all the images
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5435	in the current image list. The added images are the equivalent of a <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5436	href="command-line-options.html#blend">-blend</a> composition. The <em class="arg">frames</em>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5437	argument determine how many images to interpolate between each image. </p>
				5438
				5439
				5440	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5441	<h4><a id="morphology"></a>-morphology</h4>
				5442	<h4>-morphology <em class="arg">method</em> <em class="arg">kernel</em></h4>
cristy	488844c	2010-01-22 14:02:05 +0000	[diff] [blame]	5443	</div>
				5444
cristy	2c83960	2010-04-03 02:32:08 +0000	[diff] [blame]	5445	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>apply a morphology method to the image.</td><td style='text-align:right;'></td></tr></table>
cristy	488844c	2010-01-22 14:02:05 +0000	[diff] [blame]	5446
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5447	<p>Until I get around to writing an option summary for this, see <a
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5448	href="http://www.imagemagick.org/Usage/morphology/" >IM Usage Examples,
				5449	Morphology</a>. </p>
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	5450
				5451
cristy	488844c	2010-01-22 14:02:05 +0000	[diff] [blame]	5452	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5453	<h4><a id="mosaic"></a>-mosaic</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5454	</div>
				5455
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5456	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>an simple alias for the <a href="command-line-options.html#layers" >-layers</a> method "mosaic"</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5457
				5458
				5459	<div style="margin: auto;">
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	5460	<h4><a id="motion-blur"></a>-motion-blur <em class="arg">radius</em><br />-motion-blur <em class="arg">radius</em>x<em class="arg">sigma</em>+<em class="arg">angle</em>+<em class="arg">bias</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5461	</div>
				5462
				5463	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>simulate motion blur.</td><td style='text-align:right;'></td></tr></table>
				5464
				5465	<p>Blur with the given radius, standard deviation (sigma), and angle. The
				5466	angle given is the angle toward which the image is blurred. That is the
				5467	direction people would consider the object is coming from. </p>
				5468
				5469	<p>Note that the blur is not uniform distribution, giving the motion a
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	5470	definite sense of direction of movement. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5471
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5472	<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5473	pixels which are outside the image proper are blurred into the final result.
				5474	</p>
				5475
				5476	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5477	<h4><a id="name"></a>-name</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5478	</div>
				5479
				5480	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>name an image.</td><td style='text-align:right;'></td></tr></table>
				5481	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5482	<h4><a id="negate"></a>-negate</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5483	</div>
				5484
cristy	b29bc03	2010-02-01 20:29:43 +0000	[diff] [blame]	5485	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>replace each pixel with its complementary color.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5486
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5487	<p>The red, green, and blue intensities of an image are negated. White becomes
				5488	black, yellow becomes blue, etc. Use <a href="command-line-options.html#negate">+negate</a> to only
				5489	negate the grayscale pixels of the image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5490
				5491	<div style="margin: auto;">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5492	<h4><a id="noise"></a>-noise <em class="arg">geometry</em><br/>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5493	+noise <em class="arg">type</em></h4>
				5494	</div>
				5495
				5496	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Add or reduce noise in an image.</td><td style='text-align:right;'></td></tr></table>
				5497
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5498	<p>The principal function of noise peak elimination filter is to smooth the
				5499	objects within an image without losing edge information and without creating
				5500	undesired structures. The central idea of the algorithm is to replace a pixel
				5501	with its next neighbor in value within a pixel window, if this pixel has been
				5502	found to be noise. A pixel is defined as noise if and only if this pixel is
				5503	a maximum or minimum within the pixel window.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5504
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5505	<p>Use <code><a href="command-line-options.html#noise">-noise</a> <em class="arg">radius</em></code> to
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5506	specify the width of the neighborhood when reducing noise. This is equivelent
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5507	to using a <code><a href="command-line-options.html#statistic" >-statistic</a> NonPeak</code> operation,
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5508	which should be used in preference.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5509
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5510	<p>Use <a href="command-line-options.html#noise">+noise</a> followed by a noise <em
				5511	class="arg">type</em> to add noise to an image. Choose from these noise
				5512	types:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5513
				5514	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5515	Gaussian
				5516	Impulse
				5517	Laplacian
				5518	Multiplicative
				5519	Poisson
				5520	Random
				5521	Uniform
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5522	</pre>
				5523
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5524	<p>The amount of noise added can be controled by the <code><a
				5525	href="command-line-options.html#attunuuate" >-attenuate</a></code> setting. If unset the value is
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5526	equivelent to 1.0, or a maximum noise addition.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5527
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5528	<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.
				5529
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5530	<p>To print a complete list of noises, use the <a href="command-line-options.html#list">-list noise</a> option.</p>
				5531
				5532	<p>Also see the <a href="command-line-options.html#evaluate">-evaluate</a> noise functions that allows
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	5533	the use of a controlling value to specify the amount of noise that should be
cristy	8354396	2009-10-16 19:04:28 +0000	[diff] [blame]	5534	added to an image. </p>
				5535
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5536
				5537	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5538	<h4><a id="normalize"></a>-normalize</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5539	</div>
				5540
				5541	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Increase the contrast in an image by <em>stretching</em> the range of intensity values.</td><td style='text-align:right;'></td></tr></table>
				5542
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5543	<p>The intensity values are stretched to cover the entire range of possible
				5544	values. While doing so, black-out at most <em>2%</em> of the pixels and
				5545	white-out at most <em>1%</em> of the pixels.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5546
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5547	<p>Note that as of ImageMagick 6.4.7-0, <a href="command-line-options.html#normalize" >-normalize</a>
				5548	is equivalent to <a href="command-line-options.html#contrast-stretch" >-contrast-stretch 2%x1%</a>.
				5549	(Before this version, it was equivalent to <a href="command-line-options.html#contrast-stretch"
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5550	>-contrast-stretch 2%x99%</a>).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5551
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5552	<p>All the channels are normalized in concert by the came amount so as to
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5553	preserve color integrity, when the default <a href="command-line-options.html#channel" >+channel</a>
				5554	setting is in use. Specifying any other <a href="command-line-options.html#channel" >-channel</a>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5555	setting will normalize the RGB channels independently.</p>
				5556
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5557	<p>See <a href="command-line-options.html#contrast-stretch" >-contrast-stretch</a> for more details.
				5558	Also see <a href="command-line-options.html#auto-level" >-auto-level</a> for a 'perfect' normalization
cristy	8354396	2009-10-16 19:04:28 +0000	[diff] [blame]	5559	that is better suited to mathematically generated images. </p>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5560
				5561	<p>This operator is under review for re-development. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5562
				5563
				5564	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5565	<h4><a id="ordered-dither"></a>-ordered-dither <em class="arg">threshold_map</em>{,<em class="arg">level</em>...}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5566	</div>
				5567
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5568	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>dither the image using a pre-defined ordered dither <em
				5569	class="arg">threshold map</em> specified, and a uniform color map with the
				5570	given number of <em class="arg">levels</em> per color channel . </td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5571
				5572	<p>You can choose from these standard threshold maps:</p>
				5573
				5574	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5575	threshold 1x1 Threshold 1x1 (non-dither)
				5576	checks 2x1 Checkerboard 2x1 (dither)
				5577	o2x2 2x2 Ordered 2x2 (dispersed)
				5578	o3x3 3x3 Ordered 3x3 (dispersed)
				5579	o4x4 4x4 Ordered 4x4 (dispersed)
				5580	o8x8 8x8 Ordered 8x8 (dispersed)
				5581	h4x4a 4x1 Halftone 4x4 (angled)
				5582	h6x6a 6x1 Halftone 6x6 (angled)
				5583	h8x8a 8x1 Halftone 8x8 (angled)
				5584	h4x4o Halftone 4x4 (orthogonal)
				5585	h6x6o Halftone 6x6 (orthogonal)
				5586	h8x8o Halftone 8x8 (orthogonal)
				5587	h16x16o Halftone 16x16 (orthogonal)
				5588	c5x5b c5x5 Circles 5x5 (black)
				5589	c5x5w Circles 5x5 (white)
				5590	c6x6b c6x6 Circles 6x6 (black)
				5591	c6x6w Circles 6x6 (white)
				5592	c7x7b c7x7 Circles 7x7 (black)
				5593	c7x7w Circles 7x7 (white)
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5594	</pre>
				5595
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5596	<p> The <code>threshold</code> generated a simple 50% threshold of the image.
cristy	baacd17	2011-04-30 23:11:03 +0000	[diff] [blame]	5597	This could be used with <em class="arg" >level</em> to do the equivalent of <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5598	href="command-line-options.html#posterize" >-posterize</a> to reduce an image to basic primary colors.
cristy	945bb35	2011-04-01 15:39:28 +0000	[diff] [blame]	5599	</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5600
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5601	<p>The <code>checks</code> pattern produces a 3 level checkerboard dither
cristy	945bb35	2011-04-01 15:39:28 +0000	[diff] [blame]	5602	pattern. That is a grayscale will become a pattern of solid black, solid
				5603	white, and mid-tone colors into a checkerboard pattern of black and white.
				5604	</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5605
cristy	945bb35	2011-04-01 15:39:28 +0000	[diff] [blame]	5606	<p>You can define your own <em class="arg" >threshold map</em> for ordered
				5607	dithering and halftoning your images, in either personal or system
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5608	<code>thresholds.xml</code> XML file. See <a href="resources.html" >Resources</A>
cristy	945bb35	2011-04-01 15:39:28 +0000	[diff] [blame]	5609	for more details of configuration files. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5610
cristy	945bb35	2011-04-01 15:39:28 +0000	[diff] [blame]	5611	<p>To print a complete list of the thresholds that have been defined, use the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5612	<a href="command-line-options.html#list" >-list threshold</a> option.</p>
cristy	945bb35	2011-04-01 15:39:28 +0000	[diff] [blame]	5613
				5614	<p>Note that at this time the same threshold dithering map is used for all
				5615	color channels, no attempt is made to offset or rotate the map for different
				5616	channels is made, to create an offset printing effect. Also as the maps are
				5617	simple threshold levels, the halftone and circle maps will create incomplete
				5618	circles along the edges of a colored area. Also all the effects are purely
				5619	on/off boolean effects, without anti-aliasing to make the circles smooth
				5620	looking. Large dots can be made to look better with a small amount of blurring
				5621	after being created. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5622
				5623
				5624	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5625	<h4><a id="opaque"></a>-opaque <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5626	</div>
				5627
				5628	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>change this color to the fill color within the image.</td><td style='text-align:right;'></td></tr></table>
				5629
cristy	c54f5d4	2009-11-27 21:36:31 +0000	[diff] [blame]	5630	<p>The <em class="arg">color</em> argument is defined using the format
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5631	described under the <a href="command-line-options.html#fill" >-fill</a> option. The <a href="command-line-options.html#fuzz"
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5632	>-fuzz</a> setting can be used to match and replace colors similar to the one
				5633	given.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5634
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5635	<p>Use <a href="command-line-options.html#opaque">+opaque</a> to paint any pixel that does not match
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	5636	the target color. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5637
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5638	<p>The <a href="command-line-options.html#transparent">-transparent</a> operator is exactly the same
				5639	as <a href="command-line-options.html#opaque" >-opaque</a> but replaces the matching color with
				5640	transparency rather than the current <a href="command-line-options.html#fill">-fill</a> color setting.
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	5641	To ensure that it can do this it also ensures that the image has an alpha
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5642	channel enabled, as per "<code><a href="command-line-options.html#alpha" >-alpha</a> set</code>", for
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	5643	the new transparent colors, and does not require you to modify the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5644	href="command-line-options.html#channel">-channel</a> to enable alpha channel handling. </p>
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5645
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5646
				5647	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5648	<h4><a id="orient"></a>-orient <em class="arg">image orientation</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5649	</div>
				5650
				5651	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>specify orientation of a digital camera image.</td><td style='text-align:right;'></td></tr></table>
				5652
				5653	<p>Choose from these orientations:</p>
				5654
				5655	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5656	bottom-left
				5657	bottom-right
				5658	left-bottom
				5659	left-top
				5660	right-bottom
				5661	right-top
				5662	top-left
				5663	top-right
				5664	undefined
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5665	</pre>
				5666
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5667	<p>To print a complete list of orientations, use the <a href="command-line-options.html#list" >-list
cristy	d934d10	2009-10-10 12:55:13 +0000	[diff] [blame]	5668	orientation</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5669
				5670
				5671	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5672	<h4><a id="page"></a>-page <em class="arg">geometry</em><br/>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5673	-page <em class="arg">media</em>[<em class="arg">offset</em>][{<em class="arg">^!<></em>}]<br/>
				5674	+page
				5675	</h4>
				5676	</div>
				5677
				5678	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the size and location of an image on the larger virtual canvas.</td><td style='text-align:right;'></td></tr></table>
				5679
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5680	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5681
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5682	<p>For convenience you can specify the page size using <em
				5683	class="arg">media</em> (see below). Offsets can then be added as with other
				5684	<em class="arg">geometry</em> arguments (e.g. <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5685	href="command-line-options.html#page">-page</a> <code>Letter+43+43</code>).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5686
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5687	<p>Use <em class="arg">media</em> as shorthand to specify the dimensions (<em
				5688	class="arg">width</em>x<em class="arg">height</em>) of the <em
				5689	class="arg">PostScript</em> page in dots per inch or a TEXT page in pixels.
				5690	The choices for a PostScript page are:</p>
				5691
				5692	<table id="geometryTable" cellpadding="2" cellspacing="0" border="1"
				5693	width="50%" style="margin-left: auto; margin-right: auto;">
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5694	<thead>
				5695	<tr valign="top">
				5696	<th align="center"><em class="arg">media</em></th>
				5697	<th align="center"><em class="arg">width</em></th>
				5698	<th align="center"><em class="arg">height</em></th>
				5699	</tr>
				5700	</thead>
				5701	<tbody>
				5702	<tr><td align="left"> 11x17 </td> <td align="right"> 792</td> <td align="right"> 1224</td> </tr>
				5703	<tr><td align="left"> Ledger </td> <td align="right"> 1224</td> <td align="right"> 792</td> </tr>
				5704	<tr><td align="left"> Legal </td> <td align="right"> 612</td> <td align="right"> 1008</td> </tr>
				5705	<tr><td align="left"> Letter </td> <td align="right"> 612</td> <td align="right"> 792</td> </tr>
				5706	<tr><td align="left"> LetterSmall</td> <td align="right"> 612</td> <td align="right"> 792</td> </tr>
				5707	<tr><td align="left"> ArchE </td> <td align="right"> 2592</td> <td align="right"> 3456</td> </tr>
				5708	<tr><td align="left"> ArchD </td> <td align="right"> 1728</td> <td align="right"> 2592</td> </tr>
				5709	<tr><td align="left"> ArchC </td> <td align="right"> 1296</td> <td align="right"> 1728</td> </tr>
				5710	<tr><td align="left"> ArchB </td> <td align="right"> 864</td> <td align="right"> 1296</td> </tr>
				5711	<tr><td align="left"> ArchA </td> <td align="right"> 648</td> <td align="right"> 864</td> </tr>
				5712	<tr><td align="left"> A0 </td> <td align="right"> 2380</td> <td align="right"> 3368</td> </tr>
				5713	<tr><td align="left"> A1 </td> <td align="right"> 1684</td> <td align="right"> 2380</td> </tr>
				5714	<tr><td align="left"> A2 </td> <td align="right"> 1190</td> <td align="right"> 1684</td> </tr>
				5715	<tr><td align="left"> A3 </td> <td align="right"> 842</td> <td align="right"> 1190</td> </tr>
				5716	<tr><td align="left"> A4 </td> <td align="right"> 595</td> <td align="right"> 842</td> </tr>
				5717	<tr><td align="left"> A4Small </td> <td align="right"> 595</td> <td align="right"> 842</td> </tr>
				5718	<tr><td align="left"> A5 </td> <td align="right"> 421</td> <td align="right"> 595</td> </tr>
				5719	<tr><td align="left"> A6 </td> <td align="right"> 297</td> <td align="right"> 421</td> </tr>
				5720	<tr><td align="left"> A7 </td> <td align="right"> 210</td> <td align="right"> 297</td> </tr>
				5721	<tr><td align="left"> A8 </td> <td align="right"> 148</td> <td align="right"> 210</td> </tr>
				5722	<tr><td align="left"> A9 </td> <td align="right"> 105</td> <td align="right"> 148</td> </tr>
				5723	<tr><td align="left"> A10 </td> <td align="right"> 74</td> <td align="right"> 105</td> </tr>
				5724	<tr><td align="left"> B0 </td> <td align="right"> 2836</td> <td align="right"> 4008</td> </tr>
				5725	<tr><td align="left"> B1 </td> <td align="right"> 2004</td> <td align="right"> 2836</td> </tr>
				5726	<tr><td align="left"> B2 </td> <td align="right"> 1418</td> <td align="right"> 2004</td> </tr>
				5727	<tr><td align="left"> B3 </td> <td align="right"> 1002</td> <td align="right"> 1418</td> </tr>
				5728	<tr><td align="left"> B4 </td> <td align="right"> 709</td> <td align="right"> 1002</td> </tr>
				5729	<tr><td align="left"> B5 </td> <td align="right"> 501</td> <td align="right"> 709</td> </tr>
				5730	<tr><td align="left"> C0 </td> <td align="right"> 2600</td> <td align="right"> 3677</td> </tr>
				5731	<tr><td align="left"> C1 </td> <td align="right"> 1837</td> <td align="right"> 2600</td> </tr>
				5732	<tr><td align="left"> C2 </td> <td align="right"> 1298</td> <td align="right"> 1837</td> </tr>
				5733	<tr><td align="left"> C3 </td> <td align="right"> 918</td> <td align="right"> 1298</td> </tr>
				5734	<tr><td align="left"> C4 </td> <td align="right"> 649</td> <td align="right"> 918</td> </tr>
				5735	<tr><td align="left"> C5 </td> <td align="right"> 459</td> <td align="right"> 649</td> </tr>
				5736	<tr><td align="left"> C6 </td> <td align="right"> 323</td> <td align="right"> 459</td> </tr>
				5737	<tr><td align="left"> Flsa </td> <td align="right"> 612</td> <td align="right"> 936</td> </tr>
				5738	<tr><td align="left"> Flse </td> <td align="right"> 612</td> <td align="right"> 936</td> </tr>
				5739	<tr><td align="left"> HalfLetter </td> <td align="right"> 396</td> <td align="right"> 612</td> </tr>
				5740	</tbody>
				5741	</table>
				5742
				5743
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5744	<p>This option is also used to place subimages when writing to a multi-image
				5745	format that supports offsets, such as GIF89 and MNG. When used for this
				5746	purpose the offsets are always measured from the top left corner of the canvas
				5747	and are not affected by the <a href="command-line-options.html#gravity">-gravity</a> option. To
				5748	position a GIF or MNG image, use <a href="command-line-options.html#page">-page</a><em
				5749	class="arg">{+-}x{+-}y</em> (e.g. -page +100+200). When writing to a MNG
				5750	file, a <a href="command-line-options.html#page">-page</a> option appearing ahead of the first image in
				5751	the sequence with nonzero width and height defines the width and height values
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5752	that are written in the <code>MHDR</code> chunk. Otherwise, the MNG width and
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5753	height are computed from the bounding box that contains all images in the
				5754	sequence. When writing a GIF89 file, only the bounding box method is used to
				5755	determine its dimensions.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5756
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5757	<p>For a PostScript page, the image is sized as in <a
				5758	href="command-line-options.html#geometry">-geometry</a> but positioned relative to the <em>lower
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5759	left-hand corner</em> of the page by {+-}<code>x</code><em
				5760	class="arg">offset</em>{+-}<code>y</code> <em class="arg">offset</em>. Use <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5761	href="command-line-options.html#page">-page 612x792</a>, for example, to center the image within the
				5762	page. If the image size exceeds the PostScript page, it is reduced to fit the
				5763	page. The default gravity for the <a href="command-line-options.html#page">-page</a> option is <em
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5764	class="arg">NorthWest</em>, i.e., positive <code>x</code> and <code>y</code> <em
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5765	class="arg">offset</em> are measured rightward and downward from the top left
				5766	corner of the page, unless the <a href="command-line-options.html#gravity">-gravity</a> option is
				5767	present with a value other than <em class="arg">NorthWest</em>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5768
				5769	<p>The default page dimensions for a TEXT image is 612x792.</p>
				5770
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5771	<p>This option is used in concert with <a href="command-line-options.html#density">-density</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5772
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5773	<p>Use <a href="command-line-options.html#page">+page</a> to remove the page settings for an image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5774
				5775	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5776	<h4><a id="paint"></a>-paint <em class="arg">radius</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5777	</div>
				5778
				5779	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>simulate an oil painting.</td><td style='text-align:right;'></td></tr></table>
				5780
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5781	<p>Each pixel is replaced by the most frequent color in a circular
				5782	neighborhood whose width is specified with <em class="arg">radius</em>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5783
				5784	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5785	<h4><a id="path"></a>-path <em class="arg">path</em></h4></div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5786
				5787	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>write images to this path on disk.</td><td style='text-align:right;'></td></tr></table>
				5788
				5789	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5790	<h4><a id="pause_animate_"></a>-pause <em class="arg">seconds</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5791	</div>
				5792
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5793	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Pause between animation loops.</td><td style='text-align:right;'>[<a href="animate.html">animate</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5794
				5795	<p>Pause for the specified number of seconds before repeating the animation.</p>
				5796
				5797	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5798	<h4><a id="pause_import_"></a>-pause <em class="arg">seconds</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5799	</div>
				5800
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5801	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Pause between snapshots.</td><td style='text-align:right;'>[<a href="import.html">import</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5802
				5803	<p>Pause for the specified number of seconds before taking the next snapshot.</p>
				5804
				5805	<div style="margin: auto;">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5806	<h4><a id="perceptible"></a>-perceptible <em class="arg">epsilon</em></h4>
				5807	</div>
				5808
				5809	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>set each pixel whose value is less than \|<em>epsilon</em>\| to <em>-epsilon</em> or <em>epsilon</em> (whichever is closer) otherwise the pixel value remains unchanged.</td><td style='text-align:right;'></td></tr></table>
				5810
				5811	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5812	<h4><a id="ping"></a>-ping</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5813	</div>
				5814
				5815	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>efficiently determine image characteristics.</td><td style='text-align:right;'></td></tr></table>
				5816
				5817	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5818	<h4><a id="pointsize"></a>-pointsize <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5819	</div>
				5820
				5821	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>pointsize of the PostScript, OPTION1, or TrueType font.</td><td style='text-align:right;'></td></tr></table>
				5822
				5823	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5824	<h4><a id="polaroid"></a>-polaroid <em class="arg">angle</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5825	</div>
				5826
				5827	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>simulate a Polaroid picture.</td><td style='text-align:right;'></td></tr></table>
				5828
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5829	<p>Use <code>+polaroid</code> to rotate the image at a random angle between -15 and +15 degrees.</p>
				5830
				5831	<div style="margin: auto;">
				5832	<h4><a id="poly"></a>-poly <em class="arg">"wt,exp ..."</em></h4>
				5833	</div>
				5834
				5835	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>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.</td><td style='text-align:right;'></td></tr></table>
				5836
				5837	<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.
				5838
				5839	<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>
				5840
				5841	<p>The format is: output = wt1image1^exp1 + wt2image2^exp2 ...</p>
				5842
				5843	<p>Some simple uses are:</p>
				5844	<ul>
				5845	<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> <em class="arg">mean</em>.</li>
				5846	<br />
				5847	<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>
				5848	</ul>
				5849
				5850	<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>
				5851
				5852	<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>
				5853
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5854
				5855	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5856	<h4><a id="posterize"></a>-posterize <em class="arg">levels</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5857	</div>
				5858
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5859	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>reduce the image to a limited number of color levels per channel.</td><td style='text-align:right;'></td></tr></table>
				5860
				5861	<p>Very low values of <em class="arg">levels</em>, e.g., 2, 3, 4, have the most
				5862	visible effect.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5863
				5864	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5865	<h4><a id="precision"></a>-precision <em class="arg">value</em></h4>
cristy	d43a46b	2010-01-21 02:13:41 +0000	[diff] [blame]	5866	</div>
				5867
				5868	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>set the maximum number of significant digits to be printed.</td><td style='text-align:right;'></td></tr></table>
				5869
				5870	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5871	<h4><a id="preview"></a>-preview <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5872	</div>
				5873
				5874	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>image preview type.</td><td style='text-align:right;'></td></tr></table>
				5875
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5876	<p>Use this option to affect the preview operation of an image (e.g.
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5877	<code>convert file.png -preview Gamma Preview:gamma.png</code>). Choose from
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5878	these previews:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5879
				5880	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5881	Rotate Shear Roll Hue
				5882	Saturation Brightness Gamma Spiff
				5883	Dull Grayscale Quantize Despeckle
				5884	ReduceNoise Add Noise Sharpen Blur
				5885	Threshold EdgeDetect Spread Shade
				5886	Raise Segment Solarize Swirl
				5887	Implode Wave OilPaint CharcoalDrawing
				5888	JPEG
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5889	</pre>
				5890
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5891	<p>To print a complete list of previews, use the <a href="command-line-options.html#list">-list preview</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5892
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5893	<p>The default preview is <code>JPEG</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5894
				5895	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5896	<h4><a id="print"></a>-print <em class="arg">string</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5897	</div>
				5898
				5899	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>interpret string and print to console.</td><td style='text-align:right;'></td></tr></table>
				5900
				5901	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5902	<h4><a id="process"></a>-process <em class="arg">command</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5903	</div>
				5904
				5905	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>process the image with a custom image filter.</td><td style='text-align:right;'></td></tr></table>
				5906
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5907	<p>The command arguments has the form <code>"module arg1 arg2 arg3 ...
				5908	argN"</code> where <code>module</code> is the name of the module to invoke (e.g.
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5909	"Analyze") and arg1 arg2 arg3 ... argN are an arbitrary number of arguments to
				5910	pass to the process module.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5911
				5912	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5913	<h4><a id="profile"></a>-profile <em class="arg">filename</em><br/>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5914	+profile <em class="arg">profile_name</em></h4>
				5915	</div>
				5916
				5917	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Manage ICM, IPTC, or generic profiles in an image.</td><td style='text-align:right;'></td></tr></table>
				5918
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5919	<p>Using <a href="command-line-options.html#profile">-profile</a> <em class="arg">filename</em> adds an
				5920	ICM (ICC color management), IPTC (newswire information), or a generic profile
				5921	to the image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5922
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5923	<p>Use <a href="command-line-options.html#profile">+profile <em class="arg">profile_name</em></a> to
				5924	remove the indicated profile. ImageMagick uses standard filename globbing, so
				5925	wildcard expressions may be used to remove more than one profile. Here we
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5926	remove all profiles from the image except for the XMP profile: <code>+profile
				5927	"!xmp,*"</code>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5928
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	5929	<p>Use <code>identify -verbose</code> to find out which profiles are in the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5930	image file. Use <a href="command-line-options.html#strip">-strip</a> to remove all profiles (and
				5931	comments).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5932
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5933	<p>To extract a profile, the <a href="command-line-options.html#profile">-profile</a> option is not
				5934	used. Instead, simply write the file to an image format such as <em
				5935	class="arg">APP1, 8BIM, ICM,</em> or <em class="arg">IPTC</em>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5936
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5937	<p>For example, to extract the Exif data (which is stored in JPEG files in the
				5938	<em class="arg">APP1</em> profile), use.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5939
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	5940	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert cockatoo.jpg profile.exif</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5941	<p>It is important to note that results may depend on whether or not the
				5942	original image already has an included profile. Also, keep in mind that <a
				5943	href="command-line-options.html#profile">-profile</a> is an "operator" (as opposed to a "setting") and
				5944	therefore a conversion is made each time it is encountered, in order, in the
				5945	command-line. For instance, in the following example, if the original image is
				5946	CMYK with profile, a CMYK-CMYK-RGB conversion results.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5947
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	5948	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert CMYK.tif -profile "CMYK.icc" -profile "RGB.icc" RGB.tiff</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5949	<p>Furthermore, since ICC profiles are not necessarily symmetric, extra
				5950	conversion steps can yield unwanted results. CMYK profiles are often very
				5951	asymmetric since they involve 3−>4 and 4−>3 channel mapping.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5952	</p>
				5953
				5954	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	5955	<h4><a id="quality"></a>-quality <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5956	</div>
				5957
				5958	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>JPEG/MIFF/PNG compression level.</td><td style='text-align:right;'></td></tr></table>
				5959
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	5960	<p>For the JPEG and MPEG image formats, quality is 1 (lowest image quality and
				5961	highest compression) to 100 (best quality but least effective compression).
				5962	The default is to use the estimated quality of your input image if it can
				5963	be determined, otherwise 92. When the quality is greater than 90, then the
				5964	chroma channels are not downsampled.
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5965	Use the <a href="command-line-options.html#sampling-factor">-sampling-factor</a> option to specify the
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	5966	factors for chroma downsampling.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5967
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5968	<p>For the MIFF image format, quality/10 is the zlib compression level, which
				5969	is 0 (worst but fastest compression) to 9 (best but slowest). It has no effect
				5970	on the image appearance, since the compression is always lossless.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5971
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5972	<p>For the JPEG-2000 image format, quality is mapped using a non-linear
				5973	equation to the compression ratio required by the Jasper library. This
				5974	non-linear equation is intended to loosely approximate the quality provided by
				5975	the JPEG v1 format. The default quality value 100, a request for non-lossy
				5976	compression. A quality of 75 results in a request for 16:1 compression.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5977
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	5978	<p>For the MNG and PNG image formats, the quality value sets the zlib
				5979	compression level (quality / 10) and filter-type (quality % 10). The default
				5980	PNG "quality" is 75, which means compression level 7 with adaptive PNG
				5981	filtering, unless the image has a color map, in which case it means
				5982	compression level 7 with no PNG filtering.</p>
				5983
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	5984	<p>For compression level 0, the Huffman-only strategy is used, which is
				5985	fastest but not necessarily the worst compression.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5986
cristy	a4dfb12	2011-07-07 19:01:57 +0000	[diff] [blame]	5987	<p>If filter-type is 4 or less, the specified PNG filter-type is used for
				5988	all scanlines:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5989
				5990	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	5991	0: none
				5992	1: sub
				5993	2: up
				5994	3: average
				5995	4: Paeth
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	5996	</pre>
				5997
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	5998	<p>If filter-type is 5, adaptive filtering is used when quality is greater
				5999	than 50 and the image does not have a color map, otherwise no filtering is
				6000	used.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6001
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	6002	<p>If filter-type is 6, adaptive filtering
				6003	with <em class="arg">minimum-sum-of-absolute-values</em> is used.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6004
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	6005	<p>Only if the output is MNG, if filter-type is 7, the LOCO color
				6006	transformation (intrapixel differencing) and adaptive filtering
				6007	with <em class="arg">minimum-sum-of-absolute-values</em> are used.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6008
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	6009	<p>If the filter-type is 8 the zlib Z_RLE compression strategy is used with
				6010	no PNG filtering.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6011
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	6012	<p>If the filter-type is 9 the zlib Z_RLE compression strategy is used with
				6013	adaptive PNG filtering.</p>
				6014
cristy	a4dfb12	2011-07-07 19:01:57 +0000	[diff] [blame]	6015	<p>The quality setting has no effect on the appearance or signature of PNG
				6016	and MNG images, since the compression is always lossless.</p>
				6017
				6018	<p>Not all combinations of compression level, strategy, and PNG filter type
				6019	can be obtained using the -quality option. For more precise control,
				6020	you can use the PNG:compression-level=N, PNG:compression-strategy=N, and
				6021	PNG:compression-filter=N defines, respectively, instead.
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6022	See <a href="command-line-options.html#define">-define</a>. Values from the defines take precedence
cristy	a4dfb12	2011-07-07 19:01:57 +0000	[diff] [blame]	6023	over values from the -quality option.</p>
cristy	87a7f07	2011-07-01 00:08:52 +0000	[diff] [blame]	6024
				6025	<p>For further information, see
				6026	the <a href="http://www.w3.org/pub/WWW/TR">PNG</a> specification.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6027
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6028	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6029	<h4><a id="quantize"></a>-quantize <em class="arg">colorspace</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6030	</div>
				6031
cristy	3c98a4f	2010-08-13 20:09:41 +0000	[diff] [blame]	6032	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>reduce colors using this colorspace.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6033
cristy	3c98a4f	2010-08-13 20:09:41 +0000	[diff] [blame]	6034	<p>This setting defines the colorspace used to sort out and reduce the number
				6035	of colors needed by an image (for later dithering) by operators such as <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6036	href="command-line-options.html#colors" >-colors</a>, Note that color reduction also happens
cristy	3c98a4f	2010-08-13 20:09:41 +0000	[diff] [blame]	6037	automatically when saving images to color-limited image file formats, such as
				6038	GIF, and PNG8.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6039
				6040
				6041	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6042	<h4><a id="quiet"></a>-quiet</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6043	</div>
				6044
				6045	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>suppress all warning messages. Error messages are still reported.</td><td style='text-align:right;'></td></tr></table>
				6046
				6047	<div style="margin: auto;">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6048	<h4><a id="radial-blur"></a>-radial-blur <em class="arg">angle</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6049	</div>
				6050
				6051	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Blur around the center of the image.</td><td style='text-align:right;'></td></tr></table>
				6052
				6053	<p>Note that this is actually a rotational blur rather than a radial and as
				6054	such actually mis-named. </p>
				6055
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6056	<p>The <a href="command-line-options.html#virtual-pixel">-virtual-pixel</a> setting will determine how
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6057	pixels which are outside the image proper are blurred into the final result.
				6058	</p>
				6059
				6060
				6061	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6062	<h4><a id="raise"></a>-raise <em class="arg">thickness</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6063	</div>
				6064
				6065	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Lighten or darken image edges.</td><td style='text-align:right;'></td></tr></table>
				6066
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6067	<p>This will create a 3-D effect. Use <a href="command-line-options.html#raise">-raise</a> to create
				6068	a raised effect, otherwise use <a href="command-line-options.html#raise">+raise</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6069
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6070	<p>Unlike the similar <a href="command-line-options.html#frame">-frame</a> option, <a
				6071	href="command-line-options.html#raise">-raise</a> does not alter the dimensions of the image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6072
				6073	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6074	<h4><a id="random-threshold"></a>-random-threshold <em class="arg">low</em>x<em class="arg">high</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6075	</div>
				6076
				6077	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply a random threshold to the image.</td><td style='text-align:right;'></td></tr></table>
				6078
				6079	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6080	<h4><a id="red-primary"></a>-red-primary <em class="arg">x,y</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6081	</div>
				6082
				6083	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the red chromaticity primary point.</td><td style='text-align:right;'></td></tr></table>
				6084
				6085	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6086	<h4><a id="regard-warnings"></a>-regard-warnings</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6087	</div>
				6088
				6089	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Pay attention to warning messages.</td><td style='text-align:right;'></td></tr></table>
				6090
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6091	<p>This option causes some warnings in some image formats to be treated
				6092	as errors. </p>
				6093
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6094	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6095	<h4><a id="remap"></a>-remap <em class="arg">filename</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6096	</div>
				6097
				6098	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Reduce the number of colors in an image to the colors used by this image.</td><td style='text-align:right;'></td></tr></table>
				6099
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6100	<p>If the <a href="command-line-options.html#dither">-dither</a> setting is enabled (the default) then
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6101	the given colors are dithered over the image as necessary, otherwise the closest
				6102	color (in RGB colorspace) is selected to replace that pixel in the image. </p>
				6103
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6104	<p>As a side effect of applying a <a href="command-line-options.html#remap">-remap</a> of colors across all
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6105	images in the current image sequence, all the images will have the same color
				6106	table. That means that when saved to a file format such as GIF, it will use
				6107	that color table as a single common or global color table, for all the images,
				6108	without requiring extra local color tables. </p>
				6109
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6110	<p>Use <a href="command-line-options.html#remap">+remap</a> to reduce all images in the current image
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6111	sequence to use a common color map over all the images. This equivalent to
				6112	appending all the images together (without extra background colors) and color
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6113	reducing those images using <a href="command-line-options.html#colors">-colors</a> with a 256 color
				6114	limit, then <a href="command-line-options.html#remap">-remap</a> those colors over the original list of
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6115	images. This ensures all the images follow a single color map. </p>
				6116
				6117	<p>If the number of colors over all the images is less than 256, then <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6118	href="command-line-options.html#remap">+remap</a> should not perform any color reduction or dithering, as
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6119	no color changes are needed. In that case, its only effect is to force the use
				6120	of a global color table. This recommended after using either <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6121	href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#ordered-dither">-ordered-dither</a> to
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6122	reduce the number of colors in an animated image sequence. </p>
				6123
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6124	<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>
				6125
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6126	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6127	<h4><a id="region"></a>-region <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6128	</div>
				6129
				6130	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set a region in which subsequent operations apply.</td><td style='text-align:right;'></td></tr></table>
				6131
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6132	<p>The <em class="arg">x</em> and <em class="arg">y</em> offsets are treated
				6133	in the same manner as in <a href="command-line-options.html#crop">-crop</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6134
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6135	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6136
				6137	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6138	<h4><a id="remote"></a>-remote</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6139	</div>
				6140
				6141	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>perform a remote operation.</td><td style='text-align:right;'></td></tr></table>
				6142
				6143	<p>The only command recognized is the name of an image file to load.</p>
				6144
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6145	<p>If you have more than one <a href="display.html">display</a> application
				6146	running simultaneously, use the <a href="command-line-options.html#window"> window</a> option to
				6147	specify which application to control.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6148
				6149	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6150	<h4><a id="render"></a>-render</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6151	</div>
				6152
				6153	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>render vector operations.</td><td style='text-align:right;'></td></tr></table>
				6154
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6155	<p>Use <a href="command-line-options.html#render">+render</a> to turn off rendering vector operations.
				6156	This useful when saving the result to vector formats such as MVG or SVG.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6157
				6158	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6159	<h4><a id="repage"></a>-repage <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6160	</div>
				6161
				6162	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Adjust the canvas and offset information of the image.</td><td style='text-align:right;'></td></tr></table>
				6163
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6164	<p>This option is like <a href="command-line-options.html#page">-page</a> but acts as an image operator
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6165	rather than a setting. You can separately set the canvas size or the offset
				6166	of the image on that canvas by only providing those components. </p>
				6167
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6168	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6169
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6170	<p>If a <code>!</code> flag is given the offset given is added to the existing
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6171	offset to move the image relative to its previous position. This useful for
				6172	animation sequences. </p>
				6173
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6174	<p>A given a canvas size of zero such as '<code>0x0</code>' forces it to
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6175	recalculate the canvas size so the image (at its current offset) will appear
				6176	completely on that canvas (unless it has a negative offset).</p>
				6177
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6178	<p>Use <a href="command-line-options.html#repage">+repage</a> to completely remove/reset the virtual
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6179	canvas meta-data from the images. </p>
				6180
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6181	<p>The <a href="command-line-options.html#set">-set</a> '<code>page</code>' option can be used to
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6182	directly assign virtual canvas meta-data. </p>
				6183
				6184
				6185	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6186	<h4><a id="resample"></a>-resample <em class="arg">horizontal</em>x<em class="arg">vertical</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6187	</div>
				6188
				6189	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Resample image to specified horizontal and vertical resolution.</td><td style='text-align:right;'></td></tr></table>
				6190
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6191	<p>Resize the image so that its rendered size remains the same as the original
				6192	at the specified target resolution. For example, if a 300 DPI image renders at
				6193	3 inches by 2 inches on a 300 DPI device, when the image has been resampled to
				6194	72 DPI, it will render at 3 inches by 2 inches on a 72 DPI device. Note that
				6195	only a small number of image formats (e.g. JPEG, PNG, and TIFF) are capable of
				6196	storing the image resolution. For formats which do not support an image
				6197	resolution, the original resolution of the image must be specified via <a
				6198	href="command-line-options.html#density">-density</a> on the command line prior to specifying the
				6199	resample resolution.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6200
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6201	<p>Note that Photoshop stores and obtains image resolution from a proprietary
				6202	embedded profile. If this profile exists in the image, then Photoshop will
				6203	continue to treat the image using its former resolution, ignoring the image
				6204	resolution specified in the standard file header.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6205
				6206	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6207	<h4><a id="resize"></a>-resize <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6208	</div>
				6209
				6210	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Resize an image.</td><td style='text-align:right;'></td></tr></table>
				6211
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6212	<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
				6213	ignored, and the <a href="command-line-options.html#gravity">-gravity</a> option has no effect.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6214
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6215	<p>If the <a href="command-line-options.html#filter">-filter</a> option precedes the <a
				6216	href="command-line-options.html#resize">-resize</a> option, the image is resized with the specified
				6217	filter.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6218
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6219	<p>Many image processing algorithms assume your image is in a linear-light
				6220	coding. If your image is gamma-corrected, you can remove the nonlinear gamma
				6221	correction, apply the transform, then restore it like this:</p>
cristy	1353896	2010-02-26 17:53:04 +0000	[diff] [blame]	6222
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6223	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert portrait.jpg -gamma .45455 -resize 25% -gamma 2.2 \ <br/> -quality 92 passport.jpg</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6224	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6225	<h4><a id="respect-parentheses"></a>-respect-parentheses</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6226	</div>
				6227
				6228	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>settings remain in effect until parenthesis boundary.</td><td style='text-align:right;'></td></tr></table>
				6229
				6230	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6231	<h4><a id="reverse"></a>-reverse</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6232	</div>
				6233
				6234	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Reverse the order of images in the current image list.</td><td style='text-align:right;'></td></tr></table>
				6235
				6236
				6237	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6238	<h4><a id="roll"></a>-roll {<em class="arg">+-</em>}<em class="arg">x</em>{<em class="arg">+-</em>}<em class="arg">y</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6239	</div>
				6240
				6241	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>roll an image vertically or horizontally by the amount given.</td><td style='text-align:right;'></td></tr></table>
				6242
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6243	<p>A negative <em class="arg">x</em> offset rolls the image left-to-right.
				6244	A negative <em class="arg">y</em> offset rolls the image top-to-bottom.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6245
				6246
				6247	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6248	<h4><a id="rotate"></a>-rotate <em class="arg">degrees</em>{<em class="arg"><</em>}{<em class="arg">></em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6249	</div>
				6250
				6251	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply Paeth image rotation (using shear operations) to the image.</td><td style='text-align:right;'></td></tr></table>
				6252
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6253	<p>Use <code>></code> to rotate the image only if its width exceeds the
				6254	height. <code><</code> rotates the image <em>only</em> if its width is less
				6255	than the height. For example, if you specify <code>-rotate "-90>"</code> and
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6256	the image size is 480x640, the image is not rotated. However, if the image is
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6257	640x480, it is rotated by -90 degrees. If you use <code>></code> or
				6258	<code><</code>, enclose it in quotation marks to prevent it from being
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6259	misinterpreted as a file redirection.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6260
				6261	<p>Empty triangles in the corners, left over from rotating the image, are
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6262	filled with the <code>background</code> color. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6263
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6264	<p>See also the <a href="command-line-options.html#distort">-distort</a> operator and specifically the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6265	'<code>ScaleRotateTranslate</code>' distort method. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6266
				6267
				6268	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6269	<h4><a id="sample"></a>-sample <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6270	</div>
				6271
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6272	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>minify / magnify the image with pixel subsampling and pixel replication, respectively.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6273
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6274	<p>Change the image size simply by directly sampling the pixels original
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6275	from the image. When magnifying, pixels are replicated in blocks. When
				6276	minifying, pixels are sub-sampled (i.e., some rows and columns are skipped
				6277	over). </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6278
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6279	<p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6280	a <a href="command-line-options.html#filter">-filter</a> setting of <code>point</code> (nearest
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6281	neighbour), though <a href="command-line-options.html#sample">-sample</a> is a lot faster, as it
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6282	avoids all the filter processing of the image. As such it completely ignores
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6283	the current <a href="command-line-options.html#filter">-filter</a> setting. </p>
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6284
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6285	<p>The key feature of the <a href="command-line-options.html#sample">-sample</a> is that no new colors
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6286	will be added to the resulting image, though some colors may disappear. </p>
				6287
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6288	<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
				6289	ignored, unlike <a href="command-line-options.html#resize">-resize</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6290
				6291
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6292	<p>The actual sampling point is the middle of the sub-region being sampled.
				6293	As such a single pixel sampling of an image will take the middle pixel, (or
				6294	top-left-middle if image has even dimensions). However the <a
				6295	href="command-line-options.html#define">-define</a> '<code>sample:offset</code>' can be set to modify
				6296	this position some other location within each sub-region being sampled, as
				6297	a percentage offset.</p>
				6298
				6299	<p>By default this value is '<code>50</code>' for the midpoint, but could be set
				6300	to '<code>0</code>' for top-left, '<code>100</code>' for bottom-right, or with
				6301	separate X and Y offsets such as '<code>0x50</code>' for left-middle edge of
				6302	sampling sub-region.</p>
				6303
				6304
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6305	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6306	<h4><a id="sampling-factor"></a>-sampling-factor <em class="arg">horizontal-factor</em>x<em class="arg">vertical-factor</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6307	</div>
				6308
				6309	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>sampling factors used by JPEG or MPEG-2 encoder and YUV decoder/encoder.</td><td style='text-align:right;'></td></tr></table>
				6310
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6311	<p>This option specifies the sampling factors to be used by the JPEG encoder
				6312	for chroma downsampling. If this option is omitted, the JPEG library will use
				6313	its own default values. When reading or writing the YUV format and when
				6314	writing the M2V (MPEG-2) format, use <a
				6315	href="command-line-options.html#sampling-factor">-sampling-factor 2x1</a> or <a
				6316	href="command-line-options.html#sampling-factor">-sampling-factor 4:2:2</a> to specify the 4:2:2
				6317	downsampling method.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6318
				6319	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6320	<h4><a id="scale"></a>-scale <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6321	</div>
				6322
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6323	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>minify / magnify the image with pixel block averaging and pixel replication, respectively.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6324
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6325	<p>Change the image size simply by replacing pixels by averaging pixels
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6326	together when minifying, or replacing pixels when magnifying. </p>
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6327
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6328	<p>The results are thus equivalent to using <a href="command-line-options.html#resize">-resize</a> with
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6329	a <a href="command-line-options.html#filter">-filter</a> setting of <code>box</code>. Though it is a lot
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6330	faster, as it avoids all the filter processing of the image. As such it
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6331	completely ignores the current <a href="command-line-options.html#filter">-filter</a> setting. </p>
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6332
				6333	<p>If when shrinking (minifying) images the original image is some integer
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6334	multiple of the new image size, the number of pixels averaged together to
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6335	produce the new pixel color is the same across the whole image. This is
				6336	a special case known as 'binning' and is often used as a method of reducing
				6337	noise in image such as those generated by digital cameras, especially in low
				6338	light conditions. </p>
				6339
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6340
				6341	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6342	<h4><a id="scene"></a>-scene <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6343	</div>
				6344
				6345	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>set scene number.</td><td style='text-align:right;'></td></tr></table>
				6346
				6347	<p>This option sets the scene number of an image or the first image in an image sequence.</p>
				6348
				6349	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6350	<h4><a id="screen"></a>-screen</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6351	</div>
				6352
				6353	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>specify the screen to capture.</td><td style='text-align:right;'></td></tr></table>
				6354
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6355	<p>This option indicates that the GetImage request used to obtain the image
				6356	should be done on the root window, rather than directly on the specified
				6357	window. In this way, you can obtain pieces of other windows that overlap the
				6358	specified window, and more importantly, you can capture menus or other popups
				6359	that are independent windows but appear over the specified window.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6360
				6361	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6362	<h4><a id="seed"></a>-seed</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6363	</div>
				6364
				6365	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>seed a new sequence of pseudo-random numbers</td><td style='text-align:right;'></td></tr></table>
				6366
				6367	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6368	<h4><a id="segment"></a>-segment <em class="arg">cluster-threshold</em>x<em class="arg">smoothing-threshold</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6369	</div>
				6370
				6371	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>segment the colors of an image.</td><td style='text-align:right;'></td></tr></table>
				6372
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6373	<p>Segment an image by analyzing the histograms of the color components and
				6374	identifying units that are homogeneous with the fuzzy c-means technique. This
				6375	is part of the ImageMagick color quantization routines. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6376
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6377	<p>Specify <em class="arg">cluster threshold</em> as the number of pixels in
				6378	each cluster that must exceed the cluster threshold to be considered valid.
				6379	<em class="arg">Smoothing threshold</em> eliminates noise in the second
				6380	derivative of the histogram. As the value is increased, you can expect
				6381	a smoother second derivative. The default is 1.5.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6382
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6383	<p>If the <a href="command-line-options.html#verbose">-verbose</a> setting is defined, a detailed report
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6384	of the color clusters is returned.</p>
				6385
				6386
				6387	<div style="margin: auto;">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6388	<h4><a id="selective-blur"></a>-selective-blur <em class="arg">radius</em><br />-selective-blur <em class="arg">radius</em>x<em class="arg">sigma</em>{<em class="arg">+threshold</em>}</h4>
cristy	2e2662a	2010-10-09 14:29:37 +0000	[diff] [blame]	6389	</div>
				6390
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6391	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Selectively blur pixels within a contrast threshold.</td><td style='text-align:right;'></td></tr></table>
				6392
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6393	<p>Blurs those pixels that are less than or equal to the threshold in
				6394	contrast. The threshold may be expressed as a fraction of <em
				6395	class="QR">QuantumRange</em> or as a percentage.</p>
cristy	2e2662a	2010-10-09 14:29:37 +0000	[diff] [blame]	6396
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6397	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6398	<h4><a id="separate"></a>-separate</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6399	</div>
				6400
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6401	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>separate an image channel into a grayscale image. Specify the channel with <a href="command-line-options.html#channel">-channel</a>.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6402
				6403	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6404	<h4><a id="sepia-tone"></a>-sepia-tone <em class="arg">threshold</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6405	</div>
				6406
				6407	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>simulate a sepia-toned photo.</td><td style='text-align:right;'></td></tr></table>
				6408
				6409	<p>Specify <em class="arg">threshold</em> as the percent threshold of the intensity (0 - 99.9%).</p>
				6410
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6411	<p>This option applies a special effect to the image, similar to the effect
				6412	achieved in a photo darkroom by sepia toning. Threshold ranges from 0 to <em
				6413	class="QR">QuantumRange</em> and is a measure of the extent of the sepia
				6414	toning. A threshold of 80% is a good starting point for a reasonable
				6415	tone.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6416
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	6417
				6418
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6419	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6420	<h4><a id="set"></a>-set <em class="arg">key value</em></h4>
				6421	<h4>+set <em class="arg">key</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6422	</div>
				6423
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6424	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>sets image attributes and properties for images in the current
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	6425	image sequence.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6426
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6427	<p>This will assign (or modify) specific settings attached to all the images
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6428	in the current image sequence. Using the <a href="command-line-options.html#set">+set</a> form of the
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6429	option will either remove, or reset that setting to a default state, as
				6430	appropriate. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6431
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6432	<p>For example, it will modify specific well known image meta-data
				6433	'attributes' such as those normally overridden by: the options <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6434	href="command-line-options.html#delay" >-delay</a>, <a href="command-line-options.html#dispose" >-dispose</a>, and <a
				6435	href="command-line-options.html#page" >-page</a>, <a href="command-line-options.html#colorspace" >-colorspace</a>; generally
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6436	assigned before the image is read in, by using a <em class="arg">key</em> of
				6437	the same name. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6438
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6439	<p>If the given <em class="arg">key</em> does not match a specific known
				6440	'attribute ', such as shown above, the setting is stored as a a free form
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6441	'property' string. Such settings are listed in <a href="command-line-options.html#verbose"
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6442	>-verbose</a> information ("<code>info:</code>" output format) as "Properties".
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	6443	</p>
				6444
cristy	8413418	2011-06-15 22:59:00 +0000	[diff] [blame]	6445	<p>This includes string 'properties' that are set by and assigned to images
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6446	using the options <a href="command-line-options.html#comment" >-comment</a>, <a href="command-line-options.html#label"
				6447	>-label</a>, <a href="command-line-options.html#caption" >-caption</a>. These options actually assign
				6448	a global 'artifact' which are automatically assigned (and any <a href="escape.html" >Format Percent
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6449	Escapes</a> expanded) to images as they are read in. For example:</p>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	6450
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6451	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert rose: -set comment 'Rose is a rose is a rose is a rose' rose.png</span><span class='crtout'>identify -format %c rose.png</span><span class="crtprompt"> $ </span><span class='crtin'>Rose is a rose is a rose is a rose</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6452	<p>The set value can also make use of <a href="escape.html" >Format and Print Image
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6453	Properties</a> in the defined value. For example:</p>
				6454
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6455	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert rose: -set origsize '%wx%h' -resize 50% \</span><span class='crtout'> -format 'Old size = %[origsize] New size = %wx%h' info:</span><span class="crtprompt"> $ </span><span class='crtin'>Old size = 70x46 New size = 35x23</span></p>
cristy	8413418	2011-06-15 22:59:00 +0000	[diff] [blame]	6456	<p>Other well known 'properties' that are availible include:
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6457	'<code>date:create</code>' and '<code>date:modify</code>' and
				6458	'<code>signature</code>'. </p>
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6459
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6460	<p>The <a href="command-line-options.html#repage">-repage</a> operator will also allow you to modify
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6461	the '<code>page</code>' attribute of an image for images already in memory (also
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6462	see <a href="command-line-options.html#repage">-page</a>). However it is designed to provide a finer
				6463	control of the sub-parts of this 'attribute'. The <a href="command-line-options.html#set">-set page</a>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6464	option will only provide a direct, unmodified assignment of '<code>page</code>'
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6465	attribute. </p>
				6466
				6467	<p>This option can also associate a colorspace or profile with your image.
				6468	For example,</p>
				6469
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6470	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert image.psd -set profile ISOcoated_v2_eci.icc image-icc.psd</span></p>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	6471	<p>Some 'properties' must be defined in a specific way to be used. For
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6472	example only 'properties' prefixed with "<code>filename:</code>" can be used to
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	6473	modify the output filename of an image. For example</p>
				6474
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6475	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert rose: -set filename:mysize '%wx%h' 'rose_%[filename:mysize].png'</span></p>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6476	<p>If the setting value is prefixed with "<code>option:</code>" the setting will
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	6477	be saved as a global "Artifact" exactly as if it was set using the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6478	href="command-line-options.html#define" >-define</a> option. As such settings are global in scope, they
cristy	8413418	2011-06-15 22:59:00 +0000	[diff] [blame]	6479	can be used to pass 'attributes' and 'properties' of one specific image,
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6480	in a way that allows you to use them in a completely different image, even if
				6481	the original image has long since been modified or destroyed. For example: </p>
				6482
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6483	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert rose: -set option:rosesize '%wx%h' -delete 0 \</span><span class='crtout'> label:'%[rosesize]' label_size_of_rose.gif</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6484	<p>Note that <a href="escape.html" >Format Percent Escapes</a> will only match
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6485	a 'artifact' if the given <em class="arg">key</em> does not match an existing
cristy	323f35b	2011-03-24 23:05:13 +0000	[diff] [blame]	6486	'attribute' or 'property'. </p>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	6487
				6488	<p>You can set the attributes of the image registry by prefixing the value
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6489	with <code>registry:</code>.</p>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	6490
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6491	<p>The <a href="command-line-options.html#set">-set profile</a> option can also be used to inject
cristy	8413418	2011-06-15 22:59:00 +0000	[diff] [blame]	6492	previously-formatted ancillary chunks into the output PNG file, using
				6493	the commandline option as shown below or by setting the profile via a
				6494	programming interface:</p>
				6495
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6496	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert in.png -set profile PNG-chunk-x:<filename> out.png</span></p>
cristy	8413418	2011-06-15 22:59:00 +0000	[diff] [blame]	6497	<p>where <em>x</em> is a location flag and
				6498	<em class="arg">filename</em> is a file containing the chunk
				6499	name in the first 4 bytes, then a colon (":"), followed by the chunk data.
				6500	This encoder will compute the chunk length and CRC, so those must not
				6501	be included in the file.</p>
				6502
				6503	<p>"x" can be "b" (before PLTE), "m" (middle, i.e., between PLTE and IDAT),
				6504	or "e" (end, i.e., after IDAT). If you want to write multiple chunks
				6505	of the same type, then add a short unique string after the "x" to prevent
				6506	subsequent profiles from overwriting the preceding ones, e.g.,</p>
				6507
				6508
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6509	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert in.png -set profile PNG-chunk-b01:file01 / <br/>
cristy	8413418	2011-06-15 22:59:00 +0000	[diff] [blame]	6510	-profile PNG-chunk-b02:file02 out.png</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6511
				6512	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6513	<h4><a id="shade"></a>-shade <em class="arg">azimuth</em>x<em class="arg">elevation</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6514	</div>
				6515
				6516	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>shade the image using a distant light source.</td><td style='text-align:right;'></td></tr></table>
				6517
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6518	<p>Specify <em class="arg">azimuth</em> and <em class="arg">elevation</em> as
				6519	the position of the light source. Use <a href="command-line-options.html#shade">+shade</a> to return
				6520	the shading results as a grayscale image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6521
				6522	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6523	<h4><a id="shadow"></a>-shadow <em class="arg">percent-opacity</em>{x<em class="arg">sigma</em>}{<em class="arg">+-</em>}<em class="arg">x</em>{<em class="arg">+-</em>}<em class="arg">y</em>{<em class="arg">%</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6524	</div>
				6525
				6526	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>simulate an image shadow.</td><td style='text-align:right;'></td></tr></table>
				6527
				6528	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6529	<h4><a
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6530	id="shared-memory"></a>-shared-memory</h4>
				6531	</div>
				6532
				6533	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>use shared memory.</td><td style='text-align:right;'></td></tr></table>
				6534
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6535	<p>This option specifies whether the utility should attempt to use shared
				6536	memory for pixmaps. ImageMagick must be compiled with shared memory support,
				6537	and the display must support the <em class="arg">MIT-SHM</em> extension.
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6538	Otherwise, this option is ignored. The default is <code>True</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6539
				6540	<div style="margin: auto;">
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6541	<h4><a id="sharpen"></a>-sharpen <em class="arg">radius</em><br />-sharpen <em class="arg">radius</em>x<em class="arg">sigma</em>+<em class="arg">bias</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6542	</div>
				6543
				6544	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>sharpen the image.</td><td style='text-align:right;'></td></tr></table>
				6545
				6546	<p>Use a Gaussian operator of the given radius and standard deviation (sigma).</p>
				6547
				6548	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6549	<h4><a id="shave"></a>-shave <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6550	</div>
				6551
				6552	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Shave pixels from the image edges.</td><td style='text-align:right;'></td></tr></table>
				6553
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6554	<p>The <em class="arg">size</em> portion of the <em class="arg">geometry</em>
				6555	argument specifies the width of the region to be removed from both sides of
				6556	the image and the height of the regions to be removed from top and bottom.
				6557	Offsets are ignored.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6558
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6559	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6560
				6561	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6562	<h4><a id="shear"></a>-shear <em class="arg">Xdegrees</em>[x<em class="arg">Ydegrees</em>]</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6563	</div>
				6564
				6565	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Shear the image along the x-axis and/or y-axis.</td><td style='text-align:right;'></td></tr></table>
				6566
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6567	<p>The shear angles may be positive, negative, or zero. When <em
				6568	class="arg">Ydegrees</em> is omitted it defaults to 0. When both angles are
				6569	given, the horizontal component of the shear is performed before the vertical
				6570	component.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6571
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6572	<p>Shearing slides one edge of an image along the x-axis or y-axis (i.e.,
				6573	horizontally or vertically, respectively),creating a parallelogram. The amount
				6574	of each is controlled by the respective shear angle. For horizontal shears,
				6575	<em class="arg">Xdegrees</em> is measured clockwise relative to "up" (the
				6576	negative y-axis), sliding the top edge to the right when 0°<<em
				6577	class="arg">Xdegrees</em><90° and to the left when 90°<<em
				6578	class="arg">Xdegrees</em><180°. For vertical shears <em
				6579	class="arg">Ydegrees</em> is measured clockwise relative to "right" (the
				6580	positive x-axis), sliding the right edge down when 0°<<em
				6581	class="arg">Ydegrees</em><90° and up when 90°<<em
				6582	class="arg">Ydegrees</em><180°.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6583
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6584	<p>Empty triangles left over from shearing the image are filled with the color
				6585	defined by the <a href="command-line-options.html#fill">-background</a> option. The color is specified
				6586	using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6587
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6588	<p>The horizontal shear is performed before the vertical part. This is
				6589	important to note, since horizontal and vertical shears do not
				6590	<em>commute</em>, i.e., the order matters in a sequence of shears. For
				6591	example, the following two commands are not equivalent.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6592
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6593	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert logo: -shear 20x0 -shear 0x60 logo-sheared.png</span><span class='crtout'></span><span class="crtprompt"> $ </span><span class='crtin'>convert logo: -shear 0x60 -shear 20x0 logo-sheared.png</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6594	<p>The first of the two commands above is equivalent to the following, except
				6595	for the amount of empty space created; the command that follows generates
				6596	a smaller image, and so is a better choice in terms of time and space.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6597
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6598	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert logo: -shear 20x60 logo-sheared.png</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6599	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6600	<h4><a id="sigmoidal-contrast"></a>-sigmoidal-contrast <em class="arg">contrast</em>x<em class="arg">mid-point</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6601	</div>
				6602
				6603	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>increase the contrast without saturating highlights or shadows.</td><td style='text-align:right;'></td></tr></table>
				6604
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6605	<p>Increase the contrast of the image using a sigmoidal transfer function
				6606	without saturating highlights or shadows. <em class="arg">Contrast</em>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6607	indicates how much to increase the contrast. For example, near 1 is none, 3 is
				6608	typical and 20 is a lot. Note that exactly zero is mathematically invalid.
				6609	</p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6610
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6611	<p>The <em class="arg">mid-point</em> indicates where the maximum change
				6612	'slope' in contrast should fall in the resultant image (0 is white; 50% is
				6613	middle-gray; 100% is black). </p>
				6614
				6615	<p>By default the image contrast is increased, use <em
				6616	class="arg">+sigmoidal-contrast</em> to decrease the contrast.</p>
				6617
				6618	<p>To achieve the equivalent of a sigmoidal brightness change (similar to
				6619	a gamma adjustment), you would use <em class="arg">-sigmoidal-contrast
				6620	{brightness}x0%</em> to increase brightness and <em
				6621	class="arg">+sigmoidal-contrast {brightness}x0%</em> to decrease brightness.
				6622	Note the use of '0' fo rthe mid-point of the sigmoidal curve. </p>
				6623
				6624	<p>Using a very high <em class="arg">contrast</em> will produce a sort of
				6625	'smoothed thresholding' of the image. Not as sharp (with high aliasing
				6626	effects) of a true threshold, but with tapered gray-levels around the threshold
				6627	<em class="arg">mid-point</em>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6628
				6629	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6630	<h4><a id="silent"></a>-silent</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6631	</div>
				6632
				6633	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>operate silently.</td><td style='text-align:right;'></td></tr></table>
				6634
				6635	<div style="margin: auto;">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6636	<h4><a id="similarity-threshold"></a>-similarity-threshold <em class="arg">value</em></h4>
				6637	</div>
				6638
				6639	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>minimum RMSE for subimage match (default 0.0).</td><td style='text-align:right;'>[<a href="compare.html">compare</a>]</td></tr></table>
				6640
				6641	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6642	<h4><a id="size"></a>-size <em class="arg">width</em>[x<em class="arg">height</em>][<em class="arg">+offset</em>]</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6643	</div>
				6644
				6645	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>set the width and height of the image.</td><td style='text-align:right;'></td></tr></table>
				6646
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6647	<p>Use this option to specify the width and height of raw images whose
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6648	dimensions are unknown such as <code>GRAY</code>, <code>RGB</code>, or
				6649	<code>CMYK</code>. In addition to width and height, use <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6650	href="command-line-options.html#size">-size</a> with an offset to skip any header information in the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6651	image or tell the number of colors in a <code>MAP</code> image file, (e.g. -size
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6652	640x512+256).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6653
				6654	<p>For Photo CD images, choose from these sizes:</p>
				6655
				6656	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	6657	192x128
				6658	384x256
				6659	768x512
				6660	1536x1024
				6661	3072x2048
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6662	</pre>
				6663
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6664	<div style="margin: auto;">
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6665	<h4><a id="sketch"></a>-sketch <em class="arg">radius</em><br />-sketch <em class="arg">radius</em>x<em class="arg">sigma</em>+<em class="arg">angle</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6666	</div>
				6667
				6668	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>simulate a pencil sketch.</td><td style='text-align:right;'></td></tr></table>
				6669
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6670	<p>Sketch with the given radius, standard deviation (sigma), and angle. The
				6671	angle given is the angle toward which the image is sketched. That is the
				6672	direction people would consider the object is coming from. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6673
				6674	<div style="margin: auto;">
cristy	2d67ddd	2011-02-13 15:38:23 +0000	[diff] [blame]	6675	<h4><a id="smush"></a>-smush <em class="arg">offset</em></h4>
				6676	</div>
				6677
				6678	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>smush an image sequence together.</td><td style='text-align:right;'></td></tr></table>
				6679
				6680	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6681	<h4><a id="snaps"></a>-snaps <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6682	</div>
				6683
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6684	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the number of screen snapshots.</td><td style='text-align:right;'>[<a href="import.html">import</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6685
				6686	<p>Use this option to grab more than one image from the X server screen, to create an animation sequence.</p>
				6687
				6688	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6689	<h4><a id="solarize"></a>-solarize <em class="arg">threshold</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6690	</div>
				6691
				6692	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>negate all pixels above the threshold level.</td><td style='text-align:right;'></td></tr></table>
				6693
				6694	<p>Specify <em class="arg">factor</em> as the percent threshold of the intensity (0 - 99.9%).</p>
				6695
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6696	<p>This option produces a <em class="arg">solarization</em> effect seen when
				6697	exposing a photographic film to light during the development process.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6698
				6699	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6700	<h4><a id="sparse-color"></a>-sparse-color <em
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6701	class="arg">method</em> '<em class="arg">x</em>,<em class="arg">y</em> <em class="arg">color</em> ...'</h4>
				6702	</div>
				6703
				6704	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'> color the given image using the specified points of color, and filling the other intervening colors using the given methods. </td><td style='text-align:right;'></td></tr></table>
				6705
				6706
				6707	<table class="doc">
				6708	<tbody>
				6709	<tr valign="top">
				6710	<th align="left" style="width: 8%">Method</th>
				6711	<th align="left">Description</th>
				6712	</tr>
				6713
				6714	<tr valign="top">
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	6715	<td valign="top">barycentric</td>
				6716	<td valign="top">three point triangle of color given 3 points.
				6717	Giving only 2 points will form a linear gradient between those points.
				6718	The gradient generated extends beyond the triangle created by those
				6719	3 points. </td>
				6720	</tr>
				6721
				6722	<tr valign="top">
				6723	<td valign="top">bilinear</td>
				6724	<td valign="top">Like barycentric but for 4 points. Less than 4 points
				6725	fall back to barycentric. </td>
				6726	</tr>
				6727	<tr valign="top">
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6728	<td valign="top">voronoi</td>
				6729	<td valign="top">Simply map each pixel to the to nearest color point
				6730	given. The result are polygonal 'cells' of solid color. </td>
				6731	</tr>
				6732
				6733	<tr valign="top">
				6734	<td valign="top">shepards</td>
cristy	d0bda5e	2010-09-21 16:22:45 +0000	[diff] [blame]	6735	<td valign="top">Colors points biased on the ratio of inverse distance
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6736	squared. Generating spots of color in a sea of the average of
				6737	colors. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6738	</tr>
				6739
				6740	<tr valign="top">
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	6741	<td valign="top">inverse</td>
				6742	<td valign="top">Colors points biased on the ratio of inverse distance.
				6743	This generates sharper points of color rather than rounded spots of
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6744	'<code>shepards</code>' Generating spots of color in a sea of the
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	6745	average of colors. </td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6746	</tr>
				6747
				6748	</tbody>
				6749	</table>
				6750
				6751	<p>The points are placed according to the images location on the virtual
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6752	canvas (<a href="command-line-options.html#page" >-page</a> or <a href="command-line-options.html#repage" >-repage</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6753	offset), and do not actually have to exist on the given image, but may be
				6754	some point beyond the edge of the image. All points are floating point values.
				6755	</p>
				6756
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6757	<p>Only the color channels defined by the <a href="command-line-options.html#channel" >-channel</a> are
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	6758	modified, which means that by default matte/alpha transparency channel is not
				6759	effected. Typically transparency channel is turned off either before or after
				6760	the operation. </P>
				6761
				6762	Of course if some color points are transparent to generate a transparent
				6763	gradient, then the image also requires transparency enabled to store the
				6764	values. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6765
				6766	<p>All the above methods when given a single point of color will replace all
				6767	the colors in the image with the color given, regardless of the point. This is
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6768	logical, and provides an alternative technique to recolor an image to some
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6769	default value. </p>
				6770
				6771
				6772	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6773	<h4><a id="splice"></a>-splice <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6774	</div>
				6775
				6776	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Splice the current background color into the image.</td><td style='text-align:right;'></td></tr></table>
				6777
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	6778	<p>This will add rows and columns of the current <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6779	href="command-line-options.html#background">-background</a> color into the given image according to the
				6780	given <a href="command-line-options.html#gravity">-gravity</a> geometry setting. >See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument. Essentially <a href="command-line-options.html#splice">-splice</a> will divide the
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	6781	image into four quadrants, separating them by the inserted rows and columns.
				6782	</P>
				6783
				6784	If a dimension of geometry is zero no rows or columns will be added for that
				6785	dimension. Similarly using a zero offset with the appropriate <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6786	href="command-line-options.html#gravity">-gravity</a> setting will add rows and columns to the edges of
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	6787	the image, padding the image only along that one edge. Edge padding is what <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6788	href="command-line-options.html#splice">-splice</a> is most commonly used for. </p>
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	6789
				6790	<p>If the exact same <em class="arg">geometry</em> and <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6791	href="command-line-options.html#gravity">-gravity</a> is later used with <a href="command-line-options.html#chop">-chop</a> the
cristy	acc0488	2011-05-04 23:03:43 +0000	[diff] [blame]	6792	added added all splices removed. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6793
				6794	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6795	<h4><a id="spread"></a>-spread <em class="arg">amount</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6796	</div>
				6797
				6798	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>displace image pixels by a random amount.</td><td style='text-align:right;'></td></tr></table>
				6799
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6800	<p>The argument <em class="arg">amount</em> defines the size of the
				6801	neighborhood around each pixel from which to choose a candidate pixel to
				6802	swap.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6803
				6804	<div style="margin: auto;">
cristy	323f35b	2011-03-24 23:05:13 +0000	[diff] [blame]	6805	<h4><a id="statistic"></a>-statistic <em class="arg">type</em> <em class="arg">geometry</em></h4>
cristy	b52981c	2011-03-19 17:09:31 +0000	[diff] [blame]	6806	</div>
				6807
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6808	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>replace each pixel with corresponding statistic from the neighborhood.</td><td style='text-align:right;'>[<a href="convert.html">convert</a>, <a href="mogrify.html">mogrify</a>]</td></tr></table>
cristy	b52981c	2011-03-19 17:09:31 +0000	[diff] [blame]	6809
				6810	<p>Choose from these statistic types:</p>
				6811	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	6812	Gradient maximum difference in area
				6813	Maximum maximum value per channel in neighborhood
				6814	Minimum minimum value per channel in neighborhood
				6815	Mean average value per channel in neighborhood
				6816	Median median value per channel in neighborhood
				6817	Mode mode (most frequent) value per channel in neighborhood
				6818	Nonpeak value just before or after the median value per channel in neighborhood
cristy	b52981c	2011-03-19 17:09:31 +0000	[diff] [blame]	6819	</pre>
				6820
				6821	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6822	<h4><a id="stegano"></a>-stegano <em class="arg">offset</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6823	</div>
				6824
				6825	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>hide watermark within an image.</td><td style='text-align:right;'></td></tr></table>
				6826
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6827	<p>Use an offset to start the image hiding some number of pixels from the
				6828	beginning of the image. Note this offset and the image size. You will need
				6829	this information to recover the steganographic image (e.g. display -size
				6830	320x256+35 stegano:image.png).</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6831
				6832	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6833	<h4><a id="stereo"></a>-stereo <em class="arg">+x</em>{<em class="arg">+y</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6834	</div>
				6835
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6836	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>composite two images to create a red / cyan stereo anaglyph.</td><td style='text-align:right;'>[<a href="composite.html">composite</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6837
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6838	<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>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6839
				6840	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6841	<h4><a id="storage-type"></a>-storage-type <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6842	</div>
				6843
				6844	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>pixel storage type. Here are the valid types:</td><td style='text-align:right;'></td></tr></table>
				6845
				6846	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	6847	char unsigned characters
				6848	double doubles
				6849	float floats
				6850	integer integers
				6851	long longs
				6852	quantum pixels in the native depth of your ImageMagick distribution
				6853	short unsigned shorts
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6854	</pre>
				6855
				6856	<p>Float and double types are normalized from 0.0 to 1.0 otherwise the pixels
				6857	values range from 0 to the maximum value the storage type can support.</p>
				6858
				6859	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6860	<h4><a id="stretch"></a>-stretch <em class="arg">fontStretch</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6861	</div>
				6862
				6863	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set a type of stretch style for fonts.</td><td style='text-align:right;'></td></tr></table>
				6864
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6865	<p>This setting suggests a type of stretch that ImageMagick should try to
				6866	apply to the currently selected font family. Select <em
				6867	class="arg">fontStretch</em> from the following.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6868
				6869	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	6870	Any
				6871	Condensed
				6872	Expanded
				6873	ExtraCondensed
				6874	ExtraExpanded
				6875	Normal
				6876	SemiCondensed
				6877	SemiExpanded
				6878	UltraCondensed
				6879	UltraExpanded
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6880	</pre>
				6881
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6882	<p>To print a complete list of stretch types, use <a href="command-line-options.html#list">-list
				6883	stretch</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6884
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6885	<p>For other settings that affect fonts, see the options <a
				6886	href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a
				6887	href="command-line-options.html#style">-style</a>, and <a href="command-line-options.html#weight">-weight</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6888
				6889	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6890	<h4><a id="strip"></a>-strip</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6891	</div>
				6892
				6893	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>strip the image of any profiles or comments.</td><td style='text-align:right;'></td></tr></table>
				6894
				6895	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6896	<h4><a id="stroke"></a>-stroke <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6897	</div>
				6898
				6899	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>color to use when stroking a graphic primitive.</td><td style='text-align:right;'></td></tr></table>
				6900
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6901	<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6902
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6903	<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6904
				6905	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6906	<h4><a id="strokewidth"></a>-strokewidth <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6907	</div>
				6908
				6909	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>set the stroke width.</td><td style='text-align:right;'></td></tr></table>
				6910
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6911	<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6912
				6913	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6914	<h4><a id="style"></a>-style <em class="arg">fontStyle</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6915	</div>
				6916
				6917	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set a font style for text.</td><td style='text-align:right;'></td></tr></table>
				6918
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	6919	<p>This setting suggests a font style that ImageMagick should try to apply to
				6920	the currently selected font family. Select <em class="arg">fontStyle</em> from
				6921	the following.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6922
				6923	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	6924	Any
				6925	Italic
				6926	Normal
				6927	Oblique
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6928	</pre>
				6929
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6930	<p>For other settings that affect fonts, see the options <a
				6931	href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a
				6932	href="command-line-options.html#stretch">-stretch</a>, and <a href="command-line-options.html#weight">-weight</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6933
				6934	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6935	<h4><a id="subimage-search"></a>-subimage-search</h4>
cristy	ae6203d	2010-08-09 01:12:14 +0000	[diff] [blame]	6936	</div>
				6937
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6938	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>search for subimage.</td><td style='text-align:right;'>[<a href="compare.html">compare</a>]</td></tr></table>
cristy	d4d64ed	2010-08-22 22:19:33 +0000	[diff] [blame]	6939
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	6940	<p>This option is required to have compare search for the best match location
				6941	of a small image within a larger image. This search will produce two images
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6942	(or two frames). The first is the "difference" image and the second will
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	6943	be the "match score" image.</p>
				6944
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6945	<p>The "match-score" image is smaller containing a pixel for ever possible
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	6946	position of the top-left corner of the given sub-image. that is its size will
				6947	be the size of the larger_image - sub_image + 1. The brightest location in
				6948	this image is the location s the locate on the best match that is also
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6949	reported. Note that this may or may not be a perfect match, and the actual
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	6950	brightness will reflect this. Other bright 'peaks' can be used to locate other
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6951	possible matching locations. </p>
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	6952
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	6953	<p>Note that the search will try to compare the sub-image at every possible
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	6954	location in the larger image, as such it can be very slow. The smaller the
cristy	d0bd44a	2010-09-24 12:38:11 +0000	[diff] [blame]	6955	sub-image the faster this search is. </p>
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	6956
cristy	ae6203d	2010-08-09 01:12:14 +0000	[diff] [blame]	6957
				6958	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6959	<h4><a id="swap"></a>-swap <em class="arg">index,index</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6960	</div>
				6961
				6962	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Swap the positions of two images in the image sequence.</td><td style='text-align:right;'></td></tr></table>
				6963
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6964	<p>For example, <a href="command-line-options.html#swap">-swap 0,2</a> swaps the first and the third
				6965	images in the current image sequence. Use <a href="command-line-options.html#swap">+swap</a> to switch
cristy	71a3f60	2010-09-15 12:38:16 +0000	[diff] [blame]	6966	the last two images in the sequence.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6967
				6968	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6969	<h4><a id="swirl"></a>-swirl <em class="arg">degrees</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6970	</div>
				6971
				6972	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>swirl image pixels about the center.</td><td style='text-align:right;'></td></tr></table>
				6973
				6974	<p><em class="arg">Degrees</em> defines the tightness of the swirl.</p>
				6975
				6976	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6977	<h4><a id="synchronize"></a>-synchronize</h4>
cristy	5063d81	2010-10-19 16:28:10 +0000	[diff] [blame]	6978	</div>
				6979
				6980	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>synchronize image to storage device.</td><td style='text-align:right;'></td></tr></table>
				6981
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	6982	<p>Set to "true" to ensure all image data is fully flushed and synchronized to disk. There is a performance penalty, but the benefit include ensuring a valid image file in the event of a system crash and early reporting if there is not anout disk space for the image pixel cache.</p>
				6983
cristy	5063d81	2010-10-19 16:28:10 +0000	[diff] [blame]	6984	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6985	<h4><a id="taint"></a>-taint</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6986	</div>
				6987
cristy	5063d81	2010-10-19 16:28:10 +0000	[diff] [blame]	6988	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Mark the image as modified.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6989
				6990	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	6991	<h4><a id="text-font"></a>-text-font <em class="arg">name</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6992	</div>
				6993
				6994	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>font for writing fixed-width text.</td><td style='text-align:right;'></td></tr></table>
				6995
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6996	<p>Specifies the name of the preferred font to use in fixed (typewriter style)
				6997	formatted text. The default is 14 point <em class="arg">Courier</em>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	6998
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	6999	<p>You can tag a font to specify whether it is a PostScript, TrueType, or
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7000	OPTION1 font. For example, <code>Courier.ttf</code> is a TrueType font and
				7001	<code>x:fixed</code> is OPTION1.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7002
				7003	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7004	<h4><a id="texture"></a>-texture <em class="arg">filename</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7005	</div>
				7006
				7007	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>name of texture to tile onto the image background.</td><td style='text-align:right;'></td></tr></table>
				7008
				7009	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7010	<h4><a id="threshold"></a>-threshold <em class="arg">value</em>{<em class="arg">%</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7011	</div>
				7012
				7013	<!-- {<em class="arg">green,blue,opacity</em>}
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7014	<p>If the green or blue value is omitted, these channels use the same value as
				7015	the first one provided. If all three color values are the same, the result is
				7016	a bi-level image. If the opacity threshold is omitted, OpaqueOpacity is used
				7017	and any partially transparent pixel becomes fully transparent.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7018	-->
				7019
				7020	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Apply simultaneous black/white threshold to the image.</td><td style='text-align:right;'></td></tr></table>
				7021
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7022	<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
				7023	maximum channel value, while all other values are assigned the minimum.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7024
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7025	<p> The threshold value can be given as a percentage or as an absolute integer
				7026	value corresponding to the desired channel value. When given as an integer,
				7027	the minimum attainable value is 0 (corresponding to black when all channels
				7028	are affected), but the maximum value (corresponding to white) is that of the
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7029	<code>quantum depth</code> of the particular build of ImageMagick, and is
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7030	therefore dependent on the installation. For that reason, a reasonable
				7031	recommendation for most applications is to specify the threshold values as
				7032	a percentage. </p>
				7033
				7034	<p> The following would force pixels with red values above 50% to have 100%
				7035	red values, while those at or below 50% red would be set to 0 in the red
				7036	channel. The green, blue, and alpha channels (if present) would be unchanged.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7037	</p>
				7038
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	7039	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert in.png -channel red -threshold 50% out.png</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7040	<p>As (possibly) impractical but instructive examples, the following would
				7041	generate an all-black and an all-white image with the same dimensions as the
				7042	input image.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7043
				7044
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	7045	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert in.png -threshold 100% black.png</span><span class='crtout'></span><span class="crtprompt"> $ </span><span class='crtin'>convert in.png -threshold -1 white.png</span></p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7046	<p>Note that the values of the transparency channel is treated as 'matte'
				7047	values (0 is opaque) and not as 'alpha' values (0 is transparent).</p>
				7048
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7049	<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>.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7050	</p>
				7051
				7052	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7053	<h4><a id="thumbnail"></a>-thumbnail <em class="arg">geometry</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7054	</div>
				7055
				7056	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Create a thumbnail of the image.</td><td style='text-align:right;'></td></tr></table>
				7057
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7058	<p>This is similar to <a href="command-line-options.html#resize">-resize</a>, except it is optimized
				7059	for speed and any image profile, other than a color profile, is removed to
				7060	reduce the thumbnail size. To strip the color profiles as well, add <a
				7061	href="command-line-options.html#strip">-strip</a> just before of after this option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7062
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7063	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7064
				7065	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7066	<h4><a id="tile"></a>-tile <em class="arg">filename</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7067	</div>
				7068
				7069	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the tile image used for filling a subsequent graphic primitive.</td><td style='text-align:right;'></td></tr></table>
				7070
				7071	<div style="margin: auto;">
				7072	<h4>-tile <em class="arg">geometry</em></h4>
				7073	</div>
				7074
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7075	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specify the layout of images .</td><td style='text-align:right;'>[<a href="montage.html">montage</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7076
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7077	<p>See <a href="command-line-processing.html#geometry">Image Geometry</a> for complete details about the <em class="arg">geometry</em> argument.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7078
				7079	<div style="margin: auto;">
				7080	<h4>-tile</h4>
				7081	</div>
				7082
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7083	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specifies that a subsequent composite operation is repeated across and down image.</td><td style='text-align:right;'>[<a href="composite.html">composite</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7084
				7085	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7086	<h4><a id="tile-offset"></a>-tile-offset {<em class="arg">+-</em>}<em class="arg">x</em>{<em class="arg">+-</em>}<em class="arg">y</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7087	</div>
				7088
				7089	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specify the offset for tile images, relative to the background image it is tiled on.</td><td style='text-align:right;'></td></tr></table>
				7090
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7091	<p>This should be set before the tiling image is set by <a href="command-line-options.html#tile"
				7092	>-tile</a> or <a href="command-line-options.html#texture" >-texture</a>, or directly applied for
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7093	creating a tiled canvas using <code>TILE:</code> or <code>PATTERN:</code> input
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7094	formats. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7095
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7096	<p>Internally ImageMagick does a <a href="command-line-options.html#roll" >-roll</a> of the tile image
				7097	by the arguments given when the tile image is set. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7098
				7099	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7100	<h4><a id="tint"></a>-tint <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7101	</div>
				7102
				7103	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Tint the image with the fill color.</td><td style='text-align:right;'></td></tr></table>
				7104
				7105	<p>Tint the image with the fill color.</p>
				7106
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7107	<p>Specify the amount of tinting as a percentage. Pure colors like black,
				7108	white red, yellow, will not be affected by -tint. Only mid-range colors such
				7109	as the various shades of grey.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7110
				7111	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7112	<h4><a id="title"></a>-title <em class="arg">string</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7113	</div>
				7114
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7115	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Assign a title to displayed image.</td><td style='text-align:right;'>[<a href="animate.html">animate</a>, <a href="display.html">display</a>, <a href="montage.html">montage</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7116
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7117	<p>Use this option to assign a specific title to the image. This assigned to
				7118	the image window and is typically displayed in the window title bar.
				7119	Optionally you can include the image filename, type, width, height, Exif data,
				7120	or other image attribute by embedding special format characters described
				7121	under the <a href="command-line-options.html#format">-format</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7122
				7123	<p>For example,</p>
				7124
				7125	<p class="crtsnip">
				7126	-title "%m:%f %wx%h"
				7127	</p>
				7128
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7129	<p>produces an image title of <code>MIFF:bird.miff 512x480</code> for an image
				7130	titled <code>bird.miff</code> and whose width is 512 and height is 480.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7131
				7132
				7133	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7134	<h4><a id="transform"></a>-transform</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7135	</div>
				7136
				7137	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>transform the image.</td><td style='text-align:right;'></td></tr></table>
				7138
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7139	<p>This option applies the transformation matrix from a previous <a href="command-line-options.html#affine">-affine</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7140
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	7141	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert -affine 2,2,-2,2,0,0 -transform bird.ppm bird.jpg</span></p>
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	7142
				7143	<p>This operator has been now been superseded by the <a
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7144	href="command-line-options.html#distort">-distort</a> '<code>AffineProjection</code>' method. </p>
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	7145
				7146
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7147	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7148	<h4><a id="transparent"></a>-transparent <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7149	</div>
				7150
				7151	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Make this color transparent within the image.</td><td style='text-align:right;'></td></tr></table>
				7152
				7153	<p>The <em class="arg">color</em> argument is defined using the format
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7154	described under the <a href="command-line-options.html#fill">-fill</a> option. The <a href="command-line-options.html#fuzz"
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7155	>-fuzz</a> setting can be used to match and replace colors similar to the one
				7156	given. </p>
				7157
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7158	<p>Use <a href="command-line-options.html#transparent" >+transparent</a> to invert the pixels matched.
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	7159	that is make all non-matching colors transparent. </p>
				7160
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7161	<p>The <a href="command-line-options.html#opaque">-opaque</a> operator is exactly the same as <a
				7162	href="command-line-options.html#transparent" >-transparent</a> but replaces the matching color with the
				7163	current <a href="command-line-options.html#fill">-fill</a> color setting, rather than transparent.
				7164	However the <a href="command-line-options.html#transparent" >-transparent</a> operator also ensures
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7165	that the image has an alpha channel enabled, as per "<code><a href="command-line-options.html#alpha"
				7166	>-alpha</a> set</code>", and does not require you to modify the <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7167	href="command-line-options.html#channel">-channel</a> to enable alpha channel handling. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7168
cristy	b36feb2	2010-03-26 16:54:37 +0000	[diff] [blame]	7169	<p>Note that this does not define the color as being the 'transparency color'
				7170	used for color-mapped image formats, such as GIF. For that use <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7171	href="command-line-options.html#transparent-color" >-transparent-color</a> </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7172
				7173
				7174	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7175	<h4><a id="transparent-color"></a>-transparent-color <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7176	</div>
				7177
				7178	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set the transparent color.</td><td style='text-align:right;'></td></tr></table>
				7179
				7180	<p>Sometimes this is used for saving to image formats such as
				7181	GIF and PNG8 which uses this color to represent boolean transparency. This
				7182	does not make a color transparent, it only defines what color the transparent
				7183	color is in the color palette of the saved image. Use <a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7184	href="command-line-options.html#transparent">-transparent</a> to make an opaque color transparent.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7185
				7186	<p>This option allows you to have both an opaque visible color, as well as a
				7187	transparent color of the same color value without conflict. That is, you can
				7188	use the same color for both the transparent and opaque color areas within an
				7189	image. This, in turn, frees to you to select a transparent color that is
				7190	appropriate when an image is displayed by an application that does not handle a
				7191	transparent color index, while allowing ImageMagick to correctly handle images of this
				7192	type. </p>
				7193
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7194	<p>The default transparent color is <code>#00000000</code>, which is fully transparent black.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7195
				7196	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7197	<h4><a id="transpose"></a>-transpose</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7198	</div>
				7199
				7200	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Mirror the image along the top-left to bottom-right diagonal.</td><td style='text-align:right;'></td></tr></table>
				7201
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7202	<p> This option mathematically transposes the pixel array. It is equivalent to the sequence <code>-flip -rotate 90</code>.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7203	</p>
				7204
				7205	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7206	<h4><a id="transverse"></a>-transverse</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7207	</div>
				7208
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7209	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Mirror the image along the images bottom-left top-right diagonal. Equivalent to the operations <code>-flop -rotate 90</code>.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7210
				7211
				7212	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7213	<h4><a id="treedepth"></a>-treedepth <em class="arg">value</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7214	</div>
				7215
				7216	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>tree depth for the color reduction algorithm.</td><td style='text-align:right;'></td></tr></table>
				7217
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7218	<p>Normally, this integer value is zero or one. A value of zero or one causes
				7219	the use of an optimal tree depth for the color reduction algorithm.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7220
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7221	<p>An optimal depth generally allows the best representation of the source
				7222	image with the fastest computational speed and the least amount of memory.
				7223	However, the default depth is inappropriate for some images. To assure the
				7224	best representation, try values between 2 and 8 for this parameter. Refer to
				7225	the <a href="quantize.html"
				7226	>color reduction algorithm</a> for more details.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7227
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7228	<p>The <a href="command-line-options.html#colors">-colors</a> or <a href="command-line-options.html#monochrome">-monochrome</a>
				7229	option, or writing to an image format which requires color reduction, is
				7230	required for this option to take effect.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7231
				7232	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7233	<h4><a id="trim"></a>-trim</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7234	</div>
				7235
				7236	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>trim an image.</td><td style='text-align:right;'></td></tr></table>
				7237
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7238	<p>This option removes any edges that are exactly the same color as the corner
				7239	pixels. Use <a href="command-line-options.html#fuzz">-fuzz</a> to make <a href="command-line-options.html#trim">-trim</a> remove
				7240	edges that are nearly the same color as the corner pixels.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7241
				7242	<p>The page or virtual canvas information of the image is preserved allowing
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7243	you to extract the result of the <a href="command-line-options.html#trim">-trim</a> operation from the
				7244	image. Use a <a href="command-line-options.html#repage">+repage</a> to remove the virtual canvas page
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7245	information if it is unwanted.</p>
				7246
				7247	<p>If the trimmed image 'disappears' an warning is produced, and a special
				7248	single pixel transparent 'missed' image is returned, in the same way as when a
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7249	<a href="command-line-options.html#crop">-crop</a> operation 'misses' the image proper. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7250
				7251
				7252	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7253	<h4><a id="type"></a>-type <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7254	</div>
				7255
				7256	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>the image type.</td><td style='text-align:right;'></td></tr></table>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7257	<p>Choose from: <code>Bilevel</code>,
				7258	<code>Grayscale</code>, <code>GrayscaleMatte</code>, <code>Palette</code>,
				7259	<code>PaletteMatte</code>, <code>TrueColor</code>, <code>TrueColorMatte</code>,
				7260	<code>ColorSeparation</code>, or <code>ColorSeparationMatte</code>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7261
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7262	<p>Normally, when a format supports different subformats such as grayscale and
				7263	truecolor, the encoder will try to choose an efficient subformat. The <a
				7264	href="command-line-options.html#type">-type</a> option can be used to override this behavior. For
				7265	example, to prevent a JPEG from being written in grayscale format even though
				7266	only gray pixels are present, use.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7267
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	7268	<p class='crt'><span class="crtprompt"> $ </span><span class='crtin'>convert bird.png -type TrueColor bird.jpg</span></p>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7269	<p>Similarly, use <a href="command-line-options.html#type">-type TrueColorMatte</a> to force the
				7270	encoder to write an alpha channel even though the image is opaque, if the
				7271	output format supports transparency.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7272
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7273	<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>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7274
				7275	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7276	<h4><a id="undercolor"></a>-undercolor <em class="arg">color</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7277	</div>
				7278
				7279	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>set the color of the annotation bounding box.</td><td style='text-align:right;'></td></tr></table>
				7280
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7281	<p>The color is specified using the format described under the <a href="command-line-options.html#fill">-fill</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7282
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7283	<p>See <a href="command-line-options.html#draw">-draw</a> for further details.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7284
				7285
				7286	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7287	<h4><a id="update"></a>-update <em class="arg">seconds</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7288	</div>
				7289
				7290	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>detect when image file is modified and redisplay.</td><td style='text-align:right;'></td></tr></table>
				7291
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7292	<p>Suppose that while you are displaying an image the file that is currently
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7293	displayed is over-written. <code>display</code> will automagically detect that
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7294	the input file has been changed and update the displayed image
				7295	accordingly.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7296
				7297
				7298	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7299	<h4><a id="unique-colors"></a>-unique-colors</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7300	</div>
				7301
				7302	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>discard all but one of any pixel color.</td><td style='text-align:right;'></td></tr></table>
				7303
				7304
				7305	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7306	<h4><a id="units"></a>-units <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7307	</div>
				7308
				7309	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>the units of image resolution.</td><td style='text-align:right;'></td></tr></table>
				7310
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7311	<p>Choose from: <code>Undefined</code>, <code>PixelsPerInch</code>, or
				7312	<code>PixelsPerCentimeter</code>. This option is normally used in conjunction
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7313	with the <a href="command-line-options.html#density">-density</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7314
				7315
				7316	<div style="margin: auto;">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7317	<h4><a id="unsharp"></a>-unsharp <em class="arg">radius</em><br />-unsharp <em class="arg">radius</em>x<em class="arg">sigma</em>{<em class="arg">+gain</em>}{<em class="arg">+threshold</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7318	</div>
				7319
				7320	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>sharpen the image with an unsharp mask operator.</td><td style='text-align:right;'></td></tr></table>
				7321
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7322	<p>The <a href="command-line-options.html#unsharp">-unsharp</a> option sharpens an image. The image is
				7323	convolved with a Gaussian operator of the given radius and standard deviation
				7324	(sigma). For reasonable results, radius should be larger than sigma. Use
				7325	a radius of 0 to have the method select a suitable radius.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7326
				7327	<p>The parameters are:</p>
				7328
				7329	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	7330	radius The radius of the Gaussian, in pixels, not counting the center
				7331	pixel (default 0).
				7332	sigma The standard deviation of the Gaussian, in pixels (default 1.0).
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7333	gain The fraction of the difference between the original and the blur
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	7334	image that is added back into the original (default 1.0).
				7335	threshold The threshold, as a fraction of <em class="QR">QuantumRange</em>, needed to apply the
				7336	difference amount (default 0.05).
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7337	</pre>
				7338
				7339
				7340	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7341	<h4><a id="verbose"></a>-verbose</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7342	</div>
				7343
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7344	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>print detailed information about the image when this option
				7345	precedes the <a href="command-line-options.html#identify">-identify</a> option or
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7346	<code>info:</code>.</td><td style='text-align:right;'></td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7347
				7348
				7349	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7350	<h4><a id="version"></a>-version</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7351	</div>
				7352
				7353	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>print ImageMagick version string and exit.</td><td style='text-align:right;'></td></tr></table>
				7354
				7355
				7356	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7357	<h4><a id="view"></a>-view <em class="arg">string</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7358	</div>
				7359
				7360	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>FlashPix viewing parameters.</td><td style='text-align:right;'></td></tr></table>
				7361
				7362
				7363	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7364	<h4><a id="vignette"></a>-vignette <em class="arg">radius</em>{x<em class="arg">sigma</em>}{<em class="arg">+-</em>}<em class="arg">x</em>{<em class="arg">+-</em>}<em class="arg">y</em>{<em class="arg">%</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7365	</div>
				7366
				7367	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>soften the edges of the image in vignette style.</td><td style='text-align:right;'></td></tr></table>
				7368
				7369
				7370	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7371	<h4><a id="virtual-pixel"></a>-virtual-pixel <em class="arg">method</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7372	</div>
				7373
				7374	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Specify contents of <em>virtual pixels</em>.</td><td style='text-align:right;'></td></tr></table>
				7375
				7376	<p>This option defines what color source should be used if and when a color
				7377	lookup completely 'misses' the source image. The color(s) that appear to
				7378	surround the source image. Generally this color is derived from the source
				7379	image, but could also be set to a specify background color. </p>
				7380
				7381	<p>Choose from these methods:</p>
				7382
				7383	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	7384	background the area surrounding the image is the background color
				7385	black the area surrounding the image is black
				7386	checker-tile alternate squares with image and background color
				7387	dither non-random 32x32 dithered pattern
				7388	edge extend the edge pixel toward infinity
				7389	gray the area surrounding the image is gray
				7390	horizontal-tile horizontally tile the image, background color above/below
				7391	horizontal-tile-edge horizontally tile the image and replicate the side edge pixels
				7392	mirror mirror tile the image
				7393	random choose a random pixel from the image
				7394	tile tile the image (default)
				7395	transparent the area surrounding the image is transparent blackness
				7396	vertical-tile vertically tile the image, sides are background color
				7397	vertical-tile-edge vertically tile the image and replicate the side edge pixels
				7398	white the area surrounding the image is white
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7399	</pre>
				7400
				7401	<p>The default value is "edge".</p>
				7402
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7403	<p>This most important for distortion operators such as <a href="command-line-options.html#distort"
				7404	>-distort</a>, <a href="command-line-options.html#implode" >-implode</a>, and <a href="command-line-options.html#fx" >-fx</a>.
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7405	However it also effects operations that may access pixels just outside the
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7406	image proper, such as <a href="command-line-options.html#convolve">-convolve</a>, <a
				7407	href="command-line-options.html#blur">-blur</a>, and <a href="command-line-options.html#sharpen">-sharpen</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7408
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7409	<p>To print a complete list of virtual pixel types, use the <a
				7410	href="command-line-options.html#list">-list virtual-pixel</a> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7411
				7412
				7413	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7414	<h4><a id="visual"></a>-visual <em class="arg">type</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7415	</div>
				7416
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7417	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Animate images using this X visual type.</td><td style='text-align:right;'>[<a href="animate.html">animate</a>, <a href="display.html">display</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7418
				7419	<p>Choose from these visual classes:</p>
				7420
				7421	<pre class="text">
cristy	e9a32c3	2011-04-07 01:11:05 +0000	[diff] [blame]	7422	StaticGray
				7423	GrayScale
				7424	StaticColor
				7425	PseudoColor
				7426	TrueColor
				7427	DirectColor
				7428	default
				7429	visual id
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7430	</pre>
				7431
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7432	<p>The X server must support the visual you choose, otherwise an error occurs.
				7433	If a visual is not specified, the visual class that can display the most
				7434	simultaneous colors on the default screen is chosen.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7435
				7436
				7437	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7438	<h4><a id="watermark"></a>-watermark <em
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7439	class="arg">brightness</em>x<em class="arg">saturation</em></h4>
				7440	</div>
				7441
				7442	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Watermark an image using the given percentages of brightness and
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7443	saturation.</td><td style='text-align:right;'>[<a href="composite.html">composite</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7444
				7445	<p>Take a grayscale image (with alpha mask) and modify the destination image's
				7446	brightness according to watermark image's grayscale value and the <em
				7447	class="arg">brightness</em> percentage. The destinations color saturation
				7448	attribute is just direct modified by the <em class="arg">saturation</em>
				7449	percentage, which defaults to 100 percent (no color change). </p>
				7450
				7451
				7452	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7453	<h4><a id="wave"></a>-wave <em class="arg">amplitude</em><br />-wave <em class="arg">amplitude</em>x<em class="arg">wavelength</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7454	</div>
				7455
				7456	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Shear the columns of an image into a sine wave.</td><td style='text-align:right;'></td></tr></table>
				7457
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7458	<p>Specify <em class="arg">amplitude</em> and <em class="arg">wavelength</em>
				7459	of the wave.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7460
				7461	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7462	<h4><a id="weight"></a>-weight <em class="arg">fontWeight</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7463	</div>
				7464
				7465	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Set a font weight for text.</td><td style='text-align:right;'></td></tr></table>
				7466
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7467	<p>This setting suggests a font weight that ImageMagick should try to apply to
				7468	the currently selected font family. Use a positive integer for <em
				7469	class="arg">fontWeight</em> or select from the following.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7470
				7471	<table class="doc">
				7472	<col width="25%" />
				7473	<col width="75%" />
				7474	<thead>
				7475	<tr>
				7476	<th><em class="arg">fontWeight</em></th>
				7477	<th>Description</th>
				7478	</tr>
				7479	</thead>
				7480	<tbody>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7481	<tr><td>All </td>
				7482	<td>No effect. </td></tr>
				7483	<tr><td>Bold </td>
				7484	<td>Same as <em class="arg">fontWeight</em> = 700.</td></tr>
				7485	<tr><td>Bolder </td>
				7486	<td>Add 100 to font weight if currently ≤ 800.</td></tr>
				7487	<tr><td>Lighter </td>
				7488	<td>Subtract 100 to font weight if currently ≤ 100.</td></tr>
				7489	<tr><td>Normal </td>
				7490	<td>Same as <em class="arg">fontWeight</em> = 400.</td></tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7491	</tbody>
				7492	</table>
				7493
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7494	<p>To print a complete list of weight types, use <a href="command-line-options.html#list">-list
				7495	weight</a>.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7496
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7497	<p>For other settings that affect fonts, see the options <a
				7498	href="command-line-options.html#font">-font</a>, <a href="command-line-options.html#family">-family</a>, <a
				7499	href="command-line-options.html#stretch">-stretch</a>, and <a href="command-line-options.html#style">-style</a>. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7500
				7501	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7502	<h4><a id="white-point"></a>-white-point <em class="arg">x,y</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7503	</div>
				7504
				7505	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>chromaticity white point.</td><td style='text-align:right;'></td></tr></table>
				7506
				7507	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7508	<h4><a id="white-threshold"></a>-white-threshold <em class="arg">value</em>{<em class="arg">%</em>}</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7509	</div>
				7510
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7511	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Force to white all pixels above the threshold while leaving all
				7512	pixels at or below the threshold unchanged.</td><td style='text-align:right;'></td></tr></table>
cristy	5cadd61	2009-09-21 19:33:41 +0000	[diff] [blame]	7513
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7514	<p> The threshold value can be given as a percentage or as an absolute integer
				7515	value within [0, <em class="QR">QuantumRange</em>] corresponding to the
				7516	desired <a href="command-line-options.html#channel">‑channel</a> value. See <a href="command-line-options.html#threshold">‑threshold</a>for more details on thresholds and resulting values. </p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7517
				7518	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7519	<h4><a id="window"></a>-window <em class="arg">id</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7520	</div>
				7521
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7522	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>Make the image the background of a window.</td><td style='text-align:right;'>[<a href="animate.html">animate</a>, <a href="display.html">display</a>]</td></tr></table>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7523
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7524	<p><em class="arg">id</em> can be a window id or name. Specify <code>root</code>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7525	to select X's root window as the target window.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7526
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7527	<p>By default the image is tiled onto the background of the target window. If
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7528	<code>backdrop</code> or <a href="command-line-options.html#geometry">-resize</a> are specified, the
				7529	image is surrounded by the background color. Refer to <code>X RESOURCES</code>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7530	for details.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7531
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7532	<p>The image will not display on the root window if the image has more unique
				7533	colors than the target window colormap allows. Use <a
				7534	href="command-line-options.html#colors">-colors</a> to reduce the number of colors.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7535
				7536	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7537	<h4><a id="window-group"></a>-window-group</h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7538	</div>
				7539
				7540	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>specify the window group.</td><td style='text-align:right;'></td></tr></table>
				7541
				7542	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7543	<h4><a id="write"></a>-write <em class="arg">filename</em></h4>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7544	</div>
				7545
				7546	<table style='background-color:#FFFFE0; margin-left:40px; margin-right:40px; width:88%'><tr><td style='width:75%'>write an image sequence.</td><td style='text-align:right;'></td></tr></table>
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7547	<p>The image sequence preceding the <a href="command-line-options.html#write">-write</a> <em class="arg">filename</em> 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> <em class="arg">filename</em> option.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	7548
cristy	751980d	2012-06-03 23:18:35 +0000	[diff] [blame]	7549	<p>Use <a href="command-line-options.html#compress">-compress</a> to specify the type of image compression.</p>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame]	7550	</div>
				7551	</div>
cristy	eed6cb6	2012-01-28 19:38:34 +0000	[diff] [blame]	7552
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	7553	</div>
				7554
				7555	<div id="linkbar">
				7556	<span id="linkbar-west"> </span>
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7557
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	7558	<span id="linkbar-center">
cristy	8ee7f24	2013-06-20 16:08:44 +0000	[diff] [blame^]	7559	<a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> •
				7560	<a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a> •
				7561	<a href="http://jqmagick.imagemagick.org/">JqMagick</a>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	7562	</span>
				7563	<span id="linkbar-east"> </span>
				7564	</div>
				7565	<div class="footer">
cristy	45ef08f	2012-12-07 13:13:34 +0000	[diff] [blame]	7566	<span id="footer-west">© 1999-2013 ImageMagick Studio LLC</span>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	7567	<span id="footer-east"> <a href="contact.html">Contact the Wizards</a></span>
				7568	</div>
				7569	<div style="clear: both; margin: 0; width: 100%; "></div>
cristy	ad41c0c	2012-10-31 00:49:28 +0000	[diff] [blame]	7570	</body>
				7571	</html>