free-image 0.5.0

data/lib/free-image/bitmap.rb

@@ -0,0 +1,154 @@
+module FreeImage
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_Allocate(int width, int height, int bpp, unsigned red_mask FI_DEFAULT(0), unsigned green_mask FI_DEFAULT(0), unsigned blue_mask FI_DEFAULT(0));
+  attach_function('FreeImage_Allocate', [:int, :int, :int, :uint, :uint, :uint], :pointer)
+
+  # DLL_API FIBITMAP * DLL_CALLCONV FreeImage_Clone(FIBITMAP *dib);
+  attach_function('FreeImage_Clone', [:pointer], :pointer)
+
+  # DLL_API void DLL_CALLCONV FreeImage_Unload(FIBITMAP *dib);
+  attach_function('FreeImage_Unload', [:pointer], :void)
+
+  # == Summary
+  #
+  # Represents an image that has been loaded into memory.  Once the image is loaded,
+  # you can get
+  # information[rdoc-ref:FreeImage::Information] about it,
+  # convert[rdoc-ref:FreeImage::Conversions] it,
+  # modify[rdoc-ref:FreeImage::Modify] it.
+  # transform[rdoc-ref:FreeImage::Information] it,
+  #
+  # == Usage
+  #
+  #   # Open an image form a file
+  #   image = FreeImage::BitmapFile.open('test/fixtures/lena.png')
+  #
+  #   # Get information about it
+  #   bg = image.background_color
+  #
+  #   # Convert it
+  #   image = image.convert_to_greyscale
+  #
+  #   # Modify it
+  #   image = image.convert_to_greyscale
+  #
+  #   # Transform it
+  #   image = image.rotate(90)
+  #
+  class Bitmap < FFI::AutoPointer
+    include Conversions
+    include ICC
+    include Information
+    include Modify
+    include Pixels
+    include Transforms
+
+    ## The source of the image.  May be a File, in Memory string, IO stream or nil.
+    attr_reader :source
+
+    # Creates a new image with the specified width, height and bits per pixel.
+    #
+    # == Parameters
+    # width:: The width of the new image
+    # height:: The height of the new image
+    # bits_per_pixel:: The size in bits of a pixel
+    # red_mask:: The bit-layout of the red color component in a bitmap
+    # green_mask:P: The bit-layout of the green color component in a bitmap
+    # blue_mask:: The bit-layout of the blue color component in a bitmap
+    #
+    # The last three parameter are used to tell FreeImage the bit-layout of
+    # the color components in the bitmap, e.g. where in a pixel the red,
+    # green and blue components are stored.
+    #
+    # To give you an idea about how to interpret the color masks:
+    # when red_mask is 0xFF000000 this means that the last 8 bits in
+    # one pixel are used for the color red. When green_mask is 0x000000FF, it
+    # means that the first 8 bits in a pixel are used for the color green.
+    #
+    # The new image is initially filled completely with zeroes. Zero in a image
+    # is usually interpreted as black. This means that if your bitmap is palletized
+    # it will contain a completely black palette. You can access, and hence populate
+    # the palette via #palette.
+    #
+    # For 8-bit images, a default greyscale palette will also be created.
+    #
+    def self.create(width, height, bits_per_pixel, red_mask = 0, green_mask = 0, blue_mask = 0)
+      ptr = FreeImage.FreeImage_Allocate(width, height, bits_per_pixel, red_mask, green_mask, blue_mask)
+      FreeImage.check_last_error
+      new(ptr)
+    end
+
+    # Opens a new image from the specified source.
+    #
+    # == Parameters
+    # source:: The source of the image
+    #
+    # The source parameter can be a File, Memory or IO stream.  It can
+    # also be a string which is interpreted as a fully qualified file path.
+    def self.open(source)
+      bitmap = figure_source(source).open
+      unless block_given?
+        bitmap
+      else
+        begin
+          yield bitmap
+        ensure
+          bitmap.free
+        end
+      end
+    end
+
+    # Closes an image and releases its associated memory.  This
+    # is called by the ruby Garbage collector and should not
+    # be called directly.  If you would like to free an image
+    # after using it, please use Bitmap#free.
+    def self.release(ptr) #:nodoc:
+      FreeImage.FreeImage_Unload(ptr)
+    end
+
+    # Creates a new image from a c-pointer an image source.  Generally you
+    # do not want to use this method.  Instead, use Bitmap.open.
+    def initialize(ptr, source = nil)
+      @source = source
+      super(ptr)
+    end
+
+    # Creates an exact copy of the current image.
+    def clone
+      ptr = FreeImage.FreeImage_Clone(self)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Save the image to the specified source.
+    #
+    # == Parameters
+    # dst::     The destination where the image will be saved.
+    # format::  The format[rdoc-ref:FreeImage.formats] to save the image to.
+    # flags::   Format specific flags that control how a bitmap is saved.  These flags are defined
+    #            as constants on the AbstractSource class.  Flags can be combined using
+    #            Ruby's bitwise or operator (|)
+    #
+    def save(source, format, flags = 0)
+      self.class.figure_source(source).save(self, format, flags)
+    end
+
+    private
+
+    def self.figure_source(source)
+      case source
+      when AbstractSource
+        source
+      when ::IO
+        IO.new(source)
+      when String
+        File.new(source)
+      else
+        raise(ArgumentError, "Unknown source type: #{source.class.name}")
+      end
+    end
+
+    def figure_color_klass
+      
+    end
+  end
+end

data/lib/free-image/enums/color_types.rb

@@ -0,0 +1,24 @@
+# encoding: UTF-8
+
+module FreeImage
+  ##
+  # FreeImage supports the following color types:
+  # 
+  # :minis_black:: Monochrome bitmap (1-bit) -> first palette entry is black.
+  #                Palletised bitmap (4 or 8-bit) and single channel non standard bitmap -> the bitmap has a greyscale palette
+  # :minis_white:: Monochrome bitmap (1-bit) -> first palette entry is white.
+  #                Palletised bitmap (4 or 8-bit) and single channel non standard bitmap -> the bitmap has an inverted greyscale palette
+  # :palette::     Palettized bitmap (1, 4 or 8 bit)
+  # :rgb::         High-color bitmap (16, 24 or 32 bit), RGB16 or RGBF
+  # :rgb_alpha::   High-color bitmap with an alpha channel (32 bit bitmap, RGBA16 or RGBAF)
+  # :cmyk::        CMYK bitmap (32 bit only)
+  #
+  # :method: color_types
+  
+  FreeImage.enum :color_type, [:minis_white, 0,
+                               :minis_black, 1,
+                               :rgb, 2,
+                               :palette, 3,
+                               :rgb_alpha, 4,
+                               :cmyk, 5]
+end

data/lib/free-image/enums/dithers.rb

@@ -0,0 +1,24 @@
+#  encoding: UTF-8
+
+module FreeImage
+  ##
+  # FreeImage supports the following dithering algorithms:
+  #
+  # :fs::           Floyd & Steinberg error diffusion algorithm
+  # :bayer4x4::     Bayer ordered dispersed dot dithering (order 2 – 4x4 -dithering matrix)
+  # :bayer8x8::     Bayer ordered dispersed dot dithering (order 3 – 8x8 -dithering matrix)
+  # :bayer16x16::   Bayer ordered dispersed dot dithering (order 4 – 16x16 dithering matrix)
+  # :cluster6x6::   Ordered clustered dot dithering (order 3 - 6x6 matrix)
+  # :cluster8x8::   Ordered clustered dot dithering (order 4 - 8x8 matrix)
+  # :cluster16x16:: Ordered clustered dot dithering (order 8 - 16x16 matrix)
+  #
+  # :method: dithers
+  
+  FreeImage.enum :dither, [:fs, 0,
+                           :bayer4x4, 1,
+                           :bayer8x8, 2,
+                           :cluster6x6, 3,
+                           :cluster8x8, 4,
+                           :cluster16x16, 5,
+                           :bayer16x16, 6]
+end

data/lib/free-image/enums/filters.rb

@@ -0,0 +1,12 @@
+module FreeImage
+  ##
+  #FreeImage supports the following rescaling filters:
+  #
+  # :method: filters
+  enum :filter, [:box, 0,
+                 :bicubic, 1,
+                 :bilinear, 2,
+                 :bspline, 3,
+                 :catmullrom, 4,
+                 :lanczos3, 5]
+end

data/lib/free-image/enums/formats.rb

@@ -0,0 +1,84 @@
+# encoding: UTF-8
+
+module FreeImage
+  ##
+  # FreeImage supports over 30 bitmap types, which are indentified via symbols.
+  # Supported formats include:
+  # 
+  # :bmp:: Windows or OS/2 Bitmap File (*.BMP)
+  # :cut:: Dr. Halo (*.CUT)
+  # :dds:: DirectDraw Surface (*.DDS)
+  # :exr:: ILM OpenEXR (*.EXR)
+  # :faxg3:: Raw Fax format CCITT G3 (*.G3)
+  # :gif:: Graphics Interchange Format (*.GIF)
+  # :hdr:: High Dynamic Range (*.HDR)
+  # :ico:: Windows Icon (*.ICO)
+  # :iff:: Amiga IFF (*.IFF, *.LBM)
+  # :jpeg:: Independent JPEG Group (*.JPG, *.JIF, *.JPEG, *.JPE)
+  # :jng:: JPEG Network Graphics (*.JNG)
+  # :j2k:: JPEG-2000 codestream (*.J2K, *.J2C)
+  # :jp2:: JPEG-2000 File Format (*.JP2)
+  # :koala:: Commodore 64 Koala format (*.KOA)
+  # :lbm:: Amiga IFF (*.IFF, *.LBM)
+  # :mng:: Multiple Network Graphics (*.MNG)
+  # :pbm:: Portable Bitmap (ASCII) (*.PBM)
+  # :pbmraw:: Portable Bitmap (BINARY) (*.PBM)
+  # :pcd:: Kodak PhotoCD (*.PCD)
+  # :pcsx:: Zsoft Paintbrush PCX bitmap format (*.PCX)
+  # :pfm:: Portable Floatmap (*.PFM)
+  # :pgm:: Portable Graymap (ASCII) (*.PGM)
+  # :pgmraw:: Portable Graymap (BINARY) (*.PGM)
+  # :pict:: Macintosh PICT (*.PCT, *.PICT, *.PIC)
+  # :png:: Portable Network Graphics (*.PNG)
+  # :ppm:: Portable Pixelmap (ASCII) (*.PPM)
+  # :ppmraw:: Portable Pixelmap (BINARY) (*.PPM)
+  # :psd:: Adobe Photoshop (*.PSD)
+  # :ras:: Sun Rasterfile (*.RAS)
+  # :raw:: RAW camera image (many extensions)
+  # :sgi:: Silicon Graphics SGI image format (*.SGI)
+  # :targa:: Truevision Targa files (*.TGA, *.TARGA)
+  # :tiff:: Tagged Image File Format (*.TIF, *.TIFF)
+  # :wbmp:: Wireless Bitmap (*.WBMP)
+  # :xbm:: X11 Bitmap Format (*.XBM)
+  # :xpm:: X11 Pitmap Format (*.XPM)
+  #
+  # :method: formats
+  
+  FreeImage.enum :format, [:unknown, -1,
+                           :bmp, 0,
+                           :ico	, 1,
+                           :jpeg, 2,
+                           :jng	, 3,
+                           :koala, 4,
+                           :lbm, 5,
+                           :iff, 5, # Yes this is intentional!
+                           :mng, 6,
+                           :pbm, 7,
+                           :pbmraw, 8,
+                           :pcd, 9,
+                           :pcsx, 10,
+                           :pgm, 11,
+                           :pgmraw, 12,
+                           :png, 13,
+                           :ppm, 14,
+                           :ppmraw, 15,
+                           :ras, 16,
+                           :targa, 17,
+                           :tiff, 18,
+                           :wbmp, 19,
+                           :psd, 20,
+                           :cut, 21,
+                           :xbm, 22,
+                           :xpm, 23,
+                           :dds, 24,
+                           :gif, 25,
+                           :hdr, 26,
+                           :faxg3, 27,
+                           :sgi, 28,
+                           :exr, 29,
+                           :j2k, 30,
+                           :jp2, 31,
+                           :pfm, 32,
+                           :pict, 33,
+                           :raw, 34]
+end

data/lib/free-image/enums/image_types.rb

@@ -0,0 +1,36 @@
+#  encoding: UTF-8
+
+module FreeImage
+  ##
+  # FreeImage supports the following image types:
+  #
+  # :unknown:: Unknown format (returned value only, never use it as input value)
+  # :bitmap:: Standard image: 1-, 4-, 8-, 16-, 24-, 32-bit
+  # :uint16:: Array of unsigned short: unsigned 16-bit
+  # :int16:: Array of short: signed 16-bit
+  # :uint32:: Array of unsigned long: unsigned 32-bit
+  # :int32:: Array of long: signed 32-bit
+  # :float:: Array of float: 32-bit IEEE floating point
+  # :double:: Array of double: 64-bit IEEE floating point
+  # :complex:: Array of FICOMPLEX: 2 x 64-bit IEEE floating point
+  # :rgb16:: 48-bit rgb image: 3 x 16-bit
+  # :rgba16:: 64-bit rgbA image: 4 x 16-bit
+  # :rgbf:: 96-bit rgb float image: 3 x 32-bit IEEE floating point
+  # :rgbaf:: 128-bit rgbA float image: 4 x 32-bit IEEE floating point
+  #
+  # :method: image_types
+  
+  FreeImage.enum :image_type, [:unknown,
+                               :bitmap,
+                               :uint16,
+                               :int16,
+                               :uint32,
+                               :int32,
+                               :float,
+                               :double,
+                               :complex,
+                               :rgb16,
+                               :rgba16,
+                               :rgbf,
+                               :rgbaf]
+end

data/lib/free-image/errors.rb

@@ -0,0 +1,44 @@
+module FreeImage
+  LAST_ERROR = 'free_image_error'
+
+  #typedef void (*FreeImage_OutputMessageFunction)(FREE_IMAGE_FORMAT fif, const char *msg);
+  #typedef void (DLL_CALLCONV *FreeImage_OutputMessageFunctionStdCall)(FREE_IMAGE_FORMAT fif, const char *msg);
+  callback(:output_message_callback, [:format, :pointer], :void)
+
+  if FFI::Platform.windows?
+    #DLL_API void DLL_CALLCONV FreeImage_SetOutputMessageStdCall(FreeImage_OutputMessageFunctionStdCall omf);
+    attach_function('FreeImage_SetOutputMessage', 'FreeImage_SetOutputMessageStdCall', [:output_message_callback], :void)
+  else
+    #DLL_API void DLL_CALLCONV FreeImage_SetOutputMessage(FreeImage_OutputMessageFunction omf);
+    attach_function('FreeImage_SetOutputMessage', [:output_message_callback], :void)
+  end
+
+  class Error < StandardError
+    attr_reader :format
+
+    def initialize(format, message)
+      @format = format
+      super(message)
+    end
+
+#    def to_s
+#      "#{self.message}  Format: #{self.format}"
+#    end
+  end
+
+  CALLBACK = Proc.new do |format, ptr|
+    # Create an exception object and stash it away.  We can't raise it here
+    # because FreeImage won't be able to clean up any resources it needs to.
+    # Instead, the calling code must call check_last_error.
+    message = ptr.get_string(0)
+    Thread.current[LAST_ERROR] = Error.new(format, message)
+  end
+  FreeImage_SetOutputMessage(CALLBACK)
+
+  def check_last_error
+    error = Thread.current[LAST_ERROR]
+    Thread.current[LAST_ERROR] = nil
+    raise(error) if error
+  end
+  module_function :check_last_error
+end

data/lib/free-image/modules/conversions.rb

@@ -0,0 +1,166 @@
+module FreeImage
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_ConvertTo4Bits(FIBITMAP *dib);
+  attach_function('FreeImage_ConvertTo4Bits', [:pointer], :pointer)
+
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_ConvertTo8Bits(FIBITMAP *dib);
+  attach_function('FreeImage_ConvertTo8Bits', [:pointer], :pointer)
+
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_ConvertToGreyscale(FIBITMAP *dib);
+  attach_function('FreeImage_ConvertToGreyscale', [:pointer], :pointer)
+
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_ConvertTo16Bits555(FIBITMAP *dib);
+  attach_function('FreeImage_ConvertTo16Bits555', [:pointer], :pointer)
+
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_ConvertTo16Bits565(FIBITMAP *dib);
+  attach_function('FreeImage_ConvertTo16Bits565', [:pointer], :pointer)
+
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_ConvertTo24Bits(FIBITMAP *dib);
+  attach_function('FreeImage_ConvertTo24Bits', [:pointer], :pointer)
+
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_ConvertTo32Bits(FIBITMAP *dib);
+  attach_function('FreeImage_ConvertTo32Bits', [:pointer], :pointer)
+
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_Dither(FIBITMAP *dib, FREE_IMAGE_DITHER algorithm);
+  attach_function('FreeImage_Dither', [:pointer, :dither], :pointer)
+
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_Threshold(FIBITMAP *dib, BYTE T);
+  attach_function('FreeImage_Threshold', [:pointer, :byte], :pointer)
+
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_ConvertToStandardType(FIBITMAP *src, BOOL scale_linear FI_DEFAULT(TRUE));
+  attach_function('FreeImage_ConvertToStandardType', [:pointer, FreeImage::Boolean], :pointer)
+
+  #DLL_API FIBITMAP *DLL_CALLCONV FreeImage_ConvertToType(FIBITMAP *src, FREE_IMAGE_TYPE dst_type, BOOL scale_linear FI_DEFAULT(TRUE));
+  attach_function('FreeImage_ConvertToType', [:pointer, :image_type, FreeImage::Boolean], :pointer)
+
+  module Conversions
+    # Converts a bitmap to 4 bits. If the bitmap is a high-color (16, 24 or 32-bit),
+    # monochrome or greyscale bitmap (1 or 8-bit) the end result will be a greyscale bitmap.
+    # A 1-bit bitmap will become a palletized bitmap. 
+    # 
+    # Note that "greyscale" means that the resulting bitmap will have grey colors,
+    # but the palette won't be a linear greyscale palette. Thus, FreeImage::Bitmap.color_type
+    # will return a :palette.
+    def convert_to_4bits
+      ptr = FreeImage.FreeImage_ConvertTo4Bits(self)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Converts a bitmap to 8 bits. If the bitmap is a high-color (16, 24 or 32-bit),
+    # monochrome or greyscale bitmap (1 or 4-bit) the end result will be a greyscale bitmap.
+    # A 1-bit or 4-bit bitmap will become a palletized bitmap.
+    #
+    # For 16-bit greyscale images (images whose type is :uint16), conversion is done by
+    # dividing the 16-bit channel by 256 (see also FreeImage::Bitmap.ConvertToStandardType).
+    # A nil value is returned for other non-standard bitmap types.
+    def convert_to_8bits
+      ptr = FreeImage.FreeImage_ConvertTo8Bits(self)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Converts a bitmap to a 8-bit greyscale image with a linear ramp. Contrary to
+    # the FreeImage::Conversions#convert_to_8bits function, 1-, 4- and 8-bit palletized
+    # bitmaps are correctly converted, as well as images with a :minis_white color type.
+    def convert_to_greyscale
+      ptr = FreeImage.FreeImage_ConvertToGreyscale(self)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Converts a bitmap to 16 bits, where each pixel has a color pattern of
+    # 5 bits red, 5 bits green and 5 bits blue. One bit in each pixel is
+    # unused.
+    def convert_to_16bits_555
+      ptr = FreeImage.FreeImage_ConvertTo16Bits555(self)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Converts a bitmap to 16 bits, where each pixel has a color pattern of
+    # 5 bits red, 6 bits green and 5 bits blue. One bit in each pixel is
+    # unused.
+    def convert_to_16bits_565
+      ptr = FreeImage.FreeImage_ConvertTo16Bits565(self)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Converts a bitmap to 24 bits. For 48-bit RGB images, conversion is done
+    # by dividing each 16-bit channel by 256. A nil value is returned for
+    # other non-standard bitmap types.
+    def convert_to_24bits
+      ptr = FreeImage.FreeImage_ConvertTo24Bits(self)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Converts a bitmap to 32 bits. For 48-bit RGB images, conversion is done
+    # by dividing each 16-bit channel by 256 and by setting the alpha channel
+    # to an opaque value (0xFF). For 64-bit RGBA images, conversion is done
+    # by dividing each 16-bit channel by 256. A nil value is returned for
+    # other non-standard bitmap types.
+    def convert_to_32bits
+      ptr = FreeImage.FreeImage_ConvertTo32Bits(self)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Converts a non standard image whose color type is :minis_black to a
+    # standard 8-bit greyscale image.  When the scale_linear parameter is
+    # true, conversion is done by scaling linearly each pixel value from [min, max]
+    # to an integer value between [0..255], where min and max are the minimum
+    # and maximum pixel values in the image. When scale_linear is false, conversion
+    # is done by rounding each pixel value to an integer between [0..255]. Rounding
+    # is done using the following formula:
+    #
+    #  dst_pixel = (BYTE) MIN(255, MAX(0, q)) where int q = int(src_pixel + 0.5)
+    #
+    # For standard bitmaps, a clone of the original bitmap is returned.
+    # For complex images, the magnitude is extracted as a double image and then converted
+    # according to the scale parameter.
+    def convert_to_standard_type(scale_linear = true)
+      ptr = FreeImage.FreeImage_ConvertToStandardType(self, scale_linear)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Converts a bitmap to the specified destination image type.  When the image_type
+    # is equal to :bitmap, the function calls FreeImage::Converstions#convert_to_standard_type.
+    # Otherwise, conversion is done using standard C language casting conventions. When
+    # a conversion is not allowed, a nil value is returned and an error is thrown.
+    # Please refer to the FreeImage documentation for allowed conversions.
+    def convert_to_type(dst_image_type, scale_linear = true)
+      ptr = FreeImage.FreeImage_ConvertToType(self, dst_image_type, scale_linear)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Converts a bitmap to 1-bit monochrome bitmap using the specified
+    # {dithering}[rdoc-ref:FreeImage.dithers] algorithm. For 1-bit input
+    # bitmaps, the function clones the input bitmap and builds a
+    # monochrome palette.  Otherwise the function first converts the
+    # bitmap to a 8-bit greyscale bitmap.
+    def dither(algorithm)
+      ptr = FreeImage.FreeImage_Dither(self, algorithm)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # Converts a bitmap to 1-bit monochrome bitmap using a threshold value
+    # between 0 and 255.  The function first converts the bitmap to a 8-bit
+    # greyscale bitmap. Then any brightness level that is less than the
+    # threshold is set to zero and any value above is set to 1.
+    # For 1-bit input bitmaps, the function clones the input bitmap and
+    # builds a monochrome palette.
+    def threshold(value)
+      value = Integer(value)
+      unless (0..255).include?(value)
+        raise(RangeError, "Value is out of range 0..255. Value: #{value}")
+      end
+      ptr = FreeImage.FreeImage_Threshold(self, value)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+  end
+end