Mondrian AIKP (ocli.aikp.mondrian.s2)

Prerequisites

Region of Interest (ROI) in KML or GeoJSON format in the backend and added to the active project. If needed either rsync or drag-n-drop the ROI from local to, for example, /home/user_name/OCLI/USER_UPLOADS/...

roi list
roi add -n roi_name /home/user_name/OCLI/USER_UPLOADS/.../roi_name.geojson

Running the AIKP Workflow (Step-by-Step)

1. Task creation

task create -t ocli.aikp.mondrian.s2 --roi roi_name -n Mondrian --activate

The user creates a new task using the Mondrian template.
This triggers the OCLI framework to load the mondrian.s2.Template class and instantiate a task.
The template’s class method Template.create_task runs, which populates the task’s configuration with default values.
It then calls OCLI’s finder utility to inject default search filters (like date range, cloud cover) based on the sat_family_name='s2'.
At this point, the task config knows it’s dealing with a Sentinel-2 imagery product and has placeholders for search criteria.
For example, index_kind is set to a default (“NDVI”) and directories for outputs (stack_results, ai_results) are set.
The task is now initialized with all required config fields.

2. Task configuration & validation

task set index_kind=NDWI  ## other options are NDVI and NDMI
task set finder.startDate=2024-12-01

The user can list or modify task parameters before proceeding.
Running task show would display all config entries injected by the template (paths, ROI, index_kind, etc.), and a command like task set index_kind=NDWI lets the user choose a different index to compute.
Whenever a task parameter is changed via task set, the template’s validate_task method is invoked to ensure the new value is acceptable.
In Mondrian’s case, validate_task checks that required paths are provided and that index_kind is one of the supported options (“NDVI”, “NDWI”, or “NDMI”).
If an invalid value is given, it returns an error prompting the allowed choices. This validation logic is important for guiding the user (or developer) to provide correct inputs, and can be extended in a new AIKP template to validate any custom parameters.

4. Sentinel-2 scene selection

product list

This displays the results found in step 3.
Each result will have an identifier.
The user inspects the list (perhaps choosing the scene with the best fit or a specific date) and then selects one:

task set master=<scene_id>

The template intercepts this selection. Mondrian’s template uses the finder to resolve the chosen product’s details – it takes the short ID or index that the user provided and looks up the full product metadata.
As a result, the task config is updated: task.config['master'] now holds the full name of the Sentinel-2 product (e.g., the long SAFE filename). task.config['master_path'] is set to the expected local path where this product will be stored (combining the eodata base path with the product identifier).
In other words, after this step the task “knows” exactly which Sentinel-2 scene to use and where on disk it will reside.
The design pattern here is that the user just does task set master ... and the template takes care of the rest behind the scenes.

5. Selected scene retrival

task get -m --data

The -m flag tells OCLI to use the task’s Finder to download the master dataset (the selected Sentinel-2 scene).
The OCLI framework uses the information in master/master_path to either initiate a download from the source (if not already present) or verify that the data exists locally.
After this command, the raw Sentinel-2 imagery (a folder of .SAFE data) is available on the local file system (in the eodata directory).
Mondrian’s template did not need additional code for this step; by leveraging OCLI’s finder and the configured master_path, data retrieval is handled generically.

At this point, all input data for the analysis is in place.

6. Stack preparation from the raw data

task make stack s2

Next, the user generates a Stack of input layers from the raw data.
This invokes OCLI’s built-in Sentinel-2 stacking Processor. The Stack Processor reads the downloaded Sentinel-2 product and extracts bands, resampling them to a common (highest) resolution and alignment.
The OCLI stack routine will create raster files for each of the bands (in designated stack_results directory).
Essentially, this step converts the raw satellite data into a set of first level analysis-ready layers (e.g. each band as a georegistered image).

The AIKP developer’s responsibility here is minimals; the heavy lifting of reading and warping satellite data is done by the framework.
After this step, the task has a prepared stack of inputs-ready for the analytic assembly.

Keep in mind that the created Stack will include all the bands available in “raw” satellite image, since it does not know or communicate with your assemble_recipe.py’s input_list.

ai preview stack -l

Just to validate all Sentinel-2 bands are present (even thou not all need to be used by the Assembler).

7. Recipe assembly

task make recipe --zone-by-roi --override

This generates a JSON recipe that describes the analysis to be performed, including references to the ROI and placeholders for input/output data.
When this command runs, OCLI calls the template’s update_recipe method to fill in any template-specific details in the recipe.
Mondrian’s Template.update_recipe ensures that the recipe’s products section contains only the selected index. It reads the task’s index_kind (e.g. NDWI if the user changed it) and injects that into the recipe structure, removing other indices. It also tags the recipe with metadata (like adding a “scalar_index” tag to indicate the output is a single-band index).
The resulting recipe JSON (saved under the task, e.g. zone_tnsr.json) will have entries such as the chosen index name, and references to the input stack files and output file names as defined in assemble_recipe.py.

This recipe acts as a contract between the template and the assembler – it tells the assembler what to assemble.

8. Tensor assembly (computation)

ai basic assemble zone

This triggers OCLI’s Assembler to execute Mondrian’s assembly logic on the specified zone (the ROI).
The Assembler loads mondrian.s2.assemble_recipe module and does the following:

  • finds the list of input files from input_list and opens each required band file from the Stack

  • sets up the output array file names (tnsr_fnames) and prepares to generate the output in the task’s ai_results directory

  • calls the assemble_kernel(inputs, outputs, bad_pixels) function

  • within assemble_kernel, the code selects the appropriate index formula based on the recipe’s product

  • code uses a helper to fetch each band and handle no-data (bad pixels) masking

  • compute index

  • output is saved as a .npy file (and an ENVI header .hdr and JSON metadata) in the ai_results folder, using the filenames defined in tnsr_fnames (e.g. zone_tnsr.npy for the ROI zone).

The assemble template focuses purely on the computation logic.

9. Visualize the results / custom commands

task template visualize zone

Mondrian provides a custom visualization step to convert the Tensor/numPy array index values into a colored image as a custom visualize function defined in mondrian/cli.py The function loads the assembled index array (zone_tnsr.npy) using the known file naming conventions (via the Filenames helper).
It then applies color mapping: in Mondrian’s case, several thresholds are applied to the index values to assign colors (white, red, blue, yellow, etc.).
An alpha channel is also set (making areas with no data transparent).
The function uses the ocli.core.envi utility to save the colored image as an ENVI raster (pred8c file, meaning an 8-bit RGBA image) with geospatial referencing.
After this step, the task’s ai_results directory contains a human-viewable raster map of the index.

This custom command showcases how the template can extend functionality – for a different AIKP, it could be implementation of other post-processing or visualization logic in a similar way (e.g., generating plots, combining layers, etc.).
The CLI integration is done by registering the command in the template class (cli_task_mount adds the visualize command), making it seamlessly available to the CLI user as part of the task’s commands.

10. Final steps

ai makecog zone
ai makegeojson
ai upload
ai publish post

At this point, the analytic part of the workflow is complete – the user has their result.
Further generic steps include converting the ENVI file to a Cloud-Optimized GeoTIFF, creating GeoJSON metadata, uploading to cloud storage, and publishing to a webUI.
These steps are standardized by OCLI and not specific to Mondrian, so the template does not override them.
Essentially, once the template has produced the final raster, it hands off to the common pipeline for packaging and sharing the result.
In a typical geospatial AIKP, following this pattern means you can rely on existing tools for output dissemination without writing extra code.