more information about terrain data

Author: timtuxworth

common/source/docs/common-terrain-following.rst

@@ -69,11 +69,12 @@ Terrain Following in CRUISE and FBWB modes can be disabled with an RC switch ass
 Use of terrain following in AUTO missions is controlled on a waypoint by
 waypoint basis using the reference frame of the waypoint. Normal (non
 terrain following) waypoints have a "Relative" reference frame, and
-altitudes are specified relative to the home location. Not by the :ref:`TERRAIN_FOLLOW<TERRAIN_FOLLOW>` parameter. Terrain following
-waypoints have a "Terrain" reference frame, and altitudes are relative
+altitudes are specified relative to the home location, not by the :ref:`TERRAIN_FOLLOW<TERRAIN_FOLLOW>` parameter.
+Terrain following waypoints have a "Terrain" reference frame, and altitudes are relative
 to the ground level given in the terrain database.
 
-.. note:: in AUTO mode autolandings, the :ref:`TERRAIN_FOLLOW<TERRAIN_FOLLOW>` parameter does have an impact, when a rangefinder is also used. See :ref:`rangefinder-autolanding`.
+.. note:: in AUTO mode autolandings, the :ref:`TERRAIN_FOLLOW<TERRAIN_FOLLOW>` parameter
+   does have an impact, when a rangefinder is also used. See :ref:`rangefinder-autolanding`.
 
 See :ref:`common-understanding-altitude` for altitude definitions.
 
@@ -92,30 +93,51 @@ the terrain may vary significantly. Key uses are:
 -  **FPV flying.** When flying FPV in CRUISE mode it is useful to
    maintain constant height above the ground so you can spend more time
    enjoying the scenary and less time avoiding hills
+-  **Regulatory Compliance.** many countries have restrictions on the
+   altitude drones must fly at or below, often 400' (about 120m). with
+   terrain following enabled, missions items and other limits including
+   :ref:`FENCE_ALT_MIN<FENCE_ALT_MIN>` and :ref:`FENCE_ALT_MAX<FENCE_ALT_MAX>`
+   can be specified in AGL (terrain) frame.
 
 
 Sources of Terrain Data
 =======================
 
-The ground station is normally responsible for providing the raw terrain data which is sent to the aircraft via MAVLink. Right now only Mission Planner and MAVProxy support the required TERRAIN_DATA and TERRAIN_REQUEST MAVLink messages needed for terrain following download support. If you are using a different ground station , in order to download terrain data you will need to connect using one of those two ground stations in order to allow ArduPilot to load terrain data onto your board on the ground or in flight.  Once it is loaded, it is saved permanently on the microSD card.
+The ground station is normally responsible for providing the raw terrain data which is sent to the aircraft via MAVLink. 
+Right now only Mission Planner, QGroundControl, SiYi UniGCS and MAVProxy support the required TERRAIN_DATA and TERRAIN_REQUEST 
+MAVLink messages needed for terrain following download support. If you are using a different ground station , in order to download terrain data you will need to connect using one of those two ground stations in order to allow ArduPilot to load terrain data onto your board on the ground or in flight.  Once it is loaded, it is saved permanently on the microSD card.
 
-Both MissionPlanner and MAVProxy support the global SRTM database for terrain data.  The ArduPilot SRTM server used by MAVProxy and Mission Planner has 100m grid spacing. Unless the ground control station uses a different server with closer spacing, setting the :ref:`TERRAIN_SPACING <TERRAIN_SPACING>` parameter lower than 100m provides no better resolution, and only consumes more space on the SD card. 
+Both MissionPlanner and MAVProxy support the global SRTM database for terrain data.
+The ArduPilot SRTM server used by MAVProxy and Mission Planner provides data with 100m and 30m grid spacing.
+Unless the ground control station uses a different server, setting the :ref:`TERRAIN_SPACING <TERRAIN_SPACING>`
+parameter other than 100m or 30m provides no better resolution, and only consumes more space on the SD card.
 
-Terrain Data is downloaded any time you save or connect with a loaded mission with these ground stations, or, if flying, the autopilot will request data if it's flying into an area not already downloaded, assuming the ground station can provide it. Usually an internet connection is required by the ground station.
+If :ref:`TERRAIN_OPTIONS<TERRAIN_OPTIONS>` bit 1 is not set, terrain Data is downloaded any time you save or 
+connect with a loaded mission with these ground stations, or,
+if flying, the autopilot will request data if it's flying into an area not already downloaded, assuming the
+ground station can provide it. Usually an internet connection is required by the ground station for this to work.
 
-.. warning:: While the autopilot will request the terrain data around waypoints and home location, if it is not connected to a GCS that can supply enroute tiles, the autopilot just interpolates between waypoint's terrain elevation. See below:
+.. warning:: While the autopilot will request the terrain data around waypoints and home location, if it is not connected to a GCS that can supply enroute tiles, and if there relevant terrain data is not on the SD Card, the autopilot just interpolates between waypoint's terrain elevation. See below:
 .. image:: ../../../images/terrain-warning.jpg
 
-If you are not flying with a GCS that can fetch and supply terrain data as the vehicles flies between waypoints, the you may need to load terrain data covering the flight route and/or area for RTL paths manually.
+If you are not flying with a GCS that can fetch and supply terrain data as the vehicles flies between waypoints,
+the you may need to load terrain data covering the flight route and/or area for RTL paths manually.
 
-You can download a set of terrain data tiles for any anticipated flight area using this `web utility <https://terrain.ardupilot.org/>`__. 
+You can download a set of terrain data tiles at either 100m (STRM3) or 30m (SRTM1) for any anticipated
+flight area using this `web utility <https://terrain.ardupilot.org/>`__.
 
 .. image:: ../../../images/common-terrain-dl-utility.png
 
 It will create tiles for the specified radius around a geographic location. Then you can download them, unzip and write in the APM/TERRAIN folder of the SD card.
 
 You can also download .zip files for entire continents, or individual tiles from `here <https://terrain.ardupilot.org/continentsdat3/>`__. 
 
+You may also want to obtain higher resolution data, available from commercial sources online, if you have specialized requirements.
+
+It's a very good idea to remove the SD card from the AutoPilot and copy large terrain data sets directly to
+the /APM/TERRAIN folder from your PC, as copying them via MAVFtp in Mission Planner using a USB
+or other MAVlink connection is likely to take many, many hours or even days.
+
 Terrain Spacing
 ===============
 
@@ -125,16 +147,26 @@ requests for terrain data from the aircraft to the ground station. The
 default :ref:`TERRAIN_SPACING<TERRAIN_SPACING>` is 100 meters, but users may set a different
 grid spacing for specialist applications.
 
+30m spacing (SRTM1) data provides a good compromise between accuracy and
+bandwidth/storage space, and runtime memory requirements. Use ``TERRAIN_SPACING`` = 30
+meters for most normal use cases.
+
 Note that the amount of terrain data kept in memory is directly related
 to the grid spacing. If you decrease the ``TERRAIN_SPACING`` by a factor of
 2 then the amount of terrain area kept in memory is reduced by a factor
-of 4. It is recommended that you use a ``TERRAIN_SPACING`` of 100
+of 4. This may be an issue on older boards with less memory, but for a newer
+AutoPilot with 1M of RAM, the :ref:`TERRAIN_CACHE_SZ<TERRAIN_CACHE_SZ>` can be
+increased to make better use of available memory for caching terrain tiles. The default
+is 12 but a good value on an H743 or H757 processor is probably 60.
+
+If your AutoPilot has less memory, less storage space or communication
+bandwidth might be an issue, it is recommended that you use a ``TERRAIN_SPACING`` of 100
 meters to prevent the aircraft running off the side of a grid in flight
 and not having data available.
 
 If the ground station does not have terrain data available at the
 resolution requested by the aircraft then the ground station will
-interpolate as necessary to provide the requested grid size. Currently, MAVPRoxy and Mission Planner can only provide data down to 100m spacing.
+interpolate as necessary to provide the requested grid size. 
 
 Terrain Accuracy
 ================
@@ -163,13 +195,15 @@ steps
 When the autopilot has finished loading terrain data you should see
 "ter_pend" goes to zero and the current terrain altitude in meters
 showing up in "ter_alt". The "ter_pend" value is the number of terrain
-blocks that the autopilot is waiting to load from the ground station.
+blocks that the autopilot is waiting to load from the ground station or from the SD Card.
 
 Options
 -------
-There are two optional behaviors which can be selected via the :ref:`TERRAIN_OPTIONS<TERRAIN_OPTIONS>` bitmask parameter:
+There are three optional behaviors which can be selected via the :ref:`TERRAIN_OPTIONS<TERRAIN_OPTIONS>` bitmask parameter:
+
 - if bit 0 is set (value+1): downloading of terrain data is halted.
 - if bit 1 is set (value+2): enables using terrain data (via GCS) when no SD card is present.
+- if bit 2 is set (value+4): will accept "old" terrain data (see below)
 
 Terrain Look-ahead
 ==================
@@ -185,5 +219,39 @@ include climb rates your aircraft cannot achieve.
 The climb rate used in the terrain look-ahead is based on the
  :ref:`TECS_CLMB_MAX<TECS_CLMB_MAX>` parameter, combined with your current ground speed.
 
+Terrain Data Issue - Old Terrain Data
+=====================================
+In early 2026 an issue was identified with terrain data available from terrain.ardupilot.org.
+The issue was resolved on 24th February 2026. From ArduPilot 4.7, ArduPilot will raise a pre-arm 
+error if it finds older data on the SD Card, or it's served from a ground control station, perhaps 
+from an older cache. It might be risky to fly with this old data, but the risks do depend on where 
+you are flying, so you might chose to accept the risk. IF you do set :ref:`TERRAIN_OPTIONS<TERRAIN_OPTIONS>` bit 2
+which will override the warning.
+
+If you are running a 4.6.x release or earlier you won’t get the above error message, but that doesn’t mean you are safe. 
+You should:
+
+- Delete all the DAT files in the APM/TERRAIN directory on your microSD card then reboot the autopilot
+- Delete the SRTM data from your Ground Station. If using Mission Planner delete the contents of C:\\ProgramData\\Mission Planner\\srtm
+- Then either download new data from terrain.ardupilot.org or let the normal automatic terrain download system download new terrain data via your GCS.
+
+If you are running the new 4.7.x release (or you are running the latest master branch) then you should get the above warning if you have old terrain data, but if you are uncertain then the safe thing to do is delete the old DAT files from APM/TERRAIN and download again.
+
+In 4.7.x you can set :ref:`TERRAIN_OPTIONS<TERRAIN_OPTIONS>` bit 2 to override the check and allow you to use old terrain data. 
+If you are confident you are not impacted by the bugs (most locations in the world are unaffected) 
+then this new :ref:`TERRAIN_OPTIONS<TERRAIN_OPTIONS>` bit allows you to fly without the error messages.  We don’t recommend this, but for some vehicles where replacing the terrain data files is difficult this is 
+provided as an option. For example, if you have created your own DAT files from geoTIFF or similar then this would be a way to avoid having to regenerate them. Remember to unset this option bit when you move to newer terrain data.
+
+Recommended Settings
+====================
+
+-  set :ref:`TERRAIN_ENABLE<TERRAIN_ENABLE>` to 1 and :ref:`TERRAIN_FOLLOW<TERRAIN_FOLLOW>` to 1
+-  set :ref:`TERRAIN_SPACING<TERRAIN_SPACING>` to 30 meters for more precise AGL calculations
+-  set :ref:`TERRAIN_CACHE_SZ<TERRAIN_CACHE_SZ>` to 60 to load more tiles into memory (RAM)
+-  set :ref:`TERRAIN_LOOKAHD<TERRAIN_LOOKAHD>` to 1000 meters unless you have a reason to need more
+
+To avoid high bandwidth consumption due to terrain tiles being sent to the aircraft over your telemetry
+link, especially if you often fly in different locations, it's also highly recommended to download the 
+terrain around your planned flight area in the /APM/TERRAIN folder on the SD Card on the AutoPilot.
 
 [copywiki destination="plane"]