redgreenblue 0.7.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dea62bd74822100097e661284f2d44164a1be23ee0f81acdc778c182f0939ec
-  data.tar.gz: baa4c5ab0b3a367841ee18d94131ad4077661d515edb29939ed661175b479ee1
+  metadata.gz: 28b5f73bd443540e199b93625df5c7447491b502573abe5aa14089f895fd2700
+  data.tar.gz: c0a3c77946d5a4d0e6c43d5769385a6c5b72df52c9f7a4cfb52d09bdc50a5153
 SHA512:
-  metadata.gz: 81808e69a0aadb6ea54cb291fd682c1949e2178df1c31954256167552f12b990ef825561689a958cb533144c25d31852785ebcebe9d07ddb5684b3b0dfcd26ba
-  data.tar.gz: 62370184d5b291081bd8e7a1f698647d961fd4c98525677821950f59e58e5536473d5f4c0e87da53109866e875caf94fc578fdf14d4de602d50fd0085d4fe6d9
+  metadata.gz: 20b4959b4e82fdf67b48dbff3a0c82713a960c56a5bed7e32a78782cab40f1fb9d0f71c2d2fe93cef887a3c97a2590133a85d68b8d57912d7ec0bc4a0817febe
+  data.tar.gz: bdc13584341d62b90586cf768cd114079e223e64424e0e9e6c24e4398ae74746f2530ed7e2c7540071cf99a4df4afe3a2e7bdadd7c2d0d3dbc6e5d595047d7f7

data/lib/redgreenblue.rb

@@ -1,24 +1,30 @@
 class RGB
 end
 
-require 'redgreenblue/version'
+%w(
 
-require 'redgreenblue/base'
+  version
 
-require 'redgreenblue/24bit'
-require 'redgreenblue/48bit'
-require 'redgreenblue/hex'
+  base
 
-require 'redgreenblue/hsl_hsv'
+  24bit 48bit hex int
 
-require 'redgreenblue/lazy'
-require 'redgreenblue/nice'
+  hsl hsv hsb
 
-require 'redgreenblue/rgb565'
-require 'redgreenblue/bgr24bit'
-require 'redgreenblue/gif'
+  ostwald
 
-require 'redgreenblue/misc'
-require 'redgreenblue/random'
+  gamma
 
-require 'redgreenblue/os'
+  cie_1931 cie_1976
+
+  name
+
+  inspect view lazy
+
+  rgb565 bgr24bit gif terminal web gpl
+
+  mix misc random
+
+  os
+
+).each { |m| require "redgreenblue/#{m}" }

data/lib/redgreenblue/24bit.rb

@@ -51,4 +51,30 @@ class RGB
     c
   end
 
+  # Sets the red, green, and blue values to those of the nearest 24-bit color.
+  def snap!
+    self.rgb = rgb
+    self
+  end
+
+  # Creates a new RGB object 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
+      end
+    end
+    range.size ** 3
+  end
+
 end

data/lib/redgreenblue/base.rb

@@ -1,41 +1,73 @@
 class RGB
 
-  attr_reader :red, :green, :blue
-
   def initialize(*a)
     self.values = a.any? ? a : [ 0.5, 0.5, 0.5 ]
   end
 
-  def red=(n)
-    @red = limit(n)
+  # Returns the color space.
+  #
+  # Currently always 'sRGB'.
+  def color_space
+    'sRGB'
+  end
+
+  # Returns the red component as a value between 0 and 1.
+  def red
+    @red
+  end
+
+  # Returns the green component as a value between 0 and 1.
+  def green
+    @green
+  end
+
+  # Returns the blue component as a value between 0 and 1.
+  def blue
+    @blue
+  end
+
+  # Sets the red component to a value between 0 and 1.
+  #
+  # Values outside the range 0..1 will be clipped.
+  def red=(value)
+    @red = limit(value)
   end
 
-  def green=(n)
-    @green = limit(n)
+  # Sets the green component to a value between 0 and 1.
+  #
+  # Values outside the range 0..1 will be clipped.
+  def green=(value)
+    @green = limit(value)
   end
 
-  def blue=(n)
-    @blue = limit(n)
+  # Sets the blue component to a value between 0 and 1.
+  #
+  # Values outside the range 0..1 will be clipped.
+  def blue=(value)
+    @blue = limit(value)
   end
 
+  # Returns the red, green, and blue components as three values between 0 and 1.
   def values
     [ red, green, blue ]
   end
 
   alias to_a values
 
+  # Sets the red, green, and blue components using three values between 0 and 1.
+  #
+  # Values outside the range 0..1 will be clipped.
   def values=(*a)
     self.red, self.green, self.blue = a.flatten
   end
 
-  # Returns true if this object and an other object represent exactly the same color. Otherwise returns false.
+  # Returns true if this object and another object represent exactly the same color. Otherwise returns false.
   def ==(other)
     ( self.class == other.class ) && ( self.values == other.values )
   end
 
-  # Returns a sorted hash of 3 key/value pairs
-  # for red, green and blue,
-  # sorted in order of decreasing value
+  # Returns a sorted hash of 3 key/value pairs for red, green, and blue,
+  # sorted in order of decreasing value.
   def to_h
     ([:red, :green, :blue].zip values).sort_by {
       |k,v| [-v,[:red, :green, :blue].index(k)]
@@ -44,7 +76,7 @@ class RGB
 
   private
 
-  # limit to 0..1
+  # limits to range 0..1
   def limit(n)
     n <= 0 ? 0.0 : n >= 1 ? 1.0 : n
   end

data/lib/redgreenblue/bgr24bit.rb

@@ -1,16 +1,16 @@
 class RGB
 
-# bgr 24-bit methods (as used by BMP bitmaps)
-
+  # Returns a 3-byte string containing the object's color in BGR24 format.
   def bgr24
     [b, g, r].pack('C3')
   end
 
-  def bgr24=(s)
-    self.b, self.g, self.r = s.unpack('C3')
+  # Sets red, green, and blue using BGR24 data (a 3-byte string).
+  def bgr24=(bgr_string)
+    self.b, self.g, self.r = bgr_string.unpack('C3')
   end
 
-  # factory method
+  # Creates a new RGB object from BGR24 data (a 3-byte string).
   def self.bgr24(bgr)
     c = self.new
     c.bgr24 = bgr

data/lib/redgreenblue/cie_1931.rb

@@ -0,0 +1,51 @@
+class RGB
+
+  # Returns CIE 1931 XYZ values for the RGB object.
+  #
+  # Based on:
+  # - http://www.brucelindbloom.com/index.html?Eqn_RGB_to_XYZ.html
+  # - https://en.wikipedia.org/wiki/CIE_1931_color_space
+  # sRGB to XYZ matrix for D65 reference white calculated with Javascript by Bruce Lindbloom:
+  # - http://www.brucelindbloom.com/ColorCalculator.html
+  def cie_xyz(round: true)
+    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.
+  #
+  # 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
+    x, y, z = cie_xyz(round: false)
+
+    [
+
+      x / ( x + y + z ),
+      y / ( x + y + z ),
+      y
+
+    ].map { |v| v.round(8) }
+  end
+
+  alias xyy cie_xyy
+
+  # Returns CIE 1931 xy values for the RGB object.
+  def cie_xy
+    cie_xyy[0..1]
+  end
+
+  alias xy cie_xy
+
+end

data/lib/redgreenblue/cie_1976.rb

@@ -0,0 +1,105 @@
+class RGB
+
+  # Returns CIE 1976 L*a*b* (CIELAB) values for the RGB 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).
+  #
+  # 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.
+  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).
+  #
+  # When C is 0, H is nil.
+  def cie_lch_uv
+    cie_lch_ab_uv(type: :luv)
+  end
+
+  # Returns the object's color distance from another RGB object, according to the CIE 1976 delta E formula.
+  #
+  # Based on:
+  # - http://www.brucelindbloom.com/Eqn_DeltaE_CIE76.html
+  # - https://en.wikipedia.org/wiki/Color_difference
+  def delta_e_cie_1976(another)
+    l , a , b  =         cie_lab(round: false)
+    l2, a2, b2 = another.cie_lab(round: false)
+
+    Math.sqrt( (l - l2) ** 2 + (a - a2) ** 2 + (b - b2) ** 2 ).round(8)
+  end
+
+  alias de76 delta_e_cie_1976
+
+  private
+
+  # Returns either CIE 1976 L*a*b* (CIELAB) or CIE 1976 L*u*v* (CIELUV) values for the RGB object.
+  #
+  # L*a*b* formula based on:
+  # - http://www.brucelindbloom.com/Eqn_XYZ_to_Lab.html
+  # - https://en.wikipedia.org/wiki/CIELAB_color_space
+  # With peeking at:
+  # - https://github.com/halostatue/color/blob/master/lib/color/rgb.rb
+  #
+  # L*u*v* formula based on:
+  # - http://www.brucelindbloom.com/Eqn_XYZ_to_Luv.html
+  # - https://en.wikipedia.org/wiki/CIELUV
+  def cie_lab_luv(round: true, type: :lab)
+    x , y , z  =           cie_xyz(round: false)
+    xr, yr, zr = RGB.white.cie_xyz(round: false)
+
+    f = [ x / xr, y / yr, z / zr ].map { |v|
+      if v > ( 216.0 / 24389 )
+        v ** ( 1.0 / 3 ) # cube root
+      else
+        ( 24389.0 / 27 * v + 16 ) / 116.0
+      end
+    }
+
+    if type == :luv
+      [
+        l = 116 * f[1] - 16,
+        13 * l * ( ( 4 * x ) / ( x + 15 * y + 3 * z ) - ( 4 * xr ) / ( xr + 15 * yr + 3 * zr ) ),
+        13 * l * ( ( 9 * y ) / ( x + 15 * y + 3 * z ) - ( 9 * yr ) / ( xr + 15 * yr + 3 * zr ) )
+      ]
+    else
+      [
+        116 *  f[1] - 16,
+        500 * (f[0] - f[1]),
+        200 * (f[1] - f[2])
+      ]
+    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.
+  #
+  # Based on:
+  # - http://www.brucelindbloom.com/Eqn_Lab_to_LCH.html
+  # - http://www.brucelindbloom.com/Eqn_Luv_to_LCH.html
+  # - https://en.wikipedia.org/wiki/CIELAB_color_space
+  def cie_lch_ab_uv(type: :lab)
+    if type == :luv
+      l, v1, v2 = cie_luv(round: false)
+    else
+      l, v1, v2 = cie_lab(round: false)
+    end
+
+    [
+      l.round(8),
+      c = ( ( v1 ** 2 + v2 ** 2) ** ( 1.0 / 2 ) ).round(8),
+      c == 0 ? nil : ( Math.atan2(v2, v1) * 180.0 / Math::PI ).modulo(360).round(8)
+    ]
+  end
+
+end

data/lib/redgreenblue/gamma.rb

@@ -0,0 +1,44 @@
+class RGB
+
+  # Returns gamma-expanded (inverse-companded) RGB values for the object (three values between 0 and 1).
+  #
+  # Based on:
+  # - https://en.wikipedia.org/wiki/SRGB
+  # - http://www.brucelindbloom.com/Eqn_RGB_to_XYZ.html
+  # - https://entropymine.com/imageworsener/srgbformula/
+  def linear_values
+    if color_space == 'sRGB'
+      values.map { |v|
+        if v <= 0.04045
+          v / 12.92
+        else
+          ( ( v + 0.055 ) / 1.055 ) ** 2.4
+        end
+      }
+    else
+      raise "can not compute gamma for color space '#{color_space}'"
+    end
+  end
+
+  # Sets the object's RGB values using three linear RGB values, each between 0 and 1.
+  # Linear values will be converted to the object's gamma (gamma-companded).
+  #
+  # Based on:
+  # - https://en.wikipedia.org/wiki/SRGB
+  # - http://www.brucelindbloom.com/Eqn_XYZ_to_RGB.html
+  # - https://entropymine.com/imageworsener/srgbformula/
+  def linear_values=(*a)
+    if color_space == 'sRGB'
+      self.values = a.flatten.map { |v|
+        if v <= 0.0031308
+          v * 12.92
+        else
+          1.055 * ( v ** ( 1/2.4 ) ) - 0.055
+        end
+      }.map { |v| v.round(9) }
+    else
+      raise "can not compute gamma for color space '#{color_space}'"
+    end
+  end
+
+end

data/lib/redgreenblue/gpl.rb

@@ -0,0 +1,91 @@
+class RGB
+
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
+
+  class << self
+
+    # Creates a new RGB 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)
+      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.name = $~[:name] if $~[:name]
+        color
+      else
+        nil
+      end
+    end
+
+    # Loads a gpl (Gimp color palette) source and returns an array of RGB objects.
+    #
+    # Options:
+    # - file: Path to a .gpl file to be loaded.
+    # - url: URL for a .gpl source to be loaded.
+    # - compact: Defaults to true. If set to false, returns nil for each line that can not be parsed to an RGB color.
+    # - freeze: Defaults to false. If set to true, returns a frozen array of frozen objects.
+    #
+    # @example String
+    #  RGB.load_gpl "255 0 0\tred\n255 153 204\tpink\n"
+    # @example File
+    #  RGB.load_gpl file: '/path/to/palette.gpl'
+    #  RGB.load_gpl file: '/path/to/palette.gpl', compact: false
+    # @example URL
+    #  RGB.load_gpl url: 'https://lospec.com/palette-list/yuko-tomita-time.gpl'
+    def load_gpl(source=nil, file: nil, url: nil, compact: true, freeze: false)
+
+      if ! source
+        if file
+          source = File.open file
+        elsif url
+          require 'open-uri'
+          source = URI.open url
+        end
+      end
+
+      if source.respond_to? :each_line
+        list = source.each_line.map { |line| RGB.gpl(line) }
+
+        if compact
+          list.compact!
+        end
+
+        if freeze
+          list.freeze
+          list.each &:freeze
+        end
+
+        list
+      else
+        raise ArgumentError, 'Not a valid source'
+      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