PDL::Graphics::PGPLOT::Window - A OO interface to PGPLOT windows
perldl> use PDL::Graphics::PGPLOT::Window perldl> $win = PDL::Graphics::PGPLOT::Window->new(Device => '/xs'); perldl> $a = pdl [1..100] perldl> $b = sqrt($a) perldl> $win->line($b) perldl> $win->hold() perldl> $c = sin($a/10)*2 + 4 perldl> $win->line($c)
In the following documentation the commands are not shown in their OO versions. This is for historical reasons and should not cause too much trouble.
This package offers a OO interface to the PGPLOT plotting package. This is intended to replace the traditional interface in PDL::Graphics::PGPLOT and contains interfaces to a large number of PGPLOT routines. Below the usage examples for each function tend to be given in the non-OO version for historical reasons. This will slowly be changed, but in the meantime refer to the section on OO-interface below to see how to convert the usage information below to OO usage (it is totally trivial).
PDL::Graphics::PGPLOT::Window is an interface to the PGPLOT graphical libraries.
The list of currently availably methods:
imag - Display an image (uses pgimag()/pggray() as appropriate) ctab - Load an image colour table ctab_info - Get information about currently loaded 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 text - Write text in the plot area label_axes - Print axis titles legend - Create a legend with different texts, linestyles etc. cursor - Interactively read cursor positions. circle - Draw a circle ellipse - Draw an ellipse.
Device manipulation commands:
new - Constructor for a new PGPLOT output device. close - Close a PGPLOT output device. focus - Set focus to the given device. This should normally be done behind the scenes. hold - Hold current plot window range - allows overlays etc. release - Release back to autoscaling of new plot window for each command. held - Returns true if the graphics is held on the current device. env - Define a plot window, put on 'hold'. panel - Move to a specified plot panel when several panels are defined. erase - Erase the current window (or panel). options - Get the options set for the present output device. id - The ID for the device. device - The device type. name - The window name.
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. The transform() routine can be used to create this piddle.
$transform
TR()
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
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:
get_dataref
checkarg
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)
line
imag
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;
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. Some modifications apply when using the OO interface, see below.
pgslw()
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.
justify
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
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.
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. Please note that it is not possible to set arrowsize and character size in the same call to a plotting function. This should not be a problem in most cases.
$opt = {ARROWSIZE => 2.5};
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
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
TYPE
VALUE
BORDER => { TYPE => 'rel', VALUE => 0.05 }
Set the character/symbol size as a multiple of the standard size.
$opt = {CHARSIZE => 1.5}
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
However there is a much more flexible mechanism to deal with colour. The colour can be set as a 3 or 4 element anonymous array (or piddle) which gives the RGB colours. If the array has four elements the first element is taken to be the colour index to change. For normal work you might want to simply use a 3 element array with R, G and B values and let the package deal with the details. The R,G and B values go from 0 to 1.
In addition the package will also try to interpret non-recognised colour names using the default X11 lookup table, normally using the rgb.txt that came with PGPLOT.
rgb.txt
For more details on the handling of colour it is best that the user consults the PGPLOT documentation. Further details on the handling of colour can be found in the documentation for the internal routine _set_colour.
Set the fill type to be used by poly, circle, ellipse, and rectangle 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)
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)
\fn
\fr
\fi
\fs
$opt = {FONT => 'ROMAN'};
gives the same result as
$opt = {FONT => 2};
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].
min(height, width)
$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".
A boolean value which, if true, causes both axes to drawn to the same scale; see the PGPLOT pgenv() command for more information.
pgenv()
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.
Set the line width. It is specified as a integer multiple of 0.13 mm.
$opt = {LINEWIDTH => 10}; # A rather fat line
Explicitly set the plot range in x and y. X-range and Y-range are set separately via the aptly named options Xrange and Yrange. If omitted PGPLOT selects appropriate defaults (minimum and maximum of the data range in general). These options are ignored if the window is on hold.
Xrange
Yrange
line $x, $y, {xr => [0,5]}; # y-range uses default line $x, $y, {Xrange => [0,5], Yrange => [-1,3]}; # fully specified range
This section will briefly describe how the PDL::Graphics::PGPLOT::Window package can be used in an object-oriented (OO) approach and what the advantages of this would be. We will start with the latter
For the common user it is probably most interesting to use the OO interface when handling several open devices at the same time. If you have one variable for each plot device it is easier to distribute commands to the right device at the right time. This is the angle we will take in the rest of this description.
At a more fundamental level it is desirable to approach a situation where it is possible to have a generic plotting interface which gives access to several plotting libraries, much as PGPLOT gives access to different output devices. Thus in such a hypothetical package one would say:
my $win1 = Graphics::new('PGPLOT', {Device => '/xs'}); my $win2 = Graphics::new('gnuplot', {Background => 'Gray'};
From a more practical point of of view such abstraction also comes in handy when you write a large program package and you do not want to import routines nilly-willy in which case an OO approach with method calls is a lot cleaner.
Anyway, enough philosophizing, let us get down to Earth and give some examples of the use of OO PGPLOT. As an example we will take Odd (which happens to be a common Norwegian name) who is monitoring the birth of rabbits in O'Fib-o-nachy's farm (alternatively he can of course be monitoring processes or do something entirely different). Odd wants the user to be able to monitor both the birth rates and accumulated number of rabbits and the spatial distribution of the births. Since these are logically different he chooses to have two windows open:
$rate_win = PDL::Graphics::PGPLOT::Window->new(Device => '/xw', Aspect => 1, WindowWidth => 5, NXPanel => 2); $area_win = PDL::Graphics::PGPLOT::Window->new(Device => '/xw', Aspect => 1, WindowWidth => 5);
See the documentation for new below for a full overview of the options you can pass to the constructor.
Next, Odd wants to create plotting areas for subsequent plots and maybe show the expected theoretical trends
$rate_win->env(0, 10, 0, 1000, {XTitle => 'Days', YTitle => '#Rabbits'}); $rate_win->env(0, 10, 0, 100, {Xtitle=>'Days', Ytitle => 'Rabbits/day'}); $area_win->env(0, 1, 0, 1, {XTitle => 'Km', Ytitle => 'Km'}); # And theoretical prediction. $rate_win->line(sequence(10), fibonacci(10), {Panel => [1, 1]});
That is basically it. The commands should automatically focus the relevant window. Due to the limitations of PGPLOT this might however lead you to plot in the wrong panel... The package tries to be smart and do this correctly, but might get it wrong at times.
A new addition to the graphics interface is the ability to record plot commands. This can be useful when you create a nice-looking plot on the screen that you want to re-create on paper for instance. Or if you want to redo it with slightly changed variables for instance. This is still under development and views on the interface are welcome.
The functionality is somewhat detached from the plotting functions described below so I will discuss them and their use here.
Recording is off by default. To turn it on when you create a new device you can set the Recording option to true, or you can set the $PDL::Graphics::PGPLOT::RECORDING variable to 1. I recommend doing the latter in your .perldlrc file at least since you will often have use for recording in the perldl script.
Recording
$PDL::Graphics::PGPLOT::RECORDING
.perldlrc
The recording is meant to help you recreate a plot with new data or to a different device. The most typical situation is that you have created a beautiful plot on screen and want to have a Postscript file with it. In the dreary old world you needed to go back and execute all commands manually, but with this wonderful new contraption, the recorder, you can just replay your commands:
dev '/xs', {Recording => 1} $x = sequence(10) line $x, $x**2, {Linestyle => 'Dashed'} $s = retrieve_state() # Get the current tape out of the recorder. dev '/cps' replay $s
This should result in a pgplot.ps file with a parabola drawn with a dashed line. Note the command retrieve_state which retrieves the current state of the recorder and return an object (of type PDL::Graphics::State) that is used to replay commands later.
pgplot.ps
retrieve_state
Like any self-respecting recorder you can turn the recorder on and off using the turn_on_recording and turn_off_recording respectively. Likewise you can clear the state using the clear_state command.
turn_on_recording
turn_off_recording
clear_state
$w=PDL::Graphics::PGPLOT::Window->new(Device => '/xs'); $w->turn_on_recording; $x=sequence(10); $y=$x*$x; $w->line($x, $y); $w->turn_off_recording; $w->line($y, $x); $w->turn_on_recording; $w->line($x, $y*$x); $state = $w->retrieve_state();
We can then replay $state and get a parabola and a cubic plot.
$state
$w->replay($state);
The data are stored in the state object as references to the real data. This leads to one good and one potentially bad consequence:
$im = sequence(10,10) imag $im $s=retrieve_state
Now this was a rather dull plot, and in reality we wanted to show an image using rvals. Instead of re-creating the plot (which of course here would be the simplest option) we just change $im:
rvals
$im
$im -= sequence(10,10) $im += rvals(10,10)
Now replay the commands
replay $s
And hey presto! A totally different plot. Note however the trickery required to avoid losing reference to $im
$im = sequence(1000,1000) imag $im $s = retrieve_state $im = rvals(10,10)
Thus after the execution of these commands we still have a reference to a 1000x1000 array which takes up a lot of memory...
The solution is to call clear on the state variable:
clear
$s->clear()
(This is done automatically if the variable goes out of scope). I forsee this problem to most acute when working on the perldl command line, but since this is exactly where the recording is most useful the best advice is just to be careful and call clear on state variables.
perldl
If you are working with scripts and use large images for instance I would instead recommend that you do not turn on recording unless you need it.
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. The function descriptions below are all given for the non-OO usage for historical reasons, but since the conversion to an OO method is trivial there is no major need for concern. Whenever you see a function example of the form
Usage: a_simple_function($x, $y, $z [, $opt]);
and you wish to use the OO version, just let your mind read the above line as:
Usage: $win->a_simple_function($x, $y, $z [, $opt]);
where $win is a PDL::Graphics::PGPLOT::Window object. That is all.
$win
Constructor for PGPLOT object/device/plot window.
Usage: PDL::Graphics::PGPLOT::Window->new($opt); Usage: PDL::Graphics::PGPLOT::Window->new($option=>$value,...);
Options to new() can either be specified via a reference to a hash
$win = PDL::Graphics::PGPLOT::Window->new({Dev=>'/xserve',ny=>2});
or directly, as an array
# NOTE: no more {} ! $win = PDL::Graphics::PGPLOT::Window->new(Dev=>'/xserve',ny=>2);
The following lists the recognised options:
The aspect ratio of the image, in the sense vertical/horizontal. If both this and WindowWidth are set to zero, the default view surface is used. (This is the default case).
The type of device to use. The syntax of this is the one used by PGPLOT.
Hold the plot window so that subsequent plots can plot over existing plots. This can be adjusted with the hold() and release() methods.
hold()
release()
The number of panels in the X-direction
The number of panels in the Y-direction
The name to give to the window. No particular use is made of this at present. It would be great if it was possible to change the title of the window frame.
The width of the window in inches. If this is set to 0.0, the biggest window consistent with the AspectRatio setting will be chosen. If both this and AspectRatio are set to zero, the default view surface is used. (This is the default case).
These two options allow an alternative setting of WindowWidth and AspectRatio. Their values are actually not parsed here, but rather subsequently in the _setup_window routine below.
An important point to note is that the default values of most options can be specified by passing these to the constructor. All general options (common to several functions) can be adjusted in such a way, but function specific options can not be set in this way (this is a design limitation which is unlikely to be changed).
Thus the following call will set up a window where the default axis colour will be yellow and where plot lines normally have red colour and dashed linestyle.
$win = PDL::Graphics::PGPLOT::Window->new(Device => '/xs', AxisColour => 'Yellow', Colour => 'Red', LineStyle => 'Dashed');
Close a plot window
Usage: $win->close()
Close the current window. This does not necessarily mean that the window is removed from your screen, but it does ensure that the device is closed.
A message will be printed to STDOUT giving the name of the file created if the plot was made to a hardcopy device and $PDL::verbose is true.
$PDL::verbose
Check if a window is on hold
$is_held = $win->held();
Function to check whether the window is held or not.
Hold the present window.
Usage: $win->hold()
Holds the present window so that subsequent plot commands overplots.
Switch to a different panel
$win->panel(<num>);
Move to a different panel on the plotting surface. Note that you will need to erase it manually if that is what you require.
Release a plot window.
$win->release()
Release a plot window so that subsequent plot commands move to the next panel or erase the plot and create a new plot.
Erase plot
$win->erase($opt);
Erase a plot area. This accepts the option Panel or alternatively a number or array reference which makes it possible to specify the panel to erase when working with several panels.
Panel
Define a plot window, and put graphics on 'hold'
$win->env( $xmin, $xmax, $ymin, $ymax, [$justify, $axis] ); $win->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.
$xmin
$xmax
$ymin
$ymax
$justify
$axis
axis
If the second form is used, $justify and $axis can be set in the options hash, for example:
$win->env( 0, 100, 0, 50, {JUSTIFY => 1, AXIS => 'GRID', CHARSIZE => 0.7} );
In addition the following options can also be set for env:
env
The position of the plot on the page relative to the view surface in normalised coordinates as an anonymous array. The array should contain the lower and upper X-limits and then the lower and upper Y-limits. To place two plots above each other with no space between them you could do
$win->env(0, 1, 0, 1, {PlotPosition => [0.1, 0.5, 0.1, 0.5]}); $win->env(5, 9, 0, 8, {PlotPosition => [0.1, 0.5, 0.5, 0.9]});
See the description of general options for these options.
Set the colour of the coordinate axes.
Axes titles and the font and size to print them.
Label plot axes
$win->label_axes(<xtitle>, <ytitle>, <plot title>, $options);
Draw labels for each axis on a plot.
Display an image (uses pgimag()/pggray() as appropriate)
pgimag()
pggray()
$win->imag ( $image, [$min, $max, $transform], [$opt] )
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.)
To draw a colour bar (or wedge), either use the DrawWedge option, or the draw_wedge() routine (once the image has been drawn).
DrawWedge
draw_wedge()
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 is 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. DrawWedge - set to 1 to draw a colour bar (default is 0) Wedge - see the draw_wedge() routine
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: $win->imag( $a, { PIX=>1 } ); An alternative approach is to try: $win->imag( $a, { JUSTIFY=>1 } ); To see the same image, scaled 1:1 with device pixels, say: $win->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 $win->imag( $a, { PIX=>0.5, SCALE=>2 } ); To display an image at 100 dpi on any device, say: $win->imag( $a, { PITCH=>100 } ); To display an image with 100 micron pixels, say: $win->imag( $a, { PITCH=>10, UNIT=>'mm' } );
Display an image with correct aspect ratio
$win->imag1 ( $image, [$min, $max, $transform], [$opt] )
This is syntactic sugar for
$win->imag( { PIX=>1 } );
Add a wedge (colour bar) to an image.
$win->draw_wedge( [$opt] )
Adds a wedge - shows the mapping between colour and value for a pixel - to the current image. This can also be achieved by setting DrawWedge to 1 when calling the imag routine.
The colour and font size are the same as used to draw the image axes (although this will probably fail if you did it yourself). To control the size and location of the wedge, use the Wedge option, giving it a hash reference containing any of the following:
Wedge
Which side of the image to draw the wedge: can be one of 'B', 'L', 'T', or 'R'. Default is 'R'.
How far from the egde of the image should the wedge be drawn, in units of character size. To draw within the image use a negative value. Default is 2.
How wide should the wedge be, in units of character size. Default is 3.
A text label to be added to the wedge. If set, it is probably worth increasing the Width value by about 1 to keep the text readable. Default is ''.
Width
The pixel value corresponding to the "maximum" colour. If undef, uses the value used by imag (recommended choice). Default is undef.
undef
The pixel value corresponding to the "minimum" colour. If undef, uses the value used by imag (recommended choice). Default is undef.
$a = rvals(50,50); $win = PDL::Graphics::PGPLOT::Window->new(); $win->imag( $a, { Justify => 1, ITF => 'sqrt' } ); $win->draw_wedge( { Wedge => { Width => 4, Label => 'foo' } } ); # although the following might be more sensible $win->imag( $a, { Justify => 1, ITF => 'sqrt', DrawWedge => 1, Wedge => { Width => 4, Label => 'foo'} } );
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.
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.
$y
Usage: line ( [$x,] $y, [$opt] )
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};
Plot vector as points
Usage: points ( [$x,] $y, [$symbol(s)], [$opt] )
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.
AXIS, BORDER, CHARSIZE, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH
SymbolSize allows to adjust the symbol size, it defaults to CharSize.
SymbolSize
The ColorValues option allows one to plot XYZ data with the Z axis mapped to a color value. For example:
ColorValues
use PDL::Graphics::LUT; ctab(lut_data('idl5')); # set up color palette to 'idl5' points ($x, $y, {ColorValues => $z});
$y = sequence(10)**2+random(10); # Plot blue stars with a solid line through: points $y, {PLOTLINE => 1, COLOUR => BLUE, symbol => STAR}; # case insensitive
Plot error bars (using pgerrb())
pgerrb()
errb ( $y, $yerrors, [$opt] ) errb ( $x, $y, $yerrors, [$opt] ) errb ( $x, $y, $xerrors, $yerrors, [$opt] ) errb ( $x, $y, $xloerr, $xhierr, $yloerr, $yhierr, [$opt])
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'
$y = sequence(10)**2+random(10); $sigma=0.5*sqrt($y); errb $y, $sigma, {COLOUR => RED, SYMBOL => 18};
Display image as contour map
Usage: cont ( $image, [$contours, $transform, $misval], [$opt] )
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
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}
Plot vector as histogram (e.g. bin(hist($data)))
bin(hist($data))
Usage: bin ( [$x,] $data )
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
Plot image as 2d histogram (not very good IMHO...)
Usage: hi2d ( $image, [$x, $ioff, $bias], [$opt] )
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.
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 module.
ioffset
bias
$r=sequence(100)/50-1.0; $y=exp(-$r**2)*transpose(exp(-$r**2)) hi2d $y, {IOFF => 1.5, BIAS => 0.07};
Plot an arrow
Usage: arrow($x1, $y1, $x2, $y2, [, $opt]);
Plot an arrow from $x1, $y1 to $x2, $y2. The arrow shape can be set using the option Arrow. See the documentation for general options for details about this option (and the example below):
$x1, $y1
$x2, $y2
Arrow
Example:
arrow(0, 1, 1, 2, {Arrow => {FS => 1, Angle => 60, Vent => 0.3, Size => 5}});
which draws a broad, large arrow from (0, 1) to (1, 2).
Draw a polygon
Usage: poly ( $x, $y )
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;
Plot a circle on the display using the fill setting.
Usage: circle($x, $y, $radius [, $opt]);
All arguments can alternatively be given in the options hash using the following options:
The position of the center of the circle
The radius of the circle.
Plot an ellipse, optionally using fill style.
Usage: ellipse($x, $y, $a, $b, $theta [, $opt]);
The major axis of the ellipse - this must be defined or $a must be given.
$a
The minor axis, like A this is required.
The orientation of the ellipse - defaults to 0.0. This is given in radians.
The coordinates of the center of the ellipse. These must be specified or $x and $y must be given.
$x
The number of points used to draw the ellipse. This defaults to 100 and might need changing in the case of very large ellipses.
The routine also recognises the same standard options as accepted by poly.
Draw a rectangle.
Usage: rectangle($xcenter, $ycenter, $xside, $yside, [, $angle, $opt]);
This routine draws a rectangle with the chosen fill style. Internally it calls poly which is somewhat slower than pgrect but which allows for rotated rectangles as well. The routine recognises the same options as poly and in addition the following:
pgrect
poly
The position of the center of the rectangle. XCentre and YCentre are valid synonyms.
The length of the X and Y sides. If only one is specified the shape is taken to be square with that as the side-length, alternatively the user can set Side
The length of the sides of the rectangle (in this case a square) - syntactic sugar for setting XSide and YSide identical. This is overridden by XSide or YSide if any of those are set.
The angle at which the rectangle is to be drawn. This defaults to 0.0 and is given in radians.
Display 2 images as a vector field
Usage: vect ( $a, $b, [$scale, $pos, $transform, $misval] )
This routine will plot a vector field. $a is the horizontal component and $b the vertical component.
$b
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.
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};
Create transform array for contour and image plotting
$win->transform([$xdim,$ydim], $options);
This function creates a transform array in the format required by the image and contouring routines. You must call it with the dimensions of your image as arguments or pass these as an anonymous hash - see the example below.
The rotation angle of the transform
The dimensions of the image the transform is required for. The dimensions should be passed as a reference to an array.
The increment in output coordinate per pixel.
The centre of the image as an anonymous array or as a scalar. In the latter case the x and y value for the center will be set equal to this scalar. This is particularly useful in the common case when the center is (0, 0).
If you wish to set a pixel other than the image centre to a given value, use this option. It should be supplied with a reference to an array containing 2 2-element array references, e.g.
RefPos => [ [ $xpix, $ypix ], [ $xplot, $yplot ] ]
This will label pixel ($xpix,$ypix) as being at position ($xplot,$yplot). The ImageCentre option can be considered to be a special case of this option, since the following are identical (although one is a lot easier to type ;)
($xpix,$ypix)
($xplot,$yplot)
ImageCentre
ImageCentre => [ $xc, $yc ] RefPos => [ [($nx-1)/2,($ny-1)/2], [ $xc, $yc ] ]
The values supplied in ImageCentre are used if both ImageCentre and RefPos are supplied in the options list.
RefPos
$im = rvals(100, 100); $w = PDL::Graphics::PGPLOT::Window->new(Device => '/xs'); $t = $w->transform(dims($im), {ImageCenter => 0, Pixinc => 5}); $w->imag($im, {Transform => $t});
Threaded line plotting
$win->tline($x, $y, $options);
This is a threaded interface to line. This is convenient if you have a 2D array and want to plot out every line in one go. The routine will apply any options you apply in a "reasonable" way. In the sense that it will loop over the options wrapping over if there are less options than lines.
$h={Colour => ['Red', '1', 4], Linestyle => ['Solid' ,'Dashed']}; $tx=zeroes(100,5)->xlinvals(-5,5); $ty = $tx + $tx->yvals; $win->tline($tx, $ty, $h);
A threaded interface to points
Usage: tpoints($x, $y, $options);
This is a threaded interface to points. This is convenient if you have a 2D array and want to plot out every line in one go. The routine will apply any options you apply in a "reasonable" way. In the sense that it will loop over the options wrapping over if there are less options than lines.
points
$h={Colour => ['Red', '1', 4], Linestyle => ['Solid' ,'Dashed']}; $tx=zeroes(100,5)->xlinvals(-5,5); $ty = $tx + $tx->yvals; tpoints($tx, $ty, $h);
Write text in a plot window at a specified position.
Usage: text ($text, $x, $y [, $opt])
ANGLE
The angle in degrees between the baseline of the text and the horisontal (increasing counter-clockwise). This defaults to 0.
JUSTIFICATION
The justification of the text relative to the position specified. It defaults to 0.0 which gives left-justified text. A value of 0.5 gives centered text and a value of 1.0 gives right-justified text.
XPos
YPos
Text
These gives alternative ways to specify the text and position.
BackgroundColour
This sets the background colour for the text in case an opaque background is desired. You can also use the synonyms Bg and BackgroundColor.
Bg
BackgroundColor
COLOUR, CHARSIZE
line sequence(10), sequence(10)**2; text 'A parabola', 3, 9, {Justification => 1, Angle=>atan2(6,1)};
Add a legend to a plot
Usage: legend($text, $x, $y, [, $width], $opt]);
This function adds a legend to an existing plot. The action is primarily controlled by information in the options hash, and the basic idea is that $x and $y determines the upper left hand corner of the box in which the legend goes. If the width is specified either as an argument or as an option in the option hash this is used to determine the optimal character size to fit the text into part of this width (defaults to 0.5 - see the description of TextFraction below). The rest of the width is filled out with either lines or symbols according to the content of the LineStyle, Symbol, Colour and LineWidth options.
TextFraction
LineStyle
Symbol
Colour
LineWidth
The local options recognised are as follows:
An anonymous array of annotations, can also be specified directly.
The X and Y position of the upper left-hand corner of the text.
Height
The width and/or height of each line (including symbol/line). This is used to determine the character size. If any of these are set to 'Automatic' the current character size will be used.
The text and the symbol/line is set inside a box. TextFraction determines how much of this box should be devoted to text. This defaults to 0.5. You can also use Fraction as a synonym to this.
Fraction
TextShift
This option allows for fine control of the spacing between the text and the start of the line/symbol. It is given in fractions of the total width of the legend box. The default value is 0.1.
VertSpace
VSpace
By default the text lines are separated by one character height (in the sense that if the separation were 0 then they would lie on top of each other). The VertSpace option allows you to increase (or decrease) this gap in units of the character height; a value of 0.5 would add half a character height to the gap between lines, and -0.5 would remove the same distance. The default value is 0.
line $x, $y, {Color => 'Red', LineStyle => 'Solid'}; line $x2, $y2, {Color => 'Blue', 'LineStyle' => 'Dashed', LineWidth => 10}; legend ['A red line', 'A blue line'], 5, 5, {LineStyle => ['Solid', 'Dashed'], Colour => ['Red', 'Blue'] LineWidth => [undef, 10]}; # undef gives default.
Interactively read cursor positions.
Usage: ($x, $y, $ch, $xref, $yref) = cursor($opt)
This routine has no standard input parameters, but the type of cursor can be set by setting the option Type as a key in the anonymous hash $opt. The first three return values from the function are always defined and gives the position selected by the user and the character pressed.
Type
$opt
Depending on the cursor type selected the last two arguments might also be defined and these give a reference position. For instance if the cursor is selected to be Rectangle then the reference position gives one of the corners of the rectangle and $x and $y the diagonally opposite one.
Rectangle
The reference position to be used
The type of cursor. This can be selected using a number between 0 and 7 as in PGPLOT, or alternatively you can specify these as, Default (0), RadialLine (1), Rectangle (2), TwoHorizontalLines (3), TwoVerticalLines (4), HorizontalLine (5), VerticalLine (6) and CrossHair (7) respectively. The default cursor is just the normal mouse cursor.
Default
RadialLine
TwoHorizontalLines
TwoVerticalLines
HorizontalLine
VerticalLine
CrossHair
For the RadialLine you must specify the reference point, whereas for the Two(Vertical|Horizontal)Lines cursor the X or Y reference point, respectively, must be specified.
Two(Vertical|Horizontal)Lines
To select a region on a plot, use the rectangle cursor:
($x, $y, $ch, $xref, $yref) = cursor({Type => 'Rectangle'}); poly pdl($x, $xref, $xref, $x, $x), pdl($y, $y, $yref, $yref, $y);
To select a region of the X-axis:
($x1, $y1, $ch) = cursor({Type => 'VerticalLine'}); ($x2, $y2, $ch) = cursor({Type => 'TwoVerticalLines', XRef => $x1});
Open a new window. This sets the window ID, which is the one used when accessing a window later using pgslct. It also sets the window name to something easily remembered if it has not been set before.
pgslct
This routine sets up a new window with its shape and size. This is also where the two options WindowXSize and WindowYSize are parsed. These are then forgotten (well, they are stored in $self->{Options}, but forget that) and the corresponding aspect ratio and window width is stored. Alternatively, the AspectRatio and WindowWidth options are used to set the view surface. The logic goes somewhat like this:
WindowXSize
WindowYSize
AspectRatio
WindowWidth
If WindowXSize and WindowYSize are both non-zero, then those are used.
If AspectRatio is non-zero and WindowWidth is zero, WindowWidth is calculated such that it a region with the given aspect ratio will fit within the device's view surface.
If both AspectRatio and WindowWidth are zero, the device's default AspectRatio and WindowWidth is used.
Finally the subpanels are set up using pgsubp and colours and linewidth are adjusted according to whether we have a hardcopy device or not.
pgsubp
This routine checks the status of the window. It returns OPEN if the window is open and CLOSED if it is closed.
This functions reopens a window. Since this is an internal function it does not have a lot of error-checking. Make sure the device is closed before calling this routine.
There is an unfortunate problem which pops up viz. that the window name cannot be changed at this point since we are offering that to the rest of the world. That might be sensible, but it means that the window name will not reflect the id of the window - use id() for that (this is also why we do not call open_new_window )
id()
open_new_window
This routine advances one plot panel, updating the CurrentPanel as well. If the advance will proceed past the page the page will be erased. Also note that when you advance one panel the hold value will be changed.
This routine is a utility routine which checks if we need to move panel, and if so will do this. It also checks if it is necessary to advance panels, and whether they need to be erased.
This function is a cludgy utility function that expands an options hash to an array of hashes looping over options. This is mainly of use for "threaded" interfaces to standard plotting routines.
Access the options used when originally opening the window. At the moment this is not updated when the window is changed later.
Access the window ID that PGPLOT uses for the present window.
This function returns the device type of the present window.
Accessor to set and examine the name of a window.
Set focus for subsequent PGPLOT commands to this window.
Get general information about the PGPLOT environment.
@ans = $self->info( @item );
The valid values of @item are as below, where case is not important:
@item
VERSION - What PGPLOT version is in use. STATE - The status of the output device, this is returns 'OPEN'. if the device is open and 'CLOSED' otherwise. USER - The username of the owner of the spawning program. NOW - The current date and time in the format 'dd-MMM-yyyy hh:mm'. Most people are likely to use Perl functions instead. DEVICE * - The current PGPLOT device or file, see also device(). FILE * - The filename for the current device. TYPE * - And the device type for the current device. DEV/TYPE * - This combines DEVICE and TYPE in a form that can be used as input to new. HARDCOPY * - This is flag which is set to 'YES' if the current device is a hardcopy device and 'NO' otherwise. TERMINAL * - This flag is set to 'YES' if the current device is the user's terminal and 'NO' otherwise. CURSOR * - A flag ('YES' or 'NO') to inform whether the current device has a cursor.
Those items marced with a * only return a valid answer if the window is open. A question mark (?) is returned if the item is not recognised or the information is not available.
*
?
This routine takes and array and returns the first hash reference found as well as those elements that are not hashes. Note the latter point because all other references to hashes in the array will be lost.
This is a convenience routine for parsing a set of options. It returns both the full set of options and those that the user has set.
Saves the PGPLOT state so that changes to settings can be made and then the present state restored by _restore_status.
_restore_status
Restore the PGPLOT state. See "_save_status".
This routine checks and optionally alters the arguments given to it.
This is an internal routine that encapsulates all the nastiness of setting colours depending on the different PGPLOT colour models (although HLS is not supported).
The routine works in the following way:
At initialisation of the plot device the work colour index is set to 16. The work index is the index the routine will modify unless the user has specified something else.
The routine should be used after standard interpretation and synonym matching has been used. So if the colour is given as input is an integer that colour index is used.
If the colour is a reference the routine checks whether it is an ARRAY or a PDL reference. If it is not an error message is given. If it is a PDL reference it will be converted to an array ref.
ARRAY
PDL
If the array has four elements the first element is interpreted as the colour index to modify and this overrules the setting for the work index used internally. Otherwise the work index is used and incremented until the maximum number of colours for the output device is reached (as indicated by pgqcol). Should you wish to change that you need to read the PGPLOT documentation - it is somewhat device dependent.
pgqcol
When the array has been recognised the R,G and B colours of the user-set index or work index is set using the pgscr command and we are finished.
pgscr
If the input colour instead is a string we try to set the colour using the PGPLOT routine pgscrn with no other error-checking. This should be ok, as that routine returns a rather sensible error-message.
pgscrn
This internal routine is the default routine for parsing options. This routine deals with a subset of options that most routines will accept.
The coding tries to follow reasonable standards, so that all functions starting with an underscore should be considered as internal and should not be called from outside the package. In addition most routines have a set of options. These are encapsulated and are not accessible outside the routine. This is to avoid collisions between different variables.
Karl Glazebrook [kgb@aaoepp.aao.gov.au] modified by Jarle Brinchmann (jarle@astro.ox.ac.uk) who is also responsible for the OO interface, docs mangled by Tuomas J. Lukka (lukka@fas.harvard.edu) and Christian Soeller (c.soeller@auckland.ac.nz). Further contributions and bugfixes from Kaj Wiik, Doug Burke and many others.
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.
To install PDL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDL
CPAN shell
perl -MCPAN -e shell install PDL
For more information on module installation, please visit the detailed CPAN module installation guide.