Blame - www/perl-magick.html - platform/external/ImageMagick

blob: 4cec9fc4678e5600cb3c13ffb1316b7692f3947e [file] [log] [blame]

cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	1	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
				2	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
				3	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" dir="ltr">
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	4	<head>
cristy	3c98a4f	2010-08-13 20:09:41 +0000	[diff] [blame]	5	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
				6	<meta name="verify-v1" content="g222frIIxcQTrvDR3NBRUSKP3AnMNoqxOkIniCEkV7U="/>
cristy	ffb69ed	2010-12-25 00:06:48 +0000	[diff] [blame]	7	<title>ImageMagick: PerlMagick, Perl API for ImageMagick</title>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	8	<meta http-equiv="Content-Language" content="en-US"/>
				9	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
				10	<meta http-equiv="Reply-to" content="magick-users@imagemagick.org"/>
cristy	3c98a4f	2010-08-13 20:09:41 +0000	[diff] [blame]	11	<meta name="Application-name" content="ImageMagick"/>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	12	<meta name="Description" content="ImageMagick is a software suite to create, edit, compose, or convert bitmap images in a variety of formats. Use ImageMagick to scale, rotate, shear, distort and transform images."/>
cristy	3c98a4f	2010-08-13 20:09:41 +0000	[diff] [blame]	13	<meta name="Application-url" content="http://www.imagemagick.org"/>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	14	<meta name="Generator" content="PHP"/>
				15	<meta name="Keywords" content="perlmagick, perl, api, for, imagemagick, ImageMagick, ImageMagic, MagickCore, MagickWand, PerlMagick, Magick++, RMagick, PythonMagick, JMagick, TclMagick, Image, Magick, Magic, Wand, ImageMagickObject, Swiss, Army, Knife, Image, Processing"/>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	16	<meta name="Rating" content="GENERAL"/>
				17	<meta name="Robots" content="INDEX, FOLLOW"/>
				18	<meta name="Generator" content="ImageMagick Studio LLC"/>
				19	<meta name="Author" content="ImageMagick Studio LLC"/>
				20	<meta name="Revisit-after" content="2 DAYS"/>
				21	<meta name="Resource-type" content="document"/>
cristy	7e41fe8	2010-12-04 23:12:08 +0000	[diff] [blame]	22	<meta name="Copyright" content="Copyright (c) 1999-2011 ImageMagick Studio LLC"/>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	23	<meta name="Distribution" content="Global"/>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	24	<link rel="icon" href="../images/wand.png"/>
cristy	3c98a4f	2010-08-13 20:09:41 +0000	[diff] [blame]	25	<link rel="shortcut icon" href="../images/wand.ico" type="images/x-icon"/>
				26	<link rel="meta" type="application/rdf+xml" title="ICI" href="http://imagemagick.org/ici.rdf"/>
				27	<style type="text/css" media="all">
				28	@import url("../www/magick.css");
				29	</style>
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	30	<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
				31	<script type="text/javascript" src="../fancybox/jquery.fancybox-1.3.4.pack.js"></script>
				32	<link rel="stylesheet" type="text/css" href="../fancybox/jquery.fancybox-1.3.4.css" media="screen" />
				33	<script type="text/javascript">
				34	$(document).ready(function() {
				35	$("a[href$=.jpg],a[href$=.png],a[href$=.gif]").fancybox({
				36	'transitionIn' : 'elastic',
				37	'transitionOut' : 'elastic',
				38	'overlayShow' : false,
				39	'opacity' : true
				40	});
				41	});
				42	</script>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	43	</head>
				44
				45	<body id="www-imagemagick-org">
				46	<div class="titlebar">
				47	<a href="../index.html">
				48	<img src="../images/script.png" alt="[ImageMagick]"
				49	style="width: 350px; height: 60px; margin: 28px auto; float: left;" /></a>
				50	<a href="http://www.networkredux.com">
				51	<img src="../images/networkredux.png" alt="[sponsor]"
				52	style="margin: 45px auto; border: 0px; float: left;" /></a>
				53	<a href="http://www.imagemagick.org/discourse-server/">
				54	<img src="../images/logo.jpg" alt=""
				55	style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
				56	<a href="../index.html">
				57	<img src="../images/sprite.jpg" alt=""
				58	style="width: 114px; height: 118px; border: 0px; float: right;" /></a>
				59	</div>
				60
cristy	ce69bb0	2010-07-27 19:49:46 +0000	[diff] [blame]	61	<div class="westbar">
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	62
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	63	<div class="menu">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	64	<a title="About ImageMagick" href="../index.html">About ImageMagick</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	65	</div>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	66	<div class="sep"></div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	67	<div class="menu">
cristy	bb50337	2010-05-27 20:51:26 +0000	[diff] [blame]	68	<a title="Binary Releases" href="../www/binary-releases.html">Binary Releases</a>
				69	</div>
				70	<div class="sub">
				71	<a title="Binary Release: Unix" href="../www/binary-releases.html#unix">Unix</a>
				72	</div>
				73	<div class="sub">
				74	<a title="Binary Release: MacOS X" href="../www/binary-releases.html#macosx">Mac OS X</a>
				75	</div>
				76	<div class="sub">
				77	<a title="Binary Release: Windows" href="../www/binary-releases.html#windows">Windows</a>
				78	</div>
				79	<div class="sep"></div>
				80	<div class="menu">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	81	<a title="Command-line Tools" href="../www/command-line-tools.html">Command-line Tools</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	82	</div>
				83	<div class="sub">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	84	<a title="Command-line Tools: Processing" href="../www/command-line-processing.html">Processing</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	85	</div>
				86	<div class="sub">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	87	<a title="Command-line Tools: Options" href="../www/command-line-options.html">Options</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	88	</div>
				89	<div class="sub">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	90	<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]	91	</div>
				92	<div class="menu">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	93	<a title="Program Interfaces" href="../www/api.html">Program Interfaces</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	94	</div>
				95	<div class="sub">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	96	<a title="Program Interface: MagickWand" href="../www/magick-wand.html">MagickWand</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	97	</div>
				98	<div class="sub">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	99	<a title="Program Interface: MagickCore" href="../www/magick-core.html">MagickCore</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	100	</div>
				101	<div class="sub">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	102	<a title="Program Interface: PerlMagick" href="../www/perl-magick.html">PerlMagick</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	103	</div>
				104	<div class="sub">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	105	<a title="Program Interface: Magick++" href="../www/magick++.html">Magick++</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	106	</div>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	107	<div class="sep"></div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	108	<div class="menu">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	109	<a title="Install from Source" href="../www/install-source.html">Install from Source</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	110	</div>
				111	<div class="sub">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	112	<a title="Install from Source: Unix" href="../www/install-source.html#unix">Unix</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	113	</div>
				114	<div class="sub">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	115	<a title="Install from Source: Windows" href="../www/install-source.html#windows">Windows</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	116	</div>
				117	<div class="menu">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	118	<a title="Resources" href="../www/resources.html">Resources</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	119	</div>
cristy	bb50337	2010-05-27 20:51:26 +0000	[diff] [blame]	120	<div class="menu">
				121	<a title="Architecture" href="../www/architecture.html">Architecture</a>
				122	</div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	123	<div class="menu">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	124	<a title="Download" href="../www/download.html">Download</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	125	</div>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	126	<div class="sep"></div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	127	<div class="menu">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	128	<a title="Search" href="http://www.imagemagick.org/script/search.php">Search</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	129	</div>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	130	<div class="sep"></div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	131	<div class="menu">
cristy	ffb69ed	2010-12-25 00:06:48 +0000	[diff] [blame]	132	<a title="Site Map" href="../www/sitemap.html">Site Map</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	133	</div>
				134	<div class="sub">
cristy	ffb69ed	2010-12-25 00:06:48 +0000	[diff] [blame]	135	<a title="Site Map: Links" href="../www/links.html">Links</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	136	</div>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	137	<div class="sep"></div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	138	<div class="menu">
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	139	<a title="Sponsors" href="../www/sponsors.html">Sponsors:</a>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	140
				141	<div class="sponsbox">
				142	<div class="sponsor">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	143	<a title="Sponsor: Webdesign" href="http://www.renehornig.com/">Webdesign</a><!-- 20111001000240 -->
cristy	5c4585b	2010-11-11 00:13:57 +0000	[diff] [blame]	144	</div>
				145	<div class="sponsor">
cristy	7d52cd6	2010-10-01 17:26:59 +0000	[diff] [blame]	146	<a title="Sponsor: Druckerei" href="http://print24.com/de/">Druckerei</a><!-- 201110010720 -->
				147	</div>
				148	<div class="sponsor">
cristy	c5baf4f	2010-08-31 15:05:33 +0000	[diff] [blame]	149	<a title="Sponsor: Image Converter" href="http://www.batchphoto.com">Image Converter</a><!-- 201103010900 Bits Coffee-->
				150	</div>
				151	<div class="sponsor">
cristy	851dbce	2010-08-06 21:40:00 +0000	[diff] [blame]	152	<a title="Sponsor: Flyer drucken" href="http://www.online-druck.biz">Flyer drucken</a><!-- 201109010900 Floeter-->
				153	</div>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	154	</div>
				155	</div>
cristy	ce69bb0	2010-07-27 19:49:46 +0000	[diff] [blame]	156	</div>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	157
cristy	ce69bb0	2010-07-27 19:49:46 +0000	[diff] [blame]	158	<div class="eastbar">
				159	<script type="text/javascript">
				160	<!--
				161	google_ad_client = "pub-3129977114552745";
cristy	ce69bb0	2010-07-27 19:49:46 +0000	[diff] [blame]	162	google_ad_slot = "0574824969";
				163	google_ad_width = 160;
				164	google_ad_height = 600;
				165	//-->
				166	</script>
				167	<script type="text/javascript"
				168	src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
				169	</script>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	170	</div>
				171
				172	<div class="main">
				173
				174
cristy	ffb69ed	2010-12-25 00:06:48 +0000	[diff] [blame]	175	<h1>ImageMagick PerlMagick API</h1>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	176	<p class="navigation-index">[<a href="#installation">Installation</a> • <a href="#overview">Overview</a> • <a href="#example">Example Script</a> • <a href="#read">Read or Write an Image</a> • <a href="#manipulate">Manipulate an Image</a> • <a href="#set-attribute">Set an Image Attribute</a> • <a href="#get-attribute">Get an Image Attribute</a> • <a href="#compare">Compare an Image to its Reconstruction</a> • <a href="#montage">Create an Image Montage</a> • <a href="#blobs">Working with Blobs</a> • <a href="#direct-access">Direct-access to Image Pixels</a> • <a href="#miscellaneous">Miscellaneous Methods</a> • <a href="#exceptions">Handling Exceptions</a>• <a href="#constants">Constant</a> ]</p>
				177
				178	<div class="doc-section">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	179	<a id="introduction"></a>
cristy	f3bb478	2009-09-08 13:10:04 +0000	[diff] [blame]	180	<p><a href="../www/download.html">PerlMagick</a> is an objected-oriented <a href="http://www.perl.com/perl/">Perl</a> interface to ImageMagick. Use the module to read, manipulate, or write an image or image sequence from within a Perl script. This makes it very suitable for Web CGI scripts. You must have ImageMagick 6.5.5 or above and Perl version 5.005_02 or greater installed on your system for PerlMagick to build properly.</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	181
				182	<p>There are a number of useful scripts available to show you the value of PerlMagick. You can do Web based image manipulation and conversion with <a href="http://www.imagemagick.org/download/perl">MagickStudio</a>, or use <a href="https://www.imagemagick.org/subversion/ImageMagick/trunk/PerlMagick/demo/">L-systems</a> to create images of plants using mathematical constructs, and finally navigate through collections of thumbnail images and select the image to view with the <a href="http://webmagick.sourceforge.net/">WebMagick Image Navigator</a>.</p>
				183
				184	<p>You can try PerlMagick from your Web browser at the <a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">ImageMagick Studio</a>. Or, you can see <a href="../www/examples.html">examples</a> of select PerlMagick functions.</p>
				185	</div>
				186
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	187	<h2><a id="installation"></a>Installation</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	188	<div class="doc-section">
				189
				190	<p><b>UNIX</b></p>
				191
				192	<p>The following instructions for Unix apply only to the unbundled PerlMagick as obtained from CPAN. PerlMagick is included as a subdirectory (PerlMagick) of the ImageMagick source distribution, and may be configured and built using the instructions provided in the ImageMagick distribution's README.txt file. It is usually most convenient to install PerlMagick as part of the ImageMagick distribution.</p>
				193
				194	<p>ImageMagick must already be installed on your system. Next, get
				195	the <a href="../www/download.html">PerlMagick</a> distribution corresponding to the installed ImageMagick distribution
cristy	61365ad	2010-11-28 02:38:34 +0000	[diff] [blame]	196	(e.g., PerlMagick 6.66 for
				197	ImageMagick 6.6.6) and unpack it as shown below:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	198
cristy	61365ad	2010-11-28 02:38:34 +0000	[diff] [blame]	199	<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>tar xvfz PerlMagick-6.66.tar.gz</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>cd PerlMagick</span></p>
cristy	f3bb478	2009-09-08 13:10:04 +0000	[diff] [blame]	200	<p>Next, edit <kbd>Makefile.PL</kbd> and change LIBS and INC to include the appropriate path information to the required <kbd>MagickCore</kbd> library. You may need paths to JPEG, PNG, TIFF, etc. delegates if they were included with your installed version of ImageMagick. Build and install it like this:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	201
				202	<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>perl Makefile.PL</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>make</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>make install</span></p>
				203	<p>For Unix, you typically need to be <kbd>root</kbd> to install the software. There are ways around this. Consult the Perl manual pages for more information.</p>
				204
				205	<p><b>Windows XP / Windows 2000</b></p>
				206
				207	<p>ImageMagick must already be installed on your system. Also, the ImageMagick source distribution for <a href="../www/download.html">Windows 2000</a> is required. You must also have the <kbd>nmake</kbd> from the Visual C++ or J++ development environment. Copy <kbd>\bin\IMagick.dll</kbd> and <kbd>\bin\X11.dll</kbd> to a directory in your dynamic load path such as <kbd>c:\perl\site\5.00502</kbd>.</p>
				208
				209	<p>Next, type</p>
				210
				211	<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>cd PerlMagick</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>perl Makefile.nt</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>nmake</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>nmake install</span></p>
				212	<p>See the <a href="http://www.dylanbeattie.net/magick/">PerlMagick Windows HowTo</a> page for further installation instructions.</p>
				213
				214	<p><b>Running the Regression Tests</b></p>
				215
				216	<p>To verify a correct installation, type</p>
				217
				218	<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>make test</span></p>
				219	<p>Use <kbd>nmake test</kbd> under Windows. There are a few demonstration scripts available to exercise many of the functions PerlMagick can perform. Type</p>
				220
				221	<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>cd demo</span><span class='crtout'></span><span class="crtprompt"> $magick> </span><span class='crtin'>make</span></p>
				222	<p>You are now ready to utilize the PerlMagick methods from within your Perl scripts.</p>
				223
				224	</div>
				225
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	226	<h2><a id="overview"></a>Overview</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	227	<div class="doc-section">
				228
				229	<p>Any script that wants to use PerlMagick methods must first define the methods within its namespace and instantiate an image object. Do this with:</p>
				230
				231	<pre class="code">
				232	use Image::Magick;
				233
				234	$image=Image::Magick->new;
				235	</pre>
				236
				237	<p>The new() method takes the same parameters as <a href="#set-attribute">SetAttribute</a> . For example,</p>
				238
				239	<pre class="code">
				240	$image=Image::Magick->new(size=>'384x256');
				241	</pre>
				242
				243	<p>Next you will want to read an image or image sequence, manipulate it, and then display or write it. The input and output methods for PerlMagick are defined in <a href="#read">Read or Write an Image</a>. See <a href="#set-attribute">Set an Image Attribute</a> for methods that affect the way an image is read or written. Refer to <a href="#manipulate">Manipulate an Image</a> for a list of methods to transform an image. <a href="#get-attribute">Get an Image Attribute</a> describes how to retrieve an attribute for an image. Refer to <a href="#montage">Create an Image Montage</a> for details about tiling your images as thumbnails on a background. Finally, some methods do not neatly fit into any of the categories just mentioned. Review <a href="#misc">Miscellaneous Methods</a> for a list of these methods.</p>
				244
cristy	c1c6166	2009-09-30 14:04:37 +0000	[diff] [blame]	245	<p>Once you are finished with a PerlMagick object you should consider destroying it. Each image in an image sequence is stored in virtual memory. This can potentially add up to mebibytes of memory. Upon destroying a PerlMagick object, the memory is returned for use by other Perl methods. The recommended way to destroy an object is with <kbd>undef</kbd>:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	246
				247	<pre class="code">
				248	undef $image;
				249	</pre>
				250
				251	<p>To delete all the images but retain the <kbd>Image::Magick</kbd> object use</p>
				252
				253	<pre class="code">
				254	@$image = ();
				255	</pre>
				256
				257	<p>and finally, to delete a single image from a multi-image sequence, use</p>
				258
				259	<pre class="code">
				260	undef $image->[$x];
				261	</pre>
				262
				263	<p>The next section illustrates how to use various PerlMagick methods to manipulate an image sequence.</p>
				264
				265	<p>Some of the PerlMagick methods require external programs such as <a href="http://www.cs.wisc.edu/~ghost/">Ghostscript</a>. This may require an explicit path in your PATH environment variable to work properly. For example (in Unix),</p>
				266
				267	<p class='crt'><span class="crtprompt"> $magick> </span><span class='crtin'>$ENV{PATH}='/../bin:/usr/bin:/usr/local/bin';</span></p>
				268	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	269	<h2><a id="example"></a>Example Script</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	270	</div>
				271
				272	<p>Here is an example script to get you started:</p>
				273
				274	<pre class="code">
				275	#!/usr/local/bin/perl
				276	use Image::Magick;<br />
				277	my($image, $x);<br />
				278	$image = Image::Magick->new;
				279	$x = $image->Read('girl.png', 'logo.png', 'rose.png');
				280	warn "$x" if "$x";<br />
				281	$x = $image->Crop(geometry=>'100x100+100+100');
				282	warn "$x" if "$x";<br />
				283	$x = $image->Write('x.png');
				284	warn "$x" if "$x";
				285	</pre>
				286
				287	<p>The script reads three images, crops them, and writes a single image as a GIF animation sequence. In many cases you may want to access individual images of a sequence. The next example illustrates how this done:</p>
				288
				289	<pre class="code">
				290	#!/usr/local/bin/perl
				291	use Image::Magick;<br />
				292	my($image, $p, $q);<br />
				293	$image = new Image::Magick;
				294	$image->Read('x1.png');
				295	$image->Read('j*.jpg');
				296	$image->Read('k.miff[1, 5, 3]');
				297	$image->Contrast();
				298	for ($x = 0; $image->[$x]; $x++)
				299	{
				300	$image->[$x]->Frame('100x200') if $image->[$x]->Get('magick') eq 'GIF';
				301	undef $image->[$x] if $image->[$x]->Get('columns') < 100;
				302	}
				303	$p = $image->[1];
				304	$p->Draw(stroke=>'red', primitive=>'rectangle', points=>20,20 100,100');
				305	$q = $p->Montage();
				306	undef $image;
				307	$q->Write('x.miff');
				308	</pre>
				309
				310	<p>Suppose you want to start out with a 100 by 100 pixel white canvas with a red pixel in the center. Try</p>
				311
				312	<pre class="code">
				313	$image = Image::Magick->new;
				314	$image->Set(size=>'100x100');
				315	$image->ReadImage('xc:white');
				316	$image->Set('pixel[49,49]'=>'red');
				317	</pre>
				318
				319	<p>Here we reduce the intensity of the red component at (1,1) by half:</p>
				320
				321	<pre class="code">
				322	@pixels = $image->GetPixel(x=>1,y=>1);
				323	$pixels[0]*=0.5;
				324	$image->SetPixel(x=>1,y=>1,color=>\@pixels);
				325	</pre>
				326
				327	<p>Or suppose you want to convert your color image to grayscale:</p>
				328
				329	<pre class="code">
				330	$image->Quantize(colorspace=>'gray');
				331	</pre>
				332
				333	<p>Let's annotate an image with a Taipai TrueType font:</p>
				334
				335	<pre class="code">
				336	$text = 'Works like magick!';
				337	$image->Annotate(font=>'kai.ttf', pointsize=>40, fill=>'green', text=>$text);
				338	</pre>
				339
				340	<p>Perhaps you want to extract all the pixel intensities from an image and write them to STDOUT:</p>
				341
				342	<pre class="code">
				343	@pixels = $image->GetPixels(map=>'I', height=>$height, width=>$width, normalize=>true);
				344	binmode STDOUT;
				345	print pack('B*',join('',@pixels));
				346	</pre>
				347
				348	<p>Other clever things you can do with a PerlMagick objects include</p>
				349
				350	<pre class="code">
				351	$i = $#$p"+1"; # return the number of images associated with object p
				352	push(@$q, @$p); # push the images from object p onto object q
				353	@$p = (); # delete the images but not the object p
				354	$p->Convolve([1, 2, 1, 2, 4, 2, 1, 2, 1]); # 3x3 Gaussian kernel
				355	</pre>
				356
				357	<div style="margin: auto;">
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	358	<h2><a id="read"></a>Read or Write an Image</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	359	</div>
				360
				361	<p>Use the methods listed below to either read, write, or display an image or image sequence:</p>
				362
				363	<table class="doc">
				364	<caption>Read or Write Methods</caption>
				365	<colgroup>
				366	<col width="20%"></col>
				367	<col width="20%"></col>
				368	<col width="20%"></col>
				369	<col width="40%"></col>
				370	</colgroup>
				371	<tbody>
				372
				373	<tr>
				374	<th>Method</th>
				375	<th>Parameters</th>
				376	<th>Return Value</th>
				377	<th>Description</th>
				378	</tr>
				379
				380	<tr>
				381	<td valign="top">Read</td>
				382	<td valign="top">one or more filenames</td>
				383	<td valign="top">the number of images read</td>
				384	<td valign="top">read an image or image sequence</td>
				385	</tr>
				386
				387	<tr>
				388	<td valign="top">Write</td>
				389	<td valign="top">filename</td>
				390	<td valign="top">the number of images written</td>
				391	<td valign="top">write an image or image sequence</td>
				392	</tr>
				393
				394	<tr>
				395	<td valign="top">Display</td>
				396	<td valign="top">server name</td>
				397	<td valign="top">the number of images displayed</td>
				398	<td valign="top">display the image or image sequence to an X server</td>
				399	</tr>
				400
				401	<tr>
				402	<td valign="top">Animate</td>
				403	<td valign="top">server name</td>
				404	<td valign="top">the number of images animated</td>
				405	<td valign="top">animate image sequence to an X server</td>
				406	</tr>
				407	</tbody>
				408	</table>
				409
				410	<p>For convenience, methods Write(), Display(), and Animate() can take any parameter that <a href="#set-attribute">SetAttribute</a> knows about. For example,</p>
				411
				412	<pre class="code">
				413	$image->Write(filename=>'image.png', compression=>'None');
				414	</pre>
				415
				416	<p>Use <kbd>-</kbd> as the filename to method Read() to read from standard in or to method Write() to write to standard out:</p>
				417
				418	<pre class="code">
				419	binmode STDOUT;
				420	$image->Write('png:-');
				421	</pre>
				422
				423	<p>To read an image in the GIF format from a PERL filehandle, use:</p>
				424
				425	<pre class="code">
				426	$image = Image::Magick->new;
				427	open(IMAGE, 'image.gif');
				428	$image->Read(file=>\*IMAGE);
				429	close(IMAGE);
				430	</pre>
				431
				432	<p>To write an image in the PNG format to a PERL filehandle, use:</p>
				433
				434	<pre class="code">
				435	$filename = "image.png";
				436	open(IMAGE, ">$filename");
				437	$image->Write(file=>\*IMAGE, filename=>$filename);
				438	close(IMAGE);
				439	</pre>
				440
cristy	cb03ed6	2009-12-11 21:30:51 +0000	[diff] [blame]	441	<p>Note, reading from or writing to a Perl filehandle may fail under Windows due to different versions of the C-runtime libraries between ImageMagick and the ActiveState Perl distributions or if one of the DLL's is linked with the /MT option. See <a href="http://msdn.microsoft.com/en-us/library/ms235460.aspx">Potential Errors Passing CRT Objects Across DLL Boundaries</a> for an explanation.</p>
				442
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	443	<p>If <kbd>%0Nd, %0No, or %0Nx</kbd> appears in the filename, it is interpreted as a printf format specification and the specification is replaced with the specified decimal, octal, or hexadecimal encoding of the scene number. For example,</p>
				444
				445	<pre class="text">
				446	image%03d.miff
				447	</pre>
				448
				449	<p>converts files image000.miff, image001.miff, etc.</p>
				450
				451	<p>You can optionally add <i>Image</i> to any method name. For example, ReadImage() is an alias for method Read().</p>
				452
				453	</div>
				454
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	455	<h2><a id="manipulate"></a>Manipulate an Image</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	456	<div class="doc-section">
				457
				458	<p>Once you create an image with, for example, method ReadImage() you may want to operate on it. Below is a list of all the image manipulations methods available to you with PerlMagick. There are <a href="../www/examples.html">examples</a> of select PerlMagick methods. Here is an example call to an image manipulation method:</p>
				459
				460	<pre class="code">
				461	$image->Crop(geometry=>'100x100+10+20');
				462	$image->[$x]->Frame("100x200");
				463	</pre>
				464
				465	<p>And here is a list of other image manipulation methods you can call:</p>
				466
				467	<table class="doc">
				468	<caption>Image Manipulation Methods</caption>
				469	<tbody>
				470	<tr>
				471	<th>Method</th>
				472	<th style="width: 40%">Parameters</th>
				473	<th style="width: 40%">Description</th>
				474	</tr>
				475
				476	<tr>
				477	<td valign="top">AdaptiveBlur</td>
				478	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				479	<td valign="top">adaptively blur the image with a Gaussian operator of the given radius and standard deviation (sigma). Decrease the effect near edges.</td>
				480	</tr>
				481
				482	<tr>
				483	<td valign="top">AdaptiveResize</td>
				484	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, filter=>{Point, Box, Triangle, Hermite, Hanning, Hamming, Blackman, Gaussian, Quadratic, Cubic, Catrom, Mitchell, Lanczos, Bessel, Sinc}, support=><i>double</i>, blur=><i>double</i></td>
				485	<td valign="top">adaptively resize image using data dependant triangulation. Specify <kbd>blur</kbd> > 1 for blurry or < 1 for sharp</td>
				486	</tr>
				487
				488	<tr>
				489	<td valign="top">AdaptiveSharpen</td>
				490	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				491	<td valign="top">adaptively sharpen the image with a Gaussian operator of the given radius and standard deviation (sigma). Increase the effect near edges.</td>
				492	</tr>
				493
				494	<tr>
				495	<td valign="top">AdaptiveThreshold</td>
				496	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, offset=><i>integer</i></td>
				497	<td valign="top">local adaptive thresholding.</td>
				498	</tr>
				499
				500	<tr>
				501	<td valign="top">AddNoise</td>
				502	<td valign="top">noise=>{Uniform, Gaussian, Multiplicative, Impulse, Laplacian, Poisson}, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				503	<td valign="top">add noise to an image</td>
				504	</tr>
				505
				506	<tr>
				507	<td valign="top">AffineTransform</td>
				508	<td valign="top">affine=><i>array of float values</i>, translate=><i>float, float</i>, scale=> <i>float, float</i>, rotate=><i>float</i>, skewX=><i>float</i>, skewY=><i>float</i>, interpolate={Average, Bicubic, Bilinear, Filter, Integer, Mesh, NearestNeighbor}, background=><i><a href="../www/color.html">color name</a></i></td>
				509	<td valign="top">affine transform image</td>
				510	</tr>
				511
				512	<tr>
				513	<td valign="top">Affinity</td>
				514	<td valign="top">image=><i>image-handle</i>, method=>{None, FloydSteinberg, Riemersma}</td>
				515	<td valign="top">choose a particular set of colors from this image</td>
				516	</tr>
				517
				518	<tr>
				519	<td valign="top">Annotate</td>
cristy	bebec40	2010-04-23 19:19:08 +0000	[diff] [blame]	520	<td valign="top">text=><i>string</i>, font=><i>string</i>, family=><i>string</i>, style=>{Normal, Italic, Oblique, Any}, stretch=>{Normal, UltraCondensed, ExtraCondensed, Condensed, SemiCondensed, SemiExpanded, Expanded, ExtraExpanded, UltraExpanded}, weight=><i>integer</i>, pointsize=><i>integer</i>, density=><i>geometry</i>, stroke=><i><a href="../www/color.html">color name</a></i>, strokewidth=><i>integer</i>, fill=><i><a href="../www/color.html">color name</a></i>, undercolor=><i><a href="../www/color.html">color name</a></i>, kerning=><i>float</i>, geometry=><i>geometry</i>, gravity=>{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}, antialias=>{true, false}, x=><i>integer</i>, y=><i>integer</i>, affine=><i>array of float values</i>, translate=><i>float, float</i>, scale=><i>float, float</i>, rotate=><i>float</i>. skewX=><i>float</i>, skewY=> <i>float</i>, align=>{Left, Center, Right}, encoding=>{UTF-8}, interline-spacing=><i>double</i>, interword-spacing=><i>double</i>, direction=>{right-to-left, left-to-right}</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	521	<td valign="top">annotate an image with text. See <a href="#misc">QueryFontMetrics</a> to get font metrics without rendering any text.</td>
				522	</tr>
				523
				524	<tr>
				525	<td valign="top">AutoGamma</td>
				526	<td valign="top">channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				527	<td valign="top">automagically adjust gamma level of image</td>
				528	</tr>
				529
				530	<tr>
				531	<td valign="top">AutoLevel</td>
				532	<td valign="top">channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				533	<td valign="top">automagically adjust color levels of image</td>
				534	</tr>
				535
				536	<tr>
				537	<td valign="top">AutoOrient</td>
				538	<td valign="top"><br /></td>
				539	<td valign="top">automagically orient the image</td>
				540	</tr>
				541
				542	<tr>
				543	<td valign="top">BlackThreshold</td>
cristy	ec40739	2009-11-28 22:42:05 +0000	[diff] [blame]	544	<td valign="top">threshold=><i>string</i>, , channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	545	<td valign="top">force all pixels below the threshold intensity into black</td>
				546	</tr>
				547
				548	<tr>
				549	<td valign="top">BlueShift</td>
				550	<td valign="top">factor=><i>double</i>,</td>
				551	<td valign="top">simulate a scene at nighttime in the moonlight. Start with a factor of 1.5.</td>
				552	</tr>
				553
				554	<tr>
				555	<td valign="top">Blur</td>
				556	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				557	<td valign="top">reduce image noise and reduce detail levels with a Gaussian operator of the given radius and standard deviation (sigma).</td>
				558	</tr>
				559
				560	<tr>
				561	<td valign="top">Border</td>
				562	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, bordercolor=><i><a href="../www/color.html">color name</a></i>, compose=>{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCMYK, Cyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, RGB, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor },</td>
				563	<td valign="top">surround the image with a border of color</td>
				564	</tr>
				565
				566	<tr>
				567	<td valign="top">Charcoal</td>
				568	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i></td>
				569	<td valign="top">simulate a charcoal drawing</td>
				570	</tr>
				571
				572	<tr>
				573	<td valign="top">Chop</td>
				574	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, x=><i>integer</i>, y=><i>integer</i></td>
				575	<td valign="top">chop an image</td>
				576	</tr>
				577
				578	<tr>
cristy	b4c03bb	2009-09-27 13:55:46 +0000	[diff] [blame]	579	<td valign="top">Clamp</td>
				580	<td valign="top"><br /></td>
				581	<td valign="top">restrict color values from 0 to the quantum depth.</td>
				582	</tr>
				583
				584	<tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	585	<td valign="top">Clip</td>
				586	<td valign="top">id=><i>name</i>, inside=><i>{true, false}</i>,</td>
				587	<td valign="top">apply along a named path from the 8BIM profile.</td>
				588	</tr>
				589
				590	<tr>
				591	<td valign="top">ClipMask</td>
				592	<td valign="top">mask=><i>image-handle</i></td>
				593	<td valign="top">clip image as defined by the image mask</td>
				594	</tr>
				595
				596	<tr>
				597	<td valign="top">Clut</td>
				598	<td valign="top">image=><i>image-handle</i>, channel=>{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
				599	<td valign="top">apply a color lookup table to an image sequence</td>
				600	</tr>
				601
				602	<tr>
				603	<td valign="top">Coalesce</td>
				604	<td valign="top"><br /></td>
				605	<td valign="top">merge a sequence of images</td>
				606	</tr>
				607
				608	<tr>
cristy	83a272e	2010-05-07 20:40:35 +0000	[diff] [blame]	609	<td valign="top">Color</td>
				610	<td valign="top">color=><i><a href="../www/color.html">color name</a></i></td>
				611	<td valign="top">set the entire image to this color.</td>
				612	</tr>
				613
				614	<tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	615	<td valign="top">ColorDecisionList</td>
				616	<td valign="top">filename=><i>string</i>,</td>
				617	<td valign="top">color correct with a color decision list.</td>
				618	</tr>
				619
				620	<tr>
				621	<td valign="top">Colorize</td>
				622	<td valign="top">fill=><i><a href="../www/color.html">color name</a></i>, opacity=><i>string</i></td>
				623	<td valign="top">colorize the image with the fill color</td>
				624	</tr>
				625
				626	<tr>
cristy	2c83960	2010-04-03 02:32:08 +0000	[diff] [blame]	627	<td valign="top">ColorMatrix</td>
				628	<td valign="top">matrix=><i>array of float values</i></td>
				629	<td valign="top">apply color correction to the image. Although you can use variable sized matrices, typically you use a 5 x 5 for an RGBA image and a 6x6 for CMYKA. A 6x6 matrix is required for offsets (populate the last column with normalized values).</td>
				630	</tr>
				631
				632	<tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	633	<td valign="top">Comment</td>
				634	<td valign="top">string</td>
				635	<td valign="top">add a comment to your image</td>
				636	</tr>
				637
				638	<tr>
				639	<td valign="top">CompareLayers</td>
				640	<td valign="top">method=>{any, clear, overlay}</td>
				641	<td valign="top">compares each image with the next in a sequence and returns the minimum bounding region of any pixel differences it discovers. Images do not have to be the same size, though it is best that all the images are coalesced (images are all the same size, on a flattened canvas, so as to represent exactly how a specific frame should look).</td>
				642	</tr>
				643
				644	<tr>
				645	<td valign="top">Composite</td>
				646	<td valign="top">image=><i>image-handle</i>, compose=>{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCMYK, Cyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, RGB, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor }, mask=><i>image-handle</i>, geometry=><i>geometry</i>, x=><i>integer</i>, y=><i>integer</i>, gravity=>{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}, opacity=><i>integer</i>, tile=>{True, False}, rotate=><i>double</i>, color=><i><a href="../www/color.html">color name</a></i>, blend=><i>geometry</i>, interpolate=>{undefined, average, bicubic, bilinear, filter, integer, mesh, nearest-neighbor, spline}</td>
				647	<td valign="top">composite one image onto another. Use the rotate parameter in concert with the tile parameter.</td>
				648	</tr>
				649
				650	<tr>
				651	<td valign="top">Contrast</td>
				652	<td valign="top">sharpen=>{True, False}</td>
				653	<td valign="top">enhance or reduce the image contrast</td>
				654	</tr>
				655
				656	<tr>
				657	<td valign="top">ContrastStretch</td>
				658	<td valign="top">levels=><i>string</i>, 'black-point'=><i>double</i>, 'white-point'=><i>double</i>, channel=>{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
				659	<td valign="top">improve the contrast in an image by `stretching' the range of intensity values</td>
				660	</tr>
				661
				662	<tr>
				663	<td valign="top">Convolve</td>
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	664	<td valign="top">coefficients=><i>array of float values</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, bias=><i>double</i></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	665	<td valign="top">apply a convolution kernel to the image. Given a kernel <i>order</i> , you would supply <i>order*order</i> float values (e.g. 3x3 implies 9 values).</td>
				666	</tr>
				667
				668	<tr>
				669	<td valign="top">Crop</td>
cristy	a13871a	2009-12-06 19:01:22 +0000	[diff] [blame]	670	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, x=><i>integer</i>, y=><i>integer</i>, fuzz=><i>double</i>, gravity=>{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	671	<td valign="top">crop an image</td>
				672	</tr>
				673
				674	<tr>
				675	<td valign="top">CycleColormap</td>
				676	<td valign="top">amount=><i>integer</i></td>
				677	<td valign="top">displace image colormap by amount</td>
				678	</tr>
				679
				680	<tr>
				681	<td valign="top">Decipher</td>
				682	<td valign="top">passphrase=><i>string</i></td>
				683	<td valign="top">convert cipher pixels to plain pixels</td>
				684	</tr>
				685
				686	<tr>
				687	<td valign="top">Deconstruct</td>
				688	<td valign="top"><br /></td>
				689	<td valign="top">break down an image sequence into constituent parts</td>
				690	</tr>
				691
				692	<tr>
				693	<td valign="top">Deskew</td>
				694	<td valign="top">geometry=><i>string</i>,threshold=><i>double</i></td>
				695	<td valign="top">straighten the image</td>
				696	</tr>
				697
				698	<tr>
				699	<td valign="top">Despeckle</td>
				700	<td valign="top"> </td>
				701	<td valign="top">reduce the speckles within an image</td>
				702	</tr>
				703
				704	<tr>
				705	<td valign="top">Difference</td>
				706	<td valign="top">image=><i>image-handle</i></td>
				707	<td valign="top">compute the difference metrics between two images </td>
				708	</tr>
				709
				710	<tr>
				711	<td valign="top">Distort</td>
				712	<td valign="top">points=><i>array of float values</i>, method=>{Affine, AffineProjection, Bilinear, Perspective, ScaleRotateTranslate}, virtual-pixel=>{Background Black Constant Dither Edge Gray Mirror Random Tile Transparent White}, best-fit=>{True, False}</td>
				713	<td valign="top">distort image</td>
				714	</tr>
				715
				716	<tr>
				717	<td valign="top">Draw</td>
cristy	bebec40	2010-04-23 19:19:08 +0000	[diff] [blame]	718	<td valign="top">primitive=>{point, line, rectangle, arc, ellipse, circle, path, polyline, polygon, bezier, color, matte, text, @<i>filename</i>}, points=><i>string</i> , method=><i>{Point, Replace, Floodfill, FillToBorder, Reset}</i>, stroke=><i><a href="../www/color.html">color name</a></i>, fill=><i><a href="../www/color.html">color name</a></i>, font=><i>string</i>, pointsize=><i>integer</i>, strokewidth=><i>float</i>, antialias=>{true, false}, bordercolor=><i><a href="../www/color.html">color name</a></i>, x=><i>float</i>, y=><i>float</i>, dash-offset=><i>float</i>, dash-pattern=><i>array of float values</i>, affine=><i>array of float values</i>, translate=><i>float, float</i>, scale=><i>float, float</i>, rotate=><i>float</i>, skewX=><i>float</i>, skewY=><i>float</i>, interpolate=>{undefined, average, bicubic, bilinear, mesh, nearest-neighbor, spline}, kerning=><i>float</i>, text=><i>string</i>, vector-graphics=><i>string</i>, interline-spacing=><i>double</i>, interword-spacing=><i>double</i>, direction=>{right-to-left, left-to-right}</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	719	<td valign="top">annotate an image with one or more graphic primitives.</td>
				720	</tr>
				721
				722	<tr>
				723	<td valign="top">Encipher</td>
				724	<td valign="top">passphrase=><i>string</i></td>
				725	<td valign="top">convert plain pixels to cipher pixels</td>
				726	</tr>
				727
				728	<tr>
				729	<td valign="top">Edge</td>
				730	<td valign="top">radius=><i>double</i></td>
				731	<td valign="top">enhance edges within the image with a convolution filter of the given radius.</td>
				732	</tr>
				733
				734	<tr>
				735	<td valign="top">Emboss</td>
				736	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i></td>
				737	<td valign="top">emboss the image with a convolution filter of the given radius and standard deviation (sigma).</td>
				738	</tr>
				739
				740	<tr>
				741	<td valign="top">Enhance</td>
				742	<td valign="top"><br /></td>
				743	<td valign="top">apply a digital filter to enhance a noisy image</td>
				744	</tr>
				745
				746	<tr>
				747	<td valign="top">Equalize</td>
				748	<td valign="top">channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}<br /></td>
				749	<td valign="top">perform histogram equalization to the image</td>
				750	</tr>
				751
				752	<tr>
				753	<td valign="top">Extent</td>
				754	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, x=><i>integer</i>, y=><i>integer</i>, fuzz=><i>double</i>, background=><i><a href="../www/color.html">color name</a></i>, gravity=>{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}</td>
				755	<td valign="top">set the image size</td>
				756	</tr>
				757
				758	<tr>
				759	<td valign="top">Evaluate</td>
				760	<td valign="top">value=><i>double</i>, operator=><i>{Add, And, Divide, LeftShift, Max, Min, Multiply, Or, Rightshift, Subtract, Xor}</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow} </td>
				761	<td valign="top">apply an arithmetic, relational, or logical expression to the image</td>
				762	</tr>
				763
				764	<tr>
cristy	16ff93c	2010-01-13 23:18:07 +0000	[diff] [blame]	765	<td valign="top">Filter</td>
				766	<td valign="top">kernel=><i>string</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, bias=><i>double</i></td>
				767	<td valign="top">apply a convolution kernel to the image.</td>
				768	</tr>
				769
				770	<tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	771	<td valign="top">Flip</td>
				772	<td valign="top"><br /></td>
				773	<td valign="top">reflect the image scanlines in the vertical direction</td>
				774	</tr>
				775
				776	<tr>
				777	<td valign="top">Flop</td>
				778	<td valign="top"><br /></td>
				779	<td valign="top">reflect the image scanlines in the horizontal direction</td>
				780	</tr>
				781
				782	<tr>
				783	<td valign="top">FloodfillPaint</td>
				784	<td valign="top">geometry=><i>geometry</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, x=><i>integer</i>, y=><i>integer</i> , fill=><i><a href="../www/color.html">color name</a></i>, bordercolor=><i><a href="../www/color.html">color name</a></i>, fuzz=><i>double</i>, invert=>{True, False}</td>
				785	<td valign="top">changes the color value of any pixel that matches the color of the target pixel and is a neighbor. If you specify a border color, the color value is changed for any neighbor pixel that is not that color.</td>
				786	</tr>
				787
				788	<tr>
				789	<td valign="top">ForwardFourierTransform</td>
				790	<td valign="top">magnitude=>{True, False}</td>
				791	<td valign="top">implements the forward discrete Fourier transform (DFT)</td>
				792	</tr>
				793
				794	<tr>
				795	<td valign="top">Frame</td>
				796	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, inner=><i>integer</i>, outer=><i>integer</i>, fill=><i><a href="../www/color.html">color name</a></i>, compose=>{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCMYK, Cyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, RGB, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor },</td>
				797	<td valign="top">surround the image with an ornamental border</td>
				798	</tr>
				799
				800	<tr>
				801	<td valign="top">Function</td>
				802	<td valign="top">parameters=><i>array of float values</i>, function=>{Sin}, virtual-pixel=>{Background Black Constant Dither Edge Gray Mirror Random Tile Transparent White}</td>
				803	<td valign="top">apply a function to the image</td>
				804	</tr>
				805
				806	<tr>
				807	<td valign="top">Gamma</td>
				808	<td valign="top">gamma=><i>string</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				809	<td valign="top">gamma correct the image</td>
				810	</tr>
				811
				812	<tr>
				813	<td valign="top">GaussianBlur</td>
				814	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				815	<td valign="top">reduce image noise and reduce detail levels with a Gaussian operator of the given radius and standard deviation (sigma).</td>
				816	</tr>
				817
				818	<tr>
				819	<td valign="top">GetPixel</td>
				820	<td valign="top">geometry=><i>geometry</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, normalize=>{true, false}, x=><i>integer</i>, y=><i>integer</i></td>
				821	<td valign="top">get a single pixel. By default normalized pixel values are returned.</td>
				822	</tr>
				823
				824	<tr>
				825	<td valign="top">GetPixels</td>
				826	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, x=><i>integer</i>, y=><i>integer</i>, map=><i>string</i>, normalize=>{true, false}</td>
				827	<td valign="top">get image pixels as defined by the map (e.g. "RGB", "RGBA", etc.). By default non-normalized pixel values are returned.</td>
				828	</tr>
				829
				830	<tr>
				831	<td valign="top">HaldClut</td>
				832	<td valign="top">image=><i>image-handle</i>, channel=>{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
				833	<td valign="top">apply a Hald color lookup table to an image sequence</td>
				834	</tr>
				835
				836	<tr>
				837	<td valign="top">Identify</td>
cristy	045bd90	2010-01-30 18:56:24 +0000	[diff] [blame]	838	<td valign="top">file=><i>file</i>, features=><i>distance</i>, unique=>{True, False}</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	839	<td valign="top">identify the attributes of an image</td>
				840	</tr>
				841
				842	<tr>
				843	<td valign="top">Implode</td>
				844	<td valign="top">amount=><i>double</i>, interpolate=>{undefined, average, bicubic, bilinear, mesh, nearest-neighbor, spline}</td>
				845	<td valign="top">implode image pixels about the center</td>
				846	</tr>
				847
				848	<tr>
				849	<td valign="top">InverseDiscreteFourierTransform</td>
				850	<td valign="top">magnitude=>{True, False}</td>
				851	<td valign="top">implements the inverse discrete Fourier transform (DFT)</td>
				852	</tr>
				853
				854	<tr>
				855	<td valign="top">Label</td>
				856	<td valign="top">string</td>
				857	<td valign="top">assign a label to an image</td>
				858	</tr>
				859
				860	<tr>
				861	<td valign="top">Layers</td>
				862	<td valign="top">method=>{coalesce, compare-any, compare-clear, compare-over, composite, dispose, flatten, merge, mosaic, optimize, optimize-image, optimize-plus, optimize-trans, remove-dups, remove-zero}, compose=>{Undefined, Add, Atop, Blend, Bumpmap, Clear, ColorBurn, ColorDodge, Colorize, CopyBlack, CopyBlue, CopyCMYK, Cyan, CopyGreen, Copy, CopyMagenta, CopyOpacity, CopyRed, RGB, CopyYellow, Darken, Dst, Difference, Displace, Dissolve, DstAtop, DstIn, DstOut, DstOver, Dst, Exclusion, HardLight, Hue, In, Lighten, LinearLight, Luminize, Minus, Modulate, Multiply, None, Out, Overlay, Over, Plus, ReplaceCompositeOp, Saturate, Screen, SoftLight, Src, SrcAtop, SrcIn, SrcOut, SrcOver, Src, Subtract, Threshold, Xor }, dither=>{true, false}</td>
				863	<td valign="top">compare each image the GIF disposed forms of the previous image in the sequence. From this, attempt to select the smallest cropped image to replace each frame, while preserving the results of the animation.</td>
				864	</tr>
				865
				866	<tr>
				867	<td valign="top">Level</td>
				868	<td valign="top">levels=><i>string</i>, 'black-point'=><i>double</i>, 'gamma'=><i>double</i>, 'white-point'=><i>double</i>, channel=>{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
				869	<td valign="top">adjust the level of image contrast</td>
				870	</tr>
				871
				872	<tr>
cristy	e7f8fdd	2009-09-20 14:43:12 +0000	[diff] [blame]	873	<td valign="top">LevelColors</td>
				874	<td valign="top">invert=>>{True, False}, 'black-point'=><i>string</i>, 'white-point'=><i>string</i>, channel=>{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
				875	<td valign="top">level image with the given colors</td>
				876	</tr>
				877
				878	<tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	879	<td valign="top">LinearStretch</td>
				880	<td valign="top">levels=><i>string</i>, 'black-point'=><i>double</i>, 'white-point'=><i>double</i></td>
				881	<td valign="top">linear with saturation stretch</td>
				882	</tr>
				883
				884	<tr>
				885	<td valign="top">LiquidResize</td>
				886	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, delta-x=><i>double</i>, rigidity=><i>double</i></td>
				887	<td valign="top">rescale image with seam-carving.</td>
				888	</tr>
				889
				890	<tr>
				891	<td valign="top">Magnify</td>
				892	<td valign="top"><br /></td>
				893	<td valign="top">double the size of an image</td>
				894	</tr>
				895
				896	<tr>
				897	<td valign="top">Mask</td>
				898	<td valign="top">mask=><i>image-handle</i></td>
				899	<td valign="top">composite image pixels as defined by the mask</td>
				900	</tr>
				901
				902	<tr>
				903	<td valign="top">MatteFloodfill</td>
				904	<td valign="top">geometry=><i>geometry</i>, x=><i>integer</i>, y=><i>integer</i> , matte=><i>integer</i>, bordercolor=><i><a href="../www/color.html">color name</a></i>, fuzz=><i>double</i>, invert=>{True, False}</td>
				905	<td valign="top">changes the matte value of any pixel that matches the color of the target pixel and is a neighbor. If you specify a border color, the matte value is changed for any neighbor pixel that is not that color.</td>
				906	</tr>
				907
				908	<tr>
				909	<td valign="top">MedianFilter</td>
				910	<td valign="top">radius=><i>double</i></td>
				911	<td valign="top">replace each pixel with the median intensity pixel of a neighborhood.</td>
				912	</tr>
				913
				914	<tr>
				915	<td valign="top">Minify</td>
				916	<td valign="top"><br /></td>
				917	<td valign="top">half the size of an image</td>
				918	</tr>
				919
				920	<tr>
				921	<td valign="top">Modulate</td>
				922	<td valign="top">brightness=><i>double</i>, saturation=><i>double</i>, hue=><i>double</i>, lightness=><i>double</i>, whiteness=><i>double</i>, blackness=><i>double</i> </td>
				923	<td valign="top">vary the brightness, saturation, and hue of an image by the specified percentage</td>
				924	</tr>
				925
				926	<tr>
cristy	488844c	2010-01-22 14:02:05 +0000	[diff] [blame]	927	<td valign="top">Morphology</td>
				928	<td valign="top">kernel=><i>string</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, iterations=><i>integer</i></td>
				929	<td valign="top">apply a morphology method to the image.</td>
				930	</tr>
				931
				932	<tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	933	<td valign="top">MotionBlur</td>
				934	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i>, angle=><i>double</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				935	<td valign="top">reduce image noise and reduce detail levels with a Gaussian operator of the given radius and standard deviation (sigma) at the given angle to simulate the effect of motion</td>
				936	</tr>
				937
				938	<tr>
				939	<td valign="top">Negate</td>
				940	<td valign="top">gray=>{True, False}, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
cristy	b29bc03	2010-02-01 20:29:43 +0000	[diff] [blame]	941	<td valign="top">replace each pixel with its complementary color (white becomes black, yellow becomes blue, etc.)</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	942	</tr>
				943
				944	<tr>
				945	<td valign="top">Normalize</td>
				946	<td valign="top">channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}<br /></td>
				947	<td valign="top">transform image to span the full range of color values</td>
				948	</tr>
				949
				950	<tr>
				951	<td valign="top">OilPaint</td>
				952	<td valign="top">radius=><i>integer</i></td>
				953	<td valign="top">simulate an oil painting</td>
				954	</tr>
				955
				956	<tr>
				957	<td valign="top">Opaque</td>
				958	<td valign="top">color=><i><a href="../www/color.html">color name</a></i>,
				959	fill=><i><a href="../www/color.html">color name</a></i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, invert=>{True, False}</td>
				960	<td valign="top">change this color to the fill color within the image</td>
				961	</tr>
				962
				963	<tr>
				964	<td valign="top">OrderedDither</td>
				965	<td valign="top">threshold=>{threshold, checks, o2x2, o3x3, o4x4, o8x8, h4x4a, h6x6a, h8x8a, h4x4o, h6x6o, h8x8o, h16x16o, hlines6x4}, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				966	<td valign="top">order dither image</td>
				967	</tr>
				968
				969	<tr>
				970	<td valign="top">Polaroid</td>
				971	<td valign="top">caption=><i>string</i>, angle=><i>double</i>, pointsize=><i>double</i>, font=><i>string</i>, stroke=> <i><a href="../www/color.html">color name</a></i>, strokewidth=><i>integer</i>, fill=><i><a href="../www/color.html">color name</a></i>, gravity=>{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}, background=><i><a href="../www/color.html">color name</a></i></td>
				972	<td valign="top">simulate a Polaroid picture.</td>
				973	</tr>
				974
				975	<tr>
				976	<td valign="top">Posterize</td>
				977	<td valign="top">levels=><i>integer</i>, dither=>{True, False}</td>
				978	<td valign="top">reduce the image to a limited number of color level</td>
				979	</tr>
				980
				981	<tr>
				982	<td valign="top">Profile</td>
				983	<td valign="top">name=><i>string</i>, profile=><i>blob</i>, rendering-intent=>{Undefined, Saturation, Perceptual, Absolute, Relative}, black-point-compensation=>{True, False}</td>
				984	<td valign="top">add or remove ICC or IPTC image profile; name is formal name (e.g. ICC or filename; set profile to <kbd>''</kbd> to remove profile</td>
				985	</tr>
				986
				987	<tr>
				988	<td valign="top">Quantize</td>
				989	<td valign="top">colors=><i>integer</i>, colorspace=>{RGB, Gray, Transparent, OHTA, XYZ, YCbCr, YIQ, YPbPr, YUV, CMYK, sRGB, HSL, HSB}, treedepth=> <i>integer</i>, dither=>{True, False}, dither-method=>{Riemersma, Floyd-Steinberg}, measure_error=>{True, False}, global_colormap=>{True, False}, transparent-color=><i>color</i></td>
				990	<td valign="top">preferred number of colors in the image</td>
				991	</tr>
				992
				993	<tr>
				994	<td valign="top">RadialBlur</td>
				995	<td valign="top">angle=><i>double</i></td>
				996	<td valign="top">radial blur the image.</td>
				997	</tr>
				998
				999	<tr>
				1000	<td valign="top">Raise</td>
				1001	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, x=><i>integer</i>, y=><i>integer</i>, raise=>{True, False}</td>
				1002	<td valign="top">lighten or darken image edges to create a 3-D effect</td>
				1003	</tr>
				1004
				1005	<tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1006	<td valign="top">ReduceNoise</td>
				1007	<td valign="top">radius=><i>double</i></td>
				1008	<td valign="top">reduce noise in the image with a noise peak elimination filter</td>
				1009	</tr>
				1010
				1011	<tr>
				1012	<td valign="top">Remap</td>
cristy	8d72405	2009-11-24 20:52:07 +0000	[diff] [blame]	1013	<td valign="top">image=><i>image-handle</i>, dither=>{true, false}, dither-method=>{Riemersma, Floyd-Steinberg}</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1014	<td valign="top">replace the colors of an image with the closest color from a reference image.</td>
				1015	</tr>
				1016
				1017	<tr>
				1018	<td valign="top">Resample</td>
				1019	<td valign="top">density=><i>geometry</i>, x=><i>double</i>, y=><i>double</i>, filter=>{Point, Box, Triangle, Hermite, Hanning, Hamming, Blackman, Gaussian, Quadratic, Cubic, Catrom, Mitchell, Lanczos, Bessel, Sinc}, support=><i>double</i></td>
				1020	<td valign="top">resample image to desired resolution. Specify <kbd>blur</kbd> > 1 for blurry or < 1 for sharp</td>
				1021	</tr>
				1022
				1023	<tr>
				1024	<td valign="top">Resize</td>
				1025	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, filter=>{Point, Box, Triangle, Hermite, Hanning, Hamming, Blackman, Gaussian, Quadratic, Cubic, Catrom, Mitchell, Lanczos, Bessel, Sinc}, support=><i>double</i>, blur=><i>double</i></td>
				1026	<td valign="top">scale image to desired size. Specify <kbd>blur</kbd> > 1 for blurry or < 1 for sharp</td>
				1027	</tr>
				1028
				1029	<tr>
				1030	<td valign="top">Roll</td>
				1031	<td valign="top">geometry=><i>geometry</i>, x=><i>integer</i>, y=><i>integer</i></td>
				1032	<td valign="top">roll an image vertically or horizontally</td>
				1033	</tr>
				1034
				1035	<tr>
				1036	<td valign="top">Rotate</td>
				1037	<td valign="top">degrees=><i>double</i>, background=><i><a href="../www/color.html">color name</a></i></td>
				1038	<td valign="top">rotate an image</td>
				1039	</tr>
				1040
				1041	<tr>
				1042	<td valign="top">Sample</td>
				1043	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i></td>
				1044	<td valign="top">scale image with pixel sampling.</td>
				1045	</tr>
				1046
				1047	<tr>
				1048	<td valign="top">Scale</td>
				1049	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i></td>
				1050	<td valign="top">scale image to desired size</td>
				1051	</tr>
				1052
				1053	<tr>
				1054	<td valign="top">Segment</td>
				1055	<td valign="top">colorspace=>{RGB, Gray, Transparent, OHTA, XYZ, YCbCr, YCC, YIQ, YPbPr, YUV, CMYK}, verbose={True, False}, cluster-threshold=><i>double</i>, smoothing-threshold=<i>double</i></td>
				1056	<td valign="top">segment an image by analyzing the histograms of the color components and identifying units that are homogeneous</td>
				1057	</tr>
				1058
				1059	<tr>
				1060	<td valign="top">SelectiveBlur</td>
				1061	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i>, threshold=><i>double</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				1062	<td valign="top">selectively blur pixels within a contrast threshold.</td>
				1063	</tr>
				1064	<tr>
				1065	<td valign="top">Separate</td>
				1066	<td valign="top">channel=>{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}</td>
				1067	<td valign="top">separate a channel from the image into a grayscale image</td>
				1068	</tr>
				1069
				1070	<tr>
				1071	<td valign="top">Shade</td>
				1072	<td valign="top">geometry=><i>geometry</i>, azimuth=><i>double</i>, elevation=><i>double</i>, gray=>{true, false}</td>
				1073	<td valign="top">shade the image using a distant light source</td>
				1074	</tr>
				1075
				1076	<tr>
				1077	<td valign="top">SetPixel</td>
				1078	<td valign="top">geometry=><i>geometry</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}, color=><i>array of float values</i>, x=><i>integer</i>, y=><i>integer</i>, color=><i>array of float values</i></td>
				1079	<td valign="top">set a single pixel. By default normalized pixel values are expected.</td>
				1080	</tr>
				1081
				1082	<tr>
				1083	<td valign="top">Shadow</td>
				1084	<td valign="top">geometry=><i>geometry</i>, opacity=><i>double</i>, sigma=><i>double</i>, x=><i>integer</i>, y=><i>integer</i></td>
				1085	<td valign="top">simulate an image shadow</td>
				1086	</tr>
				1087
				1088	<tr>
				1089	<td valign="top">Sharpen</td>
				1090	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				1091	<td valign="top">sharpen the image with a Gaussian operator of the given radius and standard deviation (sigma).</td>
				1092	</tr>
				1093
				1094	<tr>
				1095	<td valign="top">Shave</td>
				1096	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i></td>
				1097	<td valign="top">shave pixels from the image edges</td>
				1098	</tr>
				1099
				1100	<tr>
				1101	<td valign="top">Shear</td>
				1102	<td valign="top">geometry=><i>geometry</i>, x=><i>double</i>, y=><i>double</i> fill=><i><a href="../www/color.html">color name</a></i></td>
				1103	<td valign="top">shear the image along the X or Y axis by a positive or negative shear angle</td>
				1104	</tr>
				1105
				1106	<tr>
				1107	<td valign="top">SigmoidalContrast</td>
				1108	<td valign="top">geometry=><i>string</i>, 'contrast'=><i>double</i>, 'mid-point'=><i>double</i> channel=>{Red, RGB, CMYK, Cyan, Green, Magenta, Blue, Yellow, Opacity, Black, or All}, sharpen=>{True, False}</td>
				1109	<td valign="top">sigmoidal non-lineraity contrast control. Increase the contrast of the image using a sigmoidal transfer function without saturating highlights or shadows. <em class="option">Contrast</em> indicates how much to increase the contrast (0 is none; 3 is typical; 20 is a lot); <em class="option">mid-point</em> indicates where midtones fall in the resultant image (0 is white; 50% is middle-gray; 100% is black). To decrease contrast, set sharpen to False.</td>
				1110	</tr>
				1111
				1112	<tr>
				1113	<td valign="top">Signature</td>
				1114	<td valign="top"><br /></td>
				1115	<td valign="top">generate an SHA-256 message digest for the image pixel stream</td>
				1116	</tr>
				1117
				1118	<tr>
				1119	<td valign="top">Sketch</td>
				1120	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i>, angle=><i>double</i></td>
				1121	<td valign="top">sketch the image with a Gaussian operator of the given radius and standard deviation (sigma) at the given angle</td>
				1122	</tr>
				1123
				1124	<tr>
				1125	<td valign="top">Solarize</td>
				1126	<td valign="top">geometry=><i>string</i>,threshold=><i>double</i></td>
				1127	<td valign="top">negate all pixels above the threshold level</td>
				1128	</tr>
				1129
				1130	<tr>
				1131	<td valign="top">SparseColor</td>
				1132	<td valign="top">points=><i>array of float values</i>, method=>{Barycentric, Bilinear, Shepards, Voronoi}, virtual-pixel=>{Background Black Constant Dither Edge Gray Mirror Random Tile Transparent White}</td>
				1133	<td valign="top">interpolate the image colors around the supplied points</td>
				1134	</tr>
				1135
				1136	<tr>
				1137	<td valign="top">Splice</td>
				1138	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, x=><i>integer</i>, y=><i>integer</i>, fuzz=><i>double</i>, background=><i><a href="../www/color.html">color name</a></i>, gravity=>{NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}</td>
				1139	<td valign="top">splice an image</td>
				1140	</tr>
				1141
				1142	<tr>
				1143	<td valign="top">Spread</td>
				1144	<td valign="top">radius=><i>double</i></td>
				1145	<td valign="top">displace image pixels by a random amount</td>
				1146	</tr>
				1147
				1148	<tr>
				1149	<td valign="top">Stegano</td>
				1150	<td valign="top">image=><i>image-handle</i>, offset=><i>integer</i></td>
				1151	<td valign="top">hide a digital watermark within the image</td>
				1152	</tr>
				1153
				1154	<tr>
				1155	<td valign="top">Stereo</td>
				1156	<td valign="top">image=><i>image-handle</i>, x=><i>integer</i>, y=><i>integer</i></td>
				1157	<td valign="top">composites two images and produces a single image that is the composite of a left and right image of a stereo pair</td>
				1158	</tr>
				1159
				1160	<tr>
				1161	<td valign="top">Strip</td>
				1162	<td valign="top"><br /></td>
				1163	<td valign="top">strip an image of all profiles and comments.</td>
				1164	</tr>
				1165
				1166	<tr>
				1167	<td valign="top">Swirl</td>
				1168	<td valign="top">degrees=><i>double</i>, interpolate=>{undefined, average, bicubic, bilinear, mesh, nearest-neighbor, spline}</td>
				1169	<td valign="top">swirl image pixels about the center</td>
				1170	</tr>
				1171
				1172	<tr>
				1173	<td valign="top">Texture</td>
				1174	<td valign="top">texture=><i>image-handle</i></td>
				1175	<td valign="top">name of texture to tile onto the image background</td>
				1176	</tr>
				1177
				1178	<tr>
				1179	<td valign="top">Thumbnail</td>
				1180	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i></td>
				1181	<td valign="top">changes the size of an image to the given dimensions and removes any associated profiles.</td>
				1182	</tr>
				1183
				1184	<tr>
				1185	<td valign="top">Threshold</td>
				1186	<td valign="top">threshold=><i>string</i>, channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
				1187	<td valign="top">threshold the image</td>
				1188	</tr>
				1189
				1190	<tr>
				1191	<td valign="top">Tint</td>
				1192	<td valign="top">fill=><i><a href="../www/color.html">color name</a></i>, opacity=><i>string</i></td>
				1193	<td valign="top">tint the image with the fill color.</td>
				1194	</tr>
				1195
				1196	<tr>
				1197	<td valign="top">Transparent</td>
				1198	<td valign="top">color=><i><a href="../www/color.html">color name</a></i>, invert=>{True, False}</td>
				1199	<td valign="top">make this color transparent within the image</td>
				1200	</tr>
				1201
				1202	<tr>
				1203	<td valign="top">Transpose</td>
				1204	<td valign="top"><br /></td>
				1205	<td valign="top">flip image in the vertical direction and rotate 90 degrees</td>
				1206	</tr>
				1207
				1208	<tr>
				1209	<td valign="top">Transverse</td>
				1210	<td valign="top"><br /></td>
				1211	<td valign="top">flop image in the horizontal direction and rotate 270 degrees</td>
				1212	</tr>
				1213
				1214	<tr>
				1215	<td valign="top">Trim</td>
				1216	<td valign="top"><br /></td>
				1217	<td valign="top">remove edges that are the background color from the image</td>
				1218	</tr>
				1219
				1220	<tr>
				1221	<td valign="top">UnsharpMask</td>
				1222	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i>, amount=><i>double</i>, threshold=><i>double</i></td>
				1223	<td valign="top">sharpen the image with the unsharp mask algorithm.</td>
				1224	</tr>
				1225
				1226	<tr>
				1227	<td valign="top">Vignette</td>
				1228	<td valign="top">geometry=><i>geometry</i>, radius=><i>double</i>, sigma=><i>double</i>, x=><i>integer</i>, y=><i>integer</i>, background=><i><a href="../www/color.html">color name</a></i></td>
				1229	<td valign="top">offset the edges of the image in vignette style</td>
				1230	</tr>
				1231
				1232	<tr>
				1233	<td valign="top">Wave</td>
				1234	<td valign="top">geometry=><i>geometry</i>, amplitude=><i>double</i>, wavelength=><i>double</i>, interpolate=>{undefined, average, bicubic, bilinear, mesh, nearest-neighbor, spline}</td>
				1235	<td valign="top">alter an image along a sine wave</td>
				1236	</tr>
				1237
				1238	<tr>
				1239	<td valign="top">WhiteThreshold</td>
cristy	ec40739	2009-11-28 22:42:05 +0000	[diff] [blame]	1240	<td valign="top">threshold=><i>string</i>, , channel=>{All, Default, Alpha, Black, Blue, CMYK, Cyan, Gray, Green, Index, Magenta, Opacity, Red, RGB, Yellow}</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1241	<td valign="top">force all pixels above the threshold intensity into white</td>
				1242	</tr>
				1243	</tbody>
				1244	</table>
				1245
				1246	<p>Note, that the <kbd>geometry</kbd> parameter is a short cut for the <kbd>width</kbd> and <kbd>height</kbd> parameters (e.g. <kbd>geometry=>'106x80'</kbd> is equivalent to <kbd>width=>106, height=>80</kbd> ).</p>
				1247
				1248	<p>You can specify <kbd>@filename</kbd> in both Annotate() and Draw(). This reads the text or graphic primitive instructions from a file on disk. For example,</p>
				1249
				1250	<pre class="code">
				1251	$image->Draw(fill=>'red', primitive=>'rectangle',
				1252	points=>'20,20 100,100 40,40 200,200 60,60 300,300');
				1253	</pre>
				1254
				1255	<p>Is equivalent to</p>
				1256
				1257	<pre class="code">
				1258	$image->Draw(fill=>'red', primitive=>'@draw.txt');
				1259	</pre>
				1260
				1261	<p>Where <kbd>draw.txt</kbd> is a file on disk that contains this:</p>
				1262
				1263	<pre class="text">
				1264	rectangle 20, 20 100, 100
				1265	rectangle 40, 40 200, 200
				1266	rectangle 60, 60 300, 300
				1267	</pre>
				1268
				1269	<p>The <i>text</i> parameter for methods, Annotate(), Comment(), Draw(), and Label() can include the image filename, type, width, height, or other image attribute by embedding these special format characters:</p>
				1270
				1271	<pre class="text">
				1272	%b file size
				1273	%c comment
				1274	%d directory
				1275	%e filename extension
				1276	%f filename
				1277	%g page geometry
				1278	%h height
				1279	%i input filename
				1280	%k number of unique colors
				1281	%l label
				1282	%m magick
				1283	%n number of scenes
				1284	%o output filename
				1285	%p page number
				1286	%q quantum depth
				1287	%r image class and colorspace
				1288	%s scene number
				1289	%t top of filename
				1290	%u unique temporary filename
				1291	%w width
				1292	%x x resolution
				1293	%y y resolution
				1294	%z image depth
				1295	%C image compression type
				1296	%D image dispose method
				1297	%H page height
				1298	%Q image compression quality
				1299	%T image delay
				1300	%W page width
				1301	%X page x offset
				1302	%Y page y offset
				1303	%@ bounding box
				1304	%# signature
				1305	%% a percent sign
				1306	\n newline
				1307	\r carriage return
				1308	</pre>
				1309
				1310	<p>For example,</p>
				1311
				1312	<pre class="code">
				1313	text=>"%m:%f %wx%h"
				1314	</pre>
				1315
				1316	<p>produces an annotation of <b>MIFF:bird.miff 512x480</b> for an image titled <b>bird.miff</b> and whose width is 512 and height is 480.</p>
				1317
				1318	<p>You can optionally add <i>Image</i> to any method name. For example, TrimImage() is an alias for method Trim().</p>
				1319
				1320	<p>Most of the attributes listed above have an analog in <a href="../www/convert.html">convert</a>. See the documentation for a more detailed description of these attributes.</p>
				1321
				1322	</div>
				1323
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	1324	<h2><a id="set-attribute"></a>Set an Image Attribute</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1325	<div class="doc-section">
				1326
				1327	<p>Use method Set() to set an image attribute. For example,</p>
				1328
				1329	<pre class="code">
				1330	$image->Set(dither=>'True');
				1331	$image->[$x]->Set(delay=>3);
				1332	</pre>
				1333
				1334	<p>Where this example uses 'True' and this document says '{True, False}',
				1335	you can use the case-insensitive strings 'True' and 'False', or you
				1336	can use the integers 1 and 0.</p>
				1337
				1338	<p>When you call Get() on a Boolean attribute, Image::Magick returns 1 or 0, not a string.</p>
				1339
				1340	<p>And here is a list of all the image attributes you can set:</p>
				1341
				1342	<table class="doc">
				1343	<caption>Image Attributes</caption>
				1344	<tbody>
				1345	<tr>
				1346	<th>Attribute</th>
				1347	<th style="width: 40%">Values</th>
				1348	<th style="width: 40%">Description</th>
				1349	</tr>
				1350
				1351	<tr>
				1352	<td valign="top">adjoin</td>
				1353	<td valign="top">{True, False}</td>
				1354	<td valign="top">join images into a single multi-image file</td>
				1355	</tr>
				1356
				1357	<tr>
				1358	<td valign="top">alpha</td>
				1359	<td valign="top">{On, Off, Opaque, Transparent, Copy, Extract, Set}</td>
				1360	<td valign="top">control of and special operations involving the alpha/matte channel</td>
				1361	</tr>
				1362
				1363	<tr>
				1364	<td valign="top">antialias</td>
				1365	<td valign="top">{True, False}</td>
				1366	<td valign="top">remove pixel aliasing</td>
				1367	</tr>
				1368
				1369	<tr>
				1370	<td valign="top">area-limit</td>
				1371	<td valign="top"><i>integer</i></td>
cristy	c1c6166	2009-09-30 14:04:37 +0000	[diff] [blame]	1372	<td valign="top">set pixel area resource limit.</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1373	</tr>
				1374
				1375	<tr>
				1376	<td valign="top">attenuate</td>
				1377	<td valign="top"><i>double</i></td>
				1378	<td valign="top">lessen (or intensify) when adding noise to an image.</td>
				1379	</tr>
				1380
				1381	<tr>
				1382	<td valign="top">authenticate</td>
				1383	<td valign="top"><i>string</i></td>
				1384	<td valign="top">decrypt image with this password.</td>
				1385	</tr>
				1386
				1387	<tr>
				1388	<td valign="top">background</td>
				1389	<td valign="top"><i><a href="../www/color.html">color name</a></i></td>
				1390	<td valign="top">image background color</td>
				1391	</tr>
				1392
				1393	<tr>
				1394	<td valign="top">blue-primary</td>
				1395	<td valign="top"><i>x-value</i>, <i>y-value</i></td>
				1396	<td valign="top">chromaticity blue primary point (e.g. 0.15, 0.06)</td>
				1397	</tr>
				1398
				1399	<tr>
				1400	<td valign="top">bordercolor</td>
				1401	<td valign="top"><i><a href="../www/color.html">color name</a></i></td>
				1402	<td valign="top">set the image border color</td>
				1403	</tr>
				1404
				1405	<tr>
				1406	<td valign="top">clip-mask</td>
				1407	<td valign="top"><i>image</i></td>
				1408	<td valign="top">associate a clip mask with the image.</td>
				1409	</tr>
				1410
				1411	<tr>
				1412	<td valign="top">colormap[<i>i</i>]</td>
				1413	<td valign="top"><i><a href="../www/color.html">color name</a></i></td>
				1414	<td valign="top">color name (e.g. red) or hex value (e.g. #ccc) at position
				1415	<i>i</i></td>
				1416	</tr>
				1417
				1418	<tr>
				1419	<td valign="top">comment</td>
				1420	<td valign="top"><i>string</i></td>
				1421	<td valign="top">set the image comment</td>
				1422	</tr>
				1423
				1424	<tr>
				1425	<td valign="top">compression</td>
				1426	<td valign="top">{None, BZip, Fax, Group4, JPEG, JPEG2000, LosslessJPEG, LZW, RLE, Zip}</td>
				1427	<td valign="top">type of image compression</td>
				1428	</tr>
				1429
				1430	<tr>
				1431	<td valign="top">debug</td>
				1432	<td valign="top">{All, Annotate, Blob, Cache, Coder, Configure, Deprecate, Draw, Exception, Locale, None, Resource, Transform, X11}</td>
				1433	<td valign="top">display copious debugging information</td>
				1434	</tr>
				1435
				1436	<tr>
				1437	<td valign="top">delay</td>
				1438	<td valign="top"><i>integer</i></td>
				1439	<td valign="top">this many 1/100ths of a second must expire before displaying the next image in a sequence</td>
				1440	</tr>
				1441
				1442	<tr>
				1443	<td valign="top">density</td>
				1444	<td valign="top"><i>geometry</i></td>
				1445	<td valign="top">vertical and horizontal resolution in pixels of the image</td>
				1446	</tr>
				1447
				1448	<tr>
				1449	<td valign="top">depth</td>
				1450	<td valign="top"><i>integer</i></td>
				1451	<td valign="top">image depth</td>
				1452	</tr>
				1453
				1454	<tr>
cristy	bebec40	2010-04-23 19:19:08 +0000	[diff] [blame]	1455	<td valign="top">direction</td>
				1456	<td valign="top"><i>{Undefined, right-to-left, left-to-right</i></td>
				1457	<td valign="top">render text right-to-left or left-to-right</td>
				1458	</tr>
				1459
				1460	<tr>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1461	<td valign="top">disk-limit</td>
				1462	<td valign="top"><i>integer</i></td>
cristy	c1c6166	2009-09-30 14:04:37 +0000	[diff] [blame]	1463	<td valign="top">set disk resource limit</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1464	</tr>
				1465
				1466	<tr>
				1467	<td valign="top">dispose</td>
				1468	<td valign="top"><i>{Undefined, None, Background, Previous}</i></td>
				1469	<td valign="top">layer disposal method</td>
				1470	</tr>
				1471
				1472	<tr>
				1473	<td valign="top">dither</td>
				1474	<td valign="top">{True, False}</td>
				1475	<td valign="top">apply error diffusion to the image</td>
				1476	</tr>
				1477
				1478	<tr>
				1479	<td valign="top">display</td>
				1480	<td valign="top"><i>string</i></td>
				1481	<td valign="top">specifies the X server to contact</td>
				1482	</tr>
				1483
				1484	<tr>
				1485	<td valign="top">extract</td>
				1486	<td valign="top"><i>geometry</i></td>
				1487	<td valign="top">extract area from image</td>
				1488	</tr>
				1489
				1490	<tr>
				1491	<td valign="top">file</td>
				1492	<td valign="top"><i>filehandle</i></td>
				1493	<td valign="top">set the image filehandle</td>
				1494	</tr>
				1495
				1496	<tr>
				1497	<td valign="top">filename</td>
				1498	<td valign="top"><i>string</i></td>
				1499	<td valign="top">set the image filename</td>
				1500	</tr>
				1501
				1502	<tr>
				1503	<td valign="top">fill</td>
				1504	<td valign="top"><i>color</i></td>
				1505	<td valign="top">The fill color paints any areas inside the outline of drawn shape.</td>
				1506	</tr>
				1507
				1508	<tr>
				1509	<td valign="top">font</td>
				1510	<td valign="top"><i>string</i></td>
				1511	<td valign="top">use this font when annotating the image with text</td>
				1512	</tr>
				1513
				1514	<tr>
				1515	<td valign="top">fuzz</td>
				1516	<td valign="top"><i>integer</i></td>
				1517	<td valign="top">colors within this distance are considered equal</td>
				1518	</tr>
				1519
				1520	<tr>
				1521	<td valign="top">gamma</td>
				1522	<td valign="top"><i>double</i></td>
				1523	<td valign="top">gamma level of the image</td>
				1524	</tr>
				1525
				1526	<tr>
				1527	<td valign="top">Gravity</td>
				1528	<td valign="top">{Forget, NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast}</td>
				1529	<td valign="top">type of image gravity</td>
				1530	</tr>
				1531
				1532	<tr>
				1533	<td valign="top">green-primary</td>
				1534	<td valign="top"><i>x-value</i>, <i>y-value</i></td>
				1535	<td valign="top">chromaticity green primary point (e.g. 0.3, 0.6)</td>
				1536	</tr>
				1537
				1538	<tr>
				1539	<td valign="top">index[<i>x</i>, <i>y</i>]</td>
				1540	<td valign="top"><i>string</i></td>
				1541	<td valign="top">colormap index at position (<i>x</i>, <i>y</i>)</td>
				1542	</tr>
				1543
				1544	<tr>
				1545	<td valign="top">interlace</td>
				1546	<td valign="top">{None, Line, Plane, Partition, JPEG, GIF, PNG}</td>
				1547	<td valign="top">the type of interlacing scheme</td>
				1548	</tr>
				1549
				1550	<tr>
				1551	<td valign="top">iterations</td>
				1552	<td valign="top"><i>integer</i></td>
				1553	<td valign="top">add Netscape loop extension to your GIF animation</td>
				1554	</tr>
				1555
				1556	<tr>
				1557	<td valign="top">label</td>
				1558	<td valign="top"><i>string</i></td>
				1559	<td valign="top">set the image label</td>
				1560	</tr>
				1561
				1562	<tr>
				1563	<td valign="top">loop</td>
				1564	<td valign="top"><i>integer</i></td>
				1565	<td valign="top">add Netscape loop extension to your GIF animation</td>
				1566	</tr>
				1567
				1568	<tr>
				1569	<td valign="top">magick</td>
				1570	<td valign="top"><i>string</i></td>
				1571	<td valign="top">set the image format</td>
				1572	</tr>
				1573
				1574	<tr>
				1575	<td valign="top">map-limit</td>
				1576	<td valign="top"><i>integer</i></td>
cristy	c1c6166	2009-09-30 14:04:37 +0000	[diff] [blame]	1577	<td valign="top">set map resource limit</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1578	</tr>
				1579
				1580	<tr>
				1581	<td valign="top">mask</td>
				1582	<td valign="top"><i>image</i></td>
				1583	<td valign="top">associate a mask with the image.</td>
				1584	</tr>
				1585
				1586	<tr>
				1587	<td valign="top">matte</td>
				1588	<td valign="top">{True, False}</td>
				1589	<td valign="top">enable the image matte channel</td>
				1590	</tr>
				1591
				1592	<tr>
				1593	<td valign="top">mattecolor</td>
				1594	<td valign="top"><i><a href="../www/color.html">color name</a></i></td>
				1595	<td valign="top">set the image matte color</td>
				1596	</tr>
				1597
				1598	<tr>
				1599	<td valign="top">memory-limit</td>
				1600	<td valign="top"><i>integer</i></td>
cristy	c1c6166	2009-09-30 14:04:37 +0000	[diff] [blame]	1601	<td valign="top">set memory resource limit</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1602	</tr>
				1603
				1604	<tr>
				1605	<td valign="top">monochrome</td>
				1606	<td valign="top">{True, False}</td>
				1607	<td valign="top">transform the image to black and white</td>
				1608	</tr>
				1609
				1610	<tr>
				1611	<td valign="top">option</td>
				1612	<td valign="top"><i>string</i></td>
				1613	<td valign="top">associate an option with an image format (e.g. option=>'ps:imagemask'</td>
				1614	</tr>
				1615
				1616	<tr>
				1617	<td valign="top">orientation</td>
				1618	<td valign="top">{top-left, top-right, bottom-right, bottom-left, left-top, right-top, right-bottom, left-bottom}</td>
				1619	<td valign="top">image orientation</td>
				1620	</tr>
				1621
				1622	<tr>
				1623	<td valign="top">page</td>
				1624	<td valign="top">{ Letter, Tabloid, Ledger, Legal, Statement, Executive, A3, A4, A5, B4, B5, Folio, Quarto, 10x14} or <i>geometry</i></td>
				1625	<td valign="top">preferred size and location of an image canvas</td>
				1626	</tr>
				1627
				1628	<tr>
				1629	<td valign="top">pixel[<i>x</i>, <i>y</i>]</td>
				1630	<td valign="top"><i>string</i></td>
				1631	<td valign="top">hex value (e.g. #ccc) at position (<i>x</i>, <i>y</i>)</td>
				1632	</tr>
				1633
				1634	<tr>
				1635	<td valign="top">pointsize</td>
				1636	<td valign="top"><i>integer</i></td>
				1637	<td valign="top">pointsize of the Postscript or TrueType font</td>
				1638	</tr>
				1639
				1640	<tr>
				1641	<td valign="top">quality</td>
				1642	<td valign="top"><i>integer</i></td>
				1643	<td valign="top">JPEG/MIFF/PNG compression level</td>
				1644	</tr>
				1645
				1646	<tr>
				1647	<td valign="top">red-primary</td>
				1648	<td valign="top"><i>x-value</i>, <i>y-value</i></td>
				1649	<td valign="top">chromaticity red primary point (e.g. 0.64, 0.33)</td>
				1650	</tr>
				1651
				1652	<tr>
				1653	<td valign="top">sampling-factor</td>
				1654	<td valign="top"><i>geometry</i></td>
				1655	<td valign="top">horizontal and vertical sampling factor</td>
				1656	</tr>
				1657
				1658	<tr>
				1659	<td valign="top">scene</td>
				1660	<td valign="top"><i>integer</i></td>
				1661	<td valign="top">image scene number</td>
				1662	</tr>
				1663
				1664	<tr>
				1665	<td valign="top">server</td>
				1666	<td valign="top"><i>string</i></td>
				1667	<td valign="top">specifies the X server to contact</td>
				1668	</tr>
				1669
				1670	<tr>
				1671	<td valign="top">size</td>
				1672	<td valign="top"><i>string</i></td>
				1673	<td valign="top">width and height of a raw image</td>
				1674	</tr>
				1675
				1676	<tr>
				1677	<td valign="top">stroke</td>
				1678	<td valign="top"><i>color</i></td>
				1679	<td valign="top">The stroke color paints along the outline of a shape.</td>
				1680	</tr>
				1681
				1682	<tr>
				1683	<td valign="top">texture</td>
				1684	<td valign="top"><i>string</i></td>
				1685	<td valign="top">name of texture to tile onto the image background</td>
				1686	</tr>
				1687
				1688	<tr>
				1689	<td valign="top">tile-offset</td>
				1690	<td valign="top"><i>geometry</i></td>
				1691	<td valign="top">image tile offset</td>
				1692	</tr>
				1693
				1694	<tr>
				1695	<td valign="top">time-limit</td>
				1696	<td valign="top"><i>integer</i></td>
				1697	<td valign="top">set time resource limit in seconds</td>
				1698	</tr>
				1699
				1700	<tr>
				1701	<td valign="top">type</td>
cristy	efb2bdb	2010-11-20 19:35:22 +0000	[diff] [blame]	1702	<td valign="top">{Bilevel, Grayscale, GrayscaleMatte, Palette, PaletteMatte, TrueColor, TrueColorMatte, ColorSeparation, ColorSeparationMatte}</td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1703	<td valign="top">image type</td>
				1704	</tr>
				1705
				1706	<tr>
				1707	<td valign="top">units</td>
				1708	<td valign="top">{ Undefined, PixelsPerInch, PixelsPerCentimeter}</td>
				1709	<td valign="top">units of image resolution</td>
				1710	</tr>
				1711
				1712	<tr>
				1713	<td valign="top">verbose</td>
				1714	<td valign="top">{True, False}</td>
				1715	<td valign="top">print detailed information about the image</td>
				1716	</tr>
				1717
				1718	<tr>
				1719	<td valign="top">virtual-pixel</td>
				1720	<td valign="top">{Background Black Constant Dither Edge Gray Mirror Random Tile Transparent White}</td>
				1721	<td valign="top">the virtual pixel method</td>
				1722	</tr>
				1723
				1724	<tr>
				1725	<td valign="top">white-point</td>
				1726	<td valign="top"><i>x-value</i>, <i>y-value</i></td>
				1727	<td valign="top">chromaticity white point (e.g. 0.3127, 0.329)</td>
				1728	</tr>
				1729	</tbody>
				1730	</table>
				1731
				1732	<p>Note, that the <kbd>geometry</kbd> parameter is a short cut for the <kbd>width</kbd> and <kbd>height</kbd> parameters (e.g. <kbd>geometry=>'106x80'</kbd> is equivalent to <kbd>width=>106, height=>80</kbd>).</p>
				1733
				1734	<p>SetAttribute() is an alias for method Set().</p>
				1735
				1736	<p>Most of the attributes listed above have an analog in
				1737	<a href="../www/convert.html">convert</a>. See the documentation for a more detailed description of these attributes.</p>
				1738
				1739	</div>
				1740
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	1741	<h2><a id="get-attribute"></a>Get an Image Attribute</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1742	<div class="doc-section">
				1743
				1744	<p>Use method Get() to get an image attribute. For example,</p>
				1745
				1746	<pre class="code">
				1747	($a, $b, $c) = $image->Get('colorspace', 'magick', 'adjoin');
				1748	$width = $image->[3]->Get('columns');
				1749	</pre>
				1750
				1751	<p>In addition to all the attributes listed in <a href="#set-attribute">Set an Image Attribute</a> , you can get these additional attributes:</p>
				1752
				1753	<table class="doc">
				1754	<caption>Image Attributes</caption>
				1755	<tbody>
				1756	<tr>
				1757	<th>Attribute</th>
				1758	<th>Values</th>
				1759	<th style="width: 60%">Description</th>
				1760	</tr>
				1761
				1762	<tr>
				1763	<td valign="top">area</td>
				1764	<td valign="top"><i>integer</i></td>
				1765	<td valign="top">current area resource consumed</td>
				1766	</tr>
				1767
				1768	<tr>
				1769	<td valign="top">base-columns</td>
				1770	<td valign="top"><i>integer</i></td>
				1771	<td valign="top">base image width (before transformations)</td>
				1772	</tr>
				1773
				1774	<tr>
				1775	<td valign="top">base-filename</td>
				1776	<td valign="top"><i>string</i></td>
				1777	<td valign="top">base image filename (before transformations)</td>
				1778	</tr>
				1779
				1780	<tr>
				1781	<td valign="top">base-rows</td>
				1782	<td valign="top"><i>integer</i></td>
				1783	<td valign="top">base image height (before transformations)</td>
				1784	</tr>
				1785
				1786	<tr>
				1787	<td valign="top">class</td>
				1788	<td valign="top">{Direct, Pseudo}</td>
				1789	<td valign="top">image class</td>
				1790	</tr>
				1791
				1792	<tr>
				1793	<td valign="top">colors</td>
				1794	<td valign="top"><i>integer</i></td>
				1795	<td valign="top">number of unique colors in the image</td>
				1796	</tr>
				1797
				1798	<tr>
				1799	<td valign="top">columns</td>
				1800	<td valign="top"><i>integer</i></td>
				1801	<td valign="top">image width</td>
				1802	</tr>
				1803
				1804	<tr>
				1805	<td valign="top">copyright</td>
				1806	<td valign="top"><i>string</i></td>
				1807	<td valign="top">get PerlMagick's copyright</td>
				1808	</tr>
				1809
				1810	<tr>
				1811	<td valign="top">directory</td>
				1812	<td valign="top"><i>string</i></td>
				1813	<td valign="top">tile names from within an image montage</td>
				1814	</tr>
				1815
				1816	<tr>
				1817	<td valign="top">elapsed-time</td>
				1818	<td valign="top"><i>double</i></td>
				1819	<td valign="top">elapsed time in seconds since the image was created</td>
				1820	</tr>
				1821
				1822	<tr>
				1823	<td valign="top">error</td>
				1824	<td valign="top"><i>double</i></td>
				1825	<td valign="top">the mean error per pixel computed with methods Compare() or Quantize()</td>
				1826	</tr>
				1827
				1828	<tr>
				1829	<td valign="top">bounding-box</td>
				1830	<td valign="top"><i>string</i></td>
				1831	<td valign="top">image bounding box</td>
				1832	</tr>
				1833
				1834	<tr>
				1835	<td valign="top">disk</td>
				1836	<td valign="top"><i>integer</i></td>
				1837	<td valign="top">current disk resource consumed</td>
				1838	</tr>
				1839
				1840	<tr>
				1841	<td valign="top">filesize</td>
				1842	<td valign="top"><i>integer</i></td>
				1843	<td valign="top">number of bytes of the image on disk</td>
				1844	</tr>
				1845
				1846	<tr>
				1847	<td valign="top">format</td>
				1848	<td valign="top"><i>string</i></td>
				1849	<td valign="top">get the descriptive image format</td>
				1850	</tr>
				1851
				1852	<tr>
				1853	<td valign="top">geometry</td>
				1854	<td valign="top"><i>string</i></td>
				1855	<td valign="top">image geometry</td>
				1856	</tr>
				1857
				1858	<tr>
				1859	<td valign="top">height</td>
				1860	<td valign="top"><i>integer</i></td>
				1861	<td valign="top">the number of rows or height of an image</td>
				1862	</tr>
				1863
				1864	<tr>
				1865	<td valign="top">id</td>
				1866	<td valign="top"><i>integer</i></td>
				1867	<td valign="top">ImageMagick registry id</td>
				1868	</tr>
				1869
				1870	<tr>
				1871	<td valign="top">mean-error</td>
				1872	<td valign="top"><i>double</i></td>
				1873	<td valign="top">the normalized mean error per pixel computed with methods Compare() or Quantize()</td>
				1874	</tr>
				1875
				1876	<tr>
				1877	<td valign="top">map</td>
				1878	<td valign="top"><i>integer</i></td>
				1879	<td valign="top">current memory-mapped resource consumed</td>
				1880	</tr>
				1881
				1882	<tr>
				1883	<td valign="top">matte</td>
				1884	<td valign="top">{True, False}</td>
				1885	<td valign="top">whether or not the image has a matte channel</td>
				1886	</tr>
				1887
				1888	<tr>
				1889	<td valign="top">maximum-error</td>
				1890	<td valign="top"><i>double</i></td>
				1891	<td valign="top">the normalized max error per pixel computed with methods Compare() or Quantize()</td>
				1892	</tr>
				1893
				1894	<tr>
				1895	<td valign="top">memory</td>
				1896	<td valign="top"><i>integer</i></td>
				1897	<td valign="top">current memory resource consumed</td>
				1898	</tr>
				1899
				1900	<tr>
				1901	<td valign="top">mime</td>
				1902	<td valign="top"><i>string</i></td>
				1903	<td valign="top">MIME of the image format</td>
				1904	</tr>
				1905
				1906	<tr>
				1907	<td valign="top">montage</td>
				1908	<td valign="top"><i>geometry</i></td>
				1909	<td valign="top">tile size and offset within an image montage</td>
				1910	</tr>
				1911
				1912	<tr>
				1913	<td valign="top">page.x</td>
				1914	<td valign="top"><i>integer</i></td>
				1915	<td valign="top">x offset of image virtual canvas</td>
				1916	</tr>
				1917
				1918	<tr>
				1919	<td valign="top">page.y</td>
				1920	<td valign="top"><i>integer</i></td>
				1921	<td valign="top">y offset of image virtual canvas</td>
				1922	</tr>
				1923
				1924	<tr>
				1925	<td valign="top">rows</td>
				1926	<td valign="top"><i>integer</i></td>
				1927	<td valign="top">the number of rows or height of an image</td>
				1928	</tr>
				1929
				1930	<tr>
				1931	<td valign="top">signature</td>
				1932	<td valign="top"><i>string</i></td>
				1933	<td valign="top">SHA-256 message digest associated with the image pixel stream</td>
				1934	</tr>
				1935
				1936	<tr>
				1937	<td valign="top">taint</td>
				1938	<td valign="top">{True, False}</td>
				1939	<td valign="top">True if the image has been modified</td>
				1940	</tr>
				1941
				1942	<tr>
				1943	<td valign="top">total-ink-density</td>
				1944	<td valign="top"><i>double</i></td>
				1945	<td valign="top">returns the total ink density for a CMYK image</td>
				1946	</tr>
				1947
				1948	<tr>
				1949	<td valign="top">transparent-color</td>
				1950	<td valign="top"><i><a href="../www/color.html">color name</a></i></td>
				1951	<td valign="top">set the image transparent color</td>
				1952	</tr>
				1953
				1954	<tr>
				1955	<td valign="top">user-time</td>
				1956	<td valign="top"><i>double</i></td>
				1957	<td valign="top">user time in seconds since the image was created</td>
				1958	</tr>
				1959
				1960	<tr>
				1961	<td valign="top">version</td>
				1962	<td valign="top"><i>string</i></td>
				1963	<td valign="top">get PerlMagick's version</td>
				1964	</tr>
				1965
				1966	<tr>
				1967	<td valign="top">width</td>
				1968	<td valign="top"><i>integer</i></td>
				1969	<td valign="top">the number of columns or width of an image</td>
				1970	</tr>
				1971
				1972	<tr>
				1973	<td valign="top">x-resolution</td>
				1974	<td valign="top"><i>integer</i></td>
				1975	<td valign="top">x resolution of the image</td>
				1976	</tr>
				1977
				1978	<tr>
				1979	<td valign="top">y-resolution</td>
				1980	<td valign="top"><i>integer</i></td>
				1981	<td valign="top">y resolution of the image</td>
				1982	</tr>
				1983	</tbody>
				1984	</table>
				1985
				1986	<p>GetAttribute() is an alias for method Get().</p>
				1987
				1988	<p>Most of the attributes listed above have an analog in
				1989	<a href="../www/convert.html">convert</a>. See the documentation for a more detailed description of these attributes.</p>
				1990
				1991	</div>
				1992
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	1993	<h2><a id="compare"></a>Compare an Image to its Reconstruction</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	1994	<div class="doc-section">
				1995	</div>
				1996
				1997	<p>Mathematically and visually annotate the difference between an image and its reconstruction with the Compare() method. The method supports these parameters:</p>
				1998
				1999	<table class="doc">
				2000	<caption>Compare Parameters</caption>
				2001	<tbody>
				2002	<tr>
				2003	<th>Parameter</th>
				2004	<th style="width: 40%">Values</th>
				2005	<th style="width: 40%">Description</th>
				2006	</tr>
				2007
				2008	<tr>
				2009	<td valign="top">channel</td>
				2010	<td valign="top"><i>double</i></td>
				2011	<td valign="top">select image channels, the default is all channels except alpha.</td>
				2012	</tr>
				2013
				2014	<tr>
				2015	<td valign="top">fuzz</td>
				2016	<td valign="top"><i>double</i></td>
				2017	<td valign="top">colors within this distance are considered equal</td>
				2018	</tr>
				2019
				2020	<tr>
				2021	<td valign="top">image</td>
				2022	<td valign="top"><i>image-reference</i></td>
				2023	<td valign="top">the image reconstruction</td>
				2024	</tr>
				2025
				2026	<tr>
				2027	<td valign="top">metric</td>
				2028	<td valign="top">AE, MAE, MEPP, MSE, PAE, PSNR, RMSE</td>
				2029	<td valign="top">measure differences between images with this metric</td>
				2030	</tr>
				2031	</tbody>
				2032	</table>
				2033
				2034	<p>In this example, we compare the ImageMagick logo to a sharpened reconstruction:</p>
				2035
				2036	<pre class="code">
				2037	use Image::Magick;
				2038
				2039	$logo=Image::Magick->New();
				2040	$logo->Read('logo:');
				2041	$sharp=Image::Magick->New();
				2042	$sharp->Read('logo:');
				2043	$sharp->Sharpen('0x1');
				2044	$difference=$logo->Compare(image=>$sharp, metric=>'rmse');
				2045	print $difference->Get('error'), "\n";
				2046	$difference->Display();
				2047	</pre>
				2048
				2049	<p>In addition to the reported root mean squared error of around 0.024, a difference image is displayed so you can visually identify the difference between the images.</p>
				2050
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	2051	<h2><a id="montage"></a>Create an Image Montage</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2052	<div class="doc-section">
				2053
				2054	<p>Use method Montage() to create a composite image by combining several separate images. The images are tiled on the composite image with the name of the image optionally appearing just below the individual tile. For example,</p>
				2055
				2056	<pre class="code">
				2057	$image->Montage(geometry=>'160x160', tile=>'2x2', texture=>'granite:');
				2058	</pre>
				2059
				2060	<p>And here is a list of Montage() parameters you can set:</p>
				2061
				2062	<table class="doc">
				2063	<caption>Montage Parameters</caption>
				2064	<tbody>
				2065	<tr>
				2066	<th>Parameter</th>
				2067	<th style="width: 40%">Values</th>
				2068	<th style="width: 40%">Description</th>
				2069	</tr>
				2070
				2071	<tr>
				2072	<td valign="top">background</td>
				2073	<td valign="top"><i><a href="../www/color.html">color name</a></i></td>
				2074	<td valign="top">background color name</td>
				2075	</tr>
				2076
				2077	<tr>
				2078	<td valign="top">border</td>
				2079	<td valign="top"><i>integer</i></td>
				2080	<td valign="top">image border width</td>
				2081	</tr>
				2082
				2083	<tr>
				2084	<td valign="top">filename</td>
				2085	<td valign="top"><i>string</i></td>
				2086	<td valign="top">name of montage image</td>
				2087	</tr>
				2088
				2089	<tr>
				2090	<td valign="top">fill</td>
				2091	<td valign="top"><a href="../www/color.html">color name</a></td>
				2092	<td valign="top">fill color for annotations</td>
				2093	</tr>
				2094
				2095	<tr>
				2096	<td valign="top">font</td>
				2097	<td valign="top"><i>string</i></td>
				2098	<td valign="top">X11 font name</td>
				2099	</tr>
				2100
				2101	<tr>
				2102	<td valign="top">frame</td>
				2103	<td valign="top"><i>geometry</i></td>
				2104	<td valign="top">surround the image with an ornamental border</td>
				2105	</tr>
				2106
				2107	<tr>
				2108	<td valign="top">geometry</td>
				2109	<td valign="top"><i>geometry</i></td>
				2110	<td valign="top">preferred tile and border size of each tile of the composite
				2111	image (e.g. 120x120+4+3>)</td>
				2112	</tr>
				2113
				2114	<tr>
				2115	<td valign="top">gravity</td>
				2116	<td valign="top">NorthWest, North, NorthEast, West, Center, East, SouthWest,
				2117	South, SouthEast</td>
				2118	<td valign="top">direction image gravitates to within a tile</td>
				2119	</tr>
				2120
				2121	<tr>
				2122	<td valign="top">label</td>
				2123	<td valign="top"><i>string</i></td>
				2124	<td valign="top">assign a label to an image</td>
				2125	</tr>
				2126
				2127	<tr>
				2128	<td valign="top">mode</td>
				2129	<td valign="top">Frame, Unframe, Concatenate</td>
				2130	<td valign="top">thumbnail framing options</td>
				2131	</tr>
				2132
				2133	<tr>
				2134	<td valign="top">pointsize</td>
				2135	<td valign="top"><i>integer</i></td>
				2136	<td valign="top">pointsize of the Postscript or TrueType font</td>
				2137	</tr>
				2138
				2139	<tr>
				2140	<td valign="top">shadow</td>
				2141	<td valign="top">{True, False}</td>
				2142	<td valign="top">add a shadow beneath a tile to simulate depth</td>
				2143	</tr>
				2144
				2145	<tr>
				2146	<td valign="top">stroke</td>
				2147	<td valign="top"><a href="../www/color.html">color name</a></td>
				2148	<td valign="top">stroke color for annotations</td>
				2149	</tr>
				2150
				2151	<tr>
				2152	<td valign="top">texture</td>
				2153	<td valign="top"><i>string</i></td>
				2154	<td valign="top">name of texture to tile onto the image background</td>
				2155	</tr>
				2156
				2157	<tr>
				2158	<td valign="top">tile</td>
				2159	<td valign="top"><i>geometry</i></td>
				2160	<td valign="top">the number of tiles per row and page (e.g. 6x4)</td>
				2161	</tr>
				2162
				2163	<tr>
				2164	<td valign="top">title</td>
				2165	<td valign="top">string</td>
				2166	<td valign="top">assign a title to the image montage</td>
				2167	</tr>
				2168
				2169	<tr>
				2170	<td valign="top">transparent</td>
				2171	<td valign="top"><i>string</i></td>
				2172	<td valign="top">make this color transparent within the image</td>
				2173	</tr>
				2174	</tbody>
				2175	</table>
				2176
				2177	<p>Note, that the <kbd>geometry</kbd> parameter is a short cut for the <kbd>width</kbd> and <kbd>height</kbd> parameters (e.g. <kbd>geometry=>'106x80'</kbd> is equivalent to <kbd>width=>106, height=>80</kbd>).</p>
				2178
				2179	<p>MontageImage() is an alias for method Montage().</p>
				2180
				2181	<p>Most of the attributes listed above have an analog in <a href="../www/montage.html">montage</a>. See the documentation for a more detailed description of these attributes.</p>
				2182
				2183	</div>
				2184
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	2185	<h2><a id="blobs"></a>Working with Blobs</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2186	<div class="doc-section">
				2187
				2188	<p>A blob contains data that directly represent a particular image
				2189	format in memory instead of on disk. PerlMagick supports
				2190	blobs in any of these image <a href="../www/formats.html">formats</a> and provides methods to convert a blob to or from a particular image format.</p>
				2191
				2192	<table class="doc">
				2193	<caption>Blob Methods</caption>
				2194	<tbody>
				2195	<tr>
				2196	<th>Method</th>
				2197	<th>Parameters</th>
				2198	<th>Return Value</th>
				2199	<th>Description</th>
				2200	</tr>
				2201
				2202	<tr>
				2203	<td valign="top">ImageToBlob</td>
				2204	<td valign="top">any image <a href="#set-attribute">attribute</a></td>
				2205	<td valign="top">an array of image data in the respective image format</td>
				2206	<td valign="top">convert an image or image sequence to an array of blobs</td>
				2207	</tr>
				2208
				2209	<tr>
				2210	<td valign="top">BlobToImage</td>
				2211	<td valign="top">one or more blobs</td>
				2212	<td valign="top">the number of blobs converted to an image</td>
				2213	<td valign="top">convert one or more blobs to an image</td>
				2214	</tr>
				2215	</tbody>
				2216	</table>
				2217
				2218	<p>ImageToBlob() returns the image data in their respective formats. You can then print it, save it to an ODBC database, write it to a file, or pipe it to a display program:</p>
				2219
				2220	<pre class="code">
				2221	@blobs = $image->ImageToBlob();
				2222	open(DISPLAY,"\| display -") \|\| die;
				2223	binmode DISPLAY;
				2224	print DISPLAY $blobs[0];
				2225	close DISPLAY;
				2226	</pre>
				2227
				2228	<p>Method BlobToImage() returns an image or image sequence converted from the supplied blob:</p>
				2229
				2230	<pre class="code">
				2231	@blob=$db->GetImage();
				2232	$image=Image::Magick->new(magick=>'jpg');
				2233	$image->BlobToImage(@blob);
				2234	</pre>
				2235
				2236	</div>
				2237
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	2238	<h2><a id="direct-access"></a>Direct-access to Image Pixels</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2239	<div class="doc-section">
				2240
				2241	<p>Use these methods to obtain direct access to the image pixels:</p>
				2242
				2243	<table class="doc">
				2244	<caption>Direct-access to Image Pixels</caption>
				2245	<tbody>
				2246	<tr>
				2247	<th>Method</th>
				2248	<th>Parameters</th>
				2249	<th style="width: 50%">Description</th>
				2250	</tr>
				2251
				2252	<tr>
				2253	<td valign="top">GetAuthenticPixels</td>
				2254	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, x=><i>integer</i>, y=><i>integer</i></td>
				2255	<td valign="top">return image pixels as a C pointer</td>
				2256	</tr>
				2257
				2258	<tr>
				2259	<td valign="top">GetVirtualPixels</td>
				2260	<td valign="top">geometry=><i>geometry</i>, width=><i>integer</i>, height=><i>integer</i>, x=><i>integer</i>, y=><i>integer</i></td>
				2261	<td valign="top">return image pixels as a const C pointer</td>
				2262	</tr>
				2263
				2264	<tr>
				2265	<td valign="top">GetAuthenticIndexQueue</td>
cristy	48dd1af	2009-10-02 01:21:56 +0000	[diff] [blame]	2266	<td valign="top"></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2267	<td valign="top">return image indexes as a C pointer</td>
				2268	</tr>
				2269
				2270	<tr>
				2271	<td valign="top">GetVirtualIndexQueue</td>
cristy	48dd1af	2009-10-02 01:21:56 +0000	[diff] [blame]	2272	<td valign="top"></td>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2273	<td valign="top">return image indexes as a const C pointer</td>
				2274	</tr>
				2275
				2276	<tr>
				2277	<td valign="top">SyncAuthenticPixels</td>
				2278	<td valign="top"></td>
				2279	<td valign="top">sync image pixels to pixel cache</td>
				2280	</tr>
				2281
				2282	</tbody>
				2283	</table>
				2284
				2285	</div>
				2286
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	2287	<h2><a id="miscellaneous"></a>Miscellaneous Methods</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2288	<div class="doc-section">
				2289
				2290	<p>The Append() method append a set of images. For example,</p>
				2291
				2292	<pre class="code">
				2293	$p = $image->Append(stack=>{true,false});
				2294	</pre>
				2295
				2296	<p>appends all the images associated with object <kbd>$image</kbd>. By default, images are stacked left-to-right. Set <kbd>stack</kbd> to True to stack them top-to-bottom.</p>
				2297
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2298	<p>The Clone() method copies a set of images. For example,</p>
				2299
				2300	<pre class="code">
				2301	$q = $p->Clone();
				2302	</pre>
				2303
				2304	<p>copies all the images from object <kbd>$p</kbd> to <kbd>$q</kbd>. You can use this method for single or multi-image sequences.</p>
				2305
cristy	63fed27	2010-03-07 19:08:45 +0000	[diff] [blame]	2306	<p>The EvaluateImages() method applies an arithemtic, logical or relational expression to a set of images. For example,</p>
				2307
				2308	<pre class="code">
				2309	$p = $image->EvaluateImages('mean');
				2310	</pre>
				2311
				2312	<p>averages all the images associated with object <kbd>$image</kbd>.</p>
				2313
cristy	7396d88	2010-01-27 02:37:56 +0000	[diff] [blame]	2314	<p>The Features() method returns features for each channel in the image in each of four directions (horizontal, vertical, left and right diagonals) for the specified distance. The features include the angular second momentum, contrast, correlation, sum of squares: variance, inverse difference moment, sum average, sum varience, sum entropy, entropy, difference variance, difference entropy, information measures of correlation 1, information measures of correlation 2, and maximum correlation coefficient. Values in RGB, CMYK, RGBA, or CMYKA order (depending on the image type).</p>
				2315
				2316	<pre class="code">
				2317	@features = $image->Features(1);
				2318	</pre>
				2319
				2320	<p>Finally, the Transform() method accepts a fully-qualified geometry specification for cropping or resizing one or more images. For example,</p>
				2321
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2322	<p>The Flatten() method flattens a set of images and returns it. For example,</p>
				2323
				2324	<pre class="code">
				2325	$p = $images->Flatten(background=>'none');
				2326	$p->Write('flatten.png');
				2327	</pre>
				2328
				2329	<p>The sequence of images is replaced by a single image created by composing each image after the first over the first image.</p>
				2330
				2331	<p>The Fx() method applies a mathematical expression to a set of images and returns the results. For example,</p>
				2332
				2333	<pre class="code">
				2334	$p = $image->Fx(expression=>'(g+b)/2.0',channel=>'red');
				2335	$p->Write('fx.miff');
				2336	</pre>
				2337
				2338	<p>replaces the red channel with the average of the green and blue channels.</p>
				2339
				2340	<p>See <a href="../www/fx.html">FX, The Special Effects Image Operator</a> for a detailed discussion of this method.</p>
				2341
				2342	<p>Histogram() returns the unique colors in the image and a count for each one. The returned values are an array of red, green, blue, opacity, and count values.</p>
				2343
				2344	<p>The Morph() method morphs a set of images. Both the image pixels and size are linearly interpolated to give the appearance of a meta-morphosis from one image to the next:</p>
				2345
				2346	<pre class="code">
				2347	$p = $image->Morph(frames=><i>integer</i>);
				2348	</pre>
				2349
				2350	<p>where <i>frames</i> is the number of in-between images to generate. The default is 1.</p>
				2351
				2352	<p>Mosaic() creates an mosaic from an image sequence.</p>
				2353
				2354	<p>Method Mogrify() is a single entry point for the image manipulation methods (<a href="#manipulate">Manipulate an Image</a>). The parameters are the name of a method followed by any parameters the method may require. For example, these calls are equivalent:</p>
				2355
				2356	<pre class="code">
				2357	$image->Crop('340x256+0+0');
				2358	$image->Mogrify('crop', '340x256+0+0');
				2359	</pre>
				2360
				2361	<p>Method MogrifyRegion() applies a transform to a region of the image. It is similar to Mogrify() but begins with the region geometry. For example, suppose you want to brighten a 100x100 region of your image at location (40, 50):</p>
				2362
				2363	<pre class="code">
				2364	$image->MogrifyRegion('100x100+40+50', 'modulate', brightness=>50);
				2365	</pre>
				2366
				2367	<p>Ping() is a convenience method that returns information about an image without having to read the image into memory. It returns the width, height, file size in bytes, and the file format of the image. You can specify more than one filename but only one filehandle:</p>
				2368
				2369	<pre class="code">
				2370	($width, $height, $size, $format) = $image->Ping('logo.png');
				2371	($width, $height, $size, $format) = $image->Ping(file=>\*IMAGE);
				2372	($width, $height, $size, $format) = $image->Ping(blob=>$blob);
				2373	</pre>
				2374
				2375	<p>This a more efficient and less memory intensive way to query if an image exists and what its characteristics are. <kbd>PreviewImage()</kbd> tiles 9 thumbnails of the specified image with an image processing operation applied at varying strengths. This may be helpful pin-pointing an appropriate parameter for a particular image processing operation. Choose from these operations: <kbd>Rotate, Shear, Roll, Hue, Saturation, Brightness, Gamma, Spiff, Dull, Grayscale, Quantize, Despeckle, ReduceNoise, AddNoise, Sharpen, Blur, Threshold, EdgeDetect, Spread, Solarize, Shade, Raise, Segment, Swirl, Implode, Wave, OilPaint, CharcoalDrawing, JPEG</kbd>. Here is an example:</p>
				2376
				2377	<pre class="code">
				2378	$preview = $image->Preview('Gamma');
				2379	$preview->Display();
				2380	</pre>
				2381
				2382	<p>To have full control over text positioning you need font metric information. Use</p>
				2383
				2384	<pre class="code">
				2385	($x_ppem, $y_ppem, $ascender, $descender, $width, $height, $max_advance)
				2386	= $image->QueryFontMetrics(<i>parameters</i>);
				2387	</pre>
				2388
				2389	<p>Where <i>parameters</i> is any parameter of the <a href="#manipulate">Annotate</a> method. The return values are:</p>
				2390
				2391	<ul>
				2392	<li>character width</li>
				2393	<li>character height</li>
				2394	<li>ascender</li>
				2395	<li>descender</li>
				2396	<li>text width</li>
				2397	<li>text height</li>
				2398	<li>maximum horizontal advance</li>
				2399	<li>bounds: x1</li>
				2400	<li>bounds: y1</li>
				2401	<li>bounds: x2</li>
				2402	<li>bounds: y2</li>
				2403	<li>origin: x</li>
				2404	<li>origin: y</li>
				2405	</ul>
				2406
				2407	<p>Use QueryMultilineFontMetrics() to get the maximum text width and height for multiple lines of text.</p>
				2408
				2409	<p>Call QueryColor() with no parameters to return a list of known colors names or specify one or more color names to get these attributes: red, green, blue, and opacity value.</p>
				2410
				2411	<pre class="code">
				2412	@colors = $image->QueryColor();
				2413	($red, $green, $blue, $opacity) = $image->QueryColor('cyan');
				2414	($red, $green, $blue, $opacity) = $image->QueryColor('#716bae');
				2415	</pre>
				2416
				2417	<p>QueryColorname() accepts a color value and returns its respective name or hex value;</p>
				2418
				2419	<pre class="code">
				2420	$name = $image->QueryColorname('rgba(80,60,0,0)');
				2421	</pre>
				2422
				2423	<p>Call QueryFont() with no parameters to return a list of known fonts or specify one or more font names to get these attributes: font name, description, family, style, stretch, weight, encoding, foundry, format, metrics, and glyphs values.</p>
				2424
				2425	<pre class="code">
				2426	@fonts = $image->QueryFont();
				2427	$weight = ($image->QueryFont('Helvetica'))[5];
				2428	</pre>
				2429
				2430	<p>Call QueryFormat() with no parameters to return a list of known image formats or specify one or more format names to get these attributes: adjoin, blob support, raw, decoder, encoder, description, and module.</p>
				2431
				2432	<pre class="code">
				2433	@formats = $image->QueryFormat();
				2434	($adjoin, $blob_support, $raw, $decoder, $encoder, $description, $module)
				2435	= $image->QueryFormat('gif');
				2436	</pre>
				2437
				2438	<p>Call MagickToMime() with the image format name to get its MIME type such as <kbd>images/tiff</kbd> from <kbd>tif</kbd>.</p>
				2439
				2440	<pre class="code">
				2441	$mime = $image->MagickToMime('tif');
				2442	</pre>
				2443
				2444	<p>Use RemoteCommand() to send a command to an already running <a href="../www/display.html">display</a> or <a href="../www/animate.html">animate</a> application. The only parameter is the name of the image file to display or animate.</p>
				2445
				2446	<pre class="code">
				2447	$image->RemoteCommand('image.jpg');
				2448	</pre>
				2449
				2450	<p>Statistics() returns the image statistics for each channel in the image. The returned values are an array of depth, minima, maxima, mean, standard deviation, kurtosis, and skewness values in RGB, CMYK, RGBA, or CMYKA order (depending on the image type).</p>
				2451
				2452	<pre class="code">
				2453	@statistics = $image->Statistics();
				2454	</pre>
				2455
				2456	<p>Finally, the Transform() method accepts a fully-qualified geometry specification for cropping or resizing one or more images. For example,</p>
				2457
				2458	<pre class="code">
				2459	$p = $image->Transform(crop=>'100x100+0+0', gravity=>'Center');
				2460	</pre>
				2461
				2462	<p>You can optionally add <i>Image</i> to any method name above. For example, PingImage() is an alias for method Ping().</p>
				2463
				2464	</div>
				2465
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	2466	<h2><a id="exceptions"></a>Handling Exceptions</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2467	<div class="doc-section">
				2468
				2469	<p>All PerlMagick methods return an undefined string context upon success. If any problems occur, the error is returned as a string with an embedded numeric status code. A status code less than 400 is a warning. This means that the operation did not complete but was recoverable to some degree. A numeric code greater or equal to 400 is an error and indicates the operation failed completely. Here is how exceptions are returned for the different methods:</p>
				2470
				2471	<p>Methods which return a number (e.g. Read(), Write()):</p>
				2472
				2473	<pre class="code">
				2474	$x = $image->Read(...);
				2475	warn "$x" if "$x"; # print the error message
				2476	$x =~ /(\d+)/;
				2477	print $1; # print the error number
				2478	print 0+$x; # print the number of images read
				2479	</pre>
				2480
				2481	<p>Methods which operate on an image (e.g. Resize(), Crop()):</p>
				2482
				2483	<pre class="code">
				2484	$x = $image->Crop(...);
				2485	warn "$x" if "$x"; # print the error message
				2486	$x =~ /(\d+)/;
				2487	print $1; # print the error number
				2488	</pre>
				2489
cristy	63fed27	2010-03-07 19:08:45 +0000	[diff] [blame]	2490	<p>Methods which return images (EvaluateSequence(), Montage(), Clone()) should be checked for errors this way:</p>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2491
				2492	<pre class="code">
				2493	$x = $image->Montage(...);
				2494	warn "$x" if !ref($x); # print the error message
				2495	$x =~ /(\d+)/;
				2496	print $1; # print the error number
				2497	</pre>
				2498
				2499	<p>Here is an example error message:</p>
				2500
				2501	<pre class="code">
				2502	Error 400: Memory allocation failed
				2503	</pre>
				2504
				2505	<p>Review the complete list of <a href="../www/exception.html">error and warning codes</a>.</p>
				2506
				2507	<p>The following illustrates how you can use a numeric status code:</p>
				2508
				2509	<pre class="code">
				2510	$x = $image->Read('rose.png');
				2511	$x =~ /(\d+)/;
				2512	die "unable to continue" if ($1 == ResourceLimitError);
				2513	</pre>
				2514
				2515	</div>
				2516
cristy	dcca3fa	2010-12-29 21:50:07 +0000	[diff] [blame^]	2517	<h2><a id="constants"></a>Constants</h2>
cristy	3ed852e	2009-09-05 21:47:34 +0000	[diff] [blame]	2518	<div class="doc-section">
				2519
				2520	<p>PerlMagick includes these constants:</p>
				2521
				2522	<pre class="text">
				2523	BlobError
				2524	BlobWarning
				2525	CacheError
				2526	CacheWarning
				2527	CoderError
				2528	CoderWarning
				2529	ConfigureError
				2530	ConfigureWarning
				2531	CorruptImageError
				2532	CorruptImageWarning
				2533	DelegateError
				2534	DelegateWarning
				2535	DrawError
				2536	DrawWarning
				2537	ErrorException
				2538	FatalErrorException
				2539	FileOpenError
				2540	FileOpenWarning
				2541	ImageError
				2542	ImageWarning
				2543	MissingDelegateError
				2544	MissingDelegateWarning
				2545	ModuleError
				2546	ModuleWarning
				2547	Opaque
				2548	OptionError
				2549	OptionWarning
				2550	QuantumDepth
				2551	QuantumRange
				2552	RegistryError
				2553	RegistryWarning
				2554	ResourceLimitError
				2555	ResourceLimitWarning
				2556	StreamError
				2557	StreamWarning
				2558	Success
				2559	Transparent
				2560	TypeError
				2561	TypeWarning
				2562	WarningException
				2563	XServerError
				2564	XServerWarning
				2565	</pre>
				2566
				2567	<p>You can access them like this:</p>
				2568
				2569	<pre class="code">
				2570	Image::Magick->QuantumDepth
				2571	</pre>
				2572
				2573	</div>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	2574
				2575	</div>
				2576
				2577	<div id="linkbar">
cristy	ce69bb0	2010-07-27 19:49:46 +0000	[diff] [blame]	2578	<span id="linkbar-west"> </span>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	2579	<span id="linkbar-center">
				2580	<a href="http://www.imagemagick.org/discourse-server/">Discourse Server</a> •
cristy	a890294	2010-07-30 00:49:52 +0000	[diff] [blame]	2581	<a href="http://www.imagemagick.org/MagickStudio/scripts/MagickStudio.cgi">Studio</a>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	2582	</span>
				2583	<span id="linkbar-east"> </span>
				2584	</div>
				2585	<div class="footer">
cristy	7e41fe8	2010-12-04 23:12:08 +0000	[diff] [blame]	2586	<span id="footer-west">© 1999-2011 ImageMagick Studio LLC</span>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	2587	<span id="footer-east"> <a href="http://www.imagemagick.org/script/contact.php">Contact the Wizards</a></span>
				2588	</div>
				2589	<div style="clear: both; margin: 0; width: 100%; "></div>
cristy	a890294	2010-07-30 00:49:52 +0000	[diff] [blame]	2590	<script type="text/javascript">
				2591	var _gaq = _gaq \|\| [];
				2592	_gaq.push(['_setAccount', 'UA-17690367-1']);
				2593	_gaq.push(['_trackPageview']);
				2594
				2595	(function() {
				2596	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
				2597	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
				2598	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
				2599	})();
				2600	</script>
cristy	3eaa0ef	2010-03-06 20:35:26 +0000	[diff] [blame]	2601	</body>
				2602	</html>