Add SUM Parts reproduction and Seosan Myeongcheon application pipeline
Reproduces the SUM Parts (CVPR 2025) face-labeling benchmark on a single consumer GPU, then applies it to drone-photogrammetry road survey meshes. Verified on RTX 3060 12GB / WSL2 Ubuntu 22.04 / CUDA 11.8 / torch 2.0.1: - CUDA extensions build (pointnet2_batch, pointops, chamfer_dist, emd, subsampling) - PointNet 100 epochs reaches mIoU 17.19, matching the paper's reported 15.1 - OBJ -> PLY conversion round-trips through the model and yields per-point predictions Four upstream source patches, all idempotent, originals preserved: - numpy aliases removed in 1.24 (np.long etc.) and collections ABCs moved in python 3.10 - the blind test split ships label = -1, which crashed ConfusionMatrix - mode=val referenced `epoch` before assignment Documents the traps that cost the most time, including VRAM overflow silently falling back to host RAM on WSL2 (25-100x slowdown, no OOM) and the colour scale mismatch between r/g/b float32 and red/green/blue uint8. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
nbright
@@ -0,0 +1,196 @@
|
||||
# 새 머신에서 시작하기
|
||||
|
||||
RTX 3090(24GB) 머신에서 SUM Parts + PointVector 학습을 재현하는 절차.
|
||||
|
||||
3060(12GB)에서는 VRAM이 모자라 `voxel_max`를 24000으로 낮춰야 했다.
|
||||
**24GB에서는 논문 설정 64000을 그대로 쓴다** — 이게 이 머신으로 옮기는 유일한 이유다.
|
||||
|
||||
---
|
||||
|
||||
## 0. 전제
|
||||
|
||||
| 항목 | 필요 |
|
||||
|---|---|
|
||||
| OS | Windows + WSL2 (Ubuntu 22.04) 또는 네이티브 Linux |
|
||||
| GPU | RTX 3090 24GB, 드라이버가 WSL에서 인식될 것 |
|
||||
| 디스크 | 40GB 이상 여유 (데이터 13GB + 환경 + 체크포인트) |
|
||||
| 계정 | HuggingFace 계정 (데이터 게이트 수락에 필요) |
|
||||
|
||||
WSL이면 `nvidia-smi`가 WSL 안에서 GPU를 보여야 한다. 안 보이면 여기서 멈추고 드라이버부터.
|
||||
|
||||
```bash
|
||||
nvidia-smi # RTX 3090 24576MiB 가 보여야 함
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 클론
|
||||
|
||||
```bash
|
||||
git clone <gitea-url>/sum-parts-test.git
|
||||
cd sum-parts-test
|
||||
```
|
||||
|
||||
스크립트는 경로를 `/mnt/d/MYCLAUDE_PROJECT/sum-parts-test/scripts`로 하드코딩한 곳이 있다.
|
||||
다른 경로에 두면 아래 한 줄로 일괄 치환한다.
|
||||
|
||||
```bash
|
||||
NEW=$(pwd)/scripts
|
||||
grep -rl '/mnt/d/MYCLAUDE_PROJECT/sum-parts-test/scripts' scripts/ \
|
||||
| xargs sed -i "s|/mnt/d/MYCLAUDE_PROJECT/sum-parts-test/scripts|$NEW|g"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 환경 구축 (약 40분)
|
||||
|
||||
```bash
|
||||
bash scripts/setup_env.sh # conda + CUDA 11.8 + torch 2.0.1
|
||||
bash scripts/setup_pointnext.sh # 의존성 + CUDA 확장 5종 빌드
|
||||
```
|
||||
|
||||
`setup_env.sh` 안의 `TORCH_CUDA_ARCH_LIST`를 3090에 맞춰야 한다.
|
||||
|
||||
```bash
|
||||
# RTX 3060 = 8.6, RTX 3090 = 8.6 (둘 다 Ampere라 동일, 수정 불필요)
|
||||
# RTX 4090이면 8.9로 변경
|
||||
```
|
||||
|
||||
이어서 업스트림 소스 패치 4건. **전부 멱등이라 여러 번 실행해도 안전하다.**
|
||||
|
||||
```bash
|
||||
bash scripts/patch_numpy_aliases.sh # np.long 등 제거된 별칭 + collections ABC
|
||||
bash scripts/patch_unlabeled_test.sh # 블라인드 test셋의 label=-1 처리
|
||||
bash scripts/patch_val_mode.sh # mode=val 의 UnboundLocalError
|
||||
```
|
||||
|
||||
**게이트 — 통과 못 하면 다음으로 가지 말 것:**
|
||||
|
||||
```bash
|
||||
python scripts/verify_env.py
|
||||
# 기대: ALL OK (확장 6종 import + openpoints 체인 전부)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 데이터 (약 30분)
|
||||
|
||||
HuggingFace 게이트를 **브라우저에서 1회 수동 수락**해야 한다. 자동화 불가.
|
||||
|
||||
1. https://huggingface.co/datasets/gwxgrxhyz/SUM-Parts
|
||||
2. 로그인 → CC BY-NC 4.0 수락
|
||||
3. 토큰을 `~/.cache/huggingface/token`에 두거나 `huggingface-cli login`
|
||||
|
||||
```bash
|
||||
bash scripts/download_data.sh all # 5.3GB 받아 13GB로 전개
|
||||
bash scripts/prepare_full_split.sh # validate/ -> val/ 심볼릭 링크
|
||||
bash scripts/link_data.sh # PointNeXt_bundle/data 연결
|
||||
```
|
||||
|
||||
**게이트:** 세 split이 `24 / 8 / 8`로 집계될 것.
|
||||
|
||||
---
|
||||
|
||||
## 4. VRAM 확인 (5분) — 24GB에서 반드시 먼저
|
||||
|
||||
논문 설정이 실제로 들어가는지 확인한다. 3060에서는 여기서 실패했다.
|
||||
|
||||
```bash
|
||||
CFG=pointvector-xl ITERS=5 bash scripts/sweep_voxel_max.sh 40000 48000 64000
|
||||
```
|
||||
|
||||
기대 결과 (3090 24GB):
|
||||
|
||||
| voxel_max | peak VRAM | 판정 |
|
||||
|---|---|---|
|
||||
| 64000 | 약 16.5G | ✅ 들어감 |
|
||||
|
||||
**`fits? = yes`가 나와야 한다.** `NO (spilling)`이면 그 값은 쓰면 안 된다.
|
||||
|
||||
> ⚠️ **WSL2에서 VRAM 초과는 OOM을 내지 않는다.** 드라이버가 호스트 RAM으로 흘려서
|
||||
> 학습이 **조용히 완주한다 — 25~100배 느리게.** 반드시 peak VRAM 수치로 판정할 것.
|
||||
> 판별 보조 지표는 **전력**: 사용률 100%인데 전력이 낮으면 연산이 아니라 PCIe 전송 대기다.
|
||||
|
||||
---
|
||||
|
||||
## 5. 학습 (논문 설정, 약 3~5시간)
|
||||
|
||||
```bash
|
||||
CFG_VOXEL_MAX=64000 VAL_VOXEL_MAX=64000 \
|
||||
bash scripts/launch_overnight.sh pointvector-xl
|
||||
```
|
||||
|
||||
`setsid nohup`으로 분리 실행되므로 터미널·세션을 닫아도 살아남는다.
|
||||
크래시하면 최신 체크포인트에서 자동 재개한다(최대 8회).
|
||||
|
||||
진행 확인:
|
||||
|
||||
```bash
|
||||
bash scripts/check_training.sh # epoch, GPU, best miou
|
||||
bash scripts/verify_speed.sh # HEALTHY / DEGRADED 판정
|
||||
bash scripts/epoch_timing.sh # epoch별 소요시간, 감속 지점 특정
|
||||
```
|
||||
|
||||
중단:
|
||||
|
||||
```bash
|
||||
bash scripts/stop_training.sh # 워치독 먼저 죽여서 자동 재시작 방지
|
||||
```
|
||||
|
||||
**게이트:** `verify_speed.sh`가 `HEALTHY`, peak VRAM이 카드 용량의 95% 미만.
|
||||
|
||||
---
|
||||
|
||||
## 6. 평가
|
||||
|
||||
```bash
|
||||
bash scripts/final_eval.sh # val(라벨 있음) + test(블라인드, 예측만)
|
||||
bash scripts/eval_coarse.sh # 4클래스 통합 성적 ← 우리 과제 기준
|
||||
```
|
||||
|
||||
`eval_coarse.sh`가 실제로 중요한 수치를 낸다. SUM 13클래스를
|
||||
건물 / 수목 / 차량 / 지면으로 합쳐서 채점한다.
|
||||
|
||||
**게이트:** 통합 mIoU가 **"전부 건물" 무지성 분류기(IoU 약 67%)를 이길 것.**
|
||||
절대값이 아니라 baseline 대비로 판정한다.
|
||||
|
||||
---
|
||||
|
||||
## 참고 — 3060 실측값 (비교 기준)
|
||||
|
||||
| 모델 | voxel_max | peak VRAM | s/iter | 100 epoch |
|
||||
|---|---|---|---|---|
|
||||
| pointnet | 64000 | 6.01G | 0.291 | 2.9h |
|
||||
| pointnet++msg | 64000 | 4.16G | 0.675 | 6.8h |
|
||||
| pointvector-xl | 24000 | 6.46G | 0.402 | 2.9h |
|
||||
| pointvector-xl | 64000 | **16.49G** | 13.113 | ❌ 12GB 불가 |
|
||||
| pointnext-xl | 32000 | 8.03G | 0.635 | 6.4h |
|
||||
| pointnext-xl | 64000 | **15.47G** | 46.980 | ❌ 12GB 불가 |
|
||||
|
||||
논문 보고치 (face 트랙, 12클래스):
|
||||
|
||||
| 모델 | mIoU |
|
||||
|---|---|
|
||||
| PointNet | 15.1% |
|
||||
| PointNet++ | 33.1% |
|
||||
| PointNeXt | 65.3% |
|
||||
| **PointVector** | **70.0%** |
|
||||
|
||||
3060에서 pointnet 100 epoch 실측 = **17.19%** (논문 15.1%와 근사, 재현 확인됨).
|
||||
|
||||
---
|
||||
|
||||
## 알려진 제약
|
||||
|
||||
- **test 세트는 블라인드다.** 라벨이 전부 `-1`이라 로컬 채점이 불가능하다.
|
||||
논문 수치와 직접 대조하려면 예측을 저자(gaoweixiaocuhk@gmail.com)에게 보내야 한다.
|
||||
- **`voxel_max`는 중립적 손잡이가 아니다.** 모델의 동작점 일부다.
|
||||
같은 체크포인트가 검증 프로토콜에 따라 mIoU 17.19 / 4.20으로 갈렸다.
|
||||
- **라이선스**: 데이터 CC BY-NC 4.0, 코드 GPL-3.0. 상업 이용은 저자 허락 필요.
|
||||
|
||||
---
|
||||
|
||||
## 상세 기록
|
||||
|
||||
- [docs/SUM-Parts-검토노트.md](docs/SUM-Parts-검토노트.md) — 트러블슈팅 16건, 실측 데이터 스키마, 라이선스 검토
|
||||
- [docs/pipeline.html](docs/pipeline.html) — 전체 공정 정의 (브라우저로 열 것)
|
||||
Reference in New Issue
Block a user