free-image 0.6.2 → 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9ebfb83c042b8dc13d9284759db6aaafb51f706d
+  data.tar.gz: 94a96105ad584b3a77175d2a91d997316cc303bb
+SHA512:
+  metadata.gz: 7e468e23c9918e0bebe109220e49c563277d700fc5a10d4e924a0042ae32900117e28817388dd95c48fb55659764749eb65ccc6ecaf567afa2f316d6c1380940
+  data.tar.gz: bfd559ca4e30420bf107711e3e96258e6287531407810786844ff31a00e76b1b84381eea461a71a33686b09f9e2d00cd19eaa2d633703cc69e35dfc7f86e284b

data/HISTORY

@@ -1,20 +1,31 @@
-= Release History
-
-== 0.6.2 / 2011-09-06 Charlie Savage
-
-* Add null pointer checks when loading images
-* Add null pointer check when creating a new image
-
-== 0.6.1 / 2011-09-06 Charlie Savage
-
-* Use release version on windows of FreeImage, not debug version.
-
-== 0.6.0 / 2011-09-02 Charlie Savage
-
-* Update documentation
-* Add alternate library names
-* Add support for blocks in all methods that return bitmaps
-
-== 0.5.0 / 2011-08-28 Charlie Savage
-
+= Release History
+
+== 0.7.0 / 2015-10-10
+* Add test and example for compositing images (Charlie Savage)
+* Specify freeimage version requirement (Charlie Savage)
+* Fix up failing tests and test with FreeImage version 3.17.0 (Charlie Savage)
+* Fix flip_vertical! to flip vertically, not horizontally (Chris Howlett)
+* No rgb mask stored in modern FreeImage unless using BI_BITFIELDS in 16 bit BMP  (Benjamin Armintor)
+* Ruby object_id is a 32-bit value (Benjamin Armintor)
+* Fix C type translation for bytes on osx/intel (Benjamin Armintor)
+* Test suite clean up  (Benjamin Armintor)
+* Minor documentation updates (Charlie Savage)
+
+== 0.6.2 / 2011-09-06
+
+* Add null pointer checks when loading images
+* Add null pointer check when creating a new image
+
+== 0.6.1 / 2011-09-06
+
+* Use release version on windows of FreeImage, not debug version.
+
+== 0.6.0 / 2011-09-02
+
+* Update documentation
+* Add alternate library names
+* Add support for blocks in all methods that return bitmaps
+
+== 0.5.0 / 2011-08-28 Charlie Savage
+
 * Initial Commit

data/LICENSE

@@ -1,21 +1,21 @@
-  Copyright (c) 2008-2011 Charlie Savage and contributors
-  Copyright (c) 2002-2007 Sean Chittenden and contributors
-  Copyright (c) 2001 Wai-Sun "Squidster" Chia
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in 
-the Software without restriction, including without limitation the rights to 
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
-of the Software, and to permit persons to whom the Software is furnished to do
-so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  Copyright (c) 2008-2011 Charlie Savage and contributors
+  Copyright (c) 2002-2007 Sean Chittenden and contributors
+  Copyright (c) 2001 Wai-Sun "Squidster" Chia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in 
+the Software without restriction, including without limitation the rights to 
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

data/README.rdoc

@@ -1,120 +1,120 @@
-= FreeImage Ruby Bindings
-
-== Overview
-The free-image gem provides Ruby language bindings for the
-FreeImage[http://freeimage.sourceforge.net/] 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}[rdoc-ref:FreeImage.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 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[rdoc-ref:cookbook.rdoc].
-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[http://downloads.sourceforge.net/freeimage/FreeImage3151.pdf].
-
-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.
+= FreeImage Ruby Bindings
+
+== Overview
+The free-image gem provides Ruby language bindings for the
+FreeImage[http://freeimage.sourceforge.net/] 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}[rdoc-ref:FreeImage.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}[http://cfis.github.io/free-image-ruby/].
+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[http://downloads.sourceforge.net/freeimage/FreeImage3151.pdf].
+
+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.

data/Rakefile

@@ -1,47 +1,51 @@
-# encoding: UTF-8
-# !/usr/bin/env ruby
-
-require "rubygems"
-require "rake/testtask"
-require "rubygems/package_task"
-require "rdoc/task"
-require "fileutils"
-
-GEM_NAME = "free-image"
-
-# Read the spec file
-spec = Gem::Specification.load("#{GEM_NAME}.gemspec")
-
-# Setup generic gem
-Gem::PackageTask.new(spec) do |pkg|
-  pkg.package_dir = 'pkg'
-  pkg.need_tar    = false
-end
-
-# RDoc Task
-desc "Generate rdoc documentation"
-RDoc::Task.new("rdoc") do |rdoc|
-  rdoc.rdoc_dir = 'doc'
-  rdoc.title    = "FreeImage"
-  # Show source inline with line numbers
-  rdoc.options << "--line-numbers"
-  # Use Hanna - this only works with RDoc 3.1 or greater
-  rdoc.generator = 'hanna'
-  # Make the readme file the start page for the generated html
-  rdoc.main = 'cookbook.rdoc'
-  rdoc.rdoc_files = FileList['HISTORY',
-                             'LICENSE',
-                             '*.rdoc',
-                             'lib/**/*.rb']
-end
-
-desc "Setup Cookbook"
-task :cookbook => :rdoc do
-  FileUtils.cp_r("test/images", "doc/cookbook")
-end
-
-# Test Task
-Rake::TestTask.new do |t|
-  t.libs << "test"
-  t.verbose = true
-end
+# encoding: UTF-8
+# !/usr/bin/env ruby
+
+require "rubygems"
+require "rake/testtask"
+require "rubygems/package_task"
+require "rdoc/task"
+require "fileutils"
+
+GEM_NAME = "free-image"
+
+# Read the spec file
+spec = Gem::Specification.load("#{GEM_NAME}.gemspec")
+
+# Setup generic gem
+Gem::PackageTask.new(spec) do |pkg|
+  pkg.package_dir = 'pkg'
+  pkg.need_tar    = false
+end
+
+# RDoc Task
+desc "Generate rdoc documentation"
+RDoc::Task.new("rdoc") do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "FreeImage"
+  # Show source inline with line numbers
+  rdoc.options << "--line-numbers"
+  # Use Hanna - this only works with RDoc 3.1 or greater
+  rdoc.generator = 'hanna'
+  # Make the readme file the start page for the generated html
+  rdoc.main = 'cookbook.rdoc'
+  rdoc.rdoc_files = FileList['HISTORY',
+                             'LICENSE',
+                             '*.rdoc',
+                             'lib/**/*.rb']
+end
+
+desc "Setup Cookbook"
+task :cookbook => :rdoc do
+  FileUtils.cp_r("test/images", "doc/cookbook")
+end
+
+# Test Task
+Rake::TestTask.new do |t|
+  t.pattern = 'test/**/test_*.rb'
+  t.libs << "lib"
+  t.libs << "test"
+  t.verbose = true
+end
+
+task default: :test

data/cookbook.rdoc

@@ -1,238 +1,249 @@
-= \Getting Started With \FreeImage
-Below are various recipes to get you up and running with \FreeImage as quickly
-as possible.  The example images tcan be found in the
-test/images directory.  For more general information about \FreeImage, including
-installation instructions, please refer to README.rdoc.
-
-== Loading An Image
-The first step in using \FreeImage is to load an image.  \FreeImage can load
-images from files[rdoc-ref::FreeImage::File], strings[rdoc-ref::FreeImage::Memory]
-or IO[rdoc-ref::FreeImage::IO] streams.  The simplest way to do this is
-via the FreeImage::Bitmap.open method:
-
-  image = FreeImage::Bitmap.open('images/lena.tiff')
-  image = FreeImage::Bitmap.open(io_object)
-  image = FreeImage::Bitmap.open(FreeImage::Memory.new(string))
-
-The open method also takes two additional optional parameters, format and flags,
-that provide greater control over opening images if needed.
-
-The open method works similary to File.open, meaning you can also pass it a block.
-
-  FreeImage::Bitmap.open('images/lena.png') do |image|
-    ... do some stuff..
-  end
-
-Once the block completes, the image will be automatically freed for you.  If you don't
-pass block, then the image will be freed by Ruby's Garbage Collector once it goes out
-of scope.  For more information about memory management, refer to
-the readme [rdoc-ref:README.rdoc].
-
-Image[link:cookbook/lena.png]
-
-== Saving An Image
-Now let's say you want to save the image to :png format.  This is done
-via the FreeImage::Bitmap.save method.  The save method takes a destination,
-which can be a file[rdoc-ref::FreeImage::File], string[rdoc-ref::FreeImage::Memory]
-or IO[rdoc-ref::FreeImage::IO] stream, and an image format.
-
-  image.save('images/lena.png', :png)
-
-== Creating a Thumbnail
-Next, let's assume our application needs to show a list of thumbnails for the images
- it stores.  This can be done using the make_thumbnail[rdoc-ref:FreeImage::Modify.make_thumbnail]
-method in the Modify[rdoc-ref:FreeImage::Modify] module.
-
-  thumbnail = image.make_thumbnail(100)
-  thumbnail.save('images/lena_thumbnail.png', :png)
-
-Thumbnail[link:cookbook/lena_thumbnail.png]
-
-== Putting a Border Around a Thumbnail
-Once we have created a thumbnail, let's outline it with a red border.  There
-are various approaches to do doing this.  In the first approach, we'll use
-the enlarge_canvas[FreeImage::Modify.enlarge_canvas] method.
-
-  # Border size
-  border = 4
-
-  # Specify the color as red
-  color = FreeImage::RGBQuad.create(255, 0, 0)
-
-  # Add 4 pixel red border around the thumbnail
-  thumbnail_border = thumbnail.enlarge_canvas(border, border, border, border, color)
-  thumbnail_border.save('images/lena_thumbnail_border_1.png', :png)
-
-ThumbnailBorderEnlarge[link:cookbook/lena_thumbnail_border_enlarge.png]
-
-In the second approach, let's create a image with a red background
-and then paste it on top of our thumbnail:
-
-  # Create a red image that is the same size as the thumbnail
-  red_image = FreeImage::Bitmap.create(thumbnail.width, thumbnail.height, thumbnail.bits_per_pixel)
-  red_image_new.fill_background(color)
-
-  # Now copy a subimage from the thumbnail that is 2 borders less wide and tall
-  subimage = thumbnail.copy(border, border, thumbnail.width - border, thumbnail.height - border)
-
-  # Now paste the subimage into the red image.  Specify an alpha over 255
-  # to disable alpha blending
-  red_image.paste(subimage, border, border, 300)
-  red_image.save('images/test1.png', :png)
-  thumbnail_border.save('images/lena_thumbnail_border_2.png', :png)
-
-ThumbnailBorderPaste[link:cookbook/lena_thumbnail_border_paste.png]
-
-== Resampling An Image
-If you need additional control over how an image is resampled, use the
-FreeImage::Bitmap#rescale method, which lets you specify a filtering
-algorithm.  To see how each filter works, let's scale up the thumbnail
-by 400%.
-
-  thumbnail = FreeImage::Bitmap.open('images/lena_thumbnail.png')
-
-  FreeImage.enum_type(:filter).symbols.each do |filter|
-    rescaled = thumbnail.rescale(thumbnail.width * 4, thumbnail.height * 4, filter)
-    rescaled.save("images/lena_rescale_#{filter.to_s}.png", :png)
-  end
-
-RescaleBox[link:cookbook/lena_rescale_box.png]
-RescaleBicubic[link:cookbook/lena_rescale_bicubic.png]
-RescaleBilinear[link:cookbook/lena_rescale_bilinear.png]
-RescaleBspline[link:cookbook/lena_rescale_bspline.png]
-RescaleCatmullrom[link:cookbook/lena_rescale_catmullrom.png]
-RescaleLanczos3[link:cookbook/lena_rescale_lanczos3.png]
-
-== Flipping An Image
-The Transform modules lets you flip or rotate an image. Let's say you want to
-flip your image horizontally:
-
-  image.flip_horizontal
-  image.save('images/lena_flipped.png', :png)
-
-Thumbnail[link:cookbook/lena_flipped.png]
-
-== Rotating An Image
-Next, let's rotate an image. Two methods are provide, FreeImage::Bitmap#rotate and
-FreeImage::Bitmap#rotate_ex.  The #rotate method is simpler to use:
-
-  image = FreeImage::Bitmap.open('images/lena.png', :png)
-
-  # Rotate the image 45 degrees using white as the background fill color
-  color = FreeImage::RGBQuad.create(255, 255, 255, 0)
-  rotated = image.rotate(45, color)
-  rotated.save("images/lena_rotate_45.png", :png)
-
-Thumbnail[link:cookbook/lena_rotate_45.png]
-
-Notice that the image size and geometry has changed?  Thus, the #rotate
-function is best for rotating and image 90, 180 or 270 degrees.
-
-Let's now rotate the image using the #rotate_ex method while using a mask:
-
-  rotated = image.rotate_ex(45, 0, 0, image.width/2, image.height/2, true)
-  rotated.save("images/lena_rotate_ex_45_masked.png", :png)
-
-And now let's rotate the image without a mask, so data is filled in using
-a mirroring algorithm:
-
-  rotated = image.rotate_ex(45, 0, 0, image.width/2, image.height/2, false)
-  rotated.save("images/lena_rotate_ex_45_mirrored.png", :png)
-
-Thumbnail[link:cookbook/lena_rotate_ex_45_masked.png]
-Thumbnail[link:cookbook/lena_rotate_ex_45_mirrored.png]
-
-Last, lets rotate the image around the top left corner:
-
-  rotated = image.rotate_ex(45, 0, 0, 0, 0, true)
-  rotated.save("images/lena_rotate_ex_45_top_left.png", :png)
-
-Thumbnail[link:cookbook/lena_rotate_ex_45_top_left.png]
-
-== Compositing An Image
-\FreeImage also lets you composite an image with a background color or another image.
-Here is an example of compositing an image with the color green.
-
-  image = FreeImage::Bitmap.open('images/sample.png')
-  color = FreeImage::RGBQuad.create(0, 255, 0, 0)
-  composite =  image.composite_with_color(color)
-  composite.save("images/sample_composite_color.png", :png)
-
-Sample[link:cookbook/sample.png]
-SampleCompositeColor[link:cookbook/sample_composite_color.png]
-
-== Manipulating An Image
-\FreeImage also allows you to directly access each pixel in an image.
-As an example, let's create an image that has a gradient from
-blue in the top left corner to green in the bottom right
-
-  image = FreeImage::Bitmap.create(300, 300, 24)
-  color = FreeImage::RGBQuad.new
-
-  image.width.times do |x|
-    image.height.times do |y|
-      color[:green] = (x.to_f/image.width) * 255
-      color[:blue] =  (y.to_f/image.height) * 255
-      image.set_pixel_color(x, y, color)
-    end
-  end
-
-  image.save('images/gradient.png', :png)
-
-Gradient[link:cookbook/gradient.png]
-
-You can use a similar technique as another solution to drawing a border around a
-thumbnail as discussed above.
-
-== Using Scanlines
-Scanlines[rdoc-ref:FreeImage::Scanline] provide low level access to image data.  
-The only lower-level access is working with the actual raw bytes, which you can do
-via the FreeeImage::Bitmap#bytes method, but its not recommended.
-
-A scanline represents one row of image data, starting from the bottom.  Let's go back
-to our example above of drawing a red border around a thumbnail.
-
-  # Helper method
-  def set_to_red(color)
-    color[:red] = 255
-    color[:green] = 0
-    color[:blue] = 0
-  end
-
-  # Create a thumbnail
-  image = FreeImage::Bitmap.open('images/lena.png')
-  thumbnail = image.make_thumbnail(100)
-
-  # Draw bottom border 4 pixels tall
-  (0..3).each do |index|
-    scanline = thumbnail.scanline(index)
-    scanline.each do |color|
-      set_to_red(color)
-    end
-  end
-
-  # Draw top border 4 pixels tall
-  ((thumbnail.height - 5)..(thumbnail.height - 1)).each do |index|
-    scanline = thumbnail.scanline(index)
-    scanline.each do |color|
-      set_to_red(color)
-    end
-  end
-
-  # We could skip top and bottom 4 scanlines since
-  # already drew them.
-  thumbnail.height.each do |index|
-    scanline = thumbnail.scanline(index)
-    # Draw left and right borders 4 pixels wide
-    (0..4).each do |index|
-      set_to_red(scanline[index])
-    end
-
-    ((thumbnail.width - 5)..(thumbnail.width - 1)).each do |index|
-      set_to_red(scanline[index])
-    end
-  end
-
-  thumbnail.save("images/lena_thumbnail_border_scanline.png", :png)
-
+= \Getting Started With \FreeImage
+Below are various recipes to get you up and running with \FreeImage as quickly
+as possible.  The example images tcan be found in the
+test/images directory.  For more general information about \FreeImage, including
+installation instructions, please refer to README.rdoc.
+
+== Loading An Image
+The first step in using \FreeImage is to load an image.  \FreeImage can load
+images from files[rdoc-ref::FreeImage::File], strings[rdoc-ref::FreeImage::Memory]
+or IO[rdoc-ref::FreeImage::IO] streams.  The simplest way to do this is
+via the FreeImage::Bitmap.open method:
+
+  image = FreeImage::Bitmap.open('images/lena.tiff')
+  image = FreeImage::Bitmap.open(io_object)
+  image = FreeImage::Bitmap.open(FreeImage::Memory.new(string))
+
+The open method also takes two additional optional parameters, format and flags,
+that provide greater control over opening images if needed.
+
+The open method works similary to File.open, meaning you can also pass it a block.
+
+  FreeImage::Bitmap.open('images/lena.png') do |image|
+    ... do some stuff..
+  end
+
+Once the block completes, the image will be automatically freed for you.  If you don't
+pass block, then the image will be freed by Ruby's Garbage Collector once it goes out
+of scope.  For more information about memory management, refer to
+the readme [rdoc-ref:README.rdoc].
+
+Image[link:cookbook/lena.png]
+
+== Saving An Image
+Now let's say you want to save the image to :png format.  This is done
+via the FreeImage::Bitmap.save method.  The save method takes a destination,
+which can be a file[rdoc-ref::FreeImage::File], string[rdoc-ref::FreeImage::Memory]
+or IO[rdoc-ref::FreeImage::IO] stream, and an image format.
+
+  image.save('images/lena.png', :png)
+
+== Creating a Thumbnail
+Next, let's assume our application needs to show a list of thumbnails for the images
+ it stores.  This can be done using the make_thumbnail[rdoc-ref:FreeImage::Modify.make_thumbnail]
+method in the Modify[rdoc-ref:FreeImage::Modify] module.
+
+  thumbnail = image.make_thumbnail(100)
+  thumbnail.save('images/lena_thumbnail.png', :png)
+
+Thumbnail[link:cookbook/lena_thumbnail.png]
+
+== Putting a Border Around a Thumbnail
+Once we have created a thumbnail, let's outline it with a red border.  There
+are various approaches to do doing this.  In the first approach, we'll use
+the enlarge_canvas[FreeImage::Modify.enlarge_canvas] method.
+
+  # Border size
+  border = 4
+
+  # Specify the color as red
+  color = FreeImage::RGBQuad.create(255, 0, 0)
+
+  # Add 4 pixel red border around the thumbnail
+  thumbnail_border = thumbnail.enlarge_canvas(border, border, border, border, color)
+  thumbnail_border.save('images/lena_thumbnail_border_1.png', :png)
+
+ThumbnailBorderEnlarge[link:cookbook/lena_thumbnail_border_enlarge.png]
+
+In the second approach, let's create a image with a red background
+and then paste it on top of our thumbnail:
+
+  # Create a red image that is the same size as the thumbnail
+  red_image = FreeImage::Bitmap.create(thumbnail.width, thumbnail.height, thumbnail.bits_per_pixel)
+  red_image_new.fill_background(color)
+
+  # Now copy a subimage from the thumbnail that is 2 borders less wide and tall
+  subimage = thumbnail.copy(border, border, thumbnail.width - border, thumbnail.height - border)
+
+  # Now paste the subimage into the red image.  Specify an alpha over 255
+  # to disable alpha blending
+  red_image.paste(subimage, border, border, 300)
+  red_image.save('images/test1.png', :png)
+  thumbnail_border.save('images/lena_thumbnail_border_2.png', :png)
+
+ThumbnailBorderPaste[link:cookbook/lena_thumbnail_border_paste.png]
+
+== Resampling An Image
+If you need additional control over how an image is resampled, use the
+FreeImage::Bitmap#rescale method, which lets you specify a filtering
+algorithm.  To see how each filter works, let's scale up the thumbnail
+by 400%.
+
+  thumbnail = FreeImage::Bitmap.open('images/lena_thumbnail.png')
+
+  FreeImage.enum_type(:filter).symbols.each do |filter|
+    rescaled = thumbnail.rescale(thumbnail.width * 4, thumbnail.height * 4, filter)
+    rescaled.save("images/lena_rescale_#{filter.to_s}.png", :png)
+  end
+
+RescaleBox[link:cookbook/lena_rescale_box.png]
+RescaleBicubic[link:cookbook/lena_rescale_bicubic.png]
+RescaleBilinear[link:cookbook/lena_rescale_bilinear.png]
+RescaleBspline[link:cookbook/lena_rescale_bspline.png]
+RescaleCatmullrom[link:cookbook/lena_rescale_catmullrom.png]
+RescaleLanczos3[link:cookbook/lena_rescale_lanczos3.png]
+
+== Flipping An Image
+The Transform modules lets you flip or rotate an image. Let's say you want to
+flip your image horizontally:
+
+  image.flip_horizontal
+  image.save('images/lena_flipped.png', :png)
+
+Thumbnail[link:cookbook/lena_flipped.png]
+
+== Rotating An Image
+Next, let's rotate an image. Two methods are provide, FreeImage::Bitmap#rotate and
+FreeImage::Bitmap#rotate_ex.  The #rotate method is simpler to use:
+
+  image = FreeImage::Bitmap.open('images/lena.png', :png)
+
+  # Rotate the image 45 degrees using white as the background fill color
+  color = FreeImage::RGBQuad.create(255, 255, 255, 0)
+  rotated = image.rotate(45, color)
+  rotated.save("images/lena_rotate_45.png", :png)
+
+Thumbnail[link:cookbook/lena_rotate_45.png]
+
+Notice that the image size and geometry has changed?  Thus, the #rotate
+function is best for rotating and image 90, 180 or 270 degrees.
+
+Let's now rotate the image using the #rotate_ex method while using a mask:
+
+  rotated = image.rotate_ex(45, 0, 0, image.width/2, image.height/2, true)
+  rotated.save("images/lena_rotate_ex_45_masked.png", :png)
+
+And now let's rotate the image without a mask, so data is filled in using
+a mirroring algorithm:
+
+  rotated = image.rotate_ex(45, 0, 0, image.width/2, image.height/2, false)
+  rotated.save("images/lena_rotate_ex_45_mirrored.png", :png)
+
+Thumbnail[link:cookbook/lena_rotate_ex_45_masked.png]
+Thumbnail[link:cookbook/lena_rotate_ex_45_mirrored.png]
+
+Last, lets rotate the image around the top left corner:
+
+  rotated = image.rotate_ex(45, 0, 0, 0, 0, true)
+  rotated.save("images/lena_rotate_ex_45_top_left.png", :png)
+
+Thumbnail[link:cookbook/lena_rotate_ex_45_top_left.png]
+
+== Compositing An Image
+\FreeImage also lets you composite an image with a background color or another image.
+Here is an example of compositing an image with the color green.
+
+  image = FreeImage::Bitmap.open('images/sample.png')
+  color = FreeImage::RGBQuad.create(0, 255, 0, 0)
+  composite =  image.composite_with_color(color)
+  composite.save("images/sample_composite_color.png", :png)
+
+Sample[link:cookbook/sample.png]
+SampleCompositeColor[link:cookbook/sample_composite_color.png]
+
+And here is an example of compositing two images together:
+
+    image = FreeImage::Bitmap.open(image_path('sample.png'))
+    background = FreeImage::Bitmap.open(image_path('gradient.png'))
+    # Need to make sure the background image is the same size
+    background = background.rescale(image.width, image.height, :box)
+    composite = image.composite(background)
+
+Sample[link:cookbook/sample.png]
+SampleCompositeColor[link:cookbook/sample_composite.png]
+
+== Manipulating An Image
+\FreeImage also allows you to directly access each pixel in an image.
+As an example, let's create an image that has a gradient from
+blue in the top left corner to green in the bottom right
+
+  image = FreeImage::Bitmap.create(300, 300, 24)
+  color = FreeImage::RGBQuad.new
+
+  image.width.times do |x|
+    image.height.times do |y|
+      color[:green] = (x.to_f/image.width) * 255
+      color[:blue] =  (y.to_f/image.height) * 255
+      image.set_pixel_color(x, y, color)
+    end
+  end
+
+  image.save('images/gradient.png', :png)
+
+Gradient[link:cookbook/gradient.png]
+
+You can use a similar technique as another solution to drawing a border around a
+thumbnail as discussed above.
+
+== Using Scanlines
+Scanlines[rdoc-ref:FreeImage::Scanline] provide low level access to image data.  
+The only lower-level access is working with the actual raw bytes, which you can do
+via the FreeeImage::Bitmap#bytes method, but its not recommended.
+
+A scanline represents one row of image data, starting from the bottom.  Let's go back
+to our example above of drawing a red border around a thumbnail.
+
+  # Helper method
+  def set_to_red(color)
+    color[:red] = 255
+    color[:green] = 0
+    color[:blue] = 0
+  end
+
+  # Create a thumbnail
+  image = FreeImage::Bitmap.open('images/lena.png')
+  thumbnail = image.make_thumbnail(100)
+
+  # Draw bottom border 4 pixels tall
+  (0..3).each do |index|
+    scanline = thumbnail.scanline(index)
+    scanline.each do |color|
+      set_to_red(color)
+    end
+  end
+
+  # Draw top border 4 pixels tall
+  ((thumbnail.height - 5)..(thumbnail.height - 1)).each do |index|
+    scanline = thumbnail.scanline(index)
+    scanline.each do |color|
+      set_to_red(color)
+    end
+  end
+
+  # We could skip top and bottom 4 scanlines since
+  # already drew them.
+  thumbnail.height.each do |index|
+    scanline = thumbnail.scanline(index)
+    # Draw left and right borders 4 pixels wide
+    (0..4).each do |index|
+      set_to_red(scanline[index])
+    end
+
+    ((thumbnail.width - 5)..(thumbnail.width - 1)).each do |index|
+      set_to_red(scanline[index])
+    end
+  end
+
+  thumbnail.save("images/lena_thumbnail_border_scanline.png", :png)
+
 ThumbnailBorderScanline[link:cookbook/lena_thumbnail_border_scanline.png]