view release on metacpan or  search on metacpan

lib/Graphics/Toolkit/Color.pm  view on Meta::CPAN

error message instead of a color name. You can also create your custom
color naming scheme via L<Graphics::Toolkit::Color::Name::Scheme>.

The second named argument is C<all>, which needs to be a perly boolean.
It defaults to false. But if set to 1, you will get a list of all names
that are associated with the current values. There will be no duplicates,
when several schemes are searched.

A third named argument is C<full> - also needing a perly boolean that
defaults to false. When set C<true> (1), the schema name becomes part of
the returned color name as in C<'SVG:red'>. These full names are also
accepted by the constructor.

The fourth named argument is C<distance>, which means the same thing as
in L</distance> and it defaults to zero. It is most useful in combinataion
with C<all> to get all color names that are within a certain distance.

    $blue->name();                                   # 'blue'
    $blue->name('SVG');                              # 'blue'
    $blue->name( from => [qw/CSS X/], all => 1);     # 'blue', 'blue1'
    $blue->name( from => 'CSS', full => 1);          # 'CSS:blue'
    $blue->name( distance => 3, all => 1) ;          # all names within the distance


=head2 closest_name

Returns in scalar context a color name, which has the shortest L</distance>
in I<RGB> to the current color. In list context, you get additionally
the just mentioned distance as a second return value. This method works
almost identically as method L</name>, but guarantees a none empty
result, unless invoking a unusually empty color scheme.

All arguments work as mentioned above, only here is no C<distance> argument.
The only difference is (due to the second return value), multiple names
(when requested) have to come in the form of an ARRAY as the first return value.

    my $name = $red_like->closest_name;              # closest name in default scheme
    my $name = $red_like->closest_name('HTML');      # closest HTML constant
    ($red_name, $distance) = $red_like->closest_name( from => 'Pantone', all => 1 );


=head2 distance

Is a floating point number that measures the Euclidean distance between
two colors, which represent two points in a color space. One color
is the calling object itself and the second one has to be provided as
either the only argument or the named argument L</to>, which is the only
required one.

The C<distance> is measured in I<RGB> color space unless told otherwise
by the argument L</in>. Please use the I<OKLAB> (better) or I<CIELUV> space,
if you are interested in getting a result that matches the human perception.

The third argument is named C<select>. It's useful if you want to regard
only certain dimensions (axis - long and short axis names are accepted).
For instance if you want to know only the difference in brightness between
two colors, you type C<< select => 'lightness' >> or C<< select => 'l' >>.
This naturally works only if you did also choose I<HSL> as a color space
or something similar that has a C<lightness> axis like I<LAB> or I<OKLAB>.
The C<select> argument accepts a string or an ARRAY with several axis names,
which can also repeat. For instance there is a formula to compute distances
in RGB that weights the squared value delta's:
C<< $distance =  sqrt( 3 * delta_red**2 + 4 * delta_green**2 + 2 * delta_blue**2) >>.
You can recreate that formula by typing C<< select => [qw/ r r r g g g g b b/] >>

The last argument is named L</range>, which can change the result drasticly.

    my $d = $blue->distance( 'lapisblue' );                 # how close is blue to lapis?
    $d = $blue->distance( to => 'airyblue', select => 'b'); # have they the same amount of blue?
    $d = $color->distance( to => $c2, in => 'HSL', select => 'hue' );  # same hue?
    $d = $color->distance( to => $c2, range => 'normal' );  # distance with values in 0 .. 1 range
    $d = $color->distance( to => $c2, select => [qw/r g b b/]); # double the weight of blue value differences


=head2 is_in_gamut

Takes any color definition I<new> would accept and returns a perlish pseudo 
boolean (zero or one). That will tell you, if the color is within the gamut 
(value range) of a color space. This can be either the color space the
color was defined in or you choose the space by the argument L</in>.

If you omit a color definition, the current color held by the object will be
checked against that space. But you can also use the argument I<color> 
to provide the color definition and additional information.

The optional argument L</range> overrides the default range definition 
of the space the color is defined in.

The optional argument L</raw> defaults to true, unlike within the method I<new>. 
But you can still set it false for the unlikely occasion you want to clamp the
values to the boundaries of the space the color was defined in and then convert
it into the selected space in order to check if the clamped color fits there.


    $color->is_in_gamut( in => 'okLab');                    # does convert clamp $color?
    $color->is_in_gamut([ RGB =>  255, 0, 0]);              # will new clamp this color?

    use Graphics::Toolkit::Color qw/is_in_gamut/;
    if (is_in_gamut('rgb: 0, 0, 300')){                     # false, 300 has to be clamped to 255
    is_in_gamut(color =>'rgb: 0, 0, 0', in =>'ProPhotoRGB') # black is always included
    

=head1 SINGLE COLOR

These methods generate one new color object that is related to the calling
object (invocant). You might expect that methods like C<set_value> change
the values of the invocant, but GTC objects are as mentioned in the
L</DESCRIPTION> read only. That supports a more functional programming
style as well as method stacking like:

    $color->add_value( saturation => 5)->invert->mix( to => 'green');


=head2 apply

Creates a new GTC color object with recalculated values. Each calculation
is triggered by one named argument and currently is only one possible.
I<gamma> triggers a gamma correction which can be reversed with the inverse argument.
Use an ARRAY ref to apply each color value with a different gamma. 
The argument L</in> determines in which space the carlculation takes place:

    my $linear_blue = $blue->apply( gamma => 2.2 );         # is same the as :
    my $linear_blue = $blue->apply( gamma => {r => 2.2, g =>2.2, b => 2.2}, in => 'RGB' );