| name | cli-anything-cloudcompare |
| description | Command-line interface for CloudCompare — Agent-friendly harness for CloudCompare, the open-source 3D point cloud and mesh processing software. Supports 41 commands across 9 groups: project management, session control, point cloud operations (subsample, filter, segment, analyze), mesh operations, distance computation (C2C, C2M), transformations (ICP, matrix), export (LAS/LAZ/PLY/PCD/OBJ/STL/E57), and interactive REPL. |
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
pip install cli-anything-cloudcompare
Prerequisites:
- Python 3.10+
- CloudCompare installed on your system
- Linux (Flatpak):
flatpak install flathub org.cloudcompare.CloudCompare
- macOS/Windows: download from https://cloudcompare.org
Tested with: CloudCompare 2.13.2 (Flatpak, Linux)
Global Options
These options must be placed before the subcommand:
cli-anything-cloudcompare [--project FILE] [--json] COMMAND [ARGS]...
| Option | Description |
|---|
-p, --project TEXT | Path to project JSON file |
--json | Output results as JSON (for agent consumption) |
Command Groups
1. project — Project Management (3 commands)
project new
Create a new empty project file.
cli-anything-cloudcompare project new -o myproject.json
cli-anything-cloudcompare project new -o myproject.json -n "Bridge Survey 2024"
cli-anything-cloudcompare --json project new -o myproject.json
Options: -o/--output TEXT (required), -n/--name TEXT
project info
Show project info and loaded entities.
cli-anything-cloudcompare --project myproject.json project info
cli-anything-cloudcompare --project myproject.json --json project info
project status
Show quick project status (cloud count, mesh count, last operation).
cli-anything-cloudcompare --project myproject.json project status
2. session — Session Management (4 commands)
session save
Save the current project state to disk.
cli-anything-cloudcompare --project myproject.json session save
session history
Show recent operation history.
cli-anything-cloudcompare --project myproject.json session history
cli-anything-cloudcompare --project myproject.json session history -n 5
Options: -n/--last INTEGER
session set-format
Update the default export format for future operations.
cli-anything-cloudcompare --project myproject.json session set-format --cloud-fmt LAS --cloud-ext las
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
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).
cli-anything-cloudcompare --project myproject.json session undo
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.
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"
Options: -l/--label TEXT
cloud list
List all clouds currently in the project.
cli-anything-cloudcompare --project myproject.json cloud list
cli-anything-cloudcompare --project myproject.json --json cloud list
cloud convert
Convert a cloud from one format to another (format determined by file extension).
cli-anything-cloudcompare cloud convert /data/scan.las /data/scan.ply
cli-anything-cloudcompare cloud convert /data/cloud.pcd /data/cloud.las
cloud subsample
Reduce the number of points using RANDOM, SPATIAL, or OCTREE method.
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
-o /data/sub_random.las -m random -n 100000
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
-o /data/sub_spatial.las -m spatial -n 0.05
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
-o /data/sub_octree.las -m octree -n 8 --add-to-project
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.
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
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.
cli-anything-cloudcompare --project myproject.json cloud normals 0 \
-o /data/with_normals.ply --level 6
cli-anything-cloudcompare --project myproject.json cloud normals 0 \
-o /data/with_normals.ply --level 6 --orientation plus_z --add-to-project
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.
cli-anything-cloudcompare --project myproject.json cloud invert-normals 0 \
-o /data/flipped_normals.ply --add-to-project
Options: -o/--output TEXT (required), --add-to-project
cloud filter-sor
Statistical Outlier Removal — removes isolated noise points.
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
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).
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
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).
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
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]).
cli-anything-cloudcompare --project myproject.json cloud filter-sf 0 \
-o /data/filtered.las --min 10.0 --max 50.0
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
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.
cli-anything-cloudcompare --project myproject.json cloud sf-from-coord 0 \
-o /data/with_z_sf.las --dim z --add-to-project
cli-anything-cloudcompare --project myproject.json cloud sf-from-coord 0 \
-o /data/with_x_sf.las --dim x --sf-index 0
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.
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
Options: -o/--output TEXT (required), --min FLOAT, --max FLOAT, --add-to-project
cloud sf-to-rgb
Convert the active scalar field to RGB colours.
cli-anything-cloudcompare --project myproject.json cloud sf-to-rgb 0 \
-o /data/coloured.ply --add-to-project
Options: -o/--output TEXT (required), --add-to-project
cloud rgb-to-sf
Convert RGB colours to a scalar field (luminance value).
cli-anything-cloudcompare --project myproject.json cloud rgb-to-sf 0 \
-o /data/luminance.las --add-to-project
Options: -o/--output TEXT (required), --add-to-project
cloud curvature
Compute curvature scalar field (MEAN or GAUSS).
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
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).
cli-anything-cloudcompare --project myproject.json cloud roughness 0 \
-o /data/roughness.las --radius 0.2 --add-to-project
Options: -o/--output TEXT (required), -r/--radius FLOAT, --add-to-project
cloud density
Compute point density scalar field.
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
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.
cli-anything-cloudcompare --project myproject.json cloud segment-cc 0 \
-o /data/components/ --octree-level 8 --min-points 100
cli-anything-cloudcompare --project myproject.json cloud segment-cc 0 \
-o /data/components/ --octree-level 6 --min-points 50 --fmt ply
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.
cli-anything-cloudcompare --project myproject.json cloud merge \
-o /data/merged.las --add-to-project
Options: -o/--output TEXT (required), --add-to-project
cloud mesh-delaunay
Build a 2.5-D Delaunay triangulation mesh from a cloud.
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
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.
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"
Options: -l/--label TEXT
mesh list
List all meshes in the project.
cli-anything-cloudcompare --project myproject.json mesh list
cli-anything-cloudcompare --project myproject.json --json mesh list
mesh sample
Sample a point cloud from a mesh surface.
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
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.
cli-anything-cloudcompare --project myproject.json distance c2c \
--compare 1 --reference 0 -o /data/distances.las
cli-anything-cloudcompare --project myproject.json distance c2c \
--compare 1 --reference 0 -o /data/distances.las \
--split-xyz --octree-level 8 --add-to-project
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.
cli-anything-cloudcompare --project myproject.json distance c2m \
--cloud 0 --mesh 0 -o /data/c2m_dist.las
cli-anything-cloudcompare --project myproject.json distance c2m \
--cloud 0 --mesh 0 -o /data/c2m_dist.las \
--flip-normals --unsigned --add-to-project
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.
cli-anything-cloudcompare --project myproject.json transform apply 0 \
-o /data/transformed.las -m /data/matrix.txt
cli-anything-cloudcompare --project myproject.json transform apply 0 \
-o /data/transformed.las -m /data/matrix.txt --inverse --add-to-project
The matrix file must contain 4 rows of 4 space-separated values:
1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1
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.
cli-anything-cloudcompare --project myproject.json transform icp \
--aligned 1 --reference 0 -o /data/aligned.las
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
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.
cli-anything-cloudcompare export formats
cli-anything-cloudcompare --json export formats
export cloud
Export a cloud to a target format.
cli-anything-cloudcompare --project myproject.json export cloud 0 /data/output.las
cli-anything-cloudcompare --project myproject.json export cloud 0 /data/output.ply -f ply
cli-anything-cloudcompare --project myproject.json export cloud 0 /data/output.las -f las --overwrite
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.
cli-anything-cloudcompare --project myproject.json export mesh 0 /data/model.obj
cli-anything-cloudcompare --project myproject.json export mesh 0 /data/model.stl -f stl --overwrite
Supported presets: obj, stl, ply, bin
Options: -f/--preset TEXT, --overwrite
export batch
Batch export all project clouds to a directory.
cli-anything-cloudcompare --project myproject.json export batch \
-d /data/exports/ -f las
cli-anything-cloudcompare --project myproject.json export batch \
-d /data/exports/ -f ply --overwrite
Options: -d/--output-dir TEXT (required), -f/--preset TEXT, --overwrite
8. info — Installation Info (1 command)
Show CloudCompare installation path and version.
cli-anything-cloudcompare info
cli-anything-cloudcompare --json info
9. repl — Interactive REPL (1 command)
Start the interactive REPL session with history and undo support.
cli-anything-cloudcompare repl
cli-anything-cloudcompare repl -p myproject.json
cli-anything-cloudcompare --project myproject.json
Options: -p/--project TEXT
Inside the REPL, type help to list available commands or session undo to revert the last operation.
Supported File Formats
| Format | Extension | Read | Write | Notes |
|---|
| LAS | .las | ✓ | ✓ | LiDAR standard, supports intensity/RGB |
| LAZ | .laz | ✓ | ✓ | Compressed LAS |
| PLY | .ply | ✓ | ✓ | ASCII or binary |
| PCD | .pcd | ✓ | ✓ | PCL format |
| XYZ | .xyz | ✓ | ✓ | Plain text XYZ |
| ASC | .asc | ✓ | ✓ | ASCII with header |
| CSV | .csv | ✓ | ✓ | Comma-separated |
| E57 | .e57 | ✓ | ✓ | ASTM scanner exchange |
| BIN | .bin | ✓ | ✓ | CloudCompare native binary |
| OBJ | .obj | ✓ | ✓ | Mesh (Wavefront) |
| STL | .stl | ✓ | ✓ | Mesh (3D printing) |
Typical Workflows
Workflow 1: LiDAR Pre-processing Pipeline
P=myproject.json
cli-anything-cloudcompare project new -o $P
cli-anything-cloudcompare --project $P cloud add /data/scan.las
cli-anything-cloudcompare --project $P cloud list
cli-anything-cloudcompare --project $P cloud filter-sor 0 \
-o /data/denoised.las --nb-points 6 --std-ratio 1.0 --add-to-project
cli-anything-cloudcompare --project $P cloud subsample 1 \
-o /data/subsampled.las -m spatial -n 0.05 --add-to-project
cli-anything-cloudcompare --project $P cloud filter-csf 2 \
--ground /data/ground.las --offground /data/objects.las \
--scene relief --add-to-project
cli-anything-cloudcompare --project $P export cloud 3 /data/ground_final.las -f las --overwrite
Workflow 2: Change Detection Between Two Scans
P=compare.json
cli-anything-cloudcompare project new -o $P
cli-anything-cloudcompare --project $P cloud add /data/scan_2023.las
cli-anything-cloudcompare --project $P cloud add /data/scan_2024.las
cli-anything-cloudcompare --project $P transform icp \
--aligned 1 --reference 0 -o /data/aligned_2024.las \
--overlap 90 --add-to-project
cli-anything-cloudcompare --project $P distance c2c \
--compare 2 --reference 0 -o /data/change_map.las --add-to-project
cli-anything-cloudcompare --project $P export cloud 3 /data/change_map_final.las --overwrite
Workflow 3: Height Slice Extraction
P=slice.json
cli-anything-cloudcompare project new -o $P
cli-anything-cloudcompare --project $P cloud add /data/building.las
cli-anything-cloudcompare --project $P cloud sf-filter-z 0 \
-o /data/floor_slice.las --min 2.0 --max 3.0 --add-to-project
cli-anything-cloudcompare --project $P export cloud 1 /data/floor_slice_out.las --overwrite
Workflow 4: Surface Reconstruction
P=mesh.json
cli-anything-cloudcompare project new -o $P
cli-anything-cloudcompare --project $P cloud add /data/terrain.las
cli-anything-cloudcompare --project $P cloud normals 0 \
-o /data/with_normals.ply --level 6 --orientation plus_z --add-to-project
cli-anything-cloudcompare --project $P cloud mesh-delaunay 1 \
-o /data/terrain_mesh.obj --max-edge-length 1.0 --add-to-project
cli-anything-cloudcompare --project $P export mesh 0 /data/terrain_mesh_final.obj --overwrite
Error Handling
| Exit Code | Meaning |
|---|
0 | Success |
1 | General error (see stderr for details) |
2 | Invalid arguments |
Common errors:
For AI Agents
- Always use
--json flag 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-project to build multi-step pipelines without re-loading files
- Use
cloud list --json to discover valid cloud indices before each operation
- Use
export formats --json to discover available format presets
Version
| Component | Version |
|---|
| cli-anything-cloudcompare | 1.0.0 |
| CloudCompare (tested) | 2.13.2 |
| Python (minimum) | 3.10 |