The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
Color-TupleEncode-0.11
River stage zero No dependents
/ Color::TupleEncode::2Way

NAME

Color::TupleEncode::2Way - a utility class for Color::TupleEncode that implements color encoding of a 2-tuple (x,y) to a color

VERSION

Version 0.11

SYNOPSIS

This is a utility module used by Color::TupleEncode. To use this module as the encoding method, pass the method directly or as an option in new() or set with set_options(). new()


            

              
              
%options = (-method=>"Color::TupleEncode::2Way");
$encoder = Color::TupleEncode(options=>\%options);
# using the direct setter
$encoder->set_method("Color::TupleEncode::2Way");
# setting method as an option individually
$convert->set_options(-method=>"Color::TupleEncode::2Way");

This module is not designed to be used directly.

ENCODING ALGORITHM

This class encodes a 2-tuple (x,y) to a HSV color (h,s,v). The following parameters are supported


            

              
              
# for hue          default
-hzero             180
-orientation       1
# for saturation (e.g. -saturation=>{power=>1,rmin=>0}
-rmin              0
-power             1
-min               1
-max               0
# for value (e.g. -value=>{power=>2,rmin=>1}
-rmin              1
-power             2
-min               1
-max               0

Options are set using


            

              
              
%options => {-hzero=>0, -orientation=>1, -saturation => { rmin => 0 } }
$encoder = Color::TupleEncode(method=>"Color::TupleEncode::2Way", 
                              options=>\%options)

or


            

              
              
$encoder->set_options( -hzero => 0)
$encoder->set_options( -hzero => 0, -orientation =>1 )
$encoder->set_options( -hzero => 0, -orientation =>1, -saturation => { rmin => 0} )

See examples/color-chart-2way.png for a chart of encoded colors.

The color components are calculated as follows.

Hue

Hue is defined based on the ratio of the 2-tuple components, x/y.


            

              
              
r   = x/y
hue = hzero + 180                     if  y =  0
hue = hzero - orient * 180 * (1-r)    if  r <= 1
hue = hzero + orient * 180 * (1-1/r)  if  r >  1
All hue values are modulo 360.

This method maps the (x,y) pair onto the color wheel as follows. First, a reference hue hzero is chosen. Next, the mapping orientation is selected using orient. Assuming that orient = 1, and given the ratio r=x/y, when r<=1 the hue lies in the interval [hzero-180,hzero]. Thus hue progresses in the counter-clockwise direction along the color wheel from h=hzero when r=1 to h=hzero-180 when r=0.

When r>1>, the hue lines in the interval [hzero,hzero+180] and hue progresses clock-wise.

If orient = -1, the direction of hue progression is reversed.

For example, if orient = 1 and hzero = 180 (cyan),


            

              
              
       hue  color    r = x/y
    
         0  red      0
        45  orange   0.25
        90  lime     0.5
       135  green    0.75
hzero  180  cyan     1
       240  blue     1.5
       270  violet   2
       300  purple   3
       315  purple   4
         0  red      INF, NaN (y=0)

Saturation

The saturation is calculated using the size of the 2-tuple, r = sqrt( x**2 + y**2 ). Depending on the value of power,


            

              
              
r = sqrt ( x**2 + y **2 )
                  -r/power
saturation = 1 - 2           if power > 0
saturation = 1               if power = 0

The default limits on saturation are s = 1 at r = 0 and s = 0 at r = INF. The default rate of decrease is power = 1. Thus, for every unit change in r, saturation is decreased by 50%. Use the power option to change the rate of change. In general, saturation will change by a factor of 2 for every power units of r. That is,


            

              
              
r    saturation
     power = 1    power = 2   power = 3
0    1            1           1
1    0.5          0.707       0.794
2    0.25         0.5         0.63
3    0.125        0.354       0.5
4    0.063        0.25        0.397

If power = 0, saturation will be assigned the value it would have at r = 0 if power > 0. However, keep in mind the effect of rmin, described below.

Saturation can be interpolated within [min,max] by setting the -min and -max options.


            

              
              
$convert->set_options(-saturation=>{min=>0.8,max=>0.2})

In this example, saturation will be 0.8 at r <= 0 and will start decreasing at r = 0 towards 0.2 at r = INF.

You can set the minimum value of the tuple component at which saturation begins to change. Use rmin option,


            

              
              
$convert->set_options(-saturation=>{min=>0.8,max=>0.2,rmin=>1})

In this example, saturation will be 0.8 at r <= 1, will start decreasing at r = 1 towards 0.2 at r = INF.

If rmin is set and power = 0, then saturation will be min for r <= rmin and max for r > rmin.

Value

The value is calculated using the same formula as for saturation.

By setting different rmin values for saturation and value components, you can control the range of r over which the encoding acts. For example,


            

              
              
$convert->set_options(-saturation=>{rmin=>0},-value=>{rmin=>1})

will result in saturation changing for r > 0 and value only for r > 1. For r <= 1, value will be at its min setting.

EXPORT

Exports nothing.

Use Color::TupleEncode and set the encoding method to "Color::TupleEncode::2Way" to use this module.

IMPLEMENTING AN ENCODING CLASS

The encoding class must implement the following functions. Given a Color::TupleEncode object $obj,

$value = _get_value( $obj )

$saturation = _get_saturation( $obj )

$hue = _get_hue( $obj )

$size = _get_tuple_size()

@opt_ok =_get_ok_options()

%opt_def = _get_default_options()

AUTHOR

Martin Krzywinski, <martin.krzywinski at gmail.com>

The 2-tuple color encoding implemented in this module was created by the author.

BUGS

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

SUPPORT

You can find documentation for this module with the perldoc command.


            

              
              
perldoc Color::TupleEncode

You can also look for information at:

SEE ALSO

Color::TupleEncode

Driver module. This is the module that provides an API for the color encoding. See Color::TupleEncode.

Color::TupleEncode::Baran

Encodes a 3-tuple to a color using the scheme described in

Visualization of three-way comparisons of omics data Richard Baran Martin Robert, Makoto Suematsu, Tomoyoshi Soga1 and Masaru Tomita BMC Bioinformatics 2007, 8:72 doi:10.1186/1471-2105-8-72

This publication can be accessed at http://www.biomedcentral.com/1471-2105/8/72/abstract/

Color::TupleEncode::2Way

A template class for implementing an encoding scheme.

LICENSE AND COPYRIGHT

Copyright 2010 Martin Krzywinski.

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.