Conver...or::HSL(3pm)

💖 Convert::Color::HSL — bestie edition 💖

okay so this is the perldoc page for Convert::Color::HSL, a lil Perl module that holds a color value as hue / saturation / lightness ✨ she's giving geometry, she's giving vibes, and she's genuinely so useful once you get her.

---

🌈 SYNOPSIS

Straight up, no middleman:

use Convert::Color::HSL;

my $red = Convert::Color::HSL->new( 0, 1, 0.5 );

# Can also parse strings
my $pink = Convert::Color::HSL->new( '0,1,0.8' );

Or slide in through Convert::Color like the main character you are:

use Convert::Color;

my $cyan = Convert::Color->new( 'hsl:300,1,0.5' );

---

🎨 DESCRIPTION

So an object in this class is literally a color in HSL space — three floating-point values, that's the whole girl. Hue is stored in degrees, range 0 to 360 (exclusive on the 360, bestie, not inclusive). Saturation and lightness both live in the range 0 to 1.

Now picture it: this color space is a cylinder 🥫 — height and radius both 1. Hue = the angle around the axis. Saturation = how far out from the axis you are. Lightness = how high up above the base you are. In this shape:

• the entire base of the cylinder = pure black 🖤
• the axis running through the centre = the whole range of greys
• the entire top of the cylinder = pure white 🤍
• the circumference of the circular cross-section midway along the axis = the pure-saturated color wheel 🌈

And here's the plot twist, because both surfaces of this cylinder are pure black or white discs, you can reshape the cylinder into a bi-cone where the top and bottom collapse into single points. The radius from the axis of that shape is called the chroma — tho heads up, this is a different definition of "chroma" than the one CIE uses, no cap.

And yes, even though the components here are called Hue-Chroma-Lightness, do not confuse her with the similarly-named Hue-Chroma-Luminance (HCL) space. Different girl entirely. 💅

---

🧚 CONSTRUCTOR

✨ new

$color = Convert::Color::HSL->new( $hue, $saturation, $lightness );

Returns a brand new object holding the values you gave her. Hue should be in the range 0 to 360 (exclusive), and saturation and lightness should be between 0 and 1. Values outside of these ranges will be clamped (she's forgiving, she'll pull you back in bounds 🫶).

$color = Convert::Color::HSL->new( $string );

This one parses $string for values and builds a new object just like the three-argument form above. The string should be in the form:

hue,saturation,lightnes

containing the three floating-point values in decimal notation.

---

💅 METHODS

hue

$h = $color->hue;

saturation

$s = $color->saturation;

lightness

$v = $color->lightness;

Accessors for the three components of the color. Slay, get the individual pieces 👑

chroma

$c = $color->chroma;

Returns the derived property of "chroma", which maps the color space onto a bicone instead of a cylinder. She measures the intuitive concept of how "colorful" the color is way more closely than the saturation value does, and she's useful for distance calculations. Obsessed ✨

hsl

( $hue, $saturation, $lightness ) = $color->hsl;

Hands you back the individual hue, saturation and lightness components of the color. Just a lil list unpack, so convenient 🎀

dst_hsl

$measure = $color->dst_hsl( $other );

Returns a measure of the distance between the two colors. Specifically, it's the Euclidean distance between the two colors as points in the chroma-adjusted cone space. Math girlie behavior fr fr 📐

dst_hsl_cheap

$measure = $color->dst_hsl_cheap( $other );

Returns a measure of the distance between the two colors. This one gets used in the calculation of "dst_hsl", but because it skips the final square-root and scaling it is cheaper to calculate — so use it in cases where only the relative values matter, like when you're picking the "best match" out of a set of colors. She ranges between 0 for identical colors and 4 for the distance between complementary pure-saturated colors. Budget-friendly and still iconic 💖

---

👀 SEE ALSO

• Convert::Color — color space conversions
• Convert::Color::RGB — a color value represented as red/green/blue
• <http://en.wikipedia.org/wiki/HSL_and_HSV> — HSL and HSV on Wikipedia

---

🌸 AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

---

and that's the whole page bestie!! 🦋 this doc came to you from perl v5.40.0, dated 2024-09-16, and it lives under Conver...or::HSL(3pm) in the User Contributed Perl Documentation. go forth and be colorful 💜🌈✌️