Доступ и загрузка данных обучения в Radiant MLHub API

Автор: Кевин Бут, разработчик геопространственных данных, Radiant Earth Foundation

Эта статья представляет собой вводное руководство, которое поможет вам ориентироваться в Radiant MLHub API и загружать данные обучения. Рекомендуются базовые знания JSON и навигация по RESTful API с помощью Python.

Основы Radiant MLHub API

Radiant MLHub API - это STAC-совместимый API, который предоставляет метаданные об элементах ярлыков и исходных изображениях, а также ссылки для загрузки этих элементов.

STAC - это организация метаданных для изображений и меток, упрощающая поиск элементов, соответствующих пространственным, временным или другим критериям. На корневом уровне API STAC находится список коллекций элементов. В API Radiant MLHub каждая коллекция содержит элементы либо для исходных изображений, либо для меток для набора данных. Эти элементы представляют собой описания исходных изображений или ярлыков и ссылок для загрузки ресурсов, связанных с этими элементами. Свойства, найденные в этих описаниях элементов, включают пространственную протяженность, временную протяженность, описания полос в случае оптических изображений, типы меток и свойства меток в случае меток, а также другую информацию, такую как DOI и примеры цитирования для ссылки.

Аутентификация

Чтобы получить доступ к API, вы должны быть аутентифицированы с помощью ключа API, который вы можете получить в Radiant MLHub Dashboard. Все запросы к API должны выполняться с ключом API, присутствующим в параметрах запроса, как показано ниже:

https://api.radiant.earth/mlhub/v1/collection?key=YOUR_API_KEY_HERE

Ссылки для скачивания

Ссылки на внешние ресурсы (документация, файлы geojson, файлы изображений и т. Д.) Заменяются ссылкой на конечную точку / download API. Ниже приведен пример такой ссылки.

https://api.radiant.earth/mlhub/v1/download/fd965acfbd8583cc5231ba6f98bbc7412a7e569e74a2b03745c6c962aa0c9fc6

Эти ссылки уникальны для вас и истекают через 6 часов. Если вам нужно повторно загрузить ресурс после истечения срока действия ссылки, просто повторите запрос к API, и будет сгенерирована новая ссылка. Эти ссылки для загрузки возвращают ответ перенаправления HTTP на ресурс. Вы можете прочитать заголовок Location, чтобы получить фактический URI ресурса. Иногда возвращаемая схема URI не всегда является HTTP-ресурсом. Например, если ресурс размещен в корзине S3, будет возвращен URI, как показано ниже:

s3://somebucket/foo/bar/object.txt

При загрузке ресурсов следует проверить, какая схема присутствует в URI, и загрузить ее соответствующим методом. У нас есть пример этого в нашей Учебной тетради BigEarthNet.

Пейджинг

Конечные точки / collections и / collections / COLLECTION_ID / items не всегда возвращают все свои элементы сразу. Вместо этого возвращаются страницы результатов. Чтобы перейти на следующую страницу результатов, вы можете найти ссылку на следующую страницу в свойстве links, которое будет иметь тип rel, равный next. Для получения дополнительной информации о разбиении по страницам см. Спецификацию STAC API.

Наборы данных на Radiant MLHub

Наборы данных на Radiant MLHub обычно делятся на две коллекции STAC: одна содержит элементы STAC для исходных изображений, а другие элементы STAC для этикеток. Например, набор данных Chesapeake Bay разделен на шесть коллекций: метки контуров зданий, метки земного покрова Chesapeake Conservancy, метки земного покрова NLCD, изображения NAIP, листовой спутник Landsat 8 и составной лист Landsat 8. Мы сделали это по двум причинам. Первая причина состоит в том, что это исключает необходимость проверять, является ли элемент в коллекции элементом исходного изображения или элементом ярлыка. Вы всегда можете предположить, что элементы в коллекции меток являются элементами меток, а элементы в коллекции исходных изображений являются элементами исходных изображений. Вторая причина, по которой мы разделили эти две группы, заключается в том, что несколько коллекций этикеток могут использовать одни и те же исходные изображения. Если исходные изображения должны содержаться в той же коллекции, что и ярлыки, то будут дублироваться элементы исходных изображений. На практике вам никогда не придется напрямую искать в коллекциях исходных изображений. Элементы ярлыков будут содержать ссылки на исходные изображения, относящиеся к этому конкретному ярлыку.

Обозначить элементы

Элементы метки - это объект JSON со свойствами, описывающими тип метки, возможные значения метки, пространственные и временные размеры и ссылки на ресурсы метки для загрузки. Пример из набора данных BigEarthNet показан ниже:

{
  "labels":[
    "Sea and ocean"
  ],
  "seasonal_snow":false,
  "cloud_and_shadow":false,
  "datetime":"2018-05-29T11:54:01Z",
  "label:description":"Land Cover Type Classification",
  "label:type":"vector",
  "label:classes":[
    {
      "name":"labels",
      "classes":[
        "Discontinuous urban fabric",
        "Non-irrigated arable land",
        "Pastures",
        "Coniferous forest",
        "..."
      ]
    },
    {
      "name":"seasonal_snow",
      "classes":[
        "True",
        "False"
      ]
    },
    {
      "name":"cloud_and_shadow",
      "classes":[
        "True",
        "False"
      ]
    }
  ]
}

Активы: этикетки и документация

Раздел ресурсов будет содержать ссылки на файлы документации и файл geojson в случае векторных меток или tiff в случае растровых меток. Свойство assets структурировано как словарь, а элементы, содержащие ссылку на метки, всегда имеют ключевые «метки». Ниже приведен отрывок из того же элемента лейбла BigEarthNet.

{
  "labels": {
    "href": "s3://radiant-mlhub/bigearthnet/labels/S2A_MSIL2A_20180529T115401_84_58.geojson",
    "title": "Land Type Classes"
  }
}

Ссылки: Исходные изображения

Раздел ссылок содержит ссылки на корень каталога, родительскую коллекцию и исходные элементы изображений. Вы можете определить, к какому типу относится каждая ссылка, прочитав свойство «rel». Элементы исходного изображения будут иметь свойство rel для source.

[
  {
    "rel": "source",
    "href": "https://api.radiant.earth/mlhub/v1/collections/bigearthnet_v1_source/items/bigearthnet_v1_labels_S2A_MSIL2A_20180529T115401_84_58",
    "type": "application/json"
  },
  {
    "rel": "parent",
    "href": "https://api.radiant.earth/mlhub/v1/collections/bigearthnet_v1_labels",
    "type": "application/json"
  },
  {
    "rel": "root",
    "href": "https://api.radiant.earth/mlhub/v1/",
    "type": "application/json"
  }
]

Исходные изображения

Элементы исходных изображений содержат всю информацию, необходимую для определения места и времени, когда был сделан снимок, а также ссылки для загрузки либо отдельных каналов изображений, либо файлов с несколькими диапазонами. Метаданные, связанные с датчиком и платформой, используемой для получения изображения, также включаются в элемент исходного изображения.

Ресурсы

Ресурсы (то есть файлы GeoTIFF) связаны в свойстве assets исходного элемента изображения. В зависимости от набора данных будет либо один многополосный ресурс, либо несколько однодиапазонных ресурсов, либо их комбинация.

Дополнительные свойства

Может быть полезно знать другие аспекты элемента исходного изображения, например, когда и где был сделан снимок. Свойство datetime отвечает части «когда» в объекте свойств. Часть "где" отвечает геометрией и свойствами элемента bbox. В приведенном ниже примере показан элемент исходного изображения, содержащий три одноканальных файла.

{
  "id":"bigearthnet_v1_source_S2A_MSIL2A_20180529T115401_77_67",
  "collection":"bigearthnet_v1_source",
  "type":"Feature",
  "properties":{
      "datetime":"2018-05-29T11:54:01Z",
      "eo:bands":[
         {
            "common_name":"Blue",
            "description":"Blue",
            "name":"B02"
         },
         {
            "common_name":"Green",
            "description":"Green",
            "name":"B03"
         },
         {
            "common_name":"Red",
            "description":"Red",
            "name":"B04"
         }
      ],
      "eo:constellation":"Sentinel-2",
      "eo:gsd":30,
      "eo:instrument":"MSI",
      "eo:platform":"Sentinel-2"
   },
   "assets":{
      "B02":{
         "eo:bands":[],
         "href":"https://api.radiant.earth/mlhub/v1/download/B02DOWNLOAD",
         "title":"S2A_MSIL2A_20180529T115401_77_67_B02",
         "type":"image/tiff; application=geotiff; profile=cloud-optimized"
      },
      "B03":{
         "eo:bands":[],
         "href":"https://api.radiant.earth/mlhub/v1/download/B03DOWNLOAD",
         "title":"S2A_MSIL2A_20180529T115401_77_67_B03",
         "type":"image/tiff; application=geotiff; profile=cloud-optimized"
      },
      "B04":{
         "eo:bands":[],
         "href":"https://api.radiant.earth/mlhub/v1/download/B04DOWNLOAD",
         "title":"S2A_MSIL2A_20180529T115401_77_67_B04",
         "type":"image/tiff; application=geotiff; profile=cloud-optimized"
      }
   },
   "bbox":[
      -7.548429099733649,
      3.7845317195412,
      36.08348843294896,
      55.214656159591776
   ],
   
   "geometry":{
      "coordinates":[
         [
            [
               36.08348843294896,
               3.7845317195412
            ],
            [
               36.08348843294896,
               55.214656159591776
            ],
            [
               -7.548429099733649,
               55.214656159591776
            ],
            [
               -7.548429099733649,
               3.7845317195412
            ],
            [
               36.08348843294896,
               3.7845317195412
            ]
         ]
      ],
      "type":"Polygon"
   },
   "stac_extensions":[
      "eo"
   ]
}

Доступ и загрузка данных обучения в Radiant MLHub API

Основы Radiant MLHub API

Аутентификация

Ссылки для скачивания

Пейджинг

Наборы данных на Radiant MLHub

Обозначить элементы

Активы: этикетки и документация

Ссылки: Исходные изображения

Исходные изображения

Ресурсы

Дополнительные свойства

Рекомендуемый рабочий процесс

Ресурсы

Вопросы по теме