PDL::Graphics::Prima::Palette - a set of palettes for the Prima graph widget
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], ) );
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.
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.
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.
This module provides many ready-made palettes with short-name constructors in the pal namespace.
pal
Runs from red->orange->yellow->green->blue->purple in ascending order.
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)
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.
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.
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);
Like WhiteToHSV, but smaller values are closer to black instead of white.
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, );
David Mertens (dcmertens.perl@gmail.com)
Here is the full list of modules in this distribution:
Defines the Plot widget for use in Prima applications
Specifies the behavior of axes (but not the scaling)
Specifies the behavior of DataSets
Defines the lm:: namespace
Specifies a collection of different color palettes
Defines the different ways to visualize your data
Encapsulates all interaction with the Term::ReadLine family of modules.
Specifies different kinds of scaling, including linear and logarithmic
Defines a number of useful functions for generating simple and not-so-simple plots
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.
To install PDL::Graphics::Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDL::Graphics::Prima
CPAN shell
perl -MCPAN -e shell install PDL::Graphics::Prima
For more information on module installation, please visit the detailed CPAN module installation guide.