Supported Data Formats¶

This page lists the data formats RustGIS reads and writes, how to add each one, and the main limits. Data covers adding data, large files and rasters in more detail; Maps and Basemaps covers web tile layers.

Most formats open in the desktop app and in the web app alike. Those that need C libraries (GDAL, DuckDB) or files on disk are desktop-only, as the tables say. The web app reads GeoPackages without SQLite, with a small SQLite file reader written in Rust.

Vector and tabular files¶

Files with more than 100,000 features (GeoPackage, GeoParquet, FlatGeobuf, and Shapefile on the desktop) are read in place, a view at a time, rather than loaded whole: see Large files. They draw, label, identify and run through tools like any layer; Load All Features loads one to edit it.

Formats read through GDAL¶

With GDAL installed (its ogr2ogr and ogrinfo on the PATH, GDAL 3.7 or later), the desktop app also reads the vector formats below. Each layer is converted once into a cached, indexed FlatGeobuf, so large ones stream too: see Formats through GDAL.

Files on the web¶

Home › Add Data › From URL… (layer.addUrl with "url") downloads a file by its https:// (or s3://, see S3 buckets) address and adds it like a file from this computer: GeoJSON, CSV, GeoParquet, FlatGeobuf, GeoPackage, zipped Shapefiles, KML/KMZ, GPX or GeoTIFF/COG, up to 512 MB on the desktop and 256 MB in the web app (where the server must allow requests from web pages, CORS). On the desktop, with GDAL installed, a JPEG 2000 file (.jp2, .j2k: Sentinel-2's imagery on S3) is downloaded too, converted to a GeoTIFF that the project keeps, and added. Desktop byte uploads (layer.addDataBytes) of .jp2 and .j2k use the same conversion. The web app rejects both JPEG 2000 uploads and downloads with an explicit GDAL limitation; convert them to GeoTIFF first. The format comes from the address, or from the contents when the address has no extension (an API endpoint, say), JPEG 2000 included: its signature is recognised in the contents, so the desktop converts it and the web app gives the same GDAL limitation. The app downloads in the background and adds the layer when the file arrives (to the project it was started in: opening another meanwhile drops it). A .pmtiles address is added as a tile layer and read a tile at a time instead.

For JPEG 2000 uploads and downloads on the desktop, the converted GeoTIFF must fit within 512 MiB. The private conversion workspace (source file, output and GDAL scratch files together) is monitored every 50 ms against a budget of the input file's byte length plus three times that output limit (1.5 GiB). Conversion stops when the workspace exceeds the budget, but files can grow between checks: this is not a strict operating-system disk quota. Ordinary conversions of files opened from disk do not use this workspace budget.

Conversion runs synchronously while the layer is added and can temporarily make the app unresponsive. The original JPEG 2000 byte buffer is released once it has been staged on disk, before GDAL runs or the GeoTIFF is read back. The converted GeoTIFF and decoded raster still occupy memory together; the 512 MiB file limit is not a limit on total process memory.

A cloud-optimised GeoTIFF (a tiled .tif with overviews, as most published imagery is) is read in place rather than downloaded: its header first, then, by HTTP range requests, only the tiles of the overview each part of the view needs, so a Sentinel-2 scene of 300 MB draws in a couple of seconds and full detail comes as you zoom in. It is a tile layer (map.addTiles kind cog, saved in the project by its address), drawn under the map's own layers like other tile layers: RGB(A) 8-bit images as they are, other images in grey stretched between the 2nd and 98th percentiles of their coarsest overview. A GeoTIFF in strips, with bands stored apart, or without tiles is downloaded whole as a raster layer, as is any GeoTIFF added with "whole": true (for the raster tools and symbology). The web app needs the server to allow range requests from web pages (CORS with the Range header), as public buckets such as Sentinel-2's do.

A GeoParquet or FlatGeobuf file by its address is read in place too, a view at a time, however large: the layer is streamed like a large local file, and the view's features are fetched in the background by HTTP range requests and drawn as they land. A FlatGeobuf's header and packed R-tree index are read first (a level of the tree per round of requests), then only the features in the view. A GeoParquet's footer is read first, then the row groups the view meets, by their bounding box covering column (bbox) and its statistics: the covering of groups on the view's edge, then the geometry and attribute columns of the rows taken. A view holding more than a read takes (60,000 features on the desktop, 30,000 in the web app) shows an evenly spread sample of it, in patches; zoom in for all of them. So a 12 GB FlatGeobuf of 11 million areas opens after 65 KB and draws a city in about a second from 9 MB, and a 525 MB Overture buildings file opens after 1 MB. The project keeps the address and reads it the same way when it opens. A FlatGeobuf without an index, a GeoParquet without a covering column, or a server that doesn't answer range requests means the file is downloaded whole instead, as is any file added with "whole": true; Load All Features and the geoprocessing tools fetch the whole file on the desktop, while in the web app they need the file downloaded first.

layer.addUrl waits for the download, up to a minute, which suits the command line, MCP and the desktop app's assistant; a larger file comes through the From URL… dialog, which downloads in the background. In the web app, where nothing may wait, it adds .pmtiles and GeoTIFF addresses only (a GeoTIFF read in place); other files, GeoParquet and FlatGeobuf read in place among them, come through the From URL… dialog (ui.addUrl) or a ?data= link. GeoJSON, CSV, KML and GPX files are read up to 256 MB; larger downloads (GeoParquet, FlatGeobuf, GeoPackage, GeoTIFF) up to the limits above.

Map and feature services¶

Home › Add Data › From Service… connects to a service by its address, lists what it offers from its capabilities. For OGC API feature collections, enter a group name (initially My OGC Layer) and choose Import All. The group expands into ordinary point, line and polygon layers with the same legends, styling and attribute tables as file imports. Other offerings have individual Add buttons (service.layers and service.add from scripts, the command line and MCP). An OGC API landing page works directly: RustGIS follows its advertised JSON collections link, so you don't need to append /collections. If the landing page also offers map tiles, they remain listed alongside the collections. A failed collections request leaves any available map layers usable and shows the error.

When a service can't be reached or refuses the request, the dialog says what happened in plain words and what to try next: a sign-in or token it needs (401), access refused (403), nothing at that address (404), too many requests (429), a problem on the server (5xx), or a server that couldn't be reached or took too long. When a firewall in front of the server (Cloudflare, Akamai, Imperva, Sucuri or AWS WAF) blocked or challenged RustGIS itself, told by its own block page or a header it sends only then, it says so: only the service's administrator can let RustGIS through. A firewall that only passed on the service's own refusal (a private service wanting a token) isn't blamed for it. Details, folded below, lists what the server said for an expert or the administrator: the address (without keys or tokens), the status, the server, the firewall and the request's id, the User-Agent RustGIS sent, and the title or first words of the server's answer (as text). Copy details copies them to send. In the web app the browser hides most of a refused answer, so it tells the status only.

Right-click the group and choose Refresh to rediscover its collections and update them all, including newly added or removed collections. Right-click a child and choose Refresh to update only that collection. Existing children keep their names, styles and visibility (a changed geometry type gets a suitable default symbol); selections are cleared because row positions can change. Refresh replaces local feature edits with the service's data. Failed imports or refreshes leave the map intact; a successful operation is one undo step. Groups and their source connections are saved in the project. Group downloads are limited to 2000 collections and 64 MB in total and use the existing per-collection feature limits.

Scripts use service.import {"url":"…","name":"My OGC Layer"} and service.refresh {"group":id} or service.refresh {"layer":id}. The browser uses service.groupPlan to discover the requests, then supplies text, documents, and responses: [{"url":"…","text":"GeoJSON"}] to import or refresh without blocking network calls.

The type is guessed from the address (?SERVICE=, /wmts, /wfs, /wcs, /collections, /rest/services…) or chosen (select OGC API Features and Tiles when a landing page's address doesn't identify its type). A WebMercatorQuad tileset is found by its tile matrix set, whatever the server calls it. A service that asks for a token says so. In the web app the server must allow requests from web pages (CORS).

A coverage is read once, for the view when it was added (its DescribeCoverage first, for its axes, format and bounds; service.coverage gives the GetCoverage address alone). Moving the map doesn't ask for it again: add it again for another area. The server reprojects it to EPSG:4326 (WCS 2.0 through its CRS extension); one that can't answers with an error, which is shown.

For callers that fetch documents themselves (including the web app), service.layers accepts text for the initial document and documents: [{"url": "…", "text": "…"}] for subsequent responses. It returns next while another collections document is needed; supplied documents never cause a blocking capabilities fetch. Each listed layer includes source_url; pass it and the same documents to service.add to distinguish layers with the same name. Discovery follows at most four documents and rejects loops and disallowed addresses. Collection lists aren't paged. On the desktop, feature downloads follow their next pages (see the table above).

Catalogues¶

The same dialog's Catalogue search (CSW) type searches a CSW 2.0.2 catalogue (GeoNetwork, pycsw, geocat.ch…) by words anywhere in its records and, if you like, the map's area (catalog.search). Its records are listed 20 at a time (More asks for the next), with their titles, abstracts (on hover) and bounds (Zoom), and a button per link RustGIS can follow: a WMS, WMTS, WFS, WCS, OGC API or ArcGIS service connects in the dialog, a download is added as From URL… does. Links pointing where a document on the web may not send RustGIS (the local network) are left out.

PostgreSQL and PostGIS¶

The desktop app reads the geometry and geography columns of a PostGIS database live, talking to the server itself: see PostgreSQL and PostGIS.

MySQL and MariaDB¶

The desktop app reads the spatial columns of a MySQL (8 or later) or MariaDB (10.2 or later) database live, talking to the server itself: see MySQL and MariaDB.

SQL Server and Azure SQL¶

The desktop app reads SQL Server 2012 or later and Azure SQL spatial tables live, without an external client: see SQL Server and Azure SQL.

SQL queries and DuckDB databases¶

With DuckDB installed (the duckdb program on the PATH, DuckDB 1.5 or later), the desktop app adds the result of an SQL query as a layer, and opens DuckDB database files. Results are written as cached GeoParquet, so large ones stream too: see SQL queries and DuckDB databases.

Rasters¶

Tiles and web services¶

Writing¶

GeoPackage, Shapefile and FlatGeobuf exports are written in the coordinate system the layer was read in: a Shapefile's .prj, a GeoPackage's or FlatGeobuf's own system, or the crs a CSV was added with (EPSG:25832 data goes back out as EPSG:25832). A layer read in longitude/latitude, or made in RustGIS, is written in WGS 84 (EPSG:4326). share.exportLayer takes "crs" to choose another, such as {"layer": "Parcels", "path": "parcels.gpkg", "crs": "EPSG:4647"}. GeoJSON, KML, GPX, GeoParquet and CSV are always written in WGS 84.

RustGIS files¶