FreeImage Ruby Bindings¶ ↑

Overview¶ ↑

The free-image gem provides Ruby language bindings for the FreeImage library. It is free software, released under the MIT License.

FreeImage is an light-weight, open source image manipulation library that supports many popular graphics image formats such as PNG, JPEG, GIF, BMP, and TIFF.

We think FreeImage is a great library for applications that need to read, write, create and modify images and thumbnails because:

Its easy to use
Its supports almost all popular image formats
Its a light-weight alternative to larger libraries such as ImageMagick,
supporting basic manipulation functions but not advanced functionality
Its cross-platform
The ruby bindings are implemented using FFI, so work across all Ruby
implementations and do not have to be compiled
Its much more comprehensive than ImageScience
Has comprehensive documentation

Note that FreeImage is not the right library for you if you need:

Advanced image processing operations such as convolution and transforms
Bitmap drawing
Vector graphics

Installation¶ ↑

free-image requires FreeImage version 3.10 or higher and Ruby 1.8.7 or higher. The easiest way to install free-image is via Ruby Gems. To install:

gem install free-image

Getting Started¶ ↑

Getting started is easy - first work through the examples in the cookbook. Once you've done that, the refer to rdocs for extensive documentation.

Memory Management¶ ↑

Opening and working with images consumes some memory. Generally you won't have to worry about this. When an image goes out of scope, it will be garbage collected and the underlying image memory will be freed.

Having said that, FreeImage also lets you control when the memory is freed. Any method that creates a new image also takes a block. When the block finishes, the underlying image memory is freed. This works the same way as the File.open method. For example:

FreeImage::Bitmap.open('images/lena.png') do |image|
  thumbnail = image.make_thumbail do |thumbail|
    thumbnail.save('images/thumbnail.png', :png)
  end
end

When the inner block finishes the thumbnail image is freed and when the outer block finished the lena image is freed.

If you need even more control, you can use FreeImage::Bitmap#free which frees the underlying image. Be careful though - once the image is freed further usage of it will result in a segmentation fault.

Implementation Status¶ ↑

The FreeImage API is divided into multiple parts. As summarized below, the Ruby ffi bindings currently implement a subset of the available api. Patches are welcome to extend the coverage.

Bitmap functions¶ ↑

General - FreeImage::Bitmap
Bitmap management - FreeImage::Bitmap
Bitmap information - FreeImage::Information, FreeImage::Color::Palette
Filetype - FreeImage::File, FreeImage::IO, FreeImage::Memory
Pixel access - FreeImage::Pixel
Conversion - FreeImage::Conversions
Tone mapping - Not Implemented
ICC profile - FreeImage::ICC
Plugin - Not Implemented
Multipage - Not Implemented
Memory I/O streams - FreeImage::MemoryStream
Compression - Not Implemented
Helper functions - FreeImage::Helper

Metadata Functions¶ ↑

Introduction - Not Implemented
Tag creation and destruction - Not Implemented
Tag accessors - Not Implemented
Metadata iterator - Not Implemented
Metadata accessors - Not Implemented
Metadata helper functions - Not Implemented

Toolkit Functions¶ ↑

Rotation and flipping - FreeImage::Transforms
Upsampling / downsampling - FreeImage::Modify
Color manipulation - Not Implemented
Channel processing - Not Implemented
Copy / Paste / Composite routines - FreeImage::Modify
Background filling - FreeImage::Modify
Miscellaneous algorithms - FreeImage::Helper

Documentation¶ ↑

Documentation is available via rdoc, and is installed automatically with the gem. Note that much of the documentation is directly copied from the FreeImage API documentation available here.

free-image's online documentation is generated using Hanna. To generate documentation from source:

gem install hanna-nouveau
rake rdoc
- or -
rdoc -o doc/rdoc -f hanna -m "README.rdoc" lib   /*.rb README.rdoc

Support¶ ↑

If you have any questions about using free-image, please ?

License¶ ↑

See LICENSE for license information.