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->line($x, $y); $pl->close; For more information on PLplot, see http://plplot.sourceforge.net Also see the test file, test.pl in this distribution for some working examples. This is the PDL interface to the PLplot graphics library. It is designed to be simple and light weight with a familiar 'perlish' Object Oriented interface. The following options are supported. Most options can be used with any function. A few are only supported on the call to 'new'.

Options used upon creation of a PLplot object (with 'new'):

BACKGROUND
Set the color for index 0, the plot background

DEV
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');

FILE
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') PDL::Graphics::PLplot->new(DEV => 'png', FILE => 'test.png'); PDL::Graphics::PLplot->new(DEV => 'xwin', FILE => ':0');

MEM
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. # 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;

FRAMECOLOR
Set color index 1, the frame color

JUST
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);

ORIENTATION
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);

PAGESIZE
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]);

SUBPAGES
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]); =head2 Options used after initialization (after 'new')

BOX
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]);

CHARSIZE
Set the size of text in multiples of the default size. CHARSIZE => 1.5 gives characters %150 the normal size.

COLOR
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 # These two are equivalent: $pl->xyplot ($x, $y, COLOR => 'YELLOW'); $pl->xyplot ($x, $y, COLOR => [0,255,0]);

LINEWIDTH
Set the line width for plotting. Values range from 1 to a device dependent maximum.

LINESTYLE
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.

MAJTICKSIZE
Set the length of major ticks as a fraction of the default setting. One (default) means leave these ticks the normal size.

MINTICKSIZE
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.

NXSUB
The number of minor tick marks between each major tick mark on the X axis. Specify zero (default) to let PLplot compute this automatically.

NYSUB
The number of minor tick marks between each major tick mark on the Y axis. Specify zero (default) to let PLplot compute this automatically.

PALETTE
Load pre-defined color map 1 color ranges. Currently, values include: RAINBOW -- from Red to Violet through the spectrum GREYSCALE -- from black to white via grey. # Plot x/y points with the z axis in color $pl->xyplot ($x, $y, PALETTE => 'RAINBOW', PLOTTYPE => 'POINTS', COLORMAP => $z);

PLOTTYPE
Specify which type of XY plot is desired: LINE -- A line POINTS -- A bunch of symbols LINEPOINTS -- both

SUBPAGE
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);

SYMBOL
Specify which symbol to use when plotting PLOTTYPE => 'POINTS'. Special plotting symbols range from 0 to 31, 32 - 127 are ASCII characters.

SYMBOLSIZE
Specify the size of symbols plotted in multiples of the default size (1). Value are real numbers from 0 to large.

TEXTPOSITION
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] Where: 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]);

TITLE
Add a title on top of a plot. # Plot text on top of plot $pl->xyplot ($x, $y, TITLE => 'X vs. Y');

VIEWPORT
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) # 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]);

XBOX
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. 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. # 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]);

XERRORBAR
Used only for 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).

XLAB
Specify a label for the X axis.

XTICK
Interval (in graph units/world coordinates) between major x axis tick marks. Specify zero (default) to allow PLplot to compute this automatically.

YBOX
Specify how to label the Y axis of the plot as a string of option letters. See XBOX.

YERRORBAR
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).

YLAB
Specify a label for the Y axis.

YTICK
Interval (in graph units/world coordinates) between major y axis tick marks. Specify zero (default) to allow PLplot to compute this automatically.

new
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');

setparm
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);

xyplot
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--$x and $y can be continent boundary lat and lon, for example. Arguments: $x, $y Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES (These must be set in call to 'new'.) $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);

colorkey
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 (These must be set in call to 'new'.) # 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]);

shadeplot
Create a shaded contour plot of 2D PDL 'z' with 'nsteps' contour levels. Linear scaling is used to map the coordinates of Z(Y, X) to world coordinates via the BOX option. Arguments: $z : A 2D PDL which contains surface values at each XY coordinate. This PDL is stored in Y, X order, as this is how the C code of PLplot requires it. $nsteps : The number of contour levels requested for the plot. Supported options: All options except: BACKGROUND DEV FILE FRAMECOLOR JUST PAGESIZE SUBPAGES (These must be set in call to 'new'.) # 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'); $pl->colorkey ($z, 'v', VIEWPORT => [0.93, 0.96, 0.15, 0.85]);

histogram
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 (These must be set in call to 'new'.) $pl->histogram ($x, $nbins, BOX => [$min, $max, 0, 100]);

text
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 (These must be set in call to 'new'.) $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
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; Doug Hunt, dhunt\@ucar.edu. perl(1), PDL(1), http://plplot.sourceforge.net/

pladv
Signature: (int page()) info not available

plarrows
Signature: (double u(dima);double v(dima);double x(dima);double y(dima);int n();double scale();double dx();double dy()) info not available

plaxes
Signature: (double xzero();double yzero();double xtick();int nxsub();double ytick();int nysub(); char *xopt;char *yopt) info not available

plbin
Signature: (int nbin();double x(dima);double y(dima);int center()) info not available

plbox
Signature: (double xtick();int nxsub();double ytick();int nysub(); char *xopt;char *yopt) info not available

plbox3
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) info not available

plxormod
Signature: (int mode();int status(dima)) info not available

plcol0
Signature: (int icolzero()) info not available

plcol1
Signature: (double colone()) info not available

plcpstrm
Signature: (int iplsr();int flags()) info not available

pldid2pc
Signature: (double xmin(dima);double ymin(dima);double xmax(dima);double ymax(dima)) info not available

pldip2dc
Signature: (double xmin(dima);double ymin(dima);double xmax(dima);double ymax(dima)) info not available

plenv
Signature: (double xmin();double xmax();double ymin();double ymax();int just();int axis()) info not available

plerrx
Signature: (int n();double xmin(dima);double xmax(dima);double y(dima)) info not available

plerry
Signature: (int n();double x(dima);double ymin(dima);double ymax(dima)) info not available

plfill
Signature: (int n();double x(dima);double y(dima)) info not available

plfill3
Signature: (int n();double x(dima);double y(dima);double z(dima)) info not available

plfont
Signature: (int ifont()) info not available

plfontld
Signature: (int fnt()) info not available

plgchr
Signature: (double [o]p_def(dima);double [o]p_ht(dima)) info not available

plgcol0
Signature: (int [o]icolzero();int [o]r(dima);int [o]g(dima);int [o]b(dima)) info not available

plgcolbg
Signature: (int [o]r(dima);int [o]g(dima);int [o]b(dima)) info not available

plgcompression
Signature: (int [o]compression(dima)) info not available

plgdidev
Signature: (double [o]p_mar(dima);double [o]p_aspect(dima);double [o]p_jx(dima);double [o]p_jy(dima)) info not available

plgdiori
Signature: (double [o]p_rot(dima)) info not available

plgdiplt
Signature: (double [o]p_xmin(dima);double [o]p_ymin(dima);double [o]p_xmax(dima);double [o]p_ymax(dima)) info not available

plgfam
Signature: (int [o]p_fam(dima);int [o]p_num(dima);int [o]p_bmax(dima)) info not available

plglevel
Signature: (int [o]p_level(dima)) info not available

plgpage
Signature: (double [o]p_xp(dima);double [o]p_yp(dima);int [o]p_xleng(dima);int [o]p_yleng(dima);int [o]p_xoff(dima);int [o]p_yoff(dima)) info not available

plgspa
Signature: (double [o]xmin(dima);double [o]xmax(dima);double [o]ymin(dima);double [o]ymax(dima)) info not available

plgstrm
Signature: (int [o]p_strm(dima)) info not available

plgxax
Signature: (int [o]p_digmax(dima);int [o]p_digits(dima)) info not available

plgyax
Signature: (int [o]p_digmax(dima);int [o]p_digits(dima)) info not available

plgzax
Signature: (int [o]p_digmax(dima);int [o]p_digits(dima)) info not available

plhist
Signature: (int n();double data(dima);double datmin();double datmax();int nbin();int oldwin()) info not available

plhls
Signature: (double h();double l();double s()) info not available

pljoin
Signature: (double xone();double yone();double xtwo();double ytwo()) info not available

pllightsource
Signature: (double x();double y();double z()) info not available

plline3
Signature: (int n();double x(dima);double y(dima);double z(dima)) info not available

pllsty
Signature: (int lin()) info not available

plmkstrm
Signature: (int p_strm(dima)) info not available

plmtex
Signature: (double disp();double pos();double just(); char *side;char *text) info not available

plpat
Signature: (int nlin();int inc(dima);int del(dima)) info not available

plpoin
Signature: (int n();double x(dima);double y(dima);int code()) info not available

plpoin3
Signature: (int n();double x(dima);double y(dima);double z(dima);int code()) info not available

plpoly3
Signature: (int n();double x(dima);double y(dima);double z(dima);int draw(dima);int ifcc()) info not available

plprec
Signature: (int setp();int prec()) info not available

plpsty
Signature: (int patt()) info not available

plptex
Signature: (double x();double y();double dx();double dy();double just(); char *text) info not available

plrgb
Signature: (double r();double g();double b()) info not available

plrgb1
Signature: (int r();int g();int b()) info not available

plschr
Signature: (double def();double scale()) info not available

plscmap0n
Signature: (int ncolzero()) info not available

plscmap1n
Signature: (int ncolone()) info not available

plscmap0
Signature: (int r(dima);int g(dima);int b(dima);int ncolzero()) info not available

plscmap1
Signature: (int r(dima);int g(dima);int b(dima);int ncolone()) info not available

plscmap1l
Signature: (int itype();int npts();double inensity(dima);double coordone(dima);double coordtwo(dima);double coordthree(dima);int rev(dima)) info not available

plscol0
Signature: (int icolzero();int r();int g();int b()) info not available

plscolbg
Signature: (int r();int g();int b()) info not available

plscolor
Signature: (int color()) info not available

plscompression
Signature: (int compression()) info not available

plsdidev
Signature: (double mar();double aspect();double jx();double jy()) info not available

plsdimap
Signature: (int dimxmin();int dimxmax();int dimymin();int dimymax();double dimxpmm();double dimypmm()) info not available

plsdiori
Signature: (double rot()) info not available

plsdiplt
Signature: (double xmin();double ymin();double xmax();double ymax()) info not available

plsdiplz
Signature: (double xmin();double ymin();double xmax();double ymax()) info not available

pl_setcontlabelparam
Signature: (double offset();double size();double spacing();int active()) info not available

pl_setcontlabelformat
Signature: (int lexp();int sigdig()) info not available

plsfam
Signature: (int fam();int num();int bmax()) info not available

plsmaj
Signature: (double def();double scale()) info not available

plsmin
Signature: (double def();double scale()) info not available

plsori
Signature: (int ori()) info not available

plspage
Signature: (double xp();double yp();int xleng();int yleng();int xoff();int yoff()) info not available

plspause
Signature: (int pause()) info not available

plsstrm
Signature: (int strm()) info not available

plssub
Signature: (int nx();int ny()) info not available

plssym
Signature: (double def();double scale()) info not available

plstar
Signature: (int nx();int ny()) info not available

plstart
Signature: (int nx();int ny(); char *devname) info not available

plstyl
Signature: (int nms();int mark(dima);int space(dima)) info not available

plsvpa
Signature: (double xmin();double xmax();double ymin();double ymax()) info not available

plsxax
Signature: (int digmax();int digits()) info not available

plsxwin
Signature: (int window_id()) info not available

plsyax
Signature: (int digmax();int digits()) info not available

plsym
Signature: (int n();double x(dima);double y(dima);int code()) info not available

plszax
Signature: (int digmax();int digits()) info not available

plvasp
Signature: (double aspect()) info not available

plvpas
Signature: (double xmin();double xmax();double ymin();double ymax();double aspect()) info not available

plvpor
Signature: (double xmin();double xmax();double ymin();double ymax()) info not available

plw3d
Signature: (double basex();double basey();double height();double xminzero();double xmaxzero();double yminzero();double ymaxzero();double zminzero();double zmaxzero();double alt();double az()) info not available

plwid
Signature: (int width()) info not available

plwind
Signature: (double xmin();double xmax();double ymin();double ymax()) info not available

plP_gpixmm
Signature: (double p_x(dima);double p_y(dima)) info not available

plline
Signature: (x(n); y(n)) info not available

plcolorpoints
Signature: (x(n); y(n); z(n); int sym()) info not available

plshades
Signature: (z(y,x); xmin(); xmax(); ymin(); ymax(); clevel(l); int fill_width(); int cont_color(); int cont_width(); int rectangular(); xmap(x); ymap(y)) info not available

plsmem
Signature: (int maxx();int maxy();image(3,x,y)) info not available

plfbox
Signature: (xo(); yo()) info not available