redgreenblue 0.13.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65191c26a6dcae9a6bb52abe182d376e0975b79672686120185c9a2b3d49e4e9
-  data.tar.gz: 3fb9dc542660f5edaec8283a2e74ec0687e369e05475bf6840344ca5cca0304f
+  metadata.gz: f836ad38758f98dc7f9d677e9bf97dcfd878a09e994622b16b4854d1bff01277
+  data.tar.gz: 938a0a5efefa5c4f181bccdb996be922ad51d8dfd7cfe623209d4582aa19d4e5
 SHA512:
-  metadata.gz: 4c0d6a47aa611822dba62189c14ebf38c0ef6315f08ac9b5eb9efe04b28487d2c95105c0e86536cb52fdc9ce36df445d060623a14e99f2dbab34df5e0d10e515
-  data.tar.gz: 756bdaa8c6859c685e51342ee8a6d34e7340ea0580bd79b4487443d97b04629ed1b7c8f1631bf3ac26a5570e6c243aba7f7b931243ea967f07d8437fa223d495
+  metadata.gz: c40b54efa01653b785065707a57841fd156ba6238a4eccbc09454f969b1cfd08439bbb70431de985874606fe88115e7688dc2e8819c83335bbfd17a0c339a557
+  data.tar.gz: 4a7cdf6351af6e718ac857aaf87c052f1fc85110aca42eb049a22e18f63c25188a5e0189713ff46fa9ee7573e5a4d7729979fdf892a6c1a1f992fd127045618c

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 Color object 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
@@ -62,19 +62,36 @@ class RGB
     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 Methods                            #
+#----------------------------------------------------------------------#
+
+module RGB
+
+  class << self
+
+    # Creates a new Color object 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 Color object 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,20 @@ class RGB
   end
 
 end
+
+#----------------------------------------------------------------------#
+#                            Module Methods                            #
+#----------------------------------------------------------------------#
+
+module RGB
+
+  class << self
+
+    # Creates a new Color object 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 Color object 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 object from BGR24 data (a 3-byte string).
   def self.bgr24(bgr)
     c = self.new
     c.bgr24 = bgr
@@ -18,3 +18,20 @@ class RGB
   end
 
 end
+
+#----------------------------------------------------------------------#
+#                            Module Methods                            #
+#----------------------------------------------------------------------#
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color object 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,6 @@
-class RGB
+class RGB::Color
 
-  # Returns CIE 1931 XYZ values for the RGB object.
+  # Returns CIE 1931 XYZ values for the RGB::Color object.
   #
   # Based on:
   # - http://www.brucelindbloom.com/index.html?Eqn_RGB_to_XYZ.html
@@ -21,7 +21,7 @@ class RGB
 
   alias xyz cie_xyz
 
-  # Returns CIE 1931 xyY values for the RGB object.
+  # Returns CIE 1931 xyY values for the RGB::Color object.
   #
   # Based on:
   # - https://en.wikipedia.org/wiki/CIE_1931_color_space
@@ -41,7 +41,7 @@ class RGB
 
   alias xyy cie_xyy
 
-  # Returns CIE 1931 xy values for the RGB object.
+  # Returns CIE 1931 xy values for the RGB::Color object.
   def cie_xy
     cie_xyy[0..1]
   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,4 +1,4 @@
-class RGB
+class RGB::Color
 
   #----------------------------------------------------------------------#
   #                            Class Methods                             #
@@ -6,13 +6,13 @@ class RGB
 
   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 object 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 +20,49 @@ class RGB
       end
     end
 
-    # Loads a gpl (Gimp color palette) source and returns an array of RGB objects.
+  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
+
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color object 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 +89,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,28 +106,6 @@ class RGB
       end
     end
 
-    private
-
-    # Reverse-engineered from:
-    # - https://github.com/GNOME/gimp/blob/5d79fba8238a27b8691556489898d33b3fa0dda0/app/core/gimppalette-load.c
-    def gpl_header(name, columns=nil)
-      "GIMP Palette\n" +
-      "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,17 @@ class RGB
     end
   end
 
+  private
 
-# Class methods
+  def hex6
+    '%02x%02x%02x' % [ r, g, b ]
+  end
 
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
 
-  # Creates a new object from a 6- or 3-digit hexadecimal string representing red, green, and blue.
+  # Creates a new Color object 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 +43,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 Color object 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,6 +1,6 @@
 require 'redgreenblue/hsv'
 
-class RGB
+class RGB::Color
 
   #----------------------------------------------------------------------#
   #                            Class Methods                             #
@@ -8,7 +8,7 @@ class RGB
 
   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 object from HSB values: hue (0..360), saturation (0..1), and brightness (0..1).
     alias hsb hsv
 
   end
@@ -55,7 +55,22 @@ 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 Methods                            #
+#----------------------------------------------------------------------#
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color object from HSB values: hue (0..360), saturation (0..1), and brightness (0..1).
+    alias hsb hsv
+
+  end
+
+end

data/lib/redgreenblue/hsl.rb

@@ -1,7 +1,7 @@
 require 'redgreenblue/hsx_shared'
 require 'redgreenblue/math'
 
-class RGB
+class RGB::Color
 
   #----------------------------------------------------------------------#
   #                            Class Methods                             #
@@ -9,7 +9,7 @@ class RGB
 
   class << self
 
-    # Creates a new RGB object from HSL values: hue (0..360), saturation (0..1), and lightness (0..1).
+    # Creates a new RGB::Color object from HSL values: hue (0..360), saturation (0..1), and lightness (0..1).
     def hsl(*a)
       new hsl_to_values(*a)
     end
@@ -51,7 +51,7 @@ class RGB
 
   # Sets red, green, and blue using HSL values: hue (0..360), saturation (0..1), and lightness (0..1).
   def hsl=(*a)
-    self.values = RGB.hsl_to_values(*a)
+    self.values = RGB::Color.hsl_to_values(*a)
   end
 
   # Sets HSL-hue to a number of degrees (0..360) or nil.
@@ -84,7 +84,7 @@ class RGB
     self
   end
 
-  # Creates one or more new RGB objects by rotating this object's HSL-hue a number of degrees.
+  # Creates one or more new RGB::Color objects by rotating this object's HSL-hue a number of degrees.
   def hsl_rotate(a_degrees, *b_degrees)
     if a_degrees.class != Array and b_degrees.none?
       RGB.hsl zip_add(hsl, [a_degrees, 0, 0])
@@ -94,3 +94,20 @@ class RGB
   end
 
 end
+
+#----------------------------------------------------------------------#
+#                            Module Methods                            #
+#----------------------------------------------------------------------#
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color object from HSL values: hue (0..360), saturation (0..1), and lightness (0..1).
+    def hsl(*a)
+      Color.hsl(*a)
+    end
+
+  end
+
+end

data/lib/redgreenblue/hsv.rb

@@ -1,7 +1,7 @@
 require 'redgreenblue/hsx_shared'
 require 'redgreenblue/math'
 
-class RGB
+class RGB::Color
 
   #----------------------------------------------------------------------#
   #                            Class Methods                             #
@@ -9,7 +9,7 @@ class RGB
 
   class << self
 
-    # Creates a new RGB object from HSV values: hue (0..360), saturation (0..1), and value (0..1).
+    # Creates a new RGB::Color object from HSV values: hue (0..360), saturation (0..1), and value (0..1).
     def hsv(*a)
       new hsv_to_values(*a)
     end
@@ -51,7 +51,7 @@ class RGB
 
   # Sets red, green, and blue using HSV values: hue (0..360), saturation (0..1), and value (0..1).
   def hsv=(*a)
-    self.values = RGB.hsv_to_values(*a)
+    self.values = RGB::Color.hsv_to_values(*a)
   end
 
   # Sets HSV-hue to a number of degrees (0..360) or nil.
@@ -84,7 +84,7 @@ class RGB
     self
   end
 
-  # Creates one or more new RGB objects by rotating this object's HSV-hue a number of degrees.
+  # Creates one or more new RGB::Color objects by rotating this object's HSV-hue a number of degrees.
   def hsv_rotate(a_degrees, *b_degrees)
     if a_degrees.class != Array and b_degrees.none?
       RGB.hsv zip_add(hsv, [a_degrees, 0, 0])
@@ -94,3 +94,20 @@ class RGB
   end
 
 end
+
+#----------------------------------------------------------------------#
+#                            Module Methods                            #
+#----------------------------------------------------------------------#
+
+module RGB
+
+  class << self
+
+    # Creates a new RGB::Color object from HSV values: hue (0..360), saturation (0..1), and value (0..1).
+    def hsv(*a)
+      Color.hsv(*a)
+    end
+
+  end
+
+end

data/lib/redgreenblue/hsx_shared.rb

@@ -1,4 +1,4 @@
-class RGB
+class RGB::Color
 
   #----------------------------------------------------------------------#
   #                            Class Methods                             #

data/lib/redgreenblue/hwb.rb

@@ -0,0 +1,14 @@
+class RGB::Color
+
+  # Returns the color's hue (0..360), whiteness (0..1), and blackness (0..1), as defined by the HWB color model.
+  #
+  # For achromatic colors, hue is nil.
+  #
+  # Based on:
+  # - http://alvyray.com/Papers/CG/HWB_JGTv208.pdf (PDF)
+  # - https://en.wikipedia.org/wiki/HWB_color_model
+  def hwb
+    [ hsv_h, cwk[1,2] ].flatten
+  end
+
+end