Graphic...ce::Hub(3)

💖 Graphics::Toolkit::Color::Space::Hub 💖

okay bestie, this is the manual page for Graphics::Toolkit::Color::Space::Hub — a Perl module, straight out of the User Contributed Perl Documentation collection. Buckle up, we're going in. 🎀

---

✨ NAME ✨

Graphics::Toolkit::Color::Space::Hub — the (de-)convert and deformat color value tuple central, basically. 💅

It's the whole "take a tuple of color numbers, turn it into another space, and also un-format a string back into numbers" situation. Slay.

---

🌈 SYNOPSIS 🌈

This is the main-character store for every color space object — they hold the space-specific info and the algorithms. And it's also home to all the methods that have to loop over every single color space, one by one. 🦋

use Graphics::Toolkit::Color::Space::Hub;
my $true = Graphics::Toolkit::Color::Space::Hub::is_space( 'HSL' );
my $HSL = Graphics::Toolkit::Color::Space::Hub::get_space( 'HSL');
my $RGB = Graphics::Toolkit::Color::Space::Hub::default_space();

Graphics::Toolkit::Color::Space::Hub::space_names();     # all space names and aliases

$HSL->normalize([240,100, 0]);         # 2/3, 1, 0
$HSL->convert([240, 100, 0], 'RGB');   #   0, 0, 1
$HSL->deconvert([0, 0, 1], 'RGB');     # 2/3, 1, 0
$RGB->denormalize([0, 0, 1]);          #   0, 0, 255
$RGB->format([0, 0, 255], 'hex');      #   '#0000ff'

# [0, 0, 255] , 'RGB'
my ($values, $space_name) = Graphics::Toolkit::Color::Space::Hub::deformat( '#0000ff' );

look at her go ✨ converting, deconverting, normalizing, denormalizing, formatting, deformatting — she does it all, no cap.

---

🫶 DESCRIPTION 🫶

Real talk: this module is meant to be used internally only, not directly by you, bestie — unless you wanna add your own color space, in which case go off, queen. 👑

So because of that, it exports no symbols, and its methods are much less DWIM than the main module. Like, don't expect her to read your mind — she's not doing that here. 🙈

But the good news?? A whole lot of important documentation is still right here, so you're not stranded. 💖

periodt. more parts coming, don't go anywhere — we're just getting started. 🦋

🎨 COLOR SPACES 🎨

okay so up next, bestie: a listing of all supported color spaces. These are mathematical constructs that associate each color with a point inside this space. The numerical values of a color definition become coordinates along axis that express different properties. The closer two colors are along an axis, the more similar are they in that property. All color spaces are finite and only certain value ranges along an axis are acceptable. Most spaces have 3 dimensions (axis) and are completely lineary like in Euclidean (everyday) geometry. A few spaces have more axis and some spaces are cylindrical. That means that some axis are not lines but circles and the associated value descibes an angle.

Color definitions contain either the name of a space or the names of its axis (long or short). If the space name or its long alias is used, the values have to be provided in the same order as the axis described here.

Color space or axis names may be written in any combination of upper and lower case characters, but I recommended to use the spelling presented here. Each axis has also two specific names, one long and one short, which are in rare cases equal. To define a color according a space you need to provide for each axis one value, that is inside the required value range and of a specificed type (int or real with amount of decimals).

While I acknowledge that some of the spaces below should be called systems to be technically correct, they still will be called spaces here, because the main goal of this software is seamless interoperabilitiy between them.

🌈 RGB 🌈

... is the default color space of this CPAN module. It is used by most computer hardware like monitors and follows the logic of additive color mixing as produced by an overlay of three colored light beams. The sum of all colors will be white, as in opposite to subtractive mixing. Its is a completely Cartesian (Euclidean) 3D space and thus a RGB tuple consists of three integer values:

• red (short r) range: 0 .. 255
• green (short g) range: 0 .. 255
• blue (short b) range: 0 .. 255

A higher value means a stronger beam of that base color flows into the mix above a black background, so that black is (0,0,0), white (255,255,255) and a pure red (fully saturated color) is (255, 0, 0).

🖨️ CMY 🖨️

is the opposite of RGB since it follows the logic of subtractive color mixing as used in printing. Think of it as the amount of colored ink on white paper, so that white is (0,0,0) and black (1,1,1). It uses normalized real value ranges: 0 .. 1. An CMY tuple has also three values:

• cyan (short c) is the inverse of red
• magenta (short m) is inverse to green
• yellow (short y) is inverse of blue

🖤 CMYK 🖤

is an extension of CMY with a fourth value named key (short k), which is the amount of black ink mixed into the CMY color. It also has an normalized range of 0 .. 1. This should not bother you since you are free to change the range at you preference.

🌈 HSL 🌈

.. is a cylindrical space that orders colors along cognitive properties. The first dimension is the angular one and it rotates in 360 degrees around the rainbow of fully saturated colors: 0 = red, 15 approximates orange, 60 - yellow 120 - green, 180 - cyan, 240 - blue, 270 - violet, 300 - magenta, 330 - pink. 0 and 360 points to the same coordinate. This module only outputs 0, even if accepting 360 as input. Thes second, linear dimension (axis) measures the distance between a point the the center column of the cylinder at the same height, no matter in which direction. The center column has the value 0 (white .. gray .. black) and the outer mantle of the cylinder contains the most saturated, purest colors. The third, vertical axis reaches from bottom value 0 (always black no matter the other values) to 100 (always white no matter the other values). In summary: HSL needs three integer values: hue (short h) (0 .. 359), saturation (short s) (0 .. 100) and lightness (short l) (0 .. 100).

🎨 HSV 🎨

... is also cylindrical but can be shaped like a cone. Similar to HSL we have hue and saturation, but the third axis is named value (short v). In HSL we always get white, when lightness is 100. In HSV additionally saturation has to be zero to get white. When saturation is 100 and value is 100 we have the purest, most sturated color of whatever hue sets. So unlike in HSL, here every color has its unique coordinates.

🌟 HSB 🌟

Is an alias to HSV, just the value axis is renamed with brightness (b).

🤍 HWB 🤍

An inverted HSV, where the saturated, pure colors are on the center column of the cylinder. It still has the same circular hue dimension with an integer range of 0 .. 360. The other two, linear dimensions (also 0 .. 100 inter range with optional suffix '%') are whiteness (w) and blackness (b). They desribe how much white or black are mixed into the pure hue. If both are zero, than we have a pure color. whiteness of 100 always leads to white and blackness of 100 always leads to black. The space is truncated as a cone so the sum of whiteness and blackness can never be greater than 100.

🌈 NCol 🌈

Is a more human readable variant of the HWB space with an altered hue values, that consists of a letter and two digits. The letter demarks one of the six areas around the rainbow. R is Red, Y (Yellow), G (Green), C (Cyan), B (Blue), M (Magenta). The two digits after this letter are an angular value, measuring the distance between the pure color (as stated by the letter) and the described color (toward the next color on the rainbow). The whiteness and blackness axis have integer values with the suffix '%', since they are percentual values as well.

📺 YIQ 📺

Is a space developed for NTSC to broadcast a colored television signal, which is still compatible with black and white TV. It achieves this by sending the luminance (short y) (sort of brightness with real range of 0 .. 1) in channel number one, which is all black and white TV needs. Additionally we have the axis of in-phase (short i) (cyan - orange - balance, range -0.5959 .. 0.5959) and quadrature (short q) (magenta - green - balance, range: -0.5227 .. 0.5227).

🎥 YUV 🎥

Is a slightly altered version of YIQ for the PAL TV standard. We use a variant called YPbPr, which can also be used as space name. It has computation friendly value ranges and is still relevant in video and image formats and compression algorithms, but under the name YCbCr. The only difference is that YCbCr works with digital values but this module computes with real (analogue) value to enable any precision the user might prefer. To make this clear, this space holds the name YPbPr. It has three Cartesian axis: 1. luma (short y) with a real value range of 0..1, 2. Pb (short u, -0.5 .. 0.5) and 3. Pr (short v, -0.5 .. 0.5). (see also CIELUV)

🌈 CIEXYZ 🌈

this space (alias XYZ) has the axis X, Y and Z (long and short names are same this time), that refer to the red, green and blue receptors (cones) in the retina (on the back side of the eye). Because those cones measure a lot more left and right than just exactly those colors, they got these technical names. The values in that space tell you about the amount of chemical and neurological activity a color produces inside the eye. The values range of X, Y and Z go from zero to to 0.95047, 1 and 1.08883 respectively. These values are due to the use of the standard luminant D65, which holds true for all CIE spaces in GTC.

🧪 CIELAB 🧪

(alias LAB) is a derivate of CIEXYZ that reorderes the colors along axis that reflect how the brain processes them. It uses three information channels. One named L (lightness) with a real value range of (0 .. 100). Second is channel (a, that reaches from red to green (-500 .. 500) and thirdly b from yellow to blue (-200 .. 200). Values will be displayed with three decimals. The long names of the axis names contain a '*' and are thus: L*, a* and b*. The a and b axis reflect the opponent color theory.

🧪 CIELUV 🧪

(alias LUV) is a more perceptually uniform version of CIELAB and the axis a and b got renamed to u and v (see YUV) but did not change their meaning. It has also three Cartesian dimension named L*, u* and v*, (short names have only the first letter of these names). Their have real valued ranges, which are 0 .. 100, -134 .. 220 and -140 .. 122.

🌀 CIELCHab 🌀

(alias LCH) is the cylindrical version of the CIELAB with the dimensions luminance, chroma and hue - in short l, c and h. The real valued ranges are from zero to 100, 539 and 360 respectively. Like with the HSL and HSV, hue is the circular dimensions and its values are meant as degrees in a circle. For gray colors in the middle column the value chroma has no importance and will be in this implementation implementation alsway be zero.

🌀 CIELCHuv 🌀

(alias LCHuv) is the cylindrical version of the CIELUV and works similar to CIELCHab except the real valued range of chroma is (0 .. 261) and the space has no alias name.

🌟 OKLAB 🌟

is a modern improvement of CIELAB by Bjoern Ottosson with no alias name and for nicer color transitions and better numeric behaviour. The axis long names are same as the same ones: L with values (0 .. 1), a and b with both (-0.5 .. 0.5). If you want to use it like in CSS, just add "range => [100, [-120,120], [-120,120]], suffix => '%'".

🌈 OKLCH 🌈

is the cylindrical variant of OKLAB just parallels CIELCHab. The axis names are again: luminance, chroma and hue - in short: l, c and h. Value ranges are similar as in OKLAB: luminance 0 .. 1 (normal), chroma 0 .. 0.5 I and <hue> are angles of 0 .. 360 degrees. Also if you prefer a CSS compatible format, use "range => [100, 120, 360]" and a preferred suffix.

🧪 HunterLAB 🧪

predecessor of CIELAB by Richard S. Hunter with no alias name and slightly different color transitions on yellow-blue-direction. The axis have same long and short names: L with normal values (0 .. 1), a -172.30 .. 172.30 and b -67.20 .. 67.20.

📏 RANGES 📏

As pointed out in the previous paragraph, each dimension of color space has its default range. However, one can demand custom value ranges, if the method accepts a range decriptor as argument. If so, the following values are accepted:

'normal'          real value range from 0 ..   1 (default)
'percent'         real value range from 0 .. 100
 number           integer range from zero to that number
[0 1]             real number range from 0 to 1, same as 'normal'
[min max]         range from min .. max, int if both numbers are int
[min max 'int']   integer range from min .. max
[min max 'real']  real number range from min .. max

The whole definition has to be an ARRAY ref. Each element is the range definition of one dimension. If the definition is not an ARRAY but a single value it is applied as definition of every dimension.

✨ FORMATS ✨

Unless it says otherwise, bestie, all of these formats work in every color space. Every. Single. One. 💅

🎀 list

A list of values, where the first one is the name of the color space. You can totally skip the name if it's the default color space ("RGB"). This is the default format of the output method values.

(10, 20, 30)
('XYZ', 15, 3.53, 37.1)

🎀 named_array

Same thing but with squared brackets around it. iconic.

[RGB => 10, 20, 30]

🎀 named_string

Same, but wrapped in quotes.

'RGB: 10, 20, 30'

🎀 css_string

Strings for usage in CSS, SVG files and alike. Here commas are optional. There are two spots where a space is not allowed: 1. between the space name and the opening bracket, and 2. between an axis value and its value suffix (that's the '%' here). 🫶

'rgb(10, 20, 30)'
'hsl(10  20%  30%)'

🎀 hex_string

String for websites and alike, RGB only. Long and short form can be read, but the output is long form only. no cap.

'#1020FF'
'#12F'

🎀 hash

Hash reference with long axis names.

{ red => 10, green => 20, blue => 30 }

🎀 char_hash

Hash reference with short axis names.

{ r => 10, g => 20, b => 30 }

---

🌈 ROUTINES 🌈

This package provides two sets of routines. The first one is just a lookup of what color space objects are available, what the names are, and to retrieve a color space object. The second set consists of 4 routines that can handle a lot of unknowns. They are:

1. convert — (RGB -> any)
2. deconvert — (any -> RGB)
3. deformat — (extract values)
4. deformat_partial_hash — (deformat hashes with missing axis)

not me listing "3" twice in the original, but here we are, we fixed the numbering bestie, the content is all here 💖

🌸 space_names

Returns a list of string values, which are the names of all available color spaces. See "COLOR-SPACES".

🌸 is_space

Needs one argument, which is supposed to be a color space name. If it is, the result is a 1, otherwise 0 (perlish pseudo boolean). vibe check passed or not. ✨

🌸 get_space

Needs one argument, which is supposed to be a color space name. If it is, the result is the according color space object, otherwise undef. 😭

🌸 try_get_space

Same thing, but if nothing is provided it returns the default space.

🌸 default_space

Returns the color space object of (currently) the RGB name space. This name space is special, since every color space object provides converters from and to RGB, but the RGB itself has no converter. main character behavior, honestly. 👑

🌸 convert

Converts a value vector (first argument) from the base space (RGB) into any space mentioned space (second argument — see "COLOR-SPACES"). The values have to be normalized (inside 0..1). If they are outside the acceptable range, they will be clamped, so that the result will also be normal. If the third argument is positive, the output will also be normal. Arguments four and five are for internal use to omit rounding errors. It's the original values and their color space. So when during the conversion, the method tries to convert into the space of the original, it replaces the values with them.

# convert from RGB to  HSL
my @hsl = Graphics::Toolkit::Color::Space::Hub::convert( [0.1, 0.5, .7], 'HSL' );

🌸 deconvert

Converts the result of "deformat" into a RGB value tuple.

# convert from HSL to RGB
my @rgb = Graphics::Toolkit::Color::Space::Hub::deconvert( [0.9, 0.5, 0.5], 'HSL' );

🌸 deformat

Extracts the values of a color definition in any space or format. That's why it takes only one argument, a scalar that can be a string, ARRAY ref or HASH ref. The result will be three values. The first is an ARRAY (tuple) with all the unaltered, not clamped and not rounded and not normalized values. The second is the name of the recognized color name space. Third is the format name.

my ($values, $space) =  Graphics::Toolkit::Color::Space::Hub::deformat( 'ff00a0' );
# [255, 10 , 0], 'RGB'
($values, $space) =  Graphics::Toolkit::Color::Space::Hub::deformat( [255, 10 , 0] ); # same result

🌸 deformat_partial_hash

This is a special case of the deformat routine for the hash and char_hash format (see /FORMATS). It can tolerate missing values. The result will also be a tuple (ARRAY) with missing values being undef. Since there is a given search order, a hash with only a hue value will always assume a HSL space. To change that you can provide the space name as a second, optional argument. 🦋

---

💜 SEE ALSO 💜

• Convert::Color

---

📜 COPYRIGHT & LICENSE 📜

Copyright 2023-25 Herbert Breunung.

This program is free software; you can redistribute it and/or modify it under same terms as Perl itself.

---

👑 AUTHOR 👑

Herbert Breunung, <lichtkind@cpan.org>

---

okay bestie that's the whole thing, we made it to the end 🎀✨ this page is from perl v5.42.0, dated 2026-01-17, and it's the Graphic...ce::Hub(3) page from the User Contributed Perl Documentation. slay, go convert some colors, you got this 💖🌸🫶