VRMLplot.m

To create new animations using VRMLplot you'll need a copy of Matlab but to view the output, you need only have Netscape and a VRML 2.0 compatible plug-in such as SGI's free CosmoPlayer.

Some example worlds created using VRMLplot are now on-line.

NOTE - there are known bugs in some browsers which may prevent them from working with these files - if you have difficulty see section 2.

• 1. Using VRMLplot to create output files
  • 1.1 Plots
  • 1.2 Surfaces
  • 1.3 Animations
  • 1.4 Customizing output
  • 1.5 Combining multiple graphs
• 2. Viewing output created with VRMLplot
• 3. Changes and additions
• 4. Known bugs and limitations
• 5. Downloading VRMLplot

1. Using VRMLplot to create output files

>> t=[0:0.2:6]; x=sin(2*t); y=cos(t); z=sin(t);
>> VRMLplot(x,y,z)
ans=
out.wrl

>> !netscape out.wrl &

(The ampersand may not work on non-unix machines). Its not necessary to restart netscape for each new graph, just leave it running and hit reload after creating each new graph.

1.2 Surfaces

>> Z=peaks;
>> VRMLplot(Z)
ans=
out.wrl

Pass it three matrices, containing X,Y and Z coordinates and it will plot a parametric surface:

>> [X Y Z] = peaks;
>> VRMLplot(X,Y,Z)
ans=
out.wrl


VRMLplot will automatically break the surface up into patches, compute colors and normals and generate multiple levels of detail. If you wish you can also set colors manually by specifying a fourth matrix containing intensity values (between 0 and 1) for each vertex.

Since the generated files (particularly surface plots) can be fairly large you should probably take the time to compress them. For example, surf.wrl takes 500K while surf.wrl.gz (created by using gzip) consumes less than 130K.

>> t=[0:0.1:6]; x=sin(2*t); y=cos(t); z=sin(t);
>> VRMLplot(x,y,z,t)
ans=
out.wrl

Here's an example which animates a two-link robot. First we'll create a matrix containing values for time and each of the two rotating joints, then we'll give that matrix and a model of a two link robot arm to VRMLplot:

Here's another example, this time we'll animate the motion of an object which can translate and rotate in any 3-D Cartesian direction. Once again we create a matrix describing the desired motion. In this case the matrix columns contain time,x,y,z translations and the rotation about the z,y and x axes (in radians).

For the above examples, motions were deliberately chosen to fall within the default axis sizes. In most cases you'll need to manually set min/max values for each axis so they are appropriate for your particular model and animated motion.

Both the included template files are well commented so you should not have too much difficulty modifying then to create your own models. Much more complex worlds are of course possible, for example you could have an input file describing several vehicles, each of which had several manipulators attached to it.

If you wish to animate several vehicles or manipulators you also have the option of animating each one separately and appending the animations together (see the section 1.5 for more details).

Option	Description
animation	use to set the name of a VRML file defining a model which is to be animated - see section 1.3 for details.
append	Append allows multiple graphs to be combined together. See the next subsection for more details.
color0 color1	Use to manually specify surface colors. By default color1 (corresponding to the highest vertices on the surface) is a light grey, while color0 (corresponding to the lowest points) is a very dark grey. Setting colors requires a three element matrix containing red, green and blue values, each of which is in the range 0 to 1. e.g. to pseudocolor a plot from blue (lowest) to red (highest) use: VRMLplot(Z,'color0=[0 0 1]; color1=[1 0 0]')
linecolor meshcolor modelcolor spotcolor	Use to specify the color of lines, surface meshes, animated models and spots.Setting colors requires a three element matrix containing red, green and blue values, each of which is in the range 0 to 1. e.g. to produce a plot with blue lines and red spots use: VRMLplot(Z,'linecolor=[0 0 1]; spotcolor=[1 0 0]') (Both American and Britsh spellings of color/colour are accepted).
mesh	Enables or disables mesh lines on surface plots. Set mesh=1 to add grid lines (default is 0).
labelsize	use to manually set the height of text labels on the graph. In most cases the system should automatically choose a suitable value.
linesize	use in plots to manually set the size of the lines to use in the graph. At this time only sizes of 0 and 1 are supported. To plot points without connecting lines set linesize=0.
shadow	Enables or disables shadows. Set shadow=0 to remove shadows (default is 1).
spotsize	use in plots to manually set the size of the spots used to represent each point in the graph. In most cases the system should automatically choose a suitable value. To generate line graphs without spots, set spotsize=0.
text	If you are on a slow machine or using an old browser it may be advantageous to turn off the text labels on the graph axes. Do this by setting the 'text' option to 0.
title	use to set a title for the graph. Depending on your browser this may appear somewhere in the window border when your VRML file is displayed.
tscale	By default the system animates one unit of time in one real second. Setting the tscale option allows you to stretch or compress time. For example, tscale=10 causes one unit of time to be animated over 10 real seconds.
xlabel ylabel zlabel tlabel	use to set the text under the x,y,z and time axes.
xmax ymax zmax tmax	use to set the maximum value for each axis. In most cases the system should automatically choose suitable values.
xmin ymin zmin tmin	use to set the minimum value for each axis. In most cases the system should automatically choose suitable values.
xstep ystep zstep tstep	use to set the step size along each axis. In most cases the system should automatically choose suitable values.
xscale yscale zscale	use these to set an absolute scaling factor between units along the graph axes and global coordinates within the VRML world. By default the system will either scale each dimension so the resulting graph fits within a 1 meter cube within the VRML world or, in the case of animated worlds, it will choose a scaling factor of unity. By explicitly setting a scale you can override this behavior. For example, setting xscale=1,yscale=1,zscale=1 will cause a world to be created where one unit along any axis is represented by 1 meter within the VRML world. Setting scales of 0.001 will cause each unit to be represented by 1mm within the VRML. In many cases changes in scale won't be obvious since the system recomputes viewpoints based on the scale values you choose.

1.5 Combining multiple plots

>> t=[0:0.1:6]; x=sin(2*t); y=cos(t); z=sin(t);
>> VRMLplot(x,y,z,t);
>> VRMLplot(x,y*0.9,z,t*0.95,'append=1');
>> VRMLplot(x,y*0.8,z,t*0.9,'append=1')
ans=
out.wrl

By default all the appended graphs will use the same axes and scaling factors so points which have the same values, even if on different graphs, will always appear at the same spot.

To check if your browser is compatible try some of the on-line examples from Hartman and Wernecke's VRML 2.0 Handbook. If you can view those then you'll probably also be able to view VRMLplot's output files. If you see text in place of a VRML world then you probably don't have a VRML plug-in installed.

If you get a blank screen then you're probably using either a VRML 1.0 viewer or an old version of CosmoPlayer.

If you get a warning dialog referring to "just" then you're probably using a beta version of CosmoPlayer which does not support text.

If the axes don't change when you select different viewpoints then your viewer may not support VRMLscript.

On SGI machines, using Netscape 3.0 and CosmoPlayer 1.0 you should see a screen similar to this:

Try choosing different viewpoints and notice how the axes rearrange themselves. With animations, try choosing the "view behind spot" viewpoint and then clicking on the spot to start the animation.

3. Changes and Additions

5. Downloading VRMLplot

Current version (tested on Matlab 5.0): VRMLplot.1.2.1.tar.gz

Previous version (tested on Matlab 4.2c): VRMLplot.1.2.tar.gz

http://www.dsl.whoi.edu/~sayers/VRMLplot