view release on metacpan or  search on metacpan

lib/PDL/Graphics/PGPLOT/Window.pm  view on Meta::CPAN

 pdl> $win->hold()
 pdl> $c = sin($x/10)*2 + 4
 pdl> $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.

=head1 DESCRIPTION

This package offers a OO interface to the PGPLOT plotting package. This
is intended to replace the traditional interface in
L<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.  It currently supports PGPLOT-5.2 and PGPLOT-5.2-cd2.  The
-cd2 version includes RGB output and anti-aliasing.

High-level plotting commands:

 imag       -  Display an image (uses pgimag/pggray/pgrgbi as appropriate)
 fits_imag  -  Display a FITS image in scientific coordinates
 cont       -  Display image as contour map
 fits_cont  -  Display a FITS image in scientific coordinates as a contour map
 vect       -  Display 2 images as a vector field
 fits_vect  -  Display 2 FITS images in sci. coordinates as a vector field
 ctab       -  Load an image colour table
 ctab_info  -  Get information about currently loaded colour table
 line       -  Plot vector as connected points
 tline      -  Plot a collection of vectors as lines
 lines      -  Plot a polyline, multicolor vector [broadcastable]
 points     -  Plot vector as points
 tpoints    -  Plot a collection of vectors as points [broadcastable]
 errb       -  Plot error bars
 bin        -  Plot vector as histogram (e.g. bin(hist($data)) )
 hi2d       -  Plot image as 2d histogram (not very good IMHO...)
 tcircle    -  Plot vectors as circles [broadcastable]
 label_axes -  Print axis titles
 legend     -  Create a legend with different texts, linestyles etc.

Low-level plotting commands:

 arrow      -  Draw an arrow
 poly       -  Draw a polygon
 rectangle  -  Draw a rectangle
 text       -  Write text in the plot area
 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.
 hold          -  Hold current plot window range - allows overlays etc.
 release       -  Release back to freshly autoscaling for each command.
 held          -  Indicates whether the current window is held.
 focus         -  Set focus to the given device.
 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: C<$transform> for image/cont etc. is used in the same way as the
C<TR()> array in the underlying PGPLOT FORTRAN routine but is, fortunately,
zero-offset. The L<transform()|/transform> routine can be used to create this ndarray.

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

=head2 Variable passing and extensions

In general variables are passed to the pgplot routines by using
C<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 C<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 an ndarray with dimensions (1,100,1,1) is passed to C<line>, which
expects its inputs to be vectors. C<checkarg> will then return an ndarray
with dimensions (100). If instead the same ndarray was passed to C<imag>,
which requires 2D ndarrays as output, C<checkarg> would return an ndarray
with dimensionality (100, 1) (Dimensions are removed from the I<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);
 };
 1;

(the catch_signals block prevents problems with the perl-PGPLOT
interface if the user hits Ctrl-C during an operation).

=head2 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.