Usage of Geo-SAM Tools#

If you are new to Geo-SAM, start with the Quick Start guide for a 5-minute walkthrough of the basic segmentation workflow.

Choosing a Workflow Mode#

Since v2.0, Geo-SAM provides two modes for segmentation workflows. This section describes how to use each of them.

Live Encoding mode (new)

Select a raster layer and a SAM model, then start segmenting immediately. Features are encoded on the fly using QGIS background tasks and cached for fast re-queries.

No pre-encoding step needed
First prompt triggers background encoding
Subsequent prompts load from cache at millisecond speed
Supports online tile layers (XYZ, WMS)

Recommended for most users.

Live Encoding Mode

Pre-Encoded mode

Use the Image Encoder to generate reusable feature files, then load them in the Segmentation tool. Ideal when segmenting on a remote server.

Encode once, segment many times
Features saved as .pt files with a manifest.parquet
Can be generated on Colab / AWS and loaded locally
Fastest prompt response after encoding

Best for repeated segmentation of the same image.

Pre-encoded Mode

Differences between Two Modes#

Aspect	Live Encoding mode	Pre-encoded mode
First prompt	Triggers background encoding	Instant (features pre-encoded)
Model selection	User selects any model	Locked to encoding model
Feature cache	Built on the fly	Pre-built on disk
Online tile layers	Supported	Not applicable
Best for	Quick exploration	Repeated segmentation

Tools Overview#

Segmentation

The Geo-SAM Segmentation tool is the primary interactive labelling interface. It supports both the Live Encoding and Pre-encoded modes via a source selector dropdown.

Quick Start (5 Minutes) – 5-minute guide (Live Encoding mode)
Live Encoding Mode – full Live Encoding mode reference
Pre-encoded Mode – full Pre-encoded mode reference

Image Encoder

The Geo-SAM Image Encoder is a QGIS Processing algorithm that generates reusable feature files from a raster layer. It supports band selection, sliding-window stride, memory strategy, GPU acceleration, and CRS/resolution resampling.

Geo-SAM Image Encoder – Image Encoder reference

Encoder Copilot

The Encoder Copilot helps you find the right encoding parameters by previewing patch coverage in real-time before running the full encoder.

Encoder Copilot – Encoder Copilot reference

Encoder Package (Legacy)

The standalone GeoSAM-Image-Encoder Python package is superseded by the geosam core library. See GeoSAM Image Encoder Package for legacy usage notes.