How ruiqixu37/nuvo works
This project is a research prototype implementing the paper “Nuvo: Neural UV Mapping for Unruly 3D Representations.” It’s primarily focused on training a neural network using PyTorch (with CUDA support) to predict UV mappings for 3D models (e.g., the Stanford Bunny and Nefertiti). The project is structured as a single-codebase machine learning experiment with clearly separated components for configuration, data, model definition, loss computation, training orchestration, and utility functions.
Main Components
• Data & Assets: Represented by the “data” directory (with mesh files like “nefertiti.obj” and “stanford-bunny.obj”) and the “assets” folder (likely for result images/examples).
• Configuration: The “configs” directory holds YAML files (e.g., bunny.yaml, nefertiti.yaml) which provide experiment settings.
• Dataset Module: The “dataset.py” file handles data ingestion; it likely reads 3D model files and prepares them for training.
• Neural Model: The “network.py” file defines the neural UV mapping model according to the paper’s method.
• Loss Functions: The “loss.py” file implements the custom losses used during training (e.g., distortion loss with potential finite difference method).
• Training Process: The “train.py” script orchestrates the training routine, using configurations, dataset input, the network, and the loss functions.
• Utilities: The “utils.py” contains helper functions that could be used across different modules (e.g., file I/O, logging, or additional processing).
Relationships and Interactions
• The training process, initiated via “train.py,” is the central orchestrator.
• It first reads configurations from the “configs” directory through command-line arguments.
• The dataset module (from “dataset.py”) loads the 3D data (stored in the “data” folder) and prepares it for the network.
• The network module (“network.py”) builds the neural model that predicts UV mappings.
• The loss module (“loss.py”) computes the discrepancies between model predictions and expected outputs.
• Utilities (“utils.py”) support various operations needed across the pipeline.
Architectural Patterns & Design Principles
• The project follows a modular design that separates concerns: configuration management, data handling, model definition, loss implementation, and training orchestration.
• The interaction between these modules adheres to a clear data flow: configuration → data loading → forward pass through network → loss computation → backpropagation during training.
• The emphasis is on experimental reproducibility via external configuration files.
Relevant Technologies
• Python (v3.9 as per environment)
• PyTorch (v2.3.0) with CUDA 11.8 for GPU support
• YAML configurations for experiment settings
• Linux Ubuntu environment specified, with potential dependency on GPU hardware (RTX 4090)