segment-geospatial (SamGeo): segmenting satellite imagery with SAM

What SamGeo actually solves for geospatial analysts

Running SAM on a satellite scene is not hard in principle and tedious in practice. SAM expects an image tensor and prompts; geospatial work arrives as GeoTIFFs with a CRS, often as tiles fetched from a TMS server, and the useful output is a polygon layer that lines up with everything else in your GIS. SamGeo exists to close that gap. The README states the objective plainly: to simplify the process of using SAM for geospatial data analysis with minimal coding effort.

The audience is narrow and identifiable. You are comfortable in Python, you have imagery you can read with rasterio, and you want masks as GeoPackage, Shapefile or GeoJSON rather than as PNG overlays. The QGIS plugin covers the same ground for people who would rather not write code at all. If you already have a segmentation pipeline built on raw SAM checkpoints and you are happy with it, SamGeo adds a layer you do not need.

The package is MIT licensed and cites a JOSS paper (Wu and Osco, 2023), which matters for anyone who has to justify a dependency in a written methodology.

How SamGeo turns a GeoTIFF into vector masks

The pipeline the README describes has four visible stages. First, tile download: SamGeo can pull map tiles from Tile Map Service servers and assemble them into GeoTIFF files, so you can start from a basemap URL instead of a local raster. Second, segmentation: the GeoTIFF is passed to SAM, HQ-SAM or the newer SAM 3 family, depending on which extra you installed. Third, prompting: prompts come from text (through Grounding DINO, installed by the text extra), from foreground and background markers you place interactively, or from existing markers loaded out of a vector dataset. Fourth, export: results are written as GeoPackage, Shapefile or GeoJSON, and the input prompts can themselves be saved as GeoJSON.

That last point is the design decision worth noticing. Prompts are treated as first-class data you can persist and reload, which makes a segmentation run reproducible in the sense that you can re-run the same markers against a new scene. It does not make the model deterministic, and the README does not claim it does.

There is also a REST API for serving segmentation over HTTP, documented separately at samgeo.gishub.org/api, and the repository ships a Dockerfile that builds on jupyter/base-notebook with leafmap, localtileserver and sam2==0.4.1 pinned, plus jupyter-server-proxy so localtileserver works behind the proxy. The Dockerfile also sets PROJ_LIB to /opt/conda/share/proj, which is the kind of detail you only learn by reading the file.

Installing segment-geospatial and running a first segmentation

The README recommends pixi for installation, specifically on Windows or when PyTorch/CUDA and SAM 3 dependencies are involved, on the grounds that it resolves dependencies faster than conda/mamba and avoids numpy version conflicts. The pixi quick start installs pixi, creates a project, and expects you to edit pixi.toml before installing.

curl -fsSL https://pixi.sh/install.sh | sh
pixi init geo
cd geo
pixi install
pixi run jupyter lab

On Windows the README gives a PowerShell one-liner instead: powershell -ExecutionPolicy Bypass -c "irm -useb https://pixi.sh/install.ps1 | iex". After pixi install and pixi run jupyter lab, Jupyter Lab opens and you work from a notebook.

If you prefer pip, the package is on PyPI and is deliberately split into extras so a CI environment does not pull every model. The README lists segment-geospatial[samgeo], [samgeo2], [samgeo3], [fast], [hq], [text], [fer] and [api], plus [all] and [extra]. The base install and [samgeo] carry only the minimum to run SamGeo.

pip install "segment-geospatial[samgeo3]"

Pick the extra that matches the model you intend to run. The README points to pyproject.toml for the exact package list behind each name, and that file is the authoritative source: samgeo3 pulls sam3>=0.1.4, transformers, scikit-learn, scikit-image, buildingregulariser, leafmap, localtileserver, spacy and triton, with a platform marker for Linux and a separate triton-windows pin. That is a heavy dependency set, and it is the reason the extras exist.

Conda users can install from conda-forge instead. The README notes the package is available there, though the installation section is truncated before it shows the command, so check the conda-forge feedstock page rather than guessing the channel syntax.

What you should see after a successful install: a Python environment where segment-geospatial imports, and, in the pixi path, a running Jupyter Lab. The README does not print an expected import banner, so treat a clean import as the signal.

Where SamGeo gets in your way

The dependency split is the first real cost. There is no single install that is obviously correct. Choosing [all] or [extra] drags in every model family and, for [extra], notebook tooling and leafmap as well; choosing a narrow extra means a second install the moment you want text prompts or HQ-SAM. The README frames this as a feature for CI package size, and it is, but it moves the decision onto you before you have run anything.

The second cost is the classifier in pyproject.toml, which still reads Development Status :: 2 - Pre-Alpha despite the project being at version 1.4.2 with a JOSS paper. That is a metadata inconsistency rather than a functional warning, but it is the kind of thing that trips automated dependency policy checks.

Third, the README does not document rollback. There is no section on pinning a working version, no note on what changes between 1.4.0, 1.4.1 and 1.4.2 beyond the release tags, and no migration guidance between the SAMGeo 1, 2 and 3 model paths. If you are deploying the REST API extra into a shared service, that silence is the gap to close yourself before you upgrade.

Finally, this is the wrong tool when your imagery is not georeferenced, when you want instance tracking across video rather than per-scene masks, or when you need a segmentation model you can fine-tune end to end. SamGeo orchestrates SAM-family models over geospatial inputs; it does not replace them.

SamGeo against segment-anything-eo and raw SAM

The README is explicit that SamGeo draws its inspiration from segment-anything-eo by Aliaksandr Hancharenka, that the source code was adapted from that repository, and that credit for the original version goes to him. So the honest comparison is not SamGeo versus a stranger; it is SamGeo versus its own ancestor and versus using SAM directly.

segment-anything-eo is the closer sibling. It established the pattern of feeding georeferenced imagery to SAM. SamGeo's difference is packaging and surface area: a published PyPI and conda-forge package with named extras, a documented REST API, a QGIS plugin in a separate repository, a Dockerfile, and a JOSS citation. If you need a citable, installable dependency with a stable import name, that difference is the whole point. If you are already running segment-anything-eo successfully and do not need the extras or the plugin, switching buys you maintenance continuity more than capability.

Against raw SAM, the difference is more concrete. Raw SAM gives you a mask predictor and expects you to handle tiling, CRS, raster I/O and vector export. SamGeo handles those and hands you GeoJSON, Shapefile or GeoPackage. The trade is control: you get less say over how tiles are stitched and how prompts are encoded, and you inherit the dependency choices above. For a one-off experiment on a small scene, raw SAM plus rasterio is fewer moving parts. For repeated work across scenes, the plumbing SamGeo provides is the part you would otherwise rewrite.

Licence, maintenance and the cost of upgrading

SamGeo is MIT licensed, which is permissive and imposes no copyleft obligation on your own code. That says nothing about the licences of what it pulls in. The samgeo3 extra depends on sam3, transformers, spacy, leafmap and localtileserver, each with its own terms, and the Dockerfile pins sam2==0.4.1 from conda-forge. Before shipping a product, read the licence of every model package your chosen extra installs. This is not legal advice; it is a list of files to open.

On maintenance, the repository is not archived and the last push was on 2026-09-07, with v1.4.2 released on 2026-08-22. That is recent activity, but it is a fact about timing, not a promise about the roadmap, and the README publishes no support policy or deprecation schedule.

Upgrade cost is where the extras architecture bites. Because dependencies are declared per extra in pyproject.toml, an upgrade can move torch, triton or sam3 underneath you without any change to the segment-geospatial version number you pinned. The practical mitigation is to pin the whole environment, not just the package: pixi.lock if you went the pixi route, or a fully resolved requirements file if you did not. The README does not describe a supported upgrade path, so treat the lockfile as the upgrade mechanism.

Editorial conclusion

Adopt SamGeo if you work in Python or QGIS and want SAM masks as georeferenced vectors without writing the raster and tiling glue yourself; the pixi path is the one the README calls most reliable on Windows. Skip it if you need a documented rollback story or a single default install, because the package splits its dependencies across extras and the README does not describe how to revert a version. Before committing, verify that your chosen extra resolves against your Python version (>=3.10) and that a small AOI segments acceptably on your hardware.

Frequently asked questions

Official sources

1. License: MIT
2. opengeos/segment-geospatial on GitHub
3. Project website
4. README
5. Releases