Quickstart¶

This tutorial walks through a basic field boundary delineation workflow in under five minutes.

Prerequisites¶

Python >= 3.10 with agribound installed.
A study area boundary file (GeoJSON, Shapefile, or GeoParquet).
For GEE-based sources: a Google Earth Engine project with authentication configured. See GEE Setup.

Install the required extras for this tutorial:

pip install agribound[gee,delineate-anything]

Python Usage¶

Basic Delineation¶

import agribound

gdf = agribound.delineate(
    study_area="my_area.geojson",
    source="sentinel2",
    year=2024,
    engine="delineate-anything",
    gee_project="my-gee-project",
)

print(f"Detected {len(gdf)} field boundaries")
print(gdf.head())

The pipeline will:

Build a cloud-free annual composite from Sentinel-2 imagery via GEE.
Run the Delineate-Anything model to extract field boundaries.
Post-process polygons (merge overlapping tiles, filter small areas, simplify).
LULC crop filter — automatically remove non-agricultural polygons (roads, water, forest, urban) using the best available land cover dataset for your region.
Export results to fields_sentinel2_2024.gpkg.

Automatic crop filtering

Agribound is the only field boundary package that automatically filters output to agricultural areas. It uses NLCD (CONUS, 1985–2024), Dynamic World (global, 2015–present), or C3S Land Cover (global, pre-2015, 1992–2022) depending on your study area location and year. Disable with lulc_filter=False for non-agricultural use cases or local files without GEE access.

Using a Configuration Object¶

For more control, build an AgriboundConfig first:

from agribound import AgriboundConfig, delineate

config = AgriboundConfig(
    study_area="my_area.geojson",
    source="sentinel2",
    year=2024,
    engine="delineate-anything",
    gee_project="my-gee-project",
    output_path="output/fields.gpkg",
    composite_method="greenest",
    min_field_area_m2=5000,
)

gdf = delineate(config=config, study_area=config.study_area)

Using a Local GeoTIFF¶

If you already have satellite imagery on disk:

gdf = agribound.delineate(
    study_area="my_area.geojson",
    source="local",
    engine="delineate-anything",
    local_tif_path="composite.tif",
)

Visualizing Results¶

m = agribound.show_boundaries(gdf)
m  # displays in Jupyter

CLI Usage¶

Run Delineation¶

agribound delineate \
    --study-area my_area.geojson \
    --source sentinel2 \
    --year 2024 \
    --engine delineate-anything \
    --gee-project my-gee-project \
    --output fields.gpkg

Using a YAML Config File¶

agribound delineate --config run_config.yaml

Where run_config.yaml contains:

study_area: my_area.geojson
source: sentinel2
year: 2024
engine: delineate-anything
gee_project: my-gee-project
output_path: fields.gpkg
composite_method: median
min_field_area_m2: 2500

List Available Resources¶

agribound list-engines
agribound list-sources

Viewing Results¶

The output GeoPackage (or GeoJSON/GeoParquet) can be opened in:

QGIS -- drag and drop the .gpkg file.
Python -- geopandas.read_file("fields.gpkg").
Jupyter -- use agribound.show_boundaries(gdf) for an interactive map.

Each output polygon includes metadata columns:

Column	Description
`id`	Unique field identifier
`metrics:area`	Field area in square meters
`metrics:perimeter`	Field perimeter in meters
`determination:method`	Always `auto-imagery`
`determination:datetime`	Target year
`agribound:engine`	Engine used for delineation
`agribound:source`	Satellite source
`agribound:year`	Target year
`lulc:crop_fraction`	Crop probability/fraction from LULC filter (when `lulc_filter=True`)

Examples¶

Fifteen example scripts and Jupyter notebooks demonstrate workflows spanning six continents, eight satellite sources, and all delineation engines. See the examples README for full details.

Situation	Approach	Example
Reference boundaries available	DINOv3 + SAM2 per source	Example 14
No reference boundaries	Embedding clustering + LULC filter + SAM2	Example 15
Multi-model ensemble	All engines on same sensor, majority vote	Example 12
Multi-year time series	Single engine per year, fine-tune once	Example 01
Quick local test	Delineate-Anything on local GeoTIFF	Example 10