color_lib 1.4.4

data/lib/color_lib/css.rb

@@ -0,0 +1,15 @@
+require 'color_lib'
+# This namespace contains some CSS colour names.
+module ColorLib::CSS
+  # Returns the RGB colour for name or +nil+ if the name is not valid.
+  def self.[](name)
+    @colors[name.to_s.downcase.to_sym]
+  end
+
+  @colors = {}
+  ColorLib::RGB.constants.each do |const|
+    next if const == "PDF_FORMAT_STR"
+    next if const == "Metallic"
+    @colors[const.downcase.to_sym] ||= ColorLib::RGB.const_get(const)
+  end
+end

data/lib/color_lib/grayscale.rb

@@ -0,0 +1,205 @@
+# A colour object representing shades of grey. Used primarily in PDF
+# document creation.
+class ColorLib::GrayScale
+  # The format of a DeviceGrey 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 %s"
+
+  # Creates a greyscale colour object from fractional values 0..1.
+  #
+  #   ColorLib::GreyScale.from_fraction(0.5)
+  def self.from_fraction(g = 0)
+    color   = ColorLib::GrayScale.new
+    color.g = g
+    color
+  end
+
+  # Creates a greyscale colour object from percentages 0..100.
+  #
+  #   ColorLib::GrayScale.from_percent(50)
+  def self.from_percent(g = 0)
+    ColorLib::GrayScale.new(g)
+  end
+
+  # Creates a greyscale colour object from percentages 0..100.
+  #
+  #   ColorLib::GrayScale.new(50)
+  def initialize(g = 0)
+    @g = g / 100.0
+  end
+
+  # Compares the other colour to this one. The other colour will be
+  # converted to GreyScale before comparison, so the comparison between a
+  # GreyScale colour and a non-GreyScale colour will be approximate and
+  # based on the other colour's #to_greyscale conversion. If there is no
+  # #to_greyscale conversion, this will raise an exception. This will report
+  # that two GreyScale values are equivalent if they are within
+  # COLOR_TOLERANCE of each other.
+  def ==(other)
+    other = other.to_grayscale
+    other.kind_of?(ColorLib::GrayScale) and
+      ((@g - other.g).abs <= ColorLib::COLOR_TOLERANCE)
+  end
+
+  # Present the colour as a DeviceGrey fill colour string for PDF. This will
+  # be removed from the default package in color-tools 2.0.
+  def pdf_fill
+    PDF_FORMAT_STR % [@g, "g"]
+  end
+
+  # Present the colour as a DeviceGrey stroke colour string for PDF. This
+  # will be removed from the default package in color-tools 2.0.
+  def pdf_stroke
+    PDF_FORMAT_STR % [@g, "G"]
+  end
+
+  def to_255
+    [(@g * 255).round, 255].min
+  end
+
+  private :to_255
+
+  # Present the colour as an HTML/CSS colour string.
+  def html
+    gs = "%02x" % to_255
+    "##{gs * 3}"
+  end
+
+  # Present the colour as an RGB HTML/CSS colour string (e.g., "rgb(0%, 50%,
+  # 100%)").
+  def css_rgb
+    "rgb(%3.2f%%, %3.2f%%, %3.2f%%)" % [gray, gray, gray]
+  end
+
+  # Present the colour as an RGBA (with alpha) HTML/CSS colour string (e.g.,
+  # "rgb(0%, 50%, 100%, 1)").
+  def css_rgba
+    "rgba(%3.2f%%, %3.2f%%, %3.2f%%, %1.2f)" % [gray, gray, gray, 1]
+  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.
+  def css_hsl
+    to_hsl.css_hsl
+  end
+
+  # 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.
+  def css_hsla
+    to_hsl.css_hsla
+  end
+
+  # Convert the greyscale colour to CMYK.
+  def to_cmyk
+    k = 1.0 - @g.to_f
+    ColorLib::CMYK.from_fraction(0, 0, 0, k)
+  end
+
+  # Convert the greyscale colour to RGB.
+  def to_rgb(ignored = true)
+    ColorLib::RGB.from_fraction(g, g, g)
+  end
+
+  # Reflexive conversion.
+  def to_grayscale
+    self
+  end
+
+  alias to_greyscale to_grayscale
+
+  # Lightens the greyscale colour by the stated percent.
+  def lighten_by(percent)
+    g = [@g + (@g * (percent / 100.0)), 1.0].min
+    ColorLib::GrayScale.from_fraction(g)
+  end
+
+  # Darken the greyscale colour by the stated percent.
+  def darken_by(percent)
+    g = [@g - (@g * (percent / 100.0)), 0.0].max
+    ColorLib::GrayScale.from_fraction(g)
+  end
+
+  # Returns the YIQ (NTSC) colour encoding of the greyscale value. This is
+  # an approximation, as the values for I and Q are calculated by treating
+  # the greyscale value as an RGB value. The Y (intensity or brightness)
+  # value is the same as the greyscale value.
+  def to_yiq
+    y = @g
+    i = (@g * 0.596) + (@g * -0.275) + (@g * -0.321)
+    q = (@g * 0.212) + (@g * -0.523) + (@g * 0.311)
+    ColorLib::YIQ.from_fraction(y, i, q)
+  end
+
+  # Returns the HSL colour encoding of the greyscale value.
+  def to_hsl
+    ColorLib::HSL.from_fraction(0, 0, @g)
+  end
+
+  # Returns the brightness value for this greyscale value; this is the
+  # greyscale value itself.
+  def brightness
+    @g
+  end
+
+  # Returns the grayscale value as a percentage of white (100% gray is
+  # white).
+  def gray
+    @g * 100.0
+  end
+
+  alias grey gray
+  # Returns the grayscale value as a fractional value of white in the range
+  # 0.0 .. 1.0.
+  def g
+    @g
+  end
+
+  # Sets the grayscale value as a percentage of white.
+  def gray=(gg)
+    @g = ColorLib.normalize(gg / 100.0)
+  end
+
+  alias grey= gray=;
+  # Returns the grayscale value as a fractional value of white in the range
+  # 0.0 .. 1.0.
+  def g=(gg)
+    @g = ColorLib.normalize(gg)
+  end
+
+  # Adds another colour to the current colour. The other colour will be
+  # converted to grayscale before addition. This conversion depends upon a
+  # #to_grayscale method on the other colour.
+  #
+  # The addition is done using the grayscale accessor methods to ensure a
+  # valid colour in the result.
+  def +(other)
+    other = other.to_grayscale
+    ng    = self.dup
+    ng.g  += other.g
+    ng
+  end
+
+  # Subtracts another colour to the current colour. The other colour will be
+  # converted to grayscale before subtraction. This conversion depends upon
+  # a #to_grayscale method on the other colour.
+  #
+  # The subtraction is done using the grayscale accessor methods to ensure a
+  # valid colour in the result.
+  def -(other)
+    other = other.to_grayscale
+    ng    = self.dup
+    ng.g  -= other.g
+    ng
+  end
+
+  def inspect
+    "Gray [%.2f%%]" % [gray]
+  end
+end
+
+module ColorLib
+  # A synonym for ColorLib::GrayScale.
+  GreyScale = GrayScale
+end

data/lib/color_lib/hsl.rb

@@ -0,0 +1,221 @@
+# An HSL colour object. Internally, the hue (#h), saturation (#s), and
+# luminosity/lightness (#l) values are dealt with as fractional values in
+# the range 0..1.
+class ColorLib::HSL
+  class << self
+    # Creates an HSL colour object from fractional values 0..1.
+    def from_fraction(h = 0.0, s = 0.0, l = 0.0)
+      colour   = ColorLib::HSL.new
+      colour.h = h
+      colour.s = s
+      colour.l = l
+      colour
+    end
+  end
+
+  # Compares the other colour to this one. The other colour will be
+  # converted to HSL before comparison, so the comparison between a HSL
+  # colour and a non-HSL colour will be approximate and based on the other
+  # colour's #to_hsl conversion. If there is no #to_hsl conversion, this
+  # will raise an exception. This will report that two HSL values are
+  # equivalent if all component values are within ColorLib::COLOR_TOLERANCE of
+  # each other.
+  def ==(other)
+    other = other.to_hsl
+    other.kind_of?(ColorLib::HSL) and
+      ((@h - other.h).abs <= ColorLib::COLOR_TOLERANCE) and
+      ((@s - other.s).abs <= ColorLib::COLOR_TOLERANCE) and
+      ((@l - other.l).abs <= ColorLib::COLOR_TOLERANCE)
+  end
+
+  # Creates an HSL colour object from the standard values of degrees and
+  # percentages (e.g., 145 deg, 30%, 50%).
+  def initialize(h = 0, s = 0, l = 0)
+    @h = h / 360.0
+    @s = s / 100.0
+    @l = l / 100.0
+  end
+
+  # Present the colour as an HTML/CSS colour string.
+  def html
+    to_rgb.html
+  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
+  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
+  end
+
+  # Present the colour as an HSL HTML/CSS colour string (e.g., "hsl(180,
+  # 25%, 35%)").
+  def css_hsl
+    "hsl(%3.2f, %3.2f%%, %3.2f%%)" % [hue, saturation, luminosity]
+  end
+
+  # Present the colour as an HSLA (with alpha) HTML/CSS colour string (e.g.,
+  # "hsla(180, 25%, 35%, 1)").
+  def css_hsla
+    "hsla(%3.2f, %3.2f%%, %3.2f%%, %3.2f)" % [hue, saturation, luminosity, 1]
+  end
+
+  # Converting to HSL as adapted from Foley and Van-Dam from
+  # http://www.bobpowell.net/RGBHSB.htm.
+  #
+  # NOTE:
+  # * If the colour's luminosity is near zero, the colour is always black.
+  # * If the colour's luminosity is near one, the colour is always white.
+  # * If the colour's saturation is near zero, the colour is always a shade
+  #   of grey and is based only on the luminosity of the colour.
+  #
+  def to_rgb(ignored = nil)
+    return ColorLib::RGB.new if ColorLib.near_zero_or_less?(@l)
+    return ColorLib::RGB.new(0xff, 0xff, 0xff) if ColorLib.near_one_or_more?(@l)
+    return ColorLib::RGB.from_fraction(@l, @l, @l) if ColorLib.near_zero?(@s)
+
+    # Is the value less than 0.5?
+    if ColorLib.near_zero_or_less?(@l - 0.5)
+      tmp2 = @l * (1.0 + @s.to_f)
+    else
+      tmp2 = @l + @s - (@l * @s.to_f)
+    end
+    tmp1 = 2.0 * @l - tmp2
+
+    tmp3 = [@h + (1.0 / 3.0), @h, @h - (1.0 / 3.0)]
+
+    rgb = tmp3.map { |hue|
+      hue += 1.0 if ColorLib.near_zero_or_less?(hue)
+      hue -= 1.0 if ColorLib.near_one_or_more?(hue)
+
+      if ColorLib.near_zero_or_less?((6.0 * hue) - 1.0)
+        tmp1 + ((tmp2 - tmp1) * hue * 6.0)
+      elsif ColorLib.near_zero_or_less?((2.0 * hue) - 1.0)
+        tmp2
+      elsif ColorLib.near_zero_or_less?((3.0 * hue) - 2.0)
+        tmp1 + (tmp2 - tmp1) * ((2 / 3.0) - hue) * 6.0
+      else
+        tmp1
+      end
+    }
+
+    ColorLib::RGB.from_fraction(*rgb)
+  end
+
+  # Converts to RGB then YIQ.
+  def to_yiq
+    to_rgb.to_yiq
+  end
+
+  # Converts to RGB then CMYK.
+  def to_cmyk
+    to_rgb.to_cmyk
+  end
+
+  # Returns the luminosity (#l) of the colour.
+  def brightness
+    @l
+  end
+
+  def to_greyscale
+    ColorLib::GrayScale.from_fraction(@l)
+  end
+
+  alias to_grayscale to_greyscale
+
+  # Returns the hue of the colour in degrees.
+  def hue
+    @h * 360.0
+  end
+
+  # Returns the hue of the colour in the range 0.0 .. 1.0.
+  def h
+    @h
+  end
+
+  # Sets the hue of the colour in degrees. Colour is perceived as a wheel,
+  # so values should be set properly even with negative degree values.
+  def hue=(hh)
+    hh = hh / 360.0
+
+    hh += 1.0 if hh < 0.0
+    hh -= 1.0 if hh > 1.0
+
+    @h = ColorLib.normalize(hh)
+  end
+
+  # Sets the hue of the colour in the range 0.0 .. 1.0.
+  def h=(hh)
+    @h = ColorLib.normalize(hh)
+  end
+
+  # Returns the percentage of saturation of the colour.
+  def saturation
+    @s * 100.0
+  end
+
+  # Returns the saturation of the colour in the range 0.0 .. 1.0.
+  def s
+    @s
+  end
+
+  # Sets the percentage of saturation of the colour.
+  def saturation=(ss)
+    @s = ColorLib.normalize(ss / 100.0)
+  end
+
+  # Sets the saturation of the colour in the ragne 0.0 .. 1.0.
+  def s=(ss)
+    @s = ColorLib.normalize(ss)
+  end
+
+  # Returns the percentage of luminosity of the colour.
+  def luminosity
+    @l * 100.0
+  end
+
+  alias lightness luminosity
+  # Returns the luminosity of the colour in the range 0.0 .. 1.0.
+  def l
+    @l
+  end
+
+  # Sets the percentage of luminosity of the colour.
+  def luminosity=(ll)
+    @l = ColorLib.normalize(ll / 100.0)
+  end
+
+  alias lightness= luminosity=;
+  # Sets the luminosity of the colour in the ragne 0.0 .. 1.0.
+  def l=(ll)
+    @l = ColorLib.normalize(ll)
+  end
+
+  def to_hsl
+    self
+  end
+
+  def inspect
+    "HSL [%.2f deg, %.2f%%, %.2f%%]" % [hue, saturation, luminosity]
+  end
+
+  # Mix the mask colour (which will be converted to an HSL colour) with the
+  # current colour at the stated mix percentage as a decimal value.
+  #
+  # NOTE::  This differs from ColorLib::RGB#mix_with.
+  def mix_with(color, mix_percent = 0.5)
+    color = color.to_hsl
+    _h    = ((color.h - self.h) * mix_percent) + self.h
+    _s    = ((color.s - self.s) * mix_percent) + self.s
+    _l    = ((color.l - self.l) * mix_percent) + self.l
+
+    self.class.from_fraction(_h, _s, _l)
+  end
+end

data/lib/color_lib/palette.rb

@@ -0,0 +1,4 @@
+require 'color_lib'
+
+module ColorLib::Palette
+end