NAME
Graphics::Toolkit::Color::Space - base class of all color spaces
SYNOPSIS
This class is the low level API of this distribution. Every instance represent one color space, containing all specific informations about the names, shapes and sizes of the axis and all specific algorithms, such as converter and (de-) formatter. Because these are all instances of the same class, they can be treated the same from the outside.
use Graphics::Toolkit::Color::Space;
my $def = Graphics::Toolkit::Color::Space->new (
name => 'demo', # space name, defaults to axis initials
alias => 'alias', # second space name
axis => [qw/one two three/], # long axis names
short => [qw/1 2 3/], # short names, defaults to first char of long
type => [qw/linear circular angular/], # axis type
range => [1, [-2, 2], [-3, 3]], # axis value range
precision => [-1, 0, 1], # precision of value output
suffix => ['', '', '%'], # suffix of value in output
);
$def->add_converter( 'RGB', \&to_rgb, \&from_rgb );
$def->add_formatter( 'name', sub {...} );
$def->add_deformatter( 'name', sub {...} );
$def->add_constraint( 'name', 'error', sub {...}, sub {} );
$def->set_value_formatter( sub {...}, sub {...}, )DESCRIPTION
This package provides the API for constructing custom color spaces. Please name them Graphics::Toolkit::Color::Space::Instance::MyName. These instances are supposed to be loaded by Graphics::Toolkit::Color::Space::Hub. So if you are an author of your own color space, you have to call *::Hub::add_space manually at runtime or submit you color space as merge request and I add your space into the list of automatically loaded spaces.
METHODS
new
The constructor takes eight named arguments, of which only axis is required. The values of these arguments have to be in most cases an ARRAY references, which have one element for each axis of this space. Sometimes are also strings acceptable, either because its about the name of the space or its a property that is the same for all axis (dimensions).
The argument axis defines the long names of all axis, which will set also the numbers of dimensions of this space. Each axis will have also a shortcut name, which is per default the first letter of the full name. If you prefer other shortcuts, define them via the short argument.
The concatenation of the upper-cased long name initials (in the order given with the axis argument) is the default name of this space. More simply: red, green blue becomes RGB. But you can override that by using the name argument or even use alias if there is a secong longer name, under which the space is known.
If no argument under the name type is provided, then all dimensions will be linear (Euclidean). But you might want to change that for some axis to be circular or it's alias angular. This will influenc how the methods clamp ans delta work. A third option for the type argument is no, which indicates that you can not treat the values of this dimension as numbers and they will be ignored for the most part.
Under the argument range you can set the numeric limits of each dimension. If none are provided, normal ranges (0 .. 1) are assumed. One number is understood as the upper limit of all dimensions and the lower bound being zero. An ARRAY ref with two number set the lower and upper bound of each dimension, but you can also provide an ARRAY ref filled with numbers or ARRAY ref defining the bounds for each dimension. You can also use the string 'normal' to indicate normal ranges (0 .. 1) and the word 'percent' to indicate integer valued ranges of 0 .. 100.
The argument precision defines how many decimals a value of that dimension has to have. Zero makes the values practically an integer and negative values express the demand for the maximally available precision. The default precision is -1, except when min and max value of the range are int. Then the default precision will be zero as well - except for normal ranges. With them the default precision is again -1.
The argument suffix is only interesting if color values has to have a suffix like '%' in '63%'. Its defaults to the empty string.
add_converter
Takes three arguments:
1. A name of a space the values will be converter from and to (usually just 'RGB').
2. & 3. Two CODE refs of the actual converter methods, which have to take the normalized values as a list and return normalized values as a list. The first CODE converts to the named (by first argument) space and the second from the named into the name space the objects implements.
add_formatter
Takes two arguments: name of the format and CODE ref that takes the denormalized values as a list and returns whatever the formatter wishes to provide, which then the GTC method values can provide.
add_deformatter
Same as add_formatter but the CODE does here the opposite transformation, providing a format reading ability for the GTC constructor.
add_constraint
This method enables you cut off corners from you color space. It has to get four arguments. 1 a constraint name. 2. an error message, that gets shown if a color has one of these illegal values that are inside the normal ranges but outside of this constraint. 3. a CODE ref of a routine that gets a tuple and gives a perly true if the constraint was violated. 4. another routine that can remedy violating values.
set_value_formatter
This method was introduced for the NCol space, where one value is partially represented by letters. When reading a NCol color definition from an input, this value has to be translated into a number, so it can be then processed as other numerical values. That will be done by the first routine, given by this method. The second routine does just the translation back, when the values has to become an output.
AUTHOR
Herbert Breunung, <lichtkind@cpan.org>
COPYRIGHT & LICENSE
Copyright 2023-25 Herbert Breunung.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.