-
Notifications
You must be signed in to change notification settings - Fork 0
/
MethodSynopsis.html
401 lines (388 loc) · 22.2 KB
/
MethodSynopsis.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
<!DOCTYPE html>
<html lang="en">
<h1>ICAO ATS and OLDI Parser Method Synopsis</h1>
<p>This section contains descriptions for a number of methods that can be used to retrieve data for a
parsed message. The parser only has to be instantiated once. The input string and flight plan output class
must be provided as new instances of:
</p>
<ul>
<li>An input string representing a message to parse;</li>
<li>An instance of the FlightPlanRecord class that will contain all the fields and any associated errors
extracted from a parsed message;</li>
</ul>
<p></p>
<p></p>
<p></p>
<p></p>
<p></p>
<h2>Parsing a Message</h2>
<p>Two methods are provided to parse a message, one method returns an instance of a flight plan record,
the other takes an instance of a flight plan record as an input parameter; both methods require a string
representing the message to parse.
</p>
<p>A string representing a message to parse must be instantiated first, the following provides an
example ATS FPL messages that can be used to evaluate the parser:
</p>
<table>
<colgroup>
<col span="1" style="background-color:lightgrey">
</colgroup>
<tr><td>
<pre><code>icao_message: str = "(FPL-TEST01
-IS-B737/M
-S/C-LOWW0800
-N0450f350 PNT B9 LNZ1A
-EGLL0200
-RMK/THIS IS A REMARK)"
</code></pre>
</td></tr>
</table>
<h3>Message Parser - Method 1</h3>
<p>The following parser method returns an instance of a flight plan record:</p>
<p>Method Parameters:
</p>
<ul>
<li>String: A string representing the message to parse;</li>
<li>Return: An instance of FlightPlanRecord containing the fields extracted from the parsed message;</li>
</ul>
<table>
<colgroup>
<col span="1" style="background-color:lightgrey">
</colgroup>
<tr><td>
<pre><code># Instantiate the parser...</code></pre>
<pre><code>icao_message_parser: IcaoAtsMessageParser = IcaoAtsMessageParser()</code></pre>
</td></tr>
<tr><td>
<pre><code># Parse the message...</code></pre>
<pre><code>flight_plan_record: FlightPlanRecord = icao_message_parser.parse_message_p1(icao_message)</code></pre>
</td></tr>
</table>
<h3>Message Parser - Method 2</h3>
<p>The following parser method takes both an instance of a flight plan record and a string
representing a message to parse:
</p>
<p>Method Parameters:
</p>
<ul>
<li>String: A string representing the message to parse;</li>
<li>FlightPlanRecord: An instance of FlightPlanRecord that will contain the fields extracted from the
parsed message;</li>
<li>Return: True if errors were detected, False if no errors were detected;</li>
</ul>
<table>
<colgroup>
<col span="1" style="background-color:lightgrey">
</colgroup>
<tr><td>
<pre><code># Instantiate a FlightPlanRecord, the output is written into this class instance.</code></pre>
<pre><code>flight_plan_record: FlightPlanRecord = FlightPlanRecord() </code></pre>
</td></tr>
<tr><td>
<pre><code># Instantiate the parser...</code></pre>
<pre><code>icao_message_parser = IcaoAtsMessageParser() </code></pre>
</td></tr>
<tr><td>
<pre><code># Parse the message...</code></pre>
<pre><code>result = icao_message_parser.parse_message_p2(flight_plan_record, icao_message) </code></pre>
</td></tr>
</table>
<h2>Retrieving Data for a Parsed Message</h2>
<p>This section describes methods to recover data from a parsed message. The first section describes
how to ascertain if errors were detected and how to retrieve the errors.
The second part describes how to retrieve message field data.
</p>
<h3>Error Detection</h3>
<p>There exist two sources of errors:
</p>
<ul>
<li>Errors generated by parsing any ICAO field other than ICAO field 15;</li>
<li>Errors generated as a result of performing route extraction on ICAO Field 15;</li>
</ul>
<p>The errors for case 1 above are stored directly in a FlightPlanRecord instance as a list of one or more
ErrorRecord instances. The field 15 errors are stored in an ExtractedRouteSequence instance which
is stored in the FlightPlanRecord instance; hence for the field 15 route extraction errors,
the errors have to be retrieved through the ExtractedRouteSequence class.
</p>
<h4>Errors for all Fields except Field 15</h4>
<p>The following describes how to recover errors related to any field other than field 15.
</p>
<table>
<colgroup>
<col span="1" style="background-color:lightgrey">
</colgroup>
<tr><td>
<pre><code># First, parse the message...</code></pre>
<pre><code>result = icao_message_parser.parse_message_p2(flight_plan_record, icao_message) </code></pre>
</td></tr>
<tr><td>
<pre><code># If errors were detected, result will be False; to get the error records do the following...</code></pre>
<pre><code>if not result:</code></pre>
<pre><code> # For fields other than field 15 call the following method, this returns a list of ErrorRecord's...</code></pre>
<pre><code> basic_field_errors: [ErrorRecord] = flight_plan_record.get_erroneous_fields() </code></pre>
</td></tr>
</table>
<p>The ErrorRecord class contains the following methods to recover the field text, errors and zero based
indices of a fields position in the original message:
</p>
<ul>
<li>ErrorRecord.get_field_text(): Recovers the text representing the field in error;</li>
<li>ErrorRecord.get_start_index(): The zero based index to the first character of the field in the original message;</li>
<li>ErrorRecord.get_end_index(): The zero based index to the last character + 1 of the field in the original message;</li>
<li>ErrorRecord.get_error_message(): The error message reported by the parser for this field;</li>
</ul>
<h4>Errors for Field 15</h4>
<p>The following describes how to recover route extraction errors generated by parsing field 15.
</p>
<table>
<colgroup>
<col span="1" style="background-color:lightgrey">
</colgroup>
<tr><td>
<pre><code># For field 15, get the Extracted Route Sequence and get the errors, returns a list of Tokens...</code></pre>
<pre><code>if flight_plan_record.get_extracted_route_sequence().get_number_of_errors() > 0:</code></pre>
<pre><code> field_15_errors: [ExtractedRouteRecord] = flight_plan_record.get_f15_errors() </code></pre>
</td></tr>
</table>
<p>The ExtractedRouteRecord class contains the following methods to recover the field text, errors and zero based
indices of a fields position in the original message:
</p>
<ul>
<li>ExtractedRouteRecord.get_name(): Recovers the text representing the field in error within field 15;</li>
<li>ExtractedRouteRecord.get_start_index(): The zero based index to the first character of the field in the original message;</li>
<li>ExtractedRouteRecord.get_end_index(): The zero based index to the last character + 1 of the field in the original message;</li>
<li>ExtractedRouteRecord.get_error_text(): The error message reported by the parser for this field;</li>
</ul>
<p>The ExtractedRouteRecord class contains numerous other methods to retrieve further information about an
extracted route item. These methods are covered in the section dealing with data recovery from the extracted
route record in general. The above example deals with retrieving error information. The start and end
indices can be used to highlight an erroneous field in a GUI.
</p>
<h2>Data Retrieval for all Fields except Field 15</h2>
<p>This section describes how to retrieve data for individual fields. All field access and their associated
subfields requires the use of the enumeration values from the Configuration.EnumerationConstants.FieldIdentifiers
and Configuration.EnumerationConstants.SubFieldIdentifiers enumeration classes; a number of these
enumeration values will be used in the following examples.
</p>
<p>The following example shows how to retrieve ICAO Field 13; (e.g. LOWW0800). for other fields, use the
relevant field identifier from those available in the FieldIdentifiers enumeration class.
</p>
<p>If the field is unavailable, 'None' is returned.
</p>
<table>
<colgroup>
<col span="1" style="background-color:lightgrey">
</colgroup>
<tr><td>
<pre><code># Get the complete ICAO Field 13</code></pre>
<pre><code>f13: str = flight_plan_record.get_icao_field(FieldIdentifiers.F13).get_field_text()</code></pre>
</td></tr>
</table>
<p>The following example shows how to retrieve a subfield from ICAO Field 16, subfield 'b', (e.g. if F16
contained 'EGLL0200 EGMM') then '0200' would be returned. For other field/subfields, use the
relevant field and subfield identifiers from those available in the FieldIdentifiers and
SubFieldIdentifiers enumeration classes.
</p>
<p>If the subfield is unavailable, 'None' is returned.
</p>
<table>
<colgroup>
<col span="1" style="background-color:lightgrey">
</colgroup>
<tr><td>
<pre><code># Get the ICAO field 16 EET (Field 16 'b')</code></pre>
<pre><code>f16b: str = flight_plan_record.get_icao_subfield(</code></pre>
<pre><code> FieldIdentifiers.F16, SubFieldIdentifiers.F16b).get_field_text() </code></pre>
</td></tr>
</table>
<h3>Flight Plan Record Get Methods</h3>
<p>There are numerous 'getter' methods included in the FlightPlanRecord class; these are described below:
</p>
<ul>
<li><b>as_xml()</b>: Returns an XML representation of the parsed message; returns a string as a valid
XML document;</li>
<li><b>get_all_icao_subfields(FieldIdentifiers, SubFieldIdentifiers)</b>: A number of Field 18 keyword/data items
can occur more than once; this method is provided to retrieve 'n' subfields from an ICAO field.
The method takes the field and subfield identifiers as parameters and returns a list of SubFieldRecord
records. If the field or subfield(s) do not exist, None is returned.
</li>
<li><b>get_derived_flight_rules()</b>: Returns the flight rules derived by parsing field 15, (this is NOT
field 8a). When performing route extraction, the parser determines the flight rules from the route. This
is used in consistency checking field 15 with field 8a (which should be the same). Returns an
enumeration value from the FlightRules class, (refer to section describing access to the
ExtractedRouteRecord).
</li>
<li><b>get_erroneous_fields()</b>: Returns a list of ErrorRecord instances that store all erroneous fields
found during parsing.
</li>
<li><b>get_extracted_route()</b>: Returns an instance of the ExtractedRouteSequence class containing
the extracted route sequenced derived by the field 15 parser.
</li>
<li><b>get_f15_errors()</b>: Returns a list of ExtractedRouteRecord class instances for erroneous field
15 items.
</li>
<li><b>get_f22_flight_plan()</b>: Return an instance of FlightPlanRecord that contains all the fields
extracted and parsed by the field 22 parser.
</li>
<li><b>get_icao_field(FieldIdentifiers)</b>: Returns an instance of a FieldRecord class containing the
field specified by the FieldIdentifiers enumeration value, or None if the field does not
exist.
</li>
<li><b>get_icao_subfield(FieldIdentifiers, SubFieldIdentifiers)</b>: Returns an instance of a SubFieldRecord
class containing the subfield specified by the FieldIdentifiers and ubFieldIdentifiers enumeration
values, or None if the subfield does not exist.
</li>
<li><b>get_message_body()</b>: Returns the message body as submitted for parsing, the message body
excludes the message header; this starts at the open bracket for ICAO format messages.
</li>
<li><b>get_message_complete()</b>: Returns the complete message, that is the message header and body
as submitted for parsing.
</li>
<li><b>get_message_header()</b>: Returns the message header as submitted for parsing, the message header
excludes the message body; this starts at the beginning of a message up to the character preceding the
open bracket for ICAO format messages.
</li>
<li><b>get_message_title()</b>: Returns the message title as an enumeration value from the
MessageTitles class. If the title is unrecognised by the parser MessageTitles->UNKNOWN is returned.
</li>
<li><b>get_message_type()</b>: Returns the message type (ICAO ATS, OLDI, ADEXP or UNKNOWN) as an
enumeration value from the MessageTypes class.</li>
<li><b>get_receiver_adjacent_unit_name(self)</b>: Returns the name of the receiver adjacent unit name
extracted from Field 3b as an enumeration value from the AdjacentUnits class.
</li>
<li><b>get_sender_adjacent_unit_name(self)</b>: Returns the name of the sending adjacent unit name
extracted from Field 3b as an enumeration value from the AdjacentUnits class.
</li>
</ul>
<h3>Extracted Route Sequence Get Methods</h3>
<p>Field 15 is parsed and an extracted route sequence produced that is stored in the flight plan record.
The extracted route can be retrieved from the flight plan record with a call to
<b>FlightPlanRecord.get_extracted_route()</b>. This call returns an instance of
<b>ExtractedRouteSequence</b> that contains the extracted route as a list of <b>ExtractedRouteRecords</b>.
</p>
<p>Many of the methods available in the ExtractedRouteSequence class return one or mor ExtractedRouteRecord
instances. For details on the ExtractedRouteRecord refer to the section
<a href="#Extracted Route Record Get Methods">Extracted Route Record Get Methods.</a>
</p>
<p>The following methods are implemented in the <b>ExtractedRouteSequenceClass</b>, the first list relates to
methods applicable to the extracted route as a whole.
</p>
<ul>
<li><b>get_derived_flight_rules()</b>: Returns the flight rules derived by parsing field 15, (this is NOT
field 8a). When performing route extraction, the parser determines the flight rules from the route. This
is used in consistency checking field 15 with field 8a (which should be the same). Returns a string
as 'IFR', 'VFR' 'Y' or 'Z'.
</li>
</ul>
<p>The following methods relate to retrieving records that together represent the complete
extracted route derived from field 15.
</p>
<ul>
<li><b>get_all_elements()</b>: Returns a list of ExtractedRouteRecord instances where each instance
represents a single item in the extracted route.
</li>
<li><b>get_element_at(index)</b>: Returns an ExtractedRouteRecord from the list of records at the
parameter index.
</li>
<li><b>get_first_element()</b>: Returns the first ExtractedRouteRecord from the list of records.
</li>
<li><b>get_last_element()</b>: Returns the last ExtractedRouteRecord from the list of records.
</li>
<li><b>get_number_of_elements()</b>: Returns the number of ExtractedRouteRecord instances in
the list of ExtractedRouteRecord's.
</li>
<li><b>get_previous_to_last_element()</b>: Returns the one but last ExtractedRouteRecord from
the list of records.
</li>
</ul>
<p>The following methods relate to retrieving records that represent erroneous items found in field 15
while parsing field 15. The items in error are also stored as an instance of an
<b>ExtractedRouteRecord</b>, hence the data available is identical to a 'normal' extracted route
record (except if the error prevented data from being derived from a field 15 item).
</p>
<ul>
<li><b>get_number_of_errors()</b>: Returns the number of ExtractedRouteRecord instances in
the list of ExtractedRouteRecord records for erroneous items in field 15.
</li>
<li><b>get_all_errors()</b>: Returns a list of ExtractedRouteRecord instances where each instance
represents a single item found in field 15 that contains one or more errors. The error message
can be extracted from the ExtractedRouteRecord class.
</li>
</ul>
<h3 id="Extracted Route Record Get Methods">Extracted Route Record Get Methods</h3>
<p>The ExtractedRouteRecord contains a lot of information related to the extracted route. The extracted
route records contain position, speed, altitude and flight rules at an item. The methods shown below
can be used to extract information at each extracted route item.
</p>
<ul>
<li><b>get_altitude()</b>: Returns a route elements altitude as a string, this is what appears in field 15,
e.g. F350.
</li>
<li><b>get_altitude_cruise_to()</b>: Returns a route elements target cruise climb altitude, this is
what appears in field 15, e.g. F350. It is unlikely this item will appear in field 15 as it
relates to the 'cruise/climb' item that was implemented by ICAO for the concorde and supersonic
flight.
</li>
<li><b>get_altitude_cruise_to_si()</b>: Returns a route elements target cruise climb altitude in SI
units (meters) as a floating point number; the SI units are calculated from the altitude values
found in field 15 cruise/climb data. It is unlikely this item will appear in field 15 as it
relates to the 'cruise/climb' item that was implemented by ICAO for the concorde and supersonic
flight.
</li>
<li><b>get_altitude_si()</b>: Returns a route elements altitude in SI units (meters) as a floating
point number; the SI units are calculated from the altitude values found in field 15 altitude data.
</li>
<li><b>get_bearing()</b>: Returns the bearing/azimuth from a point record to the next point record;
this value is only available where the points both have geographic coordinates available.
</li>
<li><b>get_break_text()</b>: This method returns the 'break text' at a rule change point; a route
break occurs when IFR routing stops such as when routing changes to VFR or OAT traffic. Text
that appears following the 'break' indicator is not part of the routing data and is treated
as free text associated with the point at which IFR rules where cancelled.
For example, field 15 'N0100F0200 PNT VFR THIS IS BREAK TEXT' would cause an extracted
route item 'VFR' to be part of the extracted route sequence; this record would contain the
'break text' 'THIS IS BREAK TEXT'.
</li>
<li><b>get_distance()</b>: Returns the distance from a point record to the next point record; this
value is only available where the points both have geographic coordinates available.
</li>
<li><b>get_end_index()</b>: Returns the zero based index where an elements last character + 1 is
located in the original field 15 source text.
</li>
<li><b>get_error_text()</b>: Returns the error text for an item determined by the field 15 parser
to be incorrect. This is only populated when an ExtractedRouteRecord is used for storing
an erroneous field 15 item.
</li>
<li><b>get_flight_rules()</b>: Returns a route elements flight rules, (one of 'I', 'V', 'Y' or 'Z');
</li>
<li><b>get_latitude()</b>: Returns the latitude for a points position in decimal degrees as a floating
point number; this value is calculated from the value found in field 15 which is given as degrees
and minutes.
</li>
<li><b>get_longitude()</b>: Returns the longitude for a points position in decimal degrees as a floating
point number; this value is calculated from the value found in field 15 which is given as degrees
and minutes.
</li>
<li><b>get_name()</b>: Returns a route elements text as found in field 15, could be a point,
latitude/longitude, ATS route SID, STAR etc. as given in field 15.
</li>
<li><b>get_speed()</b>: Returns a route elements speed as a string, this is what appears in field
15, e.g. N0450.
</li>
<li><b>get_speed_si()</b>: Returns a route elements speed in SI units (meters/second) as a floating
point number; the SI units are calculated from the speed values found in field 15 speed data.
</li>
<li><b>get_start_index()</b>: Returns the zero based index where an elements first character is
located in the original field 15 source text.
</li>
<li><b>get_stay_time()</b>: Returns the STAY time in minutes assigned to a point; in field 15 the
time is given in HHMM format, this is converted and stored as an integer value in minutes.
</li>
<li><b>as_xml(error)</b>: This method converts an ERS record into an XML string; the method is
called from the ExtractedRouteSequence class to generate an XML document containing a complete
extracted route sequence as an XML document. If the 'error' parameter is true, an error record
is included containing the associated error message, if false, a record is output with break
text instead of error text. In all other respects the output is identical.
</li>
</ul>
</html>