.. Copyright (C) 2016-2024 SpaceKnow, Inc.

.. _api.kraken:

*********************************
Kraken API (Imagery and Analyses)
*********************************

Legends say that the Kraken was a giant sea creature that was bigger than the eye could
see. Sometimes, one wants to get an overview of a bigger area than
:ref:`Ragnar API <api.ragnar>` can provide. Borrowing its name from the Kraken, the sea monster, the
Kraken API was born to serve this very need.

The API interfaces imagery and analyses through `tiled web map`_ interface.

.. _tiled web map: https://en.wikipedia.org/wiki/Tiled_web_map

.. only:: holygrail

    * URL: http://api.local/kraken

    For more information about algorithms available for Kraken see
    :ref:`algorithms <api.kraken_algorithms>`.


Map and Tiling
==============

Kraken map is Earth surface between -180 to +180 of longitude and -85.051129 to
+85.051129 of latitude projected to a square with `Web Mercator`_ projection.
The map is divided into multiple zoom levels each consisting of a grid of
tiles.

.. _Web Mercator: https://en.wikipedia.org/wiki/Web_Mercator

A tile is unambiguously identified by :math:`(z, x, y)` coordinates, where
:math:`z` represents zoom level, :math:`x` represents a horizontal coordinate
and :math:`y` represents a vertical coordinate. The top-left tile has
coordinates :math:`(z, 0, 0)`.

A zoom level is a number that indicates the level of tile's fine-detail. The
lowest zoom level, at which the whole map is rendered to a single tile, is 0.
With each successive zoom level, the total number of map tiles quadruples. The
zoom level :math:`z >= 0` is a grid with :math:`2^z \times 2^z` tiles.

A tile is physically represented by one or many files representing area given
by the tile boundaries. The files may consist of PNG and other images with
dimensions of 512x512 pixels (256x256 pixels for legacy files with version
<= 372), a GeoJSON or other types of raster and vector data.
See :ref:`api.kraken.grid-files`.

.. _api.kraken.release:

Glossary
========

* Kraken map -- an individual image or analyses identified with a unique ID.
* Map type -- type of analysis (type of Kraken map), e.g. ``IMAGERY``,
  ``AIRCRAFT``, ``NDVI``
* Grid file -- a map is divided into tiles. For every tile (i.e. some zoom,
  x, y coordinates) there is one or more available
  :ref:`grid files <api.kraken.grid-files>` (e.g. ``truecolor.png`` or
  ``detections.geojson``).

Release The Kraken!
===================

Kraken release endpoints serve as a preparation and/or re-computation of
a map. All release endpoints generate a map ID which can be later used to
access the :ref:`map <api.kraken.grid-files>`. A map ID expires in one year.

Generic Kraken Release Endpoints
--------------------------------

Kraken API can execute analysis over area specified by GeoJSON. Type of
analysis to execute is given by map type, e.g. ``AIRCRAFT``.

.. only:: not holygrail

    .. note::

        The area must be :ref:`allocated using Credits API <api.credits>`.

.. _api.kraken.release.initiate:

**Needed Permissions**:

 * ``kraken.release``
 * Also a set of permissions in the form ``<prefix>.<provider>.<dataset>`` is
   needed. ``<prefix>`` is replaced with ``algorithms.<name-of-algorithm>`` or
   with ``imagery.images``.

.. http:post:: /kraken/release/initiate

    :<json list mapTypes: required; Map types to be analyzed.
    :<json list sceneIds: required; ID of scene(s) from which the map should
        be generated. See :ref:`api.ragnar`. Number of input scenes depends on
        given map type, single input map types require 1 ``sceneIds``, pairwise
        map types require 2 ``sceneIds`` and N-wise map types require ``k`` or
        more ``sceneIds``. Value of ``k`` is dependent on exact N-wise map type
        used but it is always at least 2.
    :<json object extent: required; area of interest which must intersect with
        scene's footprint, see :ref:`api.mechanics.extent`.
    :<json object subGeometry: optional; Subset of ``extent`` of interest.
        If provided the response contains subGeometryId which can later be
        used in Kraken Grid endpoint to crop result of analysis.
        See :ref:`Release with subGeometry <api.kraken.sub-geometry>`.

    **Example request**:

    .. sourcecode:: json

        {
            "mapTypes": ["imagery", "aircraft"],
            "sceneIds": ["abc"],
            "extent": {
                "type": "MultiPolygon",
                "coordinates": [
                    [
                        [
                            [-122.51, 37.69],
                            [-122.35, 37.69],
                            [-122.35, 37.80],
                            [-122.51, 37.80],
                            [-122.51, 37.69]
                        ]
                    ]
                ]
            },
            "subGeometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [-122.49, 37.71],
                        [-122.44, 37.71],
                        [-122.44, 37.77],
                        [-122.49, 37.77],
                        [-122.49, 37.71]
                    ]
                ]
            }
        }

    **Example response**:

    See :ref:`pipeline initiation <api.mechanics.asynchronous.initiate>`.

**Max zoom**

Max zoom is determined by the following formula:

.. math::

    z_{max} = \lceil log_2(\frac{4 \cdot 10^7 \cdot
    cos(\frac{l \cdot \pi}{180})}{256 \cdot r_e}) \rceil

where :math:`l` is latitude of the scene footprint centroid and
:math:`r_e` is the effective resolution in meters per pixel.

Effective resolution for the map can be determined by the following pseudo
code:

.. code-block:: python

    if release_type == 'imagery':
        r_e = min(r for b in bands for r in (b.approx_res_x, b.approx_res_y))
    elif provider == 'pl':
        r_e = 3.125
    else:
        r_e = 0.5

.. _api.kraken.release.retrieve:

**Needed Permissions**: ``kraken.release``

.. http:post:: /kraken/release/retrieve

    **Example request**:

    See :ref:`pipeline retrieve <api.mechanics.asynchronous.retrieve>`.

    :>json list maps: list of successfully analyzed maps
    :>json list failedMapTypes: list of map types for which the analysis failed
    :>json string maps[i].mapId: map ID to be used to access map tiles
    :>json string maps[i].mapType: map type of the result
    :>json int maps[i].maxZoom: maximum zoom available for returned ``mapId``
    :>json int maps[i].sceneId: sceneId of the map. Can differ from originally
        released sceneId for clipped or paired scenes.
    :>json list maps[i].tiles: List of tiles which were successfully created,
        the system may be unable to release some of the requested tiles. This
        is always a subset of requested tiles. It is guaranteed that at most
        four tiles, all at equal zoom level, are returned. User is allowed to
        request any descendant tile, note that some child tiles of ``tiles``
        may be missing.

    **Example response**:

    .. sourcecode:: json

        {
            "imagery": {
                "mapId": "xyz",
                "maxZoom": 19,
                "sceneId": "scene-id"
                "status": "succeeded",
                "tiles": [
                    [19, 83861, 202628]
                ]
            },
            "aircraft": {
                "mapId": "xyz",
                "maxZoom": 19,
                "status": "succeeded",
                "tiles": [
                    [19, 83861, 202628]
                ]
            },
            "aircraft": {
                "errorCode": "ZERO-TILES-AVAILABLE",
                "errorMessage": "No tile has been successfully generated.",
                "status": "failed"
            }
        }

.. _api.kraken.sub-geometry:

Release with subGeometry
------------------------

Sometimes it is useful to have kraken analyze bigger extent and then download
only subset of what was analyzed. This is the case for SAR change algorithms
when we want to analyze AoI buffered sufficiently so that kraken can use AoI
neighborhood for data normalization.

Kraken Pairwise API
===================

Use this endpoint to generate pairs from a list of scenes according to chosen
pairing type and other options. Each pair can be afterwards analyzed with
pairwise map types through :ref:`Kraken release <api.kraken.release.initiate>`.

.. _api.kraken.pairwise.initiate:

**Needed Permissions**:

 * ``imagery.availability``

.. http:post:: /kraken/pairwise/initiate

    :<json list sceneIds: required; IDs of scenes from which the pairs should
        be generated.
    :<json object extent: required; area of interest which must intersect with
        footprints of both scenes.
    :<json string periodicity: optional; Periodicity used to generate slots.
        Supported periodicities are ``none``, ``daily``, ``weekly``,
        ``amweekly``, ``semi-monthly`` (two samples per each month
        1-14, 15+), ``monthly``, ``quarterly`` and ``yearly``.
    :<json float minIntersection: optional; Minimum required intersection of
        the scenes in sq km. Defaults to 0.
    :<json float pairingType: optional; Possible options:

        * ``continuous`` create pairs from all successive records. Default value.
        * ``first`` pairs the first record (sorted by time of the occurrence)
          in the input to the rest of the records.
        * ``yoy`` pairs records with one year of time between them with some
          leeway to mitigate seasonality, see --max-yoy-delta.

    :<json float maxYoyDelta: optional; Maximum deviation from exact year over
        year pairing in days. Use decimal number for more accuracy. Only
        applicable for yoy pairing. Defaults to 15.0.
    :<json float minDayDelta: optional; SAR specific. Minimum span between
        paired scenes in days. Defaults to 0.0.
    :<json float maxDayDelta: optional; SAR specific. Maximum span between
        paired scenes in days. Defaults to unlimited day difference.
    :<json bool onlyTopOrbitNumber: optional; SAR specific.  Whether to include
        only scene set with same relative orbit number and orbit pass that has
        most occurrences in input. Defaults to False.

    **Example request**:

    .. sourcecode:: json

        {
            "sceneIds": ["scene_id1","scene_id2","scene_id3"],
            "periodicity": "daily",
            "extent": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            [-122.51747131348, 37.694823535365],
                            [-122.35130310059, 37.694823535365],
                            [-122.35130310059, 37.809919574016],
                            [-122.51747131348, 37.809919574016],
                            [-122.51747131348, 37.694823535365]
                        ]
                    ]
                ]
            }
        }

    **Example response**:

    :<json list pairwise: list of paired scenes. Dictionary contains
        ``oldSceneId`` and ``newSceneId``.

    .. sourcecode:: json

        {
            "pairwise": [
                {"oldSceneId": "scene_id1", "oldSceneId": "scene_id2"},
                {"oldSceneId": "scene_id2", "oldSceneId": "scene_id3"}
            ]
        }

Kraken N-wise API
=================

Use this endpoint to generate groups from a list of scenes according to chosen
parameters. Each group can be afterwards analyzed with N-wise map types through
:ref:`Kraken release <api.kraken.release.initiate>`.

The endpoint fails with ``SCENES-WITH-SAME-DATETIME`` error if two scenes
within one relative orbit number group have identical datetimes. Scenes must
be deduplicated on datetime before sending them to the endpoint.

.. _api.kraken.nwise.initiate:

**Needed Permissions**:

 * ``imagery.availability``

.. http:post:: /kraken/nwise/initiate

    :<json string groupingType: required; grouping type, either ``windowed`` or
        ``cumulated`` or ``cumulated-yoy``
    :<json list sceneIds: required; IDs of scenes from which the pairs should
        be generated.
    :<json object extent: required; area of interest which must intersect with
        footprints of both scenes.
    :<json string windowStart: optional; date from which to start calculating
        group windows. Required in ``windowed`` groupingType.
    :<json int windowSizeDays: optional; length of the window for one group to
        fit in. Required in ``windowed`` groupingType.
    :<json float windowStepDays: optional; spacing between windows for
        grouping. Required in ``windowed`` groupingType.
    :<json string startDate: optional; start date of window of interest.
        Required in ``cumulated-yoy`` groupingType.
    :<json string endDate: optional; end date of window of interest. Required
        in ``cumulated-yoy`` groupingType.
    :<json float yoyPairMinIntersectionKm2: optional; minimum intersection area
        for the scene pair to be considered for YoY pairing. Required in
        ``cumulated-yoy`` groupingType.
    :<json int minScenes: optional; minimum number of scenes within returned
        group. Only usable in ``cumulated`` groupingType. Defaults to 3.

    **Example request**:

    .. sourcecode:: json

        {
            "groupingType": "windowed",
            "sceneIds": ["scene_id1","scene_id2","scene_id3","scene_id4"],
            "extent": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            [-122.51747131348, 37.694823535365],
                            [-122.35130310059, 37.694823535365],
                            [-122.35130310059, 37.809919574016],
                            [-122.51747131348, 37.809919574016],
                            [-122.51747131348, 37.694823535365]
                        ]
                    ]
                ]
            },
            "windowSizeDays": 20,
            "windowStart": "2021-01-10",
            "windowStepDays": 10
        }

    **Example response**:

    :<json list nwise: list of groups of scene IDs.

    .. sourcecode:: json

        {
            "nwise": [
                ["scene_id1", "scene_id2", "scene_id3"],
                ["scene_id2", "scene_id3", "scene_id4"],
            ]
        }

    **Example request**:

    .. sourcecode:: json

        {
            "groupingType": "cumulated",
            "sceneIds": ["scene_id1","scene_id2","scene_id3","scene_id4"],
            "extent": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            [-122.51747131348, 37.694823535365],
                            [-122.35130310059, 37.694823535365],
                            [-122.35130310059, 37.809919574016],
                            [-122.51747131348, 37.809919574016],
                            [-122.51747131348, 37.694823535365]
                        ]
                    ]
                ]
            },
            "minScenes": 3
        }

    **Example response**:

    .. sourcecode:: json

        {
            "nwise": [
                ["scene_id1", "scene_id2", "scene_id3"],
                ["scene_id1", "scene_id2", "scene_id3", "scene_id4"],
            ]
        }

    **Example request**:

    .. sourcecode:: json

        {
            "groupingType": "cumulated",
            "sceneIds": ["scene_id1", "scene_id2", "scene_id3", "scene_id4", "scene_id5", "scene_id6"],
            "extent": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            [-122.51747131348, 37.694823535365],
                            [-122.35130310059, 37.694823535365],
                            [-122.35130310059, 37.809919574016],
                            [-122.51747131348, 37.809919574016],
                            [-122.51747131348, 37.694823535365]
                        ]
                    ]
                ]
            },
            "startDate": "2021-05-01",
            "endDate": "2021-10-01",
            "yoyPairMinIntersectionKm2": 0,
        }

    **Example response**:

    .. sourcecode:: json

        {
            "nwise": [
                ["scene_id1", "scene_id2", "scene_id3", "scene_id4", "scene_id5", "scene_id6"],
            ]
        }

.. _api.kraken.grid:
.. _api.kraken.grid-files:

Grid Files
==========

A tile can be downloaded using the following endpoint.

.. http:get:: /kraken/grid/<map_id>/<geometry_id>/<z>/<x>/<y>/<file_name>

    :param string map_id: ID of a map returned by the :ref:`retrieve endpoint <api.kraken.release.retrieve>`.
    :param string geometry_id: For internal use only, use ``-``.
    :param int z: Zoom level of the tile.
    :param int x: Horizontal coordinate of the tile.
    :param int y: Vertical coordinate of the tile.
    :param string file_name: One of the output files available for the released map type that should be returned.
        See the :ref:`documentation of individual Kraken map types above <api.kraken>`.
    :query int force_download: Optional; Set to ``1`` to download chosen output file
        even if the file has all pixels invalid.
    :query int download_unclipped: Optional; Set to ``1`` to disable clipping of tiles to requested geometry in the Grid endpoint.
        ``kraken.download-unclipped`` permission needed.
    :query float user_threshold: Optional; If given binarize grid files
        according to the user threshold. The value must be in [0, 1] interval.
        Only available for pixel index algorithms. Only available for
        ``metadata.json`` and ``PNG`` grid files.
    :query string detection_filters: Optional; If given filter features in vector grid
        file according to detection filters. The value is set of lines (conditions) which
        consists of three space-separated items: property, condition, value.
        Example `area gt 1000\nwidth lt 100`
        Only available for ``detections.geojson`` grid files.
    :status 200: File is present and has valid data.
    :status 204: PNG/SKI does not have valid pixels in requested area, this
        behaviour can be overridden by setting force_download to ``1``.
    :status 400: Invalid request: a possible reason is invalid or expired map ID.
    :status 401: Given map ID doesn't include requested tile.
    :status 404: Requested tile doesn't exist: data are not available or the area of
        the tile cannot be analyzed.

    **Example requests**:

    .. sourcecode:: http

        GET /kraken/grid/xyz/-/19/83861/202628/truecolor.png HTTP/1.1

    .. sourcecode:: http

        GET /kraken/grid/abc/-/19/83861/202628/aircraft.png HTTP/1.1

    .. sourcecode:: http

        GET /kraken/grid/abc/-/19/83861/202628/segmentation.ski HTTP/1.1

    .. sourcecode:: http

        GET /kraken/grid/abc/-/19/83861/202628/detections.geojson HTTP/1.1

    .. sourcecode:: http

        GET /kraken/grid/abc/-/19/83861/202628/metadata.json HTTP/1.1

``.png`` tile can be either RGBA or grayscale+alpha PNG and requested polygon
is drawn to the PNG alpha channel.

``truecolor.png`` can be represented by:

* Bands corresponding to RGB in satellite imagery if such bands are present.
* Bands chosen to fill RGB channels that are not corresponding to red, green,
  blue. For example imagery from ``idaho-swir`` contains only data from
  infrared bands and 3 of them are chosen to be visualized.
* One Grayscale channel if only one band is present in satellite imagery. This
  grayscale band can correspond to visible light band in some imagery but
  generally it can contain other data too.
* SAR imagery is visualized as ``(log(S), log(O), arctan(S/O))`` where ``S``
  is intensity of detected radio waves with
  same polarisation as radio waves emitted by the satellite, ``O`` is
  intensity of detected radio waves with polarisation perpendicular to emitted
  radio waves. ``arctan`` in blue band represents measure of preservation of
  polarisation plane in reflected light.

Kraken Dry-Run
==============

Use this endpoint to get the size of ingested imagery and analysis.
Useful for predicting costs of a particular analysis before it's run.


.. _api.kraken.dry-run.initiate:

**Needed Permissions**:

 * ``kraken.dry-run``

.. http:post:: /kraken/dry-run/initiate

    :<json object extent: required; area of interest which must intersect with
        scene's footprint.
    :<json list dryRuns: required; list of dry run dictionaries.
        Contains a list of Kraken map types to use. Also contains list of lists
        with sceneIds. Scene list can contain single scene_id for single
        algorithms or multiple scenes for change or n-wise algorithm.
    :<json bool ignoreCache: optional; true value skips checking previously
        cached results.
    :<json bool allocate: optional; if set to true allocate requested scenes
        and tiles for group of which userId client is part of. If not present
        or set to false it only checks credits and area required for allocation.
    :<json string deliveryId: optional; Will be propagated to Transaction
        entities if provided.

    **Example request**:

    .. sourcecode:: json

        {
          "dryRuns": [
            {
              "scenes": [["DXc_fDD2aRjkHVOJ4elbKQ"],["DXc_fDD2aRjkHVOJ4elbKg"]],
              "mapTypes": ["imagery", "aircraft", "wrunc"]
            },
            {
              "scenes": [["DXc_fDD2aRjkHVOJ4elbKQ", "DXc_fDD2aRjkHVOJ4elbKg"]],
              "mapTypes": ["wrunc-change", "change"]
            }
          ],
          "extent": {
            "type": "MultiPolygon",
            "coordinates": [
              [
                [
                  [-122.51747131348, 37.694823535365],
                  [-122.35130310059, 37.694823535365],
                  [-122.35130310059, 37.809919574016],
                  [-122.51747131348, 37.809919574016],
                  [-122.51747131348, 37.694823535365]
                ]
              ]
            ]
          }
        }

    **Example response**:

    :>json float ingestedKm2: square kilometres of area that would be
        downloaded from the imagery provider.
    :>json float analyzedKm2: square kilometres of area that would be analyzed.
    :>json float krakenKm2: square kilometres of area that would be moved
        from Ragnar to Kraken.
    :>json float allocatedKm2: number of :math:`km^2` required/allocated.
    :>json float allocatedCredits: number of credits required/allocated.

    .. sourcecode:: json

        {
            "ingestedKm2": 100.69,
            "krakenKm2": 75.434,
            "analyzedKm2": 50.23,
            "allocatedKm2": 100.69,
            "allocatedCredits":1.06
        }


.. _api.kraken.map_type:

Kraken MapType List
===================

Use this endpoint to see which algorithms you can access.
Useful to determine the name of the algorithm to run.
Only map types that user has permissions for are listed.

**Needed Permissions**:

 * ``kraken.release``

.. http:post:: /kraken/map-types

    **Example request**:

    .. sourcecode:: json

        {}

    **Example response**:

    :>jsonarr str mapType: the name of the algorithm.
    :>jsonarr str description: the short description of the algorithm
    :>jsonarr dict gridFiles: available grid files for given mapType per suffix
    :>jsonarr dict availableDatasets: available datasets grouped per provider
    :>jsonarr dict segmentationMetadata.segmentationColors: RGB colors for
        segmentation classes of given map type. ``segmentationMetadata`` key is
        not present for non-segmentation map types.
    :>jsonarr list segmentationHierarchy.baseClasses: List of base classes for given
        map type. Only present for map types that have hierarchy.
    :>jsonarr dict segmentationHierarchy.parentClasses: Keys are names of parent
        classes, values are lists of base classes that belong to given parent class.
        Only present for map types that have hierarchy.
    :>jsonarr str segmentationHierarchy.masterClass: Master class that all base classes
        belong to. Only present for map types that have hierarchy.
    :>jsonarr dict deprecatedClasses: Contains mapping from deprecated previous versions
        to classes which were supported up to the given version. For each class name,
        its RGB color is specified.

    .. sourcecode:: json

        [
            {
                "mapType": "aircraft",
                "description": "Aircraft detection algorithm",
                "gridFiles": {
                    "png": ["segmentation.png", "transport.png", "fighter.png", "rotary-wing.png"],
                    "ski": ["segmentation.ski"],
                    "geojson": ["detections.geojson"],
                    "json": ["metadata.json"],
                    "geotiff": ["analysis.geotiff", "visualization.geotiff"]},
                "availableDatasets": {
                    "gbdx": [["idaho-pansharpened", {
                                "version": "some-number",
                                "is_global": true,
                                "max_gsd": null,
                                "margin_m": 0,
                                "margin_px": 80,
                                "min_size_px": 0,
                                "resolution": null
                            }]],
                    "pl": [["PSScene4Band", {
                                "version": "some-number2",
                                "is_global": false,
                                "max_gsd": 4.5,
                                "margin_m": 0,
                                "margin_px": 80,
                                "min_size_px": 0,
                                "resolution": 3.125
                            }]]}
                "segmentationMetadata": {
                    "segmentationColors": {
                        "aircraft": [255, 193, 7]
                    }
                }
                "segmentationHierarchy": {
                    "baseClasses": ["transport", "fighter", "rotary-wing"],
                    "parentClasses": {
                        "fixed-wing": ["transport", "fighter"]
                    },
                    "masterClass": "aircraft",
                },
                "deprecatedClasses": {
                    "430.2": {
                        "mig-23": [255, 193, 7]
                    }
                },
            {
                "mapType": "ships",
                "description": "Ship detection algorithm",
                "gridFiles": {
                    "png": ["segmentation.png", "ships.png"],
                    "ski": ["segmentation.ski"],
                    "geojson": ["detections.geojson"],
                    "json": ["metadata.json"],
                    "geotiff": ["analysis.geotiff", "visualization.geotiff"]},
                "availableDatasets": {
                    "gbdx": [["idaho-pansharpened", {
                                "version": "some-number3",
                                "is_global": true,
                                "max_gsd": null,
                                "margin_m": 100,
                                "margin_px": 0,
                                "min_size_px": 0,
                                "resolution": 0.3
                            }]],
                    "pl": [["PSScene4Band", {
                                "version": "some-number4",
                                "is_global": true,
                                "max_gsd": 4.5,
                                "margin_m": 100,
                                "margin_px": 80,
                                "min_size_px": 0,
                                "resolution": 3.125
                            }]]}
                "segmentationMetadata": {
                    "segmentationColors": {
                        "ships": [253, 46, 4]
                    }
                }
            }
        ]

Kraken MapType by Map ID
========================

Use this endpoint to get classes with colors which were used
by algorithm applied for map with given ID.
Useful for obtaining colors based on map ID for anonymous users
(as this endpoint does not require authentication).

.. http:get:: /kraken/map-types/<signed_map_id>

    :param string map_id: ID of a map returned by the :ref:`retrieve endpoint <api.kraken.release.retrieve>`.

    **Example request**:

    .. sourcecode:: http

        GET /kraken/map-types/xyz HTTP/1.1

    **Example response**:

    :>json str mapType: the name of the algorithm.
    :>json dict segmentationMetadata.segmentationColors: RGB colors for
        segmentation classes of given map type. ``segmentationMetadata`` key is
        not present for non-segmentation map types.
    :>json list segmentationHierarchy.baseClasses: List of base classes for given
        map type. Only present for map types that have hierarchy.
    :>json dict segmentationHierarchy.parentClasses: Keys are names of parent
        classes, values are lists of base classes that belong to given parent class.
        Only present for map types that have hierarchy.
    :>json str segmentationHierarchy.masterClass: Master class that all base classes
        belong to. Only present for map types that have hierarchy.
    :>json dict deprecatedClasses: Contains mapping from deprecated previous versions
        to classes which were supported up to the given version. For each class name,
        its RGB color is specified.

    .. sourcecode:: json

        {
            "mapType": "aircraft",
            "segmentationMetadata": {
                "segmentationColors": {
                    "aircraft": [255, 193, 7]
                }
            }
            "segmentationHierarchy": {
                "baseClasses": ["transport", "fighter", "rotary-wing"],
                "parentClasses": {
                    "fixed-wing": ["transport", "fighter"]
                },
                "masterClass": "aircraft",
            },
            "deprecatedClasses": {
                "430.2": {
                    "mig-23": [255, 193, 7]
                }
            },
        }


Kraken Pdf generation
=====================

This is asynchronous API endpoint which creates a PDF with summary of
the analysis.

**Needed Permissions:** ``analytics.analysis.download.report``

.. http:post:: /kraken/pdf-report/initiate

    :<json str analysisId: ID of the analysis to generate pdf from.
    :<json str entityId:   ID of the entity to generate pdf from.
    :<json list mapTypes:  list of map types in frontend naming notation (eg. KRAKEN_IMAGERY)
                           to put into PDF report. Only analysis that is already written
                           in frontend analysis can be used.
    :<json str comment:    optional; comment to be added to the PDF report.
    :<json str subpolygon: optional; ID of the subpolygon that should be used for PDF
                           report.

    **Example request**:

    .. sourcecode:: json

        {
            "analysisId": "abcd",
            "entityId": "abcd",
            "mapTypes": ["KRAKEN_IMAGERY", "CHANGE_DETECTION_SENTINEL&wrt=prev", "SHIPS"],
            "subpolygon": "abcd",
            "comment": "Interesting location with SU-57"
        }

    **Example response**:

    See :ref:`pipeline initiation <api.mechanics.asynchronous.initiate>`.



**Needed Permissions**: ``analytics.analysis.download.report``

.. http:post:: /kraken/pdf-report/retrieve

    **Example request**:

    See :ref:`pipeline retrieve <api.mechanics.asynchronous.retrieve>`.

    :<json str link: link to the PDF with 7-day expiration

    **Example response**:

    .. sourcecode:: json

        {
            "link": "some-long-link"
        }