.. Copyright (C) 2016-2025 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 ` 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 See also :docs:`Kraken API reference`. .. only:: holygrail * URL: http://api.local/kraken For more information about algorithms available for Kraken see :ref:`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 ` (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 `. 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 `. See :docs:`Kraken Initiate` and :docs:`Kraken Retrieve`. **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. .. _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 =================== See :docs:`Kraken Pairwise API reference`. Kraken N-wise API ================= See :docs:`Kraken Nwise API reference`. .. _api.kraken.grid: .. _api.kraken.grid-files: Grid Files ========== See :docs:`Kraken Grid API reference` and :docs:`Kraken Tileless Grid API reference`. ``.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 ============== See :docs:`Kraken Dry Run Initiate API reference` and :docs:`Kraken Dry Run Retrieve API reference`. Kraken MapType List =================== See :docs:`Kraken Map Type List API reference`. Kraken MapType by Map ID ======================== See :docs:`Kraken Map Type by ID API reference`. Kraken Pdf generation ===================== See :docs:`Kraken Pdf Report Initiate API reference` and :docs:`Kraken Pdf Report Retrieve API reference`.