This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: PDL/FFT, Next: PDL/Filter/LinPred, Prev: PDL/FAQ, Up: Module List FFTs for PDL ************ NAME ==== PDL::FFT - FFTs for PDL DESCRIPTION =========== FFTs for PDL. These work for arrays of any dimension, although ones with small prime factors are likely to be the quickest. Each routine works `inplace'. SYNOPSIS ======== use PDL::FFT qw/:Func/; fft($real,$imag); ifft($real,$imag); realfft($real); realifft($real); fftnd($real,$imag); ifftnd($real,$imag); $kernel = kernctr($image,$smallk); fftconvolve($image,$kernel); ALTERNATIVE FFT PACKAGES ======================== Various other modules - such as `PDL::FFTW|PDL::FFTW' in this node and `PDL::Slatec|PDL::Slatec' in this node - contain FFT routines. However, unlike PDL::FFT, these modules are optional, and so may not be installed. FUNCTIONS ========= fft --- ifft ---- realfft() --------- The real part of the transform ends up in the first half of the array and the imaginary part of the transform ends up in the second half of the array. realifft() ---------- fftnd() ------- ifftnd() -------- fftconvolve() ------------- fftconvolve works inplace, and returns an error array in kernel as an accuracy check - all the values in it should be negligible. The sizes of the image and the kernel must be the same. `kernctr|' in this node centres a small kernel to emulate the behaviour of the direct convolution routines. The speed cross-over between using straight convolution (`PDL::Image2D::conv2d()|PDL::Image2D' in this node) and these fft routines is for kernel sizes roughly 7x7. kernctr() --------- kernctr centres a small kernel to emulate the behaviour of the direct convolution routines. convmath -------- cmul ---- cdiv ---- BUGS ==== Where the source is marked `FIX', could re-implement using phase-shift factors on the transforms and some real-space bookkeeping, to save some temporary space and redundant transforms. AUTHOR ====== This file copyright (C) 1997, 1998 R.J.R. Williams (rjrw@ast.leeds.ac.uk), Karl Glazebrook (kgb@aaoepp.aao.gov.au), Tuomas J. Lukka, (lukka@husc.harvard.edu). All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Filter/LinPred, Next: PDL/Filter/Linear, Prev: PDL/FFT, Up: Module List Linear predictive filtering *************************** NAME ==== PDL::Filter::LinPred - Linear predictive filtering SYNOPSIS ======== $a = new PDL::Filter::LinPred( {NLags => 10, LagInterval => 2, LagsBehind => 2, Data => $dat}); ($pd,$corrslic) = $a->predict($dat); DESCRIPTION =========== A filter by doing linear prediction: tries to predict the next value in a data stream as accurately as possible. The filtered data is the predicted value. The parameters are NLags Number of time lags used for prediction LagInterval How many points each lag should be LagsBehind If, for some strange reason, you wish to predict not the next but the one after that (i.e. usually f(t) is predicted from f(t-1) and f(t-2) etc., but with LagsBehind => 2, f(t) is predicted from f(t-2) and f(t-3)). Data The input data, which may contain other dimensions past the first (time). The extraneous dimensions are assumed to represent epochs so the data is just concatenated. AutoCovar As an alternative to Data, you can just give the temporal autocorrelation function. Smooth Don't do prediction or filtering but smoothing. The method *predict* gives a prediction for some data plus a corresponding slice of the data, if evaluated in list context. This slice is given so that you may, if you wish, easily plot them atop each other. The rest of the documentation is under lazy evaluation. AUTHOR ====== Copyright (C) Tuomas J. Lukka 1997. All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Filter/Linear, Next: PDL/Fit/Gaussian, Prev: PDL/Filter/LinPred, Up: Module List linear filtering for PDL ************************ NAME ==== PDL::Filter::Linear - linear filtering for PDL SYNOPSIS ======== $a = new PDL::Filter::Linear( {Weights => $v, Point => 10}); $b = new PDL::Filter::Gaussian(15,2); # 15 points, 2 std devn. ($pred,$corrslic) = $a->predict($dat); DESCRIPTION =========== A wrapper for generic linear filters. Just for convenience. This should in the future use DataPresenter. Also, this class should at some point learn to do FFT whenever it is useful.  File: pm.info, Node: PDL/Fit/Gaussian, Next: PDL/Fit/LM, Prev: PDL/Filter/Linear, Up: Module List routines for fitting gaussians ****************************** NAME ==== PDL::Fit::Gaussian - routines for fitting gaussians DESCRIPTION =========== This module contains some custom gaussian fitting routines. These were developed in collaboration with Alison Offer, they do a reasonably robust job and are quite useful. Gaussian fitting is something I do a lot of, so I figured it was worth putting in my special code. Note this code is also used in the Karma package. SYNOPSIS ======== use PDL::Fit::Gaussian; ($cen, $pk, $fwhm, $back, $err, $fit) = fitgauss1d($x, $data); ($pk, $fwhm, $back, $err, $fit) = fitgauss1dr($r, $data); FUNCTIONS ========= fitgauss1d ---------- Fit's a 1D Gaussian robustly free parameters are the centre, peak height, FWHM. The background is NOT fit, because I find this is generally unreliable, rather a median is determined in the 'outer' 10% of pixels (i.e. those at the start/end of the data piddle). The initial estimate of the FWHM is the length of the piddle/3, so it might fail if the piddle is too long. (This is non-robust anyway). Most data does just fine and this is a good default gaussian fitter. SEE ALSO: fitgauss1dr() for fitting radial gaussians fitgauss1dr ----------- Fit's a 1D radial Gaussian robustly free parameters are the peak height, FWHM. Centre is assumed to be X=0 (i.e. start of piddle). The background is NOT fit, because I find this is generally unreliable, rather a median is determined in the 'outer' 10% of pixels (i.e. those at the end of the data piddle). The initial estimate of the FWHM is the length of the piddle/3, so it might fail if the piddle is too long. (This is non-robust anyway). Most data does just fine and this is a good default gaussian fitter. SEE ALSO: fitgauss1d() to fit centre as well. BUGS ==== May not converge for weird data, still pretty good! AUTHOR ====== This file copyright (C) 1999, Karl Glazebrook (kgb@aaoepp.aao.gov.au), Gaussian fitting code by Alison Offer (aro@aaocbn.aao.gov.au). All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Fit/LM, Next: PDL/Fit/Linfit, Prev: PDL/Fit/Gaussian, Up: Module List Levenber-Marquardt fitting routine for PDL ****************************************** NAME ==== PDL::Fit::LM - Levenber-Marquardt fitting routine for PDL DESCRIPTION =========== This module provides fitting functions for PDL. Currently, only Levenberg-Marquardt fitting is implemented. Other procedures should be added as required. For a fairly concise overview on fitting see Numerical Recipes, chapter 15 "Modeling of data". SYNOPSIS ======== use PDL::Fit::LM; $ym = lmfit $x, $y, $sig, \&expfunc, $a, {Maxiter => 300}; FUNCTIONS ========= lmfit ----- Options: The user supplied sub routine reference should accept 4 arguments * a vector of independent values $x * a vector of fitting parameters * a vector of dependent variables that will be assigned upon return * a matrix of partial derivatives with respect to the fitting parameters that will be assigned upon return As an example take this definition of a single exponential with 3 parameters (width, amplitude, offset): sub expdec { my ($x,$par,$ym,$dyda) = @_; my ($a,$b,$c) = map {$par->slice("($_)")} (0..2); my $arg = $x/$a; my $ex = exp($arg); $ym .= $b*$ex+$c; my (@dy) = map {$dyda->slice(",($_)")} (0..2); $dy[0] .= -$b*$ex*$arg/$a; $dy[1] .= $ex; $dy[2] .= 1; } Note usage of the `.=' operator for assignment In scalar context returns a vector of the fitted dependent variable. In list context returns fitted y-values, vector of fitted parameters, an estimate of the covariance matrix (as an indicator of goodness of fit) and number of iterations performed. tlmfit ------ Signature: a threaded version of lmfit by using perl threading. Direct threading in lmfit seemed difficult since we have an if condition in the iteration. In principle that can be worked around by using where but .... Send a threaded lmfit version if you work it out! Since we are using perl threading here speed is not really great but it is just convenient to have a threaded version for many applications (no explicit for-loops required, etc). Suffers from some of the current limitations of perl level threading. BUGS ==== Not known yet. AUTHOR ====== This file copyright (C) 1999, Christian Soeller (c.soeller@auckland.ac.nz). All rights reserved. There is no warranty. You are allowed to redistribute this software documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Fit/Linfit, Next: PDL/Fit/Polynomial, Prev: PDL/Fit/LM, Up: Module List routines for fitting data with linear combinations of functions. **************************************************************** NAME ==== PDL::Fit::Linfit - routines for fitting data with linear combinations of functions. DESCRIPTION =========== This module contains routines to perform general curve-fits to a set (linear combination) of specified functions. Given a set of Data: (y0, y1, y2, y3, y4, y5, ...ynoPoints-1) The fit routine tries to model y as: y' = beta0*x0 + beta1*x1 + ... beta_noCoefs*x_noCoefs Where x0, x1, ... x_noCoefs, is a set of functions (curves) that the are combined linearly using the beta coefs to yield an approximation of the input data. The Sum-Sq error is reduced to a minimum in this curve fit. *Inputs:* $data This is your data you are trying to fit. Size=n $functions 2D array. size (n, noCoefs). Row 0 is the evaluation of function x0 at all the points in y. Row 1 is the evaluation of of function x1 at all the points in y, ... etc. Example of $functions array Structure: $data is a set of 10 points that we are trying to model using the linear combination of 3 functions. $functions = ( [ 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ], # Constant Term [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ], # Linear Slope Term [ 0, 2, 4, 9, 16, 25, 36, 49, 64, 81] # quadradic term ) SYNOPSIS ======== $yfit = linfit1d $data, $funcs FUNCTIONS ========= linfit1d -------- Uses a standard matrix inversion method to do a least squares/min chi^2 fit to data. Returns the fitted data and optionally the coefficients. One can thread over extra dimensions to do multiple fits (except the order can not be threaded over - i.e. it must be one fixed set of fit functions `fitFuncs'. The data is normalised internally to avoid overflows (using the mean of the abs value) which are common in large polynomial series but the returned fit, coeffs are in unnormalised units.  File: pm.info, Node: PDL/Fit/Polynomial, Next: PDL/Func, Prev: PDL/Fit/Linfit, Up: Module List routines for fitting with polynomials ************************************* NAME ==== PDL::Fit::Polynomial - routines for fitting with polynomials DESCRIPTION =========== This module contains routines for doing simple polynomial fits to data SYNOPSIS ======== $yfit = fitpoly1d $data; FUNCTIONS ========= fitpoly1d --------- Uses a standard matrix inversion method to do a least squares/min chi^2 polynomial fit to data. Order=2 is a linear fit (two parameters). Returns the fitted data and optionally the coefficients. One can thread over extra dimensions to do multiple fits (except the order can not be threaded over - i.e. it must be one fixed scalar number like "4"). The data is normalised internally to avoid overflows (using the mean of the abs value) which are common in large polynomial series but the returned fit, coeffs are in unnormalised units. BUGS ==== May not work too well for data with large dynamic range. SEE ALSO ======== `"polyfit"', *Note PDL/Slatec: PDL/Slatec, AUTHOR ====== This file copyright (C) 1999, Karl Glazebrook (kgb@aaoepp.aao.gov.au). All rights reserved. There is no warranty. You are allowed to redistribute this software documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Func, Next: PDL/Gaussian, Prev: PDL/Fit/Polynomial, Up: Module List useful functions **************** NAME ==== PDL::Func - useful functions SYNOPSIS ======== use PDL::Func; use PDL::Math; # somewhat pointless way to estimate cos and sin, # but is shows that you can thread if you want to # (and the library lets you) # my $obj = init PDL::Func( Interpolate => "Hermite" ); # my $x = pdl( 0 .. 45 ) * 4 * 3.14159 / 180; my $y = cat( sin($x), cos($x) ); $obj->set( x => $x, y => $y, bc => "simple" ); # my $xi = pdl( 0.5, 1.5, 2.5 ); my $yi = $obj->interpolate( $xi ); # print "sin( $xi ) equals ", $yi->slice(':,(0)'), "\n"; sin( [0.5 1.5 2.5] ) equals [0.87759844 0.070737667 -0.80115622] # print "cos( $xi ) equals ", $yi->slice(':,(1)'), "\n"; cos( [0.5 1.5 2.5] ) equals [ 0.4794191 0.99768655 0.59846449] # print sin($xi), "\n", cos($xi), "\n"; [0.47942554 0.99749499 0.59847214] [0.87758256 0.070737202 -0.80114362] DESCRIPTION =========== This module aims to contain useful functions. Honest. INTERPOLATION AND MORE ====================== This module aims to provide a relatively-uniform interface to the various interpolation methods available to PDL. The idea is that a different interpolation scheme can be used just by changing an attribute of a `PDL::Func' object. Some interpolation schemes (as exemplified by the SLATEC library) also provide additional functionality, such as integration and gradient estimation. Throughout this documentation, $x and `$y' refer to the function to be interpolated whilst `$xi' and `$yi' are the interpolated values. The avaliable types, or *schemes*, of interpolation are listed below. Also given are the valid attributes for each scheme: the flag value indicates whether it can be set (s), got (g), and if it is required (r) for the method to work. Interpolate => Linear An extravagent way of calling the linear interpolation routine `PDL::Primitive::interpolate|PDL::Primitive' in this node. The valid attributes are: Attribute Flag Description x sgr x positions of data y sgr function values at x positions err g error flag Interpolate => Hermite Use the piecewice cubic Hermite interpolation routines from the SLATEC library. Only available if `PDL::Slatec|PDL::Slatec' in this node is installed. The valid attributes are: Attribute Flag Description x sgr x positions of data y sgr function values at x positions bc sgr boundary conditions g g estimated gradient at x positions err g error flag Given the initial set of points `(x,y)', an estimate of the gradient is made at these points, using the given boundary conditions. The gradients are stored in the g attribute, accessible via: $gradient = $obj->get( 'g' ); However, as this gradient is only calculated 'at the last moment', g will only contain data after one of interpolate, `gradient', or `integrate' is used. Boundary conditions for the Hermite routines -------------------------------------------- If your data is monotonic, and you are not too bothered about edge effects, then the default value of `bc' of `simple' is for you. Otherwise, take a look at the description of `PDL::Slatec::chic|PDL::Slatec' in this node and use a hash reference for the `bc' attribute, with the following keys: monotonic 0 if the interpolant is to be monotonic in each interval (so the gradient will be 0 at each switch point), otherwise the gradient is calculated using a 3-point difference formula at switch points. If > 0 then the interpolant is forced to lie close to the data, if < 0 no such control is imposed. Default = 0. start A perl list of one or two elements. The first element defines how the boundary condition for the start of the array is to be calculated; it has a range of `-5 .. 5', as given for the `ic' parameter of `chic|PDL::Slatec' in this node. The second element, only used if options 2, 1, -1, or 2 are chosen, contains the value of the `vc' parameter. Default = *[ 0 ]*. end As for start, but for the end of the data. An example would be $obj->set( bc => { start => [ 1, 0 ], end => [ 1, -1 ] } ) which sets the first derivative at the first point to 0, and at the last point to -1. Errors ------ The status method provides a simple mechanism to check if the previous method was successful. If the function returns an error flag, then it is stored in the err attribute. To find out which routine was used, use the `routine' method. FUNCTIONS ========= PDL::Func::init --------------- If not specified, the value of Interpolate is taken to be `Linear', which means the interpolation is performed by `PDL::Primitive::interpolate|PDL::Primitive' in this node. A value of `Hermite' uses piecewise cubic Hermite functions, which also allows the integral and gradient of the data to be estimated. PDL::Func::set -------------- The return value gives the number of the supplied attributes which were actually set. PDL::Func::get -------------- Given a list of attribute names, return a list of their values; in scalar mode return a scalar value. If the supplied list contains an unknown attribute, get returns a value of undef for that attribute. PDL::Func::scheme ----------------- Returns either `Linear' or `Hermite'. PDL::Func::status ----------------- This method provides a high-level indication of the success of the last method called (except for get which is ignored). Returns 1 if everything is okay, 0 if there has been a serious error, and *-1* if there was a problem which was not serious. In the latter case, `$obj->get("err")' may provide more information, depending on the particular scheme in use. PDL::Func::routine ------------------ This is mainly useful for decoding the value stored in the err attribute. PDL::Func::attributes --------------------- Useful in case the documentation is just too opaque! PDL::Func::interpolate ---------------------- A status value of -1, as returned by the status method, means that some of the `$xi' points lay outside the range of the data. The values for these points were calculated by extrapolation (the details depend on the scheme being used). PDL::Func::gradient ------------------- PDL::Func::integrate -------------------- The integration can either be between points of the original x array (index), or arbitrary x values (x). For both cases, a two element piddle should be given, to specify the start and end points of the integration. index The values given refer to the indices of the points in the x array. x The array contains the actual values to integrate between. If the status method returns a value of -1, then one or both of the integration limits did not lie inside the x array. *Caveat emptor* with the result in such a case. TODO ==== It should be relatively easy to provide an interface to other interpolation routines, such as those provided by the Gnu Scientific Library (GSL), or the B-spline routines in the SLATEC library. In the documentation, the methods are preceeded by `PDL::Func::' to avoid clashes with functions such as set when using the help or apropos commands within *perldl*. HISTORY ======= Amalgamated `PDL::Interpolate' and `PDL::Interpolate::Slatec' to form `PDL::Func'. Comments greatly appreciated on the current implementation, as it is not too sensible. AUTHOR ====== Copyright (C) 2000 Doug Burke (burke@ifa.hawaii.edu). All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation as described in the file COPYING in the PDL distribution.  File: pm.info, Node: PDL/Gaussian, Next: PDL/Graphics2D, Prev: PDL/Func, Up: Module List Gaussian distributions. *********************** NAME ==== PDL::Gaussian - Gaussian distributions. SYNOPSIS ======== $a = new PDL::Gaussian([3],[5]); $a->set_covariance(...) DESCRIPTION =========== This package provides a set of standard routines to handle sets gaussian distributions. A new set of gaussians is initialized by $a = new PDL::Gaussian(xdims,gdims); Where *xdims* is a reference to an array containing the dimensions in the space the gaussian is in and *gdimslist* is a reference to an array containing the dimensionality of the gaussian space. For example, after $a = new PDL::Gaussian([2],[3,4]); $b = new PDL::Gaussian([],[]); The variable `$a' contains set of 12 (=`3*4') 2-Dimensional gaussians and $b is the simplest form: one 1D gaussian. Currently, *xdims* may containe either zero or one dimensions due to limitations of `PDL::PP|PDL::PP' in this node. To set the distribution parameters, you can use the routines $a->set_covariance($cv); # covariance matrices $a->set_icovariance($icv); # inverse covariance matrices $a->set_mu($mu); # centers The dimensions of `$cv' and `$icv' must be `(@xdims,@xdims,@gdims)' and the dimensions of `$mu' must be `(@xdims,@gdims)'. Alternatively you can use the routines $cv = $a->get_covariance(); # cv = reference to covariance matrix ... # Fuzz around with cv $a->upd_covariance(); # update and similarly for `icovariance' (inverse covariance). The last sub call is important to update the other parts of the object. To get a string representation of the gaussians (most useful for debugging) use the routine $string = $a->asstr(); It is possible to calculate the probability or logarithm of probability of each of the distributions at some points. $a->calc_value($x,$p); $a->calc_lnvalue($x,$p); Here, $x must have dimensions `(ndims,...)' and $p must have dimensions `(gdimslist, ...)' where the elipsis represents the same dimensions in both variables. It is usually advisable to work with the logarithms of probabilities to avoid numerical problems. It is possible to generate the parameters for the gaussians from data. The function $a->fromweighteddata($data,$wt,$small_covariance); where $data is of dimensions `(ndims,npoints)' and `$wt' is of dimensions `(npoints,gdimslist)', analyzes the data statistically and gives a corresponding gaussian distribution. The parameter `$small_covariance' is the smallest allowed covariance in any direction: if one or more of the eigenvalues of the covariance matrix are smaller than this, they are automatically set to `$small_covariance' to avoid singularities. BUGS ==== Stupid interface. Limitation to 1 x-dimensions is questionable (although it's hard to imagine a case when more is needed). Note that this does not mean that you can only have 1-dimensional gaussians. It just means that if you want to have a 6-dimensional gaussian, your xs must be structured like (6) and not (2,3). So clumping the dimensions should make things workable. Also, it limits you so that even if you have one variable, you need to have the '1' dimensions explicitly everywhere. Singular distributions are not handled. This should use SVD and be able to handle both infinitely narrow and wide dimensions, preferably so that infinitely narrow dimensions can be queried like `$a-'relations()> or something like that. The routines should, if the user requests for it, check all the dimensions of the given arguments for reasonability. AUTHOR ====== Copyright (C) 1996 Tuomas J. Lukka (lukka@fas.harvard.edu) All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Graphics2D, Next: PDL/Graphics/IIS, Prev: PDL/Gaussian, Up: Module List An object oriented interface to PDL graphics ******************************************** NAME ==== PDL::Graphics2D - An object oriented interface to PDL graphics SYNOPSIS ======== use PDL::Graphics2D; $win = PDL::Graphics2D->new(, ); DESCRIPTION =========== This is an umbrella class allowing for a simple interface to all plotting routines in PDL. On its own it does not do any work it merely passes information to the appropriate class. Ideally this should probably offer a uniform interface to a variety of packages. This requires a lot more work before it is useful I feel, but it can be used already.  File: pm.info, Node: PDL/Graphics/IIS, Next: PDL/Graphics/LUT, Prev: PDL/Graphics2D, Up: Module List Display PDL images on IIS devices (saoimage/ximtool) **************************************************** NAME ==== PDL::Graphics::IIS - Display PDL images on IIS devices (saoimage/ximtool) SYNOPSIS ======== use PDL::Graphics::IIS; saoimage ( -geometry => '800x800' ); iis rvals(100,100); DESCRIPTION =========== This module provides an interface to any image display 'device' which support the 'IIS protocol' - viz the SAOimage and Ximtool X-windows programs, the old SunView imtool program and presumably even the original IIS CRT itself if they aren't all in museums! These programs should be familiar to astronomer's - they are used by the common IRAF system. The programs and their HTML documentation can be obtained from the following URLs: SAOimage: http://tdc-www.harvard.edu/software/saoimage.html Ximtool: http://iraf.noao.edu/iraf/web/projects/x11iraf/x11iraf.html Non-astronomer's may find they quite nifty for displaying 2D data. The Perl variable `$stdimage' is exported from the module and controls the frame buffer configuration currently in use. The default value is `imt1024' which specifies a `1024x1024' frame buffer. Other values supported by the module are: imt512, imt800, imt1024, imt1600, imt2048, and imt4096. If you have a `$HOME/.imtoolrc' you can use it to specify other frame buffer names and configurations in exactly the same way you can in IRAF. Here is a sample file: -------------------snip------------------------- # Format: configno nframes width height 1 2 512 512 # imt1|imt512 2 2 800 800 # imt2|imt800 3 2 1024 1024 # imt3|imt1024 4 1 1600 1600 # imt4|imt1600 5 1 2048 2048 # imt5|imt2048 6 1 4096 4096 # imt6|imt4096 7 1 8192 8192 # imt7|imt8192 8 1 1024 4096 # imt8|imt1x4 9 2 1144 880 # imt9|imtfs full screen (1152x900 minus frame) 10 2 1144 764 # imt10|imtfs35 full screen at 35mm film aspect ratio -------------------snip------------------------- (Note: some versions of SAOimage may not even work if this file is not present. If you get funny error messages about 'imtoolrc' try copying the above to `$HOME/.imtoolrc' or `/usr/local/lib/imtoolrc') The Perl variable `$iisframe' is also exported from the module and controls which display frame number to use in programs such as Ximtool which supports multiple frames. This allows you to do useful things such as blink between images. The module communicates with the IIS device down FIFO pipes (special UNIX files) - unlike IRAF this module does a pretty decent job of intelligently guessing which file names to use for the pipes and will prompt for their creating if absent. Also if SAOimage or Ximtool are started from within Perl using the module this will guarantee correct file names! FUNCTIONS ========= iis --- Displays image on a IIS device. If `min()' or `max()' are omitted they are autoscaled. A good demonstration of PDL threading can be had by giving `iis()' a data *cube* - `iis()' will be repeatedly called for each plane of the cube resulting in a poor man's movie! If supplied, TITLE is used to label the frame, if no title is supplied, either the OBJECT value stored in the image header or a default string is used (the title is restricted to a maximum length of 32 characters). To specify which frame to draw to, either use the package variable `$iisframe', or the `FRAME' option. iiscur ------ This function puts up an interactive cursor on the IIS device and returns the `($x,$y)' position and the character typed (`$ch') by the user. iiscirc ------- Draws circles on the IIS device with specied points and colours. Because this module uses `PDL::PP|PDL::PP' in this node threading you can supply lists of points via 1D arrays, etc. An amusing PDL idiom is: perldl> iiscirc iiscur Note the colours are the same as IRAF, viz: 201 = cursor color (white) 202 = black 203 = white 204 = red 205 = green 206 = blue 207 = yellow 208 = cyan 209 = magenta 210 = coral 211 = maroon 212 = orange 213 = khaki 214 = orchid 215 = turquoise 216 = violet 217 = wheat saoimage -------- Starts up the SAOimage external program. Default FIFO devices are chosen so as to be compatible with other IIS module functions. If no suitable FIFOs are found it will offer to create them. e.g.: ximtool ------- Starts up the Ximtool external program. Default FIFO devices are chosen so as to be compatible with other IIS module functions. If no suitable FIFOs are found it will offer to create them. e.g. BUGS ==== None known AUTHOR ====== Copyright (C) Karl Glazebrook 1997. All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Graphics/LUT, Next: PDL/Graphics/OpenGL, Prev: PDL/Graphics/IIS, Up: Module List provides access to a number of look-up tables ********************************************* NAME ==== PDL::Graphics::LUT - provides access to a number of look-up tables SYNOPSIS ======== use PDL::Graphics::PGPLOT; use PDL::Graphics::LUT; # what tables are available my @tables = lut_names(); # get the reversed colour table 'smooth', # with the gamma intensity ramp my ( $l, $r, $g, $b ) = lut_data( 'smooth', 1, 'gamma' ); # use the table idl5 in ctab ctab( lut_data('idl5') ); DESCRIPTION =========== PDL::Graphics::LUT contains a number of colour look-up tables (in rgb format) and intensity ramps, and provides routines to access this data. The format of the data is suitable for use by `ctab', *Note PDL/Graphics/PGPLOT: PDL/Graphics/PGPLOT,. Unlike the initial release of the package, the data tables are now stored within the PDL distribution (see `$tabledir|' in this node and `$rampdir|' in this node) rather than in the module itself. Changes to these directories will be picked up on the next call to one of the package functions. FUNCTIONS ========= lut_names() ----------- lut_ramps() ----------- lut_data() ---------- Returns the levels and r, g, b components of the colour table `$table'. If `$reverse' is 1 (defaults to 0 if not supplied), then the r, g, and b components are reversed before being returned. If not supplied, `$ramp' defaults to *"ramp"* (this is a linear intensity ramp). The returned values are piddles containing values in the range 0 to 1 inclusive, and are floats. VARIABLES ========= $tabledir --------- $rampdir -------- $suffix ------- FURTHER INFORMATION =================== The colour tables were taken from the STARLINK GAIA package, and are provided under the GNU copyleft. See http://star-www.rl.ac.uk/ and http://star-www.dur.ac.uk/~pdraper/ for more details. AUTHOR ====== Doug Burke (burke@ifa.hawaii.edu), with thanks to Peter Draper/STARLINK for providing the colour-table data, and Christian Soeller and Karl Glazebrook for their help. All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Graphics/OpenGL, Next: PDL/Graphics/OpenGLQ, Prev: PDL/Graphics/LUT, Up: Module List a PDL interface to the OpenGL graphics library. PDL::Graphics::OpenGLOO - an Object Oriented interface to the interface. ************************************************************************************************************************ NAME ==== PDL::Graphics::OpenGL - a PDL interface to the OpenGL graphics library. PDL::Graphics::OpenGLOO - an Object Oriented interface to the interface. DESCRIPTION =========== This package implements an interface to various OpenGL or OpenGL emulator libraries. Most of the interface is generated at PDL compile time by the script opengl.pd which runs the c preprocessor on various OpenGL include files to determine the correct C prototypes for each configuration. The object oriented interface defines an Object which contains the Display, Window and Context properties of the defined OpenGL device. Any OpenGL function called from the OO interface will recieve these fields from the object, they should not be passed explicitly. This package is primarily intended for internal use by the PDL::Graphics::TriD package, but should also be usable in its own right. FUNCTIONS ========= new($class,$options) -------------------- Returns a new OpenGL object with attributes specified in the options field. These attributes are: =for ref x,y - the position of the upper left corner of the window (0,0) width,height - the width and height of the window in pixels (500,500) parent - the parent under which the new window should be opened (root) mask - the user interface mask (StructureNotifyMask) attributes - attributes to pass to glXChooseVisual default_options --------------- default options for object oriented methods XResizeWindow(x,y) ------------------ OO interface to XResizeWindow glpXNextEvent() --------------- OO interface to glpXNextEvent glpRasterFont() --------------- OO interface to the glpRasterFont function AUTOLOAD -------- If the function is not prototyped in OO we assume there is no explicit mention of the three identifying parameters (Display, Window, Context) and try to load the OpenGL function. glXCopyContext -------------- OO interface to the glXCopyContext function glXCreateContext ---------------- OO interface to the glXCreateContext function glXCreateGLXPixmap ------------------ OO interface to the glXCreateGLXPixmap function glXDestroyContext ----------------- OO interface to the glXDestroyContext function glXDestroyGLXPixmap ------------------- OO interface to the glXDestroyGLXPixmap function glXGetConfig ------------ OO interface to the glXGetConfig function glXIsDirect ----------- OO interface to the glXIsDirect function glXMakeCurrent -------------- OO interface to the glXMakeCurrent function glXQueryExtension ----------------- OO interface to the glXQueryExtension function glXQueryVersion --------------- OO interface to the glXQueryVersion function glXSwapBuffers -------------- OO interface to the glXSwapBuffers function glXGetFBConfigAttrib -------------------- OO interface to the glXGetFBConfigAttrib function glXCreatePixmap --------------- OO interface to the glXCreatePixmap function glXDestroyPixmap ---------------- OO interface to the glXDestroyPixmap function glXCreateNewContext ------------------- OO interface to the glXCreateNewContext function glXQueryContext --------------- OO interface to the glXQueryContext function glXMakeContextCurrent --------------------- OO interface to the glXMakeContextCurrent function glXCreatePbuffer ---------------- OO interface to the glXCreatePbuffer function glXDestroyPbuffer ----------------- OO interface to the glXDestroyPbuffer function glXQueryDrawable ---------------- OO interface to the glXQueryDrawable function glXSelectEvent -------------- OO interface to the glXSelectEvent function glXGetSelectedEvent ------------------- OO interface to the glXGetSelectedEvent function glXCreateWindow --------------- OO interface to the glXCreateWindow function glXDestroyWindow ---------------- OO interface to the glXDestroyWindow function glXMakeCurrentReadSGI --------------------- OO interface to the glXMakeCurrentReadSGI function glXBindChannelToWindowSGIX -------------------------- OO interface to the glXBindChannelToWindowSGIX function glXQueryChannelDeltasSGIX ------------------------- OO interface to the glXQueryChannelDeltasSGIX function glXChannelRectSGIX ------------------ OO interface to the glXChannelRectSGIX function glXQueryChannelRectSGIX ----------------------- OO interface to the glXQueryChannelRectSGIX function glXChannelRectSyncSGIX ---------------------- OO interface to the glXChannelRectSyncSGIX function glXHyperpipeConfigSGIX ---------------------- OO interface to the glXHyperpipeConfigSGIX function glXDestroyHyperpipeConfigSGIX ----------------------------- OO interface to the glXDestroyHyperpipeConfigSGIX function glXBindHyperpipeSGIX -------------------- OO interface to the glXBindHyperpipeSGIX function glXQueryHyperpipeBestAttribSGIX ------------------------------- OO interface to the glXQueryHyperpipeBestAttribSGIX function glXQueryHyperpipeAttribSGIX --------------------------- OO interface to the glXQueryHyperpipeAttribSGIX function glXHyperpipeAttribSGIX ---------------------- OO interface to the glXHyperpipeAttribSGIX function glXQueryContextInfoEXT ---------------------- OO interface to the glXQueryContextInfoEXT function glXGetContextIDEXT ------------------ OO interface to the glXGetContextIDEXT function glXImportContextEXT ------------------- OO interface to the glXImportContextEXT function glXFreeContextEXT ----------------- OO interface to the glXFreeContextEXT function glXGetFBConfigAttribSGIX ------------------------ OO interface to the glXGetFBConfigAttribSGIX function glXCreateGLXPixmapWithConfigSGIX -------------------------------- OO interface to the glXCreateGLXPixmapWithConfigSGIX function glXCreateContextWithConfigSGIX ------------------------------ OO interface to the glXCreateContextWithConfigSGIX function glXGetFBConfigFromVisualSGIX ---------------------------- OO interface to the glXGetFBConfigFromVisualSGIX function glXCreateGLXPbufferSGIX ----------------------- OO interface to the glXCreateGLXPbufferSGIX function glXDestroyGLXPbufferSGIX ------------------------ OO interface to the glXDestroyGLXPbufferSGIX function glXQueryGLXPbufferSGIX ---------------------- OO interface to the glXQueryGLXPbufferSGIX function glXSelectEventSGIX ------------------ OO interface to the glXSelectEventSGIX function glXGetSelectedEventSGIX ----------------------- OO interface to the glXGetSelectedEventSGIX function glXJoinSwapGroupSGIX -------------------- OO interface to the glXJoinSwapGroupSGIX function glXBindSwapBarrierSGIX ---------------------- OO interface to the glXBindSwapBarrierSGIX function glXQueryMaxSwapBarriersSGIX --------------------------- OO interface to the glXQueryMaxSwapBarriersSGIX function OpenGL Interface Functions --------------------------  File: pm.info, Node: PDL/Graphics/OpenGLQ, Next: PDL/Graphics/PGPLOT, Prev: PDL/Graphics/OpenGL, Up: Module List quick routines to plot lots of stuff from piddles. ************************************************** NAME ==== PDL::Graphics::OpenGLQ - quick routines to plot lots of stuff from piddles. SYNOPSIS ======== only for internal use - see source DESCRIPTION =========== only for internal use - see source AUTHOR ====== Copyright (C) 1997,1998 Tuomas J. Lukka. All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.  File: pm.info, Node: PDL/Graphics/PGPLOT, Next: PDL/Graphics/PGPLOT/Window, Prev: PDL/Graphics/OpenGLQ, Up: Module List PGPLOT enhanced interface for PDL ********************************* NAME ==== PDL::Graphics::PGPLOT - PGPLOT enhanced interface for PDL SYNOPSIS ======== perldl> $a = pdl [1..100] perldl> $b = sqrt($a) perldl> line $b perldl> hold Graphics on HOLD perldl> $c = sin($a/10)*2 + 4 perldl> line $c DESCRIPTION =========== PDL::Graphics::PGPLOT is a convenience interface to the PGPLOT commands, implemented using the object oriented PGPLOT plotting package in *Note PDL/Graphics/PGPLOT/Window: 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. The list of currently availably commands: imag - Display an image (uses pgimag()/pggray() as appropriate) im - Shorthand to display an image with aspect ratio of 1 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 cont - Display image as contour map bin - Plot vector as histogram (e.g. bin(hist($data)) ) hi2d - Plot image as 2d histogram (not very good IMHO...) poly - Draw a polygon vect - Display 2 images as a vector field 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. Device manipulation commands: 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 'release' env - Define a plot window, put on 'hold' 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 exisiting plot windows close_window - Close an open window FUNCTIONS ========= The following is a list of the functions that are private to this package, for the other functions please read the *Note PDL/Graphics/PGPLOT/Window: PDL/Graphics/PGPLOT/Window, documentation. dev --- `$device' is a PGPLOT graphics device such as "/xserve" or "/ps", if omitted defaults to last used device (or value of env var `PGPLOT_DEV' if first time). `$nx', `$ny' specify sub-panelling. The function returns the id of the newly created window - this can subsequently be used as argument to focus_window to select the window. The result of this command can be modified using options. The options recognised are the same as for new_window - which primarily and in addition it is possible to set the default values for a window that are defined in `PDL::PGPLOTOptions' in this node, see this for details but see below for a synopsis. In addition dev recognises the option `NewWindow' which allows the user to specify that a dev 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. Here is a quick summary of the most useful additional options that can be given: Device Alternative to `$device'. AspectRatio The aspect ratio of the output window WindowWidth The width of the plot window in inches 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 (CharSize) and axis and box styles. See *Note PDL/Graphics/PGPLOTOptions: PDL/Graphics/PGPLOTOptions, for details. WindowName The name of a window. This name can subsequently be used to refer to the window instead of its ID, making interactive use somewhat more intuitive. $win = dev('/xs'); To open two windows, one small and square, one large and wide: $win1 = dev('/xs', {Aspect => 1, WindowWidth => 4}); $win2 = dev('/xs', {Aspect => 0.5, WindowWidth => 10}); new_window ---------- This function is identical to `dev' in this node except that it always creates a new window. This means that the user is required to close all windows explicitly using `close_window' in this node. All functionality is otherwise like dev so see the documentation for `dev' in this node for details of use. close_window ------------ This function closes a PGPLOT output device created with dev or new_window. It requires the id of the window to close. If $id 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 `focus_window' in this node after any call to close_window. _get_windownumber ----------------- Internal function to obtain the ID of a window. This allows the user to refer to a window with its name. focus_window ------------ This command is used to switch output focus to another window created by `dev' in this node or `new_window' in this node. The window can be referred to either by its ID or by its name. focus_window('X-output'); # Or focus_window($win1); <.. Commands ..> focus_window($win2); # Or focus_window('PS-output'); <.. Commands ..> window_list ----------- `$numbers' and `$names' are anonymous arrays giving the ID numbers and names of the open windows respectively.  File: pm.info, Node: PDL/Graphics/PGPLOT/Window, Next: PDL/Graphics/PGPLOTOptions, Prev: PDL/Graphics/PGPLOT, Up: Module List A OO interface to PGPLOT windows ******************************** NAME ==== PDL::Graphics::PGPLOT::Window - A OO interface to PGPLOT windows SYNOPSIS ======== perldl> use PDL::Graphics::PGPLOT::Window perldl> $win = PDL::Graphics::PGPLOT::Window->new({Device => '/xs'}); perldl> $a = pdl [1..100] perldl> $b = sqrt($a) perldl> $win->line($b) perldl> $win->hold() perldl> $c = sin($a/10)*2 + 4 perldl> $win->line($c) In the following documentation the commands are not shown in their OO versions. This is for historical reasons and should not cause too much trouble. DESCRIPTION =========== This package offers a OO interface to the PGPLOT plotting package. This is intended to replace the traditional interface in *Note PDL/Graphics/PGPLOT: PDL/Graphics/PGPLOT, and contains interfaces to a large number of PGPLOT routines. Below the usage examples for each function tend to be given in the non-OO version for historical reasons. This will slowly be changed, but in the meantime refer to the section on OO-interface below to see how to convert the usage information below to OO usage (it is totally trivial). PDL::Graphics::PGPLOT::Window is an interface to the PGPLOT graphical libraries. The list of currently availably methods: imag - Display an image (uses pgimag()/pggray() as appropriate) 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 cont - Display image as contour map bin - Plot vector as histogram (e.g. bin(hist($data)) ) hi2d - Plot image as 2d histogram (not very good IMHO...) poly - Draw a polygon vect - Display 2 images as a vector field 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. Device manipulation commands: new - Constructor for a new PGPLOT output device close - Close a PGPLOT output device focus - Set focus to the given device. This should normally be done behind the scenes. hold - Hold current plot window range - allows overlays etc. release - Release back to autoscaling of new plot window for each command held - Returns true if the graphics is held on the current device. env - Define a plot window, put on 'hold' panel - Move to a specified plot panel when several panels are defined. erase - Erase the current window (or panel) options - Get the options set for the present output device id - The ID for the device device - The device type name - The window name Notes: `$transform' for image/cont etc. is used in the same way as the `TR()' array in the underlying PGPLOT FORTRAN routine but is, fortunately, zero-offset. For completeness: The transformation array connect the pixel index to a world coordinate such that: X = tr[0] + tr[1]*i + tr[2]*j Y = tr[3] + tr[4]*i + tr[5]*j Variable passing and extensions ------------------------------- In general variables are passed to the pgplot routines by using `get_dataref' to get the reference to the values. Before passing to pgplot routines however, the data are checked to see if they are in accordance with the format (typically dimensionality) required by the PGPLOT routines. This is done using the routine `checkarg' (internal to PGPLOT). This routine checks the dimensionality of the input data. If there are superfluous dimensions of size 1 they will be trimmed away until the dimensionality is correct. Example: Assume a piddle with dimensions (1,100,1,1) is passed to line, which expects its inputs to be vectors. `checkarg' will then return a piddle with dimensions (100). If instead the same piddle was passed to imag, which requires 2D piddles as output, `checkarg' would return a piddle with dimensionality (100, 1) (Dimensions are removed from the start) Thus, if you want to provide support for another PGPLOT function, the structure currently look like this (there are plans to use the Options package to simplify the options parsing): # Extract the hash(es) on the commandline ($arg, $opt)=_extract_hash(@_); checkarg($x, 3); # For a hypothetical 3D routine. ... pgcube($n, $x->get_dataref); 1; Setting options --------------- All routines in this package take a hash with options as an optional input. This options hash can be used to set parameters for the subsequent plotting without going via the PGPLOT commands. This is implemented such that the plotting settings (such as line width, line style etc.) are affected only for that plot, any global changes made, say, with `pgslw()' are preserved. Some modifications apply when using the OO interface, see below. Alphabetical listing of standard options ---------------------------------------- The following options are always parsed. Whether they have any importance depend on the routine invoked - e.g. line style is irrelevant for imag, or the justify option is irrelevant if the display is on 'hold'. This is indicated in the help text for the commands below. The options are not case sensitive and will match for unique substrings, but this is not encouraged as obscure options might invalidate what you thought was a unique substring. In the listing below examples are given of each option. The actual option can then be used in a plot command by specifying it as an argument to the function wanted (it can be placed anywhere in the command list). E.g: $opt={COLOR=>2}; line $x, $y, $opt; # This will plot a line with red color arrow This options allows you to set the arrow shape, and optionally size for arrows for the vect routine. The arrow shape is specified as a hash with the key FS to set fill style, ANGLE to set the opening angle of the arrow head, VENT to set how much of the arrow head is cut out and SIZE to set the arrowsize. The following $opt = {ARROW => {FS=>1, ANGLE=>60, VENT=>0.3, SIZE=>5}}; will make a broad arrow of five times the normal size. Alternatively the arrow can be specified as a set of numbers corresponding to an extention to the syntax for pgsah. The equivalent to the above is $opt = {ARROW => pdl([1, 60, 0.3, 5})}; For the latter the arguments must be in the given order, and if any are not given the default values of 1, 45, 0.3 and 1.0 respectively will be used. arrowsize The arrowsize can be specified separately using this option to the options hash. It is useful if an arrowstyle has been set up and one wants to plot the same arrow with several sizes. Please note that it is not possible to set arrowsize and character size in the same call to a plotting function. This should not be a problem in most cases. $opt = {ARROWSIZE => 2.5}; axis Set the axis value (see `' in this node). It can either be specified as a number, or by one of the following names: EMPTY (-2) draw no box, axes or labels BOX (-1) draw box only NORMAL (0) draw box and label it with coordinates AXES (1) same as NORMAL, but also draw (X=0,Y=0) axes GRID (2) same as AXES, but also draw grid lines LOGX (10) draw box and label X-axis logarithmically LOGY (20) draw box and label Y-axis logarithmically LOGXY (30) draw box and label both axes logarithmically border Normally the limits are chosen so that the plot just fits; with this option you can increase (or decrease) the limits by either a relative (ie a fraction of the original axis width) or an absolute amount. Either specify a hash array, where the keys are TYPE (set to 'relative' or 'absolute') and VALUE (the amount to change the limits by), or set to 1, which is equivalent to BORDER => { TYPE => 'rel', VALUE => 0.05 } charsize Set the character/symbol size as a multiple of the standard size. $opt = {CHARSIZE => 1.5} colour (or color) Set the colour to be used for the subsequent plotting. This can be specified as a number, and the most used colours can also be specified with name, according to the following table (note that this only works for the default colour map): 0 - WHITE 1 - BLACK 2 - RED 3 - GREEN 4 - BLUE 5 - CYAN 6 - MAGENTA 7 - YELLOW 8 - ORANGE 14 - DARKGRAY 16 - LIGHTGRAY filltype Set the fill type to be used by `poly|' in this node. The fill can either be specified using numbers or name, according to the following table, where the recognised name is shown in capitals - it is case-insensitive, but the whole name must be specified. 1 - SOLID 2 - OUTLINE 3 - HATCHED 4 - CROSS_HATCHED $opt = {FILLTYPE => 'SOLID'}; (see below for an example of hatched fill) font Set the character font. This can either be specified as a number following the PGPLOT numbering or name as follows (name in capitals): 1 - NORMAL 2 - ROMAN 3 - ITALIC 4 - SCRIPT (Note that in a string, the font can be changed using the escape sequences `\fn', `\fr', `\fi' and `\fs' respectively) $opt = {FONT => 'ROMAN'}; gives the same result as $opt = {FONT => 2}; hatching Set the hatching to be used if either fillstyle 3 or 4 is selected (see above) The specification is similar to the one for specifying arrows. The arguments for the hatching is either given using a hash with the key ANGLE to set the angle that the hatch lines will make with the horizontal, SEPARATION to set the spacing of the hatch lines in units of 1% of `min(height, width)' of the view surface, and PHASE to set the offset the hatching. Alternatively this can be specified as a 1x3 piddle `$hatch=pdl[$angle, $sep, $phase]'. $opt = {FILLTYPE => 'HATCHED', HATCHING => {ANGLE=>30, SEPARATION=>4}}; Can also be specified as $opt = {FILL=> 'HATCHED', HATCH => pdl [30,4,0.0]}; For another example of hatching, see `' in this node. justify A boolean value which, if true, causes both axes to drawn to the same scale; see the PGPLOT `pgenv()' command for more information. linestyle Set the line style. This can either be specified as a number following the PGPLOT numbering: 1 - SOLID line 2 - DASHED 3 - DOT-DASH-dot-dash 4 - DOTTED 5 - DASH-DOT-DOT-dot or using name (as given in capitals above). Thus the following two specifications both specify the line to be dotted: $opt = {LINESTYLE => 4}; $varopt = {LINESTYLE => 'DOTTED'}; The names are not case sensitive, but the full name is required. linewidth Set the line width. It is specified as a integer multiple of 0.13 mm. $opt = {LINEWIDTH => 10}; # A rather fat line OBJECT-ORIENTED INTERFACE ========================= This section will briefly describe how the PDL::Graphics::PGPLOT::Window package can be used in an object-oriented (OO) approach and what the advantages of this would be. We will start with the latter Multiple windows. For the common user it is probably most interesting to use the OO interface when handling several open devices at the same time. If you have one variable for each plot device it is easier to distribute commands to the right device at the right time. This is the angle we will take in the rest of this description. Coding and abstraction At a more fundamental level it is desirable to approach a situation where it is possible to have a generic plotting interface which gives access to several plotting libraries, much as PGPLOT gives access to different output devices. Thus in such a hypothetical package one would say: my $win1 = Graphics::new('PGPLOT', {Device => '/xs'}); my $win2 = Graphics::new('gnuplot', {Background => 'Gray'}; From a more practical point of of view such abstraction also comes in handy when you write a large program package and you do not want to import routines nilly-willy in which case an OO approach with method calls is a lot cleaner. Anyway, enough philosophizing, let us get down to Earth and give some examples of the use of OO PGPLOT. As an example we will take Odd (which happens to be a common Norwegian name) who is monitoring the birth of rabbits in O'Fib-o-nachy's farm (alternatively he can of course be monitoring processes or do something entirely different). Odd wants the user to be able to monitor both the birth rates and accumulated number of rabbits and the spatial distribution of the births. Since these are logically different he chooses to have two windows open: $rate_win = PDL::Graphics::PGPLOT::Window->new({Device => '/xw', Aspect => 1, WindowWidth => 5, NXPanel => 2}); $area_win = PDL::Graphics::PGPLOT::Window->new({Device => '/xw', Aspect => 1, WindowWidth => 5}); See the documentation for `new' in this node below for a full overview of the options you can pass to the constructor. Next, Odd wants to create plotting areas for subsequent plots and maybe show the expected theoretical trends $rate_win->env(0, 10, 0, 1000, {XTitle => 'Days', YTitle => '#Rabbits'}); $rate_win->env(0, 10, 0, 100, {Xtitle=>'Days', Ytitle => 'Rabbits/day'}); $area_win->env(0, 1, 0, 1, {XTitle => 'Km', Ytitle => 'Km'}); # And theoretical prediction. $rate_win->line(sequence(10), fibonacci(10), {Panel => [1, 1]}); That is basically it. The commands should automatically focus the relevant window. Due to the limitations of PGPLOT this might however lead you to plot in the wrong panel... The package tries to be smart and do this correctly, but might get it wrong at times. FUNCTIONS ========= A more detailed listing of the functions and their usage follows. For all functions we specify which options take effect and what other options exist for the given function. The function descriptions below are all given for the non-OO usage for historical reasons, but since the conversion to an OO method is trivial there is no major need for concern. Whenever you see a function example of the form Usage: a_simple_function($x, $y, $z [, $opt]); and you wish to use the OO version, just let your mind read the above line as: Usage: $win->a_simple_function($x, $y, $z [, $opt]); where `$win' is a PDL::Graphics::PGPLOT::Window object. That is all. Window control functions. ------------------------- new --- $opt is a reference to a hash with options for the new device. The options recognised are the following: AspectRatio The aspect ratio of the image, in the sense vertical/horisontal. Device The type of device to use. The syntax of this is the one used by PGPLOT. Hold Hold the plot window so that subsequent plots can plot over existing plots. This can be adjusted with the `hold()' and release() methods. NXPanel The number of panels in the X-direction NYPanel The number of panels in the Y-direction WindowName The name to give to the window. No particular use is made of this at present. It would be great if it was possible to change the title of the window frame. WindowWidth The width of the window in inches. If this is set to 0.0, the biggest window consistent with the AspectRatio setting will be chosen. WindowXSize and WindowYSize These two options allow an alternative setting of WindowWidth and AspectRatio. Their values are actually not parsed here, but rather subsequently in the _setup_window routine below. An important point to note is that the default values of most options can be specified by passing these to the constructor. All general options (common to several functions) can be adjusted in such a way, but function specific options can not be set in this way (this is a design limitation which is unlikely to be changed). Thus the following call will set up a window where the default axis colour will be yellow and where plot lines normally have red colour and dashed linestyle. $win = PDL::Graphics::PGPLOT::Window->new({Device => '/xs', AxisColour => 'Yellow', Colour => 'Red', LineStyle => 'Dashed'}); close ----- Close the current window. This does not necessarily mean that the window is removed from your screen, but it does ensure that the device is closed. held ---- Function to check whether the window is held or not. hold ---- Holds the present window so that subsequent plot commands overplots. panel ----- Move to a different panel on the plotting surface. Note that you will need to erase it manually if that is what you require. release ------- Release a plot window so that subsequent plot commands move to the next panel or erase the plot and create a new plot. erase ----- Erase a plot area. This accepts the option `Panel' or alternatively a number or array reference which makes it possible to specify the panel to erase when working with several panels. Plotting functions ------------------ env --- `$xmin', `$xmax', `$ymin', `$ymax' are the plot boundaries. `$justify' is a boolean value (default is 0); if true the axes scales will be the same (see `' in this node). `$axis' describes how the axes should be drawn (see `' in this node) and defaults to 0. If the second form is used, $justify and $axis can be set in the options hash, for example: env 0, 100, 0, 50, {JUSTIFY => 1, AXIS => 'GRID', CHARSIZE => 0.7}; In addition the following options can also be set for env: PlotPosition The position of the plot on the page relative to the view surface in normalised coordinates as an anonymous array. The array should contain the lower and upper X-limits and then the lower and upper Y-limits. To place two plots above each other with no space between them you could do env(0, 1, 0, 1, {PlotPosition => [0.1, 0.5, 0.1, 0.5]}); env(5, 9, 0, 8, {PlotPosition => [0.1, 0.5, 0.5, 0.9]}); Axis, Justify, Border See the description of general options for these options. AxisColour Set the colour of the coordinate axes. XTitle, YTitle, Title, Font, CharSize Axes titles and the font and size to print them. label_axes ---------- Draw labels for each axis on a plot. imag ---- Notes: `$transform' for image/cont etc. is used in the same way as the `TR()' array in the underlying PGPLOT FORTRAN routine but is, fortunately, zero-offset. There are several options related to scaling. By default, the image is scaled to fit the PGPLOT default viewport on the screen. Scaling, aspect ratio preservation, and 1:1 pixel mapping are available. (1:1 pixel mapping GREATLY increases the speed of pgimag, and is useful for, eg, movie display; but it's not recommended for final output as it's not device-independent.) To draw a colour bar (or wedge), either use the `DrawWedge' option, or the `draw_wedge()' routine (once the image has been drawn). Options recognised: ITF - the image transfer function applied to the pixel values. It may be one of 'LINEAR', 'LOG', 'SQRT' (lower case is acceptable). It defaults to 'LINEAR'. MIN - Sets the minimum value to be used for calculation of the display stretch MAX - Sets the maximum value for the same TRANSFORM - The transform 'matrix' as a 6x1 vector for display PIX - Sets the image pixel aspect ratio. By default, imag stretches the image pixels so that the final image aspect ratio fits the viewport exactly. Setting PIX=>1 causes the image aspect ratio to be preserved. (the image is scaled to avoid cropping, unless you specify scaling manually). Larger numbers yield "landscape mode" pixels. PITCH - Sets the number of image pixels per screen unit, in the Y direction. The X direction is determined by PIX, which defaults to 1 if PITCH is specified and PIX is not. PITCH causes UNIT to default to "inches" so that it is easy to say 100dpi by specifying {PITCH=>100}. Larger numbers yield higher resolution (hence smaller appearing) images. UNIT - Sets the screen unit used for scaling. Must be one of the PGPLOT supported units (inch, mm, pixel, normalized). You can refer to them by name or by number. Defaults to pixels if not specified. SCALE - Syntactic sugar for the reciprocal of PITCH. Makes the UNIT default to "pixels" so you can say "{SCALE=>1}" to see your image in device pixels. Larger SCALEs lead to larger appearing images. DrawWedge - set to 1 to draw a colour bar (default is 0) Wedge - see the draw_wedge() routine The following standard options influence this command: AXIS, BORDER, JUSTIFY imag1 ----- Notes: This is syntactic sugar for imag({PIX=>1}). draw_wedge ---------- Adds a wedge - shows the mapping between colour and value for a pixel - to the current image. This can also be achieved by setting `DrawWedge' to 1 when calling the imag routine. The colour and font size are the same as used to draw the image axes (although this will probably fail if you did it yourself). To control the size and location of the wedge, use the `Wedge' option, giving it a hash reference containing any of the following: Side Which side of the image to draw the wedge: can be one of 'B', 'L', 'T', or 'R'. Default is 'R'. Displacement How far from the egde of the image should the wedge be drawn, in units of character size. To draw within the image use a negative value. Default is 2. Width How wide should the wedge be, in units of character size. Default is 3. Label A text label to be added to the wedge. If set, it is probably worth increasing the Width value by about 1 to keep the text readable. Default is ". ForeGround (synonym Fg) The pixel value corresponding to the "maximum" colour. If undef, uses the value used by imag (recommended choice). Default is undef. BackGround (synonym Bg) The pixel value corresponding to the "minimum" colour. If undef, uses the value used by imag (recommended choice). Default is undef. ctab ---- Usage: Note: See `PDL::Graphics::LUT|PDL::Graphics::LUT' in this node for access to a large number of colour tables. line ---- If the 'MISSING' option is specified, those points in the `$y' vector which are equal to the MISSING value are not plotted, but are skipped over. This allows one to quickly draw multiple lines with one call to line, for example to draw coastlines for maps. The following standard options influence this command: AXIS, BORDER, COLO(U)R, JUSTIFY, LINESTYLE, LINEWIDTH, MISSING points ------ Options recognised: SYMBOL - Either a piddle with the same dimensions as $x, containing the symbol associated to each point or a number specifying the symbol to use for every point, or a name specifying the symbol to use according to the following (recognised name in capital letters): 0 - SQUARE 1 - DOT 2 - PLUS 3 - ASTERISK 4 - CIRCLE 5 - CROSS 7 - TRIANGLE 8 - EARTH 9 - SUN 11 - DIAMOND 12- STAR PLOTLINE - If this is >0 a line will be drawn through the points. The following standard options influence this command: AXIS, BORDER, CHARSIZE, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH errb ---- Usage: Options recognised: TERM - Length of terminals in multiples of the default length SYMBOL - Plot the datapoints using the symbol value given, either as name or number - see documentation for 'points' The following standard options influence this command: AXIS, BORDER, CHARSIZE, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH cont ---- Notes: `$transform' for image/cont etc. is used in the same way as the `TR()' array in the underlying PGPLOT FORTRAN routine but is, fortunately, zero-offset. Options recognised: CONTOURS - A piddle with the contour levels FOLLOW - Follow the contour lines around (uses pgcont rather than pgcons) If this is set >0 the chosen linestyle will be ignored and solid line used for the positive contours and dashed line for the negative contours. LABELS - An array of strings with labels for each contour LABELCOLOUR - The colour of labels if different from the draw colour This will not interfere with the setting of draw colour using the colour keyword. MISSING - The value to ignore for contouring NCONTOURS - The number of contours wanted for automatical creation, overridden by CONTOURS TRANSFORM - The pixel-to-world coordinate transform vector The following standard options influence this command: AXIS, BORDER, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH bin --- Options recognised: CENTRE - if true, the x values denote the centre of the bin otherwise they give the lower-edge (in x) of the bin CENTER - as CENTRE The following standard options influence this command: AXIS, BORDER, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH hi2d ---- Options recognised: IOFFSET - The offset for each array slice. >0 slants to the right <0 to the left. BIAS - The bias to shift each array slice up by. The following standard options influence this command: AXIS, BORDER, JUSTIFY Note that meddling with the `ioffset' and bias often will require you to change the default plot range somewhat. It is also worth noting that if you have TriD working you will probably be better off using `mesh3d|PDL::Graphics::TriD' in this node or a similar command - see *Note PDL/Graphics/TriD: PDL/Graphics/TriD,. arrow ----- Plot an arrow from `$x1, $y1' to `$x2, $y2'. The arrow shape can be set using the option Arrow. See the documentation for general options for details about this option (and the example below): arrow(0, 1, 1, 2, {Arrow => {FS => 1, Angle => 60, Vent => 0.3, Size => 5}}); which draws a broad, large arrow from (0, 1) to (1, 2). poly ---- Options recognised: The following standard options influence this command: AXIS, BORDER, COLOUR, FILLTYPE, HATCHING, JUSTIFY, LINESTYLE, LINEWIDTH circle ------ All arguments can alternatively be given in the options hash using the following options: XCenter and YCenter The position of the center of the circle Radius The radius of the circle. ellipse ------- All arguments can alternatively be given in the options hash using the following options: MajorAxis The major axis of the ellipse - this must be defined or `$a' must be given. MinorAxis The minor axis, like A this is required. Theta (synonym Angle) The orientation of the ellipse - defaults to 0.0. This is given in radians. XCenter and YCenter The coordinates of the center of the ellipse. These must be specified or $x and `$y' must be given. NPoints The number of points used to draw the ellipse. This defaults to 100 and might need changing in the case of very large ellipses. rectangle --------- This routine draws a rectangle with the chosen fill style. Internally it calls `poly' in this node which is somewhat slower than `pgrect' but which allows for rotated rectangles as well. The routine recognises the same options as poly and in addition the following XCenter and YCenter The position of the center of the rectangle. XCentre and YCentre are valid synonyms. XSide and YSide The length of the X and Y sides. If only one is specified the shape is taken to be square with that as the side-length, alternatively the user can set Side Side The length of the sides of the rectangle (in this case a square) - syntactic sugar for setting XSide and YSide identical. This is overridden by XSide or YSide if any of those are set. Angle (synonym Theta) The angle at which the rectangle is to be drawn. This defaults to 0.0 and is given in radians. vect ---- Notes: `$transform' for image/cont etc. is used in the same way as the `TR()' array in the underlying PGPLOT FORTRAN routine but is, fortunately, zero-offset. This routine will plot a vector field. `$a' is the horizontal component and $b the vertical component. Options recognised: SCALE - Set the scale factor for vector lengths. POS - Set the position of vectors. <0 - vector head at coordinate >0 - vector base at coordinate =0 - vector centered on the coordinate TRANSFORM - The pixel-to-world coordinate transform vector MISSING - Elements with this value are ignored. The following standard options influence this command: ARROW, ARROWSIZE, AXIS, BORDER, CHARSIZE, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH transform --------- This function creates a transform array in the format required by the image and contouring routines. You must call it with the dimensions of your image as arguments or pass these as an anonymous hash - see the example below. Angle The rotation angle of the transform ImageDimensions The dimensions of the image the transform is required for. The dimensions should be passed as a reference to an anonymous hash. Pixinc The increment in output coordinate per pixel. ImageCenter The centre of the image as an anonymous array or as a scalar. In the latter case the x and y value for the center will be set equal to this scalar. This is particularly useful in the common case when the center is (0, 0). Example: $im = rvals(100, 100); $w = PDL::Graphics::PGPLOT::Window->new({Device => '/xs'}); $t = $w->transform(dims($im), {ImageCenter => 0, Pixinc => 5}); $w->imag($im, {Transform => $t}); tline ----- This is a threaded interface to line. This is convenient if you have a 2D array and want to plot out every line in one go. The routine will apply any options you apply in a "reasonable" way. In the sense that it will loop over the options wrapping over if there are less options than lines. Example: $h={Colour => ['Red', '1', 4], Linestyle => ['Solid' ,'Dashed']}; $tx=zeroes(100,5)->xlinvals(-5,5); $ty = $tx + $tx->yvals; tline($tx, $ty, $h); tpoints ------- This is a threaded interface to points. This is convenient if you have a 2D array and want to plot out every line in one go. The routine will apply any options you apply in a "reasonable" way. In the sense that it will loop over the options wrapping over if there are less options than lines. Example: $h={Colour => ['Red', '1', 4], Linestyle => ['Solid' ,'Dashed']}; $tx=zeroes(100,5)->xlinvals(-5,5); $ty = $tx + $tx->yvals; tpoints($tx, $ty, $h); Text routines ------------- text ---- Options recognised: `ANGLE' The angle in degrees between the baseline of the text and the horisontal (increasing counter-clockwise). This defaults to 0. `JUSTIFICATION' The justification of the text relative to the position specified. It defaults to 0.0 which gives left-justified text. A value of 0.5 gives centered text and a value of 1.0 gives right-justified text. `XPos', `YPos', Text These gives alternative ways to specify the text and position. The following standard options influence this command: COLOUR legend ------ This function adds a legend to an existing plot. The action is primarily controlled by information in the options hash, and the basic idea is that $x and `$y' determines the upper left hand corner of the box in which the legend goes. If the width is specified either as an argument or as an option in the option hash this is used to determine the optimal character size to fit the text into part of this width (defaults to 0.5 - see the description of `Fraction' below). The rest of the width is filled out with either lines or symbols according to the content of the `LineStyle', Symbol, `Colour' and `LineWidth' options. The local options recognised are as follows: Text An anonymous array of annotations, can also be specified directly. `XPos' and `YPos' The X and Y position of the upper left-hand corner of the text. Width and `Height' The width and/or height of each line (including symbol/line). This is used to determine the character size. If any of these are set to 'Automatic' the current character size will be used. `Fraction' The text and the symbol/line is set inside a box. `Fraction' determines how much of this box should be devoted to text. THis defaults to 0.5. `TextShift' This option allows for fine control of the spacing between the text and the start of the line/symbol. It is given in fractions of the total width of the legend box. The default value is 0.1. legend 5, 5, ['A red line', 'A blue line'], {LineStyle => ['Solid', 'Dashed'], Colour => ['Red', 'Blue'] LineWidth => [undef, 10]}; # undef gives default. Cursor routines --------------- cursor ------ This routine has no standard input parameters, but the type of cursor can be set by setting the option Type as a key in the anonymous hash $opt. The first three return values from the function are always defined and gives the position selected by the user and the character pressed. Depending on the cursor type selected the last two arguments might also be defined and these give a reference position. For instance if the cursor is selected to be `Rectangle' then the reference position gives one of the corners of the rectangle and $x and `$y' the diagonally opposite one. Options recognised: XRef, YRef The reference position to be used Type The type of cursor. This can be selected using a number between 0 and 7 as in PGPLOT, or alternatively you can specify these as, Default (0), `RadialLine' (1), `Rectangle' (2), `TwoHorizontalLines' (3), `TwoVerticalLines' (4), `HorizontalLine' (5), `VerticalLine' (6) and `CrossHair' (7) respectively. The default cursor is just the normal mouse cursor. For the `RadialLine' you must specify the reference point, whereas for the `Two(Vertical|Horizontal)Lines' cursor the X or Y reference point, respectively, must be specified. ($x, $y, $ch, $xref, $yref) = cursor({Type => 'Rectangle'}); poly pdl($x, $xref, $xref, $x, $x), pdl($y, $y, $yref, $yref, $y); To select a region of the X-axis: ($x1, $y1, $ch) = cursor({Type => 'VerticalLine'}); ($x2, $y2, $ch) = cursor({Type => 'TwoVerticalLines', XRef => $x1}); Internal routines ----------------- _open_new_window ---------------- Open a new window. This sets the window ID, which is the one used when accessing a window later using `pgslct'. It also sets the window name to something easily remembered if it has not been set before. _setup_window ------------- This routine sets up a new window with its shape and size. This is also where the two options WindowXSize and `WindowYSize' is parsed. These are then forgotten (well, they are stored in $self->{Options}, but forget that) and the corresponding aspect ratio and window width is stored. Finally the subpanels are set up using `pgsubp' and colours and linewidth are adjusted according to whether we have a hardcopy device or not. _status ------- This routine checks the status of the window. It returns OPEN if the window is open and CLOSED if it is closed. _reopen ------- This functions reopens a window. Since this is an internal function it does not have a lot of error-checking. Make sure the device is closed before calling this routine. There is an unfortunate problem which pops up viz. that the window name cannot be changed at this point since we are offering that to the rest of the world. That might be sensible, but it means that the window name will not reflect the id of the window - use id() for that (this is also why we do not call `open_new_window' ) _advance_panel -------------- This routine advances one plot panel, updating the CurrentPanel as well. If the advance will proceed past the page the page will be erased. Also note that when you advance one panel the hold value will be changed. _check_move_or_erase -------------------- This routine is a utility routine which checks if we need to move panel, and if so will do this. It also checks if it is necessary to advance panels, and whether they need to be erased. _thread_options --------------- This function is a cludgy utility function that expands an options hash to an array of hashes looping over options. This is mainly of use for "threaded" interfaces to standard plotting routines. options ------- Access the options used when *originally* opening the window. At the moment this is not updated when the window is changed later. id -- Access the window ID that PGPLOT uses for the present window. device ------ This function returns the device type of the present window. name ---- Accessor to set and examine the name of a window. focus ----- Set focus for subsequent PGPLOT commands to this window. info ---- The valid values of `@item' are as below, where case is not important: VERSION - What PGPLOT version is in use STATE - The status of the output device, this is returns 'OPEN' if the device is open and 'CLOSED' otherwise. USER - The username of the owner of the spawning program. NOW - The current date and time in the format 'dd-MMM-yyyy hh:mm'. Most people are likely to use Perl functions for this. DEVICE * - The current PGPLOT device or file, see also C FILE * - The filename for the current device TYPE * - And the device type for the current device DEV/TYPE * - This combines DEVICE and TYPE in a form that can be used as input to C. HARDCOPY * - This is flag which is set to 'YES' if the current device is a hardcopy device and 'NO' otherwise. TERMINAL * - This flag is set to 'YES' if the current device is the user's terminal and 'NO' otherwise. CURSOR * - A flag ('YES' or 'NO') to inform whether the current device has a cursor. Those items marced with a * only return a valid answer if the window is open. A question mark (?) is returned if the item is not recognised or the information is not available. _extract_hash ------------- This routine takes and array and returns the first hash reference found as well as those elements that are not hashes. Note the latter point because all other references to hashes in the array will be lost. _parse_options -------------- This is a convenience routine for parsing a set of options. It returns both the full set of options and those that the user has set. _save_status ------------ Saves the PGPLOT state so that changes to settings can be made and then the present state restored by _restore_status. _restore_status --------------- Restore the PGPLOT state. See `_save_status' in this node. _checkarg --------- This routine checks and optionally alters the arguments given to it. _standard_options_parser ------------------------ This internal routine is the default routine for parsing options. This routine deals with a subset of options that most routines will accept. INTERNAL ======== The coding tries to follow reasonable standards, so that all functions starting with an underscore should be considered as internal and should not be called from outside the package. In addition most routines has a set of options. These are encapsulated and are not accessible outside the routine. This is to avoid collisions between different variables. AUTHOR ====== Karl Glazebrook [kgb@aaoepp.aao.gov.au] modified by Jarle Brinchmann (jarle@astro.ox.ac.uk) who is also responsible for the OO interface, docs mangled by Tuomas J. Lukka (lukka@fas.harvard.edu) and Christian Soeller (c.soeller@auckland.ac.nz). Further contributions and bugfixes from Kaj Wiik, Doug Burke and many others. All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.