.. figure::  images/esa.jpg
   :align:   right
   :scale:   50%

.. _IODD:

Input Output Data Definition (IODD)
***********************************

Introduction
============

This is the Input / Output Data Definition document (IODD) for the Sen2Three application.
This document is produced in the context of the development of the Sentinel 2 Level 3 processor.

Purpose and Scope
-----------------

The purpose of the Input / Output Data Definition document (IODD) is to provide a precise description of
the input and output files and parameters as used and generated by the Sen2Three Level 3 processor.

Applicable Documents
--------------------

Table 4-1: Applicable Documents

+------------------+------+-------------------------------------------+----------+
| Reference        | Code | Title                                     | Issue    |
+==================+======+===========================================+==========+
| L3_DPMD          | ATBD | Level 3 ATBD                              | 1.0      |
+------------------+------+-------------------------------------------+----------+

Reference Documents
-------------------

Table 4-2: Reference Documents

+------------------+------+-------------------------------------------+----------+
| Reference        | Code | Title                                     | Issue    |
+==================+======+===========================================+==========+
| L3_SUM           | SUM  | Software Installation and User Manual     | 1.0      |
+------------------+------+-------------------------------------------+----------+
| L3_PFS           | PFS  | Product Format Specification              | 1.0      |
+------------------+------+-------------------------------------------+----------+
| L3_DPMD          | DPMD | Detailed Processing Model Documentation   | 1.0      |
+------------------+------+-------------------------------------------+----------+

Acronyms and Abbreviations
--------------------------

All acronyms and abbreviations are listed in [L3-GLODEF]

Document Structure
------------------

This is the final part of a set of four documents describing the Sentinel 2 Level 3 Processor for Spatio- Temporal
synthesis, consisting of:

1. Software Installation and User’s Manual (SUM);
2. Detailed Processing Model Documentation (DPMD);
3. Product Format Specification (PFS);
4. Input Output Data Definition (IODD), this document.

Input Data
==========

Sen2Three Input data are standard Level 2A products as generated and formatted by the Sen2Cor processor.
Using the option “–SC_ONLY”, Sen2Cor can also generate “pseudo” Level-2A Products, which have the same dimensioning
and formatting as standard Level-2A products, but contain non atmospheric corrected Level-1C input images, which can
be used for generating Level 3 composites. In the latter case, the Aerosol Optical Thickness map is not part of the
product.

*   **Ground Image Processing Parameter (GIPP):** These are the user configurable parameter driving the processing
    steps.

*   **Image Data** are the JPEG 2000 images and additional bitmaps, as retrieved during the preceding
    processing steps.

*   **Metadata:** All L3 Metadata are specific to the image products forming the **Input Data**. They are
    inherited from the corresponding L2A (input) metadata and are extended by the parameters obtained during
    the actual processing. The metadata are collected in three different xml tree like data structures which are
    separated as follows:

   *   L3 User Product Metadata;
   *   L3 Tile Metadata;
   *   L3 Datastrip Metadata;

In contrast to the GIPP, no user activated configuration change of these metadata is foreseen. The update of these data
will solely be driven by the processor.

Ground Image Processing Parameter (GIPP)
----------------------------------------

The GIPP are the user configurable parameter driving the processing steps. All GIPP are collected in an xml data
structure called **L3_GIPP.xml**. This is by default located in the cfg folder of the Sen2Three home directory.
The Sen2Three's home directory is referenced by the environment variable $SEN2THREE_HOME. Details as given in the
:ref:`Sen2Three Installation <inst>`. The class L3_Config, together with helper class L3_XmlParser provides the
necessary facilities for reading the GIPP. The tables below give an overview on the configuration parameters.
The complete xsd scheme is detailled in L3_GIPP_.

.. _L3_GIPP: http://step.esa.int/thirdparties/sen2three/1.1.0/sen2three-1.1.0_doc/_l3_gipp/L3_GIPP.html

Table 4-3: Log level configuration

+----------------------------------+-----------+
| Log_Level                        |           |
+----------------------------------+-----------+
| - Type: unsigned byte            |           |
| - Range: 0 - 5                   |           |
| - Description: level of logging. |           |
+----------------------------------+-----------+
| Key                              | Value     |
+==================================+===========+
| NOTSET                           | 0         |
+----------------------------------+-----------+
| DEBUG                            | 1         |
+----------------------------------+-----------+
| INFO                             | 2         |
+----------------------------------+-----------+
| WARNING                          | 3         |
+----------------------------------+-----------+
| ERROR                            | 4         |
+----------------------------------+-----------+
| CRITICAL                         | 5         |
+----------------------------------+-----------+

Table 4-4: Common configuration parameter

+------------------+---------+----------+-----------+-------------------------------------+
| Key              | Default | Type     | Range     | Description                         |
+==================+=========+==========+===========+=====================================+
| Display_Data     | false   | string   | n/a       | Flag for graphical display of data. |
+------------------+---------+----------+-----------+-------------------------------------+
| Target_Directory | DEFAULT | string   | n/a       | Location of output data.            |
+------------------+---------+----------+-----------+-------------------------------------+

Table 4-5: Level 3 synthesis

+------------------+---------+----------+-----------+--------------------------------------+
| Key              | Default | Type     | Range     | Description                          |
+==================+=========+====+=====+===========+======================================+
| Min_Time         | n/a     | time_str | n/a       | Lower border acquisition time.       |
+------------------+---------+----------+-----------+--------------------------------------+
| Max_Time         | n/a     | time_str | n/a       | Upper border acquisition time.       |
+------------------+---------+----------+-----------+--------------------------------------+
| Tile_Filter      | n/a     | str_list | n/a       | A list of tiles separated by blanks. |
+------------------+---------+----------+-----------+--------------------------------------+

Table 4-6: Algorithm

+------------------------------------+----------+
| Algorithm                          |          |
+====================================+==========+
| - Type: string                     |          |
| - Range: 1 - 4                     |          |
| - Description: the algorithm used. |          |
+------------------------------------+----------+
| **Key**                            | **Type** |
+------------------------------------+----------+
| MOST_RECENT                        | string   |
+------------------------------------+----------+
| TEMP_HOMOGENEITY                   | string   |
+------------------------------------+----------+
| RADIOMETRIC_QUALITY                | string   |
+------------------------------------+----------+
| AVERAGE                            | string   |
+------------------------------------+----------+

Table 4-7: Radiometric preference

+------------------------------------+----------+
| Radiometric_Preference             |          |
+====================================+==========+
| - Type: string                     |          |
| - Range: 1 - 2                     |          |
| - Description: for Radiometric     |          |
|   Quality only                     |          |
+------------------------------------+----------+
| **Key**                            | **Type** |
+------------------------------------+----------+
| AEROSOL_OPTICAL_THICKNESS          | string   |
+------------------------------------+----------+
| SOLAR_ZENITH_ANGLE                 | string   |
+------------------------------------+----------+

Table 4-8: Other options

+-------------------------------+---------+-------+---------+---------------------------+
| Key                           | Default | Type  | Range   | Description               |
+===============================+=========+=======+=========+===========================+
| Cirrus_Removal                | true    | bool  | 0 : 1   | Activate cirrus removal.  |
+-------------------------------+---------+-------+---------+---------------------------+
| Shadow_Removal                | true    | bool  | 0 : 1   | Activate shadow removal.  |
+-------------------------------+---------+-------+---------+---------------------------+
| Snow_Removal                  | true    | bool  | 0 : 1   | Activate snow removal.    |
+-------------------------------+---------+-------+---------+---------------------------+
| Max_Cloud_Probability         | n/a     | ubyte | 0 : 100 | Terminate if reached.     |
+-------------------------------+---------+-------+---------+---------------------------+
| Max_Invalid_Pixels_Percentage | n/a     | ubyte | 0 : 100 | Terminate if reached.     |
+-------------------------------+---------+-------+---------+---------------------------+
| Max_Aerosol_Optical_Thickness | n/a     | ubyte | 0 : 100 | Currently unused.         |
+-------------------------------+---------+-------+---------+---------------------------+
| Max_Solar_Zenith_Angle        | n/a     | ubyte | 0 : 70  | Currently unused.         |
+-------------------------------+---------+-------+---------+---------------------------+
| Median_Filter                 | 1       | ubyte | 1:3     | Smoothing of area borders.|
+-------------------------------+---------+-------+---------+---------------------------+

Table 4-9: Classification map

+----------------------------------------------------------------+-----------+
| Classificators                                                 |           |
+----------------------------------------------------------------+-----------+
| - Type: ubyte                                                  |           |
| - Range: 0 : 11                                                |           |
| - Description: classifies the pixel type of the current scene. |           |
+----------------------------------------------------------------+-----------+
| Key                                                            | Value     |
+================================================================+===========+
| NO_DATA                                                        | 0         |
+----------------------------------------------------------------+-----------+
| SATURATED_DEFECTIVE                                            | 1         |
+----------------------------------------------------------------+-----------+
| DARK_FEATURES                                                  | 2         |
+----------------------------------------------------------------+-----------+
| CLOUD_SHADOWS                                                  | 3         |
+----------------------------------------------------------------+-----------+
| VEGETATION                                                     | 4         |
+----------------------------------------------------------------+-----------+
| NOT_VEGETATED                                                  | 5         |
+----------------------------------------------------------------+-----------+
| WATER                                                          | 6         |
+----------------------------------------------------------------+-----------+
| UNCLASSIFIED                                                   | 7         |
+----------------------------------------------------------------+-----------+
| MEDIUM_PROBA_CLOUDS                                            | 8         |
+----------------------------------------------------------------+-----------+
| HIGH_PROBA_CLOUDS                                              | 9         |
+----------------------------------------------------------------+-----------+
| THIN_CIRRUS                                                    | 10        |
+----------------------------------------------------------------+-----------+
| SNOW_ICE                                                       | 11        |
+----------------------------------------------------------------+-----------+

Image Data
----------

The image data are provided in form of standard Level 2A data format as processed in advance by the Sen2Cor application.
The Sen2Three processor will check in ahead, which resolutions are provided in the input data and will only process those
resolutions which are available.

Table 4-10: Level 2A image data specification

+----------------------------+------------------------------------------------------------+
| Name                       | Level-2A Image Data                                        |
+============================+============================================================+
| Content                    | L2A, BOA Reflectance, orthorectified, georeferenced        |
+----------------------------+------------------------------------------------------------+
| Format                     | OpenJPEG 2.1.0                                             |
+----------------------------+------------------------------------------------------------+
| Packaging                  | Tiles                                                      |
+----------------------------+------------------------------------------------------------+
| Tile sizes                 | 60m: (1830^2), 20m: (5490^2), 10m: (10980^2)               |
+----------------------------+------------------------------------------------------------+
| Codeblock size             | 64 (default)                                               |
+----------------------------+------------------------------------------------------------+
| Order                      | RPCL                                                       |
+----------------------------+------------------------------------------------------------+
| Unit                       | Dimensionless, Unsigned Integer                            |
+----------------------------+------------------------------------------------------------+
| Calibration and Range      | Configurable 0 : MAX (10000) represents                    |
|                            | radiometric reflectance values from 0.0:1.0                |
+----------------------------+------------------------------------------------------------+
| Sampling                   | 16 bits/pixel, maximum is 10000                            |
+----------------------------+------------------------------------------------------------+
| **Input resolution**       | **Generated output resolution**                            |
+----------------------------+------------------------------------------------------------+
| B01 (443nm): 60m           | 60m                                                        |
+----------------------------+------------------------------------------------------------+
| B02 (490nm): 60m, 20m, 10m | 60m, 20m, 10m                                              |
+----------------------------+------------------------------------------------------------+
| B03 (560nm): 60m, 20m, 10m | 60m, 20m, 10m                                              |
+----------------------------+------------------------------------------------------------+
| B04 (665nm): 60m, 20m, 10m | 60m, 20m, 10m                                              |
+----------------------------+------------------------------------------------------------+
| B05 (705nm): 60m, 20m      | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| B06 (740nm): 60m, 20m      | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| B07 (783nm): 60m, 20m      | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| B08 (842nm): 10m           | 10m                                                        |
+----------------------------+------------------------------------------------------------+
| B8a (865nm): 60m, 20m      | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| B09 (945nm): 60m           | 60m                                                        |
+----------------------------+------------------------------------------------------------+
| B10 (1375nm): 60m          | No output generated, does not contain surface information. |
+----------------------------+------------------------------------------------------------+
| B11 (1610nm): 60m, 20m     | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| B12 (2190nm): 20m          | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| SC Map:                    | 60m, 20m, generated during SC processing.                  |
+----------------------------+------------------------------------------------------------+
| AOT: (n/a)                 | 60m, 20m, 10m, 16 bit, generated during AC processing.     |
+----------------------------+------------------------------------------------------------+

Output Data
===========

Output data are the JPEG 2000 images, the updated scene classification and additional
bitmaps as generated by the considered processing steps and the corresponding metadata.

Image Data
----------

Table 4-11: Level 3 image data specification

+----------------------------+------------------------------------------------------------+
| Name                       | Level-2A Image Data                                        |
+============================+============================================================+
| Content                    | L2A, BOA Reflectance, orthorectified, georeferenced        |
+----------------------------+------------------------------------------------------------+
| Format                     | OpenJPEG 2.1.0                                             |
+----------------------------+------------------------------------------------------------+
| Packaging                  | Tiles                                                      |
+----------------------------+------------------------------------------------------------+
| Tile sizes                 | 60m: (1830*1830), 20m: (5490*5490), 10m: (10980*10980)     |
+----------------------------+------------------------------------------------------------+
| Codeblock size             | 64 (default)                                               |
+----------------------------+------------------------------------------------------------+
| Order                      | RPCL                                                       |
+----------------------------+------------------------------------------------------------+
| Unit                       | Dimensionless, Unsigned Integer                            |
+----------------------------+------------------------------------------------------------+
| Calibration and Range      | Configurable 0 : MAX (10000) represents                    |
|                            | radiometric reflectance values from 0.0:1.0                |
+----------------------------+------------------------------------------------------------+
| Sampling                   | 16 bits/pixel, maximum is 10000                            |
+----------------------------+------------------------------------------------------------+
| **Input resolution**       | **Generated output resolution**                            |
+----------------------------+------------------------------------------------------------+
| B01 (443nm): 60m           | 60m                                                        |
+----------------------------+------------------------------------------------------------+
| B02 (490nm): 60m, 20m, 10m | 60m, 20m, 10m                                              |
+----------------------------+------------------------------------------------------------+
| B03 (560nm): 60m, 20m, 10m | 60m, 20m, 10m                                              |
+----------------------------+------------------------------------------------------------+
| B04 (665nm): 60m, 20m, 10m | 60m, 20m, 10m                                              |
+----------------------------+------------------------------------------------------------+
| B05 (705nm): 60m, 20m      | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| B06 (740nm): 60m, 20m      | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| B07 (783nm): 60m, 20m      | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| B08 (842nm): 10m           | 10m                                                        |
+----------------------------+------------------------------------------------------------+
| B8a (865nm): 60m, 20m      | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| B09 (945nm): 60m           | 60m                                                        |
+----------------------------+------------------------------------------------------------+
| B10 (1375nm): 60m          | No output generated, does not contain surface information. |
+----------------------------+------------------------------------------------------------+
| B11 (1610nm): 60m, 20m     | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| B12 (2190nm): 20m          | 60m, 20m                                                   |
+----------------------------+------------------------------------------------------------+
| SC map: 60m, 20m           | 60m, 20m, 10m, updated and resampled during L3 processing. |
+----------------------------+------------------------------------------------------------+
| Mosaic Map:                | 60m, 20m, 10m, generated during L3 processing.             |
+----------------------------+------------------------------------------------------------+

Metadata
--------

Table 4-12 below keeps a statistics of the contents of the scene classification map. The scene classification map
is located in the QI_DATA folder of the corresponding tile for the given resolution.

Table 4-12: Level 3 statistics on pixel level (absolute)

+----------------------------------------------------------------+
| L3_Classification_QI, absolute                                 |
+----------------------------------------------------------------+
| - Type: unsigned int                                           |
| - Range: 0 : 120560400                                         |
| - Description: count of all occurrences of classified pixel.   |
+----------------------------------------------------------------+
| Key                                                            |
+================================================================+
| TOTAL_PIXEL_COUNT                                              |
+----------------------------------------------------------------+
| NODATA_PIXEL_COUNT                                             |
+----------------------------------------------------------------+
| SATURATED_DEFECTIVE_PIXEL_COUNT                                |
+----------------------------------------------------------------+
| DARK_FEATURES_COUNT                                            |
+----------------------------------------------------------------+
| CLOUD_SHADOW_COUNT                                             |
+----------------------------------------------------------------+
| VEGETATION_COUNT                                               |
+----------------------------------------------------------------+
| NOT_VEGETATED_COUNT                                            |
+----------------------------------------------------------------+
| WATER_COUNT                                                    |
+----------------------------------------------------------------+
| UNCLASSIFIED_COUNT                                             |
+----------------------------------------------------------------+
| MEDIUM_PROBA_CLOUDS_COUNT                                      |
+----------------------------------------------------------------+
| HIGH_PROBA_CLOUDS_COUNT                                        |
+----------------------------------------------------------------+
| THIN_CIRRUS_COUNT                                              |
+----------------------------------------------------------------+
| SNOW_ICE_COUNT                                                 |
+----------------------------------------------------------------+

Table 4-13: Level 3 statistics on pixel level (percentage)

+----------------------------------------------------------------+
| L3_Classification_QI, percentage                               |
+----------------------------------------------------------------+
| - Type: float32                                                |
| - Range: 0.0 : 100.0                                           |
| - Description:                                                 |
| - NO_DATA - percentage relative to all pixels of image.        |
| - all other - percentage relative to all data pixels of image. |
+----------------------------------------------------------------+
| Key                                                            |
+================================================================+
| NODATA_PIXEL_PERCENTAGE                                        |
+----------------------------------------------------------------+
| SATURATED_DEFECTIVE_PIXEL_PERCENTAGE                           |
+----------------------------------------------------------------+
| DARK_FEATURES_PERCENTAGE                                       |
+----------------------------------------------------------------+
| CLOUD_SHADOW_PERCENTAGE                                        |
+----------------------------------------------------------------+
| VEGETATION_PERCENTAGE                                          |
+----------------------------------------------------------------+
| NOT_VEGETATED_PERCENTAGE                                       |
+----------------------------------------------------------------+
| WATER_PERCENTAGE                                               |
+----------------------------------------------------------------+
| UNCLASSIFIED_PERCENTAGE                                        |
+----------------------------------------------------------------+
| MEDIUM_PROBA_CLOUDS_PERCENTAGE                                 |
+----------------------------------------------------------------+
| HIGH_PROBA_CLOUDS_PERCENTAGE                                   |
+----------------------------------------------------------------+
| THIN_CIRRUS_PERCENTAGE                                         |
+----------------------------------------------------------------+
| SNOW_ICE_PERCENTAGE                                            |
+----------------------------------------------------------------+

Table 4-14 below keeps a statistics of the contents of the mosaic map. Each tile with an equivalent tile ID wil be
represented by an increasing tile number in the mosaic map, where it's tile ID can be matched to the corresponding
tile number. The mosaic map is located in parallel to the scene classification map in the QI_DATA folder of the
corresponding tile.

Table 4-14: Level 3 statistics on pixel level (mosaic map)

+-----------------------+---------+---------+-----------+---------------------------------+
| Key                   | Default | Type    | Range     | Description                     |
+=======================+=========+=========+===========+=================================+
| TILE_NUMBER           | n/a     | ubyte   | 1 : 255   | Number of tile in sequence.     |
+-----------------------+---------+---------+-----------+---------------------------------+
| PRODUCT_ID            | n/a     | string  | n/a       | The product ID                  |
+-----------------------+---------+---------+-----------+---------------------------------+
| TILE_ID               | n/a     | string  | n/a       | Tile ID referenced              |
|                       |         |         |           | by tile number (see above).     |
+-----------------------+---------+---------+-----------+---------------------------------+
| TILE_PIXEL_COUNT      | n/a     | ubyte   | 1 : 255   | Count of all pixels matching    |
|                       |         |         |           | the given tile ID.              |
+-----------------------+---------+---------+-----------+---------------------------------+
| TILE_PIXEL_PERCENTAGE | n/a     | float32 | 0 : 100.0 | Percentage of all pixels        |
|                       |         |         |           | matching the given tile ID.     |
+-----------------------+---------+---------+-----------+---------------------------------+
| TILE_DATE_TIME        | n/a     | time    | n/a       | Acquisition time stamp of       |
|                       |         | string  |           | tile referenced by tile nr.     |
+-----------------------+---------+---------+-----------+---------------------------------+
| TILE_AOT_MEAN         | n/a     | float32 | 0 : 100.0 | Mean AOT of tile                |
|                       |         |         |           | referenced by tile number.      |
+-----------------------+---------+---------+-----------+---------------------------------+
| TILE_SZA_MEAN         | n/a     | float32 | 0 : 70.0  | mean SZA of tile                |
|                       |         |         |           | referenced by tile number.      |
+-----------------------+---------+---------+-----------+---------------------------------+