.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "PGPLOT 3pm"
.TH PGPLOT 3pm "2016-09-24" "perl v5.24.1" "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"
PGPLOT \- allow subroutines in the PGPLOT graphics library to be called from Perl.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use PGPLOT;
\&
\& pgbegin(0,"/xserve",1,1);  
\& pgenv(1,10,1,10,0,0);        
\& pglabel(\*(AqX\*(Aq,\*(AqY\*(Aq,\*(AqMy plot\*(Aq);  
\& pgpoint(7,[2..8],[2..8],17);
\&
\& # etc...
\&
\& pgend;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Originally developed in the olden days of Perl4 (when it was known
as 'pgperl' due to the necessity of making a special perl executable)
\&\s-1PGPLOT\s0 is now a dynamically loadable perl module which interfaces
to the \s-1FORTRAN\s0 graphics library of the same name.
.PP
\&\s-1PGPLOT,\s0 originally developed as a \s-1FORTRAN\s0 library, is now available with
C bindings (which the Perl module uses), though a \s-1FORTRAN\s0 compiler is
still required to build it.
.PP
For every \s-1PGPLOT C/FORTRAN\s0 function the module provides an equivalent
Perl function with the same arguments. Thus the user of the module should
refer to the \s-1PGPLOT\s0 manual to learn all about how to use \s-1PGPLOT\s0 and for
the complete list of available functions.  This manual comes with the
\&\s-1PGPLOT\s0 distribution and is also available at the \s-1WWW\s0 address:
.PP
http://astro.caltech.edu/~tjp/pgplot/
.PP
Also refer to the extensive set of test scripts (\f(CW\*(C`test*.p\*(C'\fR) included
in the module distribution for examples of usage of all kinds of
\&\s-1PGPLOT\s0 routines.
.PP
How the \s-1FORTRAN/C\s0 function calls map on to Perl calls is detailed below.
.SS "\s-1ARGUMENT MAPPING \- SIMPLE NUMBERS AND ARRAYS\s0"
.IX Subsection "ARGUMENT MAPPING - SIMPLE NUMBERS AND ARRAYS"
This is more or less as you might expect \- use Perl scalars 
and Perl arrays in place of \s-1FORTRAN/C\s0 variables and arrays.
.PP
Any \s-1FORTRAN\s0 REAL/INTEGER/CHARACTER* scalar variable maps to a
Perl scalar (Perl doesn't care about the differences between
strings and numbers and ints and floats).
.PP
Thus you can say:
.PP
To draw a line to point (42,$x):
.PP
.Vb 1
\& pgdraw(42,$x);
.Ve
.PP
To plot 10 points with data in Perl arrays \f(CW@x\fR and \f(CW@y\fR with plot symbol
no. 17. Note the Perl arrays are passed by reference:
.PP
.Vb 1
\& pgpoint(10, \e@x, \e@y, 17);
.Ve
.PP
You can also use the old Perl4 style:
.PP
.Vb 1
\& pgpoint(10, *x, *y, 17);
.Ve
.PP
but this is deprecated in Perl5.
.PP
Label the axes:
.PP
.Vb 1
\& pglabel("X axis", "Data units", $label);
.Ve
.PP
Draw \s-1ONE\s0 point, see how when \f(CW\*(C`N=1\*(C'\fR \f(CW\*(C`pgpoint()\*(C'\fR can take a scalar as well as
a array argument:
.PP
.Vb 1
\&  pgpoint(1, $x, $y, 17);
.Ve
.SS "\s-1ARGUMENT MAPPING \- IMAGES AND 2D ARRAYS\s0"
.IX Subsection "ARGUMENT MAPPING - IMAGES AND 2D ARRAYS"
Many of the \s-1PGPLOT\s0 commands (e.g. \f(CW\*(C`pggray\*(C'\fR) take 2D arrays as
arguments. Several schemes are provided to allow efficient use
from Perl:
.IP "1." 4
Simply pass a reference to a 2D array, e.g:
.Sp
.Vb 1
\&  # Create 2D array
\&
\&  $x=[];
\&  for($i=0; $i<128; $i++) { 
\&     for($j=0; $j<128; $j++) {
\&       $$x[$i][$j] = sqrt($i*$j); 
\&     }
\&  }
\&  pggray( $x, 128, 128, ...);
.Ve
.IP "2." 4
Pass a reference to a 1D array:
.Sp
.Vb 7
\&  @x=();
\&  for($i=0; $i<128; $i++) { 
\&     for($j=0; $j<128; $j++) {
\&       $x[$i][$j] = sqrt($i*$j); 
\&     }
\&  }
\&  pggray( \e@x, 128, 128, ...);
.Ve
.Sp
Here \f(CW@x\fR is a 1D array of 1D arrays. (Confused? \- see \fIperldata\fR\|(1)).
Alternatively \f(CW@x\fR could be a flat 1D array with 128x128 elements, 2D
routines such as \f(CW\*(C`pggray()\*(C'\fR etc. are programmed to do the right thing
as long as the number of elements match.
.IP "3." 4
If your image data is packed in raw binary form into a character string
you can simply pass the raw string. e.g.:
.Sp
.Vb 2
\&   read(IMG, $img, 32768); 
\&   pggray($img, $xsize, $ysize, ...);
.Ve
.Sp
Here the \f(CW\*(C`read()\*(C'\fR function reads the binary data from a file and the
\&\f(CW\*(C`pggray()\*(C'\fR function displays it as a grey-scale image.
.Sp
This saves unpacking the image data in to a potentially very large 2D
perl array. However the types must match. The string must be packed as a
\&\f(CW"f*"\fR for example to use \f(CW\*(C`pggray\*(C'\fR. This is intended as a short-cut for
sophisticated users. Even more sophisticated users will want to download
the \f(CW\*(C`PDL\*(C'\fR module which provides a wealth of functions for manipulating
binary data.
.Sp
\&\s-1PLEASE NOTE:\s0 As \s-1PGPLOT\s0 is a Fortran library it expects it's images to be
be stored in row order. Thus a 1D list is interpreted as a sequence of
rows end to end. Perl is similar to C in that 2D arrays are arrays of
pointers thus images end up stored in column order.
.Sp
Thus using perl multidimensional arrays the coordinate ($i,$j) should be
stored in \f(CW$img\fR[$j][$i] for things to work as expected, e.g:
.Sp
.Vb 5
\&   $img = [];
\&   for $j (0..$nx\-1) for $i (0..$ny\-1) { 
\&      $$img[$j][$i] = whatever();
\&   }}
\&   pggray($$img, $nx, $ny, ...);
.Ve
.Sp
Also \s-1PGPLOT\s0 displays coordinate (0,0) at the bottom left (this is
natural as the subroutine library was written by an astronomer!).
.SS "\s-1ARGUMENT MAPPING \- FUNCTION NAMES\s0"
.IX Subsection "ARGUMENT MAPPING - FUNCTION NAMES"
Some \s-1PGPLOT\s0 functions (e.g. \f(CW\*(C`pgfunx\*(C'\fR) take functions as callback
arguments. In Perl simply pass a subroutine reference or a name,
e.g.:
.PP
.Vb 1
\& # Anonymous code reference:
\&
\& pgfunx(sub{ sqrt($_[0]) },  500, 0, 10, 0);
\&
\& # Pass by ref:
\&
\& sub foo {
\&   my $x=shift;
\&   return sin(4*$x);
\& }
\&
\& pgfuny(\e&foo, 360, 0, 2*$pi, 0);
\&
\& # Pass by name:
\&
\& pgfuny("foo", 360, 0, 2*$pi, 0);
.Ve
.SS "\s-1ARGUMENT MAPPING \- GENERAL HANDLING OF BINARY DATA\s0"
.IX Subsection "ARGUMENT MAPPING - GENERAL HANDLING OF BINARY DATA"
In addition to the implicit rules mentioned above \s-1PGPLOT\s0 now provides
a scheme for explicitly handling binary data in all routines.
.PP
If your scalar variable (e.g. \f(CW$x\fR) holds binary data (i.e. 'packed')
then simply pass \s-1PGPLOT\s0 a reference to it (e.g. \f(CW\*(C`\e$x\*(C'\fR). Thus one can
say:
.PP
.Vb 3
\&   read(MYDATA, $wavelens, $n*4);
\&   read(MYDATA, $spectrum, $n*4);
\&   pgline($n, \e$wavelens, \e$spectrum);
.Ve
.PP
This is very efficient as we can be sure the data never gets copied
and will always be interpreted as binary.
.PP
Again see the \f(CW\*(C`PDL\*(C'\fR module for sophisticated manipulation of
binary data. \f(CW\*(C`PDL\*(C'\fR takes great advantage of these facilities.
.PP
Be \s-1VERY\s0 careful binary data is of the right size or your segments
might get violated.