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
default color is applied to all vertices.
- 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
- ) Get, and unpack the SurfStat package onto your computer.
- ) Copy the ShapeToolsReadSurf1.m file into the directory containing the SurfStat files (you may download it from this web page).
- ) 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).
- ) start your Matlab interpreter from the directory containing the SurfStat files.
- ) 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
- 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');
- ) 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.
- ) Replace use of the SurfStatReadSurf1 function with the ShapeToolsReadSurf1 function:
- ) locate the file SurfStatReadSurf.m
- ) make a copy of this file, named, for example: SurfStatReadSurfOriginal.m
- ) edit SurfStatReadSurf.m.
- ) on lines 64 and 106 replace SurfStatReadSurf1 by ShapeToolsReadSurf1
- ) save your changes and exit your editor.
- ) use SurfStat normally.
Using ShapeTools with Matlab
| 