Описания активных областей

Описания активных областей должны быть сформированы отдельно для каждого тайла и для всех уровней масштабирования. В стандартной реализации API в качестве формата описания данных используется JSON.

В JSON-описании активной области необходимо указать:

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

Идентификатор активной области должен быть сгенерирован самостоятельно. Он должен являться уникальным в пределах одного слоя.

Позиция фигуры задается в пиксельных координатах относительно левого верхнего угла соответствующего тайла.

Типы геометрии активных областей в API строго определены. В таблице ниже представлены допустимые типы:

ПримерТип геометрииОписание
RectangleПрямоугольник.
PolygonМногоугольник.*
ConvexPolygonВыпуклый многоугольник.
MultipolygonСложная фигура. Состоит из нескольких многоугольников.
MultiConvexPolygonСложная фигура. Состоит только из выпуклых многоугольников.

* Многоугольники могут иметь внутренний контур. Если многоугольник является выпуклым, то внутренний его контур тоже должен быть выпуклым.

Также в описании активной области можно указать ряд ее свойств, например, содержание балуна или хинта, или z-index области относительно других областей.

Ниже приведен пример описания активных областей:

"data": {
    "type": "FeatureCollection",
    // Массив активных областей.
    "features": [{
        "type": "Feature",
        // Данные активной области.
        "properties": {
            "hintContent": "Содержимое текстовой подсказки.",
            "balloonContentBody": "Содержимое балуна.",
            "balloonContentHeader": "Заголовок балуна.",
            "balloonContentFooter": "Нижняя часть балуна.",
            // Можно задавать свойство balloonContent вместо Body/Header/Footer

            // Обязательное поле
           "HotspotMetaData": {
               // Идентификатор активной области.
               "id": 10469893,

               // Данные, на основе которых создается геометрия активной области.
               // Обязательное поле.
               "RenderedGeometry": {
                   "type": "Polygon",
                   // Координаты многоугольника.
                   "coordinates": [
                       // Первый контур многоугольника.
                       [
                           [-315, 280], [32, 442], [141, 208], [-206, 46], [-315, 280]
                       ],
                       // Второй контур многоугольника.
                       [
                           [-186, 155], [-238, 265], [-152, 306], [-100, 196], [-186, 155]
                       ]
                   ]
               }
           }
        },
    },
    {
        "type": "Feature",
        "properties": {
            // описание следующего хотспотного объекта...
        }
    }]
}

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

На рисунках ниже приведен пример указания координат вершин прямоугольника, попадающего в тайлы [0,0], [1,0], [0,1] и [1,1] (примеры приведены для первых двух тайлов).

Координаты вершин прямоугольника относительно тайла [0,0]:

Координаты вершин прямоугольника относительно тайла [1,0]:

Хранение данных об активных областях

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

API предоставляет возможность использования шаблонов для именования файлов данных. Если файлы именовать в соответствии с определенным шаблоном, то для получения URL данных для каждого тайла API достаточно лишь знать, какой шаблон используется.

Например, пусть шаблон URL данных тайла имеет следующий вид:

http://server.domain/%z/%x/%y

API выполнит следующую подстановку значений: вместо %z — значение коэффициента масштабирования, вместо %x и %y — номер тайла по x и номер тайла по y соответственно. Затем по получившемуся адресу API будет обращаться к серверу за данными для соответствующего тайла.

Например, для тайла [2,3] при z=4 URL данных будет следующим: http://server.domain/4/2/3.

Подробнее об использовании шаблонов можно посмотреть в справочнике.

Примечание. Пользователю API необходимо самостоятельно сформировать описания всех активных областей и позаботиться о том, чтобы сервер возвращал API эти данные, обернутые в json-callback (подробнее см. в разделе Источник данных).