Color::TupleEncode::Baran - a utility class for Color::TupleEncode that implements color encoding of a 3-tuple (x,y,z) to a color
Color::TupleEncode
(x,y,z)
Version 0.11
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
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()
method
new()
set_options()
%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.
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
(a,b,c)
(h,s,v)
# 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.
examples/color-chart-3way.png
The color components are calculated as follows.
Given the tuple (a,b,c), let the characteristic hues for each tuple be ha,hb,hc. Form the differences
ha,hb,hc
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).
dac
(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.
(0.1,1,0.1)
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.
(0.1,1,0.15)
hb = 120
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.
(0.3,0.6,0.9)
ha
hc
h = 300
Given the tuple (a,b,c) and the differences
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
d
[ dmin, dmax ]
set_options
$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.
dmin = 0.25
dmax = 0.75
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 ].
-relative
d > 0
[ 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].
[ min, max ]
min,max
$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).
min
max
If either of (dmin,dmax) parameters are not set, s = 1 always. You can clear a parameter by setting it to undef.
(dmin,dmax)
s = 1
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}>.
-saturation=
You can combine saturation and value encoding together. See the "Value" section.
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.
[0,2]
s = 0
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.
[ 2, 5 ]
dmax
min = 1
max = 0
Below is an example of the HSV values for various ( x, y, z) using the options above.
( x, y, z)
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
> examples/example-3way -options "{-saturation=>{dmin=>0,dmax=>2}, -value=>{dmin=2,dmax=>5,min=>1,max=>0}}" -tuple 0,0.1,1.5
Exports nothing.
Use Color::TupleEncode. The method implemented by this module is used by default.
The encoding class must implement the following functions. Given a Color::TupleEncode object $obj,
$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()
Martin Krzywinski, <martin.krzywinski at gmail.com>
<martin.krzywinski at gmail.com>
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.
bug-color-threeway at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Color::TupleEncode
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Color-TupleEncode
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Color-TupleEncode
CPAN Ratings
http://cpanratings.perl.org/d/Color-TupleEncode
Search CPAN
http://search.cpan.org/dist/Color-TupleEncode/
For details about the color encoding, see
Driver module. This is the module that provides an API for the color encoding. See Color::TupleEncode.
A utility module that encodes a 2-tuple to a color. See Color::TupleEncode::2Way.
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.
To install Color::TupleEncode, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Color::TupleEncode
CPAN shell
perl -MCPAN -e shell install Color::TupleEncode
For more information on module installation, please visit the detailed CPAN module installation guide.