概述
3D Tiles 工具是一組用于轉換、優化、處理和分析 3D Tiles 數據的工具和實用程序。
安裝
要在本地目錄中安裝 3D Tiles 工具，請運行以下命令：
npm install 3d-tiles-tools
如果想直接使用 Git 倉庫的克隆版本，請參閱開發者設置。
命令行用法
注意： 所有 3D Tiles 工具的輸入和輸出路徑都是_區分大小寫_的。即使某些操作系統（如 Windows）通常不區分大小寫，命令行中提供的文件名和目錄名也必須與實際名稱完全匹配。
每個功能的通用命令行選項：
| 標志 | 描述 | 是否必需 |
|---|---|---|
-i, --input | 輸入文件或目錄 | 是 |
-o, --output | 輸出文件或目錄 | 是 |
-f, --force | 如果輸出已存在，則覆蓋 | 否，默認為 false |
--logLevel | 日志級別。有效值為 trace、debug、info、warn、error、fatal 和 silent | 否，默認為 info |
--logJson | 將日志消息打印為 JSON 而不是美化格式 | 否，默認為 false |
瓦片集的命令行工具
gzip
對輸入的瓦片集進行 Gzip 壓縮。
npx 3d-tiles-tools gzip -i ./specs/data/TilesetOfTilesets/ -o ./output/TilesetOfTilesets-gzipped/
附加命令行選項：
| 標志 | 描述 | 是否必需 |
|---|---|---|
-t, --tilesOnly | 僅壓縮瓦片 | 否，默認為 false |
（注意：使用 tilesOnly 的確切文件集尚未指定）
ungzip
解壓輸入的瓦片集。
npx 3d-tiles-tools ungzip -i ./specs/data/TilesetOfTilesets-gzipped/ -o ./output/TilesetOfTilesets-ungzipped/
combine
將所有外部瓦片集合并為一個單一瓦片集。
注意 關于
merge和combine的區別：combine命令接受一個已經引用了_外部_瓦片集的瓦片集，并創建一個新的瓦片集，其中原來的_外部_瓦片集被“內聯”。結果是一個沒有外部引用的單一瓦片集。
示例：
npx 3d-tiles-tools combine -i ./specs/data/combineTilesets/input -o ./specs/data/combineTilesets/output
merge
將多個瓦片集合并為一個，該瓦片集將輸入的瓦片集作為外部瓦片集引用。
注意 關于
merge和combine的區別：merge命令創建一個_新_瓦片集，該瓦片集將給定的瓦片集作為_外部_瓦片集引用。這意味著生成的瓦片集在沒有那些作為merge命令輸入的瓦片集時是不完整的。
示例：
npx 3d-tiles-tools merge -i ./specs/data/mergeTilesets/TilesetA -i ./specs/data/mergeTilesets/sub/TilesetA -o ./specs/data/mergeTilesets/output
mergeJson
將多個瓦片集合并為一個單一瓦片集 JSON 文件，該文件將輸入的瓦片集作為外部瓦片集引用。
這與 merge 命令的不同之處在于它不會將輸入瓦片集復制到輸出目錄，而只是創建合并瓦片集的 JSON 文件，該文件使用相對路徑引用輸入瓦片集。常見的用例是在某個目錄中創建瓦片集 JSON 文件，而輸入瓦片集位于子目錄中。
示例：
npx 3d-tiles-tools mergeJson -i ./example/TilesetA/tileset.json -i ./example/TilesetB/tileset.json -o ./example/mergedTileset.json
upgrade
將瓦片集升級到最新的 3D Tiles 版本。
npx 3d-tiles-tools upgrade -i ./specs/data/TilesetOfTilesets/tileset.json -o ./output/upgraded
附加命令行選項：
| 標志 | 描述 | 是否必需 |
|---|---|---|
--targetVersion | 要升級到的目標版本。可以是 1.0 或 1.1 | 否，默認為 1.0 |
--options | 所有在此標志之后的參數都會被 gltf-pipeline 使用 | 否 |
默認情況下，這會將舊版瓦片集升級以符合 3D Tiles 1.0 規范。
這些升級包括：
- 資產版本將設置為
'1.0'。 - 使用
url的瓦片內容將升級為使用uri。 refine值將轉換為全大寫。- B3DM 或 I3DM 中的 glTF 1.0 模型將升級為 glTF 2.0。
實現說明：
內部，glTF 1.0 資產轉換為 glTF 2.0 資產是通過使用
gltf-pipeline處理 GLB 數據來完成的。這將包括嘗試將使用KHR_technique_webgl擴展的材質轉換為 PBR 材質。在--options參數之后給出的選項將傳遞給gltf-pipeline。這些選項可能包括應指示特定紋理是否應作為 PRB 材質的基礎顏色紋理的統一變量名稱。例如，當瓦片集中包含帶KHR_technique_webgl擴展的 B3DM 或 I3DM 數據，且統一變量名稱u_diff_tex和u_diffuse表明某個紋理應為基礎顏色紋理時，可以使用以下命令行：npx 3d-tiles-tools upgrade -i ./input/tileset.json -o ./output/tileset.json --options --baseColorTextureNames u_diff_tex --baseColorTextureNames u_diffuse
當指定了 --targetVersion 1.1 時，這將把舊版瓦片集升級以符合 3D Tiles 1.1 規范，_包括_嘗試將 PNTS、B3DM 和 I3DM 瓦片內容轉換為 glTF 資產。升級內容還包括：
- 資產版本將設置為
'1.1'。 - 使用
url的瓦片內容將升級為使用uri。 refine值將轉換為全大寫。- B3DM 或 I3DM 中的 glTF 1.0 模型將升級為 glTF 2.0。
3DTILES_content_gltf擴展聲明將被移除。- PNTS、B3DM、I3DM 和 CMPT 內容將被轉換為 glTF。
實現說明：
將舊版瓦片格式轉換為 glTF 應被視為_預覽功能_。在某些極端情況下，這種轉換不可能通用地完成——例如，當 I3DM 瓦片內容包含帶有動畫的 glTF 數據，或當 CMPT（間接）包含多個已經使用
EXT_structural_metadata擴展的 glTF 資產時。未來可能會更明確地指定轉換可能的條件。
convert
（此命令替代了 databaseToTileset 和 tilesetToDatabase 命令）
在瓦片集和瓦片集包格式之間進行轉換。
npx 3d-tiles-tools convert -i ./specs/data/TilesetOfTilesets/tileset.json -o ./output/TilesetOfTilesets.3tz
附加命令行選項：
| 標志 | 描述 | 是否必需 |
|---|---|---|
--inputTilesetJsonFileName | 應被視為頂級瓦片集 JSON 文件的輸入文件名 | 否 |
此命令的輸入和輸出參數可以是：
- 包含
tileset.json文件的目錄名稱（或完整路徑至瓦片集 JSON 文件） .3tz文件名.3dtiles文件名
輸入也可以是包含 tileset.json 文件的 .zip 文件。
當輸入是包含多個瓦片集 JSON 文件的 .zip 文件或目錄，且其中沒有任何文件名為 tileset.json 時，可以使用 --inputTilesetJsonFileName 參數定義哪個 JSON 文件應被視為頂級瓦片集 JSON 文件。例如，當有一個包含兩個 JSON 文件 tilesetA.json 和 tilesetB.json 的 ambiguous.zip 文件時，可以使用以下命令指定 tilesetA.json 為頂級瓦片集 JSON 文件：
npx 3d-tiles-tools convert -i ./specs/data/convert/ambiguous.zip -o ./output/ambiguous.3tz --inputTilesetJsonFileName tilesetA.json
databaseToTileset
已棄用。此功能現在通過 convert 命令提供。
tilesetToDatabase
已棄用。此功能現在通過 convert 命令提供。
瓦片內容的命令行工具
glbToB3dm
從 glb 創建一個帶有空批次表的 b3dm。
npx 3d-tiles-tools glbToB3dm -i ./specs/data/CesiumTexturedBox/CesiumTexturedBox.glb -o ./output/CesiumTexturedBox.b3dm
glbToI3dm
從 glb 創建一個帶有單個實例（位置 [0, 0, 0]）和空批次表的 i3dm。
npx 3d-tiles-tools glbToI3dm -i ./specs/data/CesiumTexturedBox/CesiumTexturedBox.glb -o ./output/CesiumTexturedBox.i3dm
b3dmToGlb
從 b3dm 提取 glb。
npx 3d-tiles-tools b3dmToGlb -i ./specs/data/batchedWithBatchTableBinary.b3dm -o ./output/extracted.glb
i3dmToGlb
從 i3dm 提取 glb。
npx 3d-tiles-tools i3dmToGlb -i ./specs/data/instancedWithBatchTableBinary.i3dm -o ./output/extracted.glb
cmptToGlb
從 cmpt 瓦片提取 glb 模型。如果找到多個模型，將在輸出文件名后追加數字。
npx 3d-tiles-tools cmptToGlb -i ./specs/data/composite.cmpt -o ./output/extracted.glb
splitCmpt
將 cmpt 瓦片拆分為其內部瓦片。每個內部瓦片的輸出文件名將通過在給定輸出文件名后追加數字和取決于內部瓦片數據類型的擴展名來確定。
npx 3d-tiles-tools splitCmpt -i ./specs/data/compositeOfComposite.cmpt -o ./output/inner --recursive
對于包含一個復合瓦片的 compositeOfComposite.cmpt 輸入文件，該復合瓦片包含一個 B3DM 和一個 I3DM 內容，這將在輸出目錄中生成文件 inner_0.b3dm 和 inner_1.i3dm。
附加命令行選項：
| 標志 | 描述 | 是否必需 |
|---|---|---|
--recursive | 是否應對內部復合瓦片遞歸執行拆分操作 | 否，默認為 false |
convertB3dmToGlb
將 b3dm 文件轉換為使用 glTF 擴展表示批次和特性表信息的 glTF 資產。
npx 3d-tiles-tools convertB3dmToGlb -i ./data/example.b3dm -o ./data/example.glb
convertPntsToGlb
將 pnts 文件轉換為使用 glTF 擴展表示點屬性及批次和特性表信息的 glTF 資產。
npx 3d-tiles-tools convertPntsToGlb -i ./data/example.pnts -o ./data/example.glb
convertI3dmToGlb
將 i3dm 文件轉換為使用 glTF 擴展表示批次和特性表信息的 glTF 資產。如果輸入 i3dm 的 GLB 包含動畫，此轉換可能是有損的。
npx 3d-tiles-tools convertI3dmToGlb -i ./data/example.i3dm -o ./data/example.glb
optimizeB3dm
使用 gltf-pipeline 優化 b3dm。
npx 3d-tiles-tools optimizeB3dm -i ./specs/data/batchedWithBatchTableBinary.b3dm -o ./output/optimized.b3dm
附加命令行選項：
| 標志 | 描述 | 是否必需 |
|---|---|---|
--options | 此標志后的所有參數都將由 gltf-pipeline 使用 | 否 |
示例：
要使用 Draco 壓縮，傳遞 draco 標志
npx 3d-tiles-tools optimizeB3dm -i ./specs/data/Textured/batchedTextured.b3dm -o ./output/optimized.b3dm --options --draco.compressMeshes --draco.compressionLevel=9
此示例優化了 b3dm 并使用 Draco 高壓縮級別壓縮網格。
optimizeI3dm
使用 gltf-pipeline 優化 i3dm。
npx 3d-tiles-tools optimizeI3dm -i ./specs/data/instancedWithBatchTableBinary.i3dm -o ./output/optimized.i3dm
有關更多示例，請參見 optimizeB3dm。
updateAlignment
更新 B3DM、I3DM、PNTS 或 CMPT 文件以確保批次和特性表以及整個瓦片數據的對齊要求得到滿足。對于 CMPT 瓦片數據，將遞歸更新內部瓦片的數據。
npx 3d-tiles-tools updateAlignment -i ./specs/data/updateAlignment/testComposite.cmpt -o ./output/testCompositeFixed.cmpt
analyze
分析輸入文件，并將結果寫入輸出目錄。
npx 3d-tiles-tools analyze -i ./specs/data/batchedWithBatchTableBinary.b3dm -o ./output/analyzed/
這將接受 B3DM、I3DM、PNTS、CMPT 和 GLB 文件（無論是 glTF 1.0 還是 glTF 2.0），并在輸出目錄中寫入包含特性表、批次表、布局信息、GLB 和 GLB JSON 的文件。這主要用于調試和分析瓦片數據。因此，生成的輸出文件的確切命名和內容未指定。
createTilesetJson
從給定的一組瓦片內容文件創建瓦片集 JSON 文件。
附加命令行選項：
| 標志 | 描述 | 是否必需 |
|---|---|---|
--cartographicPositionDegrees | 一個包含兩個或三個值的數組，分別是目標位置的（經度，緯度）或（經度，緯度，高度）。經度和緯度以度為單位給出，高度以米為單位給出。 | 否 |
如果輸入是單個文件，則結果將是具有該輸入文件作為瓦片內容的單個（根）瓦片。如果輸入是目錄，則該目錄中的所有內容文件將作為瓦片內容遞歸使用。被視為“瓦片內容”的確切文件類型集未指定，但將包括 GLB、B3DM、PNTS、I3DM 和 CMPT 文件。
示例：
npx 3d-tiles-tools createTilesetJson -i ./input/ -o ./output/tileset.json --cartographicPositionDegrees -75.152 39.94 10
這將創建指定的瓦片集 JSON 文件，該文件將引用給定輸入目錄中的所有瓦片內容文件作為其瓦片內容。瓦片集的根節點將具有一個變換，將其放置在給定的地心坐標位置上。
流水線
執行在 JSON 文件中描述的操作序列。
注意： 流水線執行功能是初步的。流水線定義的許多方面，包括 JSON 表示形式和流水線中支持的操作的確切集合，可能會在未來版本中發生變化。
流水線 JSON 文件的基本結構總結如下：
- 流水線具有一個
input和output，它們是瓦片集目錄或包的名稱 - 流水線具有一個“瓦片集階段”數組
- 瓦片集階段具有一個
name和description - 瓦片集階段可以攜帶關于其應用內容類型的信息
- 瓦片集階段具有一個“內容階段”數組
- 內容階段具有一個
name和description
一個簡單的示例流水線可能如下所示：
{"input": "./specs/data/TilesetOfTilesetsWithUris","output": "./output/TilesetOfTilesetsWithUris.3tz","tilesetStages": [{"name": "_b3dmToGlb","description": "將 B3DM 轉換為 GLB","contentStages": [{"name": "b3dmToGlb","description": "將每個 B3DM 內容轉換為 GLB"}]}]
}
瓦片集階段或內容階段的 name 可以引用一組預定義的操作，這些操作可以執行。如果 name 不是已知操作之一，它應以 _ 下劃線開頭。
瓦片集階段或內容階段的 description 旨在作為人類可讀的摘要，用作日志輸出。
預定義的操作大致對應于命令行功能。
已知的瓦片集階段包括：
- 修改：
upgrade：將輸入瓦片集升級到最新版本。關于這意味著什么的詳細信息在此省略。combine：合并輸入瓦片集的所有外部瓦片集，以創建一個單一瓦片集
- 壓縮：
gzip：對所有文件應用 GZIP 壓縮（可選過濾器）ungzip：解壓所有使用 GZIP 壓縮的文件
已知的內容階段包括：
-
轉換：
glbToB3dm：將所有 GLB 瓦片內容轉換為 B3DMglbToI3dm：將所有 GLB 瓦片內容轉換為 I3DM（GLB 作為唯一實例）b3dmToGlb：將所有 B3DM 瓦片內容轉換為 GLB（假設 B3DM 僅是 GLB 的包裝器）i3dmToGlb：將所有 I3DM 瓦片內容轉換為 GLB（假設 I3DM 僅是 GLB 的包裝器）separateGltf：將所有 GLB 瓦片內容轉換為帶有外部資源的.gltf文件
-
優化：
這些操作接收一個
options對象，這是一個未經類型化的對象，攜帶傳遞給gltf-pipeline用于優化的選項。optimizeGlb：使用gltf-pipeline優化 GLB 瓦片內容optimizeB3dm：使用gltf-pipeline優化 B3DM 瓦片內容的 GLB 負載optimizeI3dm：使用gltf-pipeline優化 I3DM 瓦片內容的 GLB 負載
展示一系列多個操作流水線的示例見 examplePipeline.json。
開發者設置
當工具不是從 NPM 安裝的包，而是直接在克隆的倉庫中使用時，命令行用法如下：
- 將倉庫克隆到當前目錄：
git clone https://github.com/CesiumGS/3d-tiles-tools - 切換到克隆倉庫的目錄：
cd 3d-tiles-tools - 安裝工具及其所有依賴項：
npm install
之后，可以使用與上述相同的命令行選項執行工具，例如：
npx ts-node .\src\cli\main.ts gzip -i ./specs/data/TilesetOfTilesets/ -o ./output/TilesetOfTilesets-gzipped/
有關項目結構的詳細信息，請參閱實現說明。
