Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

4681 lines (3263 sloc) 130.408 kB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org" />
<title>RMagick 0.0.0: class Image (class methods and instance
methods a-d)</title>
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii" />
<meta name="GENERATOR" content="Quanta Plus" />
<meta name="Copyright" content=
"Copyright (C) 2006 by Timothy P. Hunter" />
<link rel="stylesheet" type="text/css" href="css/doc.css" />
<script type="text/javascript" src="scripts/doc.js">
</script>
<script type="text/javascript">
//<![CDATA[
<!-- Pre-load this image so that the browser knows how big it is. -->
flower_hat = new Image();
flower_hat.src = "ex/images/Flower_Hat.jpg";
function show_noise(type)
{
if (type == null)
{
document.getElementById("add_noise_example").src = "ex/images/Flower_Hat.jpg";
}
else
{
document.getElementById("add_noise_example").src = "ex/add_noise_" + type + ".jpg";
}
}
//]]>
</script>
<style type="text/css">
/*<![CDATA[*/
.noise_example_wrapper img {
float: left;
}
.noise_example_wrapper p, .noise_example_wrapper ul {
margin-left: 4px;
float: left;
}
/*]]>*/
</style>
</head>
<body>
<h6 id="header">RMagick 0.0.0 User's Guide and Reference</h6>
<div class="nav">
&laquo;&nbsp;<a href="imageattrs.html">Prev</a> | <a href=
"index.html">Contents</a> | <a href=
"image2.html">Next</a>&nbsp;&raquo;
</div>
<h1>class Image <span class="superclass">&lt; Object</span>
(class methods and instance methods a-d)<br />
<span class="mixin">mixes in Comparable</span></h1>
<div id="toc">
<h2>Table of Contents</h2>
<h3>class methods</h3>
<div>
<div class="toccol">
<ul>
<li><a href="#capture">capture</a></li>
<li><a href="#combine">combine</a></li>
<li><a href="#constitute">constitute</a></li>
</ul>
</div>
<div class="toccol">
<ul>
<li><a href="#from_blob">from_blob</a></li>
<li><a href="#new">new</a></li>
<li><a href="#ping">ping</a></li>
</ul>
</div>
<div class="toccol">
<ul>
<li><a href="#read">read</a></li>
<li><a href="#read_inline">read_inline</a></li>
</ul>
</div>
</div>
<h3>instance methods</h3>
<div>
<div class="toccol">
<ul>
<li><a href="#aref">[&nbsp;]</a></li>
<li><a href="#aset">[&nbsp;]=</a></li>
<li><a href="#spaceship">&lt;=&gt;</a></li>
<li><a href="#adaptive_blur">adaptive_blur</a></li>
<li><a href=
"#adaptive_blur_channel">adaptive_blur_channel</a></li>
<li><a href="#adaptive_resize">adaptive_resize</a></li>
<li><a href="#adaptive_sharpen">adaptive_sharpen</a></li>
<li><a href=
"#adaptive_sharpen_channel">adaptive_sharpen_channel</a></li>
<li><a href=
"#adaptive_threshold">adaptive_threshold</a></li>
<li><a href="#add_compose_mask">add_compose_mask</a></li>
<li><a href="#add_noise">add_noise</a></li>
<li><a href=
"#add_noise_channel">add_noise_channel</a></li>
<li><a href="#add_profile">add_profile</a></li>
<li><a href="#affine_transform">affine_transform</a></li>
<li><a href="#alpha">alpha</a></li>
<li><a href="#alpha_q">alpha?</a></li>
<li><a href="#annotate">annotate</a></li>
<li><a href=
"#auto_gamma_channel">auto_gamma_channel</a></li>
<li><a href=
"#auto_level_channel">auto_level_channel</a></li>
<li><a href="#auto_orient">auto_orient</a></li>
<li><a href="#auto_orient_bang">auto_orient!</a></li>
<li><a href="#bilevel_channel">bilevel_channel</a></li>
<li><a href="#black_threshold">black_threshold</a></li>
<li><a href="#blend">blend</a></li>
<li><a href="#blue_shift">blue_shift</a></li>
<li><a href="#blur_channel">blur_channel</a></li>
<li><a href="#blur_image">blur_image</a></li>
</ul>
</div>
<div class="toccol">
<ul>
<li><a href="#border">border</a></li>
<li><a href="#border_bang">border!</a></li>
<li><a href="#bounding_box">bounding_box</a></li>
<li><a href="#change_geometry">change_geometry</a></li>
<li><a href="#changed_q">changed?</a></li>
<li><a href="#channel">channel</a></li>
<li><a href="#channel_depth">channel_depth</a></li>
<li><a href="#channel_extrema">channel_extrema</a></li>
<li><a href="#channel_mean">channel_mean</a></li>
<li><a href="#charcoal">charcoal</a></li>
<li><a href="#check_destroyed">check_destroyed</a></li>
<li><a href="#chop">chop</a></li>
<li><a href="#clone">clone</a></li>
<li><a href="#clut_channel">clut_channel</a></li>
<li><a href=
"#color_fill_to_border">color_fill_to_border</a></li>
<li><a href="#color_floodfill">color_floodfill</a></li>
<li><a href="#color_histogram">color_histogram</a></li>
<li><a href="#colorize">colorize</a></li>
<li><a href="#colormap">colormap</a></li>
<li><a href="#color_point">color_point</a></li>
<li><a href="#color_reset_bang">color_reset!</a></li>
<li><a href="#compare_channel">compare_channel</a></li>
<li><a href="#composite">composite</a></li>
<li><a href="#composite_bang">composite!</a></li>
<li><a href="#composite_affine">composite_affine</a></li>
<li><a href=
"#composite_mathematics">composite_mathematics</a></li>
<li><a href="#composite_tiled">composite_tiled</a></li>
</ul>
</div>
<div class="toccol">
<ul>
<li><a href=
"#composite_tiled_bang">composite_tiled!</a></li>
<li><a href=
"#compress_colormap_bang">compress_colormap!</a></li>
<li><a href="#contrast">contrast</a></li>
<li><a href=
"#contrast_stretch_channel">contrast_stretch_channel</a></li>
<li><a href="#convolve">convolve</a></li>
<li><a href="#convolve_channel">convolve_channel</a></li>
<li><a href="#copy">copy</a></li>
<li><a href="#crop">crop</a></li>
<li><a href="#crop_bang">crop!</a></li>
<li><a href="#crop_resized">crop_resized</a></li>
<li><a href="#cycle_colormap">cycle_colormap</a></li>
<li><a href="#decipher">decipher</a></li>
<li><a href=
"#delete_compose_mask">delete_compose_mask</a></li>
<li><a href="#delete_profile">delete_profile</a></li>
<li><a href="#deskew">deskew</a></li>
<li><a href="#despeckle">despeckle</a></li>
<li><a href="#destroy_bang">destroy!</a></li>
<li><a href="#destroyed_q">destroyed?</a></li>
<li><a href="#difference">difference</a></li>
<li><a href="#dispatch">dispatch</a></li>
<li><a href="#displace">displace</a></li>
<li><a href="#display">display</a></li>
<li><a href="#dissolve">dissolve</a></li>
<li><a href="#distort">distort</a></li>
<li><a href=
"#distortion_channel">distortion_channel</a></li>
<li><a href="#dup">dup</a></li>
</ul>
</div>
</div>
</div>
<h2 class="methods">class methods</h2>
<div class="sig">
<h3 id="capture">capture</h3>
<p>Image.capture(<span class=
"arg">silent=</span><code>false</code>, <span class=
"arg">frame=</span><code>false</code>, <span class=
"arg">descend=</span><code>false</code>, <span class=
"arg">screen=</span><code>false</code>, <span class=
"arg">borders=</span><code>false</code>) [ <span class=
"arg">{&nbsp;optional arguments&nbsp;}</span> ] -&gt;
<em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Reads an image from an X window. Unless you identify a
window to capture via the <em>optional arguments</em> block,
when <code>capture</code> is invoked the cursor will turn into
a cross. Click the cursor on the window to be captured.</p>
<p>Within the optional arguments block, specify
<code>self.filename = "root"</code> to capture the entire
desktop. To programatically specify the window to be captured,
use <code>self.filename = window_id</code>, where window_id is
the id displayed by xwininfo(1).</p>
<h4>Arguments</h4>
<dl>
<dt>silent</dt>
<dd>If <code>true</code>, suppress the beeps that signal the
start and finish of the capture process. The bell rings once
to signal the start of the capture and twice to signal the
finish.</dd>
<dt>frame</dt>
<dd>If <code>true</code>, include the window frame.</dd>
<dt>descend</dt>
<dd>If <code>true</code>, <span class="imquote">obtain image
by descending window hierarchy.</span></dd>
<dt>screen</dt>
<dd>If <code>true</code>, specifies that <span class=
"imquote">the GetImage request used to obtain the image
should be done on the root window, rather than directly on
the specified window. In this way, you can obtain pieces of
other windows that overlap the specified window, and more
importantly, you can capture menus or other popups that are
independent windows but appear over the specified
window.</span></dd>
<dt>borders</dt>
<dd>If <code>true</code>, include the border in the
image.</dd>
<dt>optional arguments</dt>
<dd>You can specify any of these Image::Info attributes in
the <em>optional arguments</em> block: <a href=
"info.html#colorspace">colorspace</a>, <a href=
"info.html#depth">depth</a>, <a href=
"info.html#dither">dither</a>, <a href=
"info.html#interlace">interlace</a>, and <a href=
"info.html#type">type</a>.</dd>
</dl>
<h4>Returns</h4>
<p>A new image.</p>
<h4>Example</h4>
<pre>
img = Image.capture {
self.filename = "root"
}
</pre>
</div>
<div class="sig">
<h3 id="combine">combine</h3>
<p>Image.combine(<span class="arg">red_ch</span>=nil,
<span class="arg">green_ch</span>=nil, <span class=
"arg">blue_ch</span>=nil<span class="arg">,
opacity_ch</span>=nil) -&gt;<em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Combines the grayscale value of the pixels in each image to
form a new image.</p>
<h4>Arguments</h4>
<p>The red channel of the image specified in the first argument
is used as the red channel in the new image. The green channel
of the image specified in the second argument is used as the
green channel in the new image. The blue channel of the image
specified in the third argument is used as the blue channel in
the new image. The opacity channel of the image specified in
the fourth argument is used as the opacity channel in the new
image.</p>
<p>Any of the arguments may be nil. Trailing nil arguments may
be omitted. You must specify at least one image argument.</p>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p>The same results can be obtained using the <a href=
"#composite">composite</a> method and the
CopyRed/Green/Blue/OpacityCompositeOp <a href=
"constants.html#CompositeOperator">CompositeOperator</a> enum
values.</p>
<h4>Magick API</h4>
<p>CombineImages</p>
</div>
<div class="sig">
<h3 id="constitute">constitute</h3>
<p>Image.constitute(<span class="arg">width</span>,
<span class="arg">height</span>, <span class="arg">map</span>,
<span class="arg">pixels</span>) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Creates an image from an array of pixels. This method is the
reverse of <a href="#dispatch"><code>dispatch</code></a>.</p>
<h4>Arguments</h4>
<dl>
<dt>width</dt>
<dd>The number of columns in the image</dd>
<dt>height</dt>
<dd>The number of rows in the image</dd>
<dt>map</dt>
<dd>A string describing <span class="imquote">the expected
ordering of the pixel array. It can be any combination or
order of R = red, G = green, B = blue, A = alpha, C = cyan, Y
= yellow, M = magenta, K = black, or I = intensity (for
grayscale).</span></dd>
<dt>pixels</dt>
<dd>The pixel data. The pixel data in the array must be
stored in scanline order, left-to-right and top-to-bottom.
The elements in the array must be either all
<code>Integers</code> or all <code>Floats</code>. If the
elements are <code>Integers</code>, the <code>Integers</code>
must be in the range [0..QuantumRange]. If the elements are
<code>Floats</code>, they must be in the range [0..1].</dd>
</dl>
<h4>Returns</h4>
<p>An image constructed from the pixel data.</p>
<h4>Example</h4>
<pre>
image = Image.constitute(width, height, "RGB", pixels)
</pre>
<h4>See also</h4>
<p><a href=
"image2.html#import_pixels"><code>import_pixels</code></a>,
<a href=
"image3.html#store_pixels"><code>store_pixels</code></a></p>
<h4>Magick API</h4>
<p>ConstituteImage</p>
</div>
<div class="sig">
<h3 id="from_blob">from_blob</h3>
<p>Image.from_blob(<span class="arg">string</span>) [
<span class="arg">{ optional arguments }</span> ] -&gt;
<em>array</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Creates an array of images from a BLOB, that is, a
<em>B</em>inary <em>L</em>arge <em>OB</em>ject. In RMagick, a
BLOB is a string.</p>
<h4>Arguments</h4>
<p>A blob can be a string containing an image file such as a
JPEG or GIF. The string can contain a multi-image file such as
an animated GIF or a Photoshop image with multiple layers. A
blob can also be one of the strings produced by <a href=
"image3.html#to_blob">to_blob</a>. Control the format of the
created image(s) by setting additional <a href=
"info.html">Image::Info</a> attributes in the optional block
argument.</p>
<h4>Returns</h4>
<p>An array of one or more images constructed from the
BLOB.</p>
<h4>Example</h4>
<p>See <a href=
"image3.html#to_blob"><code>to_blob</code></a>.</p>
<h4>Magick API</h4>
<p>BlobToImage</p>
</div>
<div class="sig">
<h3 id="new">new</h3>
<p>Image.new(<span class="arg">columns</span>, <span class=
"arg">rows</span> [, <span class="arg">fill</span>]) [
<span class="arg">{ optional arguments }</span> ] -&gt;
<em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>Creates a new instance with the specified
number of columns and rows. You can specify other arguments by
setting <a href="info.html">Image::Info</a> attributes in the
optional block. If the optional <span class="arg">fill</span>
argument is not specified, the image is set to the background
color.
<h4>Arguments</h4>
<dl>
<dt>columns</dt>
<dd>The number of columns</dd>
<dt>rows</dt>
<dd>The number of rows</dd>
<dt>fill</dt>
<dd>A <a href="struct.html#fill"><code>Fill</code></a>
object</dd>
</dl>
<h4>Returns</h4>
<p>A new image.</p>
<h4>Example</h4>
<pre>
img = Image.new(256, 64) {
self.background_color = 'red'
}
</pre>
<h4>See also</h4>
<p><a href=
"ilist.html#new_image"><code>ImageList.new_image</code></a></p>
<h4>Magick API</h4>
<p>AllocateImage</p>
</div>
<div class="sig">
<h3 id="ping">ping</h3>
<p>Image.ping(<span class="arg">filename</span>) [ <span class=
"arg">{ optional arguments }</span> ] -&gt;
<em>array</em><br />
Image.ping(<span class="arg">file</span>) [ <span class="arg">{
optional arguments }</span> ] -&gt; <em>array</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Creates one or more images from the image file, omitting the
pixel data. Only the attributes are stored in the images. This
method is faster than <code><a href="#read">read</a></code> and
uses less memory.</p>
<h4>Arguments</h4>
<p>An image file name or open file object. You can specify
other arguments by setting <a href="info.html">Image::Info</a>
attributes in the optional block.</p>
<h4>Returns</h4>
<p>An array containing 0 or more images.</p>
<h4>Example</h4>
<pre>
cheetah = Image.ping("Cheetah.jpg") &raquo;
[Cheetah.jpg JPEG 1024x768 DirectClass 8-bit 101684b]
p cheetah[0].rows &raquo; 768
p cheetah[0].columns &raquo; 1024
</pre>
<h4>See also</h4>
<p><a href="#read"><code>read</code></a></p>
<h4>Magick API</h4>
<p>PingImage</p>
</div>
<div class="sig">
<h3 id="read">read</h3>
<p>Image.read(<span class="arg">filename</span>) [ <span class=
"arg">{ optional arguments }</span> ] -&gt;
<em>array</em><br />
Image.read(<span class="arg">file</span>) [ <span class="arg">{
optional arguments }</span> ] -&gt; <em>array</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Reads all the images from the specified file.</p>
<p><span style="font-style:italic">Note:</span> Because an
image file can contain multiple images or multiple image
layers, <code>read</code> always returns an array containing 0
or more elements, one element for each image or image layer in
the file.</p>
<h4>Arguments</h4>
<p>An image file name or open file object. You can specify
other arguments by setting <a href="info.html">Image::Info</a>
attributes in the optional block.</p>
<h4>Returns</h4>
<p>An array containing 0 or more Image objects. If the file is
a multi-image file such as an animated GIF or a Photoshop PSD
file with multiple layers, the array contains an Image object
for each image or layer in the file.</p>
<h4>Example</h4>
<pre>
animated = Image.read("animated.gif") &raquo;
[animated.gif GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b
animated.gif[1] GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b,
animated.gif[2] GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b]
</pre>
<h4>See also</h4>
<p><a href="#ping"><code>ping</code></a></p>
<h4>Note</h4>
<p>The read method does not accept a StringIO object. If you
want to create an image from a string buffer, use <a href=
"image1.html#from_blob">from_blob</a>.</p>
<h4>Magick API</h4>
<p>ReadImage</p>
</div>
<div class="sig">
<h3 id="read_inline">read_inline</h3>
<p>Image.read_inline(<span class="arg">content</span>) [
<span class="arg">{ optional arguments }</span> ] -&gt;
<em>array</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Converts a Base64-encoded image or multi-image sequence to
an array of Image objects.</p>
<h4>Arguments</h4>
<p>A Base64-encoded string. Generally no optional arguments are
required. If the image format cannot be deduced from the image
data, you can use the <a href="info.html#format">format</a>
attribute. If you want to extract a subset of an image
sequence, see <a href="imusage.html#frames">here</a>.</p>
<h4>Returns</h4>
<p>An array containing 0 or more Image objects. If the content
is a multi-image sequence such as an animated GIF or a
Photoshop PSD file with multiple layers, the array contains an
Image object for each image or layer in the file.</p>
<h4>Example</h4>
<pre>
content = "R0lGODlhnAEuAferAAAAAAcIBggJBgw..."
img = Image.read_inline(content)
</pre>
<h4>See also</h4>
<p><a href="#read"><code>read</code></a></p>
</div>
<h2 class="methods">instance methods</h2>
<div class="sig">
<h3 id="aref">[&nbsp;]</h3>
<p><span class="arg">img</span>[<span class="arg">key</span>]
-&gt; <em>string</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Returns the value of the image property identified by
<span class="arg">key</span>. An image may have any number of
properties. Each property is identified by a string (or symbol)
key. The property value is a string. ImageMagick predefines
some properties, including <code>Label</code>,
<code>Comment</code>, <code>Signature</code>, and in some cases
<code>EXIF</code>.</p>
<h4>Arguments</h4>The key may be a <code>String</code> or a
<code>Symbol</code>.
<h4>Returns</h4>
<p>The value of the property.</p>
<h4>Example</h4>
<pre>
mom['Label'] = 'My Mother'
</pre>
<h4>See also</h4>
<p><a href="#aset"><code>[ ]=</code></a>, <a href=
"image3.html#properties"><code>properties</code></a></p>
<h4>Magick API</h4>
<p>GetImageAttribute</p>
<h4>Note</h4>
<p>ImageMagick calls properties "attributes." I use the word
"properties" to reduce the confusion with image object
attributes such as <code>rows</code> and
<code>columns</code>.</p>
</div>
<div class="sig">
<h3 id="aset">[&nbsp;]=</h3>
<p><span class="arg">img</span>[<span class="arg">key</span>] =
<span class="arg">string</span> -&gt; <em>self</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Sets the value of an image property. An image may have any
number of properties.</p>
<h4>Arguments</h4>The <span class="arg">key</span> may be a
string or a symbol. The value can be any string.
<h4>Returns</h4><code>self</code>
<h4>Example</h4>See <a href=
"javascript:popup('demo.rb.html')">demo.rb</a> for an example
of the use of the Label property.
<h4>See also</h4>
<p><a href="#aref">[<code>&nbsp;]</code></a>, <a href=
"image3.html#properties"><code>properties</code></a></p>
<h4>Magick API</h4>
<p>SetImageAttribute</p>
</div>
<div class="sig">
<h3 id="spaceship">&lt;=&gt;</h3>
<p><span class="arg">img</span> &lt;=&gt; <span class=
"arg">other_image</span> -&gt; -1, 0, 1</p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Compares two images and returns -1, 0, or 1 if <span class=
"arg">img</span> is less than, equal to, or greater than
<span class="arg">other_image</span> as determined by comparing
the signatures of the images. If one of the arguments is not an
image, this method raises a TypeError exception (in Ruby 1.6)
or returns <code>nil</code> (in Ruby 1.8)</p>
<p>In addition to &lt;=&gt;, <code>Image</code> mixes in the
<code>Comparable</code> module, which defines the &lt;, &lt;=,
== &gt;=, &gt;, and <code>between?</code> methods.</p>
<p>The <code>difference</code> method compares images (for
equality only) but also returns information about the amount
two images differ, which may be more useful.</p>
<h4>Returns</h4>
<p>The value of <span class=
"arg">img</span>.<code>signature</code> &lt;=&gt; <span class=
"arg">other_image</span>.<code>signature</code>.</p>
<h4>See also</h4>
<p><a href="image3.html#signature">signature</a>, <a href=
"#difference">difference</a>, <a href=
"#compare_channel">compare_channel</a></p>
<h4>Magick API</h4>
<p>SignatureImage</p>
</div>
<div class="sig">
<h3 id="adaptive_blur">adaptive_blur</h3>
<p><span class="arg">img</span>.adaptive_blur(<span class=
"arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0)
-&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p><span class="imquote">Adaptively blurs the image by blurring
more intensely near image edges and less intensely far from
edges.</span> The adaptive_blur method blurs <span class=
"imquote">the image with a Gaussian operator of the
given</span> <span class="arg">radius</span> <span class=
"imquote">and standard deviation</span> (<span class=
"arg">sigma</span>). <span class="imquote">For reasonable
results,</span> <span class="arg">radius</span> <span class=
"imquote">should be larger than</span> <span class=
"arg">sigma</span>. <span class="imquote">Use a</span>
<span class="arg">radius</span> <span class="imquote">of 0 and
adaptive_blur selects a suitable</span> <span class=
"arg">radius</span> <span class="imquote">for you.</span></p>
<h4>Arguments</h4>
<dl>
<dt>radius</dt>
<dd><span class="imquote">The radius of the Gaussian in
pixels, not counting the center pixel.</span> The default is
0.0.</dd>
<dt>sigma</dt>
<dd><span class="imquote">The standard deviation of the
Laplacian, in pixels.</span> The default is 1.0.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href=
"#adaptive_blur_channel">adaptive_blur_channel</a></p>
<h4>Magick API</h4>
<p>AdaptiveBlurImage</p>
</div>
<div class="sig">
<h3 id="adaptive_blur_channel">adaptive_blur_channel</h3>
<p><span class="arg">img</span>.adaptive_blur(<span class=
"arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0
[,<span class="arg">channel</span>...]) -&gt;
<em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>The same as <code>adaptive_blur</code> except only the
specified channels are blurred.</p>
<h4>Arguments</h4>
<dl>
<dt>radius</dt>
<dd><span class="imquote">The radius of the Gaussian in
pixels, not counting the center pixel.</span> The default is
0.0.</dd>
<dt>sigma</dt>
<dd><span class="imquote">The standard deviation of the
Laplacian, in pixels.</span> The default is 1.0.</dd>
<dt>channel...</dt>
<dd>0 or more <a href=
"constants.html#ChannelType">ChannelType</a> arguments. If no
channels are specified, blurs all the channels. Specifying no
channel arguments has the same effect as the
<code>adaptive_blur</code> method, above.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="#adaptive_blur">adaptive_blur</a></p>
<h4>Magick API</h4>
<p>AdaptiveBlurImageChannel</p>
</div>
<div class="sig">
<h3 id="adaptive_resize">adaptive_resize</h3>
<p><span class="arg">img</span>.adaptive_resize(<span class=
"arg">new_width</span>, <span class="arg">new_height</span>)
-&gt; <em>image</em><br />
<span class="arg">img</span>.adaptive_resize(<span class=
"arg">scale_factor</span>) -&gt; <span class=
"arg">image</span></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Resizes the image with data dependent triangulation.</p>
<h4>Arguments</h4>
<p>You can specify the new size in two ways. Either specify the
new width and height explicitly, or specify a <em>scale
factor</em>, a number that represents the percentage
change.</p>
<p>Use the <a href="#change_geometry">change_geometry</a>
method to compute new dimensions for an image with constraints
such as "maintain the current proportions."</p>
<dl>
<dt>new_width, new_height</dt>
<dd>The desired width and height.</dd>
<dt>scale_factor</dt>
<dd>You can use this argument instead of specifying the
desired width and height. The percentage size change. For
example, 1.25 makes the new image 125% of the size of the
receiver. The scale factor 0.5 makes the new image 50% of the
size of the receiver.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="image3.html#resize">resize</a></p>
<h4>Magick API</h4>
<p>AdaptiveResizeImage</p>
</div>
<div class="sig">
<h3 id="adaptive_sharpen">adaptive_sharpen</h3>
<p><span class="arg">img</span>.adaptive_sharpen(<span class=
"arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0)
-&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p><span class="imquote">Adaptively sharpens the image by
sharpening more intensely near image edges and less intensely
far from edges.</span> The adaptive_sharpen method sharpens
<span class="imquote">the image with a Gaussian operator of the
given</span> <span class="arg">radius</span> <span class=
"imquote">and standard deviation</span> (<span class=
"arg">sigma</span>). <span class="imquote">For reasonable
results,</span> <span class="arg">radius</span> <span class=
"imquote">should be larger than</span> <span class=
"arg">sigma</span>. <span class="imquote">Use a</span>
<span class="arg">radius</span> <span class="imquote">of 0 and
adaptive_sharpen selects a suitable</span> <span class=
"arg">radius</span> <span class="imquote">for you.</span></p>
<h4>Arguments</h4>
<dl>
<dt>radius</dt>
<dd><span class="imquote">The radius of the Gaussian in
pixels, not counting the center pixel.</span> The default is
0.0.</dd>
<dt>sigma</dt>
<dd><span class="imquote">The standard deviation of the
Laplacian, in pixels.</span> The default is 1.0.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href=
"#adaptive_sharpen_channel">adaptive_sharpen_channel</a></p>
<h4>Magick API</h4>
<p>AdaptiveSharpenImage</p>
</div>
<div class="sig">
<h3 id="adaptive_sharpen_channel">adaptive_sharpen_channel</h3>
<p><span class="arg">img</span>.adaptive_sharpen(<span class=
"arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0
[,<span class="arg">channel</span>...]) -&gt;
<em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>The same as <code>adaptive_sharpen</code> except only the
specified channels are sharpened.</p>
<h4>Arguments</h4>
<dl>
<dt>radius</dt>
<dd><span class="imquote">The radius of the Gaussian in
pixels, not counting the center pixel.</span> The default is
0.0.</dd>
<dt>sigma</dt>
<dd><span class="imquote">The standard deviation of the
Laplacian, in pixels.</span> The default is 1.0.</dd>
<dt>channel...</dt>
<dd>0 or more <a href=
"constants.html#ChannelType">ChannelType</a> arguments. If no
channels are specified, sharpens all the channels. Specifying
no channel arguments has the same effect as the
<code>adaptive_sharpen</code> method, above.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="#adaptive_sharpen">adaptive_sharpen</a></p>
<h4>Magick API</h4>
<p>AdaptiveSharpenImageChannel</p>
</div>
<div class="sig">
<h3 id="adaptive_threshold">adaptive_threshold</h3>
<p><span class="arg">img</span>.adaptive_threshold(<span class=
"arg">width</span>=3, <span class="arg">height</span>=3,
<span class="arg">offset</span>=0) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p class="imquote">Selects an individual threshold for each
pixel based on the range of intensity values in its local
neighborhood. This allows for thresholding of an image whose
global intensity histogram doesn't contain distinctive
peaks.</p>
<h4>Arguments</h4>
<dl>
<dt>width, height</dt>
<dd>define the width and height of the local
neighborhood</dd>
<dt>offset</dt>
<dd>constant to subtract from pixel neighborhood mean</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<p class="rollover"><a href=
"javascript:popup('adaptive_threshold.rb.html')"><img src=
"ex/adaptive_threshold.jpg" onmouseover=
"this.src='ex/images/Flower_Hat.jpg'" onmouseout=
"this.src='ex/adaptive_threshold.jpg'" alt=
"adaptive_threshold example" title=
"Click to see the example script" /></a> <img src=
"ex/images/spin.gif" alt="" class="spin" title=
"Mouse over the example to see the original image" /></p>
<h4>See also</h4>
<p><a href="#bilevel_channel">bilevel_channel</a>, <a href=
"image3.html#random_threshold_channel">random_threshold_channel</a>,
<a href="image3.html#threshold">threshold</a></p>
<h4>Magick API</h4>
<p>AdaptiveThresholdImage</p>
</div>
<div class="sig">
<h3 id="add_compose_mask">add_compose_mask</h3>
<p><span class="arg">img</span>.add_compose_mask(<span class=
"arg">mask</span>) -&gt; <em>self</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Associates a mask with an image that will be used as the
destination image in a <a href="#composite">composite</a>
operation. The areas of the destination image that are masked
by white pixels will be modified by the <a href=
"#composite">composite</a> method, while areas masked by black
pixels are unchanged.</p>
<p>See <a href=
"http://www.imagemagick.org/Usage/compose/#mask">Using a
Compose Mask to Limit the Composed Area</a> in Anthony
Thyssen's <a href="http://www.imagemagick.org/Usage/">Examples
of ImageMagick Usage</a>.</p>
<h4>Arguments</h4>
<p>The mask image must have the same dimensions as the
destination image.</p>
<h4>Returns</h4>
<p>self</p>
<h4>Example</h4>
<div>
<table summary="compose_mask example">
<tr>
<td><a href=
"javascript:add_popup('compose_mask.rb.html')"><img src=
"ex/images/Flower_Hat.jpg" width="100" height="125" alt=
"Source image for add_compose_mask example" title=
"Click to see the example script" /></a></td>
<td><a href=
"javascript:add_popup('compose_mask.rb.html')"><img src=
"ex/compose_mask_source.gif" width="100" height="125"
alt="Background image for add_compose_mask example"
title="Click to see the example script" /></a></td>
<td><a href=
"javascript:add_popup('compose_mask.rb.html')"><img src=
"ex/compose_mask.gif" width="100" height="125" alt=
"Mask image for compose_mask example" title=
"Click to see the example script" /></a></td>
<td><a href=
"javascript:add_popup('compose_mask.rb.html')"><img src=
"ex/compose_mask_example.jpg" width="93" height="125"
alt="Result image for compose_mask example" title=
"Click to see the example script" /></a></td>
</tr>
<tr>
<td align="center">Background</td>
<td align="center">Source</td>
<td align="center">Mask</td>
<td align="center">Result</td>
</tr>
</table>
</div>
<h4>See also</h4>
<p><a href="#composite">composite</a>, <a href=
"#delete_compose_mask">delete_compose_mask</a></p>
<h4>Notes</h4>
<p>This method uses a <em>copy</em> of the argument as the
mask. If you change the mask image you must call this method
again to update the mask.</p>
<h4>Magick API</h4>
<p>SetImageMask</p>
</div>
<div class="sig">
<h3 id="add_noise">add_noise</h3>
<p><span class="arg">img</span>.add_noise(<span class=
"arg">noise_type</span>) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Adds random noise to the image. The amount of time
<code>add_noise</code> requires depends on the NoiseType
argument.</p>
<h4>Arguments</h4>
<p>A <a href="constants.html#NoiseType">NoiseType</a>
value.</p>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<div class="noise_example_wrapper">
<a href="javascript:popup('add_noise.rb.html')"><img src=
"ex/images/Flower_Hat.jpg" alt="add_noise example" id=
"add_noise_example" title=
"Click to see the example script" /></a>
<p>Click the NoiseType to see the effect.</p>
<ul>
<li><a href="javascript:show_noise(null)">No noise</a></li>
<li><a href=
"javascript:show_noise('UniformNoise');">UniformNoise</a></li>
<li><a href=
"javascript:show_noise('GaussianNoise');">GaussianNoise</a></li>
<li><a href=
"javascript:show_noise('MultiplicativeGaussianNoise');">MultiplicativeGaussianNoise</a></li>
<li><a href=
"javascript:show_noise('ImpulseNoise');">ImpulseNoise</a></li>
<li><a href=
"javascript:show_noise('LaplacianNoise');">LaplacianNoise</a></li>
<li><a href=
"javascript:show_noise('PoissonNoise');">PoissonNoise</a></li>
</ul>
</div>
<div style="clear: both;"></div>
<h4>Notes</h4>
<p>The RandomNoise type was added in ImageMagick 6.3.5.</p>
<h4>Magick API</h4>
<p>AddNoiseImage</p>
<h4>See also</h4>
<p><a href="#add_noise_channel">add_noise_channel</a></p>
</div>
<div class="sig">
<h3 id="add_profile">add_profile</h3>
<p><span class="arg">img</span>.add_profile(<span class=
"arg">filename</span>) -&gt; <span class="arg">self</span></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Adds an ICC (a.k.a. ICM), IPTC, or generic profile. If the
file contains more than one profile all the profiles are
added.</p>
<h4>Arguments</h4>
<p>The filename of a file containing the profile.</p>
<h4>Returns</h4>
<p>self</p>
<h4>Example</h4>
<pre>
img.add_profile('my_cmyk.icm')
</pre>
<h4>See also</h4>
<p>The <a href="imageattrs.html#iptc_profile">iptc_profile</a>
and <a href="imageattrs.html#color_profile">color_profile</a>
attributes provide very similar functionality, except that
these attributes accept the profile data in the form of a
string. The <a href="image3.html#profile_bang">profile!</a>
method can also be used to add a profile. The type of profile
must be specified and the profile data must be in the form of a
string. Also see <a href="#delete_profile">delete_profile</a>
and <a href="image2.html#each_profile">each_profile</a>.</p>
<h4>Magick API</h4>
<p>ProfileImage</p>
</div>
<div class="sig">
<h3 id="add_noise_channel">add_noise_channel</h3>
<p><span class="arg">img</span>.add_noise_channel(<span class=
"arg">noise_type</span> [,<span class="arg">channel</span>...])
-&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Adds random noise to the specified channel or channels in
the image.</p>
<h4>Arguments</h4>
<dl>
<dt>noise_type</dt>
<dd>A <a href="constants.html#NoiseType">NoiseType</a>
value.</dd>
<dt>channel...</dt>
<dd>0 or more <a href=
"constants.html#ChannelType">ChannelType</a> arguments. If no
channels are specified, adds noise to all the channels.
Specifying no channel arguments has the same effect as the
<code>add_noise</code> method, above.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Magick API</h4>
<p>AddNoiseImageChannel</p>
<h4>See also</h4>
<p><a href="#add_noise">add_noise</a></p>
</div>
<div class="sig">
<h3 id="affine_transform">affine_transform</h3>
<p><span class="arg">img</span>.affine_transform(<span class=
"arg">matrix</span>) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Transforms the image as specified by the affine matrix.</p>
<p>See <a href=
"http://www.w3.org/TR/SVG/coords.html#EstablishingANewUserSpace">
<b>Coordinate system transformations</b></a> in the
<cite>Scalable Vector Graphics (SVG) 1.0 Specification</cite>
for more information about transformation matrices.</p>
<h4>Arguments</h4>
<p>An <a href=
"struct.html#AffineMatrix"><code>AffineMatrix</code></a>
object.</p>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<p>The affine matrix in this example skews the receiver by
&pi;/6 radians along both axes.</p>
<p class="rollover"><a href=
"javascript:popup('affine_transform.rb.html')"><img onmouseover="this.src='ex/images/Flower_Hat.jpg'"
onmouseout="this.src='ex/affine_transform.jpg'" src=
"ex/affine_transform.jpg" alt="affine_transform example" title=
"Click to see the example script" /></a> <img src=
"ex/images/spin.gif" alt="" class="spin" style="left: 235px;"
title="Mouse over the example to see the original image" /></p>
<h4>See also</h4>
<p><a href="image3.html#rotate">rotate</a>, <a href=
"#shear">shear</a></p>
<h4>Magick API</h4>
<p>AffineTransformImage</p>
</div>
<div class="sig">
<h3 id="alpha">alpha</h3>
<p><span class="arg">img</span>.alpha(<span class=
"arg">type</span>) -&gt; <em>type</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Set a flag to indicate whether or not to use alpha channel
data.</p>
<h4>Arguments</h4>
<p>One of the following values of the AlphaChannelType
enumeration:</p>
<dl>
<dt>ActivateAlphaChannel</dt>
<dd class="imquote">Enable the images use of transparency. If
transparency data did not exist, allocate the data and set to
opaque. If the image previously had transparency data, the
data is again enable as it was when turned off. The
transparency data is not changed or modified in any way.</dd>
<dt>BackgroundAlphaChannel</dt>
<dd>Set fully transparent pixels to the background color.
(Available in IM 6.5.2-5.)</dd>
<dt>CopyAlphaChannel</dt>
<dd class="imquote">Turns on the alpha/matte channel, then
copies the gray-scale intensity of the image, as an alpha
mask, into the alpha channel, converting a gray-scale mask
into a transparent shaped image ready to be colored
appropriately. The color channels are not modified.</dd>
<dt>DeactivateAlphaChannel</dt>
<dd class="imquote">Disables the image's transparency
channel. Does not delete or change the existing data, just
turns of the use of that data. This is the same as assigning
false to the old matte= attribute.</dd>
<dt>ExtractAlphaChannel</dt>
<dd>Creates a grayscale mask of the image's shape by copying
the alpha channel values into all the color channels, and
then turning off the image's transparency. The inverse of
CopyAlphaChannel</dd>
<dt>OpaqueAlphaChannel</dt>
<dd class="imquote">Turns on the alpha/matte channel and
forces it to be fully opaque.</dd>
<dt>ResetAlphaChannel</dt>
<dd>(Deprecated as of IM 6.4.3-7.) Set the alpha channel to
fully opaque.</dd>
<dt>SetAlphaChannel</dt>
<dd class="imquote">Turns on the alpha/matte channel and if
it was previously turned off resets the channel to opaque. If
the image already had the alpha channel turned on, it will
have no effect.</dd>
<dt>ShapeAlphaChannel</dt>
<dd class="imquote">As CopyAlphaChannel but also colors the
resulting shape mask with the current background color.</dd>
<dt>TransparentAlphaChannel</dt>
<dd class="imquote">Turns on the alpha/matte channel and
forces it to be fully transparent. This effectivally creates
a transparent image the same size as the original, with all
its meta-data still attached.</dd>
</dl>
<h4>Returns</h4>
<p>The argument.</p>
<h4>See also</h4>
<p><a href="#alpha_q">alpha?</a></p>
<h4>Notes</h4>
<p>Available in ImageMagick 6.3.5 and later.</p>
<h4>Magick API</h4>
<p>SetImageAlphaChannel</p>
</div>
<div class="sig">
<h3 id="alpha_q">alpha?</h3>
<p><span class="arg">img</span>.alpha? -&gt; <code>true</code>
or <code>false</code></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Returns <code>true</code> if the alpha channel will be used,
<code>false</code> otherwise.</p>
<h4>See also</h4>
<p><a href="#alpha">alpha</a></p>
<h4>Magick API</h4>
<p>GetImageAlphaChannel</p>
</div>
<div class="sig">
<h3 id="annotate">annotate</h3>
<p><span class="arg">img.</span>annotate(<span class=
"arg">draw, width, height, x, y, text</span>) <span class=
"arg">[&nbsp;{ additional parameters }&nbsp;]</span> -&gt;
<em>self</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>This is the same method as the <code>annotate</code> method
in the Draw class, except that the first argument is a Draw
object. Refer to the documentation for <a href=
"draw.html#annotate">Draw#annotate</a> for more information.
Some users feel like <code>annotate</code> is better placed in
Image than in Draw. Okay, here it is!</p>
<h4>Returns</h4>
<p>self</p>
</div>
<div class="sig">
<h3 id="auto_gamma_channel">auto_gamma_channel</h3>
<p><span class=
"arg">img</span>.auto_gamma_channel([<span class="arg">channel</span>...])
-&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>"Automagically" adjust the gamma level of an image.</p>
<h4>Arguments</h4>
<dl>
<dt>channel...</dt>
<dd>0 or more <a href=
"constants.html#ChannelType">ChannelType</a> arguments. If no
channels are specified, automagically adjusts the gamma level
of all the channels.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
</div>
<div class="sig">
<h3 id="auto_level_channel">auto_level_channel</h3>
<p><span class=
"arg">img</span>.auto_level_channel([<span class="arg">channel</span>...])
-&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>"Automagically" adjust the color levels of an image.</p>
<h4>Arguments</h4>
<dl>
<dt>channel...</dt>
<dd>0 or more <a href=
"constants.html#ChannelType">ChannelType</a> arguments. If no
channels are specified, automagically adjusts the color level
of all the channels.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
</div>
<div class="sig">
<h3 id="auto_orient">auto_orient</h3>
<p><span class="arg">img</span>.auto_orient -&gt;
<em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Rotates or flips the image based on the image's EXIF
orientation tag. Note that only some models of modern digital
cameras can tag an image with the orientation. If the image
does not have an orientation tag, or the image is already
properly oriented, then <code>auto_orient</code> returns an
exact copy of the image.</p>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="#auto_orient_bang">auto_orient!</a></p>
<h4>Magick API</h4>
<p>FlipImage, FlopImage, RotateImage, TransposeImage,
TransverseImage</p>
</div>
<div class="sig">
<h3 id="auto_orient_bang">auto_orient!</h3>
<p><span class="arg">img</span>.auto_orient! -&gt;
<em>self</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Rotates or flips the image based on the image's EXIF
orientation tag. Note that only some models of modern digital
cameras can tag an image with the orientation. If the image
does not have an orientation tag, or the image is already
properly oriented, then <code>auto_orient!</code> returns
<code>nil</code>.</p>
<h4>Returns</h4>
<p>self. or <code>nil</code> if the image is already properly
oriented</p>
<h4>See also</h4>
<p><a href="#auto_orient">auto_orient</a></p>
</div>
<div class="sig">
<h3 id="bilevel_channel">bilevel_channel</h3>
<p><span class="arg">img</span>.bilevel_channel(<span class=
"arg">threshold</span> [,<span class="arg">channel...</span>])
-&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p class="imquote">Changes the value of individual pixels based
on the intensity of each pixel channel. The result is a
high-contrast image.</p>
<h4>Arguments</h4>
<dl>
<dt>threshold</dt>
<dd>The threshold value, a number between 0 and
QuantumRange.</dd>
<dt>channel...</dt>
<dd>0 or more <a href=
"constants.html#ChannelType">ChannelType</a> arguments. If no
channels are specified, all the channels are
thresholded.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<p><code>bilevel_channel(2*QuantumRange/3,
RedChannel)</code></p>
<p class="rollover"><a href=
"javascript:popup('bilevel_channel.rb.html')"><img onmouseover=
"this.src='ex/images/Flower_Hat.jpg'" onmouseout=
"this.src='ex/bilevel_channel.jpg'" src=
"ex/bilevel_channel.jpg" alt="bilevel_channel example" title=
"Click to see the example script" /></a> <img src=
"ex/images/spin.gif" alt="" class="spin" title=
"Mouse over the example to see the original image" /></p>
<h4>See also</h4>
<p><a href="#adaptive_threshold">adaptive_threshold</a>,
<a href=
"image3.html#random_threshold_channel">random_threshold_channel</a></p>
<h4>Magick API</h4>
<p>BilevelImageChannel</p>
</div>
<div class="sig">
<h3 id="black_threshold">black_threshold</h3>
<p><span class="arg">img</span>.black_threshold(<span class=
"arg">red_channel</span> [, <span class=
"arg">green_channel</span> [, <span class=
"arg">blue_channel</span> [, <span class=
"arg">opacity_channel</span>]]]) -&gt; <em>image</em></p>
</div><!-- this example is larger than normal -->
<div class="desc">
<h4>Description</h4>
<p class="imquote">Forces all pixels below the threshold into
black while leaving all pixels above the threshold
unchanged.</p>
<h4>Arguments</h4>
<p>Each channel argument is a number between 0 and
QuantumRange. All arguments except the first may be omitted. If
the <span class="arg">green_channel</span> or <span class=
"arg">blue_channel</span> argument is omitted, the default
value is the <span class="arg">red_channel</span> value. If the
<span class="arg">opacity_channel</span> argument is omitted,
the default value is <a href=
"constants.html#Opacity">OpaqueOpacity</a>.</p>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="image3.html#white_threshold">white_threshold</a>,
<a href="#bilevel_channel">bilevel_channel</a></p>
<h4>Magick API</h4>
<p>BlackThresholdImage</p>
</div>
<div class="sig">
<h3 id="blend">blend</h3>
<p><span class="arg">img</span>.blend(<span class=
"arg">overlay</span>, <span class="arg">src_percentage</span>,
<span class="arg">dst_percentage</span>, <span class=
"arg">x_offset</span>=0, <span class="arg">y_offset</span>=0)
-&gt; <em>image</em><br />
<span class="arg">img</span>.blend(<span class=
"arg">overlay</span>, <span class="arg">src_percentage</span>,
<span class="arg">dst_percentage</span>, <span class=
"arg">gravity</span>, <span class="arg">x_offset</span>=0,
<span class="arg">y_offset</span>=0) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Adds the <span class="arg">overlay</span> image to the
target image according to <span class="arg">src_percent</span>
and <span class="arg">dst_percent</span>.</p>
<p>This method corresponds to the -blend option of
ImageMagick's <code>composite</code> command.</p>
<h4>Arguments</h4>
<dl>
<dt>overlay</dt>
<dd>The source image for the composite operation. Either an
imagelist or an image. If an imagelist, uses the current
image.</dd>
<dt>src_percentage</dt>
<dd>Either a non-negative number a string in the form "NN%".
If <span class="arg">src_percentage</span> is a number it is
interpreted as a percentage. Both 0.25 and "25%" mean 25%.
This argument is required.</dd>
<dt>dst_percentage</dt>
<dd>Either a non-negative number a string in the form "NN%".
If <span class="arg">src_percentage</span> is a number it is
interpreted as a percentage. Both 0.25 and "25%" mean 25%.
This argument may omitted if no other arguments follow it. In
this case the default is 100%-<span class=
"arg">src_percentage</span>.</dd>
</dl>
<p>The <code>blend</code> method can be called with or without
a <span class="arg">gravity</span> argument. The <span class=
"arg">gravity</span>, <span class="arg">x_offset</span>, and
<span class="arg">y_offset</span> arguments are described in
the documentation for <a href=
"image3.html#watermark">watermark</a>.</p>
<h4>Example</h4>
<p>See <a href=
"http://www.cit.gu.edu.au/~anthony/graphics/imagick6/compose/#blend">
"Blend Two Images Together"</a> in Anthony Thyssen's
<cite><a href=
"http://www.cit.gu.edu.au/~anthony/graphics/imagick6/">Examples
of ImageMagick Usage</a></cite>.</p>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="#dissolve">dissolve</a>, <a href=
"#composite">composite</a></p>
</div>
<div class="sig">
<h3 id="blue_shift">blue_shift</h3>
<p><span class="arg">img</span>.blue_shift(<span class=
"arg">factor</span>=1.5) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p class="imquote">Simulate a scene at nighttime in the
moonlight.</p>
<h4>Arguments</h4>
<dl>
<dt>factor</dt>
<dd>Larger values increase the effect. The default is
1.5.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Notes</h4>
<p>Available in ImageMagick 6.5.4-3 and later.</p>
<h4>Magick API</h4>
<p>BlueShiftImage</p>
</div>
<div class="sig">
<h3 id="blur_channel">blur_channel</h3>
<p><span class="arg">img</span>.blur_channel(<span class=
"arg">radius=0.0</span>, <span class=
"arg">sigma=1.0</span><span class="arg">[, channel...]]</span>)
-&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Blurs the specified channel. <span class="imquote">We
convolve the image with a Gaussian operator of the given radius
and standard deviation (sigma) . The <code>blur_channel</code>
method differs from <a href=
"image2.html#gaussian_blur_channel">gaussian_blur_channel</a>
in that it uses a separable kernel which is faster but
mathematically equivalent to the non-separable
kernel.</span></p>
<h4>Arguments</h4>
<p class="imquote">For reasonable results, the <span class=
"arg">radius</span> should be larger than <span class=
"arg">sigma</span>. Use a radius of 0 and
<code>blur_channel</code> selects a suitable radius for
you.</p>
<dl>
<dt>channel...</dt>
<dd>One or more <a href=
"constants.html#ChannelType">ChannelType</a> values. If none
are specified, the red, green, and blue channels are blurred.
This is the equivalent of <a href=
"#blur_image">blur_image</a>.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="#blur_image">blur_image</a>, <a href=
"image2.html#gaussian_blur_channel">gaussian_blur_channel</a>,
<a href="image2.html#motion_blur">motion_blur</a>, <a href=
"image3.html#radial_blur">radial_blur</a>, <a href=
"image3.html#selective_blur_channel">selective_blur_channel</a></p>
<h4>Magick API</h4>
<p>BlurImageChannel</p>
</div>
<div class="sig">
<h3 id="blur_image">blur_image</h3>
<p><span class="arg">img</span>.blur_image(<span class=
"arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0)
-&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Blurs the image. <span class="imquote">We convolve the image
with a Gaussian operator of the given radius and standard
deviation (sigma).</span></p>
<h4>Arguments</h4>
<p class="imquote">For reasonable results, the <span class=
"arg">radius</span> should be larger than <span class=
"arg">sigma</span>. Use a <span class="arg">radius</span> of 0
and <code>blur_image</code> selects a suitable <span class=
"arg">radius</span> for you.</p>
<h4>Returns</h4>
<p>A new image.</p>
<h4>Example</h4>
<p class="rollover"><a href=
"javascript:popup('blur_image.rb.html')"><img onmouseover=
"this.src='ex/images/Flower_Hat.jpg'" onmouseout=
"this.src='ex/blur_image.jpg'" src="ex/blur_image.jpg" alt=
"blur_image example" title=
"Click to see the example script" /></a> <img src=
"ex/images/spin.gif" alt="" class="spin" title=
"Mouse over the example to see the original image" /></p>
<h4>See also</h4>
<p><a href="#blur_channel">blur_channel</a>, <a href=
"image2.html#gaussian_blur">gaussian_blur</a>, <a href=
"image2.html#motion_blur">motion_blur</a>, <a href=
"image3.html#radial_blur">radial_blur</a>, <a href=
"image3.html#selective_blur_channel">selective_blur_channel</a></p>
<h4>Magick API</h4>
<p>BlurImage</p>
</div>
<div class="sig">
<h3 id="border">border</h3>
<p><span class="arg">img</span>.border(<span class=
"arg">width</span>, <span class="arg">height</span>,
<span class="arg">color</span>) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Add a border around the image.</p>
<h4>Arguments</h4>
<dl>
<dt>width</dt>
<dd>Border width in pixels</dd>
<dt>height</dt>
<dd>Border height in pixels</dd>
<dt>color</dt>
<dd>Border color. Use a <a href=
"imusage.html#color_names">named color</a> or a <a href=
"struct.html#Pixel">pixel</a> object.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<p class="rollover"><a href=
"javascript:popup('border.rb.html')"><img style=
"padding: 10px; display: none;" id="borderless" onmouseout=
"this.style.display='none'; bordered.style.display='';" src=
"ex/images/Flower_Hat.jpg" alt="border example" title=
"Click to see the example script" /> <img id="bordered"
onmouseover=
"this.style.display='none'; borderless.style.display='';" src=
"ex/border.jpg" alt="border example" /></a><img src=
"ex/images/spin.gif" alt="" class="spin" style="left: 224px;"
title="Mouse over the example to see the original image" /></p>
<h4>See also</h4>
<p><a href="#border_bang">border!</a>, <a href=
"image2.html#frame">frame</a></p>
<h4>Magick API</h4>
<p>BorderImage</p>
</div>
<div class="sig">
<h3 id="border_bang">border!</h3>
<p><span class="arg">img</span>.border!(<span class=
"arg">width</span>, <span class="arg">height</span>,
<span class="arg">color</span>) -&gt; <em>self</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>In-place form of <a href="#border">border</a></p>
<h4>Returns</h4>
<p>self</p>
</div>
<div class="sig">
<h3 id="bounding_box">bounding_box</h3>
<p><span class="arg">img</span>.bounding_box -&gt;
<em>rectangle</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>The image's <em>bounding box</em>. The bounding box is the
rectangle that encloses all the pixels not in the border color.
Uses the current <a href="imageattrs.html#fuzz">fuzz</a>
value.</p>
<h4>Returns</h4>A <a href="struct.html#Rectangle">Rectangle</a>
object.
<h4>Example</h4>
<p>In this example, the bounding box is the gray square
enclosing the blue circle. (The coordinates and red circles
were added after the bounding box was computed.)</p>
<p><a href="javascript:popup('bounding_box.rb.html')"><img src=
"ex/bounding_box.gif" alt="ex/bounding_box.rb" title=
"Click to see the example script" /></a></p>
</div>
<div class="sig">
<h3 id="change_geometry">change_geometry</h3>
<p><span class="arg">img</span>.change_geometry(<span class=
"arg">string</span>) {|cols,rows,image| <span class=
"arg">block</span>} -&gt; <em>??? (see Returns)</em><br />
<span class="arg">img.change_geometry</span>(<span class=
"arg">geometry</span>) {|cols,rows,image| <span class=
"arg">block</span>} -&gt; <em>??? (see Returns)</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>The <code>change_geometry</code> method supports resizing a
method by specifying constraints. For example, you can specify
that the image should be resized such that the aspect ratio
should be retained but the resulting image should be no larger
than 640 pixels wide and 480 pixels tall.</p>
<p>The argument may be either a <a href=
"imusage.html#geometry">geometry string</a> or a <a href=
"struct.html#Geometry">Geometry</a> object.
<code>Change_geometry</code> yields to the block, passing new
width and height values based on the argument with respect to
<code>self</code>. The return value is the return value of the
block.</p>
<h4>Arguments</h4>An <a href="imusage.html#geometry">geometry
string</a> or a <code>Geometry</code> object
<h4>Returns</h4>
<p>The value returned by the block</p>
<h4>Example</h4>
<pre>
mona = Image.read('MonaLisa.jpg').first
mona.change_geometry!('320x240') { |cols, rows, img|
img.resize!(cols, rows)
}
</pre>
<h4>Magick API</h4>
<p>ParseSizeString</p>
<h4>Note</h4>
<p><code>change_geometry!</code> is an alias for
<code>change_geometry</code>.</p>
</div>
<div class="sig">
<h3 id="changed_q">changed?</h3>
<p><span class="arg">img</span>.changed? -&gt;
<code>true</code> or <code>false</code></p>
</div>
<div class="desc">
<h4>Description</h4>Returns <code>true</code> if any pixel has
been altered since the image was constituted.
<h4>Magick API</h4>
<p>IsTaintImage</p>
</div>
<div class="sig">
<h3 id="channel">channel</h3>
<p><span class="arg">img</span>.channel(<span class=
"arg">channel</span>) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Extracts a channel from the image. <span class="imquote">A
channel is a particular color component of each pixel in the
[image].</span></p>
<h4>Arguments</h4>
<p>A <a href="constants.html#ChannelType">ChannelType</a>
value.</p>
<h4>Returns</h4>
<p>An image in which the RGB values of all the pixels have been
set to a gray corresponding to the specified channel value. For
example, given a pixel in the original image with the value
R=255, G=128, B=0 and the RedChannel argument, the equivalent
pixel in the result image will have the value R=255, G=255, and
B=255. For the BlueChannel argument, the pixel would have the
value R=0, G=0, B=0.</p>
<h4>Example</h4>
<p>The channel image preserves the tone of the selected RGB
component.</p>
<p><a href="javascript:popup('channel.rb.html')"><img src=
"ex/channel.jpg" alt="channel example" /></a></p>
<h4>Magick API</h4>
<p>ChannelImage</p>
</div>
<div class="sig">
<h3 id="channel_depth">channel_depth</h3>
<p><span class="arg">img</span>.channel_depth([<span class=
"arg">channel</span>...]) -&gt; <em>number</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Returns the maximum depth for the specified channel or
channels.</p>
<h4>Arguments</h4>
<dl>
<dt>channel...</dt>
<dd>Zero or more <a href=
"constants.html#ChannelType">ChannelType</a> values. If no
arguments are specified, the default is all channels.</dd>
</dl>
<h4>Returns</h4>
<p>The maximum depth</p>
<h4>See also</h4>
<p><a href=
"image3.html#set_channel_depth">set_channel_depth</a></p>
<h4>Magick API</h4>
<p>GetImageChannelDepth</p>
</div>
<div class="sig">
<h3 id="channel_extrema">channel_extrema</h3>
<p><span class="arg">img</span>.channel_extrema([<span class=
"arg">channel</span>...]) -&gt; <em>[number, number]</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Returns the minimum and maximum intensity values for the
specified channel or channels.</p>
<h4>Arguments</h4>
<dl>
<dt>channel...</dt>
<dd>Zero or more <a href=
"constants.html#ChannelType">ChannelType</a> values. If no
arguments are specified, the default is all channels.</dd>
</dl>
<h4>Returns</h4>
<p>An array. The first element in the array is the minimum
value. The second element is the maximum value.</p>
<h4>Magick API</h4>
<p>GetImageChannelExtrema</p>
</div>
<div class="sig">
<h3 id="channel_mean">channel_mean</h3>
<p><span class="arg">img</span>.channel_mean([<span class=
"arg">channel</span>...]) -&gt; <em>[number, number]</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Returns the mean and standard deviation values for the
specified channel or channels.</p>
<h4>Arguments</h4>
<dl>
<dt>channel...</dt>
<dd>Zero or more <a href=
"constants.html#ChannelType">ChannelType</a> values. If no
arguments are specified, the default is all channels.</dd>
</dl>
<h4>Returns</h4>
<p>An array. The first element in the array is the mean value.
The second element is the standard deviation.</p>
<h4>Magick API</h4>
<p>GetImageChannelMean</p>
</div>
<div class="sig">
<h3 id="charcoal">charcoal</h3>
<p><span class="arg">img</span>.charcoal(<span class=
"arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0)
-&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Adds a "charcoal" effect to the image. You can alter the
intensity of the effect by changing the <span class=
"arg">radius</span> and <span class="arg">sigma</span>
arguments.</p>
<h4>Arguments</h4>
<dl>
<dt>radius</dt>
<dd class="imquote">The radius of the pixel
neighborhood.</dd>
<dt>sigma</dt>
<dd class="imquote">The standard deviation of the Gaussian,
in pixels.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<p class="rollover"><a href=
"javascript:popup('charcoal.rb.html')"><img onmouseover=
"this.src='ex/images/Flower_Hat.jpg'" onmouseout=
"this.src='ex/charcoal.jpg'" src="ex/charcoal.jpg" alt=
"charcoal example" title=
"Click the image to see the example script" /></a> <img src=
"ex/images/spin.gif" alt="" class="spin" title=
"Mouse over the example to see the original image" /></p>
<h4>Magick API</h4>
<p>CharcoalImage</p>
</div>
<div class="sig">
<h3 id="check_destroyed">check_destroyed</h3>
<p><span class="arg">img</span>.check_destroyed -&gt;
<code>nil</code></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Raises DestroyedImageError if the image has been destroyed.
Returns nil otherwise.</p>
<h4>See also</h4>
<p><a href="#destroy_bang">destroy!</a>, <a href=
"#destroyed_q">destroyed?</a></p>
</div>
<div class="sig">
<h3 id="chop">chop</h3>
<p><span class="arg">img</span>.chop(<span class=
"arg">x</span>, <span class="arg">y</span>, <span class=
"arg">width</span>, <span class="arg">height</span>) -&gt;
<em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Removes the specified rectangle and collapses the rest of
the image to fill the removed portion.</p>
<h4>Arguments</h4>
<dl>
<dt>x</dt>
<dd>The x offset of the rectangle from the upper-left corner
of the image.</dd>
<dt>y</dt>
<dd>The y offset of the rectangle from the upper-left corner
of the image.</dd>
<dt>width</dt>
<dd>The width of the rectangle.</dd>
<dt>height</dt>
<dd>The height of the rectangle.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<p>The chop rectangle is highlighted in the "before" image. The
result may seem counter-intuitive!</p>
<p class="rollover"><a href=
"javascript:popup('chop.rb.html')"><img onmouseover=
"this.src='ex/chop_before.jpg'" onmouseout=
"this.src='ex/chop_after.jpg'" src="ex/chop_after.jpg" alt=
"chop example" title=
"Click the image to see the example script" /></a> <img src=
"ex/images/spin.gif" alt="" class="spin" title=
"Mouse over the example to see the original image" /></p>
<h4>See also</h4>
<p><a href="#crop">crop</a></p>
<h4>Magick API</h4>
<p>ChopImage</p>
</div>
<div class="sig">
<h3 id="clone">clone</h3>
<p><span class="arg">img</span>.clone -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Same as <a href="#dup">dup</a> except the frozen state of
the original is propagated to the new copy.</p>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="#dup">dup</a></p>
</div>
<div class="sig">
<h3 id="clut_channel">clut_channel</h3>
<p><span class="arg">img</span>.clut(<span class=
"arg">clut_image</span> [, <span class=
"arg">channel...</span>]) -&gt; <em>self</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Replace the channel values in the target image with a lookup
of its replacement value in an LUT gradient image.</p>
<p class="imquote">The LUT image should be either a single row
or column image of replacement colors. The lookup is controlled
by the -interpolate setting, especially for an LUT which is not
the full length needed by the IM installed Quality (Q) level.
Good settings for this is the default 'bilinear' or 'bicubic'
interpolation setting for a smooth color gradient, or 'integer'
for a direct unsmoothed lookup of color values.</p>
<p class="imquote">This method is especially suited to
replacing a grayscale image with specific color gradient from
the CLUT image.</p>
<p class="imquote">Note that color replacements involving
transparency (alpha/matte channel) will lookup the replacement
alpha/matte value using the alpha/matte value of the original
image. As such correct alpha channel lookup for a pure
gray-scale original image will require a copy of that grayscale
to be transferred into its alpha channel before applying the
-clut operator.</p>
<h4>Arguments</h4>
<dl>
<dt>clut_image</dt>
<dd>The LUT gradient image. Specify which interpolation
method to use by setting this image's <a href=
"imageattrs.html#pixel_interpolation_method">pixel_interpolation_method</a>
attribute to a <a href=
"constants.html#InterpolatePixelMethod">InterpolatePixelMethod</a>
value.</dd>
<dt>channel...</dt>
<dd>Limit which channels are modified by specifying one or
more <a href="constants.html#ChannelType">ChannelType</a>
values. Only these channels will be changed. If no channels
are specified, all channels will be changed.</dd>
</dl>
<h4>Returns</h4>
<p>self</p>
<h4>See also</h4>
<p>ImageMagick's -clut option.</p>
</div>
<div class="sig">
<h3 id="color_fill_to_border">color_fill_to_border</h3>
<p><span class=
"arg">img</span>.color_fill_to_border(<span class=
"arg">x</span>, <span class="arg">y</span>, <span class=
"arg">fill_color</span>) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Changes any pixel that is a neighbor of the target pixel and
is not the border color to the fill color.</p>
<h4>Arguments</h4>
<dl>
<dt>x, y</dt>
<dd>The target pixel's location.</dd>
<dt>fill_color</dt>
<dd>The fill color. The fill color can be either color name
or a <a href="struct.html#Pixel">Pixel</a> object.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<p>In this example, the aquamarine fill starts at the center of
the circle and fills to the black border. All non-black pixels
are replaced by the fill color. Contrast the result of
<code>color_fill_to_border</code> with that of
<code>color_floodfill</code> example, below.</p>
<p class="rollover"><a href=
"javascript:popup('color_fill_to_border.rb.html')"><img onmouseover="this.src='ex/color_fill_to_border_before.gif'"
onmouseout="this.src='ex/color_fill_to_border_after.gif'" src=
"ex/color_fill_to_border_after.gif" alt=
"color_fill_to_border example" title=
"Click the image to see the example script" /></a><img src=
"ex/images/spin.gif" alt="" class="spin" style=
"margin-bottom: 182px; margin-left: 4px;" title=
"Mouse over the example to see the original image" /></p>
<h4>See also</h4>
<p><a href="#color_floodfill">color_floodfill</a></p>
<h4>Magick API</h4>
<p>ColorFloodfillImage</p>
</div>
<div class="sig">
<h3 id="color_floodfill">color_floodfill</h3>
<p><span class="arg">img</span>.color_floodfill(<span class=
"arg">x</span>, <span class="arg">y</span>, <span class=
"arg">fill_color</span>) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Changes any pixel that is the same color and is a neighbor
of the target pixel to the fill color.</p>
<h4>Arguments</h4>
<dl>
<dt>x, y</dt>
<dd>The target pixel's location.</dd>
<dt>fill_color</dt>
<dd>The fill color, either color name or a <a href=
"struct.html#Pixel">Pixel</a> object.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<p>In this example, the aquamarine fill starts at the center of
the circle and replaces all neighboring white pixels. Contrast
the result of <code>color_floodfill</code> with that of
<code>color_fill_to_border</code>, above.</p>
<p class="rollover"><a href=
"javascript:popup('color_floodfill.rb.html')"><img onmouseover=
"this.src='ex/color_floodfill_before.gif'" onmouseout=
"this.src='ex/color_floodfill_after.gif'" src=
"ex/color_floodfill_after.gif" alt="color_floodfill example"
title="Click the image to see the example script" /></a>
<img src="ex/images/spin.gif" alt="" class="spin" style=
"margin-bottom: 182px;" title=
"Mouse over the example to see the original image" /></p>
<h4>See also</h4>
<p><a href="#color_fill_to_border">color_fill_to_border</a>,
<a href="image2.html#opaque">opaque</a></p>
<h4>Magick API</h4>
<p>ColorFloodfillImage</p>
</div>
<div class="sig">
<h3 id="color_histogram">color_histogram</h3>
<p><span class="arg">img</span>.color_histogram() -&gt;
<em>hash</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Computes the number of times each unique color appears in
the image.</p>
<h4>Returns</h4>
<p>A hash. Each key in the hash is a <a href=
"struct.html#Pixel">pixel</a> representing a color that appears
in the image. The value associated with the key is the number
of times that color appears in the image. <em>Caution:</em> if
the image contains many colors the hash will be very large. You
may want to use the <a href="image3.html#quantize">quantize</a>
method to reduce the number of colors before using
<code>color_histogram</code>.</p>
<h4>Example</h4>
<p>This histogram was produced by sorting the hash returned by
<code>color_histogram</code> by increasing frequency.</p>
<p><a href=
"javascript:popup('color_histogram.rb.html')"><img src=
"ex/color_histogram.gif" alt="color_histogram example" title=
"Click the image to see the example script" /></a></p>
<h4>Magick API</h4>
<p>GetImageHistogram</p>
</div>
<div class="sig">
<h3 id="colorize">colorize</h3>
<p><span class="arg">img</span>.colorize(<span class=
"arg">red_pct</span>, <span class="arg">green_pct</span>,
<span class="arg">blue_pct</span>, [<span class=
"arg">matte_pct</span>, ] <span class="arg">fill</span>) -&gt;
<em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Blend the fill color with the image pixels. The red_pct,
green_pct, blue_pct and matte_pct arguments are the percentage
to blend with the red, green, blue and matte channels.</p>
<h4>Arguments</h4>
<dl>
<dt>red_pct, green_pct, blue_pct, matte_pct</dt>
<dd>The percentage of the fill color red, green, blue and
matte (transparency) components to blend with the image
pixel. For example, <code>.25</code> is 25%. The matte_pct
argument is optional.</dd>
<dt>fill</dt>
<dd>A color name or a <a href=
"struct.html#Pixel">Pixel</a></dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<p>This example converts a color image to a "sepia-tone-ish"
image using the <a href="image3.html#quantize">quantize</a> and
<code>colorize</code> methods.</p>
<p class="rollover"><a href=
"javascript:popup('colorize.rb.html')"><img onmouseover=
"this.src='ex/images/Flower_Hat.jpg'" onmouseout=
"this.src='ex/colorize.jpg'" src="ex/colorize.jpg" alt=
"colorize example" title=
"Click the image to see the example script" /></a> <img src=
"ex/images/spin.gif" alt="" class="spin" title=
"Mouse over the example to see the original image" /></p>
<h4>See also</h4>
<p><a href="image3.html#sepiatone">sepiatone</a></p>
<h4>Magick API</h4>
<p>ColorizeImage</p>
</div>
<div class="sig">
<h3 id="colormap">colormap</h3>
<p><span class="arg">img</span>.colormap(<span class=
"arg">index</span>[, <span class="arg">new_color</span>]) -&gt;
<em>string</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Returns the color in the color map at the specified index.
If the <span class="arg">new_color</span> argument is
specified, replaces the color at that index with the new
color.</p>
<p>Raises IndexError if the image does not contain a color map.
Only <a href="constants.html#ClassType">PseudoClass</a> images
have a color map.</p>
<h4>Arguments</h4>
<dl>
<dt>index</dt>
<dd>A number between 0 and the number of colors in the color
map. If the value is out of range, <code>colormap</code>
raises an IndexError. You can get the number of colors in the
color map from the <a href=
"imageattrs.html#colors">colors</a> attribute.</dd>
<dt>new_color</dt>
<dd>Optional. If specified, may be either a <a href=
"imusage.html#color_names">color name</a> or a <a href=
"struct.html#Pixel">pixel</a>.</dd>
</dl>
<h4>Returns</h4>
<p>The name of the color at the specified location in the color
map</p>
</div>
<div class="sig">
<h3 id="color_point">color_point</h3>
<p><span class="arg">img</span>.color_point(<span class=
"arg">x</span>, <span class="arg">y</span>, <span class=
"arg">fill</span>) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>Set the color of the pixel at <span class=
"arg">x</span>,<span class="arg">y</span> to the fill color.
This method creates a new image object. If you want to set a
single pixel in the image without creating a new image, use
<a href="image3.html#pixel_color">pixel_color</a> or the
<a href="draw.html#point">Draw#point</a> method.
<h4>Arguments</h4>
<dl>
<dt>x, y</dt>
<dd>The location of the pixel.</dd>
<dt>fill</dt>
<dd>The fill color, either color name or a <a href=
"struct.html#Pixel">Pixel</a> object.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<pre>
f.color_point(50,50, 'red')
</pre>
<h4>See also</h4>
<p><a href="image3.html#pixel_color">pixel_color</a>, <a href=
"draw.html#point">Draw#point</a></p>
<h4>Magick API</h4>
<p>GetImagePixels, SyncImagePixels</p>
</div>
<div class="sig">
<h3 id="color_reset_bang">color_reset!</h3>
<p><span class="arg">img</span>.color_reset!(<span class=
"arg">fill</span>) -&gt; <em>self</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Sets all the pixels in the image to the specified fill
color.</p>
<h4>Arguments</h4>The fill color, either color name or a
<a href="struct.html#Pixel">Pixel</a> object.
<h4>Returns</h4>self
<h4>Example</h4>
<pre>
f.color_reset!(red)
</pre>
<h4>See also</h4>
<p><a href="image2.html#erase_bang">erase!</a></p>
<h4>Magick API</h4>SetImage
</div>
<div class="sig">
<h3 id="compare_channel">compare_channel</h3>
<p><span class="arg">img</span>.compare_channel(<span class=
"arg">img</span>, <span class="arg">metric</span> [,
<span class="arg">channel...</span>]) [ <span class=
"arg">{&nbsp;optional arguments&nbsp;}</span> ] -&gt;
[<em>image</em>, <em>float</em>]</p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Compares <span class="arg">img</span> with the receiver.</p>
<h4>Arguments</h4>
<dl>
<dt>image</dt>
<dd>Either an imagelist or an image. If an imagelist, uses
the current image.</dd>
<dt>metric</dt>
<dd>The desired distortion metric. A <a href=
"constants.html#MetricType">MetricType</a> value.</dd>
<dt>channel...</dt>
<dd>Zero or more <a href=
"constants.html##ChannelType">ChannelType</a> values. All the
specified channels contribute to the comparison and the
distortion value. If no channels are specified, compares all
channels.</dd>
<dt>optional arguments</dt>
<dd>
If present, <code>compare_channel</code> yields to a block
in which you can set optional arguments by setting
attributes on <em>self</em>. In both cases <span class=
"arg">color</span> may be either a <a href=
"imusage.html#color_names">color name</a> or a <a href=
"struct.html#Pixel">pixel</a>.
<dl>
<dt>self.highlight_color = color</dt>
<dd>Emphasize pixel differences with this color. The
default is partially transparent red.</dd>
<dt>self.lowlight_color = color</dt>
<dd>Demphasize pixel differences with this color. The
default is partially transparent white.</dd>
</dl>
</dd>
</dl>
<h4>Returns</h4>
<p>An array. The first element is a difference image, the
second is a the value of the computed distortion represented as
a <code>Float</code>.</p>
<h4>See also</h4>
<p><a href="#difference">difference</a>, <a href=
"#spaceship">&lt;=&gt;</a>, <a href=
"#distortion_channel">distortion_channel</a></p>
<h4>Magick API</h4>
<p>ImageCompareChannels</p>
<h4>Notes</h4>
<p>This method was named <code>channel_compare</code> in
earlier releases of RMagick. That name remains an alias for
<code>compare_channel</code>.</p>
</div>
<div class="sig">
<h3 id="composite">composite</h3>
<p><span class="arg">dest</span>.composite(<span class=
"arg">src</span>, <span class="arg">x</span>, <span class=
"arg">y</span>, <span class="arg">composite_op</span>) -&gt;
<em>image</em><br />
<span class="arg">dest</span>.composite(<span class=
"arg">src</span>, <span class="arg">gravity</span>,
<span class="arg">composite_op</span>) -&gt;
<em>image</em><br />
<span class="arg">dest</span>.composite(<span class=
"arg">src</span>, <span class="arg">gravity</span>,
<span class="arg">x</span>, <span class="arg">y</span>,
<span class="arg">composite_op</span>) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>Composites <span class="arg">src</span>
onto <span class="arg">dest</span> using the specified
composite operator.
<h4>Arguments</h4>
<p>The composite method can be called three different ways:</p>
<dl>
<dt style="font-style: normal;">1.&nbsp;Without a gravity
argument:</dt>
<dd>
<dl>
<dt>src</dt>
<dd>Either an imagelist or an image. If an imagelist,
uses the current image.</dd>
<dt>x, y</dt>
<dd>The x- and y-offset of the composited image, measured
from the upper-left corner of the image.</dd>
<dt>composite_op</dt>
<dd>A <a href=
"constants.html#CompositeOperator">CompositeOperator</a>
value.</dd>
</dl>
</dd>
<dt style="font-style: normal;">2.&nbsp;With a gravity
argument, without x and y arguments:</dt>
<dd>
<dl>
<dt>src</dt>
<dd>Either an imagelist or an image. If an imagelist,
uses the current image.</dd>
<dt>gravity</dt>
<dd>
A <a href="constants.html#GravityType">GravityType</a>
value that specifies the location of <em>img</em> on
<em>image</em>:
<dl>
<dt>NorthWestGravity</dt>
<dd>The composited image abuts the top and left sides
of the image.</dd>
<dt>NorthGravity</dt>
<dd>The composited image is centered left-to-right
and abuts the top of the image.</dd>
<dt>NorthEastGravity</dt>
<dd>The composited image abuts the top and right
sides of the image.</dd>
<dt>EastGravity</dt>
<dd>The composited image is centered top-to-bottom
and abuts the right side of the image.</dd>
<dt>SouthEastGravity</dt>
<dd>The composited image abuts the bottom and right
sides of the image.</dd>
<dt>SouthGravity</dt>
<dd>The composited image is centered left-to-right
and abuts the bottom of the image.</dd>
<dt>SouthWestGravity</dt>
<dd>The composited image abuts the bottom and left
sides of the image.</dd>
<dt>WestGravity</dt>
<dd>The composited image is centered top-to-bottom
and abuts the left side of the image.</dd>
<dt>CenterGravity</dt>
<dd>The composited image is centered left-to-right
and top-to-bottom.</dd>
</dl>
</dd>
<dt>composite_op</dt>
<dd>A <a href=
"constants.html#CompositeOperator">CompositeOperator</a>
value.</dd>
</dl>
</dd>
<dt style="font-style: normal;">3.&nbsp;With gravity, x, and
y arguments:</dt>
<dd>
<dl>
<dt>src</dt>
<dd>Either an imagelist or an image. If an imagelist,
uses the current image.</dd>
<dt>gravity</dt>
<dd>A <a href=
"constants.html#GravityType">GravityType</a> value.</dd>
<dt>x, y</dt>
<dd>The x- and y-offset of the composited image, measured
relative to the <em>gravity</em> argument.</dd>
<dt>composite_op</dt>
<dd>A <a href=
"constants.html#CompositeOperator">CompositeOperator</a>
value.</dd>
</dl>
</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>Example</h4>
<p>This example shows the effect of some of the composite
operators.</p>
<p><a href="javascript:popup('composite.rb.html')"><img src=
"ex/composite.gif" alt="composite example" title=
"Click the image to see the example script" /></a></p>
<h4>See also</h4>
<p><a href="#composite_bang">composite!</a>, <a href=
"#dissolve">dissolve</a>, <a href=
"image3.html#watermark">watermark</a></p>
<h4>Magick API</h4>
<p>CompositeImage</p>
</div>
<div class="sig">
<h3 id="composite_bang">composite!</h3>
<p><span class="arg">dest</span>.composite!(<span class=
"arg">src</span>, <span class="arg">x</span>, <span class=
"arg">y</span>, <span class="arg">composite_op</span>) -&gt;
<em>self</em><br />
<span class="arg">dest</span>.composite!(<span class=
"arg">src</span>, <span class="arg">gravity</span>,
<span class="arg">composite_op</span>) -&gt;
<em>self</em><br />
<span class="arg">dest</span>.composite!(<span class=
"arg">src</span>, <span class="arg">gravity</span>,
<span class="arg">x</span>, <span class="arg">y</span>,
<span class="arg">composite_op</span>) -&gt; <em>self</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>In-place form of <a href="#composite">composite</a>.</p>
<h4>Returns</h4>
<p>self</p>
</div>
<div class="sig">
<h3 id="composite_affine">composite_affine</h3>
<p><span class="arg">dest</span>.composite_affine(<span class=
"arg">src</span>, <span class="arg">affine</span>) -&gt;
<em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>Composite <span class="arg">src</span> over
<span class="arg">dest</span> as dictated by the <span class=
"arg">affine</span> argument.
<h4>Arguments</h4>
<dl>
<dt>img</dt>
<dd>An image or imagelist</dd>
<dt>affine</dt>
<dd>An <code>AffineMatrix</code></dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="#composite">composite</a>, <a href=
"#affine_transform">affine_transform</a></p>
<h4>Magick API</h4>
<p>DrawAffineImage</p>
</div>
<div class="sig">
<h3 id="composite_mathematics">composite_mathematics</h3>
<p><span class=
"arg">dest</span>.composite_mathematics(<span class=
"arg">src</span>, <span class="arg">a</span>, <span class=
"arg">b</span>, <span class="arg">c</span>, <span class=
"arg">d</span>, <span class="arg">gravity</span>) -&gt;
<em>image</em><br />
<span class=
"arg">dest</span>.composite_mathematics(<span class="arg">src</span>,
<span class="arg">a</span>, <span class="arg">b</span>,
<span class="arg">c</span>, <span class="arg">d</span>,
<span class="arg">x</span>, <span class="arg">y</span>) -&gt;
<em>image</em><br />
<span class=
"arg">dest</span>.composite_mathematics(<span class="arg">src</span>,
<span class="arg">a</span>, <span class="arg">b</span>,
<span class="arg">c</span>, <span class="arg">d</span>,
<span class="arg">gravity</span>, <span class="arg">x</span>,
<span class="arg">y</span>) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Merge the source and destination images according to the
formula
<em>a*Sc*Dc&nbsp;+&nbsp;b*Sc&nbsp;+&nbsp;c*Dc&nbsp;+&nbsp;d</em>
where Sc is the source pixel and Dc is the destination
pixel.</p>
<p>Equivalent to the <code>-compose Mathematics -set
option:compose:args a,b,c,d</code> options to ImagMagick's
<code>convert</code> command. See <a href=
"http://www.imagemagick.org/Usage/compose/#mathematics">Examples
of ImageMagick Usage</a>.</p>
<h4>Arguments</h4>
<dl>
<dt>src</dt>
<dd>Either an imagelist or an image. If an imagelist, uses
the current image.</dd>
<dt>a, b, c, d</dt>
<dd>See the description.</dd>
<dt>gravity</dt>
<dd>A <a href="constants.html#GravityType">GravityType</a>
value. If omitted, the default gravity is
NorthWestGravity.</dd>
<dt>x, y</dt>
<dd>The x- and y-offset of the composited image, measured
relative to the <em>gravity</em> argument. If omitted, the
default value is 0.0.</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="#composite">composite</a></p>
<h4>Magick API</h4>
<p>CompositeImage</p>
</div>
<div class="sig">
<h3 id="composite_tiled">composite_tiled</h3>
<p><span class="arg">img</span>.composite_tiled(<span class=
"arg">src</span>, <span class="arg">composite_op</span> =
Magick::OverCompositeOp) -&gt; <em>image</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>Composites multiple copies of the source image across and
down the image, producing the same results as ImageMagick's
composite command with the -tile option.</p>
<h4>Arguments</h4>
<dl>
<dt>src</dt>
<dd>The source image</dd>
<dt>composite_op</dt>
<dd>A <a href=
"constants.html#CompositeOperator">CompositeOperator</a>
value</dd>
</dl>
<h4>Returns</h4>
<p>A new image</p>
<h4>See also</h4>
<p><a href="#composite">composite</a>, <a href=
"#composite_tiled_bang">composite_tiled!</a></p>
<h4>Magick API</h4>
<p>CompositeImage</p>
</div>
<div class="sig">
<h3 id="composite_tiled_bang">composite_tiled!</h3>
<p><span class="arg">img</span>.composite_tiled!(<span class=
"arg">src</span>, <span class="arg">composite_op</span> =
Magick::OverCompositeOp) -&gt; <em>self</em></p>
</div>
<div class="desc">
<h4>Description</h4>
<p>In-place form of <a</