Color Finding

Finding colors on the screen is quite simple. Simba offers methods like FindColor to locate colors on the screen.

These methods are usually composed out of several (but not always all) components:

  • The color 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 color matching. With a maximum tolerance all colors 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 colors 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 Deformable Template Models (DTM) section.

Note

Although the documentation uses the English spelling of color; the code for compatibility sake uses color, without the u.

Color Finding Methods

A list of all color finding methods in Simba.

SimilarColors

function SimilarColors(C1, C2, Tolerance: Integer): Boolean;

SimilarColors returns true if the two passed colors are similar given the passed Tolerance.

GetColor

function GetColor(x, y: Integer): Integer;

GetColor returns the color on the coordinate (x, y).

Example printing the color on coordinate (25, 25).

program printcolor;

begin
  Writeln('Color is ' + IntToStr(GetColor(25, 25)))
end.

GetColors

function GetColors(const Coords : TPointArray) : TIntegerArray;

GetColors returns an array of the colors at the given Coords.

CountColor

function CountColor(Color, xs, ys, xe, ye: Integer): Integer;

Returns how many times Color occurs in the area defined by (xs, ys), (xe, ye)

CountColorTolerance

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)

FindColor

function FindColor(var x, y: Integer; col, x1, y1, x2, y2: Integer): Boolean;

FindColor returns true if the exact color 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

function FindColorTolerance(var x, y: Integer; col, x1, y1, x2, y2, tol: Integer): Boolean;

FindColorTolerance returns true if a color within the given tolerance range tol of the given color 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 color is within the tolerance range is determined by the Color tolerance mode. It searches from the top left to the bottom right and will stop after matching a point.

FindColors

function FindColors(var pts: TPointArray; col, x1, y1, x2, y2): Boolean;

FindColors returns a list of all points that match the color col in an area defined by x1, y1, x2, y2. It returns true if one or more points have been found.

FindColorsTolerance

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 color 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 Color tolerance mode. It searches from the top left to the bottom right and will find all matching points in the area.

FindColorSpiral

function FindColorSpiral(var x, y: Integer; color, xs,ys,xe,ye:Integer): Boolean;

Same as FindColor, but starts searching from x, y.

FindColorSpiralTolerance

function FindColorSpiralTolerance(var x, y: Integer; color, xs,ys,xe,ye,tolerance:Integer): Boolean

Same as FindColorTolerance, but starts searching from x, y.

FindColorsSpiralTolerance

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.

Find areas of colors

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.

function FindColoredAreaTolerance(var x, y : Integer; color, xs, ys, xe, ye, MinArea, Tolerance : Integer): Boolean;

FindColoredArea finds an area that consists out of Colors 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.

Color tolerance

Simba contains several algorithms for determining if two colors 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 colors. Some differ a lot in saturation, but very little in hue. Luminance is assigned a somewhat static function, and has no modifier.
  • CTS 3: Comparison using CIE L*a*b color space, uses Pythagorean distance.

Get and Set Color Tolerance

procedure SetColorToleranceSpeed(cts: integer);

Set the current color tolerance speed. Valid values are: 0, 1 and 2. Somewhat improperly named compared to the other CTS functions.

SetColorToleranceSpeed(2);

And the proper way to get the current tolerance is to use the following function, which returns the current color tolerance speed:

function GetToleranceSpeed: Integer;

Example printing the Color Tolerance

Writeln(Format('Tolerance Speed = %d', [GetToleranceSpeed]))

Get And Set Color Modifiers

procedure SetToleranceSpeed2Modifiers(nHue, nSat: Extended);

Set color speed 2 modifiers.

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

procedure GetToleranceSpeed2Modifiers(var hMod, sMod: Extended);

returns color speed 2 modifiers.

Example getting the modifiers:

procedure WriteModifiers;
var
    H, S: Extended;
begin
    GetToleranceSpeed2Modifiers(H, S);
    Writeln(format('H = %f; S = %f', [H, S]));
end;

FindColoredArea

function FindColoredArea(var x, y: Integer; Color, xs, ys, xe, ye: Integer; MinArea: Integer): Boolean

FindColoredAreaTolerance

function FindColoredAreaTolerance(var x, y: Integer; Color, xs, ys, xe, ye, MinArea, tol: Integer): Boolean

GetColorsWrap

procedure GetColorsWrap(Coords: TPointArray; var Colors: TIntegerArray)

GetToleranceSpeed2Modifiers

procedure GetToleranceSpeed2Modifiers(var hMod, sMod: Extended)

GetToleranceSpeed3Modifier

function GetToleranceSpeed3Modifier: Extended

GetToleranceSpeed

function GetToleranceSpeed: Integer

SetColorToleranceSpeed

procedure SetColorToleranceSpeed(cts: Integer)

SetToleranceSpeed2Modifiers

procedure SetToleranceSpeed2Modifiers(nHue, nSat: Extended)

SetToleranceSpeed3Modifier

procedure SetToleranceSpeed3Modifier(Modifier: Extended)