Skip to main content

OBIA

PyPI PyPI Downloads Docker Pulls Tests Docs Contributors License

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)

Source distribution for obia 0.2.0
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)

Table of built distributions (wheels) for obia 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page