cli-anything-cloudcompare

O que cli-anything-cloudcompare faz?

Invocador de linha de comando amigável para agentes de CloudCompare — o software open-source de processamento de nuvem de pontos e malhas 3D.

41 comandos em 9 grupos.

Instalação

pip install cli-anything-cloudcompare

Pré-requisitos:

• Python 3.10+
• CloudCompare instalado no seu sistema
  • Linux (Flatpak): flatpak install flathub org.cloudcompare.CloudCompare
  • macOS/Windows: baixe de https://cloudcompare.org

Testado com: CloudCompare 2.13.2 (Flatpak, Linux)

Opções Globais

Estas opções devem ser colocadas antes do subcomando:

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

Opção	Descrição
-p, --project TEXT	Caminho para o arquivo de projeto JSON
--json	Saída dos resultados como JSON (para consumo pelo agente)

Grupos de Comandos

1. project — Gerenciamento de Projeto (3 comandos)

project new

Criar um novo arquivo de projeto vazio.

# Criar um projeto com nome padrão
cli-anything-cloudcompare project new -o myproject.json

# Criar um projeto com nome personalizado
cli-anything-cloudcompare project new -o myproject.json -n "Bridge Survey 2024"

# Saída JSON para agentes
cli-anything-cloudcompare --json project new -o myproject.json

Opções: -o/--output TEXT (obrigatório), -n/--name TEXT

project info

Mostrar informações do projeto e entidades carregadas.

cli-anything-cloudcompare --project myproject.json project info

# Saída JSON
cli-anything-cloudcompare --project myproject.json --json project info

project status

Mostrar status rápido do projeto (contagem de nuvens, contagem de malhas, última operação).

cli-anything-cloudcompare --project myproject.json project status

---

2. session — Gerenciamento de Sessão (4 comandos)

session save

Salvar o estado atual do projeto no disco.

cli-anything-cloudcompare --project myproject.json session save

session history

Mostrar histórico recente de operações.

# Mostrar as últimas 10 operações (padrão)
cli-anything-cloudcompare --project myproject.json session history

# Mostrar as últimas 5 operações
cli-anything-cloudcompare --project myproject.json session history -n 5

Opções: -n/--last INTEGER

session set-format

Atualizar o formato de exportação padrão para operações futuras.

# Definir exportação padrão de nuvem como LAS
cli-anything-cloudcompare --project myproject.json session set-format --cloud-fmt LAS --cloud-ext las

# Definir exportação padrão de malha como OBJ
cli-anything-cloudcompare --project myproject.json session set-format --mesh-fmt OBJ --mesh-ext obj

# Definir padrões para nuvem e malha
cli-anything-cloudcompare --project myproject.json session set-format \
  --cloud-fmt PLY --cloud-ext ply \
  --mesh-fmt STL --mesh-ext stl

Opções: --cloud-fmt TEXT, --cloud-ext TEXT, --mesh-fmt TEXT, --mesh-ext TEXT

session undo

Remover a última operação do histórico (desfazer suave — não exclui arquivos de saída).

cli-anything-cloudcompare --project myproject.json session undo

---

3. cloud — Operações em Nuvem de Pontos (21 comandos)

Todos os comandos de nuvem recebem CLOUD_INDEX (inteiro baseado em 0 de cloud list) e a maioria aceita --add-to-project para registrar a saída de volta no projeto.

cloud add

Adicionar um arquivo de nuvem de pontos ao projeto.

# Adicionar um arquivo LAS
cli-anything-cloudcompare --project myproject.json cloud add /data/scan.las

# Adicionar com um rótulo
cli-anything-cloudcompare --project myproject.json cloud add /data/scan.las -l "roof scan"

Opções: -l/--label TEXT

cloud list

Listar todas as nuvens atualmente no projeto.

cli-anything-cloudcompare --project myproject.json cloud list

# Saída JSON para análise de índices
cli-anything-cloudcompare --project myproject.json --json cloud list

cloud convert

Converter uma nuvem de um formato para outro (formato determinado pela extensão do arquivo).

# 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

Reduzir o número de pontos usando o método RANDOM, SPATIAL ou OCTREE.

# Aleatório: manter 100.000 pontos
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
  -o /data/sub_random.las -m random -n 100000

# Espacial: distância mínima de 0,05 m entre pontos
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
  -o /data/sub_spatial.las -m spatial -n 0.05

# Octree: nível 8
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
  -o /data/sub_octree.las -m octree -n 8 --add-to-project

Opções: -o/--output TEXT (obrigatório), -m/--method [random|spatial|octree], -n/--param FLOAT, --add-to-project

cloud crop

Recortar uma nuvem para uma caixa delimitadora alinhada aos eixos.

# Manter pontos dentro da caixa
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

# Manter pontos FORA da caixa
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

Opções: -o/--output TEXT (obrigatório), --xmin/ymin/zmin/xmax/ymax/zmax FLOAT (todos obrigatórios), --outside, --add-to-project

cloud normals

Calcular normais de superfície pelo método octree.

# Calcular normais no nível octree 6
cli-anything-cloudcompare --project myproject.json cloud normals 0 \
  -o /data/with_normals.ply --level 6

# Calcular normais orientadas para +Z
cli-anything-cloudcompare --project myproject.json cloud normals 0 \
  -o /data/with_normals.ply --level 6 --orientation plus_z --add-to-project

Opções: -o/--output TEXT (obrigatório), --level INTEGER (1–10), --orientation [plus_x|plus_y|plus_z|minus_x|minus_y|minus_z], --add-to-project

cloud invert-normals

Inverter todos os vetores normais na nuvem.

cli-anything-cloudcompare --project myproject.json cloud invert-normals 0 \
  -o /data/flipped_normals.ply --add-to-project

Opções: -o/--output TEXT (obrigatório), --add-to-project

cloud filter-sor

Filtro de Remoção de Outlier Estatístico (SOR) — remove pontos de ruído isolados.

# Parâmetros padrão (k=6 vizinhos, razão std 1,0)
cli-anything-cloudcompare --project myproject.json cloud filter-sor 0 \
  -o /data/denoised.las

# Parâmetros personalizados
cli-anything-cloudcompare --project myproject.json cloud filter-sor 0 \
  -o /data/denoised.las --nb-points 12 --std-ratio 2.0 --add-to-project

Opções: -o/--output TEXT (obrigatório), --nb-points INTEGER, --std-ratio FLOAT, --add-to-project

cloud noise-filter

Remover pontos ruidosos usando o filtro de ruído PCL (modo KNN ou raio).

# Modo KNN (padrão)
cli-anything-cloudcompare --project myproject.json cloud noise-filter 0 \
  -o /data/clean.las --knn 8 --noisiness 1.0

# Modo raio
cli-anything-cloudcompare --project myproject.json cloud noise-filter 0 \
  -o /data/clean.las --radius 0.1 --use-radius --add-to-project

Opções: -o/--output TEXT (obrigatório), --knn INTEGER, --noisiness FLOAT, --radius FLOAT, --use-radius, --absolute, --add-to-project

cloud filter-csf

Filtragem de solo usando o algoritmo CSF (Cloth Simulation Filter). Separa o solo de pontos não-solo (edifícios, vegetação).

# Extrair apenas o solo — terreno misto
cli-anything-cloudcompare --project myproject.json cloud filter-csf 0 \
  --ground /data/ground.las --scene relief

# Dividir solo + não-solo — cena urbana
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

# Encosta íngreme e florestada com pós-processamento de declive
cli-anything-cloudcompare --project myproject.json cloud filter-csf 0 \
  --ground /data/terrain.las --scene slope --proc-slope --add-to-project

Opções: -g/--ground TEXT (obrigatório), -u/--offground TEXT, --scene [slope|relief|flat], --cloth-resolution FLOAT, --class-threshold FLOAT, --max-iteration INTEGER, --proc-slope, --add-to-project

cloud filter-sf

Filtrar uma nuvem por intervalo de valores de campo escalar (manter pontos onde SF ∈ [min, max]).

# Manter pontos com valor SF entre 10 e 50
cli-anything-cloudcompare --project myproject.json cloud filter-sf 0 \
  -o /data/filtered.las --min 10.0 --max 50.0

# Filtrar usando um índice SF específico
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

Opções: -o/--output TEXT (obrigatório), --min FLOAT (obrigatório), --max FLOAT (obrigatório), --sf-index INTEGER, --add-to-project

cloud sf-from-coord

Converter um eixo de coordenada (X/Y/Z) em um campo escalar. Comumente usado para criar um campo escalar de altura (Z).

# Criar campo escalar Z (altura)
cli-anything-cloudcompare --project myproject.json cloud sf-from-coord 0 \
  -o /data/with_z_sf.las --dim z --add-to-project

# Criar campo escalar X com um índice ativo específico
cli-anything-cloudcompare --project myproject.json cloud sf-from-coord 0 \
  -o /data/with_x_sf.las --dim x --sf-index 0

Opções: -o/--output TEXT (obrigatório), --dim [x|y|z] (padrão: z), --sf-index INTEGER, --add-to-project

cloud sf-filter-z

Comando de conveniência: converter Z → campo escalar e filtrar por intervalo de altura em uma única etapa.

# Extrair pontos entre z=1,0 m e 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

# Apenas aplicar limite superior
cli-anything-cloudcompare --project myproject.json cloud sf-filter-z 0 \
  -o /data/below_5m.las --max 5.0

Opções: -o/--output TEXT (obrigatório), --min FLOAT, --max FLOAT, --add-to-project

cloud sf-to-rgb

Converter o campo escalar ativo em cores RGB.

cli-anything-cloudcompare --project myproject.json cloud sf-to-rgb 0 \
  -o /data/coloured.ply --add-to-project

Opções: -o/--output TEXT (obrigatório), --add-to-project

cloud rgb-to-sf

Converter cores RGB em um campo escalar (valor de luminância).

cli-anything-cloudcompare --project myproject.json cloud rgb-to-sf 0 \
  -o /data/luminance.las --add-to-project

Opções: -o/--output TEXT (obrigatório), --add-to-project

cloud curvature

Calcular campo escalar de curvatura (MEAN ou GAUSS).

# Curvatura média com raio 0,5 m
cli-anything-cloudcompare --project myproject.json cloud curvature 0 \
  -o /data/curvature.las --type mean --radius 0.5

# Curvatura Gaussiana
cli-anything-cloudcompare --project myproject.json cloud curvature 0 \
  -o /data/curvature.las --type gauss --radius 0.5 --add-to-project

Opções: -o/--output TEXT (obrigatório), --type [mean|gauss], -r/--radius FLOAT, --add-to-project

cloud roughness

Calcular campo escalar de rugosidade (desvio do plano de melhor ajuste local).

cli-anything-cloudcompare --project myproject.json cloud roughness 0 \
  -o /data/roughness.las --radius 0.2 --add-to-project

Opções: -o/--output TEXT (obrigatório), -r/--radius FLOAT, --add-to-project

cloud density

Calcular campo escalar de densidade de pontos.

# Densidade KNN
cli-anything-cloudcompare --project myproject.json cloud density 0 \
  -o /data/density.las --type knn --radius 0.5

# Densidade de superfície
cli-anything-cloudcompare --project myproject.json cloud density 0 \
  -o /data/density.las --type surface --radius 1.0 --add-to-project

Opções: -o/--output TEXT (obrigatório), -r/--radius FLOAT, --type [knn|surface|volume], --add-to-project

cloud segment-cc

Segmentar nuvem em componentes conectados (clusters). Cada componente é salvo como um arquivo separado.

# Segmentar com nível octree 8, mínimo de 100 pontos por componente
cli-anything-cloudcompare --project myproject.json cloud segment-cc 0 \
  -o /data/components/ --octree-level 8 --min-points 100

# Salvar componentes como arquivos PLY
cli-anything-cloudcompare --project myproject.json cloud segment-cc 0 \
  -o /data/components/ --octree-level 6 --min-points 50 --fmt ply

Opções: -o/--output-dir TEXT (obrigatório), --octree-level INTEGER, --min-points INTEGER, --fmt TEXT

cloud merge

Mesclar todas as nuvens no projeto em uma única nuvem.

cli-anything-cloudcompare --project myproject.json cloud merge \
  -o /data/merged.las --add-to-project

Opções: -o/--output TEXT (obrigatório), --add-to-project

cloud mesh-delaunay

Construir uma malha de triangulação de Delaunay 2,5 D a partir de uma nuvem.

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

# Plano de melhor ajuste com limite de comprimento máximo de aresta
cli-anything-cloudcompare --project myproject.json cloud mesh-delaunay 0 \
  -o /data/surface.ply --best-fit --max-edge-length 2.0 --add-to-project

Opções: -o/--output TEXT (obrigatório), --best-fit, --max-edge-length FLOAT, --add-to-project

---

4. mesh — Operações em Malha (3 comandos)

mesh add

Adicionar um arquivo de malha ao projeto.

cli-anything-cloudcompare --project myproject.json mesh add /data/model.obj

# Adicionar com rótulo
cli-anything-cloudcompare --project myproject.json mesh add /data/model.ply -l "building model"

Opções: -l/--label TEXT

mesh list

Listar todas as malhas no projeto.

cli-anything-cloudcompare --project myproject.json mesh list

# Saída JSON
cli-anything-cloudcompare --project myproject.json --json mesh list

mesh sample

Amostrar uma nuvem de pontos a partir de uma superfície de malha.

# Amostrar 50.000 pontos da malha no índice 0
cli-anything-cloudcompare --project myproject.json mesh sample 0 \
  -o /data/sampled.las -n 50000

# Adicionar nuvem amostrada de volta ao projeto
cli-anything-cloudcompare --project myproject.json mesh sample 0 \
  -o /data/sampled.las -n 100000 --add-to-project

Opções: -o/--output TEXT (obrigatório), -n/--count INTEGER (obrigatório), --add-to-project

---

5. distance — Cálculo de Distâncias (2 comandos)

distance c2c

Distância Cloud-to-Cloud (nuvem a nuvem). Para cada ponto na nuvem de referência, encontrar o ponto mais próximo na nuvem comparada e registrar a distância.

# Distância C2C local (preenchimento de vizinho mais próximo)
cli-anything-cloudcompare --project myproject.json distance c2c 0 1 \
  -o /data/distances.las

# Aproximação de casca grossa (mais rápida para nuvens grandes)
cli-anything-cloudcompare --project myproject.json distance c2c 0 1 \
  -o /data/distances.las --max-dist 1.0 --add-to-project

Opções: -o/--output TEXT (obrigatório), --max-dist FLOAT, --add-to-project

distance c2m

Distância Cloud-to-Mesh (nuvem a malha). Calcular a distância de cada ponto na nuvem de referência para a superfície da malha de referência.

# Distância C2M com malha no índice 0
cli-anything-cloudcompare --project myproject.json distance c2m 0 0 \
  -o /data/c2m_distances.las

# Incluir resultado no projeto
cli-anything-cloudcompare --project myproject.json distance c2m 0 0 \
  -o /data/c2m_distances.las --add-to-project

Opções: -o/--output TEXT (obrigatório), --add-to-project

---

6. align — Alinhamento e Transformações (3 comandos)

align icp

Registro de nuvem de pontos usando o algoritmo Iterative Closest Point (ICP).

# Alinhar nuvem 1 para nuvem 0, 50 iterações máx, tolerância RMS 1e-5
cli-anything-cloudcompare --project myproject.json align icp 0 1 \
  -o /data/aligned.las --iterations 50 --rms-tolerance 1e-5

# Usar subamostragem aleatória (amostrar 20.000 pontos por iteração)
cli-anything-cloudcompare --project myproject.json align icp 0 1 \
  -o /data/aligned.las --sample-count 20000 --add-to-project

Opções: -o/--output TEXT (obrigatório), -i/--iterations INTEGER, -r/--rms-tolerance FLOAT, -s/--sample-count INTEGER, --add-to-project

align apply-matrix

Aplicar uma matriz de transformação 4×4 a uma nuvem ou malha.

# Aplicar transformação a partir de um arquivo de matriz
echo "0.999 -0.013 0.008 0.5; 0.013 0.999 0.005 -0.3; -0.008 -0.005 0.999 1.2; 0 0 0 1" > transform.txt
cli-anything-cloudcompare --project myproject.json align apply-matrix 0 \
  -o /data/transformed.las --matrix-file transform.txt

# Especificar matriz diretamente
cli-anything-cloudcompare --project myproject.json align apply-matrix 0 \
  -o /data/translated.las --matrix "1 0 0 2.5; 0 1 0 0.0; 0 0 1 0.0; 0 0 0 1"

Opções: -o/--output TEXT (obrigatório), --matrix-file PATH, --matrix TEXT, --add-to-project

align merge-entities

Mesclar todas as nuvens e malhas após o alinhamento.

cli-anything-cloudcompare --project myproject.json align merge-entities \
  -o /data/merged_scene.las --add-to-project

Opções: -o/--output TEXT (obrigatório), --add-to-project

---

7. export — Exportação (3 comandos)

export cloud

Exportar uma nuvem para um formato de arquivo suportado (Las/LAZ/PLY/PCD/E57).

# Exportar como LAS
cli-anything-cloudcompare --project myproject.json export cloud 0 \
  /data/exported.las

# Exportar como LAZ (LAS comprimido)
cli-anything-cloudcompare --project myproject.json export cloud 0 \
  /data/exported.laz

# Exportar para um caminho diferente com novo nome
cli-anything-cloudcompare --project myproject.json export cloud 0 \
  /output/archive/scan.ply

Opções: -o PATH (obrigatório, posicional)

export mesh

Exportar uma malha para um formato de arquivo suportado (OBJ/STL/PLY).

# Exportar como OBJ
cli-anything-cloudcompare --project myproject.json export mesh 0 \
  /data/model.obj

# Exportar como STL
cli-anything-cloudcompare --project myproject.json export mesh 0 \
  /data/model.stl

Opções: -o PATH (obrigatório, posicional)

export all

Exportar todas as entidades do projeto para um diretório.

# Exportar tudo para diretório com nomes de arquivo padrão
cli-anything-cloudcompare --project myproject.json export all /output/dir/

# Exportar com prefixo personalizado
cli-anything-cloudcompare --project myproject.json export all /output/dir/ --prefix "bridge_"

Opções: -o DIR (obrigatório, posicional), --prefix TEXT

---

8. info — Consultas de Entidade (3 comandos)

info cloud

Mostrar informações detalhadas sobre uma nuvem.

cli-anything-cloudcompare --project myproject.json info cloud 0

# Saída JSON para o agente
cli-anything-cloudcompare --project myproject.json --json info cloud 0

Opções: CLOUD_INDEX (obrigatório, posicional)

info mesh

Mostrar informações detalhadas sobre uma malha.

cli-anything-cloudcompare --project myproject.json info mesh 0

# Saída JSON
cli-anything-cloudcompare --project myproject.json --json info mesh 0

Opções: MESH_INDEX (obrigatório, posicional)

info summary

Mostrar um resumo geral do projeto (contagens, extensão, última ação).

cli-anything-cloudcompare --project myproject.json info summary

# Saída JSON
cli-anything-cloudcompare --project myproject.json --json info summary

---

9. repl — Modo REPL Interativo (1 comando)

Inicie um shell interativo onde todos os comandos de cli-anything-cloudcompare estão disponíveis sem o prefixo cli-anything-cloudcompare.

cli-anything-cloudcompare repl --project myproject.json

Exemplo de sessão REPL:

> cloud list
> cloud add /data/new_scan.las -l "roof"
> cloud filter-sor 0 -o /data/denoised.las
> export cloud 1 /data/exported.ply
> session history
> exit

Opções: --project TEXT, --json

---

Exemplo de Uso

Pipeline de processamento LIDAR completo:

# 1. Inicializar projeto
cli-anything-cloudcompare project new -o bridge.lidar -n "Ponte Rio 2024"

# 2. Carregar dados
cli-anything-cloudcompare --project bridge.lidar cloud add /data/scan1.las -l "ponte"
cli-anything-cloudcompare --project bridge.lidar cloud add /data/scan2.las -l "margem"

# 3. Filtrar ruído
cli-anything-cloudcompare --project bridge.lidar cloud filter-sor 0 -o /data/denoised_bridge.las --add-to-project

# 4. Classificar solo vs. não solo
cli-anything-cloudcompare --project bridge.lidar cloud filter-csf 1 --ground /data/ground.las --offground /data/veg.las --scene relief

# 5. Amostrar nuvem de malha
cli-anything-cloudcompare --project bridge.lidar mesh sample 0 -o /data/sampled_pts.las -n 50000 --add-to-project

# 6. Verificar distância entre varreduras
cli-anything-cloudcompare --project bridge.lidar distance c2c 2 3 -o /data/c2c_results.las

# 7. Alinhar varreduras com ICP
cli-anything-cloudcompare --project bridge.lidar align icp 2 3 -o /data/aligned.las --add-to-project

# 8. Exportar produtos finais
cli-anything-cloudcompare --project bridge.lidar export all /output/bridge_pipeline/ --prefix "bridge_"

Licença

MIT