ShapeTools Ucf Programmer's Guide

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

Revision:Revised: 22 July 2005

Table of Contents

Quick Start

(table of contents)

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.

QuickStart Example 1 - Read Ucf Coordinates

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) {
}

QuickStart Example 2 - Read a Ucf, Change the data values, write the result

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

ShapeTools library overview

(table of contents)

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:

edu.ucla.loni.ccb.shape
Defines the Shape class. This is the central class of the ShapeTools library. It is essentially a placeholder for the geometrical components of a Shape and any associated data attributes.

edu.ucla.loni.ccb.shape.geometry
edu.ucla.loni.ccb.shapeio
Supports Input and Output of Shapes. Readers and Writers are provided for selected file formats.

ShapeTools library definitions

(table of contents)

Point
A Point is location in space. Points may be of any dimensionality. However, because UCF files use 3 dimensional points, the points stored in shape which have been read from a ucf are 3 dimensional. You can find the dimensionality of the points using PointSet methods . Each of a Shape's Points has a unique numerical id number. Points are not stored as separate objects in a Shape but are instead grouped into a PointSet

Edge
An edge is a line segment that connects two points. In the ShapeTools library, edges are directed: An edge that starts at point A and ends at point B differs from an edge starting at B and ending at A. Each of a Shape's Edges has a unique numerical id number. Edges are not stored as separate objects in a Shape but are instead grouped into a EdgeSet

Face
A Face is a polygon composed of Edges. Each Face has a unique numerical id number. Faces are not stored as separate objects in a Shape but are instead grouped into a FaceSet

Solid
A Solid is an collection of Faces. Each Solid has a unique numerical id number.

Attribute
An Attribute is an element of data that is associated with Shape or with a Shape's components. Attributes are used to store any data that is not geometrical information (Points,Edges, Faces or Solids). Each attribute must have a String identifier unique to the AttributeSet which stores that Attribute.

AttributeSets
An Attribute Set is a collection of Attributes. Only one AttributeSet may be associated with a Shape or a shape component at a time. Each shape component may have it's own attribute set. As an example, the set of a Shape's Points may have an AttributeSet containing data pertinent to the points, while the Shape object may have a different AttributeSet containing data that describes the shape as a whole.

PointSet
A PointSet is a collection of Points. A PointSet must provide the methods specified in the IPointSet interface. Various implementations of IPointSets exist. These allow a programmer to use an implementation of a set of points whose properties suit the programming task at hand. Of particular interset are PointSets that exploit knowledge of regular geometries (like a mesh) to provide enhance performance.

EdgesSet
An EdgeSet is a collection of Edges. EdgeSets must provide the methods specified in the IEdgeSet interface.

FaceSet
A FaceSet is a collection of Faces. FaceSets must provide the methods specified in the IFaceSet interface.

SolidSet
A SolidSet is a collection of Solids. SolidSets must provide the methods specified in the ISolidSet interface.

Shape
A shape is a data structure that may contain one or zero of each the following components:

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.

Shape ID
A string that identifies this shape.

(table of contents)

Ucf File Format Support

Ucf's are read into a specialized Shape class UcfShapeImpl. They are created with the following components:

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.

Getting the value of a Ucf Header Attribute


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

Table of Ucf Header Attributes

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 Shape Impl - Standard Shape Attributes

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

readContourGroup

Reading ucf files

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

  1. A set of vertices whose edge connections form disjoint lines.
  2. A set of vertices connected as a single, rectangular 2D connected surface.
  3. A collection of separate contours stored as children of a parent shape.
In this latter case the parent has no vertices of it's own. The contours are stored as separate Shapes which are children of the shape returned. Each child contour is assigned an id formed from the ucf level index (see method getAttributeId(int n).)

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

   

Reading the ucf as a vertices with disjoint line connections

String fileName = "myUcfFile.ucf";
try {
    Shape ucf = UcfIO.read(fileName);

} catch (IOException e) {
   // unable to read file
}

Reading the ucf as a rectangular 2d surface

The ucf vertices, edges and faces are associated directly with the Shape; e.g. no children. The "width"of the constructed surface is set to the length of the shortest contour level in the ucf. The contour vertices are connected in a rectilinear 2D grid. String fileName = "myUcfFile.ucf";

try {
    Shape ucf = UcfIO.read(fileName,true);
} catch (IOException e) {
   // unable to read file
}

Reading the ucf as a a collection of separate contours


String fileName = "myUcfFile.ucf";
try {
    Shape ucf = UcfIO.read(fileName);
} catch (IOException e) {

   // unable to read file
}

Reading 4D Ucf files

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

Writing 4D Ucf files

Modifying an existing 4D ucf Shape

It is common to write a program with the following structure:

  1. Read a 4D ucf
  2. Change the 4D parameter values
  3. Write a new ucf with the changed 4D values.
The following two convenience methods simplify this procedure:

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

ShapeTools Ucf Programming Examples

(table of contents)

Changing the 4D Ucf data values with ShapeTools

/**
* 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: in.ucf out.ucf");

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

  }
 }
}

Reading Ucf files with ShapeTools

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

QuickStart Example #2

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

Creating Ucf Compatible Shapes

To create a Shape that may be written as a Ucf use one of the following three methods in the UcfUtilty class:

  1. createUcfShape(float [][][] coordinates);
  2. createUcfShape( boolean surface, int width, int height, float[] levelNumbers, int [] levelCounts, float[][] coords, float [] vertexData);
  3. createUcfShape( boolean surface, int width, int height, float[] levelNumbers, int [] levelCounts, IPointSet points, float [] vertexData);

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.

Notes on parameters of createUcfShape()

surface

Ucf's are often interpreted as a the vertices of a 2D connected surface. Because a Shape contains the connections (edges) between vertices, this distinction (surface, or a collection of polylines) must be decided when the Shape is constructed. If the Shape is constructed as a surface grid it must contain the same number of vertices in each level. If this condition is not met an InappropriateGeometryException is thrown. the createUcfShape(float [][][]) method does not support surface grid connections.
width
An integer describing the width, in pixels, of the space in which the Ucf exists. This value is sometimes used by programs that read Ucf files to provide context for the ucf points. It is not used by the ShapeTools library.
height
An integer describing the height, in pixels, of the space in which the Ucf exists. This value is sometimes used by programs that read Ucf files to provide context for the ucf points. It is not used by the ShapeTools library.
levelNumbers
An number associated with a Ucf level. It's meaning is somewhat arbitrary. Some programs that read Ucf files use the level as a way to spatially order the contours contained in a file. This number is often identical to the coordinate of the drawing plane (Z value). It should be noted that this is only a convention common to several drawing programs which write their output as Ucf files, and is not part of the formal definition of a Ucf. Tools should not assume that sucessive level numbers increase in value, nor should they assume that contours in adjacent levels are drawn in parallel planes, or, for that matter, that the contours of a level lie in any plane at all. Level Numbers are not used by the ShapeTools library.
levelCounts

The number of vertices in the level. The vertices are assumed to be in the coordinate arrays (or IPointSet) in order of their appearance in the various levels. Levels may, and usually will, have different numbers of vertices. Thus, if there are 95 vertices in level 0, and 44 vertices in level 1, the first two values in the levelCounts array will be 95 and 44. The total of all levelCounts values must equal the total number of vertices in the entire Shape.
xrange, yrange and zrange
The header of a Ucf file contains 3 attributes not found in the various createUcfShape() methods. These describe the range of spatial coordinates spanned by the points. These values are calculated when the Shape is written to a Ucf file. If you wish to specify these values you may do so by adding the appropriate FloatArrayAttribute to the Shape's AttributeSet. The required names of these attributes may be found in the variables UcfIO.X_RANGE, UcfIO.Y_RANGE and UcfIO.Z_RANGE.

Example Code

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

For new Java programmers

(table of contents)

Compiling and running a java program

  1. save the "Illustrate4dUcf" example (above) into a file named Illustrate4dUcf.java

  2. Locate or download a complete shape tools library jar .
    Make sure it is has as date newer than 18 July 2005. In our example, we use the 19 July 2005 release, "ShapeTools_19_July_2005_complete.jar".
  3. Compile the program with this javac command line:
    javac -classpath ShapeTools_19_Jul_2005_complete.jar Illustrate4dUcf.java
    You should now have a file named Illustrate4dUcf.class .
  4. Obtain a Ucf file. If you don't have on, use the sample ucf file.

  5. Run the program
    java -classpath ShapeTools_19_Jul_2005_complete.jar:. Illustrate4dUcf sample.ucf Output.ucf

  6. Use a text editor (or, on Unix, the more program) to find the differences between the two files. You should find that the 4D data values have (randomly) changed.
    If your ucf file does not contain a 4D ucf parameter you will see this error message:

    Unable to read ucf: filename.ucf

A sample Ucf file

(table of contents)

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>

Some ShapeTools PointSet methods

(table of contents)

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

(table of contents)

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[2][0] | 2 (Z 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".

Yes,the Point [] might be a bit easier to use in a program, but it uses a lot of memory,and creates many java objects. In the Point [] example a total of 1001 java objects are allocted - 1 array, and 1000 points.

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

}

Ucf Advanced Topics

(table of contents)

Reading and Writing Ucf files containing more than one data attribute

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.

Reading multiple data attributes from a Ucf

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

Writing multiple data attributes to a Ucf

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.


Craig Schwartz, UCLA Laboratory of Neuro-Imaging