.. _MERSegmentationMap:


Segmentation Map Product
========================



Data Product Name
_________________
.. DataProductNameStart

DpdMerSegmentationMap

.. DataProductNameEnd


Data Product Custodian
______________________
.. DataProductCustodianStart

MER

.. DataProductCustodianEnd


Name of the Schema File
_______________________
.. NameSchemaStart

.. raw:: html 

    <a href="https://gitlab.euclid-sgs.uk/ST-DM/ST_DataModel/-/blob/10.0.4/ST_DM_Schema/auxdir/ST_DM_Schema/dpd/mer/euc-mer-SegmentationMap.xsd" target="_blank">euc-mer-SegmentationMap.xsd</a>

.. NameSchemaEnd


Last Edited for DPDD Version
____________________________
.. DpddVersionlTagStart

2.0

.. DpddVersionTagEnd


Processing Elements Creating / Updating / Using the Product
___________________________________________________________
.. PECreatorStart

**Creators:**

* MER_Detection
* MER_Deblending
* MER_MBCombine
* MER_Compression


**Consumers:**

* MER_Deblending
* MER_MBCombine
* MER_Photometry
* MER_Compression
* MER_Validation

.. PECreatorEnd


Processing Function Using the Product
_____________________________________
.. PFUsingStart

MER, SIR, SHE

.. PFUsingEnd


Proposed for Inclusion in EAS/SAS
_________________________________
.. IncludeInSASStart

This product is proposed for inclusion in the SAS: yes.

These products contain the segmentation map produced by the object detection
and deblending steps. It is useful to have them in the SAS in case
scientist want to replicate the morphology and photometry calculations
performed by MER.

.. IncludeInSASEnd

Data Product Elements
_____________________
.. DataProductElementsStart

:Header: object of type sys:genericHeader
:Data: object of type mer:merSegmentationMap
:QualityFlags: object of type dqc:sqfDpdMerSegmentationMap
:Parameters: object of type ppr:genericKeyValueParameters

.. DataProductElementsEnd


Detailed Description of the Data Product
________________________________________
.. DetailedDescStart

Map showing the connected pixels of the objects detected on the corresponding
:ref:`MER detection mosaics <MERDetectionMosaic>`. 

The segmentation map returned by the MER pipeline is a combination of the VIS
and NIR segmentation maps produced by the MER object detection and object
deblending steps. These steps run in parallel on the VIS and NIR-stack detection 
mosaics and produce two independent source catalogs and segmentaion maps. The 
combination of the segmentation maps gives preferece to VIS over NIR. The 
segmented pixels associated to a given VIS source are never modified, even when
a NIR-only source spatially overlaps with them. In that case, the overlapping 
pixels will be removed from the NIR-only source segmented area. The reason for 
that is that SHE measurements are based only on the VIS-detected sources and
should not be biased by the NIR-only sources.

The object id numbers in the segmentation map coincide with the 
``SEGMENTATION_MAP_ID`` column values in the 
:ref:`MER final catalog <MERFinalCatalog>`. ``SEGMENTATION_MAP_ID`` is computed
combining the reference tile index and the source detection ids via:

.. math::
   :label: semap_id_equ_1
   
   \text{SEGMENTATION_MAP_ID} = \text{TILE_INDEX} \times 10^6 + \text{SOURCE_DETECTION_ID}

This makes sure that the segmentation map ids are unique for a given data
release. For all the sources laying outside the :ref:`MER tile <MERTile>` core
area (i.e. not included in the associated MER final catalog),
``SEGMENTATION_MAP_ID`` is set to -1.

The main elements inside the MER segmentation map product are:

* **FilterList**: List of filters that were used to produce the segmentation map
  (normally VIS and/or NIR filters).
* **WCS**: The segmentation map astrometric parameters (e.g., CTYPE1, CRVAL2,
  CRPIX1, CD1_1).
* **ImgSpatialFootprint**: The segmentation map spatial footprint.
* **TileIndex**: The MER tile index.
* **PatchIdList**: The sky patch ids associated to the product.
* **ObservationIdList**: List of unique IDs identifying the Euclid observations
  that were used to generate the product.
* **CalblockIdList** (optional): The calibration block ids associated to the
  product.
* **CalblockVariantList**: The calibration block variants associated to the
  product.
* **ProcessingMode**: The MER pipeline processing mode (e.g. WIDE, DEEP) used to
  generate the product.
* :ref:`DataStorage <mer-segmentation-map-fits>`: Element that links to a FITS
  file containing the segmentation map data set.
* :ref:`QualityParams <mer-segmentation-map-quality-parameters>`: The
  segmentation map quality parameters.


.. _mer-segmentation-map-fits:

Sementation map FITS file
^^^^^^^^^^^^^^^^^^^^^^^^^

This FITS file contains contains information about the pixels associated to 
each individual source in the :ref:`MER final catalog <MERFinalCatalog>`. 

PRIMARY extension header keywords:

.. table::
   :width: 100%

   +----------------------------------------------------------------------------+
   |                         **HDU** *PRIMARY*: header                          |
   +==========+==========+==========================================+===========+
   |          | **Name** |             **Description**              | **Value** |
   +----------+----------+------------------------------------------+-----------+
   | Keywords |  BITPIX  |             array data type              |  integer  |
   +          +----------+------------------------------------------+-----------+
   |          |  CDELT1  | [deg] Coordinate increment at reference  |   double  |
   +          +----------+------------------------------------------+-----------+
   |          |  CDELT2  | [deg] Coordinate increment at reference  |   double  |
   +          +----------+------------------------------------------+-----------+
   |          |  CRPIX1  |      Reference pixel on this axis        |   double  |
   +          +----------+------------------------------------------+-----------+
   |          |  CRPIX2  |      Reference pixel on this axis        |   double  |
   +          +----------+------------------------------------------+-----------+
   |          |  CRVAL1  |      World coordinate on this axis       |   double  |
   +          +----------+------------------------------------------+-----------+
   |          |  CRVAL2  |      World coordinate on this axis       |   double  |
   +          +----------+------------------------------------------+-----------+
   |          |  CTYPE1  |    WCS projection type for this axis     |   string  |
   +          +----------+------------------------------------------+-----------+
   |          |  CTYPE2  |    WCS projection type for this axis     |   string  |
   +          +----------+------------------------------------------+-----------+
   |          |  CUNIT1  |                Axis unit                 |   string  |
   +          +----------+------------------------------------------+-----------+
   |          |  CUNIT2  |                Axis unit                 |   string  |
   +          +----------+------------------------------------------+-----------+
   |          | DATASETR |      The pipeline data set release       |   string  |
   +          +----------+------------------------------------------+-----------+
   |          | EQUINOX  |               Mean equinox               |   double  |
   +          +----------+------------------------------------------+-----------+
   |          | LATPOLE  | [deg] Native latitude of celestial pole  |   double  |
   +          +----------+------------------------------------------+-----------+
   |          | LONPOLE  | [deg] Native longitude of celestial pol  |   double  |
   +          +----------+------------------------------------------+-----------+
   |          |  MJDREF  |         [d] MJD of fiducial time         |   double  |
   +          +----------+------------------------------------------+-----------+
   |          |  NAXIS   |        number of array dimensions        |  integer  |
   +          +----------+------------------------------------------+-----------+
   |          |  NAXIS1  |    NUMBER OF ELEMENTS ALONG THIS AXIS    |  integer  |
   +          +----------+------------------------------------------+-----------+
   |          |  NAXIS2  |    NUMBER OF ELEMENTS ALONG THIS AXIS    |  integer  |
   +          +----------+------------------------------------------+-----------+
   |          | NIR_OFF  |  Offset of the NIR detected source IDs   |  integer  |
   +          +----------+------------------------------------------+-----------+
   |          |  ORIGIN  |    Where it was done (Swarp keyword)     |   string  |
   +          +----------+------------------------------------------+-----------+
   |          |  PC1_1   | Coordinate transformation matrix elemen  |   double  |
   +          +----------+------------------------------------------+-----------+
   |          |  PC2_2   | Coordinate transformation matrix elemen  |   double  |
   +          +----------+------------------------------------------+-----------+
   |          | PIPDEFID |        The pipeline definition id        |   string  |
   +          +----------+------------------------------------------+-----------+
   |          | PPLANID  |            The parent plan id            |   string  |
   +          +----------+------------------------------------------+-----------+
   |          |  PPOID   |     The pipeline processing order id     |   string  |
   +          +----------+------------------------------------------+-----------+
   |          | PSWNAME  |        The pipeline software name        |   string  |
   +          +----------+------------------------------------------+-----------+
   |          |  PSWREL  |      The pipeline software release       |   string  |
   +          +----------+------------------------------------------+-----------+
   |          | RADESYS  |            Astrometric system            |   string  |
   +          +----------+------------------------------------------+-----------+
   |          |  SIMPLE  |        conforms to FITS standard         |  logical  |
   +          +----------+------------------------------------------+-----------+
   |          | WCSAXES  |        Number of coordinate axes         |  integer  |
   +----------+----------+------------------------------------------+-----------+



.. _mer-segmentation-map-quality-parameters:

Segmentation map quality parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following list of quality parameters is calculated for each MER segmentation
map. Their values can be used to select an specific subset of segmentation maps,
to study global trends, or to detect potencial problems in the MER pipeline or
its input products.

+-------------------+--------------------------------------+
| Quality parameter | Descriptiom                          |
+===================+======================================+
| NonZeroFraction   | The fraction of pixels larger than 0 |
+-------------------+--------------------------------------+

.. DetailedDescEnd