Filter

Introduction

The filter function allows you to show only the data you are intereting, it is useful when you want to

  • Trace one or several specific aircraft(s), by track number, callsign or Mode-S address;
  • Find data with special charactoristic, e.g. SSR is 7500;
  • Analyze data from a specific sensor;
  • Etc.

When a filter is applied

  • System will check all loaded data, and shows only data which can match the filter;
  • System will check new incoming data (read from file, or received from network), and shows only data which can match the filter;
  • Unmatched data will not be shown, but still kept in memory.

There are two types of filter, Simple Filter and Lua Filter.

Simple Filter

A simple filter, as explained by its name, is simple and easy to use. It's useful when you just need to filter data with one condition, e.g. callsign is KAR2681.

In mainwindow, there is a filter toolbar, by default it is in simple filter mode. You can simply type a filter command, and press "Enter" key or click on "Apply" button, the filter will be applied.

filter_simple_applied.png
Simple Filter Applied

When click on "Clear" button, the filter will be cancelled.

filter_simple_cancelled.png
Simple Filter Cancelled
Warning
If a large number of messages have been loaded, system need to reload all data when you cancel a filter, this process could take a while and cause UI no response for a short time. It will recover when all data is reloaded.

Syntex

The syntex of simple filter is:

KEYWORD = VALUE

The rules for simple filter are:

  • Keyword must be known by system;
  • Only one keyword can be used;
  • Both keyword and value are case insensitive;
  • All spaces will be ignored.

A tapical simple filter looks like:

callsign = KAL937

It means, show data with callsign field and its callsign is "KAL937".

To make it's easier to write, this filter is equivalent to:

cs=kal937

Here "cs" is the abbreviation of "callsign", and "kal" is the same with "KAL" or "Kal".

Below is a list of keywords supported by simple filter.

Keyword Abbreviation Description Example Note
callsign cs, acid, targetid Callsign callsign=KAL937
squawk ssr, mode3a, mode-3a Squawk squawk=3562 Range 0000-7777
tracknum trackid, track_num, track_id Track number tracknum=65
level modec, mode-c Flight level level=310 Unit is 100 feet
sacsic id Sensor SAC and SIC sacsic=126031 Means SAC=126, SIC=31
icaoaddr addr 24-bit ICAO Address icaoaddr=7F1E00

Lua Filter

Lua filter, is based on Lua script language. You can use Lua script to write a complex filter, and match specific data you are interesting.

For example, with Lua filter, you can match data which is

from aircrafts belong to Lufthansa (DLH), registered in Germany, with flight level between F290 to F320, and are in emergency status.

To use lua filter, first you need to click on the "Lua" button in filter toolbar, to switch the filter from simple filter mode to Lua filter mode, and a new button "Edit" will appear.

filter_lua_mode.png
Lua Filter Enabled

Then, after clicking "Edit" button, a "Lua Script Filter" window will appear.

filter_lua_window.png
Lua Filter Window

In this window, you can type any valid Lua script. A syntex highlight mechanism similary with any code editor has been integrated into this window, so you can detect protential errors in script when you type them.

Please be aware of the green color comments in this window, those are preset data which can be used to test your script. When you finsh your filter script, you can click on "Test" button, and system will try to use you script to match data in comments, and show matching result in the "Result" text field. The result can be:

  • True, your script match test data and return true.
  • False, your script doesn't match test data and return false.
  • Error, there is error when interpreting your script, an error message will be shown in "Result" text field.
filter_lua_test_true.png
Lua Filter Test Success
filter_lua_test_error.png
Lua Script with Error

When your script is ready to use, you can click "Apply" button to apply the filter, or click "Close" button to close this window without applying the filter.

When click on "Clear" button in filter toolbar, the filter will be cancelled.

Syntex

The syntex of Lua script language can be found at Lua website. The Lua version used by Lua filter is 5.3.

Everytime, when system need to check if one data record can match the filter or not, it will use the data to construct a Lua table name record. The following fields are included in the record table:

Field Description Example
category ASTERIX category number 34
sac Sensor SAC 12
sic Sensor SIC 252
msgtype Message type, can be north, sector, plot, track "track"
tracknum Track number 798
squawk SSR code 3065
callsign Callsign "SAI1401"
icaoaddr ICAO 24-bit address 18932
flightlevel Mode-C level in feet 31000

If any field is not appliable, it will be set to nil.

The filter script should check if the data contained in record can match its purpose or not. If match, the script must return true, and the record will be kept in result; if not match, the script must return false, and the record will be ignored.

Example:

if (string.sub(record.callsign, 1, 3) == "DLH" and record.squawk == 7500)
then
return true;
else
return false
end

This script means, if the callsign in record starts with "DLH" and squawk is 7500 (hijack), the data will match the filter and be kept in result, all others will be ignored.