cli-anything-cloudcompare

cli-anything-cloudcompare

面向 Agent 的 CloudCompare 命令行封装工具 —— 开源 3D 点云与网格处理软件。

涵盖 9 个组、共 41 条命令。

安装

pip install cli-anything-cloudcompare

前置要求：

• Python 3.10+
• 系统中已安装 CloudCompare
  • Linux（Flatpak）：flatpak install flathub org.cloudcompare.CloudCompare
  • macOS/Windows：从 https://cloudcompare.org 下载

测试环境： CloudCompare 2.13.2（Flatpak，Linux）

全局选项

这些选项必须放在子命令之前：

cli-anything-cloudcompare [--project FILE] [--json] COMMAND [ARGS]...

选项	说明
-p, --project TEXT	项目 JSON 文件路径
--json	以 JSON 格式输出结果（供 Agent 使用）

命令组

1. project — 项目管理（3 条命令）

project new

创建一个新的空项目文件。

# Create a project with default name
cli-anything-cloudcompare project new -o myproject.json

# Create a project with a custom name
cli-anything-cloudcompare project new -o myproject.json -n "Bridge Survey 2024"

# JSON output for agents
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 output
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

显示最近的操作历史。

# Show last 10 operations (default)
cli-anything-cloudcompare --project myproject.json session history

# Show last 5 operations
cli-anything-cloudcompare --project myproject.json session history -n 5

选项：-n/--last INTEGER

session set-format

更新后续操作的默认导出格式。

# Set default cloud export to LAS
cli-anything-cloudcompare --project myproject.json session set-format --cloud-fmt LAS --cloud-ext las

# Set default mesh export to OBJ
cli-anything-cloudcompare --project myproject.json session set-format --mesh-fmt OBJ --mesh-ext obj

# Set both cloud and mesh defaults
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 命令都需要 CLOUD_INDEX（来自 cloud list 的从 0 开始的整数），且大多数命令接受 --add-to-project，用于将输出注册回项目中。

cloud add

将点云文件添加到项目。

# Add a LAS file
cli-anything-cloudcompare --project myproject.json cloud add /data/scan.las

# Add with a label
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 output for parsing indices
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 方法减少点数。

# Random: keep 100 000 points
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
  -o /data/sub_random.las -m random -n 100000

# Spatial: minimum distance 0.05 m between points
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
  -o /data/sub_spatial.las -m spatial -n 0.05

# Octree: level 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

将点云裁剪到轴对齐包围盒。

# Keep points inside the box
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

# Keep points OUTSIDE the box
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

通过八叉树方法计算表面法线。

# Compute normals at octree level 6
cli-anything-cloudcompare --project myproject.json cloud normals 0 \
  -o /data/with_normals.ply --level 6

# Compute normals oriented toward +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

统计离群点移除 —— 去除孤立的噪点。

# Default parameters (k=6 neighbours, 1.0 std ratio)
cli-anything-cloudcompare --project myproject.json cloud filter-sor 0 \
  -o /data/denoised.las

# Custom parameters
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 mode (default)
cli-anything-cloudcompare --project myproject.json cloud noise-filter 0 \
  -o /data/clean.las --knn 8 --noisiness 1.0

# Radius mode
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）算法进行地面滤波。将地面点与非地面点（建筑物、植被）分离。

# Extract ground only — mixed terrain
cli-anything-cloudcompare --project myproject.json cloud filter-csf 0 \
  --ground /data/ground.las --scene relief

# Split ground + off-ground — urban scene
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

# Steep forested slope with slope post-processing
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] 的点）。

# Keep points with SF value between 10 and 50
cli-anything-cloudcompare --project myproject.json cloud filter-sf 0 \
  -o /data/filtered.las --min 10.0 --max 50.0

# Filter using a specific SF index
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）标量场。

# Create Z scalar field (height)
cli-anything-cloudcompare --project myproject.json cloud sf-from-coord 0 \
  -o /data/with_z_sf.las --dim z --add-to-project

# Create X scalar field with a specific active index
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 → 标量场转换并按高度范围过滤。

# Extract points between z=1.0 m and 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

# Only apply upper bound
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）。

# Mean curvature with radius 0.5 m
cli-anything-cloudcompare --project myproject.json cloud curvature 0 \
  -o /data/curvature.las --type mean --radius 0.5

# Gaussian curvature
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 density
cli-anything-cloudcompare --project myproject.json cloud density 0 \
  -o /data/density.las --type knn --radius 0.5

# Surface density
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

将点云分割为连通分量（聚类）。每个分量保存为单独的文件。

# Segment with octree level 8, minimum 100 points per component
cli-anything-cloudcompare --project myproject.json cloud segment-cc 0 \
  -o /data/components/ --octree-level 8 --min-points 100

# Save components as PLY files
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 Delaunay 三角剖分网格。

# Basic Delaunay mesh
cli-anything-cloudcompare --project myproject.json cloud mesh-delaunay 0 \
  -o /data/surface.obj

# Best-fit plane with max edge length limit
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

# Add with label
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 output
cli-anything-cloudcompare --project myproject.json --json mesh list

mesh sample

从网格表面采样点云。

# Sample 50 000 points from mesh at index 0
cli-anything-cloudcompare --project myproject.json mesh sample 0 \
  -o /data/sampled.las -n 50000

# Add sampled cloud back to project
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 — 距离计算（2 个命令）

distance c2c

计算点云到点云的距离。为被比较的点云添加距离标量场。

# Compare cloud 1 to reference cloud 0
cli-anything-cloudcompare --project myproject.json distance c2c \
  --compare 1 --reference 0 -o /data/distances.las

# Split into X/Y/Z components at octree level 8
cli-anything-cloudcompare --project myproject.json distance c2c \
  --compare 1 --reference 0 -o /data/distances.las \
  --split-xyz --octree-level 8 --add-to-project

选项：--compare TEXT（必填）、--reference TEXT（必填）、-o/--output TEXT（必填）、--split-xyz、--octree-level INTEGER、--add-to-project

distance c2m

计算点云到网格的距离。为点云添加距离标量场。

# Basic cloud-to-mesh distance
cli-anything-cloudcompare --project myproject.json distance c2m \
  --cloud 0 --mesh 0 -o /data/c2m_dist.las

# With flipped normals and unsigned distances
cli-anything-cloudcompare --project myproject.json distance c2m \
  --cloud 0 --mesh 0 -o /data/c2m_dist.las \
  --flip-normals --unsigned --add-to-project

选项：--cloud INTEGER（必填）、--mesh INTEGER（必填）、-o/--output TEXT（必填）、--flip-normals、--unsigned、--add-to-project

---

6. transform — 变换与配准（2 个命令）

transform apply

对点云应用 4×4 刚体变换矩阵。

# Apply a transformation matrix from file
cli-anything-cloudcompare --project myproject.json transform apply 0 \
  -o /data/transformed.las -m /data/matrix.txt

# Apply the inverse transformation
cli-anything-cloudcompare --project myproject.json transform apply 0 \
  -o /data/transformed.las -m /data/matrix.txt --inverse --add-to-project

矩阵文件必须包含 4 行，每行 4 个以空格分隔的值：

1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1

选项：-o/--output TEXT（必填）、-m/--matrix TEXT（必填）、--inverse、--add-to-project

transform icp

运行 ICP（迭代最近点）配准，将一个点云对齐到另一个点云。

# Basic ICP alignment
cli-anything-cloudcompare --project myproject.json transform icp \
  --aligned 1 --reference 0 -o /data/aligned.las

# ICP with overlap and iteration control
cli-anything-cloudcompare --project myproject.json transform icp \
  --aligned 1 --reference 0 -o /data/aligned.las \
  --max-iter 50 --overlap 80 --min-error-diff 1e-6 --add-to-project

选项：--aligned INTEGER（必填）、--reference INTEGER（必填）、-o/--output TEXT（必填）、--max-iter INTEGER、--min-error-diff FLOAT、--overlap FLOAT、--add-to-project

---

7. export — 导出点云和网格（4 个命令）

export formats

列出所有可用的导出格式预设。

cli-anything-cloudcompare export formats

# JSON output
cli-anything-cloudcompare --json export formats

export cloud

将点云导出为目标格式。

# Export cloud at index 0 as LAS
cli-anything-cloudcompare --project myproject.json export cloud 0 /data/output.las

# Export as PLY using preset
cli-anything-cloudcompare --project myproject.json export cloud 0 /data/output.ply -f ply

# Overwrite if file exists
cli-anything-cloudcompare --project myproject.json export cloud 0 /data/output.las -f las --overwrite

支持的预设：las、laz、ply、pcd、xyz、asc、csv、bin、e57

选项：-f/--preset TEXT、--overwrite

export mesh

将网格导出为目标格式。

# Export mesh at index 0 as OBJ
cli-anything-cloudcompare --project myproject.json export mesh 0 /data/model.obj

# Export as STL
cli-anything-cloudcompare --project myproject.json export mesh 0 /data/model.stl -f stl --overwrite

支持的预设：obj、stl、ply、bin

选项：-f/--preset TEXT、--overwrite

export batch

将所有项目点云批量导出到指定目录。

# Export all clouds as LAS
cli-anything-cloudcompare --project myproject.json export batch \
  -d /data/exports/ -f las

# Overwrite existing files
cli-anything-cloudcompare --project myproject.json export batch \
  -d /data/exports/ -f ply --overwrite

选项：-d/--output-dir TEXT（必填）、-f/--preset TEXT、--overwrite

---

8. info — 安装信息（1 个命令）

显示 CloudCompare 的安装路径和版本。

cli-anything-cloudcompare info

# JSON output
cli-anything-cloudcompare --json info

---

9. repl — 交互式 REPL（1 个命令）

启动支持历史记录和撤销操作的交互式 REPL 会话。

# Start REPL without a project
cli-anything-cloudcompare repl

# Start REPL with an existing project
cli-anything-cloudcompare repl -p myproject.json

# Equivalent: run without subcommand
cli-anything-cloudcompare --project myproject.json

选项：-p/--project TEXT

在 REPL 中，输入 help 可列出可用命令，输入 session undo 可撤销上一次操作。

---

支持的文件格式

格式	扩展名	读取	写入	说明
LAS	.las	✓	✓	LiDAR 标准格式，支持强度/RGB
LAZ	.laz	✓	✓	压缩的 LAS
PLY	.ply	✓	✓	ASCII 或二进制
PCD	.pcd	✓	✓	PCL 格式
XYZ	.xyz	✓	✓	纯文本 XYZ
ASC	.asc	✓	✓	带文件头的 ASCII
CSV	.csv	✓	✓	逗号分隔
E57	.e57	✓	✓	ASTM 扫描仪交换格式
BIN	.bin	✓	✓	CloudCompare 原生二进制
OBJ	.obj	✓	✓	网格（Wavefront）
STL	.stl	✓	✓	网格（3D 打印）

---

典型工作流

工作流 1：LiDAR 预处理流水线

P=myproject.json

# 1. Create project and load scan
cli-anything-cloudcompare project new -o $P
cli-anything-cloudcompare --project $P cloud add /data/scan.las
cli-anything-cloudcompare --project $P cloud list  # note index → 0

# 2. Denoise
cli-anything-cloudcompare --project $P cloud filter-sor 0 \
  -o /data/denoised.las --nb-points 6 --std-ratio 1.0 --add-to-project

# 3. Subsample to 5 cm grid
cli-anything-cloudcompare --project $P cloud subsample 1 \
  -o /data/subsampled.las -m spatial -n 0.05 --add-to-project

# 4. Extract ground plane (CSF)
cli-anything-cloudcompare --project $P cloud filter-csf 2 \
  --ground /data/ground.las --offground /data/objects.las \
  --scene relief --add-to-project

# 5. Export result
cli-anything-cloudcompare --project $P export cloud 3 /data/ground_final.las -f las --overwrite

工作流 2：两次扫描之间的变化检测

P=compare.json
cli-anything-cloudcompare project new -o $P
cli-anything-cloudcompare --project $P cloud add /data/scan_2023.las   # index 0
cli-anything-cloudcompare --project $P cloud add /data/scan_2024.las   # index 1

# ICP alignment (align 2024 to 2023)
cli-anything-cloudcompare --project $P transform icp \
  --aligned 1 --reference 0 -o /data/aligned_2024.las \
  --overlap 90 --add-to-project   # index 2

# Cloud-to-cloud distance
cli-anything-cloudcompare --project $P distance c2c \
  --compare 2 --reference 0 -o /data/change_map.las --add-to-project

# Export as LAS with distance scalar field
cli-anything-cloudcompare --project $P export cloud 3 /data/change_map_final.las --overwrite

工作流 3：高度切片提取

P=slice.json
cli-anything-cloudcompare project new -o $P
cli-anything-cloudcompare --project $P cloud add /data/building.las

# Extract points at 2–3 m height (floor level)
cli-anything-cloudcompare --project $P cloud sf-filter-z 0 \
  -o /data/floor_slice.las --min 2.0 --max 3.0 --add-to-project

# Export
cli-anything-cloudcompare --project $P export cloud 1 /data/floor_slice_out.las --overwrite

工作流 4：曲面重建

P=mesh.json
cli-anything-cloudcompare project new -o $P
cli-anything-cloudcompare --project $P cloud add /data/terrain.las

# Compute normals
cli-anything-cloudcompare --project $P cloud normals 0 \
  -o /data/with_normals.ply --level 6 --orientation plus_z --add-to-project

# Delaunay mesh
cli-anything-cloudcompare --project $P cloud mesh-delaunay 1 \
  -o /data/terrain_mesh.obj --max-edge-length 1.0 --add-to-project

# Export mesh
cli-anything-cloudcompare --project $P export mesh 0 /data/terrain_mesh_final.obj --overwrite

---

错误处理

退出代码	含义
0	成功
1	一般错误（详情请参阅 stderr）
2	无效参数

常见错误：

# CloudCompare not found
# → Install CloudCompare; check `cli-anything-cloudcompare info`

# Index out of range
# → Run `cloud list` or `mesh list` to confirm valid indices

# File already exists (no --overwrite)
# → Add --overwrite flag to export commands

# fcntl not available (Windows)
# → File locking is skipped automatically; project save still works

---

面向 AI Agent

1. 始终使用 --json 标志以获得可解析的输出
2. 检查返回代码 — 0 表示成功，非零表示错误
3. 解析 stderr 以获取失败时的错误信息
4. 对所有文件参数使用绝对路径
5. 在导出操作后验证输出文件是否存在
6. 与 --add-to-project 链式组合，无需重新加载文件即可构建多步流水线
7. 使用 cloud list --json 在每次操作前发现有效的点云索引
8. 使用 export formats --json 发现可用的格式预设

版本

组件	版本
cli-anything-cloudcompare	1.0.0
CloudCompare（已测试）	2.13.2
Python（最低要求）	3.10