Linux Certif

Toute la documentation sur la certification Linux LPI

Color::Calc.3pm

NAME

Color::Calc - Simple calculations with RGB colors.

SYNOPSIS

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

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.

Using the calculation functions

There are three methods to use the calculation functions: You can create an object, import customised functions into your namespace, or you can access them as class methods.

Object-oriented interface

The object-oriented interface can be used to access the calculation functions through an object reference:

   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. The constructor can be passed the following options:

ColorScheme

One of the color schemes accepted by "Graphics::ColorNames", which is used to interpret color names on input. Valid values include "X" (color names used in X-Windows) and "HTML" (color names defined in the HTML 4.0 specification). For a full list of possible values, please refer to the documentation of of "Graphics::ColorNames".

Default: "X" (Note: This is incompatible with HTML color names).

OutputFormat

One of the output formats defined by this module. See below for possible values.

Default: "__MODEvar"

set_output_format

   $cc->set_output_format( $format );
 
 

Changes the output format for an existing "Color::Calc" object.

Importing customised functions

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 a prefix to the front of the method names. You can call the methods as prefix_method_name (the specified value plus an underscore plus the 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')>

Calling unimported class functions

(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::WWW::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::color_invert_hex('FFF');   # prints '000000'
 
 

Color formats

The module supports different color formats for in- and output.

As a general rule, all input formats are accepted at any time regardless of the output format specified by "OutputFormat". This also means that function calls can be nested easily:

   print color_invert(color_invert('blue'));
 
 

Note: Nesting does not work as expected if you specify "html" as the "OutputFormat" and a "ColorScheme" incompatible with HTML (e.g. "X"). (This may change in future versions.)

(Note: The module internally only works with color values in the integer range 0..255, i.e. 8 bit precision. This may change in future versions.)

Input

The module accepts color values 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 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 string containing a hexadecimal RGB value like "#RGB"/"#RRGGBB"/"#RRRGGGBBB"/..., or "RGB"/"RRGGBB"/"RRRGGGBBB"/...

•

A color name accepted by "Graphics::ColorNames". The interpretation is controlled by the "ColorScheme" parameter.

•

A "Graphics::ColorObject" reference.

Output

"Color::Calc" can return colors in the following formats

tuple

Returns a list of three values in the range 0..255. The first value is guaranteed to have a "length" that is not a multiple of three.

hex

Returns a hexadecimal RGB value as a string in the format RRGGBB.

(Note: future versions may return an object that mimics a string instead.)

html

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

(Note: future versions may return an object that mimics a string instead.)

object

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

pdf

Returns a string compatible with "PDF::API2", i.e. #RRGGBB.

(Note: future versions may return an object that mimics a string instead.)

__MODEvar

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

Calculation functions

The module supports the following calculation functions, which can be accessed through one of the methods described above:

get($color)

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

invert($color)

Returns the inverse of $color.

bw($color)

grey($color)

gray($color)

Converts $color to greyscale.

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.

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 [255,255,255] only), the default is 0.5.

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 [0,0,0] only), the default is 0.5.

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.

contrast_bw($color [, $cut])

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

This is done by 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.

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.

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

Graphics::ColorObject (optional)

AUTHOR/LICENSE

Copyright X 2004-2008 Claus Fa.rber <CFAERBER@cpan.org>

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.