This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: PDL/Graphics/PGPLOTOptions, Next: PDL/Graphics/TriD, Prev: PDL/Graphics/PGPLOT/Window, Up: Module List Setting PGPLOT options ********************** NAME ==== PDL::Graphics::PGPLOTOptions - Setting PGPLOT options SYNOPSIS ======== use PGPLOTOptions qw('default_options'); DESCRIPTION =========== This package contains one function (at present) which returns PDL::Option objects for default settings for plot windows and plot commands. This should be complemented by functions that could affect this such as file reading commands etc. OPTIONS ======= The following is a listing of options that are set in this file and what they do and what their default value is Window specfic options ---------------------- These options modify the appearance of windows and can also modify the default settings for creation of plot axes etc. Device The default PGPLOT device to use. The default value is set to the PGPLOT_DEV environment variable if set, otherwise to '?'. AxisColour The colour with which to draw axes HardLW, HardCH, HardFont, HardAxisColour The linewidth, character height, font and axis colour to use on hardcopy devices. Axis The axis style to use. See the *Note PDL/Graphics/PGPLOT/Window: PDL/Graphics/PGPLOT/Window, documentation for details. It defaults to 'Normal' which is a labelled box. Valid arguments are 'Empty', 'Box', 'Normal', 'Axes', 'Grid', 'LogX', 'LogY', 'LogXY'. AspectRatio The aspect ratio of the output device it defaults to 0.618. WindowWidth The width of the output window in inches and defaults to as big as possible. WindowXSize and WindowYSize These are alternatives to AspectRatio and WindowWidth. WindowName The name of the window - can later be retrieved using name(). It defaults to 'Window'+Window ID. NXPanel The number of panels in the X-direction - defaults to 1 NYPanel The number of panels in the Y-direction - defaults to 1 Justify A boolean value which, if true, causes both axes to drawn to the same scale; see the PGPLOT `pgenv()' command for more information. Border Adjust the spacing around the plot. See the documentation in *Note PDL/Graphics/PGPLOT/Window: PDL/Graphics/PGPLOT/Window, for details. CharSize The default charsize for the plot - used when annotating the axes for instance. PlotPosition The position of the plot in normalised coordinates. NoErase Allows plotting multiple panels on one plot, normally used with 'PlotPosition'. Plot specific options --------------------- For the moment see the `PDL::Graphics::PGPLOT::Window' documentation for these.  File: pm.info, Node: PDL/Graphics/TriD, Next: PDL/Graphics/TriD/ButtonControl, Prev: PDL/Graphics/PGPLOTOptions, Up: Module List PDL 3D interface **************** NAME ==== PDL::Graphics::TriD - PDL 3D interface SYNOPSIS ======== use PDL::Graphics::TriD; # After each graph, let the user rotate is and # wait for him to press 'q', then make new graph line3d($coords); # $coords = (3,n,...) line3d($coords,$colors); # $colors = (3,n,...) line3d([$x,$y,$z]); imagrgb([$r,$g,$b]); lattice3d([$x,$y,$z]); # 2-d piddles points3d([$x,$y,$z]); hold3d(); # the following graphs are on top of each other and the previous line3d([$x,$y,$z]); line3d([$x,$y,$z+1]); $pic = grabpic3d(); # Returns the picture in a (3,$x,$y) float piddle (0..1). release3d(); # the next graph will again wipe out things. WARNING ======= These modules are still in a somewhat unfocused state: don't use them yet if you don't know how to make them work if they happen to do something strange. DESCRIPTION =========== This module implements a generic 3D plotting interface for PDL. Points, lines and surfaces (among other objects) are supported. With OpenGL, it is easy to manipulate the resulting 3D objects with the mouse in real time - this helps data visualization a lot. With VRML, you can generate objects for everyone to see with e.g. Silicon Graphics' Cosmo Player. You can find out more about VRML at `http://vrml.sgi.com/' or `http://www.vrml.org/' SELECTING A DEVICE ================== The default device for TriD is currently OpenGL. You can specify a different device either in your program or in the environment variable `PDL_3D_DEVICE'. The one specified in the program takes priority. The currently available devices are GL OpenGL GLpic OpenGL but off-line (pixmap) rendering and writing to a graphics file. VRML VRML objects rendering. This writes a VRML file describing the scene. This VRML file can then be read with a browser. ONLINE AND OFFLINE VISUALIZATION ================================ TriD offers both on- and off-line visualization. Currently the interface w.r.t. this division is still much in motion. For OpenGL you can select either on- or off-line rendering. VRML is currently always offline (this may change later, if someone bothers to write the java(script) code to contact PDL and wait for the next PDL image over the network. COORDINATE SPECIFICATIONS ========================= Specifying a set of coordinates is generally a context-dependent operation. For a traditional 3D surface plot, you'll want two of the coordinates to have just the xvals and yvals of the piddle, respectively. For a line, you would generally want to have one coordinate held at zero and the other advancing. This module tries to make a reasonable way of specifying the context while letting you do whatever you want by overriding the default interpretation. The alternative syntaxes for specifying a set of coordinates (or colors) are $piddle # MUST have 3 as first dim. [$piddle] [$piddle1,$piddle2] [$piddle1,$piddle2,$piddle3] [CONTEXT,$piddle] [CONTEXT,$piddle1,$piddle2] [CONTEXT,$piddle1,$piddle2,$piddle3] where CONTEXT is a string describing in which context you wish these piddles to be interpreted. Each routine specifies a default context which is explained in the routines documentation. Context is usually used only to understand what the user wants when he/she specifies less than 3 piddles. The following contexts are currently supported: SURF2D A 2-D lattice. [$piddle] is interpreted as the Z coordinate over a lattice over the first dimension. Equivalent to [$piddle->xvals, $piddle->yvals, $piddle]. POLAR2D A 2-D polar coordinate system. [$piddle] is interpreted as the z coordinate over theta and r (theta = the first dimension of the piddle). COLOR A set of colors. [$piddle] is interpreted as grayscale color (equivalent to [$piddle,$piddle,$piddle]). LINE A line made of 1 or 2 coordinates. [$piddle] is interpreted as [$piddle->xvals,$piddle,0]. [$piddle1,$piddle2] is interpreted as [$piddle1,$piddle2,$piddle1->xvals]. What makes contexts useful is that if you want to plot points instead of the full surface you plotted with imag3d([$zcoords]); you don't need to start thinking about where to plot the points: points3d([SURF2D,$zcoords]); will do exactly the same. SIMPLE ROUTINES =============== Because using the whole object-oriented interface for doing all your work might be cumbersome, the following shortcut routines are supported: FUNCTIONS ========= line3d ------ perldl> line3d [sqrt(rvals(zeroes(50,50))/2)] - Lines on surface perldl> line3d [$x,$y,$z] - Lines over X, Y, Z perldl> line3d $coords - Lines over the 3D coordinates in $coords. Note: line plots differ from mesh plots in that lines only go in one direction. If this is unclear try both! See module documentation for more information on contexts and options imag3d ------ perldl> imag3d [sqrt(rvals(zeroes(50,50))/2)], {{Lines=>0}; - Rendered image of surface See module documentation for more information on contexts and options mesh3d ------ perldl> mesh3d [sqrt(rvals(zeroes(50,50))/2)] - mesh of surface Note: a mesh is defined by two sets of lines at right-angles (i.e. this is how is differs from line3d). See module documentation for more information on contexts and options lattice3d --------- points3d -------- perldl> points3d [sqrt(rvals(zeroes(50,50))/2)]; - points on surface See module documentation for more information on contexts and options imagrgb ------- This would be used to plot an image, specifying red, green and blue values at each point. Note: contexts are very useful here as there are many ways one might want to do this. perldl> $a=sqrt(rvals(zeroes(50,50))/2) perldl> imagrgb [0.5*sin(8*$a)+0.5,0.5*cos(8*$a)+0.5,0.5*cos(4*$a)+0.5] imagrgb3d --------- The piddle gives the colors. The option allowed is Points, which should give 4 3D coordinates for the corners of the polygon, either as a piddle or as array ref. The default is [[0,0,0],[1,0,0],[1,1,0],[0,1,0]]. perldl> imagrgb3d $colors, {Points => [[0,0,0],[1,0,0],[1,0,1],[0,0,1]]}; - plot on XZ plane instead of XY. grabpic3d --------- The returned piddle has dimensions (3,$x,$y) and is of type float (currently). XXX This should be altered later. hold3d, release3d ----------------- or hold3d(1); hold3d(0); keeptwiddling3d, nokeeptwiddling3d ---------------------------------- Usually, when showing 3D images, the user is given a chance to rotate it and then press 'q' for the next image. However, sometimes (for e.g. animation) this is undesirable and it is more desirable to just run one step of the event loop at a time. or keeptwiddling3d(1); keeptwiddling3d(0); When an image is added to the screen, keep twiddling it until user explicitly presses 'q'. twiddle3d --------- Let the user rotate the image in 3D space, either for one step or until (s)he presses 'q', depending on the 'keeptwiddling3d' setting. If 'keeptwiddling3d' is not set the routine returns immediately and indicates that a 'q' event was received by returning 1. If the only events received were mouse events, returns 0. CONCEPTS ======== The key concepts (object types) of TriD are explained in the following: Object ------ In this 3D abstraction, everything that you can "draw" without using indices is an Object. That is, if you have a surface, each vertex is not an object and neither is each segment of a long curve. The whole curve (or a set of curves) is the lowest level Object. Transformations and groups of Objects are also Objects. A Window is simply an Object that has subobjects. Twiddling --------- Because there is no eventloop in Perl yet and because it would be hassleful to do otherwise, it is currently not possible to e.g. rotate objects with your mouse when the console is expecting input or the program is doing other things. Therefore, you need to explicitly say "$window->twiddle()" in order to display anything. OBJECTS ======= The following types of objects are currently supported. Those that do not have a calling sequence described here should have their own manual pages. There are objects that are not mentioned here; they are either internal to PDL3D or in rapidly changing states. If you use them, you do so at your own risk. The syntax PDL::Graphics::TriD::Scale(x,y,z) here means that you create an object like $a = new PDL::Graphics::TriD::Scale($x,$y,$z); PDL::Graphics::TriD::LineStrip ------------------------------ This is just a line or a set of lines. The arguments are 3 1-or-more-D piddles which describe the vertices of a continuous line and an optional color piddle (which is 1-D also and simply defines the color between red and blue. This will probably change). PDL::Graphics::TriD::Lines -------------------------- This is just a line or a set of lines. The arguments are 3 1-or-more-D piddles where each contiguous pair of vertices describe a line segment and an optional color piddle (which is 1-D also and simply defines the color between red and blue. This will probably change). PDL::Graphics::TriD::Image -------------------------- This is a 2-dimensional RGB image consisting of colored rectangles. With OpenGL, this is implemented by texturing so this should be relatively memory and execution-time-friendly. PDL::Graphics::TriD::Lattice ---------------------------- This is a 2-D set of points connected by lines in 3-space. The constructor takes as arguments 3 2-dimensional piddles. PDL::Graphics::TriD::Points --------------------------- This is simply a set of points in 3-space. Takes as arguments the x, y and z coordinates of the points as piddles. PDL::Graphics::TriD::Scale(x,y,z) --------------------------------- Self-explanatory PDL::Graphics::TriD::Translation(x,y,z) --------------------------------------- Ditto PDL::Graphics::TriD::Quaternion(c,x,y,z) ---------------------------------------- One way of representing rotations is with quaternions. See the appropriate man page. PDL::Graphics::TriD::ViewPort ----------------------------- This is a special class: in order to obtain a new viewport, you need to have an earlier viewport on hand. The usage is: $new_vp = $old_vp->new_viewport($x0,$y0,$x1,$y1); where $x0 etc are the coordinates of the upper left and lower right corners of the new viewport inside the previous (relative to the previous viewport in the (0,1) range. Every implementation-level window object should implement the new_viewport method. BUGS ==== Not enough is there yet. AUTHOR ====== Copyright (C) 1997 Tuomas J. Lukka (lukka@husc.harvard.edu). Documentation contributions from 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/Graphics/TriD/ButtonControl, Next: PDL/Graphics/TriD/Contours, Prev: PDL/Graphics/TriD, Up: Module List default event handler subroutines ********************************* NAME ==== PDL::Graphics::TriD::ButtonControl - default event handler subroutines FUNCTIONS ========= new() ----- mouse_moved ----------- sub mouse_moved{ print "mouse_moved @_\n" if $PDL::Graphics::TriD::verbose; } ButtonRelease ------------- sub ButtonRelease{ my ($this,$x,$y) = @_; $this->{Win}{Active} = 0; print "ButtonRelease @_\n" if $PDL::Graphics::TriD::verbose; } ButtonPressed ------------- set_wh ------  File: pm.info, Node: PDL/Graphics/TriD/Contours, Next: PDL/Graphics/TriD/Geomview, Prev: PDL/Graphics/TriD/ButtonControl, Up: Module List 3D Surface contours for TriD **************************** NAME ==== PDL::Graphics::TriD::Contours - 3D Surface contours for TriD SYNOPSIS ======== use PDL::Graphics::TriD; use PDL::Graphics::TriD::Contours; $size = 25; $x = (xvals zeroes $size,$size) / $size; $y = (yvals zeroes $size,$size) / $size; $z = (sin($x*6.3) * sin($y*6.3)) ** 3; $data=new PDL::Graphics::TriD::Contours($z, [$z->xvals/$size,$z->yvals/$size,0]); PDL::Graphics::TriD::graph_object($data) FUNCTIONS ========= new() ----- where $d is a 2D pdl of data to be contoured. [$x,$y,$z] define a 3D map of $d into the visualization space [$r,$g,$b] is an optional [3,1] piddle specifing the contour color and $options is a hash reference to a list of options documented below. Contours can also be colored by value using the set_color_table function. If ContourVals is specified ContourInt, ContourMin, and ContourMax are ignored. If no options are specified, the algorthym tries to choose values based on the data supplied. Font can also be specified or overwritten by the addlabels() function below. addlabels() ----------- $labelint is the integer interval between labeled contours. If you have 8 countour levels and specify $labelint=3 addlabels will attempt to label the 1st, 4th, and 7th contours. $labelint defaults to 1. $segint specifies the density of labels on a single contour level. Each contour level consists of a number of connected line segments, $segint defines how many of these segments get labels. $segint defaults to 5, that is every fifth line segment will be labeled. set_colortable($table) ---------------------- coldhot_colortable() --------------------  File: pm.info, Node: PDL/Graphics/TriD/Geomview, Next: PDL/Graphics/TriD/Labels, Prev: PDL/Graphics/TriD/Contours, Up: Module List  File: pm.info, Node: PDL/Graphics/TriD/Labels, Next: PDL/Graphics/TriD/MathGraph, Prev: PDL/Graphics/TriD/Geomview, Up: Module List Text tools ********** NAME ==== PDL::Graphics::TriD::Labels - Text tools SYNOPSIS ======== my $l = new PDL::Graphics::TriD::Labels($lablepoints, {Strings=>$strlist ,Font=>$font}); WARNING ======= This module is experimental and the interface will probably change. DESCRIPTION =========== This module is used to write Labels on the graphs of TriD AUTHOR ====== Copyright (C) 1997 Tuomas J. Lukka (lukka@husc.harvard.edu). 2000 James P. Edwards (jedwards@inmet.gov.br) 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/TriD/MathGraph, Next: PDL/Graphics/TriD/Objects, Prev: PDL/Graphics/TriD/Labels, Up: Module List Mathematical Graph objects for PDL ********************************** NAME ==== PDL::Graphics::TriD::MathGraph - Mathematical Graph objects for PDL SYNOPSIS ======== see the file Demos/TriD/tmathgraph.p in the PDL distribution. WARNING ======= This module is experimental and the interface will probably change. DESCRIPTION =========== This module exists for plotting mathematical graphs (consisting of nodes and arcs between them) in 3D and optimizing the placement of the nodes so that the graph is visualizable in a clear way. AUTHOR ====== Copyright (C) 1997 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/Graphics/TriD/Objects, Next: PDL/Graphics/TriD/Rout, Prev: PDL/Graphics/TriD/MathGraph, Up: Module List Simple Graph Objects for TriD ***************************** NAME ==== PDL::Graphics::TriD::Objects - Simple Graph Objects for TriD SYNOPSIS ======== Look in PDL/Demos/TkTriD_demo.pm for several examples, the code in PDL/Demos/TriD1.pm and PDL/Demos/TriD2.pm also uses objects but it hides them from the user. DESCRIPTION =========== GObjects can be either stand-alone or in Graphs, scaled properly. All the points used by the object must be in the member {Points}. I guess we can afford to force data to be copied (X,Y,Z) -> (Points)... OBJECTS ======= PDL::Graphics::TriD::GObject ---------------------------- Inherits from base PDL::Graphics::TriD::Object and adds fields Points, Colors and Options. Need lots more here...  File: pm.info, Node: PDL/Graphics/TriD/Rout, Next: PDL/Graphics/TriD/Tk, Prev: PDL/Graphics/TriD/Objects, Up: Module List Helper routines for Three-dimensional graphics ********************************************** NAME ==== PDL::Graphics::TriD::Rout - Helper routines for Three-dimensional graphics DESCRIPTION =========== This module is for miscellaneous PP-defined utility routines for the PDL::Graphics::TriD module. Currently, there are FUNCTIONS ========= combcoords ---------- Combine x, y and z to a single piddle the first dimension of which is 3. This routine does dataflow automatically. repulse ------- repulse uses a hash table of cubes to quickly calculate a repulsive force that vanishes at infinity for many objects. For use by the module `PDL::Graphics::TriD::MathGraph|PDL::Graphics::TriD::MathGraph' in this node. For definition of the potential, see the actual function. attract ------- attract is used to calculate an attractive force for many objects, of which some attract each other (in a way like molecular bonds). For use by the module `PDL::Graphics::TriD::MathGraph|PDL::Graphics::TriD::MathGraph' in this node. For definition of the potential, see the actual function. vrmlcoordsvert -------------- contour_segments ---------------- $c is a contour value (or a list of contour values) $data is an [m,n] array of values at each point `$points' is a list of [3,m,n] points, it should be a grid monotonically increasing with m and n. contour_segments returns a reference to a Perl array of line segments associated with each value of $c. It does not (yet) handle missing data values. Algorthym The data array represents samples of some field observed on the surface described by points. For each contour value we look for intersections on the line segments joining points of the data. When an intersection is found we look to the adjoining line segments for the other end(s) of the line segment(s). So suppose we find an intersection on an x-segment. We first look down to the left y-segment, then to the right y-segment and finally across to the next x-segment. Once we find one in a box (two on a point) we can quit because there can only be one. After we are done with a given x-segment, we look to the leftover possibilities for the adjoining y-segment. Thus the contours are built as a collection of line segments rather than a set of closed polygons. AUTHOR ====== Copyright (C) 2000 James P. Edwards Copyright (C) 1997 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/TriD/Tk, Next: PDL/Graphics/TriD/VRML, Prev: PDL/Graphics/TriD/Rout, Up: Module List A Tk widget interface to the PDL::Graphics::TriD. ************************************************* NAME ==== PDL::Graphics::TriD::Tk - A Tk widget interface to the PDL::Graphics::TriD. SYNOPSIS ======== my $MW = MainWindow->new(); my $TriDW = $MW->Tk( )->pack(-expand=>1, -fill=>'both'); $TriDW->MainLoop; DESCRIPTION =========== The widget is composed of a Frame and the Display device of the TriD output. It inherits all of the attributes of a Tk Frame. All of the events associated with this window are handled through Tk with the exception of the event which must be handled by TriD because the Frame is never exposed. Default Mouse bindings, defined for button1 and button3, control TriD object orientation and size respectively. FUNCTIONS ========= Populate -------- MainLoop -------- GLinit ------ refresh ------- AUTOLOAD -------- buttonmotion ------------ Author ====== *James P. Edwards, Instituto Nacional de Meteorologia Brasil* jedwards@inmet.gov.br  File: pm.info, Node: PDL/Graphics/TriD/VRML, Next: PDL/IO/Browser, Prev: PDL/Graphics/TriD/Tk, Up: Module List TriD VRML backend ***************** NAME ==== PDL::Graphics::TriD::VRML - TriD VRML backend SYNOPSIS ======== BEGIN { $PDL::Graphics::TriD::device = "VRML"; } use PDL::Graphics::TriD; use PDL::LiteF; # set some vrml parameters my $set = tridsettings(); # get the defaults $set->browser_com('netscape/unix'); $set->compress(); $set->file('/www-serv/vrml/dynamic_scene.wrl.gz'); line3d([$x,$y,$z]); # plot some lines and view the scene with a browser DESCRIPTION =========== This module implements the VRML for PDL::Graphics::TriD (the generic 3D plotting interface for PDL). You can use this backend either (a) for generating 3D graphics on your machine which can be directly viewed with a VRML browser or (b) generate dynamic VRML worlds to distribute over the web. With VRML, you can generate objects for everyone to see with e.g. Silicon Graphics' Cosmo Player. You can find out more about VRML at `http://vrml.sgi.com/' or `http://www.vrml.org/' BUGS ==== Probably incomplete/buggy implementation of some TriD features. AUTHOR ====== Copyright (C) 1997, 1998 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/IO/Browser, Next: PDL/IO/FastRaw, Prev: PDL/Graphics/TriD/VRML, Up: Module List 2D data browser for PDL *********************** NAME ==== PDL::IO::Browser - 2D data browser for PDL DESCRIPTION =========== cursor terminal browser for piddles. SYNOPSIS ======== use PDL::IO::Browser; FUNCTIONS ========= browse ------ browse ------ This uses the CURSES library to allow one to scroll around a PDL array using the cursor keys. AUTHOR ====== Copyright (C) Robin Williams 1997 (rjrw@ast.leeds.ac.uk). 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/FastRaw, Next: PDL/IO/FlexRaw, Prev: PDL/IO/Browser, Up: Module List A simple, fast and convenient io format for PerlDL. *************************************************** NAME ==== PDL::IO::FastRaw - A simple, fast and convenient io format for PerlDL. SYNOPSIS ======== use PDL; use PDL::IO::FastRaw; writefraw($pdl,"fname"); # write a raw file $pdl2 = readfraw("fname"); # read a raw file $pdl2 = PDL->readfraw("fname"); $pdl3 = mapfraw("fname2",{ReadOnly => 1}); # mmap a file, don't read yet $pdl4 = maptextfraw("fname3",{...}); # map a text file into a 1-D pdl. DESCRIPTION =========== This is a very simple and fast io format for PerlDL. The disk data consists of two files, a header metadata file in ASCII and a binary file consisting simply of consecutive bytes, shorts or whatever. It is hoped that this will not only make for a simple PerlDL module for saving and retrieving these files but also make it easy for other programs to use these files. The format of the ASCII header is simply ... The binary files are in general NOT interchangeable between different architectures since the binary file is simply dumped from the memory region of the piddle. This is what makes the approach efficient. It is also possible to mmap the file which can give a large speedup in certain situations as well as save a lot of memory by using a disk file as virtual memory. When a file is mapped, parts of it are read only as they are accessed in the memory (or as the kernel decides: if you are reading the pages in order, it may well preread some for you). Note that memory savings and copy-on-write are operating-system dependent - see Core.xs and your operating system documentation for exact semantics of whatever. Basically, if you write to a mmapped file without ReadOnly, the change will be reflected in the file immediately. ReadOnly doesn't really make it impossible to write to the piddle but maps the memory privately so the file will not be changed when you change the piddle. Be aware though that mmapping a 40Mb file without ReadOnly spends no virtual memory but with ReadOnly it does reserve 40Mb. FUNCTIONS ========= readfraw -------- writefraw --------- mapfraw ------- Dims, Datatype If creating a new file or if you want to specify your own header data for the file, you can give an array reference and a scalar, respectively. Creat Create the file. Also writes out a header for the file. Trunc Set the file size. Automatically enabled with Creat. NOTE: This also clears the file to all zeroes. ReadOnly Disallow writing to the file. maptextfraw ----------- Note that this function maps the raw format so if you are using an operating system which does strange things to e.g. line delimiters upon reading a text file, you get the raw (binary) representation. The file doesn't really need to be text but it is just mapped as one large binary chunk. This function is just a convenience wrapper which firsts stats the file and sets the dimensions and datatype. BUGS ==== Should be documented better. writefraw and readfraw should also have options (the author nowadays only uses mapfraw ;) 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/IO/FlexRaw, Next: PDL/IO/Grib, Prev: PDL/IO/FastRaw, Up: Module List A flexible binary i/o format for PerlDL. **************************************** NAME ==== PDL::IO::FlexRaw - A flexible binary i/o format for PerlDL. SYNOPSIS ======== use PDL; use PDL::IO::FlexRaw; ($x,$y,...) = readflex("filename" [, $hdr]) ($x,$y,...) = mapflex("filename" [, $hdr] [, $opts]) $hdr = writeflex($file, $pdl1, $pdl2,...) writeflexhdr($file, $hdr) DESCRIPTION =========== FlexRaw is a generic method for the input and output of `raw' data arrays. In particular, it is designed to read output from FORTRAN 77 UNFORMATTED files and the low-level C write function, even if the files are compressed or gzipped. As in FastRaw, the data file is supplemented by a header file (although this can be replaced by the optional `$hdr' argument). More information can be included in the header file than for FastRaw - the description can be extended to several data objects within a single input file. For example, to read the output of a FORTRAN program real*4 a(4,600,600) open (8,file='banana',status='new',form='unformatted') write (8) a close (8) the header file (`banana.hdr') could look like # FlexRaw file header # Header word for F77 form=unformatted Byte 1 4 # Data Float 3 # this is ignored 4 600 600 Byte 1 4 As is this, as we've got all dims The data can then be input using $a = (readflex('banana'))[1]; The format of the hdr file is an extension of that used by FastRaw. Comment lines (starting with #) are allowed, as are descriptive names (as elsewhere: byte, short, ushort, long, float, double) for the data types - note that case is ignored by FlexRaw. After the type, one integer specifies the number of dimensions of the data `chunk', and subsequent integers the size of each dimension. So the specifier above (`Float 3 4 600 600') describes our FORTRAN array. A scalar can be described as `float 0' (or `float 1 1', or `float 2 1 1', etc.). When all the dimensions are read - or a # appears after whitespace - the rest of the current input line is ignored. What about the extra 4 bytes at the head and tail, which we just threw away? These are added by FORTRAN (at least on Suns, Alphas and Linux), and specify the number of bytes written by each WRITE - the same number is put at the start and the end of each chunk of data. You may need to know all this in some cases. In general, FlexRaw tries to handle it itself, if you simply add a line saying `f77' to the header file, before any data specifiers: # FlexRaw file header for F77 form=unformatted F77 # Data Float 3 4 600 600 - the redundancy in FORTRAN data files even allows FlexRaw to automatically deal with files written on other machines which use back-to-front byte ordering. This won't always work - it's a 1 in 4 billion chance it won't, even if you regularly read 4Gb files! Also, it currently doesn't work for compressed files, so you can say `swap' (again before any data specifiers) to make certain the byte order is swapped. The optional `$hdr' argument allows the use of an anonymous array to give header information, rather than using a .hdr file. For example, $header = [ {Type => 'f77'}, {Type => 'float', NDims => 3, Dims => [ 4,600,600 ] } ]; @a = readflex('banana',$header); reads our example file again. As a special case, when NDims is 1, Dims may be given as a scalar. Within PDL, readflex and writeflex can be used to write several pdls to a single file - e.g. use PDL; use PDL::IO::FastRaw; @pdls = ($pdl1, $pdl2, ...); $hdr = writeflex("fname",@pdls); @pdl2 = readflex("fname",$hdr); writeflexhdr("fname",$hdr); @pdl3 = readflex("fname"); - writeflex produces the data file and returns the file header as an anonymous hash, which can be written to a .hdr file using writeflexhdr. The reading of compressed data is switched on automatically if the filename requested ends in .gz or .Z, or if the originally specified filename does not exist, but one of these compressed forms does. Mapflex memory maps, rather than reads, the data files. Its interface is similar to `readflex'. Extra options specify if the data is to be loaded `ReadOnly', if the data file is to be `Creat'-ed anew on the basis of the header information or `Trunc'-ated to the length of the data read. The extra speed of access brings with it some limitations: mapflex won't read compressed data, auto-detect f77 files or read f77 files written by more than a single unformatted write statement. More seriously, data alignment constraints mean that mapflex cannot read some files, depending on the requirements of the host OS (it may also vary depending on the setting of the `uac' flag on any given machine). You may have run into similar problems with common blocks in FORTRAN. For instance, floating point numbers may have to align on 4 byte boundaries - if the data file consists of 3 bytes then a float, it cannot be read. Mapflex will warn about this problem when it occurs, and return the PDLs mapped before the problem arose. This can be dealt with either by reorganizing the data file (large types first helps, as a rule-of-thumb), or more simply by using `readflex'. BUGS ==== The test on two dimensional byte arrays fail using g77 2.7.2, but not Sun f77. I hope this isn't my problem! Assumes gzip is on the PATH. Can't auto-swap compressed files, because it can't seek on them. The header format may not agree with that used elsewhere. Should it handle handles? Mapflex should warn and fallback to reading on SEGV? Would have to make sure that the data was written back after it was `destroyed'. FUNCTIONS ========= readflex -------- writeflex --------- mapflex ------- AUTHOR ====== Copyright (C) Robin Williams 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/IO/Grib, Next: PDL/IO/Grib/Field, Prev: PDL/IO/FlexRaw, Up: Module List Grib file utilities for perl **************************** NAME ==== PDL::IO::Grib - Grib file utilities for perl SYNOPSIS ======== use PDL; use PDL::IO::Grib; $gh = new PDL::IO::Grib; $gh->readgrib("filename"); $gh->getfield("fieldname"); DESCRIPTION =========== Grib.pm allows the user to read files in the grib FORM FM 92-IX Ext. GRIB Edition 1 - it may not read all possible grib format combinations. The Grib format has 4 sections (PDS, GDS, BMS, BDS), two of which (GDS, BMS) are optional. Each field of a section is described in the definition by an offset in bytes from the beginning of the section and a length. The contents of each field can vary widely according to the center of origin of the data. This decoder reads the entire section into a PDL and only decodes fields on request, it has a default decoding method and allows the user to define methods not known to this decoder. So for example, the first 3 bytes of the PDS section describes the length of that section, each of the next 10 bytes can be decoded as unsigned integers. Bytes 11 and 12 may be two seperate integers or one two-byte integer depending on the value of byte 10. It gets worse from there... FUNCTIONS ========= new --- Grib::readgrib -------------- Grib::getfield -------------- Grib::showinventory ------------------- get_grib1_date() ---------------- anyfield -------- .gribtables =========== The .gribtables file is searched for first in the working directory then in the user's home directory. The format is rather simple - anything following a *#* sign is a comment otherwise a name:pds[9]:pds[4]:pds[10]:pds[11]:pds[12] is expected where name can be anything as long as it begins with an alpha character and does not containb{:} and the pds[#] refers to the octet number in the pds sector of the grib file. Fields 11 and 12 are optional in the file and if not found all of the records which match fields 9 4 10 will be combined into a single 3d dataset by getfield So suppose the file .gribtables contains the entry T_PG:11:2:100 to specify 3d temperature on a pressure grid, then to get the 500mb pressure you would do $t500 = $gh->getfield ("T_PG:500"); Author ====== Jim Edwards  File: pm.info, Node: PDL/IO/Grib/Field, Next: PDL/IO/Grib/Wgrib, Prev: PDL/IO/Grib, Up: Module List Field tools for Grib files ************************** NAME ==== PDL::IO::Grib::Field - Field tools for Grib files SYNOPSIS ======== use PDL; use PDL::IO::Grib; $gh = new PDL::IO::Grib; $gh->readgrib("filename"); $gh->getfield("fieldname"); $f = $gh->anyfield(); DESCRIPTION =========== Field.pm gives you access to the individual fields of a Grib file. Here is the code that attempts to decipher each of the sections associated with the format. All of the data is read into PDLs (one for each section) and it only deciphers those pdls on demand. It only knows how to decipher a small subset of the possibilities at this time, but should allow the developer to write and test new or local decipher methods easily. Of course if you write a new method and can cleanly merge it with whats working please feel free to send it back to me. FUNCTIONS ========= new --- name ---- id -- initialize ---------- read_section ------------ pds_has_octet12 --------------- pds_attribute ------------- gds_attribute ------------- bms_attribute ------------- bds_attribute ------------- section_dump ------------ PDL::packint3 ------------- PDL::unpackint3 --------------- PDL::packint2 ------------- PDL::unpackint2 --------------- gds_vertical_parameters ----------------------- read_data --------- write_bds --------- write -----  File: pm.info, Node: PDL/IO/Grib/Wgrib, Next: PDL/IO/Misc, Prev: PDL/IO/Grib/Field, Up: Module List shamelessly stolen code *********************** NAME ==== PDL::IO::Grib::Wgrib - shamelessly stolen code SYNOPSIS ======== Helper routines for PDL::IO::Grib DESCRIPTION =========== This module is for miscellaneous PP-defined utility routines for the PDL::IO::Grib module. AUTHOR ====== Copyright (C) 2000 James P. Edwards 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 ========= BDSunpack --------- decode_ref_val -------------- encode_ref_val --------------  File: pm.info, Node: PDL/IO/Misc, Next: PDL/IO/NDF, Prev: PDL/IO/Grib/Wgrib, Up: Module List misc IO routines for PDL ************************ NAME ==== PDL::IO::Misc - misc IO routines for PDL DESCRIPTION =========== A mixture of basic I/O functionality SYNOPSIS ======== use PDL::IO::Misc; FUNCTIONS ========= rfits() ------- Suffix magic: # Automatically uncompress via gunzip pipe $pdl = rfits('file.fits.gz'); # Automatically uncompress via uncompress pipe $pdl = rfits('file.fits.Z'); $pdl = rfits('file.fits[2]'); # Read HDU extension #2 $pdl = rfits('file.fits.gz[3]'); # Read HDU extension #3 The default is to read the primary HDU. One can read other HDU's by using the [n] syntax, the second one is [1]. This works as long as they are IMAGE extensions - this module does not do FITS tables! FITS Headers stored in piddle and can be retrived with $a->gethdr. The `hdrcpy|PDL::Core' in this node flag of the piddle is set so that the header is copied to new piddles. This header is a reference to a hash where the hash keys are the keywords in the FITS header. It is important to note that for strings, the surrounding quotes are kept to ensure that strings that look like numbers are kept as strings. This is also of importance if you create your own header information and you want the value to be printed out as a string. Each record (comprising keyword, value, and any comment string) must fit within 80 characters; any value that is too long is truncated (silently). Comments in headers are stored as `$$h{COMMENT}{}' where $h is the header retrieved with `$a->gethdr'. History entries in the header are stored as `$$h{HISTORY}', which is an anonymous array for each HISTORY entry in the header. wfits() ------- Suffix magic: # Automatically compress through pipe to gzip wfits $pdl, 'filename.fits.gz'; # Automatically compress through pipe to compress wfits $pdl, 'filename.fits.Z'; $BITPIX is optional and coerces the output format. rcols() ------- There are two calling conventions - the old version, where a pattern can be specified after the filename/handle, and the new version where options are given as as hash reference. This reference can be given as either the second or last argument. The default behaviour is to ignore lines beginning with a # character and lines that only consist of whitespace. Options exist to only read from lines that match, or do not match, supplied patterns, and to set the types of the created piddles. Can take file name or *HANDLE, and if no columns are specified, all are assumed. For the allowed types, see `Datatype_conversions', *Note PDL/Core: PDL/Core,. Options: EXCLUDE or IGNORE - ignore lines matching this pattern (default *'/^#/'*). INCLUDE or KEEP - only use lines which match this pattern (default "). LINES - which line numbers to use. Line numbers start at 0 and the syntax is 'a:b:c' to use every c'th matching line between a and b (default "). DEFTYPE - default data type for stored data (if not specified, use the type stored in `$PDL::IO::Misc::deftype', which starts off as double). TYPES - reference to an array of data types, one element for each column to be read in. Any missing columns use the DEFTYPE value (default []). PERLCOLS - an array of column numbers which are to be read into perl arrays rather than piddles. References to these arrays are returned after the requested piddles (default undef). # read in lines containing the string foo, where the first # example also ignores lines that with a # character. ($x,$y,$z) = rcols 'file2', 0,4,5, { INCLUDE => '/foo/' }; ($x,$y,$z) = rcols 'file2', 0,4,5, { INCLUDE => '/foo/', EXCLUDE => '' }; # ignore the first 27 lines of the file, reading in as ushort's ($x,$y) = rcols 'file3', { LINES => '27:-1', DEFTYPE => ushort }; ($x,$y) = rcols 'file3', { LINES => '27:', TYPES => [ ushort, ushort ] }; # read in the first column as a perl array and the next two as piddles ($x,$y,$name) = rcols 'file4', 1, 2, { PERLCOLS => [ 0 ] }; printf "Number of names read in = %d\n", 1 + $#$name; Notes: 1. Quotes are required on patterns. 2. Columns are separated by whitespace by default, use `$PDL::IO::Misc::colsep' to specify an alternate separator. 3. For PDL-2.003, the meaning of the 'c' value in the LINES option has changed: it now only counts matching lines rather than all lines as in previous versions of PDL. 4. LINES => '-1:0:3' may not work as you expect, since lines are skipped when read in, then the whole array reversed. wcols() ------- If no columns are specified all are assumed. Will optionally only process lines matching a pattern. Can take file name or *HANDLE, and if no file/filehandle is given defaults to STDOUT. Options: HEADER - prints this string before the data. If the string is not terminated by a newline, one is added (default "). e.g., wcols "%10.3f", $a,$b; # Formatted wcols "%10.3f %10.5g", $a,$b; # Individual column formatting wcols $a,$b, { HEADER => "# a b" }; Note: columns are separated by whitespace by default, use $PDL::IO::Misc::colsep to specify an alternate separator. swcols() -------- rgrep() ------- Usage e.g. i.e. the vectors `$a' and $b get the progressive values of $1, $2 etc. rdsa() ------ Requires non-PDL DSA module. Contact Frossie (frossie@jach.hawaii.edu) Usage: Not yet tested with PDL-1.9X versions isbigendian() ------------- rasc() ------ rcube ----- This IO function allows direct reading of files into a large data cube, Obviously one could use cat() but this is more memory efficient. The reading function (e.g. rfits, readfraw) (passed as a reference) and files are the arguments. The cube is created as the same X,Y dims and datatype as the first image specified. The Z dim is simply the number of images. bswap2 ------ bswap4 ------ bswap8 ------ 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/IO/NDF, Next: PDL/IO/Pic, Prev: PDL/IO/Misc, Up: Module List PDL Module for reading and writing Starlink N-dimensional data structures as PDLs. ********************************************************************************** NAME ==== PDL::IO::NDF - PDL Module for reading and writing Starlink N-dimensional data structures as PDLs. SYNOPSIS ======== use PDL::IO::NDF; $a = PDL->rndf($file); $a = rndf('test_image'); $a = rndf('test_image', 1); $a->wndf($file); wndf($a, 'out_image'); propndfx($a, 'template', 'out_image'); DESCRIPTION =========== This module adds the ability to read and write Starlink N-dimensional data files as N-dimensional PDLs. FUNCTIONS ========= rndf() ------ The '.sdf' suffix is optional. The optional second argument turns off automatic quality masking and returns a quality array as well. BUG? `rndf('bob.sdf',1)' calls ndf_sqmf(1,...), which means that the quality array is turned into bad pixels - ie the *opposite* of above. Or am I confused? Header information and NDF Extensions are stored in the piddle as a hash which can be retreived with the `$pdl->gethdr' command. Array extensions are stored in the header as follows: $a - the base DATA_ARRAY If `$hdr = $a->gethdr'; then: %{$hdr} contains all the FITS headers plus: $$hdr{Error} contains the Error/Variance PDL $$hdr{Quality} The quality byte array (if reqeusted) @{$$hdr{Axis}} Is an array of piddles containing the information for axis 0, 1, etc. $$hdr{NDF_EXT} Contains all the NDF extensions $$hdr{Hist} Contains the history information $$hdr{NDF_EXT}{_TYPES} Data types for non-PDL NDF extensions so that wndf can reconstruct a NDF. All extension information is stored in the header hash array. Extension structures are preserved in hashes, so that the PROJ_PARS component of the IRAS.ASTROMETRY extension is stored in `$$hdr{NDF_EXT}{IRAS}{ASTROMETRY}{'PROJ_PARS'}'. All array structures are stored as arrays in the Hdr: numeric arrays are stored as PDLs, logical and character arrays are stored as plain Perl arrays. FITS arrays are a special case and are expanded as scalars into the header. PDL does not have a signed byte datatype, so any '_BYTE' data is read into a byte (unsigned) piddle and a warning is printed to STDOUT. wndf() ------ wndf can be used for writing PDLs to NDF files. The '.sdf' suffix is optional. All the extensions created by rndf are supported by wndf. This means that error, axis and quality arrays will be written if they exist. Extensions are also reconstructed by using their name (ie FIGARO.TEST would be expanded as a FIGARO extension and a TEST component). Hdr keywords Label, Title and Units are treated as special cases and are written to the label, title and units fields of the NDF. Header information is written to corresponding NDF extensions. NDF extensions can also be created in the {NDF} hash by using a key containing '.', ie {NDF}{'IRAS.DATA'} would write the information to an IRAS.DATA extension in the NDF. rndf stores this as `$$hdr{NDF}{IRAS}{DATA}' and the two systems are interchangeable. rndf stores type information in {NDF}{'_TYPES'} and below so that wndf can reconstruct the data type of non-PDL extensions. If no entry exists in _TYPES, wndf chooses between characters, integer and double on a best guess basis. Any perl arrays are written as CHAR array extensions (on the assumption that numeric arrays will exist as PDLs). propndfx() ---------- Routine to write a PDL to an NDF by copying the extension information from an existing NDF and writing DATA,VARIANCE, QUALITY and AXIS info from a PDL (if they exist). Extensions, labels and history are propogated from the old NDF. No new extension information is written. This command has been superseded by `wndf()|' in this node. NOTES ===== The perl NDF module must be available. This is available from the author or from Starlink (http://www.starlink.rl.ac.uk). If an NDF is read which contains AST World Coordinate information (a .WCS component) this information is currently ignored. Currently WCS information can only be written and stored using standard FITS headers. See http://rlspc5.bnsc.rl.ac.uk/star/docs/sun211.htx/sun211.html#xref_ for more information on AST. AUTHOR ====== This module was written by Tim Jenness . Copyright (C) Tim Jenness 1997-2000. All Rights Reserved. SEE ALSO ======== *Note PDL/FAQ: PDL/FAQ, for general information on the Perl Data language, `NDF' in this node for information on the NDF module.