Skip to content

Commit 1652059

Browse files
committed
Improve matching script documentation
Related to swift-project/pilotclient#176
1 parent bdd1f2f commit 1652059

File tree

4 files changed

+102
-38
lines changed

4 files changed

+102
-38
lines changed

docs/img/matching_log.jpg

106 KB
Loading

docs/img/matching_stages.jpg

74.3 KB
Loading

docs/troubleshooting/model_matching/matching_script.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ Matching script allow to write your own matching logic beyond the scope of the s
2020
2. Then we use these unified data and try to find the best match in your model set.
2121
This is what we call **model matching**.
2222

23+
![](./../../img/matching_stages.jpg){: style="width:60%"}
24+
2325
swift exposes some of its APIs to matching script:
2426

2527
- A wrapper for the swift database web services

docs/troubleshooting/model_matching/matching_script_technical.md

Lines changed: 100 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -3,65 +3,127 @@
33
SPDX-License-Identifier: GFDL-1.3-only
44
-->
55

6-
This document covers some technical details for matching script programmers
6+
This document covers some technical details for matching script programmers.
77

8-
## Matching script interacting with swift
8+
The matching script consists of a JavaScript file containing an anonymous function:
99

10-
There are classes, which may be used as objects in Matching script (i.e. JavaScript).
11-
Those classes start with a `MS` prefix (matching script).
12-
Those classes can be found in `BlackMisc::Simulation` and `BlackCore`.
10+
```js
11+
(function() { /* your code goes here */ })
12+
```
13+
14+
Inside the function, the following objects are available:
1315

14-
- MSInOutValues
15-
- MSModelSet
16-
- MSWebServices
16+
- ``inObject``: Object with all the data from the network and the swift-provided reverse lookup stage
17+
- ``outObject``: The object that should contain the script results.
18+
In the beginning, this object contains the same content as ``matchedObject`` and can be changed by your script.
19+
- ``matchedObject``: Object with the model (and additional information) deduced so far in previous stages. In the reverse lookup script, this is identical to ``inObject`` as no further stages were already executed.
20+
- ``modelSet``: User's current model set. Not available in reverse lookup
21+
- ``webServices``: Wrapper to access the swift web services
22+
23+
As already stated, your script must return the ``outObject``:
24+
25+
```js
26+
(function() {
27+
/* Do some modifications of outObject here */
28+
return outObject;
29+
})
30+
```
1731

1832
## Using properties
1933

34+
The provided objects contain properties that you can use.
35+
These properties are listed in the [``matchingscript.h``](https://github.com/swift-project/pilotclient/blob/main/src/blackmisc/simulation/matchingscript.h) as ``Q_PROPERTY``.
2036

21-
MS class properties as below
2237

23-
```cpp
24-
//! MSNetworkValues properties @{
25-
Q_PROPERTY(QString callsign READ getCallsign WRITE setCallsign NOTIFY callsignChanged)
26-
Q_PROPERTY(QString callsignAsSet READ getCallsignAsSet)
27-
Q_PROPERTY(QString flightNumber READ getFlightNumber)
28-
Q_PROPERTY(int dbAircraftIcaoId READ getDbAircraftIcaoId WRITE setDbAircraftIcaoId NOTIFY
29-
```
38+
| Javascript Object | Corresponding C++ class |
39+
|---------------------|-------------------------|
40+
| ``inObject`` | ``MSInOutValues`` |
41+
| ``outObject`` | ``MSInOutValues`` |
42+
| ``matchedObject`` | ``MSInOutValues`` |
43+
| ``modelSet`` | ``MSModelSet`` |
3044

31-
can be used in matching script as follows
45+
The second parameter of ``Q_PROPERTY`` is the name of the property in JavaScript.
46+
They can be used in the scripts as like as follows:
3247

3348
```js
34-
outObject.aircraftIcao = "C172";
35-
outObject.modified = true; // tell we changed something
49+
if (outObject.airlineIcao == "ABC") {
50+
outObject.aircraftIcao = "A320";
51+
}
3652
```
3753

38-
Some properties are read only, and you can see the type from property definition.
54+
Some properties are read only, and you can see the type from the ``Q_PROPERTY`` definition.
3955

4056
## Using functions
57+
Some of the provided JavaScript objects contain functions that can be invoked by your script.
58+
These functions are listed in the [``matchingscript.h``](https://github.com/swift-project/pilotclient/blob/main/src/blackmisc/simulation/matchingscript.h) as ``Q_INVOKABLE``.
59+
They can be invoked like this:
4160

42-
Functions of MS classes can be used if they are marked as `Q_INVOKABLE` (only those you can invoke from matching script).
43-
44-
```cpp
45-
//! Functions calling the web services @{
46-
Q_INVOKABLE int countAircraftIcaoCodesForDesignator(const QString &designator) const;
47-
Q_INVOKABLE int countAirlineIcaoCodesForDesignator(const QString &designator) const;
48-
//! @}
61+
```js
62+
var contains = modelSet.containsModelString("C172");
4963
```
5064

51-
or
65+
## Effect of the ``outObject`` properties on reverse lookup and matching
5266

53-
```cpp
54-
//! Model string of model with closest color distance
55-
Q_INVOKABLE QString findCombinedTypeWithClosestColorLivery(const QString &combinedType, const QString &rgbColor) const;
56-
```
67+
After executing the script, the following properties are used by swift to influence the reverse lookup or matching:
5768

58-
Those you can call those as functions in matching script
69+
- ``logMessage``: Contains a string message that is logged individually for each callsign/aircraft the matching script was invoked for.
70+
See also [this section](#log-messages-from-the-matching-script).
71+
- ``modified:`` Boolean flag that **must** be set to ``true`` if any of the other properties should be used.
72+
If set to ``false``, the data from this script run are discarded.
73+
- ``rerun``: When set to ``true``, rerun the stage that runs before this script but without executing the script again.
74+
Example: When this is set to ``true`` in the reverse lookup script, the swift-provided reverse lookup stage is executed again (it was already executed before the script was invoked).
75+
- ``dbModelId``: New model ID. Set this to -1 if you do not want to set the model ID explicitly. This invalidates the model ID as ``outObject`` is prepoulated with data from ``matchedModel``.
76+
When this property contains a different value than -1, the model is fetched from the webservices.
77+
If the fetched model is valid, all other properties are discarded and the specified model is used.
78+
- ``modelString``: String with a new model string. Set this to empty if you do not want to set it explicitly.
79+
This invalidates the model string as ``outObject`` is prepoulated with data from ``matchedModel``.
80+
The model string is first searched in the webservices and if not found there in the user's model set.
81+
If the model string is valid, all other properties are discarded and the specified model is used.
82+
- ``aircraftIcao``: Set the aircraft ICAO as a string. The webservices are used to find more information about the aircraft ICAO.
83+
If the webservice search was unsuccessful, the aircraft ICAO as a string is used anyway.
84+
- ``liveryId``: ID of the livery to use.
85+
The corresponding database entry is always fetched from the webservice.
86+
Invalid livery IDs might lead to some default livery.
87+
All airline ICAO options (below) are skipped if this property is set.
88+
- ``airlineIcaoId``: ID of the airline ICAO to use.
89+
Further data about the ID is gathered from the webservices.
90+
If the ID is not found via the webservices, some default/empty airline will be used.
91+
As a livery, the "standard" livery for the specified airline is used.
92+
This option is discarded when using ``liveryId``.
93+
This property takes precedence over ``airlineIcao``.
94+
The ``airlineIcao`` property is discarded in this case.
95+
- ``airlineIcao``: Airline ICAO string to use.
96+
Further data about the airline ICAO string is gathered from the webservices.
97+
If the ICAO is not found via the webservices, some default/empty airline will be used.
98+
As a livery, the "standard" livery for the specified airline is used.
99+
This option does not work when using ``liveryId`` or ``airlineIcaoId``.
59100

60-
```js
61-
var mscl = modelSet.findCombinedTypeWithClosestColorLivery(combinedType, white);
62-
```
101+
## Log messages from the matching script
102+
103+
The ``outObject`` contains a ``logMessage`` property to display a log message for each invokation.
104+
105+
!!! warning
106+
107+
These messages are **not** displayed in the normal swift application log!
108+
109+
### swiftgui
110+
In swiftgui, this logging only works if the corresponding logging (reverse lookup or matching) **and** "detailed" logging is enabled on the ``Models->Matching Log`` page.
111+
The log is shown on the same page after entering a callsign.
112+
113+
![](./../../img/matching_log.jpg){: style="width:50%"}
114+
115+
### swiftdata
116+
117+
Within the model matcher of swiftdata, the script log messages are always displayed.
118+
119+
## Error logs
120+
If the script for some reason fails to execute (syntax errors, ...), a log file with the cause of the error is created at the following locations:
121+
122+
- for the reverse lookup script: ``<SWIFT_LOG_DIR>/logMatchingScriptReverseLookup.log``
123+
- for the matching script: ``<SWIFT_LOG_DIR>/logMatchingScriptMatchingStage.log``
63124

64-
## Examples
125+
To find your log directory, see [this page](./../swift_log_files.md).
65126

127+
## Example scripts
66128

67-
Check out the `matchingscript` directory for examples, like `\swift-0.9.2-64bit\share\matchingscript`.
129+
Check out the `matchingscript` directory for examples: `<SWIFT_INSTALL_DIR>\share\matchingscript`.

0 commit comments

Comments
 (0)