redgreenblue 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 766113ae54ad00c066d264e8bd8d63610f5347e75d95aee3c34bacac0b027a99
-  data.tar.gz: a91d7d49e36ebfc29328e32c2aa67df908e4fbc9d36c4ec957e1e6d8ed3220b7
+  metadata.gz: 3acd4edad3c6c358886e6c49138133f207571b610d8ea980fd6ff4d0cb38b7a8
+  data.tar.gz: 81833b3ed57dfcde3c0558f196e7be284ac040e56330019a994e214b39c75463
 SHA512:
-  metadata.gz: 587d547ca6139b84ef36f8064a768aee1cdb3f5618f4f03c9ab606df477ad6ebffe82b00837fe55b06fcf2ba6275a1d85484f758394755567b1aab81351bf1df
-  data.tar.gz: e5203156810f3f577bbe20de7d862f96518db292b1f848778dc2c9dc5223b16c9e15e6effc2e08ed4dba655891805873fdf95cda511c5a533f87462200401746
+  metadata.gz: 57a8b63684a52f0495ee14c47a391a42bce9ce40914b9eee7523d1685fc4a66135ccb453b9c5c2ab68900dc700266e71651cb420fd0cd3cbdcf57cecb3012d27
+  data.tar.gz: 78917822fe1a7cd67acc98912adf1107736609fd996300003bc7c77ff02cbfcdabf6efce4b86481f27dbb568612237dbee726563de76dab1b60188b9c27e2ef8

data/lib/redgreenblue.rb

@@ -8,7 +8,9 @@ require 'redgreenblue/base'
 require 'redgreenblue/24bit'
 require 'redgreenblue/48bit'
 require 'redgreenblue/hex'
+require 'redgreenblue/int'
 
+require 'redgreenblue/gamma'
 require 'redgreenblue/hsl_hsv'
 require 'redgreenblue/cie'
 

data/lib/redgreenblue/base.rb

@@ -66,7 +66,7 @@ class RGB
     ( self.class == other.class ) && ( self.values == other.values )
   end
 
-  # Returns a sorted hash of 3 key/value pairs for red, green and blue,
+  # 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 {

data/lib/redgreenblue/cie.rb

@@ -8,7 +8,7 @@ class RGB
   # sRGB to XYZ matrix for D65 reference white by Bruce Lindbloom:
   # - http://www.brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html
   def cie_xyz
-    r, g, b = expanded_srgb_values
+    r, g, b = linear_values
     [
       r * 0.4124564 + g * 0.3575761 + b * 0.1804375,
       r * 0.2126729 + g * 0.7151522 + b * 0.0721750,
@@ -42,21 +42,4 @@ class RGB
 
   alias xy cie_xy
 
-  private
-
-  # Returns gamma-expanded (inverse-companded) RGB values for sRGB.
-  #
-  # Based on:
-  # - https://en.wikipedia.org/wiki/SRGB
-  # - http://www.brucelindbloom.com/Eqn_RGB_to_XYZ.html
-  def expanded_srgb_values
-    values.map { |v|
-      if v <= 0.04045
-        v / 12.92
-      else
-        ( ( v + 0.055 ) / 1.055 ) ** 2.4
-      end
-    }
-  end
-
 end

data/lib/redgreenblue/gamma.rb

@@ -0,0 +1,44 @@
+class RGB
+
+  # Returns gamma-expanded (inverse-companded) RGB values for the object (three values between 0 and 1).
+  #
+  # Based on:
+  # - https://en.wikipedia.org/wiki/SRGB
+  # - http://www.brucelindbloom.com/Eqn_RGB_to_XYZ.html
+  # - https://entropymine.com/imageworsener/srgbformula/
+  def linear_values
+    if color_space == 'sRGB'
+      values.map { |v|
+        if v <= 0.04045
+          v / 12.92
+        else
+          ( ( v + 0.055 ) / 1.055 ) ** 2.4
+        end
+      }
+    else
+      raise "can not compute gamma for color space '#{color_space}'"
+    end
+  end
+
+  # Sets the object's RGB values using three linear RGB values, each between 0 and 1.
+  # Linear values will be converted to the object's gamma (gamma-companded).
+  #
+  # Based on:
+  # - https://en.wikipedia.org/wiki/SRGB
+  # - http://www.brucelindbloom.com/Eqn_XYZ_to_RGB.html
+  # - https://entropymine.com/imageworsener/srgbformula/
+  def linear_values=(*a)
+    if color_space == 'sRGB'
+      self.values = a.flatten.map { |v|
+        if v <= 0.0031308
+          v * 12.92
+        else
+          1.055 * ( v ** ( 1/2.4 ) ) - 0.055
+        end
+      }.map { |v| v.round(9) }
+    else
+      raise "can not compute gamma for color space '#{color_space}'"
+    end
+  end
+
+end

data/lib/redgreenblue/inspect.rb

@@ -14,16 +14,24 @@ class RGB
     terminal_background + "   \e[0m"
   end
 
+  def _inspect_short
+    _inspect_swatch + " ##{hex}"
+  end
+
   def _inspect_simple
     _inspect_default _inspect_swatch
   end
 
   public
 
+  # Returns a programmer-friendly representation of the object.
+  #
+  # You can choose among several inspect styles. See the styles, style, and style= class methods.
   def inspect
     send "_inspect_#{self.class.style}"
   end
 
+  # Returns a string representation of the object.
   def to_s
     _inspect_default
   end
@@ -44,6 +52,8 @@ class RGB
   end
 
   # Selects an inspect style.
+  #
+  # Only the first few characters of your preferred style are required.
   def self.style=(s)
     @@style = styles.grep( /^#{s.to_s.downcase}/ ).first || style
   end

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/misc.rb

@@ -13,8 +13,8 @@ class RGB
 
   # 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 +24,10 @@ 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
+
 end

data/lib/redgreenblue/mix.rb

@@ -31,6 +31,19 @@ class RGB
     mix(RGB.black, portion)
   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)

data/lib/redgreenblue/opt/philipshue.rb

@@ -1,4 +1,8 @@
 # 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'
@@ -8,6 +12,7 @@ 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.
+  # Only available when optional support for Philips Hue lights is loaded (require 'redgreenblue/opt/philipshue').
   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)

data/lib/redgreenblue/rgb565.rb

@@ -15,8 +15,13 @@ 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
+  # 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
 

data/lib/redgreenblue/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redgreenblue
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - lllist.eu
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-12-20 00:00:00.000000000 Z
+date: 2020-03-02 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: 
@@ -22,10 +22,12 @@ files:
 - lib/redgreenblue/base.rb
 - lib/redgreenblue/bgr24bit.rb
 - lib/redgreenblue/cie.rb
+- lib/redgreenblue/gamma.rb
 - lib/redgreenblue/gif.rb
 - lib/redgreenblue/hex.rb
 - lib/redgreenblue/hsl_hsv.rb
 - lib/redgreenblue/inspect.rb
+- lib/redgreenblue/int.rb
 - lib/redgreenblue/lazy.rb
 - lib/redgreenblue/misc.rb
 - lib/redgreenblue/mix.rb
@@ -40,7 +42,8 @@ files:
 homepage: https://github.com/lllisteu/redgreenblue
 licenses:
 - MIT
-metadata: {}
+metadata:
+  changelog_uri: https://github.com/lllisteu/redgreenblue/blob/master/History.md
 post_install_message: 
 rdoc_options: []
 require_paths: