color 1.7.1 → 2.0.0.pre.0

data/lib/color.rb

@@ -1,112 +1,226 @@
-# :title: Color -- Colour Management with Ruby
-# :main: README.rdoc
-
-# = Colour Management with Ruby
+# frozen_string_literal: true
+
+# # \Color -- \Color Math in Ruby
+#
+# - **code**: [github.com/halostatue/color](https://github.com/halostatue/color)
+# - **issues**: [github.com/halostatue/color/issues](https://github.com/halostatue/color/issues)
+# - **changelog**: [CHANGELOG](rdoc-ref:CHANGELOG.md)
+#
+# \Color is a Ruby library to provide RGB, CMYK, HSL, and other color space manipulation
+# support to applications that require it. It provides 152 named RGB colors that are
+# commonly supported in HTML, SVG, and X11 applications.
+#
+# The \Color library performs purely mathematical manipulation of the colors based on
+# color theory without reference to device color profiles (such as sRGB or Adobe RGB). For
+# most purposes, when working with RGB and HSL color spaces, this won't matter. Absolute
+# color spaces (like CIE LAB and CIE XYZ), however, cannot be reliably converted to
+# relative color spaces (like RGB) without color profiles. When necessary for conversions,
+# \Color provides \D65 and \D50 reference white values in Color::XYZ.
+#
+# \Color 2.0 is a major release to the \Color library, dropping support for all versions of
+# Ruby prior to 3.2.
+#
+# > **NOTE**: This is a pre-release version of \Color 2.0.
+# > The main goals for a 2.0 release have been met: modernizing the codebase, but
+# > consideration will be given to improving color transformation robustness and accuracy
+# > with Matrix operations and Rational numbers instead of floating point decimal values.
+#
+# In \Color 2.0, color objects are immutable (derived from Data) and do not expose the
+# `new` class method, instead using only `from_*` class methods. There is always
+# a `from_values` class method which represents the native color channel values (which may
+# not match the internal representation). This method _may_ have a counterpart that is
+# recommended for readability.
 module Color
-  COLOR_VERSION = '1.7.1'
-
-  class RGB; end
-  class CMYK; end
-  class HSL; end
-  class GrayScale; end
-  class YIQ; end
-
-  # The maximum "resolution" for colour math; if any value is less than or
-  # equal to this value, it is treated as zero.
-  COLOR_EPSILON = 1e-5
-  # The tolerance for comparing the components of two colours. In general,
-  # colours are considered equal if all of their components are within this
-  # tolerance value of each other.
-  COLOR_TOLERANCE = 1e-4
-
-  # Compares the +other+ colour to this one. The +other+ colour will be
-  # coerced to the same type as the current colour. Such converted colour
-  # comparisons will always be more approximate than non-converted
-  # comparisons.
+  ##
+  # The maximum "resolution" for color math; if any value is less than or equal to this
+  # value, it is treated as zero.
+  EPSILON = 1e-5
+
+  ##
+  # The tolerance for comparing the components of two colors. In general, colors are
+  # considered equal if all of their components are within this tolerance value of each
+  # other.
+  TOLERANCE = 1e-4
+
+  # :stopdoc:
+  CIELAB = Data.define(:l, :a, :b)
+  CMYK = Data.define(:c, :m, :y, :k)
+  Grayscale = Data.define(:g)
+  HSL = Data.define(:h, :s, :l)
+  RGB = Data.define(:r, :g, :b, :names)
+  XYZ = Data.define(:x, :y, :z)
+  YIQ = Data.define(:y, :i, :q)
+  # :startdoc:
+
+  ##
+  # It is useful to know the number of components in some cases. Since most colors are
+  # defined with three components, we define a constant value here. Color classes that
+  # require more or less should override this.
   #
-  # If the +other+ colour cannot be coerced to the current colour class, a
-  # +NoMethodError+ exception will be raised.
+  # We _could_ define this as `members.count`, but this would require a special case
+  # for Color::RGB _regardless_ because there's an additional member for RGB colors
+  # (names).
+  def components = 3 # :nodoc:
+
+  ##
+  # Compares the `other` color to this one. The `other` color will be coerced to the same
+  # type as the current color. Such converted color comparisons will always be more
+  # approximate than non-converted comparisons.
   #
-  # All values are compared as floating-point values, so two colours will be
-  # reported equivalent if all component values are within COLOR_TOLERANCE
-  # of each other.
+  # All values are compared as floating-point values, so two colors will be reported
+  # equivalent if all component values are within +TOLERANCE+ of each other.
   def ==(other)
-    Color.equivalent?(self, other)
+    other.is_a?(Color) && to_internal.zip(coerce(other).to_internal).all? { near?(_1, _2) }
   end
 
-  # The primary name for the colour.
-  def name
-    names.first
-  end
+  ##
+  # Apply the provided block to each color component in turn, returning a new color
+  # instance.
+  def map(&block) = self.class.from_internal(*to_internal.map(&block))
 
-  # All names for the colour.
-  def names
-    self.names = nil unless defined? @names
-    @names
-  end
-  def names=(n) # :nodoc:
-    @names = Array(n).flatten.compact.map(&:to_s).map(&:downcase).sort.uniq
-  end
-  alias_method :name=, :names=
-end
+  ##
+  # Apply the provided block to the color component pairs in turn, returning a new color
+  # instance.
+  def map_with(other, &block) = self.class.from_internal(*zip(other).map(&block))
 
-class << Color
-  # Returns +true+ if the value is less than COLOR_EPSILON.
-  def near_zero?(value)
-    (value.abs <= Color::COLOR_EPSILON)
-  end
+  ##
+  # Zip the color component pairs together.
+  def zip(other) = to_internal.zip(coerce(other).to_internal)
 
-  # Returns +true+ if the value is within COLOR_EPSILON of zero or less than
-  # zero.
-  def near_zero_or_less?(value)
-    (value < 0.0 or near_zero?(value))
+  ##
+  # Multiplies each component value by the scaling factor or factors, returning a new
+  # color object with the scaled values.
+  #
+  # If a single scaling factor is provided, it is applied to all components:
+  #
+  # ```ruby
+  # rgb = Color::RGB::Wheat # => RGB [#f5deb3]
+  # rgb.scale(0.75)         # => RGB [#b8a786]
+  # ```
+  #
+  # If more than one scaling factor is provided, there must be exactly one factor for each
+  # color component of the color object or an `ArgumentError` will be raised.
+  #
+  # ```ruby
+  # rgb = Color::RGB::Wheat # => RGB [#f5deb3]
+  # # 0xf5 * 0 == 0x00, 0xde * 0.5 == 0x6f, 0xb3 * 2 == 0x166 (clamped to 0xff)
+  # rgb.scale(0, 0.5, 2)    # => RGB [#006fff]
+  #
+  # rgb.scale(1, 2) # => Invalid scaling factors [1, 2] for Color::RGB (ArgumentError)
+  # ```
+  def scale(*factors)
+    if factors.size == 1
+      factor = factors.first
+      map { _1 * factor }
+    elsif factors.size != components
+      raise ArgumentError, "Invalid scaling factors #{factors.inspect} for #{self.class}"
+    else
+      new_components = to_internal.zip(factors).map { _1 * _2 }
+      self.class.from_internal(*new_components)
+    end
   end
 
-  # Returns +true+ if the value is within COLOR_EPSILON of one.
-  def near_one?(value)
-    near_zero?(value - 1.0)
+  ##
+  def css_value(value, format = nil) # :nodoc:
+    if value.nil?
+      "none"
+    elsif near_zero?(value)
+      "0"
+    else
+      suffix =
+        case format
+        in :percent
+          "%"
+        in :degrees
+          "deg"
+        else
+          ""
+        end
+
+      "%3.2f%s" % [value, suffix]
+    end
   end
 
-  # Returns +true+ if the value is within COLOR_EPSILON of one or more than
-  # one.
-  def near_one_or_more?(value)
-    (value > 1.0 or near_one?(value))
-  end
+  private
+
+  ##
+  def from_internal(...) = self.class.from_internal(...)
+
+  ##
+  # Returns `true` if the value is less than EPSILON.
+  def near_zero?(value) = (value.abs <= Color::EPSILON) # :nodoc:
+
+  ##
+  # Returns `true` if the value is within EPSILON of zero or less than zero.
+  def near_zero_or_less?(value) = (value < 0.0 or near_zero?(value)) # :nodoc:
+
+  ##
+  # Returns +true+ if the value is within EPSILON of one.
+  def near_one?(value) = near_zero?(value - 1.0) # :nodoc:
+
+  ##
+  # Returns +true+ if the value is within EPSILON of one or more than one.
+  def near_one_or_more?(value) = (value > 1.0 or near_one?(value)) # :nodoc:
 
+  ##
   # Returns +true+ if the two values provided are near each other.
-  def near?(x, y)
-    (x - y).abs <= Color::COLOR_TOLERANCE
-  end
+  def near?(x, y) = (x - y).abs <= Color::TOLERANCE # :nodoc:
 
-  # Returns +true+ if the two colours are roughly equivalent. If colour
-  # conversions are required, this all conversions will be implemented
-  # using the default conversion mechanism.
-  def equivalent?(a, b)
-    a.to_a.zip(a.coerce(b).to_a).all? { |(x, y)| near?(x, y) }
+  ##
+  def to_degrees(radians) # :nodoc:
+    if radians < 0
+      (Math::PI + radians % -Math::PI) * (180 / Math::PI) + 180
+    else
+      (radians % Math::PI) * (180 / Math::PI)
+    end
   end
 
-  # Coerces, if possible, the second given colour object to the first
-  # given colour object type. This will probably involve colour
-  # conversion and therefore a loss of fidelity.
-  def coerce(a, b)
-    a.coerce(b)
+  ##
+  def to_radians(degrees) # :nodoc:
+    degrees = ((degrees % 360) + 360) % 360
+    if degrees >= 180
+      Math::PI * (degrees - 360) / 180.0
+    else
+      Math::PI * degrees / 180.0
+    end
   end
 
+  ##
   # Normalizes the value to the range (0.0) .. (1.0).
-  def normalize(value)
-    if near_zero_or_less? value
-      0.0
-    elsif near_one_or_more? value
-      1.0
+  module_function def normalize(value, range = 0.0..1.0) # :nodoc:
+    value = value.clamp(range)
+    if near?(value, range.begin)
+      range.begin
+    elsif near?(value, range.end)
+      range.end
     else
       value
     end
   end
-  alias normalize_fractional normalize
 
+  ##
+  # Translates a value from range `from` to range `to`. Both ranges must be closed.
+  # As 0.0 .. 1.0 is a common internal range, it is the default for `from`.
+  #
+  # This is based on the formula:
+  #
+  #     [a, b] ← from ← [from.begin, from.end]
+  #     [c, d] ← to ← [to.begin, to.end]
+  #
+  #     y = (((x - a) * (d - c)) / (b - a)) + c
+  #
+  # The value is clamped to the values of `to`.
+  module_function def translate_range(x, to:, from: 0.0..1.0) # :nodoc:
+    a, b = [from.begin, from.end]
+    c, d = [to.begin, to.end]
+    y = (((x - a) * (d - c)) / (b - a)) + c
+    y.clamp(to)
+  end
+
+  ##
   # Normalizes the value to the specified range.
-  def normalize_to_range(value, range)
-    range = (range.end..range.begin) if (range.end < range.begin)
+  def normalize_to_range(value, range) # :nodoc:
+    range = (range.end..range.begin) if range.end < range.begin
 
     if value <= range.begin
       range.begin
@@ -117,68 +231,21 @@ class << Color
     end
   end
 
+  ##
   # Normalize the value to the range (0) .. (255).
-  def normalize_byte(value)
-    normalize_to_range(value, 0..255).to_i
-  end
-  alias normalize_8bit normalize_byte
+  def normalize_byte(value) = normalize_to_range(value, 0..255).to_i # :nodoc:
 
+  ##
   # Normalize the value to the range (0) .. (65535).
-  def normalize_word(value)
-    normalize_to_range(value, 0..65535).to_i
-  end
-  alias normalize_16bit normalize_word
+  def normalize_word(value) = normalize_to_range(value, 0..65535).to_i # :nodoc:
 end
 
-require 'color/rgb'
-require 'color/cmyk'
-require 'color/grayscale'
-require 'color/hsl'
-require 'color/yiq'
-require 'color/css'
-
-class << Color
-  def const_missing(name) #:nodoc:
-    case name
-    when "VERSION", :VERSION, "COLOR_TOOLS_VERSION", :COLOR_TOOLS_VERSION
-      warn "Color::#{name} has been deprecated. Use Color::COLOR_VERSION instead."
-      Color::COLOR_VERSION
-    else
-      if Color::RGB.const_defined?(name)
-        warn "Color::#{name} has been deprecated. Use Color::RGB::#{name} instead."
-        Color::RGB.const_get(name)
-      else
-        super
-      end
-    end
-  end
+require "color/cmyk"
+require "color/grayscale"
+require "color/hsl"
+require "color/cielab"
+require "color/rgb"
+require "color/xyz"
+require "color/yiq"
 
-  # Provides a thin veneer over the Color module to make it seem like this
-  # is Color 0.1.0 (a class) and not Color 1.4 (a module). This
-  # "constructor" will be removed in the future.
-  #
-  # mode = :hsl::   +values+ must be an array of [ hue deg, sat %, lum % ].
-  #                 A Color::HSL object will be created.
-  # mode = :rgb::   +values+ will either be an HTML-style colour string or
-  #                 an array of [ red, green, blue ] (range 0 .. 255). A
-  #                 Color::RGB object will be created.
-  # mode = :cmyk::  +values+ must be an array of [ cyan %, magenta %, yellow
-  #                 %, black % ]. A Color::CMYK object will be created.
-  def new(values, mode = :rgb)
-    warn "Color.new has been deprecated. Use Color::#{mode.to_s.upcase}.new instead."
-    color = case mode
-            when :hsl
-              Color::HSL.new(*values)
-            when :rgb
-              values = [ values ].flatten
-              if values.size == 1
-                Color::RGB.from_html(*values)
-              else
-                Color::RGB.new(*values)
-              end
-            when :cmyk
-              Color::CMYK.new(*values)
-            end
-    color.to_hsl
-  end
-end
+require "color/version"