Documentation for the implementation of color encoding schemes. The Color::TupleEncode Perl module is available on CPAN).
$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()
Color::TupleEncode::2Way - a utility class for Color::TupleEncode
that
implements color encoding of a 2-tuple (x,y)
to a color
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()
%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
# 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 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)
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
.
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.
Exports nothing.
Use Color::TupleEncode and set the encoding method to
"Color::TupleEncode::2Way"
to use this module.
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()
Martin Krzywinski, <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 rt.cpan.org I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.
You can find documentation for this module with the perldoc command.
perldoc Color::TupleEncode
You can also look for information at:
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 www.biomedcentral.com
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 dev.perl.org for more information.
(c) 2006-2017 Martin Krzywinski mkweb.bcgsc.ca