redgreenblue 0.8.0 → 0.13.0

data/lib/redgreenblue/hsl.rb

@@ -0,0 +1,96 @@
+require 'redgreenblue/hsx_shared'
+require 'redgreenblue/math'
+
+class RGB
+
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
+
+  class << self
+
+    # Creates a new RGB object from HSL values: hue (0..360), saturation (0..1), and lightness (0..1).
+    def hsl(*a)
+      new hsl_to_values(*a)
+    end
+
+    # Calculates RGB values from HSL.
+    # Given hue (0..360), saturation (0..1), and lightness (0..1),
+    # returns red, green, and blue as three values between 0 and 1.
+    def hsl_to_values(*a)
+      hsm_to_values(:hsl, a)
+    end
+
+  end
+
+  #----------------------------------------------------------------------#
+  #                           Instance Methods                           #
+  #----------------------------------------------------------------------#
+
+  # 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 the object's HSL-hue (0..360).
+  def hsl_h
+    hsl[0]
+  end
+
+  # Returns the object's HSL-saturation (0..1).
+  def hsl_s
+    hsl[1]
+  end
+
+  # Returns the object's HSL-lightness (0..1).
+  def hsl_l
+    hsl[2]
+  end
+
+  # Sets red, green, and blue using HSL values: hue (0..360), saturation (0..1), and lightness (0..1).
+  def hsl=(*a)
+    self.values = RGB.hsl_to_values(*a)
+  end
+
+  # Sets HSL-hue to a number of degrees (0..360) or nil.
+  #
+  # Adjusts red, green, and blue, leaving saturation and lightness unchanged.
+  # When hue is nil, saturation will be 0.
+  def hsl_h=(degrees)
+    self.hsl = hsl.fill(degrees,0,1)
+  end
+
+  # Sets HSL-saturation to a value between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving hue and lightness unchanged.
+  # When saturation is 0, hue will be nil.
+  def hsl_s=(value)
+    self.hsl = hsl.fill(value  ,1,1)
+  end
+
+  # Sets HSL-lightness to a value between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving hue and saturation unchanged.
+  # When lightness is 0 or 1, hue will be nil, and saturation will be 0.
+  def hsl_l=(value)
+    self.hsl = hsl.fill(value  ,2,1)
+  end
+
+  # Sets red, green, and blue by rotating the object's HSL-hue a number of degrees.
+  def hsl_rotate!(degrees)
+    self.hsl = zip_add(hsl, [degrees, 0, 0])
+    self
+  end
+
+  # Creates one or more new RGB objects by rotating this object's HSL-hue a number of degrees.
+  def hsl_rotate(a_degrees, *b_degrees)
+    if a_degrees.class != Array and b_degrees.none?
+      RGB.hsl zip_add(hsl, [a_degrees, 0, 0])
+    else
+      ( [a_degrees] + b_degrees ).flatten.map { |degrees| RGB.hsl zip_add(hsl, [degrees, 0, 0]) }
+    end
+  end
+
+end

data/lib/redgreenblue/hsv.rb

@@ -0,0 +1,96 @@
+require 'redgreenblue/hsx_shared'
+require 'redgreenblue/math'
+
+class RGB
+
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
+
+  class << self
+
+    # Creates a new RGB object from HSV values: hue (0..360), saturation (0..1), and value (0..1).
+    def hsv(*a)
+      new hsv_to_values(*a)
+    end
+
+    # Calculates RGB values from HSV.
+    # Given hue (0..360), saturation (0..1), and value (0..1),
+    # returns red, green, and blue as three values between 0 and 1.
+    def hsv_to_values(*a)
+      hsm_to_values(:hsv, a)
+    end
+
+  end
+
+  #----------------------------------------------------------------------#
+  #                           Instance Methods                           #
+  #----------------------------------------------------------------------#
+
+  # Returns color as HSV:
+  # hue (0..360), saturation (0..1), value (0..1).
+  # When saturation is 0, hue is nil.
+  def hsv
+    hsl_hsv_c[1]
+  end
+
+  # Returns the object's HSV-hue (0..360).
+  def hsv_h
+    hsv[0]
+  end
+
+  # Returns the object's HSV-saturation (0..1).
+  def hsv_s
+    hsv[1]
+  end
+
+  # Returns the object's HSV-value (0..1).
+  def hsv_v
+    hsv[2]
+  end
+
+  # Sets red, green, and blue using HSV values: hue (0..360), saturation (0..1), and value (0..1).
+  def hsv=(*a)
+    self.values = RGB.hsv_to_values(*a)
+  end
+
+  # Sets HSV-hue to a number of degrees (0..360) or nil.
+  #
+  # Adjusts red, green, and blue, leaving HSV-saturation and -value unchanged.
+  # When hue is nil, saturation will be 0.
+  def hsv_h=(degrees)
+    self.hsv = hsv.fill(degrees,0,1)
+  end
+
+  # Sets HSV-saturation to a number between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving HSV-hue and -value unchanged.
+  # When saturation is 0, hue will be nil.
+  def hsv_s=(value)
+    self.hsv = hsv.fill(value  ,1,1)
+  end
+
+  # Sets HSV-value to a number between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving HSV-hue and -saturation unchanged.
+  # When value is 0, hue will be nil, and saturation will be 0.
+  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.
+  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.
+  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])
+    else
+      ( [a_degrees] + b_degrees ).flatten.map { |degrees| RGB.hsv zip_add(hsv, [degrees, 0, 0]) }
+    end
+  end
+
+end

data/lib/redgreenblue/hsx_shared.rb

@@ -0,0 +1,94 @@
+class RGB
+
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
+
+  class << self
+
+    private
+
+    # Calculates RGB values from HSL or HSV.
+    # With help from:
+    # - https://en.wikipedia.org/wiki/HSL_and_HSV
+    def hsm_to_values(type, *a)
+      raise NotImplementedError unless [:hsl, :hsv].include? type
+
+      hue, saturation, magnitude = a.flatten
+
+      if ( saturation == 0 ) or ( ! hue )
+        return Array.new(3) { magnitude }
+      end
+
+      hue = hue.modulo 360
+
+      chroma = case type
+        when :hsl
+          ( 1 - ( 2 * magnitude - 1 ).abs ) * saturation
+        when :hsv
+          magnitude * saturation
+      end
+
+      values = [
+        chroma,
+        ( 1 - ( ( hue / 60.0 ).modulo(2) - 1 ).abs ) * chroma,
+        0
+      ]
+
+      values = case type
+        when :hsl
+          values.map { |v| ( v + magnitude - chroma / 2.0 ).round(9) }
+        when :hsv
+          values.map { |v| ( v + magnitude - chroma       ).round(9) }
+      end
+
+      # order values according to hue sextant
+      [ [0,1,2], [1,0,2], [2,0,1], [2,1,0], [1,2,0], [0,2,1] ][hue.div 60].map { |i| values[i]}
+    end
+
+  end
+
+  #----------------------------------------------------------------------#
+  #                           Instance Methods                           #
+  #----------------------------------------------------------------------#
+
+  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
+        ).round(6)
+      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/inspect.rb

@@ -3,34 +3,54 @@ class RGB
   private
 
   def _inspect_default(prefix='RGB')
-    "#{prefix} ##{hex} (red=%1.5f green=%1.5f blue=%1.5f)" % [red, green, blue]
+    "#{prefix} #{_inspect_hex} (red=%1.5f green=%1.5f blue=%1.5f)" % [red, green, blue] + ( name ? ' ' + name : '' )
   end
 
   def _inspect_hex
-    "##{hex}"
+    (self == snap ? '#' : '~') + hex
   end
 
   def _inspect_swatch
     terminal_background + "   \e[0m"
   end
 
+  def _inspect_short
+    "#{_inspect_swatch} #{_inspect_hex}"
+  end
+
   def _inspect_simple
     _inspect_default _inspect_swatch
   end
 
+  def _inspect_name
+    _inspect_swatch + ( name ? ' ' + name : '' )
+  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
 
   # 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.
@@ -44,6 +64,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

@@ -1,38 +1,73 @@
 class RGB
 
-  # Creates a white RGB object.
-  def self.white
-    new(1,1,1)
-  end
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
 
-  # Creates a black RGB object.
-  def self.black
-    new(0,0,0)
-  end
+  class << self
 
-  # 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
+    # Creates a white RGB object.
+    def white
+      new(1,1,1)
+    end
 
-  # Alias gray for grey.
-  self.singleton_class.send(:alias_method, :gray, :grey)
+    # Creates a black RGB object.
+    def black
+      new(0,0,0)
+    end
 
-  # Creates a pure red RGB object.
-  def self.red
-    new(1,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 grey(lightness=0.5)
+      new(lightness, lightness, lightness)
+    end
 
-  # Creates a pure green RGB object.
-  def self.green
-    new(0,1,0)
-  end
+    # Alias gray for grey.
+    alias gray grey
+
+    # Creates a pure red RGB object.
+    def red
+      new(1,0,0)
+    end
+
+    # Creates a pure green RGB object.
+    def green
+      new(0,1,0)
+    end
+
+    # Creates a pure blue RGB object.
+    def blue
+      new(0,0,1)
+    end
+
+    # Creates a yellow RGB object.
+    def yellow
+      new(1,1,0)
+    end
+
+    # Creates a cyan RGB object.
+    def cyan
+      new(0,1,1)
+    end
+
+    # Creates a magenta RGB object.
+    def magenta
+      new(1,0,1)
+    end
+
+    # Returns the 8 corners of the RGB cube.
+    def corners
+      [ black, red, yellow, green, cyan, blue, magenta, white ]
+    end
+
+    # Returns the centre of the RGB cube.
+    def centre
+      grey
+    end
+
+    alias center centre
 
-  # Creates a pure blue RGB object.
-  def self.blue
-    new(0,0,1)
   end
 
 end