# schillij95/thaumatoanakalyptor architecture

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

- Interactive diagram: https://gitdiagram.com/schillij95/thaumatoanakalyptor
- Repository: https://github.com/schillij95/thaumatoanakalyptor

## Overview

##### Project type and purpose
- This is a specialized full-stack data-processing and visualization pipeline (not a web app) that automates segmentation of papyrus sheets from CT-scan volumes. It combines:
- A Python “orchestrator” (ThaumatoAnakalyptor.py) and CLI/GUI frontend
- Deep-learning 3D instance segmentation (Mask3D)
- Graph‐based patch stitching (C++ solver)
- Mesh reconstruction and texturing
- Utilities for pre/post-processing (point clouds, rendering, etc.)

##### File structure to extract architectural modules
- Top level
- DockerfileThaumato – defines containerizing environment
- GUI/ – PyQt GUI code
- ThaumatoAnakalyptor.py – entry point, dispatches CLI/GUI tasks
- ThaumatoAnakalyptor/ – core Python package
- Vesuvius-Grandprize-Winner/ – ink detection model (external repo submodule)
- In ThaumatoAnakalyptor/:
- mask3d/ – 3D instance-segmentation neural net (PyTorch, configs, models, training scripts)
- graph_problem/ – C++ code and CUDA solver for sheet-patch optimization
- sheet_generation/ – C++ library and Python bindings for HDBSCAN clustering and sheet‐stitching
- Utilities – pointcloud/mesh converters, rendering, BP node deactivation, belief_propagation modules
- Data folders under mask3d (conf/, data/, models/, scripts/, third_party, trainer, utils) show a standard ML training/inference sub-architecture.

##### README for additional insights
- The README describes a multi-stage pipeline:
a. Volume preprocessing & grid generation
b. PointCloud extraction
c. 3D instance segmentation (Mask3D)
d. Patch graph construction & optimization (graph_problem)
e. Mesh reconstruction (Poisson)
f. Texture unwrapping (Volume Cartographer)
g. GUI for interactive use

##### Detailed capturing of essential elements
- Third-party modules (pointnet2, HDBSCAN) as sub-blocks within mask3d/sheet_generation
- Denote entry point “ThaumatoAnakalyptor.py” as the central orchestrator

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker container boundary
    subgraph "Docker Container"
        direction TB
        OC["ThaumatoAnakalyptor.py\n(Orchestrator)"]:::python
        OC -->|dispatch| GUI
        OC -->|dispatch| CLI

        subgraph "Frontend" 
            direction TB
            GUI["PyQt GUI"]:::python
            CLI["CLI"]:::python
        end

        OC --> Pre["Preprocessing"]:::python
        Pre --> PC["PointCloud Module"]:::python
        PC --> ML["Mask3D Inference"]:::ml
        ML --> IG["instances_to_graph"]:::python
        IG --> GS["Graph Solver (C++/CUDA)"]:::cpp
        GS --> MR["Mesh Reconstruction"]:::python
        MR --> TX["Texturing Module"]:::python
    end

    %% Data Stores
    vol["Input volpkg\n(CT Volume)"]:::data
    grid["Grid TIFFs"]:::data
    ply[".ply PointCloud"]:::data
    mask["Instance Masks"]:::data
    graphBin["graph.bin"]:::data
    meshObj["mesh.obj"]:::data
    finalMesh["Textured Mesh\n(output)"]:::data

    %% External Hardware
    GPU(["GPU"]):::ext
    CPU(["CPU"]):::ext

    %% Data Flow
    vol -->|volpkg| OC
    Pre -->|2D TIFF grids| grid
    grid -->|reads| PC
    PC -->|.ply PointCloud| ply
    ply -->|reads| ML
    ML -->|Instance Masks| mask
    mask -->|builds graph| IG
    IG -->|graph.bin| graphBin
    graphBin -->|optimize| GS
    GS -->|solved graph.bin| graphBin
    graphBin -->|to mesh| MR
    MR -->|mesh.obj| meshObj
    meshObj -->|to texturing| TX
    TX -->|final UV mesh| finalMesh

    %% Hardware associations
    GPU --> ML
    GPU --> GS
    CPU --> OC

    %% Click events
    click GUI "https://github.com/schillij95/thaumatoanakalyptor/tree/main/GUI/"
    click GUI/ConfigWindow.py "https://github.com/schillij95/thaumatoanakalyptor/blob/main/GUI/ConfigWindow.py"
    click GUI/MainWindow.py "https://github.com/schillij95/thaumatoanakalyptor/blob/main/GUI/MainWindow.py"
    click GUI/CollapsibleBox.py "https://github.com/schillij95/thaumatoanakalyptor/blob/main/GUI/CollapsibleBox.py"
    click GUI/UmbilicusWindow.py "https://github.com/schillij95/thaumatoanakalyptor/blob/main/GUI/UmbilicusWindow.py"
    click OC "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor.py"
    click OC "https://github.com/schillij95/thaumatoanakalyptor/tree/main/ThaumatoAnakalyptor/"
    click Pre "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/generate_half_sized_grid.py"
    click Pre "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/cut_tif_region.py"
    click Pre "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/split_mesh.py"
    click PC "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/grid_to_pointcloud.py"
    click ML "https://github.com/schillij95/thaumatoanakalyptor/tree/main/ThaumatoAnakalyptor/mask3d/"
    click ML "https://github.com/schillij95/thaumatoanakalyptor/tree/main/ThaumatoAnakalyptor/mask3d/conf/"
    click ML "https://github.com/schillij95/thaumatoanakalyptor/tree/main/ThaumatoAnakalyptor/mask3d/models/"
    click ML "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/mask3d/inference.py"
    click ML "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/mask3d/main_instance_segmentation.py"
    click GS "https://github.com/schillij95/thaumatoanakalyptor/tree/main/ThaumatoAnakalyptor/graph_problem/"
    click GS "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/graph_problem/main_gpu.cpp"
    click GS "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/graph_problem/solve_gpu.cu"
    click IG "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/instances_to_graph.py"
    click SG "https://github.com/schillij95/thaumatoanakalyptor/tree/main/ThaumatoAnakalyptor/sheet_generation/"
    click SG "https://github.com/schillij95/thaumatoanakalyptor/tree/main/ThaumatoAnakalyptor/sheet_generation/pybind11/"
    click MR "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/graph_to_mesh.py"
    click MR "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/sheet_to_mesh.py"
    click MR "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/finalize_mesh.py"
    click TX "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/large_mesh_to_surface.py"
    click TX "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/mesh_to_uv.py"
    click TX "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/slim_uv.py"
    click U1 "https://github.com/schillij95/thaumatoanakalyptor/blob/main/ThaumatoAnakalyptor/pointcloud_to_instances.py"
    click U2 "https://github.com/schillij95/thaumatoanakalyptor/tree/main/ThaumatoAnakalyptor/rendering_utils/"
    click U3 "https://github.com/schillij95/thaumatoanakalyptor/tree/main/ThaumatoAnakalyptor/BP_node_deactivation/"
    click U4 "https://github.com/schillij95/thaumatoanakalyptor/tree/main/ThaumatoAnakalyptor/belief_propagation/"

    %% Styles
    classDef python fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef cpp fill:#d4edda,stroke:#28a745,color:#000;
    classDef ml fill:#ffe5b4,stroke:#ff9900,color:#000;
    classDef data fill:#ececec,stroke:#999999,color:#000,shape:cylinder;
    classDef ext fill:#f5f5f5,stroke:#666666,color:#000,shape:hexagon;
```
