chunky_png 1.0.0.rc1 → 1.0.0.rc2

data/lib/chunky_png/canvas/resampling.rb

@@ -14,13 +14,14 @@ module ChunkyPNG
       # @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)
+      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
 
+        pixels = []
         for y in 1..new_height do
           source_y   = (y - 0.5) * height_ratio + 0.5
           input_y    = source_y.to_i
@@ -29,14 +30,19 @@ module ChunkyPNG
             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))
+            pixels << get_pixel([input_x - 1, 0].max, [input_y - 1, 0].max)
           end
         end
         
-        return resampled_image
+        replace_canvas!(new_width.to_i, new_height.to_i, pixels)
+      end
+      
+      def resample_nearest_neighbor(new_width, new_height)
+        dup.resample_nearest_neighbor!(new_width, new_height)
       end
       
       alias_method :resample, :resample_nearest_neighbor
+      alias_method :resize, :resample
     end
   end
 end

data/lib/chunky_png/color.rb

@@ -2,11 +2,6 @@ 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.
@@ -27,7 +22,9 @@ module ChunkyPNG
   #   @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.
+  # @return [Integer] The determined color value as RGBA integer.
+  # @raise [ArgumentError] if the arguments weren't understood as a color.
+  # @see ChunkyPNG::Color
   def self.Color(*args)
     case args.length
       when 4; ChunkyPNG::Color.rgba(*args)
@@ -38,9 +35,9 @@ module ChunkyPNG
           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}!"
+          else raise ArgumentError, "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}!"
+      else raise ArgumentError, "Don't know how to create a color from #{args.inspect}!"
     end
   end
 
@@ -63,9 +60,11 @@ module ChunkyPNG
     # @return [Integer] The maximum value of each color component.
     MAX = 0xff
     
+    # @private
     # @return [Regexp] The regexp to parse hex color values.
     HEX_COLOR_REGEXP  = /^(?:#|0x)?([0-9a-f]{6})([0-9a-f]{2})?$/i
-    
+
+    # @private
     # @return [Regexp] The regexp to parse named color values.
     HTML_COLOR_REGEXP = /^([a-z][a-z_ ]+[a-z])(?:\ ?\@\ ?(1\.0|0\.\d+))?$/i
     
@@ -75,8 +74,8 @@ module ChunkyPNG
 
     # 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] g The g-component (0-255)
+    # @param [Integer] b The b-component (0-255)
     # @param [Integer] a The opacity (0-255)
     # @return [Integer] The newly constructed color value.
     def rgba(r, g, b, a)
@@ -85,8 +84,8 @@ module ChunkyPNG
 
     # 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)
+    # @param [Integer] g The g-component (0-255)
+    # @param [Integer] b The b-component (0-255)
     # @return [Integer] The newly constructed color value.
     def rgb(r, g, b)
       r << 24 | g << 16 | b << 8 | 0xff
@@ -94,7 +93,7 @@ module ChunkyPNG
 
     # 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.
+    # @return [Integer] The newly constructed color value.
     def grayscale(teint)
       teint << 24 | teint << 16 | teint << 8 | 0xff
     end
@@ -141,13 +140,14 @@ module ChunkyPNG
     # @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.
+    # @raise [ArgumentError] if the value given is not a hex color notation.
     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}!"
+        raise ArgumentError, "Not a valid hex color notation: #{hex_value.inspect}!"
       end
     end
 
@@ -333,7 +333,7 @@ module ChunkyPNG
     # @param [Integer] mask The opauqe variant of the color that was being composed
     # @param [Integer] bg The background color on which the color was composed.
     # @param [Integer] tolerance The decomposition tolerance level, a value between 0 and 255.
-    # @return [Integer] The decomposed alpha channel value, between 0 and 255.
+    # @return [Boolean] True if the alpha component can be decomposed successfully.
     # @see #decompose_alpha
     def alpha_decomposable?(color, mask, bg, tolerance = 1)
       components = decompose_alpha_components(color, mask, bg)
@@ -360,11 +360,11 @@ module ChunkyPNG
     end
     
     # Decomposes an alpha channel for either the r, g or b color channel.
-    # @param [:r, :g, :b] The channel to decompose the alpha channel from.
+    # @param [:r, :g, :b] channel The channel to decompose the alpha channel from.
     # @param [Integer] color The color that was the result of compositing.
-    # @param [Integer] mask The opauqe variant of the color that was being composed
+    # @param [Integer] mask The opaqe variant of the color that was being composed
     # @param [Integer] bg The background color on which the color was composed.
-    # @param [Integer] The decomposed alpha value for the channel.
+    # @return [Integer] The decomposed alpha value for the channel.
     def decompose_alpha_component(channel, color, mask, bg)
       ((send(channel, bg) - send(channel, color)).to_f / 
           (send(channel, bg) - send(channel, mask)).to_f * MAX).round

data/lib/chunky_png/dimension.rb

@@ -24,6 +24,8 @@ module ChunkyPNG
   #      width.
   #   @return [ChunkyPNG::Dimension] The instantiated dimension.
   #
+  # @return [ChunkyPNG::Dimension] The dimension created by this factory method.
+  # @raise [ArgumentError] If the argument(s) given where not understood as a dimension.
   # @see ChunkyPNG::Dimension
   def self.Dimension(*args)
 
@@ -34,15 +36,15 @@ module ChunkyPNG
           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)
+          when ChunkyPNG::Dimension::DIMENSION_REGEXP; 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}!"
+              raise ArgumentError, "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}!"
+      else raise ArgumentError, "Don't know how to construct a point from #{args.inspect}!"
     end
   end
   
@@ -51,6 +53,10 @@ module ChunkyPNG
   # This class contains some methods to simplify performing dimension related checks.
   class Dimension
 
+    # @return [Regexp] The regexp to parse dimensions from a string.
+    # @private
+    DIMENSION_REGEXP = /^[\(\[\{]?(\d+)\s*[x,]?\s*(\d+)[\)\]\}]?$/
+
     # @return [Integer] The width-compontent of this dimension.
     attr_accessor :width
     
@@ -73,6 +79,7 @@ module ChunkyPNG
     # 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.
+    # @see ChunkyPNG.Point
     def include?(*point_like)
       point = ChunkyPNG::Point(*point_like)
       point.x >= 0 && point.x < width && point.y >= 0 && point.y < height

data/lib/chunky_png/point.rb

@@ -25,7 +25,8 @@ module ChunkyPNG
   #     <tt>'(0 4)'</tt>, <tt>[0,4}'</tt>, etc.
   #   @return [ChunkyPNG::Point] The instantiated point.
   #
-  # @raise [ChunkyPNG::ExpectationFailed] if the arguments weren't understood.
+  # @return [ChunkyPNG::Point]
+  # @raise [ArgumentError] if the arguments weren't understood.
   # @see ChunkyPNG::Point
   def self.Point(*args)
     case args.length
@@ -35,15 +36,15 @@ module ChunkyPNG
           when ChunkyPNG::Dimension; ChunkyPNG::Point.new(source.width, source.height)
           when Array; ChunkyPNG::Point.new(source[0], source[1])
           when Hash; ChunkyPNG::Point.new(source[:x] || source['x'], source[:y] || source['y'])
-          when /^[\(\[\{]?(\d+)\s*[,]?\s*(\d+)[\)\]\}]?$/; ChunkyPNG::Point.new($1.to_i, $2.to_i)
+          when ChunkyPNG::Point::POINT_REGEXP; ChunkyPNG::Point.new($1.to_i, $2.to_i)
           else 
             if source.respond_to?(:x) && source.respond_to?(:y)
               ChunkyPNG::Point.new(source.x, source.y)
             else
-              raise ChunkyPNG::ExpectationFailed, "Don't know how to construct a point from #{source.inspect}!"
+              raise ArgumentError, "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}!"
+      else raise ArgumentError, "Don't know how to construct a point from #{args.inspect}!"
     end
   end
   
@@ -54,6 +55,10 @@ module ChunkyPNG
   #
   # @see ChunkyPNG.Point
   class Point
+    
+    # @return [Regexp] The regexp to parse points from a string.
+    # @private
+    POINT_REGEXP = /^[\(\[\{]?(\d+)\s*[,]?\s*(\d+)[\)\]\}]?$/
 
     # @return [Integer] The x-coordinate of the point.
     attr_accessor :x

data/lib/chunky_png/vector.rb

@@ -12,6 +12,10 @@ module ChunkyPNG
   # @overload Vector(pointlike, pointlike, pointlike, ...)
   #   Creates a vector by converting every argument to a point using {ChunkyPNG.Point}.
   #   @return [ChunkyPNG::Vector] The instantiated vector.
+  #
+  # @return [ChunkyPNG::Vector] The vector created by this factory method.
+  # @raise [ArgumentError] If the given arguments could not be understood as a vector.
+  # @see ChunkyPNG::Vector
   def self.Vector(*args)
     
     return args.first if args.length == 1 && args.first.kind_of?(ChunkyPNG::Vector)
@@ -24,58 +28,140 @@ module ChunkyPNG
   end
   
   # Class that represents a vector of points, i.e. a list of {ChunkyPNG::Point} instances.
+  #
+  # Vectors can be created quite flexibly. See the {ChunkyPNG.Vector} factory methods for 
+  # more information on how to construct vectors.
   class Vector
     
     include Enumerable
     
+    # @return [Array<ChunkyPNG::Point>] The array that holds all the points in this vector.
     attr_reader :points
     
+    # Initializes a vector based on a list of Point instances.
+    #
+    # You usually do not want to use this method directy, but call {ChunkyPNG.Vector} instead.
+    #
+    # @param [Array<ChunkyPNG::Point>] points
+    # @see ChunkyPNG.Vector
     def initialize(points = [])
       @points = points
     end
     
+    # Iterates over all the edges in this vector.
+    #
+    # An edge is a combination of two subsequent points in the vector. Together, they will form
+    # a path from the first point to the last point
+    #
+    # @param [true, false] close Whether to close the path, i.e. return an edge that connects the last
+    #   point in the vector back to the first point.
+    # @return [void]
+    # @raise [ChunkyPNG::ExpectationFailed] if the vector contains less than two points.
+    # @see #edges
     def each_edge(close = true)
       raise ChunkyPNG::ExpectationFailed, "Not enough points in this path to draw an edge!" if length < 2
       points.each_cons(2) { |a, b| yield(a, b) }
       yield(points.last, points.first) if close
     end
     
+    # Returns an enumerator that will iterate over all the edges in this vector.
+    # @param (see #each_edge)
+    # @return [Enumerator] The enumerator that iterates over the edges.
+    # @raise [ChunkyPNG::ExpectationFailed] if the vector contains less than two points.
+    # @see #each_edge
     def edges(close = true)
       Enumerator.new(self, :each_edge, close)
     end
     
+    # Returns the number of points in this vector.
+    # @return [Integer] The length of the points array.
     def length
       points.length
     end
     
+    # Iterates over all the points in this vector
+    # @yield [ChunkyPNG::Point] The points in the correct order.
+    # @return [void]
     def each(&block)
       points.each(&block)
     end
     
+    # Comparison between two vectors for quality.
+    # @param [ChunkyPNG::Vector] other The vector to compare with.
+    # @return [true, false] true if the list of points are identical
     def eql?(other)
       other.points == points
     end
     
     alias_method :==, :eql?
-    
-    def to_a
-      edges
-    end
-    
-    alias_method :to_ary, :to_a
 
+    # Returns the range in x-coordinates for all the points in this vector.
+    # @return [Range] The (inclusive) range of x-coordinates.
     def x_range
       Range.new(*points.map { |p| p.x }.minmax)
     end
-    
+
+    # Returns the range in y-coordinates for all the points in this vector.
+    # @return [Range] The (inclusive) range of y-coordinates.
     def y_range
       Range.new(*points.map { |p| p.y }.minmax)
     end
     
+    # Finds the lowest x-coordinate in this vector.
+    # @return [Integer] The lowest x-coordinate of all the points in the vector.
+    def min_x
+      x_range.first
+    end
+    
+    # Finds the highest x-coordinate in this vector.
+    # @return [Integer] The highest x-coordinate of all the points in the vector.
+    def max_x
+      x_range.last
+    end
+
+    # Finds the lowest y-coordinate in this vector.
+    # @return [Integer] The lowest y-coordinate of all the points in the vector.
+    def min_y
+      y_range.first
+    end
+    
+    # Finds the highest y-coordinate in this vector.
+    # @return [Integer] The highest y-coordinate of all the points in the vector.
+    def max_y
+      y_range.last
+    end
+    
+    # Returns the offset from (0,0) of the minimal bounding box of all the
+    # points in this vector
+    # @return [ChunkyPNG::Point] A point that describes the top left corner if a
+    #    minimal bounding box would be drawn around all the points in the vector.
+    def offset
+      ChunkyPNG::Point.new(min_x, min_y)
+    end
+    
+    # Returns the width of the minimal bounding box of all the points in this vector.
+    # @return [Integer] The x-distance between the points that are farthest from each other.
+    def width
+      1 + (max_x - min_x)
+    end
+
+    # Returns the height of the minimal bounding box of all the points in this vector.
+    # @return [Integer] The y-distance between the points that are farthest from each other.
+    def height
+      1 + (max_y - min_y)
+    end
+    
+    # Returns the dimension of the minimal bounding rectangle of the points in this vector.
+    # @return [ChunkyPNG::Dimension] The dimension instance with the width and height 
+    def dimension
+      ChunkyPNG::Dimension.new(width, height)
+    end
+    
+    # @return [Array<ChunkyPNG::Point>] The list of points interpreted from the input array.
     def self.multiple_from_array(source)
       return [] if source.empty?
       if source.first.kind_of?(Numeric) || source.first =~ /^\d+$/
-        raise ChunkyPNG::ExpectationFailed, "The points array is expected to have an even number of items!" if source.length % 2 != 0
+        raise ArgumentError, "The points array is expected to have an even number of items!" if source.length % 2 != 0
 
         points = []
         source.each_slice(2) { |x, y| points << ChunkyPNG::Point.new(x, y) }
@@ -85,6 +171,7 @@ module ChunkyPNG
       end
     end
     
+    # @return [Array<ChunkyPNG::Point>] The list of points parsed from the string.
     def self.multiple_from_string(source_str)
       multiple_from_array(source_str.scan(/[\(\[\{]?(\d+)\s*[,x]?\s*(\d+)[\)\]\}]?/))
     end

data/spec/chunky_png/canvas/drawing_spec.rb

@@ -6,8 +6,8 @@ describe ChunkyPNG::Canvas::Drawing do
     subject { ChunkyPNG::Canvas.new(1, 1, ChunkyPNG::Color.rgb(200, 150, 100)) }
     
     it "should compose colors correctly" do
-      subject.compose_pixel(0,0, ChunkyPNG::Color.rgba(100, 150, 200, 128))
-      subject['0,0'].should == ChunkyPNG::Color.rgb(150, 150, 150)
+      subject.compose_pixel(0,0, ChunkyPNG::Color(100, 150, 200, 128))
+      subject['0,0'].should == ChunkyPNG::Color(150, 150, 150)
     end
     
     it "should return the composed color" do
@@ -21,8 +21,8 @@ describe ChunkyPNG::Canvas::Drawing do
     end
     
     it "should do nothing when the coordinates are out of bounds" do
-      subject.compose_pixel(1, -1, ChunkyPNG::Color::BLACK).should be_nil
-      lambda { subject.compose_pixel(1, -1, ChunkyPNG::Color::BLACK) }.should_not change { subject['0,0'] }
+      subject.compose_pixel(1, -1, :black).should be_nil
+      lambda { subject.compose_pixel(1, -1, :black) }.should_not change { subject['0,0'] }
     end
   end
   
@@ -45,39 +45,37 @@ describe ChunkyPNG::Canvas::Drawing do
     
     it "should draw partial lines if the coordinates are partially out of bounds" do
       canvas = ChunkyPNG::Canvas.new(1, 2, ChunkyPNG::Color::WHITE)
-      canvas.line(-5, -5, 0, 0, ChunkyPNG::Color::BLACK)
+      canvas.line(-5, -5, 0, 0, '#000000')
       canvas.pixels.should == [ChunkyPNG::Color::BLACK, ChunkyPNG::Color::WHITE]
     end
     
     it "should return itself to allow chaining" do
       canvas = ChunkyPNG::Canvas.new(16, 16, ChunkyPNG::Color::WHITE)
-      canvas.line(1, 1, 10, 10, ChunkyPNG::Color::BLACK).should equal(canvas)
+      canvas.line(1, 1, 10, 10, :black).should equal(canvas)
     end
   end
   
   describe '#rect' do
+    subject { ChunkyPNG::Canvas.new(16, 16, '#ffffff') }
+    
     it "should draw a rectangle with the correct colors" do
-      canvas = ChunkyPNG::Canvas.new(16, 16, ChunkyPNG::Color::WHITE)
-      canvas.rect(1, 1, 10, 10, ChunkyPNG::Color.rgba(0, 255, 0,  80), ChunkyPNG::Color.rgba(255, 0, 0, 100))
-      canvas.rect(5, 5, 14, 14, ChunkyPNG::Color.rgba(0, 0, 255, 160), ChunkyPNG::Color.rgba(255, 255, 0, 100))
-      canvas.should == reference_canvas('rect')
+      subject.rect(1, 1, 10, 10, ChunkyPNG::Color.rgba(0, 255, 0,  80), ChunkyPNG::Color.rgba(255, 0, 0, 100))
+      subject.rect(5, 5, 14, 14, ChunkyPNG::Color.rgba(0, 0, 255, 160), ChunkyPNG::Color.rgba(255, 255, 0, 100))
+      subject.should == reference_canvas('rect')
     end
     
     it "should return itself to allow chaining" do
-      canvas = ChunkyPNG::Canvas.new(16, 16, ChunkyPNG::Color::WHITE)
-      canvas.rect(1, 1, 10, 10).should equal(canvas)
+      subject.rect(1, 1, 10, 10).should equal(subject)
     end
     
     it "should draw partial rectangles if the coordinates are partially out of bounds" do
-      canvas = ChunkyPNG::Canvas.new(1, 1)
-      canvas.rect(0, 0, 10, 10, ChunkyPNG::Color::BLACK, ChunkyPNG::Color::WHITE)
-      canvas[0, 0].should == ChunkyPNG::Color::BLACK
+      subject.rect(0, 0, 20, 20, :black, :white)
+      subject[0, 0].should == ChunkyPNG::Color::BLACK
     end
     
     it "should draw the rectangle fill only if the coordinates are fully out of bounds" do
-      canvas = ChunkyPNG::Canvas.new(1, 1)
-      canvas.rect(-10, -10, 10, 10, ChunkyPNG::Color::BLACK, ChunkyPNG::Color::WHITE)
-      canvas[0, 0].should == ChunkyPNG::Color::WHITE
+      subject.rect(-1, -1, 20, 20, :black, :white)
+      subject[0, 0].should == ChunkyPNG::Color::WHITE
     end
   end
   
@@ -97,7 +95,7 @@ describe ChunkyPNG::Canvas::Drawing do
     end
 
     it "should return itself to allow chaining" do
-      subject.circle(10, 10, 5).should equal(subject)
+      subject.circle(10, 10, 5, :red).should equal(subject)
     end
   end