Как работать с рендерером 3D Tiles

Разработчики из Европейской экономической зоны (ЕЭЗ)

Фотореалистичные 3D-плитки представлены в стандартном формате OGC glTF, поэтому для создания 3D-визуализаций можно использовать любой рендерер, поддерживающий спецификацию OGC 3D Tiles. Например, Cesium – это базовая библиотека с открытым исходным кодом для рендеринга трехмерных визуализаций.

Работа с CesiumJS

CesiumJS – это библиотека JavaScript с открытым исходным кодом для 3D-визуализации в интернете. Дополнительную информацию об использовании CesiumJS можно найти в руководстве по CesiumJS.

Личные

В средстве визуализации тайлов CesiumJS есть стандартный набор элементов управления.

Действие Описание
Панорама Нажать левую кнопку и перетащить
Масштабирование Нажмите правой кнопкой мыши и перетащите или прокрутите колесо мыши.
Поворот Ctrl + нажать левую/правую кнопку мыши и перетащить или нажать среднюю кнопку мыши и перетащить

Рекомендации

Есть несколько способов сократить время загрузки 3D-объектов CesiumJS. Пример:

  • Чтобы включить одновременные запросы, добавьте в HTML-код отрисовки следующее выражение:

    Cesium.RequestScheduler.requestsByServer["tile.googleapis.com:443"] = <REQUEST_COUNT>
    

    Чем выше REQUEST_COUNT, тем быстрее загружаются фрагменты. Однако при загрузке в браузере Chrome с REQUEST_COUNT больше 10 и отключенным кешем вы можете столкнуться с известной проблемой Chrome. В большинстве случаев для оптимальной производительности рекомендуется использовать значение REQUEST_COUNT, равное 18.

  • Включите пропуск уровней детализации. Дополнительную информацию можно найти в этой статье о проблеме с Cesium.

Чтобы правильно показывать атрибуцию данных, включите showCreditsOnScreen: true. Дополнительную информацию можно найти в разделе Правила.

Показатели отрисовки

Чтобы узнать частоту кадров, посмотрите, сколько раз в секунду вызывается метод requestAnimationFrame.

Чтобы узнать, как рассчитывается задержка кадров, посмотрите класс PerformanceDisplay.

Примеры рендеринга CesiumJS

Чтобы использовать средство визуализации CesiumJS с 3D-фрагментами Map Tiles API, достаточно указать URL корневого набора фрагментов.

Простой пример

В следующем примере инициализируется средство отрисовки CesiumJS, а затем загружается корневой набор тайлов.

<!DOCTYPE html>
<head>
  <meta charset="utf-8">
  <title>CesiumJS 3D Tiles Simple Demo</title>
  <script src="https://ajax.googleapis.com/ajax/libs/cesiumjs/1.105/Build/Cesium/Cesium.js"></script>
  <link href="https://ajax.googleapis.com/ajax/libs/cesiumjs/1.105/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
</head>
<body>
  <div id="cesiumContainer"></div>
  <script>

    // Enable simultaneous requests.
    Cesium.RequestScheduler.requestsByServer["tile.googleapis.com:443"] = 18;

    // Create the viewer.
    const viewer = new Cesium.Viewer('cesiumContainer', {
      imageryProvider: false,
      baseLayerPicker: false,
      geocoder: false,
      globe: false,
      // https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/#enabling-request-render-mode
      requestRenderMode: true,
    });

    // Add 3D Tiles tileset.
    const tileset = viewer.scene.primitives.add(new Cesium.Cesium3DTileset({
      url: "https://tile.googleapis.com/v1/3dtiles/root.json?key=YOUR_API_KEY",
      // This property is needed to appropriately display attributions
      // as required.
      showCreditsOnScreen: true,
    }));
  </script>
</body>

Подробную информацию о параметре requestRenderMode можно найти в разделе Включение режима обработки запросов.

HTML-страница будет выглядеть так, как показано ниже.

Интеграция с Places API (новой версии)

Чтобы получить больше информации, вы можете использовать CesiumJS с Places API (New). Вы можете использовать виджет автозаполнения, чтобы перейти к области просмотра мест. В этом примере используется Places Autocomplete API, который включается по этим инструкциям, и Maps JavaScript API, который включается по этим инструкциям.

<!DOCTYPE html>
<head>
 <meta charset="utf-8" />
 <title>CesiumJS 3D Tiles Places API (New) Integration Demo</title>
 <script src="https://ajax.googleapis.com/ajax/libs/cesiumjs/1.105/Build/Cesium/Cesium.js"></script>
 <link href="https://ajax.googleapis.com/ajax/libs/cesiumjs/1.105/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
</head>
<body>
 <label for="pacViewPlace">Go to a place: </label>
 <input
   type="text"
   id="pacViewPlace"
   name="pacViewPlace"
   placeholder="Enter a location..."
   style="width: 300px"
 />
 <div id="cesiumContainer"></div>
 <script>
   // Enable simultaneous requests.
   Cesium.RequestScheduler.requestsByServer["tile.googleapis.com:443"] = 18;

   // Create the viewer.
   const viewer = new Cesium.Viewer("cesiumContainer", {
     imageryProvider: false,
     baseLayerPicker: false,
     requestRenderMode: true,
     geocoder: false,
     globe: false,
   });

   // Add 3D Tiles tileset.
   const tileset = viewer.scene.primitives.add(
     new Cesium.Cesium3DTileset({
       url: "https://tile.googleapis.com/v1/3dtiles/root.json?key=YOUR_API_KEY",
       // This property is required to display attributions as required.
       showCreditsOnScreen: true,
     })
   );

   const zoomToViewport = (viewport) => {
     viewer.entities.add({
       polyline: {
         positions: Cesium.Cartesian3.fromDegreesArray([
           viewport.getNorthEast().lng(), viewport.getNorthEast().lat(),
           viewport.getSouthWest().lng(), viewport.getNorthEast().lat(),
           viewport.getSouthWest().lng(), viewport.getSouthWest().lat(),
           viewport.getNorthEast().lng(), viewport.getSouthWest().lat(),
           viewport.getNorthEast().lng(), viewport.getNorthEast().lat(),
         ]),
         width: 10,
         clampToGround: true,
         material: Cesium.Color.RED,
       },
     });
     viewer.flyTo(viewer.entities);
   };

   function initAutocomplete() {
     const autocomplete = new google.maps.places.Autocomplete(
       document.getElementById("pacViewPlace"),
       {
         fields: [
           "geometry",
           "name",
         ],
       }
     );
     autocomplete.addListener("place_changed", () => {
       viewer.entities.removeAll();
       const place = autocomplete.getPlace();
       if (!place.geometry || !place.geometry.viewport) {
         window.alert("No viewport for input: " + place.name);
         return;
       }
       zoomToViewport(place.geometry.viewport);
     });
   }
 </script>
 <script
   async=""
   src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initAutocomplete"
 ></script>
</body>

Вращающийся вид с дрона

Вы можете управлять камерой, чтобы анимировать набор фрагментов. В сочетании с Places API (New) и Elevation API эта анимация имитирует интерактивный облет дроном любой достопримечательности.

Этот пример кода позволяет облететь место, выбранное в виджете Autocomplete.

<!DOCTYPE html>
<head>
  <meta charset="utf-8" />
  <title>CesiumJS 3D Tiles Rotating Drone View Demo</title>
  <script src="https://ajax.googleapis.com/ajax/libs/cesiumjs/1.105/Build/Cesium/Cesium.js"></script>
  <link href="https://ajax.googleapis.com/ajax/libs/cesiumjs/1.105/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
</head>
<body>
  <label for="pacViewPlace">Go to a place: </label>
  <input type="text" id="pacViewPlace" name="pacViewPlace" placeholder="Enter a location..." style="width: 300px" />
  <div id="cesiumContainer"></div>
  <script>
    // Enable simultaneous requests.
    Cesium.RequestScheduler.requestsByServer["tile.googleapis.com:443"] = 18;

    // Create the viewer and remove unneeded options.
    const viewer = new Cesium.Viewer("cesiumContainer", {
      imageryProvider: false,
      baseLayerPicker: false,
      homeButton: false,
      fullscreenButton: false,
      navigationHelpButton: false,
      vrButton: false,
      sceneModePicker: false,
      geocoder: false,
      globe: false,
      infobox: false,
      selectionIndicator: false,
      timeline: false,
      projectionPicker: false,
      clockViewModel: null,
      animation: false,
      requestRenderMode: true,
    });

    // Add 3D Tile set.
    const tileset = viewer.scene.primitives.add(
      new Cesium.Cesium3DTileset({
        url: "https://tile.googleapis.com/v1/3dtiles/root.json?key=YOUR_API_KEY",
        // This property is required to display attributions.
        showCreditsOnScreen: true,
      })
    );

    // Point the camera at a location and elevation, at a viewport-appropriate distance.
    function pointCameraAt(location, viewport, elevation) {
      const distance = Cesium.Cartesian3.distance(
        Cesium.Cartesian3.fromDegrees(
          viewport.getSouthWest().lng(), viewport.getSouthWest().lat(), elevation),
        Cesium.Cartesian3.fromDegrees(
          viewport.getNorthEast().lng(), viewport.getNorthEast().lat(), elevation)
      ) / 2;
      const target = new Cesium.Cartesian3.fromDegrees(location.lng(), location.lat(), elevation);
      const pitch = -Math.PI / 4;
      const heading = 0;
      viewer.camera.lookAt(target, new Cesium.HeadingPitchRange(heading, pitch, distance));
    }

    // Rotate the camera around a location and elevation, at a viewport-appropriate distance.
    let unsubscribe = null;
    function rotateCameraAround(location, viewport, elevation) {
      if(unsubscribe) unsubscribe();
      pointCameraAt(location, viewport, elevation);
      unsubscribe = viewer.clock.onTick.addEventListener(() => {
        viewer.camera.rotate(Cesium.Cartesian3.UNIT_Z);
      });
    }

    function initAutocomplete() {
      const autocomplete = new google.maps.places.Autocomplete(
        document.getElementById("pacViewPlace"), {
          fields: [
            "geometry",
            "name",
          ],
        }
      );

      autocomplete.addListener("place_changed", async () => {
        const place = autocomplete.getPlace();

        if (!(place.geometry && place.geometry.viewport && place.geometry.location)) {
          window.alert(`Insufficient geometry data for place: ${place.name}`);
          return;
        }
        // Get place elevation using the ElevationService.
        const elevatorService = new google.maps.ElevationService();
        const elevationResponse =  await elevatorService.getElevationForLocations({
          locations: [place.geometry.location],
        });

        if(!(elevationResponse.results && elevationResponse.results.length)){
          window.alert(`Insufficient elevation data for place: ${place.name}`);
          return;
        }
        const elevation = elevationResponse.results[0].elevation || 10;

        rotateCameraAround(
          place.geometry.location,
          place.geometry.viewport,
          elevation
        );
      });
    }
  </script>
  <script async src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initAutocomplete"></script>
</body>

Как рисовать ломаные линии и добавлять к ним ярлыки

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

Вы можете провести для пользователей экскурсию по району или показать соседние объекты недвижимости, которые сейчас продаются, а затем добавить на сцену 3D-объекты, например рекламные щиты.

Вы можете обобщить поездку, перечислив просмотренные вами объекты недвижимости и отобразив эти сведения в виртуальных объектах.

<!DOCTYPE html>
<head>
  <meta charset="utf-8" />
  <title>CesiumJS 3D Tiles Polyline and Label Demo</title>
  <script src="https://ajax.googleapis.com/ajax/libs/cesiumjs/1.105/Build/Cesium/Cesium.js"></script>
  <link
    href="https://ajax.googleapis.com/ajax/libs/cesiumjs/1.105/Build/Cesium/Widgets/widgets.css"
    rel="stylesheet"
  />
</head>
<body>
  <div id="cesiumContainer"></div>
  <script>
    // Enable simultaneous requests.
    Cesium.RequestScheduler.requestsByServer["tile.googleapis.com:443"] = 18;

    // Create the viewer.
    const viewer = new Cesium.Viewer("cesiumContainer", {
      imageryProvider: false,
      baseLayerPicker: false,
      requestRenderMode: true,
      geocoder: false,
      globe: false,
    });

    // Add 3D Tiles tileset.
    const tileset = viewer.scene.primitives.add(
      new Cesium.Cesium3DTileset({
        url: "https://tile.googleapis.com/v1/3dtiles/root.json?key=YOUR_API_KEY",

        // This property is required to display attributions as required.
        showCreditsOnScreen: true,
      })
    );

    // Draws a circle at the position, and a line from the previous position.
    const drawPointAndLine = (position, prevPosition) => {
      viewer.entities.removeAll();
      if (prevPosition) {
        viewer.entities.add({
          polyline: {
            positions: [prevPosition, position],
            width: 3,
            material: Cesium.Color.WHITE,
            clampToGround: true,
            classificationType: Cesium.ClassificationType.CESIUM_3D_TILE,
          },
        });
      }
      viewer.entities.add({
        position: position,
        ellipsoid: {
          radii: new Cesium.Cartesian3(1, 1, 1),
          material: Cesium.Color.RED,
        },
      });
    };

    // Compute, draw, and display the position's height relative to the previous position.
    var prevPosition;
    const processHeights = (newPosition) => {
      drawPointAndLine(newPosition, prevPosition);

      const newHeight = Cesium.Cartographic.fromCartesian(newPosition).height;
      let labelText = "Current altitude (meters above sea level):\n\t" + newHeight;
      if (prevPosition) {
        const prevHeight =
          Cesium.Cartographic.fromCartesian(prevPosition).height;
        labelText += "\nHeight from previous point (meters):\n\t" + Math.abs(newHeight - prevHeight);
      }
      viewer.entities.add({
        position: newPosition,
        label: {
          text: labelText,
          disableDepthTestDistance: Number.POSITIVE_INFINITY,
          pixelOffset: new Cesium.Cartesian2(0, -10),
          showBackground: true,
          verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
        }
      });

      prevPosition = newPosition;
    };

    const handler = new Cesium.ScreenSpaceEventHandler(viewer.canvas);
    handler.setInputAction(function (event) {
      const earthPosition = viewer.scene.pickPosition(event.position);
      if (Cesium.defined(earthPosition)) {
        processHeights(earthPosition);
      }
    }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
  </script>
</body>

Орбита камеры

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

Сначала зафиксируйте камеру на точке, а затем создайте орбиту камеры, чтобы показать объект. Для этого используйте функцию камеры lookAtTransform с прослушивателем событий, как показано в примере кода ниже.

// Lock the camera onto a point.
const center = Cesium.Cartesian3.fromRadians(
  2.4213211833389243,
  0.6171926869414084,
  3626.0426275055174
);

const transform = Cesium.Transforms.eastNorthUpToFixedFrame(center);

viewer.scene.camera.lookAtTransform(
  transform,
  new Cesium.HeadingPitchRange(0, -Math.PI / 8, 2900)
);

// Orbit around this point.
viewer.clock.onTick.addEventListener(function (clock) {
  viewer.scene.camera.rotateRight(0.005);
});

Подробнее о том, как управлять камерой…

Как работать с Cesium для Unreal

Чтобы использовать плагин Cesium для Unreal с 3D Tiles API, выполните следующие действия:

  1. Установите плагин Cesium for Unreal.

  2. Создайте новый проект Unreal.

  3. Подключитесь к Google Photorealistic 3D Tiles API.

    1. Откройте окно Cesium, выбрав в меню Cesium > Cesium.

    2. Выберите Пустой набор 3D-плиток.

    3. В структурном редакторе мира откройте панель Сведения, выбрав Cesium3DTileset.

    4. В разделе Источник выберите Из URL вместо Из Cesium Ion.

    5. Укажите URL Google 3D Tiles.

    https://tile.googleapis.com/v1/3dtiles/root.json?key=YOUR_API_KEY
    
    1. Чтобы правильно отображать информацию об авторстве, включите параметр Показывать титры на экране.
  4. Загрузка мира. Чтобы перейти к любому объекту LatLng, выберите элемент CesiumGeoreference на панели Структурный редактор, а затем измените Origin Latitude/Longitude/Height (Широта/долгота/высота начала координат) на панели Детали.

Как работать с Cesium для Unity

Чтобы использовать фотореалистичные тайлы с Cesium для Unity, выполните следующие действия:

  1. Создайте проект Unity.

  2. Добавьте новый реестр с областью действия в разделе Package Manager (через Editor > Project Settings).

    • Название: Cesium

    • URL: https://unity.pkg.cesium.com

    • Области действия: com.cesium.unity

  3. Установите пакет Cesium для Unity.

  4. Подключитесь к Google Photorealistic 3D Tiles API.

    1. Откройте окно Cesium, выбрав в меню Cesium > Cesium.

    2. Нажмите Blank 3D Tiles Tileset (Пустой набор 3D-плиток).

    3. На панели слева в разделе Source (Источник) в пункте Tileset Source (Источник набора фрагментов) выберите From URL (Из URL) вместо From Cesium Ion (Из Cesium Ion).

    4. Укажите URL Google 3D Tiles.

    https://tile.googleapis.com/v1/3dtiles/root.json?key=YOUR_API_KEY
    
    1. Включите параметр Показывать информацию об авторстве на экране, чтобы правильно отображать атрибуцию.
  5. Загрузится мир. Чтобы перейти к любой точке LatLng, выберите элемент CesiumGeoreference в разделе Scene Hierarchy (Иерархия сцены), а затем измените значения Origin Latitude/Longitude/Height (Широта/долгота/высота источника) в разделе Inspector (Инспектор).

Как работать с deck.gl

deck.gl – это фреймворк JavaScript с открытым исходным кодом на основе WebGL, предназначенный для высокопроизводительной визуализации больших объемов данных.

Атрибуция

Чтобы правильно показывать атрибуцию данных, извлеките поле copyright из gltf-файла фрагментов asset и добавьте его в визуализацию. Подробнее об атрибуции данных…

Примеры рендеринга в deck.gl

Простой пример

В следующем примере инициализируется средство отрисовки deck.gl, а затем загружается место в 3D. В коде обязательно замените YOUR_API_KEY своим ключом API.

<!DOCTYPE html>
<html>
 <head>
   <title>deck.gl Photorealistic 3D Tiles example</title>
   <script src="https://unpkg.com/deck.gl@latest/dist.min.js"></script>
   <style>
     body { margin: 0; padding: 0;}
     #map { position: absolute; top: 0;bottom: 0;width: 100%;}
     #credits { position: absolute; bottom: 0; right: 0; padding: 2px; font-size: 15px; color: white;
        text-shadow: -1px 0 black, 0 1px black, 1px 0 black, 0 -1px black;}
   </style>
 </head>

 <body>
   <div id="map"></div>
   <div id="credits"></div>
   <script>
     const GOOGLE_API_KEY = YOUR_API_KEY;
     const TILESET_URL = `https://tile.googleapis.com/v1/3dtiles/root.json`;
     const creditsElement = document.getElementById('credits');
     new deck.DeckGL({
       container: 'map',
       initialViewState: {
         latitude: 50.0890,
         longitude: 14.4196,
         zoom: 16,
         bearing: 90,
         pitch: 60,
         height: 200
       },
       controller: {minZoom: 8},
       layers: [
         new deck.Tile3DLayer({
           id: 'google-3d-tiles',
           data: TILESET_URL,
           loadOptions: {
            fetch: {
              headers: {
                'X-GOOG-API-KEY': GOOGLE_API_KEY
              }
            }
          },
           onTilesetLoad: tileset3d => {
             tileset3d.options.onTraversalComplete = selectedTiles => {
               const credits = new Set();
               selectedTiles.forEach(tile => {
                 const {copyright} = tile.content.gltf.asset;
                 copyright.split(';').forEach(credits.add, credits);
                 creditsElement.innerHTML = [...credits].join('; ');
               });
               return selectedTiles;
             }
           }
         })
       ]
     });
   </script>
 </body>
</html>

Визуализация 2D-слоев поверх фотореалистичных 3D-плиток Google

Расширение deck.gl TerrainExtension позволяет визуализировать 2D-данные на 3D-поверхности. Например, вы можете наложить GeoJSON с контуром здания на фотореалистичные 3D-плитки.

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

<!DOCTYPE html>
<html>
 <head>
   <title>Google 3D tiles example</title>
   <script src="https://unpkg.com/deck.gl@latest/dist.min.js"></script>
   <style>
     body { margin: 0; padding: 0;}
     #map { position: absolute; top: 0;bottom: 0;width: 100%;}
     #credits { position: absolute; bottom: 0; right: 0; padding: 2px; font-size: 15px; color: white;
        text-shadow: -1px 0 black, 0 1px black, 1px 0 black, 0 -1px black;}
   </style>
 </head>

 <body>
   <div id="map"></div>
   <div id="credits"></div>
   <script>
     const GOOGLE_API_KEY = YOUR_API_KEY;
     const TILESET_URL = `https://tile.googleapis.com/v1/3dtiles/root.json`;
     const BUILDINGS_URL = 'https://raw.githubusercontent.com/visgl/deck.gl-data/master/examples/google-3d-tiles/buildings.geojson'
     const creditsElement = document.getElementById('credits');
     const deckgl = new deck.DeckGL({
       container: 'map',
       initialViewState: {
         latitude: 50.0890,
         longitude: 14.4196,
         zoom: 16,
         bearing: 90,
         pitch: 60,
         height: 200
       },
       controller: true,
       layers: [
         new deck.Tile3DLayer({
           id: 'google-3d-tiles',
           data: TILESET_URL,
           loadOptions: {
            fetch: {
              headers: {
                'X-GOOG-API-KEY': GOOGLE_API_KEY
              }
            }
          },
          onTilesetLoad: tileset3d => {
             tileset3d.options.onTraversalComplete = selectedTiles => {
               const credits = new Set();
               selectedTiles.forEach(tile => {
                 const {copyright} = tile.content.gltf.asset;
                 copyright.split(';').forEach(credits.add, credits);
                 creditsElement.innerHTML = [...credits].join('; ');
               });
               return selectedTiles;
             }
           },
           operation: 'terrain+draw'
         }),
         new deck.GeoJsonLayer({
           id: 'buildings',
           // This dataset is created by CARTO, using other Open Datasets available. More info at: https://3dtiles.carto.com/#about.
           data: 'https://raw.githubusercontent.com/visgl/deck.gl-data/master/examples/google-3d-tiles/buildings.geojson',
           stroked: false,
           filled: true,
           getFillColor: ({properties}) => {
             const {tpp} = properties;
             // quantiles break
             if (tpp < 0.6249)
               return [254, 246, 181]
             else if (tpp < 0.6780)
               return [255, 194, 133]
             else if (tpp < 0.8594)
               return [250, 138, 118]
             return [225, 83, 131]
           },
           opacity: 0.2,
           extensions: [new deck._TerrainExtension()]
         })
       ]
     });
   </script>
 </body>
</html>