Skip to contents

Add the Position Tracking Layer to a QGIS Project

Source: R/rfp_tracking.R
rfp_qgs_tracking_add.Rd

Writes the <maplayer> and its layer-tree entry, so a project is deployable without a QGIS Desktop round trip. Pair with rfp_qgs_tracking_set(), which needs this layer's id.

Usage

rfp_qgs_tracking_add(
  qgs,
  gpkg = NULL,
  name = .rfp_tracking_layer_name,
  group = .rfp_tracking_group,
  themes = "all",
  backup = TRUE
)

Arguments

qgs

Character. Path to the .qgs.

gpkg

Character. Path to tracking_layer.gpkg. NULL (default) looks for it beside the project.

name

Character. Display name. Default "Position track" - not "Tracking", which a real project already uses for rfp_tracking, the unrelated data-provenance table from #13.

group

Character. Layer-tree group, or NULL for the tree root.

themes

Themes to join. Default "all", matching rfp_qgs_raster_add(). #171's rule that theme membership is curation rather than a side effect of an insert governs a background layer, where joining every theme is an opinion about what a crew should see. It does not govern this one: applying a theme hides any layer the preset omits, so a tracking layer in no theme is invisible the moment a crew switches theme - the second half of #196, and the same reasoning already written into .qgs_theme_join().

backup

Logical. Write <qgs>.bak first. Default TRUE.

Value

Invisibly, the new layer's id.

What the plugin writes, and what it does not

Measured on a plugin-authored layer: 16 children and no style block at all - it ends at defaults, constraints, constraintExpressions, with no flags, no renderer-v2, no symbology. QGIS draws it with a default symbol. So this writes a bare layer too; giving it a style would make rfp's node the odd one out rather than the tidy one.

The four <defaults> are what make a track self-describing: @tracking_start_time and @tracking_end_time are supplied by the app, round($length, 2) computes distance, and @mergin_username stamps who walked it.

@mergin_username is a plugin-version dependency

The installed plugin writes @mergin_username; upstream master writes @mm_username. Picking wrong leaves tracked_by silently empty - no error, no warning, just a blank column discovered after a field season. rfp writes the spelling confirmed working (populated on all five of hornby_2026's recorded sessions), and test-rfp_tracking.R compares it against the installed plugin rather than trusting this paragraph.

See also

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