# idealab-isu/nurbsdiff architecture

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

- Interactive diagram: https://gitdiagram.com/idealab-isu/nurbsdiff
- Repository: https://github.com/idealab-isu/nurbsdiff

## Overview

##### Project Type and Purpose
- NURBSDiff is a specialized computational library. Its main purpose is to evaluate and fit NURBS (Non-Uniform Rational B-Splines) curves and surfaces to point cloud data.
- The project supports both CPU and CUDA-based GPU computation, making it a hybrid system that leverages native C++/CUDA backends via Python wrappers.
- The README and file structure suggest the library integrates with PyTorch and PyTorch3D, positioning it in a modern, deep-learning supported numerical simulation space.

##### File Structure Analysis
- The top-level directory contains the core NURBSDiff package, which includes:
- Python modules (e.g., curve_eval.py, nurbs_eval.py, surf_eval.py, utils.py) that serve as the primary interface for users.
- A csrc subdirectory that holds C++ and CUDA source files (curve_eval.cpp, curve_eval_cuda.cpp, associated CUDA kernels, and similar for surface evaluation) – these are the high-performance backends.
- The examples directory is extensive with numerous use cases (e.g., Aorta, Ducky, Hammer, Roof, ValveReconstruction, etc.), illustrating how different datasets or scenarios are handled.
- There is also a “train_open_spline_utils” submodule under examples that provides training configurations, augmentations, and model definitions for fitting curves/surfaces, indicating that the library can be integrated into machine learning pipelines.

##### Reading the README for Additional Insights
- The README identifies the core use of “curve_eval.py” for evaluating curves and outlines the input parameters (control points, point cloud data, evaluation points, etc.).
- Dependencies (PyTorch, PyTorch3D, Geomdl) indicate that the library relies on these frameworks for tensor computation, visualization, and potentially integrating neural network-based optimizations.

a. Main Components:
- Python Interface Layer: Represented by the primary Python modules (curve_eval.py, nurbs_eval.py, surf_eval.py, etc.). This layer interacts with end users and developers.
- C++/CUDA Backend Engine: Encapsulates the csrc folder modules (curve_eval.cpp, curve_eval_cuda.cpp, surf_eval_cuda_kernel.cu, surf_eval.cpp, etc.) which execute the heavy numerical computations.
- Utility Modules: Additional helpers and utility functions provided in utils.py (and possibly others), which assist in processing data and managing workflow.

b. Relationships and Interactions:

c. Architectural Patterns and Design Principles:
- Modular Design: Clearly separate core evaluation functionalities (curve vs. surface) and the utility components.
- Hybrid Computation: Illustrate the concept of using C++/CUDA for performance, invoked from Python.
- Extensibility: The organization of common utilities and examples shows the importance of clearly defined interfaces and plug-and-play components.

d. Technologies, Frameworks, and Libraries:
- Python: Primary layer for managing user inputs, wrapping functionalities, and orchestrating data flows.
- C++/CUDA: High-performance computing layer.
- PyTorch/PyTorch3D: External libraries that support GPU computation, autograd, and 3D operations.
- Geomdl: Provides additional NURBS and geometric operations.
- Example Tools: Various demonstration scripts and configuration files (YAML, JSON) hint at experimental or training pipelines for spline fitting.

##### Elements
- Annotation: Include brief annotations or notes to highlight key functions such as "curve_eval" and "surf_eval" to denote their roles in the overall evaluation/fitting process.

Final Note:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Examples / Application Layer
    subgraph "Examples / Application Layer"
        E1("Examples & Training Utils"):::examples
    end

    %% Python Interface Layer
    subgraph "Python Interface Layer"
        A1("Curve Evaluation (curve_eval.py)"):::python
        A2("NURBS Evaluation (nurbs_eval.py)"):::python
        A3("Surface Evaluation (surf_eval.py)"):::python
    end

    %% C++/CUDA Backend Engine
    subgraph "C++/CUDA Backend Engine"
        B1("Curve Eval C++ (curve_eval.cpp)"):::backend
        B2("Curve Eval CUDA (curve_eval_cuda.cpp)"):::backend
        B3("Curve Eval CUDA Kernel (curve_eval_cuda_kernel.cu)"):::backend
        B4("Surface Eval C++ (surf_eval.cpp)"):::backend
        B5("Surface Eval CUDA (surf_eval_cuda.cpp)"):::backend
        B6("Surface Eval CUDA Kernel (surf_eval_cuda_kernel.cu)"):::backend
    end

    %% Utility Modules
    subgraph "Utility Modules"
        U1("Python Utilities (utils.py)"):::utility
        U2("C++ Utilities (utils.cpp)"):::utility
        U3("C++ Utilities Header (utils.h)"):::utility
    end

    %% External Dependencies
    subgraph "External Dependencies"
        X1("PyTorch"):::external
        X2("PyTorch3D"):::external
        X3("Geomdl"):::external
    end

    %% Legacy / Experimental Code
    L1("Legacy Code (old)"):::legacy

    %% Connections
    E1 -->|"invokes"| A1
    E1 -->|"invokes"| A2
    E1 -->|"invokes"| A3

    A1 -->|"calls"| B1
    A1 -->|"calls"| B2
    A1 -->|"calls"| B3
    A3 -->|"calls"| B4
    A3 -->|"calls"| B5
    A3 -->|"calls"| B6

    A1 -->|"utilizes"| U1
    A2 -->|"utilizes"| U1
    A3 -->|"utilizes"| U1

    A1 -->|"uses"| X1
    A1 -->|"uses"| X2
    A1 -->|"uses"| X3

    B1 -->|"calls"| U2
    B1 -->|"calls"| U3

    L1 -->|"supersededBy"| A1

    %% Click Events
    click A1 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/curve_eval.py"
    click A2 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/nurbs_eval.py"
    click A3 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/surf_eval.py"

    click B1 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/csrc/curve_eval.cpp"
    click B2 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/csrc/curve_eval_cuda.cpp"
    click B3 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/csrc/curve_eval_cuda_kernel.cu"
    click B4 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/csrc/surf_eval.cpp"
    click B5 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/csrc/surf_eval_cuda.cpp"
    click B6 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/csrc/surf_eval_cuda_kernel.cu"

    click U1 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/utils.py"
    click U2 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/csrc/utils.cpp"
    click U3 "https://github.com/idealab-isu/nurbsdiff/blob/master/NURBSDiff/csrc/utils.h"

    click E1 "https://github.com/idealab-isu/nurbsdiff/tree/master/examples/"
    click L1 "https://github.com/idealab-isu/nurbsdiff/tree/master/NURBSDiff/old"

    %% Styles
    classDef python fill:#a2d5f2,stroke:#0b3d91,stroke-width:2px;
    classDef backend fill:#c3f584,stroke:#1d6d3f,stroke-width:2px;
    classDef utility fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef examples fill:#d7bde2,stroke:#6c3483,stroke-width:2px;
    classDef legacy fill:#d5dbdb,stroke:#808b96,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#f5b7b1,stroke:#922b21,stroke-width:2px;
```
