Region of Interest (ROI)

Regions of Interest (ROIs) define spatial boundaries for Earth Observation (EO) workflows in OCLI. They serve as geospatial filters for satellite data Finders, bounding extents for stack Processors, and spatial domains for AI Knowledge Pack (AIKP) analytics.

ROI in OCLI Workflows

When working with satellite imagery (Category A: ROI-required AIKPs), a task relies on an associated ROI to:

Search and filter satellite catalogs (e.g. Sentinel-1, Sentinel-2, Landsat-8) for scenes covering the target area.
Calculate spatial overlap and coverage (fit metric).
Subset, crop, or set bounding boxes during stack generation (ocli task make stack sarpy --bbox_by_roi).
Constrain output tensor assemblies and Cloud-Optimized GeoTIFF (COG) visualizations.

All ROIs within an OCLI project are stored in the project database in EPSG:4326 (WGS 84) longitude/latitude coordinates.

Adding Regions of Interest

The ocli roi add command allows you to define an ROI either from a vector file or directly from an inline Well-Known Text (WKT) string.

1. Adding ROI from an Inline WKT String

You can specify a polygon or multipolygon geometry directly on the command line using -wkt / --wkt:

# Add ROI from WKT (coordinates in EPSG:4326 longitude/latitude)
ocli roi add -n my_roi -wkt "MULTIPOLYGON (((4.88 52.36, 4.92 52.36, 4.92 52.39, 4.88 52.39, 4.88 52.36)))"

Specifying Custom CRS for WKT

If your coordinates are in a projected coordinate reference system (such as UTM or Web Mercator), supply --crs. OCLI will automatically reproject the geometry to EPSG:4326:

# WKT defined in UTM zone 31N (EPSG:32631) - automatically reprojected to EPSG:4326
ocli roi add -n roi_utm -wkt "POLYGON ((628000 5804000, 632000 5804000, 632000 5808000, 628000 5808000, 628000 5804000))" --crs "EPSG:32631"

# WKT defined in Web Mercator (EPSG:3857)
ocli roi add -n roi_wm -wkt "POLYGON ((...))" --crs "EPSG:3857"

2. Adding ROI from a Vector File

You can also load geometry from vector files (GeoJSON, ESRI Shapefile, GeoPackage, KML):

# Load from GeoJSON (CRS embedded in file)
ocli roi add boundary.geojson -n my_roi

# Load from file with an explicit CRS override (e.g., if the file lacks projection metadata)
ocli roi add boundary.geojson -n my_roi --crs "EPSG:32631"

Note: The FILE argument and -wkt / --wkt option are mutually exclusive. Exactly one source of geometry must be provided.

Managing ROIs

Listing ROIs

View all registered ROIs, their bounding boxes, and metadata:

ocli roi list

Exporting an ROI

Export a stored ROI to a GeoJSON or other vector format:

ocli roi export -r my_roi -f GeoJSON exported_roi.geojson

Deleting ROIs

# Delete a specific ROI
ocli roi delete -r my_roi

# Delete all ROIs in the project (prompts for confirmation unless -y is passed)
ocli roi delete --all -y

Attaching ROI to AIKP Tasks

When creating a task, associate the ROI using the --roi flag:

# Create task and associate with an ROI
ocli task create -t ocli.pro.aikp.scalar_index.iceye --roi my_roi -n my_iceye_task -a

# Or set ROI on an existing task:
ocli task set roi=my_roi

For stack generation bounded to the ROI extent:

ocli task make stack sarpy --bbox_by_roi