scripts

Imported from lusina0304/ZooAnimalShape (scripts/AGENTS.md). Install upstream with npx skills add lusina0304/ZooAnimalShape --skill scripts. Copyright stays with the author.

scripts

목적

105개의 Python 스크립트 모음으로 3D 동물 모델 파이프라인의 전체 작업 흐름을 지원합니다:

• 분류: 종 인식 및 SMAL 모델 피팅
• 데이터 처리: 다운로드, 병합, 검증, 재구성
• 실험: 멀티뷰, 강화학습, 아키텍처 실험
• 피팅: SMAL 메시 피팅 및 형태 최적화
• 보고: 렌더링, 시각화, PDF 생성
• 평가: 파이프라인 단계별 검증
• 생성: 논문 그림, 코드북, 학습 데이터셋

핵심 파일

하위 디렉토리

근본 파일 카테고리

평가 (evaluate_*.py)

• evaluate_v8_pipeline.py — v8 세맨틱 형태 모델 파이프라인 평가
• evaluate_semantic_shape.py — 형태 예측 정확도
• evaluate_awol_comparison.py — AWOL vs GenZoo 비교
• evaluate_clip_alignment.py — CLIP 임베딩 정렬
• evaluate_clip_shape_predictor.py — 텍스트-형태 예측
• evaluate_measurement_ranking.py — PanTHERIA 측정 우선순위
• evaluate_species_preservation.py — 종 보존 제약
• evaluate_e2e_walkthrough.py — 전체 파이프라인 최종 평가
• evaluate_multimodal.py — 멀티모달 임베딩
• evaluate_augmentation_effect.py — 강화 효과
• evaluate_magnitude.py — 형태 크기 일관성

생성 (generate_*.py)

• generate_paper_figures.py — 논문 그림 모음
• generate_nature3d_v8_paper_figures.py — Nature3D v8 논문 그림
• generate_family_standard_models.py — 과(family) 표준 모델
• generate_standard_models.py — 전체 표준 모델
• generate_qualitative_comparison.py — 질적 비교 시각화
• generate_baseline_comparison_figure.py — 베이스라인 비교
• generate_semantic_dataset.py — 학습 데이터셋
• generate_augmentation_dataset.py — 강화 데이터셋
• generate_graded_text_pairs.py — 등급별 텍스트 쌍
• generate_family_prior_145.py — 과 사전 (145차원)
• generate_subfamily_prior.py — 아과 사전

구성/빌드 (build_*.py)

• build_codebook_145.py — 145차원 베타 코드북
• build_mcbo_codebook.py — MCBO 최적화된 코드북
• build_pantheria_full_lookup.py — PanTHERIA 전체 룩업 테이블
• build_shape_codebook.py — 형태 코드북
• build_species_aware_dataset.py — 종 인식 데이터셋
• label_codebook_by_family.py — 코드북 과(family) 레이블링
• expand_codebook_genzoo.py — GenZoo 코드북 확장

학습 (train_*.py)

• train_semantic_shape.py — v6/v8 시맨틱 형태 모델
• train_residual_morph_mlp.py — 잔차 형태 MLP
• train_residual_morph_enhanced.py — 강화된 잔차 형태
• train_magnitude_aware_morph.py — 크기 인식 형태
• train_family_conditioned_mlp.py — 과 조건 MLP
• train_view_aware_mlp.py — 뷰 인식 MLP

테스트 (test_*.py)

• test_smal_gui_*.py (12개) — SMAL GUI 컴포넌트 (카메라, 조인트, 프리뷰, 비디오, 영상, 리타겟팅)
• test_v8_architecture.py — v8 아키텍처 검증
• test_e2e_residual_morph_v3.py — 전체 형태 파이프라인
• test_video_shape_extractor_predictor_init.py — 비디오 형태 추출
• test_measurement_extractor.py — 측정 추출
• test_unified_sample_policy.py — 샘플 정책
• test_species_prior_selector.py — 종 사전 선택
• test_runtime_config_contract.py — 런타임 설정

시각화 (visualize_*.py)

• visualize_shape_space.py — 형태 공간 (PCA/t-SNE)
• visualize_dataset.py — 데이터셋 브라우저
• visualize_dataset_twilight.py — Twilight 색상맵 버전
• visualize_dataset_viridis.py — Viridis 색상맵 버전
• visualize_awol_comparison.py — AWOL 비교
• visualize_task11_examples.py — 작업 예제

렌더링 (render_*.py)

• render_mesh_views.py — 메시 다중 뷰 렌더링
• render_animer_meshes.py — AniMer 메시 렌더링
• render_textured_mesh.py — 텍스처 메시 렌더링
• render_table_pdf.py — PDF 표 생성
• render_table_pdf_canvas.py — Canvas 기반 표
• render_table_pdf_meta.py — 메타데이터 표

이미지/비디오 처리

• text_to_photorealistic.py — 텍스트→사실적 이미지
• controlnet_render.py — ControlNet 렌더링
• video_to_training.py — 비디오→학습 데이터
• texture_standard_models.py — 표준 모델 텍스처
• extract_conditioning_maps.py — 조건 맵 추출

분석/검증

• validate_shape_codebook.py — 코드북 검증
• validate_shape_descriptors.py — 형태 설명자
• validate_standard_models.py — 표준 모델 검증
• validate_morph_parameters.py — 형태 파라미터
• profile_pipeline.py — 파이프라인 프로파일링

아키텍처/다이어그램

• gen_architecture_diagram.py — 아키텍처 다이어그램
• generate_v3_architecture_diagram.py — v3 다이어그램
• generate_residualmorph_v3_arch_diagram.py — 잔차 형태 v3 다이어그램
• spectrum_figure_style.py — Spectrum 스타일 설정

통합/파이프라인

• run_semantic_experiments.py — 시맨틱 실험 실행
• run_unified_image_text_pipeline.py — 통합 이미지+텍스트 파이프라인
• run_ablation_study.py — 절제 실험
• integration_test.py — 통합 테스트
• simulate_cross_species_transfer.py — 종간 전이 시뮬레이션
• simulate_population.py — 종 개체군 시뮬레이션
• simulate_temporal_morph.py — 시간 형태 시뮬레이션

데이터셋/코드북 도우미

• analyze_family_policy.py — 과 정책 분석
• analyze_partition_sensitivity.py — 분할 민감도
• analyze_cervidae_validation.py — Cervidae 검증
• analyze_clip_prompt_space.py — CLIP 프롬프트 공간
• collect_overlays.py — 오버레이 수집
• copy_fallback_renders.py — 폴백 렌더 복사
• copy_genzoo_renders.py — GenZoo 렌더 복사

AI 에이전트 가이드

작업 시 주의사항

경로 해석

• 절대 경로 사용: 모든 스크립트는 smal_config.yaml에서 경로를 읽음
• 하드코딩된 경로 없음 — 항상 Path(__file__).parent.parent 또는 config 참고
• 상대 경로 사용 시: 작업 디렉토리 항상 프로젝트 루트

한글 주석 규약

모든 스크립트는 다음을 따릅니다:

#!/usr/bin/env python3
"""
스크립트의 목적을 영어로 설명합니다 (필요시 한글 병기)
사용법, 입출력 포맷, 주요 의존성
"""

# 한글 주석으로 섹션 설명
# 인라인 로직 설명도 한글

종 분류 및 모델 선택

• 입력 분류: scripts/classification/classify_animal_species.py (BioCLIP-2, 184종)
• 모델 선택 로직: smal_config.yaml의 family→model_type 매핑
  • Felidae/Canidae/Equidae/Bovidae/Cervidae → AniMer + AWOL
  • Suidae/Ursidae/Camelidae/Hippopotamidae/나머지 → GenZoo

좌표계

• SMAL: Z-up (소중함!)
• Unity/Gradio: Y-up
• 변환: verts[:,[1,2]]=verts[:,[2,1]]; verts[:,2]=-verts[:,2]
• GLB 행렬: [[1,0,0],[0,0,1],[0,-1,0]]

데이터 참고

• 종 목록: data/taxonomy/sample_species_taxonomy.csv (184종, 25과)
• 표준 모델: data/species_standard_models/index.json (v6 + MCBO)
• PanTHERIA 룩업: data/zoological_measurements/pantheria_full_lookup.pkl (5,416종)
• v8 체크포인트: data/semantic_shape_model_v8.pt (프로덕션 기본값); v6는 --use-v6 레거시 경로

테스트

환경 검증

python scripts/check_setup.py

필수 파일, 디렉토리, Python 패키지, GPU 확인

문법 확인

python -m py_compile scripts/<script>.py

파이프라인 전체 평가

python scripts/evaluate_v8_pipeline.py
python scripts/evaluate_e2e_walkthrough.py

GUI 테스트 (SMAL)

python scripts/test_smal_gui_preview_formats.py
python scripts/test_smal_gui_camera_presets.py
python scripts/test_smal_gui_video_preview_persist.py

형태 모델 검증

python scripts/test_v8_architecture.py
python scripts/test_e2e_residual_morph_v3.py

측정 추출 테스트

python scripts/test_measurement_extractor.py

주요 패턴

스크립트 추가 체크리스트

• 파일 헤더에 docstring 포함
• 한글 주석으로 주요 섹션 설명
• Path(__file__).parent 또는 smal_config.yaml으로 상대 경로 해석
• 좌표계 명시 (Z-up 또는 Y-up)
• 입출력 형식 명확 (JSON, NPZ, OBJ, GLB 등)
• 종 또는 과 필터링 시 sample_species_taxonomy.csv 참고
• GPU 요구사항 명시

데이터 흐름

이미지
  → classify_animal_species.py (BioCLIP-2, 184종)
  → 모델 선택 (smal_config.yaml)
  → evaluate_*.py 또는 train_*.py 스크립트
  → generate_*.py로 결과 생성 또는 시각화

코드북/표준 모델

• build_codebook_145.py — 각 종별 표준 형태 구성
• build_pantheria_full_lookup.py — 측정 데이터 로드
• label_codebook_by_family.py — 과 메타데이터 추가
• generate_family_standard_models.py — 과별 평균 모델

학습 스크립트 구조

# 1. 데이터 로드 (species_standardization_pipeline.py 또는 generate_semantic_dataset.py)
# 2. 모델 초기화 (nature3d/semantic_shape_model.py)
# 3. 학습 루프 (검증, 체크포인트)
# 4. 평가 (evaluate_semantic_shape.py)

렌더링 파이프라인

• render_mesh_views.py — 다중 뷰 (Blender 또는 오프스크린)
• render_textured_mesh.py — 텍스처 메시
• render_table_pdf.py — PDF 표 생성
• 결과: results/ 디렉토리 (날짜별 서브디렉토리)

논문 그림 생성

python scripts/generate_paper_figures.py --format spectrum
python scripts/generate_nature3d_v8_paper_figures.py
python scripts/generate_baseline_comparison_figure.py

결과: results/paper_figures/

의존성

내부

핵심 모듈

데이터 파일

• data/taxonomy/sample_species_taxonomy.csv
• data/semantic_shape_model_v8.pt (실험용)
• data/species_standard_models/index.json
• data/zoological_measurements/pantheria_full_lookup.pkl

하위 스크립트 (중첩 임포트)

• research_tool/species_standardization_pipeline.py — 종 데이터 정규화
• research_tool/family_standardization.py — 과 데이터 정규화
• classification/classify_animal_species.py — 분류
• data_ops/*.py — 데이터 로드/검증

외부

핵심 패키지

시각화

렌더링/메디어

선택 패키지

• gradio — GUI 데모 (smal_gui.py 필요)
• imageio — 이미지/비디오 저장
• scikit-image — 이미지 처리
• tqdm — 진행률 표시
• humanize — 사람 읽기 포맷

GPU/CUDA

• CUDA 11.8+ (torch GPU 연산)
• cuDNN 8.6+ (권장)
• GPU 메모리: 8GB 이상 (권장 24GB)