1TriD(3) User Contributed Perl Documentation TriD(3)
2
6 PDL::Graphics::TriD -- PDL 3D interface
7
9 use PDL::Graphics::TriD;
10 # After each graph, let the user rotate is and
12 # wait for him to press 'q', then make new graph
13 line3d($coords); # $coords = (3,n,...)
14 line3d($coords,$colors); # $colors = (3,n,...)
15 line3d([$x,$y,$z]);
16 imagrgb([$r,$g,$b]);
17 lattice3d([$x,$y,$z]); # 2-d piddles
18 points3d([$x,$y,$z]);
19 hold3d(); # the following graphs are on top of each other and the previous
21 line3d([$x,$y,$z]);
22 line3d([$x,$y,$z+1]);
23 $pic = grabpic3d(); # Returns the picture in a (3,$x,$y) float piddle (0..1).
24 release3d(); # the next graph will again wipe out things.
26
28 These modules are still in a somewhat unfocused state: don't use them
29 yet if you don't know how to make them work if they happen to do
30 something strange.
31
33 This module implements a generic 3D plotting interface for PDL.
34 Points, lines and surfaces (among other objects) are supported.
35 With OpenGL, it is easy to manipulate the resulting 3D objects with the
37 mouse in real time - this helps data visualization a lot.
38
40 The default device for TriD is currently OpenGL. You can specify a
41 different device either in your program or in the environment variable
42 "PDL_3D_DEVICE". The one specified in the program takes priority.
43 The currently available devices are
45 GL OpenGL
47 GLpic OpenGL but off-line (pixmap) rendering and writing to a
49 graphics file.
50 VRML ( Not available this release )
52 VRML objects rendering. This writes a VRML file describing the
53 scene. This VRML file can then be read with a browser.
54
56 TriD offers both on- and off-line visualization. Currently the
57 interface w.r.t. this division is still much in motion.
58 For OpenGL you can select either on- or off-line rendering. VRML is
60 currently always offline (this may change later, if someone bothers to
61 write the java(script) code to contact PDL and wait for the next
62 PDL image over the network.
63
65 Specifying a set of coordinates is generally a context-dependent
66 operation. For a traditional 3D surface plot, you'll want two of the
67 coordinates to have just the xvals and yvals of the piddle,
68 respectively. For a line, you would generally want to have one
69 coordinate held at zero and the other advancing.
70 This module tries to make a reasonable way of specifying the context
72 while letting you do whatever you want by overriding the default
73 interpretation.
74 The alternative syntaxes for specifying a set of coordinates (or
76 colors) are
77 $piddle # MUST have 3 as first dim.
79 [$piddle]
80 [$piddle1,$piddle2]
81 [$piddle1,$piddle2,$piddle3]
82 [CONTEXT,$piddle]
83 [CONTEXT,$piddle1,$piddle2]
84 [CONTEXT,$piddle1,$piddle2,$piddle3]
85 where "CONTEXT" is a string describing in which context you wish these
87 piddles to be interpreted. Each routine specifies a default context
88 which is explained in the routines documentation. Context is usually
89 used only to understand what the user wants when he/she specifies less
90 than 3 piddles.
91 The following contexts are currently supported:
93 SURF2D A 2-D lattice. " [$piddle] " is interpreted as the Z coordinate
95 over a lattice over the first dimension. Equivalent to "
96 [$piddle-"xvals, $piddle->yvals, $piddle] >.
97 POLAR2D A 2-D polar coordinate system. " [$piddle] " is interpreted as
99 the z coordinate over theta and r (theta = the first dimension
100 of the piddle).
101 COLOR A set of colors. " [$piddle] " is interpreted as grayscale
103 color (equivalent to " [$piddle,$piddle,$piddle] ").
104 LINE A line made of 1 or 2 coordinates. " [$piddle] " is interpreted
106 as " [$piddle-"xvals,$piddle,0] >. " [$piddle1,$piddle2] " is
107 interpreted as " [$piddle1,$piddle2,$piddle1-"xvals] >.
108 What makes contexts useful is that if you want to plot points instead
110 of the full surface you plotted with
111 imag3d([$zcoords]);
113 you don't need to start thinking about where to plot the points:
115 points3d([SURF2D,$zcoords]);
117 will do exactly the same.
119
121 Because using the whole object-oriented interface for doing all your
122 work might be cumbersome, the following shortcut routines are
123 supported:
124
126 line3d
127 3D line plot, defined by a variety of contexts.
128 line3d piddle(3,x), {OPTIONS}
130 line3d [CONTEXT], {OPTIONS}
131 Example:
133 perldl> line3d [sqrt(rvals(zeroes(50,50))/2)]
135 - Lines on surface
136 perldl> line3d [$x,$y,$z]
137 - Lines over X, Y, Z
138 perldl> line3d $coords
139 - Lines over the 3D coordinates in $coords.
140 Note: line plots differ from mesh plots in that lines only go in one
142 direction. If this is unclear try both!
143 See module documentation for more information on contexts and options
145 imag3d
147 3D rendered image plot, defined by a variety of contexts
148 imag3d piddle(3,x,y), {OPTIONS}
150 imag3d [piddle,...], {OPTIONS}
151 Example:
153 perldl> imag3d [sqrt(rvals(zeroes(50,50))/2)], {{Lines=>0};
155 - Rendered image of surface
157 See module documentation for more information on contexts and options
159 mesh3d
161 3D mesh plot, defined by a variety of contexts
162 mesh3d piddle(3,x,y), {OPTIONS}
164 mesh3d [piddle,...], {OPTIONS}
165 Example:
167 perldl> mesh3d [sqrt(rvals(zeroes(50,50))/2)]
169 - mesh of surface
171 Note: a mesh is defined by two sets of lines at right-angles (i.e. this
173 is how is differs from line3d).
174 See module documentation for more information on contexts and options
176 lattice3d
178 alias for mesh3d
179 points3d
181 3D points plot, defined by a variety of contexts
182 points3d piddle(3), {OPTIONS}
184 points3d [piddle,...], {OPTIONS}
185 Example:
187 perldl> points3d [sqrt(rvals(zeroes(50,50))/2)];
189 - points on surface
190 See module documentation for more information on contexts and options
192 imagrgb
194 2D TrueColor Image plot
195 imagrgb piddle(3,x,y), {OPTIONS}
197 imagrgb [piddle,...], {OPTIONS}
198 This would be used to plot an image, specifying red, green and blue
200 values at each point. Note: contexts are very useful here as there are
201 many ways one might want to do this.
202 e.g.
204 perldl> $a=sqrt(rvals(zeroes(50,50))/2)
206 perldl> imagrgb [0.5*sin(8*$a)+0.5,0.5*cos(8*$a)+0.5,0.5*cos(4*$a)+0.5]
207 imagrgb3d
209 2D TrueColor Image plot as an object inside a 3D space
210 imagrdb3d piddle(3,x,y), {OPTIONS}
212 imagrdb3d [piddle,...], {OPTIONS}
213 The piddle gives the colors. The option allowed is Points, which should
215 give 4 3D coordinates for the corners of the polygon, either as a
216 piddle or as array ref. The default is
217 [[0,0,0],[1,0,0],[1,1,0],[0,1,0]].
218 e.g.
220 perldl> imagrgb3d $colors, {Points => [[0,0,0],[1,0,0],[1,0,1],[0,0,1]]};
222 - plot on XZ plane instead of XY.
223 grabpic3d
225 Grab a 3D image from the screen.
226 $pic = grabpic3d();
228 The returned piddle has dimensions (3,$x,$y) and is of type float
230 (currently). XXX This should be altered later.
231 hold3d, release3d
233 Keep / don't keep the previous objects when plotting new 3D objects
234 hold3d();
236 release3d();
237 or
239 hold3d(1);
241 hold3d(0);
242 keeptwiddling3d, nokeeptwiddling3d
244 Wait / don't wait for 'q' after displaying a 3D image.
245 Usually, when showing 3D images, the user is given a chance to rotate
247 it and then press 'q' for the next image. However, sometimes (for e.g.
248 animation) this is undesirable and it is more desirable to just run one
249 step of the event loop at a time.
250 keeptwiddling3d();
252 nokeeptwiddling3d();
253 or
255 keeptwiddling3d(1);
257 keeptwiddling3d(0);
258 When an image is added to the screen, keep twiddling it until user
260 explicitly presses 'q'.
261 keeptwiddling3d();
263 imag3d(..);
264 nokeeptwiddling3d();
265 $o = imag3d($c);
266 while(1) {
267 $c .= nextfunc($c);
268 $o->data_changed();
269 twiddle3d(); # animate one step, then return.
270 }
271 twiddle3d
273 Wait for the user to rotate the image in 3D space.
274 Let the user rotate the image in 3D space, either for one step or until
276 (s)he presses 'q', depending on the 'keeptwiddling3d' setting. If
277 'keeptwiddling3d' is not set the routine returns immediately and
278 indicates that a 'q' event was received by returning 1. If the only
279 events received were mouse events, returns 0.
280
282 The key concepts (object types) of TriD are explained in the following:
283 Object
285 In this 3D abstraction, everything that you can "draw" without using
286 indices is an Object. That is, if you have a surface, each vertex is
287 not an object and neither is each segment of a long curve. The whole
288 curve (or a set of curves) is the lowest level Object.
289 Transformations and groups of Objects are also Objects.
291 A Window is simply an Object that has subobjects.
293 Twiddling
295 Because there is no eventloop in Perl yet and because it would be
296 hassleful to do otherwise, it is currently not possible to e.g. rotate
297 objects with your mouse when the console is expecting input or the
298 program is doing other things. Therefore, you need to explicitly say
299 "$window->twiddle()" in order to display anything.
300
302 The following types of objects are currently supported. Those that do
303 not have a calling sequence described here should have their own manual
304 pages.
305 There are objects that are not mentioned here; they are either internal
307 to PDL3D or in rapidly changing states. If you use them, you do so at
308 your own risk.
309 The syntax "PDL::Graphics::TriD::Scale(x,y,z)" here means that you
311 create an object like
312 $a = new PDL::Graphics::TriD::Scale($x,$y,$z);
314 PDL::Graphics::TriD::LineStrip
316 This is just a line or a set of lines. The arguments are 3 1-or-more-D
317 piddles which describe the vertices of a continuous line and an
318 optional color piddle (which is 1-D also and simply defines the color
319 between red and blue. This will probably change).
320 PDL::Graphics::TriD::Lines
322 This is just a line or a set of lines. The arguments are 3 1-or-more-D
323 piddles where each contiguous pair of vertices describe a line segment
324 and an optional color piddle (which is 1-D also and simply defines the
325 color between red and blue. This will probably change).
326 PDL::Graphics::TriD::Image
328 This is a 2-dimensional RGB image consisting of colored rectangles.
329 With OpenGL, this is implemented by texturing so this should be
330 relatively memory and execution-time-friendly.
331 PDL::Graphics::TriD::Lattice
333 This is a 2-D set of points connected by lines in 3-space. The
334 constructor takes as arguments 3 2-dimensional piddles.
335 PDL::Graphics::TriD::Points
337 This is simply a set of points in 3-space. Takes as arguments the x, y
338 and z coordinates of the points as piddles.
339 PDL::Graphics::TriD::Scale(x,y,z)
341 Self-explanatory
342 PDL::Graphics::TriD::Translation(x,y,z)
344 Ditto
345 PDL::Graphics::TriD::Quaternion(c,x,y,z)
347 One way of representing rotations is with quaternions. See the
348 appropriate man page.
349 PDL::Graphics::TriD::ViewPort
351 This is a special class: in order to obtain a new viewport, you need to
352 have an earlier viewport on hand. The usage is:
353 $new_vp = $old_vp->new_viewport($x0,$y0,$x1,$y1);
355 where $x0 etc are the coordinates of the upper left and lower right
357 corners of the new viewport inside the previous (relative to the
358 previous viewport in the (0,1) range.
359 Every implementation-level window object should implement the
361 new_viewport method.
362
364 Not enough is there yet.
365
367 Copyright (C) 1997 Tuomas J. Lukka (lukka@husc.harvard.edu).
368 Documentation contributions from Karl Glazebrook
369 (kgb@aaoepp.aao.gov.au). All rights reserved. There is no warranty.
370 You are allowed to redistribute this software / documentation under
371 certain conditions. For details, see the file COPYING in the PDL
372 distribution. If this file is separated from the PDL distribution, the
373 copyright notice should be included in the file.
374perl v5.12.3 2009-10-24 TriD(3)