# commaai/comma2k19 architecture

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

- Interactive diagram: https://gitdiagram.com/commaai/comma2k19
- Repository: https://github.com/commaai/comma2k19

## Overview

##### Project type and purpose
- This is an open-source dataset repository (“comma2k19”) with example code and utilities to read, process, and benchmark multi-sensor driving logs (camera video, raw CAN, IMU, GNSS).
- It provides a reproducible data-processing pipeline and Jupyter notebooks for exploration, plus a Dockerfile and CI config for environment setup and tests.

##### File structure
- Top-level:
- .github/workflows/main.yml – CI pipeline
- Dockerfile – containerized environment
- Example_1/… – one sample dataset chunk containing raw “video.hevc” and compressed “raw_log.bz2”, plus precomputed “processed_log” and “global_pose” subfolders
- assets/ – images for README illustrations
- notebooks/ – Jupyter notebooks and ancillary text files (camera intrinsics, example benchmarks, readers)
- openpilot/ – git submodule providing logreader/framereader tools
- utils/ – Python package with modules for data I/O, coordinate transforms, camera models, benchmarks, and a helper for Microsoft FS quirks
- requirements.txt – Python dependencies
- Patterns:
- Data-driven pipeline: raw data → unzip → numpy arrays → benchmarks/plots
- Modular code: “utils” library used by notebooks and potentially external tools
- Reproducible environment: Docker + CI

##### README for additional insights
- Describes dataset layout and formats (processed_log, global_pose, IMU/CAN/GNSS message schemas)
- Points out integration with OpenPilot tools and Laika GNSS library
- Highlights use cases: GNSS/INS/vision fusion, mapping, benchmarking

a. Main components
- Data Storage
- Raw Data (raw_log.bz2, video.hevc)
- Preprocessed Data (processed_log/, global_pose/)
- Processing Library
- utils package (dataset reader, coordinate transforms, camera models, benchmarks)
- unzip_msft_fs.py for filesystem compatibility
- External Integrations
- OpenPilot submodule (logreader, framereader)
- Laika GNSS library (external process/library)
- Example Workflows
- Jupyter notebooks (raw_readers.ipynb, processed_readers.ipynb, position_benchmark.ipynb)
- Environment & CI
- Docker container (Dockerfile)
- GitHub Actions (main.yml)
b. Relationships & interactions
- Raw Data → unzip_msft_fs.py (if needed) → utils.dataset reader → numpy arrays
- numpy arrays + openpilot.tools → data ingestion in notebooks
- utils.camera & utils.coordinates → calibrate & project poses (refer to camera_intrinsics.txt)
- Laika library invoked within utils or notebooks for GNSS processing
- notebooks import utils and openpilot modules → generate plots/metrics
- Dockerfile bundles Python environment + openpilot submodule → reproducible runs
- CI workflow builds Docker image, runs unit tests on utils, lints notebooks, verifies example notebooks execute without errors
c. Architectural patterns / design principles
- Data pipeline pattern: clear separation between raw data ingestion, preprocessing, analysis
- Modular library design: utils package exposes clean APIs for reading and processing data streams
- Reproducibility: containerization (Docker), CI testing, sample data segment
- Extensibility: open submodule points for additional processing (e.g., swapping Laika for another GNSS library)
d. Key technologies
- Python 2.7 / 3.6, numpy, Jupyter
- OpenPilot tools (capnp-based logreader, framereader)
- Laika GNSS processing library
- Docker, GitHub Actions

##### Final advice
- Be exhaustive: break the system into data layers, code layers, and infrastructure layers
- Component with its role, inputs, and outputs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Storage Layer
    subgraph "Data Storage" 
        direction TB
        RawData["Raw Data\n(.hevc, .bz2)"]:::data
        Preprocessed["Preprocessed Data\n(processed_log/, global_pose/)"]:::data
        Assets["Assets\n(README Images)"]:::data
    end

    %% Processing Library
    subgraph "Processing Library (utils)" 
        direction TB
        UtilsInit["__init__.py"]:::code
        Dataset["dataset.py"]:::code
        Camera["camera.py"]:::code
        Coordinates["coordinates.py"]:::code
        Orientation["orientation.py"]:::code
        Benchmarks["benchmarks.py"]:::code
        UnzipHelper["unzip_msft_fs.py"]:::code
    end

    %% External Integrations
    subgraph "External Integrations" 
        direction TB
        OpenPilot["openpilot/\n(logreader, framereader)"]:::external
        Laika["Laika GNSS Library"]:::external
    end

    %% Notebooks & Workflows
    subgraph "Example Workflows (Notebooks)" 
        direction TB
        RawReaders["raw_readers.ipynb"]:::code
        ProcessedReaders["processed_readers.ipynb"]:::code
        PositionBenchmark["position_benchmark.ipynb"]:::code
        CameraIntrinsics["camera_intrinsics.txt"]:::code
    end

    %% Infrastructure & CI
    subgraph "Infrastructure & CI" 
        direction TB
        DockerfileNode["Dockerfile"]:::infra
        CI["GitHub Actions CI\n(main.yml)"]:::infra
        Requirements["requirements.txt"]:::code
    end

    %% Data Pipeline Arrows
    RawData -->|".bz2 unzip"| UnzipHelper
    UnzipHelper -->|".hevc/.bz2"| Dataset
    Dataset -->|"numpy arrays"| RawReaders
    Dataset -->|"numpy arrays"| ProcessedReaders
    Dataset -->|"numpy arrays"| PositionBenchmark

    %% Utils usage in Notebooks
    Camera -->|"camera intrinsics"| RawReaders
    Coordinates -->|"coordinate transforms"| ProcessedReaders
    Orientation -->|"pose quaternions"| PositionBenchmark
    Benchmarks -->|"generate plots/metrics"| PositionBenchmark

    %% Integrations
    OpenPilot -->|"logreader, framereader"| RawReaders
    OpenPilot -->|"tools access"| ProcessedReaders
    Laika -->|"GNSS processing"| ProcessedReaders
    Laika -->|"GNSS processing"| PositionBenchmark

    %% Infrastructure interactions
    DockerfileNode -->|"env build"| RawReaders
    DockerfileNode -->|"env build"| Dataset
    DockerfileNode -->|"includes openpilot submodule"| OpenPilot
    CI -->|"build & test"| DockerfileNode
    CI -->|"lint & notebook exec"| RawReaders
    CI -->|"unit tests"| UtilsInit
    CI -->|"unit tests"| Dataset

    %% Dependencies manifest
    Requirements -->|"install deps"| DockerfileNode

    %% Click Events
    click CI "https://github.com/commaai/comma2k19/blob/master/.github/workflows/main.yml"
    click DockerfileNode "https://github.com/commaai/comma2k19/tree/master/Dockerfile"
    click RawData "https://github.com/commaai/comma2k19/tree/master/Example_1/"
    click Assets "https://github.com/commaai/comma2k19/tree/master/assets/"
    click RawReaders "https://github.com/commaai/comma2k19/blob/master/notebooks/raw_readers.ipynb"
    click ProcessedReaders "https://github.com/commaai/comma2k19/blob/master/notebooks/processed_readers.ipynb"
    click PositionBenchmark "https://github.com/commaai/comma2k19/blob/master/notebooks/position_benchmark.ipynb"
    click CameraIntrinsics "https://github.com/commaai/comma2k19/blob/master/notebooks/camera_intrinsics.txt"
    click UtilsInit "https://github.com/commaai/comma2k19/blob/master/utils/__init__.py"
    click Benchmarks "https://github.com/commaai/comma2k19/blob/master/utils/benchmarks.py"
    click Camera "https://github.com/commaai/comma2k19/blob/master/utils/camera.py"
    click Coordinates "https://github.com/commaai/comma2k19/blob/master/utils/coordinates.py"
    click Dataset "https://github.com/commaai/comma2k19/blob/master/utils/dataset.py"
    click Orientation "https://github.com/commaai/comma2k19/blob/master/utils/orientation.py"
    click UnzipHelper "https://github.com/commaai/comma2k19/blob/master/utils/unzip_msft_fs.py"
    click OpenPilot "https://github.com/commaai/comma2k19/tree/master/openpilot/"
    click Requirements "https://github.com/commaai/comma2k19/blob/master/requirements.txt"

    %% Styles
    classDef code fill:#D3ECFF,stroke:#333,stroke-width:1px
    classDef data fill:#DFF2BF,stroke:#333,stroke-width:1px
    classDef external fill:#FFE6B3,stroke:#333,stroke-width:1px
    classDef infra fill:#EDEDED,stroke:#333,stroke-width:1px
```
