NAME

Color::Calc - Simple calculations with RGB colors.

SYNOPSIS

use Color::Calc ();
my $background = 'green';
print 'background: ',Color::Calc::color_html($background),';';
print 'border-top: solid 1px ',Color::Calc::light_html($background),';';
print 'border-bottom: solid 1px ',Color::Calc::dark_html($background),';';
print 'color: ',contrast_bw_html($background),';';

DESCRIPTION

The Color::Calc module implements simple calculations with RGB colors. This can be used to create a full color scheme from a few colors.

Color Input Formats

All of the functions accept colors as parameters in the following formats:

• An arrayref pointing to an array with three elements in the range 0..255 corresponding to the red, green, and blue component.

• A string containing a hexadecimal RGB value in the form #RRGGBB/#RGB or RGB/RRGGBB.

• A color name accepted by Graphics::ColorNames.

• A PDF::API2::Color reference.

• A Graphics::ColorObject reference.

• The return value of any of the public Color::Calc::* functions, even if it is a list returned by xxx_tuple.

Color Output Formats

Color::Calc can return colors in the following modes:

• tuple

  Returns a list of three values in the range 0..255.

• hex

  Returns a hexadecimal RGB value in the format RRGGBB.

• html

  Returns a value compatible with W3C's HTML and CSS specifications, i.e. #RRGGBB or one of the sixteen color names.

• pdf

  Returns a PDF::API2::Color reference. The module PDF::API2::Color must be installed.

• object

  Returns a Graphics::ColorObject reference. The module Graphics::ColorObject must be installed.

You can select the mode using one of the following methods:

• Add a suffix _mode to the function name:

  Call the function mix as mix_hex, for example.

• Set $Color::Calc::MODE:

  This is a global variable.

  Valid values are 'tuple', 'hex', 'html', 'obj', 'pdf', or 'object' (the default ist 'tuple' to maintain compatibility with earlier versions).

• Use a different module

  You can use one of the modules Color::Calc::hex, Color::Calc::html, Color::Calc::tulpe Color::Calc::obj, Color::Calc::pdf, or Color::Calc::object.

  The function Color::Calc::html::mix is equivalent to Color::Calc::mix_html, for example.

  These modules export their functions with the color_ prefix by default, just as the main module.

Accessing the Functions

The functions can be accessed in several ways:

• The functions are exported by default with a prefix of color_:

  use Color::Calc;
  print color_dark_hex('#FFFFFF');	# returns '808080';

• If you prefer not to import the functions, you can call them by specifying the package name; in this case, you may leave out the prefix color_:

  use Color::Calc ();
  print Color::Calc::dark_hex('#FFFFFF'); # returns '808080';
  print Color::Calc::color_dark_hex('#FFFFFF'); # returns '808080';

Note that function and color_function are fully equivalent except that only color_function is exported by default.

Available Functions

The following functions are available:

• color($color)

• color_get($color)

  Returns the color as-is (but in the format specified). This function can be used for color format conversion/normalisation.

• color_invert($color)

  Returns the inverse of $color.

• color_bw($color) =item * color_grey($color)

  Converts $color to greyscale.

• color_mix($color1, $color2 [, $alpha])

  Returns a color that is the mixture of $color1 and $color2.

  The optional $alpha parameter can be a value between 0.0 (use $color1 only) and 1.0 (use $color2 only), the default is 0.5.

• color_light($color [, $alpha])

  Returns a lighter version of $color, i.e. returns mix($color,[255,255,255],$alpha);

  The optional $alpha parameter can be a value between 0.0 (use $color only) and 1.0 (use 'white' only), the default is 0.5.

• color_dark($color [, $alpha])

  Returns a darker version of $color, i.e. returns mix($color,[0,0,0],$alpha);

  The optional $alpha parameter can be a value between 0.0 (use $color only) and 1.0 (use 'black' only), the default is 0.5.

• color_contrast($color [, $cut])

  Returns a color that has the highest possible contrast to the input color.

  This is done by setting the red, green, and blue values to 0 if the corresponding value in the input is above ($cut * 255) and to 255 otherwise.

  The default for $cut is .5, representing a cutoff between 127 and 128.

• color_contrast_bw($color [, $cut])

  Returns black or white, whichever has the higher contrast to $color.

  This is done by setting returning black if the grey value of $color is above ($cut * 255) and white otherwise.

  The default for $cut is .5, representing a cutoff between 127 and 128.

• color_blend($color [, $alpha])

  Returns a color that blends into the background, i.e. it returns mix($color,contrast($color),$alpha).

  The optional $alpha parameter can be a value between 0.0 (use $color only) and 1.0 (use contrast($color) only), the default is 0.5.

  The idea is that $color is the foreground color, so contrast($color) is similar to the background color. Mixing them returns a color somewhere between them. You might want to use mix($color, $background, $alpha) instead if you know the real background color.

• color_blend_bw($color [, $alpha])

  Returns a mix of $color and black or white, whichever has the higher contrast to $color.

  The optional $alpha parameter can be a value between 0.0 (use $color only) and 1.0 (use black/white only), the default is 0.5.

SEE ALSO

Graphics::ColorNames (required); Color::Object (optional)

AUTHOR

Claus A. Färber <perl@faerber.muc.de>

COPYRIGHT

Copyright © 2004 Claus A. Färber All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.