TriD(D) User Contributed Perl Documentation TriD(D) 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]); lat- tice3d([$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 speci- fied 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. Cur- rently the interface w.r.t. this division is still much in motion. For OpenGL you can select either on- or off-line render- ing. VRML is currently always offline (this may change later, if someone bothers to write the java(a) 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 coordi- nates (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 rou- tines 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 dimen- sion. Equivalent to [$piddle->xvals, $pid- dle->yvals, $piddle]. POLAR2D A 2-D polar coordinate system. [$piddle] is inter- preted 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,$pid- dle,$piddle]). LINE A line made of 1 or 2 coordinates. [$piddle] is interpreted as [$piddle->xvals,$piddle,0]. [$pid- dle1,$piddle2] is interpreted as [$piddle1,$pid- dle2,$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 3D line plot, defined by a variety of contexts. line3d piddle(3,x), {OPTIONS} line3d [CONTEXT], {OPTIONS} Example: 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 3D rendered image plot, defined by a variety of contexts imag3d piddle(3,x,y), {OPTIONS} imag3d [piddle,...], {OPTIONS} Example: 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 3D mesh plot, defined by a variety of contexts mesh3d piddle(3,x,y), {OPTIONS} mesh3d [piddle,...], {OPTIONS} Example: 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 alias for mesh3d points3d 3D points plot, defined by a variety of contexts points3d piddle(e), {OPTIONS} points3d [piddle,...], {OPTIONS} Example: perldl> points3d [sqrt(rvals(zeroes(50,50))/2)]; - points on surface See module documentation for more information on contexts and options imagrgb 2D TrueColor Image plot imagrgb piddle(3,x,y), {OPTIONS} imagrgb [piddle,...], {OPTIONS} 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. e.g. 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 2D TrueColor Image plot as an object inside a 3D space imagrdb3d piddle(3,x,y), {OPTIONS} imagrdb3d [piddle,...], {OPTIONS} 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]]. e.g. perldl> imagrgb3d $colors, {Points => [[0,0,0],[1,0,0],[1,0,1],[0,0,1]]}; - plot on XZ plane instead of XY. grabpic3d Grab a 3D image from the screen. $pic = grabpic3d(); The returned piddle has dimensions (3,$x,$y) and is of type float (currently). XXX This should be altered later. hold3d, release3d Keep / don't keep the previous objects when plotting new 3D objects hold3d(); release3d(); or hold3d(d); hold3d(d); keeptwiddling3d, nokeeptwiddling3d Wait / don't wait for 'q' after displaying a 3D image. 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 undesir- able and it is more desirable to just run one step of the event loop at a time. keeptwiddling3d(); nokeeptwiddling3d(); or keeptwiddling3d(d); keeptwiddling3d(d); When an image is added to the screen, keep twiddling it until user explicitly presses 'q'. keeptwiddling3d(); imag3d(..); nokeeptwiddling3d(); $o = imag3d($c); while(e) { $c .= nextfunc($c); $o->data_changed(); twiddle3d(); # animate one step, then return. } twiddle3d Wait for the user to rotate the image in 3D space. 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 "$win- dow->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 con- tinuous 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 execu- tion-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 pid- dles. PDL::Graphics::TriD::Points This is simply a set of points in 3-space. Takes as argu- ments 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 view- port, 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 previ- ous (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.har- vard.edu). Documentation contributions from Karl Glaze- brook (kgb@aaoepp.aao.gov.au). All rights reserved. There is no warranty. You are allowed to redistribute this soft- ware / 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. perl v5.6.1 2000-08-26 TriD(D)