Agribound v0.1.3: Query Published FTW Polygons by AOI¶

Agribound v0.1.3 adds a data-access helper for the published Fields of The World (FTW) global field-boundary polygons. Instead of running FTW inference end-to-end, you can now pull pre-computed FTW predictions for any area of interest with a single function call -- backed by a PyArrow GeoParquet reader against the public Source Cooperative dataset.

This is agribound's second community contribution from Jeremy Rapp at the Department of Earth and Environmental Sciences, Michigan State University -- following his USGS NAIP Plus contribution in v0.1.2.

Why a query helper?¶

FTW already publishes high-quality field-boundary predictions over much of the globe. For many downstream use cases -- comparison layers, candidate field extents, regional analyses -- you don't need to re-run inference; you just need the polygons that intersect your AOI.

Before v0.1.3, getting those polygons meant manually navigating the Source Cooperative bucket, downloading parquet shards, filtering by bbox, and stitching results. The new agribound.query_ftw helper collapses that workflow into one call.

Python API¶

import agribound as ab

ftw = ab.query_ftw(
    study_area="examples/data/small_aoi.geojson",
    year=2025,
    label="field",
    clip=True,
    output_path="ftw_small_aoi.parquet",
)

The helper filters candidate polygons by AOI bbox, filters by label and year/time columns when present, deduplicates, optionally clips to the AOI, and writes GeoParquet, GeoJSON, or GeoPackage. For smoke tests or previews against the (large) public dataset, pass max_features to cap the result.

CLI¶

agribound query-ftw \
    --study-area examples/data/small_aoi.geojson \
    --year 2025 \
    --label field \
    --clip \
    --output ftw_small_aoi.parquet

Local manifest / tile mode¶

For offline workflows or prefiltered regional extracts, query_ftw also reads a local prepared FTW tile inventory:

ftw = ab.query_ftw(
    study_area="examples/data/small_aoi.geojson",
    year=2025,
    label="field",
    clip=True,
    source_backend="manifest",
    manifest_path="path/to/ftw_tile_manifest.parquet",
    tile_dir="path/to/ftw_tiles",
    output_path="ftw_small_aoi.parquet",
)

The manifest must include a tile path column (tile_path, out_path, path, url, href, or filename); a status column and bbox/geometry columns are used when present to prioritize and prune candidate tiles.

What's in the release¶

agribound.ftw_query -- the query helper plus a query-ftw CLI subcommand.
agribound.ftw_arrow -- PyArrow backend for the public Source Cooperative GeoParquet dataset, with AOI bbox pushdown and area masking.
Example 17 -- a runnable Python script and Jupyter notebook.
User guide -- the new FTW Polygon Query page.
Unit tests -- coverage for both the GeoParquet backend and the manifest/tile mode.

Interpretation¶

FTW polygons are model-derived predictions. They are useful as comparison layers and candidate field extents, but they should not be treated as ground truth without fit-for-purpose validation. This helper retrieves existing FTW predictions; it does not run FTW inference, host FTW data, or make FTW a reference product.

Thank you, Jeremy¶

Two contributions in two releases -- both adding genuinely new data access paths to agribound. Exactly the kind of community-driven extension we hoped agribound would enable. Thank you, Jeremy!

Get it¶

pip install --upgrade agribound

See the FTW Polygon Query guide for the full API, and the CHANGELOG for the complete v0.1.3 release notes.

Give the repo a star if you find it useful!