view release on metacpan or  search on metacpan

lib/Color/TupleEncode/2Way.pm  view on Meta::CPAN

  -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 C<examples/color-chart-2way.png> for a chart of encoded colors.

The color components are calculated as follows.

=head2 Hue

Hue is defined based on the ratio of the 2-tuple components, C<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 C<(x,y)> pair onto the color wheel as
follows. First, a reference hue C<hzero> is chosen. Next, the mapping
orientation is selected using C<orient>. Assuming that C<orient = 1>,
and given the ratio C<r=x/y>, when C<r<=1> the hue lies in the
interval C<[hzero-180,hzero]>. Thus hue progresses in the
counter-clockwise direction along the color wheel from C<h=hzero> when
C<r=1> to C<h=hzero-180> when C<r=0>.

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

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

For example, if C<orient = 1> and C<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)

=head2 Saturation

The saturation is calculated using the size of the 2-tuple, C<r = sqrt( x**2 + y**2 )>. Depending on the value of C<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 C<s = 1> at C<r = 0> and C<s = 0>
at C<r = INF>. The default rate of decrease is C<power = 1>. Thus, for
every unit change in C<r>, saturation is decreased by 50%. Use the
C<power> option to change the rate of change. In general, saturation
will change by a factor of C<2> for every C<power> units of C<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 C<power = 0>, saturation will be assigned the value it would have at C<r = 0> if C<power E<gt> 0>.
However, keep in mind the effect of C<rmin>, described below.

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

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

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

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

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

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

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

=head2 Value

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

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

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

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

=head1 EXPORT

Exports nothing.

Use L<Color::TupleEncode> and set the encoding method to