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 idsplugin:<id>/<command>, which the ribbon, command search, scripts andrustgis-cliuse.versionandminRustgisVersionlook like1.2.3. RustGIS refuses a plugin that needs a newer RustGIS.permissions:edit,filesandnetwork(see Safety). Ask only for what you use.networklets 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(withchoices),boolandfile(see File parameters). - Limits: at most 64 commands and 64 tools, 32 parameters per tool, and 1 to 64
choicesperchoiceparameter. For more values than that, use atextparameter and check it in the plugin. i18ntranslates 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://ors3://. 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.layerpicks one layer of a zip, KML or GPX; the other parameters are those oflayer.addData(rustgis-cli commandslists 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
choicevalues, and the tab, group and menu labels. - RustGIS's interface languages are
de,es,fr,it,nl,pt,ru,tr,az,id,vi,zh,jaandko. A code with a region matches its language:zh-CNserveszh. - Messages the plugin builds while it runs: every request carries the interface language
(
req.lang), andreq.trlooks 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"] }
]
}
itemslists the buttons. An item is a command id,tool:<id>(which opens that tool in the Geoprocessing pane), or a dropdownmenuwhoseitemsare command ids ortool:<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
i18ntranslations 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) -> i32runs the host request atptr({"op": "...", "params": {...}}). It returns the length of the reply, which is{"ok": value}or{"error": "text"}, or-1when there is none.result(ptr: i32)copies that reply toptr. Allocate the lengthcallreturned first.log(ptr: i32, len: i32)logs a UTF-8 line.
The module exports:
memory.rustgis_alloc(len: i32) -> i32, which returns room forlenbytes. RustGIS writes the request there.rustgis_call(ptr: i32, len: i32) -> i64, which handles the request and returnsreply_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.