Compute Landmark Warp User's Guide Version 1.0
Overview
This is an application for computing a global warp, specified by two groups of homologous landmarks. A warp is a continuous function that maps
a point in the input space to a point in the output space. Each landmark point in the input space maps to it's equivalent point in the output space
(except for rigid warps, in which case the output point is the best fit to the input landmark). The behavior of points between landmarks
varies with the type of warp computed.
The user specifies which type of warp to compute and provides landmark data, which can be in several formats.
For all transformations, the landmarks must be in
general position, and may not contain duplicates, otherwise an error will occur.
The application has three required arguments. The first two arguments are the landmarks. The first required argument is the filename of the reference landmarks, and the second required argument is the filename of the target landmarks. Landmarks can be specified as either a list of points, as described in the glossary or as a
ShapeTools-compatible shape, where the vertices are used as landmarks. In the case of a shape being used for landmarks, the the homology is derived from the indices, and any duplicate vertices are removed before computing the warp. These files must specify an equal number of points with equal dimension. The third required argument is the output filename for the warp. This file will encode the parameters that define the transformation, as defined in the landmark warp framework. If this file exists, an error occur; however, if the user adds the '-overwrite' flag, the file will always be written. For a usage page, use the '-usage' flag or no arguments. For verbose output, add the '-verbose' flag. The name and version of the application can be written with the '-version' flag. If there is an error executing the program, and you think a bug has occurred, the '-debug' flag will print more information for bug reporting.
Warp Types
Run the program with the flag '-usage' to see a list of flags for the following transformation types.
- Affine: This computes the best fit linear transformation with translation. This is implemented in all dimensions.
- Procrustes: This computes the best fit rigid transformation (rotation and translation) between the landmarks using Procrustes analysis. This is implemented in two and three dimensions.
- Generalized Procrustes: This computes the best fit similarity transformation (rotation, translation and scaling) between the landmarks using Procrustes analysis. This is implemented in two and three dimensions.
- Thin Plate: This computes the thin plate spline transformation. This is implemented in two and three dimensions. This works best for sparse landmarks. See the glossary for more details.
- Elastic: This computes the equilibrium elastic body transformation with hyperbolic forces. This is implemented in two and three dimensions. This works well for any number of landmarks. See the glossary for more details.
- Rigid Quaternion: This computes the rigid transformation (rotation and translation) between the landmarks using the dual number quaternion method. This is implemented in three dimensions only.
Examples
Consider two landmark files, 'reference.lm' and 'target.lm':
$ cat reference.lm
56.0 49.0
203.0 33.0
243.0 69.0
234.0 93.0
147.0 122.0
123.0 96.0
128.0 77.0
85.0 64.0
86.0 55.0
$ cat target.lm
81.0 44.0
275.0 11.0
335.0 61.0
320.0 94.0
203.0 135.0
169.0 98.0
179.0 74.0
123.0 60.0
125.0 49.0
The affine warp between these can be computed:
java -jar ComputeLandmarkWarp.jar -affine -ref reference.lm -tar target.lm -output affineWarp.lmw
which creates the file 'affineWarp.lmw':
$cat affineWarp.lmw
# LandmarkWarpFile 2007-04-24
LandmarkWarpFramework 1.0
ParameterBlock 1
AffineWarp 1.0 6
7.600529 -21.256329 1.3347276 -3.4101342E-4 -0.04565524 1.3326551
Similarly, the elastic warp can be computed:
java -jar ComputeLandmarkWarp.jar -elastic -ref reference.lm -tar target.lm -output elasticWarp.lmw
which creates the file 'elasticWarp.lmw':
$ cat elasticWarp.lmw
# LandmarkWarpFile 2007-04-24
LandmarkWarpFramework 1.0
ParameterBlock 2
SplineWarp 1.0 44
2.0 9.0 56.0 203.0 243.0 234.0 147.0 123.0 128.0 85.0 86.0 49.0 33.0 69.0 93.0
122.0 96.0 77.0 64.0 55.0 0.0033461528 -0.0022617148 0.0053170808 0.0025175514
-0.006643218 -0.0013062886 0.0035309687 -0.0012638154 -0.0015594659 -0.0020945936
0.0075757504 0.0061496175 -0.0044715675 -0.001585037 -0.0013184593 0.0034670155
-0.005777242 -0.0036227347 0.35082436 -0.05049379 0.007223502 0.34851807 4.0297174
-19.752417
HyperbolicElasticBodyBasis 1.0 2
2.0 0.01
Now, consider two shape files, 'reference.obj' and 'target.obj', which have homologous vertices.
The Dual Quaternion rigid warp between these shape can be computed:
java -jar ComputeLandmarkWarp.jar -dualquat -ref reference.obj -tar target.obj -output dqWarp.lmw
which creates the file 'dqWarp.lmw':
$ cat dqWarp.lmw
# LandmarkWarpFile 2007-04-20
LandmarkWarpFramework 1.0
ParameterBlock 1
DualQuaternionWarp 1.0 12
-0.22229518 -1.150993 0.021450909 0.97515684 0.095011786 -0.20010486
-0.0841847 0.9945221 0.061957683 0.2048954 -0.04357269 0.97781354
All warps can be computed in this way, using either landmark files or shapes.
If you would like to know the status of the program, you can use the '-verbose' flag:
java -jar ComputeLandmarkWarp.jar -dualquat -verbose -ref reference.obj -tar target.obj -output dqWarp.lmw
This will print messages to the console.
By default, the program fails before overwriting. To enable overwriting, you can use the '-overwrite' flag.
java -jar ComputeLandmarkWarp.jar -thinplate -verbose -overwrite -ref reference.obj -tar target.obj -output dqWarp.lmw
To get the usage, you may run the program with no arguments or the '-help' flag:
java -jar ComputeLandmarkWarp.jar -help
Usage Page
Usage: java -jar ComputeLandmarkWarp.jar [options] -ref reference-tar target -output output.lmw
| Argument | Type | REQ| Description | Notes |
|-overwrite |flag |No |Enables file overwriting | |
|-debug |flag |No |Enables additional error reporting | |
|-nu |Float |No |This argument is used to specify the nu| |
| | | | parameter in the elastic warp mode. | |
| | | |This must have a value between 0.0 and | |
| | | |0.5 | |
|-proc |flag |No |Indicates that Procrustes warp should | |
| | | |be computed. The default is Affine | |
|-genproc |flag |No |Indicates that Generalized Procrustes | |
| | | |warp should be computed. The default is| |
| | | | Affine | |
|-elastic |flag |No |Indicates that Elastic warp should be | |
| | | |computed. The default is Affine | |
|-dualquat |flag |No |Indicates that Dual Quaternion warp | |
| | | |should be computed. The default is | |
| | | |Affine | |
|-affine |flag |No |Indicates that Affine warp should be | |
| | | |computed. The default is Affine | |
|-thinplate |flag |No |Indicates that Thin Plate Spline warp | |
| | | |should be computed. The default is | |
| | | |Affine | |
|-tar |File |Yes |Used to specify the filename of the | |
| | | |target landmarks. | |
|-ref |File |Yes |Used to specify the filename of the | |
| | | |reference landmarks. | |
|-output |File |Yes |Used to specify the filename of the | |
| | | |output warp file | |
|-help |flag |No |Prints help and usage information. | |
|-version |flag |No |Prints version number of this | |
| | | |application. | |
|-verbose |flag |No |Enables detailed status messages. | |
|-license |flag |No |Prints license details, and exits. | |
|-twiki |flag |No |Writes command line arguments as a | |
| | | |TWiki format table to output and exit. | |
|-pipeline |flag |No |Write pipeline descriptor file to | |
| | | |output and exit. | |
|-pipelineJar |String |No |Specify path to an application jar |Example: |
| | | |file, as a pipeline resource. |"pipeline: |
| | | | |//localhos |
| | | | |t//home/ze |
| | | | |d/Connery. |
| | | | |jar" |
|-pipelineJvm |String |No |Specify a Java Virtual Machine called | |
| | | |by a pipeline. | |
|-pipelineJvmOptions
| |String |No |Specify Java Virtual Machine options | |
| | | |used by a pipeline. | |
DESCRIPTION:
This application computes a warp between two sets of landmarks. The
user specifies the type of warp using a flag. The default is
Affine. The landmarks can be specified in an ASCII file which has
space delimited coordinates and line delimited points. Alternatively,
the landmarks may be encoded as the vertices of a shape. There must
be the same number of reference and target landmarks, and they must
have the same dimension. ASCII landmark files should not have any
duplicates; however if a shape file has duplicate points, they are
removed. The output file will be a .lmw type file.
