axon 0.0.2 → 0.1.0

data/lib/axon.rb

@@ -1,45 +1,248 @@
-require 'axon/axon'
+# :main: README.rdoc
 
-require 'axon/solid'
+require 'axon/axon'
 require 'axon/cropper'
-require 'axon/scaler'
-require 'axon/nearest_neighbor_scaler'
-require 'axon/bilinear_scaler'
 require 'axon/fit'
-
-require 'axon/jpeg_writer'
-require 'axon/png_writer'
+require 'axon/scalers'
+require 'axon/generators'
 
 module Axon
-  VERSION = '0.0.2'
+  VERSION = '0.1.0'
 
-  def self.JPEG(thing, markers=nil)
-    if thing.respond_to? :read
-      io = thing
-      rewind_after_scanlines = false
-    elsif thing[0, 1] == "\xFF"
-      io = StringIO.new(thing)
-      rewind_after_scanlines = true
-    else
-      io = File.open(thing)
-      rewind_after_scanlines = true
-    end
+  # :call-seq:
+  #   Axon.jpeg(thing [, markers]) -> image
+  #
+  # Reads a compressed JPEG image from +thing+. +thing+ can be an IO object or
+  # a string of JPEG data.
+  #
+  # +markers+ should be an array of valid JPEG header marker symbols. Valid
+  # symbols are :APP0 through :APP15 and :COM.
+  #
+  # If performance is important and you don't care about any markers, you can
+  # avaoid reading any header markers by supplying an empty array for +markers+.
+  #
+  # When +markers+ is not given, all known JPEG markers will be read.
+  #
+  #   io_in = File.open("image.jpg", "r")
+  #   image = Axon.jpeg(io_in)         # Read JPEG from a StringIO
+  #
+  #   jpeg_data = IO.read("image.jpg")
+  #   image_2 = Axon.jpeg(jpeg_data)   # Read JPEG from image data
+  #
+  #   io_in = File.open("image.jpg", "r")
+  #   image_3 = Axon.jpeg(io_in, [:APP2]) # Only reads the APP2 marker
+  #
+  def self.jpeg(thing, *args)
+    thing = StringIO.new(thing) unless thing.respond_to?(:read)
+    reader = JPEG::Reader.new(thing, *args)
+    Image.new(reader)
+  end
 
-    JPEGReader.new(io, markers, rewind_after_scanlines)
+  # :call-seq:
+  #   Axon.png(thing) -> image
+  #
+  # Reads a compressed PNG image from +thing+. +thing+ can be an IO object,
+  # the path to a PNG image, or binary PNG data.
+  #
+  #   io_in = File.open("image.png", "r")
+  #   image = Axon.png(io_in)         # Read PNG from a StringIO
+  #
+  #   png_data = IO.read("image.png")
+  #   image_2 = Axon.png(png_data)    # Read PNG from image data
+  #
+  def self.png(thing)
+    thing = StringIO.new(thing) unless thing.respond_to?(:read)
+    reader = PNG::Reader.new(thing)
+    Image.new(reader)
   end
 
-  def self.PNG(thing)
-    if thing.respond_to? :read
-      io = thing
-      rewind_after_scanlines = false
-    elsif thing[0, 1] == "\x89"
-      io = StringIO.new(thing)
-      rewind_after_scanlines = true
-    else
-      io = File.open(thing)
-      rewind_after_scanlines = true
+  class Image
+    # :call-seq:
+    #   Image.new(image_in)
+    #
+    # Wraps +image_in+ in an easy API.
+    #
+    # Rather than calling Image.new directly, you may want to call Axon.jpeg
+    # or Axon.png.
+    #
+    #   io_in = File.open("image.jpg", "r")
+    #   reader = Axon::JPEG::Reader.new(io_in)
+    #   image = Axon::Image.new(reader)
+    #
+    #   image.fit(10, 20)
+    #   image.height #=> 20 or less
+    #   image.width  #=> 10 or less
+    #
+    #   io_out = File.open("out.jpg", "w")
+    #   image.jpg(io_out) # writes a compressed JPEG file
+    #
+    def initialize(source)
+      @source = source
+      self
+    end
+
+    # :call-seq:
+    #   scale_bilinear(width, height)
+    #
+    # Scales the image using the bilinear interpolation method.
+    #
+    # Bilinear interpolation calculates the color values in the resulting image
+    # by looking at the four nearest pixels for each pixel in the resulting
+    # image.
+    #
+    # This gives a more accurate representation than nearest-neighbor
+    # interpolation, at the expense of slightly blurring the resulting image.
+    #
+    # == Example
+    #
+    #   i = Axon::JPEG('test.jpg')
+    #   i.scale_bilinear(50, 75)
+    #   i.width  # => 50
+    #   i.height # => 75
+    #
+    def scale_bilinear(*args)
+      @source = BilinearScaler.new(@source, *args)
+      self
+    end
+
+    # :call-seq:
+    #   scale_nearest(width, height)
+    #
+    # Scales the image using the nearest-neighbor interpolation method.
+    #
+    # Nearest-neighbor interpolation selects the value of the nearest pixel when
+    # calculating colors in the scaled image.
+    #
+    # == Example
+    #
+    #   i = Axon::JPEG('test.jpg')
+    #   i.scale_nearest(50, 75)
+    #   i.width  # => 50
+    #   i.height # => 75
+    #
+    def scale_nearest(*args)
+      @source = NearestNeighborScaler.new(@source, *args)
+      self
+    end
+
+    # :call-seq:
+    #   fit(width, height)
+    #
+    # Scales the image to fit inside given box dimensions while maintaining the
+    # aspect ratio.
+    #
+    # == Example
+    #
+    #   i = Axon::JPEG('test.jpg')
+    #   i.fit(5, 20)
+    #   i.width  # => 5
+    #   i.height # => 10
+    #
+    def fit(*args)
+      @source = Fit.new(@source, *args)
+      self
+    end
+
+    # :call-seq:
+    #   crop(width, height, x_offset = 0, y_offset = 0)
+    #
+    # Crops the image and extracts regions.
+    #
+    # If the region extends beyond the boundaries of the image then the cropped
+    # image will be truncated at the boundaries.
+    #
+    # == Example
+    #
+    #   i = Axon::JPEG('test.jpg')
+    #   i.crop(50, 75, 10, 20)
+    #   c.width  # => 50
+    #   c.height # => 75
+    #
+    # == Example of Cropping Past the Boundaries
+    #
+    #   i = Axon::JPEG('test.jpg')
+    #   i.crop(50, 75, 60, 20)
+    #   i.width # => 40 # note that this is not 50
+    #
+    def crop(*args)
+      @source = Cropper.new(@source, *args)
+      self
+    end
+
+    # :call-seq:
+    #   jpeg(io_out [, options])
+    #
+    # Writes the image to +io_out+ as compressed JPEG data. Returns the number
+    # of bytes written.
+    #
+    # +options+ may contain the following symbols:
+    #
+    # * :bufsize     -- the maximum size in bytes of the writes that will be
+    #   made to +io_out+
+    # * :quality     -- JPEG quality on a 0..100 scale.
+    # * :exif        -- Raw exif string that will be saved in the header.
+    # * :icc_profile -- Raw ICC profile string that will be saved in the header.
+    #
+    # == Example
+    #
+    #   i = Axon::JPEG('input.jpg')
+    #   io_out = File.open('output.jpg', 'w')
+    #   i.jpeg(io_out, :quality => 88) # writes the image to output.jpg
+    #
+    def jpeg(*args)
+      JPEG.write(@source, *args)
+    end
+
+    # :call-seq:
+    #   png(io_out)
+    #
+    # Writes the image to +io_out+ as compressed PNG data. Returns the number
+    # of bytes written.
+    #
+    # == Example
+    #
+    #   i = Axon::JPEG('input.png')
+    #   io_out = File.open('output.png', 'w')
+    #   i.png(io_out) # writes the image to output.png
+    #
+    def png(*args)
+      PNG.write(@source, *args)
+    end
+
+    # Gets the components in the image.
+    #
+    def components
+      @source.components
+    end
+
+    # Gets the color model of the image.
+    #
+    def color_model
+      @source.color_model
     end
 
-    PNGReader.new(io)
+    # Gets the width of the image.
+    #
+    def width
+      @source.width
+    end
+
+    # Gets the height of the image.
+    #
+    def height
+      @source.height
+    end
+
+    # Gets the index of the next line that will be fetched by gets, starting at
+    # 0.
+    def lineno
+      @source.lineno
+    end
+
+    # Gets the next scanline from the image.
+    #
+    def gets
+      @source.gets
+    end
   end
 end

data/lib/axon/cropper.rb

@@ -1,35 +1,97 @@
 module Axon
+
+  # == An Image Cropper
+  #
+  # Axon::Crop allows you to crop images and extract regions.
+  #
+  # == Example
+  #
+  #   image_in = Axon::Solid.new(100, 200)
+  #   c = Axon::Crop.new(image_in, 50, 75, 10, 20)
+  #   c.width  # => 50
+  #   c.height # => 75
+  #   c.gets   # => String
+  #
+  # == Example of Cropping Past the Boundaries of the Original Image
+  #
+  #   image_in = Axon::Solid.new(100, 200)
+  #   c = Axon::Crop.new(image_in, 50, 75, 60, 20)
+  #   c.width # => 40
+  #
   class Cropper
-    include Enumerable
-    include Image
+    # The index of the next line that will be fetched by gets, starting at 0.
+    attr_reader :lineno
 
-    attr_reader :image, :width, :height, :components, :color_model
+    # :call-seq:
+    #   Cropper.new(image_in, width, height, x_offset = 0, y_offset = 0)
+    #
+    # Crops +image_in+ to the size +width+ x +height+. Optionally, +x_offset+
+    # and +y_offset+ can be used to shift the upper left corner of the cropped
+    # area.
+    #
+    # If the cropped image extends beyond the boundaries of +image_in+ then the
+    # cropped image will be truncated at the boundary.
+    #
+    def initialize(source, width, height, x_offset=nil, y_offset=nil)
+      raise ArgumentError if width < 1 || height < 1
+      raise ArgumentError if x_offset && x_offset < 1 || y_offset && y_offset < 1
 
-    def initialize(image, width, height, x_offset=nil, y_offset=nil)
-      @image = image
+      @source = source
       @width = width
       @height = height
       @x_offset = x_offset || 0
       @y_offset = y_offset || 0
-      @components = image.components
-      @color_model = image.color_model
+      @lineno = 0
     end
 
-    def each
-      sl_width = @width * @components
-      sl_offset = @x_offset * @components
+    # Calculates the height of the cropped image.
+    #
+    def height
+      if @y_offset + @height > @source.height
+        [@source.height - @y_offset, 0].max
+      else
+        @height
+      end
+    end
 
-      @image.each_with_index do |orig_sl, i|
-        next if i < @y_offset
-        yield orig_sl[sl_offset, sl_width]
-        break if i == @height - 1
+    # Calculates the width of the cropped image.
+    #
+    def width
+      if @x_offset + @width > @source.width
+        [@source.width - @x_offset, 0].max
+      else
+        @width
       end
     end
-  end
 
-  module Image
-    def crop(*args)
-      Cropper.new(self, *args)
+    # Gets the components in the cropped image. Same as the components of the
+    # source image.
+    #
+    def components
+      @source.components
+    end
+
+    # Gets the color model of the cropped image. Same as the color model of the
+    # source image.
+    #
+    def color_model
+      @source.color_model
+    end
+
+    # Gets the next scanline from the cropped image.
+    #
+    def gets
+      return nil if @lineno >= height || width < 1 || height < 1
+
+      while @source.lineno < @y_offset
+        break unless @source.gets
+      end
+
+      @lineno += 1
+
+      sl_width = width * components
+      sl_offset = @x_offset * components
+      @source.gets[sl_offset, sl_width]
     end
   end
 end

data/lib/axon/fit.rb

@@ -1,43 +1,99 @@
+require 'axon/scalers'
+
 module Axon
-  class Fit
-    include Image
-    include Enumerable
 
+  # == An Image Box Scaler
+  #
+  # Axon::Fit will scale images to fit inside given box dimensions while
+  # maintaining the aspect ratio.
+  #
+  # == Example
+  #
+  #   image_in = Axon::Solid.new(10, 20)
+  #   f = Axon::Fit.new(image_in, 5, 20)
+  #   f.width  # => 5
+  #   f.height # => 10
+  #
+  class Fit
+    # :call-seq:
+    #   Fit.new(image_in, width, height)
+    #
+    # Fits +image_in+ in the box dimensions given by +width+ and +height+. The
+    # resulting image will not extend beyond the given +width+ or the given
+    # +height+. The resulting image will maintain the aspect ratio of +image_in+
+    # so the resulting image may not completely fill +width+ and +height+.
+    #
+    # The resulting image will match either +width+ or +height+.
+    #
     def initialize(source, width, height)
       @source, @fit_width, @fit_height = source, width, height
+      @scaler = nil
     end
 
+    # Gets the components in the fitted image. Same as the components of the
+    # source image.
+    #
     def components
       @source.components
     end
 
+    # Gets the color model of the fitted image. Same as the color model of the
+    # source image.
+    #
     def color_model
       @source.color_model
     end
 
+    # Gets the width of the fitted image. This will be the given width or less.
+    #
     def width
-      @source.width * calc_fit_ratio
+      @scaler ? @scaler.width : calculate_width
     end
 
+    # Gets the height of the fitted image. This will be the given height or
+    # less.
+    #
     def height
-      @source.height * calc_fit_ratio
+      @scaler ? @scaler.height : calculate_height
+    end
+
+    # Gets the index of the next line that will be fetched by gets, starting at
+    # 0.
+    #
+    def lineno
+      @scaler ? @scaler.lineno : 0
+    end
+
+    # Gets the next scanline from the fitted image.
+    #
+    def gets
+      @scaler ||= get_scaler
+      @scaler.gets
+    end
+
+    private
+
+    def calculate_width
+      (@source.width * calc_fit_ratio).to_i
+    end
+
+    def calculate_height
+      (@source.height * calc_fit_ratio).to_i
     end
 
-    def each
+    def get_scaler
       r = calc_fit_ratio
 
       if r > 1
-        scaler = NearestNeighborScaler.new(@source, r)
-        scaler.each{ |*a| yield(*a) }
+        NearestNeighborScaler.new(@source, width, height)
       elsif r < 1
-        if r <= 0.5 && @source.kind_of?(JPEGReader)
+        if r <= 0.5 && @source.kind_of?(JPEG::Reader)
           @source.scale_denom = calc_jpeg_pre_shrink(r)
           r = calc_fit_ratio
         end
-        scaler = BilinearScaler.new(@source, r)
-        scaler.each{ |*a| yield(*a) }
+        BilinearScaler.new(@source, width, height)
       else
-        @source.each{ |*a| yield(*a) }
+        @source
       end
     end
 
@@ -58,10 +114,4 @@ module Axon
       end
     end
   end
-
-  module Image
-    def fit(*args)
-      Fit.new(self, *args)
-    end
-  end
-end
+end