# emmanuel-hartman/h2_surfacematch architecture

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

- Interactive diagram: https://gitdiagram.com/emmanuel-hartman/h2_surfacematch
- Repository: https://github.com/emmanuel-hartman/h2_surfacematch

## Overview

##### Main Components
- Core Algorithms/Modules:
– Files like H2_deformation_transfer.py, H2_ivp.py, H2_match.py, H2_match_coeffs.py, H2_param.py, H2_partial_match.py, H2_stats.py, and SRNF_match.py represent core functionalities (e.g., deformation, initial value problems, and matching using different metrics).
- Enhanced/Utility Modules:
– The ‘enr’ directory contains modules such as H2.py, DDG.py, SRNF.py, regularizers.py, rigid_match.py, and varifold.py which likely implement lower-level routines, refined calculations, and regularization methods supporting the main algorithms.
- Input/Output and Helpers:
– The ‘utils’ directory (with files like input_output.py and utils.py) contains helper functions to support file I/O, data preprocessing, and other auxiliary tasks.
- Demonstrations and Use-Cases:
– The ‘demo’ folder includes several Jupyter notebooks (e.g., initial-value-problem.ipynb, matching-faces.ipynb, motion-transfer.ipynb, etc.) that showcase the practical usage scenarios for the tools provided by the package.
- Supporting Resources:
– The ‘figures’ directory contains sample images and animations that are referenced in the README, helping visually explain outputs and examples.

##### Relationships and Interactions
- Data Flow:
– Input data (often triangulated surfaces read/processed via Open3D or alternative libraries) is passed into the core matching and deformation routines.
– Core modules (H2_*.py, SRNF_match.py) call lower-level functions from the ‘enr’ modules to compute distances, deformations, and apply regularizers.
– Processed outputs can be sent to the demo notebooks for visualization and further analysis, making use of utils for any data formatting or plotting.
- Dependency Flow:
– The core algorithms depend on external libraries like Numpy, Scipy, Pytorch (with CUDA support), and PyKeops.
– The ‘enr’ modules provide the mathematical and numerical backbone which is reused by the higher-level scripts in project root.
- Architectural Patterns:
– Modular decomposition: clear separation between high-level functionalities (matching, interpolation) and lower-level implementations (discrete differential geometry, rigid matching) that are housed in distinct directories.
– Pipeline Flow: Data ingestion (from demo scripts or external sources) → pre-processing (via utils) → core processing (main H2 modules invoking enr functions) → statistical analysis and visualization (via demo notebooks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        EXT1["Numpy/Scipy"]:::external
        EXT2["PyTorch (CUDA)"]:::external
        EXT3["PyKeops"]:::external
        EXT4["Open3D"]:::external
    end

    %% User/Demo Interface
    subgraph "User/Demo Interface"
        Demo["Demo Notebooks"]:::demo
    end

    %% Utility Layer
    subgraph "Utility Layer"
        U1["input_output.py"]:::utils
        U2["utils.py"]:::utils
    end

    %% Core Processing Engine
    subgraph "Core Processing Engine"
        C1["H2_deformation_transfer.py: Deformation Transfer"]:::core
        C2["H2_ivp.py: Initial Value Problems"]:::core
        C3["H2_match.py: Geodesic Matching"]:::core
        C4["H2_match_coeffs.py: Matching Coefficients"]:::core
        C5["H2_param.py: Parameter Setup"]:::core
        C6["H2_partial_match.py: Partial(Varifold) Matching"]:::core
        C7["H2_stats.py: Statistical Analysis"]:::core
        C8["SRNF_match.py: SRNF Matching"]:::core
    end

    %% ENR Modules
    subgraph "ENR Modules"
        E1["H2.py: Core Math Routines"]:::enr
        E2["DDG.py: Discrete Differential Geometry"]:::enr
        E3["SRNF.py: SRNF Computations"]:::enr
        E4["regularizers.py: Regularization Methods"]:::enr
        E5["rigid_match.py: Rigid Matching"]:::enr
        E6["varifold.py: Varifold Operations"]:::enr
    end

    %% Supporting Resources
    subgraph "Supporting Resources"
        Figures["Figures: Sample Images & Animations"]:::resource
    end

    %% Arrows for Data Flow and Dependency
    %% Data ingestion from External Dependencies and Demo Interface
    EXT1 -->|"provides-data"| U1
    EXT2 -->|"GPU compute"| C3
    EXT4 -->|"mesh data"| C1
    Demo -->|"input-data"| U1

    %% Utility Layer to Core Processing Engine
    U1 -->|"preprocessed-data"| C1
    U2 -->|"helper-util"| C1

    %% Internal Core Processing Flow (representative connections)
    C1 -->|"setup-IVP"| C2
    C2 -->|"initiatesMatching"| C3
    C3 -->|"coefficientCalc"| C4
    C4 -->|"parameterSetup"| C5
    C5 -->|"partialMatching"| C6
    C6 -->|"statsComputation"| C7
    C7 -->|"SRNF-calls"| C8

    %% Core Algorithms invoking ENR Modules
    C3 -->|"calls"| E1
    C6 -->|"uses"| E6

    %% Statistical Analysis results visualized in Demo
    C7 -->|"visualizes"| Demo

    %% Supporting Resources aiding visualization
    Figures -->|"reference visuals"| Demo

    %% Styles
    classDef external fill:#FFCCFF,stroke:#990099,stroke-width:2px,color:#000;
    classDef demo fill:#CCE5FF,stroke:#0056b3,stroke-width:2px,color:#000;
    classDef utils fill:#CCFFCC,stroke:#228B22,stroke-width:2px,color:#000;
    classDef core fill:#FFD6A5,stroke:#FF8C00,stroke-width:2px,color:#000;
    classDef enr fill:#D0F0FD,stroke:#008B8B,stroke-width:2px,color:#000;
    classDef resource fill:#FFF2CC,stroke:#B8860B,stroke-width:2px,color:#000;

    %% Click Events for Core Algorithms/Modules
    click C1 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/H2_deformation_transfer.py"
    click C2 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/H2_ivp.py"
    click C3 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/H2_match.py"
    click C4 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/H2_match_coeffs.py"
    click C5 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/H2_param.py"
    click C6 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/H2_partial_match.py"
    click C7 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/H2_stats.py"
    click C8 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/SRNF_match.py"

    %% Click Events for ENR Modules
    click E1 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/enr/H2.py"
    click E2 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/enr/DDG.py"
    click E3 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/enr/SRNF.py"
    click E4 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/enr/regularizers.py"
    click E5 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/enr/rigid_match.py"
    click E6 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/enr/varifold.py"

    %% Click Events for Utils
    click U1 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/utils/input_output.py"
    click U2 "https://github.com/emmanuel-hartman/h2_surfacematch/blob/main/utils/utils.py"

    %% Click Event for Demo Notebooks (using the demo directory)
    click Demo "https://github.com/emmanuel-hartman/h2_surfacematch/tree/main/demo"

    %% Click Event for Supporting Resources
    click Figures "https://github.com/emmanuel-hartman/h2_surfacematch/tree/main/figures"
```
