# Deformable Template Models (DTM)¶

A DTM is in my view just a relatively simple way of defining a relationship between several points. Each of these points have a relative offset to each other, and may different in color, tolerance, area size and shape. A DTM generally consists out of one Main Point, and several Sub Points.

Finding functions for DTM include the usual parameters. For explanation on these, see Color Finding.

The structure of a DTM looks like this:

Where each point in a DTM has a color, tolerance, area size and area shape entity. The main point’s point is typically `(0, 0)`, and all the subpoint points are relative to the main point.

## Introduction¶

### Example of a simple DTM¶

If one was to create his own DTM, he would first have to think of a useful DTM structure.

Say:

```MainPoint = (123, 456)
SubPoint_1 = (122, 460)
SubPoint_2 = (120, 450)
```

Then we could create the following MDTM structure:

```// Give dtm.p a length of three.
// Mainpoint
dtm.p = Point(123, 456);

// Subpoints
dtm.p = Point(122, 460)
dtm.p = Point(120, 450)
```

Note that we do not include other variables, such as color, tolerance, area size and area shape; they are of no importance in this example.

However, this code is not very clear about the DTM’s points. Better would be to write:

```// Give dtm.p a length of three.
// Mainpoint
dtm.p = Point(0, 0);

// Subpoints
dtm.p = Point(-1, 4)  // 122 - 123 = -1, 460 - 456 = 4
dtm.p = Point(-3, -6) // 120 - 123 = -3, 450 - 456 = -6
```

As you can see it is perfectly valid to use negative points.

### Color and Tolerance¶

The color value of a point in a DTM is just a RGB integer value. Black = 0, Red = 255, White = 16777215, et cetera.

The value tolerance decides if a color is similar enough to the given color; if this is the case, we say that the colors matched.

With no Area Size and Area Shape specified we say that a DTM matches if for each point in the DTM, the color at the relative point matches the color in dtm with the given tolerance.

### Area Size and Shape¶

Area Size and Shape add that nifty extra functionality to DTM’s. Area Size defines the area that should all match the color with the given tolerance. Area Shape is currently not implemented, mainly because we haven’t found a good use for area shapes.

It is also possible to load a DTM from a zipped string. The details of the algorithm will not be explained here. (Have a look at dtm.pas if you’re interested)

### MDTM and TDTM¶

One may know DTM’s as a different type:

```TDTMPointDef = record
x, y, Color, Tolerance, AreaSize, AreaShape: integer;
end;

TDTMPointDefArray = Array Of TDTMPointDef;

TDTM = record
MainPoint: TDTMPointDef;
SubPoints: TDTMPointDefArray;
end;
```

The MML provides the two functions MDTMtoTDTM and TDTMtoMDTM to directly convert between the two types.

### Main Point and AreaSize / Shape¶

The main point’s area size and shape are not used in the current implementation. It wouldn’t be that hard to add them, however.

## DTM Functions¶

### DTMFromString¶

```function DTMFromString(const DTMString: String): Integer;
```

Load a DTM from a string generated by the DTM Editor.

### SetDTMName¶

```procedure SetDTMName(DTM : integer;const name : string);
```

Assign the DTM a name. Very useful for debugging purposes as it allows the programmers to find out what DTMs are not being freed.

### FreeDTM¶

```procedure FreeDTM(DTM: Integer);
```

Free a DTM identified by DTM.

### FindDTM¶

```function FindDTM(DTM: Integer; var x, y: Integer;
xs, ys, xe, ye: Integer): Boolean;
```

FindDTM is the most basic DTM finding function. It takes a box to search in, defined by x1, y1, x2, y2; and if the DTM is found, it will set x and y to the coordinate the DTM was found at and it will also return true. Else, it returns false. Once a DTM is found, it will stop searching. In other words; it always returns the first found DTM.

### FindDTMs¶

```function FindDTMs(DTM: Integer; var p: TPointArray;
xs, ys, xe, ye: Integer): Boolean;
```

FindDTMs is like FindDTM, but it returns an array of x and y, as the TPointArray type.

### FindDTMRotatedSE¶

```function FindDTMRotatedSE(DTM: Integer; var x, y: Integer;
xs, ys, xe, ye: Integer; sAngle, eAngle, aStep: Extended;
var aFound: Extended): Boolean;
```

FindDTMRotatedSE behaves like FindDTM. Only, it will rotate the DTM between sAngle and eAngle by aStep each time. It will also return the angle which the DTM was found at. Start rotating at StartAngle.

### FindDTMRotatedAlternating¶

```function FindDTMRotatedAlternating(DTM: Integer; var x, y: Integer;
xs, ys, xe, ye: Integer;
sAngle, eAngle, aStep: Extended; var aFound: Extended): Boolean;
```

FindDTMRotatedAlternating behaves like FindDTM. Only, it will rotate the DTM between sAngle and eAngle by aStep each time. It will also return the angle which the DTM was found at. Starts at (sAngle + eAngle) / 2 degrees and alternates between - and + aStep to search for the DTM. It finds the closest math to (aAngle+eAngle) / 2.

### FindDTMsRotatedSE¶

```function FindDTMsRotatedSE(DTM: Integer; var Points: TPointArray;
xs, ys, xe, ye: Integer; sAngle, eAngle, aStep: Extended;
var aFound: T2DExtendedArray) : Boolean;
```

FindDTMsRotatedSE behaves like FindRotatedDTMSE, but finds all DTM occurances. Since one point can be found on several angles, aFound is a 2d array.

### FindDTMsRotatedAlternating¶

```function FindDTMsRotatedAlternating(DTM: Integer;
var Points: TPointArray; xs, ys, xe, ye: Integer; sAngle, eAngle, aStep:
Extended; var aFound: T2DExtendedArray) : Boolean;
```

FindDTMsRotatedAlternating behaves like FindRotatedDTMAlternating, but finds all DTM occurances. Since one point can be found on several angles, aFound is a 2d array.

```function AddMDTM(const d: TMDTM): Integer;
```

```function AddDTM(const d: TMDTM): Integer;
```

Load a TMDTM structure as DTM in Simba’s system. (After it is loaded you can use it in FindDTM, etc)

```function AddSDTM(const d: TSDTM): Integer;
```

Load a TSDTM structure as DTM in Simba’s system. (After it is loaded you can use it in FindDTM, etc)

### GetDTM¶

```function GetDTM(index: Integer) : TMDTM
```

Returns the TMDTM of the given DTM index.

### SDTMToMDTM¶

```function SDTMToMDTM(Const DTM: TSDTM): TMDTM;
```

Convert a SDTM to MDTM.

### PrintDTM¶

```procedure PrintDTM(const DTM : TMDTM);
```

Print the DTM contents.

### MDTMToSDTM¶

```function MDTMToSDTM(Const DTM: TMDTM): TSDTM;
```

Convert a MDTM to SDTM.

### CreateDTMPoint¶

```function CreateDTMPoint(x,y,c,t,asz : integer; bp : boolean) : TMDTMPoint;
```

Create a DTM point.

### DTMExists¶

```function DTMExists(index: Integer): Boolean
```