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


   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:


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:



                       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



              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


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


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


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


   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


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.



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.





Examples from Sneath (1967, Trend-surface analysis of transformation

grids.  J. Zoology, 151:65-122).  All figs. can be compared with each







                             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



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.