redgreenblue 0.8.0 → 0.13.0

data/lib/redgreenblue/mac.rb

@@ -0,0 +1,8 @@
+class RGB
+
+  # Returns the color in the format used by AppleScript (a 48-bit RGB triplet).
+  def applescript
+    "{%i, %i, %i}" % rrggbb
+  end
+
+end

data/lib/redgreenblue/match.rb

@@ -0,0 +1,21 @@
+class RGB
+
+  # Matches this color to a set of colors by calculating their euclidean distance.
+  #
+  # Returns the given set of colors with their distance from this color, sorted by distance (nearest color first).
+  # @example What is nearer: red, grey or white?
+  #  RGB.hex('f9c').match_distance [RGB.red, RGB.grey, RGB.white]
+  def match_distance(others)
+    others.map { |c| [ c, distance(c) ] }.sort_by { |a| a[1] }
+  end
+
+  # Matches this color to a set of colors using the CIE 1976 delta E formula.
+  #
+  # Returns the given set of colors with their difference from this color, sorted by difference (nearest color first).
+  # @example Find the 3 nearest CSS named colors
+  #  RGB.hex('f9c').match_de76(RGB.css).first(3)
+  def match_de76(others)
+    others.map { |c| [ c, de76(c) ] }.sort_by { |a| a[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

@@ -11,10 +11,16 @@ class RGB
     dup.invert!
   end
 
+  # Returns true when this is an achromatic color: red, green, and blue have equal values.
+  # Otherwise false.
+  def achromatic?
+    values.min == values.max
+  end
+
   # 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
+  # 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
@@ -24,4 +30,23 @@ class RGB
     [ RGB.new(red,0,0), RGB.new(0,green,0), RGB.new(0,0,blue) ]
   end
 
+  # 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
+
+  # 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

@@ -16,9 +16,13 @@ class RGB
     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)
+  # 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.
@@ -26,9 +30,26 @@ class RGB
     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)
+  # 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

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,13 +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.
   #
-  # When formatted as JSON, this hash can be used directly to set a light's state.
+  # 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
 

data/lib/redgreenblue/os/mac.rb

@@ -1,17 +1,20 @@
 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)
+    result = RGB.mac_choose(self)
     if result
       self.rrggbb = result
     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)
+    result = RGB.mac_choose(default_color)
     if result
       RGB.rrggbb result
     else
@@ -29,7 +32,7 @@ class RGB
   #
   # Applescript command documented here:
   # Standard Additions -> User Interaction -> choose color
-  def self.mac_choose(color)
+  def self.mac_choose(default_color)
 
     app = case ENV['TERM_PROGRAM']
       when /iTerm\.app/
@@ -41,7 +44,7 @@ class RGB
     script = <<~ENDSCRIPT
       tell application "#{app}"
         try
-          return choose color default color { #{color[0]}, #{color[1]}, #{color[2]} }
+          return choose color default color #{default_color.applescript}
         on error
           return ""
         end try

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

data/lib/redgreenblue/rgb565.rb

@@ -15,11 +15,6 @@ class RGB
     self.b = ( ( v & 0x001f )       ) << 3
   end
 
-  # Returns the color in 16-bit RGB565 format as a string of 0's and 1's
-  def rgb565_binary
-    rgb565.bytes.reverse.map { |b| "%08b" % b }.join
-  end
-
   # Creates a new RGB color from 16-bit RGB565 data.
   def self.rgb565(rgb565_string)
     c = self.new

data/lib/redgreenblue/version.rb

@@ -1,3 +1,11 @@
 class RGB
-  VERSION = '0.8.0'
+
+  # redgreenblue version.
+  VERSION = '0.13.0'
+
+  # Returns RGB::VERSION.
+  def self.version
+    VERSION
+  end
+
 end