osmgl 0.7.3 → 0.8.0

package/dist/osmgl.d.cts

@@ -697,6 +697,69 @@ declare class Shader {
     destroy(): void;
 }
 
+/**
+ * Разбор Mapbox Vector Tile (spec 2.1) — наш тайлсервер отдаёт именно его
+ * (схема OpenMapTiles v3: building / transportation / water / landuse / poi …).
+ *
+ * Читаем «лениво»: сначала только оглавление слоёв, геометрию каждой фичи
+ * распаковываем по требованию. На тайл с 20 тыс. фич это разница между
+ * 40 мс и 3 мс, когда генератору нужен один слой из пятнадцати.
+ */
+declare const enum GeomType {
+    Unknown = 0,
+    Point = 1,
+    LineString = 2,
+    Polygon = 3
+}
+type PropValue = string | number | boolean | null;
+/** Кольцо/линия: плоский массив [x0,y0,x1,y1,...] в координатах тайла [0..extent]. */
+type Ring = number[];
+declare class VectorTileFeature {
+    private pbf;
+    readonly keys: string[];
+    readonly values: PropValue[];
+    readonly extent: number;
+    id?: number;
+    type: GeomType;
+    properties: Record<string, PropValue>;
+    /** Позиция блока геометрии в буфере; -1 — геометрии нет. Пишется читателем полей. */
+    geomOffset: number;
+    constructor(pbf: Pbf, keys: string[], values: PropValue[], extent: number);
+    static read(pbf: Pbf, end: number, keys: string[], values: PropValue[], extent: number): VectorTileFeature;
+    /** Кольца/линии фичи. Для полигонов внешние и внутренние идут вперемешку — см. splitPolygons. */
+    loadGeometry(): Ring[];
+    /** BBox фичи в координатах тайла — дешёвый отсев до триангуляции. */
+    bbox(): [number, number, number, number];
+}
+declare class VectorTileLayer {
+    private pbf;
+    version: number;
+    name: string;
+    extent: number;
+    readonly featureOffsets: number[];
+    readonly keys: string[];
+    readonly values: PropValue[];
+    constructor(pbf: Pbf);
+    static read(pbf: Pbf, end: number): VectorTileLayer;
+    get length(): number;
+    feature(i: number): VectorTileFeature;
+    /** Итератор по всем фичам слоя. */
+    features(): Generator<VectorTileFeature>;
+}
+declare class VectorTile {
+    readonly layers: Record<string, VectorTileLayer>;
+    constructor(buffer: ArrayBuffer | Uint8Array);
+}
+/**
+ * Разбивает кольца полигона на группы «внешнее + его дырки».
+ * Ориентация по знаку площади: в MVT внешние кольца по часовой (положительная
+ * площадь в системе с Y вниз), дырки — против.
+ */
+declare function splitPolygons(rings: Ring[]): {
+    outer: Ring;
+    holes: Ring[];
+}[];
+
 /**
  * Формат стиля движка.
  *
@@ -1442,6 +1505,100 @@ interface StyleSpec {
  */
 declare const DEFAULT_LIGHT: LightSpec;
 
+/**
+ * Генератор геометрии зданий: экструзия полигонов слоя `building` (схема OpenMapTiles v3).
+ * Работает в воркере, отдаёт готовые типизированные массивы — они уходят в главный
+ * поток transfer'ом (без копирования) и грузятся в GPU как есть.
+ *
+ * Формат вершины (stride 18 байт):
+ *   a_pos     2 × Int16   off 0   координаты тайла [0..extent]
+ *   a_height  1 × Uint16  off 4   высота вершины в метрах × 4 (до 16383 м, шаг 0.25)
+ *   a_tint    1 × Uint8   off 6   оттенок здания (одинаков у всех его вершин)
+ *   a_ao      1 × Uint8   off 7   0 — основание, 255 — верх
+ *   a_normal  3 × Int8n   off 8   нормаль
+ *   a_kind    1 × Uint8   off 11  тип поверхности и класс фасада
+ *   a_wall    3 × Uint16  off 12  фасад: смещение вдоль грани, её ширина и высота (метры × 4)
+ *
+ * Высота ушла из Float32 в Uint16 ради места под a_tint: без разброса оттенка
+ * квартал выглядит одной сплошной массой.
+ *
+ * `a_wall` появился ради РОВНОЙ раскладки окон. Сначала координата вдоль стены
+ * считалась в шейдере как проекция позиции на её направление — сетка тогда общая
+ * на всю карту, и грань режет её где придётся: у угла дома получается половина
+ * окна, а простенки у разных стен разной ширины. Ширина и высота грани позволяют
+ * ВПИСАТЬ сетку в неё: поля по краям, целое число ячеек, окно целиком.
+ */
+declare const BUILDING_VERTEX_STRIDE = 18;
+/** Множитель упаковки высоты в Uint16. */
+declare const BUILDING_HEIGHT_SCALE = 32;
+/**
+ * Множитель упаковки ПОЛОЖЕНИЯ вершины: сколько единиц Int16 приходится на единицу тайла.
+ *
+ * Было единица — то есть 0.47 м на z14, потому что координаты в MVT целые и вершину писали как
+ * есть. Пока углы дома были прямыми, этого хватало: вершина и так стояла в узле сетки. Со
+ * СКРУГЛЕНИЕМ хватать перестало — дуга радиусом 1.6 м это семь точек в пределах трёх единиц тайла,
+ * и округление сажает их на ту же сетку: вместо дуги выходит лесенка со ступенью в полметра, она же
+ * «угловатость» на ближнем зуме.
+ *
+ * Восемь единиц на тайловую — это 5.9 см, и дуга снова читается дугой. Потолок: тайл 0..4096, при
+ * ×8 это 0..32768, и последнее значение на единицу больше, чем помещается в Int16, — оно
+ * прижимается (`clampI16`). Ошибка при этом 6 см и только у вершины, стоящей ровно на дальней
+ * границе тайла.
+ */
+declare const BUILDING_POS_SCALE = 8;
+interface BuildingsMesh {
+    vertices: ArrayBuffer;
+    indices: ArrayBuffer;
+    /** Uint32Array: id фичи на каждый треугольник — для пикинга и подсветки. */
+    featureIds: ArrayBuffer;
+    vertexCount: number;
+    indexCount: number;
+    extent: number;
+}
+interface BuildingsOptions {
+    /**
+     * Радиус скругления углов в МЕТРАХ. Скругляется контур, а значит и стены, и
+     * крыша — она строится по тому же кольцу. Ноль (по умолчанию) — острые углы,
+     * как раньше.
+     */
+    cornerRadius?: number;
+    /** Максимум отрезков на дугу: меньше — дешевле и угловатее. */
+    cornerSegments?: number;
+    /**
+     * Сколько метров в одной единице тайла. Нужен, чтобы решать по РАЗМЕРУ: дом
+     * в сотню квадратов получает скатную крышу, торговый центр — плоскую. Без
+     * него один и тот же порог на разных зумах означал бы разные здания.
+     */
+    metersPerUnit?: number;
+}
+declare function generateBuildings(layer: VectorTileLayer, extent: number, filter?: Filter, options?: BuildingsOptions, 
+/**
+ * Куда складывать дома, задевающие границу тайла.
+ *
+ * Задан — такие дома здесь НЕ строятся: из куска правильной геометрии не выйдет, их соберут из
+ * всех кусков сразу. Не задан — прежнее поведение, каждый кусок сам по себе.
+ */
+seams?: BuildingSeam[]): BuildingsMesh | null;
+/**
+ * Кусок дома, задевающего границу тайла: контур с пометкой ЛОЖНЫХ рёбер.
+ *
+ * Уезжает на главный поток, чтобы там сложиться с кусками соседних тайлов в целый дом.
+ * Кольца — в координатах СВОЕГО тайла; общую систему строит уже сборщик, он знает номера тайлов.
+ */
+interface BuildingSeam {
+    osmId: number;
+    height: number;
+    minHeight: number;
+    seed: number;
+    tint: number;
+    facade: number;
+    outer: number[];
+    holes: number[][];
+    /** `cut[i]` — ребро от вершины i к i+1 порождено обрезкой, а не стеной дома. */
+    outerCut: boolean[];
+    holeCuts: boolean[][];
+}
+
 /**
  * План для воркера и общие с ним имена.
  *
@@ -1523,69 +1680,6 @@ declare const BASE_SOURCE = "base";
 declare const SPLIT_SEP = "\u241F";
 declare const splitBucketKey: (layerId: string, value: string | number) => string;
 
-/**
- * Разбор Mapbox Vector Tile (spec 2.1) — наш тайлсервер отдаёт именно его
- * (схема OpenMapTiles v3: building / transportation / water / landuse / poi …).
- *
- * Читаем «лениво»: сначала только оглавление слоёв, геометрию каждой фичи
- * распаковываем по требованию. На тайл с 20 тыс. фич это разница между
- * 40 мс и 3 мс, когда генератору нужен один слой из пятнадцати.
- */
-declare const enum GeomType {
-    Unknown = 0,
-    Point = 1,
-    LineString = 2,
-    Polygon = 3
-}
-type PropValue = string | number | boolean | null;
-/** Кольцо/линия: плоский массив [x0,y0,x1,y1,...] в координатах тайла [0..extent]. */
-type Ring = number[];
-declare class VectorTileFeature {
-    private pbf;
-    readonly keys: string[];
-    readonly values: PropValue[];
-    readonly extent: number;
-    id?: number;
-    type: GeomType;
-    properties: Record<string, PropValue>;
-    /** Позиция блока геометрии в буфере; -1 — геометрии нет. Пишется читателем полей. */
-    geomOffset: number;
-    constructor(pbf: Pbf, keys: string[], values: PropValue[], extent: number);
-    static read(pbf: Pbf, end: number, keys: string[], values: PropValue[], extent: number): VectorTileFeature;
-    /** Кольца/линии фичи. Для полигонов внешние и внутренние идут вперемешку — см. splitPolygons. */
-    loadGeometry(): Ring[];
-    /** BBox фичи в координатах тайла — дешёвый отсев до триангуляции. */
-    bbox(): [number, number, number, number];
-}
-declare class VectorTileLayer {
-    private pbf;
-    version: number;
-    name: string;
-    extent: number;
-    readonly featureOffsets: number[];
-    readonly keys: string[];
-    readonly values: PropValue[];
-    constructor(pbf: Pbf);
-    static read(pbf: Pbf, end: number): VectorTileLayer;
-    get length(): number;
-    feature(i: number): VectorTileFeature;
-    /** Итератор по всем фичам слоя. */
-    features(): Generator<VectorTileFeature>;
-}
-declare class VectorTile {
-    readonly layers: Record<string, VectorTileLayer>;
-    constructor(buffer: ArrayBuffer | Uint8Array);
-}
-/**
- * Разбивает кольца полигона на группы «внешнее + его дырки».
- * Ориентация по знаку площади: в MVT внешние кольца по часовой (положительная
- * площадь в системе с Y вниз), дырки — против.
- */
-declare function splitPolygons(rings: Ring[]): {
-    outer: Ring;
-    holes: Ring[];
-}[];
-
 /**
  * Сбор подписей из тайла.
  *
@@ -1683,13 +1777,17 @@ interface GeometryMesh {
     vertexCount: number;
     indexCount: number;
     extent: number;
-    /** Только для зданий: id фичи на треугольник (пикинг, подсветка). */
+    /** id фичи на треугольник: пикинг, подсветка и вырезание заменённых моделью фич. */
     featureIds?: ArrayBuffer;
     /**
      * Только для поверхностей: сколько индексов в начале — обычная геометрия.
      * Хвост после них — крышки островов, их рисуют отдельно и только в глубину.
      */
     capIndexOffset?: number;
+    /** Только для поверхностей: фичи каждой объединённой фигуры, `[сколько, id, …]`. */
+    shapeFeatures?: ArrayBuffer;
+    /** Только для поверхностей: где треугольники каждой фигуры, по четыре числа на фигуру. */
+    shapeRanges?: ArrayBuffer;
 }
 /**
  * Подписи: геометрии нет, только точки привязки и строки. Раскладка глифов и
@@ -1737,6 +1835,13 @@ interface LoadedResponse {
      * У разбитых слоёв (`splitBy`) ключ составной — см. `splitBucketKey`.
      */
     buckets: Record<string, BucketMesh>;
+    /**
+     * Дома, задевающие границу тайла: контуры с пометкой ложных рёбер.
+     *
+     * В `buckets` их НЕТ — из куска правильной геометрии не построить. Главный поток складывает
+     * куски соседних тайлов и собирает целый дом (см. `generators/stitch.ts`).
+     */
+    seams?: BuildingSeam[];
     /**
      * Какие значения разбиения встретились в этом тайле: имя свойства → значения.
      * По ним строится переключатель этажей — иначе клиенту неоткуда узнать, какие
@@ -2043,6 +2148,15 @@ declare class TileSource extends Evented<TileSourceEvents> {
      * куда пользователь заезжал за сеанс.
      */
     splitValues(property: string): (string | number)[];
+    /**
+     * Все ЗАГРУЖЕННЫЕ тайлы, а не только видимые.
+     *
+     * Нужно сборщику домов на границе (`layers/seams.ts`): дом собирается из кусков нескольких
+     * тайлов, и стоит одному уехать из вида, как его кусок пропал бы из сборки — а на карте у
+     * здания отвалилась бы половина. В кеше тайл живёт заметно дольше, чем в кадре, и этого хватает,
+     * чтобы здание оставалось целым всю дорогу.
+     */
+    loadedTiles(): Iterable<[string, Tile]>;
     get pendingCount(): number;
     /** Пересчитывает видимый набор под текущую камеру и запускает недостающие загрузки. */
     update(tr: Transform): void;
@@ -3619,6 +3733,8 @@ declare class LayerRenderer {
      * перелёт через город.
      */
     private patternScale;
+    /** Красить каждый тайл своим цветом — отладка стыков. См. `Map.setDebugTiles`. */
+    debugTiles: boolean;
     /** Камера в метрах от мирового нуля — считается раз на кадр (см. render). */
     private cameraMeters;
     /** Пикселей буфера на пиксель вида — считается раз на кадр (см. render). */
@@ -3709,6 +3825,19 @@ declare class LayerRenderer {
      * подмешивать в неё чужой набор оказалось ненадёжно.
      */
     hiddenBuildings: ReadonlySet<number>;
+    /** Сборщик домов, разрезанных границей тайла. См. `layers/seams.ts`. */
+    private readonly seams;
+    /** GPU-буферы сшитых домов по ключу тайла-хозяина. */
+    private seamGpu;
+    /**
+     * Скрытые дома ПЛЮС собранные сборщиком — ПО ТАЙЛАМ.
+     *
+     * Именно по тайлам, а не одним списком на карту: замена собирается из тех кусков, что сейчас
+     * загружены, и кусок, не вошедший в сборку, обязан рисоваться сам. Иначе часть здания, уехавшая
+     * за край экрана вместе со своим тайлом, просто пропадала. Считается один раз на смену состава
+     * (см. `syncHiddenStamp`), а не на каждый тайл каждого объёмного слоя.
+     */
+    private hiddenWithSeams;
     /**
      * То же для оболочек планов этажей (`indoor-venue`).
      *
@@ -3737,6 +3866,32 @@ declare class LayerRenderer {
      * каждый тайл каждого объёмного слоя, то есть десятки раз за кадр.
      */
     private syncHiddenStamp;
+    /**
+     * Поверхность без фигур, целиком заменённых 3D-моделями.
+     *
+     * Отдельно от `cutHidden`, потому что поверхность устроена иначе. Во-первых, треугольник тут
+     * принадлежит ФИГУРЕ, а фигура — нескольким фичам сразу (соседние газоны сварены в один контур),
+     * и убрать её можно, только если скрыты все до одной. Во-вторых, у поверхности два прохода:
+     * крышки островов рисуются отдельно, хвостом буфера, и после резки их адреса сдвигаются.
+     */
+    private cutSurface;
+    /**
+     * Какие фичи ЕСТЬ в бакете. Живёт до перезагрузки тайла и переживает смену набора замен.
+     *
+     * Ограничен по размеру грубо, сбросом целиком: записи вытесненных тайлов сами по себе не уходят,
+     * а точный учёт стоил бы больше, чем пересчёт пары сотен списков раз в долгую сессию.
+     */
+    private bucketIdCache;
+    /** Разобранные поверхности без заменённых фигур. Сбрасывается вместе с `hiddenCut`. */
+    private surfaceCut;
+    private bucketIds;
+    /**
+     * Что заменено 3D-моделями. Для заливок и линий — единственный набор, который к ним применим.
+     *
+     * Швы сюда не идут: они про дома, разрезанные границей тайла, а дорожка режется по своей.
+     * Пустой набор `cutHidden` пропускает даром, поэтому проверять его снаружи не нужно.
+     */
+    private replacedIds;
     /** Набор, которым режется слой: у домов свой, у оболочек планов свой. */
     private hiddenFor;
     /**
@@ -3929,6 +4084,13 @@ declare class LayerRenderer {
      * порядке его закрыла бы крыша.
      */
     private drawOverlay;
+    /**
+     * Цвет отладочной подкраски тайла: постоянный для одного адреса и разный у соседей.
+     *
+     * Соседи обязаны отличаться заметно, иначе смысл теряется, поэтому оттенок берём не хешем, а
+     * прямо по чётности координат — шесть цветов по кругу, и любые два смежных тайла всегда разные.
+     */
+    private tileTint;
     private applyTileScale;
     private applyMaterial;
     private drawFill;
@@ -3993,6 +4155,18 @@ declare class LayerRenderer {
      */
     private drawSurface;
     private drawBuildings;
+    /** Подсветить один сшитый дом: геометрия берётся из его же меша. */
+    private drawSeamHighlight;
+    /** Нарисовать сшитые дома. Каждый лежит в координатах своего тайла-хозяина. */
+    private drawSeams;
+    /**
+     * Освободить буферы ТОЛЬКО тех хозяев, чья геометрия пересобрана.
+     *
+     * Раньше здесь сносился весь набор, и следующий кадр заливал на видеокарту все сшитые дома
+     * заново — на каждый приехавший тайл. При панораме тайлы приезжают непрерывно, так что рывки
+     * были непрерывными тоже.
+     */
+    private syncSeamGpu;
     /**
      * Доля высоты для анимации «вырастания». Считается ОДНА на бакет и берётся
      * и основным проходом, и проходом теней: иначе тень появится раньше здания
@@ -4620,74 +4794,6 @@ declare function placeAlongLine(line: ScreenPoint[], glyphs: GlyphMetric[], text
  */
 declare function clipLineToRect(line: ScreenPoint[], width: number, height: number, margin: number): ScreenPoint[][];
 
-/**
- * Генератор геометрии зданий: экструзия полигонов слоя `building` (схема OpenMapTiles v3).
- * Работает в воркере, отдаёт готовые типизированные массивы — они уходят в главный
- * поток transfer'ом (без копирования) и грузятся в GPU как есть.
- *
- * Формат вершины (stride 18 байт):
- *   a_pos     2 × Int16   off 0   координаты тайла [0..extent]
- *   a_height  1 × Uint16  off 4   высота вершины в метрах × 4 (до 16383 м, шаг 0.25)
- *   a_tint    1 × Uint8   off 6   оттенок здания (одинаков у всех его вершин)
- *   a_ao      1 × Uint8   off 7   0 — основание, 255 — верх
- *   a_normal  3 × Int8n   off 8   нормаль
- *   a_kind    1 × Uint8   off 11  тип поверхности и класс фасада
- *   a_wall    3 × Uint16  off 12  фасад: смещение вдоль грани, её ширина и высота (метры × 4)
- *
- * Высота ушла из Float32 в Uint16 ради места под a_tint: без разброса оттенка
- * квартал выглядит одной сплошной массой.
- *
- * `a_wall` появился ради РОВНОЙ раскладки окон. Сначала координата вдоль стены
- * считалась в шейдере как проекция позиции на её направление — сетка тогда общая
- * на всю карту, и грань режет её где придётся: у угла дома получается половина
- * окна, а простенки у разных стен разной ширины. Ширина и высота грани позволяют
- * ВПИСАТЬ сетку в неё: поля по краям, целое число ячеек, окно целиком.
- */
-declare const BUILDING_VERTEX_STRIDE = 18;
-/** Множитель упаковки высоты в Uint16. */
-declare const BUILDING_HEIGHT_SCALE = 32;
-/**
- * Множитель упаковки ПОЛОЖЕНИЯ вершины: сколько единиц Int16 приходится на единицу тайла.
- *
- * Было единица — то есть 0.47 м на z14, потому что координаты в MVT целые и вершину писали как
- * есть. Пока углы дома были прямыми, этого хватало: вершина и так стояла в узле сетки. Со
- * СКРУГЛЕНИЕМ хватать перестало — дуга радиусом 1.6 м это семь точек в пределах трёх единиц тайла,
- * и округление сажает их на ту же сетку: вместо дуги выходит лесенка со ступенью в полметра, она же
- * «угловатость» на ближнем зуме.
- *
- * Восемь единиц на тайловую — это 5.9 см, и дуга снова читается дугой. Потолок: тайл 0..4096, при
- * ×8 это 0..32768, и последнее значение на единицу больше, чем помещается в Int16, — оно
- * прижимается (`clampI16`). Ошибка при этом 6 см и только у вершины, стоящей ровно на дальней
- * границе тайла.
- */
-declare const BUILDING_POS_SCALE = 8;
-interface BuildingsMesh {
-    vertices: ArrayBuffer;
-    indices: ArrayBuffer;
-    /** Uint32Array: id фичи на каждый треугольник — для пикинга и подсветки. */
-    featureIds: ArrayBuffer;
-    vertexCount: number;
-    indexCount: number;
-    extent: number;
-}
-interface BuildingsOptions {
-    /**
-     * Радиус скругления углов в МЕТРАХ. Скругляется контур, а значит и стены, и
-     * крыша — она строится по тому же кольцу. Ноль (по умолчанию) — острые углы,
-     * как раньше.
-     */
-    cornerRadius?: number;
-    /** Максимум отрезков на дугу: меньше — дешевле и угловатее. */
-    cornerSegments?: number;
-    /**
-     * Сколько метров в одной единице тайла. Нужен, чтобы решать по РАЗМЕРУ: дом
-     * в сотню квадратов получает скатную крышу, торговый центр — плоскую. Без
-     * него один и тот же порог на разных зумах означал бы разные здания.
-     */
-    metersPerUnit?: number;
-}
-declare function generateBuildings(layer: VectorTileLayer, extent: number, filter?: Filter, options?: BuildingsOptions): BuildingsMesh | null;
-
 /**
  * Скругление углов контура.
  *
@@ -5084,6 +5190,13 @@ interface LineMesh {
     indices: ArrayBuffer;
     vertexCount: number;
     indexCount: number;
+    /**
+     * id фичи НА ТРЕУГОЛЬНИК — тем же форматом, что у заливки и зданий.
+     *
+     * Нужен, чтобы вырезать линию из готового меша: под 3D-моделью прячется не только здание, но и
+     * дорожки вокруг него, а их в наборе замен обычно больше всего.
+     */
+    featureIds: ArrayBuffer;
 }
 interface LineOptions {
     /**
@@ -5269,6 +5382,21 @@ interface SurfaceMesh {
      * островов: их рисуют отдельным проходом, только в глубину.
      */
     capIndexOffset: number;
+    /**
+     * ЧЬИ фичи попали в каждую фигуру: плоская таблица `[сколько, id, id, …]` в порядке фигур.
+     *
+     * Не «id на треугольник», как у зданий и заливки, и это не мелочь. Поверхность строится ПОСЛЕ
+     * объединения (`unionShapes`): соседние газоны свариваются в один контур, и треугольник в общем
+     * случае принадлежит не одной фиче, а всем, что в него слились. Прятать такую фигуру можно
+     * только целиком и только если скрыты ВСЕ её фичи — иначе под 3D-моделью исчез бы и соседний
+     * газон, которого никто не заменял.
+     */
+    shapeFeatures: ArrayBuffer;
+    /**
+     * Где лежат треугольники каждой фигуры: по четыре числа на фигуру —
+     * `[начало, конец, начало крышек, конец крышек]` в индексах итогового буфера.
+     */
+    shapeRanges: ArrayBuffer;
 }
 /**
  * Нахлёст по линии разреза, единицы тайла.
@@ -5296,6 +5424,91 @@ interface SurfaceMesh {
 declare const SURFACE_CUT_BLEED = 1;
 declare function generateSurface(layer: VectorTileLayer, extent: number, filter: Filter | undefined, opts: SurfaceOptions): SurfaceMesh | null;
 
+/**
+ * Объединение полигонов слоя в один контур — до построения меша.
+ *
+ * ЗАЧЕМ. В данных сплошного объекта не существует: газон вокруг квартала нарезан на десятки
+ * полигонов, парк граничит с газоном того же слоя, река идёт цепочкой кусков. Каждый кусок
+ * не знает о соседе и строит по своему краю борт, фаску и скругление — а на общей границе два
+ * борта складываются в гребень посреди сплошной зелени.
+ *
+ * Раньше это лечил механизм `shared`: ребро, встретившееся у двух полигонов, считалось внутренним.
+ * Он дёшев, но требует СОВПАДЕНИЯ ВЕРШИН до единицы, а тайлер упрощает каждый полигон отдельно,
+ * и общая граница у двух соседей расходится. Совпадений не находится, и весь механизм молчит.
+ *
+ * Объединение снимает вопрос целиком: внутренних границ после него просто нет, а наружу выходит
+ * один контур, по которому и строятся фаска, юбка и скругление.
+ *
+ * ЦЕНА. Булева операция дороже всего остального в генераторе, поэтому:
+ *   — объединяем ТОЛЬКО когда есть что объединять (два и более полигона);
+ *   — при отказе возвращаем исходные фигуры, а не роняем тайл: кривой контур в данных не повод
+ *     потерять слой целиком.
+ */
+interface Shape {
+    outer: Ring;
+    holes: Ring[];
+    lift?: number;
+}
+
+/**
+ * СШИВАНИЕ ПОЛИГОНА, РАЗРЕЗАННОГО ПО ТАЙЛАМ.
+ *
+ * Зачем. Дом, попавший на границу, тайлсервер отдаёт КУСКАМИ — по куску в каждый тайл, и каждый
+ * обрезан по своему квадрату с буфером. Дальше движок строит из каждого куска свою геометрию, и
+ * половинки обязаны сойтись на стыке идеально: скругление, фаска, стены, крыша — всё считается по
+ * контуру, а контуры у кусков разные, потому что у каждого свой разрез. Сколько ни выравнивай
+ * правила, остаётся угловатость на шве: разрез — это ложное ребро, и любая обработка, смотрящая на
+ * соседние вершины, на нём врёт. Признака «это ребро ненастоящее» в векторных тайлах нет — так
+ * записано и в их спецификации.
+ *
+ * Единственное честное решение — собрать дом обратно ДО того, как из него что-то строят.
+ *
+ * КАК. Не булевым объединением. Общие алгоритмы отсечения плохо переносят фигуры с совпадающими
+ * границами: у них там вырожденные случаи и чувствительность к точности float. Тот же вывод сделан
+ * в `union-subdivided-polygons` (SeaSketch), собранном ровно под эту задачу — склейку результатов
+ * `ST_Subdivide`: сшивание по совпадающим вершинам вышло на ДВА ПОРЯДКА быстрее общего отсечения и
+ * притом надёжнее.
+ *
+ * У нас случай ещё проще, и оба упрощения проверены на живых тайлах Душанбе:
+ *   • ложные рёбра известны точно — их создаёт обрезка, и мы помечаем их сами;
+ *   • координаты в тайле ЦЕЛЫЕ, а общая система — это `номер тайла × extent + локальная`, так что
+ *     совпадение вершин у соседей строгое, без допусков. Замер: из 48 зданий, попавших в два
+ *     соседних тайла, у 32 общие вершины совпали точно, у остальных куски и не пересекались.
+ *
+ * АЛГОРИТМ. Сперва самый частый и самый точный случай: если хоть один кусок пришёл БЕЗ ложных
+ * рёбер, он и есть целый полигон — дом уместился в буфер своего тайла, и складывать нечего.
+ *
+ * Иначе — булево ОБЪЕДИНЕНИЕ кусков (`union.ts`, тот же код, которым сливаются поверхности).
+ * Сначала здесь был свой обход: разрезать кольца по ложным рёбрам на цепочки и склеить цепочки по
+ * совпадающим вершинам. На простых домах он работал, а на П-образном корпусе школы замыкал кольцо
+ * РАНЬШЕ ВРЕМЕНИ — возвращал верхнюю перемычку вместо всего здания, и на карте от школы оставалась
+ * одна полоса. Объединение такого сделать не может по построению: оно не выбирает, каким путём
+ * идти, а складывает площади.
+ *
+ * Координаты сюда приходят в общей системе, но СДВИНУТЫМИ к одному тайлу — иначе числа в десятки
+ * миллионов съели бы точность булевой операции.
+ */
+/** Кусок полигона, приехавший из одного тайла. */
+interface PolygonPiece {
+    /** Замкнутое кольцо в ОБЩЕЙ системе координат (последняя точка повторяет первую). */
+    ring: Ring;
+    /** Дыры куска, если есть. */
+    holes?: Ring[];
+    /**
+     * Ложные рёбра: `cut[i]` — ребро от вершины `i` к вершине `i + 1`.
+     *
+     * Длина — на одну меньше числа точек замкнутого кольца, то есть по числу рёбер.
+     */
+    cut: boolean[];
+}
+/**
+ * Собрать полигон из кусков.
+ *
+ * Возвращает кольца с дырами. `null` — собрать не удалось, и звать надо прежний путь «каждый кусок
+ * сам по себе»: так бывает, когда дом тянется дальше загруженных тайлов и куска посередине нет.
+ */
+declare function stitchPieces(pieces: PolygonPiece[]): Shape[] | null;
+
 /**
  * Цель рендера с одной только глубиной — карта теней.
  *
@@ -5846,6 +6059,17 @@ declare class Map$1 extends Evented<MapEvents> {
      * Направление берётся у ключевого источника света (`setLight`), поэтому
      * двигать солнце и тень отдельно нельзя — и не нужно.
      */
+    /**
+     * ОТЛАДКА: красить каждый тайл своим цветом.
+     *
+     * Нужна для разбора стыков. Шов на границе тайлов по обычной картинке не читается: не понять,
+     * обрывается ли геометрия одного тайла, лезет ли поверх соседний или между ними щель — а от
+     * ответа зависит, где чинить. Подкраска отвечает на это сразу, и заодно видно, из какого тайла
+     * приехал кусок после подстановки предком.
+     *
+     * Работает на заливках и поверхностях — именно на них шов и виден.
+     */
+    setDebugTiles(on: boolean): this;
     setShadows(shadows: Partial<ShadowSettings> | boolean): this;
     /**
      * Здание под точкой экрана.
@@ -6105,4 +6329,4 @@ declare class Map$1 extends Evented<MapEvents> {
     destroy(): void;
 }
 
-export { type AnimationOptions, AssetLoader, type AssetLoaderOptions, BASE_SOURCE, BUILDING_HEIGHT_SCALE, BUILDING_POS_SCALE, BUILDING_VERTEX_STRIDE, type BuildingHit, type BuildingsMesh, CITY_STYLE, type CameraOptions, Circle, type CircleOptions, type CoverOptions, DEFAULT_ICONS, DEFAULT_LIGHT, DEFAULT_SHADOWS, DEFAULT_SKY, DEFAULT_STYLE, DepthTarget, type DeviceHints, EARTH_CIRCUMFERENCE, FILL_VERTEX_STRIDE, type Filter, type FitBoundsOptions, type FitViewport, type FogPlanes, GLOBE_MAX_PITCH, GLOBE_ZOOM_MAX, GLOBE_ZOOM_MIN, GLYPH_BORDER, GLYPH_SIZE, GROUND_SCALE, GeomType, type GestureOptions, type Glyph, type GlyphMetric, GlyphSource, type GpuClass, GroundArrows, IconSource, IndoorMask, type Interpolated, LEVEL_LIMIT, LINE_VERTEX_STRIDE, type LayerPlan, LayerRenderer, type LightSpec, type LinePlacement, type LngLat, LngLatBounds, type LngLatLike, MAX_LATITUDE, MODEL_VERTEX_STRIDE, Map$1 as Map, type MapEvents, MapObject, type MapObjectOptions, type MapOptions, Marker, type MarkerOptions, Model, ModelLayer, type ModelMesh, type ModelOptions, type ModelPrimitive, ObjectManager, type ObjectPaint, type ObjectPart, type Padding, type PlacedGlyph, type PlacedSymbol, Polygon, type PolygonOptions, Polyline, type PolylineOptions, type PolylineSegment, Popup, type PopupOptions, type Projection, type QualityChange, QualityGovernor, type QualityName, type QualityProfile, RELIEF_STYLE, RUNTIME_FILL_STRIDE, RUNTIME_LINE_STRIDE, RasterSource, type RasterSourceOptions, RasterTile, type RoundOptions, type RuntimeMesh, SDF_EDGE, SDF_PX, SOFT_STYLE, SPLIT_SEP, SURFACE_CUT_BLEED, SURFACE_LEVEL_SCALE, SURFACE_VERTEX_STRIDE, type ScreenPoint$1 as ScreenPoint, SdfAtlas, type ShadowSettings, type SkySpec, Style, type StyleLayerSpec, type StyleSpec, type SymbolHit, SymbolRenderer, THEMES, TILE_SIZE, type ThemeSpec, TileID, Transform, VectorTile, VectorTileFeature, VectorTileLayer, abbreviateStreet, addGround, altitudeFromMercatorZ, applyTheme, arrowLabelOffset, arrowVertices, buildRuntimeFill, buildRuntimeLine, cameraForBounds, circumferenceAtLatitude, clampLat, clampPixelRatio, classifyRenderer, clipLineToRect, coordinateDigits, coveringTiles, createGround, Map$1 as default, deviceHints, distToSegment, evaluateColor, evaluateNumber, extractFeature, featureLevel, fillFootprint, fogPlanes, footprintOf, formatHash, generateBuildings, generateFill, generateLine, generateSurface, generateSymbols, globeBasis, globeFlatMix, globeRadius, globeToLocal, groundAt, iconRotation, insideFootprint, latFromMercatorY, lngFromMercatorX, lngLatToUnit, matchesFilter, mercatorMetersPerTile, mercatorX, mercatorY, mercatorZFromAltitude, metersPerPixel, metersPerTile, nextQualityDown, parseGlb, parseGlbAsync, parseGlyphs, parseHash, patchUV, pickBuilding, pickFill, pitchIntent, pixelsPerMeter, placeAlongLine, pointInRing, qualityFor, qualityProfile, raySphere, resolveTemplate, roundRing, sdfFromAlpha, shapeText, splitBucketKey, splitByGround, splitPolygons, styleWithTheme, tileOriginMeters, tileUrl, toLngLat, unitToLngLat, worldSize };
+export { type AnimationOptions, AssetLoader, type AssetLoaderOptions, BASE_SOURCE, BUILDING_HEIGHT_SCALE, BUILDING_POS_SCALE, BUILDING_VERTEX_STRIDE, type BuildingHit, type BuildingsMesh, CITY_STYLE, type CameraOptions, Circle, type CircleOptions, type CoverOptions, DEFAULT_ICONS, DEFAULT_LIGHT, DEFAULT_SHADOWS, DEFAULT_SKY, DEFAULT_STYLE, DepthTarget, type DeviceHints, EARTH_CIRCUMFERENCE, FILL_VERTEX_STRIDE, type Filter, type FitBoundsOptions, type FitViewport, type FogPlanes, GLOBE_MAX_PITCH, GLOBE_ZOOM_MAX, GLOBE_ZOOM_MIN, GLYPH_BORDER, GLYPH_SIZE, GROUND_SCALE, GeomType, type GestureOptions, type Glyph, type GlyphMetric, GlyphSource, type GpuClass, GroundArrows, IconSource, IndoorMask, type Interpolated, LEVEL_LIMIT, LINE_VERTEX_STRIDE, type LayerPlan, LayerRenderer, type LightSpec, type LinePlacement, type LngLat, LngLatBounds, type LngLatLike, MAX_LATITUDE, MODEL_VERTEX_STRIDE, Map$1 as Map, type MapEvents, MapObject, type MapObjectOptions, type MapOptions, Marker, type MarkerOptions, Model, ModelLayer, type ModelMesh, type ModelOptions, type ModelPrimitive, ObjectManager, type ObjectPaint, type ObjectPart, type Padding, type PlacedGlyph, type PlacedSymbol, Polygon, type PolygonOptions, type PolygonPiece, Polyline, type PolylineOptions, type PolylineSegment, Popup, type PopupOptions, type Projection, type QualityChange, QualityGovernor, type QualityName, type QualityProfile, RELIEF_STYLE, RUNTIME_FILL_STRIDE, RUNTIME_LINE_STRIDE, RasterSource, type RasterSourceOptions, RasterTile, type RoundOptions, type RuntimeMesh, SDF_EDGE, SDF_PX, SOFT_STYLE, SPLIT_SEP, SURFACE_CUT_BLEED, SURFACE_LEVEL_SCALE, SURFACE_VERTEX_STRIDE, type ScreenPoint$1 as ScreenPoint, SdfAtlas, type ShadowSettings, type SkySpec, Style, type StyleLayerSpec, type StyleSpec, type SymbolHit, SymbolRenderer, THEMES, TILE_SIZE, type ThemeSpec, TileID, Transform, VectorTile, VectorTileFeature, VectorTileLayer, abbreviateStreet, addGround, altitudeFromMercatorZ, applyTheme, arrowLabelOffset, arrowVertices, buildRuntimeFill, buildRuntimeLine, cameraForBounds, circumferenceAtLatitude, clampLat, clampPixelRatio, classifyRenderer, clipLineToRect, coordinateDigits, coveringTiles, createGround, Map$1 as default, deviceHints, distToSegment, evaluateColor, evaluateNumber, extractFeature, featureLevel, fillFootprint, fogPlanes, footprintOf, formatHash, generateBuildings, generateFill, generateLine, generateSurface, generateSymbols, globeBasis, globeFlatMix, globeRadius, globeToLocal, groundAt, iconRotation, insideFootprint, latFromMercatorY, lngFromMercatorX, lngLatToUnit, matchesFilter, mercatorMetersPerTile, mercatorX, mercatorY, mercatorZFromAltitude, metersPerPixel, metersPerTile, nextQualityDown, parseGlb, parseGlbAsync, parseGlyphs, parseHash, patchUV, pickBuilding, pickFill, pitchIntent, pixelsPerMeter, placeAlongLine, pointInRing, qualityFor, qualityProfile, raySphere, resolveTemplate, roundRing, sdfFromAlpha, shapeText, splitBucketKey, splitByGround, splitPolygons, stitchPieces, styleWithTheme, tileOriginMeters, tileUrl, toLngLat, unitToLngLat, worldSize };