# patrikhuber/eos architecture

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

- Interactive diagram: https://gitdiagram.com/patrikhuber/eos
- Repository: https://github.com/patrikhuber/eos

## Overview

eos is a header-only 3D Morphable Face Model library. Its main documented workflow maps image landmarks to model vertices, estimates camera pose, fits shape and optionally expression/edges, then produces a mesh and pose-invariant texture. The graph also preserves model representation/loading, rendering and texture tools, experimental nonlinear and multi-image/video capabilities, and language bindings. Several subsystem paths are supported by the tree and README rather than sampled implementation, so their internal call wiring is intentionally not inferred.

Main entry points: [`include/eos/fitting/fitting.hpp`](https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/fitting.hpp) (Iterative fitting), [`include/eos/morphablemodel/MorphableModel.hpp`](https://github.com/patrikhuber/eos/blob/master/include/eos/morphablemodel/MorphableModel.hpp) (Morphable model), [`include/eos/core/Mesh.hpp`](https://github.com/patrikhuber/eos/blob/master/include/eos/core/Mesh.hpp) (Mesh generation), [`python/generate-python-bindings.cpp`](https://github.com/patrikhuber/eos/blob/master/python/generate-python-bindings.cpp) (Python bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and models"]
  node_landmarks["Landmark parsing"]
  node_mapping["Landmark mapping<br/>[LandmarkMapper.hpp]"]
  node_model["Morphable model<br/>[MorphableModel.hpp]"]
  node_pca["PCA model<br/>[PcaModel.hpp]"]
  node_modelio["Model loading<br/>[cvssp.hpp]"]
end

subgraph group_fit["Fitting"]
  node_pose["Pose estimation"]
  node_shape["Shape fitting"]
  node_fitflow["Iterative fitting<br/>[fitting.hpp]"]
  node_blendshape["Expression fitting"]
  node_edgefit["Edge fitting"]
  node_nonlinear["Nonlinear fitting"]
  node_multiframe["Multi-image fitting"]
end

subgraph group_output["Geometry and texture"]
  node_mesh["Mesh generation<br/>[Mesh.hpp]"]
  node_render["Software rendering<br/>[render.hpp]"]
  node_texture["Texture extraction"]
  node_meshio["OBJ output<br/>[write_obj.hpp]"]
  node_video["Keyframe texture merge"]
end

subgraph group_interfaces["Language interfaces"]
  node_python["Python bindings"]
  node_matlabfit["Matlab fitting<br/>[fitting.cpp]"]
end

node_user(("Image and landmarks"))
node_result["Mesh and texture"]
node_pythonuser(("Python caller"))
node_matlabuser(("Matlab caller"))

node_user -->|"provides landmarks"| node_landmarks
node_landmarks -->|"parsed points"| node_mapping
node_mapping -->|"mapped vertices"| node_pose
node_user -->|"provides image points"| node_pose
node_modelio -->|"loads model"| node_model
node_model -->|"contains PCA model"| node_pca
node_pose -->|"camera estimate"| node_fitflow
node_fitflow -->|"fits shape"| node_shape
node_fitflow -->|"fits expression"| node_blendshape
node_fitflow -->|"fits contours"| node_edgefit
node_fitflow -.->|"optional costs"| node_nonlinear
node_multiframe -->|"fits images"| node_fitflow
node_fitflow -->|"fitted shape"| node_mesh
node_model -->|"samples model"| node_mesh
node_mesh -->|"render input"| node_render
node_render -->|"rendered surface"| node_texture
node_mesh -->|"writes geometry"| node_meshio
node_texture -->|"extracts texture"| node_result
node_meshio -->|"writes mesh"| node_result
node_video -->|"extracts keyframe maps"| node_texture
node_video -->|"merges texture"| node_result
node_pythonuser -->|"calls bindings"| node_python
node_python -->|"exposes model API"| node_model
node_python -->|"exposes fitting API"| node_fitflow
node_matlabuser -->|"calls fitting"| node_matlabfit
node_matlabfit -->|"runs fitting"| node_fitflow

click node_landmarks "https://github.com/patrikhuber/eos/blob/master/include/eos/core/read_pts_landmarks.hpp"
click node_mapping "https://github.com/patrikhuber/eos/blob/master/include/eos/core/LandmarkMapper.hpp"
click node_model "https://github.com/patrikhuber/eos/blob/master/include/eos/morphablemodel/MorphableModel.hpp"
click node_pca "https://github.com/patrikhuber/eos/blob/master/include/eos/morphablemodel/PcaModel.hpp"
click node_modelio "https://github.com/patrikhuber/eos/blob/master/include/eos/morphablemodel/io/cvssp.hpp"
click node_pose "https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/orthographic_camera_estimation_linear.hpp"
click node_shape "https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/linear_shape_fitting.hpp"
click node_fitflow "https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/fitting.hpp"
click node_blendshape "https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/blendshape_fitting.hpp"
click node_edgefit "https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/closest_edge_fitting.hpp"
click node_nonlinear "https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/ceres_nonlinear.hpp"
click node_multiframe "https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/multi_image_fitting.hpp"
click node_mesh "https://github.com/patrikhuber/eos/blob/master/include/eos/core/Mesh.hpp"
click node_render "https://github.com/patrikhuber/eos/blob/master/include/eos/render/render.hpp"
click node_texture "https://github.com/patrikhuber/eos/blob/master/include/eos/render/texture_extraction.hpp"
click node_meshio "https://github.com/patrikhuber/eos/blob/master/include/eos/core/write_obj.hpp"
click node_video "https://github.com/patrikhuber/eos/blob/master/include/eos/video/keyframe_merging.hpp"
click node_python "https://github.com/patrikhuber/eos/blob/master/python/generate-python-bindings.cpp"
click node_matlabfit "https://github.com/patrikhuber/eos/blob/master/matlab/%2Beos/%2Bfitting/private/fitting.cpp"

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_landmarks,node_mapping,node_model,node_pca,node_modelio toneBlue
class node_pose,node_shape,node_fitflow,node_blendshape,node_edgefit,node_nonlinear,node_multiframe toneAmber
class node_mesh,node_render,node_texture,node_meshio,node_video toneMint
class node_python,node_matlabfit toneRose
class node_user,node_result,node_pythonuser,node_matlabuser toneIndigo
```

## Components

### Inputs and models

- [Landmark parsing](https://github.com/patrikhuber/eos/blob/master/include/eos/core/read_pts_landmarks.hpp): `include/eos/core/read_pts_landmarks.hpp`
- [Landmark mapping](https://github.com/patrikhuber/eos/blob/master/include/eos/core/LandmarkMapper.hpp): `include/eos/core/LandmarkMapper.hpp`
- [Morphable model](https://github.com/patrikhuber/eos/blob/master/include/eos/morphablemodel/MorphableModel.hpp): `include/eos/morphablemodel/MorphableModel.hpp`
- [PCA model](https://github.com/patrikhuber/eos/blob/master/include/eos/morphablemodel/PcaModel.hpp): `include/eos/morphablemodel/PcaModel.hpp`
- [Model loading](https://github.com/patrikhuber/eos/blob/master/include/eos/morphablemodel/io/cvssp.hpp): `include/eos/morphablemodel/io/cvssp.hpp`

### Fitting

- [Pose estimation](https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/orthographic_camera_estimation_linear.hpp): `include/eos/fitting/orthographic_camera_estimation_linear.hpp`
- [Shape fitting](https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/linear_shape_fitting.hpp): `include/eos/fitting/linear_shape_fitting.hpp`
- [Iterative fitting](https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/fitting.hpp): `include/eos/fitting/fitting.hpp`
- [Expression fitting](https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/blendshape_fitting.hpp): `include/eos/fitting/blendshape_fitting.hpp`
- [Edge fitting](https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/closest_edge_fitting.hpp): `include/eos/fitting/closest_edge_fitting.hpp`
- [Nonlinear fitting](https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/ceres_nonlinear.hpp): `include/eos/fitting/ceres_nonlinear.hpp`
- [Multi-image fitting](https://github.com/patrikhuber/eos/blob/master/include/eos/fitting/multi_image_fitting.hpp): `include/eos/fitting/multi_image_fitting.hpp`

### Geometry and texture

- [Mesh generation](https://github.com/patrikhuber/eos/blob/master/include/eos/core/Mesh.hpp): `include/eos/core/Mesh.hpp`
- [Software rendering](https://github.com/patrikhuber/eos/blob/master/include/eos/render/render.hpp): `include/eos/render/render.hpp`
- [Texture extraction](https://github.com/patrikhuber/eos/blob/master/include/eos/render/texture_extraction.hpp): `include/eos/render/texture_extraction.hpp`
- [OBJ output](https://github.com/patrikhuber/eos/blob/master/include/eos/core/write_obj.hpp): `include/eos/core/write_obj.hpp`
- [Keyframe texture merge](https://github.com/patrikhuber/eos/blob/master/include/eos/video/keyframe_merging.hpp): `include/eos/video/keyframe_merging.hpp`

### Language interfaces

- [Python bindings](https://github.com/patrikhuber/eos/blob/master/python/generate-python-bindings.cpp): `python/generate-python-bindings.cpp`
- [Matlab fitting](https://github.com/patrikhuber/eos/blob/master/matlab/%2Beos/%2Bfitting/private/fitting.cpp): `matlab/+eos/+fitting/private/fitting.cpp`

### Other components

- **Image and landmarks**
- **Mesh and texture**
- **Python caller**
- **Matlab caller**

## Connections

- Image and landmarks → Landmark parsing: provides landmarks
- Landmark parsing → Landmark mapping: parsed points
- Landmark mapping → Pose estimation: mapped vertices
- Image and landmarks → Pose estimation: provides image points
- Model loading → Morphable model: loads model
- Morphable model → PCA model: contains PCA model
- Pose estimation → Iterative fitting: camera estimate
- Iterative fitting → Shape fitting: fits shape
- Iterative fitting → Expression fitting: fits expression
- Iterative fitting → Edge fitting: fits contours
- Iterative fitting → Nonlinear fitting: optional costs
- Multi-image fitting → Iterative fitting: fits images
- Iterative fitting → Mesh generation: fitted shape
- Morphable model → Mesh generation: samples model
- Mesh generation → Software rendering: render input
- Software rendering → Texture extraction: rendered surface
- Mesh generation → OBJ output: writes geometry
- Texture extraction → Mesh and texture: extracts texture
- OBJ output → Mesh and texture: writes mesh
- Keyframe texture merge → Texture extraction: extracts keyframe maps
- Keyframe texture merge → Mesh and texture: merges texture
- Python caller → Python bindings: calls bindings
- Python bindings → Morphable model: exposes model API
- Python bindings → Iterative fitting: exposes fitting API
- Matlab caller → Matlab fitting: calls fitting
- Matlab fitting → Iterative fitting: runs fitting