Module: Color

Included in:
CMYK, GrayScale, HSL, RGB, YIQ
Defined in:
lib/atome/utilities/color_helper/color.rb

Overview

Colour Management with Ruby

Defined Under Namespace

Modules: CSS, Palette Classes: CMYK, GrayScale, HSL, RGB, YIQ

Constant Summary collapse

COLOR_VERSION = 
'1.8'
COLOR_EPSILON =

The maximum “resolution” for colour math; if any value is less than or equal to this value, it is treated as zero.

1e-5
COLOR_TOLERANCE =

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.

1e-4
GreyScale =

A synonym for Color::GrayScale.

Color::GrayScale

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.coerce(a, b) ⇒ Object

Coerces, if possible, the second given colour object to the first given colour object type. This will probably involve colour conversion and therefore a loss of fidelity.



100
101
102
 
# File 'lib/atome/utilities/color_helper/color.rb', line 100

def coerce(a, b)
  a.coerce(b)
end

.const_missing(name) ⇒ Object 



158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/atome/utilities/color_helper/color.rb', line 158

def const_missing(name)
  #:nodoc:
  case name
  when "VERSION", :VERSION, "COLOR_TOOLS_VERSION", :COLOR_TOOLS_VERSION
    warn "Color::#{name} has been deprecated. Use Color::COLOR_VERSION instead."
    Color::COLOR_VERSION
  else
    if Color::RGB.const_defined?(name)
      warn "Color::#{name} has been deprecated. Use Color::RGB::#{name} instead."
      Color::RGB.const_get(name)
    else
      super
    end
  end
end

.equivalent?(a, b) ⇒ Boolean

Returns true if the two colours are roughly equivalent. If colour conversions are required, this all conversions will be implemented using the default conversion mechanism.

Returns:

  • (Boolean) 


92
93
94
95
 
# File 'lib/atome/utilities/color_helper/color.rb', line 92

def equivalent?(a, b)
  return false unless a.kind_of?(Color) && b.kind_of?(Color)
  a.to_a.zip(a.coerce(b).to_a).all? { |(x, y)| near?(x, y) }
end

.near?(x, y) ⇒ Boolean

Returns true if the two values provided are near each other.

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/atome/utilities/color_helper/color.rb', line 85

def near?(x, y)
  (x - y).abs <= Color::COLOR_TOLERANCE
end

.near_one?(value) ⇒ Boolean

Returns true if the value is within COLOR_EPSILON of one.

Returns:

  • (Boolean) 


74
75
76
 
# File 'lib/atome/utilities/color_helper/color.rb', line 74

def near_one?(value)
  near_zero?(value - 1.0)
end

.near_one_or_more?(value) ⇒ Boolean

Returns true if the value is within COLOR_EPSILON of one or more than one.

Returns:

  • (Boolean) 


80
81
82
 
# File 'lib/atome/utilities/color_helper/color.rb', line 80

def near_one_or_more?(value)
  (value > 1.0 or near_one?(value))
end

.near_zero?(value) ⇒ Boolean

Returns true if the value is less than COLOR_EPSILON.

Returns:

  • (Boolean) 


63
64
65
 
# File 'lib/atome/utilities/color_helper/color.rb', line 63

def near_zero?(value)
  (value.abs <= Color::COLOR_EPSILON)
end

.near_zero_or_less?(value) ⇒ Boolean

Returns true if the value is within COLOR_EPSILON of zero or less than zero.

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/atome/utilities/color_helper/color.rb', line 69

def near_zero_or_less?(value)
  (value < 0.0 or near_zero?(value))
end

.new(values, mode = :rgb) ⇒ Object

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 (a module). This “constructor” will be removed in the future.

mode = :hsl

values must be an array of [ hue deg, sat %, lum % ]. A Color::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 Color::RGB object will be created.

mode = :cmyk

values must be an array of [ cyan %, magenta %, yellow %, black % ]. A Color::CMYK object will be created.



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/atome/utilities/color_helper/color.rb', line 185

def new(values, mode = :rgb)
  warn "Color.new has been deprecated. Use Color::#{mode.to_s.upcase}.new instead."
  color = case mode
          when :hsl
            Color::HSL.new(*values)
          when :rgb
            values = [values].flatten
            if values.size == 1
              Color::RGB.from_html(*values)
            else
              Color::RGB.new(*values)
            end
          when :cmyk
            Color::CMYK.new(*values)
          end
  color.to_hsl
end

.normalize(value) ⇒ Object Also known as: normalize_fractional

Normalizes the value to the range (0.0) .. (1.0).



105
106
107
108
109
110
111
112
113
 
# File 'lib/atome/utilities/color_helper/color.rb', line 105

def normalize(value)
  if near_zero_or_less? value
    0.0
  elsif near_one_or_more? value
    1.0
  else
    value
  end
end

.normalize_byte(value) ⇒ Object Also known as: normalize_8bit

Normalize the value to the range (0) .. (255).



131
132
133
 
# File 'lib/atome/utilities/color_helper/color.rb', line 131

def normalize_byte(value)
  normalize_to_range(value, 0..255).to_i
end

.normalize_to_range(value, range) ⇒ Object

Normalizes the value to the specified range.



118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/atome/utilities/color_helper/color.rb', line 118

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_word(value) ⇒ Object Also known as: normalize_16bit

Normalize the value to the range (0) .. (65535).



138
139
140
 
# File 'lib/atome/utilities/color_helper/color.rb', line 138

def normalize_word(value)
  normalize_to_range(value, 0..65535).to_i
end

Instance Method Details

#==(other) ⇒ Object

Compares the other colour to this one. The other colour will be coerced to the same type as the current colour. Such converted colour comparisons will always be more approximate than non-converted comparisons.

If the other colour cannot be coerced to the current colour class, a NoMethodError exception will be raised.

All values are compared as floating-point values, so two colours will be reported equivalent if all component values are within COLOR_TOLERANCE of each other.



38
39
40
 
# File 'lib/atome/utilities/color_helper/color.rb', line 38

def ==(other)
  Color.equivalent?(self, other)
end

#name ⇒ Object

The primary name for the colour.



43
44
45
 
# File 'lib/atome/utilities/color_helper/color.rb', line 43

def name
  names.first
end

#names ⇒ Object

All names for the colour.



48
49
50
51
 
# File 'lib/atome/utilities/color_helper/color.rb', line 48

def names
  self.names = nil unless defined? @names
  @names
end

#names=(n) ⇒ Object Also known as: name= 



53
54
55
56
 
# File 'lib/atome/utilities/color_helper/color.rb', line 53

def names=(n)
  # :nodoc:
  @names = Array(n).flatten.compact.map(&:to_s).map(&:downcase).sort.uniq
end