# mkazhdan/moebiusregistration architecture

> Architecture diagram of the GitHub repository mkazhdan/moebiusregistration, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mkazhdan/moebiusregistration
- Repository: https://github.com/mkazhdan/moebiusregistration

## Overview

##### Project type and purpose
- This is a C++-based scientific command-line toolkit for conformal parametrization and registration of genus-zero (water-tight) meshes.
- It provides three executables—SphereMap, Parametrization, and Register—that together compute conformal sphere mappings, center them via Möbius inversions (or spherical harmonics), tessellate to equirectangular grids, perform fast spherical correlation, and output registered meshes.

##### File structure
- Top level:
- / – header-only and source files for third-party dependencies (Eigen linear algebra, Misha’s geometry utilities, and FFTW wrappers).
- SOFT1.0/ – source for the SOFT library (spherical harmonic transforms and FFT routines).
- Parametrization/, Register/, SphereMap/ – each contains a single .cpp and .vcxproj (Visual Studio) defining one CLI tool.
- Makefile & MoebiusRegistration.sln – build scripts (Linux Make and Windows solution).
- Patterns:
- Modular CLI tools (each in its own directory).
- Layered architecture: CLI front-ends → core algorithms → third-party libraries → system & data I/O.

##### README for additional insights
- Confirms the three primary commands and their interactions (SphereMap first produces sphere parametrizations or .sgrid; Parametrization remaps meshes; Register aligns parametrizations via correlation).
- Lists external dependencies: Eigen (linear algebra), SOFT (spherical transforms), FFTW (FFT backbone).

##### Main components
a. Executable components (containers):
- SphereMap
- Parametrization
- Register
b. Core algorithm modules (libraries within the project):
- Conformalized Mean Curvature Flow
- Möbius/Spherical Harmonic Centering
- Tessellation to Equirectangular Grid
- Fast Spherical Correlation (via SOFT + FFTW)
c. Third-party libraries:
- Eigen – dense/sparse linear algebra
- SOFT 1.0 – spherical harmonic transforms
- FFTW – FFT engine (external .dll/.lib or system install)
- Misha Utilities – geometry, sparse solvers
d. Data artifacts:
- Input mesh (PLY)
- Parametrized mesh (PLY with px,py,pz)
- SGrid (.sgrid or PLY)
- Registered mesh (PLY)

##### Relationships and data flow
- SphereMap reads InputMesh → applies CMCF → Möbius/Spherical centering → tessellates → writes out ParametrizedMesh (+ optional SGrid).
- Parametrization reads ParametrizedMesh → rewrites purely spherical positions → writes OutputMesh.
- Register reads two ParametrizedMeshes or SGrids → performs spherical correlation (SOFT+FFTW) → writes RegisteredMesh.
- All executables invoke core algorithm modules, which link against Eigen, SOFT, FFTW, and Misha code.

##### Architectural patterns and design principles
- Layered decomposition: CLI layer → algorithm layer → library layer.
- Single-responsibility: each executable has one clear function in the pipeline.
- Dependency inversion: core algorithms coded against abstracted linear-algebra (Eigen) and FFT interfaces (SOFT/FFTW).
- Reuse of header-only libs (Eigen, Misha) for portability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Artifacts
    InputMesh["Input Mesh<br/>(PLY)"]:::data
    ParamMesh["Parametrized Mesh<br/>(PLY)"]:::data
    SGridFile["SGrid<br/>(.sgrid)"]:::data
    OutputMesh["Output Mesh<br/>(PLY)"]:::data
    RegisteredMesh["Registered Mesh<br/>(PLY)"]:::data

    %% Executables
    SphereMap["SphereMap"]:::exe
    Parametrization["Parametrization"]:::exe
    RegisterExec["Register"]:::exe

    %% Core Modules
    CMCF["Conformalized Mean<br/>Curvature Flow"]:::core
    Mobius["Möbius/Spherical Harmonic<br/>Centering"]:::core
    SGridModule["SphericalGrid"]:::core
    SquareGrid["SquareGrid"]:::core
    Correlation["Fast Spherical<br/>Correlation"]:::core

    %% Third-Party Libraries
    Eigen["Eigen"]:::lib
    MishaUtils["Misha Utilities"]:::lib
    SOFTLib["SOFT 1.0"]:::lib
    FFTW1["soft_fftw.h"]:::lib
    FFTW2["FST_semi_memo_fftw.h"]:::lib

    %% Relationships - Data Flow
    InputMesh -->|PLY| SphereMap
    SphereMap --> CMCF
    CMCF --> Mobius
    Mobius --> SGridModule
    Mobius --> SquareGrid
    SGridModule -->|grid| SGridFile
    SquareGrid -->|grid| ParamMesh
    SGridFile -->|.sgrid| RegisterExec
    ParamMesh -->|PLY| Parametrization
    Parametrization -->|PLY| OutputMesh
    ParamMesh -->|PLY| RegisterExec
    RegisterExec --> Correlation
    Correlation -->|PLY| RegisteredMesh

    %% Relationships - Executable to Core Modules
    SphereMap --> CMCF
    SphereMap --> Mobius
    SphereMap --> SGridModule
    SphereMap --> SquareGrid

    Parametrization --> SquareGrid

    RegisterExec --> Correlation

    %% Core Modules to Libraries
    CMCF --> Eigen
    CMCF --> MishaUtils
    Mobius --> MishaUtils
    SGridModule --> MishaUtils
    SquareGrid --> MishaUtils
    Correlation --> SOFTLib
    Correlation --> FFTW1
    Correlation --> FFTW2
    Correlation --> Eigen

    %% Executable Click Events
    click SphereMap "https://github.com/mkazhdan/moebiusregistration/blob/master/SphereMap/SphereMap.cpp"
    click Parametrization "https://github.com/mkazhdan/moebiusregistration/blob/master/Parametrization/Parametrization.cpp"
    click RegisterExec "https://github.com/mkazhdan/moebiusregistration/blob/master/Register/Register.cpp"

    %% Core Module Click Events
    click Mobius "https://github.com/mkazhdan/moebiusregistration/blob/master/Include/Misha/SphericalHarmonics.h"
    click SGridModule "https://github.com/mkazhdan/moebiusregistration/blob/master/Include/Misha/SphericalGrid.h"
    click SquareGrid "https://github.com/mkazhdan/moebiusregistration/blob/master/Include/Misha/SquareGrid.h"
    click Correlation "https://github.com/mkazhdan/moebiusregistration/blob/master/SOFT1.0/so3_correlate_fftw.cpp"
    click Correlation "https://github.com/mkazhdan/moebiusregistration/blob/master/SOFT1.0/so3_correlate_fftw.h"

    %% Library Click Events
    click SOFTLib "https://github.com/mkazhdan/moebiusregistration/tree/master/SOFT1.0/"
    click Eigen "https://github.com/mkazhdan/moebiusregistration/tree/master/Include/Eigen/"
    click MishaUtils "https://github.com/mkazhdan/moebiusregistration/tree/master/Include/Misha/"
    click FFTW1 "https://github.com/mkazhdan/moebiusregistration/blob/master/Include/soft_fftw.h"
    click FFTW2 "https://github.com/mkazhdan/moebiusregistration/blob/master/Include/FST_semi_memo_fftw.h"

    %% Styling
    classDef exe fill:#D0E8FF,stroke:#3B7DDD,stroke-width:1px,shape:roundrectangle
    classDef core fill:#DFFFD0,stroke:#3BB715,stroke-width:1px
    classDef lib fill:#FFE8B0,stroke:#DD7D03,stroke-width:1px,shape:cylinder
    classDef data fill:#E0E0E0,stroke:#7D7D7D,stroke-width:1px,shape:rectangular  	
    class SphereMap,Parametrization,RegisterExec exe
    class CMCF,Mobius,SGridModule,SquareGrid,Correlation core
    class Eigen,MishaUtils,SOFTLib,FFTW1,FFTW2 lib
    class InputMesh,ParamMesh,SGridFile,OutputMesh,RegisteredMesh data
```
