使用 3D 資訊方塊轉譯器

歐洲經濟區 (EEA) 開發人員

擬真 3D 圖塊採用 OGC 標準 glTF 格式，因此您可以使用任何支援 OGC 3D 圖塊規格的轉譯器，建構 3D 視覺化內容。舉例來說，Cesium 是用於算繪 3D 視覺效果的基礎開放原始碼程式庫。

使用 CesiumJS

CesiumJS 是開放原始碼 JavaScript 程式庫，用於在網路上呈現 3D 視覺效果。如要進一步瞭解如何使用 CesiumJS，請參閱「Learn CesiumJS」(瞭解 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 (新版)，擷取更多資訊。您可以使用 Autocomplete 小工具，飛到地點的可視區域。這個範例使用 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 (新版) 和 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 for Unreal

如要搭配使用 Cesium for Unreal 外掛程式和 3D Tiles API，請按照下列步驟操作。

  1. 安裝 Cesium for Unreal 外掛程式。

  2. 建立新的 Unreal 專案。

  3. 連結 Google Photorealistic 3D Tiles API。

    1. 在選單中依序選取「Cesium」 >「Cesium」，開啟 Cesium 視窗。

    2. 選取「Blank 3D Tiles Tileset」。

    3. 在「World Outliner」中，選取這個「Cesium3DTileset」，開啟「Details」面板。

    4. 將「Source」從「From Cesium Ion」變更為「From URL」。

    5. 將網址設為 Google 3D 圖塊網址。

    https://tile.googleapis.com/v1/3dtiles/root.json?key=YOUR_API_KEY
    1. 啟用「在螢幕上顯示製作團隊名單」，即可正確顯示出處。

  4. 系統會載入世界。如要移至任何經緯度，請在「Outliner」面板中選取「CesiumGeoreference」項目，然後在「Details」面板中編輯「Origin Latitude/Longitude/Height」。

使用 Cesium for Unity

如要在 Cesium for Unity 中使用擬真圖塊，請按照下列步驟操作。

  1. 建立新的 Unity 專案。

  2. 在「套件管理工具」部分 (依序點選「編輯者」 >「專案設定」)，新增指定範圍註冊資料庫。

    • 名稱：Cesium

    • 網址：https://unity.pkg.cesium.com

    • 範圍：com.cesium.unity

  3. 安裝 Cesium for Unity 套件。

  4. 連線至 Google Photorealistic 3D Tiles API。

    1. 在選單中依序選取「Cesium」 >「Cesium」，開啟 Cesium 視窗。

    2. 按一下「Blank 3D Tiles Tileset」。

    3. 在左側面板中，依序選取「Source」下方的「Tileset Source」選項，以及「From URL」 (而非「From Cesium Ion」)。

    4. 將網址設為 Google 3D 圖塊網址。

    https://tile.googleapis.com/v1/3dtiles/root.json?key=YOUR_API_KEY
    1. 啟用「在螢幕上顯示製作團隊名單」，即可正確顯示出處。

  5. 系統會載入世界。如要移至任何經緯度，請在「Scene Hierarchy」中選取「CesiumGeoreference」項目，然後在「Inspector」中編輯原點緯度/經度/高度。

使用 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 圖塊幾何圖形上。

在以下範例中，建築物圖層會以多邊形呈現，並根據擬真 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>