# mikedh/trimesh architecture

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

- Interactive diagram: https://gitdiagram.com/mikedh/trimesh
- Repository: https://github.com/mikedh/trimesh

## Overview

##### Project Type and Purpose
- Trimesh is a pure-Python 3.7+ library for loading, manipulating, analyzing, and exporting triangular mesh data.
- Soft dependencies (scipy, networkx, pyglet, embree, etc.) add optional features.

##### Top-Level Components
a. Core Geometry (trimesh/base.py, boolean.py, convex.py, curvature.py, etc.)
b. Exchange (trimesh/exchange) – loaders & exporters for STL, OBJ, PLY, GLTF/GLB, DXF, SVG, 3MF, XAML, 3DXML, URDF, etc.
c. Path Module (trimesh/path) – 2D/3D vector path creation, manipulation, DXF/SVG I/O, packing, rasterization.
e. Voxel & Volume (trimesh/voxel) – voxelization, morphology, encoding, transforms.
f. Interfaces (trimesh/interfaces) – external tools: Blender, Gmsh, generic command-line.
g. Viewer (trimesh/viewer) – pyglet window, Jupyter inline three.js widget.
h. Resources (trimesh/resources) – JSON schemas, JavaScript viewer, templates, unit conversion data.
i. Utilities & Caching (trimesh/util.py, caching.py, constants, resolvers, etc.)

##### Relationships & Data Flow
- Core operations (boolean, convex hull, slicing, mass properties) all operate on Trimesh objects and return new Trimesh or geometric results.
- Trimesh & Scene objects feed into:
– Exporters in Exchange → output files/formats
– Viewer for display (pyglet, three.js)
– Voxel module (for voxelization pipelines)
– Path module (2D cross sections & paths from mesh slices)

##### Architectural Patterns & Principles
- Layered architecture:
– Bottom: Utilities & caching
– Middle: Core geometry algorithms
– Top: I/O (Exchange), Voxel, Path, Scene, Visual, Viewer
- API-first design: Trimesh and Scene classes are the central data models.
- Plugin-style I/O: each file format lives in its own module under exchange.
- Resource bundling: JSON schemas and viewer assets are packaged under resources.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Utilities & Caching Layer
    subgraph "Utilities & Caching"
        direction TB
        Utilities["Utilities & Caching"]:::util
        Utilities -->|hard dependency| Core
    end

    %% Core Geometry Layer
    subgraph "Core Geometry"
        direction TB
        Core["Core: Trimesh Object & Algorithms"]:::core
    end

    %% I/O and Feature Modules
    subgraph "I/O & Feature Modules"
        direction TB
        Exchange["Exchange (Loaders & Exporters)"]:::io
        SceneVisual["Scene & Visual"]:::io
        Path["Path Module"]:::io
        Voxel["Voxel & Volume"]:::io
        Interfaces["Interfaces (External Tools)"]:::optional
        Viewer["Viewer (pyglet & Jupyter)"]:::io
        Resources["Resources (Schemas & Assets)"]:::resources
    end

    %% CLI Entry Point
    CLI["CLI Entry Point (__main__.py)"]:::io

    %% External Dependencies
    subgraph "Optional External Dependencies"
        direction TB
        SciPy["SciPy"]:::external
        NetworkX["NetworkX"]:::external
        Pyglet["pyglet"]:::external
        Embree["Embree"]:::external
        BlenderExt["Blender"]:::external
        GmshExt["Gmsh SDK"]:::external
        LXML["lxml"]:::external
    end

    %% Relationships & Data Flow
    Exchange -->|"load() / import"| Core
    Core -->|"export() / write()"| Exchange
    Core -->|"slice()/path()"| Path
    Core -->|"voxelize()"| Voxel
    Core -->|"scene graph"| SceneVisual
    Core -->|"render() / visualize"| Viewer
    Core -->|"wrap external"| Interfaces
    Core -->|"use assets"| Resources
    CLI -->|"entry point"| Core

    %% Utilities bidirectional
    Utilities --- Core

    %% Optional integrations dashed
    SciPy -.->|optional| Core
    NetworkX -.->|optional| Core
    Pyglet -.->|optional| Viewer
    Embree -.->|optional| Interfaces
    BlenderExt -.->|optional| Interfaces
    GmshExt -.->|optional| Interfaces
    LXML -.->|optional| Exchange

    %% Click Events
    click Utilities "https://github.com/mikedh/trimesh/blob/main/trimesh/util.py"
    click Exchange "https://github.com/mikedh/trimesh/tree/main/trimesh/exchange/"
    click Path "https://github.com/mikedh/trimesh/tree/main/trimesh/path/"
    click SceneVisual "https://github.com/mikedh/trimesh/tree/main/trimesh/scene/"
    click Voxel "https://github.com/mikedh/trimesh/tree/main/trimesh/voxel/"
    click Interfaces "https://github.com/mikedh/trimesh/tree/main/trimesh/interfaces/"
    click Viewer "https://github.com/mikedh/trimesh/tree/main/trimesh/viewer/"
    click Resources "https://github.com/mikedh/trimesh/tree/main/trimesh/resources/"
    click CLI "https://github.com/mikedh/trimesh/blob/main/trimesh/__main__.py"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#2a6496,stroke-width:2px,color:#0b2e6f
    classDef io fill:#d9ead3,stroke:#6aa84f,stroke-width:2px,color:#274e13
    classDef util fill:#f4cccc,stroke:#a61c00,stroke-width:2px,color:#761b18
    classDef optional stroke-dasharray: 5 5,fill:#fce5cd,stroke:#b45f06,stroke-width:2px,color:#783f04
    classDef resources fill:#eeeeee,stroke:#888888,stroke-width:2px,color:#333333
    classDef external fill:#f9cb9c,stroke:#e69138,stroke-width:2px,color:#874e0f
```
