Code architecture

python -m eghumannerf, python main.py and python -m eghumannerf.runtime share one CLI. The runtime loads a Hydra experiment, constructs datasets, loads model state and runs a single-device Lightning trainer.

Modules

Module	Responsibility
eghumannerf/runtime.py	Command-line options and training/evaluation lifecycle
eghumannerf/data.py	Dataset and data-loader construction
eghumannerf/thuman.py, thuman_io.py, thuman_geometry.py	THuman sample assembly, file readers and camera/sampling transforms
eghumannerf/body.py	Fitted body evaluation through the separately installed SMPL-X implementation
eghumannerf/resources.py	Resource registration and linked-data write protection
eghumannerf/model/network.py	Registered model components
eghumannerf/model/features.py	Image features and sparse feature volumes
eghumannerf/model/rendering.py	Ray sampling and radiance rendering
eghumannerf/model/training.py	Optimization and losses
eghumannerf/model/validation.py	View evaluation and metrics
eghumannerf/model/geometry.py	Geometry extraction
eghumannerf/model/upsampling.py	Image-space refinement
eghumannerf/observability.py	Image export, metrics and training diagnostics
eghumannerf/scene.py, realtime.py	Source-frame preparation and camera-dependent rendering
eghumannerf/camera.py, reference_frame.py	Interactive cameras, training-frame normalization and shell ray sampling
eghumannerf/cuda_rasterizer.py, cuda_graph.py	Optional CUDA shell rasterization and graph replay for vertex fusion and refinement
eghumannerf/gui.py, benchmark.py	Interactive viewer and steady-state rendering measurements
eghumannerf/recording.py	X11 window capture with FFmpeg

EGHumanNeRF is also exposed as VolRecon for import compatibility. Model mixins share the same registered state and checkpoint key layout. source/model.py and source/upscaling_cnn.py provide compatibility imports; additional upsampler architectures are loaded lazily from source/legacy/.

Configuration and resources

Experiment configurations live in config/experiment/. Nested Hydra options are flattened with last-leaf-wins precedence; conflicting duplicate names produce a warning.

Data and body resources are linked, while checkpoints are copied with SHA256 checksums. Dataset cache writes are disabled. A Python audit hook rejects writes into resolved linked resource directories; it covers Python file operations, not arbitrary native-library writes.

Checkpoint loading

The upsampler registers shared layers under short names and generator_obs.*. The checkpoint loader expands aliases that refer to the same tensor object, rejects conflicting values and loads the resulting state strictly.

The ZJU checkpoint contains inactive ray-attention tensors. For the matching sparse-feature configuration, these are retained as non-trainable buffers under their original keys. The compatibility mapping requires the exact key set and inactive configuration. See eghumannerf/checkpoints.py for the loading logic.

Artifact collection

Callbacks consume validation tensors to export images and metrics. Training diagnostics include loss, gradient norms and sampled parameter updates. Checkpoint restoration and output formats are described in usage.

Interactive rendering API

SceneSession.select(index) prepares a source frame and caches its image features. SceneSession.render(camera) returns a GPU RGB tensor with shape [1, 3, H, W]. Camera expresses the target view in the prepared scene's coordinate system; rendering rebuilds geometry features in the target-camera coordinate frame.