RMagick

Table of Contents


Introduction

What is RMagick?

RMagick is a interface, or binding, from the Ruby language to the ImageMagick TM library of image manipulation routines. Here's how the ImageMagick home page describes ImageMagick:
ImageMagickTM is a robust collection of tools and libraries...to 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.
Here are just a few examples of what ImageMagick can do:
RMagick is a complete interface to ImageMagick that defines three major classes containing over 100 methods, plus numerous attributes and constants. RMagick exploits Ruby-isms such as blocks and iterators, Struct and Array classes, symbols, ?- and !-suffixed methods, and exceptions.

About this document

This document is divided into 3 parts. The first is this page. The second part is a usage guide covering both RMagick and ImageMagick 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.

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. Click any image to see the program that created it.

Conventions

Names  I've tried to follow standard Ruby conventions in this document. A class is always 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, an generic ImageList object is referred to as an imagelist. 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, anImage refers to a Image object, and anImageList refers to an ImageList object.

RMagick is implemented in the Magick module, therefore its constants are in the Magick namespace. However, for clarity I've omitted the Magick:: prefix in most places in this document .

ImageMagick documentation   Text in this color is quoted from the ImageMagick documentation.

ImageMagick versions   The ImageMagick API changes rapidly. When a method is not available in some versions of ImageMagick, the ImageMagick version number where it is first supported is shown next to the method name like this: (5.5.2). That is, the method is available with ImageMagick 5.5.2 (for example) and later versions.

Example programs and images   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 blue background.

How to get help

If you have a question that is not answered by these pages, email me at cyclists@nc.rr.com.

Reporting bugs

Please report problems with RMagick installation and usage to cyclists@nc.rr.com. If you include "RMagick" in the subject I'll probably give your email top priority.

For quickest results, include the RMagick and ImageMagick version numbers, along with a thorough description of the problem.1 RMagick will tell you both its version number and ImageMagick's version number. Simply bring up irb and print the Magick::Version constant and the Magick::Magick_version constants.

irb -r RMagick
p Magick::Version » "RMagick 1.0.1"
p Magick::Magick_version » "ImageMagick 5.5.6 04/01/03 Q16 http://www.imagemagick.org"

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!).

Please remember I can't help with Ruby or ImageMagick installation and configuration problems. For help with Ruby, post your questions to comp.lang.ruby. For help with ImageMagick, join the ImageMagick mailing list. See the instructions at http://www.imagemagick.org/www/magick-list.html.

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 ImageMagick C API to help you compose a question to the ImageMagick developers.

Contributions

If you produce 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 contrib directory to distribute with RMagick. I'm particularly interested in getting examples for the RMagick methods that currently have no examples.

Copyright Notices


1Don'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.


<- Prev Contents Next ->