User Guide¶

The ribbon¶

The last three form the contextual Feature Layer group, shown while a layer is selected in the Contents pane.

To give the map more room, collapse the ribbon to its tab row with the chevron at its right end, by double-clicking a tab, or with Ctrl+F1 (⌘F1 on macOS, where F1 may need the Fn key). Click a tab to peek at its commands while collapsed.

Data¶

Vector coordinates are WGS 84 longitude/latitude and are displayed in Web Mercator. Rasters keep their own coordinate system (any EPSG code, such as UTM zones or national grids) and are reprojected on the fly as they draw.

Projections¶

The flat map is drawn in Web Mercator by default. View › Projection switches it to another projection, and clicking the coordinate system in the status bar opens the Coordinate System dialog, which also takes any projected EPSG code (such as 3035, 32633 for UTM zone 33N or 2056 for Switzerland):

Layers are projected on the fly. Each projection has an area of use: polar projections show their hemisphere poleward of 30°, regional ones their region, transverse Mercator (UTM) zones 30° either side of their meridian, and data outside it isn't drawn. Switching keeps the centre and scale, and the choice is saved with the map (map.projection from the command line). A raster already in the map's coordinate system draws without being reprojected. Robinson, Equal Earth, Natural Earth, Winkel Tripel and Eckert IV are computed by RustGIS itself on a sphere, so EPSG:8857 (Equal Earth) works too.

Globe¶

View › Globe shows the map as a 3D globe seen from space instead of the flat Web Mercator map, and back again. Drag to turn the globe, scroll to zoom, and use Full Extent to see the whole Earth. Every layer draws on the globe: vectors are clipped at the horizon and follow great circles, rasters are draped onto the sphere, and labels, selection, identify, measuring and editing work as on the flat map. The scale stays the same when you switch, and the choice is saved with each map in the project (map.projection from the command line).

Rasters¶

Add a GeoTIFF or an ASCII grid with Add Data, by dropping it on the window, or in the web app by picking it. An ASCII grid takes its coordinate system from a .prj file next to it that names an EPSG code; otherwise, and always in the web app, which only sees the one file, it must be in longitude/latitude degrees. Exporting a raster opened from an overview writes that overview. GeoTIFFs may be grey, RGB(A), palette or multiband, of any pixel type, tiled or striped, and compressed with Deflate, LZW, PackBits or JPEG. A raster too large to hold in memory (more than 120 million samples) opens from its largest overview that fits.

Selecting a raster layer in Contents shows the Raster Layer tab group:

Clicking a raster with the Explore tool shows its pixel values. Projects remember a raster's file path and reopen it; rasters added in the browser are stored inside the project.

Symbology¶

• Single Symbol: one fill, outline and marker for every feature.
• Unique Values: one colour per distinct value of a field.
• Graduated Colors: classes of a numeric field by natural breaks (Jenks), equal interval or quantile.
• Proportional Symbols: point size grows with a numeric field.

Selection and queries¶

Select By Attributes and definition queries use SQL WHERE clauses:

pop_est > 100000000 AND continent = 'Asia'
name LIKE 'S%'
iso_a3 IN ('FRA', 'DEU', 'ITA')
gdp_md IS NULL
"OR" = 1          -- double quotes name a field, even a keyword

Geoprocessing tools¶

Tools honour the current selection: with features selected, only those are processed.

GeoLibre tools¶

The desktop app and the command line can also run the GeoLibre tool suite: over 1,000 tools from Whitebox and GeoLibre for terrain analysis (slope, aspect, hillshade, curvature), hydrology (fill depressions, flow direction and accumulation, watersheds), image processing, interpolation and vector work. They run on the map's layers and add their outputs as new layers.

The suite is an optional download, so RustGIS itself stays small: the GeoLibre runner, a single geolibre program (about 20 MB to download). In the Geoprocessing pane, click Install GeoLibre tools under GeoLibre tools: RustGIS downloads the latest runner for your platform from the geolibre-rust releases, checks it against its published SHA-256 checksum (which catches a corrupted download; the release itself is trusted as when you download it by hand) and installs it in its data folder (~/.local/share/rustgis/geolibre on Linux, ~/Library/Application Support/RustGIS/geolibre on macOS, %LOCALAPPDATA%\RustGIS\geolibre on Windows). From the command line, gp.installGeolibre does the same.

To install it yourself instead, download the archive for your platform (geolibre-<version>-<platform>.tar.gz, or .zip on Windows), unpack it anywhere, and click Locate… to pick the geolibre program; RustGIS remembers it.

RustGIS also finds the runner without asking when it is next to the RustGIS program (or in a geolibre folder beside it), on your PATH, or named by the RUSTGIS_GEOLIBRE environment variable (the command line uses these). The tools then appear under GeoLibre › Raster, Vector, Lidar, Hydrology, Terrain, Conversion in the Geoprocessing pane and the Catalog's toolboxes, and Find Tools searches them.

• Raster inputs are passed as their own files; vector layers (or their selection) are written in the first raster input's coordinate system, or the UTM zone around the data, so distances and areas are in metres. Data spanning more than 40° of longitude stays in degrees.
• Raster outputs are kept inside the project, so they save and reopen with it. Text and table reports appear in the tool's messages.
• LiDAR and other inputs RustGIS doesn't open as layers take a file path, read like Add Data reads one. Outputs are written to a fresh scratch folder and loaded from there.
• Each run is a separate geolibre process, so a tool that fails can't take RustGIS down.
• From the command line: gp.run={"tool":"geolibre:slope","params":{"input":"dem"}}; gp.tools lists every tool's parameters, gp.geolibre shows the runner in use and gp.setGeolibre={"path":"…"} picks one.

In the web app, click Load GeoLibre tools in the Geoprocessing pane instead. RustGIS loads geolibre-rust's WebAssembly runner (the geolibre-wasm package, from jsDelivr, about 25 MB the first time, then from the browser's cache) and the tools run in the page, in an in-memory folder: nothing is uploaded. The web app remembers this and loads them again on your next visit. The runner's code comes from jsDelivr, pinned to one geolibre-wasm release, the same trust as installing that package. Tools that read files by path (LiDAR files, for instance) need the desktop app, since a web page has no file system.

In the desktop app and on the command line, RustGIS waits while a tool runs, so a long run on a large raster or point cloud keeps the window busy until it finishes. In the web app the run is started in the background and the result is added when it ends, but the tool itself runs in the page, so the page is busy while it computes.

Keyboard shortcuts¶