/ 
Graphics-Toolkit-Color-2.01
River stage one • 4 direct dependents • 4 total dependents
/ Graphics::Toolkit::Color::Space

NAME

Graphics::Toolkit::Color::Space - base class of all color spaces

SYNOPSIS

    use Graphics::Toolkit::Color::Space qw/:all/;

    Graphics::Toolkit::Color::Space->new (
              name => 'demo',               # space name, defaults to concatenated short axis names
             alias => 'alias',              # second, user set space name, often a shortcut
              axis => [qw/red green blue/], # long axis names, required !
             short => [qw/Re Gr Bl/],       # 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],                    # axis value precision of value output
            suffix => ['', '', '%'],                 # axis value suffix of value in in and output
        value_form => ['\d{3}','\d{1,3}','\d{1,3}'], # special axis value shape
            values => {read => \&read_vals, write => \&write_vals }, # translate values to numbers and back
           convert => {RGB => [\&to_rgb, \&from_rgb, {..flags..}]},  # converter CODE, required !
            format => {'hex_string'=> [\&hex_from_tuple,\&tuple_from_hex]}, # custom IO format
        constraint => {cone => {checker => '$_[0][1] + $_[0][2] <= 1',
	                           error    => 'The sum of whiteness and blackness can not exceed 100%.',
		                       remedy   => 'my $s = $_[0][1] + $_[0][2];[$_[0][0], $_[0][1]/$s, $_[0][2]/$s]', }},
    );

DESCRIPTION

This is the low level API of this distribution. Its purpose is to define color space representing objects that hold all specific informations about the names, shapes and sizes of the axis and all algorithms for conversion and formating. As a result all spaces can be managed by one central Hub and accessed via onother unified API.

The mentioned (low level) API is formed by the constructor arguments, as demonstrated in the SYNOPSIS. They build together a little DSL for defining color spaces. This keeks the space classes short and sweet and helps also contributers to program own color spaces with little effort.

Please name them Graphics::Toolkit::Color::Space::Instance::MyName and send them in as a merge request or feature request. Or if you want to keep it for yourself load them ad runtime via Graphics::Toolkit::Color::Space::Hub::add_space.

The other mentioned API is provided by the other methods of this class. They are not documented here, because they are for internal use only.

METHODS

new

The constructor takes thirteen named arguments, which will be explained in this chapter in logical order. Of those only axis is required. But without also providing convert the space becomes useless.

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 a property of the space or its a property that is the same for all axis or dimensions.

The argument axis defines the long names of all axis, which will set also the number and ordering of the space dimensions! Each axis will also have a short name, which is per default the first letter of the long name. If you prefer other shortcuts, define them via the short argument. Please note that a short axis name can be only one letter long or it will trimmed to the first letter.

The concatenation of the upper-cased short axis names will be the name of the space. In case that doesn't suit your wishes, set the name argument. (Example: axis => [qw/red green blue/] ... becomes ... short => [qw/r g b/] ... becomes ... name => 'RGB' ). Some spaces have a second, longer name which you can set via the argument alias, that defaults to an empty string that will be ignored.

If no argument under the name type is provided, then all dimensions (axis) will be linear (Euclidean). But you might want to change that for some axis to be circular or angular (same thing). This will influenc how the methods clamp ans delta work. For instance cylindrical spaces like HSL or Lab have one circular and two linear axis. 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, values can have in that dimension. If none are provided, normal ranges (0 .. 1) are assumed. You can make it explicit by stating range => 'normal'. range => 'percent' sets all axis to a range of 0 .. 100. The same can be achieved by : range => 100. The one number is the upper bound and the lower is zero by default. A range -100 .. 100 you get from: range => [-100, 100]. If every axis needs an individual range you can combine these statements inside an ARRAY ref like: [20, 'normal', [2,5]].

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.

The argument suffix is only interesting if color values has to have a suffix like '%' in '63%'. Its defaults to the empty string. It is imortant to declare it so it can be removed before calculations and added to putputs.

value_form is for very special cases when axis values are not simply numerical. You can pass you own regular expressions and even provide custom code that can transform your values into numbers and back. Please see the NCol space as an example. If even that is not possible and GTC has simply to ignore the values of one axis, you can still set the axis type to 'no'.

Most important is the convert argument. Here you pass the converter code to one of the already accepted color spaces. The argument expects an HASH ref with one! key, which is the name of the color space you want to convert to and from. This key gets as value an ARRAY ref with two or three values. The first two are CODE references to routines that do the converstion. First the one that converts to that other space. That the routine that converts from it. These routines should expect and return the color values as a tuple (ARRAY ref with numbers). The optional third element in ARRAY which is the value to the key which is the other color space is a HASH with converter flags. This will help to optimize for precision and will be documented later when implemented.

If you want to invent a special format for your color space - with format you can! This option was introduced, so that the RGB space can have it's special hex_string and array formats. Same rules apply as for convert.

Finally there is the constraint argument. It is used for the rare cases, when you space has a custom shape. It expects a HASH ref with as many keys as necessary. The keys are there only for documentation and separation purposes. But to each key belongs a HASH which holds another three keys. checker contains a string with perl code and formulates a condition that must be kept for a point to be inside your space. Again the values are given as a tuple (ARRAY) as the first argument to that code ($_[0]). The second key, remedy contains similar Perl code that can handle the case if a color is outside that constraint (if the condition is not met). The thir key, error is just a fitting error message so the use can know, what the condition is about, that was not met.

AUTHOR

Herbert Breunung, <lichtkind@cpan.org>

COPYRIGHT & LICENSE

Copyright 2023-26 Herbert Breunung.

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