# OverheadFinder

Prayer/Protection Overhead Detection System.

A comprehensive system for detecting and locating prayer and protection overhead icons
in game. This module uses template matching to identify various
overhead prayer effects on players and NPCs.

The overhead icons are read straight from the game cache.


- - -

## EOverhead
```pascal
EOverhead = (
  MAGIC, RANGED, MELEE, RETRIBUTION, REDEMPTION, SMITE,
  MAGIC_AND_RANGED, MAGIC_AND_MELEE, RANGED_AND_MELEE, ALL,
  DAMPEN_MELEE, DAMPEN_RANGED, DAMPEN_MAGIC
);
```
Enumeration of all detectable overhead prayer and protection types in game.
Includes individual protections, combinations, and special prayer effects.

`DAMPEN_RANGED` and `DAMPEN_MAGIC` are last so the values of the others stay the same for scripts
that saved them.


- - -

## TOverhead
```pascal
TOverhead = record
  Position: TPoint;
  Overhead: EOverhead;
end;
```
Record containing information about a detected overhead prayer icon.
Stores both the screen position and the type of overhead detected.


- - -

## TOverheadArray
```pascal
TOverheadArray = array of TOverhead;
```
Dynamic array of TOverhead records for storing multiple detected overhead icons.


- - -

## TOverheadFinder
```pascal
TOverheadFinder = record
  Images: array[EOverhead] of TImage;
  Similarity: Single;
end;
```
Main overhead detection system that manages template images and performs
overhead icon recognition using template matching algorithms.


- - -

## TOverheadFinder.Setup
```pascal
procedure TOverheadFinder.Setup();
```

Internal procedure called when library is loaded.
Sets the default similarity threshold.

Example:
```pascal
OverheadFinder.Setup();
WriteLn('OverheadFinder initialized successfully');
```


- - -

## TOverheadFinder.LoadImages
```pascal
procedure TOverheadFinder.LoadImages();
```
Internal procedure that reads the overhead icons out of the game cache and fills `Images`.

All overheads are frames of the same 25x25 sprite. Only the middle 14x14 of each frame is kept,
which leaves out the transparent corners so the icons match whatever the game draws behind them.
It runs once, the first time an overhead image is needed.


- - -

## TOverheadFinder.GetImage
```pascal
function TOverheadFinder.GetImage(overhead: EOverhead): TImage;
```
Internal function.
Retrieves the template image for a specific overhead type.
Images are read from the game cache the first time one is needed and kept in memory after that.

Parameters:
- overhead: The overhead type to get the template image for

Returns TImage object containing the template, or raises exception if image cannot be loaded.


- - -

## TOverheadFinder.Find
```pascal
function TOverheadFinder.Find(overheads: set of EOverhead; maxToFind: Integer = 5): TOverheadArray;
```
Searches the main screen for specified overhead prayer/protection icons using template matching.
Detects overhead icons by first finding their characteristic colors: the tan background of the
protection prayers, the purple background of the dampen ones, the red of retribution and the teal
of smite and redemption. The regions around those colors are then searched with template matching.

Parameters:
- overheads: Set of overhead types to search for
- maxToFind: Maximum number of overhead icons to detect (default: 5)

Returns TOverheadArray containing detected overhead positions and types.

Example:
```pascal
var
  foundOverheads: TOverheadArray;
  i: Integer;
begin
  OverheadFinder.Setup();
  foundOverheads := OverheadFinder.Find([MAGIC, RANGED, MELEE], 10);

  if Length(foundOverheads) > 0 then
  begin
    WriteLn('Found ' + ToStr(Length(foundOverheads)) + ' overhead icons:');
    for i := 0 to High(foundOverheads) do
      WriteLn('- ' + ToStr(foundOverheads[i].Overhead) + ' at ' + ToStr(foundOverheads[i].Position));
  end else
    WriteLn('No overhead icons detected');
end;
```

{figure} ../../images/overhead_detection_example.png


- - -

## OverheadFinder variable
Global {ref}`TOverheadFinder` variable. Use this instance for all overhead
detection operations in your scripts.