free-image 0.5.0

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

@@ -0,0 +1,135 @@
+module FreeImage
+  #DLL_API BYTE *DLL_CALLCONV FreeImage_GetBits(FIBITMAP *dib);
+  attach_function('FreeImage_GetBits', [:pointer], :pointer)
+  
+  #DLL_API BYTE *DLL_CALLCONV FreeImage_GetScanLine(FIBITMAP *dib, int scanline);
+  attach_function('FreeImage_GetScanLine', [:pointer, :int], :pointer)
+
+  #DLL_API BOOL DLL_CALLCONV FreeImage_GetPixelIndex(FIBITMAP *dib, unsigned x, unsigned y, BYTE *value);
+  attach_function('FreeImage_GetPixelIndex', [:pointer, :uint, :uint, :pointer], FreeImage::Boolean)
+
+  #DLL_API BOOL DLL_CALLCONV FreeImage_SetPixelIndex(FIBITMAP *dib, unsigned x, unsigned y, BYTE *value);
+  attach_function('FreeImage_SetPixelIndex', [:pointer, :uint, :uint, :pointer], FreeImage::Boolean)
+
+  #DLL_API BOOL DLL_CALLCONV FreeImage_GetPixelColor(FIBITMAP *dib, unsigned x, unsigned y, RGBQUAD *value);
+  attach_function('FreeImage_GetPixelColor', [:pointer, :uint, :uint, :pointer], FreeImage::Boolean)
+
+  #DLL_API BOOL DLL_CALLCONV FreeImage_SetPixelColor(FIBITMAP *dib, unsigned x, unsigned y, RGBQUAD *value);
+  attach_function('FreeImage_SetPixelColor', [:pointer, :uint, :uint, :pointer], FreeImage::Boolean)
+
+  # == Summary
+  # 
+  # The \Pixel module provides methods that allow you to read, write and work pixel-by-pixel
+  # with image data. \FreeImage not only can work with standard bitmap data
+  # (e.g. 1-, 4-, 8-, 16-, 24- and 32-bit) but also with scientific data such as
+  # 16-bit greyscale images, or images made up of long, double or complex values
+  # (often used in signal and image processing algorithms).
+  #
+  # The \FreeImage coordinate system is upside down relative to usual graphics
+  # conventions. Thus, the scanlines are stored upside down, with the first
+  # scan in memory being the bottommost scan in the image.
+  #
+  # For additional information, please refer to the FreeImage::Scanline documentation.
+  #
+  module Pixels
+    # Returns the data-bits of the bitmap. It is up to you to interpret these bytes
+    # correctly, according to the results of Information#bits_per_pixel, Information#red_mask,
+    # Information#green_mask and Information#blue_mask.
+    #
+    # If the bitmap does not contain pixel data (see Information#has_pixels),
+    # nil will be returned.
+    #
+    # For a performance reason, the address returned by FreeImage_GetBits is aligned on
+    # a 16 bytes alignment boundary
+    #
+    def bits
+      ptr = FreeImage.FreeImage_GetBits(self)
+      FreeImage.check_last_error
+      ptr.read_string
+    end
+
+    # Returns the requested row of image data as a FreeImage::Scanline instance.
+    #
+    # If the bitmap does not contain pixel data (see Information#has_pixels),
+    # nil will be returned.
+    def scanline(index)
+      unless (0...self.height).include?(index)
+        raise(RangeError, "Index must be between 0 and #{self.height - 1}")
+      end
+      ptr = FreeImage.FreeImage_GetScanLine(self, index)
+      FreeImage.check_last_error
+
+      ptr ? Scanline.new(self, index, ptr) : nil
+    end
+
+    # Gets the pixel index of a palettized image at the specified coordinate.
+    #
+    # == Parameters
+    # x:: The pixel position in horizontal direction
+    # y:: The pixel position in vertical direction.
+    #
+    def pixel_index(x, y)
+      byte_type = FreeImage.find_type(:byte)
+      ptr = FFI::MemoryPointer.new(byte_type)
+      result = FreeImage.FreeImage_GetPixelIndex(self, x, y, ptr)
+      FreeImage.check_last_error
+      return nil unless result
+      
+      data = ptr.read_bytes(byte_type.size)
+      if byte_type.size == 1
+        data.ord
+      else
+        data
+      end
+    end
+
+    # Sets the pixel index of a palettized image at the specified coordinate.
+    #
+    # == Parameters
+    # x:: The pixel position in horizontal direction
+    # y:: The pixel position in vertical direction.
+    #
+    # The function returns true on success and false otherwise.
+    #
+    def set_pixel_index(x, y, index)
+      byte_type = FreeImage.find_type(:byte)
+      ptr = FFI::MemoryPointer.new(byte_type.size)
+      if byte_type.size == 1
+        ptr.put_bytes(0, index.chr, 0, byte_type.size)
+      else
+        ptr.put_bytes(0, index.to_s, 0, byte_type.size)
+      end
+      result = FreeImage.FreeImage_SetPixelIndex(self, x, y, ptr)
+      FreeImage.check_last_error
+      result
+    end
+
+    # Gets the pixel color of a 16-, 24- or 32-bit image at the specified coordinate.
+    #
+    # == Parameters
+    # x:: The pixel position in horizontal direction
+    # y:: The pixel position in vertical direction.
+    #
+    def pixel_color(x, y)
+      color = RGBQuad.new
+      result = FreeImage.FreeImage_GetPixelColor(self, x, y, color)
+      FreeImage.check_last_error
+      result ? color : nil
+    end
+
+    # Sets the pixel color of a 16-, 24- or 32-bit image at the specified coordinate.
+    #
+    # == Parameters
+    # x:: The pixel position in horizontal direction
+    # y:: The pixel position in vertical direction.
+    # color:: The new color as a RGBAQuad instance.
+    #
+    # The function returns true on success and false otherwise.
+    #
+    def set_pixel_color(x, y, color)
+      result = FreeImage.FreeImage_SetPixelColor(self, x, y, color)
+      FreeImage.check_last_error
+      result
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+module FreeImage
+  # DLL_API FIBITMAP *DLL_CALLCONV FreeImage_Rotate(FIBITMAP *dib, double angle, const void *bkcolor FI_DEFAULT(NULL));
+  attach_function('FreeImage_Rotate', [:pointer, :double, :pointer], :pointer)
+    
+  # DLL_API FIBITMAP *DLL_CALLCONV FreeImage_RotateEx(FIBITMAP *dib, double angle, double x_shift, double y_shift, double x_origin, double y_origin, BOOL use_mask);
+  attach_function('FreeImage_RotateEx', [:pointer, :double, :double, :double, :double, :double, FreeImage::Boolean], :pointer)
+
+  # DLL_API BOOL DLL_CALLCONV FreeImage_FlipHorizontal(FIBITMAP *dib);
+  attach_function('FreeImage_FlipHorizontal', [:pointer], FreeImage::Boolean)
+
+  # DLL_API BOOL DLL_CALLCONV FreeImage_FlipVertical(FIBITMAP *dib);
+  attach_function('FreeImage_FlipVertical', [:pointer], FreeImage::Boolean)
+
+  module Transforms
+    # call-seq:
+    #   bitmap.rotate(angle, bk_color) -> bitmap
+    #
+    # Rotates an image around the center of the image area by means of 3 shears.
+    # The rotated image retains the same size and aspect ratio of source image
+    # (the resulting image size is usually bigger), so that this function should
+    # be used when rotating an image by 90°, 180° or 270°.
+    #
+    # When the angle value isn’t an integer multiple of 90°, the background is
+    # filled with the supplied bkcolor parameter.  When bkcolor is nil, the
+    # default value, the background is filled with a black.
+    #
+    # == Parameters
+    #
+    #  angle::    Specifies the angle of rotation in degrees
+    #  bk_color:: The color used to fill the background.
+    #
+    def rotate(angle, bk_color = nil)
+      ptr = FreeImage.FreeImage_Rotate(self, angle, bk_color)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # call-seq:
+    #   bitmap.rotate_ex(aangle, x_shift, y_shift, x_origin, y_origin, use_mask = false) -> bitmap
+    #
+    # Rotates an image using a 3rd order (cubic) B-Spline. The rotated image will have
+    # the same width and height as the source image, so that this function is better
+    # suited for computer vision and robotics.
+    #
+    # == Parameters:
+    #
+    #  angle::    Specifies the angle of rotation in degrees
+    #  x_shift::  Specifies horizonal image translation
+    #  y_shift::  Specifies vertical image translation
+    #  x_origin:: Specifies the x coordinate of the center of rotation
+    #  y_origin:: Specifies the y coordinate of the center of rotation
+    #  use_mask:: When true, irrelevant parts of the image are set to black,
+    #             otherwise, a mirroring technique is used to fill irrelevant pixels.
+    #
+    def rotate_ex(angle, x_shift, y_shift, x_origin, y_origin, use_mask = false);
+      ptr = FreeImage.FreeImage_RotateEx(self, angle, x_shift, y_shift, x_origin, y_origin, use_mask)
+      FreeImage.check_last_error
+      self.class.new(ptr)
+    end
+
+    # call-seq:
+    #   bitmap.flip_horizontal -> boolean
+    #
+    # Flip the input image horizontally along the vertical axis.
+    #
+    def flip_horizontal!
+      result = FreeImage.FreeImage_FlipHorizontal(self)
+      FreeImage.check_last_error
+      result
+    end
+
+    # call-seq:
+    #   bitmap.flip_vertical -> boolean
+    #
+    # Flip the input image vertically horizontally along the horizontal axis.
+    #
+    def flip_vertical!
+      result = FreeImage.FreeImage_FlipHorizontal(self)
+      FreeImage.check_last_error
+      result
+    end
+  end
+end

data/lib/free-image/palette.rb

@@ -0,0 +1,44 @@
+# encoding: UTF-8
+module FreeImage
+  #DLL_API unsigned DLL_CALLCONV FreeImage_GetColorsUsed(FIBITMAP *dib);
+  attach_function('FreeImage_GetColorsUsed', [:pointer], :ulong)
+
+  #DLL_API RGBQUAD *DLL_CALLCONV FreeImage_GetPalette(FIBITMAP *dib);
+  attach_function('FreeImage_GetPalette', [:pointer], :pointer)
+
+  # Represents a bitmaps palette. If the bitmap doesn’t have a palette (i.e. when
+  # its pixel bit depth is greater than 8), this function returns nil.
+  class Palette
+    include Enumerable
+    
+    def initialize(bitmap)
+      # Keep reference to bitmap so its not gc'ed
+      @bitmap = bitmap
+    end
+
+    # Returns the palette-size for palletised bitmaps, and 0 for high-colour bitmaps.
+    def size
+      result = FreeImage.FreeImage_GetColorsUsed(@bitmap)
+      FreeImage.check_last_error
+      result
+    end
+    alias :colors_used :size
+
+    # Returns the index color as an instance of FreeImage::RGBQuad
+    def [](index)
+      unless (0..self.size).include?(index)
+        raise(RangeError, "Value is out of range 0..#{self.size}. Value: #{index}")
+      end
+
+      ptr = FreeImage.FreeImage_GetPalette(@bitmap)
+      FreeImage.check_last_error
+      RGBQuad.new(ptr[index])
+    end
+
+    def each
+      size.times do |i|
+        yield (self[i])
+      end
+    end
+  end
+end

data/lib/free-image/scanline.rb

@@ -0,0 +1,151 @@
+module FreeImage
+  #DLL_API BYTE *DLL_CALLCONV FreeImage_GetScanLine(FIBITMAP *dib, int scanline);
+  attach_function('FreeImage_GetScanLine', [:pointer, :int], :pointer)
+
+  # == Summary
+  # Scanlines 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. You can
+  # get a scanline via the Freeimage::Pixels#scanline method.
+  #
+  # To understand how scanlines work, you have to first understand that image data
+  # is stored differently depending on the {image type}[FreeImage.image_types]
+  # and the {bits per pixel}[FreeImage::Information#bits_per_pixel].  Thus, when
+  # you call reeImage::Scanline#[] with an index, you will get back a different 
+  # object depending on the image type and bit depth.
+  #
+  # In a :bitmap image, possible bit depths are 1-, 4-, 8-, 16-, 24-, 32-, 48-,
+  # 64-, 96- and 128-bit. 
+  #
+  # * 1-bit DIBs are stored using each bit as an index into the color table. The most
+  #   significant bit is the leftmost pixel. This is not currently supported.
+  # * 4-bit DIBs are stored with each 4 bits representing an index into the color table. The
+  #   most significant nibble is the leftmost pixel.  This is not currently supported.
+  # * 8-bit DIBs are the easiest to store because each byte is an index into the color table.
+  #   This is not currently supported.
+  # * 24-bit DIBs have every 3 bytes representing a color, using the same ordering as the
+  #   RGBTRIPLE structure.  Colors are represented using FreeImage::RGBTriple.
+  # * 32-bit DIB have every 4 bytes representing a color associated to a alpha value (used
+  #   to indicate transparency). Colors are represented using FreeImage::RGBTriple.
+  #
+  # Non standard image types such as short, long, float or double do not have a color
+  # table. Pixels are stored in a similar way as 8-bit DIB.
+  # 
+  # Complex image types are stored in a similar way as 24- or 32bit DIB.  Colors are
+  # represented using FreeImage::Complex.
+  #
+  # 16-bit RGB[A] image types are stored in a similar way as 24-bit
+  # DIBs. Colors are represented using FreeImage::RGB16 or FreeImage::RFBA16.
+  # 
+  # Float RGB[A] image types are stored in a similar way 32bit
+  # DIBs. Colors are represented using FreeImage::RGBF or FreeImage::RFBAF.
+  #
+  class Scanline
+    include Enumerable
+
+    # Creates a new scanline instance
+    #
+    # == Parameters
+    # bitmap:: An instance of FreeImage::Bitmap
+    # index:: The index of the scanline, must be between 0 and the image
+    #         pixel heigh minus one.
+    # ptr:: A pointer to the raw pixel data.
+    #
+    # Generally you do not want to call this method directly.  Instead, use
+    # FreeImage::Bitmap#scanline.
+    #
+    def initialize(bitmap, index, ptr)
+      @bitmap = bitmap
+      @index = index
+      @ptr = ptr
+    end
+
+    # Returns the appropriate color object for the image type and
+    # bit depth.  See notes for the FreeImage::Scanline class.
+    #
+    # == Parameters
+    # index:: The index of the scanline, must be between 0 and the image
+    #         pixel width minus one.
+    #
+    # Returns the appropriate object for manipulating the data.
+    #
+    def [](index)
+      unless (0...pixelsize).include?(index)
+        raise(RangeError, "Index must be between 0 and #{pixelsize - 1}")
+      end
+      bytes_per_pixel = @bitmap.bits_per_pixel/8
+
+      # Now get the address of the pixel
+      address = @ptr.address + (index * bytes_per_pixel)
+
+      # Now get a pointer to the pixel
+      ptr = FFI::Pointer.new(bytes_per_pixel, address)
+
+      # Now return a nice object to work with
+      color_type.new(ptr)
+    end
+
+    # The width of the image in pixels.  Same as FreeImage::Bitmap#width.
+    #
+    def pixelsize
+      @bitmap.width
+    end
+    
+    # The width of the image in bytes.  Same as FreeImage::Bitmap#pitch.
+    #
+    def bytesize
+      @bitmap.pitch
+    end
+
+    # Iterate over each pixel, returning the appropriate object to manipulate
+    # the underlying data.
+    #
+    def each
+      pixelsize.times do |i|
+        yield (self[i])
+      end
+    end
+
+    private
+
+    def color_type
+      case @bitmap.image_type
+      when :bitmap
+        case @bitmap.bits_per_pixel
+        when 24
+          RGBTriple
+        when 32
+          RGBQuad
+        else
+          raise(ArgumentError, "Not Supported")
+        end
+      when :uint16
+        FFI::UINT16
+      when :int16
+        FFI::INT16
+      when :uint32
+        FFI::UINT32
+      when :int32
+        FFI::INT16
+      when :float
+        FFI::FLOAT
+      when :double
+        FFI::DOUBLE
+      when :complex
+        Complex
+      when :rgb16
+        RGB16
+      when :rgba16
+        RGBA16
+      when :rgbf
+        RGBF
+      when :rgbaf
+        RGBAF
+      else
+        raise(ArgumentError, "Not Supported")
+      end
+    end
+  end
+end

data/lib/free-image/sources/abstract_source.rb

@@ -0,0 +1,172 @@
+module FreeImage
+  # == Summary
+  #
+  # FreeImage can load images from a variety of files,
+  # memory or streams.  For additional details please see:
+  #
+  # FreeImage::File::    Use to load images from files
+  # FreeImage::Memory::  Use to load images from byte strings
+  # FreeImage::IO::    Use to load images from io streams
+  #
+  class AbstractSource
+    # The Decoder module defines various constants that
+    # control how various image formats are loaded.
+    module Decoder
+      # Load the image header only (not supported by all plugins)
+      FIF_LOADNOPIXELS = 0x8000
+      GIF_DEFAULT = 0x0
+      # Load the image as a 256 color image with ununsed palette entries, if it's 16 or 2 color
+      GIF_LOAD256 = 0x1
+      # 'Play' the GIF to generate each frame (as 32bpp) instead of returning raw frame data when loading
+      GIF_PLAYBACK = 0x2
+      ICO_DEFAULT = 0x0
+      # Loading (see JPEG_FAST); saving (see JPEG_QUALITYGOOD|JPEG_SUBSAMPLING_420)
+      JPEG_DEFAULT = 0x0
+      # Load the file as fast as possible, sacrificing some quality
+      JPEG_FAST = 0x1
+      # Load the file with the best quality, sacrificing some speed
+      JPEG_ACCURATE = 0x2
+      # Load separated CMYK "as is" (use | to combine with other load flags)
+      JPEG_CMYK = 0x4
+      # Load and rotate according to Exif 'Orientation' tag if available
+      JPEG_EXIFROTATE =0x8
+      PCD_DEFAULT = 0x0
+      # Load the bitmap sized 768 x 512
+      PCD_BASE = 0x1
+      # Load the bitmap sized 384 x 256
+      PCD_BASEDIV4 = 0x2
+      # Load the bitmap sized 192 x 128
+      PCD_BASEDIV16 = 0x3
+      # Loading: avoid gamma correction
+      PNG_IGNOREGAMMA	= 0x1
+      PSD_DEFAULT = 0x0
+      # Reads tags for separated CMYK (default is conversion to RGB)
+      PSD_CMYK = 0x1
+      # Reads tags for CIELab (default is conversion to RGB)
+      PSD_LAB = 0x2
+      # Load the file as linear RGB 48-bit
+      RAW_DEFAULT = 0x0
+      # Try to load the embedded JPEG preview with included Exif Data or default to RGB 24-bit
+      RAW_PREVIEW = 0x1
+      # Load the file as RGB 24-bit
+      RAW_DISPLAY = 0x2
+      # Output a half-size color image
+      RAW_HALFSIZE = 0x4
+      # If set the loader converts RGB555 and ARGB8888 -> RGB888.
+      TARGA_LOAD_RGB888 = 0x1
+      # Reads/stores tags for separated CMYK (use | to combine with compression flags)
+      TIFF_CMYK = 0x1
+    end
+
+    # The Encoder module defines various constants that
+    # control how various image formats are saved.
+    module Encoder
+      BMP_DEFAULT = 0x0
+      BMP_SAVE_RLE = 0x1
+      # Save data as half with piz-based wavelet compression
+      EXR_DEFAULT = 0x0
+      # Save data as float instead of as half (not recommended)
+      EXR_FLOAT = 0x0001
+      # Save with no compression
+      EXR_NONE = 0x0002
+      # Save with zlib compression, in blocks of 16 scan lines
+      EXR_ZIP	 = 0x0004
+      # Save with piz-based wavelet compression
+      EXR_PIZ	 = 0x0008
+      # Save with lossy 24-bit float compression
+      EXR_PXR24 = 0x0010
+      # Save with lossy 44% float compression - goes to 22% when combined with EXR_LC
+      EXR_B44 = 0x0020
+      # Save images with one luminance and two chroma channels, rather than as RGB (lossy compression)
+      EXR_LC = 0x0040
+      # Save with a 16:1 rate
+      J2K_DEFAULT =	0x0
+      # Save with a 16:1 rate
+      JP2_DEFAULT =	0x0
+      # Loading (see JPEG_FAST); saving (see JPEG_QUALITYGOOD|JPEG_SUBSAMPLING_420)
+      JPEG_DEFAULT = 0x0
+      # Save with superb quality (100:1)
+      JPEG_QUALITYSUPERB = 0x80
+      # Save with good quality (75:1)
+      JPEG_QUALITYGOOD = 0x0100
+      # Save with normal quality (50:1)
+      JPEG_QUALITYNORMAL = 0x0200
+      # Save with average quality (25:1)
+      JPEG_QUALITYAVERAGE = 0x0400
+      # Save with bad quality (10:1)
+      JPEG_QUALITYBAD = 0x0800
+      # Save as a progressive-JPEG (use | to combine with other save flags)
+      JPEG_PROGRESSIVE = 0x2000
+      # Save with high 4x1 chroma subsampling (4:1:1)
+      JPEG_SUBSAMPLING_411 = 0x1000
+      # Save with medium 2x2 medium chroma subsampling (4:2:0) - default value
+      JPEG_SUBSAMPLING_420 = 0x4000
+      # Save with low 2x1 chroma subsampling (4:2:2)
+      JPEG_SUBSAMPLING_422 = 0x8000
+      # Save with no chroma subsampling (4:4:4)
+      JPEG_SUBSAMPLING_444 = 0x10000
+      # On saving, compute optimal Huffman coding tables (can reduce a few percent of file size)
+      JPEG_OPTIMIZE = 0x20000
+      # Save basic JPEG, without metadata or any markers
+      JPEG_BASELINE = 0x40000
+      PNG_DEFAULT = 0x0
+      # Save using ZLib level 1 compression flag (default value is 6)
+      PNG_Z_BEST_SPEED = 0x0001
+      # Save using ZLib level 6 compression flag (default recommended value)
+      PNG_Z_DEFAULT_COMPRESSION = 0x0006
+      # Save using ZLib level 9 compression flag (default value is 6)
+      PNG_Z_BEST_COMPRESSION = 0x0009
+      # Save without ZLib compression
+      PNG_Z_NO_COMPRESSION = 0x0100
+      # Save using Adam7 interlacing (use | to combine with other save flags)
+      PNG_INTERLACED = 0x0200
+      PNM_DEFAULT = 0x0
+      # If set the writer saves in RAW format (i.e. P4, P5 or P6)
+      PNM_SAVE_RAW = 0x0
+      # If set the writer saves in ASCII format (i.e. P1, P2 or P3)
+      PNM_SAVE_ASCII = 0x1
+      TARGA_DEFAULT = 0x0
+      # If set, the writer saves with RLE compression
+      TARGA_SAVE_RLE = 0x2
+      TIFF_DEFAULT = 0x0
+      # Reads/stores tags for separated CMYK (use | to combine with compression flags)
+      TIFF_CMYK = 0x0001
+      # Save using PACKBITS compression
+      TIFF_PACKBITS = 0x0100
+      # Save using DEFLATE compression (a.k.a. ZLIB compression)
+      TIFF_DEFLATE = 0x0200
+      # Save using ADOBE DEFLATE compression
+      TIFF_ADOBE_DEFLATE = 0x0400
+      # Save without any compression
+      TIFF_NONE = 0x0800
+      # Save using CCITT Group 3 fax encoding
+      TIFF_CCITTFAX3 = 0x1000
+      # Save using CCITT Group 4 fax encoding
+      TIFF_CCITTFAX4 = 0x2000
+      # Save using LZW compression
+      TIFF_LZW = 0x4000
+      # Save using JPEG compression
+      TIFF_JPEG = 0x8000
+      # Save using LogLuv compression
+      TIFF_LOGLUV = 0x10000
+    end
+    
+    # :nodoc: - This method is documented on subclasses
+    def open(format = nil, flags = 0)
+      format ||= self.format
+
+      # Do we know the format?
+      if format == :unknown
+        raise(Error.new(:unknown, "Cannot load :unknown image format"))
+      end
+
+      # Can we load the image?
+      unless FreeImage.FreeImage_FIFSupportsReading(format)
+        raise(Error.new("Cannot load image"))
+      end
+
+      ptr = load(format, flags)
+      Bitmap.new(ptr, self)
+    end
+  end
+end