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:
- The vertices of a set of polygons which collectively define a surface in a three dimensional space.
- The faces of the surface, defined by the indices of the vertices that compose the polygons.
- The edges of the surface (these are not used in the ShapeTools Library)
- Attributes of those vertices or faces.
- Any number of comments
- A magic string on the first line of the file
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:
- the first line contains the comment: "# CCBBM 1.0"
- all faces must refer to vectices defined somewhere in the file
- all indices must be natural numbers
- all or none of the vertices or faces must have an attribute type
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:
- Each point has a unique index.
- Points are stored in PointSet.
- A directed line from one point to another is an Edge.
- Each Edge has a unique index.
- Edges are stored in an EdgeSet.
- An ordered set of Edges comprise a Face (polygon).
- Each Face of a Shape has a unique index number.
- Faces are stored in a FaceSet.
- An ordered set of Faces comprise a Solid
- Each Solid has a unique number.
- Solids are stored in a SolidSet (not yet implemented - v1.1.0).
- Each SolidSet (will) refer to a FaceSet
- Each FaceSet refers to an EdgeSet
- Each EdgeSet refers to a PointSet
- A Shape is not required to contain any of PointSets, EdgeSets , FaceSets, or SolidSets, except as noted above.
- Shapes, PointSets, EdgeSets, FaceSets and SolidSets all contain a attributes, stored in an AttributeSet.
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);