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,48 @@ 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.
 
-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.
+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.
 
 .. 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:
 .. 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
 ===============
 
@@ -128,7 +147,17 @@ grid spacing for specialist applications.
 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.
+
+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.
+
+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.
 
@@ -163,7 +192,7 @@ 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
 -------
@@ -185,5 +214,16 @@ 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.
 
+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"]