Skip to content

Write a plugin

The quickest start is the Rust WebAssembly template: use it on GitHub (Use this template), pick a starter (commands on the Plugins tab, a tab of its own, a panel, or geoprocessing tools), and its workflows build, test and release your .rgplugin. The official plugins are examples to read, starting with Hello RustGIS.

WebAssembly plugins are written in Rust with the rustgis-plugin SDK, and built for wasm32-unknown-unknown (rustup target add wasm32-unknown-unknown).

Writing a process plugin?

A process plugin is a program instead of a WebAssembly module. It isn't sandboxed and runs on the desktop and the command line only. Start from the Rust process template for a native executable with JSON-line transport, command and tool examples, packaging, and Linux, Windows and universal macOS release builds. Users need no Rust or Python installation to run its packaged executable. For a Python script with libraries such as numpy or GDAL, use the Python process template. See A process plugin for how either runtime is listed.

[lib]
crate-type = ["cdylib"]

[dependencies]
rustgis-plugin = { git = "https://github.com/opengeos/rustgis-plugins" }

[profile.release]
opt-level = "s"
lto = true
panic = "abort"
strip = true
use rustgis_plugin::{Kind, Request, ToolOutput, Value, geojson, host, json};

fn handle(req: Request) -> Result<Value, String> {
    match (req.kind, req.id.as_str()) {
        (Kind::Command, "layer-report") => {
            let n = host::layers()?.as_array().map_or(0, Vec::len);
            host::notify(&format!("{n} layers"));
            Ok(json!({"layers": n}))
        }
        (Kind::Tool, "bounding-boxes") => {
            let boxes: Vec<Value> = req.features("input")?.iter().filter_map(|f| {
                let b = geojson::bbox(&geojson::positions(&f["geometry"]))?;
                Some(geojson::feature(geojson::polygon(&[[b[0], b[1]], [b[2], b[1]], [b[2], b[3]], [b[0], b[3]]]), json!({})))
            }).collect();
            Ok(ToolOutput::new().layer("Boxes", geojson::collection(boxes)).into())
        }
        (_, other) => Err(format!("unknown '{other}'")),
    }
}

rustgis_plugin::export!(handle);
cargo build --release --target wasm32-unknown-unknown
# package plugin.json and the module (renamed plugin.wasm) as <id>-<version>.rgplugin:
mkdir -p pkg && cp plugin.json pkg/ && cp target/wasm32-unknown-unknown/release/my_plugin.wasm pkg/plugin.wasm
(cd pkg && zip -X ../my-plugin-0.1.0.rgplugin plugin.json plugin.wasm)

To try it while you work, load the folder instead of a package. In RustGIS, use Plugins › Plugin Manager › Settings › Add Plugin Folder…; on the command line, use rustgis-cli run --plugin ./pkg --sample --cmd 'plugin:my-plugin/hello'. The templates' scripts do this for you: python scripts/package.py builds, checks and packages the plugin into dist/, and python scripts/smoke.py runs it in RustGIS.

plugin.json

{
  "id": "hello-rustgis",
  "name": "Hello RustGIS",
  "version": "0.1.0",
  "description": "What it does, in a sentence or two.",
  "author": "You",
  "homepage": "https://github.com/you/your-plugin",
  "license": "MIT",
  "entry": "plugin.wasm",
  "abi": 1,
  "minRustgisVersion": "0.1.0",
  "permissions": ["edit"],
  "commands": [
    { "id": "layer-report", "label": "Layer\nReport", "help": "Shown on hover.", "icon": "stats", "params": "{}" }
  ],
  "tools": [
    {
      "id": "bounding-boxes", "name": "Bounding Boxes", "summary": "One line.", "toolbox": "Hello",
      "params": [
        { "name": "input", "label": "Input features", "kind": "vectorLayer", "required": true },
        { "name": "whole", "label": "One box for the whole layer", "kind": "bool", "default": false }
      ]
    }
  ],
  "i18n": { "de": { "Layer\nReport": "Layer-\nbericht" } }
}
  • id: lower-case letters, digits and hyphens. Commands and tools get ids plugin:<id>/<command>, which the ribbon, command search, scripts and rustgis-cli use.
  • version and minRustgisVersion look like 1.2.3. RustGIS refuses a plugin that needs a newer RustGIS.
  • permissions: edit, files and network (see Safety). Ask only for what you use. network lets the plugin have RustGIS fetch from addresses the plugin gives: web tile layers (map.addTiles), data files (layer.addUrl, see Data from the web) and the commands that query web services. An address can carry data, so it is a permission of its own.
  • commands[].icon: the name of one of RustGIS's own icons (stats, zoom_full, bookmark, buffer…), or a puzzle piece when it isn't one.
  • Tool parameter kinds: layer, vectorLayer, polygonLayer, pointLayer, field, numericField, number, text, choice (with choices), bool and file (see File parameters).
  • Limits: at most 64 commands and 64 tools, 32 parameters per tool, and 1 to 64 choices per choice parameter. For more values than that, use a text parameter and check it in the plugin.
  • i18n translates the plugin's own text into the interface language, by language code. See Translations.

A package is a zip archive named <id>-<version>.rgplugin. It holds plugin.json and the module at its root, or inside one top-level folder. Packages are at most 64 MB, and modules at most 48 MB.

File parameters

A tool can read a file the user picks, such as a NetCDF model run or a GeoTIFF, with a file parameter. It needs the files permission, and a RustGIS with file parameters (set minRustgisVersion to the first release that has them):

{ "name": "model", "label": "Model output", "kind": "file", "required": true, "extensions": ["nc", "nc4"] }

extensions filters the file picker: at most 16, each 1 to 16 letters or digits, without the dot. Leave it out for any file. RustGIS reads the file, up to 64 MB, and the tool gets it with req.take_file (which decodes it in place, without a second copy) or req.file:

// In `fn handle(mut req: Request)`:
let model = req.take_file("model")?; // model.name ("run.nc") and model.bytes

To read raster and vector formats from the bytes inside the module, use a pure-Rust library that builds for wasm32-unknown-unknown, such as terrio (terrio::memory::open_raster_bytes(model.bytes, &model.name)). A 64 MB file, its copy in the request and what you make of it all share the module's 512 MB of memory.

Data from the web

The module itself has no network access, but a command can ask RustGIS to download a file and add it as layers with layer.addUrl. It needs the network and edit permissions, and RustGIS 0.2.1 or later.

let url = format!("https://www.confini-amministrativi.it/api/v2/it/{date}/{level}.gpkg");
let out = host::run("layer.addUrl", json!({"url": url, "name": "Comuni", "zoom": true}))?;
  • The address is http://, https:// or s3://. The format comes from its extension, else from the contents: GeoJSON, CSV, GeoParquet, FlatGeobuf, GeoPackage, Shapefile or other data in a .zip, KML, KMZ, GPX, GeoTIFF, or a PMTiles archive. layer picks one layer of a zip, KML or GPX; the other parameters are those of layer.addData (rustgis-cli commands lists them).
  • Cloud-optimised GeoTIFFs, PMTiles, and FlatGeobuf or GeoParquet files with a spatial index are read in place, by range, rather than downloaded whole.
  • The answer names the layers added. In the web app, a file that is downloaded whole is downloaded off the frame: the answer is {"pending": true, "url": ...}, and the layer appears when the download lands. There the server must allow requests from other sites (CORS), as for Add Data › From URL.

layer.addData opens files, not addresses: use layer.addUrl for those. IDE Chile adds its layers with layer.addUrl.

Translations

RustGIS shows a plugin in the interface language when its plugin.json has an i18n table: for each language code, the plugin's English strings (exactly as written, \n included) and their translations. A string with no translation shows in English, so translations are optional.

  • They cover the name and description (in the Plugin Manager, before the plugin is installed too), command labels and help, tool names, summaries and toolboxes, parameter labels and choice values, and the tab, group and menu labels.
  • RustGIS's interface languages are de, es, fr, it, nl, pt, ru, tr, az, id, vi, zh, ja and ko. A code with a region matches its language: zh-CN serves zh.
  • Messages the plugin builds while it runs: every request carries the interface language (req.lang), and req.tr looks a message up in the same table and fills its {placeholders}:
const MANIFEST: &str = include_str!("../plugin.json");

host::notify(&req.tr(MANIFEST, "Zoomed to {name}.", &[("name", &layer)]));

Add "Zoomed to {name}." to the i18n tables like any other string. Layer and field names are data: leave them in English. - python scripts/i18n.py audit -v lists what each plugin is missing per language (CI runs it and fails on a translation that drops a {placeholder}). missing -o todo.json writes the gaps to fill in, and insert todo.json adds them to the manifests.

Hello RustGIS translates its messages this way.

A tab of its own

By default a plugin's commands and tools get a group on the Plugins tab. A plugin can have a ribbon tab of its own instead. The tab sits at the end of the tab strip, and Help › Ribbon can hide it like any other. Declare it in plugin.json:

"tab": {
  "label": "Explorer",
  "groups": [
    {
      "label": "Go To",
      "items": [
        { "menu": "Continent", "icon": "zoom_world", "help": "Go to a continent.", "items": ["go-africa", "go-europe"] },
        "random-place"
      ]
    },
    { "label": "Inspect", "items": ["layer-report", "tool:field-summary"] }
  ]
}
  • items lists the buttons. An item is a command id, tool:<id> (which opens that tool in the Geoprocessing pane), or a dropdown menu whose items are command ids or tool:<id>.
  • A tab has 1 to 8 groups, a group has 1 to 16 items, and a menu has 1 to 32 entries. Every entry must name one of the plugin's own commands or tools.
  • The label can't be the name of one of RustGIS's tabs (Map, Insert, Analysis, Plugins…). The i18n translations apply to the tab, group and menu labels too.

Map Explorer is an example.

A panel

A plugin can have a panel: a pane on the right of the map with texts, checkboxes, sliders, buttons, trees, dropdowns, date pickers and range sliders bound to its commands. Its button comes first in the plugin's group on the Plugins tab; on a tab of its own, put panel among a group's items. Panels need a RustGIS newer than 0.3.0, which ignores them (keep the commands usable from the ribbon too). Trees need one newer than 0.4.0, which refuses a manifest with a tree: set minRustgisVersion to the first release with them. Dropdowns (choice), dates and ranges need one newer than 0.6.0 in the same way.

"panel": {
  "title": "Year Picker",
  "icon": "history",
  "help": "Pick a year.",
  "state": "panel-state",
  "items": [
    { "kind": "text", "id": "summary", "label": "Summary" },
    { "kind": "checkbox", "id": "visible-only", "label": "Visible layers only", "command": "panel-state" },
    { "kind": "slider", "id": "year", "label": "Year", "min": 2000, "max": 2025, "steps": true, "command": "pick-year" },
    { "kind": "button", "command": "reset" },
    { "kind": "tree", "id": "catalogue", "label": "Catalogue", "search": true, "command": "show" },
    { "kind": "choice", "id": "theme", "label": "Theme", "options": [{ "id": "env", "label": "Environment" }], "default": "env" },
    { "kind": "date", "id": "start", "label": "Start date", "default": "2024-01-01" },
    { "kind": "range", "id": "years", "label": "Years", "min": 2000, "max": 2025, "default": [2010, 2020] }
  ]
}

A tree shows nodes the plugin gives (themes and their datasets, say), at most 5,000 of them and 8 levels deep. search: true adds a box above it that RustGIS filters on its own, as the Layers pane's: the plugin only hears of the node the user chooses. A dropdown (choice) lists options from plugin.json or the plugin (at most 1,000; a default must be one of the options plugin.json declares, so a dropdown filled at run time sets its value from the plugin); a date is a box for YYYY-MM-DD with a calendar; a range is a slider with two handles, its value [low, high].

RustGIS keeps the widgets' values, and every request of the plugin carries them. With the SDK, read them with req.panel_bool("visible-only"), req.panel_i64("year") and req.panel_str("catalogue") (a tree's chosen node id, a dropdown's chosen option id or a date, None when nothing is chosen), req.panel_range("years") (a range's (low, high); req.changed("year") says whether this call set it), and answer the panel's new state with a Panel:

use rustgis_plugin::{Node, Panel};

let panel = Panel::new().value("year", 2020).text("summary", "3 layers").enabled("reset", true);
Ok(panel.answer(json!({"year": 2020}))) // {"year": 2020, "panel": {...}}

A tree gets its nodes the same way; a node's id is what panel_str gives when it is chosen, so it must be unique in the tree:

let env = Node::new("env", "Environment").count(2).children([Node::new("parks", "Parks"), Node::new("rivers", "Rivers")]);
let panel = Panel::new().nodes("catalogue", [env, Node::new("roads", "Roads")]);

A dropdown gets its options with options (nodes whose children are ignored), and a range its value as [low, high]:

let panel = Panel::new().options("theme", [Node::new("env", "Environment"), Node::new("farm", "Farming")]).value("years", json!([2010, 2020]));

See A panel in RustGIS's documentation for every widget and field.

What a plugin can ask for

Inside a request, host::call(op, params) sends one of these to RustGIS:

Request Answer
host.info RustGIS's version, the ABI, the plugin's id and permissions
host.layers [{id, name, raster, visible, geometry, features, selected, active, fields: [{name, type}]}]
host.features {layer, selected?, limit?} the layer's features as GeoJSON; each feature has its row
host.view {center: [lon, lat], scale, projection}
host.notify {text, error?} shows a message in the status bar
host.addLayer {name, geojson} adds a layer (edit)
layer.addUrl {url, name?, layer?, zoom?, ...} downloads a data file and adds its layers (edit and network, see Data from the web)
map.addTiles {url, kind?, name?, attribution?, minZoom?, maxZoom?, tileSize?, tms?, subdomains?, opacity?, overlay?, replace?, id?} adds a web tile layer: raster tiles, vector tiles or a MapLibre style (edit and network); id marks it so the plugin can find it again in map.tiles
map.tiles the map's tile layers, top first: [{index, name, id, kind, url, visible, opacity, overlay, attribution, minZoom, maxZoom}]
map.removeTiles {index? \| name? \| id?}, map.setTiles {index? \| name?, visible?, opacity?, move?, rename?} removes (every one when none is named) and changes tile layers (edit)
any command id (layer.zoomTo, select.byAttributes, layer.symbology…) what the command returns, within the plugin's permissions

rustgis-cli commands lists every command id and its parameters.

Tools work differently. A tool receives its layer parameters' features as GeoJSON (only the selected features when a layer has a selection), and its file parameters' files. It returns new layers, standalone tables or a selection, plus messages for the Geoprocessing history. RustGIS adds the results as it does for built-in tools, with undo. Tools can log, but they make no host requests.

The ABI (version 1)

The SDK implements this; it is described here for other languages.

The module is wasm32 with no imports except these three, in module rustgis:

  • call(ptr: i32, len: i32) -> i32 runs the host request at ptr ({"op": "...", "params": {...}}). It returns the length of the reply, which is {"ok": value} or {"error": "text"}, or -1 when there is none.
  • result(ptr: i32) copies that reply to ptr. Allocate the length call returned first.
  • log(ptr: i32, len: i32) logs a UTF-8 line.

The module exports:

  • memory.
  • rustgis_alloc(len: i32) -> i32, which returns room for len bytes. RustGIS writes the request there.
  • rustgis_call(ptr: i32, len: i32) -> i64, which handles the request and returns reply_ptr << 32 | reply_len. The reply is {"ok": value} or {"error": "text"}.

Requests are {"abi": 1, "kind": "command" | "tool", "id": "...", "params": {...}, "layers": {...}}. Tools also get layers, which maps each layer's name to its FeatureCollection, and, when they have file parameters, files, which maps each one's name to {"name", "data"} with the file's contents in base64. A tool's ok value is {"layers": [{"name", "geojson"}], "tables": [...], "selection": {"layer", "rows"}, "messages": [...]}.

Each call gets a fresh instance, so a module keeps no state between calls and need not free memory. The fuel budget is about 2×10⁹ instructions for a command and 4×10¹⁰ for a tool.