# mclemot/skeletonlearning architecture

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

- Interactive diagram: https://gitdiagram.com/mclemot/skeletonlearning
- Repository: https://github.com/mclemot/skeletonlearning

## Overview

##### Project type and purpose
- This is a research-oriented data-processing and machine-learning pipeline for 3D medial skeleton extraction.
- It ingests 3D meshes or point clouds, trains or loads implicit neural networks (INRs) to approximate a distance field, extracts a medial skeleton, and optionally renders results in Blender.

##### High-level components
A. Data
- Pretrained network snapshots in `Pretrained/`
B. I/O & Preprocessing
- io3d.py: loads meshes/point clouds, extracts points & normals
- geometry.py & distances.py: compute SDFs, distance transforms, normals processing
- tools.py & display.py: sampling, plotting helper functions
C. Neural Network Core
- nn.py: base network definitions
- siren_nn.py, igr_nn.py, build_*.py: wrappers to build variants (SIREN, IGR, SoftPlus, ReLU)
- pretrain.py: training loop that fits an INR to sampled surface data (PyTorch backend)
D. Skeleton Extraction
- build_coverage_skeleton.py, build_neural_skeleton.py, build_siren_neural_skeleton.py, build_igr_neural_skeleton.py: end-to-end scripts
- main.py: unified entry point (`python main.py [input] [output]`)
E. Experiment & Reproducibility Scripts
- reproduce_*.py: orchestrate benchmarking, cube/torus fertility experiments, full render pipelines
F. Visualization & Rendering
- render.py: generates slices, point clouds, saves intermediate files
- BlenderToolbox/ & display.py: prepare Blender scenes and run headless renders

##### Interactions & Data Flow
- Data Input → I/O & Preprocessing → (Uniform) Sampling → INR Training (pretrain.py) → Model Checkpoint
- Checkpoint → Skeleton Extraction (main.py or build_*.py) → Skeletal .obj output
- compare/benchmark scripts call these building blocks in sequence and dump results under `Comparisons/` and `Results/`

##### Architectural patterns & principles
- Pipeline architecture: clear separation between Data Ingest → Model Training → Inference → Visualization
- Modular ML components: interchangeable INR architectures (SIREN, SoftPlus, ReLU) under a shared interface
- Scriptable experiments: reproducibility through dedicated top-level scripts (reproduce_*.py)

##### Technologies & frameworks
- Python 3.10
- PyTorch for neural network training and inference
- NumPy, SciPy for numerical computations
- PyGEL3D, gudhi for geometry & topology processing
- Blender (bpy) for 3D renderings
- matplotlib, tabulate for plotting and CLI tabular outputs

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data" 
        direction TB
        Objects["Objects"]:::dataio
        Comparisons["Comparisons"]:::dataio
        Pretrained["Pretrained"]:::dataio
    end

    subgraph "I/O & Preprocessing"
        direction TB
        io3d["io3d.py"]:::dataio
        geometry["geometry.py"]:::dataio
        distances["distances.py"]:::dataio
        tools["tools.py"]:::dataio
        display["display.py"]:::dataio
    end

    subgraph "ML Core"
        direction TB
        nn["nn.py"]:::ml
        siren_nn["siren_nn.py"]:::ml
        igr_nn["igr_nn.py"]:::ml
        pretrain["pretrain.py"]:::ml
    end

    subgraph "Skeleton Extraction"
        direction TB
        skeleton["skeleton.py"]:::extract
        build_cov["build_coverage_skeleton.py"]:::extract
        build_neu["build_neural_skeleton.py"]:::extract
        build_siren["build_siren_neural_skeleton.py"]:::extract
        build_igr["build_igr_neural_skeleton.py"]:::extract
        main["main.py"]:::extract
    end

    subgraph "Rendering & Visualization"
        direction TB
        render["render.py"]:::render
        BlenderToolbox["BlenderToolbox"]:::render
    end

    subgraph "Experiments"
        direction TB
        repro_bench["reproduce_benchmark.py"]:::exp
        repro_cube["reproduce_cube.py"]:::exp
        repro_fert["reproduce_fertility.py"]:::exp
        repro_rend["reproduce_renderings.py"]:::exp
        repro_torus["reproduce_torus.py"]:::exp
    end

    Objects -->|".obj/.xyz → points+normals"| io3d
    Comparisons -->|".obj/.xyz → points+normals"| io3d
    io3d -->|"raw points+normals"| geometry
    geometry -->|"SDF & normals"| distances
    distances -->|"samples"| tools
    tools -->|"plots"| display
    tools -->|"sampled data"| pretrain
    pretrain -->|"trained .net checkpoint"| skeleton
    Pretrained -->|"loaded checkpoint"| skeleton
    skeleton -->|".obj skeleton mesh"| render
    main -->|".obj skeleton mesh"| render
    render -->|"scene files"| BlenderToolbox

    repro_bench -->|run pipeline| io3d
    repro_bench -->|run pipeline| pretrain
    repro_bench -->|run pipeline| skeleton
    repro_bench -->|run pipeline| render

    repro_cube -->|run pipeline| io3d
    repro_fert -->|run pipeline| pretrain
    repro_torus -->|run pipeline| skeleton
    repro_rend -->|run pipeline| render

    classDef dataio fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ml fill:#d4edda,stroke:#333,stroke-width:1px
    classDef extract fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef render fill:#e5ccff,stroke:#333,stroke-width:1px
    classDef exp fill:#e5e5e5,stroke:#333,stroke-width:1px

    click Objects "https://github.com/mclemot/skeletonlearning/tree/main/Objects/"
    click Comparisons "https://github.com/mclemot/skeletonlearning/tree/main/Comparisons/"
    click Pretrained "https://github.com/mclemot/skeletonlearning/tree/main/Pretrained/"
    click io3d.py "https://github.com/mclemot/skeletonlearning/blob/main/io3d.py"
    click geometry.py "https://github.com/mclemot/skeletonlearning/blob/main/geometry.py"
    click distances.py "https://github.com/mclemot/skeletonlearning/blob/main/distances.py"
    click tools.py "https://github.com/mclemot/skeletonlearning/blob/main/tools.py"
    click display.py "https://github.com/mclemot/skeletonlearning/blob/main/display.py"
    click nn.py "https://github.com/mclemot/skeletonlearning/blob/main/nn.py"
    click siren_nn.py "https://github.com/mclemot/skeletonlearning/blob/main/siren_nn.py"
    click igr_nn.py "https://github.com/mclemot/skeletonlearning/blob/main/igr_nn.py"
    click pretrain.py "https://github.com/mclemot/skeletonlearning/blob/main/pretrain.py"
    click skeleton.py "https://github.com/mclemot/skeletonlearning/blob/main/skeleton.py"
    click build_coverage_skeleton.py "https://github.com/mclemot/skeletonlearning/blob/main/build_coverage_skeleton.py"
    click build_neural_skeleton.py "https://github.com/mclemot/skeletonlearning/blob/main/build_neural_skeleton.py"
    click build_siren_neural_skeleton.py "https://github.com/mclemot/skeletonlearning/blob/main/build_siren_neural_skeleton.py"
    click build_igr_neural_skeleton.py "https://github.com/mclemot/skeletonlearning/blob/main/build_igr_neural_skeleton.py"
    click main.py "https://github.com/mclemot/skeletonlearning/blob/main/main.py"
    click render.py "https://github.com/mclemot/skeletonlearning/blob/main/render.py"
    click BlenderToolbox "https://github.com/mclemot/skeletonlearning/tree/main/BlenderToolbox/"
    click reproduce_benchmark.py "https://github.com/mclemot/skeletonlearning/blob/main/reproduce_benchmark.py"
    click reproduce_cube.py "https://github.com/mclemot/skeletonlearning/blob/main/reproduce_cube.py"
    click reproduce_fertility.py "https://github.com/mclemot/skeletonlearning/blob/main/reproduce_fertility.py"
    click reproduce_renderings.py "https://github.com/mclemot/skeletonlearning/blob/main/reproduce_renderings.py"
    click reproduce_torus.py "https://github.com/mclemot/skeletonlearning/blob/main/reproduce_torus.py"
```
