- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    PGPERL        - A GRAPHICS EXTENSION FOR PERL.
    ------        - A MACRO LANGUAGE FOR PGPLOT.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

INTRODUCTION
------------

'pgperl' is a version of the Perl language which has available
the PGPLOT FORTRAN library, a very popular package for plotting
astronomical data. (As a glance through any issue of ApJ or MNRAS will
confirm.) The details of this involve some complicated C glue routines
but are transparent to the user.

The idea is to provide a command langage for PGPLOT and a more
beautiful alternative to the various (incompatible) flavours of MONGO.
Personally I have always thought that PGPLOT produced far nicer plots
but at greater pain owing to the long compile/link/run cycle of F77 or
C.  Wouldn't it be nice if one could call PGPLOT subroutines directrly
from the elegant perl language?  Five days after reading `Programming
Perl' I found myself at a telescope with little to do, so I hacked out
the basics of `pgperl'.  The rest followed during the odd spare evening
in Cambridge.

Unlike MONGO, perl is a real C-like language with full control
structures, and is very fast and efficient. All the power of perl (and
believe me that is a *lot*) is available to extract data to plot from
multitudes of files in complicated free formats. Using pgperl one has
all the extra functionality of SM (v.t. `SuperMongo') and IMHO the
language is far more robust and elegant.  Unlike the MONGOs pgperl is
free and public domain - though I trust people will communicate
improvements back to me to avoid version explosions.

pgperl is *complete* - all the PGPLOT routines can be used and I have
tested most of them.

I have tried very hard to keep the pgperl calls "obvious" to anybody
who knows PGPLOT and perl. See the notes below for examples of PGPLOT
use from pgperl. I refer people to the excellent reference manuals
available for PGPLOT and perl for complete information.

The current version is 1.0 and is built with PGPLOT v5.0 commands.
There are versions availalable for perl4 (which requires making a new
perl executable linked with pgplot) and perl5 (as a dynamically loadble
perl5 module). If you use pgperl please drop me an email and I can put
you on my mailing list for updates.

See the file LICENSE in the pgperl distribution for copyright/licensing
information and the file pgperl.doc on how to use pgplot from perl.
This is also similar documentation on the pgperl WWW Home Page at:

http://www.ast.cam.ac.uk/~kgb/pgperl.html

Many thanks to Frossie for the original inspiration, and to Larry Wall
and Tim Pearson for providing the excellent ingredients I stuck
together.

enjoy (I hope),

Karl Glazebrook, 
---
kgb@mail.ast.cam.ac.uk              
Institute of Astronomy, Cambridge

THE PERL5 VERSION OF PGPERL - CHANGES FROM PERL4
------------------------------------------------

This file describes the use and enhancements of the pgperl package (PGPLOT
graphics for perl) with perl5. For installation instructions see the file
BUILDING.


LOADING PGPERL
--------------

Since perl5 supports dynamic loading it is no longer necessary to make
a special version of the perl binary which has been linked with PGPLOT.
One just uses the normal perl5 binary and the statement:

use PGPLOT; # Load PGPLOT module (perl5)

will load in the PGPLOT module which contains all the C/perl necessary for
pgperl (assuming pgperl has been installed in the correct place).

This replaces the older perl4 statement:

require 'pgplot.pl';  # Obsolete - perl4 only

This will still work though - it aliases to the new command - so all old
pgperl scripts should work unchanged with perl5, subject to the areas where
perl5 itself has a behaviour slightly different from perl4. These are rare
though and are changes for the better.


IMPROVEMENTS IN CALLING SYNTAX
------------------------------

In the old pgperl pgplot routines were called thus:

&pgdraw($x, $y);

In the new perl5 version the "&" is no longer necessary and one
can say:

pgdraw($x, $y);

Moreover all functions can now be used as list operators and so one
can even say:

pgdraw $x, $y ;

(Beware operator precedence though! - see perlop(1))


IMPROVEMENTS IN ARRAY PASSING 
-----------------------------

In the old pgperl the only way to pass an array was to use the "*"
notation ("*x" passes a "glob reference" to all variables named "x"),
e.g.:

&pgpoint($n, *x, *y, $symbol); # Still works

This continues to work. However one can also pass new-style references 
to individual arrays, e.g.:

pgpoint($n, \@x, \@y, 17); # Direct reference

or using variables to hold references:

$xref = \@x; $yref = \@y;
pgpoint($n, $xref, $yref, 17);

or even:

pgpoint 3, [1,2,3], [4,5,6], 17;   # Anonymous references

See perlref(1) for all the grubby details on references in perl5.


SCALARS INSTEAD OF ARRAYS
-------------------------

Because of the extra magic now built into pgperl it is possible to
use scalar variables with array routines, e.g.:

$x=2; $y=4;
pgpoint(1, $x, $y, 17); # Plot a single point


This was not possible in perl4 which resulted in the creation of special
routines to deal with scalars, e.g. pgpoint1($x,$y,$sym). These old names
will still work, for easy backwards compatability, but they are no longer
necessary.


TWO-DIMENSIONAL ARRAYS
----------------------

perl5 now supports multi-dimensional arrays by means of the reference 
syntax. (In fact it supports N-dimensional mixtures of normal arrays
and associative arrays but let's not go into that - see perlref(1)).

In the old pgperl 2D arrays had to be passed to pgplot as one-D arrays,
e.g.:

pggray(*img, $nx, $ny, 1, $nx, 1,$ny, $max, $min ,*tr); # @img is 1D

This still works but is also now possible to pass a reference to a 
2D array, e.g.:

for($i=0; $i<128; $i++) { for($j=0; $j<128; $j++) { # Set up 128x128 image
   $$img[$i][$j] = sqrt($i*$j) / 128; 
}}
pggray($img,128,128,1,128,1,128,1,0,*tr);  # Plot image

The type of the array is automatically sensed - but make sure the array
is square and all the elements are defined!


Finally there exists a mechanism for efficient memory handling of large
images. They can be stored as byte-arrays in scalar variables and are
automgically sensed and passed onwards to the PGPLOT routines with no
conversion, e.g.:

open(IMG,"test.img");       # Read in 128x128 image stored in file as binary 
read(IMG, $img, 4*128*128); # data, i.e. list of 4 byte float [C type] /REAL*4
close(IMG);                 # [f77 type] values, and store as perl string. 
pggray($img,128,128,1,128,1,128,1,0,*tr); # Plot

Obviously it is not possible to do any operations on such objects with perl
functions unless they are first converted to normal perl arrays (e.g. with
@image = unpack("f*",$img);) but this is useful for efficient passing around
of large images and one might imagine using library routines to read data
from files and return these structures. (Note: by "large" I mean >=1024x1024
- for the 128x128 example it makes negligible difference.)


EXAMPLES
--------

All these features are demonstrated in the new test script called
testpgperl10.pg (which only works with perl5).

perl5 also has trendy object-oriented features - an example of
using this with PGPLOT is shown in testpgperl11.pg for the sake of 
amusement.


Karl Glazebrook, 
---
kgb@ast.cam.ac.uk  Institute of Astronomy, Cambridge, U.K.
pgperl software:   http://www.ast.cam.ac.uk/~kgb/pgperl.html

-----------------------------------------------------------------------------
                                               Last Modified. 18/May/1995.