/ 
Color-TupleEncode-0.11
River stage zero No dependents
/ Color::TupleEncode::Baran

NAME

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

VERSION

Version 0.11

SYNOPSIS

This is a utility module used by Color::TupleEncode. This module provides the default color encoding scheme. Therefore, if you do not explicitly set the encoding method in a Color::TupleEncode object explicitly, it will be set to Color::TupleEncode::Baran

To change or set the encoding method, pass the method directly or as an option in new() or set with set_options(). new()

 %options = (-method=>"Color::TupleEncode::Baran");

 $encoder = Color::TupleEncode(options=>\%options);

 # using the direct setter

 $encoder->set_method("Color::TupleEncode::Baran");

 # setting method as an option individually

 $convert->set_options(-method=>"Color::TupleEncode::Baran");

This module is not designed to be used directly.

ENCODING ALGORITHM

This module encodes a 3-tuple (x,y,z) to a HSV 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/

This class encodes a 3-tuple (x,y,z) (or (a,b,c) in accordance with the terminology in the publication) to a HSV color (h,s,v). The following parameters are supported

# for hue          default
-ha                0
-hb                20
-hc                240

# for saturation - set using hash reference as
# option value, e.g. -saturation=>{dmin=>0.2,dmax=>0.8}
-saturation   dmin     0
              dmax     1
              min      0
              max      0
              relative 0

# for value - set using has reference as
# option value, e.g. -saturation=>{min=>0.2}
-value        dmin     NOT SET
              dmax     NOT SET
              min      0
              max      1
              relative 0

Options are set using

%options=>{-ha=>60, -hb=>180, -hc=>300, -saturation=>{dmin=>0,dmax=>2}}

$encoder = Color::TupleEncode(method=>"Color::TupleEncode::2Way", 
                              options=>\%options);

or

$encoder->set_options(-ha=>60);
$encoder->set_options(-ha=>60, -saturation=>{dmin=>0,dmax=>2});

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

The color components are calculated as follows.

Hue

Given the tuple (a,b,c), let the characteristic hues for each tuple be ha,hb,hc. Form the differences

dab = | a - b |
dac = | a - c |
dbc = | b - c |

The hue is calculated along the gradient formed by the two components that form the largest difference. For example, if dac is the largest difference, the final hue lies along the gradient formed by (ha,hc).

hue = 0  if a = b = c

# values of hue below are fractional in the range [0,1] and
# always modulo 1 (e.g. hue=1.2 becomes 0.2).

hue = ha + ( hb - ha ) * dbc / dab      if dab >= dbc and dab >= dac

hue = hb + ( hc - hb ) * dac / dbc      if dbc > dab and dbc >= dac

hue = hc + ( ha + 1 - hc ) * dab / dac  if  dac > dab and dac > dbc

# convert from [0,1] to [0,360]

hue = hue * 360

The effect of this encoding is to emphasize the component that is the most different.

If two components equal and the third is very different, e.g. (0.1,1,0.1) then the encoded hue will the characteristic hue of the largest component. In this case h = hb = 120.

When the difference in the close values is small (0.1,1,0.15) the encoded hue will be very close to the characterstic hue of the most different component. In this case, the hue will be very close to hb = 120 - the hue is h = 113.

When the values are spread equally (0.3,0.6,0.9) the hue will be half way between the characteristic hues of the components that form the largest difference. In this case, the hue will lie between ha and hc - the hue is h = 300.

Saturation

Given the tuple (a,b,c) and the differences

dab = | a - b |
dac = | a - c |
dbc = | b - c |

let

d    = max( dab, dac, dbc )

Saturation is given by

 s = 0                              if d <= dmin
 
 s = 1                              if d >= dmax

 s = ( d - dmin ) / ( dmax - dmin ) if dmin < d < dmax

Thus, saturation is interpolated when the maximum difference d is within [ dmin, dmax ]. These limits are set by set_options. For example

$encoder->set_options( -saturation => { dmin => 0.25, dmax => 0.75 } );

would result in saturation varying from its minimum to maximum value from dmin = 0.25 to dmax = 0.75. Depending on the magnitude of the difference in components in your tuples, you will want to adjust the difference range to match.

If the -relative option is used, then a relative correction is applied to d if d > 0 before saturation is calculated. Note that with this correction, d will always be in the range [ 0, 1 ].

drel = d / max( |a|, |b|, |c|, d )

d <- drel

Saturation can be constrained within a range [ min, max ] by setting the min,max parameters. These values must be in the range [0,1].

$encoder->set_options( -saturation => { min => 0.25, max => 0.75 } );

You can set min < max (e.g. saturation increases as d increases), or min > max (e.g. saturatio decreases as d increases).

If either of (dmin,dmax) parameters are not set, s = 1 always. You can clear a parameter by setting it to undef.

$encoder->set_options( -saturation => { -dmin => undef, -dmax => undef } )

To toggle the use of relative difference,

$encoder->set_options( -saturation => { relative => 1 } );

The Baran et al. publication in which this encoding was introduced suggests to use the product of absolute and relative saturations as the final saturation. This can be done by calculating two values of saturation, one with the -saturation={relative=>0}> option, and one with -saturation={relative=>1}>.

You can combine saturation and value encoding together. See the "Value" section.

Value

The value is defined analogously to saturation.

You can supplement saturation encoding with value encoding as follows. Set the difference range [ dmin, dmax ] for value to be higher/lower than the difference range for saturation. For example,

$encoder->set_options(-saturation => { dmin => 0 , dmax => 2},
                      -value      => { dmin => 2 , dmax => 5 , min => 1 , max => 0 };

The effect will be to adjust saturation when the largest component difference is in the range [0,2] (from s = 0 to s = 1). Thus as the difference grows, the color becomes more saturated.

In the range [ 2, 5 ], s = 1 since the range is beyond dmax set for saturation. However, in this higher range the value will be adjusted from min = 1 to max = 0. Thus, as the difference grows, the color gets darker.

Below is an example of the HSV values for various ( x, y, z) using the options above.

0 , 0.1 , 1.0   251  0.50  1.0
0 , 0.1 , 1.5   248  0.75  1.0
0 , 0.1 , 2.0   246  1.00  1.0
0 , 0.1 , 3.0   243  1.00  0.67
0 , 0.1 , 4.0   242  1.00  0.33
0 , 0.1 , 5.0   242  1.00  0.00
0 , 0.1 , 6.0   242  1.00  0.00

You can obtain these values with examples/example-3way as follows, for each tuple,

> examples/example-3way -options "{-saturation=>{dmin=>0,dmax=>2},
                                   -value=>{dmin=2,dmax=>5,min=>1,max=>0}}" 
                        -tuple 0,0.1,1.5

EXPORT

Exports nothing.

Use Color::TupleEncode. The method implemented by this module is used by default.

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>

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

For details about the color encoding, see

Color::TupleEncode

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

Color::TupleEncode::2Way

A utility module that encodes a 2-tuple to a color. See Color::TupleEncode::2Way.

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.