redgreenblue 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dea62bd74822100097e661284f2d44164a1be23ee0f81acdc778c182f0939ec
-  data.tar.gz: baa4c5ab0b3a367841ee18d94131ad4077661d515edb29939ed661175b479ee1
+  metadata.gz: 766113ae54ad00c066d264e8bd8d63610f5347e75d95aee3c34bacac0b027a99
+  data.tar.gz: a91d7d49e36ebfc29328e32c2aa67df908e4fbc9d36c4ec957e1e6d8ed3220b7
 SHA512:
-  metadata.gz: 81808e69a0aadb6ea54cb291fd682c1949e2178df1c31954256167552f12b990ef825561689a958cb533144c25d31852785ebcebe9d07ddb5684b3b0dfcd26ba
-  data.tar.gz: 62370184d5b291081bd8e7a1f698647d961fd4c98525677821950f59e58e5536473d5f4c0e87da53109866e875caf94fc578fdf14d4de602d50fd0085d4fe6d9
+  metadata.gz: 587d547ca6139b84ef36f8064a768aee1cdb3f5618f4f03c9ab606df477ad6ebffe82b00837fe55b06fcf2ba6275a1d85484f758394755567b1aab81351bf1df
+  data.tar.gz: e5203156810f3f577bbe20de7d862f96518db292b1f848778dc2c9dc5223b16c9e15e6effc2e08ed4dba655891805873fdf95cda511c5a533f87462200401746

data/lib/redgreenblue.rb

@@ -10,14 +10,18 @@ require 'redgreenblue/48bit'
 require 'redgreenblue/hex'
 
 require 'redgreenblue/hsl_hsv'
+require 'redgreenblue/cie'
 
+require 'redgreenblue/inspect'
 require 'redgreenblue/lazy'
-require 'redgreenblue/nice'
 
 require 'redgreenblue/rgb565'
 require 'redgreenblue/bgr24bit'
 require 'redgreenblue/gif'
+require 'redgreenblue/terminal'
+require 'redgreenblue/web'
 
+require 'redgreenblue/mix'
 require 'redgreenblue/misc'
 require 'redgreenblue/random'
 

data/lib/redgreenblue/24bit.rb

@@ -51,4 +51,19 @@ class RGB
     c
   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
+    @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.rb

@@ -0,0 +1,62 @@
+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 = expanded_srgb_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
+
+  private
+
+  # Returns gamma-expanded (inverse-companded) RGB values for sRGB.
+  #
+  # Based on:
+  # - https://en.wikipedia.org/wiki/SRGB
+  # - http://www.brucelindbloom.com/Eqn_RGB_to_XYZ.html
+  def expanded_srgb_values
+    values.map { |v|
+      if v <= 0.04045
+        v / 12.92
+      else
+        ( ( v + 0.055 ) / 1.055 ) ** 2.4
+      end
+    }
+  end
+
+end

data/lib/redgreenblue/hex.rb

@@ -1,35 +1,66 @@
 class RGB
 
+  # Returns a 6-digit hexadecimal string representing the object's red, green, and blue components as 8-bit values.
+  #
+  # If shorthand is true, returns 3-digit shorthand if possible.
   def hex(shorthand=false)
     if shorthand
-      RGB.hex_shorthand hexadecimal
+      RGB.hex_shorthand hex6
     else
-      hexadecimal
+      hex6
     end
   end
 
-  def hex=(s)
-    if ( s =~ /^(#?)(\h\h)(\h\h)(\h\h)$/ ) # 6-digit hex
-      self.rgb = [ $2.to_i(16), $3.to_i(16), $4.to_i(16) ]
-    elsif  ( s =~ /^(#?)(\h)(\h)(\h)$/ ) # 3-digit hex
-      self.rgb = [ ($2*2).to_i(16), ($3*2).to_i(16), ($4*2).to_i(16) ]
+  # Sets red, green, and blue using a 6- or 3-digit hexadecimal string.
+  #
+  # The string may include a '#' prefix.
+  def hex=(hex_string)
+    if rgb = RGB.hex_to_rgb(hex_string)
+      self.rgb = rgb
+    else
+      raise ArgumentError, "'#{hex_string}' is not a usable hexadecimal string"
+    end
+  end
+
+
+# Class methods
+
+
+  # Creates a new 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)
+    if rgb = RGB.hex_to_rgb(hex_string)
+      self.rgb rgb
+    else
+      raise ArgumentError, "'#{hex_string}' is not a usable hexadecimal string"
     end
   end
 
-  # factory method
-  def self.hex(s)
-    c = self.new
-    c.hex = s
-    c
+  # 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
 
-  def self.hex_shorthand(h)
-    h.sub( /^(#?)(\h)\2(\h)\3(\h)\4$/, '\1\2\3\4' )
+  # 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
+    end
   end
 
   private
 
-  def hexadecimal
+  def hex6
     '%02x%02x%02x' % [ r, g, b ]
   end
 

data/lib/redgreenblue/inspect.rb

@@ -0,0 +1,51 @@
+class RGB
+
+  private
+
+  def _inspect_default(prefix='RGB')
+    "#{prefix} ##{hex} (red=%1.5f green=%1.5f blue=%1.5f)" % [red, green, blue]
+  end
+
+  def _inspect_hex
+    "##{hex}"
+  end
+
+  def _inspect_swatch
+    terminal_background + "   \e[0m"
+  end
+
+  def _inspect_simple
+    _inspect_default _inspect_swatch
+  end
+
+  public
+
+  def inspect
+    send "_inspect_#{self.class.style}"
+  end
+
+  def to_s
+    _inspect_default
+  end
+
+  # Returns the base inspect style, dependent on the COLORTERM environment variable.
+  def self.base_style
+    ENV['COLORTERM'] == 'truecolor' ? 'simple' : 'default'
+  end
+
+  # Returns the current inspect style.
+  def self.style
+    @@style ||= base_style
+  end
+
+  # Returns a list of all available inspect styles.
+  def self.styles
+    ( self.instance_methods + self.private_instance_methods ).grep( /^_inspect_(.*)/ ) { $1 }.sort
+  end
+
+  # Selects an inspect style.
+  def self.style=(s)
+    @@style = styles.grep( /^#{s.to_s.downcase}/ ).first || style
+  end
+
+end

data/lib/redgreenblue/misc.rb

@@ -1,60 +1,27 @@
 class RGB
 
-# Mix
-
-  # Mix with second RGB color.
-  # p denotes portion of the mixed-in color to be used.
-  # p=0 delivers pure original color (no change),
-  # p=1 delivers pure mixed-in color.
-
-  def mix!(color,p=0.5)
-    self.values = mix_values(color.values, p)
-    self
-  end
-
-  def mix(color,p=0.5)
-    RGB.new mix_values(color.values, p)
-  end
-
-# Invert
-
+  # Inverts the object's color.
   def invert!
-    self.values = values.map { |v| 1-v }
+    self.values = values.map { |v| 1 - v }
     self
   end
 
+  # Creates a new RGB object with the inverted color of this RGB object.
   def invert
     dup.invert!
   end
 
-# Mix with white
-
-  def whiten!(p)
-    mix!(RGB.white, p)
-  end
-
-  def whiten(p)
-    mix(RGB.white, p)
-  end
-
-# Mix with black
-
-  def blacken!(p)
-    mix!(RGB.black, p)
+  # Returns an array of RGB objects for all possible ways in which the red, green, and blue values of this object can be exchanged.
+  #
+  # Example: RGB.red.permutation returns [ RGB.red, RGB.green, RGB.blue ]
+  # See also: shuffle
+  def permutation
+    values.permutation.to_a.uniq.map { |v| RGB.new v }
   end
 
-  def blacken(p)
-    mix(RGB.black, p)
+  # Returns an array of three RGB objects, for the red, green, and blue components of this object.
+  def components
+    [ RGB.new(red,0,0), RGB.new(0,green,0), RGB.new(0,0,blue) ]
   end
 
-  private
-
-  def mix_values(v, p)
-    raise(ArgumentError, "Portion '#{p}' not in range (0..1)") unless (0..1).include? p
-    [
-      ( red   * (1-p) ) + ( v[0] * p ),
-      ( green * (1-p) ) + ( v[1] * p ),
-      ( blue  * (1-p) ) + ( v[2] * p )
-    ]
-  end
 end

data/lib/redgreenblue/mix.rb

@@ -0,0 +1,44 @@
+class RGB
+
+  # Changes the object's color by mixing it with a portion of another RGB color.
+  def mix!(another,portion=0.5)
+    self.values = mix_values(another.values, portion)
+    self
+  end
+
+  # Creates a new RGB object by mixing this object's color with a portion of another RGB color.
+  def mix(another,portion=0.5)
+    RGB.new mix_values(another.values, portion)
+  end
+
+  # Changes the object's color by mixing it with a portion of white.
+  def whiten!(portion=0.5)
+    mix!(RGB.white, portion)
+  end
+
+  # Creates a new RGB object by mixing this object's color with a portion of white.
+  def whiten(portion=0.5)
+    mix(RGB.white, portion)
+  end
+
+  # Changes the object's color by mixing it with a portion of black.
+  def blacken!(portion=0.5)
+    mix!(RGB.black, portion)
+  end
+
+  # Creates a new RGB object by mixing this object's color with a portion of black.
+  def blacken(portion=0.5)
+    mix(RGB.black, portion)
+  end
+
+  private
+
+  def mix_values(some_values, portion)
+    raise(ArgumentError, "Portion '#{portion}' not in range (0..1)") unless (0..1).include? portion
+    [
+      ( red   * (1 - portion) ) + ( some_values[0] * portion ),
+      ( green * (1 - portion) ) + ( some_values[1] * portion ),
+      ( blue  * (1 - portion) ) + ( some_values[2] * portion )
+    ]
+  end
+end

data/lib/redgreenblue/opt/philipshue.rb

@@ -1,9 +1,13 @@
+# Optional support for Philips Hue lights.
+
+# Automatically load core RGB class before loading options.
+require 'redgreenblue'
+
 class RGB
 
   # Returns the arguments required by the Philips Hue API to set a light to this RGB object's hue, saturation and brightness (HSB).
   #
-  # When formatted as JSON, this hash can be used
-  # directly to set a light's state.
+  # When formatted as JSON, this hash can be used directly to set a light's state.
   def to_philips_hue_api_hsb_arguments(black_off=true)
     my_hsb = hsb
 

data/lib/redgreenblue/os/mac.rb

@@ -31,8 +31,15 @@ class RGB
   # Standard Additions -> User Interaction -> choose color
   def self.mac_choose(color)
 
+    app = case ENV['TERM_PROGRAM']
+      when /iTerm\.app/
+        'iTerm'
+      else
+        'Terminal'
+      end
+
     script = <<~ENDSCRIPT
-      tell application "Terminal"
+      tell application "#{app}"
         try
           return choose color default color { #{color[0]}, #{color[1]}, #{color[2]} }
         on error

data/lib/redgreenblue/random.rb

@@ -6,6 +6,11 @@ class RGB
     self
   end
 
+  # Creates a new RGB object with this object's red, green, and blue values shuffled.
+  def shuffle
+    RGB.new values.shuffle
+  end
+
   # Assigns random values to red, green, and blue.
   def randomize!
     self.values = Kernel::rand, Kernel::rand, Kernel::rand

data/lib/redgreenblue/terminal.rb

@@ -0,0 +1,19 @@
+class RGB
+
+  # With help from:
+  # - https://gist.github.com/XVilka/8346728
+  # - https://unix.stackexchange.com/questions/404414
+
+  # Returns the ANSI escape sequence required to set the foreground color on a terminal to this color.
+  # Only works on terminals that support 24-bit colors, so-called "true color".
+  def terminal_foreground
+    "\e[38;2;%d;%d;%dm" % rgb
+  end
+
+  # Returns the ANSI escape sequence required to set the background color on a terminal to this color.
+  # Only works on terminals that support 24-bit colors, so-called "true color".
+  def terminal_background
+    "\e[48;2;%d;%d;%dm" % rgb
+  end
+
+end

data/lib/redgreenblue/version.rb

@@ -1,3 +1,3 @@
 class RGB
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 end

data/lib/redgreenblue/web.rb

@@ -0,0 +1,10 @@
+class RGB
+
+  # Returns the object's RGB value in hexadecimal notation as used in CSS.
+  #
+  # Shortens to 3 digits when possible.
+  def css_hex
+    "##{hex true}"
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redgreenblue
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - lllist.eu
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-11 00:00:00.000000000 Z
+date: 2019-12-20 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: 
@@ -21,18 +21,22 @@ files:
 - lib/redgreenblue/48bit.rb
 - lib/redgreenblue/base.rb
 - lib/redgreenblue/bgr24bit.rb
+- lib/redgreenblue/cie.rb
 - lib/redgreenblue/gif.rb
 - lib/redgreenblue/hex.rb
 - lib/redgreenblue/hsl_hsv.rb
+- lib/redgreenblue/inspect.rb
 - lib/redgreenblue/lazy.rb
 - lib/redgreenblue/misc.rb
-- lib/redgreenblue/nice.rb
+- lib/redgreenblue/mix.rb
 - lib/redgreenblue/opt/philipshue.rb
 - lib/redgreenblue/os.rb
 - lib/redgreenblue/os/mac.rb
 - lib/redgreenblue/random.rb
 - lib/redgreenblue/rgb565.rb
+- lib/redgreenblue/terminal.rb
 - lib/redgreenblue/version.rb
+- lib/redgreenblue/web.rb
 homepage: https://github.com/lllisteu/redgreenblue
 licenses:
 - MIT
@@ -52,8 +56,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
-summary: A simple Ruby library for handling RGB colors
+summary: A simple Ruby library for handling RGB colors.
 test_files: []

data/lib/redgreenblue/nice.rb

@@ -1,9 +0,0 @@
-class RGB
-
-  def inspect
-    "RGB ##{hex} (red=%1.5f green=%1.5f blue=%1.5f)" % [red, green, blue]
-  end
-
-  alias to_s inspect
-
-end