TPSPLINE
Thin-plate spline
14 Sept. 1994
Copyright, (c), 1994, F. James Rohlf
Department of Ecology and Evolution
State University of New York at Stony Brook
Stony Brook, NY 11794
Rohlf@life.bio.sunysb.edu
The program computes the thin-plate spline transformations and
the weighted principal warps (the "partial warps") of a shape as
described in Bookstein (1989) "Principal warps: thin-plate
splines and the decomposition of deformations", IEEE trans. on
Pattern Analysis and Machine Intelligence. 11(6):567-585. It is
also described in the "orange book" for those who have a copy from
the Michigan Morphometrics Workshop held in May 1988. It is also
described in the proceedings of that workshop (Rohlf and
Bookstein, 1990) One of these publications must be consulted in
order to understand what this program does. But you can still
look at the pretty pictures without reference to those papers.
This README.TPS file consists of the following sections:
1. Installation
2. Operation of the program
3. Data file format
4. Entering points using the mouse
5. Description of the thin-plate spline menu
6. Description of Warp Menu
7. Description of output listings
8. Requirements
9. Program limitations
10. Sample data files
11. BGI files
12. Changes from previous versions
----------------------------------------------------------------
1. Installation
To use the program, extract the files
to your working disk. The program is distributed in the
form of a self-extracting archive file using the PKZIP program.
To extract all of the files you should place the distribution disk
in a floppy disk drive (e.g., A:) and then make to subdirectory
where you want the files to be stored the current directory (e.g.,
c:\tpspline). Then type "a:tpsz" to extract all of the files.
You can also extract single files (e.g., the readme.tps file) by
typing the name of the file (e.g., "a:tpsz readme.tps"). In
addition you need to copy appropriate BGI files. You will need a
BGI file for your graphics monitor and one or more for the
printers you plan to use to print graphics. The are distributed
in a separate file. See Section "11. BGI files". If in doubt,
copy them all and the program will use the appropriate one. You
can also copy some of the test data files. To run the program
type "tpspline". The program will then ask whether the data are
to be furnished in files or by using a mouse. If you have a mouse
it must be initialized before you enter the tpspline program
(usually by typing the command "mouse").
There are two versions of the program. One for DOS real mode
and another for DOS protected mode (DPMI). Their use is identical
except that the protected mode version requires that the RTM.EXE
program be present (it will be loaded automatically in order to
switch into protected mode). Unless you are running software that
provides DPMI services (e.g., Windows, 386Max, OS/2) you also need
to have the program DPMI16BI.OVL present in the directory with the
TPSPLINE program. The protected mode version requires an 80386 or
80486 computer and is able to use both ordinary RAM and extended
memory so that larger datasets can be processed (but that is
usually not a problem for typical applications of this program).
It does not make use of overlay files.
Note: this version requires the set of BGI graphics driver
files whose names begin with an underscore character "_".
----------------------------------------------------------------
2. Operation of the program
Enter the name of the program:
TPSPLINE
and the program will display its main menu. Initially, only
the first and last choices will be available (show in higher
intensity on the screen).
The first choice open another window where you will be asked
for the names of the two data files and the name to give to an
output listing file. The contents of the data files will be
scrolled by as they are read. The display will stop if an error
is found. If you have a mouse installed, you can also leave the
file names blank. You will then be presented with a grid where
you can enter landmark points for two objects.
See the section below on "Entering data points with a mouse" for
more details.
The last choice will allow you to specify the graphics hardcopy
device. A window will be displayed that lists the various devices
and their modes. Another window will then be displayed that asks
for a device or file name. If you would like the output written
to a file for later use then enter a valid file name. To have the
output sent directly to a printer attached to a printer port enter
LPT1 or LPT2. For output directly to a printer or a plotter
attached to a serial port enter COM1 or COM2. In the later case
you must also specify the baud rate, parity, number of data bits,
and whether or not to use XON/XOFF protocol.
The available baud rates are: 300, 1200, 2400, 4800, and 9600.
Parity can be N (none), E (even), or O (odd).
The number of data bits can be 7 or 8.
Use the symbol "X" to indicate XON/XOFF.
These codes are entered after the port name. For example, for
a plotter attached to COM1 and working with 2400 baud, no parity,
8 data bits, and using XON/XOFF enter the following:
COM1,2400,N,8,X
----------------------------------------------------------------
3. Data file format
Each specimen's data are stored in a separate file. The format
a file is simply the number of landmarks on the first line,
followed by the x,y-coordinates for the specimen, followed by the
number of "background" contours to be entered (these are displayed
but not used for computations), followed by the number of
x,y-corrdinate pairs for each contour. Look at the example files
for more help.
Example of the data file format (does NOT include the comments to the
right of each line):
4 <--- number of landmarks
0 1 <--- x,y coordinates
-1 0 "
0 -1 "
1 0 "
2 <-- number of background contours
4 <-- number of points in first contour
0 2 <-- x,y coordinates of first contour
-1 1 "
-2 0 "
-1 -1 "
4 <-- number of points in second contour
0 -2 <-- x,y-corrdinates of second contour
1 -1 "
2 0 "
1 1 "
----------------------------------------------------------------
4. Entering points using the mouse
Just point to a location on the grid and click the left button.
Repeat for the maximum landmarks. When done with the first
specimen press enter (actually any key will work) and then point
and click for the the background contours. Press Enter to mark
the end of each contour. Press Enter again to indicate that the
last contour has been completed. Repeat this process for the
second specimen. You must enter the same number of landmarks as
for the first specimen and they must be entered in the same order.
At present there is no edit feature to correct an error -- so be
careful! Messages will be displayed to tell you what information
the computer expects you to enter.
*** NOTE: the ability to enter background points has been disabled in
this version in order to increase the number of points that the
program can process. ***
After the data have been entered by either of the above two
procedures, a small menu will be displayed at the bottom of the
screen.
----------------------------------------------------------------
5. Description of the thin-plate spline menu
Keys Description
--- --------------------------------------------------
H Help (an explanation of the menu choices will be displayed).
C Compute and then display the results (the original grid and the
landmarks will be shown transformed by the thin-plate spline).
1 Display object 1.
2 Display object 2.
B Display both specimens in the original untransformed space.
- If you wish to make a landmark "inactive" (displayed but not used
for the computations). You will be given a chance to point and
click at the landmark to make inactive.
+ Make a point active again.
A Make all points active.
R Create a report in the listing file.
You should not select this until after you have pressed C.
P Print the current screen plot on the graphics output device.
ESC Press the ESC key (or the letter Q) to quit.
----------------------------------------------------------------
6. Description of Warp Menu
(note: a limitation at present is that all landmarks
are used for the computation of the warps).
Keys Description
--- --------------------------------------------------
0,A Displays the affine component of the thin-plate spline.
N Displays the total non-affine components of the thin-plate
spline ("sum of the warps").
E, M, or V
Select whether partial warps are to be displayed in order of
their "energy," magnitude of their contribution to the
thin-plate spline, or in reverse order of their eigenvalue.
If "E" is selected then the first warp will be the one that
contributes most energy to the thin-plate spline
transformation to fit object 1 to object 2. If "V" is
selected then the first warp will be the one with the
SMALLEST eigenvalue and corresponds to the largest scale
feature of the deformation. If "M" is selected then the
order will be by magnitude. The default is "V".
An eigenvalue should be interpreted as an inverse index to
the scale of the corresponding principal warp. A large
energy value means that the principal warp reflects a
small-scale deformation of object 1
Magnitude is a measure of how important a principal warp is
for fitting to object 2. It is computed as the sum of the
squared partial warp weights.
The bending energy for a principal warp can be computed as
the product of its eigenvalue and its magnitude.
1..9 display warps 1 through 9 (in order determined by the option
described above. Shows energy & eigenvalue for that warp.
+ or - displays the next or the previous warp (in the order
determined by the E, M, or V option described above).
R Write a report to the output listing file.
H Display a help screen.
P Print the current screen plot on the graphics output device.
ESC Exit the warp menu and return to the main menu.
----------------------------------------------------------------
7. Description of reports in the listing file
The report option in the menus will cause files to be produced
that contain the numerical results of the computations.
Example of report files for the 5-point example in Bookstein
(1989) fig. 4 on page 572.
File: "bkeg1.1"
5 5-point example
3.6929 10.3819
6.5827 8.8386
6.7756 12.0866
4.8189 11.2047
5.6969 10.0748
0
File: "bkeg1.2"
5 5-point example y+4
3.9724 6.5354
6.6969 4.1181
6.5394 7.2362
5.4016 6.4528
5.7756 5.1142
0
Sample output:
TPS -- thin-plate spline analysis
F. James Rohlf
version: 1/27/94
Reading specimen 1 from file: bkeg1.1
Number of landmarks = 5
Reading specimen 2 from file: bkeg1.2
Number of landmarks = 5
Specimen 1 has been centered over specimen 2 for display
(Initial displacement: deltaX = 0.10040 deltaY = -4.78545
Number of landmarks = 5
Active landmarks (5) =
1 2 3 4 5
Bending energy = 0.04299949
X: min = 3.79330 max = 6.87600
Y: min = 4.05315 max = 7.30115
Translation values (after the initial displacements):
X Y
1.12906327 1.49413789
Affine transformation matrix:
X Y
1: 0.87472587 -0.29556056
2: -0.02886041 0.92163259
Coefficients for nonaffine part of thin-plate spline:
Landmark X Y
1 -0.03803014 0.04244693
2 0.02318775 0.01591661
3 -0.02475506 0.02881348
4 0.07978226 -0.04542552
5 -0.04018482 -0.04175150
Warps
Number of landmarks = 5
Active landmarks = ALL
Translation values (after the initial displacements):
X Y
1.12906327 1.49413789
Affine transformation matrix:
X Y
1: 0.87472587 -0.29556056
2: -0.02886041 0.92163259
Weights for each partial warp to create the total spline:
Partial warp X Y
1 -0.24115491 0.02790552
2 0.16632143 -0.38712707
(Note: multiply above by sqrt(2) for scaling based on r2 ln(r2) metric)
Contribution of each partial warp towards the total spline:
Partial warp Eigenvalue Energy Magnitude
1 0.28375049 0.01672267 0.05893441
2 0.14801326 0.02627682 0.17753019
---------- ----------
0.43176376 0.04299949
(Note: multiply energy values by 2 for scaling based on r2 ln(r2) metric)
Normalized Principal Warps:
1 2
Landmarks ----------------------
1 | 0.215241 -0.494070
2 | -0.326510 -0.241538
3 | 0.134579 -0.336974
4 | -0.655347 0.470010
5 | 0.632038 0.602573
----------------------------------------------------------------
8. Requirements
This program requires a graphics monitor. The standard
monitors (e.g., CGA, EGA, VGA, 8514, Hercules) are supported. In
addition, it is useful to have a mouse (but it is not required for
processing data in files). A math coprocessor (8087 chip) is
useful because the program does a lot of computation -- but it is
not required. A full 640K of RAM is needed for any realistic
problem.
While a datafile can be processed if you do not have a mouse,
experimentation with adding or deleting points is more direct with
a mouse. Using a mouse to enter coordinates also allows you to
experiment more easily with different configurations of points.
You could even "digitize" a specimen by holding a transparency up
to the screen and clicking when the mouse cursor is under the
desired landmark.
The graphics output devices that are supported are listed above
(see section 2).
----------------------------------------------------------------
9. Program limitations
The help key in the program gives the size limitations of
the current version of the program. At the time this README file
was prepared the limitations for the DOS version were:
max landmarks = 40
max background contours = 10
max points per contour = 120
Note that dynamic memory allocation methods are used and thus these
limits may not be achieved if the amount of free RAM is not
sufficient.
For the DPMI protected mode version the maximum number of
landmarks is 60.
The program works on both color and monochrome graphics screens
(those supported by Borland's Turbo Pascal version 7.0) but the
visual distinction between different kinds of points requires a
color monitor.
----------------------------------------------------------------
10. Sample data files
There are several sample data files on the distribution disk:
Data corresponding to the 5 landmark example in Bookstein (1989)
Fig. 4 page 572.
bkeg1.1
bkeg1.2
Two pairs of examples from Thompson (1917, On growth and form.
Cambridge:London 753 pp.) Compare Fig. 517 with 518 and Fig. 519
with 520.
fig517.dta
fig518.dta
fig519.dta
fig520.dta
Examples from Sneath (1967, Trend-surface analysis of transformation
grids. J. Zoology, 151:65-122). All figs. can be compared with each
other.
sneath1.dta
sneath2.dta
sneath3.dta
sneath4.dta
----------------------------------------------------------------
11. BGI files
A number of files are provided for graphics support. They are
distributed in the BGI.ZIP and BGI.EXE files. Extract the
desired files as for the tpspline program itself.
Graphics adapters:
ATT.BGI AT&T6300
CGA.BGI IBM CGA, MCGA
EGAVGA.BGI IBM EGA, VGA
HERC.BGI Hercules monochrome graphics
IBM8514.BGI IBM 8514
PC3270.BGI IBM 3270PC
Graphics printers and plotters:
_CANON.BGI Canon LBP-8 printer
_CFX.BGI 9-pin color dot matrix
_CLQ.BGI 24-pin color dot matrix
_DIC.BGI Kodax Diconic printer
_DJ.BGI HP DeskJet printer
_DJC.BGI HP Color DeskJet printer
_DMPL.BGI DM/PL plotters
_FX.BGI Epson 9-pin printers
_HP7470.BGI HP7470 plotter
_HP7475.BGI HP7475 plotter
_HP7550.BGI HP7550 plotter
_HP7585.BGI HP7585 plotter
_LQ.BGI Epson 24-pin printers
_LJ.BGI HP LaserJet printer
_LJ3R.BGI HP LaserJet III printer
_OKI92.BGI Okidata 92 native mode
_PJET.BGI HP paintjet
_PP24.BGI 24 pin dot matrix
_TJ.BGI HP ThinkJet printer
For the above devices you will need to know how it is attached
to your computer (printer or serial port). In the case of a
serial port you will also need to know the baud rate, parity,
number of data bits, and whether the XON/XOFF protocol is used.
Graphics file formats:
_AI.BGI Adobe Illustrator Postscript
_BMP.BGI MS Windows bitmap files
_CGM.BGI CGM files
_DXF.BGI AutoCad
_IMG.BGI GEM IMG files
_PCX.BGI PCX paint file format
_TIFF.BGI Compressed TIFF format
_UTIFF.BGI Uncompressed TIFF format
_WPG.BGI WordPerfect WPG files
The BGI files whose names begin with "_" are part of the
GRAF/DRIVE package from Flemming Software as is the GCOPY.EXE
program that can be used to copy graphic files to a printer or
plotter. Type GCOPY and instructions will be displayed.
----------------------------------------------------------------
12. Changes from previous versions:
11/11/91 : Corrected display of eigenvalues in the report. Fixed
the use of the + and - keys to display warps past the
9th. I now print out the displacements that I add to
specimen 1's x and y-coordinates so that the center of
specimen 1 will display on top of the center of specimen 2.
11/29/91 Fixed a problem with the order in which the warps were
displayed and labelled.
7/6/93 Recompiled for BP 7 and added support for DOS DPMI mode.
9/27/93 Fixed yet another problem with the ordering of the warps.
1/27/94 Fixed yet another problem with the ordering of the warps
and also improved the formatting of the numerical output.