glTF-плагин версии 2

Вы можете добавлять glTF-модели на карту, используя:

• Редактор стилей и источник данных: подробнее см. инструкцию 3D-модели.
• glTF-плагин версии 2. Он загружает и отрисовывает модели полностью с помощью движка MapGL. Это позволяет применять к моделям различные эффекты, настройки для которых задаются в стиле карты: туман, освещение, тени и другие. Использование плагина наиболее удобно в случаях, когда на карте нужно показать несколько моделей, не затрагивая при этом базовый картографический стиль.

С помощью плагина вы можете:

• загружать glTF-модели на карту;
• показывать и скрывать модели на карте;
• показывать POI с информацией при наведении на модель;
• отображать этажные планы.

Важно

В отличие от первой версии, glTF-плагин версии 2 не использует библиотеку Three.js. Чтобы перейти с первой версии плагина на вторую, см. раздел Основные изменения.

Подключение плагина

При помощи тега script

Чтобы использовать плагин, добавьте следующую строку в код страницы:

<script src="https://unpkg.com/@2gis/mapgl-gltf@^2/dist/bundle.js"></script>

Главный класс плагина будет доступен в пространстве имён mapgl:

const plugin = new mapgl.GltfPlugin(map);

Установка через npm

Если вы используете npm, можно подключить библиотеку с помощью пакета @2gis/mapgl-gltf:

npm install @2gis/mapgl-gltf

Инициализация плагина

Чтобы инициализировать плагин, передайте существующий экземпляр карты в конструктор плагина:

const plugin = new GltfPlugin(map);

В качестве опций плагина PluginOptions используются значения по умолчанию. Чтобы кастомизировать плагин, передайте опции вторым аргументом:

const plugin = new GltfPlugin(map, {
    hoverOptions: {
        color: '#ff000088',
    },
    labelGroupDefaults: {
        fontSize: 16,
    },
    modelsBaseUrl: 'https://example.com/s3_storage/gltf_models',
    modelsLoadStrategy: 'dontWaitAll',
    floorsControl: {
        position: 'centerLeft',
    },
    groundCoveringColor: '#000000CC',
    zIndex: 5,
});

Где:

• hoverOptions: опции для состояния моделей при наведении на них курсора. Доступна только опция color. Значение по умолчанию — #FFFFFF. Цвет к модели применяется путем перемножения всех компонентов.
• labelGroupDefaults: значения по умолчанию для группы подписей, если соответствующие опции не заданы в LabelGroupOptions:
  • fontSize: размер шрифта подписей. Значение по умолчанию — 14.
  • fontColor: цвет шрифта подписей. Значение по умолчанию — #000000.
  • image: опции подложки текста подписей. Применяется к группе, если в LabelGroupOptions значение image задано как 'default'. Значение по умолчанию:

    {
        url: 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjgiIGhlaWdodD0iMjgiIHZpZXdCb3g9IjAgMCAyOCAyOCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iMjgiIGhlaWdodD0iMjgiIHJ4PSI0IiBmaWxsPSIjZWFlYWVhIi8+PHJlY3QgeD0iMSIgeT0iMSIgd2lkdGg9IjI2IiBoZWlnaHQ9IjI2IiByeD0iMyIgZmlsbD0id2hpdGUiLz48L3N2Zz4=',
        size: [38, 38],
        stretchX: [[4, 24]],
        stretchY: [[4, 24]],
        padding: [5, 10, 5, 10],
    }
    

• modelsBaseUrl: URL-адрес для определения относительного пути модели. Если URL модели задан без http:// или https:// и доменного имени, модели будут загружаться относительно этого параметра. Значение по умолчанию — '', то есть модели загружаются относительно хоста веб-приложения.
• modelsLoadStrategy: стратегия загрузки и отображения моделей. Возможные значения:
  • waitAll: все модели загружаются, а затем отображаются на карте одновременно (значение по умолчанию).
  • dontWaitAll: модели отображаются по отдельности по мере готовности каждой.
• floorsControl: настройки UI-элемента с кнопками этажей на интерактивной сцене недвижимости. Доступна только опция position. Значение по умолчанию — centerLeft. Возможные значения описаны см. в ControlPosition.
• groundCoveringColor: цвет подложки карты при отображении подземного этажного плана. Значение по умолчанию — #F8F8EBCC.
• zIndex: порядок отрисовки объектов плагина (моделей и подписей) относительно других объектов (Objects) на карте.

События плагина

Чтобы подписаться на события плагина, которые возникают при взаимодействии с его объектами (моделями, подписями):

plugin.on('click', (event) => {
    console.log(event);
});

Список событий, на которые можно подписаться, см. в GltfPluginEventTable. В зависимости от того, какой объект вызывает событие, в аргумент функции-обработчика передаётся событие модели GltfPluginModelEvent или подписи GltfPluginLabelEvent.

Работа с моделями и подписями к ним

Процесс добавления модели на карту состоит из загрузки модели и её отображения. Способ отображения моделей на карте зависит от опции modelsLoadStrategy: см. раздел Инициализация плагина.

Примечание

Чтобы не подбирать настройки позиционирования модели (координаты, поворот и масштаб) вручную, используйте инструмент для позиционирования моделей на карте. Вы можете спозиционировать модель и скопировать значения настроек: см. инструкцию по размещению моделей на карте.

Работа с одной моделью

Перед загрузкой убедитесь, что модель соответствует требованиям.

Чтобы добавить модель на карту, используйте метод addModel и передайте опции модели ModelOptions первым аргументом (второй аргумент не задаётся):

plugin.addModel({
    modelId: 'ea234f1',
    coordinates: [82.8865, 54.9809],
    modelUrl: 'http://example.com/models/model1.glb',
    rotateZ: -15,
    scale: 2,
    interactive: true,
});

Чтобы загрузить модель в кеш, но не отображать её сразу, передайте вторым аргументом значение true.

Чтобы отобразить модель, используйте метод showModel и передайте её идентификатор:

plugin.showModel('ea234f1');

Чтобы скрыть модель с карты, используйте метод hideModel и передайте её идентификатор:

plugin.hideModel('ea234f1');

Чтобы удалить модель с карты и из кеша, используйте метод removeModel:

plugin.removeModel('ea234f1');

Работа с несколькими моделями

Перед загрузкой убедитесь, что модели соответствуют требованиям.

Чтобы добавить несколько моделей на карту, используйте метод addModels и передайте массив опций моделей ModelOptions первым аргументом (второй аргумент не задаётся):

const models = [
    {
        modelId: '347da1',
        coordinates: [82.88651, 54.98092],
        modelUrl: 'http://example.com/models/model1.glb',
        rotateZ: 10,
        interactive: true,
    },
    {
        modelId: 'f932d2',
        coordinates: [82.88659, 54.98101],
        modelUrl: 'http://example.com/models/model2.glb',
        scale: 2,
    },
];

plugin.addModels(models);

Чтобы загрузить модели в кеш, но отобразить только часть из них, передайте вторым аргументом массив их идентификаторов:

plugin.addModels(models, ['347da1']);

Чтобы загрузить модели в кеш, но не отображать их, передайте вторым аргументом пустой массив:

plugin.addModels(models, []);

Чтобы отобразить модели, используйте методы showModels или showModel и передайте их идентификаторы:

plugin.showModels(['347da1', 'f932d2']);

plugin.showModel('ea234f1');

Чтобы скрыть несколько моделей с карты, используйте метод hideModels и передайте массив их идентификаторов:

plugin.hideModels(['347da1', 'f932d2']);

Чтобы удалить модели с карты и из кеша, используйте метод removeModels:

plugin.removeModels(['347da1', 'f932d2']);

Замена объекта на карте моделью

Зачастую необходимо отобразить модель вместо какого-либо объекта на карте, например, здания. Чтобы скрыть объект на карте, который пересекается с моделью:

1. Получите идентификаторы объектов:

   1. Настройте логирование идентификаторов объектов на карте по клику:

      map.on('click', (e) => {
          console.log(e);
      });
      

   2. Откройте Инструменты разработчика браузера (клавиша F12) и нажмите на объекты, которые необходимо скрыть. Скопируйте идентификатор из поля target.id события клика, например:

      {
          "originalEvent": {
              "isTrusted": true
          },
          "lngLat": [82.89980568100268, 54.97787890875184],
          "point": [420, 231],
          "target": {
              "id": "141373143533390"
          },
          "targetData": {
              "type": "default",
              "id": "141373143533390"
          }
      }
      

2. Передайте массив идентификаторов объектов в поле linkedIds опций модели ModelOptions:

   plugin.addModel({
       modelId: 'ea234f1',
       coordinates: [82.8865, 54.9809],
       modelUrl: 'http://example.com/models/model1.glb',
       linkedIds: ['141373143533390'],
   });
   

Работа с подписями моделей

Вы можете разместить дополнительную текстовую информацию на карте через подписи или группу подписей с привязкой к модели и без. Подписи могут содержать любую информацию, например характеристики здания, площадь квартиры, сведения о месте на карте, а также ссылки.

Чтобы добавить подписи на карту, используйте метод addLabelGroup и передайте LabelGroupOptions в качестве аргумента:

const labelGroup = {
    id: '722ea9',
    image: 'default',
    minZoom: 17,
    elevation: 30,
    interactive: true,
    labels: [
        {
            coordinates: [82.886554, 54.980988],
            text: '10 м²',
            userData: {},
        },
        {
            coordinates: [82.8865, 54.9809],
            text: '20 м²',
            elevation: 33,
            interactive: false,
        },
    ],
};

plugin.addLabelGroup(labelGroup);

Примечание

Некоторые опции, например elevation и interactive, можно задать в опциях конкретной подписи в группе LabelOptions. В этом случае приоритет отдается значению из подписи, а не группы.

Чтобы привязать группу подписей к модели (например, зданию), передайте опции модели BuildingState вторым аргументом:

plugin.addLabelGroup(labelGroup, {
    buildingId: 'ea234f1',
});

Чтобы привязать подписи к этажу здания, укажите floorId:

plugin.addLabelGroup(labelGroup, {
    buildingId: 'ea234f1',
    floorId: '123456',
});

Опции будут добавлены в поле target события подписи плагина GltfPluginLabelEvent.

Чтобы удалить группу подписей c карты, используйте метод removeLabelGroup и передайте идентификатор группы в качестве аргумента:

plugin.removeLabelGroup('722ea9');

Пример результата добавления моделей на карту

Работа с интерактивной сценой

Интерактивная сцена недвижимости позволяет представить здание с этажными планами и подписями на карте, с которыми можно взаимодействовать, например, переключать этажи и видеть информацию об отдельных помещениях на этаже.

Способ появления моделей на карте зависит от опции modelsLoadStrategy (см. раздел Инициализация плагина):

• При стратегии waitAll будут загружены сразу все модели из конфигурации сцены, включая модели поэтажных планов. Это увеличит объём загружаемых данных и время появления сцены на карте, но при переключении этажных планов не будет задержки из-за их дозагрузки. Модели сцены недвижимости появятся на карте синхронно.
• При стратегии dontWaitAll будут загружены только главные модели зданий (и этажный план, если задано начальное состояние сцены). Это позволит снизить объём загружаемых данных и показать сцену как можно быстрее. Модели при этом будут отображаться асинхронно, по мере загрузки каждой из них. При переключении этажных планов целевой этаж будет показан с задержкой, если до этого он не был загружен.

Примечание

Для настройки интерактивной сцены с помощью инструмента для позиционирования моделей см. инструкцию Настройка интерактивной сцены.

Конфигурация главной модели здания

На верхнем уровне иерархии находится фасад здания — главная модель, опции которой (BuildingOptions) состоят из опций моделей ModelOptions и дополнительных полей:

• mapOptions: опции карты, которые будут применены, когда фасад становится активным;
• popupOptions: опции всплывающей подсказки, которая отображается при наведении курсора на фасад.

const facade = {
    modelId: '03a234cb',
    coordinates: [47.245286302641034, 56.134743473834099],
    modelUrl: 'http://example.com/models/model1.glb',
    interactive: true,
    rotateZ: 15,
    scale: 1.2,
    linkedIds: ['70030076555821177'],
    mapOptions: {
        center: [47.24547737708662, 56.134591508663135],
        pitch: 40,
        zoom: 19,
        rotation: -41.4,
    },
    popupOptions: {
        coordinates: [47.24511721603574, 56.13451456056651],
        title: 'Корпус 1. 11 этажей',
        description: 'Срок сдачи: IV кв. 2024 г. <br />15 мин. пешком до ст. м. Московская',
    },
};

Конфигурация этажных планов

Чтобы добавить этажные планы в рамках главной модели (фасада), используйте опцию floors. Все добавляемые конфигурации этажных планов переиспользуют опции трансформации моделей своего родительского здания. Таким образом вам не нужно повторно определять поворот, масштабирование и смещение моделей для этажных планов, которые принадлежат одному и тому же зданию.

Опции этажного плана BuildingFloorOptions также содержат поля:

• mapOptions: опции карты, которые будут применены, когда этажный план становится активным;
• text: текст в элементе управления сценой недвижимости;
• labelGroups: групп подписей этажного плана (LabelGroupOptions), с помощью которых можно отображать дополнительную информацию о помещениях на этаже (например, задавать разные группы для проданных апартаментов и находящихся в продаже).

Примечание

Некоторые опции, например elevation и interactive, можно задать в опциях конкретной подписи в группе LabelOptions. В этом случае приоритет отдается значению из подписи, а не группы.

const buildingOptions = {
    ...facade,
    floors: [
        {
            id: '235034',
            text: '1-10',
            modelUrl: 'http://example.com/models/model1_floor1.glb',
            mapOptions: {
                center: [47.24524342863023, 56.13449524271827],
                pitch: 40,
                zoom: 20,
                rotation: -57.5,
            },
            labelGroups: [
                {
                    id: '1111',
                    elevation: 5,
                    image: 'default',
                    minZoom: 19.5,
                    fontSize: 12,
                    fontColor: '#3a3a3a',
                    interactive: true,
                    labels: [
                        {
                            coordinates: [47.245048150280994, 56.134470449142164],
                            text: '3к\n78.4 м²',
                            userData: {
                                url: 'https://docs.2gis.com',
                            },
                        },
                        {
                            coordinates: [47.24520807647288, 56.13443854463778],
                            text: '2к\n67 м²',
                            userData: {
                                url: 'https://docs.2gis.com',
                            },
                        },
                    ],
                },
            ],
        },
    ],
};

Примечание

Этажи должны располагаться в массиве в порядке от самого первого этажа к самому последнему.

Отображение подземных этажей

Чтобы отобразить подземные этажи, задайте значение true опции isUnderground в опциях этажного плана BuildingFloorOptions.

При отображении подземного этажного плана появится подложка, перекрывающая остальные объекты на карте, а другие объекты интерактивной сцены будут скрыты и не будут перекрывать отображённый подземный этажный план. Цвет подложки по умолчанию — #F8F8EBCC. Чтобы его изменить, задайте цвет в свойстве groundCoveringColor опций плагина PluginOptions. Чтобы менять цвет на лету, используйте метод setOptions (может быть полезно при изменении стиля карты).

Добавление интерактивной сцены

Чтобы добавить интерактивную сцену, используйте метод addRealtyScene. Метод автоматически настраивает все необходимые обработчики событий для корректной работы сцены:

plugin.addRealtyScene([buildingOptions]);

В качестве второго аргумента вы можете передать состояние сцены BuildingState, с помощью которого определяется, какой фасад и этаж будут активными после добавления сцены недвижимости на карту:

plugin.addRealtyScene([buildingOptions], { modelId: '03a234cb', floorId: '235034' });

Скрытие интерактивной сцены с последующим показом

Чтобы скрыть интерактивную сцену с карты, используйте метод hideRealtyScene (загруженные модели сохранятся в кеше):

plugin.hideRealtyScene();

Чтобы снова отобразить сцену, используйте метод showRealtyScene:

plugin.showRealtyScene();

Удаление интерактивной сцены

Чтобы удалить интерактивную сцену, используйте метод removeRealtyScene:

plugin.removeRealtyScene();

Пример добавления интерактивной сцены на карту

Когда модели будут отображены на карте, нажмите на одну из них для отображения поэтажных планов.

Основные изменения версии 2

Поскольку во второй версии плагина не используется библиотека ThreeJS, вам необходимо подобрать параметры поворота и смещения и коэффициенты масштабирования моделей заново. Про направления осей модели можно подробнее узнать здесь.

Изменения в опциях плагина

• Из интерфейса PluginOptions удалены следующие опции:

  • dracoScriptsUrl, поскольку загрузка теперь осуществляется силами движка карты;
  • ambientLight, поскольку освещение теперь задаётся через стили карты, которые вы можете настроить в Редакторе стилей.

• Опция hoverHighlight заменена на опцию hoverOptions, в которой можно настроить цвет состояния модели, когда на неё наведён курсор. Цвет применяется путём перемножения каждого компонента, поэтому нет возможности выделять модель белым цветом.

• Опция poiConfig заменена на опцию labelGroupDefaults, которая содержит настройки по умолчанию для каждой группы подписей без разделения на primary и secondary. В версии 1 эти типы применяются для разделения подписей с подложкой и без. В версии 2 подложка для текста задается в опциях группы подписей, а пользовательскую подложку по умолчанию можно задать через опцию image в labelGroupDefaults.

// Пример опций плагина версии 1
{
    dracoScriptsUrl: 'https://unpkg.com/@2gis/mapgl-gltf@^1/dist/libs/draco/',
    poiConfig: {
        primary: {
            fontSize: 14,
            fontColor: '#000000',
        },
        secondary: {
            fontSize: 14,
            fontColor: '#000000',
        },
    },
    ambientLight: {
        color: '#ffffff',
        intencity: 3,
    },
    hoverHighlight: {
        color: '#ff000088',
        intencity: 0.0,
    },
}

// Те же опции плагина версии 2
{
    labelGroupDefaults: {
        fontSize: 14,
        fontColor: '#000000',
    },
    hoverOptions: {
        color: '#ff000088',
    },
}

Изменения в событиях плагина

• Изменения в интерфейсе ModelTarget:

  • Опция modelId стала обязательной и теперь принимает только тип string;
  • Опция floorId удалена.

• Интерфейс PoiTarget переименован в LabelTarget:

  • Значение опции type заменено на label;
  • Опция data теперь принимает значение LabelOptions;
  • Опция modelId переименована в buildingId, которая теперь принимает только тип string;
  • Опция floorId теперь принимает только тип string.

• Интерфейс GltfPluginPoiEvent заменён на GltfPluginLabelEvent.

Изменения в методах плагина

• Метод addModelsPartially удалён. Частичное добавление моделей на карту доступно в методе addModels:

// Пример использования в версии 1
plugin.addModelsPartially(
    [
        {
            modelId: '347da1',
            coordinates: [82.88651, 54.98092],
            modelUrl: 'http://example.com/models/model1.glb',
        },
        {
            modelId: 'f932d2',
            coordinates: [82.88659, 54.98101],
            modelUrl: 'http://example.com/models/model2.glb',
        },
    ],
    ['347da1'],
);

// Тот же пример в версии 2
plugin.addModels(
    [
        {
            modelId: '347da1',
            coordinates: [82.88651, 54.98092],
            modelUrl: 'http://example.com/models/model1.glb',
            interactive: true,
        },
        {
            modelId: 'f932d2',
            coordinates: [82.88659, 54.98101],
            modelUrl: 'http://example.com/models/model2.glb',
            interactive: true,
        },
    ],
    ['347da1'],
);

• В методах removeModel и removeModels удалён второй аргумент preserveCache. Чтобы скрыть модель с карты, используйте методы hideModel или hideModels:

// Пример использования в версии 1
plugin.removeModel('ea234f1', true);
// или
plugin.removeModels(['ea234f1', 'abc354', ..., 'def123'], true);

// Тот же пример в версии 2
plugin.hideModel('ea234f1');
// или
plugin.hideModels(['ea234f1', 'abc354', ..., 'def123']);

• Метод addPoiGroup заменён на метод addLabelGroup:

// Пример использования в версии 1
plugin.addPoiGroup({
    id: '722ea9',
    type: 'primary',
    elevation: 30,
    data: [
        {
            coordinates: [82.886554, 54.980988],
            label: '10 м²',
        },
    ],
});

plugin.addPoiGroup({
    id: '456qwe',
    type: 'secondary',
    elevation: 33,
    data: [
        {
            coordinates: [82.886, 54.98],
            label: '20 м²',
        },
    ],
});

// Тот же пример в версии 2
plugin.addPoiGroup({
    id: '722ea9',
    image: 'default',
    elevation: 30,
    labels: [
        {
            coordinates: [82.886554, 54.980988],
            text: '10 м²',
        },
    ],
});

plugin.addPoiGroup({
    id: '456qwe',
    elevation: 33,
    labels: [
        {
            coordinates: [82.886, 54.98],
            text: '20 м²',
        },
    ],
});

• Метод removePoiGroup заменён на метод removeLabelGroup.
• В методе removeRealtyScene удалён аргумент preserveCache. Чтобы скрыть сцену недвижимости с карты, а затем показать, используйте методы hideRealtyScene и showRealtyScene соответственно:

// Пример использования в версии 1
plugin.removeRealtyScene(true);
plugin.addRealtyScene([ ... ]);

// Тот же пример в версии 2
plugin.hideRealtyScene();
plugin.showRealtyScene();

Изменения в остальных интерфейсах

• Изменения в интерфейсе ModelOptions:
  • Опция modelId теперь принимает только тип string;
  • Опция interactive теперь содержит значение false по умолчанию.

// Пример использования в версии 1
plugin.addModel({
    modelId: 1234,
    coordinates: [82.8865, 54.9809],
    modelUrl: 'http://example.com/models/model1.glb',
});

// Тот же пример в версии 2
plugin.addModel({
    modelId: '1234',
    coordinates: [82.8865, 54.9809],
    modelUrl: 'http://example.com/models/model1.glb',
    interactive: true,
});

• Изменения в интерфейсе BuildingFloorOptions:
  • Опция id теперь принимает только тип string.
  • Опция poiGroups переименована в labelGroups, которая теперь принимает массив LabelGroupOptions.
• Интерфейс PoiGroupOptions переименован в интерфейс LabelGroupOptions:
  • Опция id теперь принимает только тип string.
  • Удалена опция type. Используйте опцию image, которая принимает настройки подложки для текста подписей в группе.
  • Опция data переименована в labels и теперь принимает массив LabelOptions.
• Интерфейс PoiOptions переименован в LabelOptions:
  • Опция label переименована в text.

// Пример использования в версии 1
plugin.addRealtyScene([{
    ...,
    floors: [{
        id: 235034,
        text: '1-10',
        modelUrl: 'http://example.com/models/model1_floor1.glb',
        poiGroups: [
            {
                id: 1111,
                type: 'primary',
                elevation: 5,
                data: [{
                    coordinates: [47.245048150280994, 56.134470449142164],
                    label: '3к\n78.4 м²',
                }],
            },
            {
                id: 2222,
                type: 'secondary',
                elevation: 5,
                data: [{
                    coordinates: [47.2451, 56.1344],
                    label: '2к\n60 м²',
                }],
            },
        ],
    }],
}]);

// Тот же пример в версии 2
plugin.addRealtyScene([{
    ...,
    floors: [{
        id: '235034',
        text: '1-10',
        modelUrl: 'http://example.com/models/model1_floor1.glb',
        labelGroups: [
            {
                id: '1111',
                image: 'default',
                elevation: 5,
                interactive: true,
                labels: [{
                    coordinates: [47.245048150280994, 56.134470449142164],
                    text: '3к\n78.4 м²',
                }],
            },
            {
                id: '2222',
                elevation: 5,
                interactive: true,
                labels: [{
                    coordinates: [47.2451, 56.1344],
                    text: '2к\n60 м²',
                }],
            },
        ],
    }],
}]);

• Изменения в интерфейсе BuildingState:
  • Опция modelId заменена на опцию buildingId, которая теперь принимает только тип string.
  • Опция floorId теперь принимает только тип string.

// Пример использования в версии 1
plugin.addPoiGroup({ ... }, {
    modelId: 1111,
    floorId: 2222,
});
// или
plugin.addRealtyScene([ ... ], {
    modelId: 'abc123',
    floorId: 'def456',
});

// Тот же пример в версии 2
plugin.addLabelGroup({ ... }, {
    buildingId: '1111',
    floorId: '2222',
});
// или
plugin.addRealtyScene([ ... ], {
    buildingId: 'abc123',
    floorId: 'def456',
});