Geo-SAM Image Encoder#

Prerequisites

Before using the Image Encoder, make sure you have installed the required dependencies and downloaded a SAM model in Settings.

The Geo-SAM Image Encoder is a QGIS Processing algorithm that pre-processes geospatial images and generates reusable feature files using the SAM image encoder. The generated features can then be loaded in the Pre-encoded Mode mode to label landforms interactively.

Opening the Encoder#

Click the Geo-SAM Image Encoder icon in the toolbar. The QGIS Processing dialog opens with the algorithm parameters.

Image Encoder demo

Parameters#

Required Parameters#

Parameter

Description

Input raster layer

The raster layer or image file to encode.

Bands

Select up to 3 bands (preferably in RGB order). If omitted, the first 1-3 bands are used.

Sliding-window stride

Determines patch overlap. Overlap = patch_size - stride. Default: 512. Range: 1-1024.

GeoSAM model

Select a model from the dropdown. The model must be downloaded first.

Output feature-cache directory

The folder where features and manifest will be saved.

Use GPU if CUDA is available

Enable GPU acceleration (default: on).

Load output features in Geo-SAM tool

Automatically load the features in the Segmentation tool after encoding (default: on).

Advanced Parameters#

Parameter

Description

Target CRS

Resample the image to a different CRS. Defaults to the original CRS.

Target resolution

Resample to a specific resolution in meters. When the input CRS is geographic (degrees), a UTM CRS is estimated automatically. Defaults to native resolution.

Data value range

Fixed [min, max] range to rescale to [0, 255]. If omitted, the tool computes min/max from raster statistics.

CUDA device id

GPU device index when multiple GPUs are available (default: 0).

Encoding memory strategy

Balanced (default) or Low Memory. See below.

Band Selection#

SAM natively supports only three-band RGB images. Geo-SAM has been adapted to support one or two-band images, so you can use:

  • Grayscale images (1 band)

  • Spectral index images like NDVI, NDWI (1 band)

  • SAR images (1-2 bands)

  • Standard RGB images (3 bands)

If you select no bands, the tool defaults to the first 1-3 bands.

Value Range Rescaling#

SAM expects input values in the range [0, 255]. Remote sensing images often have values outside this range. The tool handles this in two ways:

  • Automatic (default): computes the min and max values from the raster statistics within the processing extent and rescales [min, max] to [0, 255].

  • Manual: specify a fixed [min, max] range in the advanced Data value range parameter.

Patch Sampling#

SAM supports input images of size 1024 x 1024 (SAM3 uses 1008 x 1008). The encoder handles images of any size by sampling them into overlapping patches:

  • Small images are resized to match the input size.

  • Large images are split into a grid of overlapped patches.

The stride parameter controls the overlap: overlap = patch_size - stride. A smaller stride produces more overlap (more patches, slower encoding, better edge continuity). A larger stride produces less overlap (fewer patches, faster encoding).

Memory Strategy#

Strategy

Description

Balanced

Flushes GPU/Python memory every 16 chips. Good balance of speed and memory.

Low Memory

Flushes memory after every chip. Slower but uses less peak memory. Use this when you encounter out-of-memory errors.

Output Structure#

The encoder creates the following structure in the output directory:

output_directory/
├── manifest.parquet           # chip metadata (GeoDataFrame)
└── <layer_name>/
    └── features/
        ├── chip_000000.pt     # encoded feature for chip 0
        ├── chip_000001.pt     # encoded feature for chip 1
        └── ...

The manifest.parquet contains per-chip metadata including bounds, CRS, transform, shape, model type, and checkpoint path. This allows the Segmentation tool to load features efficiently.

After Encoding#

If Load output features in Geo-SAM tool is enabled (default), the Segmentation tool opens automatically and loads the generated feature folder. You can start labelling immediately.

If you disabled auto-loading, open the Segmentation tool, switch to Pre-encoded mode, and load the output folder manually.

Tips for Faster Encoding#

  • Choose a smaller processing extent instead of encoding the full image.

  • Reduce the target resolution (in advanced parameters) to decrease the number of patches.

  • Increase the stride to minimize overlap and reduce patch count.

  • Choose a smaller model (e.g., SAM2.1 Tiny instead of SAM2.1 Large).

  • Use a GPU when enough accelerator memory is available.

  • Use the Low Memory strategy when peak memory matters more than speed.

Model Support for Feature Reuse#

Most SAM models support reusable features (encoding once, querying many times). If a model does not support feature reuse, the encoder will report an error. SAM3 models use a different image size (1008 x 1008) which is handled automatically.