Using GeoMarmot¶

GeoMarmot is a canvas of transformers: data comes in through Readers, flows from node to node, and leaves through Writers. Nothing is computed until you look at it — select a node and its rows appear in the table and its geometry on the map. The ⓘ at the start of a row opens that feature: all its attributes, and its geometry described (type, vertices, extents, area, validity, WKT).

Anything that takes more than a moment — the engine starting, a file opening or downloading, the graph running its slower steps (hexagons, overlays, Zarr chunks), Run writing files — shows a progress card in the middle of the canvas, with a percentage when it is known. You can keep working while it shows.

The toolbar¶

Getting data in¶

Drag files onto the page, or click Connect in the toolbar and pick where the data is:

The window remembers the connector you used last, the bucket and folder you were in, and recent buckets and links (links with a query string, such as signed URLs, are not kept). It never keeps a password or a key.

Each file becomes a line under Layers; hover it for its rows, columns and CRS, and click + Reader to add a Reader node for it. Files from your computer are read in your browser and never uploaded; remote files are read in parts, as queries need them. Which formats are supported, and how, is in Formats.

Google Cloud Storage without the server¶

On the hosted demo there is no server to read your gcloud credentials, and a web page cannot read them itself. Sign in with Google asks Google for a read-only Cloud Storage token for this page; Google shows its consent screen, and the token lasts about an hour. It is kept in the tab's memory only and is sent to storage.googleapis.com and nowhere else. You see the buckets your Google account can read; no change to the buckets is needed.

Differences from the server:

• A file is downloaded whole, then opened like a file from your computer. Files over 1 GB ask first. With the server, large Parquet files are read in parts instead.
• Zarr stores need the server.

The sign-in needs an OAuth client ID for the site, set up once in the Google Cloud console:

1. APIs & Services ▸ OAuth consent screen: choose Internal to limit it to your Google Workspace organisation (no Google review needed), and add the scope https://www.googleapis.com/auth/devstorage.read_only.
2. APIs & Services ▸ Credentials ▸ Create credentials ▸ OAuth client ID, type Web application. Under Authorised JavaScript origins, add the site's origin (for example https://regislon.github.io) and, for development, http://localhost:5173. No redirect URI is needed.
3. Either paste the client ID into the connector (it is remembered in this browser), or set it as the GOOGLE_CLIENT_ID variable of the GitHub repository (Settings ▸ Secrets and variables ▸ Actions ▸ Variables) so the published demo has it built in. A client ID is not a secret.

Building a graph¶

Add transformers from the Transformers list, or, with the pointer over the canvas, start typing part of a name (Quick Add): the transformer lands where the pointer is. Drag from an output port to an input port to connect them. Select a node to edit its settings in the inspector on the right; the ? button explains what it does. Wherever a setting asks for an attribute, type part of its name to find it; a list of attributes has a filter box above it, and Select all then picks the ones it shows. A node in error says why, and the nodes after it wait.

Saving and opening¶

There are two places to keep your work:

• On your computer, as a file: Save ▸ To this computer downloads graph.flow.json, and Open ▸ From this computer… opens one. Use a file to share a graph, keep it with a project, or move it to another computer. A graph opened from a file always comes back with its SQL restricted (security).
• In this browser, as named workspaces: Save ▸ To this browser (⌘S) asks for a name the first time, then saves under it. Open ▸ From this browser… (⌘O) lists them, newest first, to open or delete. They stay in this browser profile on this computer, and go if you clear the site's data.

Either way, what is saved is the graph — its nodes, their settings and any transformers the assistant generated — not your data. After opening, load the files its Readers need again. The current graph is also saved automatically in the browser as you work, and comes back when you reload the page.

Writing results¶

Add a Writer, connect it, choose a format and a file name, then press Run. Every connected Writer writes its file; the browser saves it to your downloads. A Writer's own Write this file writes just that one.

The assistant¶

Assistant opens a chat beside the canvas. Describe what you want — "make points from the E and N columns" — and it proposes the nodes as a draft: it can preview the draft on a sample, and nothing changes in your graph until you press Apply (one Undo step) or Discard. Its settings (the gear) choose the provider, the model, your API key and, most importantly, what it may see of your data — by default only column names and types. See security and privacy.