# rohan-sawhney/fcpw architecture

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

- Interactive diagram: https://gitdiagram.com/rohan-sawhney/fcpw
- Repository: https://github.com/rohan-sawhney/fcpw

## Overview

##### Main Components
- Library Core (C++ API):
- The bulk of the code is contained within the “include/fcpw” directory. This directory is organized into submodules like “core” (basic types and operations), “aggregates” (data structures like BVH, MBVH, CSG nodes), “geometry” (for triangles, line segments, silhouette edges), “gpu” (GPU-specific shaders and interop elements), and “utilities” (scene handling and loaders).
- Classes such as Scene (templated with a dimension) and Interaction encapsulate the central functionality for performing geometric queries.
- Python API:
- The “python” directory shows that Python bindings/wrappers are provided (e.g., explicit 3D versions such as scene_3D and gpu_scene_3D) to mirror the C++ API.
- GPU Support:
- Within “include/fcpw/gpu” are the shader source files (with .slang extensions) and bridging headers (e.g., fcpw_gpu.h) to facilitate the GPU acceleration.
- Demos and Tests:
- The “demos” folder contains demonstration code in both C++ and Python.
- The “tests” folder provides unit tests (in C++ and Python) along with example inputs (like OBJ files) to validate the library’s functionality.
- Build and Dependency Management:
- The top-level CMakeLists.txt and associated CMakeLists.txt in demos, python, and tests show the project builds using CMake.
- The “deps” directory houses third-party libraries (e.g., enoki, eigen, and polyscope) and even a submodule for nanobind for Python binding construction.

##### Relationships and Interactions
- At the heart of the system is the Scene object (templated to work with arbitrary dimensions) which:
- Loads geometric input.
- Builds acceleration structures (using BVH or variants).
- Processes queries (closest point or ray intersection).
- When GPU acceleration is used, the CPU-built acceleration structures are sent over to the GPU (using GPUScene or gpu_scene_*D classes) and then processed in the GPU pipeline.
- The Python API wraps and mirrors these functionalities, allowing developers to call equivalent functions from Python.
- Demonstration components (the demos) illustrate usage patterns, and the tests verify that the various components work together correctly.

##### Architectural Patterns and Design Principles
- Modular Design: The separation into directories (core, aggregates, geometry, gpu, utilities) indicates a well-modularized design where each module has clear responsibilities.
- Template-Based & Dimensional Abstraction: The use of templates for the C++ Scene class to operate in multiple dimensions is a key architectural decision.
- Multi-Backend Implementation: There’s a clear separation between CPU (vectorized queries via Enoki or fallback to Eigen) and GPU processing (via Slang shaders and a dedicated GPUScene), demonstrating a multi-backend approach.
- Cross-Language Bindings: With both C++ and Python interfaces closely aligned, the design emphasizes consistency between the two language bindings.

##### Relevant Technologies and Frameworks
- C++: Header-only library with heavy use of templates.
- Python: Bindings created through nanobind.
- GPU: Slang shading language for GPU acceleration.
- Dependency Libraries: Enoki for CPU vectorization, Eigen as a fallback, polyscope (for demos), and nanobind for Python bindings.
- Build System: CMake for configuration and compilation.

##### Specific Elements to Illustrate
- From Input Geometry → Scene Loading in C++ → Acceleration Structure Build → Query Processing.
- From Scene → Transfer to GPU → GPU Query Processing.
- From the Python API layer → Calls to underlying C++ functions.
- Core Computational Modules (e.g., core, aggregates, geometry).
- GPU-specific modules.
- Interface layers (Python API and demos/tests).
- Supporting/build infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Input Geometry"]:::external
    B["FCPW Library Core (C++ API)"]:::cpp
    C["Core Submodule (Scene & Interaction)"]:::cpp
    D["Aggregates (BVH, MBVH, CSG)"]:::cpp
    E["Geometry Module (Triangles,2D/3D)"]:::cpp
    F["Utilities (Scene Loaders)"]:::cpp
    G["Scene Query Processing"]:::proc
    H["GPU Transfer/Query Processing"]:::proc
    I["GPU Module (Shaders & Interop)"]:::gpu
    J["Python API Bindings"]:::python
    K["Demos"]:::demo
    L["Tests"]:::demo
    M["Build & Dependencies (CMake,deps)"]:::build

    A --> B
    B --> C
    C --> D
    C --> E
    C --> F
    D --> G
    E --> G
    F --> G
    G -->|"GPUTransfer"| H
    H --> I
    J -->|"Calls"| C
    K -->|"Demonstrates"| C
    L -->|"Verifies"| C
    M --> B
    M --> J
    M --> K
    M --> L

    click B "https://github.com/rohan-sawhney/fcpw/tree/master/include/fcpw"
    click C "https://github.com/rohan-sawhney/fcpw/tree/master/include/fcpw/core"
    click D "https://github.com/rohan-sawhney/fcpw/tree/master/include/fcpw/aggregates"
    click E "https://github.com/rohan-sawhney/fcpw/tree/master/include/fcpw/geometry"
    click F "https://github.com/rohan-sawhney/fcpw/tree/master/include/fcpw/utilities"
    click I "https://github.com/rohan-sawhney/fcpw/tree/master/include/fcpw/gpu"
    click J "https://github.com/rohan-sawhney/fcpw/tree/master/python"
    click K "https://github.com/rohan-sawhney/fcpw/tree/master/demos"
    click L "https://github.com/rohan-sawhney/fcpw/tree/master/tests"
    click M "https://github.com/rohan-sawhney/fcpw/blob/master/CMakeLists.txt and deps"

    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef cpp fill:#bbf,stroke:#333,stroke-width:2px;
    classDef proc fill:#faa,stroke:#333,stroke-width:2px;
    classDef gpu fill:#dda,stroke:#333,stroke-width:2px;
    classDef python fill:#cfc,stroke:#333,stroke-width:2px;
    classDef demo fill:#fc9,stroke:#333,stroke-width:2px;
    classDef build fill:#ccc,stroke:#333,stroke-width:2px;
```
