cli-anything-cloudcompare

# cli-anything-cloudcompare Agent-friendly command-line harness for [CloudCompare](https://cloudcompare.org) — the open-source 3D point cloud and mesh processing software. **41 commands** across 9 groups. ## Installation ```bash 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: ```bash 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. ```bash # 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 ``` Options: `-o/--output TEXT` (required), `-n/--name TEXT` #### project info Show project info and loaded entities. ```bash cli-anything-cloudcompare --project myproject.json project info # JSON output cli-anything-cloudcompare --project myproject.json --json project info ``` #### project status Show quick project status (cloud count, mesh count, last operation). ```bash cli-anything-cloudcompare --project myproject.json project status ``` --- ### 2. session — Session Management (4 commands) #### session save Save the current project state to disk. ```bash cli-anything-cloudcompare --project myproject.json session save ``` #### session history Show recent operation history. ```bash # 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 ``` Options: `-n/--last INTEGER` #### session set-format Update the default export format for future operations. ```bash # 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 ``` 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). ```bash 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. ```bash # 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" ``` Options: `-l/--label TEXT` #### cloud list List all clouds currently in the project. ```bash cli-anything-cloudcompare --project myproject.json cloud list # JSON output for parsing indices cli-anything-cloudcompare --project myproject.json --json cloud list ``` #### cloud convert Convert a cloud from one format to another (format determined by file extension). ```bash # 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 Reduce the number of points using RANDOM, SPATIAL, or OCTREE method. ```bash # 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 ``` 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. ```bash # 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 ``` 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. ```bash # 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 ``` 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. ```bash 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. ```bash # 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 ``` 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). ```bash # 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 ``` 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). ```bash # 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 ``` 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]). ```bash # 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 ``` 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. ```bash # 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 ``` 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. ```bash # 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 ``` Options: `-o/--output TEXT` (required), `--min FLOAT`, `--max FLOAT`, `--add-to-project` #### cloud sf-to-rgb Convert the active scalar field to RGB colours. ```bash 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). ```bash 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). ```bash # 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 ``` 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). ```bash cli-anything-cloudcompare --project myproject.json cloud roughness 0 \ -o /data/roughness.las --radius 0.2 --add-to-project ```