cli-anything-cloudcompare 是做什麼的?
為 AI 代理打造的 CloudCompare 命令列外殼 — 該軟體為開源 3D 點雲與網格處理軟體。
41 個命令,分為 9 大類。
安裝
pip install cli-anything-cloudcompare
先決條件:
- Python 3.10+
- 系統上已安裝 CloudCompare
- Linux (Flatpak):
flatpak install flathub org.cloudcompare.CloudCompare - macOS/Windows:從 https://cloudcompare.org 下載
- Linux (Flatpak):
測試於: CloudCompare 2.13.2 (Flatpak, Linux)
全域選項
這些選項必須放在子命令之前:
cli-anything-cloudcompare [--project FILE] [--json] COMMAND [ARGS]...
| 選項 | 說明 |
|---|---|
-p, --project TEXT | 專案 JSON 檔案的路徑 |
--json | 以 JSON 格式輸出結果(供代理使用) |
命令群組
1. project — 專案管理(3 個命令)
project new
建立一個新的空白專案檔案。
# 使用預設名稱建立專案
cli-anything-cloudcompare project new -o myproject.json
# 使用自訂名稱建立專案
cli-anything-cloudcompare project new -o myproject.json -n "Bridge Survey 2024"
# 使用 JSON 輸出(供代理使用)
cli-anything-cloudcompare --json project new -o myproject.json
選項:-o/--output TEXT(必要),-n/--name TEXT
project info
顯示專案資訊與已載入的實體。
cli-anything-cloudcompare --project myproject.json project info
# JSON 輸出
cli-anything-cloudcompare --project myproject.json --json project info
project status
顯示快速專案狀態(點雲數量、網格數量、上次操作)。
cli-anything-cloudcompare --project myproject.json project status
2. session — 會話管理(4 個命令)
session save
將目前的專案狀態儲存至磁碟。
cli-anything-cloudcompare --project myproject.json session save
session history
顯示最近的操作歷史。
# 顯示最近 10 項操作(預設)
cli-anything-cloudcompare --project myproject.json session history
# 顯示最近 5 項操作
cli-anything-cloudcompare --project myproject.json session history -n 5
選項:-n/--last INTEGER
session set-format
更新未來操作的預設匯出格式。
# 將預設點雲匯出格式設為 LAS
cli-anything-cloudcompare --project myproject.json session set-format --cloud-fmt LAS --cloud-ext las
# 將預設網格匯出格式設為 OBJ
cli-anything-cloudcompare --project myproject.json session set-format --mesh-fmt OBJ --mesh-ext obj
# 同時設定點雲與網格的預設格式
cli-anything-cloudcompare --project myproject.json session set-format \
--cloud-fmt PLY --cloud-ext ply \
--mesh-fmt STL --mesh-ext stl
選項:--cloud-fmt TEXT,--cloud-ext TEXT,--mesh-fmt TEXT,--mesh-ext TEXT
session undo
從歷史記錄中移除最後一項操作(軟復原 — 不會刪除輸出檔案)。
cli-anything-cloudcompare --project myproject.json session undo
3. cloud — 點雲操作(21 個命令)
所有雲端命令都接受 CLOUD_INDEX(從 cloud list 取得的 0 起始整數),且大多數接受 --add-to-project 以將輸出註冊回專案中。
cloud add
將一個點雲檔案新增至專案。
# 新增 LAS 檔案
cli-anything-cloudcompare --project myproject.json cloud add /data/scan.las
# 新增並加上標籤
cli-anything-cloudcompare --project myproject.json cloud add /data/scan.las -l "roof scan"
選項:-l/--label TEXT
cloud list
列出專案中目前所有的點雲。
cli-anything-cloudcompare --project myproject.json cloud list
# 以 JSON 輸出解析索引
cli-anything-cloudcompare --project myproject.json --json cloud list
cloud convert
將點雲從一種格式轉換為另一種(格式由副檔名決定)。
# LAS → PLY
cli-anything-cloudcompare cloud convert /data/scan.las /data/scan.ply
# PCD → LAS
cli-anything-cloudcompare cloud convert /data/cloud.pcd /data/cloud.las
cloud subsample
使用 RANDOM、SPATIAL 或 OCTREE 方法減少點數。
# 隨機:保留 100,000 個點
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
-o /data/sub_random.las -m random -n 100000
# 空間:點之間的最小距離為 0.05 公尺
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
-o /data/sub_spatial.las -m spatial -n 0.05
# 八叉樹:層級 8
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
-o /data/sub_octree.las -m octree -n 8 --add-to-project
選項:-o/--output TEXT(必要),-m/--method [random|spatial|octree],-n/--param FLOAT,--add-to-project
cloud crop
將點雲裁剪到一個軸對齊的邊界框中。
# 保留框內的點
cli-anything-cloudcompare --project myproject.json cloud crop 0 \
-o /data/cropped.las \
--xmin 0.0 --ymin 0.0 --zmin 0.0 \
--xmax 10.0 --ymax 10.0 --zmax 5.0
# 保留框外的點
cli-anything-cloudcompare --project myproject.json cloud crop 0 \
-o /data/exterior.las \
--xmin 0.0 --ymin 0.0 --zmin 0.0 \
--xmax 10.0 --ymax 10.0 --zmax 5.0 --outside
選項:-o/--output TEXT(必要),--xmin/ymin/zmin/xmax/ymax/zmax FLOAT(全部必要),--outside,--add-to-project
cloud normals
透過八叉樹方法計算表面法線。
# 在八叉樹層級 6 計算法線
cli-anything-cloudcompare --project myproject.json cloud normals 0 \
-o /data/with_normals.ply --level 6
# 計算朝向 +Z 的法線
cli-anything-cloudcompare --project myproject.json cloud normals 0 \
-o /data/with_normals.ply --level 6 --orientation plus_z --add-to-project
選項:-o/--output TEXT(必要),--level INTEGER(1–10),--orientation [plus_x|plus_y|plus_z|minus_x|minus_y|minus_z],--add-to-project
cloud invert-normals
翻轉點雲中的所有法線向量。
cli-anything-cloudcompare --project myproject.json cloud invert-normals 0 \
-o /data/flipped_normals.ply --add-to-project
選項:-o/--output TEXT(必要),--add-to-project
cloud filter-sor
統計離群值移除 — 移除孤立的雜訊點。
# 預設參數(k=6 個鄰居,1.0 標準差比值)
cli-anything-cloudcompare --project myproject.json cloud filter-sor 0 \
-o /data/denoised.las
# 自訂參數
cli-anything-cloudcompare --project myproject.json cloud filter-sor 0 \
-o /data/denoised.las --nb-points 12 --std-ratio 2.0 --add-to-project
選項:-o/--output TEXT(必要),--nb-points INTEGER,--std-ratio FLOAT,--add-to-project
cloud noise-filter
使用 PCL 雜訊濾波器(KNN 或半徑模式)移除雜訊點。
# KNN 模式(預設)
cli-anything-cloudcompare --project myproject.json cloud noise-filter 0 \
-o /data/clean.las --knn 8 --noisiness 1.0
# 半徑模式
cli-anything-cloudcompare --project myproject.json cloud noise-filter 0 \
-o /data/clean.las --radius 0.1 --use-radius --add-to-project
選項:-o/--output TEXT(必要),--knn INTEGER,--noisiness FLOAT,--radius FLOAT,--use-radius,--absolute,--add-to-project
cloud filter-csf
使用布料模擬濾波(CSF)演算法進行地面濾波。將地面點與非地面點(建築物、植被)分離。
# 僅提取地面 — 混合地形
cli-anything-cloudcompare --project myproject.json cloud filter-csf 0 \
--ground /data/ground.las --scene relief
# 分離地面 + 非地面 — 都市場景
cli-anything-cloudcompare --project myproject.json cloud filter-csf 0 \
--ground /data/ground.las \
--offground /data/buildings.las \
--scene flat --cloth-resolution 0.5 --class-threshold 0.3
# 陡峭森林坡地,使用坡度後處理
cli-anything-cloudcompare --project myproject.json cloud filter-csf 0 \
--ground /data/terrain.las --scene slope --proc-slope --add-to-project
選項:-g/--ground TEXT(必要),-u/--offground TEXT,--scene [slope|relief|flat],--cloth-resolution FLOAT,--class-threshold FLOAT,--max-iteration INTEGER,--proc-slope,--add-to-project
cloud filter-sf
根據純量場數值範圍濾波點雲(保留 SF ∈ [min, max] 的點)。
# 保留 SF 值介於 10 到 50 的點
cli-anything-cloudcompare --project myproject.json cloud filter-sf 0 \
-o /data/filtered.las --min 10.0 --max 50.0
# 使用特定 SF 索引進行濾波
cli-anything-cloudcompare --project myproject.json cloud filter-sf 0 \
-o /data/filtered.las --min 0.0 --max 1.5 --sf-index 2 --add-to-project
選項:-o/--output TEXT(必要),--min FLOAT(必要),--max FLOAT(必要),--sf-index INTEGER,--add-to-project
cloud sf-from-coord
將座標軸(X/Y/Z)轉換為純量場。常用於建立高度(Z)純量場。
# 建立 Z 純量場(高度)
cli-anything-cloudcompare --project myproject.json cloud sf-from-coord 0 \
-o /data/with_z_sf.las --dim z --add-to-project
# 建立 X 純量場,指定活躍索引
cli-anything-cloudcompare --project myproject.json cloud sf-from-coord 0 \
-o /data/with_x_sf.las --dim x --sf-index 0
選項:-o/--output TEXT(必要),--dim [x|y|z](預設:z),--sf-index INTEGER,--add-to-project
cloud sf-filter-z
便利命令:一次完成 Z → 純量場轉換與依高度範圍濾波。
# 提取 z=1.0 m 到 z=2.5 m 之間的點
cli-anything-cloudcompare --project myproject.json cloud sf-filter-z 0 \
-o /data/slice.las --min 1.0 --max 2.5 --add-to-project
# 僅套用上限
cli-anything-cloudcompare --project myproject.json cloud sf-filter-z 0 \
-o /data/below_5m.las --max 5.0
選項:-o/--output TEXT(必要),--min FLOAT,--max FLOAT,--add-to-project
cloud sf-to-rgb
將活躍的純量場轉換為 RGB 顏色。
cli-anything-cloudcompare --project myproject.json cloud sf-to-rgb 0 \
-o /data/coloured.ply --add-to-project
選項:-o/--output TEXT(必要),--add-to-project
cloud rgb-to-sf
將 RGB 顏色轉換為純量場(亮度值)。
cli-anything-cloudcompare --project myproject.json cloud rgb-to-sf 0 \
-o /data/luminance.las --add-to-project
選項:-o/--output TEXT(必要),--add-to-project
cloud curvature
計算曲率純量場(MEAN 或 GAUSS)。
# 平均曲率,半徑 0.5 公尺
cli-anything-cloudcompare --project myproject.json cloud curvature 0 \
-o /data/curvature.las --type mean --radius 0.5
# 高斯曲率
cli-anything-cloudcompare --project myproject.json cloud curvature 0 \
-o /data/curvature.las --type gauss --radius 0.5 --add-to-project
選項:-o/--output TEXT(必要),--type [mean|gauss],-r/--radius FLOAT,--add-to-project
cloud roughness
計算粗糙度純量場(與局部最佳擬合平面的偏差)。
cli-anything-cloudcompare --project myproject.json cloud roughness 0 \
-o /data/roughness.las --radius 0.2 --add-to-project
選項:-o/--output TEXT(必要),-r/--radius FLOAT,--add-to-project
cloud density
計算點密度純量場。
# KNN 密度
cli-anything-cloudcompare --project myproject.json cloud density 0 \
-o /data/density.las --type knn --radius 0.5
# 表面密度
cli-anything-cloudcompare --project myproject.json cloud density 0 \
-o /data/density.las --type surface --radius 1.0 --add-to-project
選項:-o/--output TEXT(必要),-r/--radius FLOAT,--type [knn|surface|volume],--add-to-project
cloud segment-cc
將點雲分割為連通分量(群集)。每個分量儲存為獨立檔案。
# 使用八叉樹層級 8 分割,每個分量至少 100 個點
cli-anything-cloudcompare --project myproject.json cloud segment-cc 0 \
-o /data/components/ --octree-level 8 --min-points 100
# 將分量儲存為 PLY 檔案
cli-anything-cloudcompare --project myproject.json cloud segment-cc 0 \
-o /data/components/ --octree-level 6 --min-points 50 --fmt ply
選項:-o/--output-dir TEXT(必要),--octree-level INTEGER,--min-points INTEGER,--fmt TEXT
cloud merge
將專案中所有的點雲合併為單一點雲。
cli-anything-cloudcompare --project myproject.json cloud merge \
-o /data/merged.las --add-to-project
選項:-o/--output TEXT(必要),--add-to-project
cloud mesh-delaunay
從點雲建立 2.5-D 德勞內三角網格。
# 基本德勞內網格
cli-anything-cloudcompare --project myproject.json cloud mesh-delaunay 0 \
-o /data/surface.obj
# 最佳擬合平面,限制最大邊長
cli-anything-cloudcompare --project myproject.json cloud mesh-delaunay 0 \
-o /data/surface.ply --best-fit --max-edge-length 2.0 --add-to-project
選項:-o/--output TEXT(必要),--best-fit,--max-edge-length FLOAT,--add-to-project
4. mesh — 網格操作(3 個命令)
mesh add
將一個網格檔案新增至專案。
cli-anything-cloudcompare --project myproject.json mesh add /data/model.obj
# 新增並加上標籤
cli-anything-cloudcompare --project myproject.json mesh add /data/model.ply -l "building model"
選項:-l/--label TEXT
mesh list
列出專案中所有的網格。
cli-anything-cloudcompare --project myproject.json mesh list
# JSON 輸出
cli-anything-cloudcompare --project myproject.json --json mesh list
mesh sample
從網格表面取樣點雲。
# 從索引 0 的網格取樣 50,000 個點
cli-anything-cloudcompare --project myproject.json mesh sample 0 \
-o /data/sampled.las -n 50000
# 將取樣的點雲加回專案
cli-anything-cloudcompare --project myproject.json mesh sample 0 \
-o /data/sampled.las -n 100000 --add-to-project
選項:-o/--output TEXT(必要),-n/--count INTEGER(必要),--add-to-project
5. distance — 距離計算(4 個命令)
distance cloud-to-cloud (C2C)
計算兩個點雲之間的絕對距離。
# 將點雲 0 與點雲 1 比較
cli-anything-cloudcompare --project myproject.json distance c2c \
--cloud-src 0 --cloud-dst 1 -o /data/c2c_dist.las --add-to-project
選項:--cloud-src INTEGER(必要),--cloud-dst INTEGER(必要),-o/--output TEXT(必要),--add-to-project
distance cloud-to-mesh (C2M)
計算點雲與網格之間的距離。
# 比較點雲 0 與網格 0,樣本數 500,000
cli-anything-cloudcompare --project myproject.json distance c2m \
--cloud-src 0 --mesh-index 0 -o /data/c2m_dist.las \
--samples 500000 --add-to-project
選項:--cloud-src INTEGER(必要),--mesh-index INTEGER(必要),-o/--output TEXT(必要),--samples INTEGER,--add-to-project
distance cloud-to-primitive (C2P)
計算點雲與原幾何體(平面、球體、圓柱體、圓錐體、環面)之間的距離。
# 平面比較
cli-anything-cloudcompare --project myproject.json distance c2p \
--cloud-src 0 --prim plane --params "0,0,0,1,0,0" \
-o /data/c2p_dist.las --add-to-project
選項:--cloud-src INTEGER(必要),--prim [plane|sphere|cylinder|cone|torus](必要),--params TEXT(必要),-o/--output TEXT(必要),--add-to-project
distance hausdorff
計算兩個點雲之間的豪斯多夫距離。
cli-anything-cloudcompare --project myproject.json distance hausdorff \
--cloud-src 0 --cloud-dst 1 -o /data/hausdorff_dist.las --add-to-project
選項:--cloud-src INTEGER(必要),--cloud-dst INTEGER(必要),-o/--output TEXT(必要),--add-to-project
6. transform — 座標轉換(2 個命令)
transform icp
執行迭代最近點(ICP)配準,將點雲 0 對齊到點雲 1。
# 基本 ICP 配準
cli-anything-cloudcompare --project myproject.json transform icp \
--source 0 --target 1 -o /data/aligned.las
# 使用自訂疊代次數與 RMS 閾值
cli-anything-cloudcompare --project myproject.json transform icp \
--source 0 --target 1 -o /data/aligned.las \
--iterations 50 --rms 0.01 --add-to-project
選項:-s/--source INTEGER(必要),-t/--target INTEGER(必要),-o/--output TEXT(必要),-i/--iterations INTEGER,--rms FLOAT,--add-to-project
transform matrix
對點雲套用 4×4 剛體轉換矩陣。
# 從檔案讀取矩陣
cli-anything-cloudcompare --project myproject.json transform matrix -s 0 \
-o /data/transformed.las --matrix matrix.txt
# 透過命令列參數指定矩陣
cli-anything-cloudcompare --project myproject.json transform matrix -s 0 \
-o /data/transformed.las --m00 0.707 --m01 -0.707 ... --add-to-project
選項:-s/--source INTEGER(必要),-o/--output TEXT(必要),--matrix FILE,--m00/m01/... FLOAT,--add-to-project
7. export — 匯出(3 個命令)
export cloud
將點雲匯出至支援的格式。
# 將點雲 0 匯出為 LAS
cli-anything-cloudcompare --project myproject.json export cloud 0 \
--fmt LAS --ext las -o /data/exported.las
# 匯出為 PLY(二進位)
cli-anything-cloudcompare --project myproject.json export cloud 0 \
--fmt PLY --ext ply -o /data/exported.ply --binary
選項:--fmt [LAS|LAZ|PLY|PCD|OBJ|STL|E57](必要),--ext TEXT(必要),-o/--output TEXT(必要),--binary
export mesh
將網格匯出至支援的格式。
# 將網格 0 匯出為 OBJ
cli-anything-cloudcompare --project myproject.json export mesh 0 \
--fmt OBJ --ext obj -o /data/exported.obj
# 匯出為 STL(二進位)
cli-anything-cloudcompare --project myproject.json export mesh 0 \
--fmt STL --ext stl -o /data/exported.stl --binary
選項:--fmt [LAS|LAZ|PLY|PCD|OBJ|STL|E57](必要),--ext TEXT(必要),-o/--output TEXT(必要),--binary
export all
將專案中的所有點雲與網格匯出至目錄。
cli-anything-cloudcompare --project myproject.json export all \
--cloud-fmt LAS --cloud-ext las \
--mesh-fmt OBJ --mesh-ext obj -o /data/exports/
選項:--cloud-fmt TEXT(必要),--cloud-ext TEXT(必要),--mesh-fmt TEXT(必要),--mesh-ext TEXT(必要),-o/--output-dir TEXT(必要)
8. info — 資訊查詢(3 個命令)
info cloud
顯示點雲的詳細資訊(點數、邊界框、SF 數量等)。
cli-anything-cloudcompare --project myproject.json info cloud 0
# JSON 輸出
cli-anything-cloudcompare --project myproject.json --json info cloud 0
info cloud-stats
顯示點雲統計資料(總計、平均值、標準差等)。
cli-anything-cloudcompare --project myproject.json info cloud-stats 0
# JSON 輸出
cli-anything-cloudcompare --project myproject.json --json info cloud-stats 0
info mesh
顯示網格的詳細資訊(面數、頂點數、邊界框)。
cli-anything-cloudcompare --project myproject.json info mesh 0
# JSON 輸出
cli-anything-cloudcompare --project myproject.json --json info mesh 0
9. repl — 互動式 Shell(1 個命令)
互動式 REPL,用於探索命令與格式。
cli-anything-cloudcompare repl
在 REPL 中輸入 help 以取得使用說明。
支援的格式
| 格式 | 匯入 | 匯出 | 備註 |
|---|---|---|---|
| LAS | ✅ | ✅ | 點雲 |
| LAZ | ✅ | ✅ | 壓縮的 LAS |
| PLY | ✅ | ✅ | 支援二進位/文字 |
| PCD | ✅ | ✅ | PCL 格式 (XYZ/RGB) |
| OBJ | ✅ | ✅ | 網格(也可作為點雲) |
| STL | ✅ | ✅ | 網格(支援二進位) |
| E57 | ✅ | ✅ | ASTM E57 格式 |
| ASC/TXT | ✅ | ❌ | 透過 CloudCompare 直接匯入 |
| BIN | ❌ | ✅ | CloudCompare 原生二進位格式 |
E57 支援需在 CloudCompare 中啟用 LIBE57 編譯。
專案格式
專案檔案為 JSON 格式:
{
"clouds": ["/path/to/cloud1.las", "/path/to/cloud2.ply"],
"meshes": ["/path/to/mesh.obj"],
"cloud_formats": {"default": "LAS", "default_ext": "las"},
"mesh_formats": {"default": "OBJ", "default_ext": "obj"}
}
環境變數
| 變數 | 說明 |
|---|---|
CC_PATH | CloudCompare 可執行檔案的路徑(若未在 PATH 中) |
CC_FLATPAK | 設定為 1 以使用 Flatpak 安裝(覆蓋自動偵測) |
Flatpak (Linux) 支援
平台: Linux
若 CloudCompare 是透過 Flatpak 安裝,外殼會自動偵測並使用正確的執行包裝器。
也可透過 CC_FLATPAK=1 環境變數強制使用 Flatpak 模式。
# 自動偵測
cli-anything-cloudcompare --project project.json cloud list
# 強制 Flatpak
CC_FLATPAK=1 cli-anything-cloudcompare --project project.json cloud list
系統支援
| 平台 | 狀態 | 安裝方式 |
|---|---|---|
| Linux (Flatpak) | ✅ 完整支援 | flatpak install flathub org.cloudcompare.CloudCompare |
| macOS (應用程式) | ✅ 完整支援 | 從 https://cloudcompare.org 下載 |
| Windows (安裝程式) | ✅ 完整支援 | 從 https://cloudcompare.org 下載 |
開發
git clone https://github.com/your-username/cli-anything-cloudcompare.git
cd cli-anything-cloudcompare
pip install -e ".[dev]"
pre-commit install
執行測試
pytest