此页面由 Cloud Translation API 翻译。

使用 3D 卡片渲染程序

欧洲经济区 (EEA) 开发者

仿真 3D 图块采用 OGC 标准 glTF 格式，这意味着您可以使用任何支持 OGC 3D 图块规范的渲染器来构建 3D 可视化效果。例如，Cesium 是一个用于渲染 3D 可视化的基础开源库。

使用 CesiumJS

CesiumJS 是一个开源 JavaScript 库，用于在 Web 上进行 3D 可视化。如需详细了解如何使用 CesiumJS，请参阅 Learn CesiumJS。

用户控制功能

CesiumJS 图块渲染器具有一组标准的用户控件。

操作	说明
全景视图	左键点击并拖动
缩放视图	右键点击并拖动，或滚动鼠标滚轮
旋转视图	按住 Ctrl 键并使用鼠标左键/右键点击并拖动，或使用鼠标中键点击并拖动

最佳做法

您可以采取多种方法来缩短 CesiumJS 3D 加载时间。例如：

通过将以下语句添加到渲染 HTML 中来启用同步请求：
```
Cesium.RequestScheduler.requestsByServer["tile.googleapis.com:443"] = <REQUEST_COUNT>
```
REQUEST_COUNT 值越高，图块加载速度越快。不过，当在 REQUEST_COUNT 大于 10 且缓存已停用的 Chrome 浏览器中加载时，您可能会遇到已知的 Chrome 问题。对于大多数使用情形，我们建议将 REQUEST_COUNT 设置为 18，以获得最佳性能。
启用后可跳过详细程度级别。如需了解详情，请参阅此 Cesium 问题。

通过启用 showCreditsOnScreen: true，确保您正确显示数据提供方信息。如需了解详情，请参阅政策。

呈现指标

如需查找帧速率，请查看每秒调用 requestAnimationFrame 方法的次数。

如需了解帧延迟时间的计算方式，请查看 PerformanceDisplay 类。

CesiumJS 渲染器示例

您只需提供根图块集网址，即可将 CesiumJS 渲染器与 Map Tiles API 的 3D 图块搭配使用。

简单示例

以下示例初始化了 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 搭配使用，以检索更多信息。您可以使用自动补全 widget 飞往地点的视口。此示例使用地点自动补全 API（通过按照这些说明操作启用）和 Maps JavaScript API（通过按照这些说明操作启用）。

<!DOCTYPE html>
<head>
 <meta charset="utf-8" />
 <title>CesiumJS 3D Tiles Places API 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 和 Elevation API 结合使用，此动画可模拟对任何兴趣点的交互式无人机飞越。

此代码示例可让您在自动补全微件中选择的地点周围飞行。

<!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 for Unreal

如需将 Cesium for Unreal 插件与 3D Tiles API 搭配使用，请按以下步骤操作。

安装 Cesium for Unreal 插件。
创建新的 Unreal 项目。
连接到 Google 仿真 3D 图块 API。
1. 依次选择菜单中的 Cesium > Cesium，打开 Cesium 窗口。
2. 选择空白 3D 图块图块集。
3. 在世界大纲视图中，选择此 Cesium3DTileset 以打开详细信息面板。
4. 将来源从 Cesium Ion 更改为来自网址。
5. 将网址设置为 Google 3D 地块网址。
```
https://tile.googleapis.com/v1/3dtiles/root.json?key=YOUR_API_KEY
```
1. 启用在屏幕上显示提供方信息，以便正确显示提供方信息。
这会加载世界。如需移动到任何 LatLng，请在大纲面板中选择 CesiumGeoreference 项，然后在详细信息面板中修改原点纬度/经度/高度。

使用 Cesium for Unity

如需在 Cesium for Unity 中使用照片级逼真图块，请按以下步骤操作。

创建新的 Unity 项目。
在“Package Manager”（资源包管理器）部分中添加新的 Scoped Registry（通过 Editor > Project Settings）。
- 名称：Cesium
- 网址：https://unity.pkg.cesium.com
- 范围：com.cesium.unity
安装 Cesium for Unity 软件包。
连接到 Google 仿真 3D 图块 API。
1. 依次选择菜单中的 Cesium > Cesium，打开 Cesium 窗口。
2. 点击空白 3D 图块图块集。
3. 在左侧面板的来源下，选择 Tileset Source 选项中的 From 网址（而不是 From Cesium Ion）。
4. 将网址设置为 Google 3D 图块网址。
```
https://tile.googleapis.com/v1/3dtiles/root.json?key=YOUR_API_KEY
```
1. 启用在屏幕上显示提供方信息，以便正确显示提供方信息。
这会加载世界。如需移动到任何 LatLng，请在场景层次结构中选择 CesiumGeoreference 项，然后在检查器中修改原点纬度/经度/高度。

使用 deck.gl

deck.gl 是一款由 WebGL 提供支持的开源 JavaScript 框架，可用于实现高性能的大规模数据可视化。

归因

通过从图块 gltf asset 中提取 copyright 字段，然后在渲染视图中显示该字段，确保您正确显示数据提供方信息。如需了解详情，请参阅显示数据提供方信息。

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>

在 Google 仿真 3D 图块之上直观呈现 2D 图层

deck.gl TerrainExtension 可将原本为 2D 的数据渲染到 3D 表面上。例如，您可以将建筑物轮廓的 GeoJSON 覆盖在仿真 3D 图块几何图形之上。

在以下示例中，建筑物图层以多边形的形式可视化，这些多边形已适应 Photorealistic 3D Tiles 表面。

<!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>

使用 3D 卡片渲染程序 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

使用 CesiumJS

用户控制功能

最佳做法

呈现指标

CesiumJS 渲染器示例

简单示例

Places API 集成

旋转无人机视图

绘制多段线和标签

相机轨道

使用 Cesium for Unreal

使用 Cesium for Unity

使用 deck.gl

归因

deck.gl 渲染器示例

简单示例

在 Google 仿真 3D 图块之上直观呈现 2D 图层

使用 3D 卡片渲染程序