Recipe 15.1. Installing RMagick for Image Processing

Problem

Contributed by: Matt Ridenour

You would like your Rails application to create and modify graphic files, performing tasks such as generating thumbnail previews, drawing simple graphs, or adding textual information such as a timestamp to an image.

Solution

RMagick is an interface that gives Ruby access to the ImageMagick or GraphicsMagick image processing libraries. ImageMagick and GraphicsMagick have built in support for manipulating several image formats; they rely on delegate libraries for additional formats. The installation process varies considerably from platform to platform. Depending on your needs, it can be quite easy or quite involved.

Windows

Windows users are fortunate to have available an RMagick gem that includes ImageMagick as well as the most commonly used delegate libraries in a precompiled binary form. Installation involves a few quick trips to the command prompt but is generally fast and easy.

The RMagick win32 gem isn't available on the RubyForge gem server, so you must install the gem locally. Download the latest version of the RMagick win32 binary gem from the RMagick RubyForge page (http://rubyforge.org/projects/rmagick).

Unzip the archive (RMagick-1.9.1-IM-6.2.3-win32.zip), and navigate to the unzipped directory using the command prompt. Type the following command to install the downloaded gem:

C:\src\RMagick-1.9.1-IM-6.2.3-win32>gem install RMagick-win32-1.9.2-mswin32.gem

Next, run the setup script to finish the installation. This script is also located in the unzipped RMagick directory:

C:\src\RMagick-1.9.1-IM-6.2.3-win32>ruby postinstall.rb

The Windows installation is complete.

Linux

We will use the apt-get package manager, to download, build, and install all the delegate libraries necessary to run the ImageMagick and GraphicsMagick sample scripts. Then we'll manually download, build, and install ImageMagick and RMagick.

~$ sudo apt-get install freetype libjpeg libtiff libpng libwmf

Now we are ready to install ImageMagick or GraphicsMagick. For this example, we'll use ImageMagick, but the process is the same for both.

Next, download the ImageMagick source files archive (ImageMagick.tar.gz) from http://www.imagemagick.org.

Uncompress the archive, and navigate to the compressed archive folder with the following shell commands:

~$ tar xvzf ImageMagick.tar.gz ~$ cd ImageMagick-x.x.x

Now, use this command to configure ImageMagick:

~/ImageMagick-x.x.x]$ ./configure --disable-static --with-modules

Once the configuration process is finished, type the following commands to compile and install ImageMagick:

~/ImageMagick-x.x.x]$ make ~/ImageMagick-x.x.x]$ sudo make install

Now download the latest version of RMagick from RubyForge. Uncompress the archive (RMagick-x.x.x.tar.gz) and navigate to the RMagick folder with the following shell commands:

~$ tar xvzf RMagick-x.x.x.tar.gz ~$ cd RMagick-x.x.x

Finally, configure, compile, and install with the following shell commands:

~/RMagick-x.x.x]$ ./configure ~/RMagick-x.x.x]$ make ~/RMagick-x.x.x]$ sudo make install

RMagick is now installed on Linux.

Mac OS X

If you want to jump into using RMagick with Rails on Mac OS X as quickly as possible, use the Locomotive Max Bundle. If you are a system administrator building a Mac OS X production server, the MacPorts method would better suit your needs.

Chances are, if you're running Rails for anything more complicated than a personal blog or small business application, you will quickly outgrow Locomotive. Let's look at the process of installing RMagick without using Locomotive. Things are going to get a bit more complex. There is a lot of downloading and compilation ahead, so allocate yourself some time. You will need to be an administrative user to continue. If you're a coffee drinker, refill now, and use the big mug. We will be building all the libraries we need from their source code, so make sure you've installed Apple's XCode Tools. You also need have X11 and X11SDK installed. All of these are located on your Mac OS X installation disk. There are several ways of going about RMagick's installation, but one of the gentler paths is using MacPorts (formerly DarwinPorts) to download and install all the necessary software. If you don't already have MacPorts, you can get it from http://www.macports.org.

Once you've downloaded the MacPorts disk image and mounted it, double-click the installer, and follow the instructions. After the installation completes, verify that the port command is available:

~$ which port /opt/local/bin/port

If you get a "command not found" message, then add the following line to your .bash_profile:

export PATH=$PATH:/opt/local/bin

If you already have MacPorts installed, and it's been a while since you updated the port list, it would be good idea to update before continuing:

$ sudo port -d selfupdate

Now use MacPorts to download and compile all the dependencies, dependencies of dependencies, et al., for ImageMagick and GraphicsMagick. Open the Terminal, and type the following sequence of commands:

~$ sudo port install jpeg libpng libwmf tiff lcms freetype ghostscript

Of special note here is the freetype library. You should now have two different versions of it installed on your Mac, one from the X11 installation and the one we just installed using MacPorts. Make sure you are using the MacPorts version before continuing. Use the Unix which command to find out where freetype-config lives; it should be in /opt/local/bin:

~$ which freetype-config

/opt/local/bin/freetype-config

What you don't want to see is this:

/usr/X11R6/bin/freetype-config

If you are having a problem, you need to alter the order of directories in your shell's $PATH variable. Edit your shell settings so that in the $PATH variable, the /opt/local/bin path appears before the /usr/X11R6/bin/ path.

Now we are ready to install ImageMagick or GraphicsMagick. For this example, we'll use ImageMagick, but the process is just the same for both. Download the ImageMagick source files archive (ImageMagick-x.x.x-x.tar.gz) from http://www.imagemagick.org. Uncompress the archive, and navigate to the ImageMagick folder with the following Terminal commands:

~$ tar xvzf ImageMagick.tar.gz ~$ cd ImageMagick-6.2.7/

Use these commands to configure ImageMagick:

~/ImageMagick-6.2.7$ export CPPFLAGS=-I/opt/local/include ~/ImageMagick-6.2.7$ export LDFLAGS=-L/opt/local/lib ~/ImageMagick-6.2.7$ ./configure --prefix=/opt/local \ > --disable-static --with-modules \ > --with-gs-font-dir=/opt/local/share/ghostscript/fonts \ > --without-perl --without-magick-plus-plus --with-quantum-depth=8

Once the configuration process is finished, type the following commands to compile and install ImageMagick:

~/ImageMagick-6.2.7$ make ~/ImageMagick-6.2.7$ sudo make install

At last we are ready to download and compile RMagick. Download the latest version from http://rubyforge.org/projects/rmagick. Uncompress the archive (RMagick-x.x.x.tar.gz), and navigate to the compressed archive folder with the following Terminal commands:

~$ tar xvzf RMagick-x.x.x.tar.gz ~$ cd RMagick-x.x.x

Only three steps left. Configure, compile, and install with the following commands:

~/RMagick-x.x.x$ ./configure ~/RMagick-x.x.x$ make ~/RMagick-x.x.x$ sudo make install

If your home folder is on a volume that has a blank space in the volume name, RMagick won't compile. Rename the volume, or install from another account without this limitation.

Congratulations, you've just installed RMagick.

Discussion

To test that everything is running smoothly, create this simple script:

require 'rubygems' require 'RMagick' include Magick test_image = Image.new(100,100) { self.background_color = "green" } test_image.write("green100x100.jpg") exit

Save the script as test_RMagick.rb, and run it from the command line. The script should create a green 100x100 pixel JPEG file in the current directory named green100x100.jpg. You can open this image using your favorite image viewing program.

RMagick comes with an excellent set of documentation including tutorials and reference material in HTML format. On Windows, this documentation is installed in the gem's directory. For example, if you are using InstantRails, you can find the documentation here:

C:\Instant-Rails-1.0\ruby\lib\ruby\gems\1.8\gems\RMagick-win32-1.9.2-mswin32\    doc\index.html

In Linux, look for the RMagick documentation here:

/usr/local/share/RMagick/index.html

On Mac OS X, the RMagick documentation for the MacPorts install is located here:

/opt/local/share/RMagick

And the Mac OS X Locomotive RMagick documentation is hidden here:

/Application/Locomotive/Bundles/rails-1.0.0-max.bundle/Contents/      Resources/ports/lib/ruby/gems/1.8/gems/rmagick-1.10.1/doc/index.html

The documentation isn't Rails-specific but it will provide you with the necessary skills to get started using the library.