paleta 0.0.5 → 0.1.0

data/.gitignore

@@ -4,4 +4,7 @@ Gemfile.lock
 Guardfile
 *.gem
 .bundle
-tmp
+tmp
+.yardoc
+_yardoc
+doc/

data/Gemfile

@@ -4,3 +4,4 @@ gemspec
 
 gem 'rspec', '~>2.8.0'
 gem 'guard-rspec'
+gem 'rmagick'

data/lib/paleta/color.rb

@@ -1,11 +1,40 @@
 require 'paleta/core_ext/math'
 
 module Paleta
+  # Represents a color
   class Color
     include Math
     
     attr_reader :red, :green, :blue, :hue, :saturation, :lightness, :hex
     
+    # Initailize a {Color}
+    #
+    # @overload initialize()
+    #   Initialize a {Color} to black
+    #
+    # @overload initialize(color)
+    #   Initialize a {Color} from a {Color}
+    #   @param [Color] color a color to copy
+    #
+    # @overload initialize(model, value)
+    #   Initialize a {Color} with a hex value
+    #   @param [Symbol] model the color model, should be :hex in this case
+    #   @param [String] value a 6 character hexadecimal string
+    #
+    # @overload initialize(model, value, value, value)
+    #   Initialize a {Color} with HSL or RGB component values
+    #   @param [Symbol] model the color model, should be :hsl or :rgb
+    #   @param [Number] (red,hue) the red or hue component value, depending on the value of model
+    #   @param [Number] (green,saturation) the green or saturation component value
+    #   @param [Number] (blue,lightness) the blue or lightness component value
+    #
+    # @overload initialize(value, value, value)
+    #   Initialize a {Color} with RGB component values
+    #   @param [Number] red the red component value
+    #   @param [Number] green the green component value
+    #   @param [Number] blue the blue component value
+    #
+    # @return [Color] A new instance of {Color}
     def initialize(*args)
       
       if args.length == 1 && args[0].is_a?(Color)
@@ -31,22 +60,6 @@ module Paleta
       end
     end
     
-    def rgb_init(red = 0, green = 0, blue = 0)
-      self.red = red
-      self.green = green
-      self.blue = blue
-    end
-    
-    def hsl_init(hue = 0, saturation = 0, lightness = 0)
-      self.hue = hue
-      self.saturation = saturation
-      self.lightness = lightness
-    end
-    
-    def hex_init(val = "000000")
-      self.hex = val
-    end
-    
     def red=(val)
       @red = range_validator(val, 0..255)
       update_hsl
@@ -92,44 +105,63 @@ module Paleta
       update_hsl
     end
     
+    # Determine the equality of the receiver and another {Color}
+    # @param [Color] color color to compare
+    # @return [Boolean]
     def ==(color)
       color.is_a?(Color) ? (self.hex == color.hex) : false
     end
     
-    def lighten(percent = 5)
+    # Create a copy of the receiver and lighten it by a percentage
+    # @param [Number] percentage percentage by which to lighten the {Color}
+    # @return [Color] a lightened copy of the receiver
+    def lighten(percentage = 5)
       copy = self.class.new(self)
-      copy.lighten!(percent)
+      copy.lighten!(percentage)
       copy
     end
     
-    def lighten!(percent = 5)
-      @lightness += percent
+    # Lighten the receiver by a percentage
+    # @param [Number] percentage percentage by which to lighten the {Color}
+    # @return [Color] self
+    def lighten!(percentage = 5)
+      @lightness += percentage
       @lightness = 100 if @lightness > 100
       update_rgb
       update_hex
       self
     end
     
-    def darken(percent = 5)
+    # Create a copy of the receiver and darken it by a percentage
+    # @param [Number] percentage percentage by which to darken the {Color}
+    # @return [Color] a darkened copy of the receiver
+    def darken(percentage = 5)
       copy = self.class.new(self)
-      copy.darken!(percent)
+      copy.darken!(percentage)
       copy
     end
     
-    def darken!(percent = 5)
-      @lightness -= percent
+    # Darken the receiver by a percentage
+    # @param [Number] percentage percentage by which to darken the {Color}
+    # @return [Color] self
+    def darken!(percentage = 5)
+      @lightness -= percentage
       @lightness = 0 if @lightness < 0
       update_rgb
       update_hex
       self
     end
     
+    # Create a copy of the receiver and invert it
+    # @return [Color] an inverted copy of the receiver
     def invert
       copy = self.class.new(self)
       copy.invert!
       copy
     end
     
+    # Invert the receiver
+    # @return [Color] self
     def invert!
       @red = 255 - @red
       @green = 255 - @green
@@ -139,12 +171,16 @@ module Paleta
       self
     end
     
+    # Create a copy of the receiver and desaturate it
+    # @return [Color] a desaturated copy of the receiver
     def desaturate
       copy = self.class.new(self)
       copy.desaturate!
       copy
     end
-    
+
+    # Desaturate the receiver
+    # @return [Color] self
     def desaturate!
       @saturation = 0
       update_rgb
@@ -152,12 +188,16 @@ module Paleta
       self
     end
     
+    # Create a new {Color} that is the complement of the receiver
+    # @return [Color] a desaturated copy of the receiver
     def complement
       copy = self.class.new(self)
       copy.complement!
       copy
     end
     
+    # Turn the receiver into it's complement
+    # @return [Color] self
     def complement!
       @hue = (@hue + 180) % 360
       update_rgb
@@ -165,12 +205,31 @@ module Paleta
       self
     end
     
+    # Calculate the similarity between the receiver and another {Color}
+    # @param [Color] color color to calculate the similarity to
+    # @return [Number] a value in [0..1] with 0 being identical and 1 being as dissimilar as possible
     def similarity(color)
       distance({ :r => @red, :g => @green, :b => @blue}, { :r => color.red, :g => color.green, :b => color.blue}) / sqrt(3 * (255 ** 2))
     end
     
     private
     
+    def rgb_init(red = 0, green = 0, blue = 0)
+      self.red = red
+      self.green = green
+      self.blue = blue
+    end
+    
+    def hsl_init(hue = 0, saturation = 0, lightness = 0)
+      self.hue = hue
+      self.saturation = saturation
+      self.lightness = lightness
+    end
+    
+    def hex_init(val = "000000")
+      self.hex = val
+    end
+    
     def update_hsl
       r = @red / 255.0 rescue 0.0
       g = @green / 255.0 rescue 0.0

data/lib/paleta/palette.rb

@@ -1,20 +1,58 @@
 require 'paleta/core_ext/math'
 
 module Paleta
+  
+  module MagickDependent
+    def self.included(klass)
+      require 'RMagick'
+      klass.extend(ClassMethods)
+    rescue LoadError
+      puts "You must install RMagick to use Palette.generate(:from => :image, ...)"
+    end
+    
+    module ClassMethods
+      def generate_from_image(path, size = 5)
+        include Magick
+        begin
+          image = Magick::ImageList.new(path)
+          
+          # quantize image to the nearest power of 2 greater the desired palette size
+          quantized_image = image.quantize((Math.sqrt(size).ceil ** 2), Magick::RGBColorspace)
+          colors = quantized_image.color_histogram.sort { |a, b| b[1] <=> a[1] }[0..(size - 1)].map do |color|          
+            Paleta::Color.new(color[0].red / 256, color[0].green / 256, color[0].blue / 256)
+          end
+          return Paleta::Palette.new(colors)
+        rescue Magick::ImageMagickError
+          raise "Invalid image at " << path
+        end
+      end
+    end
+  end
+  
+  # Represents a palette, a collection of {Color}s
   class Palette
     include Math
     include Enumerable
+    include MagickDependent
     
     attr_accessor :colors
     
+    # Initialize a {Palette} from a list of {Color}s
+    # @param [Array] colors a list of {Color}s to include in the {Palette}
+    # @return [Palette] A new instance of {Palette}
     def initialize(*args)
       @colors = []
       colors = (args.length == 1 && args[0].is_a?(Array)) ? args[0] : args
-      colors.each do |color|
-        self << color
-      end
+      colors.each { |color| self << color }
     end
     
+    # Add a {Color} to the {Palette}
+    # @overload <<(color)
+    #   @param [Color] color a {Color} to add to the receiver
+    # @overload <<(palette)
+    #   @param [Palette] palette a {Palette} to merge with the receiver
+    # @return [Palette] self
+    # @see Paleta::Palette.push(obj)
     def <<(obj)
       if obj.is_a?(Color)
         @colors << obj
@@ -26,67 +64,97 @@ module Paleta
       self
     end
     
+    # Add a {Color} to the {Palette}
+    # @overload push(color)
+    #   @param [Color] color a {Color} to add to the receiver
+    # @overload push(palette)
+    #   @param [Palette] palette a {Palette} to merge with the receiver
+    # @return [Palette] self
+    # @see Paleta::Palette.<<(obj)
     def push(obj)
       self << obj
     end
     
+    # Remove the most recently added {Color} from the receiver
     def pop
       @colors.pop
     end
     
-    def delete_at(i = 0)
-      @colors.delete_at(i)
+    # Remove a {Color} from the receiver by index
+    # @param [Number] index the index at which to remove a {Color}
+    def delete_at(index = 0)
+      @colors.delete_at(index)
     end
     
-    def [](i)
-      @colors[i]
+    # Access a {Color} in the receiver by index
+    # @param [Number] index the index at which to access a {Color}
+    def [](index)
+      @colors[index]
     end
     
+    # The number of {Color}s in the {Palette}
+    # @return [Number] the number of {Color}s in the receiver
     def size
       @colors.size
     end
     
+    # Iterate through each {Color} in the {Palette}
     def each
       @colors.each { |c| yield c }
     end
     
-    def sort &blk
-      @colors.sort &blk
+    # Create a new instance of {Palette} that is a sorted copy of the receiver
+    # @return [Palette] a new instance of {Palette}
+    def sort(&blk)
+      @colors.sort(&blk)
       Paleta::Palette.new(@colors)
     end
     
-    def sort! &blk
-      @colors.sort! &blk
+    # Sort the {Color}s in the receiver
+    # return [Palette] self
+    def sort!(&blk)
+      @colors.sort!(&blk)
       self
     end
     
+    # Test if a {Color} exists in the receiver
+    # @param [Color] color color to test for inclusion in the {Palette}
+    # @return [Boolean]
     def include?(color)
       @colors.include?(color)
     end
     
-    def lighten!(percent = 5)
-      @colors.each do |color|
-        color.lighten!(percent)
-      end
+    # Lighen each {Color} in the receiver by a percentage
+    # @param [Number] percentage percentage by which to lighten each {Color} in the receiver
+    # @return [Palette] self
+    def lighten!(percentage = 5)
+      @colors.each { |color| color.lighten!(percentage) }
+      self
     end
     
-    def darken!(percent = 5)
-      @colors.each do |color|
-        color.darken!(percent)
-      end
+    # Lighen each {Color} in the receiver by a percentage
+    # @param [Number] percentage percentage by which to lighten each {Color} in the receiver
+    # @return [Palette] self
+    def darken!(percentage = 5)
+      @colors.each { |color| color.darken!(percentage) }
+      self
     end
     
+    # Invert each {Color} in the receiver by a percentage
+    # @return [Palette] self
     def invert!
-      @colors.each do |color|
-        color.invert!
-      end
+      @colors.each { |color| color.invert! }
+      self
     end
     
+    # Calculate the similarity between the receiver and another {Palette}
+    # @param [Palette] palette palette to calculate the similarity to
+    # @return [Number] a value in [0..1] with 0 being identical and 1 being as dissimilar as possible
     def similarity(palette)
       r, a, b = [], [], []
       (0..1).each { |i| a[i], b[i] = {}, {} }
       
-      # r[i] is the Math::MultipleRegression of the Palette in RGB space
+      # r[i] is a hash of the multiple regression of the Palette in RGB space
       r[0] = fit
       r[1] = palette.fit
             
@@ -105,16 +173,38 @@ module Paleta
       d1 + d2
     end
     
+    # Generate a {Palette} from a seed {Color}
+    # @param [Hash] opts the options with which to generate a new {Palette}
+    # @option opts [Symbol] :type the type of palette to generate
+    # @option opts [Symbol] :from how to generate the {Palette}
+    # @option opts [Color] :color if :from == :color, pass a {Color} object as :color
+    # @option opts [String] :image if :from == :image, pass the path to an image as :image
+    # @option opts [Number] :size the number of {Color}s to generate for the {Palette}
+    # @return [Palette] A new instance of {Palette}
     def self.generate(opts = {})
-      raise(ArgumentError, "Pass a Color using :from, generate( :from => Color )") if opts.empty?
-      color = opts[:from]
-      type = opts[:type] || :shades
+      
       size = opts[:size] || 5
+      
+      if !opts[:type].nil? && opts[:type].to_sym == :random
+        return self.generate_random_from_color(opts[:color], size)
+      end
+      
+      unless (opts[:from].to_sym == :color && !opts[:color].nil?) || (opts[:from].to_sym == :image && !opts[:image].nil?)
+        return raise(ArgumentError, 'You must pass :from and it must be either :color or :image, then you must pass :image => "/path/to/img" or :color => color')
+      end
+                  
+      if opts[:from].to_sym == :image
+        path = opts[:image]
+        return self.generate_from_image(path, size)
+      end
+      
+      color = opts[:color]
+      type = opts[:type] || :shades
+      
       case type
       when :analogous; self.generate_analogous_from_color(color, size)
       when :complementary; self.generate_complementary_from_color(color, size)
       when :monochromatic; self.generate_monochromatic_from_color(color, size)
-      when :random; self.generate_random_from_color(color, size)
       when :shades; self.generate_shades_from_color(color, size)
       when :split_complement; self.generate_split_complement_from_color(color, size)
       when :tetrad; self.generate_tetrad_from_color(color, size)
@@ -130,7 +220,7 @@ module Paleta
       palette = self.new(color)
       step = 20
       below = (size / 2)
-      above = (size % 2 == 0) ? (size / 2) - 1: (size / 2)
+      above = (size % 2 == 0) ? (size / 2) - 1 : (size / 2)
       below.times do |i|
         hue = color.hue - ((i + 1) * step)
         hue += 360 if hue < 0

data/lib/paleta/version.rb

@@ -1,3 +1,3 @@
 module Paleta
-  VERSION = '0.0.5'
+  VERSION = '0.1.0'
 end

data/readme.markdown

@@ -125,46 +125,52 @@ Palettes can calculate their similarity to other Palettes by using the `similari
 	
 #### Generating Palettes
 
-Palettes can be generated from a "seed" Color by using the `generate` method.
-
-**Generate a random Palette**
-
-	palette = Paleta::Palette.generate(:type => :random, :size = 5)
+Palettes can be generated from a "seed" Color or from an image by using the `generate` method.
 	
 **Generate a Palette of shades from a Color**
 
 	color = Paleta::Color.new(:hex, "ff0000")
-	palette = Paleta::Palette.generate(:type => :shades, :from => color, :size => 5)
+	palette = Paleta::Palette.generate(:type => :shades, :from => :color, :size => 5)
 	
 **Generate a Palette of analogous Colors from a Color**
 
     color = Paleta::Color.new(:hex, "0066cc")
-    palette = Paleta::Palette.generate(:type => :analogous, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :analogous, :from => :color, :size => 5)
 	
 **Generate a Palette of monochromatic Colors from a Color**
 
     color = Paleta::Color.new(:hex, "336699")
-    palette = Paleta::Palette.generate(:type => :monochromatic, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :monochromatic, :from => :color, :size => 5)
 	
 **Generate a Palette of complementary Colors from a Color**
 
     color = Paleta::Color.new(:hex, "0000ff")
-    palette = Paleta::Palette.generate(:type => :complementary, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :complementary, :from => :color, :size => 5)
 
 **Generate a Palette of split-complement Colors from a Color**
 
     color = Paleta::Color.new(:hex, "006699")
-    palette = Paleta::Palette.generate(:type => :split_complement, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :split_complement, :from => :color, :size => 5)
 
 **Generate a Palette of triad Colors from a Color**
 
     color = Paleta::Color.new(:hex, "006699")
-    palette = Paleta::Palette.generate(:type => :triad, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :triad, :from => :color, :size => 5)
 
 **Generate a Palette of tetrad Colors from a Color**
 
     color = Paleta::Color.new(:hex, "dd5533")
-    palette = Paleta::Palette.generate(:type => :tetrad, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :tetrad, :from => :color, :size => 5)
+	
+**Generate a random Palette**
+
+	palette = Paleta::Palette.generate(:type => :random, :size => 5)
+	
+Palettes can also be generated from a seed image
+	
+**Generate a Palette from an image**
+
+	palette = Paleta::Palette.generate(:from => :image, :image => "/path/to/image.jpg", :size => 5)
 
 ***
 

data/spec/models/palette_spec.rb

@@ -137,7 +137,7 @@ describe Paleta::Palette do
   
   it "should generate a new Palette of shades of a single Color" do
     color = Paleta::Color.new(:hex, "ff0000")
-    palette = Paleta::Palette.generate(:from => color, :size => 5)
+    palette = Paleta::Palette.generate(:from => :color, :color => color, :size => 5)
     palette.size.should == 5
     palette.each do |p|
       p.hue.should == color.hue
@@ -152,7 +152,7 @@ describe Paleta::Palette do
   
   it "should generate a new Palette of Colors analogous to the seed Color" do
     color = Paleta::Color.new(:hex, "0066cc")
-    palette = Paleta::Palette.generate(:type => :analogous, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :analogous, :from => :color, :color => color, :size => 5)
     palette.size.should == 5
     palette.each do |p|
       p.lightness.should == color.lightness
@@ -167,7 +167,7 @@ describe Paleta::Palette do
   
   it "should generate a new Palette of Colors monochromatic to the seed Color" do
     color = Paleta::Color.new(:hex, "0066cc")
-    palette = Paleta::Palette.generate(:type => :monochromatic, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :monochromatic, :from => :color, :color => color, :size => 5)
     palette.size.should == 5
     palette.each do |p|
       p.hue.should == color.hue
@@ -187,7 +187,7 @@ describe Paleta::Palette do
   
   it "should generate a new complementary Palette from the seed Color" do
     color = Paleta::Color.new(:hex, "0066cc")
-    palette = Paleta::Palette.generate(:type => :complementary, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :complementary, :from => :color, :color => color, :size => 5)
     palette.size.should == 5
     palette.each do |c|
       c.lightness.should == color.lightness
@@ -197,7 +197,7 @@ describe Paleta::Palette do
 
   it "should generate a new triad Palette from the seed Color" do
     color = Paleta::Color.new(:hex, "0066cc")
-    palette = Paleta::Palette.generate(:type => :triad, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :triad, :from => :color, :color => color, :size => 5)
     palette.size.should == 5
     palette.each do |c|
       c.lightness.should == color.lightness
@@ -207,7 +207,7 @@ describe Paleta::Palette do
 
   it "should generate a new tetrad Palette from the seed Color" do
     color = Paleta::Color.new(:hex, "0066cc")
-    palette = Paleta::Palette.generate(:type => :tetrad, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :tetrad, :from => :color, :color => color, :size => 5)
     palette.size.should == 5
     palette.each do |c|
       c.lightness.should == color.lightness
@@ -217,11 +217,22 @@ describe Paleta::Palette do
   
   it "should generate a new split-complement Palette from the seed Color" do
     color = Paleta::Color.new(:hex, "0066cc")
-    palette = Paleta::Palette.generate(:type => :split_complement, :from => color, :size => 5)
+    palette = Paleta::Palette.generate(:type => :split_complement, :from => :color, :color => color, :size => 5)
     palette.size.should == 5
     palette.each do |c|
       c.lightness.should == color.lightness
       [color.hue, (color.hue + 150) % 360, (color.hue + 210) % 360].include?(c.hue).should be_true
     end
   end
+  
+  it "should generate a Palette from an image" do
+    path = File.join(File.dirname(__FILE__), '..', 'images/test.jpg')
+    size = 5
+    palette = Paleta::Palette.generate(:from => :image, :image => path, :size => size)
+    palette.size.should == size
+  end
+  
+  it "should raise an error when generating a Palette from an invalid image" do
+    expect{ Paleta::Palette.generate(:from => :image, :image => "/no/image.here") }.to raise_error(RuntimeError)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paleta
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-20 00:00:00.000000000Z
+date: 2012-03-02 00:00:00.000000000Z
 dependencies: []
 description: A gem for working with color palettes
 email:
@@ -28,6 +28,7 @@ files:
 - lib/paleta/version.rb
 - paleta.gemspec
 - readme.markdown
+- spec/images/test.jpg
 - spec/models/color_spec.rb
 - spec/models/palette_spec.rb
 - spec/spec_helper.rb
@@ -57,6 +58,8 @@ specification_version: 3
 summary: A little library for creating, manipulating and comparing colors and color
   palettes
 test_files:
+- spec/images/test.jpg
 - spec/models/color_spec.rb
 - spec/models/palette_spec.rb
 - spec/spec_helper.rb
+has_rdoc: