File: perl-api-reference.tex

package info (click to toggle)
imagemagick 6:6.0.6.2-2.9
• links: PTS
• area: main
• in suites: sarge
• size: 33,284 kB
• ctags: 14,844
• sloc: ansic: 190,790; cpp: 17,203; sh: 8,740; perl: 4,190; makefile: 1,740; tcl: 459
 file content (2888 lines) | stat: -rw-r--r-- 87,606 bytes parent folder | download
 12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888 \title{Perl API Methods} \toctitle{Perl API Methods} \titlerunning{Perl API Methods} \maketitle \section{Image::Magick Attributes} \label{Image::Magick Attributes} An image has certain attributes associated with it such as width, height, number of colors in the colormap, page geometry, and others. Many of the image methods allow you to set relevant attributes directly in the method call, or you can use Set(), as in: {\small \begin{verbatim} $image->Set(loop=>100);$image->[$x]->Set(dither=>1); \end{verbatim} } To get an imageattribute, use Get(): {\small \begin{verbatim} ($width, $height,$depth) = $image->Get('width', 'height', 'depth');$colors = $image->[2]->Get('colors'); \end{verbatim} } The methods GetAttribute() and SetAttribute() are aliases for Get() and Set() and may be used interchangeably. Following is a list of image attributes acceptable to either Set() or Get() as noted. \subsubsection{adjoin} join images into a single multi-image file. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(adjoin=$>$\var{boolean}) \\ \hspace*{-0.25in} \$image-$>$Get('adjoin') \end{quote} Certain file formats accept multiple images within a single file (e.g. a GIF animation). If \texttt{adjoin} is value other than 0 and the image is a multi-image format, multiple reads to the same image object will join the images into a single file when you call the Write() method. Set \texttt{adjoin} to 0 if you do not want the images output to a single file. \subsubsection{antialias} remove pixel aliasing. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(antialias=$>$\var{boolean}) \\ \hspace*{-0.25in} \$image-$>$Get('antialias') \end{quote} The visible effect of antialias is to blend the edges of any text or graphics with the image background. This attribute affects how text and graphics are rendered when certain image formats are read (e.g. Postscript or SVG) or when certain Image::Magick methods are called (e.g. Annotate() or Draw()). \subsubsection{background} image background color. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(background=$>$\var{color-name}) \\ \hspace*{-0.25in} \$image-$>$Get('background') \end{quote} This attribute sets (or gets) the background color of an image. Image formats such as GIF, PICT, PNG, and WMF retain the background color information. \subsubsection{base-filename} base image filename (before transformations). \begin{quote} \hspace*{-0.25in} \$image-$>$Get('base-filename'') \end{quote} The original filename is returned as a string. \subsubsection{base-height} base image height (before transformations). \begin{quote} \hspace*{-0.25in} \$image-$>$Get('base-height') \end{quote} This attribute returns the original height of image before any resizing operation. \subsubsection{base-width} base image width (before transformations). \begin{quote} \hspace*{-0.25in} \$image-$>$Get('base-width') \end{quote} This attribute returns the original width of image before any resizing operation. \subsubsection{blue-primary} chromaticity blue primary point. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(blue-primary=$>$\var{x-value},\var{y-value}) \\ \hspace*{-0.25in} \$image-$>$Get('blue-primary') \end{quote} This attribute sets or returns the chromaticity blue primary point. This is a color management option. \subsubsection{cache-threshold} cache threshold. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(cache-threshold=$>$\var{integer}) \\ \hspace*{-0.25in} \$image-$>$Get('cache-threshold') \end{quote} Image pixels are stored in your computer's memory until it has been consumed or the cache threshold is exceeded. Subsequent pixel operations are cached to disk. Operations to memory are significantly faster, but if your computer does not have a sufficient amount of free memory to read or transform an image, you may need to set this threshold to a small megabyte value (e.g. 32). Use 0 to cache all images to disk. \subsubsection{class} image class. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('class') \end{quote} A \texttt{Direct} class image is a continuous tone image and is stored as a sequence of red-green-blue and optional opacity intensity values. A \texttt{Pseudo} class image is an image with a colormap, where the image is stored as a map of colors and a sequence of indexes into the map. \subsubsection{clip-mask} associate a clip mask with the image. \begin{quote} \hspace*{-0.25in} \$image-$>$Set('clip-mask'=$>$\var{image}) \\ \$image-$>$Get('clip-mask') \\ \end{quote} \texttt{Clip-mask} associates a clip mask with the image. \subsubsection{colormap} color of a particular colormap entry. \begin{quote} \hspace*{-0.25in} \$image-$>$Set('colormap[\var{\$i}]'=$>$\var{color-name}) \\ \hspace*{-0.25in} \$image-$>$Get('colormap[\var{\$i}]') \end{quote} This attribute returns the red, green, blue, and opacity values at colormap position \var{\$i}. You can set the color with a colorname (e.g. red) or color hex value (e.g. \#ccbdbd). \subsubsection{colors} number of distinct colors in the image. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('colors') \end{quote} This attribute returns the number of distinct colors in the image. \subsubsection{comment} image comment. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('comment') \end{quote} Return the image comment. \subsubsection{compression} type of compression. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(compression=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('compression') \end{quote} \texttt{Compression} defaults to the compression type of the image when it was first read. The value of \texttt{compression} can be one of the following: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> None \> BZip \> Fax \\ \> Group4 \> JPEG \> LosslessJPEG \\ \> LZW \> RLE \> Zip \end{tabbing} If you set a compression type that is incompatible with the output file type, a compatible compression value is used instead (e.g. a PNG image ignores a \texttt{compression} value of JPEG and saves with Zip compression). \subsubsection{delay} interframe delay. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(delay=$>$\var{integer}) \\ \hspace*{-0.25in} \$image-$>$Get('delay') \end{quote} \texttt{Delay} regulates the playback speed of a sequence of images. The value is the number of hundredths of a second that must pass before displaying the next image. The default is 0 which means there is no delay and the animation will play as fast as possible. \subsubsection{density} image resolution. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(density=$>$\var{geometry}) \\ \hspace*{-0.25in} \$image-$>$Get('density') \end{quote} This attribute to set the horizontal and vertical resolution of an image. Use attribute \texttt{units} to define the units of resolution. The default is 72 dots-per-inch. \subsubsection{depth} color component depth. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('depth') \end{quote} Return the color component depth of the image, either 8 or 16. A depth of 8 represents color component values from 0 to 255 while a depth of 16 represents values from 0 to 65535. \subsubsection{directory} thumbnail names of an image montage. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('directory') \end{quote} A montage is one or more image thumbnails regularly spaced across a color or textured background created by the Montage() method or \textit{montage} program. \texttt{Directory} returns the filenames associated with each thumbnail. \subsubsection{dispose} GIF disposal method. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(dispose=$>$\var{0, 1, 2, 3}) \\ \hspace*{-0.25in} \$image-$>$Get('dispose') \end{quote} The \texttt{dispose} attribute sets the GIF disposal method that defines how an image is refreshed when flipping between scenes in a sequence. The disposal methods are defined as: \begin{tabbing} 0000\=1111111111\=222222222222222\kill \> 0 \> replace one full-size, non-transparent frame with another\\ \> 1 \> any pixels not covered up by the next frame continue to display\\ \> 2 \> background color or background tile shows through transparent pixels\\ \> 3 \> restore to the state of a previous, undisposed frame \end{tabbing} \subsubsection{dither} apply dithering to the image. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(dither=$>$\var{boolean}) \\ \hspace*{-0.25in} \$image-$>$Get('dither') \end{quote} Color reduction is performed implicitly when an image is converted from a file format that allows many colors to one that allows fewer (e.g. JPEG to GIF). Dithering helps smooth out the apparent contours produced when sharply reducing colors. The default is to dither an image during color reduction. \subsubsection{error} mean error per pixel. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('error') \end{quote} This value reflects the mean error per pixel introduced when reducing the number of colors in an image either implicitedly or explicitly: \begin{enumerate} \item Explicitly, when you use the Quantize() method. \item Implicitly, when an image is converted from a file format that allows many colors to one that allows fewer (e.g. JPEG to GIF). \end{enumerate} The mean error gives one measure of how well the color reduction algorithm performed and how similiar the color reduced image is to the original. \subsubsection{file} Perl filehandle. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(file=$>$\var{filehandle}) \\ \hspace*{-0.25in} \$image-$>$Get('file') \end{quote} The Read() and Write() methods accept an already opened Perl filehandle and the image is read or written directly from or to the specified filehandle. \subsubsection{filename} filename of image. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(filename=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('filename') \end{quote} The default filename is the name of the file from which the image was read. Write() accepts a filename as a parameter, however, if you do not specify one, it uses the name defined by the \texttt{filename} attribute. For example: {\small \begin{verbatim}$image->Read('logo.gif'); $image->Write(); # write image as logo.gif$image->Set(filename=>'logo.png'); $image->Write(); # write image as logo.png \end{verbatim} } \subsubsection{filesize} size of file in bytes. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('filesize') \end{quote} Returns the number of bytes the image consumes in memory or on disk. \subsubsection{font} text font. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(font=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('font') \end{quote} Both Annotate() and Draw() require a font to render text to an image. A font can be Truetype (Arial.ttf), Postscript (Helvetica), or a fully-qualified X11 font (-*-helvetica-medium-r-*-*-12-*-*-*-*-*-iso8859-*) name. \subsubsection{format} descriptive image format. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('format') \end{quote} Attribute \texttt{magick} returns the abbreviated image format (e.g. JPEG) while \texttt{format} returns more descriptive text about the format (e.g. Joint Photographic Experts Group JFIF format). \subsubsection{fuzz} close colors are treated as equal. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(fuzz=$>$\var{integer}) \\ \hspace*{-0.25in} \$image-$>$Get('fuzz') \end{quote} A number of image methods (e.g. ColorFloodfill()) compare a target color to a color within the image. By default these colors must match exactly. However, in many cases two colors may differ by a small amount. \texttt{Fuzz} defines how much tolerance is acceptable to consider two different colors as the same. For example, set \texttt{fuzz} to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color. \subsubsection{gamma} image gamma. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(gamma=$>$\var{float}) \\ \hspace*{-0.25in} \$image-$>$Get('gamma') \end{quote} Set or return the image gamma value. Unlike Gamma() that actually applies the gamma value to the image pixels, here we just set the value. This is useful if the correct gamma is already known about a particular image. \subsubsection{geometry} shortcut for specifying width and height. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(geometry=$>$\var{geometry}) \\ \hspace*{-0.25in} \$image-$>$Get('geometry') \end{quote} The \texttt{geometry} attribute is a convenient way to specify the width, height, and any offset of an image region as a single string. For example, {\small \begin{verbatim} geometry=>'640x80' \end{verbatim} } is equivalent to: {\small \begin{verbatim} width=>640, height=>480 \end{verbatim} } To refer to a 20 x 20 region of pixels starting at coordinate (100, 150), use: {\small \begin{verbatim} geometry=>'20x20+100+150' \end{verbatim} } \subsubsection{gravity} type of gravity. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(gravity=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('gravity') \end{quote} \texttt{Gravity} defaults to NorthWest. The value of \texttt{gravity} can be one of the following: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> NorthWest \> North \> NorthEast \\ \> West \> Center \> East \\ \> SouthWest \> South \> SouthEast \end{tabbing} \subsubsection{green-primary} chromaticity green primary point. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(green-primary=$>$\var{x-value},\var{y-value}) \\ \hspace*{-0.25in} \$image-$>$Get('green-primary') \end{quote} This attribute sets or returns the chromaticity green primary point. This is a color management option. \subsubsection{height} image height. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('height') \end{quote} This attribute returns the height (in pixel rows) of the image. \subsubsection{index} colormap index at a particular pixel location. \begin{quote} \hspace*{-0.25in} \$image-$>$Set('index[\var{\$x, \$y}]'=$>$\var{color-name}) \\ \hspace*{-0.25in} \$image-$>$Get('index[\var{\$x, \$y}]') \end{quote} This attribute sets or returns the colormap index at position (\var{\$x, \$y}). The result is undefined if the image does not have a colormap or the specified location lies outside the the image area. \subsubsection{ICM} color information profile. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('ICM') \end{quote} This attribute returns the color information profile. \subsubsection{id} ImageMagick registry ID. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('id') \end{quote} This attribute returns the ImageMagick registry ID. The registry allows for persistent images that can later be referenced as a filename (e.g. \texttt{registry:0xbd}). \subsubsection{interlace} type of interlacing scheme. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(interlace=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('interlace') \end{quote} The \texttt{interlace} attribute allows you to specify the interlacing scheme used by certain image formats such as GIF, JPEG, RGB, and CMYK. The default is \texttt{None} but can be any of the following: \begin{tabbing} 0000\=1111111111\=222222222222222\kill \> None \> no interlacing \\ \> Line \> scanline interlacing \\ \> Plane \> plane interlacing \\ \> Partition \> partition interlacing \end{tabbing} \subsubsection{IPTC} newswire information profile. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('IPTC') \end{quote} This attribute returns the newswire information profile. \subsubsection{label} image label. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(label=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('label') \end{quote} Use labels to optionally annotate a Postscript or PDF image or the thumbnail images of a montage created by the Montage() method or \textit{montage} program. A label can include any of the special formatting characters described in the Comment() method description. \subsubsection{loop} add loop extension to your image sequence. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(loop=$>$\var{integer}) \\ \hspace*{-0.25in} \$image-$>$Get('loop') \end{quote} The \texttt{loop} attribute adds the Netscape looping extension to an image sequence. A value of 0 causes the animation sequence to loop continuously. Any other value results in the animation being repeated for the specified number of times. The default value is 1. \subsubsection{magick} image file format. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(magick=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('magick') \end{quote} The default image format is whatever format the image was in when it was read. Write() accepts an image format as a parameter, however, if you do not specify one, it uses the format defined by the \texttt{magick} attribute. For example: {\small \begin{verbatim}$image->Read('logo.gif'); $image->Write(); # write image as GIF$image->Set(magick=>'PNG'); $image->Write(); # write image as PNG \end{verbatim} } \subsubsection{matte} transparency boolean. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(matte=$>$\var{boolean}) \\ \hspace*{-0.25in} \$image-$>$Get('matte') \end{quote} Some images have a transparency mask associated with each pixel ranging from opaque (pixel obscures background) to fully transparent (background shows thru). The transparency mask, if it exists, is ignored if the \texttt{matte} attribute is 0 and all pixels are treated as opaque. \subsubsection{maximum-error} normalized maximum mean error per pixel. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('maximum-error') \end{quote} This value reflects the normalized maximum per pixel introduced when reducing the number of colors in an image either implicitedly or explicitly: \begin{enumerate} \item Explicitly, when you use the Quantize() method. \item Implicitly, when an image is converted from a file format that allows many colors to one that allows fewer (e.g. JPEG to GIF). \end{enumerate} The normalized maximum error gives one measure of how well the color reduction algorithm performed and how similiar the color reduced image is to the original. \subsubsection{mean-error} normalized mean mean error per pixel. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('mean-error') \end{quote} This value reflects the normalized mean per pixel introduced when reducing the number of colors in an image either implicitedly or explicitly: \begin{enumerate} \item Explicitly, when you use the Quantize() method. \item Implicitly, when an image is converted from a file format that allows many colors to one that allows fewer (e.g. JPEG to GIF). \end{enumerate} The normalized mean error gives one measure of how well the color reduction algorithm performed and how similiar the color reduced image is to the original. \subsubsection{montage} tile size and offset within an image montage. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('montage') \end{quote} A montage is one or more image thumbnails regularly spaced across a color or textured background returned by the Montage() method or \textit{montage} program. The \texttt{montage} attribute returns the geometry of the region associated with each image thumbnail (e.g. 160x120+10+10). This information is useful for creating image maps for dynamic web pages. \subsubsection{page} perferred size and location of the image canvas. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(page=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('page') \end{quote} \texttt{Page} declares the image canvas size and location. Typically this is only useful for the Postscript, text, and GIF formats. The value of \texttt{string} can be: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Letter \> Tabloid \> Ledger \\ \> Legal \> Statement \> Executive \\ \> A3 \> A4 \> A5 \\ \> B4 \> B5 \> Folio \\ \> Quarto \> 10x14 \> \end{tabbing} or a geometry (612x792). The default value is \texttt{Letter}. \subsubsection{pointsize} pointsize of a font. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(pointsize=$>$\var{integer}) \\ \hspace*{-0.25in} \$image-$>$Get('pointsize') \end{quote} The \texttt{pointsize} attribute determines how large to draw a Postscript or TrueType font with the Annotate() or Draw() methods. The default is 12. \subsubsection{preview} type of image preview. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(preview=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('preview') \end{quote} Set or get the type of preview for the Preview image format. \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> 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 \end{tabbing} Suppose we want to determine an ideal gamma setting for our image: {\small \begin{verbatim} $image->Write(filename=>'model.png',preview=>'Gamma');$image->Display(); \end{verbatim} } \subsubsection{quality} compression level. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(quality=$>$\var{integer}) \\ \hspace*{-0.25in} \$image-$>$Get('quality') \end{quote} The quality attribute sets the JPEG, MIFF, MNG, or PNG compression level. The range is 0 (worst) to 100 (best). The default is 75. Quality is a trade-off between image size and compression speed for the MIFF, MNG, and PNG formats. The higher the quality, the smaller the resulting image size but with a requisite increase in compute time. The quality value is used as two decimal digits. The tens'' digit conveys the zlib compression level and the ones'' digit conveys the PNG filter method. When the compression level is 0, the Huffman compression strategy is used, which is fast but does not necessarily obtain the worst compression. The MIFF encoder ignores the PNG filter method conveyed by the ones'' digit. The JPEG trade-off is between image size and image appearance. A high quality returns an image nearly free of compression artifacts but with a larger image size. If you can accept a lower quality image appearance, the resulting image size would be considerably less. \subsubsection{red-primary} chromaticity red primary point. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(red-primary=$>$\var{x-value},\var{y-value}) \\ \hspace*{-0.25in} \$image-$>$Get('red-primary') \end{quote} This attribute sets or returns the chomaticity red primary point. This is a color management option. \subsubsection{rendering-intent} intended rendering model. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(rendering-intent=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('rendering-intent') \end{quote} This is a color management option. Choose from these models: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Undefined \> Saturation \> Perceptual \\ \> Absolute \> Relative \> \end{tabbing} \subsubsection{sampling-factor} image sampling factor. \begin{quote} \hspace*{-0.25in} \$image-$>$Set('sampling-factor'=$>$\var{geometry}) \\ \hspace*{-0.25in} \$image-$>$Get('sampling-factor') \end{quote} Use this attribute to set the horizontal and vertical sampling factor for use by the JPEG encoder. \subsubsection{scene} image scene number. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(scene=$>$\var{integer}) \\ \hspace*{-0.25in} \$image-$>$Get('scene') \end{quote} By default each image in a sequence has a scene number that starts at 0 and each subsequent image in the sequence increments by 1. Use \texttt{scene} to reset this value to whatever is appropriate for your needs. \subsubsection{signature} SHA-256 message digest. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('signature') \end{quote} Retrieves the SHA-256 message digest associated with the image. A signature is generated across all the image pixels. If a single pixel changes, the signature will change as well. The signature is mostly useful for quickly determining if two images are identical or if an image has been modified. \subsubsection{size} width and height of a raw image. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(size=$>$\var{geometry}) \\ \hspace*{-0.25in} \$image-$>$Get('size') \end{quote} Set the \texttt{size} attribute before reading an image from a raw data file format such as RGB, GRAY, TEXT, or CMYK (e.g. 640x480) or identify a desired resolution for Photo CD images (e.g. 768x512). {\small \begin{verbatim}$image->Set(size=>'640x480'); $image->Read('gray:protein'); \end{verbatim} } \subsubsection{server} X server to contact. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(server=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('server') \end{quote} Display(), Animate(), or any X11 font use with Annotate() require contact with an X server. Use \texttt{server} to specify which X server to contact (e.g. \texttt{mysever:0}). \subsubsection{taint} pixel change boolean. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('taint') \end{quote} \texttt{Taint} returns a value other than 0 if any image pixel has modified since it was first read. \subsubsection{texture} name of texture to tile. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(texture=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('texture') \end{quote} The \texttt{texture} attribute assigns a filename of a texture to be tiled onto the image background when any TXT or WMF image formats are read. \subsubsection{type} image type. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(type=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('type') \end{quote} The image type can be any of the following \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Bilevel \> Grayscale \> GrayscaleMatte \\ \> Palette \> PaletteMatte \> TrueColor\\ \> TrueColorMatte \> ColorSeparation \> ColorSeparationMatte \\ \> Optimize \end{tabbing} When getting this attribute, the value reflects the type of image pixels. For example a colormapped GIF image would most likely return Palette as the image type. You can also force a particular type with Set(). For example if you want to force your color image to black and white, use: {\small \begin{verbatim} $image->Set(type=>'Bilevel'); \end{verbatim} } \subsubsection{units} units of resolution. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(units=$>$\var{string}) \\ \hspace*{-0.25in} \$image-$>$Get('units') \end{quote} Return or set the units in which the image's resolution are defined. Values may be: \begin{tabbing} 0000\=111111111111111\kill \> Undefined \\ \> pixels/inch \\ \> pixels/centimeter \end{tabbing} \subsubsection{verbose} print details. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(verbose=$>$\var{boolean}) \\ \end{quote} When set, \texttt{verbose} causes some image operations to print details about the operation as it progresses. \subsubsection{white-point} chromaticity white point. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(white-point=$>$\var{x-value},\var{y-value}) \\ \hspace*{-0.25in} \$image-$>$Get('white-point') \end{quote} This attribute sets or returns the chomaticity white point. This is a color management option. \subsubsection{width} image width. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('width') \end{quote} Returns the width (integer number of pixel columns) of the image. \subsubsection{x-resolution} horizontal resolution. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('x-resolution') \end{quote} Returns the \textit{x} resolution of the image in the units defined by the \texttt{units} attribute (e.g. 72 pixels/inch). Use the \texttt{density} attribute to change this value. \subsubsection{y-resolution} vertical resolution. \begin{quote} \hspace*{-0.25in} \$image-$>$Get('y-resolution') \end{quote} Returns the \textit{y} resolution of the image in the units defined by the \texttt{units} attribute (e.g. 72 pixels/inch). Use the \texttt{density} attribute to change this value. \section{Image::Magick Methods} \subsubsection{AddNoise()} add noise to an image. \begin{quote} \hspace*{-0.25in} \$image-$>$AddNoise(noise=$>$\var{string}) \end{quote} This method adds random noise to the image, where \var{string} specifies one of the following types: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Uniform \> Gaussian \> Multiplicative \\ \> Impulse \> Laplacian \> Poisson \end{tabbing} \subsubsection{AffineTransform} affine transform the image. \begin{quote} \hspace*{-0.25in} \$image-$>$AffineTransform(affine=$>$\var{array of float values}, rotate=$>$\var{rotate-angle}, scale=$>$\var{sx, sy}, skewX=$>$\var{skew-angle}, skewY=$>$\var{skew-angle}, translate=$>$\var{tx, ty}) \end{quote} AffineTransform() \begin{description} \item[rotate] Specifies a rotation of \var{rotate-angle} degrees about a given point. \item[scale] Specifies a scale operation by \var{sx} and \var{sy}. \item[skewX] Specifies a skew transformation along the x-axis. \item[skewY] Specifies a skew transformation along the y-axis. \item[translate] Specifies a translation by \var{tx} and \var{ty}. \end{description} \subsubsection{Animate()} animate an image sequence. \begin{quote} \hspace*{-0.25in} \$image-$>$Animate() \end{quote} Animate() repeatedly displays an image sequence to any X window screen. This method accepts the same parameters as Set() as described in section \ref{Image::Magick Attributes}. \subsubsection{Annotate()} annotate an image with text. \begin{quote} \hspace*{-0.25in} \$image-$>$Annotate(text=$>$\var{string}, affine=$>\var{array of float values}, align=>$\var{string}, antialias=$>$\var{boolean}, density=$>$\var{geometry}, encoding$>$\var{string}, fill=$>$\var{color-name}, family=$>$\var{string}, font=$>$\var{string}, geometry=$>$\var{geometry}, gravity=$>$\var{string}, pointsize=$>$\var{integer}, rotate=$>$\var{rotate-angle}, scale=$>$\var{sx, sy}, skewX=$>$\var{skew-angle}, skewY=$>$\var{skew-angle}, stroke=$>$\var{color-name}, strokewidth=$>$\var{integer}, stretch=$>$\var{string}, style=$>$\var{string}, translate=$>$\var{tx, ty}, undercolor=$>$\var{color-name}, unicode=$>$\var{boolean}, weight=$>$\var{string}, x=$>$\var{integer}, y=$>\var{integer}) \end{quote} Annotate() allows you to scribble text across an image. The text may be represented as a string or filename. Precede the filename with an "at" sign (\texttt{@}) and the contents of the file are drawn on the image. You can affect how text is drawn by specifying one or more of the following parameters: \begin{description} \item[align] font alignment. Choose from these alignments: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Left \> Center \> Right \end{tabbing} \item[antialias] The visible effect of antialias is to smooth out the rounded corners of text characters. Set to 0 to keep crisp edges. \item[density] Set the vertical and horizontal resolution of the font. The default is 72 pixels/inch. \item[encoding] Font encoding. \item[family] font family. \item[fill] The fill color paints any areas inside the outline of the text. \item[font] A font can be a Truetype (arial.ttf), Postscript (Helvetica), or a fully-qualified X11 font (-*-helvetica-medium-r-*-*-12-*-*-*-*-*-iso8859-*). \item[geometry] Geometry defines the baseline position where text is rendered (e.g. +100+50). \item[gravity] Gravity affects how the text is rendered relative to the (\var{x, y}) baseline position. By default gravity is NorthWest which renders text above the baseline position. Choose from these gravities: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> NorthWest \> North \> NorthEast \\ \> West \> Center \> East \\ \> SouthWest \> South \> SouthEast \end{tabbing} \item[pointsize] The font pointsize. The default is 12. \item[rotate] Specifies a rotation by the specified number of degrees about a given point. \item[scale] Specifies a scale operation by \var{sx} and \var{sy}. \item[skewX] Specifies a skew transformation along the x-axis. \item[skewY] Specifies a skew transformation along the y-axis. \item[stretch] font stretch. Choose from these stretches: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Normal \> UltraCondensed \> ExtraCondensed \\ \> Condensed \> SemiCondensed \> SemiExpanded \\ \> Expanded \> ExtraExpanded \> UltraExpanded \end{tabbing} \item[stroke] A stroke color paints along the outline of the text. \item[strokewidth] The width of the stroke on the text. A zero value causes no stroke to be painted. \item[style] font style. Choose from these styles: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Normal \> Italic \> Oblique \\ \> Any \end{tabbing} \item[translate] Specifies a translation by \var{tx} and \var{ty}. \item[undercolor] By default text is blended with the image background. Set the undercolor color to give a uniform background to your text of the color you choose. \item[unicode] Set to true if text is Unicode. \item[weight] Font weight. \item[x] Specifies the \var{x} baseline position of the text. \item[y] Specifies the \var{y} baseline position of the text. \end{description} \subsubsection{Append()} append a set of images. \begin{quote} \hspace*{-0.25in} \image-$>$Append(stack=$>$\var{boolean}) \end{quote} The Append() method takes a set of images and appends them to each other. Append() returns a single image where each image in the original set is side-by-side. If the stack parameter is True, the images are stacked top-to-bottom. {\small \begin{verbatim} $append =$image->Append(); \end{verbatim} } \subsubsection{Average()} average a set of images. \begin{quote} \hspace*{-0.25in} \$image-$>$Average() \end{quote} The Average() method takes a set of images and averages them together. Each image in the set must have the same width and the same height. Average() returns a single image with each corresponding pixel component of each image averaged. \subsubsection{BlobToImage()} return an image from a Binary Large OBject. \begin{quote} \hspace*{-0.25in} \$image-$>$BlobToImage(\var{blob}) \end{quote} Read() returns an image from a file on disk, whereas, BlobToImage() performs the same function if the image format is stored in memory: {\small \begin{verbatim} @blob = $db->GetImage(); # get blob from database$image = Image::Magick->New(magick=>'jpg'); # the blob is a JPEG image $image->BlobToImage(@blob); # convert blob to Image::Magick object \end{verbatim} } \subsubsection{Blur()} blur the image. \begin{quote} \hspace*{-0.25in} \$image-$>$Blur(geometry=$>$\var{geometry}, radius=$>$\var{float}, sigma=$>$\var{float}) \end{quote} Blur() blurs an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, the radius should be larger than sigma. Use a radius of 0 and Blur() selects a suitable radius for you. \texttt{Geometry} represents radius x sigma as one parameter (e.g. 0x1). \subsubsection{Border()} frame the image with a border. \begin{quote} \hspace*{-0.25in} \$image-$>$Border(geometry=$>$\var{geometry}, width=$>$\var{integer}, height=$>$\var{integer}, fill=$>$\var{color-name}) \end{quote} This method surrounds the image with a border of the specified color. \texttt{Geometry} represents {\it width x height} as one parameter (e.g. 10x5). \subsubsection{Channel()} extract a channel from the image. \begin{quote} \hspace*{-0.25in} \$image-$>$Channel(channel=$>$\var{string}); \end{quote} Extract a channel from the image. A channel is a particular color component of each pixel in the image. Choose from these components: \begin{tabbing} 0000\=111111\kill \> Red \\ \> Cyan \\ \> Green \\ \> Magenta \\ \> Blue \\ \> Yellow \\ \> Opacity \\ \> Black \end{tabbing} \subsubsection{Charcoal()} special effect filter. \begin{quote} \hspace*{-0.25in} \$image-$>$Charcoal(geometry=$>$\var{geometry}, radius=$>$\var{float}, sigma=$>$\var{float}) \end{quote} Charcoal() is a special effect filter that simulates a charcoal drawing. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and Charcoal() selects a suitable radius for you. \texttt{Geometry} represents radius x sigma as one parameter (e.g. 0x1). \subsubsection{Chop()} chop an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Chop(geometry=$>$geometry, width=$>$integer, height=$>$integer, x=$>$integer, y=$>$integer) \end{quote} Chop() removes a region of an image and collapses the image to occupy the removed portion. Columns \texttt{x} through \texttt{x+width} and the rows \texttt{y} through \texttt{y+height} are chopped. Use \texttt{Geometry} as a shortcut for {\it width x height + x + y} (e.g. 100x50+10+20). \subsubsection{Clone()} create a new copy of an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Clone() \end{quote} The Clone() method copies a set of images and returns the copy as a new image object. For example {\small \begin{verbatim}$clone = $image=>Clone(); \end{verbatim} } copies all of the images from \texttt{\$image} to \texttt{\$clone}. \subsubsection{Coalesce()} coalesce a set of images. \begin{quote} \hspace*{-0.25in} \$image-$>$Coalesce() \end{quote} This method composites a set of images while respecting any page offsets and disposal methods. GIF, MIFF, and MNG animation sequences typically start with an image background and each subsequent image varies in size and offset. Coalesce() returns a new sequence where each image in the sequence is the same size as the first and composited over the previous images in the sequence. \subsubsection{ColorFloodfill()} floodfill the designed area with color. \begin{quote} \hspace*{-0.25in} \$image-$>$ColorFloodfill(geometry=$>$\var{geometry}, x=$>$\var{integer}, y=$>$\var{integer}, fill=$>$\var{color-name}, bordercolor=$>$\var{color-name}, fuzz=$>$\var{float}) \end{quote} ColorFloodfill() changes the color value of any pixel that matches \texttt{fill} and is an immediate neighbor. If \texttt{bordercolor} is specified, the color value is changed for any neighbor pixel that is not \texttt{bordercolor}. Use \texttt{Geometry} as a shortcut for {\it x + y} (e.g. +10+20). By default \texttt{fill} must match a particular pixel color exactly. However, in many cases two colors may differ by a small amount. \texttt{Fuzz} defines how much tolerance is acceptable to consider two colors as the same. For example, set fuzz to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color for the purposes of the floodfill. \subsubsection{Colorize()} colorize an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Colorize(fill=$>$\var{color-name}, opacity=$>$\var{string}) \end{quote} Colorize() blends the fill color with each pixel in the image. A percentage blend is specified with \texttt{opacity}. Control the application of different color components by specifying a different percentage for each component (e.g. 90/100/10 is 90\% red, 100\% green, and 10\% blue). \subsubsection{Comment()} add a comment to an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Comment(comment=$>$\var{string}) \end{quote} Add a comment to an image. Optionally you can include any of the following bits of information about the image by embedding the appropriate special characters: \begin{tabbing} 0000\=1111\=222222222222222\kill \> \%b \> file size in bytes. \\ \> \%c \> comment. \\ \> \%d \> directory in which the image resides. \\ \> \%e \> extension of the image file. \\ \> \%f \> original filename of the image. \\ \> \%g \> page geometry. \\ \> \%h \> height of image. \\ \> \%i \> filename of the image. \\ \> \%k \> number of unique colors. \\ \> \%l \> image label. \\ \> \%m \> image file format. \\ \> \%n \> number of images in the image sequence. \\ \> \%o \> output image filename. \\ \> \%p \> page number of the image. \\ \> \%q \> image depth (8 or 16). \\ \> \%s \> image scene number. \\ \> \%t \> image filename without any extension. \\ \> \%u \> a unique temporary filename. \\ \> \%w \> image width. \\ \> \%x \> x resolution of the image. \\ \> \%y \> y resolution of the image. \\ \> \%z \> image depth. \\ \> \%\# \> SHA-256 message digest. \end{tabbing} Given an image whose filename is \texttt{logo.gif} and dimensions of 640 pixels in width and 480 pixels in height, this statement: {\small \begin{verbatim}$image->Comment('%f %m %wx%h') \end{verbatim} } generates a comment that reads: \texttt{logo.gif GIF 640x480}. \subsubsection{Composite} composite one image to another. \begin{quote} \hspace*{-0.25in} \$image-$>$Composite(image=$>$\var{image-handle}, color=$>$\var{color-name}, compose=$>$\var{string}, geometry=$>$\var{geometry}, mask=$>$\var{image-handle}, gravity=$>$\var{string}, opacity=$>$\var{integer}, rotate=$>$\var{float}, tile=$>$\var{boolean} x=$>$\var{integer}, y=$>$\var{integer}, ) \end{quote} Composite() allows you to overlay one image to another. You can affect how and where the composite is overlaid by specifying one or more of the following options: \begin{description} \item[compose] This operator affects how the composite is applied to the image. The default is Over. Choose from these operators: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Over \> In \> Out \\ \> Atop \> Xor \> Plus \\ \> Minus \> Add \> Subtract \\ \> Difference \> Bumpmap \> Copy \\ \> Displace \end{tabbing} \item[geometry] Geometry defines the baseline position where the composite is placed (e.g. +100+50). \item[gravity] Gravity affects how the image is placed relative to the (\var{x, y}) baseline position. By default gravity is NorthWest which renders the image just below the baseline position. Choose from these gravities: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> NorthWest \> North \> NorthEast \\ \> West \> Center \> East \\ \> SouthWest \> South \> SouthEast \end{tabbing} \item[image] The image. \item[mask] The mask image. \item[opacity] Blend composite with the image background. \texttt{Opacity} is expressed as percent transparency. \item[rotate] Rotate image before it is composited, expressed in degrees. \item[tile] A value other than 0 tiles the composite repeatedly across \item[x] Specifies the \var{x} baseline position of the composite. \item[y] Specifies the \var{y} baseline position of the composite. and down the image. \end{description} \subsubsection{Contrast()} enhance or reduce the image contrast. \begin{quote} \hspace*{-0.25in} \$image-$>$Contrast(sharpen=$>$\var{boolean}) \end{quote} Contrast() enhances the intensity differences between the lighter and darker elements of the image. Set \texttt{sharpen} to a value other than 0 to increase the image contrast otherwise the contrast is reduced. \subsubsection{Convolve()} apply a convolution kernel to the image. \begin{quote} \hspace*{-0.25in} \$image-$>$Convolve(coefficients=$>$\var{array of float values}) \end{quote} Apply a custom convolution kernel to the image. Given a particular kernel \var{order}, you must supply \var{order x order} float values. For example, a kernel of order 3 implies 9 values (3x3): {\small \begin{verbatim}$image->Convolve([1, 2, 1, 2, 4, 2, 1, 2, 1]); \end{verbatim} } \subsubsection{Crop} crop an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Crop(geometry=$>$\var{geometry}, width=$>$\var{integer}, height=$>$\var{integer}, x=$>$\var{integer}, y=$>$\var{integer}) \end{quote} Crop() extracts a region of the image starting at the offset defined by \texttt{x} and \texttt{y} and extending for \texttt{width} and \texttt{height}. \texttt{Geometry} is a shorthard method to define a region. To crop 100 x 50 region that begins at position (10, 20), use {\small \begin{verbatim}$image->Crop('100x50+10+20'); \end{verbatim} } \subsubsection{CycleColormap} displace a colormap. \begin{quote} \hspace*{-0.25in} \$image-$>$CycleColormap(display=$>$\var{integer}) \end{quote} CycleColormap() displaces an image's colormap by a given number of positions. If you cycle the colormap a number of times you can produce a psychodelic effect. \subsubsection{Deconstruct} return the constituent parts of an image sequence. \begin{quote} \hspace*{-0.25in} \$image-$>$Deconstruct() \end{quote} Deconstruct() returns a new sequence that consists of the first image in the sequence followed by the maximum bounding region of any differences in subsequent images. This method can undo a coalesced sequence returned by Coalesce(), and is useful for removing redundant information from a GIF or MNG animation. \subsubsection{Despeckle} filter speckles. \begin{quote} \hspace*{-0.25in} \$image-$>$Despeckle() \end{quote} Despeckle() reduces the {\em speckle} noise in an image while perserving the edges of the original image. \subsubsection{Display()} display image. \begin{quote} \hspace*{-0.25in} \$image-$>$Display(server=$>$\var{server-name}) \end{quote} Display() displays the image to any X window screen. \subsubsection{Draw} annotate an image with a graphic primitive. \begin{quote} \hspace*{-0.25in} \$image-$>$Draw(primitive=$>$\var{string}, affine=$>$\var{array of float values}, antialias=$>$\var{boolean}, bordercolor=$>$\var{color-name}, density=$>$\var{geometry}, fill=$>$\var{color-name}, font=$>$\var{string}, geometry=$>$\var{geometry}, method=$>$\var{string}, points=$>$\var{string}, pointsize=$>$\var{integer}, rotate=$>$\var{rotate-angle}, scale=$>$\var{sx, sy}, skewX=$>$\var{skew-angle}, skewY=$>$\var{skew-angle}, stroke=$>$\var{color-name}, strokewidth=$>$\var{integer}, translate=$>$\var{tx, ty} \end{quote} Draw() allows you to draw a graphic primitive on your image. The primitive may be represented as a string or filename. Precede the filename with an "at" sign (\texttt{@}) and the contents of the file are drawn on the image. You can affect how text is drawn by specifying one or more of the following parameters: \begin{description} \item[primitive] The primitive describes the type of graphic to draw. Choose from these primitives: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Point \> Line \> Rectangle \\ \> roundRectangle \> Arc \> Ellipse \\ \> Circle \> Polyline \> Polygon \\ \> Bezier \> Path \> Color \\ \> Matte \> Text \> Image \end{tabbing} \item[antialias] The visible effect of antialias is to smooth out the rounded corners of the drawn shape. Set to 0 to keep crisp edges. \item[bordercolor] The Color primitive with a method of FloodFill changes the color value of any pixel that matches \texttt{fill} and is an immediate neighbor. If \texttt{bordercolor} is specified, the color value is changed for any neighbor pixel that is not \texttt{fill}. \item[density] This parameter sets the vertical and horizontal resolution of the font. The default is 72 pixels/inch. \item[fill] The fill color paints any areas inside the outline of drawn shape. \item[font] A font can be a Truetype (arial.ttf), Postscript (Helvetica), or a fully-qualified X11 font (-*-helvetica-medium-r-*-*-12-*-*-*-*-*-iso8859-*). \item[geometry] Geometry defines the baseline position where the graphic primitive is rendered (e.g. +100+50). \item[method] Primitives Matte and Image behavior depends on the painting method you choose: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Point \> Replace \> Floodfull \\ \> FillToBorder \> Reset \end{tabbing} \item[points] List one or more sets of coordinates as required by the graphic primitive you selected. \item[pointsize] The font pointsize. The default is 12. \item[rotate] Specifies a rotation of \var{rotate-angle} degrees about a given point. \item[scale] Specifies a scale operation by \var{sx} and \var{sy}. \item[skewX] Specifies a skew transformation along the x-axis. \item[skewY] Specifies a skew transformation along the y-axis. \item[stroke] A stroke color paints along the outline of the shape. \item[strokewidth] The width of the stroke of the shape. A zero value means no stroke is painted. \item[translate] Specifies a translation by \var{tx} and \var{ty}. \end{description} \subsubsection{Edge} detect edges within an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Edge(radius=$>$\var{float}) \end{quote} Edge() finds edges in an image. \texttt{Radius} defines the radius of the convolution filter. Use a radius of 0 and Edge() selects a suitable radius for you. \subsubsection{Emboss} emboss the image. \begin{quote} \hspace*{-0.25in} \code{\$image-$>$Emboss(geometry=$>$\var{geometry}, radius=$>$\var{float}, sigma=$>$\var{float})} \end{quote} Emboss() returns a grayscale image with a three-dimensional effect. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and Emboss() selects a suitable radius for you. \texttt{Geometry} represents radius x sigma as one parameter (e.g. 0x1). \subsubsection{Enhance} filter a noisy image. \begin{quote} \hspace*{-0.25in} \$image-$>$Enhance() \end{quote} Enhance() applies a digital filter that improves the quality of a noisy image. \subsubsection{Equalize} equalize an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Equalize() \end{quote} Perform a histogram equalization on the image. \subsubsection{Flatten()} flatten a sequence of images. \begin{quote} \hspace*{-0.25in} \$image-$>$Coalesce() \end{quote} This method composites a sequence of images while respecting any page offsets. A Photoshop image typically starts with an image background and each subsequent layer varies in size and offset. Flatten() returns a single image with all the layers composited onto the first image in the sequence. \subsubsection{Flip} reflect an image vertically. \begin{quote} \hspace*{-0.25in} \$image-$>$Flip() \end{quote} Flip() creates a vertical mirror image by reflecting the pixels around the central x-axis. \subsubsection{Flop} reflect an image horizontally. \begin{quote} \hspace*{-0.25in} \$image-$>$Flop() \end{quote} Flop() creates a horizontal mirror image by reflecting the pixels around the central y-axis. \subsubsection{Frame} surround the image with a decorative border. \begin{quote} \hspace*{-0.25in} \$image-$>$Frame(geometry=$>$\var{geometry}, width=$>$\var{integer}, height=$>$\var{integer}, inner=$>$\var{integer}, outer=$>$\var{integer}, fill=$>$\var{color-name}) \end{quote} Frame() adds a simulated three-dimensional border around the image. The color of the border is defined by \texttt{fill}. \texttt{Width} and \texttt{height} specify the border width of the vertical and horizontal sides of the frame. The \texttt{inner} and \texttt{outer} parameters indicate the width of the inner and outer {\em shadows} of the frame. Use \texttt{Geometry} as a shortcut for \texttt{width}, \texttt{height}, \texttt{inner}, and \texttt{outer} (e.g. 10x10+3+3). \subsubsection{Gamma} gamma-correct the image. \begin{quote} \hspace*{-0.25in} \$image-$>$Gamma(gamma=$>$\var{string}, channel=$>$\var{Red, Green, Blue, Opacity, Index, Cyan, Yellow, Magenta, Black, or All}) \end{quote} Use Gamma() to gamma-correct an image. The same image viewed on different devices will have perceptual differences in the way the image's intensities are represented on the screen. Specify individual gamma levels for the red, green, and blue channels, or adjust all three with the \texttt{gamma} parameter. Values typically range from 0.8 to 2.3. You can also reduce the influence of a particular channel with a gamma value of 0. \subsubsection{Get()} get an image attribute. \begin{quote} \hspace*{-0.25in} \$image-$>$Get(\var{attribute}, ...) \end{quote} Get() accepts one or more image attributes listed in section \ref{Image::Magick Attributes} and return their value. \subsubsection{ImageToBlob()} return image as a Perl variable. \begin{quote} \hspace*{-0.25in} \$image-$>$ImageToBlob() \end{quote} ImageToBlob() behaves just like Write() except the image is returned as a Perl variable rather than written to disk. This method accepts the same parameters as Set() as described in section \ref{Image::Magick Attributes}. \subsubsection{Implode()} apply an implosion/explosion filter. \begin{quote} \hspace*{-0.25in} \$image-$>$Implode(amount=$>$\var{double}) \end{quote} Implode() applies a special effects filter to the image where \texttt{amount} determines the amount of implosion. Use a negative amount for an explosive effect. \subsubsection{Label()} add a label to an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Label(label=$>$\var{string}) \end{quote} Use labels to optionally annotate a Postscript or PDF image or the thumbnail images of a montage created by the Montage() method or \textit{montage} program. A label can include any of the special formatting characters described in the Comment() method description. \subsubsection{Level} adjust the level of image contrast. \begin{quote} \hspace*{-0.25in} \$image-$>$Level(levels=$>$\var{string}, 'black-point'=$>$\var{float}, 'mid-point'=$>$\var{float}, 'white-point'=$>$\var{float}) \end{quote} The white and black points range from 0 to MaxRGB and mid ranges from 0 to 10. \subsubsection{Magnify()} scale the image to twice its size. \begin{quote} \hspace*{-0.25in} \$image-$>$Magnify() \end{quote} Magnify() is a convenience method that scales an image proportionally to twice its size. \subsubsection{Map()} choose a set of colors from another image. \begin{quote} \hspace*{-0.25in} \$image-$>$Map(image=$>$\var{image-handle}, dither=$>$\var{boolean}) \end{quote} Map() changes the colormap of the image to that of the image given by \texttt{image}. Use this method to change the colormap in an image or image sequence to a set of predetermined colors. Set \texttt{dither} to a value other than zero to helps smooth out the apparent contours produced when sharply reducing colors. One useful example of mapping is to convert an image to the Netscape 216-color web safe palette: {\small \begin{verbatim}$safe = new Image::Magick; $safe->Read('Netscape:');$image->Map(image=>$safe, dither=>'True'); \end{verbatim} } \subsubsection{MatteFloodfill()} floodfill an area with transparency. \begin{quote} \hspace*{-0.25in} \$image-$>$MatteFloodfill(geometry=$>$\var{geometry}, x=$>$\var{integer}, y=$>$\var{integer}, opacity=$>$\var{integer}, bordercolor=$>$\var{color-name}, fuzz=$>$\var{float}) \end{quote} MatteFloodfill() changes the transparency value of any pixel that matches \texttt{opacity} and is an immediate neighbor. If \texttt{bordercolor} is specified, the transparency value is changed for any neighbor pixel that is not \texttt{bordercolor}. Use \texttt{Geometry} as a shortcut for {\it x + y} (e.g. +10+20). By default \texttt{opacity} must match a particular pixel transparency exactly. However, in many cases two transparency values may differ by a small amount. \texttt{Fuzz} defines how much tolerance is acceptable to consider two transparency values as the same. For example, set fuzz to 10 and the opacity values of 100 and 102 respectively are now interpreted as the same value for the purposes of the floodfill. \subsubsection{MedianFilter()} filter a noisy image. \begin{quote} \hspace*{-0.25in} \$image-$>$MedianFilter(radius=$>$\var{float}) \end{quote} MedianFilter() applies a digital filter that improves the quality of a noisy image. Each pixel is replaced by the median in a set of neighboring pixels as defined by \texttt{radius}. \subsubsection{Minify()} scale the image to half its size. \begin{quote} \hspace*{-0.25in} \$image-$>$Magnify() \end{quote} Minify() is a convenience method that scales an image proportionally to half its size. \subsubsection{Modulate} adjust the brightness, saturation, and hue. \begin{quote} \hspace*{-0.25in} \$image-$>$Modulate(factor=$>$\var{string}, brightness=$>$\var{float}, saturation=$>$\var{float}, hue=$>$\var{float}) \end{quote} Modulate() lets you control the brightness, saturation, and hue of an image. Each parameter is in the form of a percentage relative to 100. For example, to decrease the brightness by 10% and increase saturation by 50%, use: {\small \begin{verbatim}$image->Modulate(brightness=$>$90, saturation=$>$150); \end{verbatim} } \texttt{Factor} represents the brightness, saturation, and hue as one parameter (e.g. 90/150/100). \subsubsection{Mogrify()} alternative calling scheme. \begin{quote} \hspace*{-0.25in} \$image-$>$Mogrify(method, ...) \end{quote} The Mogrify() method is convenience function that allows you to call any image manipulation method by giving a method name followed by one or parameters to pass to the method. The following calls have the same result: {\small \begin{verbatim}$image->Crop('340x256+0+0') $image->Mogrify('Crop', '340x256+0+0') \end{verbatim} } \subsubsection{MogrifyRegion()} apply method to a region. \begin{quote} \hspace*{-0.25in} \$image-$>$MogrifyRegion(geometry, method, ...) \end{quote} MogrifyRegion() applies an image manipulation method to a region of the image as defined by \var{geometry}. For example if you want to sharpen a 100 x 100 region starting at position (20, 20), use: result: {\small \begin{verbatim} $image->MogrifyRegion('100x100+20+20', Sharpen, '0x1') \end{verbatim} } \subsubsection{Montage()} uniformly tile thumbnails across an image canvas. \begin{quote} \hspace*{-0.25in} \$image-$>$Montage(background=$>$\var{color-name}, bordercolor=$>$\var{color-name}, borderwidth=$>$\var{integer}, compose=$>$\var{string}, fill=$>$\var{color-name}, font=$>$\var{string}, frame=$>$\var{geometry}, geometry=$>$\var{geometry}, gravity=$>$\var{string}, label=$>$\var{string}, mattecolor=$>$\var{color-name}, mode=$>$\var{string}, pointsize=$>$\var{integer}, shadow=$>$\var{boolean}, stroke=$>$\var{color-name}, texture=$>$\var{string}, tile=$>$\var{geometry}, title=$>$\var{string}, transparent=$>$\var{color-name}) \end{quote} The Montage() method is a layout manager that lets you tile one or more thumbnails across an image canvas. Use these parameters to control how the layout manager places the thumbnails: \begin{description} \item[background] The color name for the montage background. \item[bordercolor] The color name for the thumbnail border. \item[borderwidth] The width of the thumbnail border. \item[compose] This operator affects how the thumbnail is composited on the image canvas. The default is Over. Choose from these operators: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Over, \> In \> Out \\ \> Atop \> Xor \> Plus \\ \> Minus \> Add \> Subtract \\ \> Difference \> Bumpmap \> Copy \\ \> Displace \end{tabbing} \item[fill] The fill color paints any areas inside the outline of the thumbnail label. \item[font] A font can be a Truetype (arial.ttf), Postscript (Helvetica), or a fully-qualified X11 font (-*-helvetica-medium-r-*-*-12-*-*-*-*-*-iso8859-*). \item[frame] Adds a simulated three-dimensional border around each thumbnail. The color of the border is defined by \texttt{mattecolor}. Specify the border width of the vertical and horizontal sides of the frame and the inner and outer {\em shadows} of the frame as a geometry (e.g. 10x10+3+3). \item[geometry] Geometry defines the baseline position where a thumbnail is composited (e.g. +100+50). \item[gravity] Gravity affects how the thumbnail is placed relative to the (\var{x, y}) baseline position. By default gravity is South which positions the thumbnail centered south of the baseline position. Choose from these gravities: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> NorthWest \> North \> NorthEast \\ \> West \> Center \> East \\ \> SouthWest \> South \> SouthEast \end{tabbing} \item[label] A label optionally appears just below each thumbnail. Use this parameter to customize the label. See Comment() for a list of embedded formatting options for the thumbnail label. \item[mode] Define one of three thumbnail framing options: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Frame \> Unframe \> Concatentate \end{tabbing} The default is \texttt{Frame} which adds a simulated three-dimensional border around each thumbnail. \texttt{Unframe} tiles thumbnails without any border or frame, and \texttt{Concatentate} causes each image to be tightly packed without any border, frame, or space between them. \item[pointsize] The font pointsize. The default is 12. \item[shadow] Any value other than 0 will add a simulated shadow beneath and to the right side of each thumbnail. \item[stroke] The stroke color paints along the outline of any text labels. \item[texture] Tile this image across and down the image canvas before compositing the image thumbnails. \item[tile] Give the number of thumbnails across and down the canvas as a geometry string. The default is 5 x 4. If the number of thumbnails exceed this maximum, more then one image canvas is created. \item[title] Give a title to the montage. The title is centered near the top of the montage image. \item[transparent] Make this color transparent. \end{description} \subsubsection{Mosaic()} form a single coherent picture. \begin{quote} \hspace*{-0.25in} \$image-$>$Mosiac() \end{quote} The Mosaic() method takes a set of images and inlays them to form a single coherent pictiure. Mosaic() returns a single image with each image in the sequence inlayed in the image canvas at an offset as defined in the image. {\small \begin{verbatim}$mosaic = $image->Mosaic(); \end{verbatim} } \subsubsection{MotionBlur()} simulate motion blur. \begin{quote} \hspace*{-0.25in} \$image-$>$MotionBlur(geometry=$>$\var{geometry}, radius=$>$\var{float}, sigma=$>$\var{float}, angle=$>$\var{float}) \end{quote} MotionBlur() simulates motion blur. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and MotionBlur() selects a suitable radius for you. \texttt{Geometry} represents radius x sigma as one parameter (e.g. 0x1). \texttt{Angle} gives the angle of the blurring motion. \subsubsection{Morph()} morph a set of images. \begin{quote} \hspace*{-0.25in} \$image-$>$Morph(frames=$>$\var{integer}) \end{quote} The Morph() method requires a minimum of two images. The first image is transformed into the second by a number of intervening images as specified by \texttt{frames}. The result is returned as a new image sequence, for example: {\small \begin{verbatim}$morph = $image->Morph(30); \end{verbatim} } \subsubsection{Negate} apply color inversion. \begin{quote} \hspace*{-0.25in} \$image-$>$Negate(gray=$>$\var{boolean}) \end{quote} Negate() negates the intensities of each pixel in the image. If \texttt{gray} is a value other than 0, only the grayscale pixels are inverted. \subsubsection{New()} create an image object. \begin{quote} \hspace*{-0.25in} \$image = new Image::Magick; \\ \$image = Image::Magick->New() \end{quote} New() instantiates an image object. As a convenience, you can set any image attribute that Set() knows about. See section \ref{Get or Set an Image Attribute} for a list of known image attributes. Here is an example: {\small \begin{verbatim} $image = Image::Magick->New(size=>'160x120');$image->Read('gray:protein'); \end{verbatim} } \subsubsection{Normalize()} enhance image contrast. \begin{quote} \hspace*{-0.25in} \$image-$>$Normalize() \end{quote} The Normalize() method enhances the contrast of a color image by adjusting the pixels color to span the entire range of colors available. \subsubsection{OilPaint()} simulate an oil painting. \begin{quote} \hspace*{-0.25in} \$image-$>$OilPaint(radius=$>$\var{integer}) \end{quote} OilPaint() applies a special effect filter that simulates an oil painting. Each pixel is replaced by the most frequent color occurring in a circular region defined by \texttt{radius}. \subsubsection{Opaque()} globally change a color. \begin{quote} \hspace*{-0.25in} \$image-$>$Opaque(color=$>$\var{color-name}, fill=$>$\var{color-name}, fuzz=$>$\var{float}) \end{quote} Opaque() changes any pixel that matches \texttt{color} with the color defined by \texttt{fill}. By default \texttt{color} must match a particular pixel color exactly. However, in many cases two colors may differ by a small amount. \texttt{Fuzz} defines how much tolerance is acceptable to consider two colors as the same. For example, set fuzz to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color. \subsubsection{OrderedDither()} reduce the image to black and white. \begin{quote} \hspace*{-0.25in} \$image-$>$OrderedDither() \end{quote} The OrderedDither() method reduces the image to black and white. \subsubsection{Ping()} get information about an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Ping(filename=$>$\var{string}, file=$>$\var{file-handle}, blob=$>$\var{blob}) \end{quote} 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: {\small \begin{verbatim} ($width, $height,$size, $format) =$image->Ping('logo.gif'); ($width,$height, $size,$format) = $image->Ping(file=>\*IMAGE); ($width, $height,$size, $format) =$image->Ping(blob=>\$blob); \end{verbatim} } \subsubsection{Profile()} add, remove, or apply an image profile. \begin{quote} \hspace*{-0.25in} \$image-$>$Profile(name=$>$\var{variable}, profile=$>$\var{blob}) \end{quote} The Profile() method adds, removes, or applies an image profile. The two most common profiles are ICC, a color management option, IPTC, a newswire profile, and APP1, which is a JPEG marker that can contain EXIF data. \texttt{Profile} is a Perl variable representing the binary profile information. To remove all profiles from the image, use an asterick as the profile name: {\small \begin{verbatim} $image->Profile('*'); \end{verbatim} } \subsubsection{Quantize()} set the maximum number of colors in an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Quantize(colors=$>$\var{integer}, colorspace=$>$\var{string}, dither=$>$\var{boolean}, global\_colormap=$>$\var{boolean} measure\_error=$>$\var{boolean}, tree\_depth=$>$\var{integer}) \end{quote} The Quantize() method sets the maximum number of colors in an image. If the number of colors in the image exceeds \texttt{colors}, a color reduction algorithm repeatly merges pixels of similar color until the total number of unique colors is less or equal to the maximum. Here is a description of the color reduction parameters: \begin{description} \item[colors] Set the maximum number of colors in the image. \item[colorspace] By default, color merging is performed in the RGB colorspace. However, RGB is not perceptually uniform like YCbCr for example. You may get better results by trying one of the following colorspaces: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> CMYK \> Gray \> OHTA \\ \> RGB \> sRGB \> Transparent \\ \> XYZ \> YCbCr \> YCC \\ \> YIQ \> YPbPr \> YUV \end{tabbing} \item[dither] Images which suffer from severe contouring when reducing colors can be improved with this option. \item[global\_colormap] A value other than 0 creates one global colormap for a sequence of images. \item[measure\_error] A value other than 0 returns a measure of how closely the color reduced image matches the original. The mean error, normalized mean error, and normalized maximum mean error per pixel are computed. Obtain these values with the Get() method. \item[tree\_depth] By default, the color reduction uses a Oct-tree algorithm whose depth ranges from 1-8 which is optimally determined to allow the best representation of the image with the fastest computational speed and least amount of memory consumption. You can override the default with this parameter. \end{description} \subsubsection{QueryColor()} return numerical values corresponding to a color name. \begin{quote} \hspace*{-0.25in} \$image-$>$QueryColor( ... ) \end{quote} 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. {\small \begin{verbatim} @colors =$image->QueryColor(); ($red,$green, $blue,$opacity) = $image->QueryColor('red'); ($red, $green,$blue, $opacity) =$image->QueryColor('#716bae'); \end{verbatim} } \subsubsection{QueryColorname()} return a color name corresponding to the numerical values. \begin{quote} \hspace*{-0.25in} \$image-$>$QueryColorname( ... ) \end{quote} QueryColorname() accepts one or more numerical values and returns their respective color name: {\small \begin{verbatim}$color = $image->QueryColorname('rgba(65535,0,0,0)'); \end{verbatim} } \subsubsection{QueryFont()} get font attributes. \begin{quote} \hspace*{-0.25in} \$image-$>$QueryFont( ... ) \end{quote} 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. {\small \begin{verbatim} @fonts = $image->QueryFont();$weight = ($image->QueryFont('Helvetica'))[5]; \end{verbatim} } \subsubsection{QueryFontMetrics()} query font metrics. \begin{quote} \hspace*{-0.25in} \$image-$>$QueryFontMetrics(font=>\var{string}, ... ) \end{quote} QueryFontMetrics() accepts a font name and any parameter acceptable to Annotate(). The method returns these attributes associated with the given font: \begin{itemize} \item character width \item character height \item ascender \item descender \item text width \item text height \item maximum horizontal advance \end{itemize} For example, {\small \begin{verbatim} @metrics = $image->QueryFontMetrics(font=>'arial.ttf', pointsize=>24); \end{verbatim} } \subsubsection{QueryFormat()} get image format attributes. \begin{quote} \hspace*{-0.25in} \$image-$>$QueryFormat( ... ) \end{quote} 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, format, decoder, encoder, description, and module. {\small \begin{verbatim} @formats = $image->QueryFormat(); ($adjoin, $blob_support,$raw, $decoder,$encoder, $description,$module) = $image->QueryFormat('gif'); \end{verbatim} } \subsubsection{Raise()} lighten or darken edges to create a 3-D effect. \begin{quote} \hspace*{-0.25in} \$image-$>$Raise(geometry=$>$\var{geometry}, width=$>$\var{integer}, height=$>$\var{integer}, raise=$>$\var{boolean}) \end{quote} Raise() creates a simulated three-dimensional button-like effect by lightening and darkening the edges of the image. \texttt{Width} and \texttt{height} define the width of the vertical and horizontal edge of the effect. Use \texttt{Geometry} as a shortcut for \texttt{width} and \texttt{height} (e.g. 10x10). A value other than 0 for \texttt{raise} simulates a raised button-like effect otherwise a sunken button-like effect is applied to the image. \subsubsection{Read()} read one or more image files. \begin{quote} \hspace*{-0.25in} \$image-$>$Read(filename=$>$\var{float}, file=$>$\var{file-handle}) \end{quote} \begin{description} \item[filename] the name of an image file. \item[file-handle] read the image from an open filehandle. \end{description} The Read() method reads an image or image sequence from one or more filenames or the filehandle you specify. You can specify more than one filename but only one filehandle: {\small \begin{verbatim}$image->Read(filename=>'logo.gif'); # read a single GIF into # $image object.$image->Read('logo.jpg', 'button.gif'); # read two images. $image->Read('*.png'); # read all the PNG files in the # current directory.$image->Read(file=>\*IMAGE); # read from open Perl filehandle. \end{verbatim} } Read() returns the number of images that were successfully read. \subsubsection{ReduceNoise()} smooth an image. \begin{quote} \hspace*{-0.25in} \$image-$>$ReduceNoise(radius=$>$\var{float}) \end{quote} The ReduceNoise() method smooths the contours of an image while still preserving edge information. The algorithm works by replacing each pixel with its neighbor closest in value. A neighbor is defined by \texttt{radius}. Use a radius of 0 and ReduceNoise() selects a suitable radius for you. \subsubsection{Resize()} scale an image with a filter. \begin{quote} \hspace*{-0.25in} \$image-$>$Resize(geometry=$>$\var{geometry}, width=$>$\var{integer}, height=$>$\var{integer}, filter=$>$\var{string}, blur=$>$\var{float}) \end{quote} Resize() scales an image to the desired dimensions with one of these filters: \begin{tabbing} 0000\=1111111111111111\=2222222222222222\=3333333333333333\kill \> Bessel \> Blackman \> Box \\ \> Catrom \> Cubic \> Gaussian \\ \> Hanning \> Hermite \> Lanczos \\ \> Mitchell \> Point \> Quadratic \\ \> Sinc \> Triangle \> \end{tabbing} The default is Lanczos. Use \texttt{width} and \texttt{height} to specify the image size, or use \texttt{geometry} as a shortcut (e.g. 640x480). Set \texttt{Blur} to a value greater than 1 to blur the image as it is scaled. A value less than 1 sharpens as the image is scaled. \subsubsection{Roll()} offset and roll over an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Roll(geometry=$>$\var{geometry}, x=$>$\var{integer}, y=$>$\var{integer}) \end{quote} Roll() offsets an image as defined by \texttt{x} and \texttt{y}. \texttt{Geometry} represents + x + y as one parameter (e.g. +10+20). \subsubsection{Rotate()} rotate an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Rotate(degrees=$>$\var{float}, color=$>$\var{color-name}) \end{quote} Rotate() rotates an image around the x axis by the number of degrees by \texttt{degrees}. Any empty spaces are filled with \texttt{color}. \subsubsection{Sample()} sample an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Sample(geometry=$>$\var{geometry}, width=$>$\var{integer}, height=$>$\var{integer}) \end{quote} Sample() scales an image to the desired dimensions with pixel sampling. Unlike other scaling methods, this method does not introduce any additional color into the scaled image. Use \texttt{width} and \texttt{height} to specify the image size, or use \texttt{geometry} as a shortcut (e.g. 640x480). \subsubsection{Scale()} scale an image to given dimensions. \begin{quote} \hspace*{-0.25in} \$image-$>$Scale(geometry=$>$\var{geometry}, width=$>$\var{integer}, height=$>$\var{integer}) \end{quote} Scale() changes the size of an image to the given dimensions. Use \texttt{width} and \texttt{height} to specify the image size, or use \texttt{geometry} as a shortcut (e.g. 640x480). \subsubsection{Segment()} segment an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Segment(geometry=$>$\var{geometry}, cluster\_threshold=$>$\var{float}, smoothing\_threshold=$>$\var{float}, colorspace=$>$\var{string}, verbose=$>$\var{boolean}) \end{quote} Segment() segments an image by by analyzing the histograms of the color components and identifying units that are homogeneous. The default value for \texttt{cluster\_threshold} is 1.0 and \texttt{smoothing\_threshold} is 1.5. This can be represented with a shortcut geometry of 1.0x1.5. \subsubsection{Set()} set an image attribute. \begin{quote} \hspace*{-0.25in} \$image-$>$Set(\var{attribute}, ...) \end{quote} Set() accepts one or more image attributes listed in section \ref{Image::Magick Attributes} and sets their value. \subsubsection{Shade()} shade the image with light source. \begin{quote} \hspace*{-0.25in} \$image-$>$Shade(geometry=$>$\var{geometry}, azimuth=$>$\var{float}, elevation=$>$\var{float}, color=$>$\var{boolean}) \end{quote} Shade() shines a distant light on an image to create a three-dimensional effect. You control the positioning of the light with \var{azimuth} and \var{elevation}; azimuth is measured in degrees off the x axis and elevation is measured in pixels above the Z axis. The geometry parameter is a shortcut for azimuth x elevation (e.g. 30x30). \subsubsection{Sharpen()} sharpen an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Sharpen(geometry=$>$\var{geometry}, radius=$>$\var{float}, sigma=$>$\var{float}) \end{quote} Sharpen() sharpens an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and Sharpen() selects a suitable radius for you. \texttt{Geometry} represents radius x sigma as one parameter (e.g. 0x1). \subsubsection{Shave()} shave pixels from the image edges. \begin{quote} \hspace*{-0.25in} \$image-$>$Border(geometry=$>$\var{geometry}, width=$>$\var{integer}, height=$>$\var{integer}) \end{quote} This method shaves pixels from the image edges. \texttt{Geometry} represents {\it width x height} as one parameter (e.g. 10x5). \subsubsection{Shear()} shear an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Shear(geometry=$>$\var{geometry}, x=$>$\var{float}, y=$>$\var{float}, color=$>$\var{color-name}) \end{quote} Shear() transforms an image by shearing it along the x or y axis. The \texttt{x} and \texttt{y} parameters specify the degree of shear and ranges from -179.9 to 179.9. \texttt{Geometry} represents x x y as one parameter (e.g. 30x60). Any empty spaces created when shearing are filled with \texttt{color}. \subsubsection{Signature()} generate an SHA-256 message digest. \begin{quote} \hspace*{-0.25in} \$image-$>$Signature() \end{quote} Signature() generates an SHA-256 message digest across all the image pixels. The signature can later be used to verify the color integrity of the image. Two images with the same signature are identical. \subsubsection{Solarize()} apply solorization special effect. \begin{quote} \hspace*{-0.25in} \$image-$>$Solarize(threshold=$>$\var{float}) \end{quote} Solarize() applies a special effect to the image, similar to the effect achieved in a photo darkroom by selectively exposing areas of photo sensitive paper to light. \texttt{Threshold} ranges from 0 to MaxRGB and is a measure of the extent of the solarization. \subsubsection{Spread()} randomly displace pixels. \begin{quote} \hspace*{-0.25in} \$image-$>$Spread(amount=$>$\var{integer}) \end{quote} Spead() is a special effects method that randomly displaces each pixel in a block defined by the \texttt{amount} parameter. \subsubsection{Stereo()} create a stereo special effect. \begin{quote} \hspace*{-0.25in} \$image-$>$Stereo(image=$>$\var{image-handle}) \end{quote} Stereo() combines two images and produces a single image that is the composite of a left and right image of a stereo pair. Special red-green stereo glasses are required to view this effect. \subsubsection{Stegano()} hide a digital watermark. \begin{quote} \hspace*{-0.25in} \$image-$>$Stegano(image=$>$\var{image-handle}, offset=$>$\var{integer}) \end{quote} Use Stegano() to hide a digital watermark within the image. Recover the hidden watermark later to prove that the authenticity of an image. texttt{Offset} defines the start position within the image to hide the watermark. \subsubsection{Swirl()} swirl pixels about image center. \begin{quote} \hspace*{-0.25in} \$image-$>$Swirl(degrees=$>$\var{float}) \end{quote} The Swirl() method swirls the pixels about the center of the image, where \texttt{degrees} indicates the sweep of the arc through which each pixel is moved. You get a more dramatic effect as the degrees move from 1 to 360. \subsubsection{Texture()} tile a texture on image background. \begin{quote} \hspace*{-0.25in} \$image-$>$Texture(texture=$>$\var{image-handle}) \end{quote} Texture() repeatedly tiles the texture image across and down the image canvas. \subsubsection{Threshold()} divide pixels based on intensity values. \begin{quote} \hspace*{-0.25in} \$image-$>$Threshold(threshold=$>$\var{integer}) \end{quote} Threshold() changes the value of individual pixels based on the intensity of each pixel compared to \texttt{threshold}. The result is a high-contrast, two color image. \subsubsection{Transform()} resize or crop an image. \begin{quote} \hspace*{-0.25in} \$image-$>$Transform(geometry=$>$\var{string}, crop=$>$\var{string}) \end{quote} Transform() behaves like Resize() or Crop() but rather than acting on the image, it returns a new image handle: {\small \begin{verbatim}$slices = $image->Transform(crop=>'100x100') \end{verbatim} } \subsubsection{Transparent()} make color transparent. \begin{quote} \hspace*{-0.25in} \$image-$>$Transparent(color=$>$\var{color-name}, opacity=$>$\var{integer} fuzz=$>$\var{float}) \end{quote} Transparent() changes the opacity value associated with any pixel that matches \texttt{color} to the value defined by \texttt{opacity}. By default \texttt{color} must match a particular pixel color exactly. However, in many cases two colors may differ by a small amount. \texttt{Fuzz} defines how much tolerance is acceptable to consider two colors as the same. For example, set fuzz to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color. \subsubsection{Trim()} remove background color from edges of image. \begin{quote} \hspace*{-0.25in} \$image-$>$Trim(fuzz=$>$\var{float}) \end{quote} Trim() crops a rectangular box around the image to remove edges that are the background color. By default the edge pixels must match in color exactly to be trimmed. However, in many cases two colors may differ by a small amount. \texttt{Fuzz} defines how much tolerance is acceptable to consider two colors as the same. For example, set fuzz to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color. \subsubsection{UnsharpMask()} sharpen an image. \begin{quote} \hspace*{-0.25in} \$image-$>$UnsharpMask(geometry=$>$\var{geometry}, radius=$>$\var{float}, sigma=$>$\var{float}, amount=$>$\var{float}, threshold=$>$\var{float}) \end{quote} UnsharpMask() sharpens an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and UnsharpMask() selects a suitable radius for you. \texttt{Geometry} represents radius x sigma as one parameter (e.g. 0x1). \subsubsection{Wave()} special effects filter. \begin{quote} \hspace*{-0.25in} \$image-$>$Wave(geometry=$>$\var{string}, amplitude=$>$\var{float}, wavelength=$>$\var{float}) \end{quote} The Wave() filter creates a "ripple" effect in the image by shifting the pixels vertically along a sine wave whose amplitude and wavelength is specified by the given parameters. \texttt{Geometry} represents amplitude x wavelength as one parameter (e.g. 30x30). \subsubsection{Write()} write one or more image files. \begin{quote} \hspace*{-0.25in} \$image-$>$Write(filename=$>$\var{float}, file=$>$\var{file-handle}) \end{quote} Write() allows you to write a single or image or a sequence to a file or filehandle. You can specify more than one filename but only one filehandle: {\small \begin{verbatim} $image->Write(filename=>'logo.gif'); # write a single GIF image.$image->Write('logo.jpg', 'button.gif'); # write two images. $image->Write('gif:-'); # write to STDOUT.$image->[0]->Write('logo.png'); # write only first image # in a sequence. \$image->Write(file=>\*IMAGE); # write to a open Perl filehandle. \end{verbatim} } Write() returns the number of images that were written. \section{Image::Magick Errors} Most Image::Magick methods return an undefined value if the operation was successful. When an error occurs, a message is returned with an embedded numeric status code. Look up the status code in table \ref{Error and Warning Codes} to determine the reason the operation failed. The mnemonics are aliases for the the corresponding numeric codes. \begin{longtable}{p{1cm} | p{4cm} | p{8cm}} \caption{Error and Warning Codes} \\[0.5in] \multicolumn{3}{c}{Error and Warning Codes}\\[0.5in] \textbf{Code} & \textbf{Mnemonic} & \textbf{Description} \\ \hline \endfirsthead \multicolumn{3}{c}{Error and Warning Codes (continued)}\\[0.5in] \textbf{Code} & \textbf{Mnemonic} & \textbf{Description} \\ \hline \endhead 0 & Success & Method completed without an error or warning. \\ 300 & ResourceLimitWarning & A program resource is exhausted (e.g. not enough memory). \\ 305 & TypeWarning & A font is unavailable; a substitution may have occured. \\ 310 & OptionWarning & An option parameter was malformed. \\ 315 & DelegateWarning & An ImageMagick {\em delegate} returned a warning. \\ 320 & MissingDelegateWarning & The image type can not be read or written because the required {\em delegate} is missing. \\ 325 & CorruptImageWarning & The image file may be corrupt. \\ 330 & FileOpenWarning & The image file could not be opened. \\ 335 & BlobWarning & A Binary Large OBject could not be allocated. \\ 340 & StreamWarning & There was a problem reading or writing from a stream. \\ 345 & CacheWarning & Pixels could not be saved to the pixel cache. \\ 385 & XServerWarning & An X resource is unavailable. \\ 390 & RegistryWarning & There was a problem getting or setting the registry. \\ 395 & ConfigureWarning & There was a problem getting a configuration file. \\ 400 & ResourceLimitError & A program resource is exhausted (e.g. not enough memory). \\ 405 & TypeError & A font is unavailable; a substitution may have occured. \\ 410 & OptionError & An option parameter was malformed. \\ 415 & DelegateError & An ImageMagick {\em delegate} returned a warning. \\ 420 & MissingDelegateError & The image type can not be read or written because the required {\em delegate} is missing. \\ 425 & CorruptImageError & The image file may be corrupt. \\ 430 & FileOpenError & The image file could not be opened. \\ 435 & BlobError & A Binary Large OBject could not be allocated. \\ 440 & StreamError & There was a problem reading or writing from a stream. \\ 445 & CacheError & Pixels could not be saved to the pixel cache. \\ 485 & XServerError & An X resource is unavailable. \\ 490 & RegistryError & There was a problem getting or setting the registry. \\ 495 & ConfigureError & There was a problem getting a configuration file. \\ \end{longtable}