composite_single AIKP (ocli.aikp.composite_single.sentinel_2)

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. Project creation

create -n project_name
activate project_name

Create a new OCLI project with the specified name and activate it for further configuration and processing.

2. Adding a region of interest

Before creating a task, add a region of interest (ROI) to the project. The ROI defines the area for which satellite imagery will be searched and the final processing result will be generated.

roi add -n roi_name /root/OCLI_HOME/USER_UPLOADS/rois/roi_name.geojson

3. Task creation

task create -t ocli.aikp.composite_single.sentinel_2 --roi roi_name -n task_name --activate

The user creates a new task using the AIKP template. This triggers the OCLI framework to load the composite_single.sentinel_2.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, composite_kind is set to a default (truecolor) and directories for outputs (stack_results, ai_results) are set.
The task is now initialized with all required config fields.

4. Task configuration & validation

task set composite_kind=falsecolor
task set finder.startDate=2026-01-01
task set finder.completionDate=2026-06-30

Supported values for composite_kind include truecolor, falsecolor, swir, agriculture, geology, bathymetry, atmosphericpenetration, healthyvegetation, land/water, snow, urban, burnt, and soilbright. Before proceeding, the user can view the current task configuration using:

task show

This command displays the parameters added by the task template, including the ROI, image search dates, composite type, paths, and other task settings. Task parameters can be modified using the task set command. Each time a parameter is changed, the template’s validate_task method checks whether the provided value is valid. If an unsupported value is entered, OCLI returns an error indicating the accepted options. The validation logic ensures that all required parameters are provided and can be extended in a custom AIKP template to validate additional task-specific settings.

6. Sentinel-2 scene selection

product list

This displays the results found in step 5.
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 handles this selection. The AIKP template uses the Finder to resolve the selected product details - it takes the short product ID or list index provided by the user and retrieves the complete product metadata. As a result, the task configuration is updated: task.config['master'] contains the full Sentinel-2 product identifier, such as the complete SAFE product name. task.config['master_path'] contains the expected local path where the product will be stored, constructed from the EO data base path and the product identifier. After this step, the task “knows” which Sentinel-2 scene to use and where it is expected to be stored locally. The user only needs to run task set master ... - the template automatically updates the related configuration parameters.

7. Selected scene retrival

task get -m --data

The -m flag tells OCLI to download the master dataset selected through the task’s Finder. Using master and master_path, OCLI downloads the Sentinel-2 product if necessary or verifies that it is already available locally. After the command completes, the raw .SAFE data is stored in the EO data directory. No additional AIKP-specific code is required, as data retrieval is handled by the OCLI Finder. At this point, the input data is ready for processing.

8. Stack preparation from the raw data

task make stack s2

Next, the user creates a stack of input layers from the raw Sentinel-2 data. The built-in Stack Processor extracts the available bands, resamples them to a common (highest) resolution and alignment, and saves each band as a georeferenced raster in the stack_results directory. Most data reading and resampling is handled by OCLI, so minimal AIKP-specific code is required. After this step, the input layers are ready for tensor assembly. The stack includes all bands available in the raw product because the Stack Processor does not use the input_list defined in assemble_recipe.py.

ai preview stack -l

This command displays the image band stack, allowing the user to review all available Sentinel-2 bands before recipe assembly.

9. Filtering

Filtering is controlled by two task parameters: denoising.sigma.algorithm specifies the filtering method. denoising.sigma.parameters specifies the filter parameters. Filtering is disabled by default. To enable anisotropic diffusion filtering, run:

task set denoising.sigma.algorithm=anisotropic_diffusion

The default parameters for this filter are [15, 1.5, 0.2, None, 3]. The parameters can be changed, for example:

task set denoising.sigma.parameters='[10, 5.0, 0.2, None, 3]'

This AIKP supports only the anisotropic_diffusion filter. The OCLI PRO version also provides the following filters:

  • nlmd - Non-Local Means Denoising;

  • gabor - Gabor filtering;

  • bm3d - Block-Matching and 3D filtering;

  • bm3d_with_post - Block-Matching and 3D filtering with post-processing.

10. Recipe assembly

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

This command generates a JSON recipe describing the analysis, including the selected ROI, input stack files, and output data.

When the recipe is created, OCLI calls the template’s update_recipe method to add AIKP-specific settings. The method reads the selected composite_kind, keeps only the corresponding composite in the recipe’s products section, and adds relevant metadata. The resulting recipe, saved under the task as a file such as zone_tnsr.json, contains the selected composite and the input and output file definitions from assemble_recipe.py. The recipe acts as a contract between the template and the Assembler, defining what data must be processed and what result must be produced.

11. Tensor assembly (computation)

ai basic assemble zone

This triggers OCLI’s Assembler to execute AIKP’s assembly logic on the specified zone (the ROI).
The Assembler loads ocli.aikp.composite_single.sentinel_2.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 composite formula based on the recipe’s product;

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

  • compute composite;

  • 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.

12. Visualize the results / custom commands

task template visualize zone

The command provides a custom visualization step to convert the Tensor/numPy array composite values into a colored image as a custom visualize function defined in composite_single/cli.py 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 composite.
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.

13. Final steps

ai makecog zone
ai makegeojson
ai upload
ai publish post

At this stage, the analytical workflow is finished and the result has been generated. The common OCLI pipeline can then convert the ENVI raster to a Cloud-Optimized GeoTIFF, generate GeoJSON metadata, upload the files to cloud storage, and publish them in the web UI. By using this shared output pipeline, a geospatial AIKP can package and distribute its results without requiring additional implementation.