.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "Graphics::Toolkit::Color::Space 3" .TH Graphics::Toolkit::Color::Space 3 2026-03-09 "perl v5.42.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Graphics::Toolkit::Color::Space \- base class of all color spaces .SH SYNOPSIS .IX Header "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. .PP .Vb 1 \& use Graphics::Toolkit::Color::Space; \& \& my $def = Graphics::Toolkit::Color::Space\->new ( \& name => \*(Aqdemo\*(Aq, # space name, defaults to axis initials \& alias => \*(Aqalias\*(Aq, # 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 => [\*(Aq\*(Aq, \*(Aq\*(Aq, \*(Aq%\*(Aq], # suffix of value in output \& ); \& \& $def\->add_converter( \*(AqRGB\*(Aq, \e&to_rgb, \e&from_rgb ); \& $def\->add_formatter( \*(Aqname\*(Aq, sub {...} ); \& $def\->add_deformatter( \*(Aqname\*(Aq, sub {...} ); \& $def\->add_constraint( \*(Aqname\*(Aq, \*(Aqerror\*(Aq, sub {...}, sub {} ); \& $def\->set_value_formatter( sub {...}, sub {...}, ) .Ve .SH DESCRIPTION .IX Header "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 \f(CW*::Hub::add_space\fR manually at runtime or submit you color space as merge request and I add your space into the list of automatically loaded spaces. .SH METHODS .IX Header "METHODS" .SS new .IX Subsection "new" The constructor takes eight named arguments, of which only \f(CW\*(C`axis\*(C'\fR 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). .PP The argument \fBaxis\fR 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 \fBshort\fR argument. .PP The concatenation of the upper\-cased long name initials (in the order given with the \f(CW\*(C`axis\*(C'\fR argument) is the default name of this space. More simply: red, green blue becomes RGB. But you can override that by using the \fBname\fR argument or even use \fBalias\fR if there is a secong longer name, under which the space is known. .PP If no argument under the name \fBtype\fR is provided, then all dimensions will be \fIlinear\fR (Euclidean). But you might want to change that for some axis to be \fIcircular\fR or it\*(Aqs alias \fIangular\fR. This will influenc how the methods \fIclamp\fR ans \fIdelta\fR work. A third option for the \fItype\fR argument is \fIno\fR, which indicates that you can not treat the values of this dimension as numbers and they will be ignored for the most part. .PP Under the argument \fBrange\fR 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 \fI\*(Aqnormal\*(Aq\fR to indicate normal ranges (0 .. 1) and the word \&\fI\*(Aqpercent\*(Aq\fR to indicate integer valued ranges of 0 .. 100. .PP The argument \fBprecision\fR 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. .PP The argument \fBsuffix\fR is only interesting if color values has to have a suffix like \fI\*(Aq%\*(Aq\fR in \*(Aq63%\*(Aq. Its defaults to the empty string. .SS add_converter .IX Subsection "add_converter" Takes three arguments: .PP 1. A name of a space the values will be converter from and to (usually just \*(AqRGB\*(Aq). .PP 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. .SS add_formatter .IX Subsection "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 \fIvalues\fR can provide. .SS add_deformatter .IX Subsection "add_deformatter" Same as \fIadd_formatter\fR but the CODE does here the opposite transformation, providing a format reading ability for the GTC constructor. .SS add_constraint .IX Subsection "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. .SS set_value_formatter .IX Subsection "set_value_formatter" This method was introduced for the \fINCol\fR space, where one value is partially represented by letters. When reading a \fINCol\fR 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. .SH AUTHOR .IX Header "AUTHOR" Herbert Breunung, .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2023\-25 Herbert Breunung. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.