CCBBM Programming Notes

This TWiki topic provides notes on use of CCBBM files (BM).

Overview

The CCBBM format uses ASCII text to represent arbitrary triangulated meshes with associated metadata.

A CCBBM file contains:

Format Specification

In the CCBBM format, each line is either white space, a comment, a vertex, a face, and edge or a mixture of one and a comment. Comments are specified by a '#', and the rest of the line following this will not be considered.

The format has the following constraints:

Vertex and face specifications are of the form:

Vertex index x y z

Face index vertexA vertexB vertexC

where x, y, and z are floats. The order of the vertex and faces does not matter, as long as the faces refer to defined vertices.

Attributes are appended to the end of the vertex or face specification. They are defined as such:

Vertex 3 1.3 4.3 7.7 {attribute1=(value1 value2 value3) attribute2=(value4 value5 value6)}

where attribute1,2 are strings and value1,2,3,4,5,6 are floats. Attributes are specified in braces and have the form $name=$values. =$value=s can either be space-delimited floats in parenthesis or a single float. Recall that attributes must be consistent. All vertices would have to specify the same types of attributes otherwise an error occurs. Two attributes are the same type if they have the same string and dimension.

Here is a simple example file, which specifies four vertices with one attribute each and two faces with two attribute each:

# CCBBM 1.0
# A comment

Vertex 2 1.4 2.6 7.8 {width=4.6}
Vertex 1 7.2 7.3 5.4 {width=6.7}
Vertex 3 6.1 6.1 3.1 {width=2.2}
Vertex 4 1.1 2.1 5.1 {width=4.2}
Face 1 3 2 1 {normal=(.1 .02 .8) weight=(.8)}
Face 2 4 3 2 {normal=(.01 .4 .7) weight=(.4)}

How a CCBBM is represented as a ShapeTools Shape

Overview

ShapeTools reads data from CCBBM files into a Shape.

The CCBBM vertices are stored in the Shape's PointSet.

The CCBBM faces are stored in the Shape's FaceSet with an implementation CGALFaceSet.

The vertex/face attributes are stored in FloatTupleArrayAttributes in an AttributeSet of the corresponding PointSet or FaceSet of the Shape.

The name of the CCBBM attribute in the file is used as the ID of the ShapeTools attribute that encodes it. If color or normals are used, the appropriate common attribute is used.

The ShapeTools Data Model

The basic data model used in ShapeTools is:

Reading a CCBBM file using ShapeTools

The easiest way to to read a CCBBM is to use the ShapeTools ShapeToolsReader.read() method. This method will determine which ShapeReader class can read the data file. This frees a ShapeTools programmer from having to know the type of the input file. Here is how to do so:

import edu.ucla.loni.ccb.shape.About;
import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shapeio.util.ShapeToolsReader;  
import java.io.IOException;

public class Example 
{
  // construct an Example
  public Example ()
    {
      // check version of library
      if (About.getMajorVersionNumber() != 1) {
        System.err.println("Incompatible ShapeTools library.");
       System.exit(1);
      }
    }

  /** 
   * Read a CCBBM file into a shape.
   * 
   * @param ccbbmFilename name of a CCBBM file.
   *
   * @returns a Shape read from a CCBBM.
   * throws IOException if unable to read the CCBBM.
  */
  public Shape read(String ccbbmFilename)
    {
      ShapeToolsReader reader = new ShapeToolsReader();
      Shape ccbbmShape = reader.readShape(ccbbmFilename);
      return ccbbmShape;
    }
}

An alternative (and more direct approach) is to use the method in the edu.ucla.loni.ccb.shapeio.ccbbm.BmIO class.

The call

Shape ccbbmShape = BmIO.read(String filename)

will read a shape from the file located at the given filename. An IOException will be thrown if it cannot be read for some reason.

Getting data from a CCBBM Shape

Getting vertex coordinates

Vertex coordinates (points) are stored in the Shape's PointSet.

import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shape.geometry.IPointSet;

IPointSet pointSet = shape.getVertices();

Note: Points of any dimension are supported by ShapeTools. If you need to know the number of dimensions of a point use

int numDimensions = pointSet.getPointDimensions(); this will always be 3 for a CCBBM file

To get the coordinates of a single point Note: this method allocates a new float[] for each point's coordinates so obtained.

// index of desired point
int index = 23;
float [] coordinateTuple = pointSet.getPoint(index);

You'll often want the coordinates of the points as an array of floats. To minimize memory use ShapeTools returns such requests as a group of arrays in which each array contains all point coordinates of a specific spatial dimension.

float [][] coordinates = pointSet.getPoints();
// print coordinates of all points

for (int pointIndex = 0; pointIndex < pointSet.size(); pointIndex++) {
 System.out.print("Coords of point #" + pointIndex + ": [");
 for (int dim = 0; dim< coordinates.length; dim ++) { 
   System.out.print(coordinates[dim][pointIndex] + " ");
  }
 System.out.println("]");
}

Getting triangle faces from a CCBBM Shape

The vertices of a particular face may be obtained from the FaceSet

 // get number of the points of all faces in a Shape:
 IFaceSet faceSet = shape.getFaces();
 for (int faceIndex =0; faceIndex < faceSet.size(); faceIndex++) {
   int [] verticesInAFace = getVertexIndices(int faceIndex)
 }

The edges of a particular face may be obtained from the FaceSet

 // get number of the points of all faces in a Shape:
 IFaceSet faceSet = shape.getFaces();
 for (int faceIndex =0; faceIndex < faceSet.size(); faceIndex++) {
   int [] edgesInFace  = getEdgeIndices(int faceIndex)
 }

If the order of faces retrieved from a FaceSet does not matter you can use a FaceSetIterator

IFaceSet faces;
FaceSetIterator iter = new FaceSetIterator(faces);

while (iter.hasNext()) {
  Face thisFace = (Face)iter.next();
}

Getting attribute data from a CCBBM Shape

Face attributes are stored in the AttributeSet of the FaceSet, and likewise, the vertex attributes are stored in the AttributeSet of the PointSet.

Each ShapeTools attribute has a string that identifies it. If you need attribute data from a CCBBM shape, you need to know the name used in the file. This will be the ID of the ShapeTools attribute.

For example, if a file specified a vertex attribute as such:

Vertex 25 1.5 4.3 5.6 {curvature=(1.3 5.3 2.2)}

then the shape would have a PointSet attribute with an ID "curvature". The attribute will be a FloatTupleArrayAttribute. Here is a call to get the attribute:

FloatTupleArrayAttribute attribute = shape.getVertices().getAttributeSet().getAttribute("curvature");

You could then check the dimensions of the attribute with the following calls:

int numberOfAttribute = attribute.size();
int dimension = attribute.getFloat(0).length;

You could get the values of the N-th attribute (the N-th vertex's) as a float[]:

float[] value = attribute.getFloat(N);

There are several special attributes used. First is the format attribute. This is a StringAttribute in the AttributeSet of the Shape. This stores the version of the file read. Additionally, there are two "common attributes", color and normals. If there are CCBBM attributes with the name "rgb" or "normal", these are register as common attributes of the FaceSet. Here is a call to get the attribute associated with the common color attribute (the same applies for normals):

String colorAttributeName = aShape.getFaces().getCommonAttributeName(ShapeComponent.COLOR_ATTRIBUTE);

if(colorAttributeName != null)
  FloatTupleArrayAttribute = aShape.getFaces().getAttributeSet().getAttribute(colorAttributeName);