NAME

Graphics::ColorObject - convert between color spaces

UPGRADING FROM 0.3a2 AND OLDER VERSIONS

This version is a complete rewrite since the previous version, 0.3a2. The API is completely changed. The old API should be emulated, but that has not been tested as extensively as I'd like. Therefore, please test any code that uses this module when upgrading. If you encounter any strange behavior, please downgrade to 0.3a2 and email me a bug report. Additionally, the exact values returned by some functions may be slightly different, this is not a bug - the new values are (more) correct.

SYNOPSIS

  use Graphics::ColorObject;
  
  # rgb to hsv
  $color = Graphics::ColorObject->new_RGB([$r, $g, $b]);
  ($h, $s, $v) = @{ $color->as_HSV() };
  
  # one rgb space to another (NTSC to PAL)
  $color = Graphics::ColorObject->new_RGB([$r, $g, $b], space=>'NTSC');
  ($r, $g, $b) = @{ $color->as_RGB(space=>'PAL') };

ABSTRACT

Use this module to convert between all the common color spaces. As a pure Perl module, it is not very fast, and so it you want to convert entire images, this is probably not what you want. The emphasis is on completeness and accurate conversion.

Supported color spaces are: RGB (including sRGB, Rec 601, Rec 709, ITU, and about a dozen other RGB spaces), CMY, CMYK, HSL, HSV, XYZ, xyY, Lab, LCHab, Luv, LCHuv, YPbPr, YCbCr. Future support is planned for YUV, YIQ, YCC and possibly others.

Conversion between different RGB working spaces, and between different white-points, is fully supported.

DESCRIPTION

For any supported color space XXX, there is one constructor new_XXX that creates a color using data in that color space, and one method as_XXX that returns the current color as expressed in that color space. For example, for RGB there is new_RGB and as_RGB. The color data is always passed as an array reference to a three-element array. Thus, to convert from RGB to HSL, you can use:

  $color = Graphics::ColorObject->new_RGB([$r, $g, $b]);
  ($h, $s, $l) = @{ $color->as_HSL() };

The constructor can always take a hash of optional arguments in addition to the color value, namely the working RGB space and the white point. For example:

  $color = Graphics::ColorObject->new_RGB([$r, $g, $b], space=>'Adobe', white_point=>'D65');

For a list of all RGB working spaces and of all white points that this module supports, call Graphics::ColorObject->list_rgb_spaces() and Graphics::ColorObject->list_white_points(). If not specified, the working RGB space will be sRGB, and operations that default to using that will print a warning.

Most conversions will return out-of-gamut values if necessary, because that way they are lossless and can be chained in calculations, or reversed to produce the original values. At present there is no way to check whether a value is within gamut for a particular space; that feature may be added in the future. (An RGB value is within gamut simply if R, G and B are between 0 and 1, but other spaces can be much harder to check.)

RGB values are non-linear (i.e. gamma-adjusted) floating-point values scaled in the range from 0 to 1. If you want integer values in the range 0..255, use the RGB255 functions instead.

Functions that use an angle value always express it in degrees. That includes the hue H in HSL, HSV, LCHab and LCHuv. Use rad2deg and deg2rad from Math::Trig to convert to/from degrees if necessary.

METHODS

$color = Graphics::ColorObject->new_XYZ([$X, $Y, $Z])

$color = Graphics::ColorObject->new_xyY([$x, $y, $Y])

$color = Graphics::ColorObject->new_RGB([$R, $G, $B])

$color = Graphics::ColorObject->new_RGB255([$R, $G, $B])

$color = Graphics::ColorObject->new_RGBhex($rgbhex)

$color = Graphics::ColorObject->new_Lab([$L, $a, $b])

$color = Graphics::ColorObject->new_LCHab([$L, $C, $H])

$color = Graphics::ColorObject->new_Luv([$L, $u, $v])

$color = Graphics::ColorObject->new_LCHuv([$L, $C, $H])

$color = Graphics::ColorObject->new_HSL([$H, $S, $L])

$color = Graphics::ColorObject->new_HSV([$H, $S, $V])

$color = Graphics::ColorObject->new_CMY([$C, $M, $Y])

$color = Graphics::ColorObject->new_CMYK([$C, $M, $Y])

$color = Graphics::ColorObject->new_YPbPr([$Y, $Pb, $Pr])

$color = Graphics::ColorObject->new_YCbCr([$Y, $Cb, $Cr])

($X, $Y, $Z) = @{ $color->as_XYZ() }

($R, $G, $B) = @{ $color->as_RGB() }

($R, $G, $B) = @{ $color->as_RGB255() }

$hex = $color->as_RGBhex()

($x, $y, $Y) = @{ $color->as_xyY() }

($L, $a, $b) = @{ $color->as_Lab() }

($L, $C, $H) = @{ $color->as_LCHab() }

($L, $u, $v) = @{ $color->as_Luv() }

($L, $C, $H) = @{ $color->as_LCHuv() }

($H, $S, $L) = @{ $color->as_HSL() }

($H, $S, $V) = @{ $color->as_HSV() }

($C, $M, $Y) = @{ $color->as_CMY() }

($C, $M, $Y, $K) = @{ $color->as_CMYK() }

($Y, $Pb, $Pr) = @{ $color->as_YPbPr() }

($Y, $Cb, $Cr) = @{ $color->as_YCbCr() }

($Y, $C1, $C2) = @{ $color->as_YCC() } UNIMPLEMENTED

($Y, $U, $V) = @{ $color->as_YUV() } UNIMPLEMENTED

($Y, $I, $Q) = @{ $color->as_YIQ() } UNIMPLEMENTED

EXPORT

None by default. The 'all' tag causes the non-object-oriented interface to be exported, and you get all the XXX_to_YYY functions, for example RGB_to_XYZ. Please note that many of these functions need extra arguments in addition to the color value to be converted.

BUGS

Backwards compatibility with the previous version is not very well tested.

Some color transformations are not exactly reversible. In particular, conversions between different white points are almost but not exactly reversible.

There is no way to choose a white point or RGB space other than the built-in ones.

There is no way to choose any other color-adaptation algorithm than the Bradford algorithm.

There is no way to check whether a value is within gamut for a particular space.

Support for CMYK is very basic, it relies on assumptions that completely do not work in the physical world. If you tried to convert an image to CMYK for printing using these functions, the results will not be very good, to say the least.

SEE ALSO

The Color FAQ by Charles Poynton is one of the definitive references on the subject: http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.txt

Bruce Lindbloom's web site contains a tremendous amount of information on color: http://www.brucelindbloom.com/index.html?Math.html

AUTHOR

Alex Izvorski, <izv@dslextreme.com>

Alfred Reibenschuh <alfredreibenschuh@yahoo.com> was the original author for versions up to 0.3a2.

Many thanks to:

Alfred Reibenschuh <alfredreibenschuh@yahoo.com> for the previous versions of Graphics::ColorObject, and for the HSL/HSV/CMYK code.

Bruce Lindbloom <info@brucelindbloom.com> for providing a wealth of information on color space conversion and color adaptation algorithms, and for the precalculated RGB conversion matrices.

Charles Poynton <colorfaq@poynton.com> for the Color FAQ.

Timo Autiokari <timo.autiokari@aim-dtp.net> for information on white points.

COPYRIGHT AND LICENSE

Copyright 2003-2004 by Alex Izvorski

Portions Copyright 2001-2003 by Alfred Reibenschuh

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Graphics::ColorObject

perl -MCPAN -e shell
install Graphics::ColorObject