/ 
PDL-Graphics-Prima-0.17
River stage zero No dependents
/ PDL::Graphics::Prima::Palette

NAME

PDL::Graphics::Prima::Palette - a set of palettes for the Prima graph widget

DESCRIPTION

Suppose you want to use color to convey some meaningful value. For example, you want the color to represent the topography of a landscape, darker is lower, lighter is higher. In that case, you need a mapping from a height to a color, i.e. from a scalar value to a color. This is what palettes provide.

If all you need is basic palette, you can use one of the palette builders provided below. That said, creating custom color palettes, when you have some idea of what you're doing and a simple means for doing so, is a lot of fun. This, for example, creates a palette that runs from black to red. You could just use pal::BlackToHSV, but what's the fun in that?

my $palette = PDL::Graphics::Prima::Palette->new(
    apply => sub {
        my $data = shift;
        my ($min, $max) = $data->minmax;
        
        # Build the rgb piddle
        my $rgb = zeroes(3, $data->dims);
        $rgb->slice("0") .= (($data->double - $min) / ($max - $min)) * 255;
        
        # Convert to Prima colors
        return $rgb->rgb_to_color;
    }
);

Applying the palette to some data simply calls the subref that your provided earlier:

my $colors = $palette->apply($some_data);

Using this with a standard palette builder is pretty easy, too:

my $colors = pal::Rainbow->apply($some_data);

And, you can provide the palette to customize how pgrid::Matrix colorizes its data:

plot(
    -data => ds::Grid( $matrix,
        plotType => pgrid::Matrix(palette => $palette),
        bounds => [0, 0, 1, 1],
    )
);

new

Accepts key/value pairs. The only required key is the apply key, which should have a coderef that accepts a data piddle and performs the data-to-color conversion, returning a piddle of Prima colors.

apply

Every palette knows how to apply itself to its data. The apply function returns a piddle of Prima color values given a piddle of scalar values.

plotType

Every Palette knows the specific data and plot type to which it belongs. The first time that a Palette is used in a drawing operation, it will become associated with that specific plotType object, which is in turn associated with that specific dataSet and widget. Thereafter, you can retrieve the plotType object using this accessor, but you cannot change it. If you want to use the same Palette with a different plotType, you can create a copy of your palette using the "copy" method.

copy

You can make a copy of a Palette that is identical to your current pallete except that it does not have an associated plotType. This way, if you put a lot of effort into making a palette, you can easily reuse that palette with minimal effort.

Note that this mechanism does not perform a deep copy, and any nested data structures will be copied by reference to the new palette object.

Special Palettes

This module provides many ready-made palettes with short-name constructors in the pal namespace.

pal::Rainbow

Runs from red->orange->yellow->green->blue->purple in ascending order.

pal::RainbowSV

Runs from red->orange->yellow->green->blue->purple in ascending order. The two arguments it accepts are the saturation and value, which it holds uniformly. This makes it much easier to create palettes that can be easily seen against a white background. For example, the yellow from this palette is much eaiser to see against a white background than the yellow from pal::Rainbow:

pal::RainbowSV(1, 0.8)
pal::BlackToWhite

Larger values are white, smaller values are black. The optional argument is the gamma exponent correction value, which should be positive. Typically, gamma exponents are near 0.5.

pal::WhiteToBlack

Larger values are black, smaller values are white. The optional argument is the gamma exponent correction value, which should be positive. Typically, gamma exponents are near 0.5.

pal::WhiteToHSV

Smaller values are closer to white, larger values are closer to the color indicated by the HSV values that you specify, which are supplied to the function as three different scalars. The first three arguments are hue, saturation, and value. The optional fourth value is a gamma correction exponent.

For example:

my $white_to_red = pal::WhiteToHSV(0, 1, 1);
my $gamma_white_to_red = pal::WhiteToHSV(0, 1, 1, 0.8);
pal::BlackToHSV

Like WhiteToHSV, but smaller values are closer to black instead of white.

pal::HSVrange

Maps data in ascending order from the start to the stop values in hue, saturation, and value. You can specify the initial and final hue, saturation, and value in one of two ways: (1) a pair of three-element arrayrefs/piddles with the initial and final hsv values, or (3) a set of key/value pairs describing the initial and final hue, saturation and value.

For example, this creates a palette that runs from red (H=360) to blue (H=240):

my $blue_to_red = pal::HSVrange([360, 1, 1] => [240, 1, 1]);

If you know the Prima name of your color, you can use the conversion functions provided by PDL::Drawing::Prima::Utils to build an HSV range. This example produces a palette from blue to red:

my $blue_hsv = pdl(cl::LightBlue)->color_to_rgb->rgb_to_hsv;
my $red_hsv = pdl(cl::LightRed)->color_to_rgb->rgb_to_hsv;
my $blue_to_red = pal::HSVrange($blue_hsv, $red_hsv);

The final means for specifying a range in HSV space is to provide key/value pairs that describe your initial and final points in HSV space. You can also specify a non-unitary gamma correction exponent. For example, to go from blue to red with a gamma of 0.8, you could say:

my $blue_to_red = pal::HSVrange(
      h_start => 240,
      s_start => 1,
      v_start => 1,
      h_stop  => 360,
      s_stop  => 1,
      v_stop  => 1,
      gamma   => 0.8,
  );

However, you do not need to provide all of these values. Any key that you do not supply will use a default value:

Key       Default
-----------------
h_start   0
s_start   1
v_start   1
h_stop    360
s_stop    1
v_stop    1
gamma     1

So the blue-to-red palette, without a gamma correction, could be specified as:

my $blue_to_red = pal::HSVrange(
    h_start => 240, h_stop => 360,
);

AUTHOR

David Mertens (dcmertens.perl@gmail.com)

ADDITIONAL MODULES

Here is the full list of modules in this distribution:

PDL::Graphics::Prima

Defines the Plot widget for use in Prima applications

PDL::Graphics::Prima::Axis

Specifies the behavior of axes (but not the scaling)

PDL::Graphics::Prima::DataSet

Specifies the behavior of DataSets

PDL::Graphics::Prima::Limits

Defines the lm:: namespace

PDL::Graphics::Prima::Palette

Specifies a collection of different color palettes

PDL::Graphics::Prima::PlotType

Defines the different ways to visualize your data

PDL::Graphics::Prima::ReadLine

Encapsulates all interaction with the Term::ReadLine family of modules.

PDL::Graphics::Prima::Scaling

Specifies different kinds of scaling, including linear and logarithmic

PDL::Graphics::Prima::Simple

Defines a number of useful functions for generating simple and not-so-simple plots

LICENSE AND COPYRIGHT

Unless otherwise stated, all contributions in code and documentation are copyright (c) their respective authors, all rights reserved.

Portions of this module's code are copyright (c) 2011 The Board of Trustees at the University of Illinois.

Portions of this module's code are copyright (c) 2011-2013 Northwestern University.

Portions of this module's code are copyright (c) 2013-2014 Dickinson College.

This module's documentation is copyright (c) 2011-2014 David Mertens.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.