osmgl 0.15.0 → 0.17.0

package/README.md

@@ -183,6 +183,18 @@ nginx отдаёт его двумя путями — `/maps/osmgl.global.js` (
 ГОЧА: на слабом профиле поверхность рисуется ЗАЛИВКОЙ (`flattened`), поэтому квадраты пишет и
 `drawFill`. Без этого на телефоне линии лежали поверх асфальта, а на компьютере — нет.
 
+### Линия под настилом (`depthTest`)
+
+Поднятые линии рисуются без теста глубины: краска лежит на своём асфальте в сантиметрах, и такой
+зазор буфер глубины не различает. Поэтому краска улицы под эстакадой проступала сквозь настил.
+
+Слой с `"depthTest": true` проходит тест глубины (без записи), а его глубина сдвинута к камере на
+долю расстояния (`DEPTH_NUDGE` = 0.4 %). Своё полотно в сантиметрах ниже её не закрывает, настил в
+5–8 м над ней — закрывает. Сдвиг — одна постоянная в z клипа на кадр: `B·k/(1−k)`, где `B` — элемент
+[14] перспективы (`Transform.projZOffset`); точка на экране не двигается. Действует только в
+проходе поднятых линий, не на шаре и не в текстуре рельефа. Дальше ~2 км от камеры сдвиг больше
+просвета, и краска под настилом снова видна.
+
 ### Разноцветная линия
 
 Маршрут, раскрашенный по пробкам, — как у Яндекса:
@@ -411,6 +423,49 @@ new OsmGL.Map({ icons: { taxi: '<svg viewBox="0 0 24 24">…</svg>' } })
 Настоящего шейпинга нет: перо двигается по `advance`. Кириллице, латинице и таджикскому
 этого достаточно, арабский и иврит потребуют отдельного прохода.
 
+### Пороги подробности по зуму
+
+Чтобы телефон не захлёбывался на общем плане города, подробность включается ступенями
+(30.09.2026, одинаково в вебе, на Android и в iOS):
+
+| Зум | Дома | Дороги | Детальные 3D-объекты |
+|-----|------|--------|----------------------|
+| до 15 | нет | линии | нет |
+| 15–16 | плоские (`building-flat`, цвет крыши) | линии | нет |
+| с 16 | объём, растёт до полной высоты к 16.8 | асфальт (полотно), разметка с 16.5 | нет |
+| с 17 | объём | асфальт | есть |
+
+На z15 кадр захватывает вчетверо больше города, чем на z16, а стены с окнами, тени и асфальт
+на этом зуме не разглядеть. Плоский дом берёт цвет крыши объёмного слоя ссылкой
+`{ from: 'building', property: 'roofColor' }` (поле `property` у `ColorFrom`), поэтому его красят
+те же темы и на пороге z16 нет шва. Тайлы полотна на z15 больше не запрашиваются
+(`minzoom` источника 16). Ниже порога моделей маска замены снимается, и на месте модели стоит
+обычный дом.
+
+Тесселяцию зданий это не экономит: тайл z14 — потолок источника, и воркер собирает в нём здания
+на всех зумах выше. Экономится отрисовка: стены, окна, скругления и проход теней.
+
+### Иерархия подписей мест
+
+Во всех пяти стилях места делятся по КЛАССУ, а не по рангу. Ранг в тайлах navigram — порядковый
+номер внутри клетки сетки, о размере места он не говорит ничего: Худжанд с рангом 12 до z10.5 не
+показывался вовсе. Приоритет слоя сильнее любого ранга фичи, поэтому порядок задаётся слоями:
+
+| Слой | Что | С зума | `priority` |
+|------|-----|--------|-----------:|
+| `place-capital` | столица и центры областей: Душанбе, Худжанд, Бохтар, Хорог | 4 | 110 |
+| `place-region` | области (свой источник `regions` в стиле) | 4.5 | 100 |
+| `place-label` | остальные города и страна | 4 | 90 |
+| `place-label-minor` | посёлки (`town`) | 7.5 | 70 |
+| `place-label-local` | сёла, кварталы, острова | 10.5 | 55 |
+
+Верхнего зума у областей нет. Центры стоят ВЫШЕ областей: крупное название области иначе
+накрывает на мелком зуме свой же областной центр. Признака столицы (`capital`) в тайлах navigram
+нет, поэтому центры выбираются по имени, в обоих написаниях (`Хуҷанд`/`Худжанд`, `Хоруғ`/`Хорог`).
+Обычные города исключают их тем же списком (`!in`), иначе одна подпись встала бы дважды. Точек
+областей в данных navigram нет совсем, поэтому они едут в стиле встроенным geojson-источником.
+Проверяется `tests/places.test.mjs`.
+
 ## Планы этажей
 
 Помещения ТЦ, вокзалов и рынков. Схема тайлов — [indoorequal](https://github.com/indoorequal/indoorequal)
@@ -692,6 +747,11 @@ CPU в экранных координатах — поэтому пережив
 перенесённые сюда скриптом, чтобы карта на своём движке выглядела так же, как
 везде в продукте:
 
+Ледяная модель света у зданий (`ice: 1`: свет прибавляется, тёмных сторон нет, швов нет) стоит не
+только у `ice`: её кодом получают светлая `3d`, тёмная `night` и пара «Атлас» (`atlas-day`,
+`atlas-night`). У тёмного «Атласа» кровля — цветом стены: своей у палитры нет, и движок брал ей
+светлую по умолчанию.
+
 `ice` — отдельная тема со СВОЕЙ палитрой целиком, а не правка светлой. Цвета сняты
 с растровых тайлов Baidu Maps (Луцзяцзуй, z17, 25 тайлов): земля `#f5f3f0`,
 дороги белые с серой обводкой `#dbdbdd`, магистрали `#ffd86b`, вода `#90ddf6`,
@@ -1019,6 +1079,12 @@ map.getQuality()                     // { auto, profile, pixelRatio }
 | `balanced` | ≤1.75 | ≤2560×2160 | да | ≤4 | 1024 | 0.85 |
 | `low` | ≤1.25 | ≤1920×1350 | нет | ≤2 | 512 | 0.5 |
 
+На `low` и `minimal` геометрия упрощается (`simpleGeometry`): объёмные поверхности становятся
+плоскими заливками. Исключение — полотно дорог с настилом (`deck`): его объём даёт и высоту
+эстакады, и глубину, которой настил закрывает разметку под собой (`depthTest`). Пока оно
+упрощалось, режим «Эстакады с высотой» на слабом телефоне не делал ничего, а эмулятор Android
+(он определяется как `minimal`) показывал эстакады плоскими.
+
 Телефон отличается от десктопа не столько силой GPU, сколько **плотностью
 экрана**: при `devicePixelRatio` 3 кадр 412×892 CSS — это 3,3 миллиона
 пикселей, вдвое больше типичного окна на ноутбуке, и рисует их вчетверо более
@@ -1507,6 +1573,14 @@ node scripts/smoke.mjs         # рендер в headless-браузере, 4 р
 
 ## Грабли, на которые уже наступили
 
+- **Перенос кадра подписей на Android и iOS (KMP) усыплял проявление.** Подпись встаёт в
+  начале проявления, почти прозрачной. Следующие ~300 мс кадр подписей переносится на камеру
+  (`reproject`) вместе с прозрачностью на момент раскладки и продолжения не просит. На
+  неподвижной карте цикл кадров засыпал, и подписи оставались невидимыми до первого касания.
+  Чаще всего это видно на мелком зуме: шрифт приезжает позже тайлов. Теперь проход подписей
+  просит кадр, пока кадр `fading`, и на переносе тоже (`labelsFading` в `layers/Renderer.kt`).
+  В вебе переноса нет, поэтому там этого не было. Проверяется
+  `SymbolFrameTest.lateGlyphsArePlacedWithoutCameraMove`.
 - **`ELEMENT_ARRAY_BUFFER` — состояние VAO, а не глобальное.** Создание индексного буфера
   соседнего тайла, пока привязан VAO предыдущего, молча переписывало тому привязку: тайл
   начинал рисовать чужими индексами по своим вершинам. Ошибок GL нет, кадр не падает — тайл