.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 "2020-11-09" "perl v5.32.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"
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"
This module provides an inteface to the \s-1PGPLOT\s0 graphics library. To
obtain the library and its manual, see \*(L"\s-1OBTAINING PGPLOT\*(R"\s0.
.PP
For every \s-1PGPLOT\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. Note that \s-1PGPLOT\s0 is at
its heart a Fortran library, so the documentation describes the
Fortran interface.
.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 function calls map on to Perl calls is detailed below.
.SS "Argument Mapping \- Simple Numbers And Arrays"
.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 "Argument Mapping \- Images And 2d Arrays"
.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 \fBperldata\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
\&\fIPlease Note\fR: As \s-1PGPLOT\s0 is a Fortran library it expects its 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 "Argument Mapping \- Function Names"
.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 "Argument Mapping \- General Handling Of Binary Data"
.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 \s-1PDL\s0 module for sophisticated manipulation of
binary data, since it takes great advantage of these facilities.
See in particular PDL::Graphics::PGPLOT.
.PP
Be \s-1VERY\s0 careful binary data is of the right size or your segments
might get violated.
.SH "HISTORY"
.IX Header "HISTORY"
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.
.SH "OBTAINING PGPLOT"
.IX Header "OBTAINING PGPLOT"
\&\s-1PGPLOT\s0 is a \s-1FORTRAN\s0 library with C bindings, While the Perl module
uses the latter, a \s-1FORTRAN\s0 compiler is still required to build the library.
.PP
The official library and the manual are available from
.PP
Building the library using the official distribution is arcane, tedious,
and error-prone. Additionally, the official distribution lacks a number
of bug fixes and additions provided by the community over the years.
.PP
A modern packaging (using the \s-1GNU\s0 autotools) of the more up-to-date
code base is available from
.PP
The packaging has been tested on Linux and Mac \s-1OS X.\s0
.PP
Source code is available at either of these sites
.IP "" 4
.IX Item ""
.PD 0
.IP "" 4
.IX Item ""
.PD
.SH "AUTHORS"
.IX Header "AUTHORS"
Karl Glazebrook