博客 / 詳情

返回

JSAPI Three 是什麼？—— 百度地圖二三維一體化渲染引擎入門指南

如果你正在尋找一個既能實現傳統地圖的二維功能，又能無縫融合三維渲染能力的解決方案，或者對"JSAPI Three"、"mapvthree"這些名詞感到困惑，那麼這篇文章就是為你準備的。我們將用最通俗易懂的方式，幫你理解這個突破傳統地圖引擎侷限的二三維一體化渲染引擎。

一、JSAPI Three 是什麼？

1.1 簡單理解

JSAPI Three 是百度地圖推出的二三維一體化地圖渲染引擎，它的全稱是"百度地圖 JavaScript API Three"。

想象一下：

  • 傳統地圖（如 JSAPI 2D）：是平面的，就像一張紙上的地圖，只能顯示二維信息
  • JSAPI GL：是 2.5D 的，可以旋轉和傾斜，但仍然是平面的，無法加載真正的三維模型
  • JSAPI Three：是二三維一體化的，既能像傳統地圖一樣顯示二維信息，又能無縫切換到三維模式，加載三維模型、地形等，就像遊戲裏的 3D 地圖

關鍵區別：

  • 傳統地圖引擎：要麼只能做二維，要麼只能做三維，需要切換不同的引擎
  • JSAPI Three：一個引擎同時支持二維和三維，可以在同一場景中無縫融合

1.2 核心定位

JSAPI Three 是一個Web 端二三維一體化渲染引擎，主要目標是：

實現二三維一體化，讓地圖既好用又好看。在保留傳統地圖所有功能的基礎上，無縫融合三維渲染能力，讓二維地圖數據和三維模型可以在同一場景中自然融合。

核心價值：

  • 既好用：完全保留傳統地圖的所有功能（標註、覆蓋物、路徑規劃、地點搜索等），開發者可以像使用傳統地圖一樣使用
  • 又好看：無縫融合三維渲染能力（三維模型、地形、特效、光照等），讓地圖展示更加生動和直觀
  • 二三維一體化：二維和三維可以在同一場景中自然切換和融合，無需切換引擎，一個引擎搞定所有需求
  • 無縫融合：二維地圖數據和三維模型可以在同一場景中同時展示，支持一鍵切換投影方式

應用場景：

  • 數字孿生場景：將現實世界（如城市、園區、交通系統）在數字空間中完整復刻
  • 二三維混合展示：同一場景中既有二維地圖數據，又有三維模型和特效
  • 漸進式升級：在現有二維地圖項目基礎上，逐步引入三維能力

1.3 技術特點

  • 基於 Three.js：使用業界成熟的 Three.js 作為底層渲染引擎
  • 二三維一體化：在同一個引擎中，既可以像傳統地圖一樣使用二維功能，也可以無縫切換到三維渲染
  • 無縫融合：二維地圖數據和三維模型可以在同一場景中自然融合，支持一鍵切換投影方式
  • WebGL 渲染：利用 GPU 加速，性能強大
  • 開箱即用：提供豐富的可視化組件和功能模塊，同時保留傳統地圖的所有能力

二、JSAPI Three 和 mapvthree 的關係

這是很多初學者最困惑的地方，讓我們來理清楚：

2.1 名稱關係

JSAPI Three（產品名稱）
    ↓
mapvthree（npm 包名）
    ↓
@baidumap/mapv-three（完整包名）

簡單來説：

  • JSAPI Three：這是百度地圖官方給這個產品的正式名稱
  • mapvthree：這是 npm 包中的命名空間（代碼裏使用的名字）
  • @baidumap/mapv-three：這是 npm 包的完整包名（安裝時使用的名字）

2.2 使用中的體現

在文檔和宣傳中：

  • 通常使用"JSAPI Three"這個正式名稱
  • 強調這是百度地圖的產品

在代碼中：

  • 使用 mapvthree 作為命名空間
  • 例如：import * as mapvthree from '@baidumap/mapv-three'
  • 然後使用：new mapvthree.Engine()

類比理解：

  • 就像"微信"是產品名，"WeChat"是英文名，"weixin"可能是內部代號
  • 它們指向同一個東西，只是在不同場景使用不同的稱呼

2.3 為什麼有兩個名字？

  1. JSAPI Three：符合百度地圖 API 系列的命名規範（JSAPI、JSAPI GL 等）
  2. mapvthree：更簡潔，適合在代碼中使用，也便於記憶

三、JSAPI Three 能做什麼？

3.1 核心能力

1. 二三維地圖渲染

// 可以顯示多種地圖底圖
- 百度矢量地圖
- 衞星影像
- 地形 DEM
- 3D Tiles（傾斜攝影）
- 其他標準地圖服務（WMS、WMTS、MVT 等）

2. 數據可視化

// 支持多種數據格式和可視化方式
- 點數據：散點圖、氣泡圖、圖標、標籤、熱力圖
- 線數據：路徑圖、遷徙飛線
- 面數據：多邊形、網格、牆體
- 三維模型：GLTF/GLB、OBJ、FBX 等

3. 三維場景構建

// 可以創建豐富的三維場景
- 加載三維建築模型
- 添加地形起伏
- 設置天空和天氣效果
- 模擬光照和陰影

4. GIS 分析功能

// 內置多種空間分析能力
- 坡度分析
- 可視域分析
- 通視分析
- 淹沒分析
- 體積分析

3.2 典型應用場景

智慧城市

  • 城市三維可視化
  • 城市規劃展示
  • 城市數據大屏

智慧園區

  • 園區三維展示
  • 設備資產管理
  • 安防監控可視化

交通數字孿生

  • 實時車流可視化
  • 交通信號燈管理
  • 路況分析

房地產

  • 樓盤三維展示
  • 虛擬看房
  • 周邊環境展示

四、目標受眾

4.1 主要受眾

前端開發者

  • 有地圖開發需求：需要在項目中集成地圖功能
  • 需要三維可視化：不滿足於傳統二維地圖，需要更豐富的視覺效果
  • 數字孿生項目：參與智慧城市、智慧園區等數字孿生項目

GIS 開發者

  • Web GIS 應用開發：需要將 GIS 數據在 Web 端三維展示
  • 空間分析需求：需要進行三維空間分析

產品/項目經理

  • 技術選型：為項目選擇合適的地圖渲染方案
  • 需求評估：評估項目是否需要三維地圖能力

4.2 技術背景要求

必需技能

  • [√] JavaScript 基礎：熟悉 ES6+ 語法
  • [√] 前端開發基礎：瞭解 HTML、CSS、DOM 操作
  • [√] npm/包管理：能夠使用 npm 安裝和管理依賴

加分技能（非必需）

  • Three.js 基礎：瞭解 Three.js 的基本概念會更容易上手
  • WebGL 知識：瞭解 WebGL 有助於理解渲染原理
  • GIS 基礎：瞭解地理座標系、投影等概念

不需要的技能

  • [×] 不需要精通 Three.js：JSAPI Three 已經封裝好了，可以直接使用
  • [×] 不需要深入瞭解 WebGL：引擎已經處理了底層細節
  • [×] 不需要GIS 專業知識：基礎的地理座標概念即可

4.3 適合的項目類型

適合使用 JSAPI Three 的項目

  1. 數字孿生項目

    • 智慧城市可視化平台
    • 智慧園區管理系統
    • 交通數字孿生系統

  2. 三維數據展示

    • 需要加載三維模型（建築、設備等）
    • 需要展示地形起伏
    • 需要三維空間分析

  3. 沉浸式體驗

    • 虛擬旅遊
    • 房地產展示
    • 遊戲化地圖應用

  4. 數據可視化大屏

    • 需要結合地圖的數據大屏
    • 需要三維效果的數據展示

不適合使用 JSAPI Three 的項目

  1. 簡單的 LBS 應用

    • 只需要顯示位置、路徑規劃
    • 不需要三維效果
    • 建議使用 JSAPI 2D 或 JSAPI GL

  2. 對性能要求極高的場景

    • 需要在低端設備上運行
    • 對包體積有嚴格限制
    • 可以考慮更輕量的方案

  3. 團隊技術棧限制

    • 團隊完全不熟悉 Three.js
    • 無法接受學習成本
    • 可以考慮更簡單的方案

五、JSAPI Three 的設計目標

5.1 核心目標

1. 實現二三維一體化，讓地圖既好用又好看

傳統地圖引擎的侷限：

  • JSAPI 2D：功能完整（好用），但只能顯示二維地圖，視覺效果有限（不夠好看）
  • JSAPI GL：支持 2.5D 視角（稍微好看），但無法加載三維模型，功能相對有限
  • 其他三維引擎：視覺效果出色（好看），但缺乏傳統地圖的二維能力（不夠好用）

JSAPI Three 的突破：

  • [√] 既好用：完整保留傳統地圖引擎的所有功能（標註、覆蓋物、路徑規劃、地點搜索等），開發者可以像使用傳統地圖一樣使用
  • [√] 又好看：無縫融合三維渲染能力（三維模型、地形、特效、光照等），讓地圖展示更加生動和直觀
  • [√] 二三維一體化：二維和三維可以在同一場景中自然融合，支持一鍵切換投影方式，一個引擎搞定所有需求
  • [√] 漸進式升級：可以在現有二維地圖項目基礎上，逐步引入三維能力，無需重寫代碼，讓地圖從"好用"升級到"既好用又好看"
// 同一個引擎，既可以做二維
const engine = new mapvthree.Engine(container, {
    map: {
        projection: 'EPSG:3857',  // 二維投影
        // 可以使用所有傳統地圖功能
    },
});

// 也可以無縫切換到三維
engine.map.setProjection('ECEF');  // 三維投影
engine.map.setPitch(75);  // 設置俯視角度
// 可以加載三維模型、地形等

2. 降低三維地圖開發門檻

傳統方式的問題：

  • 需要深入瞭解 Three.js
  • 需要處理複雜的地理座標轉換
  • 需要自己實現地圖投影
  • 需要處理大量底層細節
  • 二維和三維需要分別使用不同的引擎

JSAPI Three 的解決方案：

// 傳統方式可能需要數百行代碼，還需要切換引擎
// JSAPI Three 只需要幾行，一個引擎搞定
const engine = new mapvthree.Engine(container);
engine.map.setPitch(75);  // 設置俯視角度，從二維切換到三維視角

3. 提供開箱即用的功能

內置功能模塊：

  • [√] 好用功能：地圖底圖、標註、覆蓋物、路徑規劃、地點搜索等（傳統地圖能力，讓地圖好用）
  • [√] 好看功能：三維模型、地形、天空系統、天氣特效、光照陰影等（三維渲染能力，讓地圖好看）
  • [√] 可視化組件：點、線、面等，支持二維和三維兩種模式，既實用又美觀
  • [√] GIS 分析功能：坡度分析、可視域分析等三維空間分析，功能強大且直觀

4. 支持現代前端開發流程

特點：

  • [√] 通過 npm 安裝（本地包形式）
  • [√] 支持 ES6+ 模塊化
  • [√] 支持 TypeScript（通過類型定義）
  • [√] 與現代前端框架（React、Vue）良好集成

5.2 設計理念

1. 漸進式學習

學習路徑：

基礎使用（簡單配置）
    ↓
添加可視化組件（數據展示）
    ↓
加載三維模型（場景構建）
    ↓
使用 GIS 分析（高級功能）
    ↓
自定義擴展（Three.js 原生能力）

2. 二三維無縫切換

靈活切換投影和視角：

  • 二維模式：使用傳統地圖的二維投影，適合傳統地圖應用
  • 三維模式：切換到三維投影，支持任意角度和三維模型
  • 一鍵切換：可以在運行時動態切換，無需重新初始化
// 二維模式（傳統地圖）
const engine = new mapvthree.Engine(container, {
    map: {
        projection: 'EPSG:3857',  // 二維投影
        pitch: 0,  // 水平視角
    },
});

// 切換到三維模式
engine.map.setProjection('ECEF');  // 三維投影
engine.map.setPitch(75);  // 俯視角度

// 也可以直接使用 Three.js 原生能力
const mesh = new THREE.Mesh(geometry, material);
engine.add(mesh);

3. 性能優先

優化策略：

  • GPU 加速渲染
  • 實例化渲染（大量相同對象）
  • LOD（細節層次，根據距離調整細節）
  • 3D Tiles 支持（高效加載大規模場景）

六、快速開始示例

6.1 最簡單的例子

<!DOCTYPE html>
<html>
<head>
    <title>JSAPI Three 示例</title>
    <script>
        window.MAPV_BASE_URL = 'mapvthree/';
    </script>
</head>
<body>
    <div id="container" style="width: 100%; height: 500px;"></div>
    
    <script type="module">
        import * as mapvthree from '@baidumap/mapv-three';
        
        // 配置百度地圖 AK
        mapvthree.BaiduMapConfig.ak = '您的AK密鑰';
        
        // 創建引擎
        const container = document.getElementById('container');
        const engine = new mapvthree.Engine(container, {
            map: {
                center: [116.404, 39.915],  // 北京天安門
                pitch: 60,                   // 俯視角度
                range: 1000,                 // 高度 1000 米
            },
        });
    </script>
</body>
</html>

運行效果：

  • 顯示一個三維地圖
  • 可以鼠標拖動旋轉
  • 可以滾輪縮放
  • 默認有天空效果

6.2 添加數據可視化

// 準備數據
const dataSource = new mapvthree.GeoJSONDataSource.fromGeoJSON({
    type: 'FeatureCollection',
    features: [
        {
            type: 'Feature',
            geometry: {
                type: 'Point',
                coordinates: [116.404, 39.915],
            },
        },
    ],
});

// 添加可視化組件
const point = engine.add(new mapvthree.SimplePoint({
    size: 20,
    color: '#ff0000',
}));
point.dataSource = dataSource;

七、常見問題

Q1: JSAPI Three 和 JSAPI GL 有什麼區別？

簡單回答：

  • JSAPI GL：2.5D 地圖，支持旋轉和傾斜，但無法實現真正的三維場景，也無法加載三維模型
  • JSAPI Three：二三維一體化引擎，既能實現傳統地圖的二維功能，又能無縫融合三維渲染能力

詳細對比：

  • 二維能力：JSAPI Three 完全保留傳統地圖的二維功能，JSAPI GL 也支持但功能相對有限
  • 三維能力：JSAPI GL 的 tilt（傾斜角度）最大約 75 度，無法加載三維模型；JSAPI Three 的 pitch（俯仰角）可以任意角度，支持加載三維模型、地形等
  • 二三維融合：JSAPI Three 支持在同一個場景中融合二維地圖數據和三維模型，支持一鍵切換投影方式；JSAPI GL 無法實現真正的二三維融合
  • 升級路徑：如果現有項目使用 JSAPI GL，可以平滑升級到 JSAPI Three，保留原有功能的同時獲得三維能力

Q2: 需要學習 Three.js 嗎？

不需要深入學習，但瞭解基礎概念有幫助：

必須瞭解：

  • 場景（Scene）、相機（Camera）、渲染器（Renderer）的基本概念
  • 這些 JSAPI Three 已經封裝好了，不需要直接操作

有幫助但不必須：

  • Three.js 的幾何體、材質、網格等概念
  • 瞭解這些可以更好地使用 JSAPI Three 的高級功能

完全不需要：

  • WebGL 的底層 API
  • 着色器編程
  • 複雜的數學計算

Q3: 性能如何？

優勢：

  • 基於 WebGL，GPU 加速
  • 支持實例化渲染，可以渲染大量對象
  • 支持 LOD，自動優化性能

限制：

  • 需要支持 WebGL 的瀏覽器
  • 低端設備可能性能有限
  • 大規模場景需要合理優化

Q4: 可以離線使用嗎？

可以：

  • JSAPI Three 通過 npm 安裝，是本地包
  • 地圖底圖可以配置為離線資源
  • 不依賴在線服務（除了地圖數據）

Q5: 支持哪些瀏覽器？

支持現代瀏覽器：

  • Chrome/Edge（推薦）
  • Firefox
  • Safari
  • 需要支持 WebGL

不支持：

  • IE 瀏覽器
  • 不支持 WebGL 的舊版瀏覽器

八、總結

8.1 核心要點

  1. JSAPI Three 是百度地圖的二三維一體化渲染引擎
  2. mapvthree 是代碼中使用的命名空間，指向同一個產品
  3. 核心目標是實現二三維一體化，讓地圖既好用又好看
  4. 核心價值是在保留傳統地圖所有功能的基礎上，無縫融合三維渲染能力
  5. 既好用：完整保留傳統地圖的所有功能，開發者可以像使用傳統地圖一樣使用
  6. 又好看：無縫融合三維渲染能力，讓地圖展示更加生動和直觀
  7. 適合需要二三維混合展示或從二維升級到三維的項目
  8. 學習成本相對較低，不需要深入 Three.js，傳統地圖開發者可以快速上手

8.2 選擇建議

選擇 JSAPI Three 如果：

  • [√] 需要二三維混合展示（既有二維地圖功能，又有三維渲染）
  • [√] 需要從現有二維地圖項目升級到三維
  • [√] 需要真正的三維地圖展示和三維模型加載
  • [√] 需要三維空間分析
  • [√] 項目是數字孿生相關，需要二三維一體化能力

選擇其他方案如果：

  • [×] 只需要簡單的 LBS 功能，完全不需要三維（考慮 JSAPI 2D）
  • [×] 只需要 2.5D 效果，不需要真正的三維模型（考慮 JSAPI GL）
  • [×] 對性能要求極高且場景簡單，不需要二三維融合

8.3 下一步

如果你對 JSAPI Three 感興趣，建議：

  1. 閲讀官方文檔：JSAPI Three 官方文檔
  2. 查看示例代碼：在文檔中查看各種功能的示例
  3. 動手實踐：按照文檔創建第一個三維地圖
  4. 加入社區：遇到問題可以在社區尋求幫助

參考資源：

  • JSAPI Three 官方文檔
  • mapvthree NPM 包
  • Three.js 官方文檔
  • 百度地圖開放平台
three.js , 百度地圖 , 前端
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.