pigment 0.2.1 → 0.3.1

data/lib/pigment/color.rb

@@ -0,0 +1,195 @@
+require_relative '../pigment'
+
+module Pigment
+  # Represent an abstract color in any format
+  module Color
+    class << self
+      # @param [#to_f] red
+      # @param [#to_f] blue
+      # @param [#to_f] green
+      # @param [#to_f] alpha
+      # @return [Pigment::Color::RGB]
+      def rgba(red, blue, green, alpha = 1.0)
+        Pigment::Color::RGB.new(red, blue, green, alpha)
+      end
+
+      # @param [Integer] hue between 0 and 360 degrees
+      # @param [#to_f] saturation between 0.0 and 1.0
+      # @param [#to_f] lightness between 0.0 and 1.0
+      # @param [#to_f] alpha between 0.0 and 1.0
+      # @return [Pigment::Color::HSL]
+      def hsla(hue, saturation, lightness, alpha = 1.0)
+        Pigment::Color::HSL.from_hue_angle(hue, saturation, lightness, alpha)
+      end
+
+      alias_method :rgb, :rgba
+      alias_method :hsl, :hsla
+
+      # sets aliases for any color format
+      # @param [Class] klass
+      def included(klass)
+        klass.alias_method :gray?,         :grayscale?
+        klass.alias_method :-@,            :inverse
+        klass.alias_method :inv,           :inverse
+        klass.alias_method :invert,        :inverse
+        klass.alias_method :complementary, :inverse
+        klass.alias_method :complement,    :inverse
+        klass.alias_method :to_floats,     :to_a
+        klass.alias_method :to_f,          :to_a
+        klass.alias_method :inspect,       :to_s
+      end
+    end
+
+    # @param [Class] color_type
+    # @return [Pigment::Color]
+    def into(color_type)
+      color_type.convert(self)
+    end
+
+    # @return [Pigment::Color]
+    def dup
+      self.class.new(*to_a)
+    end
+
+    # @return [Pigment::Color]
+    def inverse
+      into(Pigment::Color::RGB).inverse.into(self.class)
+    end
+
+    # @param [Object] other
+    # @return [Boolean]
+    def inverse?(other)
+      other.is_a?(Pigment::Color) && self.inverse == other
+    end
+
+    # @return [Array<Pigment::Color>]
+    def triadic
+      into(Pigment::Color::RGB).triadic.map { |color| color.into(self.class) }
+    end
+
+    # @param [Object] other
+    # @return [Boolean]
+    def triadic_of?(other)
+      other.into(self.class)
+      other.triadic.include?(self)
+    end
+
+    # @param [Array<Object>] others
+    # @return [Boolean]
+    def triadic_include?(*others)
+      colors = triadic
+      others.all? { |color| colors.include?(color) }
+    end
+
+    # @return [Array<Pigment::Color>]
+    def split
+      into(Pigment::Color::HSL).split.map { |color| color.into(self.class) }
+    end
+
+    # @param [Object] other
+    # @return [Boolean]
+    def split_of?(other)
+      other.split.include?(self)
+    end
+
+    # @param [Array<Object>] others
+    # @return [Boolean]
+    def split_include?(*others)
+      colors = split
+      others.all? { |color| colors.include?(color) }
+    end
+
+    # @return [Array<Pigment::Color>]
+    def analogous
+      into(Pigment::Color::HSL).analogous.map { |color| color.into(self.class) }
+    end
+
+    # @param [Object] other
+    # @return [Boolean]
+    def analogous_of?(other)
+      other.analogous.include?(self)
+    end
+
+    # @param [Array<Object>] others
+    # @return [Boolean]
+    def analogous_include?(*others)
+      colors = analogous
+      others.all? { |color| colors.include?(color) }
+    end
+
+    # @return [Array<Pigment::Color>]
+    def tetradic
+      into(Pigment::Color::HSL).tetradic.map { |color| color.into(self.class) }
+    end
+
+    # @param [Object] other
+    # @return [Boolean]
+    def tetradic_of?(other)
+      other.tetradic.include?(self)
+    end
+
+    # @param [Array<Object>] others
+    # @return [Boolean]
+    def tetradic_include?(*others)
+      others.all? { |color| tetradic.include?(color) }
+    end
+
+    # @return [Array<Pigment::Color>]
+    def rectangular
+      into(Pigment::Color::HSL).rectangular.map { |color| color.into(self.class) }
+    end
+
+    # @param [Object] other
+    # @return [Boolean]
+    def rectangular_of?(other)
+      other.rectangular.include?(self)
+    end
+
+    # @param [Array<Object>] others
+    # @return [Boolean]
+    def rectangular_include?(*others)
+      colors = rectangular
+      others.all? { |color| colors.include?(color) }
+    end
+
+    # @return [Array<Pigment::Color>]
+    def tertiary
+      into(Pigment::Color::HSL).tertiary.map { |color| color.into(self.class) }
+    end
+
+    # @param [Object] other
+    # @return [Boolean]
+    def tertiary_of?(other)
+      other.tertiary.include?(self)
+    end
+
+    # @param [Array<Object>] others
+    # @return [Boolean]
+    def tertiary_include?(*others)
+      colors = tertiary
+      others.all? { |color| colors.include?(color) }
+    end
+
+    # @param [Boolean] with_alpha
+    # @return [String]
+    def to_html(with_alpha: false)
+      "##{to_hex(with_alpha: with_alpha)}"
+    end
+
+    # @param [Boolean] with_alpha
+    # @return [Array<Integer>]
+    def to_ints(with_alpha: true)
+      into(Pigment::Color::RGB).to_ints(with_alpha: with_alpha)
+    end
+
+    # @param [Boolean] with_alpha
+    # @return [String]
+    def to_hex(with_alpha: true)
+      into(Pigment::Color::RGB).to_hex(with_alpha: with_alpha)
+    end
+  end
+end
+
+require_relative 'color/rgb'
+require_relative 'color/hsl'
+

data/lib/pigment/color/hsl.rb

@@ -0,0 +1,158 @@
+require_relative '../color'
+
+module Pigment
+  module Color
+    # Represent a color in the HSL Format
+    class HSL
+      using FloatSnap
+
+      # @return [Float]
+      attr_reader :hue, :saturation, :lightness, :alpha
+
+      class << self
+
+        # Converts a color into HSL format from any possible format, given they know how to convert to RGB
+        # @param [Pigment::Color] color
+        # @return [Pigment::Color::HSL]
+        def convert(color)
+          return color if color.is_a?(self)
+          color   = color.into(Pigment::Color::RGB)
+          rgb     = color.rgb
+          r, g, b = rgb
+
+          min    = rgb.min
+          max    = rgb.max
+          chroma = max - min
+          sum    = max + min
+          l      = sum / 2.0
+
+          return new(0, 0, l, color.alpha) if chroma == 0.0
+
+          s = l > 0.5 ? chroma / (2.0 - sum) : chroma / sum
+
+          h = case max
+          when r then ((g - b) / chroma) / 6 + (g < b && 1 || 0)
+          when g then ((b - r) / chroma) / 6.0 + (1.0 / 3.0)
+          when b then ((r - g) / chroma) / 6.0 + (2.0 / 3.0)
+          end
+
+          new(h, s, l, color.alpha)
+        end
+
+        # @param [Integer] hue between 0 and 360 degrees
+        # @param [#to_f] saturation between 0.0 and 1.0
+        # @param [#to_f] lightness between 0.0 and 1.0
+        # @param [#to_f] alpha between 0.0 and 1.0
+        # @return [Pigment::Color::HSL]
+        def from_hue_angle(hue, saturation, lightness, alpha = 1.0)
+          new(hue / 360.0, saturation, lightness, alpha)
+        end
+      end
+
+      # @param [#to_f] hue between 0.0 and 1.0 mapping to 0 to 360 degrees
+      # @param [#to_f] saturation between 0.0 and 1.0
+      # @param [#to_f] lightness between 0.0 and 1.0
+      # @param [#to_f] alpha between 0.0 and 1.0
+      # @return [Pigment::Color::HSL]
+      # @raise [InvalidColorFormatError]
+      def initialize(hue, saturation, lightness, alpha = 1.0)
+        @hue        = hue % 1.0
+        @saturation = saturation.to_f.snap
+        @lightness  = lightness.to_f.snap
+        @alpha      = alpha.to_f.snap
+
+        color = to_f(with_alpha: true)
+        raise InvalidColorFormatError, color unless color.all? { |c| c.between?(0.0, 1.0) }
+      end
+
+      # @return [Pigment::Color::HSL] the grayscale correspondent of the color
+      def grayscale
+        self.class.new(@hue, 0, @lightness, @alpha)
+      end
+
+      # @return [Boolean] true if saturation is 0, false otherwise
+      def grayscale?
+        @saturation == 0
+      end
+
+      # @return [Array<Pigment::Color>] An array with the triadic colors  of the color
+      def triadic
+        [self.class.new(@hue + 1 / 3.0, s, l), self.class.new(@hue + 2 / 3.0, s, l)]
+      end
+
+      # @return [Array<Pigment::Color>] An array with the split colors  of the color
+      def split
+        [self.class.new(@hue - 5 / 12.0, s, l), self.class.new(@hue + 5 / 12.0, s, l)]
+      end
+
+      # @return [Array<Pigment::Color>] An array with the analogous colors  of the color
+      def analogous
+        [self.class.new(@hue - 1 / 12.0, s, l), self.class.new(@hue + 1 / 12.0, s, l)]
+      end
+
+      # @return [Array<Pigment::Color>] An array with the tetradic colors  of the color
+      def tetradic
+        [
+            self.class.new(@hue + 1 / 4.0, @saturation, @lightness),
+            self.class.new(@hue + 1 / 2.0, @saturation, @lightness),
+            self.class.new(@hue + 3 / 4.0, @saturation, @lightness)
+        ]
+      end
+
+      # @return [Array<Pigment::Color>] An array with the rectangular colors  of the color
+      def rectangular
+        [
+            self.class.new(@hue + 1 / 6.0, @saturation, @lightness),
+            self.class.new(@hue + 1 / 2.0, @saturation, @lightness),
+            self.class.new(@hue + 2 / 3.0, @saturation, @lightness)
+        ]
+      end
+
+      # @return [Array<Pigment::Color>] An array with the tertiary colors  of the color
+      def tertiary
+        [
+            self.class.new(@hue + 1 / 6.0, @saturation, @lightness),
+            self.class.new(@hue + 1 / 3.0, @saturation, @lightness),
+            self.class.new(@hue + 1 / 2.0, @saturation, @lightness),
+            self.class.new(@hue + 2 / 3.0, @saturation, @lightness),
+            self.class.new(@hue + 5 / 6.0, @saturation, @lightness),
+        ]
+      end
+
+      # @param [Boolean] with_alpha
+      # @return [Array<Float>] an array with the color components
+      def to_a(with_alpha: true)
+        with_alpha ? [@hue, @saturation, @lightness, @alpha] : [@hue, @saturation, @lightness]
+      end
+
+      # @return [String] the string representation of a hsl color
+      def to_s
+        "HSL Color(hue: #{hue}, saturation: #{saturation}, lightness: #{lightness}, alpha: #{alpha})"
+      end
+
+      # @param [Object] other
+      # @return [Boolean] wether the color is equal to other object
+      def ==(other)
+        other = Pigment::Color::HSL.convert(other)
+        other.hue.snap == @hue.snap &&
+            other.saturation.snap == @saturation.snap &&
+            other.lightness.snap == @lightness.snap &&
+            other.alpha.snap == @alpha.snap
+      end
+
+      alias_method :a, :alpha
+      alias_method :h, :hue
+      alias_method :s, :saturation
+      alias_method :l, :lightness
+
+      include Pigment::Color
+
+      private
+      # @return [Array] an array with the respective hsla components
+      def method_missing(method, *args)
+        super unless method =~ /^[ahsl]+$/ && args.empty?
+        method.to_s.each_char.map { |component| send(component) }
+      end
+    end
+  end
+end

data/lib/pigment/color/invalid_color_format_error.rb

@@ -0,0 +1,10 @@
+module Pigment
+  module Color
+    # Error raised when an invalid color format is used
+    class InvalidColorFormatError < ArgumentError
+      def initialize(object)
+        super("Invalid Format #{object.inspect}")
+      end
+    end
+  end
+end

data/lib/pigment/color/rgb.rb

@@ -0,0 +1,283 @@
+require_relative '../color'
+
+module Pigment
+  module Color
+    # Represent a color in the RGB Format
+    class RGB
+      using FloatSnap
+
+      # @return [Float]
+      attr_reader :red, :green, :blue, :alpha
+
+      class << self
+        # Converts a color into RGB format from any possible format
+        # @param [Pigment::Color] color
+        # @return [Pigment::Color]
+        # @raise [InvalidColorFormatError]
+        def convert(color)
+          case color
+          when RGB then color
+          when HSL then from_hsl(*color)
+          else raise InvalidColorFormatError, color
+          end
+        end
+
+        # Creates a Pigment::Color::RGB from an HTML Hex code String
+        # @param [String, Integer, Float] hex
+        # @return [Pigment::Color::RGB]
+        # @raise [InvalidColorFormatError]
+        def from_hex(hex)
+          case hex
+          when String  then from_hex_string(hex)
+          when Integer then from_hex_integer(hex)
+          when Float   then from_hex_integer(hex.round)
+          else raise InvalidColorFormatError, hex
+          end
+        end
+
+        # Creates a Pigment::Color from a group of rgba Integers
+        # @param [Integer] red
+        # @param [Integer] green
+        # @param [Integer] blue
+        # @param [Integer] alpha
+        # @return [Pigment::Color::RGB]
+        # @raise [InvalidColorFormatError]
+        def from_rgba_integers(red, green, blue, alpha = 255)
+          color = [red, green, blue, alpha]
+          raise InvalidColorFormatError, color unless color.all? do |c|
+            (0..255).include? c
+          end
+          new(*color.map { |c| c / 255.0 })
+        end
+
+        # @param [Integer] red
+        # @param [Integer] green
+        # @param [Integer] blue
+        # @return [Pigment::Color::RGB]
+        def from_rgb_integers(red, green, blue)
+          from_rgba_integers(red, green, blue)
+        end
+
+        # @return [Pigment::Color::RGB] a random generated color
+        def random
+          new(rand(0.0..1.0), rand(0.0..1.0), rand(0.0..1.0))
+        end
+
+        # Suppress an array of floats by dividing by the greatest color component.
+        # @param [Array] color
+        # @return [Array]
+        def suppress(color)
+          return color.map { |c| c / color.max } unless color.max.between?(0.0, 1.0)
+          color
+        end
+
+        private
+        # @param [Integer] hex
+        # @return [Pigment::Color::RGB]
+        def from_hex_integer(hex)
+          raise InvalidColorFormatError, hex unless hex.is_a?(Numeric) && hex.between?(0, 0xFFFFFFFF)
+          red   = (hex >> 24 & 0xFF)
+          green = (hex >> 16 & 0xFF)
+          blue  = (hex >>  8 & 0xFF)
+          alpha = (hex       & 0xFF)
+          from_rgba_integers(red, green, blue, alpha)
+        end
+
+        # @param [String] hex
+        # @raise [InvalidColorFormatError]
+        # @return [Pigment::Color::RGB]
+        def from_hex_string(hex)
+          matches = hex.match(/^#?(?<r>\h{2})(?<g>\h{2})(?<b>\h{2})(?<a>\h{2})?$/)&.named_captures
+          raise InvalidColorFormatError, hex unless matches
+          matches["a"] ||= 'FF'
+          new(*matches.values.map { |value| value.to_i(16) / 255.0 })
+        end
+
+        # Creates a Pigment::Color::RGB form the HSL color System. It's mostly used to calculate harmonic colors.
+        # @param [#to_f] hue between 0.0 and 1.0
+        # @param [#to_f] saturation between 0.0 and 1.0
+        # @param [#to_f] lightness between 0.0 and 1.0
+        # @param [#to_f] alpha between 0.0 and 1.0
+        # @return [Pigment::Color::RGB]
+        def from_hsl(hue, saturation, lightness, alpha = 1.0)
+          return new(lightness, lightness, lightness, alpha) if saturation == 0
+          v2 = lightness < 0.5 ? lightness * (1 + saturation) : lightness + saturation - saturation * lightness
+          v1 = 2 * lightness - v2
+          color = [hue + (1 / 3.0), hue, hue - (1 / 3.0)].map do |hv|
+            hv = hv < 0 ? hv + 1
+                : hv > 1 ? hv - 1
+                : hv
+
+            case
+            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
+          color << alpha
+          new(*color.map { |c| c.round(2) })
+        end
+      end
+
+      # Pigment uses sRGB or sRGBA as the default color system
+      # Pigment::Color::RGB is represented as an array of floats, which are ranged from 0.0 to 1.0
+      # @param [Float, Integer] red between 0.0 and 1.0
+      # @param [Float, Integer] green between 0.0 and 1.0
+      # @param [Float, Integer] blue between 0.0 and 1.0
+      # @param [Float, Integer] alpha between 0.0 and 1.0
+      # @return [Pigment::Color::RGB]
+      # @raise [InvalidColorFormatError]
+      def initialize(red, green, blue, alpha = 1.0)
+        @red   = red.to_f.snap
+        @green = green.to_f.snap
+        @blue  = blue.to_f.snap
+        @alpha = alpha.to_f
+
+        color = to_floats(with_alpha: true)
+        raise InvalidColorFormatError, color unless color.all? { |c| c.between?(0.0, 1.0) }
+      end
+
+      # Sums all the two colors components. If any component gets out of the 0 to 1.0 range it gets suppressed.
+      # @param [Pigment::Color] color
+      # @return [Pigment::Color::RGB]
+      # @raise [InvalidColorFormatError]
+      def +(color)
+        raise InvalidColorFormatError, color unless color.is_a?(Pigment::Color)
+        color = color.into(self.class)
+        color = [
+            @red + color.red,
+            @green + color.green,
+            @blue + color.blue
+        ]
+
+        self.class.new(*self.class.suppress(color), @alpha)
+      end
+
+      # Subtracts all the two color components. If any component gets out of the 0 to 1.0 range it gets suppressed.
+      # Tone component will be 0 if it gets lower than 0
+      # @param [Pigment::Color] color
+      # @return [Pigment::Color::RGB]
+      # @raise [InvalidColorFormatError]
+      def -(color)
+        raise InvalidColorFormatError, color unless color.is_a?(Pigment::Color)
+        color = color.into(self.class)
+        self.class.new(*self.class.suppress([
+            @red - color.red,
+            @green - color.green,
+            @blue - color.blue
+        ].map { |c| c >= 0 ? c : 0 }), @alpha)
+      end
+
+      # Multiplies all the color components by n. If any component gets out of the 0 to 1.0 range it gets suppressed.
+      # @param [Numeric] n
+      # @return [Pigment::Color::RGB]
+      def *(n)
+        raise ArgumentError, "Expecting Numeric. Given #{n.class}" unless n.is_a? Numeric
+        n = rgb.map { |c| c * n.to_f }
+        self.class.new(*self.class.suppress(n), @alpha)
+      end
+
+      # Divides all the color components by n. If any component gets out of the 0 to 1.0 range it gets suppressed.
+      # @param [Numeric] n
+      # @return [Pigment::Color::RGB]
+      def /(n)
+        raise ArgumentError, "Expecting Numeric. Given #{n.class}" unless n.is_a? Numeric
+        n =  rgb.map { |c| c / n.to_f }
+        self.class.new(*self.class.suppress(n), @alpha)
+      end
+
+      # Test if two colors are equal
+      # @param [Pigment::Color] other
+      # @return [Boolean]
+      def ==(other)
+        return false unless other.is_a?(Pigment::Color)
+        other = Pigment::Color::RGB.convert(other)
+        other.red.snap       == @red.snap &&
+            other.blue.snap  == @blue.snap &&
+            other.green.snap == @green.snap &&
+            other.alpha.snap == @alpha.snap
+      end
+
+      # @return [Pigment::Color::RGB] the grayscale correspondent of the color
+      def grayscale
+        gray = (@red + @green + @blue) / 3.0
+        self.class.new(gray, gray, gray, @alpha)
+      end
+
+      # @return [Boolean] true if all components are the same, false otherwise
+      def grayscale?
+        @red == @green && @green == @blue
+      end
+
+      # Interpolates two colors. Amount must be an float between -1.0 and 1.0
+      # @param [Pigment::Color] color
+      # @param [Float] amount
+      # @return [Pigment::Color::RGB]
+      # @raise [InvalidColorFormatError]
+      def interpolate(color, amount = 0.5)
+        raise InvalidColorFormatError, color unless color.is_a?(Pigment::Color)
+        raise ArgumentError, "Amount must be an float between -1.0 and 1.0, got #{amount}" unless (-1.0..1.0).include?(amount)
+        color = color.into(Pigment::Color::RGB)
+        n = [rgb, color.rgb].transpose.map! { |c, d| c + amount * (d - c) }
+        self.class.new(*self.class.suppress(n))
+      end
+
+      # @return [RGB] the Invert color
+      def inverse
+        self.class.new(*rgb.map { |c| 1.0 - c }, @alpha)
+      end
+
+
+      # @return [Array<Pigment::Color>] An array of the triadic colors from self
+      def triadic
+        [self.class.new(@blue, @red, @green, @alpha), self.class.new(@green, @blue, @red, @alpha)]
+      end
+
+      # @param [Boolean] with_alpha
+      # @return [Array<Float>] an array of the color components. Alpha value is passed as well if with_alpha is set to true.
+      def to_a(with_alpha: true)
+        with_alpha ? [@red, @green, @blue, @alpha] : [@red, @green, @blue]
+      end
+
+      # @param [Boolean] with_alpha
+      # @return [Array<Integer>] an array of the color components. Alpha value is passed as well if with_alpha is set to true.
+      def to_ints(with_alpha: true)
+        to_a(with_alpha: with_alpha).map { |v| (v * 255).to_i }
+      end
+
+      # @param [Boolean] with_alpha
+      # @return [String] an hexadecimal representation of the color components. Alpha value is passed as well if
+      #   with_alpha is set to true.
+      def to_hex(with_alpha: true)
+        to_ints(with_alpha: with_alpha).map { |v| '%02x' % v }.join
+      end
+
+      # @return [Array<Float>] an array with the red, green and blue color components
+      def rgb
+        to_a(with_alpha: false)
+      end
+
+      # @return [String] the string representation of a hsl color
+      def to_s
+        "RGB Color(red: #{red}, green: #{green}, blue: #{blue}, alpha: #{alpha})"
+      end
+
+      alias_method :mix,  :interpolate
+      alias_method :r,    :red
+      alias_method :g,    :green
+      alias_method :b,    :blue
+      alias_method :a,    :alpha
+      alias_method :rgba, :to_a
+
+      include Pigment::Color
+
+      private
+      # @return [Array<Float>] an array with the respective rgba components
+      def method_missing(method, *args)
+        return super unless method =~ /^[abgr]+$/ && args.empty?
+        method.size.times.map{ |i| send(method[i]) }
+      end
+    end
+  end
+end