Shape Viewer Frequently Asked Questions

---

I get this error: ShapeViewer requires java3d 1.3 or greater.

The problem is that the ShapeViewer cannot find the 3d graphics extension Java3d. This is not usually included automatically included in the Java Runtime interpreter, and must be manually installed into each version of java (Mac OSX excepted).

If you think you installed java3d, be sure to verify you (or your system administrator) put it into the right place. It's very easy to put the java3d libraries in the wrong place, or in a different java runtime.

In addition, when you upgrade to a new version of java, the Java3D files need to be installed into each new java version.

The program ShapeJava (click here to download) can help diagnose these problems. Run this program with the following text, typed on an command line, in the directory where the download file is saved.

java -jar ShapeJava.jar

on a Macintosh OS X computer, running this program (by java -jar

Current operating system is:  Unix Mac MacOSX
Current java runtime version is: 1.5
Java home directory is: /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home
Java library Path is: .:/Users/craig/Library/Java/Extensions:/Library/Java/Extensions:/System/Library/Java/Extensions:/usr/lib/java
Successfully loaded java3D test class: javax.media.j3d.Canvas3D
Java Processors Available : 2

then either

• java3d was not installed into the same Java runtime that is used when you double click.
• java3d was not installed correctly at all

in this case, you want to look carefully at the folders listed in the "Java library Path"; one of these is usually where the java3d library and extensions are installed.

For example on an Apple OS X (10.5) computer

    ls  /System/Library/Java/Extensions

shows these Java extensions:

AppleScriptEngine.jar           dns_sd.jar                      jai_core.jar                    libQTJNative.jnilib
CoreAudio.jar                   j3daudio.jar                    libAppleScriptEngine.jnilib     libShark.jnilib
MRJToolkit.jar                  j3dcore.jar                     libJ3D.jnilib                   libmlib_jai.jnilib
Notes                           j3dutils.jar                    libJ3DAudio.jnilib              mlibwrapper_jai.jar
QTJava.zip                      jai_codec.jar                   libJ3DUtils.jnilib              vecmath.jar

of these, Java3D is split into the these jar files: j3daudio.jar j3dcore.jar, j3dutils.jar, vecmath.jar , on a Macintosh OS X computer.

---

How can I open multiple files from on a remote computer ?

You can either open all the files in a remote directory. If you need more control (as when a remote directory contains a file you do not want to display) you can open a list, on your local computer, of remote file URL refereneces.

---

The viewer is very slow. How can I make it run faster ?

• try running with a larger allocation of memory java -Xmx250m -jar ShapeViewer.jar.
• try using the "points" draw mode first, then "lines", then 'surface" and finally, "surface fill". "Points" is fastest, "surface fill" is slowest.

I cannot see my surface as the shape is very dark

If you are using the "points" or "lines" draw mode:

• change the color of the shape to a brighter color.

if you are using "surface" or "surface fill" draw mode, also try:

• turn on the vertex normals (see Right hand side controls) -if image is still very dark, flip the vertex normals ( [flip] button ).

How do I start two synchronized ShapeViewers on my computer ?

Note: You must have Java RMI support is available (e.g. you'll need the 'rmiregistry' program).

To run two copies of the ShapeViewer, with one controlling the other, on the same machine:

1) start the master (server) shape viewer

java -jar ShapeViewer.jar -server -files

2) start the secondary (client) shape viewer

java -jar ShapeViewer.jar -client

3) use mouse to instruct the master (1) to load the first file 4) use mouse to instruct the client (2) to load the second file 5) use mouse to manipulate (rotate, zoom, ...) the master (1).

As an alternative, you may also specify a file to be loaded from the command line.

1a) java -jar ShapeViewer.jar -server -files

2a) java -jar ShapeViewer.jar -client -files

I cannot refresh the display of remote files . How can I update the list ?

Reloading the remote files displayed in the Virtual File System Browser only upates filess in the currently opened diectory. In 'read Directory' mode, in order to reload the directory, you must use a DOUBLE click to open it,and then press the 'Reload' button.

---

Why should I use the ShapeViewer instead of OpenDX ?

The ShapeViewer and OpenDX are designed for very different purposes. OpenDX is a general pupose data visualization and processing toolkit; ShapeViewer pupose is to display three dimensional shapes in a tool with an easily used interface, that reads commonly used neurological file formats.

Additional features of ShapeViewer are:

• Reads LONI Ucf, Loni TM, Minc Obj, and GeomView OFF formats (OpenDX does not).
• Portability: the ShapeViewer application binaries are portable as-is. OpenDX requires different binaries for each type of computer.
• Immediately usable. OpenDX requires training, or that a pre-defined display program be supplied.
• Visual Whiteboard - a ShapeViewer display may be propagated to remote , client ShapeViewers.

OpenDX is capable and flexible general purpose toolkit that fulfils a different usage niche than the ShapeViewer. If you wish to use it with the file formats previously mentioned please see the ShapeTools application program ShapeToDX.

---

How may I use the ShapeViewer to display a surface in my Java program ?

The ShapeViewer may be launched from any Java program and used to display a geometrical surface created by that program. The program fragment (below) shows one way to construct a surface (IFaceSet) from the vertices of that surface. A surface is considered to be composed of one or more faces. Each face is composed of three or more edges. Edges are a directed connection between two vertices.

In general, therefore, to construct a Shape that represents a surface mesh you will need to know:

• The locations of the mesh vertices
• The edges of the mesh (e.g. an edge connects vertex 0 with vertex 3)
• The faces of the mesh (e.g. face #4 is composed of edges 4,5,23 - in that order).

These elements corrospond directly to the following classes in the ShapeTools library:

• IPointSet
• IEdgeSet
• IFaceSet

A Shape, then, is a collection of these classes. Shapes need not contain all these classes; for example, a Shape may contain only points. However, because the classes refer to each other - eg. an IFaceSet^? refers to an IEdgeSet^? which, in turn refers to an IPointSet^? - a Shape containing an IFaceSet^? must also contain the associated edge and point sets.

All these components of a Shape - Shape, PointSet, EdgeSet and FaceSet - are defined as Java interfaces. This allows specific implementations of these interfaces to make different capability/performance tradeoffs.

It is common to define the faces of a mesh only by the an ordered set of vertices; the edges in this case are implied by the order of the vertices listed as defining a face. The CGALFaceSet and CGALEdgeSet classes may be used to simplify construction of a mesh from the vertices of it's faces. Full documentation is available from the ShapeToolsLibrary. For our purposes here it suffices to know that - in this particular case only - we do not need to explicitly create an instance of the edge set - that is done by the CGALFaceSet when it is instantiated.

You will, however, need to tell the Shape class which edge set to use. The example below shows how to

• Create a set of arbitrarily distributed points (IrregularPointSet)
• Create the lists of which vertices define the faces of a pyramid
• Construct a CGALFaceSet from the points and face definitions
• Create a Shape from these components
• Use the ShapeViewer to display this Shape.

Note:

The ShapeTools library stores vertex coordinates as a 2d float array whose 1d float array components store all vertices of a spatial dimension. This is the transpose of how most people think of a list of vertex coordinates. A different way to say this is that all the X-coordinates of the vertices are stored in on float [], all the Y-coordinates in a second float array, and all the Z-coordinates in a third. These are then collected as a single 2D array:

float [] x_coords = {0,1,2,3};
float [] y_coords = {0,1,0,1};
float [] z_coords = {0,0,0,0};

float [][] coords = {
   x_coords,
   y_coords,
   z_coords
};

Please see the ShapeToolsLibrary documentation for more explanations and examples.

import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shape.ShapeImpl;
import edu.ucla.loni.ccb.shape.geometry.CGALFaceSet;
import edu.ucla.loni.ccb.shape.geometry.CoordinateArray;
import edu.ucla.loni.ccb.shape.geometry.IFaceSet;
import edu.ucla.loni.ccb.shape.geometry.IPointSet;
import edu.ucla.loni.ccb.shape.geometry.IrregularPointSet;
import edu.ucla.loni.ccb.shapeviewer.IShape;
import edu.ucla.loni.ccb.shapeviewer.ShapeViewer;

   /*
   * Create a Shape and instruct the ShapeViewer to 
   * display it.
   */
    public static void main(String [] args)
      {
        // create Shape to hold points, edges, and faces  
        Shape shape = new ShapeImpl();
        
        // define vertices of pyramid  and form into a PointSet
        float [][] vertices = {
              { 0.0f, 1.0f, 0.0f,-1.0f, 0.0f},
              {-1.0f, 1.0f, 1.0f, 0.0f, 0.0f},
              { 0.5f, 0.5f, 0.5f, 0.5f, 0.0f}
        };
        CoordinateArray coords = new CoordinateArray(vertices);
        IPointSet points = new IrregularPointSet(coords);
        
        // define faces of pyramid  by enumerating the vertex indices
        int [][] verticesOfFaces = {
              {0,1,2,3},
              {2,1,4},
              {2,4,3},
              {4,3,0},
              {0,4,1}
        };
        IFaceSet faces = new CGALFaceSet(points,verticesOfFaces);
        
        // Attach components to Shape. Use a CGALFaceSet
        // to enable defining the faces by a list of vertices
        // composing each face. Note that in this special case
        // the edge set is obtained from the CGALFaceSet.
        // If other face set classes are used the IEdgeSet is
        // created independently of the IFaceSet.
        shape.setVertices(points);
        shape.setEdges(faces.getEdges());
        shape.setFaces(faces);
        
        // display shape in viewer
        IShape iShape = ShapeViewer.display(shape); 
        
     }
      }