1
0
mirror of https://github.com/moparisthebest/Simba synced 2024-11-11 20:05:03 -05:00
Simba/Doc/sphinx/scriptref/colourfinding.rst
2010-09-02 18:32:23 +02:00

157 lines
4.3 KiB
ReStructuredText

.. _scriptref_colour:
.. note::
Not all colour finding functions have been documented yet.
Colour Finding
==============
Finding colours on the screen is quite simple. Simba offers methods like
``FindColor`` to locate colours on the screen.
These methods are usually composed out of several (but not always all)
components:
* The colour to search for.
* An area to search in, defined by *x1*, *y1*, *x2*, *y2*.
* Tolerance applied to the colour matching. With a maximum tolerance all
colours are matched.
* Spiral. A spiral defines a point where the search will start from.
This is particulary useful if you want the first result near specific
coordinates.
* AreaSize. The size the box of colours should be. Usually this is not
adjustable.
* A single point in *x*, *y* can be returned, or a set or points called
a *TPointArray*.
.. note::
Other techniques exist, which involve relative point distance from one point
to another; these are found in the :ref:`_scriptref_DTM` section.
.. note::
Although the documentation uses the ``English`` spelling of
``colour``; the code for compatibility sake uses ``color``, without the u.
Colour Finding Methods
----------------------
A list of all colour finding methods in Simba.
SimilarColors
~~~~~~~~~~~~~
.. code-block:: pascal
function SimilarColors(C1, C2, Tolerance: Integer): Boolean;
SimilarColors returns true if the two passed colours are *similar* given the
passed tolerance.
FindColor
~~~~~~~~~
.. code-block:: pascal
function FindColor(var x, y: Integer; col, x1, y1, x2, y2: Integer):
Boolean;
FindColor returns true if the exact colour given (col) is found in the box
defined by *x1*, *y1*, *x2*, *y2*.
The point is returned in *x* and *y*.
It searches from the top left to the bottom right and will stop
after matching a point.
FindColorTolerance
~~~~~~~~~~~~~~~~~~
.. code-block:: pascal
function FindColorTolerance(var x, y: Integer; col, x1, y1, x2, y2, tol:
Integer): Boolean;
FindColorTolerance returns true if a colour within the given tolerance range
*tol* of the given colour *col* is found in the box defined by *x1*, *y1*,
*x2*, *y2*.
Only the first point is returned in *x* and *y*.
Whether or not a colour is within the tolerance range is determined by the
:ref:`scriptref_CTS` mode. It searches from the top left to the bottom right
and will stop after matching a point.
FindColors
~~~~~~~~~~
.. code-block:: pascal
function FindColors(var pts: TPointArray; col, x1, y1, x2, y2): Boolean;
FindColors returns a list of all points that match the colour *col* in an area
defined by *x1*, *y1*, *x2*, *y2*. It returns true if one or more points have
been found.
FindColorsTolerance
~~~~~~~~~~~~~~~~~~~
.. code-block:: pascal
function FindColorsTolerance(var pts: TPointArray; col, x1, y1, x2, y2,
tol: Integer): Boolean;
FindColorsTolerance returns true if at least one point was found.
A point is found if it is within the given tolerance range *tol*
of the given colour *col* and inside the box defined by *x1*, *y1*, *x2*, *y2*.
Whether or not a color is within the tolerance range is determined by the
:ref:`scriptref_CTS` mode.
It searches from the top left to the bottom right and will find all
matching points in the area.
FindColorSpiral
~~~~~~~~~~~~~~~
.. code-block:: pascal
function FindColorSpiral(var x, y: Integer; color, xs,ys,xe,ye:Integer):
Boolean;
Same as FindColor, but starts searching from *x*, *y*.
FindColorSpiralTolerance
~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: pascal
function FindColorToleranceSpiral(var x, y: Integer; color,
xs,ys,xe,ye,tolerance:Integer): Boolean
Same as FindColorTolerance, but starts searching from *x*, *y*.
FindColorsSpiralTolerance
~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: pascal
function FindColorsSpiralTolerance(x, y: Integer;
var pts: TPointArray; col, x1, y1, x2, y2, tol: Integer): Boolean;
Same as FindColorsTolerance, but starts searching from *x*, *y*.
.. _scriptref_CTS:
Colour tolerance
----------------
Simba contains several algorithms for determining if two colours are equal
given a tolerance. There are three algorithms:
.. XXX FIXME COMPLETE ME
.. note::
This is a stub and needs to be expanded.
* CTS 0:
* CTS 1:
* CTS 2: