view release on metacpan or  search on metacpan

Graphics/PGPLOT/PGPLOT.pm  view on Meta::CPAN

# Graphics functions for the PDLA module, this module
# requires the PGPLOT module be previously installed.
# PGPLOT functions are also made available to the caller.

=head1 NAME

PDLA::Graphics::PGPLOT - PGPLOT enhanced interface for PDLA

=head1 SYNOPSIS

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

=head1 DESCRIPTION

C<PDLA::Graphics::PGPLOT> is a convenience interface to the PGPLOT commands,
implemented using the object oriented PGPLOT plotting package in
L<PDLA::Graphics::PGPLOT::Window|PDLA::Graphics::PGPLOT::Window>. See the documentation for that package
for in-depth information about the usage of these commands and the options
they accept.

The list of currently availably commands:

 imag       -  Display an image (uses pgimag()/pggray() as appropriate)
 im         -  Shorthand to display an image with aspect ratio of 1
 fits_imag  -  Display a FITS image with appropriate transforms & labels
 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
 points     -  Plot vector as points
 errb       -  Plot error bars
 bin        -  Plot vector as histogram (e.g. bin(hist($data)) )
 hi2d       -  Plot image as 2d histogram (not very good IMHO...)
 poly       -  Draw a polygon
 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:

 hold         -  Hold current plot window range - allows overlays etc.
 release      -  Release back to autoscaling of new plot window for each 
                 command
 rel          -  short alias for 'release'
 env          -  Define a plot window, put on 'hold'
 dev          -  Explicitly set a new PGPLOT graphics device
 new_window   -  Create a new plot window (use of dev is recommended)
 focus_window -  Change focus to a new window
 window_list  -  Get a list of currently exisiting plot windows
 close_window -  Close an open window


=head1 FUNCTIONS

The following is a list of the functions that are private to this package,
for the other functions please read the L<PDLA::Graphics::PGPLOT::Window|PDLA::Graphics::PGPLOT::Window>
documentation.

=head2 dev

=for ref

Open PGPLOT graphics device

=for usage

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

C<$device> is a PGPLOT graphics device such as "/xserve" or "/ps",
if omitted defaults to last used device (or value of env
var C<PGPLOT_DEV> if first time).
C<$nx>, C<$ny> specify sub-panelling. The function returns the id of
the newly created window - this can subsequently be used as argument to
C<focus_window> to select the window.

The result of this command can be modified using options. The options
recognised are the same as for C<new_window> - which primarily and in
addition it is possible to set the default values for a window that are
defined in L<PDLA::Graphics::PGPLOTOptions|PDLA::Graphics::PGPLOTOptions>, see this for details but see below for
a synopsis.

In addition C<dev> recognises the option C<NewWindow> which allows the
user to specify that a C<dev> command is to create a new window rather than
closing the previous. This allows a large number of output destinations to
be open at the same time, which occasionally can be convenient.

Here is a quick summary of the most useful additional options that can
be given:

=over

=item Device

Alternative to C<$device>.

=item AspectRatio

The aspect ratio of the output window

=item WindowWidth