redgreenblue 0.9.0 → 0.14.0

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,18 +1,28 @@
 # Optional support for Philips Hue lights.
 #
 # Conforms to Bridge API 1.35 for Philips Hue, published 20-Nov-2019.
-# See (regrettably requires registration):
-# - https://developers.meethue.com/develop/hue-api/
 
 # 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.
-  # Only available when optional support for Philips Hue lights is loaded (require 'redgreenblue/opt/philipshue').
+  # 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

@@ -3,7 +3,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)
+    result = RGB.mac_choose(self)
     if result
       self.rrggbb = result
     end
@@ -14,7 +14,7 @@ class RGB
   #
   # 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
@@ -32,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/
@@ -44,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(round: true)
+    [
+      color_portion = values.max - values.min,
+      white_portion = values.min,
+      1 - color_portion - white_portion
+    ].map { |v| round ? v.round(8) : v }
+  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,16 +15,6 @@ class RGB
     self.b = ( ( v & 0x001f )       ) << 3
   end
 
-  # Deprecated: this method will be removed in a future version.
-  # Returns the color in 16-bit RGB565 format as a string of 0's and 1's.
-  def rgb565_binary
-    unless defined? @@warned_rgb565_binary_deprecation
-      warn "Warning: 'rgb565_binary' has been deprecated and will be removed in a future version of redgreenblue."
-      @@warned_rgb565_binary_deprecation = true
-    end
-    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,7 +1,7 @@
 class RGB
 
   # redgreenblue version.
-  VERSION = '0.9.0'
+  VERSION = '0.14.0'
 
   # Returns RGB::VERSION.
   def self.version

data/lib/redgreenblue/view.rb

@@ -0,0 +1,34 @@
+class RGB
+
+  # Prints details for the RGB object, using multiple lines.
+  def view
+    puts _inspect_view
+  end
+
+  alias v view
+
+  private
+
+  def _inspect_view
+    o = []
+    o << 3.times.map { terminal_background + "      \e[0m "}
+    o << [ "#{_inspect_hex} ", '%-7.7s ' % color_space, '        ' ]
+
+    o << components.map { |c| c.terminal_background + "  \e[0m " }
+    o << %w(R: G: B:)
+    o << values.map { |v| '%1.5f ' % v }
+    o << rgb.map { |v| '%3d ' % v }
+
+    o << %w(H: S: L:)
+    o << hsl.map { |v| v ? ('%7.3f ' % v) : '  -     ' }
+    o << %w(H: S: B:)
+    o << hsb.map { |v| v ? ('%7.3f ' % v) : '  -     ' }
+
+    o << 3.times.map { (ostwald_color ? ostwald_color.terminal_background + "  \e[0m " : '   ') }
+    o << %w(C: W: K:)
+    o << ostwald_cwk.map { |v| '%1.3f ' % v }
+
+    o.transpose.map(&:join).join("\n")
+  end
+
+end

data/lib/redgreenblue/web.rb

@@ -1,5 +1,60 @@
 class RGB
 
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
+
+  class << self
+
+    # Returns CSS named colors, as per CSS Color Module Level 4.
+    #
+    # Optional selector argument can be:
+    # - String or Regexp (to select by name)
+    # - RGB color (to select by color)
+    # - Integer (to select by index).
+    # Selection by name (string or regular expression) is case-insensitive by default.
+    #
+    # @example No Selector
+    #  # All colors
+    #  RGB.css
+    #
+    #  # Pastels
+    #  RGB.css.select { |c| c.ostwald_cwk[1] > 0.6 }
+    # @example Select by Name
+    #  # Exact name
+    #  RGB.css 'pink'
+    #
+    #  # Regular expression
+    #  RGB.css /pink|rose/
+    #
+    # @example Select by RGB color
+    #  RGB.css RGB.hex('0ff')
+    def css(selector=nil)
+      @@css ||= load_gpl file: ( File.join File.dirname(__FILE__), 'palettes', 'css.gpl' ), freeze: true
+      case selector
+        when NilClass
+          @@css
+        when String
+          n = selector.downcase
+          @@css.select { |c| c.name == n }.first
+        when Regexp
+          r = Regexp.new selector.source, Regexp::IGNORECASE
+          @@css.select { |c| c.name =~ r }
+        when Integer
+          @@css[selector]
+        when self
+          @@css.select { |c| c == selector }
+        else
+          raise ArgumentError, 'Unsupported selector'
+      end
+    end
+
+  end
+
+  #----------------------------------------------------------------------#
+  #                           Instance Methods                           #
+  #----------------------------------------------------------------------#
+
   # Returns the object's RGB value in hexadecimal notation as used in CSS.
   #
   # Shortens to 3 digits when possible.
@@ -7,4 +62,48 @@ class RGB
     "##{hex true}"
   end
 
+  # Returns the names of CSS named colors identical to this color.
+  # @example
+  #  RGB.hex('f0f').css_names
+  def css_names
+    RGB.css(self).map &:name
+  end
+
+  # Returns the color's relative luminance, as defined by the Web Content Accessibility Guidelines (WCAG) 2.0.
+  #
+  # This is different from the Y component of CIE 1931 XYZ.
+  #
+  # Based on:
+  # - https://www.w3.org/TR/WCAG20/#relativeluminancedef
+  def wcag20_luminance(round: true)
+    if color_space == 'sRGB'
+      values.map { |v|
+        if v <= 0.03928
+          v / 12.92
+        else
+          ( ( v + 0.055 ) / 1.055 ) ** 2.4
+        end
+      }.zip( [0.2126, 0.7152, 0.0722] ).map { |c,f|
+        c * f
+      }.inject(:+).instance_eval { |v| round ? v.round(8) : v }
+    else
+      raise "can not calculate luminance for color space '#{color_space}'"
+    end
+  end
+
+  # Returns the contrast ratio for this color and another color, as defined by the Web Content Accessibility Guidelines (WCAG) 2.0.
+  #
+  # Based on:
+  # - https://www.w3.org/TR/WCAG20/#contrast-ratiodef
+  def wcag20_contrast_ratio(another, round: true)
+    luminances = [
+      wcag20_luminance(round: false),
+      another.wcag20_luminance(round: false)
+    ].sort.reverse
+
+    contrast_ratio = ( luminances[0] + 0.05 ) / ( luminances[1] + 0.05 )
+
+    round ? contrast_ratio.round(8) : contrast_ratio
+  end
+
 end