PDL::Graphics::PLplot - Object-oriented interface from perl/PDL to the PLPLOT plotting library
use PDL; use PDL::Graphics::PLplot; my $pl = PDL::Graphics::PLplot->new (DEV => "png", FILE => "test.png"); my $x = sequence(10); my $y = $x**2; $pl->xyplot($x, $y); $pl->close;
Only version 5.15.0+ of PLplot is fully supported, due to a C-level API change that is invisible at PDL-level. However, the library does support installation with PLplot 5.13.0+.
For more information on PLplot, see
http://www.plplot.org/
Also see the test file, t/plplot.t in this distribution for some working examples.
If you are annoyed by the long constructor call, consider installing the aliased CPAN package. Using aliased, the above example becomes
aliased
use PDL; use aliased 'PDL::Graphics::PLplot'; my $pl = PLplot->new (DEV => "png", FILE => "test.png"); my $x = sequence(10); # etc, as above
This is the PDL interface to the PLplot graphics library. It provides a familiar 'perlish' Object Oriented interface as well as access to the low-level PLplot commands from the C-API.
The following options are supported. Most options can be used with any function. A few are only supported on the call to 'new'.
Set the color for index 0, the plot background
Set the output device type. To see a list of allowed types, try:
PDL::Graphics::PLplot->new();
PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png');
Set the output file or display. For file output devices, sets the output file name. For graphical displays (like 'xwin') sets the name of the display, eg ('hostname.foobar.com:0')
'xwin'
'hostname.foobar.com:0'
PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png'); PDL::Graphics::PLplot->new(DEV => 'xwin', FILE => ':0');
Set plotting options. See the PLplot documentation for the complete listing of available options. The value of 'OPTS' must be a hash reference, whose keys are the names of the options. For instance, to obtain PostScript fonts with the ps output device, use:
'OPTS'
PDL::Graphics::PLplot->new(DEV => 'ps', OPTS => {drvopt => 'text=1'});
This option is used in conjunction with DEV => 'mem'. This option takes as input a PDL image and allows one to 'decorate' it using PLplot. The 'decorated' PDL image can then be written to an image file using, for example, PDL::IO::Pic. This option may not be available if plplot does not include the 'mem' driver.
DEV => 'mem'
# read in Earth image and draw an equator. my $pl = PDL::Graphics::PLplot->new (MEM => $earth, DEV => 'mem'); my $x = pdl(-180, 180); my $y = zeroes(2); $pl->xyplot($x, $y, BOX => [-180,180,-90,90], VIEWPORT => [0.0, 1.0, 0.0, 1.0], XBOX => '', YBOX => '', PLOTTYPE => 'LINE'); $pl->close;
Set color index 1, the frame color
A flag used to specify equal scale on the axes. If this is not specified, the default is to scale the axes to fit best on the page.
PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png', JUST => 1);
The orientation of the plot:
0 -- 0 degrees (landscape mode) 1 -- 90 degrees (portrait mode) 2 -- 180 degrees (seascape mode) 3 -- 270 degrees (upside-down mode)
Intermediate values (0.2) are acceptable if you are feeling daring.
# portrait orientation PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png', ORIENTATION => 1);
Set the size in pixels of the output page.
# PNG 500 by 600 pixels PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png', PAGESIZE => [500,600]);
Set the number of sub pages in the plot, [$nx, $ny]
# PNG 300 by 600 pixels # Two subpages stacked on top of one another. PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png', PAGESIZE => [300,600], SUBPAGES => [1,2]);
Set the plotting box in world coordinates. Used to explicitly set the size of the plotting area.
my $pl = PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png'); $pl->xyplot ($x, $y, BOX => [0,100,0,200]);
Set the size of text in multiples of the default size. CHARSIZE => 1.5 gives characters 1.5 times the normal size.
CHARSIZE => 1.5
Set the current color for plotting and character drawing. Colors are specified not as color indices but as RGB triples. Some pre-defined triples are included:
BLACK GREEN WHEAT BLUE RED AQUAMARINE GREY BLUEVIOLET YELLOW PINK BROWN CYAN TURQUOISE MAGENTA SALMON WHITE ROYALBLUE DEEPSKYBLUE VIOLET STEELBLUE1 DEEPPINK MAGENTA DARKORCHID1 PALEVIOLETRED2 TURQUOISE1 LIGHTSEAGREEN SKYBLUE FORESTGREEN CHARTREUSE3 GOLD2 SIENNA1 CORAL HOTPINK LIGHTCORAL LIGHTPINK1 LIGHTGOLDENROD
# These two are equivalent: $pl->xyplot ($x, $y, COLOR => 'YELLOW'); $pl->xyplot ($x, $y, COLOR => [0,255,0]);
Control of labels for contour plots.
Must either be 0 (turn off contour labels), 1 (turn on default contour labels) or a five element array:
offset: Offset of label from contour line (if set to 0.0, labels are printed on the lines). Default value is 0.006. size: Font height for contour labels (normalized). Default value is 0.3. spacing: Spacing parameter for contour labels. Default value is 0.1. lexp: If the contour numerical label is greater than 10^(lexp) or less than 10^(-lexp), then the exponential format is used. Default value of lexp is 4. sigdig: Number of significant digits. Default value is 2";
$pl->shadeplot ($z, $nsteps, BOX => [-1, 1, -1, 1], PLOTTYPE => 'CONTOUR', CONTOURLABELS => [0.004, 0.2, 0.2, 4, 2]); $pl->shadeplot ($z, $nsteps, BOX => [-1, 1, -1, 1], PLOTTYPE => 'CONTOUR', CONTOURLABELS => 0); # turn off labels $pl->shadeplot ($z, $nsteps, BOX => [-1, 1, -1, 1], PLOTTYPE => 'CONTOUR', CONTOURLABELS => 1); # use default labels
Set a user-defined grid map. This is an X and Y vector that tells what are the world coordinates for each pixel in $z It is used in 'shadeplot' for non-standard mappings between the input 2D surface to plot and the world coordinates. For example if your surface does not completely fill up the plotting window.
my $z = $surface; # 2D PDL to plot (generated elsewhere) my $nlevels = 20; my ($nx, $ny) = $z->dims; my @zbounds = ($minx, $maxx, $miny, $maxy); # Map X coords linearly to X range, Y coords linearly to Y range my $xmap = ((sequence($nx)*(($zbounds[1] - $zbounds[0])/($nx - 1))) + $zbounds[0]); my $ymap = ((sequence($ny)*(($zbounds[3] - $zbounds[2])/($ny - 1))) + $zbounds[2]); $pl->shadeplot ($z, $nlevels, PALETTE => 'GREENRED', GRIDMAP => [$xmap, $ymap]);
Set a user-defined two dimensional grid map. These are 2D X and Y matrices that tell what are the world coordinates for each pixel in $z It is used in 'shadeplot' for non-standard mappings between the input 2D surface to plot and the world coordinates, for example irregular grids like polar projections.
my $r_pts = 40; my $theta_pts = 40; my $pi = 4*atan2(1,1); my $nlevels = 20; my $r = ((sequence ($r_pts)) / ($r_pts - 1))->dummy (1, $theta_pts); my $z = $r; # or any other 2D surface to plot... my $theta = ((2 * $pi / ($theta_pts - 2)) * sequence ($theta_pts))->dummy (0, $r_pts); my $xmap = $r * cos ($theta); my $ymap = $r * sin ($theta); $pl->shadeplot ($z, $nlevels, PLOTTYPE => 'CONTOUR', JUST => 1, BOX => [-1,1,-1,1], PALETTE => 'GREENRED', GRIDMAP2 => [$xmap, $ymap]);
Set the line width for plotting. Values range from 1 to a device dependent maximum.
Set the line style for plotting. Pre-defined line styles use values 1 to 8, one being a solid line, 2-8 being various dashed patterns.
Set the length of major ticks as a fraction of the default setting. One (default) means leave these ticks the normal size.
Set the length of minor ticks (and error bar terminals) as a fraction of the default setting. One (default) means leave these ticks the normal size.
The number of minor tick marks between each major tick mark on the X axis. Specify zero (default) to let PLplot compute this automatically.
The number of minor tick marks between each major tick mark on the Y axis. Specify zero (default) to let PLplot compute this automatically.
Load pre-defined color map 1 color ranges. Currently, values include:
RAINBOW -- from Red to Violet through the spectrum REVERSERAINBOW -- Violet through Red GREYSCALE -- from black to white via grey. REVERSEGREYSCALE -- from white to black via grey. GREENRED -- from green to red REDGREEN -- from red to green
# Plot x/y points with the z axis in color $pl->xyplot ($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z);
Specify which type of XY or shade plot is desired:
LINE -- A line POINTS -- A bunch of symbols LINEPOINTS -- both or, for 'shadeplot': CONTOUR -- A contour plot of 2D data SHADE -- A shade plot of 2D data
For 'bargraph', request a stacked bar chart. Must contain a reference to a perl list of color names or RGB triples.
# $labels is a reference to a perl array with N x-axis labels # $values is an NxM PDL where M is the number of stacked bars (in this case 2, # since STACKED_BAR_COLORS contains two colors). $pl->bargraph($labels, $values, STACKED_BAR_COLORS => ['GREEN', [128,0,55]);
Set which subpage to plot on. Subpages are numbered 1 to N. A zero can be specified meaning 'advance to the next subpage' (just a call to pladv()).
my $pl = PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png', SUBPAGES => [1,2]); $pl->xyplot ($x, $y, SUBPAGE => 1); $pl->xyplot ($a, $b, SUBPAGE => 2);
Specify which symbol to use when plotting PLOTTYPE => 'POINTS'. A large variety of symbols are available, see: http://plplot.sourceforge.net/examples-data/demo07/x07.*.png, where * is 01 - 17. You are most likely to find good plotting symbols in the 800s: http://plplot.sourceforge.net/examples-data/demo07/x07.06.png
PLOTTYPE => 'POINTS'
Specify the size of symbols plotted in multiples of the default size (1). Value are real numbers from 0 to large.
Specify the placement of text. Either relative to border, specified as:
[$side, $disp, $pos, $just]
Where
side = 't', 'b', 'l', or 'r' for top, bottom, left and right disp is the number of character heights out from the edge pos is the position along the edge of the viewport, from 0 to 1. just tells where the reference point of the string is: 0 = left, 1 = right, 0.5 = center.
or inside the plot window, specified as:
[$x, $y, $dx, $dy, $just]
x = x coordinate of reference point of string. y = y coordinate of reference point of string. dx Together with dy, this specifies the inclination of the string. The baseline of the string is parallel to a line joining (x, y) to (x+dx, y+dy). dy Together with dx, this specifies the inclination of the string. just Specifies the position of the string relative to its reference point. If just=0, the reference point is at the left and if just=1, it is at the right of the string. Other values of just give intermediate justifications.
# Plot text on top of plot $pl->text ("Top label", TEXTPOSITION => ['t', 4.0, 0.5, 0.5]); # Plot text in plotting area $pl->text ("Line label", TEXTPOSITION => [50, 60, 5, 5, 0.5]);
Add a title on top of a plot.
# Plot text on top of plot $pl->xyplot ($x, $y, TITLE => 'X vs. Y');
For 'bargraph', if set to true then plot the bars as outlines in the current color and not as filled boxes
# Plot text on top of plot $pl->bargraph($labels, $values, UNFILLED_BARS => 1);
Set the location of the plotting window on the page. Takes a four element array ref specifying:
xmin -- The coordinate of the left-hand edge of the viewport. (0 to 1) xmax -- The coordinate of the right-hand edge of the viewport. (0 to 1) ymin -- The coordinate of the bottom edge of the viewport. (0 to 1) ymax -- The coordinate of the top edge of the viewport. (0 to 1)
You will need to use this to make color keys or insets.
# Make a small plotting window in the lower left of the page $pl->xyplot ($x, $y, VIEWPORT => [0.1, 0.5, 0.1, 0.5]); # Also useful in creating color keys: $pl->xyplot ($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z); $pl->colorkey ($z, 'v', VIEWPORT => [0.93, 0.96, 0.15, 0.85]); # Plot an inset; first the primary data and then the inset. In this # case, the inset contains a selection of the orignal data $pl->xyplot ($x, $y); $pl->xyplot (where($x, $y, $x < 1.2), VIEWPORT => [0.7, 0.9, 0.6, 0.8]);
Specify how to label the X axis of the plot as a string of option letters:
a: Draws axis, X-axis is horizontal line (y=0), and Y-axis is vertical line (x=0). b: Draws bottom (X) or left (Y) edge of frame. c: Draws top (X) or right (Y) edge of frame. d: Plot labels as date / time. Values are assumed to be seconds since the epoch (as used by gmtime). f: Always use fixed point numeric labels. g: Draws a grid at the major tick interval. h: Draws a grid at the minor tick interval. i: Inverts tick marks, so they are drawn outwards, rather than inwards. l: Labels axis logarithmically. This only affects the labels, not the data, and so it is necessary to compute the logarithms of data points before passing them to any of the drawing routines. m: Writes numeric labels at major tick intervals in the unconventional location (above box for X, right of box for Y). n: Writes numeric labels at major tick intervals in the conventional location (below box for X, left of box for Y). s: Enables subticks between major ticks, only valid if t is also specified. t: Draws major ticks.
The default is 'BCNST' which draws lines around the plot, draws major and minor ticks and labels major ticks.
'BCNST'
# plot two lines in a box with independent X axes labeled # differently on top and bottom $pl->xyplot($x1, $y, XBOX => 'bnst', # bottom line, bottom numbers, ticks, subticks YBOX => 'bnst'); # left line, left numbers, ticks, subticks $pl->xyplot($x2, $y, XBOX => 'cmst', # top line, top numbers, ticks, subticks YBOX => 'cst', # right line, ticks, subticks BOX => [$x2->minmax, $y->minmax]);
Used only with "xyplot". Draws horizontal error bars at all points ($x, $y) in the plot. Specify a PDL containing the same number of points as $x and $y which specifies the width of the error bar, which will be centered at ($x, $y).
$x
$y
Specify a label for the X axis.
Interval (in graph units/world coordinates) between major x axis tick marks. Specify zero (default) to allow PLplot to compute this automatically.
Specify how to label the Y axis of the plot as a string of option letters. See "XBOX".
Used only for xyplot. Draws vertical error bars at all points ($x, $y) in the plot. Specify a PDL containing the same number of points as $x and $y which specifies the width of the error bar, which will be centered at ($x, $y).
Specify a label for the Y axis.
Interval (in graph units/world coordinates) between major y axis tick marks. Specify zero (default) to allow PLplot to compute this automatically.
For "xyplot" (when COLORMAP is specified), for "shadeplot" and for "colorkey". Normally, the range of the Z variable (color) is taken as $z->minmax. If a different range is desired, specify it in ZRANGE, like so:
COLORMAP
$z->minmax
ZRANGE
$pl->shadeplot ($z, $nlevels, PALETTE => 'GREENRED', ZRANGE => [0,100]);
or
$pl->xyplot ($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z, ZRANGE => [-90,-20]); $pl->colorkey ($z, 'v', VIEWPORT => [0.93, 0.96, 0.13, 0.85], ZRANGE => [-90,-20]);
These are the high-level, object oriented methods for PLplot.
Create an object representing a plot.
Arguments: none. Supported options: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES
my $pl = PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png');
Set options for a plot object.
Arguments: none. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES
(These must be set in call to 'new'.)
$pl->setparm (TEXTSIZE => 2);
Plot XY lines and/or points. Also supports color scales for points. This function works with bad values. If a bad value is specified for a points plot, it is omitted. If a bad value is specified for a line plot, the bad value makes a gap in the line. This is useful for drawing maps; for example $x and $y can be the continent boundary latitude and longitude.
Arguments: $x, $y Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES
$pl->xyplot($x, $y, PLOTTYPE => 'POINTS', COLOR => 'BLUEVIOLET', SYMBOL => 1, SYMBOLSIZE => 4); $pl->xyplot($x, $y, PLOTTYPE => 'LINEPOINTS', COLOR => [50,230,30]); $pl->xyplot($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z);
Plot a set of strip plots with a common X axis, but with different Y axes. Looks like a stack of long, thin XY plots, all line up on the same X axis.
Arguments: $xs -- 1D PDL with common X axis values, length = N $ys -- reference to a list of 1D PDLs with Y-axis values, length = N or 2D PDL with N x M elements -- OR -- $xs -- reference to a list of 1D PDLs with X-axis values $ys -- reference to a list of 1D PDLs with Y-axis values %opts -- Options hash Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES
my $x = sequence(20); my $y1 = $x**2; my $y2 = sqrt($x); my $y3 = $x**3; my $y4 = sin(($x/20) * 2 * $pi); $ys = cat($y1, $y2, $y3, $y4); $pl->stripplots($x, $ys, PLOTTYPE => 'LINE', TITLE => 'functions', YLAB => ['x**2', 'sqrt(x)', 'x**3', 'sin(x/20*2pi)'], COLOR => ['GREEN', 'DEEPSKYBLUE', 'DARKORCHID1', 'DEEPPINK'], XLAB => 'X label'); # Equivalent to above: $pl->stripplots($x, [$y1, $y2, $y3, $y4], PLOTTYPE => 'LINE', TITLE => 'functions', YLAB => ['x**2', 'sqrt(x)', 'x**3', 'sin(x/20*2pi)'], COLOR => ['GREEN', 'DEEPSKYBLUE', 'DARKORCHID1', 'DEEPPINK'], XLAB => 'X label'); # Here's something a bit different. Notice that different xs have # different lengths. $x1 = sequence(20); $y1 = $x1**2; $x2 = sequence(18); $y2 = sqrt($x2); $x3 = sequence(24); $y3 = $x3**3; my $x4 = sequence(27); $a = ($x4/20) * 2 * $pi; my $y4 = sin($a); $xs = [$x1, $x2, $x3, $x4]; $ys = [$y1, $y2, $y3, $y4]; $pl->stripplots($xs, $ys, PLOTTYPE => 'LINE', TITLE => 'functions', YLAB => ['x**2', 'sqrt(x)', 'x**3', 'sin(x/20*2pi)'], COLOR => ['GREEN', 'DEEPSKYBLUE', 'DARKORCHID1', 'DEEPPINK'], XLAB => 'X label');
In addition, COLOR may be specified as a reference to a list of colors. If this is done, the colors are applied separately to each plot.
Also, the options Y_BASE and Y_GUTTER can be specified. Y_BASE gives the Y offset of the bottom of the lowest plot (0-1, specified like a VIEWPORT, defaults to 0.1) and Y_GUTTER gives the gap between the graphs (0-1, default = 0.02).
Plot a color key showing which color represents which value
Arguments: $range : A PDL which tells the range of the color values $orientation : 'v' for vertical color key, 'h' for horizontal Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES
# Plot X vs. Y with Z shown by the color. Then plot # vertical key to the right of the original plot. $pl->xyplot ($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z); $pl->colorkey ($z, 'v', VIEWPORT => [0.93, 0.96, 0.15, 0.85]);
Create a shaded contour plot of 2D PDL 'z' with 'nsteps' contour levels. Linear scaling is used to map the coordinates of Z(X, Y) to world coordinates via the "BOX" option.
Arguments: $z : A 2D PDL which contains surface values at each XY coordinate. $nsteps : The number of contour levels requested for the plot. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES
# vertical key to the right of the original plot. # The BOX must be specified to give real coordinate values to the $z array. $pl->shadeplot ($z, $nsteps, BOX => [-1, 1, -1, 1], PALETTE => 'RAINBOW', ZRANGE => [0,100]); $pl->colorkey ($z, 'v', VIEWPORT => [0.93, 0.96, 0.15, 0.85], ZRANGE => [0,100]);
Create a histogram of a 1-D variable.
Arguments: $x : A 1D PDL $nbins : The number of bins to use in the histogram. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES
$pl->histogram ($x, $nbins, BOX => [$min, $max, 0, 100]);
Create a histogram of a 1-D variable. This alternative to 'histogram' creates filled boxes and also handles Y-axis scaling better.
$pl->histogram1 ($x, $nbins, COLOR => 'GREEN');
Simple utility to plot a bar chart with labels on the X axis. The usual options can be specified, plus one other: MAXBARLABELS specifies the maximum number of labels to allow on the X axis. The default is 20. If this value is exceeded, then every other label is plotted. If twice MAXBARLABELS is exceeded, then only every third label is printed, and so on.
if UNFILLED_BARS is set to true, then plot the bars as outlines and not as filled rectangles.
A stacked bar graph can be created if the STACKED_BAR_COLORS option is set. The option takes a reference to a perl list of color names or RGB triplets. If this option is set, then $x should not be a 1-D PDL of N bar heights, but a 2D PDL of NxM where N is the number of bars and M is the number of colors in STACKED_BAR_COLORS.
Arguments: $labels -- A reference to a perl list of strings. $values -- A PDL of values to be plotted. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES
$labels = ['one', 'two', 'three']; $values = pdl(1, 2, 3); # Note if TEXTPOSITION is specified, it must be in 4 argument mode (border mode): # [$side, $disp, $pos, $just] # # Where side = 't', 'b', 'l', or 'r' for top, bottom, left and right # 'tv', 'bv', 'lv' or 'rv' for top, bottom, left or right perpendicular to the axis. # # disp is the number of character heights out from the edge # pos is the position along the edge of the viewport, from 0 to 1. # just tells where the reference point of the string is: 0 = left, 1 = right, 0.5 = center. # # The '$pos' entry will be ignored (computed by the bargraph routine) $pl->bargraph($labels, $values, MAXBARLABELS => 30, TEXTPOSITION => ['bv', 0.5, 1.0, 1.0]); # A stacked bar chart: $labels = ['label1', 'label2', 'label3']; $values = pdl([[50,40,60], # green bars [20,10,30]]); # purple ([128, 0, 56]) bars $pl->bargraph ($labels, $values, STACKED_BAR_COLORS => ['GREEN', [128, 0, 56]])
Write text on a plot. Text can either be written with respect to the borders or at an arbitrary location and angle (see the "TEXTPOSITION" entry).
Arguments: $t : The text. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES
$pl->text("Count", COLOR => 'PINK', TEXTPOSITION => ['t', 3, 0.5, 0.5]); # top, 3 units out, string ref. pt in # center of string, middle of axis
Close a PLplot object, writing out the file and cleaning up.
Arguments: None
Returns: Nothing
This closing of the PLplot object can be done explicitly though the 'close' method. Alternatively, a DESTROY block does an automatic close whenever the PLplot object passes out of scope.
$pl->close;
The PDL low-level interface to the PLplot library closely mimics the C API. Users are referred to the PLplot User's Manual, distributed with the source PLplot tarball. This manual is also available on-line at the PLplot web site (http://www.plplot.org/).
There are three differences in the way the functions are called. The first one is due to a limitation in the pp_def wrapper of PDL, which forces all the non-ndarray arguments to be at the end of the arguments list. It is the case of strings (char *) arguments in the C API. This affects the following functions:
char *
plaxes plbox plbox3 plmtex plmtex3 plstart plstripc plmap plmeridians plshades plshade1
This difference can be got around by a call to
plplot_use_standard_argument_order(1);
This re-arranges the string arguments to their proper/intuitive position compared with the C plplot interface. This can be restored to its default by calling:
plplot_use_standard_argument_order(0);
The second notable different between the C and the PDL APIs is that many of the PDL calls do not need arguments to specify the size of the the vectors and/or matrices being passed. These size parameters are deduced from the size of the ndarrays, when possible and are just omitted from the C call when translating it to perl.
The third difference has to do with output parameters. In C these are passed in with the input parameters. In the perl interface, they are omitted. For example:
C:
pllegend(&p_legend_width, &p_legend_height, opt, position, x, y, plot_width, bg_color, bb_color, bb_style, nrow, ncolumn, nlegend, opt_array, text_offset, text_scale, text_spacing, text_justification, text_colors, (const char **)text, box_colors, box_patterns, box_scales, box_line_widths, line_colors, line_styles, line_widths, symbol_colors, symbol_scales, symbol_numbers, (const char **)symbols);
perl:
my ($legend_width, $legend_height) = pllegend ($position, $opt, $x, $y, $plot_width, $bg_color, $nlegend, \@opt_array, $text_offset, $text_scale, $text_spacing, $test_justification, \@text_colors, \@text, \@box_colors, \@box_patterns, \@box_scales, \@line_colors, \@line_styles, \@line_widths, \@symbol_colors, \@symbol_scales, \@symbol_numbers, \@symbols);
Some of the API functions implemented in PDL have other specificities in comparison with the C API and will be discussed below.
Signature: (int page())
info not available
pladv does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xzero();double yzero();double xtick();int nxsub();double ytick();int nysub(); char *xopt;char *yopt)
plaxes does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int nbin();double x(dima);double y(dima);int center())
plbin does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xtick();int nxsub();double ytick();int nysub(); char *xopt;char *yopt)
plbox does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xtick();int nsubx();double ytick();int nsuby();double ztick();int nsubz(); char *xopt;char *xlabel;char *yopt;char *ylabel;char *zopt;char *zlabel)
plbox3 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int icolzero())
plcol0 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double colone())
plcol1 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int iplsr();int flags())
plcpstrm does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xmin(dima);double ymin(dima);double xmax(dima);double ymax(dima))
pldid2pc does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
pldip2dc does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xmin();double xmax();double ymin();double ymax();int just();int axis())
plenv does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plenv0 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int n();double xmin(dima);double xmax(dima);double y(dima))
plerrx does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int n();double x(dima);double ymin(dima);double ymax(dima))
plerry does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int n();double x(dima);double y(dima);double z(dima))
plfill3 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int ifont())
plfont does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int fnt())
plfontld does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double [o]p_def();double [o]p_ht())
plgchr does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int [o]compression())
plgcompression does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double [o]p_mar();double [o]p_aspect();double [o]p_jx();double [o]p_jy())
plgdidev does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double [o]p_rot())
plgdiori does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double [o]p_xmin();double [o]p_ymin();double [o]p_xmax();double [o]p_ymax())
plgdiplt does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int [o]p_fam();int [o]p_num();int [o]p_bmax())
plgfam does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int [o]p_level())
plglevel does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double [o]p_xp();double [o]p_yp();int [o]p_xleng();int [o]p_yleng();int [o]p_xoff();int [o]p_yoff())
plgpage does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double [o]xmin();double [o]xmax();double [o]ymin();double [o]ymax())
plgspa does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double [o]p_xmin();double [o]p_xmax();double [o]p_ymin();double [o]p_ymax())
plgvpd does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plgvpw does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int [o]p_digmax();int [o]p_digits())
plgxax does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plgyax does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plgzax does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xone();double yone();double xtwo();double ytwo())
pljoin does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double x();double y();double z())
pllightsource does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int lin())
pllsty does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double disp();double pos();double just(); char *side;char *text)
plmtex does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plmtex3 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int nlin();int inc(dima);int del(dima))
plpat does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int setp();int prec())
plprec does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int patt())
plpsty does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double x();double y();double dx();double dy();double just(); char *text)
plptex does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double x();double y();double z();double dx();double dy();double dz();double sx();double sy();double sz();double just(); char *text)
plptex3 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double def();double scale())
plschr does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int ncolzero())
plscmap0n does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int ncolone())
plscmap1n does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int icolzero();int r();int g();int b())
plscol0 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int r();int g();int b())
plscolbg does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int color())
plscolor does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int compression())
plscompression does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
$devices = plgDevs ()
Returns a HashRef of all device names (key) and their menu strings (value).
$devices = plgFileDevs ()
Returns a HashRef of file-oriented device names (key) and their menu strings (value).
Signature: (double mar();double aspect();double jx();double jy())
plsdidev does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int dimxmin();int dimxmax();int dimymin();int dimymax();double dimxpmm();double dimypmm())
plsdimap does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double rot())
plsdiori does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xmin();double ymin();double xmax();double ymax())
plsdiplt does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plsdiplz does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double offset();double size();double spacing();int active())
pl_setcontlabelparam does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int lexp();int sigdig())
pl_setcontlabelformat does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int fam();int num();int bmax())
plsfam does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plsmaj does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plsmin does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int ori())
plsori does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xp();double yp();int xleng();int yleng();int xoff();int yoff())
plspage does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int pause())
plspause does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int strm())
plsstrm does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int nx();int ny())
plssub does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plssym does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plstar does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int nx();int ny(); char *devname)
plstart does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int id();int pen();double x();double y())
plstripa does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int id())
plstripd does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xmin();double xmax();double ymin();double ymax())
plsvpa does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int digmax();int digits())
plsxax does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int window_id())
plsxwin does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plsyax does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plszax does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double aspect())
plvasp does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xmin();double xmax();double ymin();double ymax();double aspect())
plvpas does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plvpor does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double basex();double basey();double height();double xminzero();double xmaxzero();double yminzero();double ymaxzero();double zminzero();double zmaxzero();double alt();double az())
plw3d does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int width())
plwidth does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plwind does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double p_x(dima);double p_y(dima))
plP_gpixmm does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int r();int g();int b();double a())
plscolbga does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int icolzero();int r();int g();int b();double a())
plscol0a does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(n); y(n))
Draws line segments along (x1,y1)->(x2,y2)->(x3,y3)->...
If the nth value of either x or y are bad, then it will be skipped, breaking the line. In this way, you can specify multiple line segments with a single pair of x and y ndarrays.
The usage is straight-forward:
plline($x, $y);
For example:
# Draw a sine wave $x = sequence(100)/10; $y = sin($x); # Draws the sine wave: plline($x, $y); # Set values above 3/4 to 'bad', effectively drawing a bunch of detached, # capped waves $y->setbadif($y > 3/4); plline($x, $y);
plline processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int n(); x1(); x2(); y1(); y2())
plpath ignores the bad-value flag of the input ndarrays. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(n); y(n); z(n); int sym(); minz(); maxz())
PDL-specific: Implements what amounts to a threaded version of plsym.
Bad values for z are simply skipped; all other bad values are not processed.
In the following usage, all of the ndarrays must have the same dimensions:
plcolorpoints($x, $y, $z, $symbol_index, $minz, $maxz)
# Generate a parabola some points my $x = sequence(30) / 3; # Regular sampling my $y = $x**2; # Parabolic y my $z = 30 - $x**3; # Cubic coloration my $symbols = floor($x); # Use different symbols for each 1/3 of the plot # These should be integers. plcolorpoints($x, $y, $z, $symbols, -5, 20); # Thread over everything plcolorpoints($x, $y, 1, 1, -1, 2); # same color and symbol for all
plcolorpoints processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int maxx();int maxy();image(3,x,y))
plsmem does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (xo(); yo())
Box drawing primitive, taken from PLPLOT bar graph example
plfbox does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (xo(); yo(); bh(); w())
Box drawing primitive that allows specifying base height and width in addition to offset and height
plfbox1 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Similar box drawing primitive, but without fill (just draw outline of box)
plunfbox does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plunfbox1 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int [o] retval(); SV* argv; int mode)
Parse PLplot options given in @ARGV-like arrays
plParseOpts does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(n); y(n); int code())
Plots a character at the specified points
plpoin does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(n); y(n); z(n); int code())
Plots a character at the specified points in 3 space
plpoin3 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(n); y(n); z(n))
Draw a line in 3 space
plline3 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(n); y(n); z(n); int draw(m); int ifcc())
Draws a polygon in 3 space
plpoly3 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (data(n); datmin(); datmax(); int nbin(); int oldwin())
Plot a histogram from unbinned data
plhist does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Area fill
plfill does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(n); y(n); angle())
Area fill with color gradient
plgradient does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Plots a symbol at the specified points
plsym does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(nx); y(ny); z(nx,ny); int opt(); clevel(nlevel))
Plot shaded 3-d surface plot
plsurf3d does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(nx); y(ny); z(nx,ny); int opt(); clevel(nlevel); int indexxmin(); int indexxmax(); int indexymin(nx); int indexymax(nx))
Plot shaded 3-d surface plot with limits
plsurf3dl does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int mark(nms); int space(nms))
Set line style
plstyl does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int seed())
plseed does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double [o]rand())
plrandd does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xg(nx); double yg(ny); indx [o] grid())
Allocates a PLcGrid object for use in pltr1
plAllocGrid does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double xg(nx,ny); double yg(nx,ny); indx [o] grid())
Allocates a PLcGrid2 object for use in pltr2
plAlloc2dGrid does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (P(); C(); SV* p0; SV* p1; SV* p2)
Used internally to set the variables pltr{0,1,2}_iv to the "pointers" of the Perl subroutines pltr{1,2,3}. These variables are later used by get_standard_pltrcb to provide the pointers to the C function pltr{0,1,2}. This accelerates functions like plcont and plshades when those standard transformation functions are used.
pltr{0,1,2}_iv
pltr{1,2,3}
get_standard_pltrcb
pltr{0,1,2}
init_pltr does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (minlong(); maxlong(); minlat(); maxlat(); SV* mapform; char* type)
plot continental outline in world coordinates
plmap does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(na); y(na); char* string)
plot a string along a line
plstring does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(na); y(na); z(na); char* string)
plot a string along a 3D line
plstring3 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (dlong(); dlat(); minlong(); maxlong(); minlat(); maxlat(); SV* mapform)
Plot the latitudes and longitudes on the background
plmeridians does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (z(x,y); xmin(); xmax(); ymin(); ymax(); clevel(l); int fill_width(); int cont_color(); int cont_width(); int rectangular(); SV* defined; SV* pltr; SV* pltr_data)
Shade regions on the basis of value
plshades does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (f(nx,ny); int kx(); int lx(); int ky(); int ly(); clevel(nlevel); SV* pltr; SV* pltr_data)
Plot contours
plcont does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(nx); y(ny); z(nx,ny); int opt())
Surface mesh
plmesh does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Magnitude colored plot surface mesh with contour
plmeshc does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(nx); y(ny); z(nx,ny); int opt(); int side())
3-d surface plot
plot3d does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Plots a 3-d representation of the function z[x][y] with contour
plot3dc does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int itype(); isty(n); coord1(n); coord2(n); coord3(n); int rev(nrev))
Set color map1 colors using a piece-wise linear relationship
plscmap1l does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (a(nx,ny); left(); right(); bottom(); top(); shade_min();shade_max(); sh_cmap(); sh_color(); sh_width();min_color(); min_width(); max_color(); max_width();rectangular(); SV* defined; SV* pltr; SV* pltr_data)
Shade individual region on the basis of value
plshade1 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (idata(nx,ny); xmin(); xmax(); ymin(); ymax();zmin(); zmax(); Dxmin(); Dxmax(); Dymin(); Dymax())
Plot gray-level image
plimage does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (idata(nx,ny); xmin(); xmax(); ymin(); ymax();zmin(); zmax(); valuemin(); valuemax(); SV* pltr; SV* pltr_data)
Plot image with transformation
plimagefr does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
$status = plxormod ($mode)
Set xor mode: mode = 1-enter, 0-leave, status = 0 if not interactive device
See the PLplot manual for reference.
%gin = plGetCursor ()
plGetCursor waits for graphics input event and translate to world coordinates and returns a hash with the following keys:
type: of event (CURRENTLY UNUSED) state: key or button mask keysym: key selected button: mouse button selected subwindow: subwindow (alias subpage, alias subplot) number string: translated string pX, pY: absolute device coordinates of pointer dX, dY: relative device coordinates of pointer wX, wY: world coordinates of pointer
Returns an empty hash if no translation to world coordinates is possible.
$strm = plgstrm ()
Returns the number of the current output stream.
$driver = plgdev ()
Returns the current driver name.
$strm = plmkstrm ()
Creates a new stream and makes it the default. Returns the number of the created stream.
$version = plgver ()
Get the current library version number
Signature: (xmin(); xmax(); xjump(); ymin(); ymax();xlpos(); ylpos(); int y_ascl(); int acc();int colbox(); int collab();int colline(n); int styline(n);int [o] id(); char* xspec; char* yspec; SV* legline;char* labx; char* laby; char* labtop)
FIXME: documentation here!
plstripc does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (x(npts); y(npts); z(npts); xg(nptsx); yg(nptsy);int type(); data(); [o] zg(nptsx,nptsy))
plgriddata does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plarc ($x, $y, $a, $b, $angle1, $angle2, $rotate, $fill);
Draw a (possibly) filled arc centered at x, y with semimajor axis a and semiminor axis b, starting at angle1 and ending at angle2. See the PLplot manual for reference.
plstransform ($subroutine_reference, $data);
Sets the default transformation routine for plotting.
sub mapform { my ($x, $y, $data) = @_; my $radius = 90.0 - $y; my $xp = $radius * cos ($x * pi / 180); my $yp = $radius * sin ($x * pi / 180); return ($xp, $yp); } plstransform (\&mapform, undef);
See the PLplot manual for more details.
plslabelfunc ($subroutine_reference);
# A custom axis labeling function for longitudes and latitudes. sub geolocation_labeler { my ($axis, $value, $length) = @_; my ($direction_label, $label_val); if (($axis == PL_Y_AXIS) && $value == 0) { return "Eq"; } elsif ($axis == PL_Y_AXIS) { $label_val = $value; $direction_label = ($label_val > 0) ? " N" : " S"; } elsif ($axis == PL_X_AXIS) { my $times = floor((abs($value) + 180.0 ) / 360.0); $label_val = ($value < 0) ? $value + 360.0 * $times : $value - 360.0 * $times; $direction_label = ($label_val > 0) ? " E" : ($label_val < 0) ? " W" : ""; } return substr (sprintf ("%.0f%s", abs($label_val), $direction_label), 0, $length); } plslabelfunc(\&geolocation_labeler);
The PDL version of plslabelfunc only has one argument--the perl subroutine to do the label translation:
my $labeltext = perl_labelfunc($axis, $value, $length);
No 'data' argument is used, it is assumed that global data or a closure containing necessary data can be used in 'perl_labelfunc'.
plspal0($filename);
Set color palette 0 from the input .pal file. See the PLplot manual for more details.
plspal1($filename);
Set color palette 1 from the input .pal file. See the PLplot manual for more details.
my ($year, $month, $day, $hour, $min, $sec) = plbtime($ctime);
Calculate broken-down time from continuous time for current stream.
plconfigtime($scale, $offset1, $offset2, $ccontrol, $ifbtime_offset, $year, $month, $day, $hour, $min, $sec);
Configure transformation between continuous and broken-down time (and vice versa) for current stream.
my $ctime = plctime($year, $month, $day, $hour, $min, $sec);
Calculate continuous time from broken-down time for current stream.
pltimefmt($fmt);
Set format for date / time labels. Labels must be configured to treat values as seconds since the epoch via the XBOX/YBOX flags. $fmt is generally consistent with the POSIX strpformat/strftime flags, but see the PLplot manual for details.
$fmt
plsesc($esc);
Set the escape character for text strings. See the PLplot manual for more details.
Signature: (u(nx,ny); v(nx,ny); scale(); SV* pltr; SV* pltr_data)
Vector field plots
plvect does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (arrowx(npts); arrowy(npts); int fill())
Give zero-length PDLs for arrowx and arrowy to pass NULL to PLplot func.
plsvect does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double h();double l();double s();double [o]p_r();double [o]p_g();double [o]p_b())
plhlsrgb does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int icolzero(); int [o]r(); int [o]g(); int [o]b())
plgcol0 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int [o]r(); int [o]g(); int [o]b())
plgcolbg does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int r(n); int g(n); int b(n))
plscmap0 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plscmap1 does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int icolzero(); int [o]r(); int [o]g(); int [o]b(); double [o]a())
plgcol0a does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int [o]r(); int [o]g(); int [o]b(); double [o]a())
plgcolbga does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int r(n); int g(n); int b(n); double a(n))
plscmap0a does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
plscmap1a does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int itype(); isty(n); coord1(n); coord2(n); coord3(n); coord4(n); int rev(nrev))
Set color map1 colors using a piece-wise linear relationship, include alpha channel
plscmap1la does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int [o]p_family(); int [o]p_style(); int [o]p_weight())
plgfont does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (int family(); int style(); int weight())
plsfont does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
Signature: (double rx(); double ry(); double [o]wx(); double [o]wy(); int [o]window())
plcalc_world does not process bad values. It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
pl_cmd($CMD, $data);
See the PLplot manual for reference. Gives access to low level driver. $CMD is an integer. $data opaque data.
pl_setCairoCtx($cairo_context);
Used with cairo external drivers to set the cairo context. $cairo_context should be a Cairo::Context object. Uses pl_cmd underneath, but extracts the real C struct pointer from the Cairo::Context.
PLplot gives many errors and warnings. Some of these are given by the PDL interface while others are internal PLplot messages. Below are some of these messages, and what you need to do to address them:
Box must be a ref to a four element array
When specifying a box, you must pass a reference to a four-element array, or use an anonymous four-element array.
# Gives trouble: $pl->xyplot($x, $y, BOX => (0, 0, 100, 200) ); # What you meant to say was: $pl->xyplot($x, $y, BOX => [0, 0, 100, 200] );
Too many colors used! (max 15)
Doug Hunt <dhunt@ucar.edu> Rafael Laboissiere <rlaboiss@users.sourceforge.net> David Mertens <mertens2@illinois.edu>
perl(1), PDL(1), http://www.plplot.org/
The other common graphics packages include PDL::PGPLOT and PDL::TriD.
To install PDL::Graphics::PLplot, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDL::Graphics::PLplot
CPAN shell
perl -MCPAN -e shell install PDL::Graphics::PLplot
For more information on module installation, please visit the detailed CPAN module installation guide.