Class: Color::HSL

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

Overview

The HSL color model is a cylindrical-coordinate representation of the sRGB color model, standing for hue (measured in degrees on the cylinder), saturation (measured in percentage), and lightness (measured in percentage).

HSL colors are immutable Data class instances. Array deconstruction is ‘[hue, saturation, luminosity]` and hash deconstruction is `hue:, s:, saturation:, l:, luminosity:`. See #h, #hue, #s, #saturation, #l, #luminosity.

Constant Summary

Constants included from Color

EPSILON, TOLERANCE, VERSION

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Color

#==, #components, #css_value, #map, #map_with, normalize, #scale, translate_range, #zip

Constructor Details

#initialize(h:, s:, l:) ⇒ HSL

Creates a HSL color object from fractional values (0.0 .. 1.0).

“‘ruby Color::HSL.from_fraction(0.3, 0.3, 0.5) # => HSL [108deg 30% 50%] Color::HSL.new(h: 0.3, s: 0.3, l: 0.5) # => HSL [108deg 30% 50%] Color::HSL[0.3, 0.3, 0.5] # => HSL [108deg 30% 50%] “`



81
82
83
 
# File 'lib/color/hsl.rb', line 81

def initialize(h:, s:, l:)
  super(h: normalize(h), s: normalize(s), l: normalize(l))
end

Instance Attribute Details

#h ⇒ Object (readonly)

Returns the value of attribute h

Returns:

  • (Object) —

    the current value of h



47
48
49
 
# File 'lib/color.rb', line 47

def h
  @h
end

#l ⇒ Object (readonly)

Returns the value of attribute l

Returns:

  • (Object) —

    the current value of l



47
48
49
 
# File 'lib/color.rb', line 47

def l
  @l
end

#s ⇒ Object (readonly)

Returns the value of attribute s

Returns:

  • (Object) —

    the current value of s



47
48
49
 
# File 'lib/color.rb', line 47

def s
  @s
end

Class Method Details

.from_values(*args, **kwargs) ⇒ Object

Creates a HSL color object from degrees (0.0 .. 360.0) and percentage values (0.0 .. 100.0).

“‘ruby Color::HSL.from_values(145, 30, 50) # => HSL [145deg 30% 50%] Color::HSL.from_values(h: 145, s: 30, l: 50) # => HSL [145deg 30% 50%] “`

:call-seq:

from_values(h, s, l)
from_values(h:, s:, l:)



54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/color/hsl.rb', line 54

def self.from_values(*args, **kwargs)
  h, s, l =
    case [args, kwargs]
    in [[_, _, _], {}]
      args
    in [[], {h:, s:, l:}]
      [h, s, l]
    else
      new(*args, **kwargs)
    end

  new(h: h / 360.0, s: s / 100.0, l: l / 100.0)
end

Instance Method Details

#brightness ⇒ Object

:nodoc:



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

def brightness = l # :nodoc:

#coerce(other) ⇒ Object

Coerces the other Color object into HSL.



87
 
# File 'lib/color/hsl.rb', line 87

def coerce(other) = other.to_hsl

#css(alpha: nil) ⇒ Object

Present the color as a CSS ‘hsl` function with optional `alpha`.

“‘ruby hsl = Color::HSL.from_values(145, 30, 50) hsl.css # => hsl(145deg 30% 50%) hsl.css(alpha: 0.5) # => hsl(145deg 30% 50% / 0.50) “`



148
149
150
151
152
153
154
155
156
157
 
# File 'lib/color/hsl.rb', line 148

def css(alpha: nil)
  params = [
    css_value(hue, :degrees),
    css_value(saturation, :percent),
    css_value(luminosity, :percent)
  ].join(" ")
  params = "#{params} / #{css_value(alpha)}" if alpha

  "hsl(#{params})"
end

#deconstruct_keys(_keys) ⇒ Object

:nodoc:



211
 
# File 'lib/color/hsl.rb', line 211

def deconstruct_keys(_keys) = {h:, s:, l:, hue:, saturation:, luminance:} # :nodoc:

#hue ⇒ Object

:nodoc:



163
 
# File 'lib/color/hsl.rb', line 163

def hue = h * 360.0 # :nodoc:

#inspect ⇒ Object

:nodoc:



175
 
# File 'lib/color/hsl.rb', line 175

def inspect = "HSL [%.2fdeg %.2f%% %.2f%%]" % [hue, saturation, luminosity] # :nodoc:

#luminosity ⇒ Object Also known as: lightness

:nodoc:



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

def luminosity = l * 100.0 # :nodoc:

#mix_with(mask, *args, **kwargs) ⇒ Object

Mix the mask color (which will be converted to a HSL color) with the current color at the stated fractional mix ratio (0.0..1.0).

This implementation differs from Color::RGB#mix_with.

:call-seq:

mix_with(mask, mix_ratio: 0.5)



198
199
200
201
202
 
# File 'lib/color/hsl.rb', line 198

def mix_with(mask, *args, **kwargs)
  mix_ratio = normalize(kwargs[:mix_ratio] || args.first || 0.5)

  map_with(mask) { ((_2 - _1) * mix_ratio) + _1 }
end

#pretty_print(q) ⇒ Object

:nodoc:



178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/color/hsl.rb', line 178

def pretty_print(q) # :nodoc:
  q.text "HSL"
  q.breakable
  q.group 2, "[", "]" do
    q.text "%.2fdeg" % hue
    q.fill_breakable
    q.text "%.2f%%" % saturation
    q.fill_breakable
    q.text "%.2f%%" % luminosity
  end
end

#saturation ⇒ Object

:nodoc:



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

def saturation = s * 100.0 # :nodoc:

#to_a ⇒ Object Also known as: deconstruct

:nodoc:



205
 
# File 'lib/color/hsl.rb', line 205

def to_a = [hue, saturation, luminosity] # :nodoc:

#to_cmyk ⇒ Object

Converts from HSL to Color::CMYK via Color::RGB.



121
 
# File 'lib/color/hsl.rb', line 121

def to_cmyk(...) = to_rgb(...).to_cmyk(...)

#to_grayscale ⇒ Object

Converts from HSL to Color::Grayscale.

Luminance is treated as the Grayscale ratio.



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

def to_grayscale(...) = Color::Grayscale.from_fraction(l)

#to_hsl ⇒ Object 



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

def to_hsl(...) = self

#to_internal ⇒ Object

:nodoc:



214
 
# File 'lib/color/hsl.rb', line 214

def to_internal = [h, s, l] # :nodoc:

#to_lab ⇒ Object

Converts from HSL to Color::CIELAB via Color::RGB.



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

def to_lab(...) = to_rgb(...).to_lab(...)

#to_rgb ⇒ Object

Converts from HSL to Color::RGB.

As with all color conversions, this is an approximation. 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 a black Color::RGB value.

  • Luminance values >= 1 always translate to a white Color::RGB value.

  • 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



103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/color/hsl.rb', line 103

def to_rgb(...)
  if near_zero_or_less?(l)
    Color::RGB::Black000
  elsif near_one_or_more?(l)
    Color::RGB::WhiteFFF
  elsif near_zero?(s)
    Color::RGB.from_fraction(l, l, l)
  else
    Color::RGB.from_fraction(*compute_fvd_rgb)
  end
end

#to_xyz ⇒ Object

Converts from HSL to Color::XYZ via Color::RGB.



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

def to_xyz(...) = to_rgb(...).to_xyz(...)

#to_yiq ⇒ Object

Converts from HSL to Color::YIQ via Color::RGB.



117
 
# File 'lib/color/hsl.rb', line 117

def to_yiq(...) = to_rgb(...).to_yiq(...)