redgreenblue 0.6.0 → 0.11.0

data/lib/redgreenblue/int.rb

@@ -0,0 +1,22 @@
+class RGB
+
+  # Returns the color as a 24-bit integer in the range 0..16777215.
+  def to_i
+    ( r << 16 ) + ( g << 8 ) + b
+  end
+
+  # Creates a new RGB object from a 24-bit integer in the range 0..16777215.
+  def self.at(number)
+    n = number.to_i
+    if (0..16777215) === n
+      rgb(
+        ( n & 0xff0000 ) >> 16,
+        ( n & 0x00ff00 ) >>  8,
+        ( n & 0x0000ff )
+      )
+    else
+      raise ArgumentError, "Argument '#{number}' not in range 0..16777215"
+    end
+  end
+
+end

data/lib/redgreenblue/lazy.rb

@@ -1,11 +1,53 @@
 class RGB
 
+  # Creates a white RGB object.
   def self.white
-    new([1,1,1])
+    new(1,1,1)
   end
 
+  # Creates a black RGB object.
   def self.black
-    new([0,0,0])
+    new(0,0,0)
+  end
+
+  # Creates a grey RGB object. Defaults to lightness 0.5, a middle grey. Black equals grey(0), white equals grey(1).
+  #
+  # ::gray is an alias for ::grey.
+  def self.grey(lightness=0.5)
+    new(lightness, lightness, lightness)
+  end
+
+  # Alias gray for grey.
+  self.singleton_class.send(:alias_method, :gray, :grey)
+
+  # Creates a pure red RGB object.
+  def self.red
+    new(1,0,0)
+  end
+
+  # Creates a pure green RGB object.
+  def self.green
+    new(0,1,0)
+  end
+
+  # Creates a pure blue RGB object.
+  def self.blue
+    new(0,0,1)
+  end
+
+  # Creates a yellow RGB object.
+  def self.yellow
+    new(1,1,0)
+  end
+
+  # Creates a cyan RGB object.
+  def self.cyan
+    new(0,1,1)
+  end
+
+  # Creates a magenta RGB object.
+  def self.magenta
+    new(1,0,1)
   end
 
 end

data/lib/redgreenblue/math.rb

@@ -0,0 +1,9 @@
+class RGB
+
+private
+
+  def zip_add(a,b)
+    a.zip(b).map { |ab| ( ab[0] || 0 ) + ab[1] }
+  end
+
+end

data/lib/redgreenblue/misc.rb

@@ -1,60 +1,39 @@
 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)
+  # Returns true when this is an achromatic color: red, green, and blue have equal values.
+  # Otherwise false.
+  def achromatic?
+    values.min == values.max
   end
 
-  def whiten(p)
-    mix(RGB.white, 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
 
-# Mix with black
-
-  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
 
-  def blacken(p)
-    mix(RGB.black, p)
+  # Creates a new RGB object from three RGB objects representing the red, green, and blue components.
+  def self.assemble(*a)
+    v = a.flatten
+    RGB.new(v[0].red, v[1].green, v[2].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,65 @@
+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 one or more new RGB objects by mixing this object's color with a portion of white.
+  def whiten(portion=0.5, *portions)
+    if (portion.class != Array) and portions.none?
+      mix(RGB.white, portion)
+    else
+      ( [portion].flatten + portions ).map { |p| mix(RGB.white, p) }
+    end
+  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 one or more new RGB objects by mixing this object's color with a portion of black.
+  def blacken(portion=0.5, *portions)
+    if (portion.class != Array) and portions.none?
+      mix(RGB.black, portion)
+    else
+      ( [portion].flatten + portions ).map { |p| mix(RGB.black, p) }
+    end
+  end
+
+  # Returns a set of colors between this color and another. That other color is included.
+  #
+  # The resulting colors are spaced evenly in the RGB color space using a straightforward calculation.
+  # You will likely experience these colors as not exactly evenly spaced.
+  def steps(another,step_count=1,include_begin=false)
+    # origin (self, optional)
+    ( include_begin ? [self.dup] : [] ) +
+    # ...plus intermediate colors
+    (1..step_count-1).map { |c| mix(another, c.to_f/step_count) } +
+    # ...plus destination color
+    [another.dup]
+  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

@@ -0,0 +1,54 @@
+# Optional support for Philips Hue lights.
+#
+# Conforms to Bridge API 1.35 for Philips Hue, published 20-Nov-2019.
+
+# Automatically load core RGB class before loading options.
+require 'redgreenblue'
+
+class RGB
+
+  # Only available when optional support for Philips Hue lights is loaded.
+  #
+  # Returns a hash with the arguments required by the Philips Hue API,
+  # to set a light to this RGB object's hue, saturation and brightness.
+  #
+  # Formatted as JSON, this hash can be sent to a bridge to set a light's state.
+  #
+  # See (regrettably requires registration):
+  # - https://developers.meethue.com/develop/hue-api/
+  #
+  # @example Load
+  #  require 'redgreenblue/opt/philipshue'
+  # @example Use
+  #  RGB.magenta.to_philips_hue_api_hsb_arguments
+  #  => {"on"=>true, "bri"=>254, "hue"=>54613, "sat"=>254}
+  # @return [Hash] API arguments
+  def to_philips_hue_api_hsb_arguments(black_off=true)
+    my_hsb = hsb
+
+    # Black means 'off'
+    if black_off and ( my_hsb[2] == 0 )
+      { 'on'  => false }
+
+    else
+      {
+
+        # On/Off state of the light
+        'on'  => true,
+
+        # Brightness 1..254
+        # Note: a brightness of 1 will not switch the light off
+        'bri' => (  my_hsb[2]        * 253 + 1     ).round,
+
+        # Hue 0..65535
+        'hue' => (( my_hsb[0] || 0 ) * 65535 / 360 ).round,
+
+        # Saturation 0..254
+        'sat' => (  my_hsb[1]        * 254         ).round
+
+      }
+
+    end
+  end
+
+end

data/lib/redgreenblue/os/mac.rb

@@ -1,5 +1,7 @@
 class RGB
 
+  # On Mac OS, shows the color picker to choose a color for the RGB object.
+  # Not available on other platforms.
   def pick
     result = RGB.mac_choose(rrggbb)
     if result
@@ -7,10 +9,12 @@ class RGB
     end
   end
 
-# factory method
-
-  def self.pick
-    result = RGB.mac_choose(RGB.new.rrggbb)
+  # On Mac OS, shows the color picker and creates an RGB object with the chosen color.
+  # Not available on other platforms.
+  #
+  # If no default color is specified, the picker defaults to a middle grey.
+  def self.pick(default_color=RGB.new)
+    result = RGB.mac_choose(default_color.rrggbb)
     if result
       RGB.rrggbb result
     else
@@ -20,15 +24,25 @@ class RGB
 
   private
 
-# Use Applescript to call color picker on Mac.
-# - requires a 48-bit RGB triplet [rr, gg, bb] for default choice.
-#
-# - Returns nil when <cancel> is clicked or <esc> key hit.
-# - Otherwise returns 48-bit RGB triplet [rr, gg, bb].
+  # Uses Applescript to call the color picker on Mac OS.
+  # - requires a 48-bit RGB triplet [rr, gg, bb] for default choice.
+  #
+  # - Returns nil when <cancel> is clicked or <esc> key hit.
+  # - Otherwise returns 48-bit RGB triplet [rr, gg, bb].
+  #
+  # Applescript command documented here:
+  # 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/ostwald.rb

@@ -0,0 +1,45 @@
+class RGB
+
+  # Returns a new RGB object with this color's Ostwald full-color,
+  # or nil for achromatic colors (white, greys, and black).
+  #
+  # The resulting color contains no white or black,
+  # i.e. it has at least one RGB component set to 0, and at least one set to maximum.
+  #
+  # This is identical (barring very small rounding errors)
+  # to setting HSL-saturation to 1, and -lightness to 0.5
+  #
+  # Based on:
+  # - Color for the Sciences, pp. 575–591
+  # - https://lirias.kuleuven.be/retrieve/306124 (PDF)
+  def ostwald_color
+    white_portion = values.min
+    color_portion = values.max - white_portion
+
+    if color_portion == 0
+      nil
+    else
+      RGB.new( values.map { |v| ( ( v - white_portion ) / color_portion ).round(6) } )
+    end
+  end
+
+  # Returns the portions of Ostwald full-color, white, and black, which constitute this color.
+  #
+  # The sum of these three numbers equals 1.
+  #
+  # #cwk is an alias for #ostwald_cwk.
+  #
+  # Based on:
+  # - Color for the Sciences, pp. 575–591
+  # - https://lirias.kuleuven.be/retrieve/306124 (PDF)
+  def ostwald_cwk
+    [
+      color_portion = values.max - values.min,
+      white_portion = values.min,
+      1 - color_portion - white_portion
+    ]
+  end
+
+  alias cwk ostwald_cwk
+
+end

data/lib/redgreenblue/random.rb

@@ -1,17 +1,25 @@
 class RGB
 
+  # Shuffles the object's red, green, and blue values.
   def shuffle!
-    self.red, self.green, self.blue = [red, green, blue].shuffle
+    self.values = values.shuffle
     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.red, self.green, self.blue = Kernel::rand, Kernel::rand, Kernel::rand
+    self.values = Kernel::rand, Kernel::rand, Kernel::rand
     self
   end
 
+  # Creates a new RGB object with random red, green, and blue values.
   def self.rand
-    new([Kernel::rand, Kernel::rand, Kernel::rand])
+    new(Kernel::rand, Kernel::rand, Kernel::rand)
   end
 
 end

data/lib/redgreenblue/rgb565.rb

@@ -1,25 +1,24 @@
 class RGB
 
+  # Returns the color in 16-bit RGB565 format.
   def rgb565
     [((r >> 3) << 11) + ((g >> 2) << 5) + (b >> 3)].pack 'S<'
   end
 
-  # https://stackoverflow.com/questions/2442576/
-  def rgb565=(s)
-    v = ( s.unpack "S<" )[0]
+  # Sets the color from 16-bit RGB565 data.
+  # With help from:
+  # - https://stackoverflow.com/questions/2442576/
+  def rgb565=(rgb565_string)
+    v = ( rgb565_string.unpack "S<" )[0]
     self.r = ( ( v & 0xf800 ) >> 11 ) << 3
     self.g = ( ( v & 0x07e0 ) >>  5 ) << 2
     self.b = ( ( v & 0x001f )       ) << 3
   end
 
-  def rgb565_binary
-    rgb565.bytes.reverse.map { |b| "%08b" % b }.join
-  end
-
-  # factory method
-  def self.rgb565(s)
+  # Creates a new RGB color from 16-bit RGB565 data.
+  def self.rgb565(rgb565_string)
     c = self.new
-    c.rgb565 = s
+    c.rgb565 = rgb565_string
     c
   end