341 lines
8.8 KiB
ReStructuredText
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;
|
|
|