Wrapping your head around 3d surface specifications

Let's begin by thinking about how you might make a 2d data plot. If you sampled your data at regular intervals, you would have a time serires y(t) = (y0, y1, y2, ...). You could plot y vs t by computing t0 = 0, t1 = dt, t2 = 2 * dt, and then plotting (t0, y0), (t1, y1), etc.

Next suppose that you measured x(t) and y(t). You can still plot y vs t, but you can also plot y vs x by plotting (x0, y0), (x1, y1), etc. The x-values don't have to increase monotonically: they could back-track on each other, for example, like the latitude and longitude of a boat on a lake. If you use plplot, you would plot this data using "$pl->xyplot($x, $y, PLOTTYPE => 'POINTS')".

Good. Now let's add a third coordinate, z(t). If you actually sampled x and y at regular intervals, so that x and y lie on a grid, then you can construct a grid for z(x, y), and you would get a surface. This is the situation in which you would use "mesh3d([$surface])".

Of course, your data is not required to be regularly gridded. You could, for example, be measuring the flight path of a bat flying after mosquitos, which could be wheeling and arching all over the space. This is what you might plot using "line3d([$x, $y, $z])". You could plot the trajectories of multiple bats, in which case $x, $y, and $z would have multiple columns, but in general you wouldn't expect them to be coordinated.

More generally, each coordinate is expected to be arranged in a 3D fashion, similar to "3,x,y". The "3" is the actual 3D coordinates of each point. The "x,y" help with gridding, because each point at "x,y" is expected to have as geographical neighbours "x+1,y", "x-1,y", "x,y+1", "x,y-1", and the grid polygon-building relies on that. This is how, and why, the 3D earth in "demo 3d" arranges its data.

 #!/usr/bin/perl
 use PDL;
 use PDL::Graphics::TriD;
 # Draw out a trajectory in three-space
 $t = sequence(100)/10;
 $x = sin($t); $y = cos($t); $z = $t;
 # Plot the trajectory as (x(t), y(t), z(t))
 print "using line3d to plot a trajectory (press q when you're done twiddling)\n";
 line3d [$x,$y,$z];
 # If you give it a single ndarray, it expects
 # the data to look like
 # ((x1, y1, z1), (x2, y2, z2), ...)
 # which is why we have to do the exchange:
 $coords = cat($x, $y, $z)->transpose;
 print "again, with a different coordinate syntax (press q when you're done twiddling)\n";
 line3d $coords;
 # Draw a regularly-gridded surface:
 $surface = sqrt(rvals(zeroes(50,50))/2);
 print "draw a mesh of a regularly-gridded surface using mesh3d\n";
 mesh3d [$surface];
 print "draw a regularly-gridded surface using imag3d\n";
 imag3d [$surface], {Lines=>0};
 # Draw a mobius strip:
 $two_pi = 8 * atan2(1,1);
 $t = sequence(51) / 50 * $two_pi;
 # We want three paths:
 $mobius1_x = cos($t) + 0.5 * sin($t/2);
 $mobius2_x = cos($t);
 $mobius3_x = cos($t) - 0.5 * sin($t/2);
 $mobius1_y = sin($t) + 0.5 * sin($t/2);
 $mobius2_y = sin($t);
 $mobius3_y = sin($t) - 0.5 * sin($t/2);
 $mobius1_z = $t - $two_pi/2;
 $mobius2_z = zeroes($t);
 $mobius3_z = $two_pi/2 - $t;
 $mobius_x = cat($mobius1_x, $mobius2_x, $mobius3_x);
 $mobius_y = cat($mobius1_y, $mobius2_y, $mobius3_y);
 $mobius_z = cat($mobius1_z, $mobius2_z, $mobius3_z);
 $mobius_surface = cat($mobius_x, $mobius_y, $mobius_z)->mv(2,0);
 print "A mobius strip using line3d one way\n";
 line3d $mobius_surface;
 print "A mobius strip using line3d the other way\n";
 line3d $mobius_surface->xchg(1,2);
 print "A mobius strip using mesh3d\n";
 mesh3d $mobius_surface;
 print "The same mobius strip using imag3d\n";
 imag3d $mobius_surface, {Lines => 0};

line3d

3D line plot, defined by a variety of contexts.

Implemented by "PDL::Graphics::TriD::LineStrip".

 line3d ndarray(3,x), {OPTIONS}
 line3d [CONTEXT], {OPTIONS}

Example:

 pdl> line3d [sqrt(rvals(zeroes(50,50))/2)]
 - Lines on surface
 pdl> line3d [$x,$y,$z]
 - Lines over X, Y, Z
 pdl> 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

Implemented by "PDL::Graphics::TriD::SLattice_S".

The variant, "imag3d_ns", is implemented by "PDL::Graphics::TriD::SLattice".

 imag3d ndarray(3,x,y), {OPTIONS}
 imag3d [ndarray,...], {OPTIONS}

Example:

 pdl> 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

Implemented by "PDL::Graphics::TriD::Lattice".

 mesh3d ndarray(3,x,y), {OPTIONS}
 mesh3d [ndarray,...], {OPTIONS}

Example:

 pdl> 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

trigrid3d

Show a triangular mesh, giving $vertices and $faceidx which is a series of triplets of indices into the vertices, each describing one triangle. The order of points matters for the shading - the normal vector points towards the clockface if the points go clockwise.

Options: "Smooth" (on by default), "Lines" (off by default), "ShowNormals" (off by default, useful for debugging).

Implemented by "PDL::Graphics::TriD::STrigrid_S".

trigrid3d_ns

Like "trigrid3d", but without shading or normals.

Implemented by "PDL::Graphics::TriD::STrigrid".

points3d

3D points plot, defined by a variety of contexts

Implemented by "PDL::Graphics::TriD::Points".

 points3d ndarray(3), {OPTIONS}
 points3d [ndarray,...], {OPTIONS}

Example:

 pdl> points3d [sqrt(rvals(zeroes(50,50))/2)];
 - points on surface

See module documentation for more information on contexts and options

spheres3d

3D spheres plot (preliminary implementation)

This is a preliminary implementation as a proof of concept. It has fixed radii for the spheres being drawn and no control of color or transparency.

Implemented by "PDL::Graphics::TriD::Spheres".

 spheres3d ndarray(3), {OPTIONS}
 spheres3d [ndarray,...], {OPTIONS}

Example:

 pdl> spheres3d ndcoords(10,10,10)->clump(1,2,3)
 - lattice of spheres at coordinates on 10x10x10 grid

imagrgb

2D RGB image plot (see also imag2d)

Implemented by "PDL::Graphics::TriD::Image".

 imagrgb ndarray(3,x,y), {OPTIONS}
 imagrgb [ndarray,...], {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.

 pdl> $x=sqrt(rvals(zeroes(50,50))/2)
 pdl> imagrgb [0.5*sin(8*$x)+0.5,0.5*cos(8*$x)+0.5,0.5*cos(4*$x)+0.5]

imagrgb3d

2D RGB image plot as an object inside a 3D space

Implemented by "PDL::Graphics::TriD::Image".

 imagrdb3d ndarray(3,x,y), {OPTIONS}
 imagrdb3d [ndarray,...], {OPTIONS}

The ndarray gives the colors. The option allowed is Points, which should give 4 3D coordinates for the corners of the polygon, either as an ndarray or as array ref. The default is [[0,0,0],[1,0,0],[1,1,0],[0,1,0]].

e.g.

 pdl> 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 ndarray 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(1);
 hold3d(0);

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 undesirable and it is more desirable to just run one step of the event loop at a time.

 keeptwiddling3d();
 nokeeptwiddling3d();

or

 keeptwiddling3d(1);
 keeptwiddling3d(0);

When an image is added to the screen, keep twiddling it until user explicitly presses 'q'.

 keeptwiddling3d();
 imag3d(..);
 nokeeptwiddling3d();
 $o = imag3d($c);
 do {
        $c .= nextfunc($c);
        $o->data_changed;
 } while(!twiddle3d()); # animate one step, then iterate
 keeptwiddling3d();
 twiddle3d(); # wait one last time

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 they press '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.

close3d

Close the currently-open 3D window.

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.

PDL::Graphics::TriD::LineStrip

This is just a line or a set of lines. The arguments are 3 1-or-more-D ndarrays which describe the vertices of a continuous line and an optional color ndarray (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 ndarrays where each contiguous pair of vertices describe a line segment and an optional color ndarray (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 ndarrays.

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 ndarrays.

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.