# assimp/assimp architecture

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

- Interactive diagram: https://gitdiagram.com/assimp/assimp
- Repository: https://github.com/assimp/assimp

## Overview

##### Project Type and Purpose
- Assimp is an open-source C++ library (not a service) whose purpose is to import and export 3D file formats into a common in-memory scene representation.
- It also provides post-processing tools (normals/tangents generation, optimization passes, etc.), a C-API wrapper, language bindings (Python, Java, .NET, Rust, etc.), command-line tools, viewer tools, and sample applications.

##### High-Level File-Structure Analysis
- Top-level directories:
- code/       → C++ implementation modules
- /    → public C and C++ headers (API boundary)
- contrib/    → third-party libraries (zlib, RapidJSON, Draco, etc.)
- scripts/    → code generators for some formats
- port/       → language ports and JNI wrappers
- tools/      → command-line tools (assimp_cmd) and viewer (assimp_view)
- samples/    → sample apps demonstrating usage
- test/       → unit tests, regression tests, fuzzers
- packaging/  → installer scripts, packaging targets

##### Core Components (from README “Repository structure”)
- code/Common             – core import/export infrastructure, scene graph data structures
- code/AssetLib/<Format>  – format-specific importers/exporters (FBX, Collada, OBJ, etc.)
- code/PostProcessing     – mesh and material post-processing pipeline stages
- code/Geometry           – geometry-related utilities
- code/Material           – material system
- code/Pbrt               – PBR exporter module
- code/CApi               – C-binding glue for the public C API
- /assimp          – public API headers for C and C++ users

- Public APIs
– C++ API (headers in include/assimp)
– C API (code/CApi)
– Language bindings (port/…)
- Core Engine
– Common Core (code/Common)
– Scene Data Model (in Memory)
- Format Modules (code/AssetLib/*)
– Importer Plugins (OBJ, FBX, glTF, …)
– Exporter Plugins (OBJ, STL, 3MF, PBRt, …)
- Post-Processing Pipeline
– Steps: Triangulate, Generate Normals, Optimize, Validate, etc.
- Utilities & Tools
– Command-Line Tool (tools/assimp_cmd)
– Viewer (tools/assimp_view)
– Scripts (scripts/)
- External Dependencies
– Third-party libs (contrib/)
– Build system (CMake)
– Test frameworks (GoogleTest, libFuzzer)

1. User Application → links against Public API → calls Import()
2. Public API → dispatches into C++ Core → Common Core
3. Common Core → loads appropriate Format Module → parses file on disk (IOSystem)
4. Format Module → constructs in-memory Scene Graph
5. Scene Graph → fed into Post-Processing Pipeline → optimized Scene Graph
6. Optionally → Format Module (exporter) → writes out new file format
7. Public API → returns Scene Graph to User Application
8. Tools & Samples → use Public API to import/export/view/test models
9. Language Ports → wrap Public API for other languages

c. Architectural Patterns & Principles
- Plugin-style architecture: each format is a module under AssetLib, registered at runtime via ImporterRegistry.
- Pipeline pattern: post-processing steps are chained, configurable by flags.
- Adapter pattern: IOSystem abstracts file I/O, allowing custom streams.
- Separation of concerns: parsing, scene management, post-processing, and API exposure are distinct layers.

d. Key Technologies & Frameworks
- CMake build system (CMakeLists.txt, presets)
- GoogleTest & GoogleMock for unit testing
- Clang-Format, EditorConfig for code formatting
- libFuzzer for fuzz testing (fuzz/…)
- Third-party libs for compression, XML/JSON parsing, etc.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Public API Layer
    subgraph "Public API" 
        direction TB
        PublicCPPAPI["C++ API"]:::publicAPI
        CApi["C API Wrapper"]:::publicAPI
        Ports["Language Bindings"]:::publicAPI
    end

    %% Core Engine Layer
    subgraph "Core Engine"
        direction TB
        CommonCore["Common Core"]:::core
        SceneGraph["Scene Data Model"]:::core
        ImporterRegistry["Importer Registry"]:::core
        IOSystem["IOSystem"]:::core
    end

    %% Format Modules Layer
    subgraph "Format Modules"
        direction TB
        ObjImporter["OBJ Importer"]:::modules
        FBXImporter["FBX Importer"]:::modules
        glTFImporter["glTF Importer"]:::modules
        Exporters["Exporter Plugins"]:::modules
    end

    %% Post-Processing Layer
    subgraph "Post-Processing Pipeline"
        direction TB
        PostProcessing["Post-Processing Steps"]:::post
        GeometryUtils["Geometry Utilities"]:::post
        MaterialSys["Material System"]:::post
    end

    %% Utilities & Tools Layer
    subgraph "Utilities & Tools"
        direction TB
        CmdTool["Command-Line Tool"]:::tools
        Viewer["Viewer Tool"]:::tools
        Scripts["Script Generators"]:::tools
    end

    %% External Dependencies
    subgraph "External Dependencies" 
        direction TB
        Contrib["Third-Party Libraries"]:::external
        BuildSystem["Build System (CMake)"]:::external
        Packaging["Packaging (Inno Setup)"]:::external
        Tests["Unit Tests & Fuzzers"]:::external
        Documentation["Documentation"]:::external
        Samples["Sample Applications"]:::external
    end

    %% Data Flow Arrows
    UserApp["User Application"]:::external
    UserApp -->|"links against"| PublicCPPAPI
    UserApp -->|"links against"| CApi
    UserApp -->|"uses"| Ports

    PublicCPPAPI -->|"calls Import()"| CommonCore
    CApi -->|"dispatches"| CommonCore

    CommonCore -->|"uses"| ImporterRegistry
    CommonCore -->|"uses"| IOSystem

    ImporterRegistry -->|"loads"| ObjImporter
    ImporterRegistry -->|"loads"| FBXImporter
    ImporterRegistry -->|"loads"| glTFImporter
    ObjImporter -->|"parses file"| SceneGraph
    FBXImporter -->|"parses file"| SceneGraph
    glTFImporter -->|"parses file"| SceneGraph

    SceneGraph -->|"feeds into"| PostProcessing
    PostProcessing -->|"optimizes"| SceneGraph

    Exporters -->|"writes"| Filesystems["File System"]:::external
    PostProcessing -->|"optional export"| Exporters

    CmdTool -->|"uses API"| PublicCPPAPI
    Viewer -->|"uses API"| PublicCPPAPI
    Scripts -->|"generate code for"| ObjImporter

    Contrib -->|"linked by"| ObjImporter
    Contrib -->|"linked by"| FBXImporter
    Contrib -->|"linked by"| glTFImporter

    BuildSystem -->|"builds"| CommonCore
    BuildSystem -->|"builds"| ObjImporter
    BuildSystem -->|"builds"| FBXImporter
    BuildSystem -->|"builds"| PostProcessing
    Tests -->|"tests"| CommonCore
    Tests -->|"fuzzes"| SceneGraph
    Documentation -->|"covers"| API["API Documentation"]:::external

    Samples -->|"demonstrate"| CmdTool
    Samples -->|"demonstrate"| Viewer

    %% Click Events
    click PublicCPPAPI "https://github.com/assimp/assimp/tree/master/include/assimp"
    click CApi "https://github.com/assimp/assimp/tree/master/code/CApi"
    click Ports "https://github.com/assimp/assimp/tree/master/port/"
    click CommonCore "https://github.com/assimp/assimp/tree/master/code/Common"
    click SceneGraph "https://github.com/assimp/assimp/blob/master/code/Common/scene.cpp"
    click ImporterRegistry "https://github.com/assimp/assimp/blob/master/code/Common/ImporterRegistry.cpp"
    click IOSystem "https://github.com/assimp/assimp/blob/master/code/Common/IOSystem.cpp"
    click ObjImporter "https://github.com/assimp/assimp/tree/master/code/AssetLib/Obj"
    click FBXImporter "https://github.com/assimp/assimp/tree/master/code/AssetLib/FBX"
    click glTFImporter "https://github.com/assimp/assimp/tree/master/code/AssetLib/glTF"
    click Exporters "https://github.com/assimp/assimp/tree/master/code/AssetLib/"
    click PostProcessing "https://github.com/assimp/assimp/tree/master/code/PostProcessing"
    click GeometryUtils "https://github.com/assimp/assimp/tree/master/code/Geometry"
    click MaterialSys "https://github.com/assimp/assimp/tree/master/code/Material"
    click CmdTool "https://github.com/assimp/assimp/tree/master/tools/assimp_cmd"
    click Viewer "https://github.com/assimp/assimp/tree/master/tools/assimp_view"
    click Scripts "https://github.com/assimp/assimp/tree/master/scripts/"
    click Contrib "https://github.com/assimp/assimp/tree/master/contrib/"
    click BuildSystem "https://github.com/assimp/assimp/blob/master/CMakeLists.txt"
    click Packaging "https://github.com/assimp/assimp/tree/master/packaging/windows-innosetup"
    click Tests "https://github.com/assimp/assimp/tree/master/test/"
    click Documentation "https://github.com/assimp/assimp/tree/master/doc/"
    click Samples "https://github.com/assimp/assimp/tree/master/samples/"

    %% Styles
    classDef publicAPI fill:#bbdefb,stroke:#2196f3,stroke-width:1px
    classDef core fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef modules fill:#fff9c4,stroke:#fbc02d,stroke-width:1px
    classDef post fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef tools fill:#eceff1,stroke:#90a4ae,stroke-width:1px
    classDef external fill:#ffffff,stroke-dasharray: 5 5,stroke:#757575,stroke-width:1px
```
