chunky_png 1.0.0.beta2 → 1.0.0.rc1

data/lib/chunky_png/canvas/resampling.rb

@@ -0,0 +1,42 @@
+module ChunkyPNG
+  class Canvas
+    
+    # The ChunkyPNG::Canvas::Resampling module defines methods to perform image resampling to 
+    # a {ChunkyPNG::Canvas}.
+    #
+    # Currently, only the nearest neighbor algorithm is implemented. Bilinear and cubic
+    # algorithms may be added later on.
+    #
+    # @see ChunkyPNG::Canvas
+    module Resampling
+      
+      # Resamples the canvas.
+      # @param [Integer] new_width The width of the resamples canvas.
+      # @param [Integer] new_height The height of the resamples canvas.
+      # @param [ChunkyPNG::Canvas] A new canvas instance with the resamples pixels.
+      def resample_nearest_neighbor(new_width, new_height)
+        
+        resampled_image = self.class.new(new_width.to_i, new_height.to_i)
+        
+        width_ratio  = width.to_f / new_width.to_f
+        height_ratio = height.to_f / new_height.to_f
+
+        for y in 1..new_height do
+          source_y   = (y - 0.5) * height_ratio + 0.5
+          input_y    = source_y.to_i
+
+          for x in 1..new_width do
+            source_x = (x - 0.5) * width_ratio + 0.5
+            input_x  = source_x.to_i
+
+            resampled_image.set_pixel(x - 1, y - 1, get_pixel([input_x - 1, 0].max, [input_y - 1, 0].max))
+          end
+        end
+        
+        return resampled_image
+      end
+      
+      alias_method :resample, :resample_nearest_neighbor
+    end
+  end
+end

data/lib/chunky_png/color.rb

@@ -1,4 +1,48 @@
 module ChunkyPNG
+  
+  # Factory method to return a color value, based on the arguments given.
+  #
+  # - When given 1 argument, it can either be a color integer, which is returned as is,
+  #   or it can be a HTML named color or a color in hex notation.
+  # - When given 2 arguments, the 1st argument is parsed as color value and the second
+  #   argument is used as opacity value (range: 0-255)
+  #
+  # @overload Color(r, g, b, a)
+  #   @param (see ChunkyPNG::Color.rgba)
+  #   @return [Integer] The rgba color value.
+  #
+  # @overload Color(r, g, b)
+  #   @param (see ChunkyPNG::Color.rgb)
+  #   @return [Integer] The rgb color value.
+  #
+  # @overload Color(hex_value, opacity = nil)
+  #   @param (see ChunkyPNG::Color.from_hex)
+  #   @return [Integer] The hex color value, with the opacity applied if one was given.
+  #
+  # @overload Color(color_name, opacity = nil)
+  #   @param (see ChunkyPNG::Color.html_color)
+  #   @return [Integer] The hex color value, with the opacity applied if one was given.
+  #
+  # @overload Color(color_value, opacity = nil)
+  #   @param [Integer, :to_i] The color value.
+  #   @return [Integer] The color value, with the opacity applied if one was given.
+  #
+  # @raise [ChunkyPNG::ExpectationFailed] if the arguments weren't understood as a color.
+  def self.Color(*args)
+    case args.length
+      when 4; ChunkyPNG::Color.rgba(*args)
+      when 3; ChunkyPNG::Color.rgb(*args)
+      when 2; (ChunkyPNG::Color(args[0]) & 0xffffff00) | args[1].to_i
+      when 1
+        case source = args.first.to_s
+          when Integer, /^\d+$/; source.to_i
+          when ChunkyPNG::Color::HEX_COLOR_REGEXP;  ChunkyPNG::Color.from_hex(source)
+          when ChunkyPNG::Color::HTML_COLOR_REGEXP; ChunkyPNG::Color.html_color(source)
+          else raise ChunkyPNG::ExpectationFailed; "Don't know how to create a color from #{source.inspect}!"
+        end
+      else raise ChunkyPNG::ExpectationFailed; "Don't know how to create a color from #{args.inspect}!"
+    end
+  end
 
   # The Color module defines methods for handling colors. Within the ChunkyPNG
   # library, the concepts of pixels and colors are both used, and they are
@@ -16,32 +60,48 @@ module ChunkyPNG
   module Color
     extend self
 
-    # The maximum value of each color component.
+    # @return [Integer] The maximum value of each color component.
     MAX = 0xff
-
+    
+    # @return [Regexp] The regexp to parse hex color values.
+    HEX_COLOR_REGEXP  = /^(?:#|0x)?([0-9a-f]{6})([0-9a-f]{2})?$/i
+    
+    # @return [Regexp] The regexp to parse named color values.
+    HTML_COLOR_REGEXP = /^([a-z][a-z_ ]+[a-z])(?:\ ?\@\ ?(1\.0|0\.\d+))?$/i
+    
     ####################################################################
     # CONSTRUCTING COLOR VALUES
     ####################################################################
 
     # Creates a new color using an r, g, b triple and an alpha value.
+    # @param [Integer] r The r-component (0-255)
+    # @param [Integer] g The r-component (0-255)
+    # @param [Integer] b The r-component (0-255)
+    # @param [Integer] a The opacity (0-255)
     # @return [Integer] The newly constructed color value.
     def rgba(r, g, b, a)
       r << 24 | g << 16 | b << 8 | a
     end
 
     # Creates a new color using an r, g, b triple.
+    # @param [Integer] r The r-component (0-255)
+    # @param [Integer] g The r-component (0-255)
+    # @param [Integer] b The r-component (0-255)
     # @return [Integer] The newly constructed color value.
     def rgb(r, g, b)
       r << 24 | g << 16 | b << 8 | 0xff
     end
 
     # Creates a new color using a grayscale teint.
+    # @param [Integer] teint The grayscale teint (0-255), will be used as r, g, and b value.
     # @return [ChunkyPNG::Color] The newly constructed color value.
     def grayscale(teint)
       teint << 24 | teint << 16 | teint << 8 | 0xff
     end
 
     # Creates a new color using a grayscale teint and alpha value.
+    # @param [Integer] teint The grayscale teint (0-255), will be used as r, g, and b value.
+    # @param [Integer] a The opacity (0-255)
     # @return [Integer] The newly constructed color value.
     def grayscale_alpha(teint, a)
       teint << 24 | teint << 16 | teint << 8 | a
@@ -77,12 +137,17 @@ module ChunkyPNG
     # Color strings may include the prefix "0x" or "#".
     #
     # @param [String] str The color in hex notation. @return [Integer] The
-    # converted color value.
-    def from_hex(str)
-      case str
-        when /^(?:#|0x)?([0-9a-f]{6})$/i; ($1.hex << 8) | 0xff
-        when /^(?:#|0x)?([0-9a-f]{8})$/i; $1.hex
-        else raise ChunkyPNG::ExpectationFailed, "Not a valid hex color notation: #{str.inspect}!"
+    #   converted color value.
+    # @param [Integer] opacity The opacity value for the color. Overrides any
+    #    opacity value given in the hex value if given.
+    # @return [Integer] The color value.
+    def from_hex(hex_value, opacity = nil)
+      if HEX_COLOR_REGEXP =~ hex_value
+        base_color = $1.hex << 8
+        opacity  ||= $2 ? $2.hex : 0xff
+        base_color | opacity
+      else 
+        raise ChunkyPNG::ExpectationFailed, "Not a valid hex color notation: #{hex_value.inspect}!"
       end
     end
 
@@ -373,13 +438,189 @@ module ChunkyPNG
     # COLOR CONSTANTS
     ####################################################################
 
-    # Black pixel/color
+    # @return [Hash<Symbol, Integer>] All the prefined color names in HTML.
+    PREDEFINED_COLORS = {
+      :aliceblue => 0xf0f8ff00,
+      :antiquewhite => 0xfaebd700,
+      :aqua => 0x00ffff00,
+      :aquamarine => 0x7fffd400,
+      :azure => 0xf0ffff00,
+      :beige => 0xf5f5dc00,
+      :bisque => 0xffe4c400,
+      :black => 0x00000000,
+      :blanchedalmond => 0xffebcd00,
+      :blue => 0x0000ff00,
+      :blueviolet => 0x8a2be200,
+      :brown => 0xa52a2a00,
+      :burlywood => 0xdeb88700,
+      :cadetblue => 0x5f9ea000,
+      :chartreuse => 0x7fff0000,
+      :chocolate => 0xd2691e00,
+      :coral => 0xff7f5000,
+      :cornflowerblue => 0x6495ed00,
+      :cornsilk => 0xfff8dc00,
+      :crimson => 0xdc143c00,
+      :cyan => 0x00ffff00,
+      :darkblue => 0x00008b00,
+      :darkcyan => 0x008b8b00,
+      :darkgoldenrod => 0xb8860b00,
+      :darkgray => 0xa9a9a900,
+      :darkgrey => 0xa9a9a900,
+      :darkgreen => 0x00640000,
+      :darkkhaki => 0xbdb76b00,
+      :darkmagenta => 0x8b008b00,
+      :darkolivegreen => 0x556b2f00,
+      :darkorange => 0xff8c0000,
+      :darkorchid => 0x9932cc00,
+      :darkred => 0x8b000000,
+      :darksalmon => 0xe9967a00,
+      :darkseagreen => 0x8fbc8f00,
+      :darkslateblue => 0x483d8b00,
+      :darkslategray => 0x2f4f4f00,
+      :darkslategrey => 0x2f4f4f00,
+      :darkturquoise => 0x00ced100,
+      :darkviolet => 0x9400d300,
+      :deeppink => 0xff149300,
+      :deepskyblue => 0x00bfff00,
+      :dimgray => 0x69696900,
+      :dimgrey => 0x69696900,
+      :dodgerblue => 0x1e90ff00,
+      :firebrick => 0xb2222200,
+      :floralwhite => 0xfffaf000,
+      :forestgreen => 0x228b2200,
+      :fuchsia => 0xff00ff00,
+      :gainsboro => 0xdcdcdc00,
+      :ghostwhite => 0xf8f8ff00,
+      :gold => 0xffd70000,
+      :goldenrod => 0xdaa52000,
+      :gray => 0x80808000,
+      :grey => 0x80808000,
+      :green => 0x00800000,
+      :greenyellow => 0xadff2f00,
+      :honeydew => 0xf0fff000,
+      :hotpink => 0xff69b400,
+      :indianred => 0xcd5c5c00,
+      :indigo => 0x4b008200,
+      :ivory => 0xfffff000,
+      :khaki => 0xf0e68c00,
+      :lavender => 0xe6e6fa00,
+      :lavenderblush => 0xfff0f500,
+      :lawngreen => 0x7cfc0000,
+      :lemonchiffon => 0xfffacd00,
+      :lightblue => 0xadd8e600,
+      :lightcoral => 0xf0808000,
+      :lightcyan => 0xe0ffff00,
+      :lightgoldenrodyellow => 0xfafad200,
+      :lightgray => 0xd3d3d300,
+      :lightgrey => 0xd3d3d300,
+      :lightgreen => 0x90ee9000,
+      :lightpink => 0xffb6c100,
+      :lightsalmon => 0xffa07a00,
+      :lightseagreen => 0x20b2aa00,
+      :lightskyblue => 0x87cefa00,
+      :lightslategray => 0x77889900,
+      :lightslategrey => 0x77889900,
+      :lightsteelblue => 0xb0c4de00,
+      :lightyellow => 0xffffe000,
+      :lime => 0x00ff0000,
+      :limegreen => 0x32cd3200,
+      :linen => 0xfaf0e600,
+      :magenta => 0xff00ff00,
+      :maroon => 0x80000000,
+      :mediumaquamarine => 0x66cdaa00,
+      :mediumblue => 0x0000cd00,
+      :mediumorchid => 0xba55d300,
+      :mediumpurple => 0x9370d800,
+      :mediumseagreen => 0x3cb37100,
+      :mediumslateblue => 0x7b68ee00,
+      :mediumspringgreen => 0x00fa9a00,
+      :mediumturquoise => 0x48d1cc00,
+      :mediumvioletred => 0xc7158500,
+      :midnightblue => 0x19197000,
+      :mintcream => 0xf5fffa00,
+      :mistyrose => 0xffe4e100,
+      :moccasin => 0xffe4b500,
+      :navajowhite => 0xffdead00,
+      :navy => 0x00008000,
+      :oldlace => 0xfdf5e600,
+      :olive => 0x80800000,
+      :olivedrab => 0x6b8e2300,
+      :orange => 0xffa50000,
+      :orangered => 0xff450000,
+      :orchid => 0xda70d600,
+      :palegoldenrod => 0xeee8aa00,
+      :palegreen => 0x98fb9800,
+      :paleturquoise => 0xafeeee00,
+      :palevioletred => 0xd8709300,
+      :papayawhip => 0xffefd500,
+      :peachpuff => 0xffdab900,
+      :peru => 0xcd853f00,
+      :pink => 0xffc0cb00,
+      :plum => 0xdda0dd00,
+      :powderblue => 0xb0e0e600,
+      :purple => 0x80008000,
+      :red => 0xff000000,
+      :rosybrown => 0xbc8f8f00,
+      :royalblue => 0x4169e100,
+      :saddlebrown => 0x8b451300,
+      :salmon => 0xfa807200,
+      :sandybrown => 0xf4a46000,
+      :seagreen => 0x2e8b5700,
+      :seashell => 0xfff5ee00,
+      :sienna => 0xa0522d00,
+      :silver => 0xc0c0c000,
+      :skyblue => 0x87ceeb00,
+      :slateblue => 0x6a5acd00,
+      :slategray => 0x70809000,
+      :slategrey => 0x70809000,
+      :snow => 0xfffafa00,
+      :springgreen => 0x00ff7f00,
+      :steelblue => 0x4682b400,
+      :tan => 0xd2b48c00,
+      :teal => 0x00808000,
+      :thistle => 0xd8bfd800,
+      :tomato => 0xff634700,
+      :turquoise => 0x40e0d000,
+      :violet => 0xee82ee00,
+      :wheat => 0xf5deb300,
+      :white => 0xffffff00,
+      :whitesmoke => 0xf5f5f500,
+      :yellow => 0xffff0000,
+      :yellowgreen => 0x9acd3200
+    }
+    
+    # Gets a color value based on a HTML color name.
+    # 
+    # The color name is flexible. E.g. <tt>'yellowgreen'</tt>, <tt>'Yellow green'</tt>, 
+    # <tt>'YellowGreen'</tt>, <tt>'YELLOW_GREEN'</tt> and <tt>:yellow_green</tt> will
+    # all return the same color value.
+    #
+    # You can include a opacity level in the color name (e.g. <tt>'red @ 0.5'</tt>) or give
+    # an explit opacity value as second argument. If no opacity value is given, the color
+    # will be fully opaque.
+    #
+    # @param [Symbol, String] color_name The color name. It may include an opacity specifier
+    #   like <tt>@ 0.8</tt> to set the color's opacity.
+    # @param [Integer] opacity The opacity value for the color between 0 and 255. Overrides 
+    #   any opacity value given in the color name.
+    # @return [Integer] The color value.
+    # @raise [ChunkyPNG::Exception] If the color name was not recognized.
+    def html_color(color_name, opacity = nil)
+      if color_name.to_s =~ HTML_COLOR_REGEXP
+        opacity ||= $2 ? ($2.to_f * 255.0).round : 0xff
+        base_color_name = $1.gsub(/[^a-z]+/i, '').downcase.to_sym
+        return PREDEFINED_COLORS[base_color_name] | opacity if PREDEFINED_COLORS.has_key?(base_color_name)
+      end
+      raise ChunkyPNG::Exception, "Unknown color name #{color_name}!"
+    end
+
+    # @return [Integer] Black pixel/color
     BLACK = rgb(  0,   0,   0)
 
-    # White pixel/color
+    # @return [Integer] White pixel/color
     WHITE = rgb(255, 255, 255)
 
-    # Fully transparent pixel/color
+    # @return [Integer] Fully transparent pixel/color
     TRANSPARENT = rgba(0, 0, 0, 0)
 
     ####################################################################

data/lib/chunky_png/compatibility.rb

@@ -1,3 +1,4 @@
+# Define the byte-operators on a string if they're not defined (Ruby 1.8)
 
 class String
   alias_method :getbyte, :[]    unless method_defined?(:getbyte)
@@ -5,11 +6,10 @@ class String
   alias_method :bytesize, :size unless method_defined?(:bytesize)
 end
 
-class Object
-  unless method_defined?(:tap)
-    def tap(&block)
-      yield(self) if block_given?
-      return self
+module Enumerable
+  unless method_defined?(:minmax)
+    def minmax
+      [min, max]
     end
   end
 end

data/lib/chunky_png/dimension.rb

@@ -0,0 +1,106 @@
+module ChunkyPNG
+  
+  # Creates a {ChunkyPNG::Dimension} instance using arguments that can be interpreted 
+  # as width and height.
+  # 
+  # @overload Dimension(width, height)
+  #   @param [Integer] width The width-component of the dimension.
+  #   @param [Integer] height The height-component of the dimension.
+  #   @return [ChunkyPNG::Dimension] The instantiated dimension.
+  #
+  # @overload Dimension(string)
+  #   @param [String] string A string from which a width and height value can be parsed, e.g.
+  #      <tt>'10x20'</tt> or <tt>'[10, 20]'</tt>.
+  #   @return [ChunkyPNG::Dimension] The instantiated dimension.
+  #
+  # @overload Dimension(ary)
+  #   @param [Array] ary An array with the desired width as first element and the
+  #      desired height as second element, e.g. <tt>[10, 20]</tt>. 
+  #   @return [ChunkyPNG::Dimension] The instantiated dimension.
+  #
+  # @overload Dimension(hash)
+  #   @param [Hash] hash An hash with a <tt>'height'</tt> or <tt>:height</tt> key for the
+  #      desired height and with a <tt>'width'</tt> or <tt>:width</tt> key for the desired
+  #      width.
+  #   @return [ChunkyPNG::Dimension] The instantiated dimension.
+  #
+  # @see ChunkyPNG::Dimension
+  def self.Dimension(*args)
+
+    case args.length
+      when 2; ChunkyPNG::Dimension.new(*args)
+      when 1; case source = args.first
+          when ChunkyPNG::Dimension; source
+          when ChunkyPNG::Point; ChunkyPNG::Dimension.new(source.x, source.y)
+          when Array; ChunkyPNG::Dimension.new(source[0], source[1])
+          when Hash;  ChunkyPNG::Dimension.new(source[:width] || source['width'], source[:height] || source['height'])
+          when /^[\(\[\{]?(\d+)\s*[x,]?\s*(\d+)[\)\]\}]?$/; ChunkyPNG::Dimension.new($1, $2)
+          else
+            if source.respond_to?(:width) && source.respond_to?(:height)
+              ChunkyPNG::Dimension.new(source.width, source.height)
+            else
+              raise ChunkyPNG::ExpectationFailed, "Don't know how to construct a point from #{source.inspect}!"
+            end
+        end
+      else raise ChunkyPNG::ExpectationFailed, "Don't know how to construct a point from #{args.inspect}!"
+    end
+  end
+  
+  # Class that represents the dimension of something, e.g. a {ChunkyPNG::Canvas}.
+  #
+  # This class contains some methods to simplify performing dimension related checks.
+  class Dimension
+
+    # @return [Integer] The width-compontent of this dimension.
+    attr_accessor :width
+    
+    # @return [Integer] The height-compontent of this dimension.
+    attr_accessor :height
+    
+    # Initializes a new dimension instance.
+    # @param [Integer] width The width-compontent of the new dimension.
+    # @param [Integer] height The height-compontent of the new dimension.
+    def initialize(width, height)
+      @width, @height = width.to_i, height.to_i
+    end
+    
+    # Returns the area of this dimension.
+    # @return [Integer] The area in number of pixels.
+    def area
+      width * height
+    end
+    
+    # Checks whether a point is within bounds of this dimension.
+    # @param [ChunkyPNG::Point, ...] A point-like to bounds-check.
+    # @return [true, false] True iff the the x and y coordinate fall in this dimension.
+    def include?(*point_like)
+      point = ChunkyPNG::Point(*point_like)
+      point.x >= 0 && point.x < width && point.y >= 0 && point.y < height
+    end
+    
+    # Checks whether 2 dimensions are identical.
+    # @param [ChunkyPNG::Dimension] The dimension to compare with.
+    # @return [true, false] <tt>true</tt> iff width and height match.
+    def eql?(other)
+      other.width == width && other.height == height
+    end
+    
+    alias_method :==, :eql?
+    
+    # Compares the size of 2 dimensions.
+    # @param [ChunkyPNG::Dimension] The dimension to compare with.
+    # @return [-1, 0, 1] -1 if the other dimension has a larger area, 1 of this
+    #   dimension is larger, 0 if both are identical in size.
+    def <=>(other)
+      other.area <=> area
+    end
+    
+    # Casts this dimension into an array.
+    # @return [Array<Integer>] <tt>[width, height]</tt> for this dimension.
+    def to_a
+      [width, height]
+    end
+    
+    alias_method :to_ary, :to_a
+  end
+end