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:
- boolean canRead(ImageInputStream)
- boolean canRead(InputStream)
- boolean canRead( edu.ucla.loni.ccb.shape.data.DataReader)
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:
- A comment describing a data file
- lighting rendering parameters global to the shape - diffusion, opacity, et. cetera
- the date on which a data file was obtained.
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:
- All classes contain a class comment briefly defining the purpose of that class and the functionality it provides.
- A one line javadoc comment describes all public variables of a class.
- All public methods of class have a method comment that includes:
- A description of the what the method does.
- A one line description of all parameters, using the @param JavaDoc tag.
Example: @param numVertices the number of surface vertices.
- A short description of what values are returned by the class, if any, using the javadoc @return tag.
Example: @return a normalized vector.
- A description of all exceptions thrown by a class and the conditions which cause an exception to be throw, using a JavaDoc @throws tag.
Example: @throws IOException if unable to read an integer from the input stream, or if the the stream data cannot be converted into an integer.
- All classes include an @version JavaDoc tag whose value is the date of the last change to the class.
Example: @version 28 November 2005
Class documentation should include a complete description of :
- What file format variants are and are not supported - e.g. "ignores vertex texture data in input file"
- Limiting assumptions - "foo" format file must have names ending in ".foo"
- Publicly accessible values of data attributes - e.g. "MRI weighting is in a float shape attribute named "Foo.WEIGHTING"
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
- the class must be added to the file META-INF/services/edu.ucla.loni.ccb.shapeio.spi.ShapeWriterSpi . This file contains the list of writer SPI's that known to shape tools .
- the allowed output types are defined in the array Class outputTypes. It is _strongly reccomended that this list include DataWriter.class
ShapeReaderSPI requirements and notes
- the class must be added to the file META-INF/services/edu.ucla.loni.ccb.shapeio.spi.ShapeReaderSpi . This file contains the list of reader SPI's that known to shape tools
- the allowed data input types are defined in the array Class inputTypes. It is _strongly reccomended that this list include DataReader.class
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:
- A property that either true or false (e.g. is the data file ascii text).
- A property whose value is a quantity (e.g. number of data values stored at a vertex - could be,0, 1, 2, ...).
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:
- Obtain or define the file format
- Determine what shape components are represented by the file format (points, edges, faces, attributes)
- Decide what ShapeTools classes will be used to store the shape components, and assign any needed attribute names.
- Decide what "id" will be assigned to a shape that is read from the file.
- Decide the names of any publicly visible variables that will make available the attribute names.
- Write a file parser class that contains a method which returns an edu.loni.ucla.ccb.shape.Shape , read from an ImageInputStream.
- Write a class that describes the file properties (optional, but recommended).
First, let's go through the methodology just defined.
- File format - use the "Foo" format, defined below
- "Foo" files contain only points, so we wont use edges, faces or attributes.
- Decide upon component classes and attribute names:
- points - We have no knowledge of constraints on the vertex positions, and therfore a vertex could be anywhere. So, we'll use the most general point set class -the IrregularPointSet - to contain the vertices. Most shapes use this class to contain vertex coordinates.
- We'll set the id of the Shape to be the value "FooFile" (This id can have any String value).
- "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:
- 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
- Foo geometry files contain 3 dimensional vertices.
- Foo files do not define any edges, faces, or attributes.
- Foo files are written solely as Ascii characters.
- No Foo file lines start with whitespace.
- Foo geometry files start with the identifying "magic" number 31415 on the first line.
- Foo files contain the number of vertices on the second line.
- All subsequent lines contain the space separated vertex coordinates.
- blank lines are not allowed.
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:
- a scalar attribute, defined for the entire file. We'll store the field strength of a magnet whose units are assumed to be Tesla.
- a scalar value measured at each vertex. For this example we'll read tissue density, stored as a real number.
We'll call this file format FooPlus.
FooPlus file format
Identical to the Foo format except that
- magnet field strengh in Teslas is alone on a line following the file Magic number.
- a list of integer valued tissue densities, one per line, follows the vertex coordinates.
- A FooPlus file starts with a magic number valued "11235"
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:
- The Shape is created before the vertices and other values are read.
- The field strength is added the Shape's AttributeSet because it is a property (applies to) the entire shape.
- 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.
- 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
- each file format grouping has it's own package : edu.ucla.loni.ccb.shapeio.format. This contains a class providing read and write methods easily used by a programmer who wishes to call the read(write) method directly. These methods, however, use the formatSPI methods to perform the actual read(write) operations.
- each file format pacakge contains a subpackage named plugin. The plugin package contains the actual format service provider interface (formatSPI) and format writer classes. Ex: package edu.ucla.loniu.ccb.shapeio.vtk.plugin .
- package FORMAT contains a class named FormatIO.
- Class FormatIO is primarily static read and write methods, used by the programmer when they know ahead of time what format to write
- Class FormatIO should be a subclass of class ShapeIO .
- FormatIO should contain, at a minimum, these methods:
- public static Shape read(DataReader dataSource, IProgressNotifier notifier) throws IOException , where notifier may be null)
- public static void write(Shape shape, DataWriter dataWriter, IProgressNotifier notifier) throws IOException , where notifier may be null.
- The read methods should
- ) create an instance of the format SPI. This
- ) use the SPI class to create a reader(writer) class, which extends the
- ) call the spi.createReaderInstance() method to create a file reader.
- ) set the file reader's data source.
- ) call the reader getShape() method to read the shape.
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
- each format variant needs formatVariantSPI class.
- this class must:
- extend class ShapeReaderSpi (ex: public class VtkAsciiPolygonShapeReaderSpi extends ShapeReaderSpi)
- implement the canDecodeInput() method (see notes on canDecodeInput)
- implement the createReaderInstance() method.
- use a FileFormatProperties class to correctly desscribe the file format.
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
- is ascii (not binary) - this allows efficient selection of an output stream, should the shape data need to be written
- has an identifying FileTyps? of VTKI_ASCII_UNSTRUCTURED_GRID
and it's file format properties class looks like this:
The following routines will set these commonly occuring properties:
- setPropertyAttribute()
- setProperty()
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
- per-vertex colors
- vertex normals
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
- shapes craeated should have their file type property set (see FileTypes?.
- shape created should have the shape id set (see method shape.setId(String id)).
*
- implement the getShape() method
- extend class shapeReader
- should periodically update the progress notifier (method setProgress(int percentage) is convenient for this).
-
canDecodeInput
- this method is responsible for examining a small amount of the data stream and deciding if this data stream is in the file format.
- this method must save and restore the file mark before it returns. This is to allow other canDecodeInput() method the chance to examine the input stream.
- this method should not assume that the data stream it is examining is ascii with line breaks. attempts to read "to the end of the line" will often cause binary data streams to read the entire stream, which then causes an EOF exception, making a stream rewind() impossible.
- this method should not assume that the input stream is long enough to make it's determination of file format type. failure to handle this will also generate and 'EOF' problem.
- should have a small footprint: be quick to load (pay attention to other classes used by this method).
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