Doc: DTM additions, fixes for ui and colourfinding.

Doc/sphinx/features/ui.rst

@@ -4,8 +4,7 @@ User Interface
 Menu items
 ----------
 (Format)
-Main menu item
-  Submenu item, [shortcut, ]description
+Main menu item Submenu item, [shortcut, ]description
 
 File Menu
 ~~~~~~~~~

Doc/sphinx/scriptref/colourfinding.rst

@@ -1,9 +1,12 @@
-..  _scriptref_colour:
+.. _scriptref-colour:
 
 
+.. _scriptref-finding:
+
 Colour Finding
 ==============
 
+
 Finding colours on the screen is quite simple. Simba offers methods like
 ``FindColor`` to locate colours on the screen.
 
@@ -35,7 +38,7 @@ components:
 
 .. note::
     Other techniques exist, which involve relative point distance from one point
-    to another; these are found in the :ref:`_scriptref_DTM` section.
+    to another; these are found in the :ref:`scriptref-dtm` section.
 
 .. note::
 

Doc/sphinx/scriptref/dtm.rst

@@ -1,8 +1,136 @@
-
-.. _scriptref_dtm:
+.. _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
 -------------
@@ -11,6 +139,7 @@ DTMFromString
 
     function DTMFromString(const DTMString: String): Integer;
 
+Load a DTM from a string generated by the DTM Editor.
 
 SetDTMName
 ----------
@@ -20,6 +149,9 @@ 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
 -------
 
@@ -27,6 +159,8 @@ FreeDTM
 
     procedure FreeDTM(DTM: Integer);
 
+Free a DTM identified by *DTM*.
+
 
 FindDTM
 -------