redgreenblue 0.6.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cac7c885ca1de3e3fe22ebfaf7207dd17b7bd25e8c1dd6f82cfdab0e0b5cee1
-  data.tar.gz: 7ca71212d78ae2a638d8bfb54dcb8a824367eac6e7fe8ca1eaa1e239b22bbaa9
+  metadata.gz: dc4e866d75637857fb5a4b27b77829e20f488e321fa287b73a5d6d9c21d194a9
+  data.tar.gz: e3f9e875b0a8893bd21a6cd503702881833f54873557f84c4cf4776338294668
 SHA512:
-  metadata.gz: 23316f3526690807fabde09d5a909ae7afe396da7b039baa6352c814ab653d02ee5646aa23ece364748cf090f4b9218a34c0cd19b8a04313086b2c5f9dcadf97
-  data.tar.gz: 19f71a26312a83d845f8ff508758e653b693289be129e02281e65cb8da4b13d32ab5b58282883ea0d0dc4c156ddd775c0179354bea5dccc6065f00ad49b7f66c
+  metadata.gz: 94b96125e65443d7ceb66cfabf9ba6b0681bfc51046b8d308e86d0904a58a7f745f6ea159a040ee79dcb9713ace9adbc416a5705c4b2ebb85333bf09f0dd9a43
+  data.tar.gz: f3e0bd4c0cdcd432dd50fc518f1d2062c66ac907f55b3235405589b2d797791c48b3d62284ae665a8fc4d60c4209ce0b3d46d07a459e15d2fa261d9b1aa8df1d

data/lib/redgreenblue.rb

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

data/lib/redgreenblue/24bit.rb

@@ -2,46 +2,79 @@ class RGB
 
 # r, g, b methods
 
+  # Returns the red component as an integer in the range 0..255 (an 8-bit value).
   def r
     (red   * 255).round
   end
 
+  # Returns the green component as an integer in the range 0..255 (an 8-bit value).
   def g
     (green * 255).round
   end
 
+  # Returns the blue component as an integer in the range 0..255 (an 8-bit value).
   def b
     (blue  * 255).round
   end
 
+  # Sets the red component using an integer in the range 0..255 (an 8-bit value).
   def r=(n)
     self.red   = n / 255.0
   end
 
+  # Sets the green component using an integer in the range 0..255 (an 8-bit value).
   def g=(n)
     self.green = n / 255.0
   end
 
+  # Sets the blue component using an integer in the range 0..255 (an 8-bit value).
   def b=(n)
     self.blue  = n / 255.0
   end
 
 # rgb methods
 
+  # Returns the red, green, and blue components as integers in the range 0..255 (three 8-bit values).
   def rgb
     [r,g,b]
   end
 
-  def rgb=(rgb)
-    self.r, self.g, self.b = rgb
+  # Sets the red, green, and blue components using three integers in the range 0..255 (three 8-bit values).
+  def rgb=(*rgb)
+    self.r, self.g, self.b = rgb.flatten
   end
 
-# factory method
-
-  def self.rgb(rgb)
+  # Creates a new 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
     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/48bit.rb

@@ -2,43 +2,50 @@ class RGB
 
 # rr, gg, bb methods
 
+  # Returns the red component as an integer in the range 0..65535 (a 16-bit value).
   def rr
     (red   * 65535).round
   end
 
+  # Returns the green component as an integer in the range 0..65535 (a 16-bit value).
   def gg
     (green * 65535).round
   end
 
+  # Returns the blue component as an integer in the range 0..65535 (a 16-bit value).
   def bb
     (blue  * 65535).round
   end
 
+  # Sets the red component using an integer in the range 0..65535 (a 16-bit value).
   def rr=(n)
     self.red   = n / 65535.0
   end
 
+  # Sets the green component using an integer in the range 0..65535 (a 16-bit value).
   def gg=(n)
     self.green = n / 65535.0
   end
 
+  # Sets the blue component using an integer in the range 0..65535 (a 16-bit value).
   def bb=(n)
     self.blue  = n / 65535.0
   end
 
 # rrggbb methods
 
+  # Returns the red, green, and blue components as integers in the range 0..65535 (three 16-bit values).
   def rrggbb
     [rr,gg,bb]
   end
 
-  def rrggbb=(rrggbb)
-    self.rr, self.gg, self.bb = rrggbb
+  # Sets the red, green, and blue components using three integers in the range 0..65535 (three 16-bit values).
+  def rrggbb=(*rrggbb)
+    self.rr, self.gg, self.bb = rrggbb.flatten
   end
 
-# factory method
-
-  def self.rrggbb(rrggbb)
+  # Creates a new 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
     c

data/lib/redgreenblue/base.rb

@@ -1,36 +1,82 @@
 class RGB
 
-  attr_reader :red, :green, :blue
+  def initialize(*a)
+    self.values = a.any? ? a : [ 0.5, 0.5, 0.5 ]
+  end
+
+  # Returns the color space.
+  #
+  # Currently always 'sRGB'.
+  def color_space
+    @color_space ||= 'sRGB'
+  end
 
-  def initialize(a=[0.5, 0.5, 0.5])
-    self.values = a
+  # Returns the red component as a value between 0 and 1.
+  def red
+    @red
   end
 
-  def red=(n)
-    @red = limit(n)
+  # Returns the green component as a value between 0 and 1.
+  def green
+    @green
   end
 
-  def green=(n)
-    @green = limit(n)
+  # Returns the blue component as a value between 0 and 1.
+  def blue
+    @blue
   end
 
-  def blue=(n)
-    @blue = limit(n)
+  # 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
 
+  # 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
+
+  # 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
 
-  def values=(a)
-    self.red, self.green, self.blue = a
+  # 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 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.
+  def to_h
+    ([:red, :green, :blue].zip values).sort_by {
+      |k,v| [-v,[:red, :green, :blue].index(k)]
+    }.to_h
   end
 
   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.rb

@@ -0,0 +1,45 @@
+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 by Bruce Lindbloom:
+  # - http://www.brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html
+  def cie_xyz
+    r, g, b = linear_values
+    [
+      r * 0.4124564 + g * 0.3575761 + b * 0.1804375,
+      r * 0.2126729 + g * 0.7151522 + b * 0.0721750,
+      r * 0.0193339 + g * 0.1191920 + b * 0.9503041
+    ].map { |v| v.round(6) }
+  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 = xyz
+    [
+      x / ( x + y + z ),
+      y / ( x + y + z ),
+      y
+    ].map { |v| v.round(6) }
+  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/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/gif.rb

@@ -1,15 +1,16 @@
 class RGB
 
-  # Return a 1-pixel GIF
+  # Returns a 1-pixel GIF image set to the color.
   #
   # With help from:
-  # - http://www.perlmonks.org/?node_id=7974
+  # - https://www.perlmonks.org/?node_id=7974
   def gif_pixel
     "GIF89a\1\0\1\0\x90\0\0".b +
     rgb.pack('C3') +
     "\0\0\0,\0\0\0\0\1\0\1\0\0\x02\x02\x04\1\0;".b
   end
 
+  # Writes a 1-pixel GIF image to a file.
   def gif_pixel_write(file_path)
     File.binwrite(file_path, gif_pixel)
   end

data/lib/redgreenblue/gpl.rb

@@ -0,0 +1,30 @@
+class RGB
+
+  ########################################################################
+  # Class methods                                                        #
+  ########################################################################
+
+  class << self
+
+    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). A name for the color is optional.
+  def gpl(name=nil)
+    ( "%3d %3d %3d" % rgb ) + ( name ? "\t#{name}" : '' )
+  end
+
+end