RMagick User's Guide and Reference

Ruby+ImageMagickTM
Ruby+GraphicsMagick

# User's Guide and Reference

## Table of Contents

## Introduction

### What is RMagick?

RMagick is a binding from Ruby to the ImageMagick TM and GraphicsMagick image manipulation libraries. Here's how the ImageMagick home page describes ImageMagick:

ImageMagickTM... is a free software suite to create, edit, and compose bitmap images. It can read, convert and write images in a large variety of formats. Images can be cropped, colors can be changed, various effects can be applied, images can be rotated and combined, and text, lines, polygons, ellipses and Bézier curves can be added to images and stretched and rotated.

GraphicsMagick is a branch from ImageMagick 5.5.2 and provides a nearly identical API. The GraphicsMagick web site says this about GraphicsMagick:

GraphicsMagick is the swiss army knife of image processing. It provides a robust collection of tools and libraries which support reading, writing, and manipulating an image in over 88 major formats including important formats like DPX, GIF, JPEG, JPEG-2000, PNG, PDF, SVG, and TIFF. GraphicsMagick supports huge images on systems that support large files, and has been tested with gigapixel-size images. GraphicsMagick can create 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

Both libraries offer a full range of image processing tools that provide the capability to:

- Convert an image from one format to another (e.g. TIFF to JPEG)
- Resize, rotate, sharpen, color reduce, or add special effects to an image
- Create a montage of image thumbnails
- Create a transparent image suitable for use on the Web
- Turn a group of images into a GIF animation sequence
- Create a composite image by combining several separate images
- Draw shapes or text on an image
- Decorate an image with a border or frame
- Describe the format and characteristics of an image

RMagick is a complete interface to ImageMagick and GraphicsMagick. Version 1.0.0 was released in February, 2003. Within its four major classes and 30 minor classes RMagick defines over 600 methods and 225 constants. RMagick exploits Ruby idioms such as blocks and iterators, Struct classes, symbols, ?- and !-suffixed methods, and exceptions.

### About this document

This document is divided into 4 parts. The first is this page. The second part is a user's guide covering both RMagick and ImageMagick/GraphicsMagick usage and conventions. The third part is a reference guide to the ImageList, Image, and Draw classes. This guide includes many examples.

The fourth part covers the newest addition to RMagick, Ruby Vector Graphics (RVG). RVG is a facade for Draw that provides a high-level API for scalable vector graphics. The RVG section includes a tutorial and complete reference documentation.

Accompanying the HTML documentation is a set of over 175 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.

#### Conventions

Names I've tried to follow existing Ruby 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 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 an Image object, and `anImageList` refers to an ImageList object. Class methods are identified like this: `Class.method`. Instance methods are identified like this: `Class#method`.

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. You can use the `include Magick` statement to add the constants and methods to the Object namespace.

References to ImageMagick and GraphicsMagick GraphicsMagick is a fork of ImageMagick and shares most of its APIs. When describing a feature, API, convention, component, or other element that is shared by both, I use the string ×Magick. For example, "×Magick supports over 89 major image formats" means that both ImageMagick and GraphicsMagick support over 89 formats.

×Magick documentation Text that looks like this is quoted from the ×Magick documentation.

Example programs and images All of the example images on these pages were created by RMagick. Click the image to see the progam code. (You may need to configure your browser to allow JavaScript and popup windows.) All example images show the result of applying the method. Many example images show the "before" image as well. When the image is accompanied by this symbol mouse over the image to see the "before" version.

### How to get help

If you have a question that is not answered by these pages, you can post it at the Support Request Tracker or the Feature Request Tracker on RubyForge, or email me at `rmagick at rubyforge.org`.

### Reporting bugs

Please report problems with RMagick installation and usage to the Bug Tracker at RubyForge, or email me at `rmagick at rubyforge.org`.

For quickest results, include the RMagick, ×Magick and Ruby version numbers, along with a thorough description of the problem. RMagick will tell you both its version number and ×Magick's version number. Simply bring up irb and run this command: `ruby -r RMagick -e "puts Magick::Long_version"`

    This is RMagick 1.13.0 ($Date: 2006/09/05 23:11:25 $) Copyright (C) 2006 by Timothy P. Hunter
    Built with ImageMagick 6.2.9 08/21/06 Q8 http://www.imagemagick.org
    Built for ruby 1.8.5 (2006-08-25) [i686-linux]
    Web page: http://rmagick.rubyforge.org
    Email: rmagick@rubyforge.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 ×Magick installation and configuration problems. For help with Ruby, post your questions to `comp.lang.ruby`. For help with ImageMagick or GraphicsMagick, join the ImageMagick or GraphicsMagick mailing list. See the instructions at http://www.imagemagick.org/script/mailing-list.php or http://sourceforge.net/projects/graphicsmagick/.

I'm not an image processing guru, either, so I probably won't be able to help with questions about specific image formats and transformations. I will be glad, however, to translate between the RMagick API and the ×Magick C API to help you compose a question to the ×Magick developers.

### Contributions

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

### Copyright Notices

- RMagick is copyrighted by Timothy P. Hunter.
- ImageMagick is copyrighted by ImageMagick Studio.
- GraphicsMagick is copyrighted by the GraphicsMagick Group.
- Ruby is copyrighted free software by Yukihiro Matsumoto.