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 colour, 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 Colour Finding.

The structure of a DTM looks like this:

Where each point in a DTM has a colour, 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.

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[0] = Point(123, 456);

// Subpoints
dtm.p[1] = Point(122, 460)
dtm.p[2] = Point(120, 450)

Note that we do not include other variables, such as colour, 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[0] = Point(0, 0);

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

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

Colour and Tolerance

The colour 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 colour is similar enough to the given colour; if this is the case, we say that the colours matched.

With no Area Size and Area Shape specified we say that a DTM matches if for each point in the DTM, the colour at the relative point matches the colour 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 colour with the given tolerance. Area Shape is currently not implemented, mainly because we haven’t found a good use for area shapes.

Loading a DTM from a string

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.

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;

FindDTMRotated 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 0 degrees and alternatives between - and + aStep to search for the DTM.

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.

AddMDTM

function AddMDTM(const d: TMDTM): Integer;

AddDTM

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)

AddSDTM

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);

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.