# lsdfd/metadeepth architecture

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

- Interactive diagram: https://gitdiagram.com/lsdfd/metadeepth
- Repository: https://github.com/lsdfd/metadeepth
- Video tour (about a minute): https://gitdiagram.com/lsdfd/metadeepth/video

## Overview

MetaDeepth is a research prototype for information-optimal metasurface depth imaging, not a finished product. Its documented workflow configures an optical system, simulates point-source PSFs, evaluates depth information, renders encoded images from RGB-D samples, and scaffolds neural depth reconstruction. The graph preserves these stages and the optical, Fisher, and model internals. Relationships are based on README statements and SOURCE INDEX references; unsampled behavior is not inferred.

Main entry points: [`scripts/04_depth_learning.py`](https://github.com/lsdfd/metadeepth/blob/main/scripts/04_depth_learning.py) (Depth train/eval), [`src/optics/psf.py`](https://github.com/lsdfd/metadeepth/blob/main/src/optics/psf.py) (Point-source PSF), [`scripts/01_psf_sanity_check.py`](https://github.com/lsdfd/metadeepth/blob/main/scripts/01_psf_sanity_check.py) (PSF sanity), [`scripts/02_psf_fisher_experiment.py`](https://github.com/lsdfd/metadeepth/blob/main/scripts/02_psf_fisher_experiment.py) (PSF Fisher run)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiments["Experiment stages"]
  node_system_sweep["System sweep"]
  node_psf_sanity["PSF sanity"]
  node_psf_experiment["PSF Fisher run"]
  node_image_experiment["Image Fisher run"]
  node_depth_experiment["Depth train/eval"]
  node_results["Experiment outputs"]
end

subgraph group_optics["Optical simulation"]
  node_system_config["System parameters<br/>[system_config.py]"]
  node_config_loader["YAML config<br/>[config.py]"]
  node_pupil["Pupil and phase<br/>[pupil.py]"]
  node_propagation["Field propagation<br/>[propagation.py]"]
  node_psf["Point-source PSF<br/>[psf.py]"]
  node_fisher["PSF Fisher analysis<br/>[psf_fisher.py]"]
end

subgraph group_image["Image forward"]
  node_pilot_data[("Hypersim pilot")]
  node_rgbd_forward["RGB-D forward model<br/>[rgbd_forward.py]"]
end

subgraph group_learning["Depth learning"]
  node_depth_data["Depth datasets<br/>[depth_data.py]"]
  node_depth_model["Depth network<br/>[simple_unet.py]"]
  node_depth_losses["Depth losses<br/>[depth_losses.py]"]
  node_depth_metrics["Depth metrics<br/>[depth_metrics.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs"| node_system_sweep
node_researcher -->|"runs"| node_psf_sanity
node_researcher -->|"runs"| node_psf_experiment
node_researcher -->|"runs"| node_image_experiment
node_researcher -->|"runs"| node_depth_experiment
node_system_sweep -->|"reads parameters"| node_system_config
node_system_config -->|"loads YAML"| node_config_loader
node_psf_sanity -->|"reads parameters"| node_system_config
node_psf_sanity -->|"uses phase"| node_pupil
node_psf_sanity -->|"computes PSF"| node_psf
node_psf_experiment -->|"evaluates information"| node_fisher
node_psf_experiment -->|"computes PSF"| node_psf
node_psf_experiment -->|"uses phase"| node_pupil
node_psf -->|"builds field"| node_pupil
node_psf -->|"propagates field"| node_propagation
node_fisher -->|"evaluates PSF"| node_psf
node_image_experiment -->|"renders and evaluates"| node_rgbd_forward
node_image_experiment -->|"uses phase"| node_pupil
node_image_experiment -->|"loads sample"| node_pilot_data
node_rgbd_forward -->|"renders with PSF"| node_psf
node_depth_experiment -->|"builds datasets"| node_depth_data
node_depth_experiment -->|"trains model"| node_depth_model
node_depth_experiment -->|"computes loss"| node_depth_losses
node_depth_experiment -->|"evaluates predictions"| node_depth_metrics
node_psf_sanity -->|"writes summaries"| node_results
node_psf_experiment -->|"writes Fisher results"| node_results
node_image_experiment -->|"writes image results"| node_results
node_depth_experiment -->|"writes metrics"| node_results

click node_system_sweep "https://github.com/lsdfd/metadeepth/blob/main/scripts/00_print_system_sweep.py"
click node_psf_sanity "https://github.com/lsdfd/metadeepth/blob/main/scripts/01_psf_sanity_check.py"
click node_psf_experiment "https://github.com/lsdfd/metadeepth/blob/main/scripts/02_psf_fisher_experiment.py"
click node_image_experiment "https://github.com/lsdfd/metadeepth/blob/main/scripts/03_image_forward_fisher_experiment.py"
click node_depth_experiment "https://github.com/lsdfd/metadeepth/blob/main/scripts/04_depth_learning.py"
click node_system_config "https://github.com/lsdfd/metadeepth/blob/main/src/utils/system_config.py"
click node_config_loader "https://github.com/lsdfd/metadeepth/blob/main/src/utils/config.py"
click node_pupil "https://github.com/lsdfd/metadeepth/blob/main/src/optics/pupil.py"
click node_propagation "https://github.com/lsdfd/metadeepth/blob/main/src/optics/propagation.py"
click node_psf "https://github.com/lsdfd/metadeepth/blob/main/src/optics/psf.py"
click node_fisher "https://github.com/lsdfd/metadeepth/blob/main/src/fisher/psf_fisher.py"
click node_pilot_data "https://github.com/lsdfd/metadeepth/tree/main/data/raw/hypersim_pilot_100"
click node_rgbd_forward "https://github.com/lsdfd/metadeepth/blob/main/src/simulation/rgbd_forward.py"
click node_depth_data "https://github.com/lsdfd/metadeepth/blob/main/src/models/depth_data.py"
click node_depth_model "https://github.com/lsdfd/metadeepth/blob/main/src/models/simple_unet.py"
click node_depth_losses "https://github.com/lsdfd/metadeepth/blob/main/src/models/depth_losses.py"
click node_depth_metrics "https://github.com/lsdfd/metadeepth/blob/main/src/models/depth_metrics.py"
click node_results "https://github.com/lsdfd/metadeepth/tree/main/outputs"

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_system_sweep,node_psf_sanity,node_psf_experiment,node_image_experiment,node_depth_experiment,node_results toneBlue
class node_system_config,node_config_loader,node_pupil,node_propagation,node_psf,node_fisher toneAmber
class node_pilot_data,node_rgbd_forward toneMint
class node_depth_data,node_depth_model,node_depth_losses,node_depth_metrics toneRose
class node_researcher toneIndigo
```

## Components

### Experiment stages

- [System sweep](https://github.com/lsdfd/metadeepth/blob/main/scripts/00_print_system_sweep.py): `scripts/00_print_system_sweep.py`
- [PSF sanity](https://github.com/lsdfd/metadeepth/blob/main/scripts/01_psf_sanity_check.py): `scripts/01_psf_sanity_check.py`
- [PSF Fisher run](https://github.com/lsdfd/metadeepth/blob/main/scripts/02_psf_fisher_experiment.py): `scripts/02_psf_fisher_experiment.py`
- [Image Fisher run](https://github.com/lsdfd/metadeepth/blob/main/scripts/03_image_forward_fisher_experiment.py): `scripts/03_image_forward_fisher_experiment.py`
- [Depth train/eval](https://github.com/lsdfd/metadeepth/blob/main/scripts/04_depth_learning.py): `scripts/04_depth_learning.py`
- [Experiment outputs](https://github.com/lsdfd/metadeepth/tree/main/outputs): `outputs`

### Optical simulation

- [System parameters](https://github.com/lsdfd/metadeepth/blob/main/src/utils/system_config.py): `src/utils/system_config.py`
- [YAML config](https://github.com/lsdfd/metadeepth/blob/main/src/utils/config.py): `src/utils/config.py`
- [Pupil and phase](https://github.com/lsdfd/metadeepth/blob/main/src/optics/pupil.py): `src/optics/pupil.py`
- [Field propagation](https://github.com/lsdfd/metadeepth/blob/main/src/optics/propagation.py): `src/optics/propagation.py`
- [Point-source PSF](https://github.com/lsdfd/metadeepth/blob/main/src/optics/psf.py): `src/optics/psf.py`
- [PSF Fisher analysis](https://github.com/lsdfd/metadeepth/blob/main/src/fisher/psf_fisher.py): `src/fisher/psf_fisher.py`

### Image forward

- [Hypersim pilot](https://github.com/lsdfd/metadeepth/tree/main/data/raw/hypersim_pilot_100): `data/raw/hypersim_pilot_100`
- [RGB-D forward model](https://github.com/lsdfd/metadeepth/blob/main/src/simulation/rgbd_forward.py): `src/simulation/rgbd_forward.py`

### Depth learning

- [Depth datasets](https://github.com/lsdfd/metadeepth/blob/main/src/models/depth_data.py): `src/models/depth_data.py`
- [Depth network](https://github.com/lsdfd/metadeepth/blob/main/src/models/simple_unet.py): `src/models/simple_unet.py`
- [Depth losses](https://github.com/lsdfd/metadeepth/blob/main/src/models/depth_losses.py): `src/models/depth_losses.py`
- [Depth metrics](https://github.com/lsdfd/metadeepth/blob/main/src/models/depth_metrics.py): `src/models/depth_metrics.py`

### Other components

- **Researcher**

## Connections

- Researcher → System sweep: runs (evidence: `README.md`)
- Researcher → PSF sanity: runs (evidence: `README.md`)
- Researcher → PSF Fisher run: runs (evidence: `README.md`)
- Researcher → Image Fisher run: runs (evidence: `README.md`)
- Researcher → Depth train/eval: runs (evidence: `README.md`)
- System sweep → System parameters: reads parameters (evidence: `scripts/00_print_system_sweep.py`)
- System parameters → YAML config: loads YAML (evidence: `src/utils/system_config.py`)
- PSF sanity → System parameters: reads parameters (evidence: `scripts/01_psf_sanity_check.py`)
- PSF sanity → Pupil and phase: uses phase (evidence: `scripts/01_psf_sanity_check.py`)
- PSF sanity → Point-source PSF: computes PSF (evidence: `scripts/01_psf_sanity_check.py`)
- PSF Fisher run → PSF Fisher analysis: evaluates information (evidence: `scripts/02_psf_fisher_experiment.py`)
- PSF Fisher run → Point-source PSF: computes PSF (evidence: `scripts/02_psf_fisher_experiment.py`)
- PSF Fisher run → Pupil and phase: uses phase (evidence: `scripts/02_psf_fisher_experiment.py`)
- Point-source PSF → Pupil and phase: builds field (evidence: `src/optics/psf.py`)
- Point-source PSF → Field propagation: propagates field (evidence: `src/optics/psf.py`)
- PSF Fisher analysis → Point-source PSF: evaluates PSF (evidence: `src/fisher/psf_fisher.py`)
- Image Fisher run → RGB-D forward model: renders and evaluates (evidence: `scripts/03_image_forward_fisher_experiment.py`)
- Image Fisher run → Pupil and phase: uses phase (evidence: `scripts/03_image_forward_fisher_experiment.py`)
- Image Fisher run → Hypersim pilot: loads sample (evidence: `README.md`)
- RGB-D forward model → Point-source PSF: renders with PSF (evidence: `src/simulation/rgbd_forward.py`)
- Depth train/eval → Depth datasets: builds datasets (evidence: `scripts/04_depth_learning.py`)
- Depth train/eval → Depth network: trains model (evidence: `scripts/04_depth_learning.py`)
- Depth train/eval → Depth losses: computes loss (evidence: `scripts/04_depth_learning.py`)
- Depth train/eval → Depth metrics: evaluates predictions (evidence: `scripts/04_depth_learning.py`)
- PSF sanity → Experiment outputs: writes summaries (evidence: `README.md`)
- PSF Fisher run → Experiment outputs: writes Fisher results (evidence: `README.md`)
- Image Fisher run → Experiment outputs: writes image results (evidence: `README.md`)
- Depth train/eval → Experiment outputs: writes metrics (evidence: `README.md`)
