OBIA
Object-based image analysis tools for geospatial rasters.
OBIA groups raster pixels into objects, measures their properties, and classifies them using labelled examples. Results are stored in a GeoDataFrame: a table of polygons and their attributes that you can inspect, save, and use in GIS.
With OBIA, you can:
- Load GeoTIFFs with their coordinate reference system and spatial transform.
- Segment imagery into object polygons.
- Measure each object's band statistics, spectral indices, shape, and texture.
- Transfer point labels to objects and train a classifier.
- Train on labelled point pixels and produce a raster class map.
- Evaluate models with grouped or spatial splits, buffers, and cross-validation.
- Add point-cloud measurements or process large rasters in tiles when needed.
Install
Use Python 3.11 or newer. Install the published release with:
python -m pip install obia
The documentation follows main. For a matching source installation, optional
dependencies, or Docker setup, see the
installation guide.
Segment a raster
This example assumes at least four loaded bands. Adjust the numeric band indices
to match your image; 0 refers to the first loaded band.
from obia.datasets import chesapeake_sample
from obia.handlers.geotif import open_geotiff
from obia.segmentation.segment import segment
image = open_geotiff(chesapeake_sample("train")["image"])
objects = segment(
image,
segmentation_bands=[0, 1, 2],
statistics_bands=[0, 1, 2, 3],
method="slic",
n_segments=600,
compactness=0.3,
convert2lab=False,
)
segments = objects.segments
segments.to_file("segments.gpkg", driver="GPKG")
Each row of segments contains a polygon, a segment_id, and feature columns.
See the segmentation guide for other
algorithms, masks, and parameter examples.
Measure objects
Calculate additional features on existing polygons without repeating segmentation.
All bands use zero-based numeric positions in the loaded image. This example
uses a projected CRS for shape measurements; use shape_units="pixel" if your
raster has a geographic CRS:
from obia.features import TextureConfig, extract_features
segments = extract_features(
segments, image, bands=[0, 1, 2, 3],
spectral=("mean", "std", "median", "iqr", "mad", "valid_count", "valid_fraction"),
percentiles=(10, 90),
indices={"ndvi": (3, 0)},
shape=True,
texture=TextureConfig(bands=(0,), distances=(1, 2), entropy_radii=(1, 3)),
)
Choose index inputs to match your raster's band order. Shape uses projected map
units, or shape_units="pixel" for pixel measurements. See the
raster feature guide for definitions,
masks, and texture settings.
Label and classify objects
Provide labelled points with a class column, using the same coordinate system
as the segments:
import geopandas as gpd
from obia.classification import classify
from obia.utils.utils import label_segments
labelled_points = gpd.read_file("/path/to/labelled_points.gpkg").to_crs(segments.crs)
training_segments, mixed_segments = label_segments(
segments,
labelled_points,
)
result = classify(
segments,
training_segments,
method="rf",
n_estimators=300,
random_state=42,
)
result.classified.to_file("classified_segments.gpkg", driver="GPKG")
For validation in new sites or areas, create and inspect a partition before
fitting. For example, with a site_id column identifying independent sites:
from obia.classification import split_objects
partition = split_objects(training_segments, method="grouped", groups="site_id",
test_size=0.2, random_state=42)
print(partition.class_counts)
result = classify(segments, training_segments, method="rf", split=partition,
compute_reports=True, random_state=42)
Spatial blocks, geometry buffers, explicit train/test sets, and reusable cross-validation folds are also supported. See the validation guide for examples and the literature behind choosing a design that matches the prediction task.
Use a method name or supply a compatible estimator or pipeline. The classification guide covers model choices, preprocessing, predictions, and evaluation.
Classify pixels
Read raster values at labelled points and predict a georeferenced class map:
from obia.classification import classify_pixels
points = gpd.read_file("labelled_points.gpkg") # A CRS and a `class` column are required.
result = classify_pixels(
image, points, bands=[0, 1, 2, 3], method="xgboost",
n_estimators=100, max_depth=4, n_jobs=1, random_state=42, test_size=None,
)
result.write_geotiff("pixel_classes.tif")
print(result.class_mapping)
The same classifier names and pipelines work for object and pixel classification. See pixel classification for sampling rules, validation, masks, and prediction on another image.
Example notebooks
The notebooks run independently using the bundled Chesapeake imagery and reference maps, with plots and GIS exports:
- Raster segmentation: compare algorithms, create object polygons, and export segment IDs and a GeoPackage.
- Raster object features: spectral summaries, indices, shape, texture, and analysis masks.
- Object classification: label objects from points, compare models, and save predictions and a reusable classifier.
- Pixel classification: learn from labelled pixels, predict another area, and export a raster class map.
From the repository root, install the notebook dependencies and launch JupyterLab:
python -m pip install -e ".[notebooks]"
jupyter lab
Open docs/examples/ in JupyterLab.
See the notebook setup guide for details.
Documentation
Read the documentation for the full workflow. Optional guides cover point-cloud features, large rasters, and experimental detection.
To preview the docs from a repository checkout:
python -m pip install -e ".[docs]"
mkdocs serve
Open http://127.0.0.1:8000. If the port is already in use:
mkdocs serve -a 127.0.0.1:8001
Documentation source lives in docs/.
License
MIT (LICENSE)
Metadata
Release files for obia 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| obia-0.2.0.tar.gz | 5.6 MB | With provenance | Details for obia-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| obia-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for obia-0.2.0-py3-none-any.whl |
Total release size: 11.2 MB
Release files / obia-0.2.0.tar.gz
| Download URL | obia-0.2.0.tar.gz |
|---|---|
| Size | 5.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
18cf45e414d8de4a1ab4dfc70cd091f82f19527959331c58915fea13bb147107
|
|
BLAKE2b-256 checksum How to use checksums |
36757c1c58622f3faf1af8aa6d107216989922c8d83b202f396736c38acf551e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logRelease files / obia-0.2.0-py3-none-any.whl
| Download URL | obia-0.2.0-py3-none-any.whl |
|---|---|
| Size | 5.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
37ce86a8f10d9556ce93e37c8f1bcc0349ed432604a275b5edef13ab4fb1a39b
|
|
BLAKE2b-256 checksum How to use checksums |
b8bd4e38fdce738ead3931e95bf56802bce913bd4eefbce2708bca844d9d4b1d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logSecurity for obia 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for obia-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.