Overview
The curvature of a surface is a property of interest to neurological researchers.
The ShapeCurvature program reads a surface mesh from a data file and
computes the curvature of the surface at each mesh vertex.
These values may be saved as either an array of values (one per vertex) in a simple text file
or added to a copy of the orginal file if this action is allowed by the data file format.
If the output file format (which defaults to the same format as the input file) does not allow
saving the curvature of each vertex, then an open dx file will instead be written.
Command Line Usage
The command line follows this pattern: "java {optional java arguments} -jar {optional command line arguments} input_file output_file". The "optional command line arguments" are described by the table in the next section, and by the
illustrative examples that follow. The "optional java arguments' control the behavior of the Java
virtual machine used to run the application and, with one exception, are seldom used. That exception
is the memory allocation argument, -Xmx{number}, which asks your computer's operating system to
give more memory to the Java virtual machine that it ordinarily gets. This is used when the
data to be manipulated exceed the amount of memory. If you run the program and see an error
with text resembling
"Out of Memory"
then you will probably want to add the memory argument. The "number" part sets the amount of memory
you are requesting; a good start value is to ask for 200 megabytes, which would be done by this command:
java -Xmx200m -jar ShapeCurvature.jar input_file output_file
the
-Xmx200m is the argument that requests additional memory.
Command line arguments
The program is controlled by use of command line arguments. These select the curvature measurement used,
the type of output produced, and the value used to indicate an infinite curvature, as well as other options.
The complete table of command line arguments follows. The "Default" values listed are the values used by the
program if the corrosponding command line argument is
not specified.
Not all arguments need be specified by a user; generally, an argument is used only to override an
unwanted default behavior of the program.
| Argument | Default | Description | Notes |
|---|
| -version | n/a | prints a version string to the console output and exits normally. | |
| -help | n/a | prints usage string to the console output and exits normally. | |
| -curvatureType | -gaussian | selects the curvature measure to use | type must be one of {-mean, -gaussian, -principal} |
| -output type | text | Changes the output file type. Allowed values are "text" and "dx", which select an ascii text file or an OpenDX file | If unspecified the input file type is used, unless the input file type does not allow arbitrary data attributes at a vertex. |
| -infinity number | (2-2^23)-2127 | sets the value of the number used to indicate infinite curvature at a point. | |
| -output_attribute name | curvature | sets name of attribute used to store curvature in the output file | If the output file format does not support named attributes this parameter value is ignored. |
| -verbose | false | enables detailed status messages during calculations. | |
| -examples | n/a | prints examples of common usage | |
| -pipeline | n/a | prints a pipeline descriptor file to std. output and exits | |
| -twiki | n/a | prints a TWiki description of command line arguments to std. output, and exits. | |
Examples of common usage
In these examples we assume that the ShapeCurvature application is saved in a file
named ShapeCurvature.jar.
Ex 1) Print a usage summary to the console output.
Use this command:
java -jar ShapeCurvature -help
Note: The options illustrated in the following examples may be varied in actual use to suit your needs.
Ex 2) Measure the curvature of a surface saved in a Minc OBJ file and save the curvature values into a text file
Note: Obj files are unable to store per-vertex curvature data
- uses simple curvature measurement
- saves curvatures at each vertex into an ascii text file.
Use this command :
java -jar ShapeCurvature.jar -output text mesh.obj mesh_curvature.txt
Ex 3) Find curvature of a Ucf file and writes a copy of the input file with curvature appended as a Ucf '4D' attribute
- uses value of -1234 to represent infinite curvature.
- names output attribute "saxophone".
- saves curvature as ucf 4D attribute.
Use this command:
java -jar ShapeCurvature -infinity -1234 -output_attribute saxophone mesh.ucf meshCurvature.ucf
Ex 4) Find curvature of a Ucf file and writes a copy of the input file with curvature appended as a DX file:
Use this command:
java -jar ShapeCurvature -output dx mesh.ucf meshCurvature.dx
Detailed Description of the program
- No input or output file
- if both input file and output file are not provided the application will exit.
- Not appropriate input file
- if input file doesn't exist, or cannot be read the application wlll exit.
- Not appropriate output file
- if it is not possible to write the output file then the application will exit.
- Not appropriate output type
- if input file type doesn't match output type the application will exit.
- Not appropriate shape
- if shape has no face set or the face set has no faces the application will exit.
- Wrong curvature value
- if the surface is not closed then curvature values at the surface edge will be incorrect.
Any mesh files supported by the
ShapeTools library may be read by this program, however, it is possible
that a valid file may not contain a closed mesh surface. Loni Ucf files are a particular example of this.
Loni Ucf files may in some circumstances be explicitly interpolated to form a surface mesh. Please
see the shape tools
InterpolateContour application for more details.
Many file mesh file formats in use at Loni do not allow arbitrary per-vertex values to be stored.
Examples of such are the Obj and Off file formats. Although these permit per-vertex colors and surface
normals to be stored, they do not allow arbitrary data values , such as curvature, to be saved. In
such cases the output file will be written as an
OpenDX format file. Should this
occur
the name of the output file will be changed by appending a ".dx" to the file name.
A warning message notifying
the user of the problem is printed to the screen.
The following input formats are currently supported (3 March 2006)
| Abbreviated Name | Descripoint | Notes |
|---|
| Ucf | Loni Universal Contour Format files. | Not a mesh format, however, adjacent polyline contours with equal numbers of vertices may be interpreted as a square grid mesh. |
| OBJ | Montreal Neurological Institute surface mesh Object files. | Do not allow arbitrary data values at mesh vertices. Does support color and vertex normals |
| OFF | Geomview surface mesh files. | Do not allow arbitrary data values at mesh vertices. Does support color and vertex normals |
| DX | OpenDX general format data files (using "positions" and "connections" to define the mesh). | supports arbitrary data components at all mesh vertices |
The following output formats are currently supported (3 March 2006)
| Abbreviated Name | Descripoint | Notes |
|---|
| TXT | Ascii text files | One curvature value is written per line. Values are in the order of the vertices; that is, the curvature at the first vertex of the input file is on line 1 of the output file, the second vertex's curvature on line 2, and so on. |
| DX | OpenDX ascii general format data files | Curvature is stored in a Field component named (unsurprisingly) "Curvature" |
Curvature algorithms
The 'curvature' of a surface is the bending of a polyhedral surface at each of its vertices.
The ShapeCurvature program provides a variety of curvature measurements. It is designed to support many different
measures of curvature.
The curvature measurements currently supported are:
System requirements
- Platform - Platform independent
- Operating System - Any OS that has Java 1.4.2 or greater.
Limitations
- Input meshes must be regular, that is, all faces must have the same number of vertices.
Acknowledgements
This program is a product of the CCB
Shape Tools program.
