This guide is an introduction to how the CCB ShapeTools library may be used to read, alter and write write Laboratory of Neuro-Imaging (LONI) Universal Contour Files (UCF's). It is necessarily incomplete, both with respect to use with Ucf files, and as regards the capabilities of the ShapeTools library. For more complete documentation please see the online ShapeTools Documentation
Version:The programming examples in this
this document refer to ShapeTools version 1.1.0
There are two examples in this section. The first uses shows the easiest way to get the coordinates of a Ucf's points. The second example summarizes how to read a ucf into a Shape, how to change the data values of that shape, and how to write the changed shape into a Ucf file. Please note that these methods are specific to UCF files - they do not apply to Shapes read from other geometry file formats. Additional details of how to write programs using ShapeTools are in the examples below.
| comment | code |
|---|---|
| Get the coordinates of the UCF points as a coordinate array |
import edu.ucla.loni.ccb.shapeio.ucf.UcfUtility; import java.io.IOException; String ucfFileName = "file.ucf"; try { float[][] coordinates = UcfUtility.readUcfCoordinates(fileName) } catch ( IOException) { } |
Complete example code is here.
| comment | code |
|---|---|
| import java classes. |
import edu.ucla.loni.ccb.shapeio.ucf.UcfIO; import edu.ucla.loni.ccb.shapeio.ucf.UcfUtility; import edu.ucla.loni.ccb.shape.Shape; import edu.ucla.loni.ccb.shape.geometry.InappropriateGeometryException; import java.io.IOException; |
| Read ucf as a set of unconnected contours. |
Shape shape=null; String ucfFileName = "file.ucf"; try { // read ucf shape = UcfIO.read(ucfFIleName); |
| Get the 4D Ucf Data component |
// get 4d Values if they exist. float [] dataValues = UcfUtility.getDefaultAttributeValues(shape); if (dataValues = null) { |
|
Change the 4D Ucf Data Component. and reset the ucf shape data value |
// change dataValues here... // set 4d attribute to changed values UcfUtility.setDefaultAttributeValues(shape,dataValues); |
| Write the changed UCF |
UcfIO.write(shape,args[1],true); |
| End of "if (hasAttribute())" if statement |
} } catch (InappropriateGeometryException ige) { System.exit(1); } catch (IOException e) { System.exit(1); } // end of example 2 |
The ShapeTools library is a collection of Java classes which enable Java programmers to model geometric shapes and associated data. The library is organized into several java packages, enabling programmers to use only those portions of the library requried for their needs. Most of the key classes are defined as Java interfaces. This enables programmers to easily create specialized versions of a class as needed.
The packages are:Note that SolidSets, FaceSets and EdgeSets require the existence of a hierarchy of components: an EdgeSet requires a PointSet, a FaceSet requires both a PointSet an EdgeSet, and so on. The collection of other shapes allows construction of complex shapes from primitive shapes.
The ucf Shape is created with several standard attributes that store the data found in a Ucf file's header clauses. These attributes are used by ShapeTools to correctly write a shape into a Ucf formatted file. These are stored in the Shape's AttributeSet (4d data values are stored in the PointSet's AttributeSet).
These metadata may be usefule to other applications that use data read from Ucf files.
import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shape.attributes.AttributeSet;
import edu.ucla.loni.ccb.shape.attributes.FloatArrayAttribute;
import edu.ucla.loni.ccb.shapeio.ucf.UcfIO;
import edu.ucla.loni.ccb.shapeio.ucf.UcfShapeImpl;
// return if not a Ucf
if (!(shape instanceof UcfShapeImpl) {
return;
}
// get the level number of a ucf
// from it's attribute set
AttributeSet attrs = shape.getAttributeSet();
String levelNumberAttrId = UcfIO.LEVEL_NUMBERS;
if (attrs.hasAttribute(attrId)){
// not a valid ucf shape
return;
}
FloatArrayAttribute levNum =
(FloatArrayAttribute)attrs.getAttribute(levelNumberAttrId);
// get number of level 0
int levelNumber0 = levNum.getFloat(0);
// get all level numbers as in array
int [] levelNumbers = levNum.get();
These attributes described in the following table; some are required if the Shape is written as a Ucf file. Optional attributes are used when written if present. If not found their values are calculated from the cooordinates of the Ucf points. Please see javadoc notes on the class UcfIO for details.
| Ucf Header Element | Header description | UcfIO class constant |
Attribute ID (value of UcfIO class constant ShapeTools v1.1.0) |
Attribute Type | Required ? |
|---|---|---|---|---|---|
| N/A | LEVEL_START_VERTICES | Name of attribute holding vertex indices that begin a ucf contour | startVertexIndices | IntArrayAttribute | True |
| N/A | LEVEL_END_VERTICES | Name of attribute holding vertex indices that end a ucf contour | endVertexIndices | IntArrayAttribute | True |
| N/A | LEVEL_NUMBERS | Name of the attribute created to hold the level numbers of the ucf levels | levelNumbers | FloatArrayAttribute | True |
| xrange | X_RANGE | Name of the attribute created to hold the x range of the ucf | xrange | FloatArrayAttribute | False |
| yrange | Y_RANGE | Name of the attribute created to hold the y range of the ucf | yrange | FloatArrayAttribute | False |
| zrange | Z_RANGE | Name of the attribute created to hold the z range of the ucf | zrange | FloatArrayAttribute | False |
| zrange | WIDTH | Name of the attribute created to hold the pixel width of the ucf | width | IntAttribute | False |
| height | HEIGHT | Name of the attribute created to hold the pixel height of the ucf | height | IntAttribute | False |
A Ucf is defined as a collection of lines (contours), embedded into a 3 dimensional space. These contours are independent of each other.
Ucf's may be read either
String fileName = "myUcfFile.ucf";
try {
Shape ucf = UcfIO.readContourGroup(fileName);
} catch (IOException e) {
// unable to read file
}
// get contours
Shape [] contours = shapes.getChildren();
// get points of a level
IPointSet points = contours[2].getVertices();
String fileName = "myUcfFile.ucf";
try {
Shape ucf = UcfIO.read(fileName);
} catch (IOException e) {
// unable to read file
}
String fileName = "myUcfFile.ucf";
try {
Shape ucf = UcfIO.read(fileName,true);
} catch (IOException e) {
// unable to read file
}
String fileName = "myUcfFile.ucf";
try {
Shape ucf = UcfIO.read(fileName);
} catch (IOException e) {
// unable to read file
}
Many LONI files use a variation of a Ucf known as a "4D" ucf. These store an additional data value for each point. Each ucf point therefore contains 4 numbers (x,y,z) and the value of a data field sampled at that ucf point. If these values are present in a ucf the data values are stored into the Shape's PointSet in a FloatArrayAttribute whose attribute id is set to a predetermined value. This attribute id is needed to retrieve the attribute, and may be found by using
String attributeId = UcfIO.getDefaultDataAttributeId()
As a convenience to the Ucf Programmer the following method retrieves the 4d data directly:
float [] data4DValues = UcfUtility.getDefaultAttributeValues(shape);
AttributeSet attrs4d = shape.getPoints().getAttributeSet();
It is common to write a program with the following structure:
Change the ucf 4d data values:
float [] newValues = createNewValues();
// change the 4d ucf attribute values to those in newValues
UcfUtility.setDefaultAttributeValues(shape, newValues);
Write the ucf and the default data attribute
Shape shape;
String fileName = "changedUcf.ucf";
boolean writeDefaultAttribute=true;
UcfIO.write(shape, fileName, writeDefaultAttribute);
A simple program illustrating use of these methods is here
|
/** * This program illustrates use of ShapeTools * to read, change and write a 4D Ucf file. * * @version 19 July 2005 */ import edu.ucla.loni.ccb.shape.Shape; import edu.ucla.loni.ccb.shape.Version; import edu.ucla.loni.ccb.shapeio.ucf.UcfIO; import edu.ucla.loni.ccb.shapeio.util.UcfUtility; import edu.ucla.loni.ccb.shape.geometry.InappropriateGeometryException; import java.util.Random; import java.io.IOException; public class Illustrate4dUcf { public static void main(String [] args) { // Check for compatible ShapeTools library version if(Version.getMajorVersionNumber() = 1){ System.err.println("Incompatible ShapeTools library version"); System.exit(1); } // check for required command line arguments if(args.length < 2){ System.err.println("Usage: System.exit(1); } Shape shape=null; String ucfFileName = args[0]; //Read a Ucf File as a surface, if possible try { // read ucf as grid connected surfaces shape = UcfIO.read(ucfFileName,true); } catch (IOException e) { System.err.println("Unable to read ucf: " + ucfFileName); System.exit(1); } // get the 4d data values float [] values = UcfUtility.getDefaultAttributeValues(shape); // create a random number generator Random random = new Random(); // randomize 4d data values for (int i=0;i < values.length; i++) { values[i] = random.nextFloat(); } //set Shapes Ucf 4d data value to changed values UcfUtility.setDefaultAttributeValues(shape, values); String changedFileName = args[1]; boolean writeDefaultAttribute=true; try { UcfIO.write(shape, changedFileName, writeDefaultAttribute); } catch (InappropriateGeometryException ige) { System.err.println("Illegal ucf " + ige.getMessage()); } catch (IOException e) { System.err.println("Unable to write new ucf: " + changedFileName); } } } |
|
//Read a Ucf File import edu.ucla.loni.ccb.shapeio.ucf.UcfIO; import edu.ucla.loni.ccb.shape.Shape; import edu.ucla.loni.ccb.shape.geometry.IPointSet; Shape shape; String ucfFileName = "file.ucf"; try { // read ucf as grid connected surfaces shape = UcfIO.read(ucfFIleName); } catch (IOException e) { } //Get the Ucf Points and the spatial coordinates of the points. // Read points from ucf shape IPointSet points = shape.getVertices(); } |
Read a Ucf file. a it's 4d data value if it exists. Change each 4d data value to the average of the vertex coordinate positions and write the new Ucf with changed 4d values as a separate ucf.
import java.io.IOException;
import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shape.geometry.IPointSet;
import edu.ucla.loni.ccb.shape.geometry.InappropriateGeometryException;
import edu.ucla.loni.ccb.shape.math.ArithmeticAverage;
import edu.ucla.loni.ccb.shapeio.ucf.UcfIO;
import edu.ucla.loni.ccb.shapeio.util.UcfUtility;
/**
* ShapeTools Ucf Programmer's Guide
* QuickStart Example 2
*
* Changes ucf 4d data values and writes
* them into a ucf file.
*
* @version 18 July 2005
*/
public class QuickStart2
{
/**
* Read a ucf and write an average of ucf positions as 4d data.
*
* @param args command line arguments to this class (ucf filenames)
*/
public static void main(String[] args)
{
if (args.length < 2) {
usage();
System.exit(1);
}
Shape shape=null;
String ucfFileName = args[0];
/* Read Ucf Read ucf as a set of unconnected contours. */
try {
// read ucf
shape = UcfIO.read(ucfFileName);
/* Get the 4D Ucf Data component */
// get 4d Values if they exist.
float [] data4DValues = UcfUtility.getDefaultAttributeValues(shape);
if (data4DValues != null) {
/* Get the Ucf Points and the spatial coordinates of the
points as a coordinate array
*/
// Read points from ucf shape
IPointSet points = shape.getVertices();
// get point coordinates
float [][] coordinates = points.getPoints();
/* Change the 4D Ucf Data Component.
This example sets each data component to
the average of the coordinate values
of it's corrosponding Ucf vertex.
*/
// create an Average that performs arithmetic averaging
ArithmeticAverage avg = new ArithmeticAverage();
// change the 4d data values
for(int dataIndex=0;dataIndex < data4DValues.length;dataIndex++) {
// get coordinates of the vertex corrosponding
// to this data value
float [] vCoords = new float[3];
vCoords[0] = coordinates[0][dataIndex];
vCoords[1] = coordinates[1][dataIndex];
vCoords[2] = coordinates[2][dataIndex];
// average them
data4DValues[dataIndex] = avg.average(vCoords);
/*
* Replace the 4d data with the changed 4d data
*/
UcfUtility.setDefaultAttributeValues(shape, data4DValues);
/* Write the changed UCF /
*/
UcfIO.write(shape,args[1],true);
}
/*
End of "if (hasAttribute())" if statement
*/
}
} catch (InappropriateGeometryException e) {
System.exit(1);
} catch (IOException e) {
System.exit(1);
}
// end of example 2
}
public static void usage()
{
System.out.println("Usage: java -classpath lib.jar QuickStart2 Input.ucf Output.ucf");
}
}
|
To create a Shape that may be written as a Ucf use one of the following three methods in the UcfUtilty class:
1) This method is the simplest of three. It takes as an argument a 3 dimensional float array. The first dimension of the array is the level index, the second the coordinate dimension or data value, and the last the vertex index (within the level). The width and height of the constructed ucf are integer equivalents of the extrema of coordinate dimensions 0 and 1. Level numbers are float equivalents of the integers from [0]..[number of levels].
2) The second method is the most flexible. You provide the method with the width and height values needed by the Ucf, an array of level numbers, the number of vertices in each of the levels, an array of vertex coordinates, and , optionally, an array of floats that will be used to create the Ucf "4d" values. If you do not want to create a 4D Ucf then use "null" as this parameter.
3) This is nearly identical to the second method, except that the vertices are specifiiced using an IPointSet instead of a float [][] array.
import java.io.IOException;
import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shape.attribute.AttributeLengthException;
import edu.ucla.loni.ccb.shape.geometry.InappropriateGeometryException;
import edu.ucla.loni.ccb.shapeio.ucf.UcfIO;
import edu.ucla.loni.ccb.shapeio.util.UcfUtility;
/**
* ShapeTools Ucf Programmer's Guide
* CreateUcf
*
* Creates a Shape that may be written as a Ucf file.
*
* @version 21 July 2005
*/
public class CreateNewUcf
{
/**
* Create a Shape that represents a simple 4x3 grid and write it as a Ucf.
*
* @param args
* command line arguments to this class (ucf filenames)
*/
public static void main(String[] args)
{
if (args.length < 1) {
System.out.println("No output file name.");
System.exit(1);
}
// create a grid of 4 points across and 3 points high.
// the grid is tilted backwards, that is, the bottom row (row 0)
// has z = 1, the top row has z = 2
// Note: a total of 12 points are defined here
float[] xCoordinates = { 0.0f, 1.0f, 2.0f, 3.0f, // row 0
0.0f, 1.0f, 2.0f, 3.0f, // row 1
0.0f, 1.0f, 2.0f, 3.0f // row 2
};
float[] yCoordinates = { 1.0f, 1.0f, 1.0f, 1.0f, // row 0
2.0f, 2.0f, 2.0f, 2.0f, // row 1
3.0f, 3.0f, 3.0f, 3.0f // row 2
};
float[] zCoordinates = { 1.0f, 1.0f, 1.0f, 1.0f, 2.0f, 2.0f, 2.0f,
2.0f, 3.0f, 3.0f, 3.0f, 3.0f };
float[][] coords = new float[3][];
coords[0] = xCoordinates;
coords[1] = yCoordinates;
coords[2] = zCoordinates;
// create level numbers for the three levels
float[] levelNumbers = { 1.5f, 2.5f, 5.5f };
// set number of vertices in each level
int[] counts = { 4, 4, 4 };
// create a 4D data componenet -
// one value per vertex
float[] vertexDataValues = { 0.0f, 1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f,
7.0f, 8.0f, 9.0f, 10.0f, 11.0f };
// create a shape with attributes that will allow it to be written as a
// Ucf
Shape shape = null;
try {
shape = UcfUtility.createUcfShape(true, 256, 256, levelNumbers, counts,
coords, vertexDataValues);
} catch (AttributeLengthException ale) {
} catch (InappropriateGeometryException ige) {
}
String ucfFileName = args[0];
// Write the shape as a UCF
try {
UcfIO.write(shape, args[0], true);
} catch (InappropriateGeometryException e) {
System.exit(1);
} catch (IOException e) {
System.exit(1);
}
}
}
|
javac -classpath ShapeTools_19_Jul_2005_complete.jar Illustrate4dUcf.java
java -classpath ShapeTools_19_Jul_2005_complete.jar:. Illustrate4dUcf sample.ucf Output.ucf
Unable to read ucf: filename.ucf
The following simple ucf file has 4 levels and has one ucf 4d data value.
<width=> 256 <height=> 256 <xrange=> 51.0 133.0 <yrange=> 125.0 149.0 <zrange=> 48.0 70.0 <levels> 4 <level number=> 0.0 <point_num=> 5 <contour_data=> 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.1 2.0 0.0 0.0 0.2 3.0 0.0 0.0 0.3 4.0 0.0 0.0 0.4 <end of level> <level number=> 1.1 <point_num=> 5 <contour_data=> 0.0 1.0 0.0 1.0 1.0 1.0 0.0 1.1 2.0 1.0 0.0 1.2 3.0 1.0 0.0 1.3 4.0 1.0 0.0 1.4 <end of level> <level number=> 2.2 <point_num=> 5 <contour_data=> 0.5 2.0 0.0 2.0 4.5 2.0 0.0 2.1 6.5 2.0 0.0 2.2 8.5 2.0 0.0 2.3 10.5 2.0 0.0 2.4 <end of level> <level number=> 3.3 <point_num=> 5 <contour_data=> 1.0 3.5 4.0 -3.0 2.0 3.5 4.0 -3.1 9.0 3.5 4.0 -3.2 10.0 3.5 4.0 -3.3 11.0 3.5 4.0 -3.4 <end of level> <end>
Please see ShapeTools JavaDoc documentation for complete details.
| comment | code |
|---|---|
|
Get a point set from a Shape |
import edu.ucla.loni.ccb.shape.Shape; import edu.ucla.loni.ccb.shape.geometry.IPointSet; Shape shape = yourCreateShape(); IPointSet points = shape.getVertices(); |
|
Get a number of vertices in shape's point set. Get dimensionality of points (Ucf are 3 dimensional). |
import edu.ucla.loni.ccb.shape.Shape; import edu.ucla.loni.ccb.shape.geometry.IPointSet; IPointSet points = shape.getVertices(); int numVertices = point.getNumPoints(); // get point dimensionality int numDimensions = point.getPointDimensions(); |
ShapeTools coordinate arrays are structured with the first array parameter being the dimension, and the second array parameter is the index of the point. As an example, suppose you have two 3 dimensional points in your universe. The first, p0, has coordinates (0,1,2), while p1 has coordinates (50,60,70). If these points are stored in an IrregularPointSet , and you wanted to get their coordinate values, you do this:
IrregularPointSet pts = shape.getVertices();
float [][] coordinates = pts.get
at this moment the contents of the array coordinates would be:
array position | array value
coordinates[0][0] | 0 (X coord, p0)
coordinates[1][0] | 1 (Y coord, p0)
coordinates[0][1] | 50 (X coord, p1)
coordinates[1][1] | 60 (Y coord, p1)
coordinates[2][1] | 70 (Z coord, p1)
that is, coordinates[0][?] refers to all the X coordinates, coordinates[1][?] has all the Y coordinates, and of course, coordinates[2][...] has the Z values.
You may ask "Why did we do this the hard way ? wouldn't it
be easier to define a Point class, and then make an array of points ?
Point [] points = new Point[1000] ;
The short answer is "performance".
On the other hand, in the schema used by IrregularPointSet, only 4 objects are needed - the 2d array (float [][]) and the three one dimensional arrays of floats.
When you have 100,000 points in your data arrays , performance issues begin to matter.
An additional benefit of the float[][] schema is that it handles any number of coordinate dimensions without changing your code: Here is a prototypical loop to iterate over every coordinate of every point in the point set:<
for (int dimension =0;dimension < coordinates.length; dimension++) {
for (int pointIndex = 0; pointIndex < coordinates[0].length;
pointIndex++) {
doSomethingWith
(coordinates[dimension][pointIndex]);
}
What are colloquially referred to as "4D" ucf's are more properly described as a ucf file with one extra data value associated with each ucf vertex. The ShapeTools library allows Ucf file to containing mulitple ucf data value attributes to be written and read.
At present only programs using ShapeTools library support multiple ucf data attributes.
Data attributes read from a ucf are automatically named by ShapeTools.
The names are composed of a base name and have a digit appended.
The data attribute name of the n'th data attribute column (n=0,1,...,N
with n increasing to the right) may be obtained by the UcfIO method
String attributeId = UcfIO.getDataAttributeId(n)
.
The data attribute values may then be obtained by
AttributeSet attr = shape.getVertices().getAttributeSet();
int n = 3; // get 4th data attribute column
FloatArrayAttribute myAttribute = attr.getAttribute(UcfIO.getDataAttributeId(n));
You may write any number of FloatArrayAttributes contained in a Shape's PointSet into a Ucf. The number of elements in the FloatArrayAttribute must match then number of vertices in the PointSet. You must explicitly name the attributes you want written to the Ucf.
// define data values
float unusedFloat = 1.23;
int unusedInt = 22;
float [] floatArrayOne = {1.0f,2.0f,3.0f};
float [] floatArrayTwo = {7.5f,8.5f,9.5f};
// create Attributes
FloatArrayAttribute faOne = new FloatArrayAttribute(floatArrayOne);
FloatArrayAttribute faTwo = new FloatArrayAttribute(floatArrayTwo);
FloatAttribute unusedFloatAttribute = new FloatAttribute(unusedFloat);
IntAttribute unusedIntAttribute = new IntAttribute(unusedInt);
// add Attributes to Shape's point set
AttributeSet pointAttributes = shape.getVertices().getAttributeSet();
pointAttributes.add("unusedFloat",unusedFloatAttribute);
pointAttributes.add("unusedInt",unusedIntAttribute);
pointAttributes.add("fa_1",faOne);
pointAttributes.add("fa_2",faTwo);
String outFileName = "out.ucf";
// name attributes to save
String [] attributesToWrite = new String[2];
attributesToWrite[0] = "fa_1";
attributesToWrite[1] = "fa_2";
// write the two attributes
UcfIo.write(shape, outFileName, attributesToWrite);
This example omits the exception handling needed to write(); please see the JavaDoc of ShapeTools UcfIO class for full details.