# blaise143/shape-from-shading architecture

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

- Interactive diagram: https://gitdiagram.com/blaise143/shape-from-shading
- Repository: https://github.com/blaise143/shape-from-shading

## Overview

This repository is a command-line Shape-from-Shading application. A user supplies grayscale images and matching masks plus optimization options; the application indexes objects, optimizes surface normals under a Lambertian shading loss, and saves normal and reconstructed-depth artifacts. The graph preserves both normal parameterizations, initialization, optional light/albedo optimization, loss logging, intermediate snapshots, and evaluation/visualization modules. Sampled code supports the main run and artifact flow; connections to the unsampled evaluation module are therefore omitted.

Main entry points: [`src/run.py`](https://github.com/blaise143/shape-from-shading/blob/main/src/run.py) (Run coordinator), [`src/sfs.py`](https://github.com/blaise143/shape-from-shading/blob/main/src/sfs.py) (Shading optimizer), [`main.py`](https://github.com/blaise143/shape-from-shading/blob/main/main.py) (Command interface), [`utils/plotting/plotting.py`](https://github.com/blaise143/shape-from-shading/blob/main/utils/plotting/plotting.py) (Plotting and exports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Input and orchestration"]
  node_cli["Command interface<br/>[main.py]"]
  node_dataset["Image-mask index<br/>[data_load.py]"]
  node_runner["Run coordinator<br/>[run.py]"]
  node_config["Run configuration<br/>[config.py]"]
end

subgraph group_optimization["SFS optimization"]
  node_sfs["Shading optimizer<br/>[sfs.py]"]
  node_losses["Loss and optimizer<br/>[core_utils.py]"]
  node_initialization["Normal initialization<br/>[initializations.py]"]
  node_stereo["Stereo mapping<br/>[stereo_maps.py]"]
  node_imageutils["Image and device utils<br/>[utils.py]"]
end

subgraph group_geometry["Surface reconstruction"]
  node_integrator["Depth integration<br/>[integrator.py]"]
  node_depthnormals["Depth-to-normal conversion"]
end

subgraph group_outputs["Results and evaluation"]
  node_visualization["Plotting and exports<br/>[plotting.py]"]
  node_plothelpers["Plot helpers<br/>[helpers.py]"]
  node_artifacts["Run artifacts"]
  node_evaluation["Evaluation<br/>[eval.py]"]
end

node_user(("CLI user"))
node_wandb(("Weights &amp; Biases"))

node_user -->|"sets options"| node_cli
node_cli -->|"builds index"| node_dataset
node_cli -->|"starts run"| node_runner
node_runner -->|"selects objects"| node_dataset
node_runner -->|"builds config"| node_config
node_runner -->|"runs optimization"| node_sfs
node_sfs -->|"loads image mask"| node_imageutils
node_sfs -->|"initializes normals"| node_initialization
node_sfs -->|"maps parameters"| node_stereo
node_sfs -->|"uses losses"| node_losses
node_sfs -.->|"logs losses"| node_wandb
node_runner -->|"integrates normals"| node_integrator
node_runner -->|"saves plots"| node_visualization
node_visualization -->|"uses helpers"| node_plothelpers
node_runner -->|"writes results"| node_artifacts
node_sfs -->|"saves snapshots"| node_artifacts

click node_cli "https://github.com/blaise143/shape-from-shading/blob/main/main.py"
click node_dataset "https://github.com/blaise143/shape-from-shading/blob/main/src/data_load.py"
click node_runner "https://github.com/blaise143/shape-from-shading/blob/main/src/run.py"
click node_config "https://github.com/blaise143/shape-from-shading/blob/main/src/config.py"
click node_sfs "https://github.com/blaise143/shape-from-shading/blob/main/src/sfs.py"
click node_losses "https://github.com/blaise143/shape-from-shading/blob/main/src/core_utils.py"
click node_initialization "https://github.com/blaise143/shape-from-shading/blob/main/utils/initializations.py"
click node_stereo "https://github.com/blaise143/shape-from-shading/blob/main/utils/stereo_maps.py"
click node_imageutils "https://github.com/blaise143/shape-from-shading/blob/main/utils/utils.py"
click node_integrator "https://github.com/blaise143/shape-from-shading/blob/main/utils/integrator.py"
click node_depthnormals "https://github.com/blaise143/shape-from-shading/blob/main/utils/normals_from_depth.py"
click node_visualization "https://github.com/blaise143/shape-from-shading/blob/main/utils/plotting/plotting.py"
click node_plothelpers "https://github.com/blaise143/shape-from-shading/blob/main/utils/plotting/helpers.py"
click node_evaluation "https://github.com/blaise143/shape-from-shading/blob/main/src/eval.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_cli,node_dataset,node_runner,node_config,node_user toneBlue
class node_sfs,node_losses,node_initialization,node_stereo,node_imageutils toneAmber
class node_integrator,node_depthnormals toneMint
class node_visualization,node_plothelpers,node_artifacts,node_evaluation toneRose
class node_wandb toneIndigo
```

## Components

### Input and orchestration

- [Command interface](https://github.com/blaise143/shape-from-shading/blob/main/main.py): `main.py`
- [Image-mask index](https://github.com/blaise143/shape-from-shading/blob/main/src/data_load.py): `src/data_load.py`
- [Run coordinator](https://github.com/blaise143/shape-from-shading/blob/main/src/run.py): `src/run.py`
- [Run configuration](https://github.com/blaise143/shape-from-shading/blob/main/src/config.py): `src/config.py`

### SFS optimization

- [Shading optimizer](https://github.com/blaise143/shape-from-shading/blob/main/src/sfs.py): `src/sfs.py`
- [Loss and optimizer](https://github.com/blaise143/shape-from-shading/blob/main/src/core_utils.py): `src/core_utils.py`
- [Normal initialization](https://github.com/blaise143/shape-from-shading/blob/main/utils/initializations.py): `utils/initializations.py`
- [Stereo mapping](https://github.com/blaise143/shape-from-shading/blob/main/utils/stereo_maps.py): `utils/stereo_maps.py`
- [Image and device utils](https://github.com/blaise143/shape-from-shading/blob/main/utils/utils.py): `utils/utils.py`

### Surface reconstruction

- [Depth integration](https://github.com/blaise143/shape-from-shading/blob/main/utils/integrator.py): `utils/integrator.py`
- [Depth-to-normal conversion](https://github.com/blaise143/shape-from-shading/blob/main/utils/normals_from_depth.py): `utils/normals_from_depth.py`

### Results and evaluation

- [Plotting and exports](https://github.com/blaise143/shape-from-shading/blob/main/utils/plotting/plotting.py): `utils/plotting/plotting.py`
- [Plot helpers](https://github.com/blaise143/shape-from-shading/blob/main/utils/plotting/helpers.py): `utils/plotting/helpers.py`
- **Run artifacts**
- [Evaluation](https://github.com/blaise143/shape-from-shading/blob/main/src/eval.py): `src/eval.py`

### Other components

- **CLI user**
- **Weights & Biases**

## Connections

- CLI user → Command interface: sets options (evidence: `README.md`)
- Command interface → Image-mask index: builds index (evidence: `main.py`)
- Command interface → Run coordinator: starts run (evidence: `main.py`)
- Run coordinator → Image-mask index: selects objects (evidence: `src/run.py`)
- Run coordinator → Run configuration: builds config (evidence: `src/run.py`)
- Run coordinator → Shading optimizer: runs optimization (evidence: `src/run.py`)
- Shading optimizer → Image and device utils: loads image mask (evidence: `src/sfs.py`)
- Shading optimizer → Normal initialization: initializes normals (evidence: `src/sfs.py`)
- Shading optimizer → Stereo mapping: maps parameters (evidence: `src/sfs.py`)
- Shading optimizer → Loss and optimizer: uses losses (evidence: `src/sfs.py`)
- Shading optimizer → Weights & Biases: logs losses (evidence: `README.md`)
- Run coordinator → Depth integration: integrates normals (evidence: `src/run.py`)
- Run coordinator → Plotting and exports: saves plots (evidence: `src/run.py`)
- Plotting and exports → Plot helpers: uses helpers (evidence: `utils/plotting/plotting.py`)
- Run coordinator → Run artifacts: writes results (evidence: `src/run.py`)
- Shading optimizer → Run artifacts: saves snapshots (evidence: `src/sfs.py`)
