perldoc > Graphics::Toolkit::Color::Space::Hub

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 AT cpan.org>