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

💖 Conver...or::HSV(3pm) 💖

okay bestie, gather round, because we're about to talk about Convert::Color::HSV — it's from the User Contributed Perl Documentation and it is literally the moment. this is the manual page for representing a color as hue/saturation/value and honestly? it ate. 🎀

---

✨ NAME ✨

Convert::Color::HSV — a color value represented as hue/saturation/value 🦋

---

✨ SYNOPSIS ✨

bestie you can go in directly:

use Convert::Color::HSV;

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

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

or you can come through via Convert::Color like the main character:

use Convert::Color;

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

---

✨ DESCRIPTION ✨

so. objects in this class represent a color in HSV space, as a set of three floating-point values. no cap.

• Hue is stored as a value in degrees, in the range 0 to 360 (exclusive).
• Saturation and value are in the range 0 to 1.

ngl the way to picture this color space is as a cylinder — height and radius of 1. the hue is the angle around the axis, the saturation is the distance from the axis, and the value is the height above the base. 💅

so in this cylinder shape:

• the entire base of the cylinder? pure black. 💀
• the axis through the centre? the whole range of greys. 🩶
• the circumference of the top? the pure-saturated color wheel, with a pure white point at its centre. ⭐

and because that entire bottom surface is just black, you can make a closely-related color space by reshaping the cylinder into a cone — contract the base of the cylinder into a single point. the radius from the axis is called the chroma (though fair warning bestie, this is a different definition of "chroma" than the one CIE uses, so don't @ me).

---

✨ CONSTRUCTOR ✨

🧚 new

$color = Convert::Color::HSV->new( $hue, $saturation, $value );

returns a brand new object representing the set of values you gave it. the hue should be in the range 0 to 360 (exclusive), and saturation and value should be between 0 and 1. values outside of these ranges will be clamped (the code is not about to let you be messy like that).

---

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

this version parses $string for values, and constructs a new object just like the three-argument form above. the string should be in the form

hue,saturation,value

containing the three floating-point values in decimal notation. periodt. 🫶

---

✨ METHODS ✨

🌸 hue

$h = $color->hue;

🌸 saturation

$s = $color->saturation;

🌸 value

$v = $color->value;

accessors for the three components of the color. that's it, that's the vibe. 👑

---

🌈 chroma

$c = $color->chroma;

returns the derived property of "chroma", which maps the color space onto a cone instead of a cylinder. this more closely measures the intuitive concept of how "colorful" the color is than the saturation value does, and it's useful for distance calculations. iykyk. ✨

---

🌈 hsv

( $hue, $saturation, $value ) = $color->hsv;

returns the individual hue, saturation and value components of the color value. three-for-one, slay.

---

💫 dst_hsv

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

returns a measure of the distance between the two colors. this is the Euclidean distance between the two colors as points in the chroma-adjusted cone space. math but make it fashion. 📐

---

💫 dst_hsv_cheap

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

returns a measure of the distance between the two colors. this one is used in the calculation of "dst_hsv", but since it omits the final square-root and scaling it's cheaper to calculate — ideal for cases where only the relative values matter, like when you're picking the "best match" out of a set of colors.

it ranges between 0 for identical colors and 4 for the distance between complementary pure-saturated colors. iconic range, honestly. 🍓

---

✨ 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 was perl v5.40.0, dated 2024-09-16, and like all good things it's filed under Conver...or::HSV(3pm). go forth and pick your colors, you absolute legend. 💖✨🎀🦋