Write a Lua Script for an ESP Engine

Some ESP engines can run a Lua script to determine whether to include a record in the task's output track. Writing a Lua script allows you to specify more complex rules than you can specify using configuration parameters. For example, a Lua script might specify where in an image recognized text must appear. If text appears within this region, then depending on the engine type, the engine includes or excludes this record from its output track.

The Lua script must define a function with the name pred. This function takes one or more parameters (depending on the engine type and the number of input tracks you configure) and must return true or false. Each parameter is a record object: this is a representation of the record being processed and has the same structure as the record XML.

The pred function is called once for each record (or group of records) that the engine has to consider. The engine's response to the function depends on the engine type.

ESP Engine Number of record parameters Engine response if the function returns true
And / AndThen 2 or more The group of records is included in the engine output track.
AndAny / AndThenAny 2 The record in the Input0 track is included in the output. (Records from the other tracks are never included in the output).
AndNot / AndNotThen 2 The record in the Input0 track is discarded. (Records from the other tracks are never included in the output).
Combine 2 The record is combined with the record from the Input0 track.
Deduplicate 2 The second record is discarded.
Filter 1 The record is included in the engine output track.

When the pred function takes multiple parameters, each individual record may feature in different groups, so might be processed by the pred function any number of times. For example, for the AndNot or AndNotThen engine, a record in the first track might be passed to the function several times, being paired with different records from the other tracks. The record will only appear in the output track if pred returns false every time.

The ESP engine cannot modify the record objects passed to the pred function. Any effects of the function other than the return value are ignored.

To run a Lua script from an ESP engine, add the LuaScript parameter to the task configuration section and set it to the path of the script. For example, LuaScript=./scripts/breakingnews.lua.

Example Script

The following is an example script for the Filter ESP engine. The script filters records based on where text, read by an OCR task, appears in the image. The function returns true if text appears in the region between x=100 and x=300, and the record is included in the output track. If the text region is outside these coordinates, the record is discarded.

function pred(rec)
   return rec.OCRResult.region.left > 100 and rec.OCRResult.region.right < 300
end