# wjakob/instant-meshes architecture

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

- Interactive diagram: https://gitdiagram.com/wjakob/instant-meshes
- Repository: https://github.com/wjakob/instant-meshes

## Overview

##### Project type and purpose
- This is a native C++ desktop application (an open-source tool) for interactive mesh retopology (“Instant Meshes”) developed for SIGGRAPH Asia 2015.
- It reads input 3D meshes, computes field-aligned quad meshes, and renders them interactively via a GUI.

##### File structure
- Top-level files: CMakeLists.txt (build), .travis.yml/.appveyor.yml (CI), README.md, LICENSE.txt.
- ext/ : third-party libraries (nanogui for the GUI, rply for PLY I/O, TBB for parallelism, pcg32 PRNG, etc.).
- src/ : core C++ modules grouped roughly by functionality:
- main.cpp, viewer.cpp/.h, widgets.cpp/.h, glutil.cpp/.h — application entry point, window + rendering, GUI widget wrappers, OpenGL utilities.
- meshio.cpp/.h, serializer.cpp/.h, gui_serializer.h — mesh file reading/writing and state persistence.
- adjacency.*, aabb.h, bvh.*, dedge.* — mesh data structures and acceleration structures.
- field.*, diff.cpp/.h, normal.cpp/.h — field computation modules (orientation, position fields, normals).
- extract.*, smoothcurve.*, subdivide.*, batch.cpp/.h — mesh processing pipeline steps (field to isolines, smoothing, subdivision).
- reorder.*, cleanup.* — post-processing and mesh cleanup.
- meshstats.* — mesh statistics and analysis utilities.
- hierarchy.* — multi-resolution or hierarchical processing support.

##### README for additional insights
- Confirms GUI workflow: “Open mesh” → solve orientation field → solve position field → export mesh.
- Mentions dependencies (X11 libs on Linux, Zenity), build instructions via CMake.
- Emphasizes interactive visualization, brushing tools, and advanced panels.

- Break the system into the six main components above.
- Blue for GUI,
- Green for Processing,
- Orange for Data Structures,
- Purple for External Libraries,
- Gray for Resources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "GUI Layer"
        direction TB
        MainCpp["main.cpp"]:::gui
        ViewerCpp["viewer.cpp"]:::gui
        ViewerH["viewer.h"]:::gui
        WidgetsCpp["widgets.cpp"]:::gui
        WidgetsH["widgets.h"]:::gui
        NanoGUI["NanoGUI"]:::external
    end

    subgraph "Mesh I/O & Serialization"
        direction TB
        MeshIOCpp["meshio.cpp"]:::io
        MeshIOH["meshio.h"]:::io
        SerializerCpp["serializer.cpp"]:::io
        SerializerH["serializer.h"]:::io
        GUISerializerH["gui_serializer.h"]:::io
        RPLY["rply"]:::external
    end

    subgraph "Core Data Structures"
        direction TB
        AdjCpp["adjacency.cpp"]:::data
        AdjH["adjacency.h"]:::data
        AABB["aabb.h"]:::data
        BVHCpp["bvh.cpp"]:::data
        BVHH["bvh.h"]:::data
        DedgeCpp["dedge.cpp"]:::data
        DedgeH["dedge.h"]:::data
        CommonH["common.h"]:::data
        HierarchyCpp["hierarchy.cpp"]:::data
        HierarchyH["hierarchy.h"]:::data
        MeshStatsCpp["meshstats.cpp"]:::data
        MeshStatsH["meshstats.h"]:::data
    end

    subgraph "Processing Pipeline"
        direction TB
        FieldCpp["field.cpp"]:::proc
        FieldH["field.h"]:::proc
        DiffCpp["diff.cpp"]:::proc
        NormalCpp["normal.cpp"]:::proc
        NormalH["normal.h"]:::proc
        ExtractCpp["extract.cpp"]:::proc
        ExtractH["extract.h"]:::proc
        SmoothCurveCpp["smoothcurve.cpp"]:::proc
        SmoothCurveH["smoothcurve.h"]:::proc
        SubdivideCpp["subdivide.cpp"]:::proc
        SubdivideH["subdivide.h"]:::proc
        CleanupCpp["cleanup.cpp"]:::proc
        CleanupH["cleanup.h"]:::proc
        ReorderCpp["reorder.cpp"]:::proc
        ReorderH["reorder.h"]:::proc
        BatchCpp["batch.cpp"]:::proc
        BatchH["batch.h"]:::proc
    end

    subgraph "Visualization & Rendering"
        direction TB
        GLUtilCpp["glutil.cpp"]:::vis
        GLUtilH["glutil.h"]:::vis
        ViewerDraw["Viewer Draw"]:::vis
        Shaders["Shaders (*.vert, *.frag, *.geo)"]:::resources
    end

    subgraph "External Libraries & Tools"
        direction TB
        TBB["TBB"]:::external
        PCG["PCG32"]:::external
        HALF["half"]:::external
    end

    %% Data Flow
    MainCpp -->|load mesh| MeshIOCpp
    MeshIOCpp -->|populate| AdjCpp
    MeshIOCpp -->|populate| DedgeCpp
    MeshIOCpp -->|populate| BVHCpp
    AdjCpp -->|defines| CommonH
    DedgeCpp -->|depends on| CommonH
    BVHCpp -->|accelerates| AdjCpp
    AdjCpp -->|provides| FieldCpp
    FieldCpp -->|compute| DiffCpp
    DiffCpp -->|solve| NormalCpp
    NormalCpp -->|output| ExtractCpp
    ExtractCpp -->|generate| SmoothCurveCpp
    SmoothCurveCpp -->|smooth| SubdivideCpp
    SubdivideCpp -->|refine| CleanupCpp
    CleanupCpp -->|clean| ReorderCpp
    ReorderCpp -->|order| BatchCpp
    BatchCpp -->|finalize| MeshIOCpp
    BatchCpp -->|update| ViewerDraw
    ExtractCpp -->|preview| ViewerDraw
    MainCpp -->|render| ViewerDraw
    ViewerDraw -->|uses| GLUtilCpp
    GLUtilCpp -->|loads| Shaders

    %% External Links
    NanoGUI -.-> MainCpp
    TBB -.-> FieldCpp
    RPLY -.-> MeshIOCpp
    PCG -.-> DiffCpp
    HALF -.-> NormalCpp

    %% Click Events
    click MainCpp "https://github.com/wjakob/instant-meshes/blob/master/src/main.cpp"
    click ViewerCpp "https://github.com/wjakob/instant-meshes/blob/master/src/viewer.cpp"
    click ViewerH "https://github.com/wjakob/instant-meshes/blob/master/src/viewer.h"
    click WidgetsCpp "https://github.com/wjakob/instant-meshes/blob/master/src/widgets.cpp"
    click WidgetsH "https://github.com/wjakob/instant-meshes/blob/master/src/widgets.h"
    click NanoGUI "https://github.com/wjakob/instant-meshes/tree/master/ext/nanogui"
    click MeshIOCpp "https://github.com/wjakob/instant-meshes/blob/master/src/meshio.cpp"
    click MeshIOH "https://github.com/wjakob/instant-meshes/blob/master/src/meshio.h"
    click SerializerCpp "https://github.com/wjakob/instant-meshes/blob/master/src/serializer.cpp"
    click SerializerH "https://github.com/wjakob/instant-meshes/blob/master/src/serializer.h"
    click GUISerializerH "https://github.com/wjakob/instant-meshes/blob/master/src/gui_serializer.h"
    click RPLY "https://github.com/wjakob/instant-meshes/tree/master/ext/rply"
    click AdjCpp "https://github.com/wjakob/instant-meshes/blob/master/src/adjacency.cpp"
    click AdjH "https://github.com/wjakob/instant-meshes/blob/master/src/adjacency.h"
    click AABB "https://github.com/wjakob/instant-meshes/blob/master/src/aabb.h"
    click BVHCpp "https://github.com/wjakob/instant-meshes/blob/master/src/bvh.cpp"
    click BVHH "https://github.com/wjakob/instant-meshes/blob/master/src/bvh.h"
    click DedgeCpp "https://github.com/wjakob/instant-meshes/blob/master/src/dedge.cpp"
    click DedgeH "https://github.com/wjakob/instant-meshes/blob/master/src/dedge.h"
    click CommonH "https://github.com/wjakob/instant-meshes/blob/master/src/common.h"
    click HierarchyCpp "https://github.com/wjakob/instant-meshes/blob/master/src/hierarchy.cpp"
    click HierarchyH "https://github.com/wjakob/instant-meshes/blob/master/src/hierarchy.h"
    click MeshStatsCpp "https://github.com/wjakob/instant-meshes/blob/master/src/meshstats.cpp"
    click MeshStatsH "https://github.com/wjakob/instant-meshes/blob/master/src/meshstats.h"
    click FieldCpp "https://github.com/wjakob/instant-meshes/blob/master/src/field.cpp"
    click FieldH "https://github.com/wjakob/instant-meshes/blob/master/src/field.h"
    click DiffCpp "https://github.com/wjakob/instant-meshes/blob/master/src/diff.cpp"
    click NormalCpp "https://github.com/wjakob/instant-meshes/blob/master/src/normal.cpp"
    click NormalH "https://github.com/wjakob/instant-meshes/blob/master/src/normal.h"
    click ExtractCpp "https://github.com/wjakob/instant-meshes/blob/master/src/extract.cpp"
    click ExtractH "https://github.com/wjakob/instant-meshes/blob/master/src/extract.h"
    click SmoothCurveCpp "https://github.com/wjakob/instant-meshes/blob/master/src/smoothcurve.cpp"
    click SmoothCurveH "https://github.com/wjakob/instant-meshes/blob/master/src/smoothcurve.h"
    click SubdivideCpp "https://github.com/wjakob/instant-meshes/blob/master/src/subdivide.cpp"
    click SubdivideH "https://github.com/wjakob/instant-meshes/blob/master/src/subdivide.h"
    click CleanupCpp "https://github.com/wjakob/instant-meshes/blob/master/src/cleanup.cpp"
    click CleanupH "https://github.com/wjakob/instant-meshes/blob/master/src/cleanup.h"
    click ReorderCpp "https://github.com/wjakob/instant-meshes/blob/master/src/reorder.cpp"
    click ReorderH "https://github.com/wjakob/instant-meshes/blob/master/src/reorder.h"
    click BatchCpp "https://github.com/wjakob/instant-meshes/blob/master/src/batch.cpp"
    click BatchH "https://github.com/wjakob/instant-meshes/blob/master/src/batch.h"
    click GLUtilCpp "https://github.com/wjakob/instant-meshes/blob/master/src/glutil.cpp"
    click GLUtilH "https://github.com/wjakob/instant-meshes/blob/master/src/glutil.h"
    click Shaders "https://github.com/wjakob/instant-meshes/tree/master/resources"
    click TBB "https://github.com/wjakob/instant-meshes/tree/master/ext/tbb"
    click PCG "https://github.com/wjakob/instant-meshes/tree/master/ext/pcg32"
    click HALF "https://github.com/wjakob/instant-meshes/tree/master/ext/half"

    %% Styles
    classDef gui fill:#ADD8E6,stroke:#333;
    classDef io fill:#D3D3D3,stroke:#333;
    classDef data fill:#FFA500,stroke:#333;
    classDef proc fill:#90EE90,stroke:#333;
    classDef vis fill:#DDA0DD,stroke:#333;
    classDef external fill:#D8BFD8,stroke:#333;
    classDef resources fill:#C0C0C0,stroke:#333,stroke-dasharray: 5 5;
```
