Shape Tools - File Format Parser Programmers Guide

Purpose This guide describes how a Java programmer may write a file format parser that reads a geometrical shape into a ShapeTools data structure whose internal values are consistent with the expectations of the elements of the ShapeTools library.

Version This guide applies to ShapeTools version 1.5.0

Revision: 4 October 2010

Introduction

This programming guide shows how to write Java classes that read geometrical data from a file into a ShapeTools library Shape class. It covers the essential components needed to create a Shape, programming conventions expected by other classes in the library, and the varieties of the components available as of this writing with which a Shape may be constructed. A simple example is used to illustrate the concepts herein described.

Back to Table of Contents


Overview

ShapeIO Framework

The ShapeTools library supports several file formats in which shape information may be stored, and it is expected that the number of supported formats will grow with time. That, after all, is the purpose of this programmer's guide. The ShapeIO framework defines a group of classes and interfaces which, if implemented for a file format parser, enable the ShapeTools library to determine which file reader is appropriate for a particular file at runtime. This capacity adds great power to the application developer, as they are freed from having to limit their application to a specific group of supported files.

This framework is analagous to, and based on the Java ImageIO framework, and uses some methods from the ImageIO package. Many of the classes that must be created may be copied, with modest changes, from an example. The bulk of the original work requried of a programmer is to write a method which, given an ImageInputStream, will read enough of the streams contents to determine if the stream contains the file format for which the parser is being written, and then return (rewind) that stream to it's state prior to the method being called. The method must have one of these signatures:

More information on useing the ImageIO classes my be found in the Sun website ImageIO Guide

The association between a FileFormatProperties class and a particular file format plugin is created when the plugin is registered to the ShapeIORegistry.

Shape Components

A ShapeTools Shape is composed of several pieces which collectively store the information that defines a geometrical shape and the data associated with it. Most of these pieces are optional. The complete list of a Shape's components is:

Attributes
An optional collection of data attributes associated with the shape as whole. These are stored in an AttributeSet.
Child Shapes
An optional collection of Shapes which are related to this Shape as child nodes. Use of child shapes allows a shape to be composed of a tree hierarchy.
IPointSet
A ShapeComponent that contains the coordinates of all vertices from which this shape is composed. This component is almost always present, except in the case where a Shape is used only to contain child shapes, or shape attributes, or both.
IEdgeSet
An optional ShapeComponent that contains the connections between the vertices. An edge set must refer to a set of points, hence, the presence of an edge set requires existence of a point set.
IFaceSet
An optional ShapeComponent encoding how the edges of a shape are collected into a set of faces. Face sets refer to an edge set and so the presence of a face set implies the presensce of both edge and point sets both of which should be associated with the shape.

Shapes also have a string "id" associated with them.

Attributes

The Attributes of a shape store all the information that is neither Face, Edge, Vertex nor child shapes. The term "metadata" is frequently used to refer to this class of information. The varieties of shape metadata are limitless; some examples are:

Child Shapes

Shapes may be composed of other shapes, organized as a tree. This allows an application programmer the flexibility to refer to portions of a complex shape as a single entity. An example might be a parent "Brain" shape that contained as children a cortex, hippocampus and so forth. The use of child shapes is optional, and unconstrained, except that no two child shapes may have the same 'id' value. This constraint ensures that a tree of shapes may be unabigously navigated. Note that most ShapeTools methods are not aware of child shapes. A useful utility method which is aware of a shape's children is the method edu.ucla.loni.ccb.shape.util.ShapeUtility.flatten(), which reorganizes the children of a shape, and their descendants, into List.

Documentation

Writers of ShapeIO classes are advised to ensure that their class documentation is comprehesive enough to allow users of that class to extract both shape data(points, edges, faces) and metadata from the shape. Classes that do not include this information have limited utility to any except the programmer of that class. ShapeTools classes are documented according to JavaDoc conventions, with special attention to the following:

Class documentation should include a complete description of :

It is useful to imagine yourself in the position of someone trying to use your method without having access to the source code. Your documention must provide enough detail and examples of proper usage to allow an application programmer to correctly write code that uses your class. Examples of proper usage are encouraged.

ShapeIO Class Conventions

When adding support for a file format to the ShapeTools library observance of a few conventions will simplify use of your format.

Classes that read the files are expected to be in a java package whose parent is the edu.ucla.loni.ccb.shapeio package.

This package is expected to contain the following classes and sub-packages:

A FormatIO class
Extends the class edu.ucla.loni.ccb.shapeio.ShapeIO. Provides basic read(), write() and validate() methods.
A plugin sub-package
Contains the ShapeIO classes (see above) which implement the readers and writers of the file format.
A format specific FileFormatProperties class
describes the capabilities of a file format and where commonly used data elements are stored in the Shape used by the file format reader and writer.
An instance of the IShapePreparer class
modifes a shape, before writing, to ensure that the requirements of the file format ShapeWriter are met.

Example for the hypothetical Foo file format used elsewhere in this guide.

All classes related to reading and writing Foo format files will be found in the package edu.ucla.loni.ccb.shapeio.foo. Within this package, a class FooIO will provide simple access to the readers and writers contained in the foo.plugin subpackage.

The ShapeIO parent class defines the following methods. You should probably override these in your implementation of *FooIO*

public Shape read(DataReader reader)
reads a Shape from an DataReader.
public Shape read(ImageInputStream iis)
reads a Shape from an ImageInputStream
public Shape read(InputStream is)
reads a Shape from an InputStream
pubilc static void validate()
Used to determine if a Shape may be written to the supported file format. This is where you may verify that any attributes required by the file format exist in the shape. If the shape may be written this method does nothing. The default implementation of this method (in class ShapeIO) only checks for a null Shape).


import edu.ucla.loni.ccb.shape.data.DataReaderWriterFactory;
import edu.ucla.loni.ccb.shape.data.DataReader;

public class FooIO extends ShapeIO
  {
    /**
      * Read a Foo format file from an unspecified object. 
      * The Progress Notifer will be periodically updated to communicate how much of the read operation has been completed.
      * Any object type supported by the DataReader library will be read.
    */
    public Shape read(Object source, IProgressNotifier progress)
      {
        DataReader reader = DataReaderWriterFactor.getDataReader(source);
        return read(reader,progress);
      }  
  }

Back to Table of Contents

ShapeWriterSPI requirements and notes

ShapeReaderSPI requirements and notes

Component Classes

All ShapeTools shape components are defined as Java interfaces. This allows a wide variety of interoperable components to be written, with particular implementations designed to optimize performance according to the specifics of a file format or application need. The following tables enumerate the implementations available in the current version of the ShapeTools library. If an implementation does not suit your needs, or if you, as the author of the file parser, know of characteristics particular to your application , we encourage you to write additional implementations. If you do, and you think someone else might benefit from your implmentation, please let us know about it so we can improve the ShapeTools library by it's inclusion. Below are listed attribute implementations of point, edge and face sets of particular interest to a programmer writing shape file parsers.

IPointSet

IrregularPointSet
The most general point set class. All coordinate values are stored explictly, in float arrays of spatial coordinates.

IEdgeSet

IrregularEdgeSet
A general edge set class. All connections are explictly stored. Performs poorly for large numbers of edges.
ArrayEdgeSet
A simple , general edge set class. Inefficient use of memory restricts the utility of this class.
PolylineEdgeSet
Compactly encodes a set of edge connctions that model a group of polylines.
Rectangular2DGridEdgeSet
set of edge connctions that form a rectangular grid. Peformance is enhanced as connectivity is calculated, not stored. Addition and deletion of edges are disallowed.

IFaceSet

IrregularFaceSet
A general face set class. The numbers of edges composing faces are explicitly stored in this class.

ISolidSet

No implementations of ISolidSet have been implemented at this time.

Back to Table of Contents


Attribute Classes

All attribute classes implement the interface IAttribute. Several subtypes of attribute classes are implemented. Attribute classes have been implemented only as needed by the ShapeTools library programming; the astute reader who finds "obvious" implementations absent is invited to write these and contribute them to the ShapeTools library. Below are listed attribute implementations of particular interest to a programmer writing shape file parsers.

Object Attributes

ObjectAttribute
Stores an arbitrary Java object, as an attribute.

Scalar Attributes

FloatAttribute
Stores a single float number as an attribute.
IntAttribute
Stores a single integer as an attribute.

Array Attributes

These classes contain arrays of attributes.

ObjectArrayAttribute
Stores an array of arbitrary Java objects as an attribute.
IntArrayAttribute
Stores an array of integers as an attribute.
FloatArrayAttribute
Stores an array of floating point numbers as an attribute.
FloatTupleArrayAttribute
an array of floating point tuples, e.g. a 2-d array. Useful for storing RGBA color values, vertex normals and other attributes whose structure is a tuple of numbers.

Back to Table of Contents


Recommended Attributes

It is often necessary to determine the properties of a shape whose source and structure is not known in advance. ShapeTools library users will frequently need to determine if a shape component has a geometrical property and, if so, in what attribute that properties values are stored. For some commonly used shape properties the getCommonAttributeName() method of a ShapeComponent enable the user of a shape file to determine where to find the data attibute that contains one of these commonly used properties. This only works if the attribute names have previously been set (in the shapeio plugin) via the setCommonAttributeMethod().

ShapeComponent attributes presently supported are Colors and Normals.

Note: Astute readers will note the redundancies between the set/getCommonAttributes() methods and those discussed in the file format properties section. This redundancy is needed becuase not all shapes are created by reading a disk file.The programmer is requested to be tolerant of what appears to be nearly duplicate code.

Component Colors

If your shape contains pre-defined colors, for the shapes points, edges or faces, you may store the name of the data attribute containing the RGBA color data via the setCommonAttributeName() method.

Colors are represented in the ShapeTools library as an RGBA tuple of 4 float numbers whose values range between 0.0 and 1.0. Colors are generally stored in a FloatTupleArrayAttribute.

Example:

your shape specifies colors for each face of a shape surface. These colors are saved in a data attribute whose id is "myFaceColors". The following code will ensure that a user of your shape can find the color attributes.

FloatTupleArrayAttrbute colors = new FloatTupleArrayAttribute(rgbaColorArray); Shape shape ; // your shape
IFaceSet faces = shape.getFaces();
faces.setCommonAttributeName(ShapeComponent.COLOR_ATTRIBUTE,"myFaceColors");

Component Normals

ShapeComponents often have the normal vectors to the shape pre-computed, and stored in that shape component. An example of storing the id of the normal attribute of the points of a shape could be:

FloatTupleArrayAttrbute normals = new FloatTupleArrayAttribute(anArray); Shape shape ; // your shape
IPointSet points = shape.getVertices();
points.setCommonAttributeName(ShapeComponent.NORMALS_ATTRIBUTE,normals.getId());

FileType attributes

It is at times desireable for an application to determine from what type of file a shape was read. The FileTypes Attribute is an optional attribute which stores this information for certain commonly used file formats. The attribute ID that is expected, and the predefined attribute values are stored in the class shapeio.FileTypes. An example of their use follows:
// set FileType attribute to indicate this shape was read from an OFF file.
IntAttribute typeAttribute =
new IntAttribute(FileTypes.FileTypeAttributeID, FileTypes.DX );
AttributeSet attrSet = shape.getAttributeSet();
shape.getAttributeSet().addAttribute(typeAttribute);

Back to Table of Contents


File Format Properties

It is often necessary when reading and writing Shapes to know if the shape was created from data stored in a specific file format and, if so, the identity of that format. Most applications that write a shape to an output file will want the ability to write a shape whose data was read from an input file into an output file of the same type as the original data. To do so, the programmer needs to the ability to select the correct output writer. To allow this, the ShapeTools library suggests using an attribute of the Shape to store the type of file. This raises the question of what attribute to use - as all attributes must be named - and what values to store.

The FileTypes class defines a recommended attribute name, and a set of file types identifers , that are used by the ShapeTools plugins to store this information. The complete list of file type identifiers may be found in the javadoc descriptions fo the FileTypes class.

While using the data stored in a Shape it is often helpful to know if a Shape supports a particular geometrical property. An example is a shape viewing program that displays a shape in color. Such a program would like to know if the Shape data contains the colors of the vertices (or edges, or faces), and if so, the id and location of the attributes holding these color values. Shape tools plugin IO programmers are encouraged to create an instance of the FileFormatProperties class in their plugin package that annotates the geometrical properties of the shape that their reader creates from specific file format's information. These classes are very simple, and use the predefined property values of the FileFormatPropertyNames class to describe shape properties.

These properties fall into two categories:

To simplify the use of the FileFormatProperties the following convention is observered: All property annotations have an interger value, considered to be the quantity of that property. True/False properties are represented by considering "0" to be "false" and "1" to be true.

The following example (from the Loni Triangle Model reader) shows the FileFormatProperties of a file format that stores only the surface mesh vertex locations (and their connections). This is an ascii text file format.

Example of a simple FileFormatProperties class

package edu.ucla.loni.ccb.shapeio.tm.plugin;

import edu.ucla.loni.ccb.shapeio.FileTypes;

/**
 * Describes the properties of a Loni Tm format file.
 * 
 * @version 27 April 2006
 */
public class TmFormatProperties extends FileFormatProperties
  {
    /**
     * Constructs a description of the Ucf file format properties.
     */
    public TmFormatProperties()
      {
        // set shape tools file type identifier
        _shapeToolsfileType = FileTypes.LONI_TRI;
        
        // TM files are ascii text
        setProperty(FileFormatPropertyNames.ASCII_FILE,1);
      }
  }

A file format that stored the colors of each vertex , as well as the surface normals of each vertex would be annotated in this way:

setProperty(FileFormatPropertyNames.HAS_VERTEX_COLORS,1);
setProperty(FileFormatPropertyNames.HAS_VERTEX_NORMALS,1);

If that format also allowed, say 2 distinct scalar values to be associated with each vertex (perhaps humidity and temperature) then the plugin writer would also add:

setProperty(FileFormatPropertyNames.NUM_VERTEX_ATTRIBUTES,2);

This will allow a program using the shape file format to determine if your shape has the shape attributes it needs. However, to actually use those attributes the application program also needs to know the name of the attribute and the shape component where you (the plugin programmer) have stored that attribute.

The setAttribute() method allow you to store the location of a property by associating a property name, the shape component where that property is stored, and the name of the property attribute containing the property values. Note that not all properties are actually stored - the IS_ASCII property is an exmaple of one of these.

to complete above example, assume that both the attributes are stored in the Shape's PointSet. the Colors are in an attibute name "MyColors" and the vertex normals are in an attribute whose id is "norm".

setAttribute( FileFormatProperties.HAS_VERTEX_COLORS, FileFormatProperties.PONTS_ATTRIBUTE,"MyColors");
setAttribute( FileFormatProperties.HAS_VERTEX_NORMALS, FileFormatProperties.PONTS_ATTRIBUTE,"norm");

The setProperty() and setAttribute() steps may be combined into one method call:

setPropertyAttribute(String property , int value, int component, String name)

which in our example would look like this:

setPropertyAttribute(FileFormatProperties.HAS_VERTEX_COLORS 1, FileFormatProperties.POINTS_ATTRIBUTE,"MyColors");

Back to Table of Contents


Tutorial 1

In this simple example we will read an imaginary data file format named "foo", defined below, to contain vertices.

A methodology to follow when writing a simple parser is:

  1. Obtain or define the file format
  2. Determine what shape components are represented by the file format (points, edges, faces, attributes)
  3. Decide what ShapeTools classes will be used to store the shape components, and assign any needed attribute names.
  4. Decide what "id" will be assigned to a shape that is read from the file.
  5. Decide the names of any publicly visible variables that will make available the attribute names.
  6. Write a file parser class that contains a method which returns an edu.loni.ucla.ccb.shape.Shape , read from an ImageInputStream.
  7. Write a class that describes the file properties (optional, but recommended).

First, let's go through the methodology just defined.

  1. File format - use the "Foo" format, defined below
  2. "Foo" files contain only points, so we wont use edges, faces or attributes.
  3. Decide upon component classes and attribute names:
  4. We'll set the id of the Shape to be the value "FooFile" (This id can have any String value).
  5. "Foo" files contain no attributes, so there is nothing to be done here.

Summarizing in a table:

Item Class or Value Notes
shape vertices IrregularPointSet  
Shape Id "Foo-file.foo" if file was named /a/b/c/file.foo

Now, Step 6: create a Java class "FooReader" which uses the ImageInputStream in it's constructor:

import edu.ucla.loni.ccb.Shape;
import javax.imageio.stream.ImageInputStream;

public class FooReader
  {
     /** Stream from which Foo is read. */
     private ImageInputStream _iistream;
     
     /** set input stream. */
     public FooReader(ImageInputStream stream)
       {
          _iistream = stream;
       }

  }

Add a read() method to read the stream's contents into a Shape:

First, the framework. It doen't really do anything yet :

import java.io.IOException;
import javax.imageio.stream.ImageInputStream;
import edu.ucla.loni.ccb.shape.Shape;

public class FooReader
  {
     /** Stream from which Foo is read. */
     private ImageInputStream _iistream;
     
     /** set input stream. */
     public FooReader(ImageInputStream stream)
       {
          _iistream = stream;
       }
    
     /** read stream contents into a shape if possible. */
     public Shape read() throws IOException
       {
          // for now, return null
          Shape shape = null;
          return shape;
       }
  }

Next, add a private method to read a line from the input stream, and use this to verify that this is really a "Foo" file. If it is not, throw an IOException.

import java.io.IOException;
import javax.imageio.stream.ImageInputStream;
import edu.ucla.loni.ccb.shape.Shape;

public class FooReader
  {
     /** String value of "magic" number which must be first element of a Foo file. */
     public static final String MAGIC_NUMBER = "31415";

     /** Stream from which Foo is read. */
     private _iistream;
     
     /** set input stream. */
     public FooReader(ImageInputStream stream)
       {
          _iistream = stream;
       }
    
     /** read stream contents into a shape if possible. */
     public Shape read() throws IOException
       {
          // is this a "Foo" file ?
          String magicNumber = _readLine();
          if (!magicNumber.equals(MAGIC_NUMBER)) {
            throw new IOException ("File is not a Foo file.");
          }
          // for now, return null
          Shape shape = null;
          return shape;
       }

     /**
       * Read a line from the image input stream.
       * 
       * @return the next line read from the input stream.
       *
       * @throws IOException if unable to read from the input stream.
     */
     private String _readLine() throws IOException
       {
          return _iistream.readLine();
       }
  }

Finally, read the vertices (see method read() and set the shape id:

  1. Read the number of vertices

B. Read the vertices into an IPointSet

C. Create a Shape to hold all the data

D. Add the IPointSet to the Shape

E. Return the shape.

import java.io.IOException;
import java.util.StringTokenizer;
import javax.imageio.stream.ImageInputStream;
import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shape.ShapeImpl;
import edu.ucla.loni.ccb.shape.geometry.IPointSet;
import edu.ucla.loni.ccb.shape.geometry.IrregularPointSet;

public class FooReader
  {
     /** String value of "magic" number which must be first element of a Foo file. */
     public static final String MAGIC_NUMBER = "31415";

     /** Default id of a Foo Shape. *;
     public static final String FOO_ID = "FooFile";

     /** Stream from which Foo is read. */
     private _iistream;
     
     /** set input stream. */
     public FooReader(ImageInputStream stream)
       {
          _iistream = stream;
       }
    
     /** read stream contents into a shape if possible. */
     public Shape read() throws IOException
       {
          // is this a "Foo" file ?
          String magicNumber = _readLine();
          if (!magicNumber.equals(MAGIC_NUMBER)) {
            throw new IOException ("File is not a Foo file.");
          }
         //  A. Read the number of vertices as a string
         String vertexCountString = _readLine();
         // convert to an integer
         int numVertices = Integer.parseInt(vertexCountString);
        // B. Read the vertices into an IPointSet
         IPointSet vertices = _readVertices(numVertices);
        // C. Create a Shape to hold all the data
        Shape shape = new ShapeImpl(); // use the standard Shape implementation
        // D. Add the IPointSet to the Shape 
        shape.setVertices(vertices);
        // E. set the id of this shape
        shape.setId(FOO_ID);
        // F. Return the shape.
        return shape;
       }

     /** 
       * Read vertices into an IrregularPointSet.
       * @param numVertices the number of vertices, one per input line, to read.
       * 
       * @return an IPointSet containing the vertices read from the input stream.
       *
       * @throws IOException if not enough vertices can be read from the stream
     */
     private IPointSet _readVertices(int numVertices)
       throws IOException
       {
          // allocate a 2 d array of floats to hold vertex coordinate triples
          float [][] coords = new float[3][numVertices];
          // read the next line in the input stream and convert into x,y and z coordinate values.
          // use a StringTokenizer to split the text input line into pieces,
          // then convert each bit into a float.
          for (int vertexIndex =0; vertexIndex < numVertices; vertexIndex++) {
            StringTokenizer tokenizer = new StringTokenizer(_readLine());
            coords[0][vertexIndex] = Float.parseFloat(tokenizer.nextToken()); // x coordinate
            coords[1][vertexIndex] = Float.parseFloat(tokenizer.nextToken()); // y coordinate
            coords[2][vertexIndex] = Float.parseFloat(tokenizer.nextToken()); // z coordinate
          }
          // create an IrregularPointSet to hold vertices
          IPointSet pointSet = new IrregularPointSet(coords);
          // return it
          return pointSet;
       }

     /**
       * Read a line from the image input stream.
       * 
       * @return the next line read from the input stream.
       *
       * @throws IOException if unable to read from the input stream.
     private String _readLine() throws IOException
       {
          return _iistream.readLine();
       }
  }

Step 7: - add a file format description class describing the capabilites of this shape. Our shape format doesn't really do anything, so all this class does is to record the file type of the class:

/**
 * Describes the properties of a Foo Plus format file.
 * 
 * @version 7 May 2006
 */
public class FooPlusFormatProperties extends FileFormatProperties
  {
    /**
     * Constructs a FooPlusFormatProperties object that
     * describes the properties supported by the ShapeTools 
     * FooPlus reader and writer plugins.
     */
    public FooPlusFormatProperties ()
      {
        // set shape tools file type identifier
        // (note: FOO is not an acutal ShapeTools file format)
        _shapeToolsfileType = FileTypes.FOO;  
        
        // Foo files are ascii text
        setProperty(FileFormatPropertyNames.ASCII_FILE,1);
      }
  }

Foo File Format

A sample "Foo" file defining the points of a unit cube is:

31415
8
0 0 0
0 1 0
0 1 1
0 0 1
1 0 0
1 1 0
1 1 1
1 0 1


Tutorial 2

For this example we will extend the "Foo" format to include:

We'll call this file format FooPlus.

FooPlus file format

Identical to the Foo format except that

We choose to store the field strength in a FloatAttribute that will be assocated with the Shape. The tissue densities will be stored as a FloatArrayAttribute associated with the IPointSet of shape vertices.

The table of components becomes:

Item Class or Value Notes
shape vertices IrregularPointSet  
Shape Id "Foo-file.foo" if file was named /a/b/c/file.foo
Magnet Field Strength FloatAttribute assoc. with shape
Tissue DEnsities IntArrayAttribute assoc. with vertices

First, modify the import statements to define the new classes. The import statements are now:

import java.io.IOException;
import java.util.StringTokenizer;
import javax.imageio.stream.ImageInputStream;
import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shape.ShapeImpl;
import edu.ucla.loni.ccb.shape.attribute.AttributeSet;
import edu.ucla.loni.ccb.shape.attribute.FloatAttribute;
import edu.ucla.loni.ccb.shape.attribute.IAttribute;
import edu.ucla.loni.ccb.shape.attribute.IntArrayAttribute;
import edu.ucla.loni.ccb.shape.geometry.IPointSet;
import edu.ucla.loni.ccb.shape.geometry.IrregularPointSet;

Next add publicly visible static variables that define the attribute id's used to store the field strength and tissue density. These are public to allow methods that will use the Shape read by this class to locate and extract the (meta)data stored in the attributes.

    /** Field Strength Attribute Id.*/
    public static final String FIELD_STRENGTH_ATTRIBUTE = "tesla";
    
    /** Tissue Density Attribute Id.*/
    public static final String TISSUE_DENSITY_ATTRIBUTE = "tissueDensity";

Now add a method to read the field strength from the file and return it's value as a data attribute:

   /**
    * Reads field strength from input stream.
    * 
    * @return an Attribute containing the field strength.
    * 
    * @throws IOException if unable to read the field strength from the input stream.
    */
   private FloatAttribute _readFieldStrengthAsAttribute() throws IOException
     {
       // read value of field strength
       float fieldStrength = Float.parseFloat(_readLine()); 
       // create an attribute containing this value. 
       FloatAttribute fieldStrengthAttribute = 
             new FloatAttribute(FIELD_STRENGTH_ATTRIBUTE,fieldStrength);
       return fieldStrengthAttribute;
     }

And add a method to read the tissue density at each vertex into an array attribute. Arrays of Attributes associated with sets of points, edges or faces are expected to be in 1 : 1 corrospondence to the set in question. It is this mapping which enables a the color, normal, or other attribute of a specfic vertex (for example) to be retrieved. If an array attribute is added to a shape component and has a different number of elements than that component an Exception is thrown. Other attributes (that are not arrays) are not subject to this requirement.

   /**
    * Reads tissue densities from input stream.
    * 
    * @param count the number of density values to read.
    * 
    * @return an Attribute containing the tissue densities.
    * 
    * @throws IOException if unable to read the densities from the input stream.
    */
   private IntArrayAttribute _readTissueDensity(int count) throws IOException
     {
       // create array of density values
       int [] densities = new int[count];
       // read value of field strength
       for (int i=0;i

Use the preceding two methods by modifying the read() method. Notice the following changes:

  1. The Shape is created before the vertices and other values are read.
  2. The field strength is added the Shape's AttributeSet because it is a property (applies to) the entire shape.
  3. The IPointSet component that contains vertex coordinates has it's own AttributeSet. Tissue densities are added to the point set attributes because the density is a property of a particular point, not the shape as a whole.
  4. The vertices are associated with the Shape in a separate, explicit step. Don't forget to do this.

    /**
     * Reads a FooPlus file from an input stream as a ShapeTools shape.
     *   
     * @return a Shape containing the vertices and attributes read from the input stream.
     * 
     * @throws IOException if unable to read the shape from the input stream.
     */
    public Shape read() throws IOException
      {
         // is this a "FooPlus" file ?
         String magicNumber = _readLine();
         if (!magicNumber.equals(MAGIC_NUMBER)) {
           throw new IOException ("File is not a FooPlus file.");
         }
        // Create a Shape to hold all the data
        Shape shape = new ShapeImpl(); // use the standard Shape implementation
       
        // read the field strength as an attribute
        // and add to the Shape attribute set
        IAttribute fieldStrengthAttribute= _readFieldStrengthAsAttribute();
        AttributeSet shapeAttrSet = shape.getAttributeSet();
        shapeAttrSet.addAttribute(fieldStrengthAttribute);
        
        //  Read the number of vertices as a string
        String vertexCountString = _readLine();
        
        // convert to an integer
        int numVertices = Integer.parseInt(vertexCountString);
        
        // Read the vertices into an IPointSet
        IPointSet vertices = _readVertices(numVertices);
        
        // read the tissue densities as an attribute
        IAttribute tissueDensityAttribute = _readTissueDensity(numVertices); 
        
       // get the attribute set of the vertices
        AttributeSet vertexAttrSet = vertices.getAttributeSet();
        
        // add  tissue density attribute to vertex attribute set
        vertexAttrSet.addAttribute(tissueDensityAttribute);
       
       // Add the vertex IPointSet to the Shape
       shape.setVertices(vertices);
       
       // set the id of this shape
       shape.setId(FOO_ID);
       
       //  Return the shape.
       return shape;
      }

The file format description for the FooPlus class should document the support of a the tissue density, measured at each vertex. We do so via the NUM_VERTEX_ATTRIBUTES property:

/**
 * Describes the properties of a Foo Plus format file.
 * 
 * @version 7 May 2006
 */
public class FooPlusFormatProperties extends FileFormatProperties
  {
    /**
     * Constructs a FooPlusFormatProperties object that
     * describes the properties supported by the ShapeTools 
     * FooPlus reader and writer plugins.
     */
    public FooPlusFormatProperties ()
      {
        // set shape tools file type identifier
        // (note: FOO is not an acutal ShapeTools file format)
        _shapeToolsfileType = FileTypes.FOO;  
        
        // Foo files are ascii text
        setProperty(FileFormatPropertyNames.ASCII_FILE,1);

        setPropertyAttribute(NUM_VERTEX_ATTRIBUTES , 1,
        FileFormatProperties.POINTS_ATTRIBUTE, TISSUE_DENSITY_ATTRIBUTE);
      }
  }

Now test the complete Foo Plus parser class, reading the following FooPlus file:

Foo Plus file

11235
3.4
8
0 0 0
0 1 0
0 1 1
0 0 1
1 0 0
1 1 0
1 1 1
1 0 1
11
22
33
44
55
66
77

A simple test class produces the following output:


Shape: 
  ID = FooPlusFile
  Vertex Coordinates:
    Index| 0  | 1  | 2  | 3  | 4  | 5  | 6  | 7  
    Dim:0| 0.0| 0.0| 0.0| 0.0| 1.0| 1.0| 1.0| 1.0
    Dim:1| 0.0| 1.0| 1.0| 0.0| 0.0| 1.0| 1.0| 0.0
    Dim:2| 0.0| 0.0| 1.0| 1.0| 0.0| 0.0| 1.0| 1.0
    1 Attribute(s)
    Attribute: tissueDensity
      ID: tissueDensity | 11 22 33 44 55 66 77 88
-----------------------------------------
  Vertex IEdgeSet:
    IEdgeSet List:
    Edge#
          
          
    0 Attribute(s)
-----------------------------------------

  IFaceSet :
  Total IFaceSet: 0
    0 Attribute(s)
-----------------------------------------
  Geometry : 
    
-----------------------------------------
  Shape Attributes:
    1 Attribute(s)
    Attribute:tesla
      tesla 3.4

  Children :
    None

Back to Table of Contents


Miscellaneous Notes

canDecodeInput()
When writing the canDecodeInput() method of a shape reader spi, take care that you do not read more bytes than the shortest file - of any input type - that might be tested for readability. If you read past the EOF of a file then the input stream will be closed and all subsequent attempts to determine the file type will fail with a 'Stream Closed" exception. The ShapeInputStream.readLine(ImageInputStream, maxNumOfBytes) method is provide to help with this problem.

Package Layout and Classes

An example, from the VTK reader, is


    /**
     * Reads a VTK file into a Shape.
     *
     * @param source the data source containing the VTK surface.
     *
     * @return a Shape containing the VTK surface.
     *
     * @throws IOException if the file cannot be read.
     */
    public static Shape read(Object source) throws IOException
      {
        return read(source, null);
      }
    
    /**
     * Reads an VTK from a data source as a Shape.
     * 
     * @param source the data source from which VTK data will be read.
     * @param progress receives 'percentage done' notifications.
     * 
     * @return a Shape containing the surface stored in the VTK Surface.
     * 
     * @throws IOException if unable to read the VTK from the stream.
     */
    public static Shape read(Object source, IProgressNotifier progress)
      throws IOException 
      {
         VtkAsciiUnstructuredGridShapeReaderSpi spi =  new VtkAsciiUnstructuredGridShapeReaderSpi();
        return readSPI(source, spi, progress);
      }
    

SPI classes

File Format Properties

To assist application programs that use shapes created by the readers, shapes are reccomended to be contain a few attributes with standardized names to document the properties of the shapes. As an example, it is useful for the shape to make known if it has any vertex colors.

This is best accomplished by creating a custom FileFormatProperties class for each file format variation. This class is used in the file format's SPI class. For example, the VTK ascii unstructured grid file

and it's file format properties class looks like this:

The following routines will set these commonly occuring properties:

The properties considered to be "common" are defined in class FileFormatPropertyNames, which is currently:


/**
 * Names of Commonly used file format properties.
 * 
 * @version 29 August 2008 
 */
public class FileFormatPropertyNames
  {
    /** a constant used to indicate that a property is present.*/
    public static final int HAS_PROPERTY = 1;
    
    /** number of attributes allowed at each vertex. */
     public static final String NUM_VERTEX_ATTRIBUTES = "numPerVertexAttributes";
     
    /** number of attributes allowed at each face. */
     public static final String NUM_FACE_ATTRIBUTES = "numPerFaceAttributes";
     
    /** 1 if vertex normals are supported, 0 if not.*/
     public static final String HAS_VERTEX_NORMALS  = "hasVertexNormals";
     
    /** 1 if face normals are supported, 0 if not.*/
     public static final String HAS_FACE_NORMALS  = "hasFaceNormals";
     
    /** 1 if face colors are supported, 0 if not.*/
     public static final String HAS_FACE_COLORS  = "hasFaceColors";
     
    /** 1 if vertex colors are supported, 0 if not.*/
     public static final String HAS_VERTEX_COLORS  = "hasVertexColors";
     
    /** 1 if file is ascii text, 0 if not. */
    public static final String ASCII_FILE = "asciiFile";
  }

Property setting is illustrated by the following examples:

/**
 * Describes the properties of a unstructured grid VTK shape format file.
 * 
 * @author Bae Cheol Shin
 * @version July 17, 2007
 */
public class VtkFormatProperties extends FileFormatProperties
  {
    /**
     * Constructs an VtkFormatProperties object that describes the properties 
     * supported by the ShapeTools VTK reader and writer plugins.
     */
    public VtkFormatProperties ()
      {
        // Set shape tools file type identifier.
        _shapeToolsfileType = FileTypes.VTK_ASCII_UNSTRUCTURED_GRID;
        
        // Vtk files are ascii text
        setProperty(FileFormatPropertyNames.ASCII_FILE, 1);
      }
  }

Another example is the OFF format properties class. Off files may have

The Properties class for OFF is

/**
 * Describes the properties of a Geomview OFF format file.
 * 
 * @version 7 May 2006
 */
public class OffFormatProperties extends FileFormatProperties
  {
    /**
     * Constructs an OffFormatProperties object that
     * describes the properties supported by the ShapeTools 
     * Off reader and writer plugins.
     */
    public OffFormatProperties ()
      {
        // set shape tools file type identifier
        _shapeToolsfileType = FileTypes.GEOMVIEW_OFF;
        
        // OFF files may have any per vertex colors.
        setPropertyAttribute(FileFormatPropertyNames.HAS_VERTEX_COLORS,1,
          FileFormatProperties.POINTS_ATTRIBUTE,
          OffMetadataFormat.VERTEX_COLOR_ATTRIBUTE );
        
        // OFF files may have any per vertex normals.
        setPropertyAttribute(FileFormatPropertyNames.HAS_VERTEX_NORMALS,1,
          FileFormatProperties.POINTS_ATTRIBUTE,
          OffMetadataFormat.VERTEX_NORMALS_ATTRIBUTE );
        
        // OFF files are ascii text
        setProperty(FileFormatPropertyNames.ASCII_FILE,1);
      }
  }

file reader classes

canDecodeInput
Back to Table of Contents


Utility Classes

Note : all package paths in this section are printed without the common prefix of "edu.ucla.loni.ccb.shape", thus a class listed here as geometry.IPointSet corrosponds to the following java import statement:

edu.ucla.loni.ccb.shape.geometry.IPointSet;

About
static methods that specify which version of the ShapeTools library is used. Also contains method to return copyright acknowledgements. $ util.Print :static methods to simplfy printing Shapes and their components. Useful for debugging.
util.ShapeFactory
static methods that create simple shapes. Useful for testing.
util.GeometryUtility.addVertexPolygonFace
Creates a Face from a set of vertices. Edges are created if needed.
util.GeometryUtility.createPolygonSurfaceFaces
Creates an IFaceSet containing a regular grid of faces from a set of vertices. Edges are created if needed.

Back to Table of Contents


Glossary of Terms

The following terms are used within this programming guide.

Attribute
data associated with a shape that is not part of it's geometry. Examples include: the color of a vertex or the
value of a datum of interest (e.g tissue density) at a particular location in space.
AttributeSet
a collection of data attributes that is associated with a ShapeComponent or the Shape, as a whole.
Edge
A directed line segment connecting two points in an N-dimensional space. Edges are directional, thus an edge connecting vertex 2 to vertex 7 is not the same as the edge connecting vertex 7 to vertex 2.
IEdgeSet
A Java interface that must be implemented by all ShapeTools Java classes that represent a set of a shapes' edges.
IFaceSet
A Java interface that must be implemented by all ShapeTools Java classes that represent a set of a shapes' faces.
IPointSet
A Java interface that must be implemented by all ShapeTools Java classes that represent as set of a shapes.
ImageInputStream
A Java class in the javax.imageio.stream package
ShapeComponent
One of the elements that, together with an optional group of child shapes, compose a Shape. These typically consist of an IPointSet, an IEdgeSet and an IFaceSet.
File format parser
A computer program which reads information stored in a file with specific internal structure.

ShapeIO framework
A group of Java classes and methods which enable automatic selection of a parser appropriate to an input file.
Vertex
A point in an N-Dimensional space that is part of a geometrical shape.

Back to Table of Contents


Appendix A -- A Test class

package test.examples;

import java.io.File;
import java.io.IOException;
import javax.imageio.stream.FileImageInputStream;
import javax.imageio.stream.ImageInputStream;
import test.edu.ucla.loni.ccb.TestAll;
import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shape.util.Print;
import examples.FooPlusReader;
import examples.FooReader;


public class TestFoo
{
  /** A Foo file */
   private String _simpleFoo = TestAll.DATADIR+ "/foo/simple.foo";
  
  /** A FooPlus file */
   private String _plusFoo = TestAll.DATADIR+ "/foo/plus.foo";
 
   public void testFooReader() 
    {
      FooReader reader = new FooReader(_open(_simpleFoo));
      try {
        Shape s = reader.read();
      } catch (IOException e) {
        fail(e.getMessage());
      }
    }
  
  public void testFooPlusReader() 
    {
      FooPlusReader reader = new FooPlusReader(_open(_plusFoo));
      try {
        Shape s = reader.read();
        Print.printShape(s);
      } catch (IOException e) {
        fail(e.getMessage());
      }
    }
  
   /**
    * Open an ImageInputStream containing the data in the named file
    * or fail if unable to do so.
    * 
    * @param filePath path to a file on local file system.
    * 
    * @return an ImageInputStream containg the file's contents.
    */
   private ImageInputStream _open(String filePath)
     {
       ImageInputStream stream=null;
       try {
        stream=new FileImageInputStream(new File(filePath));
       } catch (IOException e) {
         fail("IO Error: " + e.getMessage()); 
       }
       
       return stream; 
     }
}

Back to Table of Contents


Appendix B -- The complete FooPlus parser

/*
COPYRIGHT NOTICE
Copyright (c) 2005  Craig Schwartz and Arthur W. Toga

See README.license for license notices.
*/
package examples;


/**
 * Reads a "FooPlus" file.
 * 
 * @version 28 November 2005
 */

import java.io.IOException;
import java.util.StringTokenizer;

import javax.imageio.stream.ImageInputStream;

import edu.ucla.loni.ccb.shape.Shape;
import edu.ucla.loni.ccb.shape.ShapeImpl;
import edu.ucla.loni.ccb.shape.attribute.AttributeSet;
import edu.ucla.loni.ccb.shape.attribute.FloatAttribute;
import edu.ucla.loni.ccb.shape.attribute.IAttribute;
import edu.ucla.loni.ccb.shape.attribute.IntArrayAttribute;
import edu.ucla.loni.ccb.shape.geometry.IPointSet;
import edu.ucla.loni.ccb.shape.geometry.IrregularPointSet;

public class FooPlusReader
  {
    /** String value of "magic" number which must be first element of a Foo file. */
    public static final String MAGIC_NUMBER = "11235";
    
    /** Default id of a Foo Shape. */;
    public static final String FOO_ID = "FooPlusFile";
    
    /** Field Strength Attribute Id.*/
    public static final String FIELD_STRENGTH_ATTRIBUTE = "tesla";
    
    /** Tissue Density Attribute Id.*/
    public static final String TISSUE_DENSITY_ATTRIBUTE = "tissueDensity";
    
    /** Stream from which Foo is read. */
    private ImageInputStream _iistream;
    
    /** set input stream. */
    public FooPlusReader(ImageInputStream stream)
      {
         _iistream = stream;
      }
    
    /**
     * Reads a FooPlus file from an input stream as a ShapeTools shape.
     *   
     * @return a Shape containing the vertices and attributes read from the input stream.
     * 
     * @throws IOException if unable to read the shape from the input stream.
     */
    public Shape read() throws IOException
      {
         // is this a "FooPlus" file ?
         String magicNumber = _readLine();
         if (!magicNumber.equals(MAGIC_NUMBER)) {
           throw new IOException ("File is not a FooPlus file.");
         }
        // Create a Shape to hold all the data
        Shape shape = new ShapeImpl(); // use the standard Shape implementation
       
        // read the field strength as an attribute
        // and add to the Shape attribute set
        IAttribute fieldStrengthAttribute= _readFieldStrengthAsAttribute();
        AttributeSet shapeAttrSet = shape.getAttributeSet();
        shapeAttrSet.addAttribute(fieldStrengthAttribute);
        
        //  Read the number of vertices as a string
        String vertexCountString = _readLine();
        
        // convert to an integer
        int numVertices = Integer.parseInt(vertexCountString);
        
        // Read the vertices into an IPointSet
        IPointSet vertices = _readVertices(numVertices);
        
        // read the tissue densities as an attribute
        IAttribute tissueDensityAttribute = _readTissueDensity(numVertices); 
        
       // get the attribute set of the vertices
        AttributeSet vertexAttrSet = vertices.getAttributeSet();
        
        // add  tissue density attribute to vertex attribute set
        vertexAttrSet.addAttribute(tissueDensityAttribute);
       
       // Add the vertex IPointSet to the Shape
       shape.setVertices(vertices);
       
       // set the id of this shape
       shape.setId(FOO_ID);
       
       //  Return the shape.
       return shape;
      }
    
   /**
    * Reads field strength from input stream.
    * 
    * @return an Attribute containing the field strength.
    * 
    * @throws IOException if unable to read the field strength from the input stream.
    */
   private FloatAttribute _readFieldStrengthAsAttribute() throws IOException
     {
       // read value of field strength
       float fieldStrength = Float.parseFloat(_readLine()); 
       // create an attribute containing this value. 
       FloatAttribute fieldStrengthAttribute = 
             new FloatAttribute(FIELD_STRENGTH_ATTRIBUTE,fieldStrength);
       return fieldStrengthAttribute;
     }
   
   /**
    * Reads tissue densities from input stream.
    * 
    * @param count the number of density values to read.
    * 
    * @return an Attribute containing the tissue densities.
    * 
    * @throws IOException if unable to read the densities from the input stream.
    */
   private IntArrayAttribute _readTissueDensity(int count) throws IOException
     {
       // create array of density values
       int [] densities = new int[count];
       // read value of field strength
       for (int i=0;i

Back to Table of Contents


Author : Craig Schwartz