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

### 5. Finder search
```
product load
```
After the task has been configured, the user can search for available satellite products using the built-in OCLI Finder system.
The `product load` command searches for Sentinel-2 scenes that match the task parameters, including the region of interest, specified date range, cloud cover, and other configured search criteria.
The AIKP does not implement the product search directly. It uses the OCLI Finder selected through the `sat_family_name` parameter. For Sentinel-2 data, the value `s2` selects the corresponding Sentinel-2 Finder.
The Finder sends a request to the configured remote data provider and adds the matching satellite products to the task. At this stage, the task contains a list of candidate products, but a specific product has not yet been selected for further processing.

### 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)
``` bash
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
```shell
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.