Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

275 lines (273 sloc) 12.968 kb
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1st September 2002), see">
<title>RMagick User's Guide and Reference</title>
<meta http-equiv="Content-Type" content=
"text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Quanta Plus">
<link type="text/css" rel="stylesheet" href="rubymgen.css">
<div align="center">
<img src="ex/images/rmagick.jpg" alt="RMagick">
<div align="center"><h2>User's Guide and Reference</h2></div>
<h3>Table of Contents</h3>
<li><a href="#Introduction">Introduction</a></li>
<span style="font-style: italic">Usage Guide</span>
<li><a href="usage.html">How To Use RMagick</a></li>
<li><a href="imusage.html">ImageMagick/GraphicsMagick
<li><a href="comtasks.html">Common Tasks</a></li>
<span style="font-style: italic">Reference</span>
<span style="font-style: italic">Modules</span>
<li><a href="magick.html">Magick</a></li>
<span style="font-style: italic">Classes</span>
<li><a href="ilist.html">ImageList</a></li>
<li><a href="imageattrs.html">Image (attribute
<li><a href="image.html">Image (class and instance
<li><a href="draw.html">Draw</a></li>
<span style="font-style: italic">Miscellaneous
<li><a href="struct.html">Struct classes</a></li>
<li><a href="fill.html">Fill classes</a></li>
<li><a href="info.html">Image::Info - Optional method
<li><a href="constants.html">Constants</a></li>
<h2><a name="Introduction">Introduction</a></h2>
<h3>What is RMagick?</h3>
RMagick is a binding from Ruby
to the ImageMagick <span style=
"font-size: x-small; vertical-align: super">TM</span> and
GraphicsMagick image manipulation libraries. Here's how the <a
home page</a> describes ImageMagick:
<div class="imquote">
ImageMagick<span style=
"font-size: x-small; vertical-align: super">TM</span> is a
robust collection of tools and read, write,
and manipulate an image in many image formats (over 87
major formats) including popular formats like TIFF, JPEG,
PNG, PDF, PhotoCD, and GIF. With ImageMagick you can create
images dynamically, making it suitable for Web
applications. You can also resize, rotate, sharpen, color
reduce, or add special effects to an image and save your
completed work in the same or differing image format.
<p>GraphicsMagick is a branch from ImageMagick 5.5.2 and
provides a nearly identical API. The <a href=
"">GraphicsMagick web site</a>
says this about GraphicsMagick:</p>
<div class="imquote">
<i>GraphicsMagick</i> 1.0.1 is a robust collection of tools
and libraries which support reading, writing, and
manipulating an image in over 88 major formats including
popular formats like TIFF, JPEG, JPEG-2000, PNG, PDF,
PhotoCD, SVG, and GIF. <i>GraphicsMagick</i> supports
creating new images on the fly, making it suitable for
building dynamic Web applications. GraphicsMagick may be
used to resize, rotate, sharpen, color reduce, or add
special effects to an image and save the result in the same
or differing image format. Image processing operations are
available from the command line, as well as through C, C++,
Perl, Java, or COM programming interfaces. Extensions are
available from third-parties to support programming in
Borland's Delphi, Java, PHP, Python, Scheme, and Ruby.
<p>Both libraries offer a full range of image processing tools
that provide the capability to:</p>
<div class="imquote">
<li>Convert an image from one format to another (e.g.
TIFF to JPEG)</li>
<li>Resize, rotate, sharpen, color reduce, or add special
effects to an image</li>
<li>Create a montage of image thumbnails</li>
<li>Create a transparent image suitable for use on the
<li>Turn a group of images into a GIF animation
<li>Create a composite image by combining several
separate images</li>
<li>Draw shapes or text on an image</li>
<li>Decorate an image with a border or frame</li>
<li>Describe the format and characteristics of an
<p>RMagick is a complete interface to ImageMagick and
GraphicsMagick, defining three major classes containing over
100 methods, plus numerous attributes and constants. RMagick
exploits Ruby idioms such as blocks and iterators, Struct and
Array classes, symbols, ?- and !-suffixed methods, and
<h3>About this document</h3>
<p>This document is divided into 3 parts. The first is this
page. The second part is a usage guide covering both RMagick
and ImageMagick/GraphicsMagick usage and conventions. The
third, and largest, is the reference guide, which describes all
of the RMagick classes and constants. The reference guide
includes many examples.</p>
<p>Accompanying the HTML documentation is a set of over 100
example RMagick programs. Each is a complete, stand-alone
program that either creates an image from scratch or modifies
an input image using one or more RMagick methods. The output
images are used as illustrations in the HTML documentation.
Throughout this document, click any example image to see the
program that created it.</p>
<p><b>Names&nbsp;&nbsp;</b>I've tried to follow the Pickaxe
conventions in this document. A class is identified by its
name, which always starts with a capital letter. An object is
referred to by its class name, starting with a small letter.
For example, a generic ImageList object is referred to as an
<i>imagelist</i>. In the Reference section, when a method
signature identifies the type of an argument or return value,
the type is shown by preceding the class name by "a" or "an".
For example, <var>anImage</var> refers to an Image object, and
<var>anImageList</var> refers to an ImageList object.
Class methods are identified like this: <var>Class.method</var>.
Instance methods are identified like this: <var>Class#method</var>.
<p>RMagick is implemented in the <b>Magick</b> module,
therefore its constants are in the Magick namespace. However,
for clarity I've omitted the <code>Magick::</code> prefix in
most places in this document. You can use the <code>include
Magick</code> statement to add the constants and methods to the
Object namespace.</p>
<p><b>References to ImageMagick and GraphicsMagick</b>&nbsp;
&nbsp;When describing a feature, API, convention, component, or
other element that is shared by both ImageMagick and
GraphicsMagick, I use the string <b>&times;Magick</b>. For
example, "&times;Magick supports over 87 major image formats"
means that both ImageMagick and GraphicsMagick support over 87
<p><b>&times;Magick documentation&nbsp;&nbsp;</b><span
class="imquote">Text that looks like this</span> is quoted from the
&times;Magick documentation.</p>
<p><b>ImageMagick versions&nbsp;&nbsp;</b>When a new method is
introduced in ImageMagick, the ImageMagick version number where
it is first supported is shown next to the method name like
this: <span class="imversion">(5.5.2)</span>. That is, the
method is available with ImageMagick 5.5.2 (for example) and
later versions.</p>
<p><b>GraphicsMagick versions&nbsp;&nbsp;</b>When a new method
is introduced in GraphicsMagick, the GraphicsMagick version
number where it is first supported is shown next to the method
name like this: <span class="gmversion">(1.0.1)</span>. That
is, the method is available with GraphicsMagick 1.0.1 (for
example) and later versions.</p>
<p><b>Example programs and images&nbsp;&nbsp;</b> All of the
example images on these pages were created by RMagick. Click
the image to see the progam code. Example code is shown with a
<span class="example">blue background</span>.</p>
<h3>How to get help</h3>
If you have a question that is not answered by these pages,
email me at <a href=
<h3><a name="bugs">Reporting bugs</a></h3>
<p>Please report problems with RMagick installation and usage
to <code><a href=
""></a></code>. If
you include "RMagick" in the subject I'll probably give your
email top priority.</p>
<p>For quickest results, include the RMagick and &times;Magick
version numbers, along with a thorough description of the
problem.<sup><a href="#truth">1</a></sup> RMagick will tell you
both its version number and &times;Magick's version number.
Simply bring up irb and print the <code>Magick::Version</code>
constant and the <code>Magick::Magick_version</code>
<pre class="example">
irb -r RMagick
p Magick::Version &raquo; "RMagick 1.3.0"
p Magick::Magick_version &raquo; "ImageMagick 5.5.7 05/23/03 Q8"
p Magick::Magick_version &raquo; GraphicsMagick 1.0 05/05/03 Q8"
<p>It will help a lot if you supply a small Ruby program that
reproduces the problem. (Don't forget to include any input
image files!).</p>
<p>Please remember I can't help with Ruby or &times;Magick
installation and configuration problems. For help with Ruby,
post your questions to <code>comp.lang.ruby</code>. For help
with ImageMagick or GraphicsMagick, join the ImageMagick or
GraphicsMagick mailing list. See the instructions at <a href=
"file:///usr/local/share/ImageMagick-5.5.7/www/magick-list.html"></a> or <a href=
<p>I'm not an image processing guru, either, so I probably
won't be able to help with questions about specific image
formats and transformation algorithms. I will be glad, however,
to translate between the RMagick API and the &times;Magick C
API to help you compose a question to the &times;Magick
If you have a script or an image using RMagick that you're particularly
proud of, let me know. I'd like to collect your contributions,
along with other users' contributions, and put them in a
<code>contrib</code> directory to distribute with RMagick. I'm
particularly interested in getting examples for the RMagick
methods that currently have no examples.
<h3><a name="copyrights">Copyright Notices</a></h3>
<li>RMagick is copyright &copy; 2003 by Timothy P.
<li>ImageMagick is copyright &copy; 2003 ImageMagick
<li>GraphicsMagick is copyright &copy; 2003 GraphicsMagick
<li>Ruby is copyrighted free software by Yukihiro
<p><sup><a name="truth">1</a></sup>Don't take offense at this,
please, but in my experience this is something that needs to be
said: Telling the truth will help speed the resolution of your
problem. Don't worry if you think you've done something stupid.
I've got lots of experience at doing stupid things myself.</p>
<table align="right" class="nav" cellpadding="3">
<td style="text-align: left"><a href="constants.html">&lt;-
<td style="text-align: center; color: gray">Contents</td>
<td style="text-align: right"><a href="usage.html">Next
Jump to Line
Something went wrong with that request. Please try again.