#Automation: recipes, triggers and the autopilot

GeoSpaX's power is in automation (VISION.md). This document specifies the recipe format, the triggers that start recipes, the autopilot (AutoMap) that fills in parameters and explains them, and the engine that runs recipes on desktop, web and the command line.

Status (October 2026): automation engine v0 is built, with rasters, remote sensing, providers and sensors. It includes:

• recipes (YAML) and a dependency-ordered runner;
• 27 built-in steps (32 names with aliases), among them device and sensor import, live sensor snapshots and summaries, AutoMap styling, automatic layout and PNG/SVG/PDF export, an HTML report with an auto-written methods section, SQL, buffer, hexbin, cross-validated IDW, terrain, Sentinel-2 indices, GRASS, SAGA, and R and Python steps;
• device, folder, schedule, after, stac, webhook and sensor triggers (threshold and geofence, from HTTP, MQTT or GNSS);
• a command line, an HTTP API and an Automate panel;
• thirteen gallery recipes, including terrain (Copernicus DEM), latest cloud-free NDVI (Sentinel-2), GRASS landforms, SAGA wetness, a sensor log to map and a live air-quality alert.

Measurements are in bench/RESULTS.md §11–13. Code: crates/engine/src/automation/, recipes: recipes/.

geospax run photos-to-map --input source=/media/$USER/PHONE   # the desktop binary (or geospax-server)
geospax check my-recipe.yaml                                   # validate + show the plan
geospax watch --watch ~/Field/inbox                            # triggers on, no window

#1. Concepts

#2. Recipe format (v1, as implemented)

The gallery recipe that turns a plugged-in phone into a finished map (recipes/photos-to-map.yaml):

recipe: photos-to-map
version: 1
title: Photos and tracks → finished map
triggers:
  - device: { kinds: [phone, camera, folder], has: [photos] }
inputs:
  source: { type: device, default: auto, description: device id, mounted device or folder }
steps:
  - id: import
    use: devices.import
    with: { source: "${inputs.source}" }
  - id: style
    use: automap.style                    # picks symbology for each layer and records why
    with: { layers: "${import.layers}" }
  - id: map
    use: export.map                       # page layout + PNG/SVG
    needs: [style]
    with: { layers: "${import.layers}", title: "Field photos · ${import.device}", format: [png, svg] }
  - id: report
    use: export.report                    # map + numbers + methods + decisions + provenance
    needs: [map]
    with: { title: "Field report · ${import.device} · ${run.date}" }
outputs: [import, map, report]

Expressions:

• ${inputs.x}, ${step.key} and ${step.list.0};
• ${run.date}, ${run.time}, ${run.datetime}, ${run.id}, ${run.dir} and ${recipe};
• ${trigger.kind}, ${trigger.text}, ${trigger.device}, ${trigger.root}, ${trigger.path} and ${trigger.files};
• a fallback with ${inputs.title ?? Field map}.

A string that is exactly one ${…} keeps the referenced type, so layers: "${import.layers}" is a list. Otherwise the values are interpolated as text.

Order: steps run in declaration order, except that a step always runs after every step it references or needs. Cycles are rejected. A skipped step (when: false) records { skipped: true }.

Validation reports every problem at once, before anything runs (geospax check, POST /api/recipes/validate):

✗ broken.yaml has 4 problem(s):
  - these steps depend on each other in a circle: b, c
  - step 'd' refers to ${nowhere.x}, but there is no step or input called 'nowhere'
  - step 'a': unknown step 'export.mapp' (did you mean 'export.map'? `geospax steps` lists them all)
  - step 'b': 'vector.buffer' needs 'distance'

Planned control steps: for_each (files, features, dates, devices), parallel and ask (one question with a recommended answer, only when the autopilot's confidence is low).

#Step catalogue (built)

#Step catalogue (planned)

#3. Triggers

Auto switches. Triggers fire only for recipes whose Auto switch is on. The switches persist in <state>/automation.json. Turn them on with the UI switch, geospax-server --auto id,id|all, GEOSPAX_AUTO (desktop) or PUT /api/recipes/{id}/auto. geospax watch turns all of them on (or --only id,id).

One run per recipe at a time. A trigger that fires while its recipe is busy is queued. Requests with different inputs (two devices) run one after the other; identical requests merge.

#4. Autopilot (AutoMap): smart defaults that explain themselves

Every automatic choice comes with a one-line reason. The reason appears in the run log, the report's "Automatic decisions" table and the UI.

Layout rules (export.map):

• Page: landscape or portrait from the data's shape, or A4, A3 or Letter at 150 dpi. The extent fits all the mapped data with a margin and is at least 400 m across.
• Title and subtitle: automatic (device, what was found, date).
• Map elements:
  • a legend built from the styles, with class counts;
  • a scale bar with round numbers;
  • a north arrow;
  • a graticule with round steps;
  • point labels with collision avoidance (four candidate positions).
• Context layers: land, roads and rivers are added automatically when loaded.
• Large point layers: above 30,000 points, a density grid replaces individual points.
• Credits: sources and the recipe.

#5. Three ways to write a recipe, all lazy

1. Record. ✅ v0: "Save this map as a recipe" in the Automate panel turns the visible layers and their exact styles into a recipe (io.open → style.apply → export.map → export.report) that redraws and re-exports the map on demand, or on a trigger once you add one. Planned: recording the session log, where literal paths become inputs and repeated actions become for_each.

2. Pick from the gallery. ✅ Fifteen built recipes (recipes/):

   Recipe	Trigger	What you get	Time (RESULTS §11)
   photos-to-map	phone / camera / folder with photos	Styled map of photos (with camera direction), tracks and waypoints; PNG + SVG + report	0.17 s
   track-to-map	GPS unit with tracks	Map + KML (Google Earth) + GeoJSON + report	0.11 s
   drone-flight-report	drone card	Flight path, photo positions, dissolved ground coverage (ha) in UTM, report	0.11 s
   points-to-hexbins	by hand	Auto-sized hexagon density map from any point layer (1M points)	0.65 s
   points-to-hotspots	by hand (add a folder trigger)	Hot and cold spots of incidents (or of a value) at 90/95/99 % confidence, every setting chosen from the data; map (PNG/SVG/PDF) + report with Moran's I and the distance search (§6e)	0.30 s (RESULTS §20)
   interpolate-samples	by hand (add a folder trigger)	Kriging or IDW, whichever cross-validates better: surface map, uncertainty map (kriging standard error), variogram chart, RMSE (§6e)	1.0 s (RESULTS §20)
   python-spatial-stats	by hand	Mean centre, standard distance, deviational ellipse, Clark–Evans nearest-neighbour index (Python)	0.19 s
   r-kriging	by hand	Ordinary kriging with an auto-fitted variogram and cross-validation (R gstat)	4.2 s
   terrain-report	by hand	Copernicus 30 m DEM for the area → shaded relief + contours map (PNG/SVG/PDF), slope-class map with hectares, elevation and slope sampled at your points	6.1 s
   lidar-to-terrain	a drive or drop folder with LAS/LAZ (has: [point-clouds])	Bare-earth terrain map with relief shading, contours and buildings; canopy map with tree tops and buildings over surface relief (PNG/SVG/PDF); canopy-height classes with hectares; report with points, density, canopy cover, tree and building counts	2.3 s for 0.7 M points, 12 s for 10.7 M (RESULTS §18)
   latest-ndvi	stac (new pass)	Newest Sentinel-2 pass that is clear over the area → NDVI map, vegetation classes with hectares, true-colour map, NDVI at your points	5.5 s
   landforms-grass	by hand	GRASS r.geomorphon: ten landforms over relief shading, GRASS colours, share of each	5.0 s
   wetness-saga	by hand	SAGA Wetness Index (ta_hydrology 15) over relief shading; wetness sampled at your points	6.2 s
   sensor-log-to-map	sensor logger plugged in	Every geotagged reading coloured by the main measurement (WHO classes for PM), the logger's track, statistics per measurement, GeoJSON, report	0.12 s (RESULTS §13)
   air-quality-alert	sensor (PM2.5 > 35)	Snapshot of every live sensor's last two hours → alert map + report naming the sensor and value	0.26 s from the reading (RESULTS §13)

   Times include reading the DEM and imagery over HTTP (about 2.8 s and 1.8 s here). Planned gallery entries: field-week-report, what-changed, flood-extent and drone-to-ortho.

3. Ask (optional AI). Planned. A local model (llama.cpp/Ollama) or your own provider turns a request into recipe YAML, constrained by the step catalogue (GET /api/steps) and checked by the validator. GeoSpaX shows the plan first; recipes that write outside the state folder, use the network or run code need explicit approval. An MCP server would expose recipes and steps to external agents.

#6. R and Python steps (built)

  - id: krige
    use: r
    with:
      inputs: { samples: "${samples.layer}" }   # arrives as an sf object (path if sf is missing)
      params: { field: "${inputs.field}" }      # becomes the R list `params`
      packages: [sf, gstat]                     # checked before running, with install hints
      code: |
        library(sf); library(gstat)
        pts <- st_transform(samples, 32755)
        model <- fit.variogram(variogram(ph ~ 1, pts), vgm(c("Sph", "Exp", "Gau")))
        ...
        result(model = as.character(model$model[2]), cv_rmse = rmse)   # numbers -> run log + report
        list(prediction = st_transform(grid, 4326))                    # returned sf objects -> layers

How a code step runs:

• Isolation:
  • each step runs in its own process with a scrubbed environment (PATH, HOME, locale, R/Python library paths and PROJ/GDAL data only);
  • its working directory is steps/<id>/ inside the run folder;
  • it has a timeout (timeout_s, default 600) and stops on the run's cancel button.
• Data exchange goes through files: GeoJSON in, GeoJSON or GeoPackage out. A crashing script cannot take the app down, and GPL code stays out of process.
• Results: returned layers become <recipe>.<name> and appear on the map. A non-zero exit fails the step with the last lines of stderr.

The R tab runs R steps from a console with templates for tmap, ggplot2, rayshader, terra, biomod2, MaxEnt, tidymodels, dbplyr and rgee, and R setup installs R and package kits (R.md).

Planned:

• Python environment management (uv/pixi);
• Arrow/GeoParquet and COG exchange;
• "Show me the code" (built-in steps exported as equivalent R or Python);
• webR and Pyodide for light steps in the web edition.

#6b. Rasters, remote sensing and providers (built)

Rasters are first-class. GeoTIFF, VRT, JPEG 2000, ERDAS IMAGINE (.img), ASCII grid and SRTM .hgt files in the data folders are catalogued at start; recipe outputs are added as they are made and restored after a restart. Each raster has statistics, a guessed kind (DEM, hillshade, slope, NDVI, classes, RGB…), an automatic style with a reason (§4) and a legend. A small sidecar (<file>.gsx.json) keeps what the step that made it knew: kind, title, class labels and colours, units and attribution.

Remote data without downloads. dem.fetch, embeddings.fetch, rs.search, rs.index and rs.fetch read only the area of interest: Copernicus DEM tiles and Sentinel-2 bands are cloud-optimised GeoTIFFs on AWS open data, so GDAL fetches byte ranges (/vsicurl/), and STAC searches go through GDAL's own HTTP client (proxy settings such as GDAL_HTTP_PROXY apply). For the 11 × 9 km test area, the DEM takes about 2.8 s; the cloud check plus two 10 m bands, about 1.8 s.

Providers. grass and saga steps run the installed GRASS (grass --tmp-project <first input> --exec) and SAGA (saga_cmd) headless. GeoSpaX imports the inputs, runs the script or tool, exports the outputs back as GeoTIFF or GeoPackage, and registers them like any other result. GRASS class labels and colours (r.category, r.colors.out) become the legend. Both binaries are looked up on PATH, in the usual install folders or via GEOSPAX_GRASS / GEOSPAX_SAGA; GET /api/providers reports what is available. Like code steps, they need ?approve=code when saved through the API. Whitebox, Orfeo ToolBox and SNAP providers are next.

#6c. LiDAR point clouds (built)

lidar.grid (and the lidar-to-terrain recipe around it) turns point clouds into the products surveyors and foresters make first, with no settings to choose.

Accuracy against a synthetic scene with known truth (scripts/data-sample-lidar.py: rolling ground with a hill, three buildings, 40 trees, birds and below-ground noise; scripts/test-lidar.py):

On the real Autzen Stadium survey (PDAL sample data, 10.7 million points, LAS 1.4 point format 7, Oregon Lambert feet) the whole recipe takes 12 s: 1 m cells, ground and water from the vendor classes, 55 buildings, 4,393 trees up to 49 m (RESULTS §18).

Limits: SMRF keeps buildings wider than about twice the window (warehouses: raise window:), and on steep forested slopes vendor ground classes are better; trees whose crowns merge into one dome count as one; full-waveform data, E57 and PLY are not read (convert with PDAL or CloudCompare).

#6d. 3D scenes (built)

scene.3d makes the 3D view a GIS analyst would otherwise build by hand in ArcGIS Pro's scene view or QGIS's 3D map view. It runs inside lidar-to-terrain and terrain-report, and any recipe can add it after a DEM.

- id: scene
  use: scene.3d
  with: { dem: dem, overlay: ["${contours.layer}", "${area.layer}"], title: Terrain in 3D }

Measured on the Autzen survey (10.7 million points): the scene adds 0.9 s to the recipe and holds 55 buildings, 4,391 trees and 250,000 true-colour points in 327,000 triangles. The Khronos glTF-Validator reports no errors or warnings for any test scene (RESULTS §19).

Limits: buildings are flat-roofed blocks (no roof shapes yet); trees are stylised, not species models; the model is one level of detail, so very large areas are coarser (raise grid: up to 2048); I3S and 3D Tiles are not written yet (glTF is the payload of both, so this is the next step).

#6e. Spatial statistics (built)

Two native steps cover what analysts most often open R, Python or ArcGIS's Spatial Statistics toolbox for. Every setting is chosen from the data and explained in the report. They run on every OS without R or Python, and scripts/test-stats.py checks them against R's spdep and gstat (RESULTS §20).

stats.hotspots: where do things cluster more than chance would explain?

interpolate.auto: the best surface the samples support

- id: hot
  use: stats.hotspots
  with: { layer: incidents.geojson, name: hotspots }   # cell, band and FDR chosen from the data
- id: surface
  use: interpolate.auto
  with: { layer: "${samples.layer}", field: ph }       # ${surface.raster}, ${surface.se}, ${surface.method}

Checked on every release: every planted incident cluster is a 99 % hot spot and no hot spot lies elsewhere; Gi*, Moran's I and the whole distance search equal spdep; the empirical variogram equals gstat's, the fitted models fit at least as well as fit.variogram, and predictions, standard errors and cross-validation equal krige and krige.cv for both global and 32-neighbour kriging. Against the known surfaces, kriging's error is about half of IDW's.

Limits: fixed distance bands only (no k-nearest or contiguity weights yet); no study-area boundary for zero-count cells yet; ordinary kriging only (no trend model, anisotropy or block kriging). For those, the r step with spdep or gstat is one line away, and the r-kriging recipe shows how.

#7. Execution engine (built)

• Runs each get their own thread, not a pool worker, so a step can wait for heavy work (overview builds) without starving the shared pools. They are also listed in the job registry (kind: recipe) with progress and cancel.

• Run folder <state>/runs/<run-id>/:

  • run.json (steps, status, timings, why lines, outputs, artifacts, trigger, inputs);
  • recipe.yaml (an exact copy);
  • the maps, the report and data exports;
  • steps/<id>/ for code steps (generated script, stdout, stderr, inputs, outputs).

  History survives restarts.

• Result layers:

  • Each one is written to <state>/outputs/<recipe>/<name>.gpkg with an atomic replace, registered as <recipe>.<name> and restored at startup.
  • A re-run replaces the layer in place, so the map updates itself.
  • Device imports keep the device hub's ids (<device>.photos, …).

• Provenance: the report lists the recipe id and its FNV-1a fingerprint, run id, trigger, inputs, GeoSpaX and GDAL versions and the generation time. The run folder holds the exact recipe copy.

• Failures:

  • A failing step stops the run; later steps are marked "not run" with the reason.
  • Panics inside a step are caught and reported as step errors.
  • Partial artifacts are kept.

• Planned:

  • a content-addressed step cache, hashing input fingerprints, step version and resolved parameters (the overview pyramid already works this way);
  • parallel branches;
  • providers (GRASS, SAGA, Whitebox, OTB, SNAP, ODM, PDAL) chosen by a benchmark table.

#8. Safety and trust

#9. Interfaces (built)

#10. Status