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

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

Важно

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

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

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

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

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

Подключите плагин одним из следующих способов:

• Подключение внешнего скрипта

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

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

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

  const plugin = new mapgl.GltfPlugin(map);
  

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

  npm install @2gis/mapgl-gltf
  

Инициализация и дополнительные опции

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

const plugin = new GltfPlugin(map);

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

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: опции для состояния моделей при наведении курсора (hover). На данный момент доступна только опция 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: eсли URL модели задан без http:// или https:// и доменного имени, модели будут загружаться относительно этого параметра. Значение по умолчанию — '', то есть модели будут загружаться относительно хоста веб-приложения.
• modelsLoadStrategy: стратегия загрузки и отображения моделей. Возможные значения:
  • waitAll: все модели загружаются, а затем отображаются одновременно (значение по умолчанию);
  • dontWaitAll: модели отображаются на карте по мере готовности каждой в отдельности.
• floorsControl: опции кнопок интерактивной сцены недвижимости. На данный момент доступна только опция position. Возможные значения описаны в ControlPosition. Значение по умолчанию — centerLeft.
• groundCoveringColor: цвет подложки карты при показе подземного этажного плана. Значение по умолчанию — #F8F8EBCC.
• zIndex: порядок отрисовки объектов плагина (модели, подписи) относительно других объектов на карте.

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

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

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

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

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

Процесс добавления модели на карту состоит из этапов загрузки модели и ее отображения. Способ появления моделей на карте зависит от опции modelsLoadStrategy (см. инициализацию плагина).

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

Чтобы добавить модель на карту, используйте метод addModel и передайте опции модели первым аргументом. Второй аргумент при этом не задаётся.

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

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

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

plugin.hideModel('ea234f1');

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

plugin.showModel('ea234f1');

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

plugin.removeModel('ea234f1');

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

Чтобы добавить несколько моделей на карту, используйте метод addModels и передайте массив опций моделей первым аргументом. Второй аргумент при этом не задаётся.

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, []);

В дальнейшем для отображения непоказанных моделей используйте методы showModel или showModels.

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

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

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

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

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

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

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

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

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

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

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

   2. Откройте инструменты разработчика браузера (DevTools) и кликните по объектам, которые необходимо скрыть моделью.

      Идентификатор будет находится в поле target залогированного события клика, например:

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

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

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

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

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

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

Примечание

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

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);

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

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

Также вы можете привязать подписи к этажу здания:

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

Таким образом эти опции будут добавлены в поле target события подписи плагина.

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

plugin.removeLabelGroup('722ea9');

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

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

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

Обратите внимание, что стратегия загрузки и появления моделей на карте определяется опцией modelsLoadStrategy (см. инициализацию плагина):

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

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

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

• 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. Все добавляемые конфигурации этажных планов переиспользуют опции трансформации моделей своего родительского здания. Таким образом вам не нужно повторно определять поворот, масштабирование и смещение моделей для этажных планов, которые принадлежат одному и тому же зданию.

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

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

Примечание

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

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 в опциях этажного плана.

При отображении такого этажного плана:

• появится подложка, перекрывающая остальные объекты на карте;
• другие объекты интерактивной сцены недвижимости будут скрыты;
• объекты на карте (например, другие здания) не будут перекрывать отображённый подземный этажный план.

Цвет подложки по умолчанию — #F8F8EBCC. Чтобы его изменить, задайте пользовательский цвет в опциях плагина в свойстве groundCoveringColor или воспользуйтесь методом setOptions плагина. Использование метода позволяет изменять цвет на лету, что может быть полезным при изменении стиля карты.

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

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

plugin.addRealtyScene([buildingOptions]);

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

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

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

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

plugin.hideRealtyScene();

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

plugin.showRealtyScene();

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

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

plugin.removeRealtyScene();

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

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

Основные изменения относительно версии 1

Поскольку во второй версии плагина не используется библиотека 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',
});