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

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

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

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

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

  Для этого нужно добавить следующую строку после подключения основного скрипта:

  <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. Настройте логирование идентификаторов объектов на карте по клику:

   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"
       }
   }
   

3. Передайте массив индентификаторов объектов для скрытия в поле 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, в которой можно настроить цвет hover-состояния модели. Цвет применяется путем перемножения каждой компоненты, поэтому нет возможности выделять модель белым цветом. В дальнейшем возможно расширение набора режимов смешивания цвета.

• Опция poiConfig заменена на опцию labelGroupDefaults, которая содержит настройки по умолчанию для каждой группы подписей без разделения на primary и secondary. Эти типы применялись для разделения подписей с подложкой и без. Теперь подложка для текста задается в опциях группы подписей, а пользовательскую подложку по умолчанию можно задать через опцию 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',
});