# k-3d/k3d architecture

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

- Interactive diagram: https://gitdiagram.com/k-3d/k3d
- Repository: https://github.com/k-3d/k3d

## Overview

##### Main Components/Subsystems
- Application Layer:
- This includes the executable entry points (found in the “application” directory) along with platform-specific or desktop integration components (e.g. “desktop”, distribution files for various platforms, and the “web” directory for online resources).
- The UI components are also present in dedicated directories like “k3dsdk/ngui”, “qtui”, and “ngui” subdirectories. They handle the overall user input, viewport rendering, and GUI dialogs.

- Core Engine / SDK:
- The “k3dsdk” directory holds the core system functionality – 3D geometry representations, rendering support, file I/O routines, mathematical operations, and plugin support.
- It includes core modules such as Half, algebra, geometric operations, and a host of utilities (vector, matrix, etc.).

- Modular/Plugin Framework:
- The “modules” directory contains a large number of modules (or plugins) that add features – for example, modules for mesh processing (e.g. “mesh”, “mesh_instance”, “polyhedron”), modifier operations (e.g. “deformation”, “array”, “blobby”), file formats (e.g., “collada_io”, “obj_io”, “stl_io”), external engine integration (e.g., “cuda”, “luxrender”, “renderman”), and even systems for scripting and automated tasks.
- Each module exists as its own subdirectory with a CMakeLists.txt file for independent building and integration into the overall system.

- Build and Configuration Infrastructure:
- CMake is strongly featured through numerous CMakeLists.txt files across directories. The “cmake” directory contains specialized modules for dependency detection, build dashboards, and system configuration.
- Additional directories like “tests”, “docs”, “po” (translations), and “man” (manual pages) support quality assurance, documentation, and internationalization.

- Scripting and Extensions:
- Scripting support is integrated via the “modules/scripting” folder and additional Python bindings in “k3dsdk/python”. This subsystem allows users to extend functionality, automate modeling tasks, and integrate external scripts.

##### Relationships and Data Flow
- The main application (UI layer) communicates with the core engine (K3DSDK) via well-defined APIs. Data flows from user commands (via input events) to transformations in the 3D scene.
- The modular system loads plugins at runtime or links them at build-time. These plugins extend the capabilities of the engine (for operations such as mesh modification, file import/export, rendering, etc.).
- The build system (CMake) orchestrates all these modules and ensures that integration points are satisfied.
- The scripting layer acts as a bridge between the core C++ engine and high-level user customization.

##### Key Architectural Patterns to Emphasize
- Layered Architecture: Show a clear separation between the presentation (UI) layer, the business/logic (core engine), and the extension modules.
- Build System / Dependency Resolution: Illustrate that the CMake based build scripts manage dependencies across various directories and integrate third-party libraries (for example, OpenGL, CGAL, CUDA, etc.)

- “Core Engine (K3DSDK)” (including libraries for 3D geometry, math operations, rendering, etc.)
- “Modules / Plugins” (grouped by functionality: File I/O, Mesh Modifiers, Rendering Engines, Scripting, etc.)
- “Build & Configuration” (indicating CMake and auxiliary build modules)
- “Testing & Documentation” (encompassing ‘tests’, ‘docs’, ‘man’ directories)
- UI components (perhaps rounded rectangles),

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Configuration
    subgraph "Build & Configuration"
        bc("Build & Configuration"):::build
    end

    %% Application Layer
    subgraph "Application Layer"
        app("Executable Entry Points"):::app
        desktop("Desktop Integration"):::app
        web("Web Resources"):::app
    end

    %% UI Components
    subgraph "UI Components"
        ui_ngui("Core UI (NGUI)"):::ui
        ui_qt("Core UI (Qt UI)"):::ui
        mod_ui_ngui("Module UI (NGUI)"):::ui
        mod_ui_qt("Module UI (Qt UI)"):::ui
    end

    %% Core Engine
    core("Core Engine (K3DSDK)"):::core

    %% Modular/Plugin Framework
    subgraph "Modular/Plugin Framework"
        plugins("Plugin Modules"):::plugin
    end

    %% Scripting and Extensions
    subgraph "Scripting and Extensions"
        python("Python Bindings"):::script
        scripting_mod("Scripting Module"):::script
    end

    %% Testing & Documentation
    test("Testing & Documentation"):::test

    %% Relationships
    bc --> app
    bc --> core
    bc --> plugins
    bc --> ui_ngui
    bc --> ui_qt
    bc --> python

    app -->|"calls"| core
    desktop -->|"integrates"| core
    web -->|"provides-data"| core

    ui_ngui -->|"UI-commands"| core
    ui_qt -->|"UI-commands"| core
    mod_ui_ngui -->|"UI-plugins"| core
    mod_ui_qt -->|"UI-plugins"| core

    core -->|"loads-plugins"| plugins

    python -->|"extends"| core
    scripting_mod -->|"script-plugins"| plugins

    core -->|"tested-by"| test
    plugins -->|"verified-by"| test

    %% Click Events
    click app "https://github.com/k-3d/k3d/blob/master/application/k3d_main.cpp"
    click desktop "https://github.com/k-3d/k3d/tree/master/desktop/"
    click web "https://github.com/k-3d/k3d/tree/master/web/"

    click ui_ngui "https://github.com/k-3d/k3d/tree/master/k3dsdk/ngui/"
    click ui_qt "https://github.com/k-3d/k3d/tree/master/k3dsdk/qtui/"
    click mod_ui_ngui "https://github.com/k-3d/k3d/tree/master/modules/ngui/"
    click mod_ui_qt "https://github.com/k-3d/k3d/tree/master/modules/qtui/"

    click core "https://github.com/k-3d/k3d/tree/master/k3dsdk/"

    click plugins "https://github.com/k-3d/k3d/tree/master/modules/"

    click bc "https://github.com/k-3d/k3d/tree/master/cmake/"
    click python "https://github.com/k-3d/k3d/tree/master/k3dsdk/python/"
    click scripting_mod "https://github.com/k-3d/k3d/tree/master/modules/scripting/"

    %% Styles
    classDef app fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef ui fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef plugin fill:#ff9999,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef build fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef script fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef test fill:#e6e6e6,stroke:#333,stroke-width:2px,stroke-dasharray: 2 2;
```
