# 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:
1. Search and filter satellite catalogs (e.g. Sentinel-1, Sentinel-2, Landsat-8) for scenes covering the target area.
2. Calculate spatial overlap and coverage (`fit` metric).
3. Subset, crop, or set bounding boxes during stack generation (`ocli task make stack sarpy --bbox_by_roi`).
4. 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`:

```bash
# Add ROI from WKT (coordinates in EPSG:4326 longitude/latitude)
ocli roi add -n AOI_268 -wkt "MULTIPOLYGON (((51.330414557 35.67446764, 51.272310927 35.662923419, 51.256233783 35.708678362, 51.314118675 35.720178725, 51.330414557 35.67446764)))"
```

#### 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:

```bash
# WKT defined in UTM zone 37N (EPSG:32637) - automatically reprojected to EPSG:4326
ocli roi add -n roi_utm -wkt "POLYGON ((386341 4956321, 391823 4954910, 390234 4950123, 384752 4951534, 386341 4956321))" --crs "EPSG:32637"

# 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):

```bash
# 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:32637"
```

> **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:
```bash
ocli roi list
```

### Exporting an ROI
Export a stored ROI to a GeoJSON or other vector format:
```bash
ocli roi export -r my_roi -f GeoJSON exported_roi.geojson
```

### Deleting ROIs
```bash
# 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:

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

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

For stack generation bounded to the ROI extent:
```bash
ocli task make stack sarpy --bbox_by_roi
```