mirror of
https://git.FreeBSD.org/ports.git
synced 2024-11-28 01:06:17 +00:00
Shorten this file. Please, don't put the entire 218-line README here! :(
This commit is contained in:
Satoshi Asami
parent
b9768202f4
commit
7533d48dda
Notes:
svn2git
2021-03-31 03:12:20 +00:00
svn path=/head/; revision=5079
@ -1,218 +1,15 @@
|
||||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
|
||||
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
|
||||
See the file LICENSE in /usr/local/share/doc/pgperl 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.
|
||||
|
||||
@ -1,218 +1,15 @@
|
||||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
|
||||
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
|
||||
See the file LICENSE in /usr/local/share/doc/pgperl 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user