1
0
mirror of https://github.com/moparisthebest/Simba synced 2024-12-12 02:22:20 -05:00
Simba/Doc/sphinx/scriptref/colourfinding.rst
2011-07-18 13:08:51 +02:00

341 lines
8.8 KiB
ReStructuredText

.. _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.
These methods are usually composed out of several (but not always all)
components:
* The colour to search for. This is an RGB color.
* An area to search in, defined by *x1*, *y1*, *x2*, *y2*.
If any of coordinates are outside the clients bounds; two things can
happen depending on your settings:
- Simba throws an Exception.
- Simba will resize the bounds to fit the client without notifying
you.
* 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.
.. _scriptref-similarcolors:
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*.
.. _scriptref-getcolor:
GetColor
~~~~~~~~
.. code-block:: pascal
function GetColor(x, y: Integer): Integer;
GetColor returns the color on the coordinate *(x, y)*.
Example printing the colour on coordinate (25, 25).
.. code-block:: pascal
program printcolour;
begin
Writeln('Colour is ' + IntToStr(GetColor(25, 25)))
end.
.. _scriptref-getcolors:
GetColors
~~~~~~~~~
.. code-block:: pascal
function GetColors(const Coords : TPointArray) : TIntegerArray;
GetColors returns an array of the colours at the given *Coords*.
.. _scriptref-countcolor:
CountColor
~~~~~~~~~~
.. code-block:: pascal
function CountColor(Color, xs, ys, xe, ye: Integer): Integer;
Returns how many times *Color* occurs in the area defined by (*xs*, *ys*),
(*xe*, *ye*)
.. _scriptref-countcolortolerance:
CountColorTolerance
~~~~~~~~~~~~~~~~~~~
.. code-block:: pascal
function CountColorTolerance(Color, xs, ys, xe, ye, Tolerance: Integer): Integer;
Returns how many times *Color* occurs (within *Tolerance*)
in the area defined by (*xs*, *ys*), (*xe*, *ye*)
.. _scriptref-findcolor:
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.
.. _scriptref-findcolortolerance:
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.
.. _scriptref-findcolors:
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.
.. _scriptref-findcolorstolerance:
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.
.. _scriptref-findcolorspiral:
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*.
.. _scriptref-findcolorspiraltolerance:
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*.
.. _scriptref-findcolorsspiraltolerance:
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-findcoloredarea:
.. _scriptref-findcoloredareatolerance:
Find areas of colours
~~~~~~~~~~~~~~~~~~~~~
.. code-block:: pascal
function FindColoredArea(var x, y: Integer; color, xs, ys, xe, ye,
MinArea: Integer): Boolean;
FindColoredArea finds an area that consists out of *Color* and has a minimal
size of *MinArea*. If you want minimal area of 5x5 pixels (25), then set MinArea
to 25.
.. code-block:: pascal
function FindColoredAreaTolerance(var x, y : Integer; color, xs, ys, xe,
ye, MinArea, Tolerance : Integer): Boolean;
FindColoredArea finds an area that consists out of Colours that match *Color* with
the given *Tolerance* and has a minimal size of *MinArea*.
If you want minimal area of 5x5 pixels (25), then set MinArea to 25.
.. _scriptref-CTS:
Colour tolerance
----------------
Simba contains several algorithms for determining if two colours are equal
given a tolerance. There are three algorithms, from fastest to slowest:
* CTS 0: Quick and dirty comparison. Matches if the differences between the
three RGB values are <= Tolerance
* CTS 1: RGB comparison that uses the Pythagorean distance in the RGB cube
to define tolerance. Matches if the distance <= Tolerance.
* CTS 2: HSL comparison. It has two modifiers that modify the
result tolerance, Hue and Saturation. The lower the modifier, the higher
tolerance required for a match. They can be set seperately and therefore
used to distinguish very specific colours. Some differ a lot in saturation, but
very little in hue. Luminance is assigned a somewhat static function, and
has no modifier.
..
TODO: CIE-Lab
.. _scriptref-gettolerancespeed:
.. _scriptref-setcolortolerancespeed:
Get and Set Colour Tolerance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: pascal
procedure SetColorToleranceSpeed(cts: integer);
Set the current colour tolerance speed. Valid values are: 0, 1 and 2.
Somewhat improperly named compared to the other CTS functions.
.. code-block:: pascal
SetColorToleranceSpeed(2);
And the proper way to get the current tolerance is to use the following
function, which returns the current colour tolerance speed:
.. code-block:: pascal
function GetToleranceSpeed: Integer;
Example printing the Color Tolerance
.. code-block:: pascal
Writeln(Format('Tolerance Speed = %d', [GetToleranceSpeed]))
.. _scriptref-settolerancespeed2modifiers:
.. _scriptref-gettolerancespeed2modifiers:
Get And Set Colour Modifiers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: pascal
procedure SetToleranceSpeed2Modifiers(nHue, nSat: Extended);
Set colour speed 2 modifiers.
.. code-block:: pascal
// 42.0 is a very high value, but this doesn't matter as this code is
// only meant to illustrate how to use this function
SetToleranceSpeed2Modifiers(42.0, 0.4)
The following function
.. code-block:: pascal
procedure GetToleranceSpeed2Modifiers(var hMod, sMod: Extended);
returns colour speed 2 modifiers.
Example getting the modifiers:
.. code-block:: pascal
procedure WriteModifiers;
var
H, S: Extended;
begin
GetToleranceSpeed2Modifiers(H, S);
Writeln(format('H = %f; S = %f', [H, S]));
end;