cli-anything-cloudcompare

cli-anything-cloudcompare은(는) 무엇을 하나요?

CloudCompare를 위한 에이전트 친화적 명령줄 도구 — 오픈소스 3D 포인트 클라우드 및 메시 처리 소프트웨어입니다.

9개 그룹의 41개 명령을 제공합니다.

설치

pip install cli-anything-cloudcompare

필수 조건:

• Python 3.10+
• 시스템에 CloudCompare가 설치되어 있어야 함
  • Linux (Flatpak): flatpak install flathub org.cloudcompare.CloudCompare
  • macOS/Windows: https://cloudcompare.org 에서 다운로드

테스트 환경: CloudCompare 2.13.2 (Flatpak, Linux)

전역 옵션

이 옵션들은 서브커맨드 앞에 위치해야 합니다:

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

옵션	설명
-p, --project TEXT	프로젝트 JSON 파일 경로
--json	결과를 JSON으로 출력 (에이전트 사용 용이)

명령 그룹

1. project — 프로젝트 관리 (3개 명령)

project new

새로운 빈 프로젝트 파일을 생성합니다.

# 기본 이름으로 프로젝트 생성
cli-anything-cloudcompare project new -o myproject.json

# 사용자 지정 이름으로 프로젝트 생성
cli-anything-cloudcompare project new -o myproject.json -n "Bridge Survey 2024"

# 에이전트용 JSON 출력
cli-anything-cloudcompare --json project new -o myproject.json

옵션: -o/--output TEXT (필수), -n/--name TEXT

project info

프로젝트 정보 및 로드된 엔티티를 표시합니다.

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

# JSON 출력
cli-anything-cloudcompare --project myproject.json --json project info

project status

프로젝트의 빠른 상태 (클라우드 개수, 메시 개수, 마지막 작업)를 표시합니다.

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

---

2. session — 세션 관리 (4개 명령)

session save

현재 프로젝트 상태를 디스크에 저장합니다.

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

session history

최근 작업 기록을 표시합니다.

# 마지막 10개 작업 표시 (기본값)
cli-anything-cloudcompare --project myproject.json session history

# 마지막 5개 작업 표시
cli-anything-cloudcompare --project myproject.json session history -n 5

옵션: -n/--last INTEGER

session set-format

향후 작업에 사용할 기본 내보내기 형식을 업데이트합니다.

# 기본 클라우드 내보내기를 LAS로 설정
cli-anything-cloudcompare --project myproject.json session set-format --cloud-fmt LAS --cloud-ext las

# 기본 메시 내보내기를 OBJ로 설정
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

옵션: --cloud-fmt TEXT, --cloud-ext TEXT, --mesh-fmt TEXT, --mesh-ext TEXT

session undo

기록에서 마지막 작업을 제거합니다 (소프트 실행 취소 — 출력 파일은 삭제하지 않음).

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

---

3. cloud — 포인트 클라우드 연산 (21개 명령)

모든 클라우드 명령은 CLOUD_INDEX (0부터 시작하는 정수, cloud list로 확인)를 인수로 받으며, 대부분 --add-to-project를 지원하여 출력을 프로젝트에 다시 등록합니다.

cloud add

포인트 클라우드 파일을 프로젝트에 추가합니다.

# LAS 파일 추가
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"

옵션: -l/--label TEXT

cloud list

프로젝트에 있는 모든 클라우드를 나열합니다.

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

# 인덱스 파싱을 위한 JSON 출력
cli-anything-cloudcompare --project myproject.json --json cloud list

cloud convert

클라우드를 한 형식에서 다른 형식으로 변환합니다 (형식은 파일 확장자로 결정됨).

# 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

RANDOM, SPATIAL 또는 OCTREE 방법을 사용하여 포인트 수를 줄입니다.

# 무작위: 100,000 포인트 유지
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
  -o /data/sub_random.las -m random -n 100000

# 공간: 포인트 간 최소 거리 0.05m
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
  -o /data/sub_spatial.las -m spatial -n 0.05

# 옥트리: 레벨 8
cli-anything-cloudcompare --project myproject.json cloud subsample 0 \
  -o /data/sub_octree.las -m octree -n 8 --add-to-project

옵션: -o/--output TEXT (필수), -m/--method [random|spatial|octree], -n/--param FLOAT, --add-to-project

cloud crop

축 정렬 경계 상자를 기준으로 클라우드를 자릅니다.

# 상자 안쪽 포인트 유지
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

옵션: -o/--output TEXT (필수), --xmin/ymin/zmin/xmax/ymax/zmax FLOAT (모두 필수), --outside, --add-to-project

cloud normals

옥트리 방법을 통해 표면 법선을 계산합니다.

# 옥트리 레벨 6에서 법선 계산
cli-anything-cloudcompare --project myproject.json cloud normals 0 \
  -o /data/with_normals.ply --level 6

# +Z 방향으로 법선 계산
cli-anything-cloudcompare --project myproject.json cloud normals 0 \
  -o /data/with_normals.ply --level 6 --orientation plus_z --add-to-project

옵션: -o/--output TEXT (필수), --level INTEGER (1–10), --orientation [plus_x|plus_y|plus_z|minus_x|minus_y|minus_z], --add-to-project

cloud invert-normals

클라우드의 모든 법선 벡터를 뒤집습니다.

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

옵션: -o/--output TEXT (필수), --add-to-project

cloud filter-sor

통계적 이상치 제거 — 고립된 노이즈 포인트를 제거합니다.

# 기본 매개변수 (k=6 이웃, 1.0 표준편차 비율)
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

옵션: -o/--output TEXT (필수), --nb-points INTEGER, --std-ratio FLOAT, --add-to-project

cloud noise-filter

PCL 노이즈 필터(KNN 또는 반경 모드)를 사용하여 노이즈가 있는 포인트를 제거합니다.

# KNN 모드 (기본값)
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

옵션: -o/--output TEXT (필수), --knn INTEGER, --noisiness FLOAT, --radius FLOAT, --use-radius, --absolute, --add-to-project

cloud filter-csf

CSF(Cloth Simulation Filter) 알고리즘을 사용한 지면 필터링. 지면과 비지면 포인트(건물, 식생)를 분리합니다.

# 지면만 추출 — 혼합 지형
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

옵션: -g/--ground TEXT (필수), -u/--offground TEXT, --scene [slope|relief|flat], --cloth-resolution FLOAT, --class-threshold FLOAT, --max-iteration INTEGER, --proc-slope, --add-to-project

cloud filter-sf

스칼라 필드 값 범위로 클라우드를 필터링합니다 (포인트 유지 조건: SF ∈ [min, max]).

# SF 값이 10과 50 사이인 포인트 유지
cli-anything-cloudcompare --project myproject.json cloud filter-sf 0 \
  -o /data/filtered.las --min 10.0 --max 50.0

# 특정 SF 인덱스를 사용하여 필터링
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

옵션: -o/--output TEXT (필수), --min FLOAT (필수), --max FLOAT (필수), --sf-index INTEGER, --add-to-project

cloud sf-from-coord

좌표 축(X/Y/Z)을 스칼라 필드로 변환합니다. 일반적으로 높이(Z) 스칼라 필드를 만드는 데 사용됩니다.

# Z 스칼라 필드(높이) 생성
cli-anything-cloudcompare --project myproject.json cloud sf-from-coord 0 \
  -o /data/with_z_sf.las --dim z --add-to-project

# 특정 활성 인덱스를 사용하여 X 스칼라 필드 생성
cli-anything-cloudcompare --project myproject.json cloud sf-from-coord 0 \
  -o /data/with_x_sf.las --dim x --sf-index 0

옵션: -o/--output TEXT (필수), --dim [x|y|z] (기본값: z), --sf-index INTEGER, --add-to-project

cloud sf-filter-z

편의 명령: Z → 스칼라 필드 변환 후 높이 범위로 필터링을 한 번에 수행합니다.

# z=1.0m와 z=2.5m 사이의 포인트 추출
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

옵션: -o/--output TEXT (필수), --min FLOAT, --max FLOAT, --add-to-project

cloud sf-to-rgb

활성 스칼라 필드를 RGB 색상으로 변환합니다.

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

옵션: -o/--output TEXT (필수), --add-to-project

cloud rgb-to-sf

RGB 색상을 스칼라 필드(휘도 값)로 변환합니다.

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

옵션: -o/--output TEXT (필수), --add-to-project

cloud curvature

곡률 스칼라 필드(MEAN 또는 GAUSS)를 계산합니다.

# 반경 0.5m에서 평균 곡률
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

옵션: -o/--output TEXT (필수), --type [mean|gauss], -r/--radius FLOAT, --add-to-project

cloud roughness

거칠기 스칼라 필드(국소 최적 적합 평면으로부터의 편차)를 계산합니다.

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

옵션: -o/--output TEXT (필수), -r/--radius FLOAT, --add-to-project

cloud density

포인트 밀도 스칼라 필드를 계산합니다.

# KNN 밀도
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

옵션: -o/--output TEXT (필수), -r/--radius FLOAT, --type [knn|surface|volume], --add-to-project

cloud segment-cc

클라우드를 연결된 구성 요소(클러스터)로 분할합니다. 각 구성 요소는 별도의 파일로 저장됩니다.

# 옥트리 레벨 8, 구성 요소당 최소 100 포인트로 분할
cli-anything-cloudcompare --project myproject.json cloud segment-cc 0 \
  -o /data/components/ --octree-level 8 --min-points 100

# PLY 파일로 구성 요소 저장
cli-anything-cloudcompare --project myproject.json cloud segment-cc 0 \
  -o /data/components/ --octree-level 6 --min-points 50 --fmt ply

옵션: -o/--output-dir TEXT (필수), --octree-level INTEGER, --min-points INTEGER, --fmt TEXT

cloud merge

프로젝트의 모든 클라우드를 단일 클라우드로 병합합니다.

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

옵션: -o/--output TEXT (필수), --add-to-project

cloud mesh-delaunay

클라우드에서 2.5D 들로네 삼각분할 메시를 구축합니다.

# 기본 들로네 메시
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

옵션: -o/--output TEXT (필수), --best-fit, --max-edge-length FLOAT, --add-to-project

---

4. mesh — 메시 연산 (3개 명령)

mesh add

메시 파일을 프로젝트에 추가합니다.

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"

옵션: -l/--label TEXT

mesh list

프로젝트의 모든 메시를 나열합니다.

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

# JSON 출력
cli-anything-cloudcompare --project myproject.json --json mesh list

mesh sample

메시 표면에서 포인트 클라우드를 샘플링합니다.

# 인덱스 0의 메시에서 50,000 포인트 샘플링
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

옵션: -o/--output TEXT (필수), -n/--num-points INTEGER (필수), --add-to-project

---

5. distance — 거리 연산 (2개 명령)

distance c2c (cloud-to-cloud)

두 클라우드 간의 포인트별 거리를 계산합니다.

# 클라우드 0에서 클라우드 1까지의 거리
cli-anything-cloudcompare --project myproject.json distance c2c 0 1 \
  -o /data/distances.las --add-to-project

옵션: -o/--output TEXT (필수), --add-to-project

distance c2m (cloud-to-mesh)

클라우드에서 메시까지의 거리를 계산합니다.

# 클라우드 0에서 메시 0까지의 거리
cli-anything-cloudcompare --project myproject.json distance c2m 0 0 \
  -o /data/c2m_distances.las --add-to-project

옵션: -o/--output TEXT (필수), --add-to-project

---

6. transform — 변환 연산 (2개 명령)

transform icp

반복 최근접점(ICP) 정합을 수행합니다.

# 기본 설정 (플래그 또는 참고) 사용
cli-anything-cloudcompare --project myproject.json transform icp 0 1 \
  -o /data/aligned.las

# 사용자 지정 ICP 설정
cli-anything-cloudcompare --project myproject.json transform icp 0 1 \
  -o /data/aligned.las \
  --max-iter 50 --random-sampling-limit 50000 --min-error-delta 1e-6 \
  --final-overlap 0.9 --adjust-scale --add-to-project

옵션: -o/--output TEXT (필수), --max-iter INTEGER, --random-sampling-limit INTEGER, --min-error-delta FLOAT, --final-overlap FLOAT, --adjust-scale, --add-to-project

transform matrix

클라우드에 4x4 변환 행렬을 적용합니다.

# 행렬 파일에서 변환 적용
cli-anything-cloudcompare --project myproject.json transform matrix 0 \
  /data/transform.mat -o /data/transformed.las

# 행렬을 인라인으로 적용 (4x4 공백 구분)
cli-anything-cloudcompare --project myproject.json transform matrix 0 \
  "1 0 0 2.5  0 1 0 1.0  0 0 1 -0.5  0 0 0 1" \
  -o /data/translated.las --add-to-project

옵션: -o/--output TEXT (필수), --add-to-project

---

7. export — 내보내기 연산 (1개 명령)

export cloud (단일 명령)

클라우드/메시를 일반적인 3D 형식으로 내보냅니다.

# LAS로 클라우드 내보내기
cli-anything-cloudcompare --project myproject.json export cloud 0 /data/export.las

# PLY로 내보내기 (스칼라 필드 포함)
cli-anything-cloudcompare --project myproject.json export cloud 0 /data/export.ply

# E57로 메시 내보내기
cli-anything-cloudcompare --project myproject.json export mesh 0 /data/export.e57

지원 형식: LAS, LAZ, PLY, PCD, OBJ, STL, E57, VTK, FBX, DXF, SHP

---

8. run — 실행 명령 (3개 명령)

run command

임의의 CloudCompare 명령줄 플래그를 실행합니다.

# 정밀 스칼라 필드 비교 실행
cli-anything-cloudcompare --project myproject.json run command \
  "-COMPUTE_COMPARISON" --args 0 1

# 볼륨 밀도 계산 (CloudCompare 2.13+)
cli-anything-cloudcompare --project myproject.json run command \
  "-DENSITY" --args 0 "VOLUME" "0.5"

옵션: --args TEXT... (선택 사항)

run macro

CloudCompare XML 매크로 파일을 실행합니다.

cli-anything-cloudcompare --project myproject.json run macro /path/to/macro.xml

run custom

CloudCompare 명령줄에 직접 전달할 사용자 지정 플래그를 실행합니다.

cli-anything-cloudcompare run custom -CUSTOM_FLAG arg1 arg2

---

9. experimental — 실험적 명령 (3개 명령)

experimental repl

대화형 CloudCompare REPL을 시작합니다.

cli-anything-cloudcompare experimental repl

experimental batch

점진적 구문 분석을 사용하여 대화형 일괄 처리 세션을 시작합니다.

cli-anything-cloudcompare experimental batch

experimental pipe

파이프라인 정의 JSON 파일을 실행합니다.

cli-anything-cloudcompare experimental pipe /path/to/pipeline.json