Computer vision application over satellite RGB tiles for agricultural land detection
Note: This is a short 3-hour LLM pass with Claude on an old repo which brings it up to date.
GIS polygons with land use classes (e.g. crop types) are rasterized onto Web Mercator satellite tiles, and a U-Net with an ImageNet pretrained encoder (segmentation_models_pytorch) is trained to label each pixel.
Requires Python 3.11+ and uv. GDAL comes with the
rasterio/pyogrio wheels, no system packages are needed. Training uses an
NVIDIA GPU (CUDA) or Apple Silicon GPU (MPS) when available.
git clone https://github.com/worldbank/cv4ag.git; cd cv4ag
uv sync
uv run pytest # optional: tests, including the pipeline on synthetic fields
Run commands with uv run python cv4ag.py ... (or activate .venv).
Example: corn and soybeans in a Minnesota county, with crop labels from the USDA Cropland Data Layer and NAIP aerial imagery of the same year (both public domain, read from Microsoft Planetary Computer without an account):
uv run python cv4ag.py parse -s CDL_Query --arg1 "Le Sueur County, Minnesota" --arg2 2021 --arg3 data --arg4 Corn,Soybeans --top 2
uv run python cv4ag.py satellite -i data/CDL_Le_Sueur_County_Minnesota_2021.json --year 2021 --random -c 1000
uv run python cv4ag.py overlay -i data/CDL_Le_Sueur_County_Minnesota_2021.json --top 2
uv run python cv4ag.py train -i data/CDL_Le_Sueur_County_Minnesota_2021.json --top 2 --test
uv run python cv4ag.py ml -i data/CDL_Le_Sueur_County_Minnesota_2021.json
Own GIS data work the same way: parse -i fields.shp --key crop.
- parse converts any GDAL vector format to GeoJSON (raster class maps are polygonized) and prints the most frequent classes of
--key. Labels can also come from scripts (-s, see below). - satellite writes tiles centered on features (or at random positions within the data with
--random) todata/<name>/sat/and records their centers insat/tiles.csv. The default source is NAIP (--source naip, contiguous US, ~0.6-1 m, each state every 2-3 years;--year), reprojected onto Web Mercator tiles of zoom-z.--source mapboxuses the Mapbox Static Images API with aMAPBOX_TOKEN, but its terms do not allow training models or bulk downloads. - overlay writes one label image per tile to
train/(pixel value = class id, 0 = background, 1 = most frequent class) and a visual check image tocheck/. The tile footprint is computed exactly in Web Mercator and the features are reprojected to it before rasterizing. - train trains the U-Net. With
--test, about 20% of the tiles are moved to the test set by spatial blocks; training tiles that overlap a test tile are left out so the test score is not inflated by overlapping imagery. Without--test, tiles already intest/are used for testing and never for training. Classes are weighted by median frequency balancing of their pixel counts (--no-weightsto disable). The model with the best test mean IoU is saved toweights/model.pt, the log toweights/train_log.csv. - ml classifies the images in
test/: class ids toout/<image>.png, image | prediction | label toout/<image>_vis.png, and per-class IoU/precision/recall toout/metrics.json.
scripts/CDL_Query.py reads the USDA Cropland Data Layer (30 m, contiguous US,
2008-2021) for --arg1 (place name or boundary box "west south east north")
and year --arg2. Speckles below 5 pixels are merged into their neighbours and
the map is polygonized with the class name in Descriptio (e.g. Corn,
Soybeans, Spring Wheat). --arg4 keeps only the given classes; everything
else becomes background. Crops rotate, so use NAIP imagery of the same year.
The CDL is a 30 m classification with its own errors, so labels are blocky at
field edges.
Without own GIS data, land use polygons can be downloaded from OpenStreetMap
with the Overpass API (closed ways and multipolygon relations, cached in _cache_overpass/):
uv run python cv4ag.py parse -s OSM_Query --arg1 "Le Sueur County, Minnesota" --arg2 landuse --arg3 data
--arg1 is a place name or ISO country code (looked up with Nominatim) or a
boundary box "west south east north", --arg2 the OSM tag (e.g. landuse or
landuse=farmland). The tag value is stored in Descriptio (the default --key);
all other OSM tags are kept as properties, e.g. --key crop where crops are mapped.
OSM coverage is incomplete, so unmapped fields end up as background; consider
--no-background for training.
usage: cv4ag.py [-h] [-i FILE] [-s FILE] [-o PATH] [--source {naip,mapbox}]
[--year N] [-c N] [-z N] [-x N] [-y N] [-d FILETYPE_CODE]
[-n N] [--lonshift N.N] [--latshift N.N] [--shiftformat N]
[--top N] [--key KEY] [--epsg N] [--layer N] [--mode MODE]
[--sat SAT] [--batchsize N] [--stepsize N.N] [--maxiter N]
[--encoder ENCODER] [--seed N] [--arg1 ARG1] [--arg2 ARG2]
[--arg3 ARG3] [--arg4 ARG4] [--test | --no-test]
[--background | --no-background] [--random | --no-random]
[--weights | --no-weights] [--pretrained | --no-pretrained]
[--compares | --no-compares]
OPTION [MAPBOX_TOKEN]
Machine Learning Framework for Agricultural Data.
positional arguments:
OPTION The modules to be loaded. OPTION: all - all modules
(except clear). parse - input file parser. satellite -
get satellite data. overlay - overlay classification
with satellite data. train - train. ml - apply machine
learning algorithm. clear - clear generated data from
previous run on input file
MAPBOX_TOKEN Mapbox token to download satellite images (only for
--source mapbox).
options:
-h, --help show this help message and exit
-i FILE Input file. Do not give if data obtained by script.
-s FILE Script file to obtain data
-o PATH Output folder. Satellite data are put in and read from
PATH/sat/.
--source {naip,mapbox}
Satellite images: naip (USDA aerial imagery, US only,
no account needed; default) or mapbox (needs
MAPBOX_TOKEN; its terms do not allow training models).
--year N Year of NAIP imagery (default 2021). Use the year of
the labels.
-c N Number of satellite images to download.
-z N Zoom level. Min=15, Max=19. See
libs/zoomLevelResolution.csv for resolutions.
-x N Images have width N pixel.
-y N Images have height N pixel.
-d FILETYPE_CODE Specify file type. Will find to detect filetype
automatically. Will not prompt for vector conversion
if not given. See www.gdal.org/formats_list.html or
www.gdal.org/ogr_formats.html (or libs/*_formats.csv
for FILETYPE_CODEs.
-n N Size of neural net. 0: smallest (ResNet-18 encoder).
3: largest (ResNeXt-50 encoder).
--lonshift N.N Longitudanal shift of training data.
--latshift N.N Lateral shift of training data .
--shiftformat N Format of longitudinal/lateral shift. 0: As fraction
of image. 1: Meters.
--top N Get N most frequent classes.
--key KEY Set parameter key for category in GIS file to classify
data.
--epsg N EPSG format for GIS data. Is read from data if not
set.
--layer N Number of layers to be trained on.
--mode MODE GPU (default) or CPU mode
--sat SAT Folder with training satellite images, if not in
standard location.
--batchsize N Size of training batch (default 8)
--stepsize N.N Learning rate (default 5e-4)
--maxiter N Maximum iterations at training stage
--encoder ENCODER Encoder of the U-Net, overrides -n (any
segmentation_models_pytorch encoder, e.g. resnet34)
--seed N Random seed for the train/test split and training
--arg1 ARG1 Argument 1 for script.
--arg2 ARG2 Argument 2 for script.
--arg3 ARG3 Argument 3 for script.
--arg4 ARG4 Argument 4 for script.
--test Create test set.
--no-test Do not create test set (default)
--background Classify background for training (default)
--no-background Ignore background for training.
--random Use random images within GIS boundary box.
--no-random Only use images with features (default).
--weights Weight classes inversely to their pixel frequency
(default).
--no-weights Weight all classes equally.
--pretrained Start from ImageNet weights (default).
--no-pretrained Train from scratch.
--compares Compare classified results with labels
--no-compares Do not compare classified results with labels
See LICENCE.md
https://github.com/qubvel-org/segmentation_models.pytorch (earlier versions: https://github.com/alexgkendall/caffe-segnet)