Skip to contents

Create a Mergin Maps Position Tracking Layer

Source: R/rfp_tracking.R
rfp_tracking_layer_create.Rd

Writes the GeoPackage Mergin Maps appends a track to when a field crew stops recording. The schema is fixed by the app, not a choice: the QGIS plugin creates exactly this and the mobile app writes to exactly this.

Usage

rfp_tracking_layer_create(path, overwrite = FALSE)

Arguments

path

Character. Where to write the GeoPackage. Convention is tracking_layer.gpkg at the project root - not under background_layers/, because the app looks for it beside the .qgs.

overwrite

Logical. Replace an existing file. Default FALSE, because a tracking layer that already exists holds field data.

Value

Invisibly, the path.

Details

file / tabletracking_layer.gpkg / tracking_layer, at the project root
geometryLineStringZM, EPSG:4326
fieldstracking_start_time, tracking_end_time, total_distance, tracked_by

Per vertex you get X, Y, Z and M and nothing else. Z is ellipsoidal altitude; M is the UTC timestamp in Unix epoch seconds. There is no accuracy, speed, bearing or satellite count. A track is therefore a line whose nodes each carry a time - recover it with datetime_from_epoch(m * 1000).

One feature per session, appended once when the user taps Stop. There is no periodic flush, so a crash before Stop loses the whole session (mobile#3555).

Two deliberate differences from what the plugin writes

Both were measured against a layer the plugin made (hornby_2026/tracking_layer.gpkg, 5 recorded sessions), and both are improvements rather than drift:

  • The gpkg_contents bounding box is left NULL, where the plugin writes 0,0,1,1. That is a placeholder it never updates - hornby still carries it after 5 real tracks - and it is a wrong claim about where the layer is, in the one place a reader consults for an extent without scanning. Zoom-to-layer honours it and lands in the Gulf of Guinea. Same rule as a form shipping with no seeded extent (#49).

  • The geom column's declared type is GEOMETRY, where the plugin declares LINESTRING. gpkg_geometry_columns is the authority and carries LINESTRING with z = 1, m = 1 either way; 9 of 13 rfp-written layers in a real project declare GEOMETRY and all render correctly. Changing it would mean rebuilding the table, which destroys the rtree spatial index and its 18 triggers.

See also

Other tracking: rfp_qgs_tracking_add(), rfp_qgs_tracking_fields_add(), rfp_qgs_tracking_get(), rfp_qgs_tracking_set(), rfp_tracking_fields_add()

Examples

p <- file.path(tempdir(), "tracking_layer.gpkg")
rfp_tracking_layer_create(p, overwrite = TRUE)
sf::st_layers(p)
#> Driver: GPKG 
#> Available layers:
#>       layer_name           geometry_type features fields crs_name
#> 1 tracking_layer 3D Measured Line String        0      4   WGS 84