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:

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:

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