# ouster-lidar/ouster-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/ouster-lidar/ouster-sdk
- Repository: https://github.com/ouster-lidar/ouster-sdk

## Overview

##### Project type and purpose
- This is an open‑source SDK/toolkit (C++ and Python) for Ouster LiDAR sensors. It provides:
- A C++ client library (ouster_client) to connect, configure, and read data from sensors over the network.
- A C++ PCAP module (ouster_pcap) to record/replay sensor UDP packets.
- A C++ OSF module (ouster_osf) to store and retrieve LiDAR data in the Ouster‑specific OSF file format.
- A C++ visualization library (ouster_viz) for rendering point clouds.
- A Python SDK (python/) that wraps the C++ libraries, provides a CLI, high‑level APIs, and example scripts.
- Build system glue (CMake, Docker, CI scripts), documentation (docs/), and tests.

##### File structure
- Top‑level CMakeLists.txt and related cmake/ files define a multi‑target build.
- Directories:
- ouster_client/ (C++ core networking and data structures)
- ouster_pcap/ (C++ packet capture and replay)
- ouster_osf/ (C++ OSF file encoder/decoder plus flatbuffers definitions)
- ouster_viz/ (C++ OpenGL-based point-cloud rendering)
- python/ (bindings via pybind11, CLI plugin architecture, Python SDK subpackages)
- examples/ (C++ example clients demonstrating linking and usage)
- docs/ (Sphinx-based C++ and Python API references, tutorials)
- thirdparty/ (jsoncons, spdlog, glad, etc.) for logging, JSON, GL support.
- .github/, Jenkinsfile, Dockerfiles, vcpkg.json for CI/CD, linting, packaging.

##### README for additional insights
- Confirms the above modules.
- Notes that ROS driver is external.
- Emphasizes cross‑platform support, C++/Python interoperability, and modular subcomponents.

a. Main components:
- External LiDAR Sensor Hardware
- Network Transport (UDP)
- C++ Core Libraries:
– ouster_client (sensor communication & parsing)
– ouster_pcap (pcap I/O)
– ouster_osf (file I/O via OSF FlatBuffers)
– ouster_viz (point-cloud renderer)
- Python Layer (pybind11 bindings + CLI framework + high‑level SDK)
- Examples & CLI (Python scripts & C++ binaries)
- Third‑party components (jsoncons, spdlog, GLFW/glad)
- Build & CI (CMake, Docker, GitHub Actions, Jenkins)
b. Relationships & data flows:
1. Sensor → UDP → ouster_client → LidarScan objects
2. ouster_client outputs feed into:
– live visualization (ouster_viz)
– offline capture (ouster_pcap → .pcap files)
– OSF writer (ouster_osf → .osf files)
3. Python layer wraps all C++ modules and exposes:
– CLI commands (plugins under python/src/ouster/cli/plugins/)
– Python SDK APIs (python/src/ouster/sdk/…)
4. Examples & tests import/use either C++ binaries or Python APIs.
c. Architectural patterns & principles:
– Modular, layer‑based design: transport, parsing, storage, visualization.
– Plugin architecture (Python CLI) for extensibility.
– CMake multi‑project build, pybind11 for language bindings.
– Use of FlatBuffers for binary file schema (OSF), PCAP for raw packet storage.
d. Key technologies:
– C++17, pybind11, FlatBuffers, JSONCons, spdlog, GLFW/OpenGL for rendering.
– CMake, Docker, GitHub Actions for build/test.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        Sensor["LiDAR Sensor Hardware"]:::external
        FileSystem["File System"]:::external
        Display["Display (OpenGL)"]:::external
    end

    subgraph "C++ Core Libraries"
        Client["ouster_client (sensor communication & parsing)"]:::cpp
        Pcap["ouster_pcap (PCAP I/O)"]:::cpp
        Osf["ouster_osf (OSF file I/O)"]:::cpp
        Viz["ouster_viz (point-cloud visualization)"]:::cpp
    end

    subgraph "Python Layer"
        PyBindings["pybind11 bindings"]:::py
        CLI["CLI Framework & Plugins"]:::py
        SDK["Python SDK APIs"]:::py
    end

    subgraph "Examples & Tests"
        Examples["C++ & Python Examples"]:::examples
    end

    subgraph "Build & CI/CD"
        CMake["CMakeLists.txt"]:::build
        CMakeDir["cmake/"]:::build
        CI[".github/, Jenkinsfile, Dockerfiles"]:::build
    end

    subgraph "Documentation"
        Docs["docs/"]:::docs
    end

    Thirdparty["thirdparty/ (jsoncons, spdlog, glad, etc.)"]:::thirdparty

    %% Data Flows
    Sensor -->|UDP packets| Client
    Client -->|"LidarScan objects"| Viz
    Client -->|"LidarScan objects"| Pcap
    Client -->|"LidarScan objects"| Osf

    Pcap -->|".pcap files"| FileSystem
    Osf -->|".osf files"| FileSystem
    Viz -->|"Rendered frames"| Display

    %% Python Layer Bindings
    Client -->|Pybind11 call| PyBindings
    Pcap -->|Pybind11 call| PyBindings
    Osf -->|Pybind11 call| PyBindings
    Viz -->|Pybind11 call| PyBindings

    PyBindings --> CLI
    PyBindings --> SDK

    CLI -->|CLI commands| User["End User"]:::external
    SDK -->|SDK calls| User

    Examples --> Client
    Examples --> SDK

    %% Tooling
    Client --> Thirdparty
    Pcap --> Thirdparty
    Osf --> Thirdparty
    Viz --> Thirdparty
    PyBindings --> Thirdparty

    CMake -->|build config| Client
    CMake -->|build config| Pcap
    CMake -->|build config| Osf
    CMake -->|build config| Viz
    CMake -->|build config| PyBindings
    CI -->|CI/CD pipelines| CMake

    %% Click Events
    click Client "https://github.com/ouster-lidar/ouster-sdk/tree/master/ouster_client/"
    click Pcap "https://github.com/ouster-lidar/ouster-sdk/tree/master/ouster_pcap/"
    click Osf "https://github.com/ouster-lidar/ouster-sdk/tree/master/ouster_osf/"
    click Viz "https://github.com/ouster-lidar/ouster-sdk/tree/master/ouster_viz/"
    click _client "https://github.com/ouster-lidar/ouster-sdk/blob/master/python/src/cpp/_client.cpp"
    click _pcap "https://github.com/ouster-lidar/ouster-sdk/blob/master/python/src/cpp/_pcap.cpp"
    click _osf "https://github.com/ouster-lidar/ouster-sdk/blob/master/python/src/cpp/_osf.cpp"
    click _viz "https://github.com/ouster-lidar/ouster-sdk/blob/master/python/src/cpp/_viz.cpp"
    click maincpp "https://github.com/ouster-lidar/ouster-sdk/blob/master/python/src/cpp/main.cpp"
    click CLI "https://github.com/ouster-lidar/ouster-sdk/tree/master/python/src/ouster/cli/"
    click SDK "https://github.com/ouster-lidar/ouster-sdk/tree/master/python/src/ouster/sdk/"
    click Examples "https://github.com/ouster-lidar/ouster-sdk/tree/master/examples/"
    click Docs "https://github.com/ouster-lidar/ouster-sdk/tree/master/docs/"
    click CMake "https://github.com/ouster-lidar/ouster-sdk/blob/master/CMakeLists.txt"
    click CMakeDir "https://github.com/ouster-lidar/ouster-sdk/tree/master/cmake/"
    click CI "https://github.com/ouster-lidar/ouster-sdk/tree/master/.github/"
    click Jenkinsfile "https://github.com/ouster-lidar/ouster-sdk/tree/master/Jenkinsfile"
    click DockerfileRoot "https://github.com/ouster-lidar/ouster-sdk/tree/master/Dockerfile"
    click DockerfilePy "https://github.com/ouster-lidar/ouster-sdk/tree/master/python/Dockerfile"
    click Thirdparty "https://github.com/ouster-lidar/ouster-sdk/tree/master/thirdparty/"

    %% Styles
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef cpp fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef py fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef examples fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef build fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef docs fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef thirdparty stroke:#6c757d,stroke-dasharray:5 5,stroke-width:1px,fill:none
```
