NAME

PDL::Graphics::PGPLOT - PGPLOT enhanced interface for PDL


SYNOPSIS

 perldl> $a = pdl [1..100]
 perldl> $b = sqrt($a)
 perldl> line $b
 perldl> hold
 Graphics on HOLD
 perldl> $c = sin($a/10)*2 + 4
 perldl> line $c


DESCRIPTION

PDL::Graphics::PGPLOT is an interface to the PGPLOT graphical libraries.

Current display commands:

 imag     -  Display an image (uses pgimag()/pggray() as appropriate)
 im       -  Shorthand to display an image with aspect ratio of 1
 ctab     -  Load an image colour table
 line     -  Plot vector as connected points
 points   -  Plot vector as points
 errb     -  Plot error bars
 cont     -  Display image as contour map
 bin      -  Plot vector as histogram (e.g. bin(hist($data)) )
 hi2d     -  Plot image as 2d histogram (not very good IMHO...)
 poly     -  Draw a polygon
 vect     -  Display 2 images as a vector field

Device manipulation commands:

 hold     -  Hold current plot window range - allows overlays etc.
 release  -  Release back to autoscaling of new plot window for each 
             command
 rel      -  short alias for 'release'
 env      -  Define a plot window, put on 'hold'
 dev      -  Explicitly set a new PGPLOT graphics device

The actual PGPLOT module is loaded only when the first of these commands is executed.

Notes: $transform for image/cont etc. is used in the same way as the TR() array in the underlying PGPLOT FORTRAN routine but is, fortunately, zero-offset.

For completeness: The transformation array connect the pixel index to a world coordinate such that:

 X = tr[0] + tr[1]*i + tr[2]*j
 Y = tr[3] + tr[4]*i + tr[5]*j

Variable passing and extensions

In general variables are passed to the pgplot routines by using get_dataref to get the reference to the values. Before passing to pgplot routines however, the data are checked to see if they are in accordance with the format (typically dimensionality) required by the PGPLOT routines. This is done using the routine checkarg (internal to PGPLOT). This routine checks the dimensionality of the input data. If there are superfluous dimensions of size 1 they will be trimmed away until the dimensionality is correct. Example:

Assume a piddle with dimensions (1,100,1,1) is passed to line, which expects its inputs to be vectors. checkarg will then return a piddle with dimensions (100). If instead the same piddle was passed to imag, which requires 2D piddles as output, checkarg would return a piddle with dimensionality (100, 1) (Dimensions are removed from the start)

Thus, if you want to provide support for another PGPLOT function, the structure currently look like this (there are plans to use the Options package to simplify the options parsing):

 # Extract the hash(es) on the commandline
 ($arg, $opt)=_extract_hash(@_); 
 <Check the number of input parameters>
 <deal with $arg>
 checkarg($x, 3); # For a hypothetical 3D routine.
 ...
 pgcube($n, $x->get_dataref);
 1;

Setting options

All routines in this package take a hash with options as an optional input. This options hash can be used to set parameters for the subsequent plotting without going via the PGPLOT commands.

This is implemented such that the plotting settings (such as line width, line style etc.) are affected only for that plot, any global changes made, say, with pgslw() are preserved.

Alphabetical listing of standard options

The following options are always parsed. Whether they have any importance depend on the routine invoked - e.g. line style is irrelevant for imag, or the justify option is irrelevant if the display is on 'hold'. This is indicated in the help text for the commands below.

The options are not case sensitive and will match for unique substrings, but this is not encouraged as obscure options might invalidate what you thought was a unique substring.

In the listing below examples are given of each option. The actual option can then be used in a plot command by specifying it as an argument to the function wanted (it can be placed anywhere in the command list).

E.g:

 $opt={COLOR=>2};
 line $x, $y, $opt; # This will plot a line with red color
arrow
This options allows you to set the arrow shape, and optionally size for arrows for the vect routine. The arrow shape is specified as a hash with the key FS to set fill style, ANGLE to set the opening angle of the arrow head, VENT to set how much of the arrow head is cut out and SIZE to set the arrowsize.

The following

 $opt = {ARROW => {FS=>1, ANGLE=>60, VENT=>0.3, SIZE=>5}};

will make a broad arrow of five times the normal size.

Alternatively the arrow can be specified as a set of numbers corresponding to an extention to the syntax for pgsah. The equivalent to the above is

 $opt = {ARROW => pdl([1, 60, 0.3, 5})};

For the latter the arguments must be in the given order, and if any are not given the default values of 1, 45, 0.3 and 1.0 respectively will be used.

arrowsize
The arrowsize can be specified separately using this option to the options hash. It is useful if an arrowstyle has been set up and one wants to plot the same arrow with several sizes.
 $opt = {ARROWSIZE => 2.5};

axis
Set the axis value (see env). It can either be specified as a number, or by one of the following names:
 EMPTY  (-2) draw no box, axes or labels
 BOX    (-1) draw box only
 NORMAL (0)  draw box and label it with coordinates
 AXES   (1)  same as NORMAL, but also draw (X=0,Y=0) axes
 GRID   (2)  same as AXES, but also draw grid lines
 LOGX   (10) draw box and label X-axis logarithmically
 LOGY   (20) draw box and label Y-axis logarithmically
 LOGXY  (30) draw box and label both axes logarithmically

border
Normally the limits are chosen so that the plot just fits; with this option you can increase (or decrease) the limits by either a relative (ie a fraction of the original axis width) or an absolute amount. Either specify a hash array, where the keys are TYPE (set to 'relative' or 'absolute') and VALUE (the amount to change the limits by), or set to 1, which is equivalent to
 BORDER => { TYPE => 'rel', VALUE => 0.05 }

charsize
Set the character/symbol size as a multiple of the standard size.
 $opt = {CHARSIZE => 1.5}

colour (or color)
Set the colour to be used for the subsequent plotting. This can be specified as a number, and the most used colours can also be specified with name, according to the following table (note that this only works for the default colour map):
  0 - WHITE    1 - BLACK     2 - RED      3 - GREEN    4 - BLUE
  5 - CYAN     6 - MAGENTA   7 - YELLOW   8 - ORANGE  14 - DARKGRAY
 16 - LIGHTGRAY

filltype
Set the fill type to be used by poly. The fill can either be specified using numbers or name, according to the following table, where the recognised name is shown in capitals - it is case-insensitive, but the whole name must be specified.
 1 - SOLID
 2 - OUTLINE
 3 - HATCHED
 4 - CROSS_HATCHED
 $opt = {FILLTYPE => 'SOLID'};

(see below for an example of hatched fill)

font
Set the character font. This can either be specified as a number following the PGPLOT numbering or name as follows (name in capitals):
 1 - NORMAL
 2 - ROMAN
 3 - ITALIC
 4 - SCRIPT

(Note that in a string, the font can be changed using the escape sequences \fn, \fr, \fi and \fs respectively)

 $opt = {FONT => 'ROMAN'};

gives the same result as

 $opt = {FONT => 2};

hatching
Set the hatching to be used if either fillstyle 3 or 4 is selected (see above) The specification is similar to the one for specifying arrows. The arguments for the hatching is either given using a hash with the key ANGLE to set the angle that the hatch lines will make with the horizontal, SEPARATION to set the spacing of the hatch lines in units of 1% of min(height, width) of the view surface, and PHASE to set the offset the hatching. Alternatively this can be specified as a 1x3 piddle $hatch=pdl[$angle, $sep, $phase].
 $opt = {FILLTYPE => 'HATCHED', 
         HATCHING => {ANGLE=>30, SEPARATION=>4}};

Can also be specified as

 $opt = {FILL=> 'HATCHED', HATCH => pdl [30,4,0.0]};

For another example of hatching, see poly.

justify
A boolean value which, if true, causes both axes to drawn to the same scale; see the PGPLOT pgenv() command for more information.

linestyle
Set the line style. This can either be specified as a number following the PGPLOT numbering:
 1 - SOLID line
 2 - DASHED
 3 - DOT-DASH-dot-dash
 4 - DOTTED
 5 - DASH-DOT-DOT-dot

or using name (as given in capitals above). Thus the following two specifications both specify the line to be dotted:

 $opt = {LINESTYLE => 4};
 $varopt = {LINESTYLE => 'DOTTED'};

The names are not case sensitive, but the full name is required.

linewidth
Set the line width. It is specified as a integer multiple of 0.13 mm.
 $opt = {LINEWIDTH => 10}; # A rather fat line


FUNCTIONS

A more detailed listing of the functions and their usage follows. For all functions we specify which options take effect and what other options exist for the given function.

dev

Open PGPLOT graphics device

 Usage: dev $device, [$nx,$ny];

$device is a PGPLOT graphics device such as ``/xserve'' or ``/ps'', if omitted defaults to last used device (or value of env var PGPLOT_DEV if first time). $nx, $ny specify sub-panelling.

env

Define a plot window, and put graphics on 'hold'

 Usage: env $xmin, $xmax, $ymin, $ymax, [$justify, $axis];
        env $xmin, $xmax, $ymin, $ymax, [$options];

$xmin, $xmax, $ymin, $ymax are the plot boundaries. $justify is a boolean value (default is 0); if true the axes scales will be the same (see justify). $axis describes how the axes should be drawn (see axis) and defaults to 0.

If the second form is used, $justify and $axis can be set in the options hash, for example:

 env 0, 100, 0, 50, {JUSTIFY => 1, AXIS => 'GRID', CHARSIZE => 0.7};

imag

Display an image (uses pgimag()/pggray() as appropriate)

 Usage: imag ( $image,  [$min, $max, $transform], [$opt] )

Notes: $transform for image/cont etc. is used in the same way as the TR() array in the underlying PGPLOT FORTRAN routine but is, fortunately, zero-offset.

There are several options related to scaling. By default, the image is scaled to fit the PGPLOT default viewport on the screen. Scaling, aspect ratio preservation, and 1:1 pixel mapping are available. (1:1 pixel mapping GREATLY increases the speed of pgimag, and is useful for, eg, movie display; but it's not recommended for final output as it's not device-independent.)

Options recognised:

       ITF - the image transfer function applied to the pixel values. It
             may be one of 'LINEAR', 'LOG', 'SQRT' (lower case is 
             acceptable). It defaults to 'LINEAR'.
      MIN  - Sets the minimum value to be used for calculation of the
             display stretch
      MAX  - Sets the maximum value for the same
 TRANSFORM - The transform 'matrix' as a 6x1 vector for display
      PIX  - Sets the image pixel aspect ratio.  By default, imag
             stretches the image pixels so that the final image aspect
             ratio fits the viewport exactly.  Setting PIX=>1 causes
             the image aspect ratio to be preserved.  (the image is
             scaled to avoid cropping, unless you specify scaling 
             manually).  Larger numbers yield "landscape mode" pixels.
     PITCH - Sets the number of image pixels per screen unit, in the Y
             direction.  The X direction is determined by PIX, which 
             defaults to 1 if PITCH is specified and PIX is not.  PITCH 
             causes UNIT to default to "inches" so that it's easy to say 
             100dpi by specifying {PITCH=>100}.  Larger numbers yield 
             higher resolution (hence smaller appearing) images.
      UNIT - Sets the screen unit used for scaling.  Must be one of the
             PGPLOT supported units (inch, mm, pixel, normalized).  You
             can refer to them by name or by number.  Defaults to pixels
             if not specified.
     SCALE - Syntactic sugar for the reciprocal of PITCH.  Makes the
             UNIT default to "pixels" so you can say "{SCALE=>1}"
             to see your image in device pixels.   Larger SCALEs lead
             to larger appearing images.

The following standard options influence this command:

 AXIS, BORDER, JUSTIFY
   To see an image with maximum size in the current window, but square
   pixels, say:
         imag $a,{PIX=>1}
   An alternative approach is to try:
         imag $a,{JUSTIFY=>1}
   To see the same image, scaled 1:1 with device pixels, say:
         imag $a,{SCALE=>1}
   To see an image made on a device with 1:2 pixel aspect ratio, with 
   X pixels the same as original image pixels, say
         imag $a,{PIX=>0.5,SCALE=>2}
   To display an image at 100 dpi on any device, say:
         imag $a,{PITCH=>100}
   To display an image with 100 micron pixels, say:
         imag $a,{PITCH=>10,UNIT=>'mm'}

imag1

Display an image with correct aspect ratio

 Usage:  imag1 ( $image, [$min, $max, $transform], [$opt] )

Notes: This is syntactic sugar for imag({PIX=>1}).

ctab

Load an image colour table.

Usage:

   ctab ( $name, [$contrast, $brightness] ) # Builtin col table
   ctab ( $ctab, [$contrast, $brightness] ) # $ctab is Nx4 array
   ctab ( $levels, $red, $green, $blue, [$contrast, $brightness] )
   ctab ( '', $contrast, $brightness ) # use last color table

Note: See PDL::Graphics::LUT for access to a large number of colour tables.

line

Plot vector as connected points

If the 'MISSING' option is specified, those points in the $y vector which are equal to the MISSING value are not plotted, but are skipped over. This allows one to quickly draw multiple lines with one call to line, for example to draw coastlines for maps.

 Usage: line ( [$x,] $y, [$opt] )

The following standard options influence this command:

 AXIS, BORDER, COLO(U)R, JUSTIFY, LINESTYLE, LINEWIDTH, MISSING
 $x = sequence(10)/10.;
 $y = sin($x)**2;
 # Draw a red dot-dashed line
 line $x, $y, {COLOR => 'RED', LINESTYLE=>3};

points

Plot vector as points

 Usage: points ( [$x,] $y, [$symbol(s)], [$opt] )

Options recognised:

   SYMBOL - Either a piddle with the same dimensions as $x, containing
            the symbol associated to each point or a number specifying
            the symbol to use for every point, or a name specifying the
            symbol to use according to the following (recognised name in
             capital letters):
             0 - SQUARE   1 - DOT     2 - PLUS     3 - ASTERISK
             4 - CIRCLE   5 - CROSS   7 - TRIANGLE 8 - EARTH
             9 - SUN     11 - DIAMOND 12- STAR
 PLOTLINE - If this is >0 a line will be drawn through the points.

The following standard options influence this command:

 AXIS, BORDER, CHARSIZE, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH
 $y = sequence(10)**2+random(10);
 # Plot blue stars with a solid line through:
 points $y, {PLOTLINE => 1, COLOUR => BLUE, SYMBOL => STAR};

errb

Plot error bars (using pgerrb())

Usage:

 errb ( $y, $yerrors, [$opt] )
 errb ( $x, $y, $yerrors, [$opt] )
 errb ( $x, $y, $xerrors, $yerrors, [$opt] )
 errb ( $x, $y, $xloerr, $xhierr, $yloerr, $yhierr, [$opt])

Options recognised:

   TERM - Length of terminals in multiples of the default length
 SYMBOL - Plot the datapoints using the symbol value given, either
          as name or number - see documentation for 'points'

The following standard options influence this command:

 AXIS, BORDER, CHARSIZE, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH
 $y = sequence(10)**2+random(10);
 $sigma=0.5*sqrt($y);
 errb $y, $sigma, {COLOUR => RED, SYMBOL => 18};

cont

Display image as contour map

 Usage: cont ( $image,  [$contours, $transform, $misval], [$opt] )

Notes: $transform for image/cont etc. is used in the same way as the TR() array in the underlying PGPLOT FORTRAN routine but is, fortunately, zero-offset.

Options recognised:

    CONTOURS - A piddle with the contour levels
      FOLLOW - Follow the contour lines around (uses pgcont rather than
               pgcons) If this is set >0 the chosen linestyle will be
               ignored and solid line used for the positive contours
               and dashed line for the negative contours.
      LABELS - An array of strings with labels for each contour
 LABELCOLOUR - The colour of labels if different from the draw colour
               This will not interfere with the setting of draw colour
               using the colour keyword.
     MISSING - The value to ignore for contouring
   NCONTOURS - The number of contours wanted for automatical creation,
               overridden by CONTOURS
   TRANSFORM - The pixel-to-world coordinate transform vector

The following standard options influence this command:

 AXIS, BORDER, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH
 $x=sequence(10,10);
 $ncont = 4;
 $labels= ['COLD', 'COLDER', 'FREEZING', 'NORWAY']
 # This will give four blue contour lines labelled in red.
 cont $x, {NCONT => $ncont, LABELS => $labels, LABELCOLOR => RED,
           COLOR => BLUE}

bin

Plot vector as histogram (e.g. bin(hist($data)))

 Usage: bin ( [$x,] $data )

Options recognised:

 CENTRE - if true, the x values denote the centre of the bin 
          otherwise they give the lower-edge (in x) of the bin
 CENTER - as CENTRE

The following standard options influence this command:

 AXIS, BORDER, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH

hi2d

Plot image as 2d histogram (not very good IMHO...)

 Usage: hi2d ( $image, [$x, $ioff, $bias], [$opt] )

Options recognised:

 IOFFSET - The offset for each array slice. >0 slants to the right
                                            <0 to the left.
    BIAS - The bias to shift each array slice up by.

The following standard options influence this command:

 AXIS, BORDER, JUSTIFY

Note that meddling with the ioffset and bias often will require you to change the default plot range somewhat. It is also worth noting that if you have TriD working you will probably be better off using mesh3d or a similar command - see the PDL::Graphics::TriD manpage.

 $r=sequence(100)/50-1.0;
 $y=exp(-$r**2)*transpose(exp(-$r**2))
 hi2d $y, {IOFF => 1.5, BIAS => 0.07};

poly

Draw a polygon

 Usage: poly ( $x, $y )

Options recognised:

The following standard options influence this command:

 AXIS, BORDER, COLOUR, FILLTYPE, HATCHING, JUSTIFY, LINESTYLE, 
 LINEWIDTH
 # Fill with hatching in two different colours
 $x=sequence(10)/10;
 # First fill with cyan hatching
 poly $x, $x**2, {COLOR=>5, FILL=>3};
 hold;
 # Then do it over again with the hatching offset in phase:
 poly $x, $x**2, {COLOR=>6, FILL=>3, HATCH=>{PHASE=>0.5}};
 release;

vect

Display 2 images as a vector field

 Usage: vect ( $a, $b, [$scale, $pos, $transform, $misval] )

Notes: $transform for image/cont etc. is used in the same way as the TR() array in the underlying PGPLOT FORTRAN routine but is, fortunately, zero-offset.

This routine will plot a vector field. $a is the horizontal component and $b the vertical component.

Options recognised:

     SCALE - Set the scale factor for vector lengths.
       POS - Set the position of vectors.
             <0 - vector head at coordinate
             >0 - vector base at coordinate
             =0 - vector centered on the coordinate
 TRANSFORM - The pixel-to-world coordinate transform vector
   MISSING - Elements with this value are ignored.

The following standard options influence this command:

 ARROW, ARROWSIZE, AXIS, BORDER, CHARSIZE, COLOUR, JUSTIFY, 
 LINESTYLE, LINEWIDTH
 $a=rvals(11,11,{Centre=>[5,5]});
 $b=rvals(11,11,{Centre=>[0,0]});
 vect $a, $b, {COLOR=>YELLOW, ARROWSIZE=>0.5, LINESTYLE=>dashed};


AUTHOR

Karl Glazebrook [kgb@aaoepp.aao.gov.au] modified by Jarle Brinchmann (jarle@ast.cam.ac.uk), docs mangled by Tuomas J. Lukka (lukka@fas.harvard.edu) and Christian Soeller (c.soeller@auckland.ac.nz)

All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.