Линии и многоугольники

С помощью ломаных линий и многоугольников на статической карте можно обозначить маршруты следования или границы объектов.

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

Многоугольник задается одной или несколькими замкнутыми ломаными.

Ограничение. Static API позволяет одновременно отобразить на карте не более 5 ломаных и многоугольников, при этом совокупное количество вершин фигур не должно превышать 100.

Внешний вид геометрической фигуры задается с помощью специального описания. Описание ломаной содержит данные о толщине и цвете линии, а описание многоугольника - данные о толщине и цвете линий обводки и цвете заливки (см. ниже).

Вершины всех фигур привязаны к географическим координатам.

Координаты вершин и внешний вид линий и многоугольников задаются с помощью параметра pl. Параметр содержит набор описаний всех фигур, отображаемых на карте. Описания фигур перечисляются через тильду (~): 

pl = ОписаниеФигуры1~ОписаниеФигуры2~ОписаниеФигуры3

Описание ломаной имеет следующий формат: 

c:{цвет линии},w:{толщина},bc{цвет обводки},bw{толщина обводки},{вершины}

Описание многоугольника дополнительно может содержать цвет заливки (параметр f) или обводку линий: 

c:{цвет линии},f:{цвет заливки},w:{толщина},{вершины}

Цвет линии

Шестнадцатеричное представление цвета линии в формате RGBA (вида 0xFFFFFFFF). Первые 6 символов задают цвет в системе RGB, последующие два — прозрачность линии. Значение прозрачности лежит в диапазоне от 00 (прозрачная) до FF (непрозрачная).

Например:

c:8822DDC0

Цвет заливки многоугольника

Используется тот же самый формат, что и для цвета ломаной (см. выше). Например:

f:00FF00A0

Для заливки многоугольника применяется алгоритм even-odd. То есть верно следующее правило: точка закрашивается, если луч, проведенный в бесконечность из этой точки, имеет нечетное количество пересечений с ребрами многоугольника.

Область пересечения нескольких многоугольников закрашивается всегда.

Толщина

Толщина линии (в пикселах).

w:8
Примечание. Если цвет и толщина не заданы, то используется сиреневая полупрозрачная линия толщиной 5 пикселов (8822DDC0).

Толщина обводки линии

Толщина линии обводки (в пикселах). По умолчанию толщина 0 пикселей.

bw:8

Цвет обводки линии

Шестнадцатеричное представление цвета обводки линии в формате RGBA (вида 0xFFFFFFFF). Первые 6 символов задают цвет в системе RGB, последующие два — прозрачность линии. Значение прозрачности лежит в диапазоне от 00 (прозрачная) до FF (непрозрачная). По умолчанию используется обводка белого цвета.

Например:

bc:8822DDC0

Вершины

Координаты вершин ломаной задаются одним из следующих способов:
  • Долгота1,Широта2,...,ДолготаN,ШиротаN;
  • Строкой, закодированной в Base64 формате.
    Пример кодирования координат в формат Base64

    1. Запишите координаты вершин ломаной друг под другом, по одной вершине в строке.

      37.593578 55.735094
37.592159 55.732469
37.589374 55.734162

    2. Умножьте каждую координату на 1 000 000.

      37593578 55735094
37592159 55732469
37589374 55734162

    3. Рассчитайте смещения для второй и последующих точек ломаной. 

      37593578 55735094
-1419 -2625
-2785 1693

    4. Переведите каждое из получившихся чисел в двоичную систему счисления. Дополните получившиеся значения недостающими нулями слева до 4 байтов (32 бита).

      В итоге последовательность чисел будет иметь следующий вид (по одной координате в строке):

      00000010001111011010000111101010
00000011010100100111001100110110
11111111111111111111101001110101
11111111111111111111010110111111
11111111111111111111010100011111
00000000000000000000011010011101

    5. Произведите кодирование последовательно по четыре байта. Каждые шесть бит необходимо перевести в десятичную систему счисления — это будет номер символа в строке, используемой для кодирования.

      Строка, используемая для кодирования, имеет следующий вид:

      ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_=
      Примечание. Данная строка отличается от строки, которая используется при кодировании в Base64. Дело в том, что строка с закодированными вершинами должна без ограничений передаваться в качестве параметра URL, а символы "+" и "/" в URL являются спецсимволами.

      В качестве примера ниже приводится алгоритм кодирования первого набора из 4-х байтов:

      1. Измените порядок следования байтов на обратный.

        Прямой порядок:

        00000010 00111101 10100001 11101010

        Обратный порядок:

        11101010 10100001 00111101 00000010

      2. Считывайте последовательно по шесть бит, чтобы получить номера символов:

        111010 -> символ № 58 -> символ "6"
101010 -> символ № 42 -> символ "q"
000100 -> символ № 04 -> символ "E"
111101 -> символ № 61 -> символ "9"
000000 -> символ № 00 -> символ "A"
10

        Недостающие для получения последнего символа биты берутся из следующей последовательности из четырех байтов.

        Примечание. После обработки всех байтов может сложиться ситуация, когда останется либо два, либо четыре бита, которых недостаточно для получения номера символа. Тогда каждые два недостающих бита заменяются символом "=".

      3. Общий вид закодированной в Base64 строки:

        6qE9AjZzUgN1-v__v_X__x_1__-dBgAA

Координаты вершин многоугольника, заданного одной замкнутой ломаной (первая и последняя вершины совпадают), указываются аналогично.

Для того, чтобы задать многоугольник набором замкнутых ломаных, необходимо разделять последовательности вершин для каждой ломаной точкой с запятой: КоординатыВершинЛоманой1;...КоординатыВершинЛоманой2.

Примеры

Ломаная

Ниже приведен пример запроса фрагмента карты Москвы с изображением пешеходного маршрута от станции метро "Марксистская" до здания по ул. Станиславского 21, строение 3. Вершины ломаной заданы перечислением координат вершин, цвет и ширина взяты по умолчанию:

https://static-maps.yandex.ru/1.x/?l=map&pl=37.656577,55.741176,37.656748,55.741419,37.655131,55.741814,37.658257,55.742524,37.659811,55.743066,37.659667,55.743233,37.659551,55.743603,37.659775,55.743928,37.662398,55.745281

Многоугольник, заданный одной ломаной

Ниже приведен пример запроса фрагмента карты Санкт-Петербурга с изображением границы стен Петропавловской крепости. Для обозначения границ использован многоугольник с красной линией обводки и светло-зеленой полупрозрачной заливкой. 

https://static-maps.yandex.ru/1.x/?l=map&size=400,400&pl=c:ec473fFF,f:00FF00A0, w:7,30.310514,59.948631,30.311080,59.949172,30.310290,59.949842,30.313011,59.950460,30.312688,59.950275,30.313029,59.950135,30.315015,59.951091,30.314871,59.951235,30.314637,59.951199,30.314601,59.951248,30.315625,59.952023,30.316999,59.951816,30.316963,59.951744,30.316649,59.951735,30.316747,59.951541,30.319074,59.951519,30.319173,59.951708,30.318876,59.951739,30.318876,59.951812,30.321482,59.952194,30.321401,59.951478,30.322703,59.951181,30.322101,59.950748,30.322730,59.950203,30.320305,59.949604,30.319775,59.949793,30.318589,59.949293,30.318598,59.949248,30.318463,59.949180,30.318409,59.949189,30.318059,59.949049,30.318436,59.948756,30.317870,59.948252,30.316577,59.948346,30.316415,59.948585,30.313954,59.948549,30.313945,59.948351,30.313864,59.948162,30.311501,59.947869,30.311636,59.948527,30.310514,59.948631

Многоугольник, заданный набором ломаных

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

https://static-maps.yandex.ru/1.x/?ll=37.620070,55.753630&pl=f:00FF00A0,37.610000,55.743630,37.610070,55.763630,37.630070,55.763630,37.630070,55.743630,37.610000,55.743630;37.600070,55.733630,37.600070,55.773630,37.640070,55.773630,37.640070,55.733630,37.600070,55.733630&l=map

Пересечение многоугольников

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

Область пересечения многоугольников всегда закрашивается.
https://static-maps.yandex.ru/1.x/?l=map&pl=c:cd5b45,f:2222DDC0,w:5,37.656705,55.741092,37.653551,55.742387,37.663805,55.744318,37.656705,55.741092~c:dc143c,f:8822DDC0,w:5,37.660286,55.743301,37.661831,55.745165,37.662947,55.743108,37.660286,55.743301