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 Formats

Input

All of the methods 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 like #RGB/#RRGGBB/#RRRGGGBBB/... or RGB/RRGGBB/RRRGGGBBB/...

• A color name accepted by Graphics::ColorNames.

  A Graphics::ColorObject reference.

• A list of three values in the range 0..255 corresponding to the red, green, and blue component where the first value does not have 3 or a multiple of 3 digits (e.g. ('0128',128,128)).

• A return value of any (public) Color::Calc method even if the tuple output format is selected.

Output

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.

object

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

pdf

Returns a value which can be passed to PDF::API2::Content's fillcolor and strokecolor methods.

__MODEvar

(DEPRECATED) Uses the value of $Color::Calc::MODE to select the output format. You should use local when setting this variable.

Object-Orientated interface

use Color::Calc();
my $cc = new Color::Calc( 'ColorScheme' => 'X', OutputFormat => 'HTML' );
print $cc->invert( 'white' );

new

$cc = new Color::Calc( 'ColorScheme' => $name, 'OutputFormat' => $format );

Creates a new Color::Calc object which can be used to access the color calculation methods.

ColorScheme

One of the color schemes accepted by Graphics::ColorNames. Used to translate color names on input. See the documentation of Graphics::ColorNames for possible values.

Default: X (please note that this is incompatible with HTML color names).

OutputFormat

Sets the output format of the object's methods. See above for possible values.

Default: __MODEvar

$cc->get($color)

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

$cc->invert($color)

Returns the inverse of $color.

$cc->bw($color) =item $cc->grey($color)

Converts $color to greyscale.

$cc->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.

$cc->color_light($color [, $alpha])

Returns a lighter version of $color, i.e. returns $cc->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.

$cc->dark($color [, $alpha])

Returns a darker version of $color, i.e. returns $cc->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.

$cc->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.

$cc->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.

$cc->blend($color [, $alpha])

Returns a color that blends into the background, i.e. it returns $cc->mix($color,$cc->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.

$cc->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.

Procedural Interface With Importing

You can also choose to import customised funtions into your namespace:

use Color::Calc(
  'ColorScheme' => 'X',
  'OutputFormat' => 'HTML',
  'Prefix' => 'cc' );
print cc_invert( 'white' );	# prints 'black'

On import, you can specify the following parameters:

ColorScheme

See above.

OutputFormat

See above.

Prefix

Adds the prefix and an underscore to the front of the method names. You can call the methods as prefix_method_name. You can also call prefix instead of prefix_get.

Default: color

Please note that specifying an empty list of parameters means "don't import anything". Omit the list to import the default functions.

You can also use the following modules to import the function with pre-defined parameters.

use Color::Calc::WWW

Same as use Color::Calc( ColorScheme => 'WWW', OutputFormat = 'html' )>

use Color::Calc::html

(DEPRECATED) Same as use Color::Calc( OutputFormat => 'html')

Please note that this only selects HTML as the OutputFormat but not as the ColorScheme (which defaults to 'X'), which is probably not what you expect. Use Color::Calc::WWW instead.

use Color::Calc::hex

Same as use Color::Calc( OutputFormat => 'hex')

use Color::Calc::object

Same as use Color::Calc( OutputFormat => 'object')

use Color::Calc::pdf

Same as use Color::Calc( OutputFormat => 'pdf')

use Color::Calc::tuple

Same as use Color::Calc( OutputFormat => 'tuple')

Procedural Interface Without Importing

(DEPRECATED) You can also access the methods as class methods of the various packages with and without the color prefix:

use Color::Calc::WWW();

print Color::Calc::WWW::color('FFF');		# prints 'white'
print Color::Calc::WWW::color_invert('FFF');	# prints 'black'
print Color::Calc::html::invert('FFF');	# prints 'black'

For the main module Color::Calc, you can also add a suffix _output_format to select the output format:

use Color::Calc();

print Color::Calc::color_html('FFF');		# prints 'white'
print Color::Calc::color_invert_html('FFF');	# prints 'black'
print Color::Calc::invert_hex('FFF');		# prints '000000'

SEE ALSO

Graphics::ColorNames (required);

Graphics::ColorObject (optional)

AUTHOR

Claus Färber <cfaerber@cpan.org>

COPYRIGHT

Copyright © 2004-2006 Claus Färber

This module is free software; you can redistribute it and/or modify it under the terms of either the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or the "Artistic License".

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

cpanm Color::Calc

perl -MCPAN -e shell
install Color::Calc