|
PDL::Graphics::PGPLOT::Window - A OO interface to PGPLOT windows |
PDL::Graphics::PGPLOT::Window - A OO interface to PGPLOT windows
perldl> use PDL::Graphics::PGPLOT::Window perldl> $win = pgwin(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 - Construct a new output device
pgwin - Exported hook to new()
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.
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:
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. &catch_signals; ... pgcube($n, $x->get_dataref); &release_signals; 1;
(the catch_signals/release_signals pair prevent problems with the perl-PGPLOT interface if the user hits c-C during an operation).
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.
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
If you are plotting to a hardcopy device then a number of options use a different name:
HardLW instead of LineWidth HardCH instead of CharSize HardFont instead of Font
HardAxisColour instead of AxisColour HardColour instead of Colour
[although I'm not sure when HardColour is actually used]
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.
$opt = {ARROWSIZE => 2.5};
If you set the option to a scalar value, you get one of a few standard layouts. You can specify them by name or by number:
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
If you set the option to an array ref, then you can specify the box/axis options separately for the horizontal (ordinate; X coordinate; 0th element) and vertical (abscissa; Y coordinate; 1st element)) axes. Each element of the array ref should contain a PGPLOT format string. Presence or absence of specific characters flags particular options. For normal numeric labels, the options are:
A : draw axis for this dimension.
B : draw bottom (X) or left (Y) edge of frame.
C : draw top (X) or right (Y) edge of frame.
G : draw Grid of vertical (X) or horizontal (Y) lines.
I : Invert ticks: draw them outside the plot rather than inside.
L : Label the axis Logarithmically.
P : Extend ("Project") major tick marks outside the box.
M : Numeric labels go in the alternate place above (X) or to the
right (Y) of the viewport.
N : Numeric labels go in the usual location below (X) or to the
left (Y) of the viewport
T : Draw major tick marks at the major coordinate interval.
S : Draw minor tick marks (subticks).
V : Orient numeric labels Vertically. Only applicable to Y.
(The default is to write them parallel to the axis.)
1 : Force decimal labelling, instead of automatic choice
2 : Force exponential labeling, instead of automatic.
If you don't specify any axis value at all, the default is ['BCNST','BCNST'] for plots and ['BCINST','BCINST'] for images. (These list ref elements are handed on directly to the low-level PGPLOT routines).
In addition, you can specify that your axis labels should be printed as days, hours, minutes, and seconds (ideal for julian dates and delta-t, or for angular quantities). You do that by setting additional character flags on the affected axis:
X : Use HH MM SS.S time labeling rather than conventional numeric
labels. The ordinate is in secsonds. Hours roll over at 24.
Y : Like 'X' but the hour field runs past 24 if necessary.
Z : Like 'X' but with a days field too (only shown where nonzero).
H : Label the numbers with superscript d, h, m, and s symbols.
D : Label the numbers with superscript o, ', and '' symbols.
F : Omit first (lowest/leftmost) label; useful for tight layouts.
O : Omit leading zeroes in numbers under 10 (e.g. " 3h 3m 1.2s"
rather than "03h 03m 01.2s").
For example, to plot a numeric quantity versus Julian day of the year in a standard boxed plot with tick marks, you can use [``BNCSTZHO'',``BCNST''].
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 }
$opt = {CHARSIZE => 1.5}
The HardCH option should be used if you are plotting to a hardcopy device.
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.
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.
The HardColour option should be used if you are plotting to a hardcopy device [this may be untrue?].
1 - SOLID 2 - OUTLINE 3 - HATCHED 4 - CROSS_HATCHED
$opt = {FILLTYPE => 'SOLID'};
(see below for an example of hatched fill)
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};
The HardFont option should be used if you are plotting to a hardcopy device.
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 is set true, then the plot axes are shrunk to fit
the plot or image and it specifies the aspect ratio of pixel
coordinates in the plot or image. Setting justify=>1 will
produce a correct-aspect-ratio, shrink-wrapped image or plot;
setting justify=>0.5 will do the same thing but with a short and
fat plot. The difference between justify and pix is that
pix does not affect the shape of the axes themselves.
unit (see below) to change this to number of PGPLOT units
(inches, millimeters, etc.) per data pixel. scale is deprecated,
as it is not device-independent; but it does come in handy for quick
work on digital displays, where aliasing might otherwise interfere
with image interpretation. For example, scale=1> displays
images at their native resolution.
unit (see below) to change this to any other
PGPLOT unit (millimeters, pixels, etc.). Pitch is device independent,
so an image should appear exactly the same size (e.g. Pitch=100>
is 100 dpi) regardless of output device.
pix is set, then images and plots are not stretched to fill the plot
area. the align string tells how to align them within the available
area. 'L' and 'R' shove the plot against the left and right edges,
respectively; 'B' and 'T' shove the plot against the bottom and top
edges. The default is to center the image. e.g. 'BL' puts the image
on the bottom left corner, while 'CT' centers the image horizontally
while placing it at the top of the available plot area. This defaults
to 'BT' for non-justified images, to 'CC' for justified images.
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.
$opt = {LINEWIDTH => 10}; # A rather fat line
The HardLW option should be used if you are plotting to a hardcopy device.
Panel option. There is also a
panel method, but its use is deprecated
because of a wart with the PGPLOT interface.
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.
line $x, $y, {xr => [0,5]}; # y-range uses default
line $x, $y, {XRange => [0,5], YRange => [-1,3]}; # fully specified range
imag $im, {XRange => [30,50], YRange=>[-10,30]};
fits_imag $im, {XRange=>[-2,2], YRange=>[0,1]};
Imaging requires some thought if you don't want to lose a pixel off the edge of the image. Pixels are value-centered (they are centered on the coordinate whose value they represent), so the appropriate range to plot the entirety of a 100x100 pixel image is [-0.5,99.5] on each axis.
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
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.
The pgwin exported constructor, arguably, breaks this philosophy; hopefully it will ``wither away'' when other compatible modules are available.
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.
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.
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.
$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.
$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:
$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:
$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.
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.
Exported constructor for PGPLOT object/device/plot window.
Usage: pgwin($opt); Usage: pgwin($option->$value,...); Usage: pgwin($device);
Parameters are passed on to new() and can either be specified by hash
reference or as a list.
See the documentation fo PDL::Graphics::PGPLOT::Window::new for details.
Because pgwin is a convenience function, you can specify the device by passing in a single non-ref parameter. For even further convenience, you can even omit the '/' in the device specifier, so these two lines deliver the same result:
$a = pgwin(gif);
$a = new PDL::Graphics::PGPLOT::Window({Dev=>'/gif'});
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:
hold() and release() methods.
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');
Size setting: There are a gazillion ways to set window size, in keeping with TIMTOWTDI. In general you can get away with passing any unique combination of an <X> size, a <Y> size, and/or an aspect ratio. In increasing order of precedence, the options are: (Units, AspectRatio, WindowWidth, Window<X,Y>Size, Size).
So if you specify an AspectRatio *and* an X and a Y coordinate, the AspectRatio is ignored. Likewise, if you specify Units and a three-component Size, the Units option is ignored in favor of the numeric unit in the Size.
If you don't specify enough information to set the size of the window, you get the default pane size and shape for that device.
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.
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.
This routine currently does something you probably don't want, and hence is deprecated for most use: if you say
$win->panel(1); $win->imag($image);
then $image will actually be displayed in panel 2. That's because the main plotting routines such as line and imag all advance the panel when necessary. Instead, it's better to use the Panel option within plotting commands, if you want to set the panel explicitly.
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.
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.
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:
$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]});
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)
$win->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. The transform() routine can be used to
create this piddle.
If $image is two-dimensional, you get a grey or pseudocolor image
using the scalar values at each X,Y point. If $image is
three-dimensional and the third dimension has order 3, then it is
treated as an RGB true-color image via rgbi.
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.)
Here's an additional complication: the ``pixel'' stuff refers not (necessarily) to normal image pixels, but rather to transformed image pixels. That is to say, if you feed in a transform matrix via the TRANSFORM option, the PIX, SCALE, etc. options all refer to the transformed coordinates and not physical image pixels. That is a Good Thing because it, e.g., lets you specify plate scales of your output plots directly! See fits_imag for an example application. If you do not feed in a transform matrix, then the identity matrix is applied so that the scaling options refer to original data pixels.
To draw a colour bar (or wedge), either use the DrawWedge option,
or the draw_wedge() routine (once the image has been drawn).
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
color-table stretch.
MAX - Sets the maximum value for the same.
RANGE - A more compact way to specify MIN and MAX, as a list:
you can say "Range=>[0,10]" to scale the color table for
brightness values between 0 and 10 in the iamge data.
CRANGE - Image values between MIN and MAX are scaled to an
interval in normalized color domain space, on the
interval [0,1], before lookup in the window's color
table. CRANGE lets you use only a part of the color
table by specifying your own range -- e.g. if you
say "CRange=>[0.25,0.75]" then only the middle half
of the pseudocolor space will be used. (See the
writeup on L<ctab|ctab>.)
TRANSFORM - The transform 'matrix' as a 6x1 vector for display
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, SCALE, PIX, PITCH, ALIGN, XRANGE, YRANGE
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, ALIGN=>'CC' } );
Display an RGB color image
The calling sequence is exactly like imag, except that the input image must have three dimensions: N x M x 3. The last dimension is the (R,G,B) color value. This routine requires pgplot 5.3devel or above. Calling rgbi explicitly is not necessary, as calling image with an appropriately dimensioned RGB triplet makes it fall through to rgbi.
Display a FITS image with correct axes
$win->fits_imag( image, [$min, $max], [$opt] );
Notes:
Currently fits_imag also generates titles for you by default and appends the FITS header scientific units if they're present. So if you say
$pdl->hdr->{CTYPE1} = "Flamziness";
$pdl->hdr->{CUNIT1} = "milliBleems";
$win->fits_imag($pdl);
then you get an X title of ``Flamziness (milliBleems)''. But you can (of course) override that by specifying the XTitle and YTitle switches:
$win->fits_imag($pdl,{Xtitle=>"Arbitrary"});
will give you ``Arbitrary'' as an X axis title, regardless of what's in the header.
If CTYPE1 and CTYPE2 agree, then the default pixel aspect ratio is 1 (in scientific units, NOT in original pixels). If they don't agree (as for a spectrum) then the default pixel aspect ratio is adjusted automatically to match the plot viewport and other options you've specified.
You can override the image scaling using the SCALE, PIX, or PITCH
options just as with the imag() method -- but
those parameters refer to the scientific coordinate system rather than
to the pixel coordinate system (e.g. PITCH=100> means ``100 scientific units
per inch'', and SCALE=1> means ``1 scientific unit per device pixel''. See
the imag() writeup for more info on these
options.
The default value of the ALIGN option is 'CC' -- centering the image
both vertically and horizontally.
By default fits_imag draws a color wedge on the right; you can explicitly
set the DrawWedge option to 0 to avoid this. Use the WTitle option
to set the wedge title.
Display an RGB FITS image with correct axes
$win->fits_rgbi( image, [$min,$max], [$opt] );
Works exactly like fits_imag, but the image must be in (X,Y,RGB) form. Only the first two axes of the FITS header are examined.
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:
Width value by about 1 to keep the text readable.
Default is ''. This is equivalent to the WTitle option to
imag, fits_imag, and similar methods.
undef, uses the
value used by imag (recommended choice). Default is undef.
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.
Notionally, all non-RGB images and vectors have their colors looked up in the window's color table. Colors in images and such are scaled to a normalized pseudocolor domain on the line segment [0,1]; the color table is a piecewise linear function that maps this one-dimensional scale to the three-dimensional normalized RGB color space [0,1]^3.
You can specify specific indexed colors by appropriate use of the (levels,red,green,blue) syntax -- but that is deprecated, since the actual available number of colors can change depending on the output device. (Someone needs to write a specific hardware-dependent lookup table interface).
See also imag for a description of how to use only part of the color table for a particular image.
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, LINESTYLE, LINEWIDTH, MISSING, JUSTIFY, SCALE, PITCH, PIX, ALIGN
$x = sequence(10)/10.;
$y = sin($x)**2;
# Draw a red dot-dashed line
line $x, $y, {COLOR => 'RED', LINESTYLE=>3};
Plot a list of vectors as discrete sets of connected points
This works much like line, but for discrete sets of connected
points. There are two ways to break lines: you can pass in x/y coordinates
just like in line, but with an additional pen piddle that
indicates whether the pen is up or down on the line segment following
each point (so you set it to zero at the end of each line segment you
want to draw); or you can pass in an array ref containing a list
of single polylines to draw.
Happily, there's extra meaning packed into the pen piddle: it
multiplies the COLO(U)R that you set, so if you feed in boolean
values you get what you expect -- but you can also feed in integer
or floating-point values to get multicolored lines.
Furthermore, the sign bit of pen can be used to draw hairline segments:
if pen is negative, then the segment is drawn as though it were
positive but with LineWidth and HardLW set to 1 (the minimum).
Equally happily, even if you are using the array ref mechanism
to break your polylines you can feed in an array ref of pen values to
take advantage of the color functionality or further dice your polylines.
Note that, unlike line, lines has no no specify-$y-only
calling path. That's because lines is intended more for line art than for
plotting, so you always have to specify both $x and $y.
Infinite or bad values are ignored -- that is to say, if your vector contains a non-finite point, that point breaks the vector just as if you set pen=0 for both that point and the point before it.
Usage: $w->( $x, $y, [$pen], [$opt] );
$w->( $xy, [$pen], [$opt] );
$w->( \@xvects, \@yvects, [\@pen], [$opt] );
$w->( \@xyvects, [\@pen], [$opt] );
The following standard options influence this command: AXIS, BORDER, COLO(U)R, LINESTYLE, LINEWIDTH, MISSING, JUSTIFY, SCALE, PITCH, PIX, ALIGN
CAVEAT:
Setting pen elements to 0 prevents drawing altogether, so you
can't use that to draw in the background color.
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, LINESTYLE, LINEWIDTH, JUSTIFY, SCALE, PIX, PITCH, ALIGN
SymbolSize allows to adjust the symbol size, it defaults to CharSize.
The ColorValues option allows one to plot XYZ data with the
Z axis mapped to a color value. For example:
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())
Usage:
errb ( $y, $yerrors, [$opt] ) errb ( $x, $y, $yerrors, [$opt] ) errb ( $x, $y, $xerrors, $yerrors, [$opt] ) errb ( $x, $y, $xloerr, $xhierr, $yloerr, $yhierr, [$opt])
Any of the error bar parameters may be undef to omit those error bars.
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, LINESTYLE, LINEWIDTH, JUSTIFY, SCALE, PIX, PITCH, ALIGN
$y = sequence(10)**2+random(10);
$sigma=0.5*sqrt($y);
errb $y, $sigma, {COLOUR => RED, SYMBOL => 18};
# plot X bars only errb( $x, $y, $xerrors, undef );
# plot negative going bars only errb( $x, $y, $xloerr, undef, $yloerr, undef );
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. The transform() routine can be used to
create this piddle.
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, LINESTYLE, LINEWIDTH, JUSTIFY, SCALE, PIX, PITCH, ALIGN
$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)))
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
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, SCALE, PIX, PITCH, ALIGN
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.
$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):
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 )
Options recognised:
The following standard options influence this command:
AXIS, BORDER, COLOUR, FILLTYPE, HATCHING, LINESTYLE, LINEWIDTH JUSTIFY, SCALE, PIX, PITCH, ALIGN
# 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:
Plot an ellipse, optionally using fill style.
Usage: ellipse($x, $y, $a, $b, $theta [, $opt]);
All arguments can alternatively be given in the options hash using the following options:
$a must be given.
$x and $y must be given.
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:
Display 2 images as a vector field
Usage: vect ( $w, $a, $b, [$scale, $pos, $transform, $misval], { opt } );
$w->vect($a,$b,[$scale,$pos,$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. The transform() routine can be used to
create this piddle.
This routine will plot a vector field. $a is the horizontal component
and $b the vertical component. The scale factor converts between
vector length units and scientific positional units. You can set the
scale, position, etc. either by passing in parameters in the normal parameter
list or by passing in options.
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, 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};
Display a pair of 2-D piddles as vectors, with FITS header interpretation
Usage: fits_vect ($a, $b, [$scale, $pos, $transform, $misval] )
fits_vect is to vect as fits_imag is to imag.
Create transform array for contour and image plotting
$win->transform([$xdim,$ydim], $options);
(For information on coordinate transforms, try PDL::Transform.) 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.
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 ;)
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.
Example:
$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.
Example:
$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.
Example:
$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])
Options recognised:
ANGLEJUSTIFICATIONXPos, YPos, TextBackgroundColourBg and BackgroundColor.
The following standard options influence this command:
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.
The local options recognised are as follows:
TextXPos and YPosWidth and HeightTextFractionTextFraction
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.
TextShiftVertSpace or VSpaceVertSpace 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.
BackgroundColourBg and BackgroundColor.
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.
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.
Options recognised:
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.
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.
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});
To prevent pgplot from doing a fandango on core, we have to block interrupts during PGPLOT calls. Specifically, INT needs to get caught. These internal routines provide a mechanism for that.
You simply bracket any PGPLOT calls with &catch_signals above and
&release_signals below, and the signal_catcher will queue up any
signals (like INT -- the control-C interrupt) until the
&release_signals call.
Any exit path from your hot code must include &release_signals, or
interrupts could be deferred indefinitely (which would be a bug).
This includes calls to &barf -- even barfs from someone you called!
So avoid calling out of the local module if possible, and use
release_and_barf() instead of barf() from within this module.
Perl 5.6.1 interrupt handling has a bug that this code tickles -- sometimes the re-emitted signals vanish into hyperspace. Perl 5.8 seems NOT to have that problem.
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.
This routine sets up a new window with its shape and size. This is
also where the size options are actually parsed. These are then
forgotten (well, they are stored in $self->{Options}) and the
corresponding aspect ratio and window width is stored. See the
discussion under new() for the logic.
Finally the subpanels are set up using pgsubp and colours and linewidth
are adjusted according to whether we have a hardcopy device or not.
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 )
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:
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.
Convert a unit string or number into a PGPLOT-certified length unit specification, or return undef if it won't go.
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 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:
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.
pgqcol). Should you wish to change that you need
to read the PGPLOT documentation - it is somewhat device dependent.
pgscr command and we
are finished.
pgscrn with no other error-checking. This
should be ok, as that routine returns a rather sensible error-message.
This internal routine is the default routine for parsing options. This routine deals with a subset of options that most routines will accept.
Given a PGPLOT tr matrix and an image size, calculate the data world coordinates over which the image ranges. This is used in imag and cont. It keeps track of the required half-pixel offset to display images properly -- eg feeding in no tr matrix at all, nx=20, and ny=20 will will return (-0.5,19.5,-0.5,19.5). It also checks the options hash for XRange/YRange specifications and, if they are present, it overrides the appropriate output with the exact ranges in those fields.
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, Craig DeForest, 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.
|
PDL::Graphics::PGPLOT::Window - A OO interface to PGPLOT windows |