3D-модели
Карта поддерживает отображение трёхмерных моделей в формате glTF/GLB. Такие модели позволяют улучшить эстетический вид карты, сделать акценты на нужных объектах и увеличить степень детализации.
Чтобы добавить модели на карту, настройте стилевой слой в Редакторе стилей и подготовьте данные. Примеры ниже показывают стилизацию достопримечательностей, каждой из которых соответствует уникальная модель.
Требования и рекомендации для моделей
Для оптимальной производительности карты и корректного отображения трёхмерных моделей на карте следуйте требованиям и рекомендациям.
Обязательные требования:
-
Формат: glTF/GLB (файлы
.gltf
,.glb
). -
Меш: желательно, чтобы модель содержала один меш (геометрический объект на сцене). Использование моделей с несколькими мешами незначительно снижает производительность карты.
-
Текстура:
- Меш может иметь текстуру или одноцветную заливку.
- Разрешение текстуры должно быть кратно степени двойки (2, 4, 8, 16, 32, 64, 128 и 256).
- Поддерживаются форматы изображений
.png
,.jpg
и.bmp
. - Не поддерживается сжатие текстур и свойства текстур
emissiveTexture
иnormalTexture
.
-
Инстанцирование: расширения для инстанцирования не поддерживаются.
Рекомендации по использованию и производительности:
- Размер: оптимальный размер уникальных моделей — не более 20 000 вершин; типовых моделей (например, деревьев) — от 200 до 2000 вершин.
- Текстура: оптимальный размер текстур для уникальных моделей — 256×256; для типовых моделей — 64×64.
- Цвета: если вы не настраиваете собственные стили карты, а просто загружаете модели, рекомендуется, чтобы цвета текстуры моделей сочетались с цветами карты 2ГИС.
- Матричные анимации: поддерживаются, но использование незначительно снижает производительность карты.
- Модель освещения PBR: поддерживается, но использование незначительно снижает производительность карты.
- Локальные трансформации: локальные трансформации (перемещения, вращения и масштабирования) поддерживаются, но незначительно снижают производительность карты. Рекомендуется использовать их в редких случаях: для оптимальной производительности модели должны быть без локальных трансформаций.
Настройка стилевого слоя
-
Откройте Редактор стилей.
-
Добавьте новый слой и выберите тип 3D-модель.
-
На вкладке Данные перейдите в конец списка и нажмите JSON — добавить вручную.
-
Скопируйте и вставьте следующий код:
[ "match", [ "get", "layerType" ], [ "SightModels" ], true, false ]
-
Перейдите во вкладку Стиль и настройте следующие параметры с помощью JSON (нажимайте Редактировать JSON):
Параметр Значение Источник модели ["get", "url"]
Размер ["get", "scale"]
Поворот ["get", "rotation"]
Смещение ["get", "translate"]
URL и расположение добавляемых моделей будут задаваться в геоданных, поэтому в стилевом слое нужно связать настройки модели с её атрибутами при помощи
get
-выражений. -
Разместите полученный стилевой слой после слоев с POI (иконками, обозначающими объекты на карте) и до слоев с 3D-домами, так, чтобы модели не перекрывали надписи и иконки:
-
В верхнем меню редактора выберите Поделиться и скопируйте идентификатор стиля для дальнейшего использования:
Подготовка данных
Укажите расположение каждой модели и её настройки позиционирования в GeoJSON:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"url": "https://disk.2gis.com/digital-twin/models_s3/docs/spherecafe.glb",
"layerType": "SightModels",
"scale": [1, 1, 1],
"rotation": [0, 0, 0],
"translate": [0, 0, 0],
},
"geometry": {
"type": "Point",
"coordinates": [82.926685835, 55.02533639]
}
}
]
}
Параметры:
-
"type": "Feature"
— стандартный объект GeoJSON типаFeature
. -
properties
:url
— URL для загрузки модели."layerType": "SightModels"
— позволяет карте сопоставить объект из данных с созданным стилевым слоем.scale
— начальная настройка размера объекта.rotation
— начальная настройка поворота объекта.translate
— начальная настройка смещения объекта.
Настройки трансформации можно скорректировать позже, после оценки положения модели на карте.
-
geometry
:"type": "Point"
— объект точечного типа.coordinates
— координаты центра объекта. В данном примере объект будет отображен в геоточке82.926685835, 55.02533639
.
Примечание
Чтобы не подбирать настройки позиционирования модели (координаты, поворот и масштаб) вручную, используйте инструмент для позиционирования моделей на карте. Вы можете спозиционировать модель и скопировать значения настроек: см. инструкцию по размещению моделей на карте.
Когда готовы данные с моделью и стиль с настроенным стилевым слоем, вы можете оценить промежуточный результат:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>2GIS Map API</title>
<meta name="description" content="Quickstart with 2GIS Map API" />
<style>
html,
body,
#container {
margin: 0;
width: 100%;
height: 100%;
overflow: hidden;
}
</style>
</head>
<body>
<div id="container"></div>
<script src="https://mapgl.2gis.com/api/js/v1"></script>
<script>
const map = new mapgl.Map('container', {
center: [82.9267347, 55.0253716],
zoom: 19,
rotation: -131,
pitch: 45,
key: 'Your API access key',
style: '18d586c4-4c36-4455-a60f-a4366f1fb17f'
});
map.on('click', function (ev) {
console.log(ev);
});
const modelSource = new mapgl.GeoJsonSource(map, {
data: {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"scale": [1, 1, 1],
"rotation": [0, 0, 0],
"translate": [0, 0, 0],
"layerType": "SightModels",
"url": "https://disk.2gis.com/digital-twin/models_s3/docs/spherecafe.glb",
"idsToHide": []
},
"geometry": {
"type": "Point",
"coordinates": [82.926685835, 55.02533639]
}
}
]
}
})
</script>
</body>
</html>
Видно, что модель отображается на карте, однако показывается некорректно. Нужно настроить её поворот и смещение, а также убрать 3D-здание, которое сейчас располагается на месте модели.
Настройки позиционирования
Чтобы правильно настроить позиционирование модели, откройте пример с промежуточным результатом и скорректируйте значения в свойствах scale
, rotation
, translate
объекта. Для правильного отображения модели выше подойдут следующие значения:
"scale": [0.96, 0.96, 0.96],
"rotation": [0, 0, 203],
"translate": [-2.7, 13, 0]
Подробнее о позиционировании 3D-моделей
3D-модели поддерживают трансформацию в трёхмерном пространстве, заданном осями X, Y и Z.
Трансформация размера выполняется в локальной системе координат (Local
на схеме выше). Остальные трансформации выполняются в мировой системе координат (World
), в которой ось X смотрит на восток, ось Y — на север, ось Z направлена вверх.
Размер
Размер задаётся в относительных единицах, базой для которых выступает изначальный размер модели.
Обычно менять размер моделей лучше сразу в трёх осях, в противном случае они будут тянуться и искажаться.
Поворот
Поворот моделей задаётся в градусах.
Наиболее распространенным случаем является поворот моделей вокруг оси Z. Поворот вокруг других осей может привести к искривлению моделей.
Смещение
Смещение моделей задаётся в метрах, относительно их изначального положения.
Смещение лучше задавать только в осях X и Y, чтобы модель не «висела в воздухе».
Скрытие других объектов при появлении модели
Чтобы скрыть объект на карте, который пересекается с моделью:
-
Получите идентификатор объекта:
-
Чтобы подписаться на событие
click
в карте и выводить событие в консоль, добавьте в исходный код приложения или примера следующий фрагмент:map.on('click', function (ev) { console.log(ev); });
-
Откройте Инструменты разработчика браузера (клавиша F12) и нажмите на объект, который необходимо скрыть. Скопируйте идентификатор из поля
target.id
события клика, например:
-
-
Передайте полученный идентификатор объекта в данные GeoJSON в поле
idsToHide
:{ "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": { "idsToHide": ["141373143542097"], ... }, ... } ] }
-
Укажите это поле в настройке
Id связанных объектов
стилевого слоя:Настройка Значение Id связанных объектов ["get", "idsToHide"]
Итоговый пример
Вы также можете посмотреть настройки стилевого слоя в готовом стиле. Для доступа к настройкам авторизуйтесь в Редакторе стилей и нажмите Создать копию.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>2GIS Map API</title>
<meta name="description" content="Quickstart with 2GIS Map API" />
<style>
html,
body,
#container {
margin: 0;
width: 100%;
height: 100%;
overflow: hidden;
}
</style>
</head>
<body>
<div id="container"></div>
<script src="https://mapgl.2gis.com/api/js/v1"></script>
<script>
const map = new mapgl.Map('container', {
center: [82.9267347, 55.0253716],
zoom: 19,
rotation: -131,
pitch: 45,
key: 'Your API access key',
style: '18d586c4-4c36-4455-a60f-a4366f1fb17f'
});
map.on('click', function (ev) {
console.log(ev);
});
const modelSource = new mapgl.GeoJsonSource(map, {
data: {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"scale": [0.96, 0.96, 0.96],
"rotation": [0, 0, 203],
"translate": [-2.7, 13, 0],
"layerType": "SightModels",
"url": "https://disk.2gis.com/digital-twin/models_s3/docs/spherecafe.glb",
"idsToHide": ["141373143542097"],
},
"geometry": {
"type": "Point",
"coordinates": [82.926685835, 55.02533639]
}
}
]
}
})
</script>
</body>
</html>