GNSS bundle - Elevations, transformations, providers

scripts/wordlist.txt

@@ -29,7 +29,9 @@ DOP
 ECW
 ECR
 EE
+EGM
 Emlid
+EOS
 EPSG
 Esri
 EUIPO
@@ -154,7 +156,7 @@ Skoda
 SLYR
 SSL
 Survey123
-synchronise
+TCP
 TLS
 Transifex
 Trialing

src/.vitepress/sidebar/en.js

@@ -62,6 +62,7 @@ export default {
         { text: 'How to Avoid Polygons Overlap', link: '/gis/avoid-overlap/' },
         { text: 'Publishing Projects via OGC API (WMS/WMTS, WFS)', link: '/gis/ogc-api/' },
         { text: 'Custom Projections', link: '/gis/proj/' },
+        { text: 'Elevations', link: '/gis/elevations/' },
         { text: 'Supported Formats', link: '/gis/supported_formats/' }
       ] },
     {

src/field/external_gps/index.md

@@ -74,7 +74,7 @@ Connecting external GPS receivers using a network provider is available on both
 2. Here, you can see the currently used receiver. Tap on the **Connect new receiver** button.
    ![Select GPS receiver](./mobile-app-connect-gps-receiver.webp "Select GPS receiver")
 
-3. On Android, select the **Network (<NoSpellcheck id="TCP, UDP" />)** connection type. On iOS, this is the only direct connection type.
+3. On Android, select the **Network TCP, (<NoSpellcheck id="UDP" />)** connection type. On iOS, this is the only direct connection type.
 
    Fill in the network connection details (IP Address and Port). You can also use a receiver nickname.   
 
@@ -133,7 +133,7 @@ External GPS functionality depends on the manufacturer and on the specific model
 | Carlson | <NoSpellcheck id="xML2" /> <sup><a href="#link-1">1</a></sup>| yes (mock location) | unknown |
 | Emlid | Reach RX models<sup><a href="#link-2">2</a></sup> | yes | yes (mock location) |
 | Emlid | Reach RS models<sup><a href="#link-3">3</a></sup> | yes | yes |
-| EOS | Skadi models<sup><a href="#link-11">11</a></sup> | yes | yes |
+| EOS | <NoSpellcheck id="Skadi" /> models<sup><a href="#link-11">11</a></sup> | yes | yes |
 | EOS | Arrow models<sup><a href="#link-11">11</a></sup> | yes | yes |
 | Garmin | GLO 2 | yes | yes (mock location) |
 | Geomax | <NoSpellcheck id="Zenith06" /><sup><a href="#link-8">8</a></sup>  | yes (mock location) | unknown |
@@ -162,6 +162,6 @@ External GPS functionality depends on the manufacturer and on the specific model
 - <a id="link-8">8</a>: **Geomax Zenith06, Zenith60** - through *Geomax X-PAD* app on Android, using a GNSS Mock licence from Geomax and the *Mock GNSS* option in the app.
 - <a id="link-9">9</a>: **<NoSpellcheck id="ArduSimple kits" />** - through [*GNSS Master* app](https://play.google.com/store/apps/details?id=com.gnssmaster&hl=en&gl=US&pli=1) which also acts as a NTRIP client and sends the corrections to the device. Detailed steps can be found in the tutorial [How to connect <NoSpellcheck id="ArduSimple" /> kit to Mergin Maps for centimetre-accurate mapping](https://www.ardusimple.com/how-to-connect-ardusimple-kit-to-mergin-maps-for-centimeter-accuracte-mapping/).
 - <a id="link-10">10</a>: **Geode GNS3** - through the *Geode Connect* app on [Android](https://play.google.com/store/apps/details?id=com.juniper.geode2a&hl=en_NZ&gl=US) or [iOS](https://apps.apple.com/us/app/geode-connect/id1446098695), which also acts as an NTRIP client and sends corrections to the device.
-- <a id="link-11">11</a>: **EOS receivers** - direct connection via network to [EOS Tools Pro](https://eos-gnss.com/products/software/eos-tools-pro) app that configures the receivers and sets up NTRIP corrections. Refer to EOS documentation to see how to set up TCP (network) connection.
+- <a id="link-11">11</a>: **<NoSpellcheck id="EOS" /> receivers** - direct connection via network to [<NoSpellcheck id="EOS" /> Tools Pro](https://eos-gnss.com/products/software/eos-tools-pro) app that configures the receivers and sets up NTRIP corrections. Refer to <NoSpellcheck id="EOS" /> documentation to see how to set up TCP (network) connection.
 
 **Did you use a GPS that is not in this list?** <GitHubRepo id="MerginMaps/docs/issues/124" desc="Share your experiences with us!" />

src/field/mobile-app-ui/index.md

@@ -104,19 +104,16 @@ Tapping the GPS accuracy button opens the GPS info panel:
 - **Source**
    - *Internal* or *Internal (fused)* for the GPS of the mobile device
    - the name of the receiver for [external GPS](../external_gps/) receiver connected via Bluetooth
+   - *External (Mock)* for [external GPS](../external_gps/) receiver if mock location is detected
 - **Longitude, Latitude**: current position
 - **X, Y**: current position in the project's coordinate reference system
 - **Horizontal** and **Vertical accuracy** of the GPS position
-- **Altitude**: orthometric height
-   - for *Internal* or *Internal (fused)* GPS, it is calculated from the ellipsoidal height using the <NoSpellcheck id="EGM96" /> geoid model by adding the geoid height (undulation) 
-   - for *[external GPS](../external_gps/)*, it is the orthometric height as reported by the external GPS
+- **Altitude**: orthometric height, see [Elevations](../../gis/elevations/) for more details
 - **Satellites (in use/view)**: number of satellites
 - **Speed**
 - **Last fix**: time of the last received GPS position
 - **GPS antenna height** that can be set in [GPS settings](#gps-settings)
-- **Geoid separation**: geoid height (undulation)
-   - calculated from the <NoSpellcheck id="EGM96" /> geoid model for *Internal* or *Internal (fused)* GPS
-   - as reported by the *[external GPS](../external_gps/)*
+- **Geoid separation**: geoid height (undulation), see [Elevations](../../gis/elevations/) for more details
 
 ### Sync
 The **Sync** button can be used to synchronise changes during the field survey. 

src/gis/elevations/index.md

@@ -0,0 +1,151 @@
+---
+description: See how Mergin Maps handles elevations, vertical transformations and data reported by GPS providers.
+outline: [2,3]
+---
+
+# Elevations
+
+[[toc]]
+
+When collecting data in the field, <MobileAppName /> provides information about your position and also elevation. By default, GPS receivers provide an *ellipsoidal height* that is related to the reference ellipsoid. However, for most applications, a *physical height* (also known as height above the sea level) is more appropriate.
+
+An *orthometric* height is a physical height referred to a *geoid*, a special surface that resembles the mean sea level. The difference between ellipsoidal and orthometric height is called the *geoid separation* (also known as geoid height or undulation) and it can be applied to transform between these heights.
+
+When transforming elevations from ellipsoidal to orthometric, <MainPlatformNameLink /> uses the EGM96 geoid model by default. However, it is also possible to use another geoid model as described in the [Using custom vertical reference system](#custom-vertical-reference-system) section. This may be especially useful when conducting more precise surveys or when a specific vertical reference system is required. 
+
+:::warning Learn more
+Height systems and elevations are complex topics. If you want to get more insight, we recommend going through some explanatory resources, such as [Height Systems](https://geodesy.science/item/height-systems/) by the International Association of Geodesy.
+:::
+
+::: tip Terminology
+The terms *geoid*, *geoid separation* and *orthometric heights* are used in the <MobileAppNameShort /> and this documentation for simplicity. 
+
+The same functionalities apply also if the used vertical reference system is defined by a *quasi-geoid*, another type of reference surface. Physical heights referred to a quasi-geoid are called *normal* heights.
+:::
+
+Information about the altitude and geoid separation (if available) are displayed in the [GPS info panel](../../field/mobile-app-ui/#current-position-and-gps-info).
+
+![GPS info panel](../../field/mobile-app-ui/mobile-app-gps-info.webp "GPS info panel")
+
+There are some differences in the functionality and available details depending on the GPS provider, the OS of the mobile device and the connection setup, namely the type of elevation provided, available [position variables](../../layer/variables/#position-variables) and whether it is possible to use [custom vertical reference system](#custom-vertical-reference-system).
+
+## Internal provider (no external device)
+
+### Android
+On Android, the [internal (fused)](../../field/mobile-app-ui/#gps-settings) GPS provider is used by default. It reports **orthometric heights** transformed from ellipsoidal heights by <MainPlatformName /> using the EGM96 geoid model and displays them in the [GPS info panel](../../field/mobile-app-ui/#current-position-and-gps-info).
+
+**Position variables**: :white_check_mark: *Ellipsoidal elevation*, *orthometric elevation*, *geoid separation* values are available and can be stored using [position variables](../../layer/variables/#position-variables).
+
+**Custom vertical CRS**: :white_check_mark: It is possible to use the <QGISPluginNameShort /> to transform the elevation to a different [vertical reference system](#custom-vertical-reference-system).
+
+### iOS
+On iOS, the GPS provider can provide orthometric and ellipsoidal heights.
+
+#### Ellipsoidal height not available
+If ellipsoidal height **is not** available, <MainPlatformName /> does not transform the elevation in any way. iOS reports *above the sea level* heights by default, so this information is displayed in the [GPS info panel](../../field/mobile-app-ui/#current-position-and-gps-info) in the <MobileAppNameShort />. 
+
+**Position variables**: 
+- :white_check_mark: *orthometric elevation* is available and can be stored using [position variables](../../layer/variables/#position-variables)
+- :no_entry_sign: *ellipsoidal elevation* and *geoid separation* values are **not** available
+
+**Custom vertical CRS**: :no_entry_sign: It is not possible to transform elevations to a different vertical reference system.
+
+#### Ellipsoidal height available
+If iOS provides also the ellipsoidal heights, <MainPlatformName /> transforms them to **orthometric elevations using the EGM96 geoid model** by default and displays them in the [GPS info panel](../../field/mobile-app-ui/#current-position-and-gps-info).
+
+**Position variables**: :white_check_mark: *ellipsoidal elevation*, *orthometric elevation*, *geoid separation* values are available and can be stored using [position variables](../../layer/variables/#position-variables).
+
+**Custom vertical CRS**: :white_check_mark: It is possible to use the <QGISPluginNameShort /> to transform the elevation to a different [vertical reference system](#custom-vertical-reference-system).
+
+
+## External provider - Bluetooth
+<Badge text="Android only" type="tip"/>
+On Android, external GPS can be connected [using Bluetooth](../../field/external_gps/#bluetooth-connection-android-only). If possible, we recommend using this option.
+
+If there is no [user-defined transformation](#custom-vertical-reference-system), the <MobileAppNameShort /> uses data reported by the GPS provider as-is, including the ellipsoidal height and geoid separation. <MainPlatformName /> does not receive information about the geoid model used; this information should be supplied by the GPS provider.
+
+**Position variables**: :white_check_mark: *ellipsoidal elevation*, *orthometric elevation*, *geoid separation* values are available and can be stored using [position variables](../../layer/variables/#position-variables).
+
+**Custom vertical CRS**: :white_check_mark: It is possible to use the <QGISPluginNameShort /> to transform the elevation to a different [vertical reference system](#custom-vertical-reference-system). The defined geoid model is displayed in the <MobileAppNameShort />.
+
+## External provider - Network
+External GPS can be connected using network connection on both iOS and Android. We recommend using this option.
+
+The functionality is the same as described above in [External provider - Bluetooth ](#external-provider-bluetooth).
+
+## External provider - Mock location
+
+Mock location should be only used if you are unable to connect the external GPS directly in the <MobileAppNameShort />. Because of system limitations, both Android and iOS send only a subset of available data. Some [position variables](../../layer/variables/#position-variables) may not be available.
+
+### Android
+If there is no [user-defined transformation](#custom-vertical-reference-system) (custom geoid), the <MobileAppNameShort /> uses data reported by the GPS provider as-is.
+
+**Position variables**: 
+- :white_check_mark: *orthometric elevation* is available and can be stored using [position variables](../../layer/variables/#position-variables)
+- :no_entry_sign: *ellipsoidal elevation* and *geoid separation* values are **not** available
+
+**Custom vertical CRS**: 
+- :warning: It is possible to use the <QGISPluginNameShort /> to transform the elevation to a different [vertical reference system](#custom-vertical-reference-system). However, it is necessary to **set up the mock app to report ellipsoidal heights**, otherwise the geoid separation would be applied twice leading to incorrect elevation values. 
+- :white_check_mark: If custom vertical reference system is used, the *orthometric elevation*, *ellipsoidal elevation* and *geoid separation* variables are available and can be stored using [position variables](../../layer/variables/#position-variables).
+
+### iOS
+If there is no [user-defined transformation](#custom-vertical-reference-system) (custom geoid), the <MobileAppNameShort /> uses data reported by the GPS provider as-is.
+
+**Position variables**:  
+- :white_check_mark: *orthometric elevation* is available and can be stored using [position variables](../../layer/variables/#position-variables)
+- :no_entry_sign: *ellipsoidal elevation* and *geoid separation* values are **not** available
+
+**Custom vertical CRS**: 
+- :warning: It is possible to use the <QGISPluginNameShort /> to transform the elevation to a different [vertical reference system](#custom-vertical-reference-system). However, it is necessary to **set up the mock app to report ellipsoidal heights**, otherwise the geoid separation would be applied twice leading to incorrect elevation values. 
+- :white_check_mark: If custom vertical reference system is used, the *orthometric elevation*, *ellipsoidal elevation* and *geoid separation* variables are available and can be stored using [position variables](../../layer/variables/#position-variables).
+
+## Custom vertical reference system
+
+Vertical reference system can be specified in [<MainPlatformName /> Project Properties](../../manage/plugin/#mergin-maps-project-properties) in QGIS. The grid shift file will be packaged with the project based on the selected vertical reference system.
+
+In the <MobileAppNameShort />, the info about the custom vertical system is displayed in the [GPS info panel](../../field/mobile-app-ui/#current-position-and-gps-info).
+
+1. Open your <MainPlatformName /> project and navigate to the <MainPlatformName />  tab in **Project Properties**
+
+2. Check the *Report height in a specific vertical CRS* option :heavy_check_mark:
+   ![Mergin Maps QGIS plugin vertical CRS](./plugin-vertical-crs.webp "Mergin Maps QGIS plugin vertical CRS")
+
+3. Select a vertical CRS from the list or use the **Select CRS** button to choose from predefined CRS.
+
+   Use the filter to narrow the search using a keyword or the EPSG code. 
+
+   Select a CRS and click **OK**.
+   ![Select target vertical CRS in QGIS](./plugin-target-vertical-crs.webp "Select target vertical CRS in QGIS")
+
+5. **Apply** the changes in **Project Properties** and synchronise your changes.
+   ![Mergin Maps QGIS plugin defined vertical CRS](./plugin-set-vertical-crs.webp "Mergin Maps QGIS plugin defined vertical CRS")
+
+When recording and displaying heights in the <MobileAppNameShort />, this vertical system will be used instead of the default EGM96 model.
+
+::: tip Transformations
+When transforming elevations to another reference system, <MainPlatformName /> expects WGS 84 (EPSG: 4979) as the source CRS. 
+
+To transform elevations to another CRS, make sure that the correct datum transformation is defined in the **Transformations** tab in **Project Properties** where:
+- **Source CRS**: EPSG: 4979 (WGS 84)
+- **Destination CRS**: the reference system of your choice
+
+![QGIS Project Properties Transformations](./qgis-project-properties-transformations.webp "QGIS Project Properties Transformations")
+
+:::
+### Multiple datum transformation available
+For some vertical CRS, there may be multiple datum transformations available. If this is the case, you will get a warning when selecting the CRS.
+
+![Mergin Maps QGIS plugin datum transformation warning](./plugin-transformation-warning.webp "Mergin Maps QGIS plugin datum transformation warning")
+
+Make sure to define the preferred datum transformation in the **Transformations** tab in **Project Properties**.
+
+### Downloading grid shift files
+Some specific vertical CRS transformations may not be included in QGIS by default (see [custom projections in QGIS](../proj/#custom-projections-in-qgis)). In this the case, the <QGISPluginNameShort /> will display a warning that it needs to download the geoid grid file.
+
+Use the **click here** link to download the grid.
+
+![Mergin Maps QGIS plugin geoid grid download](./plugin-download-grid-shift.webp "Mergin Maps QGIS plugin geoid grid download")
+
+The geoid grid will be downloaded and packaged with your project.
+
+![Mergin Maps QGIS plugin geoid grid download](./plugin-grid-shift-downloaded.webp "Mergin Maps QGIS plugin geoid grid download")

src/index.md

@@ -68,6 +68,7 @@ The ecosystem consist of various components:
 - [How to Set Up Snapping for <MobileAppName />](./gis/snapping/)
 - [How to Avoid Polygons Overlap](./gis/snapping/)
 - [Custom Projections](./gis/proj/)
+- [Elevations](./gis/elevations/)
 - [Supported Formats](./gis/supported_formats/)
 
 ## Configure Forms

src/layer/variables/index.md

@@ -45,10 +45,10 @@ Following variables are supported:
 | `@position_coordinate` | Geometry | A point with the coordinates in WGS84 |
 | `@position_latitude` | Number (decimal) | Latitude |
 | `@position_longitude` | Number (decimal) | Longitude |
-| `@position_elevation` | Number (decimal) | Orthometric or normal height. *May not be available for some providers* |
+| `@position_elevation` | Number (decimal) | Orthometric or normal height. *May not be available for some providers, see [Elevations](../../gis/elevations/) for more detail.* |
 | `@position_altitude` | Number (decimal) | Has been replaced by `@position_elevation`. It is still supported and returns the same values as `@position_elevation`. |
-| `@position_elevation_ellipsoid`  | Number (decimal) | Ellipsoidal height. *May not be available for some providers*  |
-| `@position_geoid_separation`  | Number (decimal) | Geoid or quasi-geoid height (undulation). *May not be available for some providers*  |
+| `@position_elevation_ellipsoid`  | Number (decimal) | Ellipsoidal height. *May not be available for some providers, see [Elevations](../../gis/elevations/) for more detail.* |
+| `@position_geoid_separation`  | Number (decimal) | Geoid or quasi-geoid height (undulation). *May not be available for some providers, see [Elevations](../../gis/elevations/) for more detail.* |
 | `@position_direction`  | Number (integer) | The bearing measured in degrees clockwise from true north to the direction of travel |
 | `@position_ground_speed`  | Number (decimal) | The ground speed, in meters/sec |
 | `@position_vertical_speed`  | Number (decimal) | The vertical speed, in meters/sec |