# open3dv/xema architecture

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

- Interactive diagram: https://gitdiagram.com/open3dv/xema
- Repository: https://github.com/open3dv/xema

## Overview

##### Project Type & Overview
- This is a full-featured hardware-software integrated system for industrial 3D imaging.
- It encompasses low-level firmware (including MCU code), camera calibration, image capturing & processing, and high-level user interfaces (both CLI and GUI) together with an SDK.
- The architecture supports industrial use cases such as bin picking, assembly, 3D inspection, and integration with deep learning processes for advanced computer vision tasks.

##### Main Components to Highlight
a. Hardware & Embedded Systems:
– Camera sensor and optics
– Industrial imaging hardware with precision calibration (as depicted in calibration and documentation folders)
– Microcontroller unit (MCU) code and associated startup routines (mcu/ folder)
– External interface hardware (e.g., power controller via firmware/power_controller.cpp)

b. Low-Level Firmware Layer:
– Firmware modules (in the firmware/ folder) that encompass image capture, camera interfacing (drivers for different camera types such as Basler, DH, Galaxy), encoding and GPU computing sections (see .cu and .cuh files for CUDA acceleration)
– Communication and network functions such as TCP socket programming (socket_tcp.cpp in firmware and sdk)

c. Calibration & Image Processing:
– Calibration algorithms (calibration/ folder) which are key for accurate 3D reconstruction
– Reconstruction, triangulation, and encoding functions (src/ and test/ directories) forming the computational backbone for 3D point-cloud generation

d. Software Development Kit (SDK) & Application Layers:
– SDK (sdk/ folder) providing API interfaces for external integration and control
– Command-line tool (cmd/ folder), examples (cpp_example, example), and test projects (functest/ and test/) that help validate functionality
– Graphical user interface (gui/ folder): Provided as a Qt-based or Windows-based GUI for calibration, camera capture and firmware updates

e. Auxiliary Tools & Documentation:
– Python and shell scripts in tools/ for generating gray codes, pattern images, and depth map conversions
– Detailed hardware design files and documentation (docs/ folder and README images) for structural chassis and PCB design

##### Relationships & Interactions
- The hardware layer interfaces with the MCU firmware (mcu/), which in turn manages low-level sensor control.
- The firmware layer processes real-time image capture and leverages CUDA for GPU-accelerated encoding, filtering, and reconstruction.
- Calibration algorithms and image processing modules (calibration/, src/, test/) are used to correct and reconstruct the 3D point cloud.
- The SDK (sdk/) exposes APIs that allow higher-level applications (CLI in cmd/, examples in cpp_example/ and example/, GUI in gui/) to control the camera, trigger image acquisition, and process images.
- Tools and scripts (tools/) assist in creating necessary calibration patterns and processing depth maps for analysis.
- A testing suite (functest/ and test/) ensures the integration between these modules is stable.

##### Architectural Patterns & Design Principles
– Layered architecture: Dividing hardware control, real-time processing, calibration/algorithms, and application layers (CLI/GUI/SDK).
– Modular design: Each folder represents a module (calibration, firmware, gui, sdk, etc.) with clear separation of concerns.
– Integration of GPU computing: Using CUDA (.cu files) for efficient image encoding and reconstruction.
– Use of common build systems: The presence of CMakeLists.txt and Visual Studio project files indicates standardized build and deployment pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware & Embedded Systems
    subgraph "Hardware & Embedded Systems"
        A1["Camera Sensor & Optics"]:::hardware
        A2["MCU Firmware (mcu/)"]:::hardware
        A3["Power Controller Source (power_controller.cpp)"]:::hardware
        A4["Power Controller Header (power_controller.h)"]:::hardware
        A5["Hardware Design Docs (docs/)"]:::hardware
    end

    %% Low-Level Firmware Layer
    subgraph "Low-Level Firmware Layer"
        B1["Firmware Modules (firmware/)"]:::firmware
    end

    %% Calibration & Image Processing
    subgraph "Calibration & Image Processing"
        C1["Calibration Algorithms (calibration/)"]:::processing
        C2["3D Reconstruction Engine (src/)"]:::processing
        C3["Image Processing Tests (test/)"]:::processing
    end

    %% SDK & Application Layers
    subgraph "SDK & Application Layers"
        D1["SDK API (sdk/)"]:::sdk
        D2["CLI Tools (cmd/)"]:::sdk
        D3["C++ Example Projects (cpp_example/)"]:::sdk
        D4["Demo Projects (example/)"]:::sdk
        D5["Functionality Tests (functest/)"]:::sdk
        D6["Additional Tests (test/)"]:::sdk
    end

    %% Graphical User Interface (GUI)
    subgraph "Graphical User Interface"
        E1["GUI Components (gui/)"]:::gui
    end

    %% Auxiliary Tools & Scripts
    subgraph "Auxiliary Tools & Scripts"
        F1["Tools & Scripts (tools/)"]:::tools
    end

    %% Connections between Components
    A1 -->|"provides raw data"| A2
    A2 -->|"controls sensor"| B1
    A2 -->|"manages power"| A3
    A2 --> A4
    B1 -->|"captured images"| C1
    B1 --> C2
    F1 -->|"assists calibration"| C1
    C1 -->|"refines data"| C2
    C2 -->|"validated by"| C3
    C1 -->|"feeds processed data"| D1
    C2 --> D1
    C3 --> D1
    D1 -->|"triggers commands"| D2
    D1 <-->|"status update"| E1
    D1 -->|"demonstrated by"| D3
    D1 --> D4
    D5 -->|"verifies integration"| D1
    D6 --> D1

    %% Styles
    classDef hardware fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef firmware fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef processing fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef sdk fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef gui fill:#e2ccff,stroke:#6f42c1,stroke-width:2px;
    classDef tools fill:#d1d1d1,stroke:#333333,stroke-width:2px;

    %% Click Events
    click A2 "https://github.com/open3dv/xema/tree/master/mcu/"
    click A3 "https://github.com/open3dv/xema/blob/master/firmware/power_controller.cpp"
    click A4 "https://github.com/open3dv/xema/blob/master/firmware/power_controller.h"
    click A5 "https://github.com/open3dv/xema/tree/master/docs/"
    click B1 "https://github.com/open3dv/xema/tree/master/firmware/"
    click C1 "https://github.com/open3dv/xema/tree/master/calibration/"
    click C2 "https://github.com/open3dv/xema/tree/master/src/"
    click C3 "https://github.com/open3dv/xema/tree/master/test/"
    click D1 "https://github.com/open3dv/xema/tree/master/sdk/"
    click D2 "https://github.com/open3dv/xema/tree/master/cmd/"
    click D3 "https://github.com/open3dv/xema/tree/master/cpp_example/"
    click D4 "https://github.com/open3dv/xema/tree/master/example/"
    click D5 "https://github.com/open3dv/xema/tree/master/functest/"
    click D6 "https://github.com/open3dv/xema/tree/master/test/"
    click E1 "https://github.com/open3dv/xema/tree/master/gui/"
    click F1 "https://github.com/open3dv/xema/tree/master/tools/"
```
