# facebookresearch/deepsdf architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/deepsdf
- Repository: https://github.com/facebookresearch/deepsdf

## Overview

DeepSDF learns a continuous signed-distance representation of 3D shapes and turns it into reconstructed meshes. The main workflow preprocesses source meshes into SDF samples, trains a decoder and per-shape latent codes, reconstructs test shapes, then evaluates the resulting meshes against sampled ground-truth surfaces. The graph also includes the documented surface-sampling branch and experiment visualization. README statements establish the overall workflow; some internal links are dashed where the available excerpts do not show the call site.

Main entry points: [`train_deep_sdf.py`](https://github.com/facebookresearch/deepsdf/blob/main/train_deep_sdf.py) (Autodecoder training), [`reconstruct.py`](https://github.com/facebookresearch/deepsdf/blob/main/reconstruct.py) (Latent optimization), [`evaluate.py`](https://github.com/facebookresearch/deepsdf/blob/main/evaluate.py) (Reconstruction evaluation), [`preprocess_data.py`](https://github.com/facebookresearch/deepsdf/blob/main/preprocess_data.py) (Preprocess orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_preparation["Data preparation"]
  node_preprocess["Preprocess orchestration<br/>[preprocess_data.py]"]
  node_sdf_sampler["SDF sampling<br/>[PreprocessMesh.cpp]"]
  node_surface_sampler["Surface sampling"]
  node_sample_store[("SDF and surface samples")]
  node_dataset_loader["SDF dataset loader<br/>[data.py]"]
end

subgraph group_learning["Model learning"]
  node_experiment_config["Experiment configuration<br/>[workspace.py]"]
  node_trainer["Autodecoder training<br/>[train_deep_sdf.py]"]
  node_decoder["SDF decoder"]
  node_checkpoints[("Model and latent checkpoints")]
end

subgraph group_inference["Reconstruction"]
  node_reconstructor["Latent optimization<br/>[reconstruct.py]"]
  node_mesh_extraction["Mesh extraction<br/>[mesh.py]"]
  node_reconstructed_meshes["Reconstructed meshes"]
end

subgraph group_assessment["Evaluation and tools"]
  node_evaluator["Reconstruction evaluation<br/>[evaluate.py]"]
  node_chamfer["Chamfer metric<br/>[chamfer.py]"]
  node_evaluation_results["Evaluation results"]
  node_progress_plot["Training progress plot<br/>[plot_log.py]"]
  node_training_meshes["Training mesh generation"]
  node_sample_inspector["Interior sample inspection"]
  node_workspace["Experiment storage helpers<br/>[workspace.py]"]
end

node_researcher(("Researcher"))
node_source_meshes["Source meshes"]

node_researcher -->|"runs preprocessing"| node_preprocess
node_source_meshes -->|"provides meshes"| node_preprocess
node_preprocess -->|"invokes sampler"| node_sdf_sampler
node_preprocess -->|"requests surface samples"| node_surface_sampler
node_sdf_sampler -->|"writes SDF samples"| node_sample_store
node_surface_sampler -->|"writes surface samples"| node_sample_store
node_sample_store -.->|"provides training samples"| node_dataset_loader
node_researcher -->|"starts training"| node_trainer
node_experiment_config -->|"configures training"| node_trainer
node_dataset_loader -.->|"supplies batches"| node_trainer
node_trainer -.->|"optimizes decoder"| node_decoder
node_trainer -->|"saves state"| node_checkpoints
node_researcher -->|"starts reconstruction"| node_reconstructor
node_checkpoints -->|"provides weights"| node_reconstructor
node_sample_store -->|"provides test SDF"| node_reconstructor
node_reconstructor -->|"queries decoder"| node_decoder
node_reconstructor -->|"extracts mesh"| node_mesh_extraction
node_mesh_extraction -->|"writes meshes"| node_reconstructed_meshes
node_researcher -->|"starts evaluation"| node_evaluator
node_reconstructed_meshes -->|"provides reconstructions"| node_evaluator
node_sample_store -->|"provides ground truth"| node_evaluator
node_evaluator -.->|"computes distance"| node_chamfer
node_evaluator -->|"writes metrics"| node_evaluation_results
node_researcher -->|"views training progress"| node_progress_plot
node_researcher -.->|"generates training meshes"| node_training_meshes
node_researcher -.->|"inspects samples"| node_sample_inspector

click node_preprocess "https://github.com/facebookresearch/deepsdf/blob/main/preprocess_data.py"
click node_sdf_sampler "https://github.com/facebookresearch/deepsdf/blob/main/src/PreprocessMesh.cpp"
click node_surface_sampler "https://github.com/facebookresearch/deepsdf/blob/main/src/SampleVisibleMeshSurface.cpp"
click node_dataset_loader "https://github.com/facebookresearch/deepsdf/blob/main/deep_sdf/data.py"
click node_experiment_config "https://github.com/facebookresearch/deepsdf/blob/main/deep_sdf/workspace.py"
click node_trainer "https://github.com/facebookresearch/deepsdf/blob/main/train_deep_sdf.py"
click node_decoder "https://github.com/facebookresearch/deepsdf/blob/main/networks/deep_sdf_decoder.py"
click node_reconstructor "https://github.com/facebookresearch/deepsdf/blob/main/reconstruct.py"
click node_mesh_extraction "https://github.com/facebookresearch/deepsdf/blob/main/deep_sdf/mesh.py"
click node_evaluator "https://github.com/facebookresearch/deepsdf/blob/main/evaluate.py"
click node_chamfer "https://github.com/facebookresearch/deepsdf/blob/main/deep_sdf/metrics/chamfer.py"
click node_progress_plot "https://github.com/facebookresearch/deepsdf/blob/main/plot_log.py"
click node_training_meshes "https://github.com/facebookresearch/deepsdf/blob/main/generate_training_meshes.py"
click node_sample_inspector "https://github.com/facebookresearch/deepsdf/blob/main/show_interior_samples.py"
click node_workspace "https://github.com/facebookresearch/deepsdf/blob/main/deep_sdf/workspace.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_preprocess,node_sdf_sampler,node_surface_sampler,node_sample_store,node_dataset_loader toneBlue
class node_experiment_config,node_trainer,node_decoder,node_checkpoints toneAmber
class node_reconstructor,node_mesh_extraction,node_reconstructed_meshes toneMint
class node_evaluator,node_chamfer,node_evaluation_results,node_progress_plot,node_training_meshes,node_sample_inspector,node_workspace toneRose
class node_researcher,node_source_meshes toneIndigo
```

## Components

### Data preparation

- [Preprocess orchestration](https://github.com/facebookresearch/deepsdf/blob/main/preprocess_data.py): `preprocess_data.py`
- [SDF sampling](https://github.com/facebookresearch/deepsdf/blob/main/src/PreprocessMesh.cpp): `src/PreprocessMesh.cpp`
- [Surface sampling](https://github.com/facebookresearch/deepsdf/blob/main/src/SampleVisibleMeshSurface.cpp): `src/SampleVisibleMeshSurface.cpp`
- **SDF and surface samples**
- [SDF dataset loader](https://github.com/facebookresearch/deepsdf/blob/main/deep_sdf/data.py): `deep_sdf/data.py`

### Model learning

- [Experiment configuration](https://github.com/facebookresearch/deepsdf/blob/main/deep_sdf/workspace.py): `deep_sdf/workspace.py`
- [Autodecoder training](https://github.com/facebookresearch/deepsdf/blob/main/train_deep_sdf.py): `train_deep_sdf.py`
- [SDF decoder](https://github.com/facebookresearch/deepsdf/blob/main/networks/deep_sdf_decoder.py): `networks/deep_sdf_decoder.py`
- **Model and latent checkpoints**

### Reconstruction

- [Latent optimization](https://github.com/facebookresearch/deepsdf/blob/main/reconstruct.py): `reconstruct.py`
- [Mesh extraction](https://github.com/facebookresearch/deepsdf/blob/main/deep_sdf/mesh.py): `deep_sdf/mesh.py`
- **Reconstructed meshes**

### Evaluation and tools

- [Reconstruction evaluation](https://github.com/facebookresearch/deepsdf/blob/main/evaluate.py): `evaluate.py`
- [Chamfer metric](https://github.com/facebookresearch/deepsdf/blob/main/deep_sdf/metrics/chamfer.py): `deep_sdf/metrics/chamfer.py`
- **Evaluation results**
- [Training progress plot](https://github.com/facebookresearch/deepsdf/blob/main/plot_log.py): `plot_log.py`
- [Training mesh generation](https://github.com/facebookresearch/deepsdf/blob/main/generate_training_meshes.py): `generate_training_meshes.py`
- [Interior sample inspection](https://github.com/facebookresearch/deepsdf/blob/main/show_interior_samples.py): `show_interior_samples.py`
- [Experiment storage helpers](https://github.com/facebookresearch/deepsdf/blob/main/deep_sdf/workspace.py): `deep_sdf/workspace.py`

### Other components

- **Researcher**
- **Source meshes**

## Connections

- Researcher → Preprocess orchestration: runs preprocessing (evidence: `README.md`)
- Source meshes → Preprocess orchestration: provides meshes (evidence: `README.md`)
- Preprocess orchestration → SDF sampling: invokes sampler (evidence: `README.md`)
- Preprocess orchestration → Surface sampling: requests surface samples (evidence: `README.md`)
- SDF sampling → SDF and surface samples: writes SDF samples (evidence: `README.md`)
- Surface sampling → SDF and surface samples: writes surface samples (evidence: `README.md`)
- SDF and surface samples → SDF dataset loader: provides training samples
- Researcher → Autodecoder training: starts training (evidence: `README.md`)
- Experiment configuration → Autodecoder training: configures training (evidence: `README.md`)
- SDF dataset loader → Autodecoder training: supplies batches
- Autodecoder training → SDF decoder: optimizes decoder
- Autodecoder training → Model and latent checkpoints: saves state (evidence: `README.md`)
- Researcher → Latent optimization: starts reconstruction (evidence: `README.md`)
- Model and latent checkpoints → Latent optimization: provides weights (evidence: `README.md`)
- SDF and surface samples → Latent optimization: provides test SDF (evidence: `README.md`)
- Latent optimization → SDF decoder: queries decoder (evidence: `reconstruct.py`)
- Latent optimization → Mesh extraction: extracts mesh (evidence: `reconstruct.py`)
- Mesh extraction → Reconstructed meshes: writes meshes (evidence: `deep_sdf/mesh.py`)
- Researcher → Reconstruction evaluation: starts evaluation (evidence: `README.md`)
- Reconstructed meshes → Reconstruction evaluation: provides reconstructions (evidence: `README.md`)
- SDF and surface samples → Reconstruction evaluation: provides ground truth (evidence: `README.md`)
- Reconstruction evaluation → Chamfer metric: computes distance
- Reconstruction evaluation → Evaluation results: writes metrics (evidence: `README.md`)
- Researcher → Training progress plot: views training progress (evidence: `README.md`)
- Researcher → Training mesh generation: generates training meshes
- Researcher → Interior sample inspection: inspects samples
