pigment 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f65760dd782badba8e2142b5b44f801956ac611c
-  data.tar.gz: 7558e44c1a8bc79bee4d4236bc86a6dedc31d0d8
+SHA256:
+  metadata.gz: dda5e6ade89b5949326fcb411e9aa8d99065fa511d3baeebb08e1cfb6199e84e
+  data.tar.gz: '058d8b2c5e47edfe74d716688ab99e33b99b51c46773dd0600c43c4755010b2e'
 SHA512:
-  metadata.gz: 257a7f79240c8875f5990861cb8d5c195ac32a26c05c2b78e49c4a532efe086cddcb206e2e8bc1fd86020c227dded6e0e6d8517950f0f81950c383e1ea84fc7e
-  data.tar.gz: 3bdc92c1b0835aae32863cd37db8255cbcb3a2d462249645f87b542f48717adf225d668f3f8662738351764c90ecb280360a4fb0fce2c2d88b729c64ff97097f
+  metadata.gz: 409765f525e55b3b63fd2ce3fe1e54af1fb070600c4f049a7992d984bd20b0b7f08bbdedb08f5702d6a9f53b50f035c4e25cff4013d741175f5615f889b1febd
+  data.tar.gz: ab38122e3bbd72c5af6f78a451ae885b52673ec3583a05d346af1bd9c81bd8d844d0dea757fb8e5a5eb7a111452815a192cfebd079304707128a35b45ced28d6

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 0.3.0
+- New classes per Color Format
+    - Pigment::Color::RGB
+    - Pigment::Color::HSL
+- Base module for Color Formats Pigment::Color
+- Palette class to handle a collection of colors

data/LICENSE.md

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright © 2020 Pedro Miranda
+
+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.md

@@ -6,29 +6,185 @@ To install:
 gem install pigment
 ```
 
-<a href='http://www.pledgie.com/campaigns/18945'><img alt='Click here to lend your support to: pigment (ruby gem) and make a donation at www.pledgie.com !' src='http://www.pledgie.com/campaigns/18945.png?skin_name=chrome' border='0' /></a>
+## Usage
+### RGB Color Format
+The RGB color format is represented with four components between 0.0 and 1.0, representing 0 to 255
+- `@red`
+- `@green`
+- `@blue`
+- `@alpha`
 
-# License
+```ruby
+require 'pigment/color/rgb'
 
-(The MIT License)
+red = Pigment::Color::RGB.new(1.0, 0.0, 0.0)
+# RGB Color(red: 1.0, green: 0.0, blue: 0.0, alpha: 0.0)
 
-Copyright &copy; 2012 Pedro Miranda
+red.to_a
+# [1.0, 0.0, 0.0, 1.0]
 
-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:
+semitransparent_red = Pigment::Color::RGB.new(1.0, 0.0, 0.0, 0.5)
+# RGB Color(red: 1.0, green: 0.0, blue: 0.0, alpha: 0.5)
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+red + semitransparent_red
+# RGB Color(red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0)
 
-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.
+semitransparent_red + red 
+# RGB Color(red: 1.0, green: 0.0, blue: 0.0, alpha: 0.5)
+
+red - semitransparent_red
+# RGB Color(red: 0.0, green: 0.0, blue: 0.0, alpha: 1.0)
+
+half_red = red / 2
+# RGB Color(red: 0.5, green: 0.0, blue: 0.0, alpha: 1.0)
+
+half_red * 2 == red
+# true
+
+gray50 = Pigment::Color::RGB.new(1.0, 0.5, 0.0).grayscale
+# RGB Color(red: 0.5, green: 0.5, blue: 0.5, alpha: 1.0)
+
+gray50.grayscale?
+# true
+
+cyan = red.inverse
+# RGB Color(red: 0.0, green: 1.0, blue: 1.0, alpha: 1.0)
+
+green, blue = red.triadic
+# [RGB Color(red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0), RGB Color(red: 0.0, green: 0.0, blue: 1.0, alpha: 1.0)]
+
+red.to_hex
+# '0xff0000ff'
+
+red.to_hex(with_alpha: false)
+# '0xff0000'
+
+Pigment::Color::RGB.convert(Pigment::Color::HSL.new(0.0, 1, 0.5))
+# RGB Color(red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0)
+```
+
+### HSL Color Format
+
+The HSL color format is represented with
+
+- `@hue` - a value from 0.0 to 1.0, representing 0 to 360 degrees
+- `@saturation` - a value from 0.0 to 1.0 
+- `@lightness` - a value from 0.0 to 1.0
+- `@alpha` - a value from 0.0 to 1.0
+
+This format is useful to calculate related colors:
+
+- triadic
+- split
+- analogous
+- tetradic
+- rectangular
+- tertiary
+
+```ruby
+require 'pigment/color/hsl'
+
+hsl_red = Pigment::Color::HSL.convert(red)
+# HSL Color(hue: 0.0, saturation: 1.0, lightness: 0.5, alpha: 1.0)
+
+hsl_red == Pigment::Color::HSL(0.0, 1, 0.5)
+# HSL Color(hue: 0.0, saturation: 1.0, lightness: 0.5, alpha: 1.0)
+
+hsl_red.triadic
+hsl_red.split
+hsl_red.analogous
+hsl_red.tetradic
+hsl_red.rectangular
+hsl_red.tertiary
+
+```
+
+### Color Module
+
+The color module works as the base for any possible color format, implementing common methods
+
+```ruby
+red.to_html
+# '#ff0000'
+
+red.into(Pigment::HSL)
+# HSL Color(hue: 0.0, saturation: 1.0, lightness: 0.5, alpha: 1.0)
+
+red.inverse?(cyan)
+# true
+
+red.triadic_of?(blue)
+# true
+
+red.triadic_include?(green, blue)
+# true
+
+red.split_of?
+red.split_include?
+red.analogous_of?
+red.analogous_include?
+red.tetradic_of?
+red.tetradic_include?
+red.rectangular_of?
+red.rectangular_include?
+red.tertiary_of?
+red.tertiary_include?
+# of -> checks if self is included in argument result  
+# include -> checks if arguments are included in self result  
+```
+
+### Color Palette
+
+```ruby
+require 'pigment/palette'
+
+pallete = Pigment::Palette.new(
+  red: red,
+  blue: blue,
+)
+
+pallete[:red]
+# RGB Color(red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0)
+
+pallete[:green] = green
+# RGB Color(red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0)
+
+# Pigment::Palette is enumerable
+
+palette.map.to_a
+# [RGB Color(red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0), RGB Color(red: 0.0, green: 0.0, blue: 1.0, alpha: 1.0), RGB Color(red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0)]
+```
+
+### Default Color Palette
+
+```ruby
+require 'pigment/default_rgb_palette'
+
+Pigment::Palette::RGB::DEFAULT[:Red]
+# RGB Color(red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0)
+
+
+Pigment::Palette::RGB::Green
+# RGB Color(red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0)
+
+Pigment::Palette::RGB.Blue
+# RGB Color(red: 0.0, green: 0.0, blue: 1.0, alpha: 1.0)
+```
+
+## Changes
+See [Changelog](CHANGELOG.md)
+
+
+## Future Work
+- [ ] new color formats:
+    - [ ] Y'CbCr
+    - [ ] RYB
+    - [ ] CMYK
+- [ ] redesign of Base Color module to support Additive color formats
+- [ ] Palette Loader to load palette files
+
+## License
+See [License](LICENSE.md)
+
+## Related interests
+- [color-names](https://github.com/meodai/color-names): javascript collection of 25586 color names  

data/lib/pigment.rb

@@ -1,306 +1,3 @@
-module Pigment
-  VERSION = '0.2.3'.freeze
-
-  class Color
-
-    @named_colors = {}
-    attr_reader :color, :hsl
-
-    # Pigment uses sRGB or sRGBA as the default color system
-    # color can be a hexadecimal code preceded by a '#' like '#FF4CB2' or a array of floats (1.0, 0.3, 0.7)
-    # or an array of integers between 0 and 255 (153, 255, 31)
-    # @param [String, Array] color
-    def initialize(*color)
-      @color = case
-               when color[0] =~ /^#([a-fA-F0-9]{2})([a-fA-F0-9]{2})([a-fA-F0-9]{2})([a-fA-F0-9]{2})?$/
-                 [$1, $2, $3, $4 || 'ff'].map { |v| v.to_i(16) / 255.0 }
-               when color.is_a?(Array) && (color.all? { |c| (0.0..1.0).include? c }) && color.length == 3
-                 [color, 1.0].flatten!
-               when color.is_a?(Array) && (color.all? { |c| (0..255).include? c && c.is_a?(Integer) } ) && color.length == 3
-                 [color.map { |c| c / 255.0 }, 1.0].flatten!
-               when color.is_a?(Array) && (color.all? { |c| (0.0..1.0).include? c }) && color.length == 4
-                 color
-               when color.is_a?(Array) && (color.all? { |c| (0..255).include? c && c.is_a?(Integer) } ) && color.length == 4
-                 color.map { |c| c / 255.0 }
-               else
-                 raise ArgumentError, "Expected String or Array with length 3 or 4. Given #{color.class} with length = #{color.length}"
-               end
-    end
-
-    # Getters and Setters.
-    %w'r g b a'.each_with_index do |m, i|
-      define_method("#{m}", ->() { @color[i] })
-      define_method("#{m}=", ->(value) { @color[i] = value if value.is_a?(Float) && (0.0..1.0).include?(value) })
-    end
-
-    %w'h s l'.each_with_index do |m, i|
-      define_method("#{m}", ->() { hsl[i] })
-    end
-
-    def method_missing(method, *args)
-      # Returns an array with the respective rgba components
-      # @return [Array]
-      super unless method =~ /(a|b|g|r)+/ && args.empty?
-      method.size.times.map{ |i| send(method[i]) }
-    end
-
-    # Return specified color by its name from the named_colors hash.
-    # @param [Symbol] name
-    # @return [Array]
-    def self.[](*colors)
-      colors.size > 1 ? colors.map { |color| @named_colors[color] } : @named_colors[colors[0]]
-    end
-
-    # Add name to a color , add it to the named_colors hash and defines a constant.
-    # @param [Array of Strings] names
-    # @param [Color] color
-    def self.[]=(*names, color)
-      color = new(color) unless color.is_a? Color
-      names.each do |name|
-        @named_colors[name.downcase] = color
-        const_set("#{name}".to_sym, color)
-      end
-    end
-
-    # Return all the named_colors as an array.
-    def self.named_colors
-      @named_colors.keys
-    end
-
-    # Return all the named_colors as a sorted array.
-    def self.named_colors_sorted
-      named_colors.sort
-    end
-
-    # Suppress an array of floats by dividing by the greatest color component.
-    # @param [Array] color
-    # @return [Array]
-    def self.suppress(color)
-      color.map!  { |c| c / color.max } unless (0.0..1.0).include?(color.max)
-      color
-    end
-
-    # Creates a Color form the HSL color System. It's mostly used to calculate harmonic colors.
-    # @param [Float] h
-    # @param [Float] s
-    # @param [Float] l
-    # @return [Color]
-    def self.from_hsl(h, s, l)
-      return new(l, l, l) if s == 0
-      v2 = l < 0.5 ? l * (1 + s) : (l + s) - (s * l)
-      v1 = 2 * l - v2
-      color = [h + (1 / 3.0), h, h - (1 / 3.0)].map do |hv|
-        case
-        when hv < 0 then hv += 1
-        when hv > 1 then hv -= 1
-        when 6 * hv < 1 then v1 +(v2 - v1) * 6 * hv
-        when 2 * hv < 1 then v2
-        when 3 * hv < 2 then v1 + (v2 - v1) * ((2 / 3.0)- hv) * 6
-        else v1
-        end
-      end
-      new(*color)
-    end
-
-    # Same as inverse.
-    def -@
-      inv
-    end
-
-    # Sums all the two colors components. If any component gets out of the 0 to 1.0 range its suppressed.
-    # @param [Numeric] color
-    # @return [Color]
-    def +(color)
-      case color
-      when Color
-        self.class.new(*self.class.suppress([color.rgb, rgb].transpose.map! { |c, d| c + d }))
-      else
-        raise ArgumentError, "Expecting Color. Given #{color.class}"
-      end
-    end
-
-    # Subtracts all the two color components. If any component gets out of the 0 to 1.0 range its suppressed.
-    # If tone component gets lower than 0 it acts like its dealing with the inverse component -> 1 - component
-    # @param [Numeric] color
-    # @return [Color]
-    def -(color)
-      case color
-      when Color
-        self.class.new(*self.class.suppress([rgb, color.rgb].transpose.map! do |c, d|
-          e = c - d
-          e >= 0 ? e : e = 1 + e
-          e
-        end))
-      else
-        raise ArgumentError, "Expecting color. Given #{color.class}"
-      end
-    end
-
-    # Multiplies all the color components by n. If any component gets out of the 0 to 1.0 range its suppressed.
-    # @param [Numeric] n
-    # @return [Color]
-    def *(n)
-      case n
-      when Numeric
-        n = rgb.map { |c| c * n.to_f }
-        self.class.new(*self.class.suppress(n))
-      else
-        raise ArgumentError, "Expecting Numeric. Given #{n.class}"
-      end
-    end
-
-    # Divides all the color components by n. If any component gets out of the 0 to 1.0 range its suppressed.
-    # @param [Numeric] n
-    # @return [Color]
-    def /(n)
-      case n
-      when Numeric
-        n = rgb.map { |c| c * n.to_f }
-        self.class.new(*self.class.suppress(n))
-      else
-        raise ArgumentError, "Expecting Numeric. Given #{n.class}"
-      end
-    end
-
-    # Test if two colors are equal
-    # @param [Color] color
-    # @return [Boolean]
-    def ==(color)
-      color.is_a?(Color) && color.rgba == rgba
-    end
-
-    # @return [Color]
-    def dup
-      self.class.new(*@color)
-    end
-
-    # Converts a color to its grayscale correspondent
-    # @return [Color]
-    def grayscale
-      r = g = b = (self.r + self.g + self.b)/3
-      self.class.new(r, g, b)
-    end
-
-    # Calculates the harmonic colors. Type can be :triadic, :split, :analogous, :complement or :complementary
-    # @param [Symbol] type
-    # @return [Color, Array of Colors]
-    def harmonize(type = :triadic)
-      color.to_hsl unless @hsl
-      case type
-      when :triadic
-        [self.class.from_hsl(h - 5 / 12.0, s, l), self.class.from_hsl(h + 1 / 3.0, s, l)]
-      when :split
-        [self.class.from_hsl(h - 5 / 12.0, s, l), self.class.from_hsl(h + 5 / 12.0, s, l)]
-      when :analogous
-        [self.class.from_hsl(h - 1 / 12.0, s, l), self.class.from_hsl(h + 1 / 12.0, s, l)]
-      when :complement, :complementary
-        inv
-      else
-        raise ArgumentError, "Expected :triadic, :split, :analogous, :complement or :complementary. Given #{type}"
-      end
-    end
-
-    # Interpolates two colors. Amount must be an float between -1.0 and 1.0
-    # @param [Color] color
-    # @param [Float] amount
-    def interpolate(color, amount = 0.5)
-      if color.is_a?(Color) && (-1.0..1.0).include?(amount)
-        n = [rgb, color.rgb].transpose.map! { |c, d| c + amount * (d - c) }
-        self.class.new(*self.class.suppress(n))
-      else
-        raise ArgumentError
-      end
-    end
-
-    # Returns the Invert color
-    # @return [Color]
-    def inverse
-      self.class.new(*rgb.map { |c| 1.0 - c })
-    end
-
-    # Returns a new Color without the given channels
-    # @param [Array of Symbols] channels
-    # @return [Color]
-    def remove_channels(*channels)
-      color = self.class.new(r, g, b, a)
-      %w'r g b a'.each do |attr|
-        color.send("#{attr}=", 0) if channels.include? attr.to_sym
-      end
-      color
-    end
-
-    # Creates an instance variable to keep the HSL values of a RGB color.
-    # @return [Array]
-    def to_hsl
-      min   = rgb.min
-      max   = rgb.max
-      delta = (max - min)
-      l     = (max + min) / 2.0
-
-      s = if delta == 0.0 # close to 0.0, so it's a grey
-            h = 0
-            0
-          elsif l < 0.5
-            delta / (max + min)
-          else
-            delta / (2.0 - max - min)
-          end
-
-      h = if r == max
-            h = ((g - b) / delta) / 6.0
-            h += 1.0 if g < b
-            h
-          elsif g == max
-            ((b - r) / delta) / 6.0 + (1.0 / 3.0)
-          elsif b == max
-            ((r - g) / delta) / 6.0 + (2.0 / 3.0)
-          end
-
-      h += 1 if h < 0
-      h -= 1 if h > 1
-      @hsl = [h, s, l]
-      self
-    end
-
-    # Returns an array of the color components. Alpha value is passed as well if with_alpha is set to true.
-    # @param [Boolean] with_alpha
-    # @return [Array]
-    def to_floats(with_alpha = true)
-      with_alpha ? @color.dup : rgb
-    end
-
-    # Returns an array of the color components. Alpha value is passed as well if with_alpha is set to true.
-    # @param [Boolean] with_alpha
-    # @return [Array]
-    def to_ints(with_alpha = true)
-      to_floats(with_alpha).map { |v| Integer(v * 255) }
-    end
-
-    # Returns an array of the color components. Alpha value is passed as well if with_alpha is set to true.
-    # @param [Boolean] with_alpha
-    # @return [Array]
-    def to_hex(with_alpha = true)
-      to_ints(with_alpha).map { |v| '%02x' % v }.join
-    end
-
-    def to_s
-      "Color(r=#{r}, g=#{g}, b=#{b}, a=#{a}#{", [h=#{h}, s=#{s}, l=#{l}]" if @hsl})"
-    end
-
-    alias_method :alpha=,        :a=
-    alias_method :inv,           :inverse
-    alias_method :invert,        :inverse
-    alias_method :complementary, :inverse
-    alias_method :mix,           :interpolate
-    alias_method :red,           :r
-    alias_method :green,         :g
-    alias_method :blue,          :b
-    alias_method :alpha,         :a
-    alias_method :to_a,          :to_floats
-    alias_method :to_ary,        :to_floats
-    alias_method :to_f,          :to_floats
-    alias_method :to_hsl,        :hsl
-  end
-end
-
-require_relative 'colors.rb'
+require_relative 'pigment/version'
+require_relative 'pigment/float_snap'
+require_relative 'pigment/color/invalid_color_format_error'