cli-anything-cloudcompare

What this skill does

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