# 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.

```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)
```