Logo
Overview
網頁3D模型讀取:斷線與離線環境應對策略

網頁3D模型讀取:斷線與離線環境應對策略

September 16, 2025
5 min read
index

摘要

隨著 BIM-Based、BIM-supported 的輔助整合工程需求持續增加,使用者對手持設備或行動裝置的操作需求也越來越高,特別是在網路不穩定甚至無網路環境還必須確保對 3D 模型進行有效的交互操作。而這類需求對許多用於內網環境的企業或政府單位也有著絕對的必要性。

在這種情況下該如何有效利用 Autodesk Platform Services 提供的 Viewer 實現模型的離線加載與斷網操作是很關鍵的問題。

  • 施工現場:現場工程師在無網絡環境下檢視建築模型,進行數據查找及註記。
  • 生產線:工程師在網絡不穩定的工廠環境中,需要檢視設備模型與管理維護數據。

概念釐清

首先根據工地場景及使用情境區分為 DisconnectedOffline 兩種,應對的方式皆不相同。

Definition (情境比較)

Offline

  • 表示設備、應用或使用者不依賴網路、當前無法使用網路功能,俗稱內網。
  • 更側重於描述一種運作模式,而非狀態的改變。

Disconnected

  • 表示設備、應用或使用者與某個網路或系統的連接已經中斷。
  • 強調當前沒有連線,可能是因為斷線、網路故障、或刻意關閉。可以重新嘗試連接,可能恢復正常運作。

按照本地模式(Local)、雲端模式(Autodesk Production)進行比較。首先關鍵點在於 AEC 資料及模型來源,其次才是考慮加載速度與快取問題。

功能本地模式雲端模式
資料來源本地文件系統Autodesk 伺服器
Access Token不需要必須配置
連接外部 API不需要必須連接,用於加載 SVF 和資源
資源下載無,直接從本地讀取有,從雲端加載
網路需求無需網路,完全離線運作需要穩定的網路連接
加載速度快速(依賴於本地存取速度)取決於網路頻寬和伺服器響應
Cache 意義無實質意義減少重複下載,提升性能

SVF、SVF2 比較

此文彙整兩者主要差異,更詳細的說明請詳閱 官網

SVF 是 APS(前身為 Forge)Model Derivative API 用來將 3D 模型轉換為可串流檢視格式的標準格式,用於 Viewer SDK 渲染。SVF2 是其優化版本,目的在提升效能和儲存效率。 會有 SVF2 的推進主要是針對大型模型的網格重複問題進行優化,源於對 BIM 360 服務的需求。這部分也可以反映網頁 3D 技術的需求性及必需性逐漸產生。

發展時間線

  • 2015年:SVF 作為 Forge Viewer 的核心格式,從 Autodesk University 2015 開始廣泛使用,用於 BIM 360 和 Forge 服務的模型轉換。SVF 是早期版本,專注於基本 3D 渲染,但隨著模型規模增大,效能瓶頸逐漸顯現。

  • 2019年:Autodesk 在 Forge DevCon 2019 演講中首次提及 「OTG」(Optimized Translation Geometry,後更名 SVF2)的開發概念,目的是處理大型模型的效能問題。

  • 2021年:SVF2 逐步滾動至 BIM 360/ACC 專案(到 2021 年底,70% 專案使用 SVF2),並在 Viewer v7.25+ 中支援。SVF 仍維持用於舊專案或特定格式(如 3ds Max 物理材質)。

  • 2024年:SVF2 做為 Model Derivative API 的預設輸出,支持更多格式(如 RVT、IFC、DWG),並整合到 DiffTool 等其他擴展中。

不同面向差異

面向SVFSVF2差異與影響
格式優化每個物件獨立網格,無跨物件共享優化網格共享(在同一 Viewable 或跨 Viewable 共享相同形狀的網格)SVF2 減少儲存大小加速載入和渲染
效能適合中小型模型適合大型模型(GPU 記憶體使用減少 50%以上)SVF2 在瀏覽器中渲染更快,尤其在 BIM 360/ACC 環境
DbId非持久 ID(修改模型後 ID 可能改變)持久/穩定 ID(未修改物件保持相同 ID),基於外部 ID(如 Revit UniqueID)SVF2 更適合版本比較和外部資料連結,但需映射舊 ID
Property DB使用 SQLite 檔案(model.sdb)易於離線存取無獨立 SQLite 檔案,需透過 API 存取SVF 適合自訂工具;SVF2 依賴 API
支援格式廣泛支援 70+ 格式(如 RVT、IFC、DWG、FBX、3ds Max)主要支援 RVT、IFC、NWD/NWC、DWG、IWMSVF2 逐步擴展,但初期限制多;FBX 等格式轉 SVF2 可能無優化效果
轉換時間較短較長(優化過程複雜)SVF2 適合生產環境,可使用 Webhooks 監控
儲存大小檔案較大(Viewable 獨立)檔案大小大幅減少(共享網格)SVF2 節省雲端儲存成本
相容性Viewer v7.0+ 支援,無需特殊設定需要 Viewer v7.25+SVF2 有 fallback 機制(自動切換至 SVF)

按照不同面向分析 SVF、SVF2 差異,可得出以下結論:

  1. SVF 是 SVF2 的基礎格式,可以從 SVF2 擴展出更多格式(如 RVT、IFC、DWG),並整合到 DiffTool 等其他擴展中。
  2. SVF2 是其優化版本,已然適應於生產環境使用,並且有對應的 API 接口進行整合。
  3. SVF2 可以利用 Webhooks 監控轉換過程減少轉換時間。
  4. SVF2 可以利用 API 存取數據,且有對應的 DbId 機制減少 Property DB 的存取時間。
  5. SVF2 仰賴與雲端交互作用;SVF 可於本地環境自訂工具使用。

回應此文章需求 SVF 相較 SVF2 適合用於斷線與離線環境開發使用,只需要將模型檔案轉換為 SVF 格式即可供 Viewer 載入顯示。 後續內容會說明如何利用 SVF 建立可串流檢視格式的模型,並透過網頁技術驗證內網或極端環境下之應對方式。

URN

統一資源名稱(Uniform Resource Name)一種資源定位符號。

剛開始學習 APS 時最先看到且必填的參數欄位就屬他,但他究竟是什麼?理解後發現指的就是 模型檔案位置,所以其實這段很長的字串內容就是指向 Autodesk 伺服器路徑下的模型位置。

urn
dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6Y2hzYzJ4YTFteTh1enl5a3BpanVlejZxZ2kzb2V4b2p4cGFlaWR0a2EybXBmandiLW1vZGVsL1RDXyVFNSU4RiVCMCVFNSU4QyU5NyVFNyU5RiVCRCVFOCVCMCVCN18lRTQlQk...
const documentId = 'urn:' + modelUrn;
Autodesk.Viewing.Document.load(documentId, _successFunction, _failureFunction);

SVF Model

根據前面章節的說明,可以理解在本地載入的模型是使用 SVF 格式而非 SVF2,以下就針對 SVF 結構做說明。

Proposition (詳細資料)
  1. Load Document

    • manifest.json - 讀取模型資源的主要文件
  2. AEC Data

    • AECModelData.json
  3. Viewer

    • 3D-Main.svf - 3D 模型
    • Sheet.pdf - 2D 圖紙
  4. Property DB

    • model.sdb
    • objects_ids.json.gz
    • objects_attrs.json.gz
    • objects_avs.json.gz
    • objects_vals.json.gz
    • objects_offs.json.gz
    • objects_viewables.json.gz
Folder Structure
📦 Model
│ 📂output
│ ├ 📂Resource
│ │ ├ 📂Coordinate
│ │ │ ├ 📂08f99ae5-b8be-4f8d-881b-128675723c10
│ │ │ │ └ 📂New Construction_638482380449167336
│ │ │ └ 📂3D-Main 2353558
│ │ │ │ ├ 📜3D-Main.svf // 3DViewer
│ │ │ │ ├ ...
│ │ ├ 📂Sheet // 圖紙文件
│ │ │ ├ 📂A-00 - B1F PLAN 16618700
│ │ │ │ └ 📂pdf
│ │ │ │ │ ├ 📜A-00 - B1F PLAN.pdf // 2DViewer
│ │ │ │ │ ├ 📜A-00 - B1F PLAN1.png
│ │ │ │ │ ├ 📜A-00 - B1F PLAN2.png
│ │ │ │ │ └ 📜A-00 - B1F PLAN4.png
│ │ │ ├ ...
│ │ ├ 📜AECModelData.json // AEC Data
│ │ ├ 📜model.sdb // Property DB
│ │ ├ 📜objects_attrs.json.gz
│ │ ├ 📜objects_avs.json.gz
│ │ ├ 📜objects_ids.json.gz
│ │ ├ 📜objects_offs.json.gz
│ │ ├ 📜objects_vals.json.gz
│ │ └ 📜objects_viewables.json.gz
│ ├ 📜preview1.png // 模型縮圖
│ ├ 📜preview2.png
│ └ 📜preview4.png
└ 📜manifest.json // 資源讀取入口

資源配置

index.html
<link rel="stylesheet" href="https://developer.api.autodesk.com/modelderivative/v2/viewers/7.103/style.css" />
<script src="https://developer.api.autodesk.com/modelderivative/v2/viewers/7.103/viewer3D.js"></script>

Service Worker

Service Worker 是一種 JavaScript 腳本,在瀏覽器的背景執行(不直接存取 DOM),主要用於增強 Web 應用程式的離線功能、快取管理和推送通知。 它充當瀏覽器與網路之間的代理(proxy),可攔截 HTTP 請求、快取資源,並在斷網時提供備用回應,從而實現 Progressive Web App (PWA) 的核心功能。

相關配置可參考 Github

Register.js
// 離線模型暫存註冊檔
document.addEventListener('DOMContentLoaded', async function () {
try {
const registration = await navigator.serviceWorker.register('ServiceWorker.js');
console.log('Service worker registered', registration.scope);
} catch (err) {
console.error('Could not register service worker', err);
}
});

載入模型

了解 SVF 模型結構及配置 Service Worker 後,接著將原有雲端 API 載入模型的流程調整為載入本地模型。

Tip (雲端與本地載入模型檔案說明)
  • 原先透過雲端載入模型流程會是取得模型 URN 後載入模型檔案。
  • 本地模型則是直接讀取模型 manifest.json 檔案後加載模型。
ModelViewer.ts
/** 加載 ADSK 雲端模型 */
const documentId = 'urn:' + modelUrn;
Autodesk.Viewing.Document.load(documentId, _successFunction, _failureFunction)
/** 加載本地模型 */
const document = new Autodesk.Viewing.Document(manifest, manifestPath, '')
ModelViewer.ts
/** 下載本地模型檔案 */
async loadSVFModelDocument(type: '3D' | '2D'): Promise<void> {
// 1. 本地模型 manifest.json 檔案路徑
const manifestPath = "";
// 2. fetch json 內容
const resp = await fetch(manifestPath, { method: 'GET' });
if (!resp.ok) throw new Error(await resp.text());
const manifest = await resp.json();
// 3. 加載本地模型
const document = new Autodesk.Viewing.Document(manifest, manifestPath, '');
const viewerConfigs = {
'3D': {
viewerName: this.viewerName,
successHandler:
(doc: Autodesk.Viewing.Document) => this.onDocumentLoadSuccess_3D(this, doc),
backgroundColor: this.bgColor_3D,
},
'2D': {
viewerName: this.drawingName,
successHandler:
(doc: Autodesk.Viewing.Document) => this.onDocumentLoadSuccess_2D(this, doc),
backgroundColor: this.bgColor_2D,
},
};
const config = viewerConfigs[type];
if (!config) return;
config.successHandler(document);
}

顯示設定

優先初始化顯示模型 viewer.start() 後,接著操作模型顯示設定。此文操作會針對幾何邊緣、滑鼠操作及背景等顯示進行設定,若有其他需求可以在參考 Viewer3D 調整。

ModelViewer.ts
const viewer = new Autodesk.Viewing.GuiViewer3D(htmlDiv);
// 1. start(3D.svf) 優先初始化先顯示模型,可是會造成後續的設定流失
const startedCode = viewer.start();
// 2. 模型顯示/操作設定,使用本地模型需要手動配置
// 模型幾何邊緣
viewer.setDisplayEdges(true);
// 滑鼠縮放反向
viewer.setReverseZoomDirection(true);
// 背景設定
viewer.setLightPreset(18);

Setting

Setting

多聚合模型操作

若本身模型包含多階段模型經操作若載入本地模型會變更為多聚合模型,所以會需要直接指定第幾個模型要載入(預設為第一個模型)。

ModelViewer.ts
// 取得所有視圖模型 viewer models
const models = viewer_3D.getAllModels();
// 顯示所有淡化物件
models.map((model: any) => {
viewer.showAll(model);
});
// 將符合樓層的物件開啟顯示
viewer_3D.impl.visibilityManager.setNodeOff(parseInt(dbId), false, models[1]);

總結

透過本地環境取代雲端 API 服務可以盡可能滿足於不同網路環境下的需求,但還是有部分問題需要克服:

  1. SVF 轉檔時間較 SVF2 長。

  2. 模型量體過大會導致效能下降。

  3. 需要特別針對 SVF 模型的匯出下載作業進行工具開發。

  4. 若有針對 DbId 進行整合應用,改為本地模型後會出現問題(尤其於更換模型時)。

  5. 本地環境無法享受 API 服務及 OPFS Caching 優化技術。

  6. 使用本地環境自訂複雜性高的功能較困難。

雖說如此,但面對不同網路環境下的需求無非只是需要 可顯示 3D 2D部分的操作模型紀錄與模型相關的操作內容 等,恢復連線後就可以切換為雲端服務進行使用。 倘若是應對內網需求也是有更深入的解決方法,可以再參考 Autodesk Platform Services 提供的 Viewer 實現模型的離線加載與斷網操作。


參考資料

相關資訊

  1. Show local model
  2. Property pipeline
  3. Properties DB
  4. SVF extractor

延伸文章

  1. SVF/SVF2 Survey, Autodesk
  2. SVF2 Public Beta: a new optimized viewer format, Autodesk
  3. SVF2 GA is now production ready, Autodesk
  4. Compute differences of model versions with DiffTool extension of APS Viewer, Autodesk
  5. Implement retry, custom query string and more for Viewer with Service Worker, Autodesk