chunky_png 1.3.0 → 1.3.1

data/lib/chunky_png/datastream.rb

@@ -3,7 +3,7 @@ module ChunkyPNG
   # The Datastream class represents a PNG formatted datastream. It supports
   # both reading from and writing to strings, streams and files.
   #
-  # A PNG datastream begins with the PNG signature, and than contains multiple
+  # A PNG datastream begins with the PNG signature, and then contains multiple
   # chunks, starting with a header (IHDR) chunk and finishing with an end
   # (IEND) chunk.
   #

data/lib/chunky_png/palette.rb

@@ -1,24 +1,23 @@
 module ChunkyPNG
-
   # A palette describes the set of colors that is being used for an image.
   #
   # A PNG image can contain an explicit palette which defines the colors of
-  # that image, but can also use an implicit palette, e.g. all truecolor
-  # colors or all grayscale colors.
+  # that image, but can also use an implicit palette, e.g. all truecolor colors
+  # or all grayscale colors.
   #
-  # This palette supports decoding colors from a palette if an explicit
-  # palette is provided in a PNG datastream, and it supports encoding colors
-  # to an explicit palette (stores as PLTE & tRNS chunks in a PNG file).
+  # This palette supports decoding colors from a palette if an explicit palette
+  # is provided in a PNG datastream, and it supports encoding colors to an
+  # explicit palette (stores as PLTE & tRNS chunks in a PNG file).
   #
   # @see ChunkyPNG::Color
   class Palette < SortedSet
-
     # Builds a new palette given a set (Enumerable instance) of colors.
     #
-    # @param [Enumerable<Integer>] enum The set of colors to include in this palette.
-    #   This Enumerable can contains duplicates.
-    # @param [Array] decoding_map An array of colors in the exact order at which
-    #   they appeared in the palette chunk, so that this array can be used for decoding.
+    # @param enum [Enumerable<Integer>] The set of colors to include in this
+    #   palette.This Enumerable can contain duplicates.
+    # @param decoding_map [Array] An array of colors in the exact order at
+    #   which they appeared in the palette chunk, so that this array can be
+    #   used for decoding.
     def initialize(enum, decoding_map = nil)
       super(enum)
       @decoding_map = decoding_map if decoding_map
@@ -29,8 +28,10 @@ module ChunkyPNG
     #
     # This method will cerate a palette that is suitable for decoding an image.
     #
-    # @param [ChunkyPNG::Chunk::Palette] The palette chunk to load from
-    # @param [ChunkyPNG::Chunk::Transparency, nil] The optional transparency chunk.
+    # @param palette_chunk [ChunkyPNG::Chunk::Palette] The palette chunk to
+    #   load from
+    # @param transparency_chunk [ChunkyPNG::Chunk::Transparency, nil] The
+    #   optional transparency chunk.
     # @return [ChunkyPNG::Palette] The loaded palette instance.
     # @see ChunkyPNG::Palette#can_decode?
     def self.from_chunks(palette_chunk, transparency_chunk = nil)
@@ -53,25 +54,30 @@ module ChunkyPNG
         index += 1
       end
 
-      self.new(decoding_map, decoding_map)
+      new(decoding_map, decoding_map)
     end
 
     # Builds a palette instance from a given canvas.
-    # @param [ChunkyPNG::Canvas] canvas The canvas to create a palette for.
+    # @param canvas [ChunkyPNG::Canvas] The canvas to create a palette for.
     # @return [ChunkyPNG::Palette] The palette instance.
     def self.from_canvas(canvas)
-      self.new(canvas.pixels)
+      # Although we don't need to call .uniq.sort before initializing, because
+      # Palette subclasses SortedSet, we get significantly better performance
+      # by doing so.
+      new(canvas.pixels.uniq.sort)
     end
 
     # Builds a palette instance from a given set of pixels.
-    # @param [Enumerable<Integer>] pixels An enumeration of pixels to create a palette for
+    # @param pixels [Enumerable<Integer>] An enumeration of pixels to create a
+    #   palette for
     # @return [ChunkyPNG::Palette] The palette instance.
     def self.from_pixels(pixels)
-      self.new(pixels)
+      new(pixels)
     end
 
     # Checks whether the size of this palette is suitable for indexed storage.
-    # @return [true, false] True if the number of colors in this palette is at most 256.
+    # @return [true, false] True if the number of colors in this palette is at
+    #   most 256.
     def indexable?
       size <= 256
     end
@@ -84,56 +90,67 @@ module ChunkyPNG
     end
 
     # Check whether this palette only contains grayscale colors.
-    # @return [true, false] True if all colors in this palette are grayscale teints.
+    # @return [true, false] True if all colors in this palette are grayscale
+    #   teints.
     # @see ChunkyPNG::Color#grayscale??
     def grayscale?
       all? { |color| Color.grayscale?(color) }
     end
 
     # Check whether this palette only contains bacl and white.
-    # @return [true, false] True if all colors in this palette are grayscale teints.
+    # @return [true, false] True if all colors in this palette are grayscale
+    #   teints.
     # @see ChunkyPNG::Color#grayscale??
     def black_and_white?
       entries == [ChunkyPNG::Color::BLACK, ChunkyPNG::Color::WHITE]
     end
-    
-    # Returns a palette with all the opaque variants of the colors in this palette.
-    # @return [ChunkyPNG::Palette] A new Palette instance with only opaque colors.
+
+    # Returns a palette with all the opaque variants of the colors in this
+    # palette.
+    # @return [ChunkyPNG::Palette] A new Palette instance with only opaque
+    #   colors.
     # @see ChunkyPNG::Color#opaque!
     def opaque_palette
       self.class.new(map { |c| ChunkyPNG::Color.opaque!(c) })
     end
 
-    # Checks whether this palette is suitable for decoding an image from a datastream.
+    # Checks whether this palette is suitable for decoding an image from a
+    # datastream.
     #
-    # This requires that the positions of the colors in the original palette chunk is known,
-    # which is stored as an array in the +@decoding_map+ instance variable.
+    # This requires that the positions of the colors in the original palette
+    # chunk is known, which is stored as an array in the +@decoding_map+
+    # instance variable.
     #
-    # @return [true, false] True if a decoding map was built when this palette was loaded.
+    # @return [true, false] True if a decoding map was built when this palette
+    #   was loaded.
     def can_decode?
       !@decoding_map.nil?
     end
 
-    # Checks whether this palette is suitable for encoding an image from to datastream.
+    # Checks whether this palette is suitable for encoding an image from to
+    # datastream.
     #
-    # This requires that the position of the color in the future palette chunk is known,
-    # which is stored as a hash in the +@encoding_map+ instance variable.
+    # This requires that the position of the color in the future palette chunk
+    # is known, which is stored as a hash in the +@encoding_map+ instance
+    # variable.
     #
-    # @return [true, false] True if a encoding map was built when this palette was loaded.
+    # @return [true, false] True if a encoding map was built when this palette
+    #   was loaded.
     def can_encode?
       !@encoding_map.nil?
     end
 
     # Returns a color, given the position in the original palette chunk.
-    # @param [Integer] index The 0-based position of the color in the palette.
-    # @return [ChunkyPNG::Color] The color that is stored in the palette under the given index
+    # @param index [Integer] The 0-based position of the color in the palette.
+    # @return [ChunkyPNG::Color] The color that is stored in the palette under
+    #   the given index
     # @see ChunkyPNG::Palette#can_decode?
     def [](index)
       @decoding_map[index]
     end
 
     # Returns the position of a color in the palette
-    # @param [ChunkyPNG::Color] color The color for which to look up the index.
+    # @param color [ChunkyPNG::Color] The color for which to look up the index.
     # @return [Integer] The 0-based position of the color in the palette.
     # @see ChunkyPNG::Palette#can_encode?
     def index(color)
@@ -151,12 +168,12 @@ module ChunkyPNG
       ChunkyPNG::Chunk::Transparency.new('tRNS', map { |c| ChunkyPNG::Color.a(c) }.pack('C*'))
     end
 
-    # Creates a PLTE chunk that corresponds with this palette to store the
-    # r, g and b channels of all colors.
+    # Creates a PLTE chunk that corresponds with this palette to store the r,
+    # g, and b channels of all colors.
     #
-    # Note that a PLTE chunk should only be included if the image is
-    # encoded using index colors. After this chunk has been built, the
-    # palette becomes suitable for encoding an image.
+    # @note A PLTE chunk should only be included if the image is encoded using
+    #   index colors. After this chunk has been built, the palette becomes
+    #   suitable for encoding an image.
     #
     # @return [ChunkyPNG::Chunk::Palette] The PLTE chunk.
     # @see ChunkyPNG::Palette#can_encode?
@@ -174,7 +191,7 @@ module ChunkyPNG
 
     # Determines the most suitable colormode for this palette.
     # @return [Integer] The colormode which would create the smallest possible
-    #    file for images that use this exact palette.
+    #  file for images that use this exact palette.
     def best_color_settings
       if black_and_white?
         [ChunkyPNG::COLOR_GRAYSCALE, 1]
@@ -192,17 +209,17 @@ module ChunkyPNG
         [ChunkyPNG::COLOR_TRUECOLOR_ALPHA, 8]
       end
     end
-    
+
     # Determines the minimal bit depth required for an indexed image
-    # @return [Integer] Number of bits per pixel, i.e. 1, 2, 4 or 8, or nil if this
-    #    image cannot be saved as an indexed image.
+    # @return [Integer] Number of bits per pixel, i.e. 1, 2, 4 or 8, or nil if
+    #   this image cannot be saved as an indexed image.
     def determine_bit_depth
       case size
-        when 1..2; 1
-        when 3..4; 2
-        when 5..16; 4
-        when 17..256; 8
-        else nil
+      when 1..2 then 1
+      when 3..4 then 2
+      when 5..16 then 4
+      when 17..256 then 8
+      else nil
       end
     end
   end

data/lib/chunky_png/version.rb

@@ -1,5 +1,5 @@
 module ChunkyPNG
   # The current version of ChunkyPNG. 
   # Set it and commit the change this before running rake release.
-  VERSION = "1.3.0"
+  VERSION = "1.3.1"
 end

data/spec/chunky_png/canvas/stream_importing_spec.rb

@@ -11,6 +11,15 @@ describe ChunkyPNG::Canvas do
     end
   end
 
+  describe '.from_bgr_stream' do
+    it "should load an image correctly from a datastream" do
+      File.open(resource_file('pixelstream.bgr')) do |stream|
+        matrix = ChunkyPNG::Canvas.from_bgr_stream(240, 180, stream)
+        matrix.should == reference_canvas('pixelstream_reference')
+      end
+    end
+  end
+
   describe '.from_rgba_stream' do
     it "should load an image correctly from a datastream" do
       File.open(resource_file('pixelstream.rgba')) do |stream|

data/spec/chunky_png/color_spec.rb

@@ -1,20 +1,20 @@
 require 'spec_helper'
 
 describe 'ChunyPNG.Color' do
-  it "should interpret 4 arguments as RGBA values" do
+  it 'should interpret 4 arguments as RGBA values' do
     ChunkyPNG::Color(1, 2, 3, 4).should == ChunkyPNG::Color.rgba(1, 2, 3, 4)
   end
-  
-  it "should interpret 3 arguments as RGBA values" do
+
+  it 'should interpret 3 arguments as RGBA values' do
     ChunkyPNG::Color(1, 2, 3).should == ChunkyPNG::Color.rgb(1, 2, 3)
   end
-  
-  it "should interpret 2 arguments as a color to parse and an opacity value" do
+
+  it 'should interpret 2 arguments as a color to parse and an opacity value' do
     ChunkyPNG::Color('0x0a649664', 0xaa).should == 0x0a6496aa
     ChunkyPNG::Color('spring green @ 0.6666', 0xff).should == 0x00ff7fff
   end
-  
-  it "should interpret 1 argument as a color to parse" do
+
+  it 'should interpret 1 argument as a color to parse' do
     ChunkyPNG::Color.should_receive(:parse).with('0x0a649664')
     ChunkyPNG::Color('0x0a649664')
   end
@@ -30,55 +30,55 @@ describe ChunkyPNG::Color do
     @non_opaque        = 0x0a649664
     @fully_transparent = 0x0a649600
   end
-  
+
   describe '#parse' do
-    it "should interpret a hex string correctly" do
+    it 'should interpret a hex string correctly' do
       parse('0x0a649664').should == ChunkyPNG::Color.from_hex('#0a649664')
     end
 
-    it "should interpret a color name correctly" do
+    it 'should interpret a color name correctly' do
       parse(:spring_green).should == 0x00ff7fff
       parse('spring green').should == 0x00ff7fff
       parse('spring green @ 0.6666').should == 0x00ff7faa
     end
-    
-    it "should return numbers as is" do
+
+    it 'should return numbers as is' do
       parse('12345').should == 12345
       parse(12345).should == 12345
     end
   end
 
   describe '#pixel_bytesize' do
-    it "should return the normal amount of bytes with a bit depth of 8" do
+    it 'should return the normal amount of bytes with a bit depth of 8' do
       pixel_bytesize(ChunkyPNG::COLOR_TRUECOLOR, 8).should == 3
     end
 
-    it "should return a multiple of the normal amount of bytes with a bit depth greater than 8" do
+    it 'should return a multiple of the normal amount of bytes with a bit depth greater than 8' do
       pixel_bytesize(ChunkyPNG::COLOR_TRUECOLOR, 16).should == 6
       pixel_bytesize(ChunkyPNG::COLOR_TRUECOLOR_ALPHA, 16).should == 8
       pixel_bytesize(ChunkyPNG::COLOR_GRAYSCALE_ALPHA, 16).should == 4
     end
-    
-    it "should return 1 with a bit depth lower than 0" do
+
+    it 'should return 1 with a bit depth lower than 0' do
       pixel_bytesize(ChunkyPNG::COLOR_TRUECOLOR, 4).should == 1
       pixel_bytesize(ChunkyPNG::COLOR_INDEXED, 2).should == 1
       pixel_bytesize(ChunkyPNG::COLOR_GRAYSCALE_ALPHA, 1).should == 1
     end
   end
-  
+
   describe '#pass_bytesize' do
-    it "should calculate a pass size correctly" do
+    it 'should calculate a pass size correctly' do
       pass_bytesize(ChunkyPNG::COLOR_TRUECOLOR, 8, 10, 10).should == 310
     end
-    
-    it "should return 0 if one of the dimensions is zero" do
+
+    it 'should return 0 if one of the dimensions is zero' do
       pass_bytesize(ChunkyPNG::COLOR_TRUECOLOR, 8, 0, 10).should == 0
       pass_bytesize(ChunkyPNG::COLOR_TRUECOLOR, 8, 10, 0).should == 0
     end
   end
 
   describe '#rgba' do
-    it "should represent pixels as the correct number" do
+    it 'should represent pixels as the correct number' do
       rgba(255, 255, 255, 255).should == @white
       rgba(  0,   0,   0, 255).should == @black
       rgba( 10, 100, 150, 255).should == @opaque
@@ -86,9 +86,9 @@ describe ChunkyPNG::Color do
       rgba( 10, 100, 150,   0).should == @fully_transparent
     end
   end
-  
+
   describe '#from_hex' do
-    it "should load colors correctly from hex notation" do
+    it 'should load colors correctly from hex notation' do
       from_hex('0a649664').should   == @non_opaque
       from_hex('#0a649664').should  == @non_opaque
       from_hex('0x0a649664').should == @non_opaque
@@ -99,17 +99,17 @@ describe ChunkyPNG::Color do
       from_hex('#abc').should       == 0xaabbccff
       from_hex('0xabc').should      == 0xaabbccff
     end
-    
-    it "should allow setting opacity explicitly" do
+
+    it 'should allow setting opacity explicitly' do
       from_hex('0x0a6496', 0x64).should == @non_opaque
       from_hex('#0a6496', 0x64).should  == @non_opaque
       from_hex('0xabc', 0xdd).should    == 0xaabbccdd
       from_hex('#abc', 0xdd).should     == 0xaabbccdd
     end
   end
-  
+
   describe '#html_color' do
-    it "should find the correct color value" do
+    it 'should find the correct color value' do
       html_color(:springgreen).should   == 0x00ff7fff
       html_color(:spring_green).should  == 0x00ff7fff
       html_color('springgreen').should  == 0x00ff7fff
@@ -117,26 +117,26 @@ describe ChunkyPNG::Color do
       html_color('SpringGreen').should  == 0x00ff7fff
       html_color('SPRING_GREEN').should == 0x00ff7fff
     end
-    
-    it "should set the opacity level explicitly" do
+
+    it 'should set the opacity level explicitly' do
       html_color(:springgreen, 0xff).should == 0x00ff7fff
       html_color(:springgreen, 0xaa).should == 0x00ff7faa
       html_color(:springgreen, 0x00).should == 0x00ff7f00
     end
-    
-    it "should set opacity levels from the color name" do
+
+    it 'should set opacity levels from the color name' do
       html_color('Spring green @ 1.0').should   == 0x00ff7fff
       html_color('Spring green @ 0.666').should == 0x00ff7faa
       html_color('Spring green @ 0.0').should   == 0x00ff7f00
     end
-    
-    it "should raise for an unkown color name" do
+
+    it 'should raise for an unkown color name' do
       lambda { html_color(:nonsense) }.should raise_error(ArgumentError)
     end
   end
-  
+
   describe '#opaque?' do
-    it "should correctly check for opaqueness" do
+    it 'should correctly check for opaqueness' do
       opaque?(@white).should be_true
       opaque?(@black).should be_true
       opaque?(@opaque).should be_true
@@ -144,47 +144,47 @@ describe ChunkyPNG::Color do
       opaque?(@fully_transparent).should be_false
     end
   end
-  
-  describe 'extractiion of separate color channels' do
-    it "should extract components from a color correctly" do
+
+  describe 'extraction of separate color channels' do
+    it 'should extract components from a color correctly' do
       r(@opaque).should == 10
       g(@opaque).should == 100
       b(@opaque).should == 150
       a(@opaque).should == 255
     end
   end
-  
+
   describe '#grayscale_teint' do
-    it "should calculate the correct grayscale teint" do
+    it 'should calculate the correct grayscale teint' do
       grayscale_teint(@opaque).should     == 79
       grayscale_teint(@non_opaque).should == 79
     end
   end
-  
+
   describe '#to_grayscale' do
-    it "should use the grayscale teint for r, g and b" do
+    it 'should use the grayscale teint for r, g and b' do
       gs = to_grayscale(@non_opaque)
       r(gs).should == grayscale_teint(@non_opaque)
       g(gs).should == grayscale_teint(@non_opaque)
       b(gs).should == grayscale_teint(@non_opaque)
     end
-    
-    it "should preserve the alpha channel" do
+
+    it 'should preserve the alpha channel' do
       a(to_grayscale(@non_opaque)).should == a(@non_opaque)
       a(to_grayscale(@opaque)).should == ChunkyPNG::Color::MAX
     end
   end
-  
+
   describe '#to_hex' do
-    it "should represent colors correcly using hex notation" do
+    it 'should represent colors correcly using hex notation' do
       to_hex(@white).should == '#ffffffff'
       to_hex(@black).should == '#000000ff'
       to_hex(@opaque).should == '#0a6496ff'
       to_hex(@non_opaque).should == '#0a649664'
       to_hex(@fully_transparent).should == '#0a649600'
     end
-    
-    it "should represent colors correcly using hex notation without alpha channel" do
+
+    it 'should represent colors correcly using hex notation without alpha channel' do
       to_hex(@white, false).should == '#ffffff'
       to_hex(@black, false).should == '#000000'
       to_hex(@opaque, false).should == '#0a6496'
@@ -194,58 +194,82 @@ describe ChunkyPNG::Color do
   end
 
   describe 'conversion to other formats' do
-    it "should convert the individual color values back correctly" do
+    it 'should convert the individual color values back correctly' do
       to_truecolor_bytes(@opaque).should == [10, 100, 150]
       to_truecolor_alpha_bytes(@non_opaque).should == [10, 100, 150, 100]
     end
   end
-  
+
   describe '#compose' do
 
-    it "should use the foregorund color as is when the background color is fully transparent" do
+    it 'should use the foregorund color as is when the background color is fully transparent' do
       compose(@non_opaque, @fully_transparent).should == @non_opaque
     end
 
-    it "should use the foregorund color as is when an opaque color is given as foreground color" do
+    it 'should use the foregorund color as is when an opaque color is given as foreground color' do
       compose(@opaque, @white).should == @opaque
     end
 
-    it "should use the background color as is when a fully transparent pixel is given as foreground color" do
+    it 'should use the background color as is when a fully transparent pixel is given as foreground color' do
       compose(@fully_transparent, @white).should == @white
     end
 
-    it "should compose pixels correctly with both algorithms" do
+    it 'should compose pixels correctly with both algorithms' do
       compose_quick(@non_opaque, @white).should   == 0x9fc2d6ff
       compose_precise(@non_opaque, @white).should == 0x9fc2d6ff
     end
   end
-  
+
   describe '#decompose_alpha' do
-    it "should decompose the alpha channel correctly" do
+    it 'should decompose the alpha channel correctly' do
       decompose_alpha(0x9fc2d6ff, @opaque, @white).should == 0x00000064
     end
-    
-    it "should return fully transparent if the background channel matches the resulting color" do
+
+    it 'should return fully transparent if the background channel matches the resulting color' do
       decompose_alpha(0xabcdefff, 0xff000000, 0xabcdefff).should == 0x00
     end
-    
-    it "should return fully opaque if the background channel matches the mask color" do
+
+    it 'should return fully opaque if the background channel matches the mask color' do
       decompose_alpha(0xff000000, 0xabcdefff, 0xabcdefff).should == 0xff
     end
-    
-    it "should return fully opaque if the resulting color matches the mask color" do
+
+    it 'should return fully opaque if the resulting color matches the mask color' do
       decompose_alpha(0xabcdefff, 0xabcdefff, 0xffffffff).should == 255
-    end    
+    end
   end
-  
+
   describe '#blend' do
-    it "should blend colors correctly" do
+    it 'should blend colors correctly' do
       blend(@opaque, @black).should == 0x05324bff
     end
-    
-    it "should not matter what color is used as foreground, and what as background" do
+
+    it 'should not matter what color is used as foreground, and what as background' do
       blend(@opaque, @black).should == blend(@black, @opaque)
     end
   end
-end
 
+  describe '#euclidean_distance_rgba' do
+    subject { euclidean_distance_rgba(color_a, color_b) }
+
+    context 'with white and black' do
+      let(:color_a) { @white }
+      let(:color_b) { @black }
+
+      it { should == Math.sqrt(195_075) } # sqrt(255^2 * 3)
+    end
+
+    context 'with black and white' do
+      let(:color_a) { @black }
+      let(:color_b) { @white }
+
+      it { should == Math.sqrt(195_075) } # sqrt(255^2 * 3)
+    end
+
+    context 'with the same colors' do
+      let(:color_a) { @white }
+      let(:color_b) { @white }
+
+      it { should == 0 }
+    end
+  end
+end