cli-anything-cloudcompare
Agent-friendly command-line harness for CloudCompare — the open-source 3D point cloud and mesh processing software.
41 commands across 9 groups.
Installation
Prerequisites:
- Python 3.10+
- CloudCompare installed on your system
- Linux (Flatpak):
flatpak install flathub org.cloudcompare.CloudCompare - macOS/Windows: download from https://cloudcompare.org
- Linux (Flatpak):
Tested with: CloudCompare 2.13.2 (Flatpak, Linux)
Global Options
These options must be placed before the subcommand:
Command Groups
1. project — Project Management (3 commands)
project new
Create a new empty project file.
Options: -o/--output TEXT (required), -n/--name TEXT
project info
Show project info and loaded entities.
project status
Show quick project status (cloud count, mesh count, last operation).
2. session — Session Management (4 commands)
session save
Save the current project state to disk.
session history
Show recent operation history.
Options: -n/--last INTEGER
session set-format
Update the default export format for future operations.
Options: --cloud-fmt TEXT, --cloud-ext TEXT, --mesh-fmt TEXT, --mesh-ext TEXT
session undo
Remove the last operation from history (soft undo — does not delete output files).
3. cloud — Point Cloud Operations (21 commands)
All cloud commands take CLOUD_INDEX (0-based integer from cloud list) and most accept --add-to-project to register the output back into the project.
cloud add
Add a point cloud file to the project.
Options: -l/--label TEXT
cloud list
List all clouds currently in the project.
cloud convert
Convert a cloud from one format to another (format determined by file extension).
cloud subsample
Reduce the number of points using RANDOM, SPATIAL, or OCTREE method.
Options: -o/--output TEXT (required), -m/--method [random|spatial|octree], -n/--param FLOAT, --add-to-project
cloud crop
Crop a cloud to an axis-aligned bounding box.
Options: -o/--output TEXT (required), --xmin/ymin/zmin/xmax/ymax/zmax FLOAT (all required), --outside, --add-to-project
cloud normals
Compute surface normals via the octree method.
Options: -o/--output TEXT (required), --level INTEGER (1–10), --orientation [plus_x|plus_y|plus_z|minus_x|minus_y|minus_z], --add-to-project
cloud invert-normals
Flip all normal vectors in the cloud.
Options: -o/--output TEXT (required), --add-to-project
cloud filter-sor
Statistical Outlier Removal — removes isolated noise points.
Options: -o/--output TEXT (required), --nb-points INTEGER, --std-ratio FLOAT, --add-to-project
cloud noise-filter
Remove noisy points using the PCL noise filter (KNN or radius mode).
Options: -o/--output TEXT (required), --knn INTEGER, --noisiness FLOAT, --radius FLOAT, --use-radius, --absolute, --add-to-project
cloud filter-csf
Ground filtering using the Cloth Simulation Filter (CSF) algorithm. Separates ground from off-ground points (buildings, vegetation).
Options: -g/--ground TEXT (required), -u/--offground TEXT, --scene [slope|relief|flat], --cloth-resolution FLOAT, --class-threshold FLOAT, --max-iteration INTEGER, --proc-slope, --add-to-project
cloud filter-sf
Filter a cloud by scalar field value range (keep points where SF ∈ [min, max]).
Options: -o/--output TEXT (required), --min FLOAT (required), --max FLOAT (required), --sf-index INTEGER, --add-to-project
cloud sf-from-coord
Convert a coordinate axis (X/Y/Z) to a scalar field. Commonly used to create a height (Z) scalar field.
Options: -o/--output TEXT (required), --dim [x|y|z] (default: z), --sf-index INTEGER, --add-to-project
cloud sf-filter-z
Convenience command: convert Z → scalar field and filter by height range in one step.
Options: -o/--output TEXT (required), --min FLOAT, --max FLOAT, --add-to-project
cloud sf-to-rgb
Convert the active scalar field to RGB colours.
Options: -o/--output TEXT (required), --add-to-project
cloud rgb-to-sf
Convert RGB colours to a scalar field (luminance value).
Options: -o/--output TEXT (required), --add-to-project
cloud curvature
Compute curvature scalar field (MEAN or GAUSS).
Options: -o/--output TEXT (required), --type [mean|gauss], -r/--radius FLOAT, --add-to-project
cloud roughness
Compute roughness scalar field (deviation from local best-fit plane).
Options: -o/--output TEXT (required), -r/--radius FLOAT, --add-to-project
cloud density
Compute point density scalar field.
Options: -o/--output TEXT (required), -r/--radius FLOAT, --type [knn|surface|volume], --add-to-project
cloud segment-cc
Segment cloud into connected components (clusters). Each component is saved as a separate file.
Options: -o/--output-dir TEXT (required), --octree-level INTEGER, --min-points INTEGER, --fmt TEXT
cloud merge
Merge all clouds in the project into a single cloud.
Options: -o/--output TEXT (required), --add-to-project
cloud mesh-delaunay
Build a 2.5-D Delaunay triangulation mesh from a cloud.
Options: -o/--output TEXT (required), --best-fit, --max-edge-length FLOAT, --add-to-project
4. mesh — Mesh Operations (3 commands)
mesh add
Add a mesh file to the project.
Options: -l/--label TEXT
mesh list
List all meshes in the project.
mesh sample
Sample a point cloud from a mesh surface.
Options: -o/--output TEXT (required), -n/--count INTEGER, --add-to-project
5. distance — Distance Computation (2 commands)
distance c2c
Compute cloud-to-cloud distances. Adds a distance scalar field to the compared cloud.
Options: --compare TEXT (required), --reference TEXT (required), -o/--output TEXT (required), --split-xyz, --octree-level INTEGER, --add-to-project
distance c2m
Compute cloud-to-mesh distances. Adds a distance scalar field to the cloud.
Options: --cloud INTEGER (required), --mesh INTEGER (required), -o/--output TEXT (required), --flip-normals, --unsigned, --add-to-project
6. transform — Transformations and Registration (2 commands)
transform apply
Apply a 4×4 rigid-body transformation matrix to a cloud.
The matrix file must contain 4 rows of 4 space-separated values:
Options: -o/--output TEXT (required), -m/--matrix TEXT (required), --inverse, --add-to-project
transform icp
Run ICP (Iterative Closest Point) registration to align one cloud to another.
Options: --aligned INTEGER (required), --reference INTEGER (required), -o/--output TEXT (required), --max-iter INTEGER, --min-error-diff FLOAT, --overlap FLOAT, --add-to-project
7. export — Export Clouds and Meshes (4 commands)
export formats
List all available export format presets.
export cloud
Export a cloud to a target format.
Supported presets: las, laz, ply, pcd, xyz, asc, csv, bin, e57
Options: -f/--preset TEXT, --overwrite
export mesh
Export a mesh to a target format.
Supported presets: obj, stl, ply, bin
Options: -f/--preset TEXT, --overwrite
export batch
Batch export all project clouds to a directory.
Options: -d/--output-dir TEXT (required), -f/--preset TEXT, --overwrite
8. info — Installation Info (1 command)
Show CloudCompare installation path and version.
9. repl — Interactive REPL (1 command)
Start the interactive REPL session with history and undo support.
Options: -p/--project TEXT
Inside the REPL, type help to list available commands or session undo to revert the last operation.
Supported File Formats
Typical Workflows
Workflow 1: LiDAR Pre-processing Pipeline
Workflow 2: Change Detection Between Two Scans
Workflow 3: Height Slice Extraction
Workflow 4: Surface Reconstruction
Error Handling
Common errors:
For AI Agents
- Always use
--jsonflag for parseable output - Check return codes — 0 for success, non-zero for errors
- Parse stderr for error messages on failure
- Use absolute paths for all file arguments
- Verify output files exist after export operations
- Chain with
--add-to-projectto build multi-step pipelines without re-loading files - Use
cloud list --jsonto discover valid cloud indices before each operation - Use
export formats --jsonto discover available format presets

