mShape - An interface to ShapeTools from within Matlab

Using ShapeTools with SurfStat : A Case Study

Objective: Increase the number of surface file types that can be analyzed with SurfStat

Overview

SurfStat is a Matlab toolbox for the statistical analysis of univariate and multivariate surface data, written by Keith J. Worsley, of McGill University. The matlab source code can be easily modified to use the ShapeTools surface readers, allowing application of SurfStat toolbox analyses to all the suface file formats supported by ShapeTools.

Reading SurfStat surfaces with ShapeTools - a simple replacement

In the SurfStat toolbox, surface data is read by the file SurfStatReadSurf1.m . This matlab function reads the vertices of a file surface, for later analysis by the SurfStat toolbox. The SurfStatReadSurf1 matlab function can be replaced with about eleven lines of (matlab) code that use the ShapeTools library to identify and read a surface from a data file.

The following example shows how to use ShapeTools to read a surface file:

% specify file containing a surface

filename='yourSurfaceFile.obj';

% tell Matlab where to find the !ShapeTools java classes
javaaddpath('ShapeTools.jar');

% replace SurfStat code

s = SurfStatReadSurf1(filename);

% with ShapeTools reader. 

% Load Java Classes
import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shapeio.util.ShapeToolsReader;
import edu.ucla.loni.ccb.shape.geometry.IPointSet;
import edu.ucla.loni.ccb.shape.math.MatrixMath;

% read shape
shape = ShapeToolsReader.readShape(filename);

% reformat vertices to Matlab / SurfStat conventions
shapeCoords = shape.getVertices().getPoints();
surf.coord  = MatrixMath.transpose(shapeCoords);

% free temporarily used memory
clear shapeCoords 

A complete example: ShapeToolsReadSurf1

The SurfStat function SurfStatReadSurf1 does more than read surface vertices. In addition to these, it may also return:

• surface vertex normals
• vertex colors
• surface face triangulations.
• whether the surface file format is binary or ascii.

Because many surface file format do not include normals and colors, and may not even be composed of triangular surface facets, adding more supported file formats to the SurfStat package is not a trivial undertaking. However, use of the ShapeTools library to accomplish these tasks made it possible to write a ShapeTools based matlab function, ShapeToolsReadSurf1, in about an hour.

This function will read any ShapeTools compatible file format. Surface vertex coordinates returned in all cases. If requested by the user, some or all of the following actions are performed:

• Surface normals are computed at each vertex
• Each vertex's color is read, f supported by the file format. If the file format does not supply vertex colors, a

• The surface triangulation is returned. If the surface is composed of rectangles (e.g. LONI UCF), the surface is triangulated and these triangulations are used.

If the file format is not recognized by ShapeTools, an error message is printed and the function returns without setting the value of the surface.

Using ShapeToolsReadSurf1

1. ) Get, and unpack the SurfStat package onto your computer.

1. ) Copy the ShapeToolsReadSurf1.m file into the directory containing the SurfStat files (you may download it from this web page).
2. ) Download a copy of ShapeTools and copy the file 'ShapeTools.jar' into the directory containing the SurfStat files (However, you can avoid having to do so via step 5b, below).
3. ) start your Matlab interpreter from the directory containing the SurfStat files.
4. ) type javaaddpath('ShapeTools.jar'); into your matlab interpeter (note 'ShapeTools.jar' must be a locally valid file system path to the ShapeTools.jar file).m
5. a) Alternatively, you may instruct matlab to read the ShapeTools.jar from our website, by typing
   javaaddpath('http://www.loni.ucla.edu/~shapetls/bin/ShapeTools.jar');
6. ) test whether ShapeToolsSurfRead1 works, by typing, into your matlab interpreter:

 s=ShapeToolsReadSurf1('cube.obj')

You should see something like the following output:

>> s=ShapeToolsReadSurf1('cube.obj')

s = 

     coord: [8x3 single]
    normal: [8x3 single]
      colr: [8x4 single]
       tri: [12x3 double]

This indicates that the ShapeToolsReadSurf1 matlab function has created a surface containing vertex coordinates, surface normals, vertex colors and the face triangulation.

1. ) Replace use of the SurfStatReadSurf1 function with the ShapeToolsReadSurf1 function:
   1. ) locate the file SurfStatReadSurf.m
   2. ) make a copy of this file, named, for example: SurfStatReadSurfOriginal.m
   3. ) edit SurfStatReadSurf.m.
   4. ) on lines 64 and 106 replace SurfStatReadSurf1 by ShapeToolsReadSurf1
   5. ) save your changes and exit your editor.
2. ) use SurfStat normally.

Using ShapeTools with Matlab

Requirements

Frequently Asked Questions

• Matlab does not recognize ShapeTools

How to set it up

• Ensure java 1.4 or greater is used by your Matlab Java Virtual Machine.
• Add the ShapeTools library Jar file to your Matlab installation classpath (See above for details).

See the Matlab web site for details.

You can then use ShapeTools directly in your matlab interpeter.

Example Usage of ShapeTools from within Matlab

• Create a Matlab shape using the matlabTriangulation method.
• Use the ShapeTools library and viewer to read and display a file's vertices.

• ShapeToolsSurfStat.zip: Contains Matlab files needed to use ShapeTools.jar with SurfStat

Attachment	Action	Size	Date	Who	Comment
ShapeToolsSurfStat.zip	manage	6.8 K	11 Sep 2008 - 23:18	CraigSchwartz	Contains Matlab files needed to use ShapeTools?.jar with SurfStat?