osmgl 0.5.0 → 0.7.0

package/dist/osmgl.d.cts

@@ -432,6 +432,20 @@ declare class Transform {
      * Порядок: левый верх, правый верх, левый низ, правый низ.
      */
     localRayCorners(): Vec3[];
+    /**
+     * Базис камеры в МИРОВЫХ осях движка (X восток, Y юг, Z вверх) и фокус в пикселях вида.
+     *
+     * По ним из пикселя восстанавливается луч: dir = normalize(fwd*focal + right*dx + up*dy). Небу
+     * этого хватает, чтобы считаться от УГЛА ЛУЧА, а не от экранной высоты, — только так у горизонта
+     * получается настоящая воздушная масса, а не нарисованная полоса.
+     */
+    cameraRay(): {
+        right: Vec3;
+        up: Vec3;
+        fwd: Vec3;
+        focal: number;
+        axisElev: number;
+    };
     /** Направление на центр планеты и её угловой радиус — для каймы атмосферы. */
     globeDisc(): {
         dir: Vec3;
@@ -977,6 +991,21 @@ interface FillExtrusionLayerSpec extends LayerBase {
         windowColor?: Interpolated<string>;
         /** Цвет переплёта и откосов. */
         windowFrameColor?: Interpolated<string>;
+        /**
+         * Разброс тона и градиента стекла, 0..1 (по умолчанию 1).
+         *
+         * Свой тон у каждого окна и отражение неба по высоте дают фасаду вторую фактуру. На синем
+         * остеклении это жизнь, а на стекле в тон стене — пятна: часть окон темнее стены, часть
+         * светлее. Ноль оставляет ровно середину.
+         */
+        windowVariation?: Interpolated<number>;
+        /**
+         * Сила швов на стенах и кровлях, 0..1 (по умолчанию 1).
+         *
+         * Швы делают дом сборным. Но там, где стена и стекло одного тона, они остаются единственным
+         * контрастом на фасаде, и дом читается сеткой линий, а не объёмом.
+         */
+        seamStrength?: Interpolated<number>;
         /**
          * Доля светящихся окон, 0..1 — для ночных тем. Какие именно окна горят,
          * решает хеш ячейки, поэтому при движении камеры свет не «бегает».
@@ -1325,8 +1354,15 @@ interface LightSpec {
 interface SkySpec {
     /** Рисовать небо и дымку. */
     enabled: boolean;
-    /** Цвет в зените. */
+    /** Цвет открытого неба над полосой мглы. */
     skyColor: string;
+    /**
+     * Цвет ВЕРХНЕЙ АТМОСФЕРЫ — выше по кадру, где воздуха меньше и синь глубже.
+     *
+     * Третья остановка градиента. Двух цветов на небо не хватает: получается ровная заливка, по
+     * которой не читается ни толща воздуха, ни высота. Так же устроено небо у Mapbox (`high-color`).
+     */
+    highColor?: string;
     /** Цвет у горизонта. В него же уходит дальняя земля — отсюда бесшовный стык. */
     horizonColor: string;
     /**
@@ -1337,6 +1373,14 @@ interface SkySpec {
     fogRange: [number, number];
     /** Предел силы дымки: 1 — дальний план сливается с горизонтом полностью. */
     fogIntensity: number;
+    /**
+     * Вертикальный диапазон дымки в МЕТРАХ: с какой высоты она начинает отпускать геометрию и на
+     * какой отпускает совсем. Мгла лежит слоем у земли, и башня из неё выходит — низ теряется,
+     * верх остаётся чистым. Ровно выцветшая по всей высоте башня выдаёт нарисованную дымку первой.
+     *
+     * Равные значения выключают учёт высоты. Аналог `fog.vertical-range` у Mapbox.
+     */
+    fogVerticalRange: [number, number];
     /** Цвет космоса за пределами атмосферы. Виден только на глобусе. */
     spaceColor: string;
     /** Цвет атмосферной каймы вокруг планеты. */
@@ -1344,12 +1388,15 @@ interface SkySpec {
     /** Яркость звёзд, 0 — выключить. Звёзды закреплены в мире, а не на экране. */
     starIntensity: number;
     /**
-     * Доля ВИДИМОЙ полосы неба, на которой цвет переходит от горизонта к зениту.
+     * Толщина полосы МГЛЫ над горизонтом — в синусе угла подъёма луча, как `fog.horizon-blend`
+     * у Mapbox. Значение 0.14 это примерно восемь градусов.
      *
-     * Именно видимой, а не высоты экрана: при поле зрения 37° над горизонтом
-     * помещается всего несколько градусов, и полоса неба в кадре — это десятки
-     * пикселей. Привязка к высоте экрана давала бы переход длиной в сотни
-     * пикселей, то есть ровный цвет вместо градиента.
+     * Величина угловая, а не доля кадра: толщина мглы от кадрирования не зависит. Доля видимого
+     * неба схлопывается в ноль, когда горизонт подходит к кромке кадра (большой зум с наклоном), и
+     * синее небо упирается в мглу стыком.
+     *
+     * Этой же полосой дымка отпускает геометрию по мере подъёма луча — небо и дальний дом обязаны
+     * приходить у горизонта в один цвет.
      */
     horizonBlend: number;
 }
@@ -1883,14 +1930,6 @@ declare const RELIEF_STYLE: StyleSpec;
  * читается шумом; вода осталась водой, её блики и есть смысл материала.
  */
 declare const CITY_STYLE: StyleSpec;
-/**
- * Готовые темы. Все — накладки поверх DEFAULT_STYLE, поэтому структура слоёв
- * у них общая: переключение темы НЕ требует пересборки геометрии.
- *
- * Первые четыре сделаны вручную под этот движок, остальные — палитры GramMaps
- * Standard из админки, перенесённые скриптом (`scripts/import-standard-themes.mjs`),
- * чтобы карта на своём движке выглядела так же, как везде в продукте.
- */
 declare const THEMES: Record<string, ThemeSpec>;
 /** Стиль с наложенной темой. Имя неизвестной темы приводит к базовому стилю. */
 declare function styleWithTheme(theme: string | ThemeSpec, base?: StyleSpec): StyleSpec;
@@ -3520,6 +3559,8 @@ declare class LayerRenderer {
     private patternScale;
     /** Камера в метрах от мирового нуля — считается раз на кадр (см. render). */
     private cameraMeters;
+    /** Пикселей буфера на пиксель вида — считается раз на кадр (см. render). */
+    private dpr;
     /**
      * Множитель процедурной детализации (фасады, материалы) — из профиля
      * качества. Ноль не ставим даже на слабых устройствах: без окон и ряби карта
@@ -3678,6 +3719,23 @@ declare class LayerRenderer {
      * отсекли изнанку. Подробности, почему не годится сам шар, — в GLOBE_CLIP_VERT.
      */
     private drawGlobeClip;
+    /**
+     * Горизонт и ширина его полосы в пикселях буфера — ОДНО число на небо и на дымку.
+     *
+     * Полоса меряется по ВИДИМОМУ небу, а не по высоте экрана: при наклоне 75° и поле зрения 37°
+     * над горизонтом помещается несколько градусов, и небо в кадре — это десятки пикселей. Привязка
+     * к высоте экрана дала бы переход длиной в сотни пикселей, то есть ровную заливку вместо
+     * градиента.
+     */
+    /**
+     * Луч и полоса мглы — ОДНИ И ТЕ ЖЕ числа небу и дымке.
+     *
+     * Небо и дальняя геометрия сходятся у горизонта, и считать их надо от одной величины: угла
+     * подъёма луча. Отсюда наклон оси камеры, фокус и центр кадра — по ним шейдер восстанавливает
+     * луч из пикселя (см. Transform.cameraRay).
+     */
+    private applyAtmosphere;
+    private skyBand;
     /** Небо: вертикальный градиент во весь экран. Геометрии у него нет. */
     private drawSky;
     /**
@@ -4976,6 +5034,11 @@ declare const SURFACE_LEVEL_SCALE = 64;
 interface SurfaceOptions {
     /** Метров в единице тайла — все размеры ниже задаются в МЕТРАХ. */
     metersPerUnit: number;
+    /**
+     * Предел длины ребра в единицах тайла: длиннее — верхняя плоскость дробится. Нужно ГЛОБУСУ,
+     * где сфера гнёт вершины, а не рёбра. Ноль (плоская карта) выключает дробление.
+     */
+    maxSegment?: number;
     /** Уровень верхней плоскости, метры. Отрицательный — ниже земли. */
     elevation: number;
     /**

package/dist/osmgl.d.ts

@@ -432,6 +432,20 @@ declare class Transform {
      * Порядок: левый верх, правый верх, левый низ, правый низ.
      */
     localRayCorners(): Vec3[];
+    /**
+     * Базис камеры в МИРОВЫХ осях движка (X восток, Y юг, Z вверх) и фокус в пикселях вида.
+     *
+     * По ним из пикселя восстанавливается луч: dir = normalize(fwd*focal + right*dx + up*dy). Небу
+     * этого хватает, чтобы считаться от УГЛА ЛУЧА, а не от экранной высоты, — только так у горизонта
+     * получается настоящая воздушная масса, а не нарисованная полоса.
+     */
+    cameraRay(): {
+        right: Vec3;
+        up: Vec3;
+        fwd: Vec3;
+        focal: number;
+        axisElev: number;
+    };
     /** Направление на центр планеты и её угловой радиус — для каймы атмосферы. */
     globeDisc(): {
         dir: Vec3;
@@ -977,6 +991,21 @@ interface FillExtrusionLayerSpec extends LayerBase {
         windowColor?: Interpolated<string>;
         /** Цвет переплёта и откосов. */
         windowFrameColor?: Interpolated<string>;
+        /**
+         * Разброс тона и градиента стекла, 0..1 (по умолчанию 1).
+         *
+         * Свой тон у каждого окна и отражение неба по высоте дают фасаду вторую фактуру. На синем
+         * остеклении это жизнь, а на стекле в тон стене — пятна: часть окон темнее стены, часть
+         * светлее. Ноль оставляет ровно середину.
+         */
+        windowVariation?: Interpolated<number>;
+        /**
+         * Сила швов на стенах и кровлях, 0..1 (по умолчанию 1).
+         *
+         * Швы делают дом сборным. Но там, где стена и стекло одного тона, они остаются единственным
+         * контрастом на фасаде, и дом читается сеткой линий, а не объёмом.
+         */
+        seamStrength?: Interpolated<number>;
         /**
          * Доля светящихся окон, 0..1 — для ночных тем. Какие именно окна горят,
          * решает хеш ячейки, поэтому при движении камеры свет не «бегает».
@@ -1325,8 +1354,15 @@ interface LightSpec {
 interface SkySpec {
     /** Рисовать небо и дымку. */
     enabled: boolean;
-    /** Цвет в зените. */
+    /** Цвет открытого неба над полосой мглы. */
     skyColor: string;
+    /**
+     * Цвет ВЕРХНЕЙ АТМОСФЕРЫ — выше по кадру, где воздуха меньше и синь глубже.
+     *
+     * Третья остановка градиента. Двух цветов на небо не хватает: получается ровная заливка, по
+     * которой не читается ни толща воздуха, ни высота. Так же устроено небо у Mapbox (`high-color`).
+     */
+    highColor?: string;
     /** Цвет у горизонта. В него же уходит дальняя земля — отсюда бесшовный стык. */
     horizonColor: string;
     /**
@@ -1337,6 +1373,14 @@ interface SkySpec {
     fogRange: [number, number];
     /** Предел силы дымки: 1 — дальний план сливается с горизонтом полностью. */
     fogIntensity: number;
+    /**
+     * Вертикальный диапазон дымки в МЕТРАХ: с какой высоты она начинает отпускать геометрию и на
+     * какой отпускает совсем. Мгла лежит слоем у земли, и башня из неё выходит — низ теряется,
+     * верх остаётся чистым. Ровно выцветшая по всей высоте башня выдаёт нарисованную дымку первой.
+     *
+     * Равные значения выключают учёт высоты. Аналог `fog.vertical-range` у Mapbox.
+     */
+    fogVerticalRange: [number, number];
     /** Цвет космоса за пределами атмосферы. Виден только на глобусе. */
     spaceColor: string;
     /** Цвет атмосферной каймы вокруг планеты. */
@@ -1344,12 +1388,15 @@ interface SkySpec {
     /** Яркость звёзд, 0 — выключить. Звёзды закреплены в мире, а не на экране. */
     starIntensity: number;
     /**
-     * Доля ВИДИМОЙ полосы неба, на которой цвет переходит от горизонта к зениту.
+     * Толщина полосы МГЛЫ над горизонтом — в синусе угла подъёма луча, как `fog.horizon-blend`
+     * у Mapbox. Значение 0.14 это примерно восемь градусов.
      *
-     * Именно видимой, а не высоты экрана: при поле зрения 37° над горизонтом
-     * помещается всего несколько градусов, и полоса неба в кадре — это десятки
-     * пикселей. Привязка к высоте экрана давала бы переход длиной в сотни
-     * пикселей, то есть ровный цвет вместо градиента.
+     * Величина угловая, а не доля кадра: толщина мглы от кадрирования не зависит. Доля видимого
+     * неба схлопывается в ноль, когда горизонт подходит к кромке кадра (большой зум с наклоном), и
+     * синее небо упирается в мглу стыком.
+     *
+     * Этой же полосой дымка отпускает геометрию по мере подъёма луча — небо и дальний дом обязаны
+     * приходить у горизонта в один цвет.
      */
     horizonBlend: number;
 }
@@ -1883,14 +1930,6 @@ declare const RELIEF_STYLE: StyleSpec;
  * читается шумом; вода осталась водой, её блики и есть смысл материала.
  */
 declare const CITY_STYLE: StyleSpec;
-/**
- * Готовые темы. Все — накладки поверх DEFAULT_STYLE, поэтому структура слоёв
- * у них общая: переключение темы НЕ требует пересборки геометрии.
- *
- * Первые четыре сделаны вручную под этот движок, остальные — палитры GramMaps
- * Standard из админки, перенесённые скриптом (`scripts/import-standard-themes.mjs`),
- * чтобы карта на своём движке выглядела так же, как везде в продукте.
- */
 declare const THEMES: Record<string, ThemeSpec>;
 /** Стиль с наложенной темой. Имя неизвестной темы приводит к базовому стилю. */
 declare function styleWithTheme(theme: string | ThemeSpec, base?: StyleSpec): StyleSpec;
@@ -3520,6 +3559,8 @@ declare class LayerRenderer {
     private patternScale;
     /** Камера в метрах от мирового нуля — считается раз на кадр (см. render). */
     private cameraMeters;
+    /** Пикселей буфера на пиксель вида — считается раз на кадр (см. render). */
+    private dpr;
     /**
      * Множитель процедурной детализации (фасады, материалы) — из профиля
      * качества. Ноль не ставим даже на слабых устройствах: без окон и ряби карта
@@ -3678,6 +3719,23 @@ declare class LayerRenderer {
      * отсекли изнанку. Подробности, почему не годится сам шар, — в GLOBE_CLIP_VERT.
      */
     private drawGlobeClip;
+    /**
+     * Горизонт и ширина его полосы в пикселях буфера — ОДНО число на небо и на дымку.
+     *
+     * Полоса меряется по ВИДИМОМУ небу, а не по высоте экрана: при наклоне 75° и поле зрения 37°
+     * над горизонтом помещается несколько градусов, и небо в кадре — это десятки пикселей. Привязка
+     * к высоте экрана дала бы переход длиной в сотни пикселей, то есть ровную заливку вместо
+     * градиента.
+     */
+    /**
+     * Луч и полоса мглы — ОДНИ И ТЕ ЖЕ числа небу и дымке.
+     *
+     * Небо и дальняя геометрия сходятся у горизонта, и считать их надо от одной величины: угла
+     * подъёма луча. Отсюда наклон оси камеры, фокус и центр кадра — по ним шейдер восстанавливает
+     * луч из пикселя (см. Transform.cameraRay).
+     */
+    private applyAtmosphere;
+    private skyBand;
     /** Небо: вертикальный градиент во весь экран. Геометрии у него нет. */
     private drawSky;
     /**
@@ -4976,6 +5034,11 @@ declare const SURFACE_LEVEL_SCALE = 64;
 interface SurfaceOptions {
     /** Метров в единице тайла — все размеры ниже задаются в МЕТРАХ. */
     metersPerUnit: number;
+    /**
+     * Предел длины ребра в единицах тайла: длиннее — верхняя плоскость дробится. Нужно ГЛОБУСУ,
+     * где сфера гнёт вершины, а не рёбра. Ноль (плоская карта) выключает дробление.
+     */
+    maxSegment?: number;
     /** Уровень верхней плоскости, метры. Отрицательный — ниже земли. */
     elevation: number;
     /**