GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Graphics::ColorUtils(3) User Contributed Perl Documentation Graphics::ColorUtils(3)

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

  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 );

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.)

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.

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.

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'.)

"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/

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()

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).

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!

Color::Rgb
Lookup of color values for names. Similar to the "names" methods in this module. Requires X11/rgb.txt.
Graphics::ColorNames
Lookup of color values for names. Similar to the "names" methods in this module. Does not require X11/rgb.txt. Comes with several sets of predefined color names (similar to this module).
Graphics::ColorObject
Color space conversions, including conversions to and from XYZ and Luv. Object-oriented interface requires instantiation of a "color-object" for each color, which can then provide a representation of itself in all color spaces.
Color::Scheme
Generates pleasant color schemes (sets of colors).

WWW/CSS
The 16 (or 17, including "orange") colors defined by the W3: http://www.w3.org/TR/css3-color
SVG
The 138 unique named colors (140 normalized unique names) defined for SVG by the W3: http://www.w3.org/TR/SVG/types.html#ColorKeywords
X11
The 502 unique named colors (549 normalized unique names) defined by the X11 libraries in /usr/lib/X11/rgb.txt on an X11 system

  • Poynton's Color FAQ: http://www.poynton.com/ColorFAQ.html
  • Paper on Color Conversion Algorithms: http://www.poynton.com/PDFs/coloureq.pdf
  • Paul Bourke's Webpage with many relevant details: http://local.wasp.uwa.edu.au/~pbourke/texture_colour/

  • Computer Graphics - Principles and Practice by James D. Foley, Andries van Dam, Steven K. Feiner, John F. Hughes (Second Edition in C, 1990, mult. print runs)

    A comprehensive reference. Beware of typos in the algorithms!

  • Introduction to Computer Graphics by James D. Foley, Andries van Dam, Steven K. Feiner, John F. Hughes, Richard L. Phillips (1990, mult. print runs)

    A textbook based on the previous title. Possibly more accessible and available.

  • Computer Graphics - C Version by Donald Hearn and M. Pauline Baker (2nd ed, 1997)

    Another textbook.

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

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.

2007-05-21 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.