redgreenblue 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb9542466d29c9ddcec8d53f6a374c228cc39f22b8d17e4c7c5b93f4f6095821
-  data.tar.gz: 53b0e22ef0143e5110fc33d6f0cd68615a5b9931c1cd31a790dfc08adc9f2198
+  metadata.gz: dc4e866d75637857fb5a4b27b77829e20f488e321fa287b73a5d6d9c21d194a9
+  data.tar.gz: e3f9e875b0a8893bd21a6cd503702881833f54873557f84c4cf4776338294668
 SHA512:
-  metadata.gz: dd97d2edb6a6503c99aa1ee055297d2dcfa21a330234b3c6fb01cf2551cad6ca5c7796103c94d99a7ba51ee33547f508551e3e4376029243eccbd77199b5ddde
-  data.tar.gz: 3b7e6ca19d6c3ee4aafda566cd4187c735e4af0d59f2a2ee09f7e7602a7efb2359c8adaed08eb14c2af9e36c254e299bcbb253cea8755b5b8ead7f8dc7816541
+  metadata.gz: 94b96125e65443d7ceb66cfabf9ba6b0681bfc51046b8d308e86d0904a58a7f745f6ea159a040ee79dcb9713ace9adbc416a5705c4b2ebb85333bf09f0dd9a43
+  data.tar.gz: f3e0bd4c0cdcd432dd50fc518f1d2062c66ac907f55b3235405589b2d797791c48b3d62284ae665a8fc4d60c4209ce0b3d46d07a459e15d2fa261d9b1aa8df1d

data/lib/redgreenblue.rb

@@ -1,33 +1,26 @@
 class RGB
 end
 
-require 'redgreenblue/version'
+%w(
 
-require 'redgreenblue/base'
+  version
 
-require 'redgreenblue/24bit'
-require 'redgreenblue/48bit'
-require 'redgreenblue/hex'
-require 'redgreenblue/int'
+  base
 
-require 'redgreenblue/hsl'
-require 'redgreenblue/hsv'
-require 'redgreenblue/hsb'
+  24bit 48bit hex int
 
-require 'redgreenblue/gamma'
-require 'redgreenblue/cie'
+  hsl hsv hsb
 
-require 'redgreenblue/inspect'
-require 'redgreenblue/lazy'
+  ostwald
 
-require 'redgreenblue/rgb565'
-require 'redgreenblue/bgr24bit'
-require 'redgreenblue/gif'
-require 'redgreenblue/terminal'
-require 'redgreenblue/web'
+  gamma cie
 
-require 'redgreenblue/mix'
-require 'redgreenblue/misc'
-require 'redgreenblue/random'
+  inspect lazy
 
-require 'redgreenblue/os'
+  rgb565 bgr24bit gif terminal web gpl
+
+  mix misc random
+
+  os
+
+).each { |m| require "redgreenblue/#{m}" }

data/lib/redgreenblue/24bit.rb

@@ -51,6 +51,17 @@ class RGB
     c
   end
 
+  # Sets the red, green, and blue values to those of the nearest 24-bit color.
+  def snap!
+    self.rgb = rgb
+    self
+  end
+
+  # Creates a new RGB object containing the nearest 24-bit color.
+  def snap
+    RGB.rgb rgb
+  end
+
   # Calls the given block for each 24-bit RGB color (from black to white), passing the color as an RGB object.
   #
   # Returns the number of iterations.

data/lib/redgreenblue/gpl.rb

@@ -0,0 +1,30 @@
+class RGB
+
+  ########################################################################
+  # Class methods                                                        #
+  ########################################################################
+
+  class << self
+
+    private
+
+    # Reverse-engineered from:
+    # - https://github.com/GNOME/gimp/blob/5d79fba8238a27b8691556489898d33b3fa0dda0/app/core/gimppalette-load.c
+    def gpl_header(name, columns=nil)
+      "GIMP Palette\n" +
+      "Name: #{name}\n" +
+      ( columns ? "Columns: #{columns}\n" : '' )
+    end
+
+  end
+
+  ########################################################################
+  # Instance methods                                                     #
+  ########################################################################
+
+  # Returns the color in the format used in .gpl files (Gimp color palettes). A name for the color is optional.
+  def gpl(name=nil)
+    ( "%3d %3d %3d" % rgb ) + ( name ? "\t#{name}" : '' )
+  end
+
+end

data/lib/redgreenblue/hsb.rb

@@ -8,6 +8,7 @@ class RGB
 
   class << self
 
+    # Creates a new RGB object from HSB values: hue (0..360), saturation (0..1), and brightness (0..1).
     alias hsb hsv
 
   end
@@ -16,24 +17,45 @@ class RGB
   # Instance methods                                                     #
   ########################################################################
 
+  # Returns color as HSB:
+  # hue (0..360), saturation (0..1), brightness (0..1).
+  # When saturation is 0, hue is nil.
   alias hsb         hsv
 
+  # Returns the object's HSB-hue (0..360).
   alias hsb_h       hsv_h
 
+  # Returns the object's HSB-saturation (0..1).
   alias hsb_s       hsv_s
 
+  # Returns the object's HSB-brightness (0..1).
   alias hsb_b       hsv_v
 
+  # Sets red, green, and blue using HSB values: hue (0..360), saturation (0..1), and brightness (0..1).
   alias hsb=        hsv=
 
+  # Sets HSB-hue to a number of degrees (0..360) or nil.
+  #
+  # Adjusts red, green, and blue, leaving HSB-saturation and -brightness unchanged.
+  # When hue is nil, saturation will be 0.
   alias hsb_h=      hsv_h=
 
+  # Sets HSB-saturation to a number between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving HSB-hue and -brightness unchanged.
+  # When saturation is 0, hue will be nil.
   alias hsb_s=      hsv_s=
 
+  # Sets HSB-brightness to a number between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving HSB-hue and -saturation unchanged.
+  # When brightness is 0, hue will be nil, and saturation will be 0.
   alias hsb_b=      hsv_v=
 
+  # Sets red, green, and blue by rotating the object's HSB-hue a number of degrees.
   alias hsb_rotate! hsv_rotate!
 
+  # Creates one or more new RGB objects by rotating this object's HSB-hue a number of degrees.
   alias hsb_rotate  hsv_rotate
 
 end

data/lib/redgreenblue/hsv.rb

@@ -10,8 +10,6 @@ class RGB
   class << self
 
     # Creates a new RGB object from HSV values: hue (0..360), saturation (0..1), and value (0..1).
-    #
-    # ::hsb is an alias for ::hsv.
     def hsv(*a)
       new hsv_to_values(*a)
     end
@@ -32,36 +30,26 @@ class RGB
   # 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
 
   # Returns the object's HSV-hue (0..360).
-  #
-  # #hsb_h is an alias for #hsv_h.
   def hsv_h
     hsv[0]
   end
 
   # Returns the object's HSV-saturation (0..1).
-  #
-  # #hsb_s is an alias for #hsv_s.
   def hsv_s
     hsv[1]
   end
 
   # Returns the object's HSV-value (0..1).
-  #
-  # #hsb_b is an alias for #hsv_v.
   def hsv_v
     hsv[2]
   end
 
   # Sets red, green, and blue using HSV values: hue (0..360), saturation (0..1), and value (0..1).
-  #
-  # #hsb= is an alias for #hsv=.
   def hsv=(*a)
     self.values = RGB.hsv_to_values(*a)
   end
@@ -70,8 +58,6 @@ class RGB
   #
   # Adjusts red, green, and blue, leaving HSV-saturation and -value unchanged.
   # When hue is nil, saturation will be 0.
-  #
-  # #hsb_h= is an alias for #hsv_h=.
   def hsv_h=(degrees)
     self.hsv = hsv.fill(degrees,0,1)
   end
@@ -80,8 +66,6 @@ class RGB
   #
   # Adjusts red, green, and blue, leaving HSV-hue and -value unchanged.
   # When saturation is 0, hue will be nil.
-  #
-  # #hsb_s= is an alias for #hsv_s=.
   def hsv_s=(value)
     self.hsv = hsv.fill(value  ,1,1)
   end
@@ -90,23 +74,17 @@ class RGB
   #
   # Adjusts red, green, and blue, leaving HSV-hue and -saturation unchanged.
   # When value is 0, hue will be nil, and saturation will be 0.
-  #
-  # #hsb_b= is an alias for #hsv_v=.
   def hsv_v=(value)
     self.hsv = hsv.fill(value  ,2,1)
   end
 
   # Sets red, green, and blue by rotating the object's HSV-hue a number of degrees.
-  #
-  # #hsb_rotate! is an alias for #hsv_rotate!.
   def hsv_rotate!(degrees)
     self.hsv = zip_add(hsv, [degrees, 0, 0])
     self
   end
 
   # Creates one or more new RGB objects by rotating this object's HSV-hue a number of degrees.
-  #
-  # #hsb_rotate is an alias for #hsv_rotate.
   def hsv_rotate(a_degrees, *b_degrees)
     if a_degrees.class != Array and b_degrees.none?
       RGB.hsv zip_add(hsv, [a_degrees, 0, 0])

data/lib/redgreenblue/inspect.rb

@@ -38,7 +38,15 @@ class RGB
 
   # Returns the base inspect style, dependent on the COLORTERM environment variable.
   def self.base_style
-    ENV['COLORTERM'] == 'truecolor' ? 'simple' : 'default'
+    if styles.include? ENV['REDGREENBLUE_STYLE']
+      ENV['REDGREENBLUE_STYLE']
+    else
+      if ENV['COLORTERM'] == 'truecolor'
+        'simple'
+      else
+        'default'
+      end
+    end
   end
 
   # Returns the current inspect style.

data/lib/redgreenblue/misc.rb

@@ -11,6 +11,12 @@ 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 ].

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,13 @@ 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.

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

@@ -1,7 +1,7 @@
 class RGB
 
   # redgreenblue version.
-  VERSION = '0.10.0'
+  VERSION = '0.11.0'
 
   # Returns RGB::VERSION.
   def self.version

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redgreenblue
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - lllist.eu
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-16 00:00:00.000000000 Z
+date: 2020-06-23 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: 
@@ -24,6 +24,7 @@ files:
 - lib/redgreenblue/cie.rb
 - lib/redgreenblue/gamma.rb
 - lib/redgreenblue/gif.rb
+- lib/redgreenblue/gpl.rb
 - lib/redgreenblue/hex.rb
 - lib/redgreenblue/hsb.rb
 - lib/redgreenblue/hsl.rb
@@ -38,6 +39,7 @@ files:
 - lib/redgreenblue/opt/philipshue.rb
 - lib/redgreenblue/os.rb
 - lib/redgreenblue/os/mac.rb
+- lib/redgreenblue/ostwald.rb
 - lib/redgreenblue/random.rb
 - lib/redgreenblue/rgb565.rb
 - lib/redgreenblue/terminal.rb
@@ -65,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: A simple Ruby library for handling RGB colors.