chunky_png 0.5.5 → 0.5.6

data/chunky_png.gemspec

@@ -3,7 +3,7 @@ Gem::Specification.new do |s|
 
   # Do not change the version and date fields by hand. This will be done
   # automatically by the gem release script.
-  s.version = "0.5.5"
+  s.version = "0.5.6"
   s.date    = "2010-02-16"
 
   s.summary     = "Pure ruby library for read/write, chunk-level access to PNG files"

data/lib/chunky_png.rb

@@ -26,7 +26,7 @@ module ChunkyPNG
 
   # The current version of ChunkyPNG. This value will be updated automatically
   # by them gem:release rake task.
-  VERSION = "0.5.5"
+  VERSION = "0.5.6"
 
   ###################################################
   # PNG international standard defined constants

data/lib/chunky_png/color.rb

@@ -238,23 +238,84 @@ module ChunkyPNG
       (color & 0xffffff00) | new_alpha
     end
     
+    # Decomposes a color, given a color, a mask color and a background color.
+    # The returned color will be a variant of the mask color, with the alpha
+    # channel set to the best fitting value. This basically is the reverse 
+    # operation if alpha composition.
+    #
+    # If the color cannot be decomposed, this method will return the fully
+    # transparentvariant of the mask color.
+    #
+    # @param [Fixnum] color The color that was the result of compositing.
+    # @param [Fixnum] mask The opaque variant of the color that was being composed
+    # @param [Fixnum] bg The background color on which the color was composed.
+    # @param [Fixnum] tolerance The decomposition tolerance level, a value between 0 and 255.
+    # @return [Fixnum] The decomposed color,a variant of the masked color with the 
+    #    alpha channel set to an appropriate value.
+    def decompose_color(color, mask, bg, tolerance = 1)
+      if alpha_decomposable?(color, mask, bg, tolerance)
+        mask & 0xffffff00 | decompose_alpha(color, mask, bg)
+      else
+        mask & 0xffffff00
+      end
+    end
+    
+    # Checks whether an alpha channel value can successfully be composed
+    # given the resulting color, the mask color and a background color,
+    # all of which should be opaque. 
+    #
+    # @param [Fixnum] color The color that was the result of compositing.
+    # @param [Fixnum] mask The opauqe variant of the color that was being composed
+    # @param [Fixnum] bg The background color on which the color was composed.
+    # @param [Fixnum] tolerance The decomposition tolerance level, a value between 0 and 255.
+    # @return [Fixnum] The decomposed alpha channel value, between 0 and 255.
+    # @see #decompose_alpha
     def alpha_decomposable?(color, mask, bg, tolerance = 1)
       components = decompose_alpha_components(color, mask, bg)
       sum = components.inject(0) { |a,b| a + b } 
       max = components.max * 3
-      return (sum + tolerance * 3) >= max
+      return components.max <= 255 && components.min >= 0 && (sum + tolerance * 3) >= max
     end
     
+    # Decomposes the alpha channel value given the resulting color, the mask color 
+    # and a background color, all of which should be opaque.
+    #
+    # Make sure to call {#alpha_decomposable?} first to see if the alpha channel
+    # value can successfully decomposed with a given tolerance, otherwise the return 
+    # value of this method is undefined.
+    #
+    # @param [Fixnum] color The color that was the result of compositing.
+    # @param [Fixnum] mask The opauqe variant of the color that was being composed
+    # @param [Fixnum] bg The background color on which the color was composed.
+    # @return [Fixnum] The best fitting alpha channel, a value between 0 and 255.
+    # @see #alpha_decomposable?
     def decompose_alpha(color, mask, bg)
       components = decompose_alpha_components(color, mask, bg)
       (components.inject(0) { |a,b| a + b } / 3.0).round
     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 [Fixnum] color The color that was the result of compositing.
+    # @param [Fixnum] mask The opauqe variant of the color that was being composed
+    # @param [Fixnum] bg The background color on which the color was composed.
+    # @param [Fixnum] 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
+    end
+    
+    # Decomposes the alpha channels for the r, g and b color channel.
+    # @param [Fixnum] color The color that was the result of compositing.
+    # @param [Fixnum] mask The opauqe variant of the color that was being composed
+    # @param [Fixnum] bg The background color on which the color was composed.    
+    # @return [Array<Fixnum>] The decomposed alpha values for the r, g and b channels.
     def decompose_alpha_components(color, mask, bg)
-      a_r = ((r(bg) - r(color)).to_f / (r(bg) - r(mask)).to_f * MAX).round
-      a_g = ((g(bg) - g(color)).to_f / (g(bg) - g(mask)).to_f * MAX).round
-      a_b = ((b(bg) - b(color)).to_f / (b(bg) - b(mask)).to_f * MAX).round
-      [a_r, a_g, a_b]
+      [
+        decompose_alpha_component(:r, color, mask, bg),
+        decompose_alpha_component(:g, color, mask, bg),
+        decompose_alpha_component(:b, color, mask, bg)
+      ]
     end
 
     ####################################################################

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: chunky_png
 version: !ruby/object:Gem::Version 
-  version: 0.5.5
+  version: 0.5.6
 platform: ruby
 authors: 
 - Willem van Bergen