# yizhou42/masiv architecture

> Architecture diagram of the GitHub repository yizhou42/masiv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yizhou42/masiv
- Repository: https://github.com/yizhou42/masiv

## Overview

MASIV identifies geometry and material physics from dynamic video: users prepare a sequence, train a dynamic Gaussian reconstruction and physical estimator, then predict novel states or inspect trajectories. The graph preserves the documented generalization and visualization branches as well as the MPM/material and differentiable-rendering layers. Some script bodies and subsystems were not excerpted; their documented capabilities are shown, but uncertain internal links are omitted.

Main entry points: [`simulator/estimator.py`](https://github.com/yizhou42/masiv/blob/main/simulator/estimator.py) (Physical estimator), [`train_dynamic.py`](https://github.com/yizhou42/masiv/blob/main/train_dynamic.py) (Dynamic training), [`scene/__init__.py`](https://github.com/yizhou42/masiv/blob/main/scene/__init__.py) (Scene loading), [`prepare_pacnerf_data.py`](https://github.com/yizhou42/masiv/blob/main/prepare_pacnerf_data.py) (Dataset preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Video and scene data"]
  node_video["Video sequences"]
  node_prep["Dataset preparation"]
  node_matting["Foreground matting<br/>[model.py]"]
  node_scene["Scene loading<br/>[__init__.py]"]
  node_readers["Dataset readers<br/>[dataset_readers.py]"]
  node_colmap["COLMAP parsing<br/>[colmap_loader.py]"]
end

subgraph group_recon["Gaussian reconstruction"]
  node_gsmodel["Gaussian model<br/>[gaussian_model.py]"]
  node_renderer["Gaussian renderer<br/>[__init__.py]"]
  node_gslearn["Gaussian optimization<br/>[train_gs.py]"]
end

subgraph group_physics["Physics identification"]
  node_training["Dynamic training<br/>[train_dynamic.py]"]
  node_estimator["Physical estimator<br/>[estimator.py]"]
  node_mpm["MPM simulation<br/>[mpm.py]"]
  node_material["Material models<br/>[meta.py]"]
  node_constitution["Constitutive laws<br/>[constitution.py]"]
end

subgraph group_outputs["Prediction and inspection"]
  node_prediction["Future prediction<br/>[predict.py]"]
  node_generalize["Novel-condition tests<br/>[generalize.py]"]
  node_visualize["Trajectory visualization<br/>[visualize.py]"]
end

subgraph group_internals["Numerical components"]
  node_svd["Differentiable SVD<br/>[svd.py]"]
  node_tape["Warp autodiff tape<br/>[tape.py]"]
  node_losses["Training losses<br/>[loss_utils.py]"]
  node_regularization["Gaussian regularization<br/>[reg_utils.py]"]
end

node_user(("Researcher"))

node_user -->|"provides"| node_video
node_user -->|"runs preprocessing"| node_prep
node_prep -.-> node_matting
node_user -->|"starts training"| node_training
node_video -->|"supplies sequence"| node_scene
node_scene -->|"dispatches loading"| node_readers
node_readers -->|"reads COLMAP"| node_colmap
node_scene -->|"initializes model"| node_gsmodel
node_training -->|"loads scene"| node_scene
node_training -->|"optimizes physics"| node_estimator
node_training -->|"uses optimization"| node_gslearn
node_renderer -->|"reads Gaussian state"| node_gsmodel
node_estimator -->|"renders observations"| node_renderer
node_estimator -->|"simulates particles"| node_mpm
node_estimator -->|"uses material model"| node_material
node_estimator -->|"uses constitutive law"| node_constitution
node_material -->|"uses decomposition"| node_svd
node_svd -->|"records gradients"| node_tape
node_estimator -->|"computes objectives"| node_losses
node_user -->|"runs prediction"| node_prediction
node_user -->|"specifies novel conditions"| node_generalize
node_user -->|"selects trajectory view"| node_visualize
node_visualize -->|"loads simulation model"| node_estimator

click node_prep "https://github.com/yizhou42/masiv/blob/main/prepare_pacnerf_data.py"
click node_matting "https://github.com/yizhou42/masiv/blob/main/matting/model.py"
click node_scene "https://github.com/yizhou42/masiv/blob/main/scene/__init__.py"
click node_readers "https://github.com/yizhou42/masiv/blob/main/scene/dataset_readers.py"
click node_colmap "https://github.com/yizhou42/masiv/blob/main/scene/colmap_loader.py"
click node_gsmodel "https://github.com/yizhou42/masiv/blob/main/scene/gaussian_model.py"
click node_renderer "https://github.com/yizhou42/masiv/blob/main/gaussian_renderer/__init__.py"
click node_gslearn "https://github.com/yizhou42/masiv/blob/main/train_gs.py"
click node_training "https://github.com/yizhou42/masiv/blob/main/train_dynamic.py"
click node_estimator "https://github.com/yizhou42/masiv/blob/main/simulator/estimator.py"
click node_mpm "https://github.com/yizhou42/masiv/blob/main/nclaw/sim/mpm.py"
click node_material "https://github.com/yizhou42/masiv/blob/main/nclaw/material/meta.py"
click node_constitution "https://github.com/yizhou42/masiv/blob/main/simulator/constitution.py"
click node_prediction "https://github.com/yizhou42/masiv/blob/main/predict.py"
click node_generalize "https://github.com/yizhou42/masiv/blob/main/generalize.py"
click node_visualize "https://github.com/yizhou42/masiv/blob/main/visualize.py"
click node_svd "https://github.com/yizhou42/masiv/blob/main/nclaw/warp/svd.py"
click node_tape "https://github.com/yizhou42/masiv/blob/main/nclaw/warp/tape.py"
click node_losses "https://github.com/yizhou42/masiv/blob/main/utils/loss_utils.py"
click node_regularization "https://github.com/yizhou42/masiv/blob/main/utils/reg_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_video,node_prep,node_matting,node_scene,node_readers,node_colmap toneBlue
class node_gsmodel,node_renderer,node_gslearn toneAmber
class node_training,node_estimator,node_mpm,node_material,node_constitution toneMint
class node_prediction,node_generalize,node_visualize toneRose
class node_svd,node_tape,node_losses,node_regularization,node_user toneIndigo
```

## Components

### Video and scene data

- **Video sequences**
- [Dataset preparation](https://github.com/yizhou42/masiv/blob/main/prepare_pacnerf_data.py): `prepare_pacnerf_data.py`
- [Foreground matting](https://github.com/yizhou42/masiv/blob/main/matting/model.py): `matting/model.py`
- [Scene loading](https://github.com/yizhou42/masiv/blob/main/scene/__init__.py): `scene/__init__.py`
- [Dataset readers](https://github.com/yizhou42/masiv/blob/main/scene/dataset_readers.py): `scene/dataset_readers.py`
- [COLMAP parsing](https://github.com/yizhou42/masiv/blob/main/scene/colmap_loader.py): `scene/colmap_loader.py`

### Gaussian reconstruction

- [Gaussian model](https://github.com/yizhou42/masiv/blob/main/scene/gaussian_model.py): `scene/gaussian_model.py`
- [Gaussian renderer](https://github.com/yizhou42/masiv/blob/main/gaussian_renderer/__init__.py): `gaussian_renderer/__init__.py`
- [Gaussian optimization](https://github.com/yizhou42/masiv/blob/main/train_gs.py): `train_gs.py`

### Physics identification

- [Dynamic training](https://github.com/yizhou42/masiv/blob/main/train_dynamic.py): `train_dynamic.py`
- [Physical estimator](https://github.com/yizhou42/masiv/blob/main/simulator/estimator.py): `simulator/estimator.py`
- [MPM simulation](https://github.com/yizhou42/masiv/blob/main/nclaw/sim/mpm.py): `nclaw/sim/mpm.py`
- [Material models](https://github.com/yizhou42/masiv/blob/main/nclaw/material/meta.py): `nclaw/material/meta.py`
- [Constitutive laws](https://github.com/yizhou42/masiv/blob/main/simulator/constitution.py): `simulator/constitution.py`

### Prediction and inspection

- [Future prediction](https://github.com/yizhou42/masiv/blob/main/predict.py): `predict.py`
- [Novel-condition tests](https://github.com/yizhou42/masiv/blob/main/generalize.py): `generalize.py`
- [Trajectory visualization](https://github.com/yizhou42/masiv/blob/main/visualize.py): `visualize.py`

### Numerical components

- [Differentiable SVD](https://github.com/yizhou42/masiv/blob/main/nclaw/warp/svd.py): `nclaw/warp/svd.py`
- [Warp autodiff tape](https://github.com/yizhou42/masiv/blob/main/nclaw/warp/tape.py): `nclaw/warp/tape.py`
- [Training losses](https://github.com/yizhou42/masiv/blob/main/utils/loss_utils.py): `utils/loss_utils.py`
- [Gaussian regularization](https://github.com/yizhou42/masiv/blob/main/utils/reg_utils.py): `utils/reg_utils.py`

### Other components

- **Researcher**

## Connections

- Researcher → Video sequences: provides
- Researcher → Dataset preparation: runs preprocessing
- Dataset preparation → Foreground matting
- Researcher → Dynamic training: starts training
- Video sequences → Scene loading: supplies sequence
- Scene loading → Dataset readers: dispatches loading (evidence: `scene/__init__.py`)
- Dataset readers → COLMAP parsing: reads COLMAP (evidence: `scene/dataset_readers.py`)
- Scene loading → Gaussian model: initializes model (evidence: `scene/__init__.py`)
- Dynamic training → Scene loading: loads scene (evidence: `train_dynamic.py`)
- Dynamic training → Physical estimator: optimizes physics (evidence: `train_dynamic.py`)
- Dynamic training → Gaussian optimization: uses optimization (evidence: `train_dynamic.py`)
- Gaussian renderer → Gaussian model: reads Gaussian state (evidence: `gaussian_renderer/__init__.py`)
- Physical estimator → Gaussian renderer: renders observations (evidence: `simulator/estimator.py`)
- Physical estimator → MPM simulation: simulates particles (evidence: `simulator/estimator.py`)
- Physical estimator → Material models: uses material model (evidence: `simulator/estimator.py`)
- Physical estimator → Constitutive laws: uses constitutive law (evidence: `simulator/estimator.py`)
- Material models → Differentiable SVD: uses decomposition
- Differentiable SVD → Warp autodiff tape: records gradients (evidence: `nclaw/warp/svd.py`)
- Physical estimator → Training losses: computes objectives (evidence: `simulator/estimator.py`)
- Researcher → Future prediction: runs prediction
- Researcher → Novel-condition tests: specifies novel conditions
- Researcher → Trajectory visualization: selects trajectory view
- Trajectory visualization → Physical estimator: loads simulation model (evidence: `visualize.py`)
