.. _files:

.. index:: files

======================================================================
Files produced
======================================================================

.. contents:: Contents:
   :local:
   :depth: 3

.. _final-products:

Final products
--------------

.. _full-S2-tiles:
.. index:: S2 tiles

Orthorectified S2 tiles
+++++++++++++++++++++++++++++

:Content: Complete final product: concatenated orthorectified S1 images on S2
          grid

:Directory:  :ref:`%(output) <paths.output>`:samp:`/{{tilename}}/`

:File name:

    - :samp:`s1{{a|b}}_{{tilename}}_{{polarity}}_{{orbitdirection}}_{{orbitnumber}}_{{YYYYMMDD}}txxxxxx.tif` when the tile has been assembled from the concatenation of several S1 images
    - :samp:`s1{{a|b}}_{{tilename}}_{{polarity}}_{{orbitdirection}}_{{orbitnumber}}_{{YYYYMMDD}}t{{hhmmss}}.tif` when the tile has been produced from a single S1 image

    .. note::
        :math:`σ^0_{RTC}` calibrated files will have their name end in
        :file:`_NormLim.tif`

:File name format:

    - :samp:`{{flying_unit_code}}_{{tile_name}}_{{polarisation}}_{{orbit_direction}}_{{orbit}}_{{acquisition_stamp}}.tif`, see :ref:`[Processing].fname_fmt.concatenation <Processing.fname_fmt.concatenation>`
    - or,  :samp:`{{flying_unit_code}}_{{tile_name}}_{{polarisation}}_{{orbit_direction}}_{{orbit}}_{{acquisition_stamp}}_NormLim.tif`, see :ref:`[Processing].fname_fmt.lia_corrected <Processing.fname_fmt.lia_corrected>`

:Format: Float32 GeoTIFF, deflate compressed

:Metadata: The following metadata is added to the origin S1 images

    .. list-table::
      :widths: auto
      :header-rows: 1
      :stub-columns: 1

      * - Metadata
        - Value

      * - ``ACQUISITION_DATETIME``
        - time of the first S1 image
      * - ``ACQUISITION_DATETIME_1``
        - time of the first S1 image
      * - ``ACQUISITION_DATETIME_2``
        - time of the second S1 image
      * - ``CALIBRATION``
        - :ref:`chosen calibration option <Processing.calibration>`
      * - ``FLYING_UNIT_CODE``
        - :samp:`s1{{a|b}}`
      * - ``IMAGE_TYPE``
        - :samp:`GRD`
      * - ``INPUT_S1_IMAGES``
        - List of the input Sentinel-1 images used to generate this product
      * - ``LIA_FILE``
        - (when applies) name of the LIA file used for Normlim calibration
      * - ``NOISE_REMOVED``
        - :ref:`chosen noise removal option <Processing.remove_thermal_noise>`
      * - ``ORBIT``
        - :samp:`{{orbitnumber}}`
      * - ``ORBIT_DIRECTION``
        - :samp:`{{orbitdirection}}`
      * - ``ORTHORECTIFIED``
        - :samp:`true`
      * - ``POLARIZATION``
        - :samp:`{{polarisation}}`
      * - ``S2_TILE_CORRESPONDING_CODE``
        - :samp:`{{tilename}}`
      * - ``SPATIAL_RESOLUTION``
        - :ref:`chosen output spatial resolution option <Processing.output_spatial_resolution>`
      * - ``TIFFTAG_DATETIME``
        - is updated with the time when the tile has been generated by S1 Tiling.
      * - ``TIFFTAG_IMAGEDESCRIPTION``
        - :samp:`{{calibration}} calibrated orthorectified Sentinel-1{{A|B}} IW GRD on S2 tile`
      * - ``TIFFTAG_SOFTWARE``
        - :samp:`S1 Tiling v{{version}}` -- |version| currently

.. _mask-files:
.. index:: Mask files

Mask files
++++++++++

:Content:

    .. todo:: Thierry?

:Directory:  :ref:`%(output) <paths.output>`:samp:`/{{tilename}}/`

:File name: the same as the one from :ref:`the S2 tiles <full-S2-tiles>`, with
            `_BorderMask` appended

:Format: Byte GeoTIFF, deflate compressed

:Metadata: This file contains the same metadata as the one from :ref:`the S2 tile product <full-S2-tiles>` it has been generated from, with the following as the only difference:

    .. list-table::
      :widths: auto
      :header-rows: 1
      :stub-columns: 1

      * - Metadata
        - Value

      * - ``TIFFTAG_IMAGEDESCRIPTION``
        - :samp:`Orthorectified Sentinel-1A IW GRD smoothed border mask S2 tile`


.. _filtered-files:
.. index:: Filtered files

Filtered files
++++++++++++++

:Content:

    .. todo:: Thierry?

:Directory:  :ref:`%(output) <paths.output>`:samp:`/filtered/{{tilename}}/`

:File name: the same as the one from :ref:`the S2 tiles <full-S2-tiles>`, with
            `_filtered` appended

:File name format:

    - :samp:`{{flying_unit_code}}_{{tile_name}}_{{polarisation}}_{{orbit_direction}}_{{orbit}}_{{acquisition_stamp}}_filtered.tif`, see :ref:`[Processing].fname_fmt.filtered <Processing.fname_fmt.filtered>`
    - or,  :samp:`{{flying_unit_code}}_{{tile_name}}_{{polarisation}}_{{orbit_direction}}_{{orbit}}_{{acquisition_stamp}}_NormLim_filtered.tif`

:Format: Float32 GeoTIFF, deflate compressed

:Metadata: This file contains the same metadata as the one from :ref:`the S2 tile product <full-S2-tiles>` it has been generated from, with the following as the only difference:

    .. list-table::
      :widths: auto
      :header-rows: 1
      :stub-columns: 1

      * - Metadata
        - Value

      * - ``FILTERED``
        - :samp:`true`

      * - ``FILTERING_METHOD``
        - The method used:
          :samp:`Lee`/:samp:`Frost`/:samp:`gammamap`/:samp:`Kuan`

      * - ``FILTERING_WINDOW_RADIUS``
        - The window radius used.

      * - ``FILTERING_DERAMP``
        - The deramp factor used (only for Frost method)

      * - ``FILTERING_NBLOOKS``
        - The number of looks used (only for Lee, Gammamap and Kuan methods)


.. _lia-files:
.. index:: Local Incidence Angle map files

Local Incidence Angle map files
+++++++++++++++++++++++++++++++

:Content:

    - Map of sines of Local Incidence Angle (LIA),
    - and optionally of LIA expressed in degree and scaled by a factor of 100.

    Given T, the target point on Earth's surface, and S the SAR sensor
    position, the LIA is the angle Θ\ :sub:`LIM` between the ground normal
    projected in range plane :math:`\overrightarrow{n}` (plane defined by S,
    T, and Earth's center) and :math:`\overrightarrow{TS}`.

    The values have been orthorectified on the Sentinel-2 tile from a pair of
    :ref:`LIA maps computed on S1 images <lia-s1-files>`.

:Directory:  :ref:`%(output_lia)/ <paths.lia>`

:File names:

    - :samp:`sin_LIA_s1{{a|b}}_{{tilename}}_{{orbitdirection}}_{{orbitnumber}}.tif` -- :math:`sin(Θ_{LIM})`
    - :samp:`LIA_s1{{a|b}}_{{tilename}}_{{orbitdirection}}_{{orbitnumber}}.tif` -- :math:`100 * Θ°_{LIM}`

:File name format:

    :samp:`{{LIA_kind}}_{{flying_unit_code}}_{{tile_name}}_{{orbit_direction}}_{{orbit}}.tif`, see :ref:`[Processing].fname_fmt.lia_product <Processing.fname_fmt.lia_product>`

:Format: Float32 (and Int16) GeoTIFF, deflate compressed

:Metadata: The following metadata is added to the origin S1 images

    .. list-table::
      :widths: auto
      :header-rows: 1
      :stub-columns: 1

      * - Metadata
        - Value

      * - ``ACQUISITION_DATETIME``
        - time of the first S1 image
      * - ``ACQUISITION_DATETIME_1``
        - time of the first S1 image
      * - ``ACQUISITION_DATETIME_2``
        - time of the second S1 image
      * - ``DATA_TYPE``
        - :samp:`100 * degree(LIA)` / :samp:`SIN(LIA)`
      * - ``FLYING_UNIT_CODE``
        - :samp:`s1{{a|b}}`
      * - ``IMAGE_TYPE``
        - :samp:`GRD`
      * - ``INPUT_S1_IMAGES``
        - List of the input Sentinel-1 images used to generate this product
      * - ``ORBIT``
        - :samp:`{{orbitnumber}}`
      * - ``ORBIT_DIRECTION``
        - :samp:`{{orbitdirection}}`
      * - ``ORTHORECTIFIED``
        - :samp:`true`
      * - ``S2_TILE_CORRESPONDING_CODE``
        - :samp:`{{tilename}}`
      * - ``SPATIAL_RESOLUTION``
        - :ref:`chosen output spatial resolution option <Processing.output_spatial_resolution>`
      * - ``TIFFTAG_DATETIME``
        - is updated with the time when the tile has been generated by S1 Tiling.
      * - ``TIFFTAG_IMAGEDESCRIPTION``
        - :samp:`Orthorectified LIA/sin_LIA Sentinel-1A IW GRD`
      * - ``TIFFTAG_SOFTWARE``
        - :samp:`S1 Tiling v{{version}}` -- |version| currently


.. _temporary-files:

.. index:: Temporary files

Temporary files
---------------

Before generating the final products, S1 Tiling produces temporary files. Some
are removed automatically, others are :ref:`cached <data-caches>` in between
several runs to shorten processing times when resuming after an interruption.

.. note:: It's up to you, end-user, to clean that directory regularly.

.. _orthoready-files:

Cut and calibrated S1 images ready for orthorectification
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
:Content: S1 images :ref:`calibrated <calibration>` and :ref:`cut <cutting>`.

:Directory:  :ref:`%(tmp) <paths.tmp>`:samp:`/S1/`

:File name: The same as the origin S1 file with ``_OrthoReady`` appended.

      .. note::
            An accompanying OTB ``.geom`` file is also generated.

      Example:

      .. code-block:: none

           s1a-iw-grd-vv-20200108t044150-20200108t044215-030704-038506-001_sigma_OrthoReady.tiff
           s1a-iw-grd-vv-20200108t044150-20200108t044215-030704-038506-001_sigma_OrthoReady.geom

:File name format:

    ``fname_fmt.cut_borders`` = :samp:`{{rootname}}_{{calibration_type}}_OrthoReady.tiff`

:Format: Float32 GeoTIFF, uncompressed.

:Metadata: The following metadata are added at this step:

    .. list-table::
      :widths: auto
      :header-rows: 1
      :stub-columns: 1

      * - Metadata
        - Value
      * - ``ACQUISITION_DATETIME``
        - time of the input S1 image
      * - ``CALIBRATION``
        - :ref:`chosen calibration option <Processing.calibration>`
      * - ``FLYING_UNIT_CODE``
        - :samp:`s1{{a|b}}`
      * - ``IMAGE_TYPE``
        - :samp:`GRD`
      * - ``INPUT_S1_IMAGES``
        - Name of the input Sentinel-1 image used to generate this product
      * - ``NOISE_REMOVED``
        - :ref:`chosen noise removal option <Processing.remove_thermal_noise>`
      * - ``ORBIT``
        - :samp:`{{orbitnumber}}`
      * - ``ORBIT_DIRECTION``
        - :samp:`{{orbitdirection}}`
      * - ``POLARIZATION``
        - :samp:`{{polarisation}}`
      * - ``TIFFTAG_IMAGEDESCRIPTION``
        - :samp:`{{calibration}} calibrated Sentinel-1{{A|B}} IW GRD`

.. note::
   These files can be kept as a same calibrated and cut S1 image can be
   orthorectified for producing several intersecting S2 tiles.

.. note::
   These temporary files will be produced only if :program:`S1Processor` is
   executed with ``--cache-before-ortho`` option.  In that case, the processing
   will no longer be done in memory and orthoready files will be produced.
   You would also have to explicitly clean these temporary files.

.. _orthorectified-files:

Orthorectified S1 images
++++++++++++++++++++++++

:Content: Single concatenated orthorectified S1 image on S2 grid

:Directory:  :ref:`%(tmp) <paths.tmp>`:samp:`/S2/{{tilename}}/`

:File name: :samp:`s1{{a|b}}_{{tilename}}_{{polarity}}_{{orbitdirection}}_{{orbitnumber}}_{{YYYYMMDD}}t{{hhmmss}}_{{calibration}}.tif`

:File name format:

    ``fname_fmt.orthorectification`` = :samp:`{{flying_unit_code}}_{{tile_name}}_{{polarisation}}_{{orbit_direction}}_{{orbit}}_{{acquisition_time}}_{{calibration_type}}.tif`

:Format: Float32 GeoTIFF, deflate compressed

:Metadata: The metadata listed for :ref:`the S2 tile product <full-S2-tiles>`
           are actually produced at this step.

.. note::
   These files are automatically cleaned up.

.. _dem-vrt-files:

DEM VRT files
+++++++++++++

:Content: Virtual aggregate of all the SRTM files that fully cover the
          associated input S1 images (in both polarities).

:Directory:  :ref:`%(tmp) <paths.tmp>`:samp:`/S1/`

:File name: :samp:`DEM-s1{{a|b}}-iw-grd-{{start_stamp}}-{{end_stamp}}-{{nr1}}-{{nr2}}.tif`

:File name format:

    ``fname_fmt.dem_s1_agglomeration`` = :samp:`DEM_{{polarless_rootname}}.vrt`

:Format: VRT

:Metadata: No metadata is added by S1Tiling to these files.

:Cleanup:

    .. warning::
       These files still **need** to be cleaned manually. This should change
       eventually, or it may be conditionned to an option.

.. _S1_on_dem-files:

Files of S1 coordinates projected on DEM geometry
+++++++++++++++++++++++++++++++++++++++++++++++++

:Content: Pixels are in the :ref:`Virtual DEM <dem-vrt-files>` geometry. Their
          values contain the XYZ cartesian coordinates of the pixel and the
          position of the matching pixel in the original Sentinel-1 image.
          This file is produced with `DiapOTB SARDEMProjection
          <https://gitlab.orfeo-toolbox.org/remote_modules/diapotb/-/wikis/Applications/app_SARDEMProjection>`_
          application.

:Directory:  :ref:`%(tmp) <paths.tmp>`:samp:`/S1/`

:File name: :samp:`S1_on_DEM-s1{{a|b}}-iw-grd-{{start_stamp}}-{{end_stamp}}-{{nr1}}-{{nr2}}.tif`

:File name format:

    ``fname_fmt.s1_on_dem`` = :samp:`S1_on_DEM_{{polarless_basename}}`

:Format: Float32 GeoTIFF, 7 bands: C (colunm into SAR image), L (line into SAR
         image), Z and Y, XCartesian, YCartesian, ZCartesian.

:Metadata: The following metadata is added to the origin S1 images

    .. list-table::
      :widths: auto
      :header-rows: 1
      :stub-columns: 1

      * - Metadata
        - Value

      * - ``ACQUISITION_DATETIME``
        - time of the first S1 image
      * - ``DEM_LIST``
        - List of DEM (SRTM currently) tiles used to generate the file
      * - ``FLYING_UNIT_CODE``
        - :samp:`s1{{a|b}}`
      * - ``IMAGE_TYPE``
        - :samp:`GRD`
      * - ``INPUT_S1_IMAGES``
        - List of the input Sentinel-1 images used to generate this product
      * - ``ORBIT``
        - :samp:`{{orbitnumber}}`
      * - ``ORBIT_DIRECTION``
        - :samp:`{{orbitdirection}}`
      * - ``PRJ.DIRECTIONTOSCANDEMC``
        - Range direction for DEM scan.
      * - ``PRJ.DIRECTIONTOSCANDEML``
        - Azimuth direction for DEM scan.
      * - ``PRJ.GAIN``
        - Gain value
      * - ``TIFFTAG_IMAGEDESCRIPTION``
        - :samp:`SARDEM projection onto DEM list`

:Cleanup:

    .. warning::
       These files still **need** to be cleaned manually. This should change
       eventually, or it may be conditionned to an option.

.. _xyz-files:

Files of XYZ cartesian coordinates in S1 geometry
+++++++++++++++++++++++++++++++++++++++++++++++++

:Content: Pixels are in the original Sentinel-1 image geometry. Their
          values contain the XYZ cartesian coordinates of the pixel.
          This file is produced with `our patched version
          <https://gitlab.orfeo-toolbox.org/s1-tiling/normlim_sigma0/-/merge_requests/1>`_
          of `DiapOTB SARCartesianMeanEstimation
          <https://gitlab.orfeo-toolbox.org/remote_modules/diapotb/-/wikis/Applications/app_SARCartesianMeanEstimation>`_
          application.

:Directory:  :ref:`%(tmp) <paths.tmp>`:samp:`/S1/`

:File name: :samp:`XYZ-s1{{a|b}}-iw-grd-{{start_stamp}}-{{end_stamp}}-{{nr1}}-{{nr2}}.tif`

:File name format:

    ``fname_fmt.xyz`` = :samp:`XYZ_{{polarless_basename}}`

:Format: Float32 GeoTIFF, 4 bands: XCartesian, YCartesian, ZCartesian, and ???

:Metadata: The following metadata changed from the :ref:`SARDEMProjected images <S1_on_dem-files>`

    .. list-table::
      :widths: auto
      :header-rows: 1
      :stub-columns: 1

      * - Metadata
        - Value

      * - ``PRJ.DIRECTIONTOSCANDEMC``
        - **Removed**
      * - ``PRJ.DIRECTIONTOSCANDEML``
        - **Removed**
      * - ``PRJ.GAIN``
        - **Removed**
      * - ``TIFFTAG_IMAGEDESCRIPTION``
        - :samp:`Cartesian XYZ coordinates estimation`

:Cleanup:

    .. warning::
       These files still **need** to be cleaned manually. This should change
       eventually, or it may be conditionned to an option.

.. _lia-s1-files:

Local Incidence Angle map files in S1 geometry
++++++++++++++++++++++++++++++++++++++++++++++

:Content:

    - Map of sines of Local Incidence Angle (LIA),
    - and optionally of LIA expressed in degree and scaled by a factor of 100.

    Given T, the target point on Earth's surface, and S the SAR sensor
    position, the LIA is the angle Θ\ :sub:`LIM` between the ground normal
    projected in range plane :math:`\overrightarrow{n}` (plane defined by S,
    T, and Earth's center) and :math:`\overrightarrow{TS}`.

    Unlike the :ref:`final LIA maps in S2 geometry <lia-files>`, the LIA map is
    in the geometry of the original Sentinel-1 image used to produce it.

:Directory:  :ref:`%(tmp) <paths.tmp>`:samp:`/S1/`

:File name:

    - :samp:`LIA-s1{{a|b}}-iw-grd-{{start_stamp}}-{{end_stamp}}-{{nr1}}-{{nr2}}.tif`
    - :samp:`sin-LIA-s1{{a|b}}-iw-grd-{{start_stamp}}-{{end_stamp}}-{{nr1}}-{{nr2}}.tif`

:File name format:

    - ``fname_fmt.s1_lia`` = :samp:`LIA_{{polarless_basename}}`
    - ``fname_fmt.s1_sin_lia`` = :samp:`sin_LIA_{{polarless_basename}}`

:Format: Float32 GeoTIFF

:Metadata: The following metadata is changed the :ref:`XYZ estimated coordinates <xyz-files>`

    .. list-table::
      :widths: auto
      :header-rows: 1
      :stub-columns: 1

      * - Metadata
        - Value

      * - ``TIFFTAG_IMAGEDESCRIPTION``
        - :samp:`LIA on Sentinel-1A IW GRD`

:Cleanup:

    .. warning::
       These files still **need** to be cleaned manually. This should change
       eventually, or it may be conditionned to an option.

.. _lia-s2-half-files:

Half Local Incidence Angle map files -- pre-concatenation.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

:Content:

    - Map of sines of Local Incidence Angle (LIA),
    - and optionally of LIA expressed in degree and scaled by a factor of 100.

    These files directly match the :ref:`LIA maps computed on S1 images
    <lia-s1-files>`, after orthorectification to the Sentinel-2 tile, and
    before their concatenation in the :ref:`final LIA maps in S2 geometry
    <lia-files>`.

:Directory:  :ref:`%(tmp) <paths.tmp>`:samp:`/S2/`

:File names:

    - :samp:`sin_LIA_s1{{a|b}}_{{tilename}}_{{orbitdirection}}_{{orbitnumber}}_{{start_stamp}}.tif` -- :math:`sin(Θ_{LIM})`
    - :samp:`LIA_s1{{a|b}}_{{tilename}}_{{orbitdirection}}_{{orbitnumber}}_{{start_stamp}}.tif` -- :math:`100 * Θ°_{LIM}`

:File name format:

    ``fname_fmt.lia_orthorectification`` = :samp:`{{LIA_kind}}_{{flying_unit_code}}_{{tile_name}}_{{orbit_direction}}_{{orbit}}_{{acquisition_time}}.tif`

:Format: Float32 (and Int16) GeoTIFF, deflate compressed

:Metadata: The following metadata is changed from the :ref:`un-orthorectified LIA maps <lia-s1-files>`

    .. list-table::
      :widths: auto
      :header-rows: 1
      :stub-columns: 1

      * - Metadata
        - Value

      * - ``DATA_TYPE``
        - :samp:`100 * degree(LIA)` / :samp:`SIN(LIA)`
      * - ``ORTHORECTIFIED``
        - :samp:`true`
      * - ``S2_TILE_CORRESPONDING_CODE``
        - :samp:`{{tilename}}`
      * - ``SPATIAL_RESOLUTION``
        - :ref:`chosen output spatial resolution option <Processing.output_spatial_resolution>`
      * - ``TIFFTAG_IMAGEDESCRIPTION``
        - :samp:`Orthorectified LIA Sentinel-1A IW GRD`

:Cleanup:

    .. warning::
       These files still **need** to be cleaned manually. This should change
       eventually, or it may be conditionned to an option.

