mahal_map 1.6.13 → 1.6.15

package/README.md

@@ -12,6 +12,28 @@ npm install mahal_map maplibre-gl
 
 `maplibre-gl` является peer dependency. Его нужно установить в приложении или подключить отдельным browser script перед SDK.
 
+Для нового 3D-движка (`engine: "3d"`) дополнительно нужен `@osm/maps3d-web`. Пакет **не публикуется в npm** — скачайте его со страницы платформы (кнопка «Web SDK — стартер»; в Vue-стартере это папка `libs/maps3d-web` с уже собранным `dist/`), положите в проект и поставьте как локальную зависимость:
+
+```sh
+npm i ./libs/maps3d-web maplibre-gl
+```
+
+`package.json` запишет ссылку на локальную папку:
+
+```json
+"@osm/maps3d-web": "file:./libs/maps3d-web"
+```
+
+Без сборщика возьмите `lib/maps3d.global.js` из скачанного стартера (IIFE-глобал `Maps3D`, three бандлится внутрь) и подключите скриптом после `maplibre-gl`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script>
+<script src="./lib/maps3d.global.js"></script>
+<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY"></script>
+```
+
+SDK сам найдёт конструктор в `window.Maps3D.Maps3D` — передавать его вручную не нужно.
+
 ## Быстрый старт через NPM
 
 ```ts
@@ -122,9 +144,9 @@ interface IMahalMapOptions {
 | `pitch`               | `number`                | Начальный наклон камеры (нужен для 3D-вида).                                                        |
 | `bearing`             | `number`                | Начальный поворот камеры.                                                                           |
 | `autoAddVectorSource` | `boolean`               | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`.           |
-| `engine`               | `"legacy" \| "3d"`     | Переключатель движка карты. `"legacy"` (по умолчанию) — старые стили mtile.gram.tj. `"3d"` — новая платформа GramMaps (route.gram.tj) с пресетами стиля и Maps3D. |
+| `engine`               | `"legacy" \| "3d"`     | Переключатель движка карты. `"legacy"` (по умолчанию) — старые стили mtile.gram.tj. `"3d"` — новая платформа GramMaps (navi.gram.tj) с пресетами стиля и Maps3D. |
 | `enable3D`             | `boolean`              | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`.                        |
-| `base`                 | `string`               | Домен платформы GramMaps для `engine: "3d"`. По умолчанию `https://route.gram.tj`.                  |
+| `base`                 | `string`               | Домен платформы GramMaps для `engine: "3d"`. По умолчанию `https://navi.gram.tj`.                  |
 | `preset`               | `string`               | Имя пресета стиля GramMaps (напр. `"standard-night"`) для `engine: "3d"`. По умолчанию `standard-day`/`standard-night` в зависимости от `theme`. |
 | `maps3d`               | `object`               | Доп. опции Maps3D слоя: `traffic`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`. |
 
@@ -165,6 +187,77 @@ const layer = map.getMaps3DLayer();
 MahalMap.getMaps3DLayer(map);
 ```
 
+`getMaps3DLayer()` возвращает реальный инстанс `Maps3D` (не обёртку) — типы `mahal_map` описывают всю его публичную поверхность, так что подключающему сервису не нужно ставить или типизировать `@osm/maps3d-web` отдельно.
+
+### Опции `maps3d` (расширенные)
+
+Передаются в `MahalMap.create({ maps3d: {...} })` при `engine: "3d"`:
+
+| Опция | Тип | По умолч. | Описание |
+| --- | --- | --- | --- |
+| `traffic` | `boolean \| { raster?, rasterMaxZoom?, graph? }` | `false` | Слой пробок. `raster: true` — картинкой с сервера вместо векторного слоя. |
+| `minZoom` | `number` | `16` | Зум появления детальных 3D. |
+| `lodBias` | `number` | `1` | `0` — всегда lod0 (детальный), `1` — lod1 на дальних зумах. |
+| `memoryBudget` | `number` | `30` | Сколько моделей держать в сцене одновременно. |
+| `maskReplaced` | `boolean` | `true` | Прятать заменённые OSM-объекты (`anchor=replace`). |
+| `typeReplacements` | `boolean` | `true` | Рисовать замены по типу (`natural=tree` → 3D-дерево и т.п.). |
+
+`buildings: true` включается автоматически при `enable3D: true` — переопределять не нужно, если только не требуется передать сам объект опций.
+
+### 3D-здания
+
+Тема (окна/свет) приходит из `metadata` пресета стиля и применяется автоматически при `map.setStyle()` — пересоздавать слой не нужно. Ручные сеттеры перебивают её:
+
+```ts
+const layer = map.getMaps3DLayer();
+
+layer?.setBuildingsEnabled(false); // 3D-здания ⇄ штатные здания стиля
+
+const b = layer?.buildings;
+b?.setWindowStyle(7); // тип окна 0..9 (сетка, лента, curtain wall, ...)
+b?.setWindowDepth(0.85);
+b?.setWindowColor("#6b9ed1");
+b?.setWindowFrameColor("#f2f2f4");
+b?.setEdgeRadius(1.2);
+b?.setSunIntensity(3.2);
+b?.setAmbient(0.76);
+b?.setSky(0.91);
+b?.setExposure(1.5);
+
+layer?.onBuildingClick((info) => {
+  if (!info) return;
+  console.log(info.id, info.height, info.props);
+});
+```
+
+### Пробки
+
+```ts
+const layer = map.getMaps3DLayer();
+
+layer?.setTraffic(true);
+layer?.setTrafficOpacity(0.85);
+layer?.setTrafficClicks(true); // попап скорости по клику
+layer?.refreshTraffic();
+
+// растровый вариант (картинка с сервера, без клика по дороге)
+layer?.setTrafficRaster(true);
+```
+
+### Жизненный цикл слоя
+
+```ts
+const layer = map.getMaps3DLayer();
+
+layer?.setMinZoom(15);
+layer?.setObjectsLight({ sun: 1.8, ambient: 0.45, sky: 1.1, exposure: 1.15 });
+await layer?.refresh();     // перечитать модели после правок
+await layer?.clearCache();  // сбросить IndexedDB-кеш ассетов
+layer?.destroy?.();         // отцепить слой (также вызывается автоматически в map.destroy())
+```
+
+`map.destroy()` / `MahalMap.destroy(map)` сами вызывают `destroy()`/`remove()` у Maps3D слоя, если он был подключен — отдельно чистить не нужно.
+
 ## MahalMap
 
 `MahalMap` - основной класс карты. Конструктор закрыт, карту нужно создавать через `MahalMap.create()`.

package/dist/index.d.mts

@@ -19,21 +19,63 @@ interface IAdditionalParamType {
     limit?: number;
 }
 
+interface IMaps3DTrafficOptions {
+    raster?: boolean;
+    rasterMaxZoom?: number;
+    graph?: string;
+}
 interface IMaps3DLayerOptions {
     apiKey?: string | null;
     base?: string;
     buildings?: boolean | Record<string, unknown>;
-    traffic?: boolean | Record<string, unknown>;
+    traffic?: boolean | IMaps3DTrafficOptions;
     minZoom?: number;
     lodBias?: number;
     memoryBudget?: number;
     maskReplaced?: boolean;
     typeReplacements?: boolean;
 }
+interface IMaps3DBuildingsController {
+    setWindowStyle(style: number): void;
+    setWindowDepth(depth: number): void;
+    setWindowColor(color: string): void;
+    setWindowFrameColor(color: string): void;
+    setEdgeRadius(radius: number): void;
+    setSunIntensity(value: number): void;
+    setAmbient(value: number): void;
+    setSky(value: number): void;
+    setExposure(value: number): void;
+}
+interface IMaps3DBuildingClickInfo {
+    id: string | number;
+    height?: number;
+    props?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface IMaps3DObjectsLightOptions {
+    sun?: number;
+    ambient?: number;
+    sky?: number;
+    exposure?: number;
+}
 interface IMaps3DLayer {
-    attach(map: Map): void;
+    attach(map: Map): void | Promise<void>;
     destroy?(): void;
     remove?(): void;
+    buildings?: IMaps3DBuildingsController;
+    setBuildingsEnabled?(enabled: boolean): void;
+    onBuildingClick?(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    traffic?: boolean;
+    trafficRaster?: boolean;
+    setTraffic?(enabled: boolean): void;
+    setTrafficOpacity?(opacity: number): void;
+    setTrafficClicks?(enabled: boolean): void;
+    setTrafficRaster?(enabled: boolean): void;
+    refreshTraffic?(): void;
+    setObjectsLight?(options: IMaps3DObjectsLightOptions): void;
+    setMinZoom?(zoom: number): void;
+    refresh?(): Promise<void>;
+    clearCache?(): Promise<void>;
 }
 interface IMaps3DTransformRequestOptions {
     base: string;
@@ -472,4 +514,4 @@ declare namespace index {
   export { index_checkCoordinates as checkCoordinates, index_debounce as debounce, index_geojsonPolyline as geojsonPolyline, index_geometryPolyline as geometryPolyline, index_trimValue as trimValue };
 }
 
-export { type IAdditionalParamType, type IMahalMapOptions, type IMapMarker, type IMaps3DLayer, type IMaps3DLayerOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type Maps3DCtor, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };
+export { type IAdditionalParamType, type IMahalMapOptions, type IMapMarker, type IMaps3DBuildingClickInfo, type IMaps3DBuildingsController, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DObjectsLightOptions, type IMaps3DTrafficOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type Maps3DCtor, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };

package/dist/index.d.ts

@@ -19,21 +19,63 @@ interface IAdditionalParamType {
     limit?: number;
 }
 
+interface IMaps3DTrafficOptions {
+    raster?: boolean;
+    rasterMaxZoom?: number;
+    graph?: string;
+}
 interface IMaps3DLayerOptions {
     apiKey?: string | null;
     base?: string;
     buildings?: boolean | Record<string, unknown>;
-    traffic?: boolean | Record<string, unknown>;
+    traffic?: boolean | IMaps3DTrafficOptions;
     minZoom?: number;
     lodBias?: number;
     memoryBudget?: number;
     maskReplaced?: boolean;
     typeReplacements?: boolean;
 }
+interface IMaps3DBuildingsController {
+    setWindowStyle(style: number): void;
+    setWindowDepth(depth: number): void;
+    setWindowColor(color: string): void;
+    setWindowFrameColor(color: string): void;
+    setEdgeRadius(radius: number): void;
+    setSunIntensity(value: number): void;
+    setAmbient(value: number): void;
+    setSky(value: number): void;
+    setExposure(value: number): void;
+}
+interface IMaps3DBuildingClickInfo {
+    id: string | number;
+    height?: number;
+    props?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface IMaps3DObjectsLightOptions {
+    sun?: number;
+    ambient?: number;
+    sky?: number;
+    exposure?: number;
+}
 interface IMaps3DLayer {
-    attach(map: Map): void;
+    attach(map: Map): void | Promise<void>;
     destroy?(): void;
     remove?(): void;
+    buildings?: IMaps3DBuildingsController;
+    setBuildingsEnabled?(enabled: boolean): void;
+    onBuildingClick?(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    traffic?: boolean;
+    trafficRaster?: boolean;
+    setTraffic?(enabled: boolean): void;
+    setTrafficOpacity?(opacity: number): void;
+    setTrafficClicks?(enabled: boolean): void;
+    setTrafficRaster?(enabled: boolean): void;
+    refreshTraffic?(): void;
+    setObjectsLight?(options: IMaps3DObjectsLightOptions): void;
+    setMinZoom?(zoom: number): void;
+    refresh?(): Promise<void>;
+    clearCache?(): Promise<void>;
 }
 interface IMaps3DTransformRequestOptions {
     base: string;
@@ -472,4 +514,4 @@ declare namespace index {
   export { index_checkCoordinates as checkCoordinates, index_debounce as debounce, index_geojsonPolyline as geojsonPolyline, index_geometryPolyline as geometryPolyline, index_trimValue as trimValue };
 }
 
-export { type IAdditionalParamType, type IMahalMapOptions, type IMapMarker, type IMaps3DLayer, type IMaps3DLayerOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type Maps3DCtor, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };
+export { type IAdditionalParamType, type IMahalMapOptions, type IMapMarker, type IMaps3DBuildingClickInfo, type IMaps3DBuildingsController, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DObjectsLightOptions, type IMaps3DTrafficOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type Maps3DCtor, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };