# sgsellan/gpytoolbox architecture

> Architecture diagram of the GitHub repository sgsellan/gpytoolbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sgsellan/gpytoolbox
- Repository: https://github.com/sgsellan/gpytoolbox

## Overview

##### Project type and purpose
- This is an open-source Python library (“gpytoolbox”) for geometry processing, with optional high-performance C++ bindings.
- It provides hundreds of algorithms (mesh operators, FEM, distance computations, etc.) as pure Python functions and, where needed, native extensions via pybind11/CMake.
- It ships as a pip-installable package, with documentation built by MkDocs and a full test suite.

##### File structure
- Top-level:
- CMakeLists.txt + cmake/ → build scripts to compile C++ code into Python extension modules
- setup.py / pyproject.toml → Python packaging, pointing at both pure-Python sources and the compiled extensions
- mkdocs.yml + docs/ → source for the MkDocs documentation website
- .github/workflows/ → CI pipelines for Linux/Mac/Windows builds, testing, doc deployment
- src/
- src/gpytoolbox/ → the pure-Python package (one .py per algorithm, copyleft submodule)
- src/cpp/ → C++ implementation files and binding_* wrappers, organized by feature (remesher, swept_volume, tinyply, etc.)
- ext/pybind11 → embedded pybind11 submodule used by CMake to generate Python bindings
- test/ → pytest-style unit tests that import Python functions (and indirectly exercise C++ bindings) against sample mesh/data fixtures

##### Diagramming guidance
- Python API layer (“gpytoolbox” package)
- C++ extension layer (compiled modules built via CMake + pybind11)
- Build system (CMake, setup.py / pyproject.toml)
- External dependencies (NumPy, SciPy, libigl, mkdocs, pytest)
- Documentation site generator (MkDocs + docs sources)
- Continuous integration pipelines (GitHub Actions workflows)
b. Relationships & data flow:
- Python API calls → C++ extension functions through pybind11 bindings
- setup.py/pyproject.toml & CMakeLists.txt → orchestrate build of native modules during pip install or manual build
- docs/ + mkdocs.yml → MkDocs → published website
- .github/workflows → trigger build→ test (pytest) → bundle & publish to PyPI & docs hosting
c. Architectural patterns & principles:
- Layered architecture separating high-level Python algorithms from low-level C++ performance kernels
- Modular design: each geometry operator lives in its own Python file with a matching C++ binding source when needed
- CI/CD pipelines ensure cross-platform compatibility and continuous documentation publishing
d. Key technologies & frameworks:
- Python packaging: setuptools, pip, pyproject.toml
- Native extensions: CMake, pybind11, custom cmake/*.cmake modules for third-party libraries (igl, glfw3webgpu, nanoflann, webgpu)
- Documentation: MkDocs
- Testing: pytest
- CI: GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Source Code"
        PYAPI["Python API (src/gpytoolbox/)"]:::pythonComp
        CPPEXT["C++ Extensions (src/cpp/)"]:::nativeComp
        PYAPI -->|"calls via pybind11"| CPPEXT
    end

    subgraph "Build System"
        CMLIST["CMakeLists.txt"]:::tooling
        CMAKEDIR["cmake/"]:::tooling
        SETUP["setup.py"]:::tooling
        PYPROJ["pyproject.toml"]:::tooling
        extPybind["Pybind11 Submodule (ext/pybind11/)"]:::nativeComp

        CMLIST --> CPPEXT
        CMAKEDIR --> CPPEXT
        SETUP --> CPPEXT
        PYPROJ --> CPPEXT
        extPybind --> CMLIST
    end

    subgraph "Testing"
        TESTDIR["test/"]:::tooling
        TESTDATA["test/unit_tests_data/"]:::tooling
        TESTDIR --> PYAPI
        TESTDIR --> CPPEXT
        TESTDATA --> PYAPI
        TESTDATA --> CPPEXT
    end

    subgraph "Documentation"
        MKCFG["mkdocs.yml"]:::tooling
        DOCSDIR["docs/"]:::tooling
        DOCGEN["MkDocs Generator"]:::tooling
        Website[(gpytoolbox.org)]:::tooling

        MKCFG --> DOCGEN
        DOCSDIR --> DOCGEN
        DOCGEN -->|"publishes to"| Website
    end

    CI["CI Pipelines (.github/workflows/)"]:::tooling
    PyPI[(PyPI)]:::tooling

    CI --> CMLIST
    CI --> CMAKEDIR
    CI --> SETUP
    CI --> PYPROJ
    CI --> TESTDIR
    CI --> DOCGEN
    CI --> PyPI

    click PYAPI "https://github.com/sgsellan/gpytoolbox/tree/main/src/gpytoolbox/"
    click CPPEXT "https://github.com/sgsellan/gpytoolbox/tree/main/src/cpp/"
    click CMLIST "https://github.com/sgsellan/gpytoolbox/blob/main/CMakeLists.txt"
    click CMAKEDIR "https://github.com/sgsellan/gpytoolbox/tree/main/cmake/"
    click SETUP "https://github.com/sgsellan/gpytoolbox/blob/main/setup.py"
    click PYPROJ "https://github.com/sgsellan/gpytoolbox/blob/main/pyproject.toml"
    click extPybind "https://github.com/sgsellan/gpytoolbox/tree/main/ext/pybind11/"
    click MKCFG "https://github.com/sgsellan/gpytoolbox/blob/main/mkdocs.yml"
    click DOCSDIR "https://github.com/sgsellan/gpytoolbox/tree/main/docs/"
    click CI "https://github.com/sgsellan/gpytoolbox/tree/main/.github/workflows/"
    click TESTDIR "https://github.com/sgsellan/gpytoolbox/tree/main/test/"
    click TESTDATA "https://github.com/sgsellan/gpytoolbox/tree/main/test/unit_tests_data/"

    classDef pythonComp fill:#D6EAF8,stroke:#3498DB,color:#154360
    classDef nativeComp fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef tooling fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
```
