redgreenblue 0.7.0 → 0.12.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

@@ -35,4 +35,19 @@ class RGB
     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,52 @@
 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 )
-    ]
+  # Returns the euclidean distance between this color and another color.
+  #
+  # When you imagine a color as a point in a 3-dimensional space,
+  # the dimensions being red, green, and blue,
+  # this is the distance between two colors.
+  def distance(another)
+    (
+      ( (another.red   - red  ) ** 2) +
+      ( (another.green - green) ** 2) +
+      ( (another.blue  - blue ) ** 2)
+    ) ** (1/2.0)
   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/name.rb

@@ -0,0 +1,13 @@
+class RGB
+
+  # Returns the name.
+  def name
+    defined?(@name) ? @name : nil
+  end
+
+  # Sets the name (a string or nil).
+  def name=(text)
+    @name = ( text.to_s.size != 0 ) ? text.to_s : nil
+  end
+
+end

data/lib/redgreenblue/opt/philipshue.rb

@@ -1,9 +1,28 @@
+# 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
 
-  # Returns the arguments required by the Philips Hue API to set a light to this RGB object's hue, saturation and brightness (HSB).
+  # 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/
   #
-  # When formatted as JSON, this hash can be used
-  # directly to set a light's state.
+  # @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
 

data/lib/redgreenblue/os/mac.rb

@@ -1,6 +1,7 @@
 class RGB
 
-  # Shows the Mac OS color picker to choose a color for the RGB object.
+  # 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
@@ -8,7 +9,9 @@ class RGB
     end
   end
 
-  # Shows the Mac OS color picker and creates an RGB object with the chosen color.
+  # 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)
@@ -31,8 +34,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/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/palettes/css.gpl

@@ -0,0 +1,164 @@
+GIMP Palette
+Name: CSS Named Colors
+#
+# As per CSS Color Module Level 4, Editor's Draft, 19 August 2020.
+#   - source: https://drafts.csswg.org/css-color/#named-colors
+#
+# Notes: 
+#  "Don't cite this document other than as work in progress."
+#
+#  "CSS defines a large set of named colors, so that 
+#   common colors can be written and read more easily."
+#
+#  "[...] all of these keywords are ASCII case-insensitive."
+#
+#  "The names resolve to colors in sRGB."
+#
+240 248 255	aliceblue
+250 235 215	antiquewhite
+  0 255 255	aqua
+127 255 212	aquamarine
+240 255 255	azure
+245 245 220	beige
+255 228 196	bisque
+  0   0   0	black
+255 235 205	blanchedalmond
+  0   0 255	blue
+138  43 226	blueviolet
+165  42  42	brown
+222 184 135	burlywood
+ 95 158 160	cadetblue
+127 255   0	chartreuse
+210 105  30	chocolate
+255 127  80	coral
+100 149 237	cornflowerblue
+255 248 220	cornsilk
+220  20  60	crimson
+  0 255 255	cyan
+  0   0 139	darkblue
+  0 139 139	darkcyan
+184 134  11	darkgoldenrod
+169 169 169	darkgray
+  0 100   0	darkgreen
+169 169 169	darkgrey
+189 183 107	darkkhaki
+139   0 139	darkmagenta
+ 85 107  47	darkolivegreen
+255 140   0	darkorange
+153  50 204	darkorchid
+139   0   0	darkred
+233 150 122	darksalmon
+143 188 143	darkseagreen
+ 72  61 139	darkslateblue
+ 47  79  79	darkslategray
+ 47  79  79	darkslategrey
+  0 206 209	darkturquoise
+148   0 211	darkviolet
+255  20 147	deeppink
+  0 191 255	deepskyblue
+105 105 105	dimgray
+105 105 105	dimgrey
+ 30 144 255	dodgerblue
+178  34  34	firebrick
+255 250 240	floralwhite
+ 34 139  34	forestgreen
+255   0 255	fuchsia
+220 220 220	gainsboro
+248 248 255	ghostwhite
+255 215   0	gold
+218 165  32	goldenrod
+128 128 128	gray
+  0 128   0	green
+173 255  47	greenyellow
+128 128 128	grey
+240 255 240	honeydew
+255 105 180	hotpink
+205  92  92	indianred
+ 75   0 130	indigo
+255 255 240	ivory
+240 230 140	khaki
+230 230 250	lavender
+255 240 245	lavenderblush
+124 252   0	lawngreen
+255 250 205	lemonchiffon
+173 216 230	lightblue
+240 128 128	lightcoral
+224 255 255	lightcyan
+250 250 210	lightgoldenrodyellow
+211 211 211	lightgray
+144 238 144	lightgreen
+211 211 211	lightgrey
+255 182 193	lightpink
+255 160 122	lightsalmon
+ 32 178 170	lightseagreen
+135 206 250	lightskyblue
+119 136 153	lightslategray
+119 136 153	lightslategrey
+176 196 222	lightsteelblue
+255 255 224	lightyellow
+  0 255   0	lime
+ 50 205  50	limegreen
+250 240 230	linen
+255   0 255	magenta
+128   0   0	maroon
+102 205 170	mediumaquamarine
+  0   0 205	mediumblue
+186  85 211	mediumorchid
+147 112 219	mediumpurple
+ 60 179 113	mediumseagreen
+123 104 238	mediumslateblue
+  0 250 154	mediumspringgreen
+ 72 209 204	mediumturquoise
+199  21 133	mediumvioletred
+ 25  25 112	midnightblue
+245 255 250	mintcream
+255 228 225	mistyrose
+255 228 181	moccasin
+255 222 173	navajowhite
+  0   0 128	navy
+253 245 230	oldlace
+128 128   0	olive
+107 142  35	olivedrab
+255 165   0	orange
+255  69   0	orangered
+218 112 214	orchid
+238 232 170	palegoldenrod
+152 251 152	palegreen
+175 238 238	paleturquoise
+219 112 147	palevioletred
+255 239 213	papayawhip
+255 218 185	peachpuff
+205 133  63	peru
+255 192 203	pink
+221 160 221	plum
+176 224 230	powderblue
+128   0 128	purple
+102  51 153	rebeccapurple
+255   0   0	red
+188 143 143	rosybrown
+ 65 105 225	royalblue
+139  69  19	saddlebrown
+250 128 114	salmon
+244 164  96	sandybrown
+ 46 139  87	seagreen
+255 245 238	seashell
+160  82  45	sienna
+192 192 192	silver
+135 206 235	skyblue
+106  90 205	slateblue
+112 128 144	slategray
+112 128 144	slategrey
+255 250 250	snow
+  0 255 127	springgreen
+ 70 130 180	steelblue
+210 180 140	tan
+  0 128 128	teal
+216 191 216	thistle
+255  99  71	tomato
+ 64 224 208	turquoise
+238 130 238	violet
+245 222 179	wheat
+255 255 255	white
+245 245 245	whitesmoke
+255 255   0	yellow
+154 205  50	yellowgreen