/ 
Color-Model-RGB-1.0
River stage one • 2 direct dependents • 2 total dependents
/ Color::Model::RGB

NAME

Color::Model::RGB - Color model of RGB

SYNOPSIS

$navy      = rgb(0, 0, 0.5);
$limegreen = rgb('#32CD32');

# use Color::Model::RGB qw(:primary);
$white   = R + G + B;       # addition (constant O and W is also prepared)
$yellow  = $white - $b;     # subtraction
$midgray = $while / 2;      # divide
$hilight = $midgray * 1.5;  # multiply
print qq(<span color="#$hilight">see<span>);    # stringify

@gradation = map { rgb('#010101') << $_ } (0..7);

# use Color::Model::RGB qw(:blender);
$violet = blend_half(R, B);
$pink   = blend_plus(R, $hilight);

DESCRIPTION

Color::Model::RGB is a color model that represented by 3D mathematical vector. This class provides a color vector and fomulae to calcucate and treat color values simply.

Color::Model::RGB uses Math::VectorReal as base. So any methods and functions of Math::VectorReal are inherited.

When some stringifying methods represents values lesser than 0 to be 0.

CONSTANTS

Some primary colors below are defined as constant. To use these, Export with tag ':primary' or ':RGB'

#     R G B
O = [ 0 0 0 ]
R = [ 1 0 0 ]
G = [ 0 1 0 ]
B = [ 0 0 1 ]
W = [ 1 1 1 ]

CONSTRUCTORS

$col1 = Color::Model::RGB->new(0.1, 0.2, 0.3);
$col2 = rgb(0.5,0.6,0.7);
$col3 = rgb256(128,128,255);
$col3 = rgbhex('0080ff');   # rgbhex('#0080ff') is also ok.
                            # and rgb($hexstr) is also ok.
$col4 = $col1->clone();

There are functions to make an object.

Method rgb(), rgb256() and rgbhex() are defalut exported functions returns new Color::Model::RGB object as new().

Method new() and rgb() require three decimal argument. Values out of range will be set -1.0 or 1.0. If one value is given to rgb(), rgb() treat it as a hexadecimal string and call reghex(). Method rgb256() requires three integer values from -255 to 255. Out of range value will be set -255 or 255. Method rgbhex() requires a hexadecimal string like HTML format. An argument starts with '#' is also allowed.

clone() returns new copy of object.

METHODS

r(), g(), b()

Returns decimal value of elements.

r256(), g256(), b256()

Returns integer value of elements, which was multiplyed by 255.

hexstr([ $head_letter ])

Returns 6 digits hexadecimal string. If some string is given as argument, value starting with it returns.

truncate(), limit()

These methods return new clone object, values of which set in regulated range. Method truncate() make values lesser than 0 set to 0, and grater than 1 set to 1. And limit() set values from -1 to 1 similarly.

stringify( [ $format [, $flag2hex] ] )

This method can takes 2 arguments. First is format string for sprintf(). Second is a boolean flag to convert to hexadecimal or not. If this flag is true, each values will be multiplyed by 255 at outputing. Default value of the format and the flag are keeped by package parameter and these are;

$Color::Model::RGB::FORMAT       = "%02x%02x%02x";
$Color::Model::RGB::FORMAT_HEXED = 1;

Arguments are omitted at stringify() calling, these defalut values will be used.

Function set_format() and get_format() describing below gives a way to change these defalut values simply.

OPERATOR OVERLOAD

Color::Model::RGB inherits operators overloading from Math::VextorReal. These functions are so useful for mathematical calculation of colors.

Note: for avoiding error of conflcting with File Test Operation, put a constant object, R, B, W or O, in blanckets"()" or separate with space when using expression with muinus and them.

$c = -(W)       # OK
$c = W - R      # OK
$c = -W         # error or raises bug. ( Perl thinks as "-W $_" )
$c = W-R        # error too.
Negation (unary minus)
$c = -$x        # -object -> rgb(-r,-b,-c)

A Color::Model::RGB object some values of which are minus is allowed for calculation. When stringifying such object, minus value will be represented as 0.

Addition (+)
$c = R + G;     # object1 + object2 -> rgb(r1+r2, g1+g2, b1+b2)
$c = B + 10;    # object  + scalar  -> rgb(r +x,  g +x,  b +x)
Subtraction (-)
$c = W - B;     # object1 - objext2 -> rgb(r1-r2, g1-g2, b1-b2)
$c = W - 10;    # object  - scalar  -> rgb(r1-x,  g1-x,  b1-x)
Object scalar multiplication (*)
$c = W * 0.5    # object  * scalar  -> rgb(r1*x,  g1*x,  b1*x)
# object1 * object2 is not allowed (croaking)
Object scalar division (/)
$c = W / 3      # object  / scalar  -> rgb(r1/x,  g1/x,  b1/x)
# object1 / object2 is not allowed (croaking)
Outer and dot products

Calculation a product is seldom used for color manipulation I guess. So I omit explanation of these.

Bitwise operations

There are bitwise operations in Color::Model::RGB such as '<<', '>>','&', '|', '^' and '~'.

$col1 = rgbhex('010101');
$col2 = $col1 << 7;     # Bit shift left,  becomes 808080
$col3 = $col2 >> 1;     # Bit shift right, becomes 404040

$col4 = $col2 | $col3;  # Object-object bit OR,  becomes c0c0c0
$col5 = $col2 | 0x66;   # Object-scalar bit OR,  becomes e6e6e6

$col6 = $col4 & $col5   # Object-object bit AND, becomes c0c0c0
$col7 = $col4 & 0x80    # Object-scalar bit AND, becomes 808080

$col8 = $col6 ^ $col7   # Object-object bit XOR, becomes 404040
$col9 = $col6 ^ 0xff;   # Object-scalar bit XOR, becomes 3f3f3f

$col10 = ~$col8;        # Bit Negate, becomes bfbfbf

In bit operation, each values of Color::Model::RGB are conveted to integers from 0 to 255 and than caluculated individually, and converted to decimal again.

Package parameter, $Color::Model::RGB::BIT_SHIFT_RIGID, changes bit shift operation's result. If this is true value, caluculated value will be ANDed with 0xff. If not, valuse over 0xff will be set to 0xff(255). Default is false(0).

$Color::Model::RGB::BIT_SHIFT_RIGID = 1;
$col = rgbhex('010101')<<8;     # becomes 000000
$Color::Model::RGB::BIT_SHIFT_RIGID = 0;
$col = rgbhex('010101')<<8;     # becomes ffffff

EXPORTING FUNCTION

There are few froups for exporting.

Defalut exporting functions are rgb, rgb256 and rgbhex.

Primary colors, R (R:255,G:0,B:0), G (R:0,G:255,B:0), B (R:0,G:0,B:255), O (R:0,G:0,B:0) and W (R:255,G:255,B:255), will be exported with tag ':primary' or ':RGB'.

Functions changes defalut about stringifying, set_format and get_format, will be exported with tag ':format'.

And color blending functions, blend_alpha, blend_half, blend_plus and blend_minus, will be exported with tag ':blender'.

CHANGING STRINGIFYING DEFALUT

set_format( $format [, $flag2hex] )
get_format()

Set and get defalut values of stringifying. See method stringify() descriped above.

BLENDING FUNCTIONS

Color::Model::RGB has several blending functions which make a new object from two objects.

$blend_alpha = blend_alpha($src,0.3,$dist,0.7); # any transparency rate
$blend_half  = blend_half($src,$dist);          # 50%:50%
$blend_plus  = blend_plus($src,$dist);          # $src + $dist
$blend_minus = blend_plus($src,$dist);          # $src - $dist

BUGS

Please report any bugs or feature requests to bug-color-model-rgb at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Color-Model-RGB. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ASLO

Math::VectorReal by Anthony Thyssen.

AUTHOR

T.Onodera, <ong at garakuta.net>

LICENSE AND COPYRIGHT

Copyright 2010 T.Onodera.

This program 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; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.