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 ShapeJava (by java -jar ShapeJava.jar) produces this as a result:


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

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.

Windows

Installing Java3D onto a Windows OS is more complex. We suggest using the java3d installation notes, typically found by googling for "java3d windows install". Some results from this search (as of 18 May 2011) are:

Running from a DOS console

If you can run the ShapeViewer via double-clicking it's icon, but running from a DOS console fails, the problem may be that DOS is using a different version of java3d than that used if you double-click the ShapeViewer JAR file.


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 ?

I cannot see my surface as the shape is very dark

If you are using the "points" or "lines" draw mode: if you are using "surface" or "surface fill" draw mode, also try:

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:

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:

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

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

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); 
        
     }
      }


I cannot color the vertex attributes

I

The ColorMapLibrary, used by the ShapeViewer, has a simple color map which supports 3 element vector attributes. Scalar color maps will use the average of the vector attribute components as the basis for mapping the vector into a color.


I cannot display my CCBBM file vertex attributes

CCBBM supports per-vertex attributes with multiple values (the "rgb" attribute. please see: "I cannot color the vertex attributes" in this FAQ listing

Can I run the ShapeViewer from within a command line script ?

You may give the ShapeViewer a list of files to load on the command line. Be sure to allocate enough memory to the java JVM to display your shape.

For i=1:N
    file1 = surface_01.obj
    file2 = surface_02.obj
    java  -Xmx350m -jar ShapeViewer.jar -files file1 file2
Pause
Next

My UCF Surfaces are not shaded

Users of LONI UCF (Universal Contour File) files often use these file to store surface. Although the UCF is not technically a surface file format, if all contours have the same number of vertices, these these contour may be assumed to represent a surface, and the connections between the line inferred to form a quadrangular grid.

This dual interpretation of the UCF file format poses a difficulty for the ShapeViewer: should it treat the collection of lines as a single connected surface, or a set of disjoint lines ? The UCF file format does not store the information needed to resolve this ambiguity. Thus, the decsion of whether to display a file as lines, or as a surface, must be made by the user of the ShapeViewer when the file is loaded.

To treat the UCF as a surface, check the [X] Load as Grid UCF checkbox that is found on the right hand side of the file selection dialog box.

fileOpenDialog.gif

To set this value as a default setting, you may set this as a user preference in the Preferences dialog. This dialog is displayed by selecting "Preferences" from the ShapeViewer File menu. This is useful when a file is loaded by dragging it's icon onto the ShapeViewer display.

Selecting the 'Preferences' menu.

Setting the startup preference to display all UCF files as a grid, if possible.

shows

Note: it is because of this intrinsic ambiguity that the ShapeTools group does not reccomend UCF as a file format.

Attachment sort Action Size Date Who Comment
ShapeJava.jar manage 244.7 K 04 Dec 2007 - 20:52 CraigSchwartz Shape tools java runtime diagnostic tool.