Provided by: libgraphics-toolkit-color-perl_1.71-1_all 
NAME
Graphics::Toolkit::Color::Space::Hub - convert, format and measure color values
SYNOPSIS
Central hub for all color value related math. Can handle vectors of all spaces mentioned
in next paragraph and translates also into and from different formats such as RGB hex
('#AABBCC').
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::base_space();
Graphics::Toolkit::Color::Space::Hub::space_names(); # all space names
$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'
my ($values, $space_name) = Graphics::Toolkit::Color::Space::Hub::deformat( '#0000ff' );
# [0, 0, 255] , 'RGB'
DESCRIPTION
This module is supposed to be used by Graphics::Toolkit::Color and not directly, thus it
exports no symbols and has a much less DWIM API then the main module.
COLOR SPACES
Color space names can be written in any combination of upper and lower case.
RGB
has three integer values: red (0 .. 255), green (0 .. 255) and blue (0 .. 255). All are
scaling from no (0) to very much (255) light of that color, so that (0,0,0) is black,
(255,255,255) is white and (0,0,255) is blue.
CMY
is the inverse of RGB but with the range: 0 .. 1. cyan is the inverse value of red,
magenta is inverse green and yellow is inverse of blue. Inverse meaning when a color has
the maximal red value, it has to have the minimal cyan value.
CMYK
is an extension of CMY with a fourth value named key (also 0 .. 1), which is basically the
amount of black mixed into the CMY color.
HSL
has three integer values: hue (0 .. 359), saturation (0 .. 100) and lightness (0 .. 100).
Hue stands for a color on a rainbow: 0 = red, 15 approximates orange, 60 - yellow 120 -
green, 180 - cyan, 240 - blue, 270 - violet, 300 - magenta, 330 - pink. 0 and 360 point to
the same coordinate. This module only outputs 0, even if accepting 360 as input.
saturation ranges from 0 = gray to 100 - clearest color set by hue. lightness ranges from
0 = black to 50 (hue or gray) to 100 = white.
HSV
Similar to HSL we have hue and saturation, but the third value in named value. In HSL the
color white is always achieved when lightness = 100. In HSV additionally saturation has
to be zero to get white. When in HSV value is 100 and saturation is also 100, than we
have the brightest clearest color of whatever hue sets.
HSB
It is an alias to HSV, just value being renamed with brightness.
HWB
An inverted HSV, where the clean colors are inside of the cylinder. It still has the
circular hue dimension, as described in "HSL". The other two, linear dimensions (also 0
.. 100 [percent]) are whiteness and blackness, desribing how much white or black are mixed
in. If both are zero, than we have a pure color. whiteness of 100 always leads to pure
white and blackness of 100 always leads to pure black.
YIQ
Has the linear dimensions luminance (sort of brightness, range 0..1), in-phase (cyan -
orange - balance, range -0.5959 .. 0.5959) and quadrature (magenta - green - balance,
range: -0.5227 .. 0.5227).
FORMATS
These formats are available in all color spaces.
string
'RGB: 10, 20, 30'
css_string
'rgb(10, 20, 30)'
array
[RGB, 10, 20, 30]
hash
{ red => 10, green => 20, blue => 30 }
char_hash
{ r => 10, g => 20, b => 30 }
ROUTINES
This package provides two sets of routines. Thes first is just a lookup of what color
space objects are available. The second set consists of three pairs or routines about 3
essential operations of number values and their reversal. The full pipeline for the
translation of color values is:
1. deformat (into a value list)
2. normalize (into 0..1 range)
3. convert/deconvert (into target color space)
4. denormalize (into target range)
5. format (into target format)
space_names
Returns a list of string values, which are the names of all available color space. See
"COLOR-SPACES".
is_space
Needs one argument, that supposed to be a color space name. If it is, the result is an 1,
otherwise 0 (perlish pseudo boolean).
get_space
Needs one argument, that supposed to be a color space name. If it is, the result is the
according color space object, otherwise undef.
base_space
Return the color space object of (currently) 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.
normalize
Normal in a mathematical sense means the range of acceptable values are between zero and
one. Normalization means there for altering the values of numbers to fit in that range.
For instance standard RGB values are integers between zero and 255. Normalizing them
essentially means just dividing them with 255.
my @rgb = Graphics::Toolkit::Color::Space::Hub::normalize( [0,10,255], 'RGB' );
It has one required and two optional arguments. The first is an ARRAY ref with the vector
or values of a color. The seond argument is name of a color space. This is in most cases
necessary, since all color space know their standard value ranges (being e.g. 3 x 0 .. 255
for RGB). If you want to normalize from special ranges like RGB16 you have use the third
argument, which has to be a valid value range definition.
my @rgb = Graphics::Toolkit::Color::Space::Hub::normalize( [0, 1000, 34000], 'RGB', 2**16 );
# which is the same as:
my @rgb = Graphics::Toolkit::Color::Space::Hub::normalize( [0, 1000, 34000], 'RGB', [[0,65536].[0,65536].[0,65536]] );
denormalize
Reverse function of normalize, taking the same arguments. If result has to be an integer
(range maximum above 1), it will be rounded.
my @rgb = Graphics::Toolkit::Color::Space::Hub::denormalize( [0,0.1,1], 'RGB' );
my @rgb = Graphics::Toolkit::Color::Space::Hub::denormalize( [0,0.1,1], 'RGB', 2**16 );
convert
Converts a value vector (first argument) from base space (RGB) into any space mentioned
space (second argument - see "COLOR-SPACES"). The values have to be normalized (inside
0..1). If there are outside the acceptable range, there will be clamped, so that the
result will also normal.
# convert from RGB to HSL
my @hsl = Graphics::Toolkit::Color::Space::Hub::convert( [0.1, 0.5, .7], 'HSL' );
deconvert
Converts a value tuple (vector - firs argument) of any color space (second argument) into
the base space (RGB).
# convert from HSL to RGB
my @rgb = Graphics::Toolkit::Color::Space::Hub::deconvert( [0.9, 0.5, 0.5], 'HSL' );
format
Putting a list of values (inside an ARRAY ref - first argument) from any supported color
space (second argument) into another data format (third argument, see /FORMATS).
my $hex = Graphics::Toolkit::Color::Space::Hub::format( [255, 0, 10], 'hex' ); # 'ff00a0'
my $string = Graphics::Toolkit::Color::Space::Hub::format( [255, 0, 10], 'string' ); # 'RGB: 255, 0, 10'
deformat
Reverse function of format, but also guesses the color space. That's why it takes only one
argument, a scalar that can be a string, ARRAY ref or HASH ref. The result will be two
values. The first is a ARRAY with all the unaltered, not clamped and not normalized
values. The second is the name of the recognized color name space.
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
partial_hash_deformat
This is a special case deformat routine for the hash and char_hash format (see /FORMATS).
It can tolerate missing values. The The result will also be a hash
SEE ALSO
• Convert::Color
COPYRIGHT & LICENSE
Copyright 2023 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>