Class: Color::HSL

Inherits:
Object
  • Object
show all
Includes:
Color
Defined in:
lib/color/hsl.rb,
lib/color.rb

Overview

An HSL colour object. Internally, the hue (#h), saturation (#s), and luminosity/lightness (#l) values are dealt with as fractional values in the range 0..1.

Constant Summary

Constants included from Color

COLOR_EPSILON, COLOR_TOLERANCE, COLOR_VERSION, GreyScale

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Color

#==, coerce, const_missing, equivalent?, #name, #names, #names=, near?, near_one?, near_one_or_more?, near_zero?, near_zero_or_less?, new, normalize, normalize_byte, normalize_to_range, normalize_word

Constructor Details

#initialize(h = 0, s = 0, l = 0, radix1 = 360.0, radix2 = 100.0, &block) ⇒ HSL

Creates an HSL colour object from the standard values of degrees and percentages (e.g., 145 deg, 30%, 50%).



23
24
25
26
27
28
 
# File 'lib/color/hsl.rb', line 23

def initialize(h = 0, s = 0, l = 0, radix1 = 360.0, radix2 = 100.0, &block) # :yields self:
  @h = Color.normalize(h / radix1)
  @s = Color.normalize(s / radix2)
  @l = Color.normalize(l / radix2)
  block.call if block
end

Class Method Details

.from_fraction(h = 0.0, s = 0.0, l = 0.0, &block) ⇒ Object

Creates an HSL colour object from fractional values 0..1.



11
12
13
 
# File 'lib/color/hsl.rb', line 11

def from_fraction(h = 0.0, s = 0.0, l = 0.0, &block)
  new(h, s, l, 1.0, 1.0, &block)
end

Instance Method Details

#brightness ⇒ Object

Returns the luminosity (#l) of the colour.



98
99
100
 
# File 'lib/color/hsl.rb', line 98

def brightness
  @l
end

#coerce(other) ⇒ Object

Coerces the other Color object into HSL.



17
18
19
 
# File 'lib/color/hsl.rb', line 17

def coerce(other)
  other.to_hsl
end

#css_hsl ⇒ Object

Present the colour as an HSL HTML/CSS colour string (e.g., “hsl(180, 25%, 35%)”).



51
52
53
 
# File 'lib/color/hsl.rb', line 51

def css_hsl
  "hsl(%3.2f, %3.2f%%, %3.2f%%)" % [ hue, saturation, luminosity ]
end

#css_hsla ⇒ Object

Present the colour as an HSLA (with alpha) HTML/CSS colour string (e.g., “hsla(180, 25%, 35%, 1)”).



57
58
59
 
# File 'lib/color/hsl.rb', line 57

def css_hsla
  "hsla(%3.2f, %3.2f%%, %3.2f%%, %3.2f)" % [ hue, saturation, luminosity, 1 ]
end

#css_rgb ⇒ Object

Present the colour as an RGB HTML/CSS colour string (e.g., “rgb(0%, 50%, 100%)”). Note that this will perform a #to_rgb operation using the default conversion formula.



38
39
40
 
# File 'lib/color/hsl.rb', line 38

def css_rgb
  to_rgb.css_rgb
end

#css_rgba(alpha = 1) ⇒ Object

Present the colour as an RGBA (with alpha) HTML/CSS colour string (e.g., “rgb(0%, 50%, 100%, 1)”). Note that this will perform a #to_rgb operation using the default conversion formula.



45
46
47
 
# File 'lib/color/hsl.rb', line 45

def css_rgba(alpha = 1)
  to_rgb.css_rgba(alpha)
end

#h ⇒ Object

Returns the hue of the colour in the range 0.0 .. 1.0.



111
112
113
 
# File 'lib/color/hsl.rb', line 111

def h
  @h
end

#h=(hh) ⇒ Object

Sets the hue of the colour in the range 0.0 .. 1.0.



125
126
127
 
# File 'lib/color/hsl.rb', line 125

def h=(hh)
  @h = Color.normalize(hh)
end

#html ⇒ Object

Present the colour as an HTML/CSS colour string.



31
32
33
 
# File 'lib/color/hsl.rb', line 31

def html
  to_rgb.html
end

#hue ⇒ Object

Returns the hue of the colour in degrees.



107
108
109
 
# File 'lib/color/hsl.rb', line 107

def hue
  @h * 360.0
end

#hue=(hh) ⇒ Object

Sets the hue of the colour in degrees. Colour is perceived as a wheel, so values should be set properly even with negative degree values.



116
117
118
119
120
121
122
123
 
# File 'lib/color/hsl.rb', line 116

def hue=(hh)
  hh = hh / 360.0

  hh += 1.0 if hh < 0.0
  hh -= 1.0 if hh > 1.0

  @h = Color.normalize(hh)
end

#inspect ⇒ Object 



168
169
170
 
# File 'lib/color/hsl.rb', line 168

def inspect
  "HSL [%.2f deg, %.2f%%, %.2f%%]" % [ hue, saturation, luminosity ]
end

#l ⇒ Object

Returns the luminosity of the colour in the range 0.0 .. 1.0.



151
152
153
 
# File 'lib/color/hsl.rb', line 151

def l
  @l
end

#l=(ll) ⇒ Object

Sets the luminosity of the colour in the ragne 0.0 .. 1.0.



160
161
162
 
# File 'lib/color/hsl.rb', line 160

def l=(ll)
  @l = Color.normalize(ll)
end

#luminosity ⇒ Object Also known as: lightness

Returns the percentage of luminosity of the colour.



146
147
148
 
# File 'lib/color/hsl.rb', line 146

def luminosity
  @l * 100.0
end

#luminosity=(ll) ⇒ Object Also known as: lightness=

Sets the percentage of luminosity of the colour.



155
156
157
 
# File 'lib/color/hsl.rb', line 155

def luminosity=(ll)
  @l = Color.normalize(ll / 100.0)
end

#mix_with(color, mix_percent = 0.5) ⇒ Object

Mix the mask colour (which will be converted to an HSL colour) with the current colour at the stated mix percentage as a decimal value.

NOTE

This differs from Color::RGB#mix_with.



176
177
178
179
180
181
 
# File 'lib/color/hsl.rb', line 176

def mix_with(color, mix_percent = 0.5)
  v = to_a.zip(coerce(color).to_a).map { |(x, y)|
    ((y - x) * mix_percent) + x
  }
  self.class.from_fraction(*v)
end

#s ⇒ Object

Returns the saturation of the colour in the range 0.0 .. 1.0.



133
134
135
 
# File 'lib/color/hsl.rb', line 133

def s
  @s
end

#s=(ss) ⇒ Object

Sets the saturation of the colour in the ragne 0.0 .. 1.0.



141
142
143
 
# File 'lib/color/hsl.rb', line 141

def s=(ss)
  @s = Color.normalize(ss)
end

#saturation ⇒ Object

Returns the percentage of saturation of the colour.



129
130
131
 
# File 'lib/color/hsl.rb', line 129

def saturation
  @s * 100.0
end

#saturation=(ss) ⇒ Object

Sets the percentage of saturation of the colour.



137
138
139
 
# File 'lib/color/hsl.rb', line 137

def saturation=(ss)
  @s = Color.normalize(ss / 100.0)
end

#to_a ⇒ Object 



183
184
185
 
# File 'lib/color/hsl.rb', line 183

def to_a
  [ h, s, l ]
end

#to_cmyk ⇒ Object

Converts to RGB then CMYK.



93
94
95
 
# File 'lib/color/hsl.rb', line 93

def to_cmyk
  to_rgb.to_cmyk
end

#to_greyscale ⇒ Object Also known as: to_grayscale 



101
102
103
 
# File 'lib/color/hsl.rb', line 101

def to_greyscale
  Color::GrayScale.from_fraction(@l)
end

#to_hsl ⇒ Object 



164
165
166
 
# File 'lib/color/hsl.rb', line 164

def to_hsl
  self
end

#to_rgb ⇒ Object

Converting from HSL to RGB. As with all colour conversions, this is approximate at best. The code here is adapted from fvd and van Dam, originally found at [1] (implemented similarly at [2]).

This simplifies the calculations with the following assumptions:

  • Luminance values <= 0 always translate to Color::RGB::Black.

  • Luminance values >= 1 always translate to Color::RGB::White.

  • Saturation values <= 0 always translate to a shade of gray using luminance as a percentage of gray.

1

bobpowell.net/RGBHSB.aspx

2

support.microsoft.com/kb/29240



73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/color/hsl.rb', line 73

def to_rgb(*)
  if Color.near_zero_or_less?(l)
    Color::RGB::Black
  elsif Color.near_one_or_more?(l)
    Color::RGB::White
  elsif Color.near_zero?(s)
    Color::RGB.from_grayscale_fraction(l)
  else
    # Only needed for Ruby 1.8. For Ruby 1.9+, we can do:
    # Color::RGB.new(*compute_fvd_rgb, 1.0)
    Color::RGB.new(*(compute_fvd_rgb + [ 1.0 ]))
  end
end

#to_yiq ⇒ Object

Converts to RGB then YIQ.



88
89
90
 
# File 'lib/color/hsl.rb', line 88

def to_yiq
  to_rgb.to_yiq
end