How yifita/deep_cage works
Main components
a. Data Storage
• Raw 3D assets (data/elaborated_chairs, data/fancy_humanoid, data/shapenet_target, data/Surreal, etc.)
• Preprocessed point clouds / cages (data/processed_shapenetseg, data/surreal_template*.ply/.picked, data/cage_*.obj)
• Trained models and outputs (trained_models/*)
b. Preprocessing & Data‐Generation Scripts
• scripts/resample_shapenet.py
• scripts/divide_shapenet_label.py
• scripts/generate_data_with_known_cage.py
• scripts/normalize_humanoids.py
• … and other scripts under scripts/
c. Core Python Modules
• datasets.py – dataset loaders (ShapeNet, SURREAL)
• common.py, option.py – shared utilities and CLI option parsing
• networks.py, network2.py – network architectures for cage deformation
• losses.py – loss definitions (CD, MVC, symmetry, normals, etc.)
• deformer_3d.py – model-only training & testing pipeline
• cage_deformer_3d.py – full pipeline for deformation with cage optimization
d. External Dependencies and Libraries
• PyTorch (torch)
• pytorch_points (vendor module)
• PyMesh2 (pymesh/pymesh2-*.whl)
• NumPy, SciPy, Open3D (via requirements.txt)
• Thea / MeshLab (for correspondence marking and mesh filtering)
e. Execution Workflows
• Training workflow
• ShapeNet deformation demo
• SURREAL deformation and deformation-transfer demo
Relationships and data flows
– Raw 3D models → Preprocessing scripts → Preprocessed point clouds and cages
– Preprocessed data + CLI options → DataLoader (datasets.py) → Batches of points + cages
– Batches → Networks (networks.py / network2.py) → Predicted cage deformations
– Predictions + ground truth → losses.py → Loss values → Optimizer → Updated network weights
– End of epoch → Checkpoint → trained_models/…
For inference:
– Source model + prebuilt cage → cage_deformer_3d.py → Loads checkpoint → Forward pass → Deformed mesh → Output renders (trained_models/*/renders)
For deformation transfer:
– Prebuilt cage + user landmarks (.picked) → optimize_cage.py → iterative optimization → Adapted cage
Architectural patterns & design principles
• Modularization: separate CLI entry-points (deformer_3d.py, cage_deformer_3d.py, optimize_cage.py) vs. reusable libraries (datasets.py, networks.py, losses.py).
• Pipeline pattern: distinct stages for data prep, training, inference.
• Configuration via option.py: decouples hyperparameters/paths from code.
• Extensibility: new datasets or deformation methods can be added by extending datasets.py or networks.py.