rmagick 1.13.0 → 1.14.0

data/doc/image3.html

@@ -93,6 +93,8 @@
 
           <li><a href="#reduce_noise">reduce_noise</a></li>
 
+          <li><a href="#resample">resample</a></li>
+
           <li><a href="#resize">resize</a></li>
 
           <li><a href="#resize_bang">resize!</a></li>
@@ -145,6 +147,8 @@
 
           <li><a href="#signature">signature</a></li>
 
+          <li><a href="#sketch">sketch</a></li>
+
           <li><a href="#solarize">solarize</a></li>
 
           <li><a href="#splice">splice</a></li>
@@ -197,6 +201,8 @@
 
           <li><a href="#trim_bang">trim!</a></li>
 
+          <li><a href="#unique_colors">unique_colors</a></li>
+
           <li><a href="#unsharp_mask">unsharp_mask</a></li>
 
           <li><a href=
@@ -206,6 +212,8 @@
 
           <li><a href="#vignette">vignette</a></li>
 
+          <li><a href="#watermark">watermark</a></li>
+
           <li><a href="#wave">wave</a></li>
 
           <li><a href="#white_threshold">white_threshold</a></li>
@@ -360,48 +368,26 @@
 
     <p>self</p>
 
+    <h4>See also</h4>
+
+    <p><a href="image1.html#add_profile">add_profile</a> and
+    <a href="image1.html#delete_profile">delete_profile</a> perform
+    very similar functions. However, <code>add_profile</code>
+    accepts the name of a profile file on disk instead of the
+    profile data itself and, if the file contains more than one
+    profile, will load all the profiles at once.</p>
+
     <h4>Magick API</h4>
 
     <p>ProfileImage</p>
 
     <h4>Notes</h4>
 
-    <ol>
-      <li>To extract a profile from an image, simply convert the
-      image, specifying the profile name (APP1, 8BIM, ICM, IPTC,
-      etc.) as the format of the output image. There are at least
-      two ways to do this.
-
-        <ol style="list-style-type: lower-alpha">
-          <li>Write the image to a file using the profile name as
-          the filename extension ("myimage.app1", for example).
-            <pre>
-img.write("myimage.app1")
-</pre>
-          </li>
-
-          <li>To capture the profile information in a string,
-          assign the profile name to the <a href=
-          "imageattrs.html#format">format=</a> attribute and call
-          <a href="image3.html#to_blob">to_blob.</a>
-            <pre>
-img.format = 'iptc'
-profile_str = img.to_blob
-</pre><a href=
-"http://www.imagemagick.org/script/formats.php#embedded">
-            This page (ImageMagick)</a> and <a href=
-            "http://www.graphicsmagick.org/www/formats.html">this
-            page (GraphicsMagick)</a> list the supported profiles.
-          </li>
-        </ol>
-      </li>
-
-      <li>&times;Magick does not automatically remove profiles when
-      resizing images. If you are trying to make your JPEG
-      thumbnail images as small as possible, use
-      <code>profile!</code> to remove any profiles from the image
-      as well. Also see <a href="#strip_bang">strip!</a></li>
-    </ol>
+    <p>&times;Magick does not automatically remove profiles when
+    resizing images. If you are trying to make your JPEG thumbnail
+    images as small as possible, use <code>profile!</code> to
+    remove any profiles from the image as well. Also see <a href=
+    "#strip_bang">strip!</a></p>
   </div>
 
   <div class="sig">
@@ -562,6 +548,10 @@ profile_str = img.to_blob
 
           <li><code>LShiftQuantumOperator</code></li>
 
+          <li><code>MaxQuantumOperator<sup>*</sup></code></li>
+
+          <li><code>MinQuantumOperator<sup>*</sup></code></li>
+
           <li><code>MultiplyQuantumOperator</code></li>
 
           <li><code>OrQuantumOperator</code></li>
@@ -571,7 +561,7 @@ profile_str = img.to_blob
           <li><code>SubtractQuantumOperator</code></li>
 
           <li><code>XorQuantumOperator</code></li>
-        </ul>
+        </ul><sup>*</sup> Available in ImageMagick 6.2.0 and later.
       </dd>
 
       <dt>rvalue</dt>
@@ -866,11 +856,57 @@ random_threshold_channel(geom, RedChannel)
     <p>ReduceNoiseImage</p>
   </div>
 
+  <div class="sig">
+    <h3 id="resample">resample</h3>
+
+    <p><span class="arg">image</span>.resample(<span class=
+    "arg">horizontal_res</span>=72.0[, <span class=
+    "arg">vertical_res</span>]) -&gt; <em>anImage</em></p>
+  </div>
+
+  <div class="desc">
+    <h4>Description</h4>
+
+    <p class="imquote">Resample image to specified horizontal and
+    vertical resolution.</p>
+
+    <p><span class="imquote">Resize the image so that its rendered
+    size remains the same as the original at the specified target
+    resolution. For example, if a 300 DPI image renders at 3 inches
+    by 2 inches on a 300 DPI device, when the image has been
+    resampled to 72 DPI, it will render at 3 inches by 2 inches on
+    a 72 DPI device. Note that only a small number of image formats
+    (e.g. JPEG, PNG, and TIFF) are capable of storing the image
+    resolution. For formats which do not support an image
+    resolution, the original resolution of the image must be
+    specified via</span> the <a href=
+    "imageattrs.html#density">density</a> attribute <span class=
+    "imquote">prior to specifying the resample
+    resolution.</span></p>
+
+    <h4>Arguments</h4>
+
+    <dl>
+      <dt>horizontal_res</dt>
+
+      <dd>the target horizontal resolution. The default is
+      72.0.</dd>
+
+      <dt>vertical_res</dt>
+
+      <dd>the target vertical resolution. The default is
+      <span class="arg">horizontal_res</span>.</dd>
+    </dl>
+  </div>
+
   <div class="sig">
     <h3 id="resize">resize</h3>
 
     <p><span class="arg">image</span>.resize(<span class=
     "arg">new_width</span>, <span class="arg">new_height</span>,
+    <em>filter</em>=<a href=
+    "constants.html#FilterType">LanczosFilter</a>,
+    <em>support</em>=1.0) -&gt; <em>image</em><br />
     <span class="arg">image</span>.resize(<span class=
     "arg">scale_factor</span>) -&gt; <em>anImage</em></p>
   </div>
@@ -909,13 +945,12 @@ random_threshold_channel(geom, RedChannel)
       IIR (infinite impulse response). Bessel and Sinc are windowed
       (brought down to zero) with the Blackman filter.</span></dd>
 
-      <dt>blur</dt>
+      <dt>support</dt>
 
-      <dd>The blur factor. Values &gt; 1 increase the blurriness.
-      Values &lt; 1 increase the sharpness. If this argument is not
-      specified, <code>resize</code> uses the value of the
-      receiver's <a href="imageattrs.html#Image.blur">blur</a>
-      attribute.</dd>
+      <dd>Values &gt; 1 increase the blurriness. Values &lt; 1
+      increase the sharpness. If this argument is not specified,
+      <code>resize</code> uses the value of the receiver's <a href=
+      "imageattrs.html#Image.blur">blur</a> attribute.</dd>
 
       <dt>scale_factor</dt>
 
@@ -950,7 +985,7 @@ random_threshold_channel(geom, RedChannel)
     <p><em>image</em>.resize!(<em>new_width</em>,
     <em>new_height</em>, <em>filter</em>=<a href=
     "constants.html#FilterType">LanczosFilter</a>,
-    <em>blur</em>=1.0) -&gt; <em>image</em><br />
+    <em>support</em>=1.0) -&gt; <em>image</em><br />
     <span class="arg">image</span>.resize!(<span class=
     "arg">scale_factor</span>) -&gt; <em>image</em></p>
   </div>
@@ -1069,7 +1104,8 @@ random_threshold_channel(geom, RedChannel)
     <h3 id="rotate">rotate</h3>
 
     <p><span class="arg">image</span>.rotate(<span class=
-    "arg">amount</span>) -&gt; <em>anImage</em></p>
+    "arg">amount</span> [, <span class="arg">qualifier</span>])
+    -&gt; <em>anImage</em></p>
   </div>
 
   <div class="desc">
@@ -1080,16 +1116,31 @@ random_threshold_channel(geom, RedChannel)
     counter-clockwise. <span class="imquote">Rotated images are
     usually larger than the originals and have "empty" triangular
     corners. Empty triangles left over from shearing the image are
-    filled with the color defined by the pixel at location
-    (0,0).</span></p>
+    filled with the <a href=
+    "imageattrs.html#background_color">background
+    color</a>.</span></p>
 
     <h4>Arguments</h4>
 
-    <p>The number of degrees to rotate the image.</p>
+    <dl>
+      <dt>amount</dt>
+
+      <dd>The number of degrees to rotate the image.</dd>
+
+      <dt>qualifier</dt>
+
+      <dd>If present, either "&gt;" or "&lt;". If "&gt;", rotates
+      the image only if the image's width exceeds its height. If
+      "&lt;" rotates the image only if its height exceeds its
+      width. If this argument is omitted the image is always
+      rotated.</dd>
+    </dl>
 
     <h4>Returns</h4>
 
-    <p>A new image</p>
+    <p>A new image, or <code>nil</code> if the image was not
+    rotated because it did not meet the qualification specified by
+    the second argument.</p>
 
     <h4>Example</h4>
 
@@ -1125,7 +1176,8 @@ random_threshold_channel(geom, RedChannel)
     <h3 id="rotate_bang">rotate!</h3>
 
     <p><span class="arg">image</span>.rotate!(<span class=
-    "arg">amount</span>) -&gt; <em>image</em></p>
+    "arg">amount</span> [, <span class="arg">qualifier</span>])
+    -&gt; <em>image</em></p>
   </div>
 
   <div class="desc">
@@ -1135,7 +1187,9 @@ random_threshold_channel(geom, RedChannel)
 
     <h4>Returns</h4>
 
-    <p>self</p>
+    <p>self, or <code>nil</code> if the image was not rotated
+    because it did not meet the qualification specified by the
+    second argument.</p>
   </div>
 
   <div class="sig">
@@ -1468,7 +1522,9 @@ random_threshold_channel(geom, RedChannel)
 
       <dt>azimuth, elevation</dt>
 
-      <dd>The light source direction.</dd>
+      <dd>The light source direction. The azimuth is measured in
+      degrees. 0&deg; is at 9 o'clock. Increasing values move the
+      light source counter-clockwise.</dd>
     </dl>
 
     <h4>Returns</h4>
@@ -1554,7 +1610,7 @@ random_threshold_channel(geom, RedChannel)
     id="shadowed" onmouseover=
     "this.style.display='none';shadowless.style.display='';" src=
     "ex/shadow_after.gif" alt="shadow example"
-    /></a> <img src="ex/images/spin.gif" alt="" style=
+     /></a> <img src="ex/images/spin.gif" alt="" style=
     "margin-bottom: 120px" title=
     "Mouse over the example to see the original image" /></p>
 
@@ -1772,7 +1828,7 @@ random_threshold_channel(geom, RedChannel)
      <img id="sheared" onmouseover=
     "this.style.display='none'; noshear.style.display='';" src=
     "ex/shear.jpg" alt="shear example"
-    /></a><img src="ex/images/spin.gif" alt="" class=
+     /></a><img src="ex/images/spin.gif" alt="" class=
     "spin" style="left: 253px; top: 34px" title=
     "Mouse over the example to see the original image" /></p>
 
@@ -1894,6 +1950,51 @@ img.properties &raquo;
     <p>SignatureImage</p>
   </div>
 
+  <div class="sig">
+    <h3 id="sketch">sketch</h3>
+
+    <p><span class="arg">image</span>.sketch(<span class=
+    "arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0,
+    <span class="arg">angle</span>=0.0) -&gt; <em>anImage</em></p>
+  </div>
+
+  <div class="desc">
+    <h4>Description</h4>
+
+    <p>Simulates a pencil sketch. For best results start with a
+    grayscale image.</p>
+
+    <h4>Arguments</h4>
+
+    <dl>
+      <dt>radius, sigma</dt>
+
+      <dd>The radius and sigma of the Gaussian operator</dd>
+
+      <dt>angle</dt>
+
+      <dd>The angle toward which the image is sketched.</dd>
+    </dl>
+
+    <h4>Returns</h4>
+
+    <p>A new image</p>
+
+    <h4>Example</h4>
+
+    <p class="rollover"><a href=
+    "javascript:popup('sketch.rb.html')"><img src="ex/sketch.jpg"
+    title="Click to see the example script" alt="sketch example"
+    onmouseover="this.src='ex/images/Flower_Hat.jpg'" onmouseout=
+    "this.src='ex/sketch.jpg'" /></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>SketchImage (available in ImageMagick 6.2.8)</p>
+  </div>
+
   <div class="sig">
     <h3 id="solarize">solarize</h3>
 
@@ -2168,6 +2269,10 @@ p stats.red.stddev &raquo; 0.231399683489667
     <h4>Magick API</h4>
 
     <p>SteganoImage</p>
+
+    <h4>See also</h4>
+
+    <p><a href="#watermark">watermark</a></p>
   </div>
 
   <div class="sig">
@@ -2899,6 +3004,29 @@ img.to_color(pixel)
     <p>self</p>
   </div>
 
+  <div class="sig">
+    <h3 id="unique_colors">unique_colors</h3>
+
+    <p><span class="arg">image</span>.unique_colors -&gt;
+    <em>anImage</em></p>
+  </div>
+
+  <div class="desc">
+    <h4>Description</h4>
+
+    <p>Constructs a new image with one pixel for each unique color
+    in the image. The new image has 1 row. The row has 1 column for
+    each unique pixel in the image.</p>
+
+    <h4>Returns</h4>
+
+    <p>A new image</p>
+
+    <h4>Magick API</h4>
+
+    <p>UniqueImageColors (available in ImageMagick 6.2.9)</p>
+  </div>
+
   <div class="sig">
     <h3 id="unsharp_mask">unsharp_mask</h3>
 
@@ -3231,6 +3359,163 @@ end
     size, shape, and background color of the vignette.</p>
   </div>
 
+  <div class="sig">
+    <h3 id="watermark">watermark</h3>
+
+    <p><span class="arg">image</span>.watermark(<span class=
+    "arg">mark</span>, <span class="arg">lightness</span>=1.0,
+    <span class="arg">saturation</span>=1.0, <span class=
+    "arg">x_offset</span>=0, <span class="arg">y_offset</span>=0)
+    -&gt; <em>anImage</em><br />
+    <span class="arg">image</span>.watermark(<span class=
+    "arg">mark</span>, <span class="arg">lightness</span>=1.0,
+    <span class="arg">saturation</span>=1.0, <span class=
+    "arg">gravity</span>, <span class="arg">x_offset</span>=0,
+    <span class="arg">y_offset</span>=0) -&gt; <em>anImage</em></p>
+  </div>
+
+  <div class="desc">
+    <h4>Description</h4>
+
+    <p>Composites a watermark image on the target image using the
+    <a href="constants.html#CompositeOperator">Modulate</a>
+    composite operator. This composite operation operates in the
+    HSL colorspace and combines part of the lightness, part of the
+    saturation, and all of the hue of each pixel in the watermark
+    with the corresponding pixel in the target image</p>
+
+    <h4>Arguments</h4>
+
+    <dl>
+      <dt>mark</dt>
+
+      <dd>The watermark image. Either an imagelist or an image. If
+      an imagelist, uses the current image.</dd>
+
+      <dt>lightness</dt>
+
+      <dd>The fraction of the lightness component of the watermark
+      pixels to be composited onto the target image. Must be a
+      non-negative number or a string in the form "NN%". If
+      lightness is a number it is interpreted as a percentage. Both
+      0.25 and "25%" mean 25%. The default is 100%.</dd>
+
+      <dt>saturation</dt>
+
+      <dd>The fraction of the saturation component of the watermark
+      pixels to be composited onto the target image. Must be a
+      non-negative number or a string in the form "NN%". If
+      lightness is a number it is interpreted as a percentage. Both
+      0.25 and "25%" mean 25%. The default is 100%.</dd>
+
+      <dt>x_offset</dt>
+
+      <dd>The offset of the watermark, measured from the left-hand
+      side of the target image. The default is 0.</dd>
+
+      <dt>y_offset</dt>
+
+      <dd>The offset of the watermark, measured from the top of the
+      target image. The default is 0.</dd>
+    </dl>
+
+    <p>Watermark can be called with a <span class=
+    "arg">gravity</span> argument or without. When a <span class=
+    "arg">gravity</span> argument is specified but the <span class=
+    "arg">x-</span> and <span class="arg">y-offsets</span> are
+    omitted, the watermark is positioned based on the value of the
+    <span class="arg">gravity</span> argument:</p>
+
+    <dl>
+      <dt>NorthWestGravity</dt>
+
+      <dd>The watermark abuts the top and left sides of the
+      image.</dd>
+
+      <dt>NorthGravity</dt>
+
+      <dd>The watermark is centered left-to-right and abuts the top
+      of the image.</dd>
+
+      <dt>NorthEastGravity</dt>
+
+      <dd>The watermark abuts the top and right sides of the
+      image.</dd>
+
+      <dt>EastGravity</dt>
+
+      <dd>The watermark is centered top-to-bottom and abuts the
+      right side of the image.</dd>
+
+      <dt>SouthEastGravity</dt>
+
+      <dd>The watermark abuts the bottom and right sides of the
+      image.</dd>
+
+      <dt>SouthGravity</dt>
+
+      <dd>The watermark is centered left-to-right and abuts the
+      bottom of the image.</dd>
+
+      <dt>SouthWestGravity</dt>
+
+      <dd>The watermark abuts the bottom and left sides of the
+      image.</dd>
+
+      <dt>WestGravity</dt>
+
+      <dd>The watermark is centered top-to-bottom and abuts the
+      left side of the image.</dd>
+
+      <dt>CenterGravity</dt>
+
+      <dd>The watermark is centered left-to-right and
+      top-to-bottom.</dd>
+    </dl>
+
+    <p>When the <span class="arg">gravity</span> argument is
+    present and the <span class="arg">x-offset</span> (and
+    optionally the <span class="arg">y-offset</span>) is present,
+    the <span class="arg">x-</span> and <span class=
+    "arg">y-offset</span> are measured from the right and/or bottom
+    edges of the target image based on the value of <span class=
+    "arg">gravity</span>. If the argument is NorthEastGravity,
+    EastGravity, or SouthEastGravity, the <span class=
+    "arg">x-offset</span> is measured from the right side of the
+    image. If the argument is SouthEastGravity, SouthGravity, or
+    SouthWestGravity, the <span class="arg">y-offset</span> is
+    measured from the bottom of the image. All other values are
+    ignored and the <span class="arg">x-</span> and <span class=
+    "arg">y-offset</span> are measured from the upper-left corner
+    of the image.</p>
+
+    <h4>Returns</h4>
+
+    <p>A new image</p>
+
+    <h4>Example</h4>
+
+    <p>See <a href=
+    "http://www.cit.gu.edu.au/~anthony/graphics/imagick6/annotating/#wmark_image">
+    "Watermarking with Images"</a> in Anthony Thyssen's <a href=
+    "http://www.cit.gu.edu.au/~anthony/graphics/imagick6/"><cite>Examples
+    of ImageMagick Usage</cite></a>.</p>
+
+    <p class="rollover"><a href=
+    "javascript:popup('watermark.rb.html')"><img src=
+    "ex/watermark.jpg" alt="watermark example" title=
+    "Click to see the example script" onmouseover=
+    "this.src='ex/images/Flower_Hat.jpg'" onmouseout=
+    "this.src='ex/watermark.jpg'" /></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="image1.html#composite">composite</a>, <a href=
+    "#stegano">stegano</a></p>
+  </div>
+
   <div class="sig">
     <h3 id="wave">wave</h3>