Minc Programming Notes
!ShapeTools version 1.1.0
This TWiki topic provides notes on use of Minc Polygon Object files (OBJ).
Overview
The Montreal Neurological Reseach Institute of McGill University, Montreal,
provides several Software Tools that facilitate neurological research.
These tools read and write a variety of file formats, two of which are frequently
used by LONI researchers, a file format storing the voxels
of brain image volumes (.MNC), and a file format storing the vertices of triangulated
surfaces (.OBJ). ShapeTools reads and writes the latter.
An OBJ file contains:
- The vertices of a set of polygons which collectively define a surface in a three dimensional space.
- The normal vectors to each of theses vertices.
- The polygons (faces) of the surface, defined by the indices of the vertices that compose the polygons.
- Either:
- a single RGBA color associated with the entire surface
or
- an RGBA color defined for each vertex of the surface.
All known examples of Minc OBJ files contain triangular faces exclusively. The file format
implies that non-triangular vertices may be supported by the Minc libraries, however, experiments
to verify this have failed. It is not known whether these failures are due to limitation in the
underlying Minc libraries or in the Minc application programs - a distinction that is academic at best.
For all practical purposes Minc Obj polygons must be triangular, with vertices ordered according to
the right-hand rule.
In OBJ files created by the Minc applications the order in which triangular files are encountered in the
data files non-contiguous and undocumented. Here, non-contigoous means that faces that share sides in
the surface modelled by the OBJ are not adjacent in the data file. The practical result of this is that
any operations on the faces of a Minc OBJ surface may not expect knowledge of that faces' neighbors, unless
an order is determined separately from reading the file data.
Minc OBJ files come in both an ascii text and a binary version. Both styles may be read and written
by the ShapeTools libraries.
How an OBJ is represented as a ShapeTools Shape
Overview
ShapeTools reads data from Minc OBJ files into a Shape.
The OBJ polygon vertices are stored in the Shape's PointSet.
The vertex normals and colors are stored in Data Attributes associated with the PointSet of the Shape.
The various lighting parameter values are stored in the Data Attributes of the Shape (not the Shape's PointSet).
The data attribute name variables are defined as constant public final variables in the [[][MincShapeConversions]] class.
Data Attributes
This table describes the data attributes read from a Minc Obj file:
| Attribute Description | Attribute Name variable | Type | Contained in AttributeSet of the |
| Vertex Colors (RGBA) | VERTEX_RGBA_COLOR_ATTRIBUTE_NAME | FloatTupleArrayAttribute | PointSet |
| Vertex Normals | VERTEX_NORMAL_ATTRIBUTE_NAME. | FloatTupleArrayAttribute | PointSet |
| Light Ambience | AMBIENCE_ATTRIBUTE_NAME | FloatAttribute | Shape |
| Light Diffusion | DIFFUSION_ATTRIBUTE_NAME | FloatAtribute | Shape |
| Light Specularity | SPECULARITY_ATTRIBUTE_NAME | FloatAttribute | Shape |
| Light Specularity exponent | SPECULARITY_EXPONENT_ATTRIBUTE_NAME | FloatAttribute | Shape |
| Light Opacity | OPACITY_ATTRIBUTE_NAME | FloatAttribute | Shape |
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 an Obj using ShapeTools
The easiest way to to read an OBJ 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 Minc Obj file into a shape.
*
* @param objFilename name of an Obj file.
*
* @returns a Shape read from an Obj.
* throws IOException if unable to read the Ob.
*/
public Shape read(String objFilename)
{
ShapeToolsReader reader = new ShapeToolsReader();
Shape objShape = reader.readShape(objFilename);
return objShape;
}
}
An alternative to using the ShapeToolsReader.readShape() methods is use
the method in the edu.ucla.loni.ccb.shapeio.minc.MincIO class.
The ImageInputStream needed to read binary OBJ may be easily created by :
edu.ucla.loni.ccb.shapeio.ShapeInputStream.getStream(String filename)
Getting data from an OBJ 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();
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 an OBJ 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();
}