Color::TupleEncode::2Way - a utility class for Color::TupleEncode that implements color encoding of a 2-tuple (x,y) to a color
Color::TupleEncode
(x,y)
Version 0.11
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()
method
new()
set_options()
%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.
This class encodes a 2-tuple (x,y) to a HSV color (h,s,v). The following parameters are supported
(h,s,v)
# 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.
examples/color-chart-2way.png
The color components are calculated as follows.
Hue is defined based on the ratio of the 2-tuple components, x/y.
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.
hzero
orient
orient = 1
r=x/y
r<=1
[hzero-180,hzero]
h=hzero
r=1
h=hzero-180
r=0
When r>1>, the hue lines in the interval [hzero,hzero+180] and hue progresses clock-wise.
r>
[hzero,hzero+180]
If orient = -1, the direction of hue progression is reversed.
orient = -1
For example, if orient = 1 and hzero = 180 (cyan),
hzero = 180
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)
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 )
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,
s = 1
r = 0
s = 0
r = INF
power = 1
r
2
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.
power = 0
power > 0
rmin
Saturation can be interpolated within [min,max] by setting the -min and -max options.
[min,max]
-min
-max
$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.
0.8
r <= 0
0.2
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.
r <= 1
r = 1
If rmin is set and power = 0, then saturation will be min for r <= rmin and max for r > rmin.
min
r <= rmin
max
r > rmin
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.
r > 0
r > 1
Exports nothing.
Use Color::TupleEncode and set the encoding method to "Color::TupleEncode::2Way" to use this module.
"Color::TupleEncode::2Way"
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>
The 2-tuple color encoding implemented in this module was created by the author.
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/
Driver module. This is the module that provides an API for the color encoding. See Color::TupleEncode.
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/
A template class for implementing an encoding scheme.
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.