segment-geospatial: SAM for GeoTIFFs, Tiles and Text Prompts

What SamGeo actually removes from the SAM workflow

SAM itself is a general image segmentation model. Point it at a satellite scene and you get masks in pixel coordinates with no georeferencing, no way to fetch the scene, and no way to write the result back into a GIS. SamGeo exists to close that gap. The README states the goal plainly: to simplify the process of using SAM for geospatial data with minimal coding effort. The package's features list is essentially that gap, enumerated. It downloads map tiles from Tile Map Service servers and assembles GeoTIFF files. It segments GeoTIFFs with SAM and HQ-SAM. It accepts text prompts, foreground and background markers, and existing markers loaded from vector datasets. It writes results to GeoPackage, Shapefile and GeoJSON, and saves the input prompts as GeoJSON too. The intended user is a geospatial analyst or remote sensing researcher who already works in Python and wants segmentation output in a format QGIS or ArcGIS can open, not a machine learning engineer building a segmentation model from scratch. The README also credits segment-anything-eo by Aliaksandr Hancharenka as the source the code was adapted from, which is worth knowing if you are tracing the lineage of a specific function.

The pipeline: tiles in, vectors out

The data flow implied by the feature list runs in one direction. Input arrives either as a local GeoTIFF or as a TMS URL that SamGeo downloads and mosaics into a GeoTIFF. Prompts arrive from three places: text (through Grounding DINO, installed via the text extra), interactive markers drawn by the user, or an existing vector dataset read from disk. The segmentation model, whether SAM, SAM 2, SAM 3, FastSAM or HQ-SAM, produces masks. Those masks are then vectorised and written to GeoPackage, Shapefile or GeoJSON, and can be displayed on an interactive map. The prompt side is preserved as GeoJSON as well, which matters for reproducibility: you can rerun the same prompt set against a different image or a later date. There is also a REST API exposed through FastAPI and Uvicorn for serving segmentation over HTTP, documented separately at samgeo.gishub.org/api. The timeseries feature is the one that most changes the shape of a workflow, because it implies the same prompt geometry can be applied across multiple acquisition dates rather than re-prompting each scene by hand. The README does not describe how the timeseries alignment is handled, so treat that as something to read the docs for before designing around it.

Installation is split by model, and the split is the point

SamGeo does not ship one dependency set. The PyPI package defines extras so you install only the model family you intend to use: segment-geospatial[samgeo] for the baseline, [samgeo2], [samgeo3], [fast] for FastSAM, [hq] for HQ-SAM, [text] for Grounding DINO so SAM 1 and 2 can take text prompts, [fer] for the feature edge reconstruction algorithm, and [api] for FastAPI and Uvicorn. Two aggregate extras exist: [all] for every model, [extra] for every model plus notebook and leafmap support. A concrete install looks like pip install "segment-geospatial[samgeo3]". The README is explicit about why: it reduces package size for CI environments, since not every model is used every time. That is a real benefit for a build pipeline, and it is also a trap. If you install the base package and then import a class that needs Grounding DINO, nothing in the extras scheme stops you; you find out at runtime. For the harder environments, the README recommends pixi over conda or mamba, citing faster and more reliable dependency resolution and avoidance of numpy version conflicts, and specifically calls out Windows and the PyTorch/CUDA combination as the cases where this matters. The pixi path is: curl -fsSL https://pixi.sh/install.sh | sh on Linux or macOS, the PowerShell equivalent on Windows, then pixi init geo, cd geo, edit pixi.toml with the GPU or CPU configuration from the docs, pixi install, and pixi run jupyter lab. Conda-forge is also supported, and a QGIS plugin exists in a separate repository for users who would rather not write Python at all.

Where the abstraction leaks

The most consequential limitation is not stated in the README but follows from the architecture: SamGeo is a wrapper, not a model. It has no training step, no fine-tuning loop and no labelled dataset format of its own. If your target class is not something SAM segments well out of the box, adding more SamGeo code will not fix it, because the failure is upstream in the model weights. The text-prompt path is the clearest example of a dependency that is not really SamGeo's: it requires Grounding DINO through the [text] extra, so text quality is a Grounding DINO property, and the README does not claim otherwise. The extras scheme creates a second class of failure, where a working script breaks after an environment change because a model dependency was never installed. The third is hardware. SAM and its variants are heavy, and the README's own recommendation of pixi for CUDA conflicts is an admission that the PyTorch dependency is the fragile part of the install, not the geospatial code. If you are running on CPU only, nothing in the README suggests this is a supported high-throughput path. And if your data is a single small image, the tile download and GeoTIFF machinery is dead weight; you would be better served calling SAM directly.

How it compares with calling SAM yourself, or with a trained classifier

The obvious alternative is the upstream Segment Anything repository from Meta, which SamGeo depends on rather than replaces. The difference in approach is narrow but decisive. Upstream SAM takes an image array and returns masks. It has no concept of a GeoTIFF, no tile downloader, no coordinate reference system, and no vector writer. Using it on satellite imagery means writing the georeferencing, tiling and export code yourself. SamGeo's contribution is exactly that code, adapted from segment-anything-eo. The second alternative is a supervised land-cover classifier, and the difference there is philosophical rather than technical. A classifier is trained on labelled examples and predicts fixed classes with a known error profile. SamGeo prompts a foundation model and returns whatever it decides is an object, with no class labels and no accuracy figure you can quote without ground truth. If your deliverable is a map of building footprints that a colleague will check against a reference layer, SamGeo's prompt-and-vectorise loop is a reasonable fit. If your deliverable is a five-class land-cover raster with a confusion matrix, SamGeo is the wrong tool and no amount of prompt tuning changes that. This is a boundary worth stating to stakeholders before a project starts.

Maintenance, releases and the MIT licence

The repository is active: the most recent push is dated 2026-09-07, and three releases landed between June and August 2026 (v1.4.0, v1.4.1, v1.4.2). The package is published on both PyPI and conda-forge, has a conda-forge feedstock, a Docker image, and a JOSS paper (Wu and Osco, 2023, JOSS 8(89):5663), which is unusual for a wrapper library and suggests the maintainers intend it to be citable in academic work. The MIT licence is permissive and imposes no copyleft obligation on your own code. What MIT does not cover is the model weights and the upstream projects SamGeo calls into: SAM, HQ-SAM, Grounding DINO and FastSAM each carry their own licence terms, and the README does not consolidate them. If you are shipping a commercial product that depends on a specific checkpoint, check that checkpoint's licence separately rather than assuming the MIT wrapper settles the question. This is not legal advice, and the licence terms of the model you actually load are the ones that matter. On upgrade cost, the extras split means a version bump can change which model dependencies resolve, so pinning the extras group you use is the practical defence.

Who should install it, and what to check first

SamGeo is a good fit for a remote sensing analyst who has GeoTIFFs or a TMS endpoint and needs vector output they can open in QGIS, and for a research group that wants a citable, MIT-licensed wrapper rather than a hand-rolled script. It is a poor fit for anyone who needs class labels, accuracy metrics, or a CPU-only batch pipeline over thousands of scenes. The QGIS plugin is the right entry point for users who do not want to touch Python. Before adopting it, verify three things in your own environment. First, install the exact extras group you need, for example pip install "segment-geospatial[samgeo3]", and confirm the imports you plan to use resolve; the base install does not include every model. Second, if you are on Windows or already have a CUDA-pinned PyTorch, follow the pixi route rather than conda, since that is the case the README singles out. Third, read the API documentation at samgeo.gishub.org/api before deciding whether to serve segmentation over HTTP or call the Python API directly, because the REST path adds FastAPI and Uvicorn to your deployment surface. The package's own documentation site, not this article, is the place to confirm the timeseries behaviour and the current model list.

Editorial conclusion

Adopt segment-geospatial if your input is already a GeoTIFF or a TMS layer and your output needs to be a GeoPackage, Shapefile or GeoJSON that a GIS can open. Do not adopt it if you need a trained land-cover classifier, if you cannot supply a GPU, or if you cannot pin the PyTorch and CUDA versions your environment already uses. Verify first that the extras group matching your model choice installs cleanly (for example pip install "segment-geospatial[samgeo3]") and that the pixi route resolves on Windows before you commit a team to conda.

Official sources

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