redgreenblue 0.14.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a61701a3122fc8e8b4f4352142862f7e3d63ed317cea1321cfe1bafd5d697a42
-  data.tar.gz: 4a76d444f8080acb74656963654375e975eb91eb0068f6c4012e9233daf58bb7
+  metadata.gz: 2359fa39f6387727f76770372b1f798ae60fdf34dce8bd481b06d58e5a128c4b
+  data.tar.gz: 6194f07e51ce46a4c9bdd3fd7d2fd895eebcb8e6f34e76c37b3c078d3ea58fb9
 SHA512:
-  metadata.gz: 502bc188625f8df6fc3a55fa53454728602843ddd39f61c8199009f0e55c1fbd38a496d27c889c565b578ae85dd9cd051a457deec87979374d89006833f37707
-  data.tar.gz: b811b0e1bc0bd366406be48eead2f11328c8304eee6eb34192bc92c40c31a4683dc5771a3944650749707df7e5a40e330d64c02b7f7818c0064dca5253ffe019
+  metadata.gz: e76a1651bfac0b0f197cae93a9fa3139e798a3a2ab0ae00950d08eb5e724834f9ccce7fe06beb98b083988fd4d7b672431aee5c23a66c24cce2782669606b517
+  data.tar.gz: 688367a83417deb0a812e96982f9c44ec369a1ee6984836338c25b07bd11843ced02053341044cebcaf2e4e71ce5ef26316799850831e446b85ece5766d31ddf

data/lib/redgreenblue/24bit.rb

@@ -1,4 +1,4 @@
-class RGB
+class RGB::Color
 
 # r, g, b methods
 
@@ -44,7 +44,7 @@ class RGB
     self.r, self.g, self.b = rgb.flatten
   end
 
-  # Creates a new object from red, green, and blue components as integers in the range 0..255 (three 8-bit values).
+  # Creates a new RGB::Color from red, green, and blue components as integers in the range 0..255 (three 8-bit values).
   def self.rgb(*rgb)
     c = self.new
     c.rgb = rgb
@@ -57,24 +57,38 @@ class RGB
     self
   end
 
-  # Creates a new RGB object containing the nearest 24-bit color.
+  # Creates a new RGB::Color containing the nearest 24-bit color.
   def snap
     RGB.rgb rgb
   end
 
-  # Calls the given block for each 24-bit RGB color (from black to white), passing the color as an RGB object.
-  #
-  # Returns the number of iterations.
-  def self.each_24bit_color
-    range = 0..255
-    range.each do |r|
-      range.each do |g|
-        range.each do |b|
-          yield self.rgb(r,g,b)
+end
+
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color from red, green, and blue components as integers in the range 0..255 (three 8-bit values).
+    def rgb(*rgb)
+      Color.rgb(*rgb)
+    end
+
+    # Calls the given block for each 24-bit RGB color (from black to white), passing the color as an RGB::Color object.
+    #
+    # Returns the number of iterations.
+    def each_24bit_color
+      range = 0..255
+      range.each do |r|
+        range.each do |g|
+          range.each do |b|
+            yield self.rgb(r,g,b)
+          end
         end
       end
+      range.size ** 3
     end
-    range.size ** 3
+
   end
 
 end

data/lib/redgreenblue/48bit.rb

@@ -1,4 +1,4 @@
-class RGB
+class RGB::Color
 
 # rr, gg, bb methods
 
@@ -44,7 +44,7 @@ class RGB
     self.rr, self.gg, self.bb = rrggbb.flatten
   end
 
-  # Creates a new object from red, green, and blue components as integers in the range 0..65535 (three 16-bit values).
+  # Creates a new RGB::Color from red, green, and blue components as integers in the range 0..65535 (three 16-bit values).
   def self.rrggbb(*rrggbb)
     c = self.new
     c.rrggbb = rrggbb
@@ -52,3 +52,17 @@ class RGB
   end
 
 end
+
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color from red, green, and blue components as integers in the range 0..65535 (three 16-bit values).
+    def rrggbb(*rrggbb)
+      Color.rrggbb(*rrggbb)
+    end
+
+  end
+
+end

data/lib/redgreenblue/base.rb

@@ -1,4 +1,4 @@
-class RGB
+class RGB::Color
 
   def initialize(*a)
     self.values = a.any? ? a : [ 0.5, 0.5, 0.5 ]
@@ -82,3 +82,17 @@ class RGB
   end
 
 end
+
+# The main namespace for redgreenblue.
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color from red, green, and blue components as three values between 0 and 1.
+    def new(*a)
+      Color.new(*a)
+    end
+
+  end
+
+end

data/lib/redgreenblue/bgr24bit.rb

@@ -1,4 +1,4 @@
-class RGB
+class RGB::Color
 
   # Returns a 3-byte string containing the object's color in BGR24 format.
   def bgr24
@@ -10,7 +10,7 @@ class RGB
     self.b, self.g, self.r = bgr_string.unpack('C3')
   end
 
-  # Creates a new RGB object from BGR24 data (a 3-byte string).
+  # Creates a new RGB::Color from BGR24 data (a 3-byte string).
   def self.bgr24(bgr)
     c = self.new
     c.bgr24 = bgr
@@ -18,3 +18,17 @@ class RGB
   end
 
 end
+
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color from BGR24 data (a 3-byte string).
+    def bgr24(bgr)
+      Color.bgr24(bgr)
+    end
+
+  end
+
+end

data/lib/redgreenblue/cie_1931.rb

@@ -1,6 +1,21 @@
-class RGB
+class RGB::Color
 
-  # Returns CIE 1931 XYZ values for the RGB object.
+  class << self
+
+    # Creates a new RGB::Color from CIE 1931 XYZ values.
+    #
+    # Assumes the XYZ values are relative to D65 reference white, the same as used in sRGB.
+    def cie_xyz(*a)
+      c = self.new
+      c.cie_xyz = a
+      c
+    end
+
+    alias xyz cie_xyz
+
+  end
+
+  # Returns CIE 1931 XYZ values for the RGB::Color object.
   #
   # Based on:
   # - http://www.brucelindbloom.com/index.html?Eqn_RGB_to_XYZ.html
@@ -11,41 +26,74 @@ class RGB
     r, g, b = linear_values
 
     [
-
       r * 0.4124_5643_9090 + g * 0.3575_7607_7644 + b * 0.1804_3748_3266,
       r * 0.2126_7285_1406 + g * 0.7151_5215_5288 + b * 0.0721_7499_3307,
       r * 0.0193_3389_5582 + g * 0.1191_9202_5881 + b * 0.9503_0407_8536
-
     ].map { |v| round ? v.round(8) : v }
   end
 
   alias xyz cie_xyz
 
-  # Returns CIE 1931 xyY values for the RGB object.
+  # Sets the red, green, and blue values by converting the given CIE 1931 XYZ values to RGB.
+  #
+  # Assumes the XYZ values are relative to D65 reference white, the same as used in sRGB.
+  #
+  # Based on:
+  # - http://www.brucelindbloom.com/index.html?Eqn_XYZ_to_RGB.html
+  # XYZ to sRGB matrix for D65 reference white calculated with Javascript by Bruce Lindbloom:
+  # - http://www.brucelindbloom.com/ColorCalculator.html
+  def cie_xyz=(*a)
+    x, y, z = a.flatten
+    self.linear_values = [
+      x *  3.2404_5416_2114 + y * -1.5371_3851_2798 + z * -0.498_5314_09556,
+      x * -0.9692_6603_0505 + y *  1.8760_1084_5447 + z *  0.0415_5601_7530,
+      x *  0.0556_4343_0959 + y * -0.2040_2591_3517 + z *  1.0572_2518_8223
+    ]
+  end
+
+  alias xyz= cie_xyz=
+
+  # Returns CIE 1931 xyY values for the RGB::Color object.
   #
   # Based on:
   # - https://en.wikipedia.org/wiki/CIE_1931_color_space
   # - http://www.brucelindbloom.com/index.html?Eqn_XYZ_to_xyY.html
   # - https://ninedegreesbelow.com/photography/xyz-rgb.html
-  def cie_xyy
+  def cie_xyy(round: true)
     x, y, z = cie_xyz(round: false)
 
     [
-
       x / ( x + y + z ),
       y / ( x + y + z ),
       y
-
-    ].map { |v| v.round(8) }
+    ].map { |v| round ? v.round(8) : v }
   end
 
   alias xyy cie_xyy
 
-  # Returns CIE 1931 xy values for the RGB object.
-  def cie_xy
-    cie_xyy[0..1]
+  # Returns CIE 1931 xy values for the RGB::Color object.
+  def cie_xy(round: true)
+    cie_xyy(round: round)[0..1]
   end
 
   alias xy cie_xy
 
 end
+
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color from CIE 1931 XYZ values.
+    #
+    # Assumes the XYZ values are relative to D65 reference white, the same as used in sRGB.
+    def cie_xyz(*a)
+      RGB::Color.cie_xyz(a)
+    end
+
+    alias xyz cie_xyz
+
+  end
+
+end

data/lib/redgreenblue/cie_1976.rb

@@ -1,27 +1,27 @@
-class RGB
+class RGB::Color
 
-  # Returns CIE 1976 L*a*b* (CIELAB) values for the RGB object.
+  # Returns CIE 1976 L*a*b* (CIELAB) values for the RGB::Color object.
   def cie_lab(round: true)
     cie_lab_luv(round: round, type: :lab)
   end
 
   alias lab cie_lab
 
-  # Returns CIE 1976 LCHab values for the RGB object, derived from L*a*b* (CIELAB).
+  # Returns CIE 1976 LCHab values for the RGB::Color object, derived from L*a*b* (CIELAB).
   #
   # When C is 0, H is nil.
   def cie_lch_ab
     cie_lch_ab_uv(type: :lab)
   end
 
-  # Returns CIE 1976 L*u*v* (CIELUV) values for the RGB object.
+  # Returns CIE 1976 L*u*v* (CIELUV) values for the RGB::Color object.
   def cie_luv(round: true)
     cie_lab_luv(round: round, type: :luv)
   end
 
   alias luv cie_luv
 
-  # Returns CIE 1976 LCHuv values for the RGB object, derived from L*u*v* (CIELUV).
+  # Returns CIE 1976 LCHuv values for the RGB::Color object, derived from L*u*v* (CIELUV).
   #
   # When C is 0, H is nil.
   def cie_lch_uv
@@ -44,7 +44,7 @@ class RGB
 
   private
 
-  # Returns either CIE 1976 L*a*b* (CIELAB) or CIE 1976 L*u*v* (CIELUV) values for the RGB object.
+  # Returns either CIE 1976 L*a*b* (CIELAB) or CIE 1976 L*u*v* (CIELUV) values for the RGB::Color object.
   #
   # L*a*b* formula based on:
   # - http://www.brucelindbloom.com/Eqn_XYZ_to_Lab.html
@@ -82,7 +82,7 @@ class RGB
     end.map { |v| v.nan? ? 0.0 : ( round ? v.round(8) : v ) }
   end
 
-  # Returns either CIE 1976 LCHab or CIE 1976 LCHuv values for the RGB object.
+  # Returns either CIE 1976 LCHab or CIE 1976 LCHuv values for the RGB::Color object.
   #
   # Based on:
   # - http://www.brucelindbloom.com/Eqn_Lab_to_LCH.html

data/lib/redgreenblue/cie_1994.rb

@@ -0,0 +1,55 @@
+class RGB::Color
+
+  # Returns the difference between this (reference) color and another color, according to the CIE 1994 delta E formula.
+  #
+  # By default uses parameters for use in graphic arts, and reference conditions.
+  # Parameters (k1, k2, kl, kc, kh) can be individually overriden for different applications and for variations in conditions.
+  #
+  # Based on:
+  # - http://www.brucelindbloom.com/Eqn_DeltaE_CIE94.html
+  # - https://archive.org/details/gov.law.cie.15.2004
+  # - https://en.wikipedia.org/wiki/Color_difference
+  def delta_e_cie_1994(another, k1: 0.045, k2: 0.015, kl: 1, kc: 1, kh: 1)
+
+    l , a , b  =         cie_lab(round: false)
+    l2, a2, b2 = another.cie_lab(round: false)
+
+    c  = Math.hypot(a , b )
+    c2 = Math.hypot(a2, b2)
+
+    da = a - a2
+    db = b - b2
+    dc = c - c2
+
+    dh2 = (da ** 2) + (db ** 2) - (dc ** 2)
+    dl = l - l2
+
+    sl = 1
+    sc = 1 + k1 * c
+    sh = 1 + k2 * c
+
+    Math.sqrt(
+      ( (dl  / ( kl*sl)) ** 2  ) +
+      ( (dc  / ( kc*sc)) ** 2  ) +
+      (  dh2 / ((kh*sh)  ** 2) )
+    ).round(6)
+
+  end
+
+  alias de94 delta_e_cie_1994
+
+  # Returns the difference between this (reference) color and another color, according to the CIE 1994 delta E formula.
+  #
+  # For use in graphic arts, under reference conditions.
+  def de94g(another)
+    delta_e_cie_1994(another)
+  end
+
+  # Returns the difference between this (reference) color and another color, according to the CIE 1994 delta E formula.
+  #
+  # For use with textiles, under reference conditions.
+  def de94t(another)
+    delta_e_cie_1994(another, k1: 0.048, k2: 0.014, kl: 2)
+  end
+
+end

data/lib/redgreenblue/gamma.rb

@@ -1,4 +1,4 @@
-class RGB
+class RGB::Color
 
   # Returns gamma-expanded (inverse-companded) RGB values for the object (three values between 0 and 1).
   #

data/lib/redgreenblue/gif.rb

@@ -1,4 +1,4 @@
-class RGB
+class RGB::Color
 
   # Returns a 1-pixel GIF image set to the color.
   #

data/lib/redgreenblue/gpl.rb

@@ -1,18 +1,14 @@
-class RGB
-
-  #----------------------------------------------------------------------#
-  #                            Class Methods                             #
-  #----------------------------------------------------------------------#
+class RGB::Color
 
   class << self
 
-    # Creates a new RGB object from a line of gpl (Gimp color palette) input. Returns nil if not successful.
+    # Creates a new RGB::Color from a line of gpl (Gimp color palette) input. Returns nil if not successful.
     #
     # @example
-    #  RGB.gpl "255 153 204\tpink"
+    #  RGB::Color.gpl "255 153 204\tpink"
     def gpl(line)
       if line.chomp.match( /^\s*(?<r>\d{1,3})\s+(?<g>\d{1,3})\s+(?<b>\d{1,3})(\s+(?<name>.*))?/ )
-        color = RGB.rgb $~[:r].to_i, $~[:g].to_i, $~[:b].to_i
+        color = RGB::Color.rgb $~[:r].to_i, $~[:g].to_i, $~[:b].to_i
         color.name = $~[:name] if $~[:name]
         color
       else
@@ -20,7 +16,46 @@ class RGB
       end
     end
 
-    # Loads a gpl (Gimp color palette) source and returns an array of RGB objects.
+  end
+
+
+  # Returns the color in the format used in .gpl files (Gimp color palettes), including its name (if present).
+  #
+  # You can optionally supply a name as argument.
+  def gpl(gpl_name=name)
+    ( "%3d %3d %3d" % rgb ) +
+    ( gpl_name.to_s.size != 0 ? "\t#{gpl_name}" : '' )
+  end
+
+end
+
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color from a line of gpl (Gimp color palette) input. Returns nil if not successful.
+    #
+    # @example
+    #  RGB.gpl "255 153 204\tpink"
+    def gpl(line)
+      Color.gpl(line)
+    end
+
+    # Returns a header for a .gpl file (Gimp color palette). Includes an optional name and number of columns.
+    #
+    # @example
+    #  RGB.gpl_header('Spring')
+    #
+    # Reverse-engineered from:
+    # - https://github.com/GNOME/gimp/blob/5d79fba8238a27b8691556489898d33b3fa0dda0/app/core/gimppalette-load.c
+    def gpl_header(name=nil, columns: nil)
+      "GIMP Palette\n" +
+      ( name    ? "Name: #{name}\n"       : '' ) +
+      ( columns ? "Columns: #{columns}\n" : '' )
+    end
+
+    # Loads a gpl (Gimp color palette) source and returns an array of RGB::Color objects.
     #
     # Options:
     # - file: Path to a .gpl file to be loaded.
@@ -47,7 +82,7 @@ class RGB
       end
 
       if source.respond_to? :each_line
-        list = source.each_line.map { |line| RGB.gpl(line) }
+        list = source.each_line.map { |line| Color.gpl(line) }
 
         if compact
           list.compact!
@@ -64,31 +99,6 @@ class RGB
       end
     end
 
-    # Returns a header for a .gpl file (Gimp color palette). Includes an optional name and number of columns.
-    #
-    # @example
-    #  RGB.gpl_header('Spring')
-    #
-    # Reverse-engineered from:
-    # - https://github.com/GNOME/gimp/blob/5d79fba8238a27b8691556489898d33b3fa0dda0/app/core/gimppalette-load.c
-    def gpl_header(name=nil, columns: nil)
-      "GIMP Palette\n" +
-      ( name    ? "Name: #{name}\n"       : '' ) +
-      ( columns ? "Columns: #{columns}\n" : '' )
-    end
-
-  end
-
-  #----------------------------------------------------------------------#
-  #                           Instance Methods                           #
-  #----------------------------------------------------------------------#
-
-  # Returns the color in the format used in .gpl files (Gimp color palettes), including its name (if present).
-  #
-  # You can optionally supply a name as argument.
-  def gpl(gpl_name=name)
-    ( "%3d %3d %3d" % rgb ) +
-    ( gpl_name.to_s.size != 0 ? "\t#{gpl_name}" : '' )
   end
 
 end

data/lib/redgreenblue/hex.rb

@@ -1,4 +1,4 @@
-class RGB
+class RGB::Color
 
   # Returns a 6-digit hexadecimal string representing the object's red, green, and blue components as 8-bit values.
   #
@@ -22,11 +22,14 @@ class RGB
     end
   end
 
+  private
 
-# Class methods
+  def hex6
+    '%02x%02x%02x' % [ r, g, b ]
+  end
 
 
-  # Creates a new object from a 6- or 3-digit hexadecimal string representing red, green, and blue.
+  # Creates a new RGB::Color from a 6- or 3-digit hexadecimal string representing red, green, and blue.
   #
   # The string may include a '#' prefix.
   def self.hex(hex_string)
@@ -37,31 +40,40 @@ class RGB
     end
   end
 
-  # Returns a 3-digit shorthand version of a 6-digit hexadecimal string.
-  #
-  # If a shorthand version is not possible, returns the original string.
-  def self.hex_shorthand(hex_string)
-    hex_string.sub( /^(#?)(\h)\2(\h)\3(\h)\4$/, '\1\2\3\4' )
-  end
+end
 
-  # Parses a 6- or 3-digit hexadecimal string.
-  # Returns three integers in the range 0..255, or nil if not successful.
-  #
-  # The string may include a '#' prefix.
-  def self.hex_to_rgb(hex_string)
-    if hex_string =~ /^(#?)(\h\h)(\h\h)(\h\h)$/
-      [$2, $3, $4].map { |h| h.to_i(16) }
-    elsif hex_string =~ /^(#?)(\h)(\h)(\h)$/
-      [$2, $3, $4].map { |h| (h*2).to_i(16) }
-    else
-      nil
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color from a 6- or 3-digit hexadecimal string representing red, green, and blue.
+    #
+    # The string may include a '#' prefix.
+    def hex(hex_string)
+      Color.hex(hex_string)
     end
-  end
 
-  private
+    # Returns a 3-digit shorthand version of a 6-digit hexadecimal string.
+    #
+    # If a shorthand version is not possible, returns the original string.
+    def hex_shorthand(hex_string)
+      hex_string.sub( /^(#?)(\h)\2(\h)\3(\h)\4$/, '\1\2\3\4' )
+    end
+
+    # Parses a 6- or 3-digit hexadecimal string.
+    # Returns three integers in the range 0..255, or nil if not successful.
+    #
+    # The string may include a '#' prefix.
+    def hex_to_rgb(hex_string)
+      if hex_string =~ /^(#?)(\h\h)(\h\h)(\h\h)$/
+        [$2, $3, $4].map { |h| h.to_i(16) }
+      elsif hex_string =~ /^(#?)(\h)(\h)(\h)$/
+        [$2, $3, $4].map { |h| (h*2).to_i(16) }
+      else
+        nil
+      end
+    end
 
-  def hex6
-    '%02x%02x%02x' % [ r, g, b ]
   end
 
 end

data/lib/redgreenblue/hsb.rb

@@ -1,22 +1,14 @@
 require 'redgreenblue/hsv'
 
-class RGB
-
-  #----------------------------------------------------------------------#
-  #                            Class Methods                             #
-  #----------------------------------------------------------------------#
+class RGB::Color
 
   class << self
 
-    # Creates a new RGB object from HSB values: hue (0..360), saturation (0..1), and brightness (0..1).
+    # Creates a new RGB::Color from HSB values: hue (0..360), saturation (0..1), and brightness (0..1).
     alias hsb hsv
 
   end
 
-  #----------------------------------------------------------------------#
-  #                           Instance Methods                           #
-  #----------------------------------------------------------------------#
-
   # Returns color as HSB:
   # hue (0..360), saturation (0..1), brightness (0..1).
   # When saturation is 0, hue is nil.
@@ -55,7 +47,19 @@ class RGB
   # Sets red, green, and blue by rotating the object's HSB-hue a number of degrees.
   alias hsb_rotate! hsv_rotate!
 
-  # Creates one or more new RGB objects by rotating this object's HSB-hue a number of degrees.
+  # Creates one or more new RGB::Color objects by rotating this object's HSB-hue a number of degrees.
   alias hsb_rotate  hsv_rotate
 
 end
+
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color from HSB values: hue (0..360), saturation (0..1), and brightness (0..1).
+    alias hsb hsv
+
+  end
+
+end