Convert::Color::HSL(3pm)

1Convert::Color::HSL(3pmU)ser Contributed Perl DocumentatiCoonnvert::Color::HSL(3pm)
2
3
4

NAME

6       "Convert::Color::HSL" - a color value represented as
7       hue/saturation/lightness
8

SYNOPSIS

10       Directly:
11
12          use Convert::Color::HSL;
13
14          my $red = Convert::Color::HSL->new( 0, 1, 0.5 );
15
16          # Can also parse strings
17          my $pink = Convert::Color::HSL->new( '0,1,0.8' );
18
19       Via Convert::Color:
20
21          use Convert::Color;
22
23          my $cyan = Convert::Color->new( 'hsl:300,1,0.5' );
24

DESCRIPTION

26       Objects in this class represent a color in HSL space, as a set of three
27       floating-point values. Hue is stored as a value in degrees, in the
28       range 0 to 360 (exclusive). Saturation and lightness are in the range 0
29       to 1.
30
31       This color space may be considered as a cylinder, of height and radius
32       1. Hue represents the position of the color as the angle around the
33       axis, the saturation as the distance from the axis, and the lightness
34       the height above the base. In this shape, the entire base of the
35       cylinder is pure black, the axis through the centre represents the
36       range of greys, and the entire top of the cylinder is pure white. The
37       circumference of the circular cross-section midway along the axis
38       contains the pure-saturated color wheel.
39
40       Because both surfaces of this cylinder contain pure black or white
41       discs, a closely-related color space can be created by reshaping the
42       cylinder into a bi-cone such that the top and bottom of the cylinder
43       become single points. The radius from the axis of this shape is called
44       the chroma (though this is a different definition of "chroma" than that
45       used by CIE).
46
47       While the components of this space are called Hue-Chroma-Lightness, it
48       should not be confused with the similarly-named Hue-Chroma-Luminance
49       (HCL) space.
50

CONSTRUCTOR

52   new
53          $color = Convert::Color::HSL->new( $hue, $saturation, $lightness )
54
55       Returns a new object to represent the set of values given. The hue
56       should be in the range 0 to 360 (exclusive), and saturation and
57       lightness should be between 0 and 1. Values outside of these ranges
58       will be clamped.
59
60          $color = Convert::Color::HSL->new( $string )
61
62       Parses $string for values, and construct a new object similar to the
63       above three-argument form. The string should be in the form
64
65          hue,saturation,lightnes
66
67       containing the three floating-point values in decimal notation.
68

METHODS

70   hue
71          $h = $color->hue
72
73   saturation
74          $s = $color->saturation
75
76   lightness
77          $v = $color->lightness
78
79       Accessors for the three components of the color.
80
81   chroma
82          $c = $color->chroma
83
84       Returns the derived property of "chroma", which maps the color space
85       onto a bicone instead of a cylinder. This more closely measures the
86       intuitive concept of how "colorful" the color is than the saturation
87       value and is useful for distance calculations.
88
89   hsl
90          ( $hue, $saturation, $lightness ) = $color->hsl
91
92       Returns the individual hue, saturation and lightness components of the
93       color value.
94
95   dst_hsl
96          $measure = $color->dst_hsl( $other )
97
98       Returns a measure of the distance between the two colors. This is the
99       Euclidean distance between the two colors as points in the chroma-
100       adjusted cone space.
101
102   dst_hsl_cheap
103          $measure = $color->dst_hsl_cheap( $other )
104
105       Returns a measure of the distance between the two colors. This is used
106       in the calculation of "dst_hsl" but since it omits the final square-
107       root and scaling it is cheaper to calculate, for use in cases where
108       only the relative values matter, such as when picking the "best match"
109       out of a set of colors. It ranges between 0 for identical colors and 4
110       for the distance between complementary pure-saturated colors.
111

AUTHOR

121       Paul Evans <leonerd@leonerd.org.uk>
122
123
124
125perl v5.38.0                      2023-07-20          Convert::Color::HSL(3pm)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

METHODS

SEE ALSO

AUTHOR