АПІ для роботи з растрами

rtile - АПІ для отримання тайлу

АПІ віддає тайл за переданими параметрами

Параметри

query
param

Параметр	Опис
BBOX	Параметр меж для тайлінгу
bbox	Альтернативний спосіб вказання попереднього параметру
height	Висота вихідного зображення у пікселях
width	Ширина вихідного зображення у пікселях
nocache	Прапорець "чи кешувати отриманий тайл?"
debug	Вмикає дебаг режим роботи АПІ
isS3	Прапорець "чи відбувається тайлінг на s3?"

Параметр	Опис
style	Ідентифікатор файлу конфігурації мапи, яку будемо тайлити
lang	Мова, якою будуть написи на мапі (вказується у загальноприйнятому стандарті скорочення мов)
z	Зум для якого буде рендеритись тайл
x	Горизонтальне положення тайлу на заданому зумі
y	Вертикальне положення тайлу на заданому зумі

Приклад

Без кешування тайлу
З кешування тайлу
Запуск у дебаг режимі

    GET <domainName>/api-user/rtile/:stylr/:z/:x/:y.png?nocache=1

Результат виконання АПІ:

У результаті отримаємо зображення тайлу у форматі png розміром 256p X 256p

    GET <domainName>/api-user/rtile/:stylr/:z/:x/:y.png

Результат виконання АПІ:

Додатково даний тайл буде збережено на сервері за шляхом:

    <workDir>/map/rtile/<style>/<lang>/<z>/<x>/<y>.png

    GET <domainName>/api-user/rtile/:stylr/:z/:x/:y.png?debug=1

Результат виконання АПІ:

{
  "bbound": [
    4187526.1575750955,
    6261721.35712164,
    4226661.916057106,
    6300857.115603653
  ],
  "cmd":"python3 test/debug.py <xml map config path> 4187526.1575750955,6261721.35712164,4226661.916057106,6300857.115603653 <path to save>/1.png"
}

АПІ повертає коорлдинати кутів тайлу у системі координат шару. Також АПІ повертає команду за допомогою якої можна перевірити чи правильно генерується тайл.

⚠️ Warning

Команду для генерації тайлу потрібно виконувати у середовищі де працює сервіс тайлінгу. В залежності від ситуації це може бути система серверу, або Docker-контейнер

⚠️ Warning

Команду для генерації тайлу потрібно виконувати з директорії, де знаходиться код сервісу

gis-layer-pretile

АПІ для виконання операції претайлу (попередньої генерації тайлів) для шару

Параметри

query
param

Параметр	Опис
minzoom	Початкове значення зуму для тайлінгу
maxzoom	Кінцеве значення зуму для тайлінгу

💡 Tip

Параметри minzoom та maxzoom є необов'язковими. За замовчуванням підставляються значення minzoom=6 та maxzoom=16

⚠️ Warning

Максимальна кількість тайлів, які АПІ може згенерувати, обмежено значенням в 100000 тайлів, але один зум буде протайлений у будь-якому випадку, навіть якщо вийти за ліміт

❗️ Warning

АПІ тайлить растр починаючи зі значення зума minzoom і до maxzoom не включно

Параметр	Опис
id	Ідентифікатор файлу конфігурації мапи, яку будемо тайлити

Приклад

Виклик АПІ:

    GET <domainName>/api-user/gis-layer-pretile/:id?minzoom=<minzoom value>&maxzoom=<maxzoom value>

Приклад відповіді:

❗️ Warning

Для правильного виводу потрібно користуватись браузером Google Chrome

gis-layer-compress

АПІ для компресування растрів

👀 Корисна інформація

Для виконання операції компресії використовується gdal-cli команда gdal_translate з наступними параметрами виклику -ot "Byte" -co COMPRESS=lzw -co num_threads=all_cpus -co predictor=2 -co bigtiff=yes -of GTiff -co TILED=YES -b 1 -b 2 -b 3 -colorinterp red,green,blue

Cхема запиту

/api-user/gis-layer-compress/:id

Параметри

param

Параметр	Опис
id	Унікальний ідентифікатор шару у системі

Результат

У результаті отримаємо зкомпресовані файли у директорії <rasterPath>/commpress. Також метаданні операції виводяться у eventStream

Приклади

Компресування одного файлу

Компресування одного файлу
Компресування одного файлу

GET <domainName>/api-user/gis-layer-compress/3266407151156856206

gis-raster

АПІ створення конфігурації для веб мапи. Воно виконує послідовно наступні дії:

Перевірка наявності растру за вказаним шляхом
Створення файлів для прев'ю (оригінальні файли, які були стиснуті у 10 раз)
Створення віртуальних растрів, якщо файлів більше ніж 1
Отримання інформації про місцеположення та систему координат
Формування конфігураційного файлу

💡 Альтернативне використання

АПІ також можна використовувати для отримання загальної інформації про растри, які є у системі.

Cхема запиту

// Отримання даних про растри у системі
/api-user/gis-raster?folder=<folder path>&nocache=<1|0>

// Створення конфігураційного файлу
/api-user/gis-raster/:path?nocache=<1|0>

Параметри

Далі наведено параметри запиту для двох різхних юзерсторі використання АПІ.

Отримання інформації
Формування конфігураційного файлу

query

Параметр	Опис
folder	Шлях до теки з растрами відносно `<workDir>/map/raster`
nocache	Беремо інформацію з кеша чи отримаємо їх заново

param
query

Параметр	Опис
path	Шлях до теки з растрами бо до конкретного растру відносно `<workDir>/map/raster`

Параметр	Опис
nocache	Беремо інформацію про растр з кеша чи отримаємо їх заново

Результат

У результаті ми можемо отримати два різні сценарії:

Отримання загальної інформації про растр/растри у вигляді об'єкта;
Отримання сформованого конфігураційного файлу для веб мапи за шляхом <workDir>/map/mapnik/<raster id>.xml.

Приклади

Приклад відповіді на отримання інформації
Приклад відповіді на формування конфігураційного файлу

{
  "time":104, // час на формування відповіді
  "folder":"z:\\work\\geo\\cardinal\\map\\raster", // директорія знаходження растру
  "rows": [
    {
      "id":"Y29sb3JfcmVsaWVm",   // ідентифікатор растру
      "name":"color_relief",     // назва растру. Якщо це лиректорія - то пишеться назва директорії
      "islayer":false,           // чи є даний растр шаром у системі
      "filename":"color_relief", // ?
      "path":"color_relief",     // шлях до растру відносно директорії <workDir>/map/rsater
      "type":"dir"               // тип растру. Якщо ракстри зберігаються у директорії - то виведе 'dir', інакше - `file`
    }
  ]
}

⚠️ Warning

У даному випадку, додатково до відповіді, пишеться етап виконання формування конфігураційного файлу в eventStream.

Приклад відповіді на формування конфігураційного файлу
Приклад виводу eventStream на формування конфігураційного файлу

{
  "id": "hillshade",                                       // назва растру/директорії
  "extent": [21.9998611,43.9998611,41.0001389,53.0001389], // екстент растру у системі координат EPSG:4326
  "url": "/api-user/rtile/hillshade/ua/{z}/{x}/{y}.png"    // ендпоінт для отримання тайлів на цей шар
}

Приклад

eventStream
data: start raster hillshade 16 ms

data: id: undefined 102 ms

data: proj4: undefined 102 ms

data: Raster File "hillshade" ... Ok 109 ms

data: Start compress 119 files 116 ms

data: Preview 278 ms ... Ok 385 ms

data: VRT "hillshade"... 6 ms ... Ok 391 ms

data: VRT Preview1 "hillshade"... 12 ms ... Ok 397 ms

data: bands: Gray 837 ms

data: srid: undefined  837 ms

data: proj4: undefined ...Ok 837 ms

data: iscompress:undefined z:\work\geo\cardinal\map\raster\hillshade\compressed 1082 ms

data: {"smallRaster":false} 1082 ms

data: [{"name":"mosaic.vrt","size":50415,"extent":[21.9998611,43.9998611,41.0001389,53.0001389],"geom":{"type":"Polygon","coordinates":[[[21.9998611,53.0001389],[21.9998611,43.9998611],[41.0001389,43.9998611],[41.0001389,53.0001389],[21.9998611,53.0001389]]]},"bands":"Gray","crs":"+proj=longlat +datum=WGS84 +no_defs","rasterSize":[68401,32401],"err":"","time":276}] 1082 ms

data: size: 50415 1082 ms

data: bounds: 21.9998611,53.0001389,41.0001389,43.9998611 1082 ms

data: rasterZoom: 14 1082 ms

data: rasterScaling: bilinear 1082 ms

data: xml:1830 1119 ms

data: XML hillshade.xml 303 ms ... Ok 1140 ms

data: Total:1033 ms ... Ok 1140 ms

data: time: preview:278 vrt:12 info:440 xml:303 1140 ms

data: Finish:success 1141 ms

gis-raster-stat

АПІ для отримання метаданих растру за його ідентифікатором.

💡 Де взяти ідентифікатор?

Ідентифікатор растру можна отримати за допомогою АПІ gis-raster

Cхема запиту

GET /api-user/gis-raster-stat/:id

Параметри

param

Параметр	Опис
id	Ідентифікатор растру закодований у `base64`

Результат

У результаті отримуємо об'єкт з описом растру. Якщо растр віртуальний - то буде вказано з яких файлів він складається.

Приклад

Приклад відповіді для одного файлу
Приклад відповіді для теки

{
  "time":22, // час на формування відповіді
  "type":"file", // тип
  "stat": {
    "cdate":"2023-12-18T12:54:58", // час створення файлу
    "edate":"2023-12-18T12:54:58", // час внесення останніх змін
    "size":4469470, // розмір у байтах
    "count":1 // кількість
  },
  "files": [
    {
      "name":"KyivTerrainRgb.tif", // назва файлу
      "size":4469470, // розмір у байтах
      "extent": [29.9998611,49.9998611,31.0001389,51.0001389], // екстент растру
      "geom": { // Опис BBOX у вигляду geojson
        "type":"Polygon",
        "coordinates":[[[29.9998611,51.0001389],[29.9998611,49.9998611],[31.0001389,49.9998611],[31.0001389,51.0001389],[29.9998611,51.0001389]]]
      },
      "bands":"Red,Green,Blue", // послідовність кольорів у бендах
      "crs":"+proj=longlat +datum=WGS84 +no_defs", // система координат растру у вигляді proj4text
      "rasterSize":[3601,3601], // розмір растру у пікселях
      "err":"", // помилки отримання інформації про растр, якщо такі мали місце
      "time":2752 // Час витрачений на отримання даних про растр у мілісекундах
    }
  ]
}

{
  "time": 385, // час витрачений на формування відповіді
  "type": "dir", // тип файлу
  "stat": {
    "cdate": "2023-12-27T10:38:39", // дата створення
    "edate": "2023-12-27T10:38:39", // дата останньої зміни
    "size": null, // розмір у байтах
    "count": 119 // кількість растрів у директорії
  },
  "files": [
    {
      "name":"n44e033.tif.tif" // назва файлу, який входить до директорії
    },
    {
      "name":"n44e034.tif.tif" // назва файлу, який входить до директорії
    }
  ]
}

gis-raster-info

АПІ для отримання метаданих растру/віртуального растру.

Cхема запиту

GET /api-user/gis-raster-info/:id?file=<file_path>&nocache=<1|0>

Параметри

query
param

Параметр	Опис
file	Шлях до файлу растру відносно директорії `<workDir>/map/raster`
nocache	Метадані беруться з кешу чи напряму отримаються з файлу

Результат

У результаті отримаємо об'єкт, який містить у собі метадані файлу, які були отримані за допомогою gdal-cli команди gdalinfo.

Приклад

Запит
Відповідь

GET <domainName>/api-user/gis-raster-info/3266407151156856206

{
  "description": "/data/softpro/work/geo/cardinal/map/raster/DEM-RGB/mosaic.vrt", // шлях до файлу
  "driverShortName":"VRT", // драйвер файлу
  "driverLongName":"Virtual Raster", // повна назва драйверу
  "files": [  
    "/data/softpro/work/geo/cardinal/map/raster/DEM-RGB/mosaic.vrt", // шлях до файлу, який включений у віртуальний растр
    ...,
    "/data/softpro/work/geo/cardinal/map/raster/DEM-RGB/n52e034.tif.tif"
  ],
  "size": [68401,32401], // розмір растру у пікселях
  "coordinateSystem": {
    "wkt": "<srs in wkt>", // опис системи координат у WKT
    "dataAxisToSRSAxisMapping": [ 2, 1 ] // яким чином розміщенні вісі координат у растрі по відношеню до системи координат
  },
  "geoTransform": [ 21.999861111111112, 0.0002777777777778, 0, 53.00013888888889, 0, -0.0002777777777778],
  "metadata": {}, // метадані растру
  "cornerCoordinates": { // опис кутових координат
    "upperLeft": [ 21.9998611, 53.0001389 ],
    "lowerLeft":[ 21.9998611, 43.9998611 ],
    "lowerRight":[ 41.0001389, 43.9998611 ],
    "upperRight":[ 41.0001389, 53.0001389 ],
    "center":[ 31.5, 48.5 ]
  },
  "wgs84Extent": { // опис екстенту у системі координат EPSG:4326
    "type":"Polygon",
    "coordinates": [
      [
        [ 21.9998611, 53.0001389],
        [ 21.9998611, 43.9998611],
        [ 41.0001389, 43.9998611],
        [ 41.0001389, 53.0001389],
        [ 21.9998611, 53.0001389]
      ]
    ]
  },
  "bands": [ // Опис бендів растру
    {
      "band": 1, // порядковий номер бенду
      "block": [ 128, 128 ], // розмір блоку
      "type": "Byte", // тип даних бенду
      "colorInterpretation": "Red", // колір бенду
      "mask": {
        "flags": [ "PER_DATASET", "ALPHA" ],
        "overviews": []
      },
      "metadata": {}
    },
    ...,
    {
      "band": 4,
      "block": [ 128, 128 ],
      "type": "Byte",
      "colorInterpretation": "Alpha",
      "metadata": {}
    }
  ]
}

⚠️ Warning

Поле files є тільки для віртуальних растрів

gis-speed-test

АПІ для перевірки швидкодії тайлінгу.

Схема запиту

/api-user/gis-speed-test?layer=<layer_id>

Параметри

query

Параметр	Опис
layer	Унікальний ідентифікатор шару у системі

Результат

У результаті отримаємо звіт з перевірки швидкодії тайлінгу через eventStream.

Приклад

Запит
Відповідь

GET <domainName>/api-user/gis-speed-test?layer=3266407151156856206

АПІ для роботи з растрами

rtile - АПІ для отримання тайлу​

Параметри​

Приклад​

gis-layer-pretile​

Параметри​

Приклад​

gis-layer-compress​

Параметри​

Результат​

Приклади​

gis-raster​

Параметри​

Результат​

Приклади​

gis-raster-stat​

Параметри​

Результат​

Приклад​

gis-raster-info​

Параметри​

Результат​

Приклад​

gis-speed-test​

Параметри​

Результат​

Приклад​

rtile - АПІ для отримання тайлу

Параметри

Приклад

gis-layer-pretile

Параметри

Приклад

gis-layer-compress

Параметри

Результат

Приклади

gis-raster

Параметри

Результат

Приклади

gis-raster-stat

Параметри

Результат

Приклад

gis-raster-info

Параметри

Результат

Приклад

gis-speed-test

Параметри

Результат

Приклад