free-image 0.5.0

data/HISTORY

@@ -0,0 +1,5 @@
+= Release History
+
+== 0.5.0 / 2011-08-28 Charlie Savage
+
+* Initial Commit

data/LICENSE

@@ -0,0 +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
+SOFTWARE.

data/README.rdoc

@@ -0,0 +1,99 @@
+= 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
+Using free-image is easy.  To get you started,  refer to the
+\FreeImage cookbook[rdoc-ref:cookbook.rdoc].
+
+
+== 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 - Not Implemented
+
+== 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

@@ -0,0 +1,47 @@
+# 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

data/cookbook.rdoc

@@ -0,0 +1,239 @@
+= \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 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 or you can call the FreeImage::Bitmap#free method.  Once you do that though,
+remember the image no longer exists and further usage of it will result in
+segmentation faults.
+
+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)
+
+ThumbnailBorderScanline[link:cookbook/lena_thumbnail_border_scanline.png]

data/free-image.gemspec

@@ -0,0 +1,30 @@
+# encoding: utf-8
+
+Gem::Specification.new do |spec|
+  spec.name        = 'free-image'
+  spec.version     = '0.5.0'
+  spec.summary     = 'Ruby Bindings for the Free Image Library'
+  spec.description = <<-EOS
+    FreeImage is an Open Source library project for developers who would like to support
+    popular graphics image formats like PNG, BMP, JPEG, TIFF and others as needed by
+    today's multimedia applications. FreeImage is easy to use, fast, multithreading
+    safe, compatible with all 32-bit or 64-bit versions of Windows, and
+    cross-platform (works both with Linux and Mac OS X).
+  EOS
+  spec.authors = [ 'Charlie Savage']
+  spec.platform = Gem::Platform::RUBY
+  spec.files = Dir.glob(['HISTORY',
+                         'LICENSE',
+                         'free-image.gemspec',
+                         'Rakefile',
+                         '*.rdoc',
+                         'lib/**/*.rb',
+                         'test/**/*'])
+  spec.test_files = Dir.glob("test/test_*.rb")
+  spec.required_ruby_version = '>= 1.8.7'
+  spec.date = Time.now
+
+  spec.add_dependency('ffi', '>=1.0.10')
+  spec.add_development_dependency('hanna-nouveau')
+  spec.add_development_dependency('open4')
+end

data/lib/free-image.rb

@@ -0,0 +1,101 @@
+# encoding: UTF-8
+require 'ffi'
+require 'rbconfig'
+
+module FreeImage
+  def self.msvc?
+    # If this is windows we assume FreeImage was compiled with
+    # MSVC since that is the binary distibution provided on
+    # the web site.  If you have compiled FreeImage yourself
+    # on windows using another compiler, set this to false.
+    #
+    # This is important because FreeImage defines different
+    # type sizes for MSVC - see types/ffi.rb
+    FFI::Platform.windows?
+  end
+
+  def self.search_paths
+    @search_paths ||= begin
+      if ENV['FREE_IMAGE_LIBRARY_PATH']
+        [ ENV['FREE_IMAGE_LIBRARY_PATH'] ]
+      elsif FFI::Platform::IS_WINDOWS
+        ENV['PATH'].split(File::PATH_SEPARATOR)
+      else
+        [ '/usr/local/{lib64,lib32,lib}', '/opt/local/{lib64,lib32,lib}', '/usr/{lib64,lib32,lib}' ]
+      end
+    end
+  end
+
+  def self.find_lib(lib)
+    files = search_paths.inject(Array.new) do |array, path|
+      file_name = File.expand_path(File.join(path, "#{lib}.#{FFI::Platform::LIBSUFFIX}"))
+      array << Dir.glob(file_name)
+      array
+    end
+    files.flatten.compact.first
+  end
+
+  def self.free_image_library_paths
+    @free_image_library_paths ||= begin
+      libs = %w{libfreeimage libfreeimage.3 FreeImaged}
+
+      libs.map do |lib|
+        find_lib(lib)
+      end.compact
+    end
+  end
+
+  extend ::FFI::Library
+
+  if free_image_library_paths.any?
+    ffi_lib(*free_image_library_paths)
+  elsif FFI::Platform.windows?
+    ffi_lib("FreeImaged")
+  else
+    ffi_lib("free_image")
+  end
+
+  ffi_convention :stdcall if FFI::Platform.windows?
+end
+
+
+# Types
+require 'free-image/types/ffi'
+require 'free-image/types/boolean'
+
+# More types
+require 'free-image/types/rgb_triple'
+require 'free-image/types/rgb_quad'
+require 'free-image/types/rgb16'
+require 'free-image/types/rgba16'
+require 'free-image/types/rgbf'
+require 'free-image/types/rgbaf'
+require 'free-image/types/complex'
+
+# Enums
+require 'free-image/enums/color_types'
+require 'free-image/enums/dithers'
+require 'free-image/enums/filters'
+require 'free-image/enums/formats'
+require 'free-image/enums/image_types'
+
+# Sources
+require 'free-image/sources/abstract_source'
+require 'free-image/sources/io'
+require 'free-image/sources/file'
+require 'free-image/sources/memory'
+
+# Modules
+require 'free-image/modules/conversions'
+require 'free-image/modules/helper'
+require 'free-image/modules/icc'
+require 'free-image/modules/information'
+require 'free-image/modules/modify'
+require 'free-image/modules/pixels'
+require 'free-image/modules/transforms'
+
+# Main classes
+require 'free-image/errors'
+require 'free-image/palette'
+require 'free-image/scanline'
+require 'free-image/bitmap'