colorist 0.0.1

data/MIT_LICENSE.rdoc

@@ -0,0 +1,19 @@
+Copyright (c) 2008 Michael Bleigh and Intridea, Inc.
+
+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 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.rdoc

@@ -0,0 +1,27 @@
+= Colorist
+
+Colorist is a library built to handle the conversion, comparison, and 
+manipulation of colors in Ruby projects with an emphasis on W3C standards 
+and CSS-style hex notation. See the Color class for additional details
+on the available methods.
+
+== Example
+
+  require 'colorist'
+  include Colorist
+  
+  gray = Color.new(0x333333)
+  gray + gray     # => #<Color #666666>
+  gray - "#333"   # => #<Color #000000>
+  
+  gray.invert     # => #<Color #cccccc>
+  gray.brightness # => 0.2
+
+  gray.contrast_with("#f00")
+  
+== Resources
+
+* GitHub Source: http://github.com/mbleigh/colorist
+* Lighthouse (for bugs): http://mbleigh.lighthouseapp.com/projects/15686-colorist
+
+Copyright (c) 2008 Michael Bleigh and Intridea, Inc. Released under the MIT open source license.

data/lib/colorist.rb

@@ -0,0 +1,2 @@
+require 'colorist/color'
+require 'colorist/core_extensions'

data/lib/colorist/color.rb

@@ -0,0 +1,232 @@
+module Colorist
+  # Color is the general class for storing and manipulating a color with the
+  # Colorist gem. It provides methods to add, subtract, and calculate aspects
+  # of the color based on W3C and other standards.
+  class Color            
+    attr_accessor :r, :g, :b
+  
+    CSS_COLOR_NAMES = {  "maroon"  => 0x800000,
+                         "red"     => 0xff0000,
+                         "orange"  => 0xffa500,
+                         "yellow"  => 0xffff00,
+                         "olive"   => 0x808000,
+                         "purple"  => 0x800080,
+                         "fuchsia" => 0xff00ff,
+                         "white"   => 0xffffff,
+                         "lime"    => 0x00ff00,
+                         "green"   => 0x008000,
+                         "navy"    => 0x000080,
+                         "blue"    => 0x0000ff,
+                         "aqua"    => 0x00ffff,
+                         "teal"    => 0x008080,
+                         "black"   => 0x000000,
+                         "silver"  => 0xc0c0c0,
+                         "gray"    => 0x808080  }
+  
+    # Creates a new color with the hex color provided as a number (i.e. 0x112233)
+    def initialize(color=0x000000)
+      string = "%.6x" % color
+      @r = string[0..1].hex
+      @g = string[2..3].hex
+      @b = string[4..5].hex
+    end
+    
+    # Initialize a color based on RGB values. By default, the values
+    # should be between 0 and 255. If you use the option <tt>:percent => true</tt>,
+    # the values should then be between 0.0 and 1.0.
+    def self.from_rgb(r,g,b,options={})
+      color = Colorist::Color.new
+      # convert from 0.0 to 1.0 to 0 to 255 if the :percent option is used
+      if options[:percent]
+        color.r, color.g, color.b = r * 255, g * 255, b * 255
+      end
+      color.r, color.g, color.b = r, g, b
+      color
+    end
+    
+    # Converts a CSS hex string into a color. Works both with the
+    # full form (i.e. <tt>#ffffff</tt>) and the abbreviated form (<tt>#fff</tt>). Can
+    # also take any of the 16 named CSS colors.
+    def self.from_string(some_string)
+      if matched = some_string.match(/\A#([0-9a-f]{3})\z/i)
+        color = Colorist::Color.from_rgb(*matched[1].split(//).collect{|v| "#{v}#{v}".hex })
+      elsif matched = some_string.match(/\A#([0-9a-f]{6})\z/)
+        color = Colorist::Color.new
+        color.r = matched[1][0..1].hex
+        color.g = matched[1][2..3].hex
+        color.b = matched[1][4..5].hex
+      elsif CSS_COLOR_NAMES.key?(some_string)
+        color = Colorist::Color.new(CSS_COLOR_NAMES[some_string])
+      else
+        raise ArgumentError, "Must provide a valid CSS hex color or color name.", caller
+      end
+      color
+    end
+    
+    # Create a new color from the provided object. Duplicates Color objects
+    # and attempts to call <tt>to_color</tt> on other objects. Will raise
+    # an ArgumentError if it is unable to coerce the color.
+    def self.from(some_entity)
+      case some_entity
+        when Colorist::Color
+          some_entity.dup
+        else
+          raise ArgumentError, "#{some_entity.class.to_s} cannot be coerced into a color.", caller unless some_entity.respond_to?(:to_color)
+          some_entity.to_color
+      end
+    end
+  
+    # Create a duplicate of this color.
+    def dup
+      Colorist::Color.from_rgb(@r,@g,@b)
+    end
+  
+    # Add the individual RGB values of two colors together. You
+    # may also use an equivalent numeric or string color representation.
+    #
+    # Examples:
+    #
+    #   gray = Colorist::Color.new(0x333333)
+    #   gray + "#300"   # => <Color #663333>
+    #   gray + 0x000000 # => <Color #333333>
+    #   white = "white".to_color
+    #   gray + white    # => <Color #ffffff>
+    def +(other_color)
+      other_color = Colorist::Color.from(other_color)
+      color = self.dup
+      color.r += other_color.r
+      color.g += other_color.g
+      color.b += other_color.b
+      color
+    end
+  
+    # Subtract the individual RGB values of the two colors together.
+    # You may also use an equivalent numeric or string color representation.
+    def -(other_color)
+      other_color = Colorist::Color.from(other_color)
+      color = self.dup
+      color.r -= other_color.r
+      color.g -= other_color.g
+      color.b -= other_color.b
+      color
+    end
+    
+    # Compares colors based on brightness.
+    def <=>(other_color)
+      other_color = Colorist::Color.from(other_color)
+      brightness <=> other_color.brightness
+    end
+    
+    # Compares colors based on brightness.
+    def < (other_color)
+      other_color = Colorist::Color.from(other_color)
+      brightness < other_color.brightness
+    end
+    
+    # Compares colors based on brightness.
+    def > (other_color)
+      other_color = Colorist::Color.from(other_color)
+      brightness > other_color.brightness
+    end
+    
+    # Equal if the red, green, and blue values are identical.
+    def ==(other_color)
+      other_color = Colorist::Color.from(other_color)
+      other_color.r == self.r && other_color.g == self.g && other_color.b == self.b
+    end
+    
+    # Equal if the brightnesses of the two colors are identical.
+    def ===(other_color)
+      other_color = Colorist::Color.from(other_color)
+      other_color.brightness == brightness
+    end
+    
+    def r=(value) #:nodoc:
+      @r = value; normalize; end 
+    def g=(value) #:nodoc:
+      @g = value; normalize; end
+    def b=(value) #:nodoc:
+      @b = value; normalize; end
+  
+    # Outputs a string representation of the color in the desired format.
+    # The available formats are:
+    #
+    # * <tt>:css</tt> - As a CSS hex string (i.e. <tt>#ffffff</tt>) (default)
+    # * <tt>:css_rgb</tt> - As a CSS RGB value string (i.e. <tt>rgb(255,255,255)</tt>)
+    # * <tt>:rgb</tt> - As an RGB triplet (i.e. <tt>1.0, 1.0, 1.0</tt>)
+    def to_s(format=:css)
+      case format
+        when :css
+          "#%.2x%.2x%.2x" % [r, g, b]
+        when :css_rgb
+          "rgb(%.2f,%.2f,%.2f)" % [r, g, b]
+        when :rgb
+          "%.3f, %.3f, %.3f" % [r / 255, g / 255, b / 255]
+      end
+    end
+  
+    def inspect
+      "#<Color #{to_s(:css)}>"
+    end
+  
+    # Returns the perceived brightness of the provided color on a
+    # scale of 0.0 to 1.0 based on the formula provided. The formulas
+    # available are:
+    #
+    # * <tt>:w3c</tt> - <tt>((r * 299 + g * 587 + b * 114) / 1000 / 255</tt>    
+    # * <tt>:standard</tt> - <tt>sqrt(0.241 * r^2 + 0.691 * g^2 + 0.068 * b^2) / 255</tt>
+    def brightness(formula=:w3c)
+      case formula
+        when :standard
+          Math.sqrt(0.241 * r**2 + 0.691 * g**2 + 0.068 * b**2) / 255
+        when :w3c
+          ((r * 299 + g * 587 + b * 114) / 255000.0)
+      end
+    end
+    
+    # Contrast this color with another color using the provided formula. The
+    # available formulas are:
+    #
+    # * <tt>:w3c</tt> - <tt>(max(r1 r2) - min(r1 r2)) + (max(g1 g2) - min(g1 g2)) + (max(b1 b2) - min(b1 b2))</tt>
+    def contrast_with(other_color, formula=:w3c)
+      other_color = Color.from(other_color)
+      case formula
+        when :w3c
+          (([self.r, other_color.r].max - [self.r, other_color.r].min) +
+          ([self.g, other_color.g].max - [self.g, other_color.g].min) +
+          ([self.b, other_color.b].max - [self.b, other_color.b].min)) / 765.0
+      end
+    end
+    
+    # Returns the opposite of the current color.
+    def invert
+      Color.from_rgb(255 - r, 255 - g, 255 - b)
+    end
+    
+    # Converts the current color to grayscale using the brightness
+    # formula provided. See #brightness for a description of the 
+    # available formulas.
+    def to_grayscale(formula=:w3c)
+      b = brightness(formula)
+      Color.from_rgb(255 * b, 255 * b, 255 * b)
+    end
+  
+    # Returns an appropriate text color (either black or white) based on
+    # the brightness of this color. The +threshold+ specifies the brightness
+    # cutoff point.
+    def text_color(threshold=0.6, formula=:standard)
+      brightness(formula) > threshold ? Colorist::Color.new(0x000000) : Colorist::Color.new(0xffffff)
+    end
+  
+    protected
+  
+    def normalize #:nodoc:
+      @r = 255 if @r > 255
+      @g = 255 if @g > 255
+      @b = 255 if @b > 255
+      @r = 0 if @r < 0
+      @g = 0 if @g < 0
+      @b = 0 if @b < 0
+    end
+  end
+end

data/lib/colorist/core_extensions.rb

@@ -0,0 +1,26 @@
+class Integer
+  # Converts a hexadecimal number into a Color. Must be
+  # the equivalent of the full hexadecimal form (for example,
+  # <tt>0x123456</tt>).
+  def to_color
+    Colorist::Color.new(self)
+  end
+end
+
+class Float
+  # Converts a number from 0.0 to 1.0 to the grayscale equivalent
+  # of that brightness value. Especially useful for adding percentages
+  # to a color.
+  def to_color
+    Colorist::Color.from_rgb(self * 255, self * 255, self * 255)
+  end
+end
+
+class String
+  # Converts a CSS-style color string to a Color. Can be
+  # in the full form (<tt>\#112233</tt>), the abbreviated form
+  # (<tt>\#123</tt>) or a CSS named color (<tt>"black"</tt> or <tt>"maroon"</tt>).
+  def to_color
+    Colorist::Color.from_string(self)
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: colorist
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Michael Bleigh
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-08-16 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: Colorist is a library built to handle the easy conversion and manipulation of colors with a special emphasis on W3C standards and CSS-style hex color notation.
+email: michael@intridea.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- MIT_LICENSE.rdoc
+- README.rdoc
+files: 
+- MIT_LICENSE.rdoc
+- README.rdoc
+- lib/colorist.rb
+- lib/colorist/color.rb
+- lib/colorist/core_extensions.rb
+has_rdoc: true
+homepage: http://github.com/mbleigh/colorist
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A library built to handle the easy conversion and manipulation of colors.
+test_files: []
+