Unix/Linux Go Back    


RedHat 9 (Linux i386) - man page for pdl::graphics::pgplot::window (redhat section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Window(3)		       User Contributed Perl Documentation			Window(3)

NAME
       PDL::Graphics::PGPLOT::Window - A OO interface to PGPLOT windows

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

DESCRIPTION
       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() rou-
       tine 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

       Variable passing and extensions

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

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

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

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

       Setting options

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

       This is implemented such that the plotting settings (such as line width, line style etc.)
       are affected only for that plot, any global changes made, say, with "pgslw()" are pre-
       served. Some modifications apply when using the OO interface, see below.

       Alphabetical listing of standard options

       The following options are always parsed. Whether they have any importance depend on the
       routine invoked - e.g. line style is irrelevant for "imag", or the "justify" option is
       irrelevant if the display is on 'hold'.	This is indicated in the help text for the com-
       mands 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]

       arrow
	   This options allows you to set the arrow shape, and optionally size for arrows for the
	   vect routine. The arrow shape is specified as a hash with the key FS to set fill
	   style, ANGLE to set the opening angle of the arrow head, VENT to set how much of the
	   arrow head is cut out and SIZE to set the arrowsize.

	   The following

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

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

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

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

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

       arrowsize
	   The arrowsize can be specified separately using this option to the options hash. It is
	   useful if an arrowstyle has been set up and one wants to plot the same arrow with sev-
	   eral 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};

       axis
	   Set the axis value (see "env").  It can either be specified as a number, or by one of
	   the following names:

	    EMPTY  (-2) draw no box, axes or labels
	    BOX    (-1) draw box only
	    NORMAL(0)	draw box and label it with coordinates
	    AXES(1)	same as NORMAL, but also draw (X=0,Y=0) axes
	    GRID(2)	same as AXES, but also draw grid lines
	    LOGX(10) draw box and label X-axis logarithmically
	    LOGY(20) draw box and label Y-axis logarithmically
	    LOGXY(30) draw box and label both axes logarithmically

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

	    BORDER => { TYPE => 'rel', VALUE => 0.05 }

       charsize
	   Set the character/symbol size as a multiple of the standard size.

	    $opt = {CHARSIZE => 1.5}

	   The HardCH option should be used if you are plotting to a hardcopy device.

       colour (or color)
	   Set the colour to be used for the subsequent plotting. This can be specified as a num-
	   ber, and the most used colours can also be specified with name, according to the fol-
	   lowing 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.

	   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?].

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

       font
	   Set the character font. This can either be specified as a number following the PGPLOT
	   numbering or name as follows (name in capitals):

	    1 - NORMAL
	    2 - ROMAN
	    3 - ITALIC
	    4 - SCRIPT

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

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

	   gives the same result as

	    $opt = {FONT => 2};

	   The HardFont option should be used if you are plotting to a hardcopy device.

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

	    $opt = {FILLTYPE => 'HATCHED',
		    HATCHING => {ANGLE=>30, SEPARATION=>4}};

	   Can also be specified as

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

	   For another example of hatching, see "poly".

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

       linestyle
	   Set the line style. This can either be specified as a number following the PGPLOT num-
	   bering:

	    1 - SOLID line
	    2 - DASHED
	    3 - DOT-DASH-dot-dash
	    4 - DOTTED
	    5 - DASH-DOT-DOT-dot

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

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

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

       linewidth
	   Set the line width. It is specified as a integer multiple of 0.13 mm.

	    $opt = {LINEWIDTH => 10}; # A rather fat line

	   The HardLW option should be used if you are plotting to a hardcopy device.

       plotting range
	   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.

	     line $x, $y, {xr => [0,5]}; # y-range uses default
	     line $x, $y, {Xrange => [0,5], Yrange => [-1,3]}; # fully specified range

OBJECT-ORIENTED INTERFACE
       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

       Multiple windows.
	   For the common user it is probably most interesting to use the OO interface when han-
	   dling 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.

       Coding and abstraction
	   At a more fundamental level it is desirable to approach a situation where it is possi-
	   ble 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.

	   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.

STATE and RECORDING
       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.

       Use of recording

       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.

       Controlling the recording

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

       Tips and Gotchas!

       The data are stored in the state object as references to the real data. This leads to one
       good and one potentially bad consequence:

       The good is that you can create the plot and then subsequently redo the same plot using a
       different set of data. This is best explained by an example. Let us first create a simple
       gradient image and get a copy of the recording:
	     $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

       This takes us immediately to the major problem with the recording though. Memory leakage!
       Since the recording keeps references to the data it can keep data from being freed (zero
       reference count) when you expect it to be. For instance, in this example, we lose totally
       track of the original $im variable, but since there is a reference to it in the state it
       will not be freed
	     $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 rec-
	   ommend that you do not turn on recording unless you need it.

FUNCTIONS
       A more detailed listing of the functions and their usage follows. For all functions we
       specify which options take effect and what other options exist for the given function. 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. When-
       ever 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.

       Window control functions.

       pgwin

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

       new

       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:

       AspectRatio
	   The aspect ratio of the image, in the sense vertical/horizontal.  See the discussion
	   on size setting.

       Device
	   The type of device to use. The syntax of this is the one used by PGPLOT.

       Hold
	   Hold the plot window so that subsequent plots can plot over existing plots.	This can
	   be adjusted with the "hold()" and "release()" methods.

       NXPanel
	   The number of panels in the X-direction

       NYPanel
	   The number of panels in the Y-direction

       Size
	   Yet another way to identify the plot window size -- this takes a scalar or an array
	   ref containing one, two, or three numbers.  One number gives you a square window.  Two
	   gives you a rectangular window (X,Y).  Three lets you specify the unit compactly (e.g.
	   [<X>,<Y>,1] for inches, [<X>,<Y>,2] for mm) but is deprecated in favor of using the
	   Unit option.  See the discussion on size setting.

       Unit
	   The unit to use for size setting.  PGPLOT accepts inch, mm, or pixel.  The default
	   unit is inches for historical reasons, but you can choose millimeters or (God forbid)
	   pixels as well.  String or numeric specifications are OK (0=normalized, 1=inches,
	   2=mm, 3=pixels).  Normalized units make no sense here and are not accepted.	Ideally
	   someone will one day hook this into the CPAN units parser so you can specify window
	   size in rods or attoparsecs.

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

       WindowWidth
	   The width of the window in inches (or the specified Unit).  See the discussion on size
	   setting.

       WindowXSize and WindowYSize
	   The width and height of the window in inches (or the specified Unit).  See the discus-
	   sion on size setting.

       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

       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.

       held

       Check if a window is on hold

	 $is_held = $win->held();

       Function to check whether the window is held or not.

       hold

       Hold the present window.

	Usage: $win->hold()

       Holds the present window so that subsequent plot commands overplots.

       panel

       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

       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

       Erase plot

	 $win->erase($opt);

       Erase a plot area. This accepts the option "Panel" or alternatively a number or array ref-
       erence which makes it possible to specify the panel to erase when working with several
       panels.

       Plotting functions

       env

       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 exam-
       ple:

	$win->env( 0, 100, 0, 50, {JUSTIFY => 1, AXIS => 'GRID',
				   CHARSIZE => 0.7} );

       In addition the following options can also be set for "env":

       PlotPosition
	   The position of the plot on the page relative to the view surface in normalised coor-
	   dinates 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]});

       Axis, Justify, Border
	   See the description of general options for these options.

       AxisColour
	   Set the colour of the coordinate axes.

       XTitle, YTitle, Title, Font, CharSize
	   Axes titles and the font and size to print them.

       label_axes

       Label plot axes

	 $win->label_axes(<xtitle>, <ytitle>, <plot title>, $options);

       Draw labels for each axis on a plot.

       imag

       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() rou-
       tine can be used to create this piddle.

       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
		    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 "portrait mode" pixels
		    to match the C<Aspect> standard parameter in the PGPLOT
		    constructor.  PIX overrides the boolean C<Justify> standard
		    PGPLOT option; but C<Justify=>1> acts the same as
		    C<PIX=>1>.

	    PITCH - Sets the number of image pixels per screen unit, in the X
		    direction.	The Y 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

	    ALIGN - How to align the image in the box.	Two-character string
		    with "L","R", or "C" in the first character and
		    "T", "B", or "C" in the second character.  This should
		    probably be implemented in a more general way but works
		    for now.  Default is "BL".	This doesn't make sense unless
		    you're manually messing with the scaling anyhow, because
		    if you're not, then the image is scaled to exactly fit the box.

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

       imag1

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

       fits_imag

       Display a FITS image with correct axes

	 $win->fits_imag( image,  [$min, $max], [$opt] );

       Notes:

       Currently fits_imag also generates titles for you and appends the CTYPE units if they're
       present.  So if you say

	 $win->fits_imag($pdl, {xtitle=>"frobnitz"})

       you automagically get an X axis label that says "frobnitz (bleems)", if $pdl's CTYPE1
       field contains "bleems".

       If you don't pass in an xtitle or ytitle parameter, you still get the units designation.
       But if there's no CTYPE1 or CTYPE2 then you get no units designation.

       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 to match the plot viewport.

       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.

       draw_wedge

       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" rou-
       tine.

       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:

       Side
	   Which side of the image to draw the wedge: can be one of 'B', 'L', 'T', or 'R'.
	   Default is 'R'.

       Displacement
	   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 1.5.

       Width
	   How wide should the wedge be, in units of character size.  Default is 2.

       Label
	   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 ''.

       ForeGround (synonym Fg)
	   The pixel value corresponding to the "maximum" colour.  If "undef", uses the value
	   used by "imag" (recommended choice).  Default is "undef".

       BackGround (synonym Bg)
	   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'} } );

       ctab

       Load an image colour table.

	Usage:

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

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

       line

       Plot vector as connected points

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

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

       The following standard options influence this command:

	AXIS, BORDER, COLO(U)R, JUSTIFY, LINESTYLE, LINEWIDTH, MISSING

	$x = sequence(10)/10.;
	$y = sin($x)**2;
	# Draw a red dot-dashed line
	line $x, $y, {COLOR => 'RED', LINESTYLE=>3};

       points

       Plot vector as points

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

       Options recognised:

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

       The following standard options influence this command:

	AXIS, BORDER, CHARSIZE, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH

       "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

       errb

       Plot error bars (using "pgerrb()")

       Usage:

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

       Options recognised:

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

       The following standard options influence this command:

	AXIS, BORDER, CHARSIZE, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH

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

       cont

       Display image as contour map

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

       Notes: $transform for image/cont etc. is used in the same way as the "TR()" array in the
       underlying PGPLOT FORTRAN routine but is, fortunately, zero-offset. The transform() rou-
       tine 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, JUSTIFY, LINESTYLE, LINEWIDTH

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

       bin

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

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

       Options recognised:

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

       The following standard options influence this command:

	AXIS, BORDER, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH

       hi2d

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

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

       Options recognised:

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

       The following standard options influence this command:

	AXIS, BORDER, JUSTIFY

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

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

       arrow

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

       poly

       Draw a polygon

	Usage: poly ( $x, $y )

       Options recognised:

       The following standard options influence this command:

	AXIS, BORDER, COLOUR, FILLTYPE, HATCHING, JUSTIFY, LINESTYLE,
	LINEWIDTH

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

       circle

       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:

       XCenter and YCenter
	   The position of the center of the circle

       Radius
	   The radius of the circle.

       ellipse

       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:

       MajorAxis
	   The major axis of the ellipse - this must be defined or $a must be given.

       MinorAxis
	   The minor axis, like A this is required.

       Theta (synonym Angle)
	   The orientation of the ellipse - defaults to 0.0. This is given in radians.

       XCenter and YCenter
	   The coordinates of the center of the ellipse. These must be specified or $x and $y
	   must be given.

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

       rectangle

       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 rou-
       tine recognises the same options as "poly" and in addition the following:

       XCenter and YCenter
	   The position of the center of the rectangle. XCentre and YCentre are valid synonyms.

       XSide and YSide
	   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

       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.

       Angle (synonym Theta)
	   The angle at which the rectangle is to be drawn. This defaults to 0.0 and is given in
	   radians.

       vect

       Display 2 images as a vector field

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

       Notes: $transform for image/cont etc. is used in the same way as the "TR()" array in the
       underlying PGPLOT FORTRAN routine but is, fortunately, zero-offset. The transform() rou-
       tine can be used to create this piddle.

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

       Options recognised:

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

       The following standard options influence this command:

	ARROW, ARROWSIZE, AXIS, BORDER, CHARSIZE, COLOUR, JUSTIFY,
	LINESTYLE, LINEWIDTH

	$a=rvals(11,11,{Centre=>[5,5]});
	$b=rvals(11,11,{Centre=>[0,0]});
	vect $a, $b, {COLOR=>YELLOW, ARROWSIZE=>0.5, LINESTYLE=>dashed};

       transform

       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.

       Angle
	   The rotation angle of the transform

       ImageDimensions
	   The dimensions of the image the transform is required for. The dimensions should be
	   passed as a reference to an array.

       Pixinc
	   The increment in output coordinate per pixel.

       ImageCenter (or ImageCentre)
	   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 use-
	   ful in the common case  when the center is (0, 0).

       RefPos (or ReferencePosition)
	   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 ;)

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

       tline

       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 "rea-
       sonable" 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);

       tpoints

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

       Text routines

       text

       Write text in a plot window at a specified position.

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

       Options recognised:

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

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

       legend

       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 char-
       acter 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:

       "Text"
	   An anonymous array of annotations, can also be specified directly.

       "XPos" and "YPos"
	   The X and Y position of the upper left-hand corner of the text.

       "Width" and "Height"
	   The width and/or height of each line (including symbol/line). This is used to deter-
	   mine the character size. If any of these are set to 'Automatic' the current character
	   size will be used.

       "TextFraction"
	   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 "Frac-
	   tion" as a synonym to this.

       "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" or "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.

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

	 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.

       Cursor routines

       cursor

       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 set-
       ting 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:

       XRef, YRef
	   The reference position to be used

       Type
	   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), "Rectan-
	   gle" (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(Verti-
	   cal|Horizontal)Lines" cursor the X or Y reference point, respectively, must be speci-
	   fied.

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

       Internal routines

       signal_catcher, catch_signals, release_signals

       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 mecha-
       nism 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.

       _open_new_window

       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.

       _setup_window

       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.

       _status

       This routine checks the status of the window. It returns OPEN if the window is open and
       CLOSED if it is closed.

       _reopen

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

       _advance_panel

       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.

       _check_move_or_erase

       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.

       _thread_options

       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.

       options

       Access the options used when originally opening the window. At the moment this is not
       updated when the window is changed later.

       id

       Access the window ID that PGPLOT uses for the present window.

       device

       This function returns the device type of the present window.

       name

       Accessor to set and examine the name of a window.

       focus

       Set focus for subsequent PGPLOT commands to this window.

       info

       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 ques-
       tion mark ("?") is returned if the item is not recognised or the information is not avail-
       able.

       _extract_hash

       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.

       _parse_unit

       Convert a unit string or number into a PGPLOT-certified length unit specification, or
       return undef if it won't go.

       _parse_options

       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.

       _save_status

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

       _checkarg

       This routine checks and optionally alters the arguments given to it.

       _set_colour

       This is an internal routine that encapsulates all the nastiness of setting colours depend-
       ing on the different PGPLOT colour models (although HLS is not supported).

       The routine works in the following way:

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

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

       o       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" refer-
	       ence it will be converted to an array ref.

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

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

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

       _standard_options_parser

       This internal routine is the default routine for parsing options. This routine deals with
       a subset of options that most routines will accept.

       _SetupViewport

       Set up the plotting viewport in the current PGPLOT window, using the options hash.  Needed
       in both initenv() and imag(), _SetupViewport is isolated in its own sub to enforce consis-
       tency of behavior.

INTERNAL
       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 vari-
       ables.

AUTHOR
       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 Tuo-
       mas 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 dis-
       tribution. If this file is separated from the PDL distribution, the copyright notice
       should be included in the file.

perl v5.8.0				    2002-08-19					Window(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:58 AM.