color 1.7.1 → 2.0.0.pre.0

data/lib/color/cmyk.rb

@@ -1,263 +1,329 @@
-# An CMYK colour object. CMYK (cyan, magenta, yellow, and black) colours are
-# based on additive percentages of ink. A CMYK colour of (0.3, 0, 0.8, 0.3)
-# would be mixed from 30% cyan, 0% magenta, 80% yellow, and 30% black.
-# Primarily used in four-colour printing processes.
+# frozen_string_literal: true
+
+##
+# The \CMYK color model is a subtractive color model based on additive percentages of
+# colored inks: cyan, magenta, yellow, and key (most often black).
+#
+# \CMYK [30% 0% 80% 30%] would be mixed from 30% cyan, 0% magenta, 80% yellow, and 30%
+# black.
+#
+# \CMYK colors are immutable Data class instances. Array deconstruction is `[cyan,
+# magenta, yellow, key]` and hash deconstruction is `{c:, cyan:, m:, magenta:, y:, yellow:
+# k:, key:}`. See #c, #cyan, #m, #magenta, #y, #yellow, #k, #key.
 class Color::CMYK
   include Color
 
-  # The format of a DeviceCMYK colour for PDF. In color-tools 2.0 this will
-  # be removed from this package and added back as a modification by the
-  # PDF::Writer package.
-  PDF_FORMAT_STR = "%.3f %.3f %.3f %.3f %s"
+  ##
+  # :attr_reader: c
+  # Returns the cyan (`C`) component as a value 0.0 .. 1.0.
 
-  # Coerces the other Color object into CMYK.
-  def coerce(other)
-    other.to_cmyk
-  end
+  ##
+  # :attr_reader: cyan
+  # Returns the cyan (`C`) component as a percentage value (0.0 .. 100.0).
 
-  class << self
-    # Creates a CMYK colour object from fractional values 0..1.
-    #
-    #   Color::CMYK.from_fraction(0.3, 0, 0.8, 0.3)
-    def from_fraction(c = 0, m = 0, y = 0, k = 0, &block)
-      new(c, m, y, k, 1.0, &block)
-    end
+  ##
+  # :attr_reader: m
+  # Returns the magenta (`M`) component as a value 0.0 .. 1.0.
 
-    # Creates a CMYK colour object from percentages. Internally, the colour is
-    # managed as fractional values 0..1.
-    #
-    #   Color::CMYK.new(30, 0, 80, 30)
-    def from_percent(c = 0, m = 0, y = 0, k = 0, &block)
-      new(c, m, y, k, &block)
-    end
-  end
+  ##
+  # :attr_reader: magenta
+  # Returns the magenta (`M`) component as a percentage value (0.0 .. 100.0).
+
+  ##
+  # :attr_reader: y
+  # Returns the yellow (`Y`) component as a value 0.0 .. 1.0.
+
+  ##
+  # :attr_reader: yellow
+  # Returns the yellow (`Y`) component as a percentage value (0.0 .. 100.0).
+
+  ##
+  # :attr_reader: k
+  # Returns the key or black (`K`) component as a value 0.0 .. 1.0.
+
+  ##
+  # :attr_reader: b
+  # Returns the key or black (`K`) component as a value 0.0 .. 1.0.
 
-  # Creates a CMYK colour object from percentages. Internally, the colour is
-  # managed as fractional values 0..1.
+  ##
+  # :attr_reader: key
+  # Returns the key or black (`K`) component as a percentage value (0.0 .. 100.0).
+
+  ##
+  # :attr_reader: black
+  # Returns the key or black (`K`) component as a percentage value (0.0 .. 100.0).
+
+  ##
+  # Creates a CMYK color object from percentage values (0.0 .. 100.0).
   #
-  #   Color::CMYK.new(30, 0, 80, 30)
-  def initialize(c = 0, m = 0, y = 0, k = 0, radix = 100.0, &block) # :yields self:
-    @c, @m, @y, @k = [ c, m, y, k ].map { |v| Color.normalize(v / radix) }
-    block.call(self) if block
-  end
+  # ```ruby
+  # Color::CMYK.from_percentage(30, 0, 80, 30) # => CMYK [30.00% 0.00% 80.00% 30.00%]
+  # Color::CMYK.from_values(30, 0, 80, 30)     # => CMYK [30.00% 0.00% 80.00% 30.00%]
+  # ```
+  #
+  # :call-seq:
+  #   from_percentage(c, m, y, k)
+  #   from_percentage(c:, m:, y:, k:)
+  #   from_values(c, m, y, k)
+  #   from_values(c:, m:, y:, k:)
+  def self.from_percentage(*args, **kwargs)
+    c, m, y, k =
+      case [args, kwargs]
+      in [[_, _, _, _], {}]
+        args
+      in [[], {c:, m:, y:, k:}]
+        [c, m, y, k]
+      else
+        new(*args, **kwargs)
+      end
 
-  # Present the colour as a DeviceCMYK fill colour string for PDF. This will
-  # be removed from the default package in color-tools 2.0.
-  def pdf_fill
-    PDF_FORMAT_STR % [ @c, @m, @y, @k, "k" ]
+    new(c: c / 100.0, m: m / 100.0, y: y / 100.0, k: k / 100.0)
   end
 
-  # Present the colour as a DeviceCMYK stroke colour string for PDF. This
-  # will be removed from the default package in color-tools 2.0.
-  def pdf_stroke
-    PDF_FORMAT_STR % [ @c, @m, @y, @k, "K" ]
-  end
+  class << self
+    alias_method :from_values, :from_percentage
 
-  # Present the colour as an RGB HTML/CSS colour string (e.g., "#aabbcc").
-  # Note that this will perform a #to_rgb operation using the default
-  # conversion formula.
-  def html
-    to_rgb.html
+    alias_method :from_fraction, :new
+    alias_method :from_internal, :new # :nodoc:
   end
 
-  # Present the colour as an RGB HTML/CSS colour string (e.g., "rgb(0%, 50%,
-  # 100%)"). Note that this will perform a #to_rgb operation using the
-  # default conversion formula.
-  def css_rgb
-    to_rgb.css_rgb
+  ##
+  # Creates a CMYK color object from fractional values (0.0 .. 1.0).
+  #
+  # ```ruby
+  # Color::CMYK.from_fraction(0.3, 0, 0.8, 0.3) # => CMYK [30.00% 0.00% 80.00% 30.00%]
+  # Color::CMYK.new(0.3, 0, 0.8, 0.3)           # => CMYK [30.00% 0.00% 80.00% 30.00%]
+  # Color::CMYK[c: 0.3, m: 0, y: 0.8, k: 0.3]   # => CMYK [30.00% 0.00% 80.00% 30.00%]
+  # ```
+  def initialize(c:, m:, y:, k:)
+    super(c: normalize(c), m: normalize(m), y: normalize(y), k: normalize(k))
   end
 
-  # Present the colour as an RGBA (with alpha) HTML/CSS colour string (e.g.,
-  # "rgb(0%, 50%, 100%, 1)"). Note that this will perform a #to_rgb
-  # operation using the default conversion formula.
-  def css_rgba
-    to_rgb.css_rgba
+  ##
+  # Output a CSS representation of the CMYK color using `device-cmyk()`.
+  #
+  # If an `alpha` value is provided, it will be included in the output.
+  #
+  # A `fallback` may be provided or included automatically depending on the value
+  # provided, which may be `true`, `false`, a Color object, or a Hash with `:color` and/or
+  # `:alpha` keys. The default value is `true`.
+  #
+  # When `fallback` is:
+  #
+  # - `true`: this CMYK color will be converted to RGB and this will be provided as the
+  #   fallback color. If an `alpha` value is provided, it will be used for the fallback.
+  # - `false`: no fallback color will be included.
+  # - a Color object will be used to produce the `fallback` value.
+  # - a Hash will be checked for `:color` and/or `:alpha` keys:
+  #   - if `:color` is present, it will be used for the fallback color; if not present,
+  #     the CMYK color will be converted to RGB.
+  #   - if `:alpha` is present, it will be used for the fallback color; if not present,
+  #     the fallback color will be presented _without_ alpha.
+  #
+  # Examples:
+  #
+  # ```ruby
+  # cmyk = Color::CMYK.from_percentage(30, 0, 80, 30)
+  # cmyk.css
+  # # => device-cmyk(30.00% 0 80.00% 30.00%, rgb(49.00% 70.00% 14.00%))
+  #
+  # cmyk.css(alpha: 0.5)
+  # # => device-cmyk(30.00% 0 80.00% 30.00% / 0.50, rgb(49.00% 70.00% 14.00% / 0.50))
+  #
+  # cmyk.css(fallback: false)
+  # # => device-cmyk(30.00% 0 80.00% 30.00%)
+  #
+  # cmyk.css(alpha: 0.5, fallback: false)
+  # # => device-cmyk(30.00% 0 80.00% 30.00% / 0.50)
+  #
+  # cmyk.css(fallback: Color::RGB::Blue)
+  # # => device-cmyk(30.00% 0 80.00% 30.00%, rgb(0.00% 0.00% 100.00%))
+  #
+  # cmyk.css(alpha: 0.5, fallback: Color::RGB::Blue)
+  # # => device-cmyk(30.00% 0 80.00% 30.00% / 0.50, rgb(0.00% 0.00% 100.00% / 0.50))
+  #
+  # cmyk.css(alpha: 0.5, fallback: { color: Color::RGB::Blue })
+  # # => device-cmyk(30.00% 0 80.00% 30.00% / 0.50, rgb(0.00% 0.00% 100.00%))
+  #
+  # cmyk.css(alpha: 0.5, fallback: { color: Color::RGB::Blue, alpha: 0.3 })
+  # # => device-cmyk(30.00% 0 80.00% 30.00% / 0.50, rgb(0.00% 0.00% 100.00% / 0.30))
+  #
+  # cmyk.css(alpha: 0.5, fallback: { alpha: 0.3 })
+  # # => device-cmyk(30.00% 0 80.00% 30.00% / 0.50, rgb(49.00% 70.00% 14.00% / 0.30))
+  # ```
+  def css(alpha: nil, fallback: true)
+    if fallback.is_a?(Color)
+      device_cmyk(alpha, fallback, alpha)
+    elsif fallback.is_a?(Hash)
+      device_cmyk(alpha, fallback.fetch(:color) { to_rgb }, fallback[:alpha])
+    elsif fallback == true
+      device_cmyk(alpha, to_rgb, alpha)
+    else
+      device_cmyk(alpha, nil, nil)
+    end
   end
 
-  # Present the colour as an HSL HTML/CSS colour string (e.g., "hsl(180,
-  # 25%, 35%)"). Note that this will perform a #to_hsl operation using the
-  # default conversion formula.
-  def css_hsl
-    to_hsl.css_hsl
-  end
+  ##
+  # Coerces the other Color object into CMYK.
+  def coerce(other) = other.to_cmyk
+
+  ##
+  def to_cmyk(...) = self
 
-  # Present the colour as an HSLA (with alpha) HTML/CSS colour string (e.g.,
-  # "hsla(180, 25%, 35%, 1)"). Note that this will perform a #to_hsl
-  # operation using the default conversion formula.
-  def css_hsla
-    to_hsl.css_hsla
+  ##
+  # Converts CMYK to Color::Grayscale.
+  #
+  # There are multiple methods for grayscale conversion, but this implements a variant of
+  # the Adobe PDF conversion method with higher precision:
+  #
+  # ```
+  # g = 1.0 - min(1.0, 0.299 * c + 0.587 * m + 0.114 * y + k)
+  # ```
+  #
+  # The default Adobe conversion uses lower precision conversion constants (0.3, 0.59, and
+  # 0.11) instead of the more precise NTSC/YIQ values.
+  def to_grayscale(...)
+    gc = 0.299 * c
+    gm = 0.587 * m
+    gy = 0.114 * y
+    g = 1.0 - [1.0, gc + gm + gy + k].min
+    Color::Grayscale.from_fraction(g)
   end
 
-  # Converts the CMYK colour to RGB. Most colour experts strongly suggest
-  # that this is not a good idea (some even suggesting that it's a very bad
-  # idea). CMYK represents additive percentages of inks on white paper,
-  # whereas RGB represents mixed colour intensities on a black screen.
+  ##
+  # Converts CMYK to Color::YIQ via Color::RGB.
+  def to_yiq(...) = to_rgb(...).to_yiq(...)
+
+  ##
+  # Converts CMYK to Color::RGB.
+  #
+  # Most color experts strongly suggest that this is not a good idea (some suggesting that
+  # it's a very bad idea). CMYK represents additive percentages of inks on white paper,
+  # whereas RGB represents mixed color intensities on an unlit (black) screen.
   #
-  # However, the colour conversion can be done, and there are two different
-  # methods for the conversion that provide slightly different results.
-  # Adobe PDF conversions are done with the first form.
+  # The color conversion can be done and there are two different methods (standard and
+  # Adobe PDF) that provide slightly different results. Using CMYK [33% 66% 83% 25%], the
+  # standard method provides an approximate RGB color of (128, 65, 33) or #804121. The
+  # Adobe PDF method provides an approximate RGB color of (107, 23, 0) or #6b1700.
   #
-  #     # Adobe PDF Display Formula
+  # Which is correct? The colors may seem to be drastically different in the RGB color
+  # space, they differ mostly in intensity. The Adobe PDF conversion is a darker, slightly
+  # redder brown; the standard conversion is a lighter brown. Because of this subtlety,
+  # both methods are offered for conversion. The Adobe PDF method is not used by default;
+  # to use it, pass `rgb_method: :adobe` to #to_rgb.
+  #
+  #   # Adobe PDF CMYK -> RGB Conversion
   #   r = 1.0 - min(1.0, c + k)
   #   g = 1.0 - min(1.0, m + k)
   #   b = 1.0 - min(1.0, y + k)
   #
-  #     # Other
+  #   # Standard CMYK -> RGB Conversion
   #   r = 1.0 - (c * (1.0 - k) + k)
   #   g = 1.0 - (m * (1.0 - k) + k)
   #   b = 1.0 - (y * (1.0 - k) + k)
   #
-  # If we have a CMYK colour of [33% 66% 83% 25%], the first method will
-  # give an approximate RGB colour of (107, 23, 0) or #6b1700. The second
-  # method will give an approximate RGB colour of (128, 65, 33) or #804121.
-  # Which is correct? Although the colours may seem to be drastically
-  # different in the RGB colour space, they are very similar colours,
-  # differing mostly in intensity. The first is a darker, slightly redder
-  # brown; the second is a lighter brown.
-  #
-  # Because of this subtlety, both methods are now offered for conversion.
-  # The Adobe method is not used by default; to enable it, pass +true+ to
-  # #to_rgb.
-  #
-  # Future versions of Color may offer other conversion mechanisms that
-  # offer greater colour fidelity, including recognition of ICC colour
-  # profiles.
-  def to_rgb(use_adobe_method = false)
-    if use_adobe_method
-      Color::RGB.from_fraction(*adobe_cmyk_rgb)
-    else
-      Color::RGB.from_fraction(*standard_cmyk_rgb)
-    end
-  end
+  # :call-seq:
+  #   to_rgb(rgb_method: :standard)
+  def to_rgb(*args, **kwargs)
+    values =
+      if kwargs[:rgb_method] == :adobe || args.first == :adobe
+        adobe_cmyk_rgb
+      else
+        standard_cmyk_rgb
+      end
 
-  # Converts the CMYK colour to a single greyscale value. There are
-  # undoubtedly multiple methods for this conversion, but only a minor
-  # variant of the Adobe conversion method will be used:
-  #
-  #   g = 1.0 - min(1.0, 0.299 * c + 0.587 * m + 0.114 * y + k)
-  #
-  # This treats the CMY values similarly to YIQ (NTSC) values and then adds
-  # the level of black. This is a variant of the Adobe version because it
-  # uses the more precise YIQ (NTSC) conversion values for Y (intensity)
-  # rather than the approximates provided by Adobe (0.3, 0.59, and 0.11).
-  def to_grayscale
-    c = 0.299 * @c.to_f
-    m = 0.587 * @m.to_f
-    y = 0.114 * @y.to_f
-    g = 1.0 - [1.0, c + m + y + @k].min
-    Color::GrayScale.from_fraction(g)
+    Color::RGB.from_fraction(*values)
   end
-  alias to_greyscale to_grayscale
 
-  def to_cmyk
-    self
-  end
+  ##
+  # Converts CMYK to Color::HSL via Color::RGB.
+  def to_hsl(...) = to_rgb(...).to_hsl(...)
 
-  def inspect
-    "CMYK [%.2f%%, %.2f%%, %.2f%%, %.2f%%]" % [ cyan, magenta, yellow, black ]
-  end
+  ##
+  # Converts CMYK to Color::CIELAB via Color::RGB.
+  def to_lab(...) = to_rgb(...).to_lab(...)
 
-  # Converts to RGB then YIQ.
-  def to_yiq
-    to_rgb.to_yiq
-  end
+  ##
+  # Converts CMYK to Color::XYZ via Color::RGB.
+  def to_xyz(...) = to_rgb(...).to_xyz(...)
 
-  # Converts to RGB then HSL.
-  def to_hsl
-    to_rgb.to_hsl
-  end
+  ##
+  def inspect = "CMYK [%.2f%% %.2f%% %.2f%% %.2f%%]" % [cyan, magenta, yellow, key] # :nodoc:
 
-  # Returns the cyan (C) component of the CMYK colour as a percentage value.
-  def cyan
-    @c * 100.0
-  end
-  # Returns the cyan (C) component of the CMYK colour as a value in the
-  # range 0.0 .. 1.0.
-  def c
-    @c
-  end
-  # Sets the cyan (C) component of the CMYK colour as a percentage value.
-  def cyan=(cc)
-    @c = Color.normalize(cc / 100.0)
-  end
-  # Sets the cyan (C) component of the CMYK colour as a value in the range
-  # 0.0 .. 1.0.
-  def c=(cc)
-    @c = Color.normalize(cc)
+  ##
+  def pretty_print(q) # :nodoc:
+    q.text "CMYK"
+    q.breakable
+    q.group 2, "[", "]" do
+      q.text ".2f%%" % cyan
+      q.fill_breakable
+      q.text ".2f%%" % magenta
+      q.fill_breakable
+      q.text ".2f%%" % yellow
+      q.fill_breakable
+      q.text ".2f%%" % key
+      q.fill_breakable
+    end
   end
 
-  # Returns the magenta (M) component of the CMYK colour as a percentage
-  # value.
-  def magenta
-    @m * 100.0
-  end
-  # Returns the magenta (M) component of the CMYK colour as a value in the
-  # range 0.0 .. 1.0.
-  def m
-    @m
-  end
-  # Sets the magenta (M) component of the CMYK colour as a percentage value.
-  def magenta=(mm)
-    @m = Color.normalize(mm / 100.0)
-  end
-  # Sets the magenta (M) component of the CMYK colour as a value in the
-  # range 0.0 .. 1.0.
-  def m=(mm)
-    @m = Color.normalize(mm)
-  end
+  ##
+  def cyan = c * 100.0 # :nodoc:
 
-  # Returns the yellow (Y) component of the CMYK colour as a percentage
-  # value.
-  def yellow
-    @y * 100.0
-  end
-  # Returns the yellow (Y) component of the CMYK colour as a value in the
-  # range 0.0 .. 1.0.
-  def y
-    @y
-  end
-  # Sets the yellow (Y) component of the CMYK colour as a percentage value.
-  def yellow=(yy)
-    @y = Color.normalize(yy / 100.0)
-  end
-  # Sets the yellow (Y) component of the CMYK colour as a value in the range
-  # 0.0 .. 1.0.
-  def y=(kk)
-    @y = Color.normalize(kk)
-  end
+  ##
+  def magenta = m * 100.0 # :nodoc:
 
-  # Returns the black (K) component of the CMYK colour as a percentage
-  # value.
-  def black
-    @k * 100.0
-  end
-  # Returns the black (K) component of the CMYK colour as a value in the
-  # range 0.0 .. 1.0.
-  def k
-    @k
-  end
-  # Sets the black (K) component of the CMYK colour as a percentage value.
-  def black=(kk)
-    @k = Color.normalize(kk / 100.0)
-  end
-  # Sets the black (K) component of the CMYK colour as a value in the range
-  # 0.0 .. 1.0.
-  def k=(kk)
-    @k = Color.normalize(kk)
-  end
+  ##
+  def yellow = y * 100.0 # :nodoc:
 
-  def to_a
-    [ c, m, y, k ]
-  end
+  ##
+  alias_method :b, :k # :nodoc:
+
+  ##
+  def key = k * 100.0 # :nodoc:
+
+  ##
+  alias_method :black, :key # :nodoc:
+
+  ##
+  def to_a = [cyan, magenta, yellow, key] # :nodoc:
+
+  ##
+  alias_method :deconstruct, :to_a # :nodoc:
+
+  ##
+  def deconstruct_keys(_keys) = {c:, m:, y:, k:, cyan:, magenta:, yellow:, key:} # :nodoc:
+
+  ##
+  def to_internal = [c, m, y, k] # :nodoc:
+
+  ##
+  def components = 4 # :nodoc:
 
   private
+
+  ##
   # Implements the Adobe PDF conversion of CMYK to RGB.
-  def adobe_cmyk_rgb
-    [ @c, @m, @y ].map { |v| 1.0 - [ 1.0, v + @k ].min }
-  end
+  def adobe_cmyk_rgb = [c, m, y].map { 1.0 - [1.0, _1 + k].min } # :nodoc:
 
+  ##
   # Implements the standard conversion of CMYK to RGB.
-  def standard_cmyk_rgb
-    [ @c, @m, @y ].map { |v| 1.0 - (v * (1.0 - k) + k) }
+  def standard_cmyk_rgb = [c, m, y].map { 1.0 - (_1 * (1.0 - k) + k) } # :nodoc:
+
+  ##
+  def device_cmyk(alpha, fallback, fallback_alpha) # :nodoc:
+    params = [
+      css_value(cyan, :percent),
+      css_value(magenta, :percent),
+      css_value(yellow, :percent),
+      css_value(key, :percent)
+    ].join(" ")
+    params = "#{params} / #{css_value(alpha)}" if alpha
+    fallback = fallback&.css(alpha: fallback_alpha)
+
+    if fallback
+      "device-cmyk(#{params}, #{fallback})"
+    else
+      "device-cmyk(#{params})"
+    end
   end
 end