redgreenblue 0.9.0 → 0.14.0

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

@@ -0,0 +1,14 @@
+class RGB
+
+  # Returns the color's hue (0..360), whiteness (0..1), and blackness (0..1), as defined by the HWB color model.
+  #
+  # For achromatic colors, hue is nil.
+  #
+  # Based on:
+  # - http://alvyray.com/Papers/CG/HWB_JGTv208.pdf (PDF)
+  # - https://en.wikipedia.org/wiki/HWB_color_model
+  def hwb
+    [ hsv_h, cwk[1,2] ].flatten
+  end
+
+end

data/lib/redgreenblue/inspect.rb

@@ -3,11 +3,11 @@ 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
@@ -15,13 +15,17 @@ class RGB
   end
 
   def _inspect_short
-    _inspect_swatch + " ##{hex}"
+    "#{_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.
@@ -38,7 +42,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/lazy.rb

@@ -1,53 +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 blue RGB object.
-  def self.blue
-    new(0,0,1)
-  end
+    # Creates a pure red RGB object.
+    def red
+      new(1,0,0)
+    end
 
-  # Creates a yellow RGB object.
-  def self.yellow
-    new(1,1,0)
-  end
+    # Creates a pure green RGB object.
+    def green
+      new(0,1,0)
+    end
 
-  # Creates a cyan RGB object.
-  def self.cyan
-    new(0,1,1)
-  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 magenta RGB object.
-  def self.magenta
-    new(1,0,1)
   end
 
 end

data/lib/redgreenblue/mac.rb

@@ -0,0 +1,8 @@
+class RGB
+
+  # Returns the color in the format used by AppleScript (a 48-bit RGB triplet).
+  def applescript
+    "{%i, %i, %i}" % rrggbb
+  end
+
+end

data/lib/redgreenblue/match.rb

@@ -0,0 +1,21 @@
+class RGB
+
+  # Matches this color to a set of colors by calculating their euclidean distance.
+  #
+  # Returns the given set of colors with their distance from this color, sorted by distance (nearest color first).
+  # @example What is nearer: red, grey or white?
+  #  RGB.hex('f9c').match_distance [RGB.red, RGB.grey, RGB.white]
+  def match_distance(others)
+    others.map { |c| [ c, distance(c) ] }.sort_by { |a| a[1] }
+  end
+
+  # Matches this color to a set of colors using the CIE 1976 delta E formula.
+  #
+  # Returns the given set of colors with their difference from this color, sorted by difference (nearest color first).
+  # @example Find the 3 nearest CSS named colors
+  #  RGB.hex('f9c').match_de76(RGB.css).first(3)
+  def match_de76(others)
+    others.map { |c| [ c, de76(c) ] }.sort_by { |a| a[1] }
+  end
+
+end

data/lib/redgreenblue/math.rb

@@ -0,0 +1,9 @@
+class RGB
+
+private
+
+  def zip_add(a,b)
+    a.zip(b).map { |ab| ( ab[0] || 0 ) + ab[1] }
+  end
+
+end

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 ].
@@ -30,4 +36,17 @@ class RGB
     RGB.new(v[0].red, v[1].green, v[2].blue)
   end
 
+  # Returns the euclidean distance between this color and another color.
+  #
+  # When you imagine a color as a point in a 3-dimensional space,
+  # the dimensions being red, green, and blue,
+  # this is the distance between two colors.
+  def distance(another)
+    (
+      ( (another.red   - red  ) ** 2) +
+      ( (another.green - green) ** 2) +
+      ( (another.blue  - blue ) ** 2)
+    ) ** (1/2.0)
+  end
+
 end

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.