This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: PDL/IO/Pic, Next: PDL/IO/Pnm, Prev: PDL/IO/NDF, Up: Module List image I/O for PDL ***************** NAME ==== PDL::IO::Pic - image I/O for PDL DESCRIPTION =========== Image I/O for PDL based on the netpbm package. ---------------------------------------------- This package implements I/O for a number of popular image formats by exploiting the xxxtopnm and pnmtoxxx converters from the netpbm package (which is based on the original pbmplus by Jef Poskanzer). Netpbm is available at ftp://wuarchive.wustl.edu/graphics/graphics/packages/NetPBM/ Pbmplus (on which netpbm is based) might work as well, I haven't tried it. If you want to read/write JPEG images you additionally need the two converters cjpeg/djpeg which come with the libjpeg distribution (the "official" archive site for this software is ftp://ftp.uu.net/graphics/jpeg). Image I/O for all formats is established by reading and writing only the PNM format directly while the netpbm standalone apps take care of the necessary conversions. In accordance with netpbm parlance PNM stands here for 'portable any map' meaning any of the PBM/PGM/PPM formats. As it appeared to be a reasonable place this package also contains the routine wmpeg to write mpeg movies from PDLs representing image stacks (the image stack is first written as a sequence of PPM images into some temporary directory). For this to work you additionally need the program mpeg_encode from the Berkeley multimedia package. You find mpeg_encode at ftp://mm-ftp.cs.berkeley.edu/pub/multimedia/mpeg/encode (they even have binaries for a number of platforms). Configuration ------------- The executables from the netpbm package are assumed to be in your path. Problems in finding the executables may show up as PNM format errors when calling wpic/rpic. If you run into this kind of problem run your program with perl -w so that perl prints a message if it can't find the filter when trying to open the pipe. FUNCTIONS ========= rpiccan, wpiccan ---------------- finds out if PDL::IO::Pic can read/write certain image formats. When called without arguments returns a list of supported formats. When called with an argument returns true if format is supported on your computer (requires appropriate filters in your path), false otherwise. rpic ---- Options Reads image files in most of the formats supported by netpbm. You can explicitly specify a supported format by additionally passing a hash containing the FORMAT key as in $im = rpic ($file, {FORMAT => 'GIF'}); This is especially useful if the particular format isn't identified by a magic number and doesn't have the 'typical' extension or you want to avoid the check of the magic number if your data comes in from a pipe. The function returns a pdl of the appropriate type upon completion. Option parsing uses the *Note PDL/Options: PDL/Options, module and therefore supports minimal options matching. You can also read directly into an existing pdl that has to have the right size(!). This can come in handy when you want to read a sequence of images into a datacube, e.g. $stack = zeroes(byte,3,500,300,4); rpic $stack->slice(':,:,:,(0)'),"PDL.jpg"; reads an rgb image (that had better be of size (500,300)) into the first plane of a 3D RGB datacube (=4D pdl datacube). You can also do transpose/inversion upon read that way. wpic ---- Write out an image file. Function will try to guess correct image format from the filename extension, e.g. $pdl->wpic("image.gif") will write a gif file. The data written out will be scaled to byte if input is of type float/double. Input data that is of a signed integer type and contains negative numbers will be rejected (assuming the user should have the desired conversion to an unsigned type already). A number of options can be specified (as a hash reference) to get more direct control of the image format that is being written. Valid options are (key => example_value): Option parsing uses the *Note PDL/Options: PDL/Options, module and therefore supports minimal options matching. A detailed explanation of supported options follows. CONVERTER directly specify the converter, you had better know what you are doing, e.g. CONVERTER => 'ppmtogif', FLAGS flags to use with the converter; ignored if !defined($$hints{CONVERTER}), e.g. with the gif format FLAGS => '-interlaced -transparent 0', IFORM intermediate PNM/PPM/PGM/PBM format to use; you can append the strings 'RAW' or 'ASCII' to enforce those modes, eg IFORMAT=>'PGMRAW' or IFORM => 'PGM', XTRAFLAGS additional flags to use with an automatically chosen converter, this example works when you write SGI files (but will give an error otherwise) XTRAFLAGS => '-imagename iris', FORMAT explicitly select the format you want to use. Required if wpic cannot figure out the desired format from the file name extension. Supported types are currently TIFF,GIF,SGI,PNM,JPEG,PS,RAST(Sun Raster),IFF,PCX, e.g. FORMAT => 'PCX', COLOR you want black and white (value *bw*), other possible value is *bwdither* which will write a dithered black&white image from the input data, data conversion will be done appropriately, e.g. COLOR => 'bw', LUT This is a palette image and the value of this key should be a pdl containg an RGB lookup table (3,x), e.g. LUT => $lut, Using the CONVERTER hint you can also build a pipe and perform several netpbm operations to get the special result you like. Using it this way the first converter/filecommand in the pipe should be specified with the CONVERTER hint and subsequent converters + flags in the FLAGS hint. This is because wpic tries to figure out the required format to be written by wpnm based on the first converter. Be careful when using the PBMBIN var as it will only be prepended to the converter. If more converters are in the FLAGS part specify the full path unless they are in your PATH anyway. Example: $im->wpic('test.ps',{CONVERTER => 'pgmtopbm', FLAGS => "-dither8 | pnmtops" }) Some of the options may appear silly at the moment and probably are. The situation will hopefully improve as people use the code and the need for different/modified options becomes clear. The general idea is to make the function perl compliant: easy things should be easy, complicated tasks possible. wmpeg ----- Writes a stack of rgb images as an mpeg movie. Expects a 4-D pdl of type byte as input. First dim has to be 3 since it is interpreted as interlaced RGB. Some of the input data restrictions will have to be relaxed in the future but routine serves as a proof of principle at the moment. It uses the program mpeg_encode from the Berkeley multimedia package (see also text at the top of this package). Mpeg parameters written by this routines haven't been tweaked in any way yet (in other words, lots of room for improvement). For an example how to use the routine see appropriate test that comes with this package. Currently, wmpeg doesn't allow modification of the parameters written through its calling interface. This will change in the future as needed. In the future it might be much nicer to implement a movie perl object that supplies methods for manipulating the image stack (insert, cut, append commands) and a final movie->make() call would invoke mpeg_encode on the picture stack (which will only be held on disk). This should get around the problem of having to hold a huge amount of data in memory to be passed into wmpeg (when you are, e.g. writing a large animation from PDL3D rendered fly-throughs). Having said that, the actual storage requirements might not be so big in the future any more if you could pass 'virtual' transform pdls into wmpeg that will only be actually calculated when accessed by the wpic routines, you know what I mean... BUGS ==== Currently only a random selection of converters/formats provided by pbmplus/netpbm is supported. It is hoped that the more important formats are covered. Other formats can be added as needed. Please send patches to the author. AUTHOR ====== Copyright (C) 1996,1997 Christian Soeller 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/IO/Pnm, Next: PDL/Image2D, Prev: PDL/IO/Pic, Up: Module List pnm format I/O for PDL ********************** NAME ==== PDL::IO::Pnm - pnm format I/O for PDL SYNOPSIS ======== use PDL::IO::Pnm; $im = wpnm $pdl, $file, $format[, $raw]; rpnm $stack->slice(':,:,:,(0)'),"PDL.ppm"; DESCRIPTION =========== pnm I/O for PDL. ---------------- FUNCTIONS ========= rpnm ---- Reads a file in pnm format (ascii or raw) into a pdl (magic numbers P1-P6). Based on the input format it returns pdls with arrays of size (width,height) if binary or grey value data (pbm and pgm) or (3,width,height) if rgb data (ppm). This also means for a palette image that the distinction between an image and its lookup table is lost which can be a problem in cases (but can hardly be avoided when using netpbm/pbmplus). Datatype is dependent on the maximum grey/color-component value (for raw and binary formats always PDL_B). rpnm tries to read chopped files by zero padding the missing data (well it currently doesn't, it barfs; I'll probably fix it when it becomes a problem for me ;). You can also read directly into an existing pdl that has to have the right size(!). This can come in handy when you want to read a sequence of images into a datacube. For details about the formats see appropriate manpages that come with the netpbm/pbmplus packages. reads an rgb image (that had better be of size (500,300)) into the first plane of a 3D RGB datacube (=4D pdl datacube). You can also do inplace transpose/inversion that way. wpnm ---- Writes data in a pdl into pnm format (ascii or raw) (magic numbers P1-P6). The $format is required (normally produced by wpic) and routine just checks if data is compatible with that format. All conversions should already have been done. If possible, usage of wpic is preferred. Currently RAW format is chosen if compliant with range of input data. Explicit control of ASCII/RAW is possible through the optional $raw argument. If RAW is set to zero it will enforce ASCII mode. Enforcing RAW is somewhat meaningless as the routine will always try to write RAW format if the data range allows (but maybe it should reduce to a RAW supported type when RAW == 'RAW'?). For details about the formats consult appropriate manpages that come with the netpbm/pbmplus packages. BUGS ==== The stderr of the converters is redirected to a file. The filename is currently generated in a probably non-portable way. A method that avoids a file (and is portable) would be prefered. rpnm currently relies on the fact that the header is separated from the image data by a newline. This is not required by the p[bgp]m formats (in fact any whitespace is allowed) but most of the pnm writers seem to comply with that. Truncated files are currently treated ungracefully (rpnm just barfs). AUTHOR ====== Copyright (C) 1996,1997 Christian Soeller 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. FUNCTIONS ========= pnminraw -------- read a raw pnm file. The type argument is only there to determine the type of the operation when creating `im' or trigger the appropriate type conversion (maybe we want a byte+ here so that `im' follows *strictly* the type of type). pnminascii ---------- pnmout ------ This function is implemented this way so that threading works naturally.  File: pm.info, Node: PDL/Image2D, Next: PDL/ImageND, Prev: PDL/IO/Pnm, Up: Module List Miscellaneous 2D image processing functions ******************************************* NAME ==== PDL::Image2D - Miscellaneous 2D image processing functions DESCRIPTION =========== Miscellaneous 2D image processing functions - for want of anywhere else to put them SYNOPSIS ======== use PDL::Image2D; FUNCTIONS ========= conv2d ------ For large kernels, using a FFT routine, such as `fftconvolve()|PDL::FFT' in this node in `PDL::FFT', will be quicker. med2d ----- Note: only points in the kernel >0 are included in the median, other points are weighted by the kernel value (medianing lots of zeroes is rather pointless) patch2d ------- `$bad' is a 2D mask array where 1=bad pixel 0=good pixel. Pixels are replaced by the average of their non-bad neighbours; if all neighbours are bad, the original data value is copied across. patchbad2d ---------- Pixels are replaced by the average of their non-bad neighbours; if all neighbours are bad, the output is set bad. If the input piddle contains no bad values, then a straight copy is performed (see `patch2d|' in this node). max2d_ind --------- Contributed by Tim Jeness centroid2d ---------- `$box' is the full-width of the box, i.e. the window is `+/- $box/2'. cc8compt -------- Connected 8-component labeling of 0,1 image - i.e. find seperate segmented objects and fill object pixels with object number polyfill -------- This function works inplace, i.e. modifies `im'. polyfillv --------- rot2d ----- This function rotates an image through an `angle' between -90 and + 90 degrees. Uses/doesn't use antialiasing depending on the aa flag. Pixels outside the rotated image are set to `bg'. Code modified from pnmrotate (Copyright Jef Poskanzer) with an algorithm based on "A Fast Algorithm for General Raster Rotation" by Alan Paeth, Graphics Interface '86, pp. 77-81. Use the `rotnewsz' function to find out about the dimension of the newly created image ($newcols,$newrows) = rotnewsz $oldn, $oldm, $angle; bilin2d ------- rescale2d --------- fitwarp2d --------- Given a set of points in the output plane (`$u,$v'), find the best-fit (using singular-value decomposition) 2D polynomial to describe the mapping back to the image plane (`$x,$y'). The order of the fit is controlled by the `$nf' parameter (the maximum power of the polynomial is `$nf - 1'), and you can restrict the terms to fit using the FIT option. `$px' and `$py' are np by np element piddles which describe a polynomial mapping (of order `np-1') from the output `(u,v)' image to the input `(x,y)' image: x = sum(j=0,np-1) sum(i=0,np-1) px(i,j) * u^i * v^j y = sum(j=0,np-1) sum(i=0,np-1) py(i,j) * u^i * v^j Please note that this storage is the transpose of that used by the `polywarp' routine in IDL. The transformation is returned for the reverse direction (ie output to input image) since that is what is required by the `warp2d()|' in this node routine. The `applywarp2d()|' in this node routine can be used to convert a set of `$u,$v' points given `$px' and `$py'. Options: FIT FIT allows you to restrict which terms of the polynomial to fit: only those terms for which the FIT piddle evaluates to true will be evaluated. If a 2D piddle is sent in, then it is used for the x and y polynomials; otherwise `$fit->slice(":,:,(0)")' will be used for `$px' and `$fit->slice(":,:,(1)")' will be used for `$py'. THRESH Remove all singular values whose valus is less than THRESH times the largest singular value. The number of points must be at least equal to the number of terms to fit (`$nf*$nf' points for the default value of FIT). applywarp2d ----------- Convert a set of points (stored in 1D piddles `$u,$v') to `$x,$y' using the 2-D polynomial with coefficients stored in `$px' and `$py'. See `fitwarp2d()|' in this node for more information on the format of `$px' and `$py'. warp2d ------ Apply the polynomial transformation encoded in the `$px' and `$py' piddles to warp the input image `$img' into the output image `$out'. It is similar to the `poly_2d' routine in IDL. The format for the polynomial transformation is described in the documentation for the `fitwarp2d()|' in this node routine. At each point `x,y', the closest 16 pixel values are combined with an interpolation kernel to calculate the value at `u,v'. The interpolation is therefore done in the image, rather than Fourier, domain. By default, a tanh kernel is used, but this can be changed using the KERNEL option discussed below (the choice of kernel depends on the frequency content of the input image). The routine is based on the `warping' command from the Eclipse data-reduction package - see http://www.eso.org/eclipse/ - and for further details on image resampling see Wolberg, G., "Digital Image Warping", 1990, IEEE Computer Society Press (ISBN 0-8186-8944-7). Currently the output image is the same size as the input one, which means data will be lost if the transformation reduces the pixel scale. This will (hopefully) be changed soon. The options are: KERNEL is used to specify which interpolation kernel to use (to see what these kernels look like, use the `warp2d_kernel()|' in this node routine). The options are: tanh Hyperbolic tangent: the approximation of an ideal box filter by the product of symmetric tanh functions. sinc For a correctly sampled signal, the ideal filter in the fourier domain is a rectangle, which produces a sinc interpolation kernel in the spatial domain: sinc(x) = sin(pi * x) / (pi * x) However, it is not ideal for the `4x4' pixel region used here. sinc2 This is the square of the sinc function. lanczos Although defined differently to the tanh kernel, the result is very similar in the spatial domain. The Lanczos function is defined as L(x) = sinc(x) * sinc(x/2) if abs(x) < 2 = 0 otherwise hann This kernel is derived from the following function: H(x) = a + (1-a) * cos(2*pi*x/(N-1)) if abs(x) < 0.5*(N-1) = 0 otherwise with `a = 0.5' and N currently equal to 2001. hamming This kernel uses the same `H(x)' as the Hann filter, but with `a = 0.54'. `NOVAL' gives the value used to indicate that a pixel in the output image does not map onto one in the input image. warp2d_kernel ------------- The valid values for $name are the same as the KERNEL option of `warp2d()|' in this node. AUTHORS ======= Copyright (C) Karl Glazebrook 1997 with additions by Robin Williams (rjrw@ast.leeds.ac.uk), Tim Jeness (timj@jach.hawaii.edu), and Doug Burke (burke@ifa.hawaii.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/ImageND, Next: PDL/ImageRGB, Prev: PDL/Image2D, Up: Module List useful image processing routines which work in N-dimensions *********************************************************** NAME ==== PDL::ImageND - useful image processing routines which work in N-dimensions DESCRIPTION =========== In some cases (though not as many as one would like) it is possible to write general routines that operate on N-dimensional objects. An example in this module is a N-Dim convolution algorithm I made up one day - it works but the boundary condtions are a bit funny. SYNOPSIS ======== use PDL::ImageND; FUNCTIONS ========= convolve -------- Convolve an array with a kernel, both of which are N-dimensional. Note because of the algorithm used (writing N-dim routines is not easy on the brain!) the boundary conditions are a bit strange. They wrap, but up to the NEXT row/column/cube-slice/etc. If this is a problem consider using zero-padding or something. ninterpol() ----------- `ninterpol' uses interpol to find a linearly interpolated value in N dimensions, assuming the data is spread on a uniform grid. To use an arbitrary grid distribution, need to find the grid-space point from the indexing scheme, then call `ninterpol' - this is far from trivial (and ill-defined in general). rebin ----- Rebin an N-dimensional array to newly specified dimensions. Specifying `Norm' keeps the sum constant, otherwise the intensities are kept constant. If more template dimensions are given than for the input pdl, these dimensions are created; if less, the final dimensions are maintained as they were. So if `$a' is a 10 x 10 pdl, then `rebin($a,15)' is a 15 x 10 pdl, while `rebin($a,15,16,17)' is a 15 x 16 x 17 pdl (where the values along the final dimension are all identical). circ_mean_p ----------- circ_mean --------- AUTHORS ======= 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/ImageRGB, Next: PDL/Impatient, Prev: PDL/ImageND, Up: Module List some utility functions for RGB image data handling ************************************************** NAME ==== PDL::ImageRGB - some utility functions for RGB image data handling DESCRIPTION =========== Collection of a few commonly used routines involved in handling of RGB, palette and grayscale images. Not much more than a start. Should be a good place to exercise some of the thread/map/clump PP stuff. Other stuff that should/could go here: * color space conversion * common image filters * image rebinning SYNOPSIS ======== use PDL::ImageRGB; FUNCTIONS ========= cquant ------ This function does color reduction for <=8bit displays and accepts 8bit RGB and 8bit palette images. It does this through an interface to the ppm_quant routine from the pbmplus package that implements the median cut routine which intellegently selects the 'best' colors to represent your image on a <= 8bit display (based on the median cut algorithm). Optional args: $ncols sets the maximum nunmber of colours used for the output image (defaults to 256). There are images where a different color reduction scheme gives better results (it seems this is true for images containing large areas with very smoothly changing colours). Returns a list containing the new palette image (type PDL_Byte) and the RGB colormap. interlrgb --------- Input should be of an integer type and the lookup table (3,x,...). Will perform the lookup for any N-dimensional input pdl (i.e. 0D, 1D, 2D, ...). Uses the index command but will not dataflow by default. If you want it to dataflow the dataflow_forward flag must be set in the $lut piddle (you can do that by saying $lut->set_dataflow_f(1)). rgbtogr ------- Performs a conversion of an RGB input image (3,x,....) to a greyscale image (x,.....) using standard formula: Grey = 0.301 R + 0.586 G + 0.113 B bytescl ------- By default $top=255, otherwise you have to give the desired top value as an argument to bytescl. Normally bytescl doesn't rescale data that fits already in the bounds 0..$top (it only does the type conversion if required). If you want to force it to rescale so that the max of the output is at $top and the min at 0 you give a negative $top value to indicate this. BUGS ==== This package doesn't yet contain enough useful functions! AUTHOR ====== Copyright 1997 Christian Soeller 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/Impatient, Next: PDL/Index, Prev: PDL/ImageRGB, Up: Module List PDL for the impatient (quick overview) ************************************** NAME ==== PDL::Impatient - PDL for the impatient (quick overview) SYNOPSIS ======== Executive summary of what PDL is about. DESCRIPTION =========== Introduction ------------ Perl is an extremely good and versatile scripting language, well suited to beginners and allows rapid prototyping. However until recently it did not support data structures which allowed it to do fast number crunching. However with the development of Perl v5, Perl acquired 'Objects'. To put it simply users can define their own special data types, and write custom routines to manipulate them either in low level languages (C and Fortran) or in Perl itself. This has been fully exploited by the PerlDL developers. The 'PDL' module is a complete Object-Oriented extension to Perl (although you don't have to know what an object is to use it) which allows large N-dimensional data sets, such as large images, spectra, time series, etc to be stored *efficiently* and manipulated *en masse*. For example with the PDL module we can write the perl code `$a=$b+$c', where $b and $c are large datasets (e.g. 2048x2048 images), and get the result in only a fraction of a second. PDL variables (or 'piddles' as they have come to be known) support a wide range of fundamental data types - arrays can be bytes, short integers (signed or unsigned), long integers, floats or double precision floats. And because of the Object-Oriented nature of PDL new customised datatypes can be derived from them. As well as the PDL modules, that can be used by normal perl programs, PerlDL comes with a command line perl shell, called 'perldl', which supports command line editing. In combination with the various PDL graphics modules this allows data to be easily played with and visualised. Help ---- PDL contains extensive documentation, available both within the *perldl* shell and from the command line, using the `pdldoc' program. For further information try either of: perldl> help help $ pdldoc HTML copies of the documentation should also be available. To find their location, try the following: perldl> foreach ( map{"$_/PDL/HtmlDocs"}@INC ) { p "$_\n" if -d $_ } Perl Datatypes and how PDL extends them --------------------------------------- The fundamental perl data structures are scalar variables, e.g. $x, which can hold numbers or strings, lists or arrays of scalars, e.g. `@x', and associative arrays/hashes of scalars, e.g. `%x'. perl v5 introduces to perl data structures and objects. A simple scalar variable $x now be a user-defined data type or full blown object (it actually holds a reference (a smart "pointer") to this but that is not relevant for ordinary use of perlDL) The fundamental idea behind perlDL is to allow $x to hold a whole 1D spectrum, or a 2D image, a 3D data cube, and so on up to large N-dimensional data sets. These can be manipulated all at once, e.g. `$a = $b + 2' does a vector operation on each value in the spectrum/image/etc. You may well ask: "Why not just store a spectrum as a simple perl `@x' style list with each pixel being a list item?" The two key answers to this are memory and *speed*. Because we know our spectrum consists of pure numbers we can compactly store them in a single block of memory corresponding to a C style numeric array. This takes up a LOT less memory than the equivalent perl list. It is then easy to pass this block of memory to a fast addition routine, or to any other C function which deals with arrays. As a result perlDL is very fast -- for example one can mulitiply a 2048*2048 image in exactly the same time as it would take in C or FORTRAN (0.1 sec on my SPARC). A further advantage of this is that for simple operations (e.g. `$x += 2') one can manipulate the whole array without caring about its dimensionality. I find when using perlDL it is most useful to think of standard perl `@x' variables as "lists" of generic "things" and PDL variables like $x as "arrays" which can be contained in lists or hashes. Quite often in my perlDL scripts I have `@x' contain a list of spectra, or a list of images (or even a mix!). Or perhaps one could have a hash (e.g. `%x') of images... the only limit is memory! perlDL variables support a range of data types - arrays can be bytes, short integers (signed or unsigned), long integers, floats or double precision floats. Usage ----- PerlDL is loaded into your perl script using this command: use PDL; # in perl scripts: use the standard perlDL modules There are also a lot of extension modules, e.g. `PDL::Graphics::TriD|PDL::Graphics::TriD' in this node. Most of these (but not all as sometimes it is not appropriate) follow a standard convention. If you say: use PDL::Graphics::TriD; You import everything in a standard list from the module. Sometimes you might want to import nothing (e.g. if you want to use OO syntax all the time and save the import tax). For these you say: use PDL::Graphics::TriD ''; And the blank quotes " are regonised as meaning 'nothing'. You can also specify a list of functions to import in the normal Perl way. There is also an interactive shell, `perldl', see *perldl*. To create a new PDL variable ---------------------------- Here are some ways of creating a PDL variable: $a = pdl [1..10]; # 1D array $a = pdl (1,2,3,4); # Ditto $b = pdl [[1,2,3],[4,5,6]]; # 2D 3x2 array $b = pdl 42 # 0-dimensional scalar $c = pdl $a; # Make a new copy $d = byte [1..10]; # See "Type conversion" $e = zeroes(3,2,4); # 3x2x4 zero-filled array $c = rfits $file; # Read FITS file @x = ( pdl(42), zeroes(3,2,4), rfits($file) ); # Is a LIST of PDL variables! The `pdl()|PDL::Core' in this node function is used to initialise a PDL variable from a scalar, list, list reference or another PDL variable. In addition all PDL functions automatically convert normal perl scalars to PDL variables on-the-fly. (also see "Type Conversion" and "Input/Output" sections below) Arithmetic (and boolean expressions) ------------------------------------ $a = $b + 2; $a++; $a = $b / $c; # Etc. $c=sqrt($a); $d = log10($b+100); # Etc $e = $a>42; # Vector conditional $e = 42*($a>42) + $a*($a<=42); # Cap top $b = $a->log10 unless any ($a <= 0); # avoid floating point error $a = $a / ( max($a) - min($a) ); $f = where($a, $a > 10); # where returns a piddle of elements for # which the condition is true print $a; # $a in string context prints it in a N-dimensional format (and other perl operators/functions) When using piddles in conditional expressions (i.e. if, `unless' and while constructs) only piddles with exactly one element are allowed, e.g. $a = pdl (1,0,0,1); print "is set" if $a->index(2); Note that the boolean operators return in general multielement piddles. Therefore, the following will raise an error print "is ok" if $a > 3; since `$a > 3' is a piddle with 4 elements. Rather use `all|PDL::Primitive' in this node or `any|PDL::Primitive' in this node to test if all or any of the elements fulfill the condition: print "some are > 3" if any $a>3; print "can't take logarithm" unless all $a>0; There are also many predefined functions, which are described on other manpages. Check *Note PDL/Index: PDL/Index,. Matrix functions ---------------- 'x' is hijacked as the matrix multiplication operator. e.g. `$c = $a x $b'; perlDL is row-major not column major so this is actually `c(i,j) = sum_k a(k,j) b(i,k)' - but when matrices are printed the results will look right. Just remember the indices are reversed. e.g.: $a = [ $b = [ [ 1 2 3 0] [1 1] [ 1 -1 2 7] [0 2] [ 1 0 0 1] [0 2] ] [1 1] ] gives $c = [ [ 1 11] [ 8 10] [ 2 2] ] Note: `transpose()|PDL::Basic::transpose' in this node does what it says and is a convenient way to turn row vectors into column vectors. It is bound to the unary operator '~' for convenience. How to write a simple function ------------------------------ sub dotproduct { my ($a,$b) = @_; return sum($a*$b) ; } 1; If put in file dotproduct.pdl would be autoloaded if you are using `PDL::AutoLoader|PDL::AutoLoader' in this node (see below). Of course, this function is already available as the `inner|PDL::Primitive' in this node function, see *Note PDL/Primitive: PDL/Primitive,. Type Conversion --------------- Default for pdl() is double. Conversions are: $a = float($b); $c = long($d); # "long" is generally a 4 byte int $d = byte($a); Also double(), short(), ushort(). These routines also automatically convert perl lists to allow the convenient shorthand: $a = byte [[1..10],[1..10]]; # Create 2D byte array $a = float [1..1000]; # Create 1D float array etc. Piddles and boolean expressions ------------------------------- Printing -------- Automatically expands array in N-dimensional format: print $a; $b = "Answer is = $a "; Sections -------- perlDL betrays its perl/C heritage in that arrays are zero-offset. Thus a 100x100 image has indices `0..99,0..99'. Furthermore [Which modules!?!], the convention is that the center of the pixel (0,0) IS at coordinate (0.0,0.0). Thus the above image ranges from `-0.5..99.5, -0.5..99.5' in real space. All perlDL graphics functions conform to this defintion and hide away the unit-offsetness of, for example, the PGPLOT FORTRAN library. Again following the usual convention coordinate (0,0) is displayed at the bottom left when displaying an image. It appears at the top left when using "`print $a'" etc. $b = $a->slice("$x1:$x2,$y1:$y1,$z1:$z2"); # Take subsection # Set part of $bigimage to values from $smallimage ($tmp = $bigimage->slice("$xa:$xb,$ya:$yb")) .= $smallimage; $newimage = ins($bigimage,$smallimage,$x,$y,$z...) # Insert at x,y,z $c = nelem ($a); # Number of pixels $val = at($object, $x,$y,$z...) # Pixel value at position $val = $object->at($x,$y,$z...) # equivalent set($myimage, $x, $y, ... $value) # Set value in image $b = xvals($a); # Fill array with X-coord values (also yvals(), zvals(), # axisvals($x,$axis) and rvals() for radial distance # from centre). Input/Output ------------ The `PDL::IO' modules implement several useful IO format functions. It would be too much to give examples of each so you are referred to the individual manpages for details. PDL::IO::Misc Ascii, FITS and FIGARO/NDF IO routines. PDL::IO::FastRaw Using the raw data types of your machine, an unportable but blindingly fast IO format. Also supports memory mapping to conserve memory as well as get more speed. PDL::IO::FlexRaw General raw data formats. PDL::IO::Browser A Curses browser for arrays. PDL::IO::Pnm Portaple bitmap and pixmap support. PDL::IO::Pic Using the previous module and netpbm, makes it possible to easily write GIF, jpeg and whatever with simple commands. Graphics -------- The philosophy behind perlDL is to make it work with a variety of existing graphics libraries since no single package will satisfy all needs and all people and this allows one to work with packages one already knows and likes. Obviously there will be some overlaps in functionality and some lack of consistency and uniformity. However this allows PDL to keep up with a rapidly developing field - the latest PDL modules provide interfaces to OpenGL and VRML graphics! PDL::Graphics::PGPLOT PGPLOT provdes a simple library for line graphics and image display. There is an easy interface to this in the internal module `PDL::Graphics::PGPLOT|PDL::Graphics::PGPLOT' in this node, which calls routines in the separately available PGPLOT top-level module. PDL::Graphics::IIS Many astronomers like to use SAOimage and Ximtool (or there derivations/clones). These are useful free widgets for inspection and visualisation of images. (They are not provided with perlDL but can easily be obtained from their official sites off the Net.) The `PDL::Graphics::IIS|PDL::Graphics::IIS' in this node package provides allows one to display images in these ("IIS" is the name of an ancient item of image display hardware whose protocols these tools conform to.) Karma The `PDL::Graphics::Karma|PDL::Graphics::Karma' in this node module provides an interface to the Karma visualisation suite. This is a set of GUI applications which are specially designed for visualising noisy 2D and 3D data sets. PDL::Graphics::TriD See `PDL::Graphics::TriD|PDL::Graphics::TriD' in this node (the name sucks...). this is a collection of 3D routines for OpenGL and (soon) VRML and other 3D formats which allow 3D point, line, and surface plots from PDL. Autoloading ----------- See *Note PDL/AutoLoader: PDL/AutoLoader,. This allows one to autoload functions on demand, in a way perhaps familiar to users of MatLab. One can also write PDL extensions as normal Perl modules. perldl shell ------------ The perl script `perldl' provides a simple command line - if the latest Readlines/ReadKey modules have beeen installed `perldl' detects this and enables command line recall and editing. See the manpage for details. e.g.: jhereg% perldl perlDL shell v1.30 PDL comes with ABSOLUTELY NO WARRANTY. For details, see the file 'COPYING' in the PDL distribution. This is free software and you are welcome to redistribute it under certain conditions, see the same file for details. ReadLines enabled Reading PDL/default.perldlrc... Found docs database /home/kgb/soft/dev/lib/perl5/site_perl/PDL/pdldoc.db Type 'help' for online help Type 'demo' for online demos Loaded PDL v2.005 perldl> $x = rfits 'm51.fits' BITPIX = 16 size = 65536 pixels Reading 131072 bytes BSCALE = 1.0000000000E0 && BZERO = 0.0000000000E0 perldl> imag $x Loaded PGPLOT Displaying 256 x 256 image from 24 to 500 ... You can also run it from the perl debugger (`perl -MPDL -d -e 1') if you want. Miscellaneous shell features: p The shell aliases p to be a convenient short form of print, e.g. perldl> p ones 5,3 [ [1 1 1 1 1] [1 1 1 1 1] [1 1 1 1 1] ] Initialization The files `~/.perldlrc' and `local.perldlrc' (in the current directory) are sourced if found. This allows the user to have global and local PDL code for startup. Help Type 'help'! One can search the PDL documentation, and look up documentation on any function. Escape Any line starting with the `#' character is treated as a shell escape. This character is configurable by setting the perl variable `$PERLDL_ESCAPE'. This could, for example, be set in `~/.perldlrc'. Overload operators ------------------ The following builtin perl operators and functions have been overloaded to work on PDL variables: + - * / > < >= <= << >> & | ^ == != <=> ** % ! ~ sin log abs atan2 sqrt cos exp [All the unary functions (sin etc.) may be used with inplace() - see "Memory" below.] Object-Orientation and perlDL ----------------------------- PDL operations are available as functions and methods. Thus one can derive new types of object, to represent custom data classes. By using overloading one can make mathematical operators do whatever you please, and PDL has some built-in tricks which allow existing PDL functions to work unchanged, even if the underlying data representation is vastly changed! See *Note PDL/Objects: PDL/Objects, Memory usage and references --------------------------- Messing around with really huge data arrays may require some care. perlDL provides many facilities to let you perform operations on big arrays without generating extra copies though this does require a bit more thought and care from the programmer. NOTE: On some most systems it is better to configure perl (during the build options) to use the system `malloc()' function rather than perl's built-in one. This is because perl's one is optimised for speed rather than consumption of virtual memory - this can result in a factor of two improvement in the amount of memory storage you can use. The Perl malloc in 5.004 and later does have a number of compile-time options you can use to tune the behaviour. Simple arithmetic If $a is a big image (e.g. occupying 10MB) then the command $a = $a + 1; eats up another 10MB of memory. This is because the expression `$a+1' creates a temporary copy of `$a' to hold the result, then `$a' is assigned a reference to that. After this, the original `$a' is destroyed so there is no *permanent* memory waste. But on a small machine, the growth in the memory footprint can be considerable. It is obviously done this way so `$c=$a+1' works as expected. Also if one says: $b = $a; # $b and $a now point to same data $a = $a + 1; Then $b and `$a' end up being different, as one naively expects, because a new reference is created and `$a' is assigned to it. However if `$a' was a huge memory hog (e.g. a 3D volume) creating a copy of it may not be a good thing. One can avoid this memory overhead in the above example by saying: $a++; The operations `++,+=,--,-=', etc. all call a special "in-place" version of the arithmetic subroutine. This means no more memory is needed - the downside of this is that if `$b=$a' then $b is also incremented. To force a copy explicitly: $b = pdl $a; # Real copy or, alternatively, perhaps better style: $b = $a->copy; Functions Most functions, e.g. `log()', return a result which is a transformation of their argument. This makes for good programming practice. However many operations can be done "in-place" and this may be required when large arrays are in use and memory is at a premium. For these circumstances the operator `inplace()|PDL::Core' in this node is provided which prevents the extra copy and allows the argument to be modified. e.g.: $x = log($array); # $array unaffected log( inplace($bigarray) ); # $bigarray changed in situ WARNINGS: 1. The usual caveats about duplicate references apply. 2. Obviously when used with some functions which can not be applied in situ (e.g. `convolve()') unexpected effects may occur! We try to indicate inplace()-safe functions in the documentation. 3. Type conversions, such as`float()', may cause hidden copying. Ensuring piddleness ------------------- If you have written a simple function and you don't want it to blow up in your face if you pass it a simple number rather than a PDL variable. Simply call the function `topdl()|PDL::Core' in this node first to make it safe. e.g.: sub myfiddle { my $pdl = topdl(shift); $pdl->fiddle_foo(...); ... } `topdl()' does NOT perform a copy if a pdl variable is passed - it just falls through - which is obviously the desired behaviour. The routine is not of course necessary in normal user defined functions which do not care about internals. AUTHOR ====== Copyright (C) Karl Glazebrook (kgb@aaoepp.aao.gov.au), Tuomas J. Lukka, (lukka@husc.harvard.edu) and Christian Soeller (c.soeller@auckland.ac.nz) 1997. Commercial reproduction of this documentation in a different format is forbidden.  File: pm.info, Node: PDL/Index, Next: PDL/Indexing, Prev: PDL/Impatient, Up: Module List an index of PDL documentation ***************************** NAME ==== PDL::Index - an index of PDL documentation DESCRIPTION =========== A meta document listing the documented PDL modules and the PDL manual dcouments PDL manuals =========== * `PDL::BadValues|PDL::BadValues' in this node - Discussion of bad value support in PDL * `PDL::Dataflow|PDL::Dataflow' in this node - description of the dataflow philosophy * `PDL::Delta|PDL::Delta' in this node - PDL changes between V1.0 and V2.0 * `PDL::FAQ|PDL::FAQ' in this node - Frequently asked questions about PDL * `PDL::Impatient|PDL::Impatient' in this node - PDL for the impatient (quick overview) * `PDL::Index|PDL::Index' in this node - an index of PDL documentation * `PDL::Indexing|PDL::Indexing' in this node - how to index piddles. * `PDL::Internals|PDL::Internals' in this node - description of the current internals * `PDL::Intro|PDL::Intro' in this node - Introduction to the Perl Data Language * `PDL::Objects|PDL::Objects' in this node - Object-Orientation, what is it and how to exploit it * `PDL::PP|PDL::PP' in this node - Generate PDL routines from concise descriptions * `PDL::Philosophy|PDL::Philosophy' in this node - what's behind PDL? * `PDL::Tips|PDL::Tips' in this node - Small tidbits of useful arcana. Programming tidbits and such. PDL modules =========== * `PDL::PDL|PDL::PDL' in this node - Main loader of PDL default modules * `PDL::Audio|PDL::Audio' in this node - Some PDL functions intended for audio processing. * `PDL::Audio::Pitches|PDL::Audio::Pitches' in this node - All the standard musical pitch names. * `PDL::Audio::Scales|PDL::Audio::Scales' in this node - Over 1200 musical scales in PDL format. * `PDL::AutoLoader|PDL::AutoLoader' in this node - MatLab style AutoLoader for PDL * `PDL::Bad|PDL::Bad' in this node - PDL does not process bad values * `PDL::Basic|PDL::Basic' in this node - Basic utility functions for PDL * `PDL::CallExt|PDL::CallExt' in this node - call functions in external shared libraries * `PDL::Char|PDL::Char' in this node - PDL subclass which allows reading and writing of fixed-length character strings as byte PDLs * `PDL::Complex|PDL::Complex' in this node - handle complex numbers * `PDL::Core|PDL::Core' in this node - fundamental PDL functionality * `PDL::Dbg|PDL::Dbg' in this node - functions to support debugging of PDL scripts * `PDL::Doc|PDL::Doc' in this node - support for PDL online documentation * `PDL::Doc::Perldl|PDL::Doc::Perldl' in this node - commands for accessing PDL doc database from 'perldl' shell * `PDL::Exporter|PDL::Exporter' in this node - PDL export control * `PDL::FFT|PDL::FFT' in this node - FFTs for PDL * `PDL::Filter::LinPred|PDL::Filter::LinPred' in this node - Linear predictive filtering * `PDL::Filter::Linear|PDL::Filter::Linear' in this node - linear filtering for PDL * `PDL::Fit::Gaussian|PDL::Fit::Gaussian' in this node - routines for fitting gaussians * `PDL::Fit::LM|PDL::Fit::LM' in this node - Levenber-Marquardt fitting routine for PDL * `PDL::Fit::Linfit|PDL::Fit::Linfit' in this node - routines for fitting data with linear combinations of functions. * `PDL::Fit::Polynomial|PDL::Fit::Polynomial' in this node - routines for fitting with polynomials * `PDL::Func|PDL::Func' in this node - useful functions * `PDL::Gaussian|PDL::Gaussian' in this node - Gaussian distributions. * `PDL::Graphics2D|PDL::Graphics2D' in this node - An object oriented interface to PDL graphics * `PDL::Graphics::IIS|PDL::Graphics::IIS' in this node - Display PDL images on IIS devices (saoimage/ximtool) * `PDL::Graphics::LUT|PDL::Graphics::LUT' in this node - provides access to a number of look-up tables * `PDL::Graphics::OpenGLQ|PDL::Graphics::OpenGLQ' in this node - quick routines to plot lots of stuff from piddles. * `PDL::Graphics::PGPLOT|PDL::Graphics::PGPLOT' in this node - PGPLOT enhanced interface for PDL * `PDL::Graphics::PGPLOT::Window|PDL::Graphics::PGPLOT::Window' in this node - A OO interface to PGPLOT windows * `PDL::Graphics::PGPLOTOptions|PDL::Graphics::PGPLOTOptions' in this node - Setting PGPLOT options * `PDL::Graphics::TriD|PDL::Graphics::TriD' in this node - PDL 3D interface * `PDL::Graphics::TriD::ButtonControl|PDL::Graphics::TriD::ButtonControl' in this node - default event handler subroutines * `PDL::Graphics::TriD::Contours|PDL::Graphics::TriD::Contours' in this node - 3D Surface contours for TriD * `PDL::Graphics::TriD::Labels|PDL::Graphics::TriD::Labels' in this node - Text tools * `PDL::Graphics::TriD::MathGraph|PDL::Graphics::TriD::MathGraph' in this node - Mathematical Graph objects for PDL * `PDL::Graphics::TriD::Rout|PDL::Graphics::TriD::Rout' in this node - Helper routines for Three-dimensional graphics * `PDL::Graphics::TriD::Tk|PDL::Graphics::TriD::Tk' in this node - Tk windows / widgets / menus for TriD. * `PDL::Graphics::TriD::VRML|PDL::Graphics::TriD::VRML' in this node - TriD VRML backend * `PDL::IO::Browser|PDL::IO::Browser' in this node - 2D data browser for PDL * `PDL::IO::FastRaw|PDL::IO::FastRaw' in this node - A simple, fast and convenient io format for PerlDL. * `PDL::IO::FlexRaw|PDL::IO::FlexRaw' in this node - A flexible binary i/o format for PerlDL. * `PDL::IO::Grib|PDL::IO::Grib' in this node - Grib file utilities for perl * `PDL::IO::Grib::Field|PDL::IO::Grib::Field' in this node - Field tools for Grib files * `PDL::IO::Grib::Wgrib|PDL::IO::Grib::Wgrib' in this node - shamelessly stolen code * `PDL::IO::Misc|PDL::IO::Misc' in this node - misc IO routines for PDL * `PDL::IO::NDF|PDL::IO::NDF' in this node - PDL Module for reading and writing Starlink * `PDL::IO::Pic|PDL::IO::Pic' in this node - image I/O for PDL * `PDL::IO::Pnm|PDL::IO::Pnm' in this node - pnm format I/O for PDL * `PDL::Image2D|PDL::Image2D' in this node - Miscellaneous 2D image processing functions * `PDL::ImageND|PDL::ImageND' in this node - useful image processing routines which work in N-dimensions * `PDL::ImageRGB|PDL::ImageRGB' in this node - some utility functions for RGB image data handling * `PDL::Lite|PDL::Lite' in this node - minimum PDL module OO loader * `PDL::LiteF|PDL::LiteF' in this node - minimum PDL module function loader * `PDL::Math|PDL::Math' in this node - extended mathematical operations and special functions * `PDL::Ops|PDL::Ops' in this node - Fundamental mathematical operators * `PDL::Opt::Simplex|PDL::Opt::Simplex' in this node - Simplex optimization routines * `PDL::Options|PDL::Options' in this node - simplifies option passing by hash in PerlDL * `PDL::Pod::Html|PDL::Pod::Html' in this node - module to convert pod files to HTML * `PDL::Primitive|PDL::Primitive' in this node - primitive operations for pdl * `PDL::Reduce|PDL::Reduce' in this node - a reduce function for PDL * `PDL::Slatec|PDL::Slatec' in this node - PDL interface to the slatec numerical programming library * `PDL::Slices|PDL::Slices' in this node - Stupid index tricks * `PDL::Tests|PDL::Tests' in this node - tests for some PP features * `PDL::Types|PDL::Types' in this node - define fundamental PDL Datatypes * `PDL::Ufunc|PDL::Ufunc' in this node - primitive ufunc operations for pdl HISTORY ======= Automatically generated by scantree.pl for PDL version 2.1.1.