readme.md
Map Feature Plugin
Introduction
The Map Feature plugin displays a world map in 2D and 3D. It can display street maps, satellite imagery as well as custom map types. On top of this, it can plot data from other plugins, such as:
- APRS symbols from the APRS Feature,
- Aircraft from the ADS-B Demodulator,
- Aircraft from the Aircraft feature (which combines data from ADS-B and ACARS demodulators) including a PFD (Primary Flight Display) and ND (Navigation Display),
- Ships from the AIS Demodulator,
- Satellites from the Satellite Tracker,
- Satellite imagery from APT Demodulator,
- The Sun, Moon and Stars from the Star Tracker,
- Weather balloons from the Radiosonde feature,
- RF Heat Maps from the Heap Map channel,
- Radials and estimated position from the VOR localizer feature,
- ILS course line and glide path from the ILS Demodulator,
- DSC geographic call areas,
- Inmarsat C message geographic areas,
- SID paths,
- Pager messages that contain coordinates,
- DJI drones from the DJI DroneID Demodulator.
As well as internet and built-in data sources:
- AM, FM and DAB transmitters in the UK and DAB transmitters in France,
- Airports, NavAids and airspaces,
- Beacons based on the IARU Region 1 beacon database and International Beacon Project,
- Radio time transmitters,
- WEFAX (weather fax) transmitters,
- GRAVES radar,
- Ionosonde station data,
- Navtex transmitters,
- VLF transmitters,
- KiwiSDRs,
- Spy Servers,
- Weather radar,
- Satellite infra-red data (clouds),
- Sea marks,
- Satellite imagery from NASA GIBS (Global Imagery Browse Services),
- Aurora probabilty.
It can also create tracks showing the path aircraft, ships, radiosondes and APRS objects have taken, as well as predicted paths for satellites.
3D Models are not included with SDRangel. They must be downloaded by pressing the Download 3D Models button in the Display Settings dialog (26). The aircraft sounds are not included either, and are downloaded with the Download Sounds button beside it.
If the 3D map doesn't display on Linux, try setting QT_QPA_PLATFORM=xcb QTWEBENGINE_CHROMIUM_FLAGS="--ignore-gpu-blocklist"
Interface
1: Find
To centre the map on an object or location, enter:
- An object name.
- Latitude and longitude. This can be in decimal degrees (E.g: -23.666413, -46.573550) or degrees, minutes and seconds (E.g: 50°40'46.461"N 95°48'26.533"W or 33d51m54.5148sS 151d12m35.6400sE).
- A Maidenhead locator (E.g: IO86av).
- An address (E.g: St Katharine's & Wapping, London EC3N 4AB)
2: 2D Map Type
Allows you to select a 2D map type. The available types will depend upon the Map provider selected under Display Settings (26).
3: Maidenhead locator conversion
When checked, opens the Maidenhead locator converter dialog, which allows conversion between addresses, latitude and longitude and Maidenhead locators. Enter a location in one field and press enter to convert.
4: Maidenhead grid
When checked, displays a Maidenhead locatator grid on the 3D map. The grid size depends on the zoom level.
5: Display Beacon dialog
When clicked, opens the Beacon dialog. Initially, no beacons will be listed. To download the IARU Region 1 beacon list, click the download button in the top right. The beacons will then be displayed in the table and on the map.
- Double clicking in a cell in the beacon table in the Callsign or Location columns, will centre the map on that beacon.
- Double clicking on the Frequency column will set the Device center frequency.
6: Display IBP Beacon Project Dialog
When clicked, opens the International Beacon Project dialog. The IBP consists of 18 HF beacons around the world, that each transmit once on each of the frequencies 14.100, 18.110, 21.150, 24.930 and 28.200MHz every 3 minutes, for 10 seconds. The IBP dialog shows which of the beacons should currently be transmitting.
- Double clicking in a cell in the Callsign column will centre the map on that beacon.
- Double clicking in a cell in the Frequency column will set the Device center frequency.
More details of the IBP can be found at: https://www.ncdxf.org/beacon/beaconfaq.html
7: Display Radio Time Transmitters dialog
When clicked, opens the Radio Time Transmitters dialog.
- Double clicking in a cell in the table in the Callsign or Location columns, will centre the map on that transmitter.
- Double clicking on the Frequency column will set the Device center frequency.
8: Display Satellite Infrared
When checked, satellite infrared measurements (10.3um) are downloaded from the internet and are overlaid on the maps. This essentially shows cloud cover. The images are updated every 10 minutes.
The data is similar to that which can be received using the APT Demodulator in the Thermal-infrared (10.3-11.3 um) channel.
This is only supported on 2D raster maps and the 3D map.
9: Display Weather Radar
When checked, weather radar measurements are downloaded from the internet and are overlaid on the maps. This shows rain and other forms of precipitation. The images are updated every 10 minutes.
Green, yellow and red are rain, with red being the most intense. Light blue through dark blue is snow, with dark blue being the most intense.
This is only supported on 2D raster maps and the 3D map.
10: Display Sea Marks
When checked, sea marks are overlaid on the maps.
This is only supported on 2D raster maps and the 3D map.
11: Display Railways
When checked, railway routes are overlaid on the maps.
This is only supported on 2D raster maps and the 3D map.
12: Display MUF Contours
When checked, contours will be downloaded and displayed on the 3D map, showing the MUF (Maximum Usable Frequency) for a 3000km path that reflects off the ionosphere. The contours will be updated every 15 minutes. MUF contour data is available for the preceding 5 days.
13: Display coF2 Contours
When checked, contours will be downloaded and displayed on the 3D map, showing coF2 (F2 layer critical frequency), the maximum frequency at which radio waves will be reflected vertically from the F2 region of the ionosphere. The contours will be updated every 15 minutes. coF2 contour data is available for the preceding 5 days.
14: Display Magnetic Declination
When checked, contours will be displayed on the 3D map showing magnetic declination.
Green contours represent 0 degrees. Red is positive, blue negative. Contours are in 2 degree steps. Clicking on a countour will display its value in the info box.
15: Display Aurora Predicition
When checked, aurora prediction data will be downloaded and displayed on the 3D map.
Probabilties:
- Green 10%
- Yellow 50%
- Red 90%
16: Display NASA GIBS Data
When checked, enables overlay of data from NASA GIBS (Global Imagery Browse Services). This includes a vast array of Earth observation satellite data, such as land and sea temperatures, atmospheric conditions, flux measurements and the like. Details of available data products can be found here.
For some data sets, GIBS has data spanning many decades. The data period may be hours, days or months. The 3D map will attempt to show data from the closest time set in the 3D map's timescale. The 2D map will only show data from the default date (which is displayed in the table at the bottom).
This is only supported on 2D raster maps and the 3D map.
17: NASA GIBS Data
Selects which data from NASA GIBS to overlay on the maps.
18: NASA GIBS Opacity
Sets the opacity used for the NASA GIBS overlay image overlay on the 3D map. Lower values make the image more transparent.
19: Display Names
When checked, names of objects are displayed in a bubble next to each object.
20: View
Select from:
- First Person - The camera is positioned at the object and looks in the direction of its heading.
- Third Person - The camera is positioned to the side of the object and looks at it. The camera can be rotated around the object by holding the left mouse button and dragging.
- Fly By - The camera is positioned ahead of the object and tracks it as it moves. When the object reaches a distance away from the camera, the camera will move to a new position ahead of the object.
21: Avionics
Check to enable individual avionics displays for aircraft selected on the 3D Map.
PFD (Primary Flight Display)
When checked, the aircraft PFD (Primary Flight Display) will be displayed. This can be either Airbus or Boeing style, depending upon the aircraft type. This is used for displaying ADS-B and Mode S data for an aircraft, such as speed, attitude, altitude, vertical rate, heading, track and QNH setting. It can display whether the autopilot is enganged (CMD or AP1+2) and selected alitutude and heading, as well as lateral and vertical navigation modes, such as LNAV/NAV, VNAV/CLB/ALT, LOC and G/S. The flight director is simulated, rather than being based on ADS-B data, as it the rad alt (radio altimeter). In the bottom left hand corner it will display the aircrafts callsign and type, if known.
The PFD can be moved by left clicking on it and dragging it. It can be resized by left clicking and dragging in the bottom right corner.
ND (Navigation Display)
When checked, the aircraft ND (Navigation Display) will be displayed for the selected aircraft. This shows a compass rose with range rings, ground speed, true air speed and wind direction, the flight plan and its waypoints when one has been received (via the Aircraft feature, from an ACARS FPN message or oceanic clearance), and other nearby aircraft as TCAS-style traffic symbols with relative altitudes.
Two display modes are supported, toggled by the MODE button in the EFIS. ARC, which shows a 120 degree arc ahead of the aircraft, and ROSE, which shows a full 360 degree compass rose. The range (10 to 320 nautical miles) can be changed with the RANGE button in the EFIS, or by scrolling the mouse wheel over the ND.
When the flight plan includes an arrival approach or runway (e.g. ILSY 18R), it is displayed at the top of the ND once the aircraft is within 250 nautical miles of the arrival airport, or whenever the approach is being flown (G/S or LOC mode active).
The ND can be moved by left clicking on it and dragging it. It can be resized by left clicking and dragging in the bottom right corner.
Note that the compass rose is orientated to the aircraft's magnetic heading, while waypoint and traffic positions are true bearings, so the overlay can be off by the local magnetic declination.
EFIS (Electronic Flight Instrument System)
When checked, the aircraft EFIS (Electronic Flight Instrument System) will be displayed. This controls what is displayed on the ND.
MODE: ROSE / ARC RANGE: 10 - 360 nm. Sets the range of the ND in nautical miles. WX: Displays live weather radar on the ND. TERR: Displays terrain on the ND. ARPT: Displays airports on the ND. VOR: Displays VORs on the ND.
RMP (Radio Management Panel)
When checked, the Radio Management Panel will be displayed. This:
- Displays transponder / squawk ID from ADS-B data.
- Sets the TCAS mode for the ND. ALL displays all aircraft in range. ABV displays aircraft from -2700 to +7000 ft. BLW displays aircraft from -7000 to +2700 ft. THRT displays nearest 8 aircraft within +-2700 ft.
- Allows control of two AM Demodulators as though there were two VHF radios in the aircraft. The AM demodulators are set in the Map Display Settings dialog. To set a frequency, select a STBY field by clicking on it, enter the frequency in MHz using the digit buttons, then press transfer to ACTIVE (the button in between the ACTIVE and STBY fields).
DCDU (Datalink Control and Display Unit)
When a datalink ATC message (CPDLC, pre-departure clearance or oceanic clearance, received via the Aircraft feature) arrives for the currently selected aircraft, or the aircraft being followed, a DCDU window pops up on the 3D map showing the time the message was received, which station it is to or from (e.g. 1412Z FROM EDDS) and the message text. Long messages are split over multiple pages - click the PG indicator to move between them. The window is closed by clicking CLOSE, and can be moved and resized like the PFD and ND.
A ring is played when a message arrives. Its volume is set by the "Cockpit volume" slider in the Map Display Settings dialog.
23: Display tracks for selected object
When checked, displays the track (taken or predicted) for the selected object.
24: Display tracks for all objects
When checked, displays the track (taken or predicted) for the all objects.
25: Save to .kml
When clicked, items and tracks on the map will be saved to a KML (.kml or .kmz) file, for use in other applications.
Note that the KML format requires 3D models in the Collada (.dae) format. However, SDRangel's models are in glTF (.glb or .gltf) format. If you wish to view the models in a KML viewer, you will need to manually convert them. Note that you should still be able to view tracks without the models. Note that the .glbe files cannot be converted to .dae.
26: Delete
When clicked, all items will be deleted from the map.
27: Display settings
When clicked, opens the Map Display Settings dialog:
For the 2D map, the settings include:
- Whether the 2D map is displayed.
- Which Map provider will be used to source the map images. OpenStreetMap provides raster maps. MapboxGL provides vector maps. Providers will vary according to Qt version and O/S.
- When OpenStreetMap is used as the provider, a custom map URL can be entered. For example, http://a.tile.openstreetmap.fr/hot/ or http://1.basemaps.cartocdn.com/light_nolabels/ or file:///opt/install/custom-map if using a map stored locally, such a map created with QGIS using the "Generate XYZ tiles (Directory)" tool or gdal2tiles or any other tool that creates map images compatible with Google Maps, OpenLayers and Leaflet.
- When MapboxGL is used as the provider, custom styles can be specified. MapboxGL requires a Mapbox API key to be entered.
- Whether aircraft are displayed using icons showing their airline's livery, instead of black icons. The Map picks the icon that matches the aircraft's 3D model, so this requires the 3D models to have been downloaded. Otherwise, aircraft are displayed with the icon sent by the source plugin, which is a livery icon when the source plugin's own livery icons option is enabled.
For the 3D map, the settings include:
- Whether the 3D map is displayed.
- The default imagery to use. Bing Maps Aerial, Sentinel-2, Earth at night and the Google Maps imagery use Cesium Ion quota, so require a Cesium Ion API key to be entered on the API Keys tab. Without one, they are greyed out and ArcGIS world imagery is used.
- The terrain provider, which provides elevation data. For a "flat" globe, terrain can be set to Ellipsoid for the WGS-84 ellipsoid. Cesium World Terrain requires a Cesium Ion API key.
- Whether lighting is applied to the terrain. Not applicable if terrain is set to Ellipsoid.
- Whether animated water effects (such as waves) are used. Not applicable if terrain is set to Ellipsoid.
- The buildings provider, which provides 3D building models. This can be set to None if no buildings are desired. The buildings may float in the air if terrain is set to Ellipsoid. Cesium OSM Buildings requires a Cesium Ion API key.
- Whether Google Photorealistic 3D Tiles are displayed. These combine terrain, buildings and imagery in a single photorealistic model, so the imagery, terrain and buildings settings above are not used while they are enabled. As the globe itself is not drawn, the map layers that are drawn on it, such as rain, clouds, sea marks, railways, NASA global imagery and the Maidenhead grid, are not displayed either. Requires a Cesium Ion API key. Aircraft are placed on top of the tiles, but items that are clamped to the ground by Cesium itself, rather than clipped to it by SDRangel, such as airports and navigation aids, may be hidden underneath them.
- Whether the globe and models are lit from the direction of the Sun or the camera.
- The camera light intensity if Lighting is set to Camera.
- Whether HDT (High Dynamic Range) rendering should be used.
- Whether low detail models are used. Aircraft converted from MSFS with a second level of detail are drawn with the simpler model while they cover less than about 8% of the height of the map, and with the full model again above 11%, which greatly improves the frame rate with many aircraft in view. An aircraft being followed is always drawn in full detail.
- Whether a fog effect should be applied.
- The camera reference frame. For ECEF (Earth Centered Earth Fixed), the camera rotates with the globe. For ECI (Earth Centred Inertial) the camera is fixed in space and the globe will rotate under it.
- Whether FXAA anti-aliasing is applied.
- Whether MSAA anti-aliasing is applied and how many samples to use.
- Whether the FPS (Frames Per Second) are displayed.
- The frame rate the 3D map is rendered at. The default is 60 fps. Display uses the refresh rate of the display the map is on. Lower rates use less CPU and GPU.
QtWebEngine puts at most 60 frames per second on screen, so to run the 3D map at more than 60 FPS, set the environment variable
QTWEBENGINE_CHROMIUM_FLAGS=--disable-frame-rate-limitbefore starting SDRangel. Without it, frames rendered above 60 FPS are discarded and Display is limited to 60 fps. However, this can result in stuttering at the Qt compositor discarding rendered frames, so currently isn't recommended.
The "Download 3D Models" button will download the 3D models of aircraft, ships and satellites that are required for the 3D map. These are not included with the SDRangel distribution, so must be downloaded. It is recommended to restart SDRangel after downloading the models.
The "Download Sounds" button will download the aircraft sounds the 3D map plays: the engine sound sets, the cockpit callouts, and the gear and flap movements.
The Map Items tab customization of how objects from different SDRangel plugins and the Internet are displayed on the 2D and 3D maps.
Each row is a group of items. Most groups are named after the plugin that sends them, and everything that plugin draws shares the row. A plugin can also put some of what it draws in a group of its own, where those items want different settings from the rest - the Aircraft feature does this for filed flight plans and oceanic clearances, which appear as Aircraft Routes. That exists because a route wants the opposite of an aircraft from the 2D Min Zoom column: an aircraft icon has to be decluttered away when the map is zoomed out, while a route drawn across an ocean is exactly what should still be visible there. So Aircraft can be left at 11 and Aircraft Routes at 0.
The settings include:
- Whether images are displayed on the 2D map and whether 3D models are displayed on the 3D map.
- Whether labels are displayed giving the name of the object.
- Whether taken and predicted tracks are displayed and in which colour. Instead of a single colour, a palette can be chosen in the Palette column, which colours the track on both the 2D and 3D maps according to the altitude of the object, with a different colour for every 5000ft, in the same way as the tracks on the ADS-B Demodulator's map. This defaults to Spectral for aircraft and None (a single colour) for everything else. Objects with predicted tracks, such as satellites, are always drawn in a single colour on the 3D map.
- How the image or 3D model is scaled as the zoom level changes.
API keys are required to access maps from different providers.
Free API keys are available by signing up for an accounts with:
If API keys are not specified, a default key will be used, but this may not work if too many users use it, so please create and use your own.
The Cesium Ion key is an exception: several 3D map layers use quota from the Cesium Ion account the key belongs to, so those layers are only available once you have entered your own key. This applies to Bing Maps Aerial, Sentinel-2, Earth at night and Google Maps imagery, Cesium World Terrain, Cesium OSM Buildings and Google Photorealistic 3D Tiles. Without a key, these are greyed out in the settings dialog and are not offered in the imagery selector on the 3D map itself.
Map
The map feature displays a 2D and a 3D map overlaid with objects reported by other SDRangel channels and features, as well as beacon locations.
- The "Home Station" antenna location is placed according to My Position set under the Preferences > My Position menu.
- To pan around the map, click the left mouse button and drag. To zoom in or out, use the mouse scroll wheel.
- The 2D map can be rotated by holding shift while using the mouse wheel, or tilted by holding control and using the mouse wheel. (Qt 6 only).
- Single clicking on an object in the map will display a text bubble with additional information about the object.
- Right clicking on a object on the 2D map will open a context menu, which allows:
- To set an object as the target. The target object will have its azimuth and elevation displayed in the text bubble and sent to the Rotator Controller feature.
- Setting the Device center frequency to the first frequency found in the text bubble for the object.
- Changing the order in which the objects are drawn, which can help to cycle through multiple objects that are at the same location on the map.
- Setting the object as the tracking target on the 3D map.
- Left double clicking while holding shift on the 3D map will place a marker showing the position. Right clicking will clear it.
- On the 3D map, WASD keys can be used to move the camera up, left, down and right. QE for forward and back.
The 2D map will only display the last reported positions for objects. The 3D map, however, has a timeline that allows replaying how objects have moved over time. To the right of the timeline is the fullscreen toggle button, which allows the 3D map to be displayed fullscreen.
SDRs
The map can display SDRangel Remote TCP Servers, KiwiSDRs and Spy Servers that are publicly accessible via the internet. A URL is displayed in the info box. Clicking on the URL will open a new KiwiSDR or RemoteTCPInput device which will connect to the corresponding SDR. Before connecting, you should check the whether the number of users is below the maximum. Server data is updated every 2 minutes.
Ionosonde Stations
When Ionosonde Stations are displayed, data is downloaded and displayed every 2 minutes. The data includes:
- MUF - Maximum Usable Frequency in MHz for 3000km path.
- M(D) - M-factor (~MUF/foF2) for 3000km path.
- foF2 - F2 region critical frequency in MHz.
- hmF2 - F2 region height in km.
- foE - E region critical frequency in MHz.
- TEC - Total Electron Content.
Each station is labelled on the maps as "MUF/foF2".
MUF and foF2 can be displayed as contours:
The contours can be clicked on which will display the data for that contour in the info box.
VLF Transmitters
The Map contains a built-in list of VLF transmitters. This can be overridden by a user-defined list contained in a file vlftransmitters.csv in the application data directory.
The file must have the following columns:
Callsign,Frequency,Latitude,Longitude,Power
GQD,19580,54.911643,-3.278456,10
Attribution
IARU Region 1 beacon list used with permission from: https://iaru-r1-c5-beacons.org/ To add or update a beacon, see: https://iaru-r1-c5-beacons.org/index.php/beacon-update/
Mapping and geolocation services are by Open Street Map: https://www.openstreetmap.org/ esri: https://www.esri.com/ Mapbox: https://www.mapbox.com/ Cesium: https://www.cesium.com Bing: https://www.bing.com/maps/
Ionosonde data and MUF/coF2 contours from KC2G with source data from GIRO and NOAA NCEI.
Aurora probility data from NOAA
Sea Marks are from OpenSeaMap: https://www.openseamap.org/
Railways are from OpenRailwayMap: https://www.openrailwaymap.org/
Weather radar and satellite data is from RainViewer: https://www.rainviewer.com
Icons made by Google from Flaticon: https://www.flaticon.com World icons created by turkkub from Flaticon: https://www.flaticon.com Layers and Boat icons created by Freepik from Flaticon: https://www.flaticon.com Railway icons created by Prosymbols Premium from Flaticon: https://www.flaticon.com Satellite icons created by SyafriStudio from Flaticon: https://www.flaticon.com Pager icons created by xnimrodx from Flaticon: https://www.flaticon.com Northern lights icons created by Abdul-Aziz from Flaticon: https://www.flaticon.com Globe icons created by Creative Stall Premium from Flaticon: https://www.flaticon.com Person icon created by Yudhi Restu Pebriyanto from Noun Project: https://thenounproject.com/ Eyes icon created by Astatine Lab from Noun Project: https://thenounproject.com/
3D models are by various artists under a variety of licenses. See: https://github.com/srcejon/sdrangel-3d-models
Creating 3D Models
If you wish to contribute a 3D model, see the https://github.com/srcejon/sdrangel-3d-models project.
API
Full details of the API can be found in the Swagger documentation. Here is a quick example of how to centre the map on an object from the command line:
curl -X POST "http://127.0.0.1:8091/sdrangel/featureset/feature/0/actions" -d '{"featureType": "Map", "MapActions": { "find": "M7RCE" }}'
And to centre the map at a particular latitude and longitude:
curl -X POST "http://127.0.0.1:8091/sdrangel/featureset/feature/0/actions" -d '{"featureType": "Map", "MapActions": { "find": "51.2 0.0" }}'

























