Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

PDL::Graphics::PLplotOO
Object-oriented interface from perl/PDL to the PLPLOT plotting library

PDL::Graphics::PLplotOO - Object-oriented interface from perl/PDL to the PLPLOT plotting library


NAME


  PDL::Graphics::PLplotOO - Object-oriented interface from perl/PDL to the PLPLOT plotting library


SYNOPSIS


  use PDL;

  use PDL::Graphics::PLplotOO;

  my $pl = PDL::Graphics::PLplotOO->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 PLplot documentation at:

 http://plplot.sourceforge.net/resources/docbook-manual/

Also see the test file, test.pl in this distribution for some working examples.


DESCRIPTION

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.


OPTIONS

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::PLplotOO->new();

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

   PDL::Graphics::PLplotOO->new(DEV => 'xwin', FILE => ':0');

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::PLplotOO->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::PLplotOO->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::PLplotOO->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::PLplotOO->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::PLplotOO->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.

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

 

=head2 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::PLplotOO->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]);

YBOX

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

YLAB

Specify a label for the Y axis.

XLAB

Specify a label for the X axis.


FUNCTIONS

new

Create an object representing a plot.


 Arguments:

 none.

 Supported options:

 BACKGROUND

 DEV

 FILE

 FRAMECOLOR

 JUST

 PAGESIZE

 SUBPAGES

  my $pl = PDL::Graphics::PLplotOO->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);

text

Print text on the plot.


 Arguments:

 $text -- The text string to print.  May contain PLplot escape sequences, see

 http://plplot.sourceforge.net/resources/docbook-manual/plplotdoc-html-0.4.3/escape-sequences.html

 Supported options:

 All options except:

 BACKGROUND

 DEV

 FILE

 FRAMECOLOR

 JUST

 PAGESIZE

 SUBPAGES

 (These must be set in call to 'new'.)

  $pl->text ("Pressure (lb/in#u2#d): #(850)", TEXTPOSITION => ['b', 4.0, 0.5, 0.5]);

  (See also the TEXTPOSITION option above)

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

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;


AUTHOR

Doug Hunt, dhunt\@ucar.edu.


SEE ALSO

perl(1), PDL(1), http://plplot.sourceforge.net/

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy