spectrum 0.0.1

data/History.txt

@@ -0,0 +1,93 @@
+== Color 1.4.1 / 2010.02.03
+* Imported to github.
+* Converted to Hoe 2.5 spec format.
+
+== Color 1.4.0 / 2007.02.11
+* Merged Austin Ziegler's color-tools library (previously part of the Ruby
+  PDF Tools project) with Matt Lyon's color library.
+  - The HSL implementation from the Color class has been merged into
+    Color::HSL. Color is a module the way it was for color-tools.
+  - A thin veneer has been written to allow Color::new to return a Color::HSL
+    instance; Color::HSL supports as many methods as possible that were
+    previously supported by the Color class.
+  - Values that were previously rounded by Color are no longer rounded;
+    fractional values matter.
+* Converted to hoe for project management.
+* Moved to the next step of deprecating Color::Name values; printing a
+  warning for each use (see the history for color-tools 1.3.0).
+* Print a warning on the access of either VERSION or COLOR_TOOLS_VERSION; the
+  version constant is now COLOR_VERSION.
+* Added humanized versions of accessors (e.g., CMYK colours now have both #cyan
+  and #c to access the cyan component of the colour; #cyan provides the value
+  as a percentage).
+* Added CSS3 formatters for RGB, RGBA, HSL, and HSLA outputs. Note that the
+  Color library does not yet have a way of setting alpha opacity, so the
+  output for RGBA and HSLA are at full alpha opacity (1.0). The values are
+  output with two decimal places.
+* Applied a patch to provide simple arithmetic colour addition and subtraction
+  to Color::GrayScale and Color::RGB. The patch was contributed by Jeremy
+  Hinegardner <jeremy@hinegardner.org>. This patch also provides the ability to
+  return the maximum RGB value as a grayscale colour.
+* Fixed two problems reported by Jean Krohn <jb.krohn@free.fr> against
+  color-tools relating to RGB-to-HSL and HSL-to-RGB conversion. (Color and
+  color-tools use the same formulas, but the ordering of the calculations is
+  slightly different with Color and did not suffer from this problem;
+  color-tools was more sensitive to floating-point values and precision
+  errors.)
+* Fixed an issue with HSL/RGB conversions reported by Adam Johnson
+  <adam.sven.johnson@gmail.com>.
+* Added an Adobe Color swatch (Photoshop) palette reader,
+  Color::Palette::AdobeColor (for .aco files only).
+
+== Color 0.1.0 / 2006.08.05
+* Added HSL (degree, percent, percent) interface.
+* Removed RGB instance variable; color is managed internally as HSL floating
+  point.
+* Tests!
+
+== color-tools 1.3.0
+* Added new metallic colours suggested by Jim Freeze <jfn@freeze.org>. These
+  are in the namespace Color::Metallic.
+* Colours that were defined in the Color namespace (e.g., Color::Red,
+  Color::AliceBlue) are now defined in Color::RGB (e.g., Color::RGB::Red,
+  Color::RGB::AliceBlue). They are added back to the Color namespace on the
+  first use of the old colours and a warning is printed. In version 1.4, this
+  warning will be printed on every use of the old colours. In version 1.5,
+  the backwards compatible support for colours like Color::Red will be
+  removed completely.
+* Added the Color::CSS module, color/css or Color::CSS that provides a name
+  lookup of Color::RGB-namespaced constants with Color::CSS[name]. Most of
+  these colours (which are mirrored from the Color::RGB default colours) are
+  only "officially" recognised under the CSS3 colour module or SVG.
+* Added the Color::HSL colour space and some helper utilities to Color::RGB
+  for colour manipulation using the HSL value.
+* Controlled internal value replacement to be between 0 and 1 for all
+  colours.
+* Updated Color::Palette::Gimp to more meaningfully deal with duplicate named
+  colours. Named colours now return an array of colours.
+* Indicated the plans for some methods and constants out to color-tools 2.0.
+* Added unit tests and fixed a number of hidden bugs because of them.
+
+== color-tools 1.2.0
+* Changed installer from a custom-written install.rb to setup.rb
+  3.3.1-modified.
+* Added Color::GreyScale (or Color::GrayScale).
+* Added Color::YIQ. This colour definition is incomplete; it does not have
+  conversions from YIQ to other colour spaces.
+
+== color-tools 1.1.0
+* Added color/palette/gimp to support the reading and use of GIMP color
+  palettes.
+
+== color-tools 1.0.0
+* Initial release.
+
+== Copyright
+  Color
+  Colour Management with Ruby
+  http://rubyforge.org/projects/color
+
+  Licensed under a MIT-style licence. See Licence.txt in the main
+  distribution for full licensing information.
+
+  Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon

data/Install.txt

@@ -0,0 +1,18 @@
+== Installing Color
+
+Color may be installed with:
+
+  % ruby setup.rb
+
+Alternatively, the RubyGems version of Color may be installed from the usual
+sources.
+
+== Copyright
+  Color
+  Colour Management with Ruby
+  http://rubyforge.org/projects/color
+
+  Licensed under a MIT-style licence. See Licence.txt in the main
+  distribution for full licensing information.
+
+  Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon

data/Licence.txt

@@ -0,0 +1,27 @@
+Color
+Colour management in Ruby
+http://rubyforge.org/projects/color/
+
+Copyright (c) 2005 - 2010 Austin Ziegler, Matt Lyon, and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+* The names of its contributors may not be used to endorse or promote
+  products derived from this software without specific prior written
+  permission.
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.txt

@@ -0,0 +1,35 @@
+= Spectrun
+
+Spectrum is a fork of the Color library.
+
+Color is a Ruby library to provide basic RGB, CMYK, HSL, and other colourspace
+manipulation support to applications that require it. It also provides 152
+named RGB colours (184 with spelling variations) that are commonly supported
+in HTML, SVG, and X11 applications. A technique for generating monochromatic
+contrasting palettes is also included.
+
+The capabilities of the Color library are limited to pure mathematical
+manipulation of the colours based on colour theory without reference to colour
+profiles (such as sRGB or Adobe RGB). For most purposes, when working with the
+RGB and HSL colours, this won't matter. However, some colour models (like CIE
+L*a*b*) are not supported because Color does not yet support colour profiles,
+giving no meaningful way to convert colours in absolute colour spaces (like
+L*a*b*, XYZ) to non-absolute colour spaces (like RGB).
+
+Color version 1.4 is the result of a project merge between color.rb 0.1.0 by
+Matt Lyon and color-tools 1.3 by Austin Ziegler. Please see History.txt for
+details on the changes this merge brings. Color version 1.4.1 changes
+development to GitHub and fixes some small problems.
+
+Copyright:: Copyright (c) 2005 - 2010 by Austin Ziegler and Matt Lyon
+Version::   1.4.1
+Homepage::  http://rubyforge.org/projects/color/
+Licence::   MIT-Style; see Licence.txt
+
+Color::Palette was developed based on techniques described by Andy "Malarkey"
+Clarke[1], implemented in JavaScript by Steve G. Chipman at SlayerOffice[2] and
+by Patrick Fitzgerald of BarelyFitz[3] in PHP.
+
+[1] http://www.stuffandnonsense.co.uk/archives/creating_colour_palettes.html 
+[2] http://slayeroffice.com/tools/color_palette/
+[3] http://www.barelyfitz.com/projects/csscolor/

data/lib/spectrum.rb

@@ -0,0 +1,145 @@
+# :title: Color -- Colour Management with Ruby
+# :main: README.txt
+
+#--
+# Color
+# Colour management with Ruby
+# http://rubyforge.org/projects/color
+#   Version 1.4.1
+#
+# Licensed under a MIT-style licence. See Licence.txt in the main
+# distribution for full licensing information.
+#
+# Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon
+#++
+
+# = Colour Management with Ruby
+module Spectrum
+  COLOR_VERSION = '1.4.1'
+
+  class RGB; end
+  class CMYK; 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
+
+  class << self
+    # Returns +true+ if the value is less than COLOR_EPSILON.
+    def near_zero?(value)
+      (value.abs <= COLOR_EPSILON)
+    end
+
+    # 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))
+    end
+
+    # Returns +true+ if the value is within COLOR_EPSILON of one.
+    def near_one?(value)
+      near_zero?(value - 1.0)
+    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
+
+    # 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
+      else
+        value
+      end
+    end
+    alias normalize_fractional normalize
+
+    def normalize_to_range(value, range)
+      range = (range.end..range.begin) if (range.end < range.begin)
+
+      if value <= range.begin
+        range.begin
+      elsif value >= range.end
+        range.end
+      else
+        value
+      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
+    
+    # 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
+  end
+end
+
+require 'spectrum/rgb'
+require 'spectrum/cmyk'
+require 'spectrum/grayscale'
+require 'spectrum/hsl'
+require 'spectrum/yiq'
+require 'spectrum/rgb/metallic'
+
+module Color
+  def self.const_missing(name) #:nodoc:
+    case name
+    when "VERSION", :VERSION, "COLOR_TOOLS_VERSION", :COLOR_TOOLS_VERSION
+      warn "Spectrum::#{name} has been deprecated. Use Spectrum::COLOR_VERSION instead."
+      Spectrum::COLOR_VERSION
+    else
+      if Spectrum::RGB.const_defined?(name)
+        warn "Spectrum::#{name} has been deprecated. Use Spectrum::RGB::#{name} instead."
+        Spectrum::RGB.const_get(name)
+      else
+        super
+      end
+    end
+  end
+
+  # 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.1 (a module). This
+  # "constructor" will be removed in the future.
+  #
+  # mode = :hsl::   +values+ must be an array of [ hue deg, sat %, lum % ].
+  #                 A Spectrum::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
+  #                 Spectrum::RGB object will be created.
+  # mode = :cmyk::  +values+ must be an array of [ cyan %, magenta %, yellow
+  #                 %, black % ]. A Spectrum::CMYK object will be created.
+  def self.new(values, mode = :rgb)
+    warn "Color.new has been deprecated. Use Spectrum::#{mode.to_s.upcase}.new instead."
+    color = case mode
+            when :hsl
+              Spectrum::HSL.new(*values)
+            when :rgb
+              values = [ values ].flatten
+              if values.size == 1
+                Spectrum::RGB.from_html(*values)
+              else
+                Spectrum::RGB.new(*values)
+              end
+            when :cmyk
+              Spectrum::CMYK.new(*values)
+            end
+    color.to_hsl
+  end
+end

data/lib/spectrum/cmyk.rb

@@ -0,0 +1,281 @@
+#--
+# Spectrum
+#
+# Based on Color
+# Colour management with Ruby
+# http://rubyforge.org/projects/color
+#   Version 1.4.1
+#
+# Licensed under a MIT-style licence. See Licence.txt in the main
+# distribution for full licensing information.
+#
+# Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon
+#++
+
+# 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.
+class Spectrum::CMYK
+  # 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"
+
+  # Compares the other colour to this one. The other colour will be
+  # converted to CMYK before comparison, so the comparison between a CMYK
+  # colour and a non-CMYK colour will be approximate and based on the other
+  # colour's #to_cmyk conversion. If there is no #to_cmyk conversion, this
+  # will raise an exception. This will report that two CMYK colours are
+  # equivalent if all component values are within COLOR_TOLERANCE of each
+  # other.
+  def ==(other)
+    other = other.to_cmyk
+    other.kind_of?(Spectrum::CMYK) and
+    ((@c - other.c).abs <= Spectrum::COLOR_TOLERANCE) and
+    ((@m - other.m).abs <= Spectrum::COLOR_TOLERANCE) and
+    ((@y - other.y).abs <= Spectrum::COLOR_TOLERANCE) and
+    ((@k - other.k).abs <= Spectrum::COLOR_TOLERANCE)
+  end
+
+  # Creates a CMYK colour object from fractional values 0..1.
+  #
+  #   Spectrum::CMYK.from_fraction(0.3, 0, 0.8, 0.3)
+  def self.from_fraction(c = 0, m = 0, y = 0, k = 0)
+    colour = Spectrum::CMYK.new
+    colour.c = c
+    colour.m = m
+    colour.y = y
+    colour.k = k
+    colour
+  end
+
+  # Creates a CMYK colour object from percentages. Internally, the colour is
+  # managed as fractional values 0..1.
+  #
+  #   Spectrum::CMYK.new(30, 0, 80, 30)
+  def self.from_percent(c = 0, m = 0, y = 0, k = 0)
+    Spectrum::CMYK.new(c, m, y, k)
+  end
+
+  # Creates a CMYK colour object from percentages. Internally, the colour is
+  # managed as fractional values 0..1.
+  #
+  #   Spectrum::CMYK.new(30, 0, 80, 30)
+  def initialize(c = 0, m = 0, y = 0, k = 0)
+    @c = c / 100.0
+    @m = m / 100.0
+    @y = y / 100.0
+    @k = k / 100.0
+  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" ]
+  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
+
+  # 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
+  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%)"). Note that this will perform a #to_hsl operation using the
+  # default conversion formula.
+  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 using the default conversion formula.
+  def css_hsla
+    to_hsl.css_hsla
+  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.
+  #
+  # 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.
+  #
+  #     # Adobe PDF Display Formula
+  #   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
+  #   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 Spectrum 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
+      r = 1.0 - [1.0, @c + @k].min
+      g = 1.0 - [1.0, @m + @k].min
+      b = 1.0 - [1.0, @y + @k].min
+    else
+      r = 1.0 - (@c.to_f * (1.0 - @k.to_f) + @k.to_f)
+      g = 1.0 - (@m.to_f * (1.0 - @k.to_f) + @k.to_f)
+      b = 1.0 - (@y.to_f * (1.0 - @k.to_f) + @k.to_f)
+    end
+    Spectrum::RGB.from_fraction(r, g, b)
+  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
+    Spectrum::GrayScale.from_fraction(g)
+  end
+  alias to_greyscale to_grayscale
+
+  def to_cmyk
+    self
+  end
+
+  def inspect
+    "CMYK [%.2f%%, %.2f%%, %.2f%%, %.2f%%]" % [ cyan, magenta, yellow, black ]
+  end
+
+  # Converts to RGB then YIQ.
+  def to_yiq
+    to_rgb.to_yiq
+  end
+
+  # Converts to RGB then HSL.
+  def to_hsl
+    to_rgb.to_hsl
+  end
+
+  # 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 = Spectrum.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 = Spectrum.normalize(cc)
+  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 = Spectrum.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 = Spectrum.normalize(mm)
+  end
+
+  # 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 = Spectrum.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 = Spectrum.normalize(kk)
+  end
+
+  # 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 = Spectrum.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 = Spectrum.normalize(kk)
+  end
+end