.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PGPLOT 3pm"
.TH PGPLOT 3pm "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::Graphics::PGPLOT \- PGPLOT enhanced interface for PDL
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\& pdl> $x = pdl [1..100]
\& pdl> $y = sqrt($x)
\& pdl> line $y
\& pdl> hold
\& Graphics on HOLD
\& pdl> $c = sin($x/10)*2 + 4
\& pdl> line $c
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`PDL::Graphics::PGPLOT\*(C'\fR is a convenience interface to the \s-1PGPLOT\s0 commands,
implemented using the object oriented \s-1PGPLOT\s0 plotting package in
PDL::Graphics::PGPLOT::Window. See the documentation for that package
for in-depth information about the usage of these commands and the options
they accept.
.PP
The list of currently availably commands:
.PP
.Vb 10
\& 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.
.Ve
.PP
Device manipulation commands:
.PP
.Vb 10
\& 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 \*(Aqrelease\*(Aq
\& env          \-  Define a plot window, put on \*(Aqhold\*(Aq
\& 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 existing plot windows
\& close_window \-  Close an open window
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
The following is a list of the functions that are private to this package,
for the other functions please read the PDL::Graphics::PGPLOT::Window
documentation.
.SS "dev"
.IX Subsection "dev"
Open \s-1PGPLOT\s0 graphics device
.PP
.Vb 1
\& Usage: dev $device, [$nx,$ny, $opt];
.Ve
.PP
\&\f(CW$device\fR is a \s-1PGPLOT\s0 graphics device such as \*(L"/xserve\*(R" or \*(L"/ps\*(R",
if omitted defaults to last used device (or value of env
var \f(CW\*(C`PGPLOT_DEV\*(C'\fR if first time).
\&\f(CW$nx\fR, \f(CW$ny\fR specify sub-panelling. The function returns the id of
the newly created window \- this can subsequently be used as argument to
\&\f(CW\*(C`focus_window\*(C'\fR to select the window.
.PP
The result of this command can be modified using options. The options
recognised are the same as for \f(CW\*(C`new_window\*(C'\fR \- which primarily and in
addition it is possible to set the default values for a window that are
defined in PDL::Graphics::PGPLOTOptions, see this for details but see below for
a synopsis.
.PP
In addition \f(CW\*(C`dev\*(C'\fR recognises the option \f(CW\*(C`NewWindow\*(C'\fR which allows the
user to specify that a \f(CW\*(C`dev\*(C'\fR 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.
.PP
Here is a quick summary of the most useful additional options that can
be given:
.IP "Device" 4
.IX Item "Device"
Alternative to \f(CW$device\fR.
.IP "AspectRatio" 4
.IX Item "AspectRatio"
The aspect ratio of the output window
.IP "WindowWidth" 4
.IX Item "WindowWidth"
The width of the plot window in inches
.IP "AxisColour" 4
.IX Item "AxisColour"
The axis colour to be used as default for plots in this window. In the same
way it is possible to set the default character size (\f(CW\*(C`CharSize\*(C'\fR) and axis
and box styles. See PDL::Graphics::PGPLOTOptions for details.
.IP "WindowName" 4
.IX Item "WindowName"
The name of a window. This name can subsequently be used to refer to the
window instead of its \s-1ID,\s0 making interactive use somewhat more intuitive.
.PP
To open a X\-window output that will stay on screen:
.PP
.Vb 1
\&  $win = dev(\*(Aq/xs\*(Aq);
.Ve
.PP
To open two windows, one small and square, one large and wide:
.PP
.Vb 2
\&  $win1 = dev(\*(Aq/xs\*(Aq, {Aspect => 1, WindowWidth => 4});
\&  $win2 = dev(\*(Aq/xs\*(Aq, {Aspect => 0.5, WindowWidth => 10});
.Ve
.SS "new_window"
.IX Subsection "new_window"
Open a \s-1PGPLOT\s0 graphics device
.PP
.Vb 1
\&  $win = new_window($dev, $nx, $ny, $opt);
.Ve
.PP
This function is identical to \*(L"dev\*(R" except that it always creates a new
window. This means that the user is required to close all windows
explicitly using \*(L"close_window\*(R". All functionality is otherwise like \f(CW\*(C`dev\*(C'\fR
so see the documentation for \*(L"dev\*(R" for details of use.
.SS "close_window"
.IX Subsection "close_window"
Close a \s-1PGPLOT\s0 output device
.PP
.Vb 1
\& Usage: close_window($id)
.Ve
.PP
This function closes a \s-1PGPLOT\s0 output device created with \f(CW\*(C`dev\*(C'\fR or
\&\f(CW\*(C`new_window\*(C'\fR. It requires the id of the window to close. If \f(CW$id\fR is
left undefined, the currently focussed window is deleted and focus is
transferred to the lowest numbered window in existence. If many windows
have been created and deleted this might not be what you expect, so
it is recommended to make an explicit call to \*(L"focus_window\*(R" after
any call to \f(CW\*(C`close_window\*(C'\fR.
.SS "_get_windownumber"
.IX Subsection "_get_windownumber"
Internal function to obtain the \s-1ID\s0 of a window. This allows the user
to refer to a window with its name.
.SS "focus_window"
.IX Subsection "focus_window"
Switch to another output window.
.PP
.Vb 1
\& Usage: focus_window($id);
.Ve
.PP
This command is used to switch output focus to another window created by
\&\*(L"dev\*(R" or \*(L"new_window\*(R". The window can be referred to either by its
\&\s-1ID\s0 or by its name.
.PP
.Vb 2
\&  $win1 = dev(\*(Aq/xs\*(Aq, {WindowName => \*(AqX\-output\*(Aq});
\&  $win2 = dev(\*(Aqtest.ps/ps\*(Aq, {WindowName => \*(AqPS\-output\*(Aq});
\&
\&  focus_window(\*(AqX\-output\*(Aq);  # Or focus_window($win1);
\&  <.. Commands ..>
\&  focus_window($win2);       # Or focus_window(\*(AqPS\-output\*(Aq);
\&  <.. Commands ..>
.Ve
.SS "window_list"
.IX Subsection "window_list"
Return a list of \s-1ID\s0 numbers and names of the windows currently opened using
\&\*(L"dev\*(R" or \*(L"new_window\*(R".
.PP
.Vb 1
\& Usage: ($numbers, $names)=window_list();
.Ve
.PP
\&\f(CW$numbers\fR and \f(CW$names\fR are anonymous arrays giving the \s-1ID\s0 numbers and
names of the open windows respectively.