Ubuntu Manpage: Graphics::ColorUtils - Easy-to-use color space conversions and more.

Provided by: libgraphics-colorutils-perl_0.17-1_all

NAME

       Graphics::ColorUtils - Easy-to-use color space conversions and more.

SYNOPSIS

         use Graphics::ColorUtils;

         ( $y, $i, $q ) = rgb2yiq( $r, $g, $b );
         ( $r, $g, $b ) = yiq2rgb( $y, $i, $q );
         $hex_string    = yiq2rgb( $y, $i, $q );

         ( $c, $m, $y ) = rgb2cmy( $r, $g, $b );
         ( $r, $g, $b ) = cmy2rgb( $c, $m, $y );
         $hex_string    = cmy2rgb( $c, $m, $y );

         ( $h, $l, $s ) = rgb2hls( $r, $g, $b );
         ( $r, $g, $b ) = hls2rgb( $h, $l, $s );
         $hex_string    = hls2rgb( $h, $l, $s );

         ( $h, $s, $v ) = rgb2hsv( $r, $g, $b );
         ( $r, $g, $b ) = hsv2rgb( $h, $s, $v );
         $hex_string    = hsv2rgb( $h, $s, $v );

         # -----

         use Graphics::ColorUtils qw( :gradients );

         ( $r, $g, $b ) = grad2rgb( $name, $f );  # where 0.0 <= $f < 1.0
         $hex_string    = grad2rgb( $name, $f );

         %color_count_for_gradient_name = available_gradients();
         $array_ref_of_rgb_triples      = gradient( $name );
         $array_ref_old_grad            = register_gradient( $name, $array_ref_of_rgb_triples );

         # -----

         use Graphics::ColorUtils qw( :names );

         ( $r, $g, $b ) = name2rgb( $name );
         $hex_string    = name2rgb( $name );

         $hash_ref_rgb_triples_for_name = available_names();
         ( $old_r, $old_g, $old_b )     = register_name( $name, $r, $g, $b );
         $old_hex_string                = register_name( $name, $r, $g, $b );
         $default_ns                    = get_default_namespace();
         $old_ns                        = set_default_namespace( $new_ns );

DESCRIPTION

       This modules provides some utility functions to handle colors and color space conversions.

       The interface has been kept simple, so that most functions can be called "inline" when
       making calls to graphics libraries such as GD, Tk, or when generating HTML/CSS. (E.g. for
       GD: "$c = $img->colorAllocate( hsv2rgb( 270, 0.5, 0.3 ) );".)

       Features:

       Color Space Conversions
           Color space conversions, in particular between the "intuitive" color spaces HSV
           (Hue/Saturation/Value) and HLS (Hue/Lightness/Saturation) to and from RGB
           (Red/Green/Blue).

       Color Lookup
           Color lookup by name for three standard sets of colors: WWW/CSS, SVG, and X11.

       Color Gradients
           Management of color gradients, which can be indexed by a floating point number in the
           range 0..1. (Mostly intended for false-color data visualization.)

CONVENTIONS

       Legal values:

         Y, I, Q: 0..1
         C, M, Y: 0..1

         R, G, B: 0..255 (may be float on input, guaranteed int on output)

         H:       0..360 (red=0->yellow->green=120->cyan->blue=240->magenta steps of 60)
         S, V:    0..1
         L, S:    0..1

       All "...2rgb" functions return a three-element array in list context, and a string
       formatted according to "#%02x%02x%02x" (e.g. '#ff3a18') in scalar context.

METHODS

   Color Space Conversions
       YIQ "rgb2yiq( $r, $g, $b )" and "yiq2rgb( $y, $i, $q)"

       CMY "rgb2cmy( $r, $g, $b )" and "cmy2rgb( $c, $m, $y)"

       HSV "rgb2hsv( $r, $g, $b )" and "hsv2rgb( $h, $s, $v)"

       HLS "rgb2hls( $r, $g, $b )" and "hls2rgb( $h, $l, $s)"

       All these methods take a triple of values and return a triple of converted values.
       However, in scalar context the "...2rgb" methods return a string formatted according to
       "#%02x%02x%02x" (e.g. '#ff3a18'). This format is appropriate e.g. for calls to Tk
       routines: "$mw->widget( -color =" hls2rgb( 180, 0.2, 0.1 ) );>, etc.

   Color Names
       Names can be arbitrary strings. If names contain a colon (':'), the part of the name
       before the colon is considered a "namespace" specification. Namespaces allow to have
       multiple color values corresponding to the same name and to control the priority in which
       those values will be retrieved.

       "name2rgb( $name )"
           Returns a triple "( $r, $g, $b )" in list context or a a hex-string in scalar context
           if the name has been found, "undef" otherwise.

           The name is normalized before lookup is attempted. Normalization consists of:
           lowercasing and elimination of whitespace. Also, "gray" is replaced with "grey".

           If the name is prefixed with a namespace (separated by colon a ':'), only this
           namespace is searched. If no namespace is specified, then the lookup occurs first in
           the global namespace, then in the default namespace.

       "available_names()"
           Returns a reference to a hash, the keys of which are the color names, and the values
           are references to three-element arrays of RGB values.

       "register_name( $name, $r, $g, $b )"
           Takes a name and an RGB triple. Stores the triple for the given name.  The name will
           be normalized (lowercased, whitespace eliminated, 'gray' replaced by 'grey') before
           assignment is made.

           If the name is not prefixed by a namespace, the color will be entered into the global
           namespace.

           Returns the old value for the name, if the name already exists, "undef" otherwise.

       "get_default_namespace()"
           Returns the current value of the default namespace. Note that the empty string ''
           corresponds to the global namespace.

       "set_default_namespace()"
           Sets the default namespace. Returns the previous value.

           Giving an empty string as argument makes the global namespace the default.  Note that
           the global namespace is initially empty.

           (On startup, the default namespace is 'x11'.)

   Color Gradients
       "grad2rgb( $name, $f )"
           Given the name of a gradient and a floating point number between 0 and 1, returns the
           color (as RGB triple or formatted hex-string) corresponding to the position in the
           gradient given by $f.  Returns "undef" when gradient not found or $f outside valid
           range.

       "available_gradients()"
           Returns a hash, the keys of which are the names of the known gradients and the values
           being the number of colors in the corresponding gradient.

       "gradient( $name )"
           Given the name of a gradient, returns a reference to an array of RGB triples or
           "undef" if the gradient is not found.

       "register_gradient( $name, $array_ref )"
           Takes the name of a (possibly new) gradient and a reference to an array of RGB
           triples. Stores the array as gradient for that name.  If the gradient name already
           existed, returns a reference to the old array, "undef" otherwise.

       An introduction, together with a large number of sample gradients can be found at Paul
       Bourke's webpage: http://local.wasp.uwa.edu.au/~pbourke/texture_colour/colourramp/

EXPORT

       Exports by default:

         rgb2yiq(), yiq2rgb()
         rgb2cmy(), cmy2rgb()
         rgb2hls(), hls2rgb()
         rgb2hsv(), hsv2rgb()

       Using the export tag ":names", exports the following additional methods:

         name2rgb()
         available_names()
         register_name()
         set_default_namespace()
         get_default_namespace()

       Using the export tag ":gradients", exports the following additional methods:

         gradient()
         grad2rgb()
         available_gradients()
         register_gradient()

BUGS

       Input parameter validation
           Most methods do not explicitly validate that their arguments lie in the valid range.

       Multiple namespaces
           Names containing multiple colons may not be handled correctly.

       Hue wrap-around
           While hue should be restricted to 0..360, both "hsv2rgb()" and "hls2rgb()" tolerate
           "moderate" violation of this constraint (up to +/- 359).

TODO

       Perl Versions
           This module has only been explicitly tested with Perl 5.8, but nothing (should)
           prevent it from running fine with other versions of Perl.

       Additional color space conversions
           For instance to and from XYZ, CIE, Luv; if desired!.

       Additional pre-defined gradients
           Suggestions welcome!

AUTHOR

       Philipp K. Janert, <janert at ieee dot org >, http://www.beyondcode.org

COPYRIGHT AND LICENSE

       Copyright (C) 2006 by Philipp K. Janert

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of
       Perl 5 you may have available.

NAME

SYNOPSIS

DESCRIPTION

CONVENTIONS

METHODS

EXPORT

BUGS

TODO

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE