Simba/Doc/sphinx/scriptref/dtm.rst

.. _scriptref-dtm:

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 :ref:`scriptref-finding`.

The structure of a DTM looks like this:


.. figure:: ../../Pics/DTM.png
   :scale: 100 %
   :alt: Structure of a DTM

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:

.. code-block:: pascal

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

Then we could create the following pDTM structure:

.. code-block:: pascal

	// 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:

.. code-block:: pascal

    // 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.

.. Colour and Tolerance
.. --------------------

.. \forall p \in P, \forall t \in Tol, \forall c \in Col : T(C(p), c) \leq t

..    With C() defining the colour at the given point, and T() defining the tolerance
..    between the two given colours.

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)

pDTM and TDTM
-------------

One may know DTM's as a different type:

.. code-block:: pascal

  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 *pDTMtoTDTM* and *TDTMtopDTM* 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
-------------

.. code-block:: pascal

    function DTMFromString(const DTMString: String): Integer;

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

SetDTMName
----------

.. code-block:: pascal

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

.. code-block:: pascal

    procedure FreeDTM(DTM: Integer);

Free a DTM identified by *DTM*.


FindDTM
-------

.. code-block:: pascal

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


FindDTMs
--------

.. code-block:: pascal

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


FindDTMRotatedSE
----------------

.. code-block:: pascal

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


FindDTMRotatedAlternating
-------------------------

.. code-block:: pascal

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


FindDTMsRotatedSE
-----------------

.. code-block:: pascal

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


FindDTMsRotatedAlternating
--------------------------

.. code-block:: pascal

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


AddMDTM
-------

.. code-block:: pascal

    function AddMDTM(const d: TMDTM): Integer;


AddDTM
------

.. code-block:: pascal

    function AddDTM(const d: TMDTM): Integer;


AddSDTM
-------

.. code-block:: pascal

    function AddSDTM(const d: TSDTM): Integer;


GetDTM
------

.. code-block:: pascal

    function GetDTM(index: Integer) : TMDTM


SDTMToMDTM
----------

.. code-block:: pascal

    function SDTMToMDTM(Const DTM: TSDTM): TMDTM;


PrintDTM
--------

.. code-block:: pascal

    procedure PrintDTM(const DTM : TMDTM);


MDTMToSDTM
----------

.. code-block:: pascal

    function MDTMToSDTM(Const DTM: TMDTM): TSDTM;


CreateDTMPoint
--------------

.. code-block:: pascal

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