redgreenblue 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cac7c885ca1de3e3fe22ebfaf7207dd17b7bd25e8c1dd6f82cfdab0e0b5cee1
-  data.tar.gz: 7ca71212d78ae2a638d8bfb54dcb8a824367eac6e7fe8ca1eaa1e239b22bbaa9
+  metadata.gz: 9dea62bd74822100097e661284f2d44164a1be23ee0f81acdc778c182f0939ec
+  data.tar.gz: baa4c5ab0b3a367841ee18d94131ad4077661d515edb29939ed661175b479ee1
 SHA512:
-  metadata.gz: 23316f3526690807fabde09d5a909ae7afe396da7b039baa6352c814ab653d02ee5646aa23ece364748cf090f4b9218a34c0cd19b8a04313086b2c5f9dcadf97
-  data.tar.gz: 19f71a26312a83d845f8ff508758e653b693289be129e02281e65cb8da4b13d32ab5b58282883ea0d0dc4c156ddd775c0179354bea5dccc6065f00ad49b7f66c
+  metadata.gz: 81808e69a0aadb6ea54cb291fd682c1949e2178df1c31954256167552f12b990ef825561689a958cb533144c25d31852785ebcebe9d07ddb5684b3b0dfcd26ba
+  data.tar.gz: 62370184d5b291081bd8e7a1f698647d961fd4c98525677821950f59e58e5536473d5f4c0e87da53109866e875caf94fc578fdf14d4de602d50fd0085d4fe6d9

data/lib/redgreenblue.rb

@@ -9,6 +9,8 @@ require 'redgreenblue/24bit'
 require 'redgreenblue/48bit'
 require 'redgreenblue/hex'
 
+require 'redgreenblue/hsl_hsv'
+
 require 'redgreenblue/lazy'
 require 'redgreenblue/nice'
 

data/lib/redgreenblue/24bit.rb

@@ -2,43 +2,50 @@ class RGB
 
 # r, g, b methods
 
+  # Returns the red component as an integer in the range 0..255 (an 8-bit value).
   def r
     (red   * 255).round
   end
 
+  # Returns the green component as an integer in the range 0..255 (an 8-bit value).
   def g
     (green * 255).round
   end
 
+  # Returns the blue component as an integer in the range 0..255 (an 8-bit value).
   def b
     (blue  * 255).round
   end
 
+  # Sets the red component using an integer in the range 0..255 (an 8-bit value).
   def r=(n)
     self.red   = n / 255.0
   end
 
+  # Sets the green component using an integer in the range 0..255 (an 8-bit value).
   def g=(n)
     self.green = n / 255.0
   end
 
+  # Sets the blue component using an integer in the range 0..255 (an 8-bit value).
   def b=(n)
     self.blue  = n / 255.0
   end
 
 # rgb methods
 
+  # Returns the red, green, and blue components as integers in the range 0..255 (three 8-bit values).
   def rgb
     [r,g,b]
   end
 
-  def rgb=(rgb)
-    self.r, self.g, self.b = rgb
+  # Sets the red, green, and blue components using three integers in the range 0..255 (three 8-bit values).
+  def rgb=(*rgb)
+    self.r, self.g, self.b = rgb.flatten
   end
 
-# factory method
-
-  def self.rgb(rgb)
+  # Creates a new object from red, green, and blue components as integers in the range 0..255 (three 8-bit values).
+  def self.rgb(*rgb)
     c = self.new
     c.rgb = rgb
     c

data/lib/redgreenblue/48bit.rb

@@ -2,43 +2,50 @@ class RGB
 
 # rr, gg, bb methods
 
+  # Returns the red component as an integer in the range 0..65535 (a 16-bit value).
   def rr
     (red   * 65535).round
   end
 
+  # Returns the green component as an integer in the range 0..65535 (a 16-bit value).
   def gg
     (green * 65535).round
   end
 
+  # Returns the blue component as an integer in the range 0..65535 (a 16-bit value).
   def bb
     (blue  * 65535).round
   end
 
+  # Sets the red component using an integer in the range 0..65535 (a 16-bit value).
   def rr=(n)
     self.red   = n / 65535.0
   end
 
+  # Sets the green component using an integer in the range 0..65535 (a 16-bit value).
   def gg=(n)
     self.green = n / 65535.0
   end
 
+  # Sets the blue component using an integer in the range 0..65535 (a 16-bit value).
   def bb=(n)
     self.blue  = n / 65535.0
   end
 
 # rrggbb methods
 
+  # Returns the red, green, and blue components as integers in the range 0..65535 (three 16-bit values).
   def rrggbb
     [rr,gg,bb]
   end
 
-  def rrggbb=(rrggbb)
-    self.rr, self.gg, self.bb = rrggbb
+  # Sets the red, green, and blue components using three integers in the range 0..65535 (three 16-bit values).
+  def rrggbb=(*rrggbb)
+    self.rr, self.gg, self.bb = rrggbb.flatten
   end
 
-# factory method
-
-  def self.rrggbb(rrggbb)
+  # Creates a new object from red, green, and blue components as integers in the range 0..65535 (three 16-bit values).
+  def self.rrggbb(*rrggbb)
     c = self.new
     c.rrggbb = rrggbb
     c

data/lib/redgreenblue/base.rb

@@ -2,8 +2,8 @@ class RGB
 
   attr_reader :red, :green, :blue
 
-  def initialize(a=[0.5, 0.5, 0.5])
-    self.values = a
+  def initialize(*a)
+    self.values = a.any? ? a : [ 0.5, 0.5, 0.5 ]
   end
 
   def red=(n)
@@ -24,8 +24,22 @@ class RGB
 
   alias to_a values
 
-  def values=(a)
-    self.red, self.green, self.blue = a
+  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.
+  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
+  def to_h
+    ([:red, :green, :blue].zip values).sort_by {
+      |k,v| [-v,[:red, :green, :blue].index(k)]
+    }.to_h
   end
 
   private

data/lib/redgreenblue/gif.rb

@@ -1,15 +1,16 @@
 class RGB
 
-  # Return a 1-pixel GIF
+  # Returns a 1-pixel GIF image set to the color.
   #
   # With help from:
-  # - http://www.perlmonks.org/?node_id=7974
+  # - https://www.perlmonks.org/?node_id=7974
   def gif_pixel
     "GIF89a\1\0\1\0\x90\0\0".b +
     rgb.pack('C3') +
     "\0\0\0,\0\0\0\0\1\0\1\0\0\x02\x02\x04\1\0;".b
   end
 
+  # Writes a 1-pixel GIF image to a file.
   def gif_pixel_write(file_path)
     File.binwrite(file_path, gif_pixel)
   end

data/lib/redgreenblue/hsl_hsv.rb

@@ -0,0 +1,59 @@
+class RGB
+
+  # Returns color as HSL:
+  # hue (0..360), saturation (0..1), lightness (0..1).
+  # When saturation is 0, hue is nil.
+  def hsl
+    hsl_hsv_c[0]
+  end
+
+  # Returns color as HSV:
+  # hue (0..360), saturation (0..1), value (0..1).
+  # When saturation is 0, hue is nil.
+  #
+  # #hsb is an alias for #hsv.
+  def hsv
+    hsl_hsv_c[1]
+  end
+
+  alias hsb hsv
+
+  private
+
+  # Compute HSL, HSV, and chroma.
+  # With help from:
+  # - https://en.wikipedia.org/wiki/HSL_and_HSV
+  def hsl_hsv_c
+    sorted_hash = to_h
+    min, max = sorted_hash.values.values_at(2,0)
+
+    chroma = max - min
+
+    hue =
+      if chroma == 0
+        nil
+      else
+        case sorted_hash.keys.first
+        when :red
+          60 * ( ( ( green - blue  ) / chroma ).modulo 6 )
+        when :green
+          60 * ( (   blue  - red   ) / chroma + 2 )
+        when :blue
+          60 * ( (   red   - green ) / chroma + 4 )
+        end
+      end
+
+    lightness = ( min + max ) / 2.0
+
+    saturation_hsl =
+      chroma == 0 ? 0.0 : ( chroma / ( 1 - (2 * lightness - 1).abs ) ).round(9)
+
+    value = max
+
+    saturation_hsv =
+      value == 0 ? 0.0 : chroma / value
+
+    [ [hue, saturation_hsl, lightness], [hue, saturation_hsv, value], chroma ]
+  end
+
+end

data/lib/redgreenblue/lazy.rb

@@ -1,11 +1,38 @@
 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
 
 end

data/lib/redgreenblue/nice.rb

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

data/lib/redgreenblue/opt/philipshue.rb

@@ -0,0 +1,35 @@
+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.
+  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,6 @@
 class RGB
 
+  # Shows the Mac OS color picker to choose a color for the RGB object.
   def pick
     result = RGB.mac_choose(rrggbb)
     if result
@@ -7,10 +8,10 @@ class RGB
     end
   end
 
-# factory method
-
-  def self.pick
-    result = RGB.mac_choose(RGB.new.rrggbb)
+  # Shows the Mac OS color picker and creates an RGB object with the chosen color.
+  # 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,11 +21,14 @@ 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)
 
     script = <<~ENDSCRIPT

data/lib/redgreenblue/random.rb

@@ -1,17 +1,20 @@
 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
 
+  # 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,29 @@
 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
 
+  # 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
 
-  # 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
 

data/lib/redgreenblue/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redgreenblue
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - lllist.eu
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-24 00:00:00.000000000 Z
+date: 2019-11-11 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: 
@@ -23,9 +23,11 @@ files:
 - lib/redgreenblue/bgr24bit.rb
 - lib/redgreenblue/gif.rb
 - lib/redgreenblue/hex.rb
+- lib/redgreenblue/hsl_hsv.rb
 - lib/redgreenblue/lazy.rb
 - lib/redgreenblue/misc.rb
 - lib/redgreenblue/nice.rb
+- lib/redgreenblue/opt/philipshue.rb
 - lib/redgreenblue/os.rb
 - lib/redgreenblue/os/mac.rb
 - lib/redgreenblue/random.rb
@@ -53,5 +55,5 @@ requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: RGB colors for Ruby
+summary: A simple Ruby library for handling RGB colors
 test_files: []