Medial Distance Users's Guide

Overview

This application computes and stores the distance between the vertices of a shape, defined as a group of contours, and a line passing through the centers of each of the contours.

Supported File Formats

Output files must support per-vertex data attributes; The current version (1.0.0) writes the following data formats:

• Loni UCF
• OpenDX

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. To increase the amount of JVM memory, pass an argument to your java virtual machine an argument:

java -Xmx512M -jar ShapeCurvature.jar input_file output_file

this sets the ammount of memory to 512MB. Note: the -Xmx512M is the argument that requests additional memory.

Command line arguments

The program is controlled by use of command line arguments. The complete table of command line arguments follows. The "Default" values listed are the values used by the program if the corresponding 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	Type	Required	Description	Notes
-help	flag	No	Prints help and usage information.
-examples	flag	No	Prints examples of common usage.
-version	flag	No	Prints version number of this application.
-verbose	flag	No	Enables detailed status messages.
-license	flag	No	Prints license details, and exits.
-euclidean	flag	No	Uses Euclidean distances.	Euclidean distances are used if no metric is selected.
-taxicab	flag	No	Uses Taxicab distances.
-dx	flag	No	Write output as a dx file.
-ucf	flag	No	Write output as a Ucf file.
-attribute	String	No	Names the output file attribute in which distances are saved.	If unspecified the attribute will be named distance
-fromcenter	flag	No	Calculate all distances from the center of the entire shape.
-frompoint	Float	No	Calculate all distances from the 3d point following this argument.	Example: -frompoint 1.0 1.5 2.3
-fromcore	flag	No	Calculate all distances from medial core of the shape.
-writeCore	File	No	Write the medial core coordinates to an output file whose structure matches the medial distance output file
-writeCoreVertices	File	No	Write the medial core coordinates to an output text file
	File	Yes	An input file path.
	File	Yes	An output file path.
-pipeline	flag	No	Write pipeline descriptor file to output and exit.
-twiki	flag	No	Write TWiki command line argument table to output and exit.

Examples of common usage

In these examples we assume that the MedialDistance application is saved in a file named MedialDistance.jar.

Ex 1) java -jar MedialDistance.jar -help

• Print a usage summary to the console output.

Ex 2) java -jar MedialDistance.jar -attrName dist DistanceContour.ucf output.ucf

• 1. Read input file from DistanceContour.ucf. The application will calculate the distance between a vertex and the center of mass of the contour containing that vertex.
• 2. This distance will be written as per-vertex attributes to output file and, the attribute will be named 'dist' as given.
• 3. Distance calculation method is Euclidean (the default).
• 4. The output file name is output.ucf as provided, and output file type will the same as the input file type since no alternate output file type is provided.

Ex 3) java -jar MedialDistance.jar -verbose -taxicab -dx DistanceContour.ucf output.dx

• 1. Read input file from DistanceContour.ucf. The application will calculate the diatance between a vertex and the center of mass of the contour containing that vertex.
• 2. Distances will be calculated with the 'taxicab' distance metric.
• 3. These distance will be written as per-vertex attributes to output file in a file attribute named 'distance'.
• 4. The output file is an OpenDX file named "output.dx".
• 5. The "-verbose" command line flag will cause details of the program's status to be written to the console output.

---

Detailed Description of the program

• Common Runtime Errors:

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 input file

if input file doesn't contain contour, 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 shape

if shape has no face set or the face set has no faces the application will exit.

Data formats supported

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 contours. If the input file does not contain contours, the program will exit. Next, the applicaiton will verify that the output file format supports per-vertex attributes. If not, the program will print an error message, and will show the command line arguments that will enable the user to choose a valid output file format.

The following input formats are currently supported (February 28, 2007)

Abbreviated Name	Description	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.
Minc Line OBJ	n/a	Since this file type does not allow arbitrary data values at mesh vertices, you must use either '-dx' or '-ucf' command argument in order to have attribute saved.

The following output formats are currently supported (February 28, 2007)

Abbreviated Name	Description	Notes
UCF	Laboratory of Neuro-Imaging (LONI) Universal Contour Files (UCF's).	There will be only one contour in the file that represents the path between two vertices. The point starts from the sink vertex and end at the source vertex.
Dx	OpenDX general format data files (using "positions" and "connections" to define the mesh).	supports arbitrary data components at all mesh vertices

---

Algorithm

• a. For each contour in the grid, obtain vertices consisting of that contour.
• b. Calculate center of mass of the contour. The center of mass is calculated taking the average of the coordinates of that contour's vertices.
• c. Calculate the diatance between a vertex and the center of mass of the contour containing that vertex.

Note: if either of the -fromcenter or -frompoint arguments are used this point is used to compute the distances.

System requirements

• Platform - Platform independent
• Operating System - Any OS that has Java 1.5 or greater.

Restrictions, Exclusions, Limitations

Assumes that contour shapes use an IContourEdgeSet (except for UCF, which are handled as a special case)

Acknowledgments

This program is a product of the CCB Shape Tools program.