# cartographer3d/cartographer3d-plugin architecture

> Architecture diagram of the GitHub repository cartographer3d/cartographer3d-plugin, 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/cartographer3d/cartographer3d-plugin
- Repository: https://github.com/cartographer3d/cartographer3d-plugin

## Overview

##### Project type and purpose
- Cartographer3D is a Python-based tool for 3D-printer probing, mesh generation, and calibration.
- It provides a CLI/library (“cartographer” entrypoint) that drives a printer via adapter layers (Klipper or Kalico), collects probe data, runs filters/integrators, and produces bed meshes or Z-offset calibrations.

##### File structure
- Top-level:
- scripts/ – helper scripts (e.g. install.sh, path plotting)
- src/cartographer/ – main package
- tests/ – unit and BDD tests
- pyproject.toml, hatch_build.py – build configuration
- src/cartographer/ layers:
- adapters/ – hardware-specific communication (klipper, kalico)
- config/ – command-line and file parser
- core.py – central orchestration
- interfaces/ – abstract interfaces (printer, multiprocessing)
- lib/ – utility algorithms (filters, NN, stats, logging)
- macros/ – high-level workflows (bed_mesh, probe, touch, calibrate)
- probe/ – data models and probe logic
- runtime/ – dynamic loader, environment setup, integrator runtime
- stream.py, toolhead.py – shared stream and toolhead abstractions

##### README for additional insights
- It’s in beta (Cartographer3D WIP)
- Documentation lives externally

– “Runtime Loader & Environment”
– “Macro Engine”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI/Launcher"
        direction TB
        Install["install.sh"]:::core
        PlotPath["plot_path.py"]:::core
        EntryPoint["pyproject.toml"]:::core
    end

    %% Config Layer
    Config["Config Parser"]:::core

    %% Core Layer
    Core["Core Orchestrator"]:::core

    %% Runtime Layer
    subgraph "Runtime Loader & Environment"
        direction TB
        Loader["loader.py"]:::core
        Env["environment.py"]:::core
        AdaptersBinding["adapters.py"]:::core
    end

    %% Macro Layer
    subgraph "Macro Engine"
        direction TB
        Macros["macros/"]:::macros
    end

    %% Integrator Layer
    subgraph "Integrator & Data Flow"
        direction TB
        KI["klipper/integrator.py"]:::adapter
        CAI["kalico/integrator.py"]:::adapter
        RInt["runtime/integrator.py"]:::adapter
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        direction TB
        KlipperAdapter["adapters/klipper/"]:::adapter
        KalicoAdapter["adapters/kalico/"]:::adapter
        Utils["utils.py"]:::adapter
    end

    %% Libraries & Interfaces
    Libs["lib/"]:::libs
    Interfaces["interfaces/"]:::interfaces
    subgraph "Shared Abstractions"
        direction TB
        Stream["stream.py"]:::interfaces
        Toolhead["toolhead.py"]:::interfaces
    end

    %% External Systems
    MCU["Printer Firmware / MCU"]:::external

    %% Output
    Output["Output (mesh file, logs)"]:::external

    %% Connections
    Install -->|entrypoint| Config
    PlotPath -->|entrypoint| Config
    EntryPoint -->|defines CLI| Config
    Config -->|"parses config"| Core
    Core -->|"loads runtime"| Loader
    Core -->|"sets env"| Env
    Core -->|"uses adapters binding"| AdaptersBinding
    Core -->|"invokes macros"| Macros
    Macros -->|"calls integrator"| RInt
    RInt -->|"routes data"| KlipperAdapter
    RInt -->|"routes data"| KalicoAdapter
    KlipperAdapter -->|controls| MCU
    KalicoAdapter -->|controls| MCU
    Macros -->|"uses libs"| Libs
    RInt -->|"uses libs"| Libs
    Core -->|"uses interfaces"| Interfaces
    KlipperAdapter -->|"uses interfaces"| Interfaces
    KalicoAdapter -->|"uses interfaces"| Interfaces
    Core -->|"uses abstraction"| Stream
    KlipperAdapter -->|"streams gcode"| Stream
    Core -->|"uses abstraction"| Toolhead
    Output -->|produced by| Core

    %% Click Events
    click Install "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/scripts/install.sh"
    click PlotPath "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/scripts/plot_path.py"
    click EntryPoint "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/pyproject.toml"
    click Config "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/src/cartographer/config/parser.py"
    click Core "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/src/cartographer/core.py"
    click Loader "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/src/cartographer/runtime/loader.py"
    click Env "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/src/cartographer/runtime/environment.py"
    click AdaptersBinding "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/src/cartographer/runtime/adapters.py"
    click KlipperAdapter "https://github.com/cartographer3d/cartographer3d-plugin/tree/main/src/cartographer/adapters/klipper/"
    click KalicoAdapter "https://github.com/cartographer3d/cartographer3d-plugin/tree/main/src/cartographer/adapters/kalico/"
    click KI "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/src/cartographer/adapters/klipper/integrator.py"
    click CAI "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/src/cartographer/adapters/kalico/integrator.py"
    click RInt "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/src/cartographer/runtime/integrator.py"
    click Macros "https://github.com/cartographer3d/cartographer3d-plugin/tree/main/src/cartographer/macros/"
    click Libs "https://github.com/cartographer3d/cartographer3d-plugin/tree/main/src/cartographer/lib/"
    click Interfaces "https://github.com/cartographer3d/cartographer3d-plugin/tree/main/src/cartographer/interfaces/"
    click Stream "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/src/cartographer/stream.py"
    click Toolhead "https://github.com/cartographer3d/cartographer3d-plugin/blob/main/src/cartographer/toolhead.py"

    %% Styles
    classDef core fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef macros fill:#E8F5E9,stroke:#43A047,color:#000
    classDef adapter fill:#FFF3E0,stroke:#FB8C00,color:#000
    classDef external fill:#EEEEEE,stroke:#BDBDBD,color:#000
    classDef libs fill:#F3E5F5,stroke:#8E24AA,color:#000
    classDef interfaces fill:#CFD8DC,stroke:#455A64,color:#000
```
