ATC-pie user guide: Difference between revisions

Version update (v1.0.1)
No edit summary
(Version update (v1.0.1))
Line 3: Line 3:
This article is a guide to help one download and run '''[[ATC-pie]]'''. It describes some of its major features and lists a few tips. Other sources to learn the program are:
This article is a guide to help one download and run '''[[ATC-pie]]'''. It describes some of its major features and lists a few tips. Other sources to learn the program are:
* the [https://www.youtube.com/playlist?list=PL1EQKKHhDVJvvWpcX_BqeOIsmeW2A_8Yb online] '''video tutorial''';
* the [https://www.youtube.com/playlist?list=PL1EQKKHhDVJvvWpcX_BqeOIsmeW2A_8Yb online] '''video tutorial''';
* the in-app '''quick reference''' available from the ''Help'' menu (summary of mouse/keyboard gestures, display conventions, etc.);
* the in-app '''quick reference''' available from the ''Help'' menu (summary of mouse/keyboard gestures, display conventions...);
* to '''play solo'''!
* to '''play solo'''!


Line 24: Line 24:


=== Starting the program ===
=== Starting the program ===
Depending on your system and preference, you might be double-clicking, typing stuff or pulling your hair out. In any case what you need is to run a Python3 interpreter on the <code>ATC-pie.py</code> file in the top-level directory. You may start the program in either '''airport''' or '''centre''' mode, i.e. respectively with or without a base airfield.
Depending on your system and preference, you might be double-clicking, typing stuff or pulling your hair out. In any case what you need is to run a Python3 interpreter on the <code>ATC-pie.py</code> file in the top-level directory. A welcome launcher window should open, from which you may start a session in either airport (AD) or centre (CTR) mode, i.e. respectively with or without a base airfield.


The '''airport mode''' is typically used for ATC positions like approach or tower control. In this mode, ATC-pie places the radar at the chosen base airfield, depicts its tarmac and runways, and enables features like tower viewing and runway use configuration. To start the airport mode from a system terminal, say with base airfield ICAO, the command to run is:
The '''airport mode''' is for ATC positions like approach or tower control. In this mode, ATC-pie places the radar at the chosen base airfield, depicts its tarmac and runways, and enables features like tower viewing and runway selection.
: <code>./ATC-pie.py ICAO</code>
If no ICAO code is given, good old KSFO will be chosen as default.


ATC-pie's '''centre mode''' is designed for en-route control centre simulation (CTR). It disables all airport-specific features, and allows to place the radar anywhere on Earth. To start this mode and define a new centre position, run the command:
The '''centre mode''' is designed for en-route control centre simulation. It disables all airport-specific features, and allows to place the radar anywhere on Earth. When selecting this mode:
: <code>./ATC-pie.py --ctr=location_code radar_position</code>
* The location code is a designator of your choice (excluding airport codes), under which to save your location-specific settings. A good idea is to use ICAO airspace designations, e.g. <code>SBBS</code> for the Brasilia FIR in central Brazil or <code>LFFF</code> for the Paris region in France.
Replace ''location_code'' by a designator of your choice (excluding airport codes), under which to save your location-specific settings. A good idea is to use ICAO airspace designations, e.g. SBBS for the Brasilia FIR in central Brazil, or LFFF for the Paris region in France. The ''radar_position'' argument specifies the point on which to centre the radar. For example, <code>./ATC-pie.py --ctr=LFFF LFPO</code> will define a CTR location named LFFF and centred on Orly airport. See down <code>resources/bg-img/Notice</code> for a full description of the syntax for point specification (look out for any character to escape from shell, e.g. quoting <code>'LFPO>090,15'</code> for a point 15 NM East of Orly).
* The radar position field specifies the point on which to centre the radar. For example, <code>LFPO>090,15</code> will centre the radar on a point 15 NM to the East of Orly airport. See down <code>resources/bg-img/Notice</code> for a full description of the syntax for point specification.


Subsequent runs at the same location will then be enabled without the second argument, and even with the generic command:
You may also bypass the launcher and start directly at a given location with the following command, using an ICAO code for an airport, or a previously defined CTR position:
: <code>./ATC-pie.py location_code</code>
: <code>./ATC-pie.py location_code</code>


Besides the location code argument, the following '''command line options''' are available:
Besides the location code, the following '''command line options''' are available:
{| class="wikitable"
{| class="wikitable"
! Option || Effect and argument specification || Default
! Option || Effect and argument specification || Default
|-
|-
| --ctr=''code'' || Start in CTR mode at given location code (see above). Anonymous argument sets/resets the radar position for this location if given. || (none)
| --map-range=''range'' || Define the distance in NM from the radar centre up to which the map will be drawn and navpoints listed in the navigator (accepted values are 20..500). This option can only be used with a location argument. || 100 in AD mode; 300 in CTR mode
|-
| --map-range=''range'' || Define the distance in NM from the radar centre up to which the map will be drawn and navpoints listed in the navigator (accepted values are 20..500). This is a different setting to the radar range configurable in the game settings. || 100 in AD mode; 300 in CTR mode
|-
| --tower-view-external=''host'' || Avoid running an internal FlightGear process for tower viewing, and specify a host on which a viewer is running. This may still be "localhost". || (none, start internal process)
|-
| --tower-view-ports=''udp'',''telnet'' || Specify the tower view ports to send/connect to. These can be the same (UDP and TCP on same port), and are used whether the viewer process is internal (child) or external (local or remote). || 5010,5010
|-
|-
| --add-view=''host'':''port'' || Register an additional FlightGear instance to forward traffic to. This enables to position more viewers freely. This option can be repeated; views can also be managed at runtime with the in-game interface. || (none)
| --add-view=''host'':''port'' || Register an additional FlightGear instance to forward traffic to. This enables to position more viewers freely. This option can be repeated; views can also be managed at runtime with the in-game interface. || (none)
Line 61: Line 53:


NB: callsigns for ATCs in FlightGear are expected to start with the ICAO code of the controlled airport or sector, and end with a hint on the provided service (twr, gnd, ctr...). Before choosing your callsign on MP connect, make sure it is not already in use, and note that [[FGMS]] restricts callsign length to 7 characters. :-(
NB: callsigns for ATCs in FlightGear are expected to start with the ICAO code of the controlled airport or sector, and end with a hint on the provided service (twr, gnd, ctr...). Before choosing your callsign on MP connect, make sure it is not already in use, and note that [[FGMS]] restricts callsign length to 7 characters. :-(
=== Windows Users ===
Getting PyQT5 and Python3 to work on Windows may be difficult for some. The easiest way to get ATC-pie working on Windows is using WinPython, and it0uchpods' Launcher script. See [https://github.com/it0uchpods/ATC-Pie-Launcher-for-Windows/blob/master/README.md this README] for more details.


== Feature notes ==
== Feature notes ==
Line 78: Line 67:
* other tokens are kept as route leg specifications to the following waypoint (allows for airway or procedure names for example).
* other tokens are kept as route leg specifications to the following waypoint (allows for airway or procedure names for example).


[[File:ATC-pie-screenshot-routeDrawing.png|thumbnail|Assigned routes can be drawn as dotted lines on the radar scope when linked to contacts]]
[[File:ATC-pie-screenshot-routeDrawing.png|thumbnail|Assigned routes are drawn as dotted lines on the radar scope when linked to contacts]]
Parsed routes on flight plans and strips are viewable in a route dialog, showing leg details and the geodesic paths on a world map. Also, when a route is parsed and linked to a radar contact, ATC-pie works out its current leg based on distance to destination, and:
Parsed routes on flight plans and strips are viewable in a route dialog, showing leg details and the geodesic paths on a world map. Also, when a route is parsed and linked to a radar contact, ATC-pie works out its current leg based on distance to destination, and:
* the route to go is drawn as a dotted line on the radar scope (according to scope "show" options);
* the route to go is drawn as a dotted line on the radar scope (according to scope "show" options);
Line 122: Line 111:
When '''playing CTR''', your task is to transit the aircraft across your airspace, always ensuring separation, and to hand each of them over to the most appropriate neighbouring centre North, South, East or West of your sector. You can specify local navpoints in the location settings so that the system includes them as turning points in the randomised aircraft's routes.
When '''playing CTR''', your task is to transit the aircraft across your airspace, always ensuring separation, and to hand each of them over to the most appropriate neighbouring centre North, South, East or West of your sector. You can specify local navpoints in the location settings so that the system includes them as turning points in the randomised aircraft's routes.


In '''airport mode''', traffic is either inbound or outbound. Assuming APP, inbound aircraft must be sequenced and vectored into tower range for handover, unless you are in the TWR position as well. Each inbound aircraft either requests ILS or visual. Playing TWR, you must clear them to land when appropriate, i.e. cleared for ILS approach or expected runway reported in sight. If landing cannot take place (too high, not cleared, etc.), aircraft will go around. Controlling GND, you must move inbound traffic near their parking position once they have vacated the runway, and hand them over to the ramp. Outbound traffic must be brought to hold short of a runway threshold and report ready for departure with TWR. If you play DEP, you must hand outbound aircraft over to the en-route centre (CTR) once they are high enough and close to their exit point if specified in its route. Entry and exit points are configurable in the location settings.
In '''airport mode''', traffic is either inbound or outbound. Assuming APP, inbound aircraft must be sequenced and vectored into tower range for handover, unless you are in the TWR position as well. Each inbound aircraft either requests ILS or visual. Playing TWR, you must clear them to land when appropriate, i.e. cleared for ILS approach or expected runway reported in sight. If landing cannot take place (too high, not cleared...), aircraft will go around. Controlling GND, you must move inbound traffic near their parking position once they have vacated the runway, and hand them over to the ramp. Outbound traffic must be brought to hold short of a runway threshold and report ready for departure with TWR. If you play DEP, you must hand outbound aircraft over to the en-route centre (CTR) once they are high enough and close to their exit point if specified in its route. Entry and exit points are configurable in the location settings.


[[File:ATC-pie-screenshot-handoverPane-solo.png|thumbnail|Handover pane when playing solo in airport mode, assuming all three available positions]]
[[File:ATC-pie-screenshot-handoverPane-solo.png|thumbnail|Handover pane when playing solo in airport mode, assuming all three available positions]]
Line 173: Line 162:
* vectors are issued by way of the vectoring assignment tool: click&drag out of a radar contact for heading, hold SHIFT and drag for altitude/FL vertically and speed horizontally (see [https://www.youtube.com/watch?v=BvA3MRlGJjU video 5] of the tutorial);
* vectors are issued by way of the vectoring assignment tool: click&drag out of a radar contact for heading, hold SHIFT and drag for altitude/FL vertically and speed horizontally (see [https://www.youtube.com/watch?v=BvA3MRlGJjU video 5] of the tutorial);
* taxi instructions are also sent by dragging out of radar contacts, when they are picked up on the ground (stopped and low enough);
* taxi instructions are also sent by dragging out of radar contacts, when they are picked up on the ground (stopped and low enough);
* all other instructions (''line up and wait'', ''clear to land'', etc.) must be sent from the dockable instruction panel.
* all other instructions (''line up and wait'', ''clear to land''...) must be sent from the dockable instruction panel.


NB: Instructions are always issued to the callsign entered in the top field, which should fill automatically on aircraft or strip selection when a callsign is known. Therefore, make sure you do not mess up your strip links or your instructions will realistically be acknowledged and followed by the wrong aircraft.
NB: Instructions are always issued to the callsign entered in the top field, which should fill automatically on aircraft or strip selection when a callsign is known. Therefore, make sure you do not mess up your strip links or your instructions will realistically be acknowledged and followed by the wrong aircraft.
Line 202: Line 191:
=== Tower viewing ===
=== Tower viewing ===
[[File:ATC-pie-screenshot-towerViewing.png|thumbnail|Tower viewing, following a departing aircraft]]
[[File:ATC-pie-screenshot-towerViewing.png|thumbnail|Tower viewing, following a departing aircraft]]
This feature allows you to overlook your airport and the connected (multi-player games) or simulated (solo and teaching sessions) traffic, like a controller from a '''tower viewpoint'''. It uses the tower position specified in the source data if any, otherwise defaults to somewhere over the airport to allow towering all available airports. It is disabled in CTR mode.
This feature allows you to overlook your airport and the connected (multi-player games) or simulated (solo and teaching sessions) traffic, like a controller from a tower viewpoint. It uses the tower position specified in the source data if any, otherwise defaults to somewhere over the airport to allow towering all available airports. It is disabled in CTR mode.


There are two ways of activating a tower view. You may let ATC-pie start its own suitably configured FlightGear process, or have it connect to an external viewer, manually set up and accepting connections. The latter way takes a little more effort but allows to run FlightGear on a different machine and thereby relieve your session from the CPU load a local instance induces. If you are going for that, start ATC-pie with <code>--tower-view-external</code> and check the <code>--tower-view-ports</code> command line option in the table above to set it up correctly.
There are two ways of activating a tower view. You may let ATC-pie start its own suitably configured FlightGear process, or have it connect to an external viewer, manually set up and accepting connections.


Running internally only requires FlightGear installed on your computer. A basic installation is enough, but:
'''Running internally''' only requires FlightGear installed on your computer. A basic installation is enough, but:
* aircraft will only be drawn properly if you have the corresponding [[Aircraft|models]] installed—read the notice in <code>resources/acft</code> and check out the <code>icao2fgfs</code> file to understand how ATC-pie chooses models for FlightGear (initially included are a few ugly substitutions like B772 for A320 to avoid the lighter installations to miss out on planes, but you can edit the file and use your own models);
* aircraft will only be drawn properly if you have the corresponding [[Aircraft|models]] installed—read the notice in <code>resources/acft</code> and check out the <code>icao2fgfs</code> file to understand how ATC-pie chooses models for FlightGear (initially included are a few ugly substitutions like B772 for A320 to avoid the lighter installations to miss out on planes, but you can edit the file and use your own models);
* more importantly, you will need the [[scenery]] for your airport if you want anything exciting to see (and not sea!)—go to [http://www.flightgear.org/download/scenery/ this page] or use [[TerraSync]] to download it to your computer, and add it to your [[$FG_ROOT|FlightGear root directory]] or set the right scenery directory in the ''System'' menu (ATC-pie will pass it on to FlightGear and save your setting).
* more importantly, you will need the [[scenery]] for your airport if you want anything exciting to see (and not sea!)—go to [http://www.flightgear.org/download/scenery/ this page] or use [[TerraSync]] to download it to your computer, and add it to your [[$FG_ROOT|FlightGear root directory]] or set the right scenery directory in the ''System'' menu (ATC-pie will pass it on to FlightGear and save your setting).


In either case, once activated from the ''View'' menu, the tower view controller pane is enabled and you can turn to runway points, follow selected aircraft, etc. Additionally, use right click and drag directly on the view to look around, and you may use the <code>x</code>/<code>X</code> keys to change the zoom level from the view window (this is direct FlightGear input).
Connecting to an '''external viewer''' takes a little more effort but allows to run FlightGear on a different machine and thereby relieve your session from the CPU load a local instance induces. If you want to do so, get a hint of the required positioning options you should start your viewer with, from the tower view tab in the system settings dialog. More options should also be considered, e.g. <code>--fdm=null</code>. Of course, scenery, models and liveries must also be available to the running process.


You can also connect '''additional viewers''' to your session, for example placed around your airport for exciting camera footage of challenging landings. You will not be able to control those viewers from ATC-pie like the tower viewer, but you will be able to activate/stop the connection with a switch in the application ''View'' menu.
In either case, once activated from the ''View'' menu, the tower view controller pane is enabled, from which you can turn to runway points, follow selected aircraft... Direct FlightGear input in the view window is also possible: right click and drag allows to look around, <code>x</code>/<code>X</code> keys change the zoom level, etc.


Every additional FlightGear viewer running on host ''XXX'' should be started with options <code>--multiplay=out,TTT,HHH,PPP</code> and <code>--multiplay=in,TTT,,YYY</code>, and registered in your ATC-pie instance. You can do this from the ''View'' menu (add viewer "''XXX'':''YYY''"), or directly from the command line with <code>--add-view=XXX:YYY</code>. In these options:
You can connect '''additional viewers''' to your session, for example placed around your airport for exciting camera footage of challenging landings. You will not be able to control those viewers from ATC-pie like the tower viewer, but you will be able to activate/stop the connection with a switch in the application ''View'' menu.
 
Every additional viewer running on host ''XXX'' should be started with options <code>--multiplay=out,TTT,HHH,PPP</code> and <code>--multiplay=in,TTT,,YYY</code>. You must then register it in ATC-pie, either from the ''View'' menu (add viewer "''XXX'':''YYY''") or directly from the command line at start through an extra <code>--add-view=XXX:YYY</code> option. In these options:
* ''HHH'' is the host on which ATC-pie is running (same value for all viewers);
* ''HHH'' is the host on which ATC-pie is running (same value for all viewers);
* ''PPP'' is the default 5009, or the chosen port number if ATC-pie is started with <code>--views-send-from</code> (same value for all viewers);
* ''PPP'' is the default 5009, or the chosen port number if ATC-pie is started with <code>--views-send-from</code> (same value for all viewers);
Line 249: Line 240:
* loose strip bays, to move unracked strips over custom backgrounds, e.g. ground charts of the airport.
* loose strip bays, to move unracked strips over custom backgrounds, e.g. ground charts of the airport.


There are two ways to create backgrounds in the program. One working for all purposes is to import '''pictures''' (pixmap files like JPEG or PNG, including transparency); the other works only for radar backgrounds and consists in writing '''drawing specification''' files to paint coloured lines and labelled points. This allows to import anything from the most complex coloured height map to the the most schematic airspace outline. The <code>resources/bg-img/Notice</code> file explains how to import and draw background images. All pictures and drawing points are positioned using lat/lon coordinates, navpoints in map range and radial/distance expressions as per the "point specification" syntax explained in the notice.
There are two ways to create backgrounds in the program. One working for all purposes is to '''import pictures''' (pixmap files like JPEG or PNG, including transparency); the other works only for radar backgrounds and consists in writing '''drawing specification''' files to paint coloured lines and labelled points. This allows to import anything from the most complex coloured height map to the the most schematic airspace outline. The <code>resources/bg-img/Notice</code> file explains how to import and draw background images. All pictures and drawing points are positioned using lat/lon coordinates, navpoints in map range and radial/distance expressions as per the "point specification" syntax explained in the notice.


For example, you can map out procedures (SID, STAR, IAD...), grouping them by associated runways. Drawings are generally appropriate for that because they allow referring to named points as per the published procedures and avoid manual positioning. But if you want more than schematic line plots, you should create the picture yourself. Using an image processing tool like ''GIMP'', superimpose a transparent layer on top of a real map canvas, or over a screenshot of your ATC-pie radar with pinned navaids as landmarks, and freely decorate your picture.
For example, you can map out procedures (SID, STAR, IAD...), grouping them by associated runways. Drawings are generally appropriate for that because they allow referring to named points as per the published procedures and avoid manual positioning. But if you want more than schematic line plots, you should create the picture yourself. Using an image processing tool like ''GIMP'', superimpose a transparent layer on top of a real map canvas, or over a screenshot of your ATC-pie radar with pinned navaids as landmarks, and freely decorate your picture.
Line 294: Line 285:
You can '''customise the radar & strip colours''' by editing the colour codes in the <code>settings/colours.ini</code> file generated on first run.
You can '''customise the radar & strip colours''' by editing the colour codes in the <code>settings/colours.ini</code> file generated on first run.


'''Heading displays''' are mostly magnetic so they can be read out to pilots. The only exceptions perhaps are the navigator and handover list tooltips, for easier human identification on the scope. All directions are geodesic.
'''Heading displays''' are mostly magnetic so they can be read out to pilots. The only exceptions are the navigator and handover list tooltips, for easier human identification on the scope. All directions are geodesic.


The grouped diamond and tick marks along the '''landing helper lines''' indicate best altitudes AMSL for final approach along the configured flight path angle: diamond marks read 5,000 ft each; every other tick mark is 1,000 ft.
The grouped diamond and tick marks along the '''landing helper lines''' indicate best altitudes AMSL for final approach along the configured flight path angle: diamond marks read 5,000 ft each; every other tick mark is 1,000 ft.
A <code>*</code> symbol in front of a strip callsign means that a '''strip comment''' is present (filled in the details). Open the detail sheet to view, or hover the strip with the mouse to show it as a tool tip.


The '''transition level''' displayed in the weather analysis is the lowest flight level that is still above the transition altitude. This does not mean the lowest to be expected in ATC clearances, which may be higher, for more vertical separation on either side of the transition layer or due to coordination with neighbouring zones and fields.
The '''transition level''' displayed in the weather analysis is the lowest flight level that is still above the transition altitude. This does not mean the lowest to be expected in ATC clearances, which may be higher, for more vertical separation on either side of the transition layer or due to coordination with neighbouring zones and fields.
Line 318: Line 307:
In airport mode, typing a single dot character <code>.</code> in an '''airport input field''' will instantly fill the box with your ICAO position. Use this as a shortcut from/to your airport when filling details.
In airport mode, typing a single dot character <code>.</code> in an '''airport input field''' will instantly fill the box with your ICAO position. Use this as a shortcut from/to your airport when filling details.


Resolving '''strip–FPL conflicts''':
A <code>*</code> symbol in front of a strip callsign means that a '''strip comment''' is present (filled in the details). Open the detail sheet to view, or hover the strip with the mouse to show it as a tool tip.
* to confirm strip details: open the strip detail sheet, tick the "push details to FPL" box and save to propagate the strip details;
* to confirm FPL details: "pull FPL details" from the button menu to reset the conflicting strip details to the values filled in the linked flight plan;
* to confirm some details of each source: open the strip sheet, get rid of the bad details before pushing to the flight plan.
 
Resolving '''local–online flight plan conflicts''':
* to update the online version with your local modifications, double-click the flight plan and tick the "publish" box before saving (if still decorated red, there was a network problem or the change was rejected by the server);
* to discard all local modifications of an online FPL, remove the FPL from the list and check for new flight plans again (the deleted entry should be retrieved with online state).


[[Category:ATC-pie]]
[[Category:ATC-pie]]
265

edits