# talmolab/sleap-io architecture

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

- Interactive diagram: https://gitdiagram.com/talmolab/sleap-io
- Repository: https://github.com/talmolab/sleap-io

## Overview

##### Project type and purpose
- sleap-io is a standalone Python library (no GUI) providing utilities to load, convert, and save animal pose-tracking data in multiple file formats. It complements the core SLEAP package by focusing solely on I/O and data manipulation, with minimal dependencies.

##### File structure
- Top-level directories:
- sleap_io/
– model/ : Core in-memory data structures (Labels, LabeledFrame, Instance, Skeleton, Camera, Video, etc.)
– io/    : Format-specific readers and writers (SLP, NWB, COCO, DeepLabCut, JABS, LabelStudio, Ultralytics, etc.), plus CLI entry point
- scripts/ : Utility scripts for coverage, changelog, ref-page, version reordering
- docs/    : MkDocs documentation site (assets, CSS, markdown guides)
- tests/   : Pytest suites for I/O modules, model behaviors, video reading/writing, integration tests
- .github/ : CI/CD workflows (Lint, CI, docs, code review)
- config (pyproject.toml, environment.yml, mkdocs.yml, codecov.yml)

- Architectural patterns
- Layered design:
– Core Model layer (defines data)
– I/O layer (adapts between files and model)
– CLI layer (exposes commands)
– Scripts and Docs (auxiliary tooling)
- Plugin-like I/O modules: each file format has its own submodule implementing load/save via a common interface.
- Factory pattern in io/main.py for dispatching based on file extension.

##### README for additional insights
- Emphasizes minimal dependencies, optional extras for video backends (opencv, ffmpeg, pyav).
- Demonstrates typical usage: load_slp, save_file, load_video, model instantiation.
- Notes that there is no labeling/training/inference in this package.

##### Detail
- How dependency injection or factory dispatch works for format readers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Core Model Layer"
        CM1["camera.py"]:::model
        CM2["instance.py"]:::model
        CM3["labeled_frame.py"]:::model
        CM4["labels.py"]:::model
        CM5["labels_set.py"]:::model
        CM6["matching.py"]:::model
        CM7["skeleton.py"]:::model
        CM8["suggestions.py"]:::model
        CM9["video.py"]:::model
    end

    subgraph "Format I/O Plugins"
        IOF["main.py (Factory)"]:::io
        IOCLI["cli.py"]:::cli
        PL1["slp.py"]:::plugin
        PL2["nwb.py"]:::plugin
        PL3["nwb_annotations.py"]:::plugin
        PL4["nwb_predictions.py"]:::plugin
        PL5["coco.py"]:::plugin
        PL6["dlc.py"]:::plugin
        PL7["jabs.py"]:::plugin
        PL8["labelstudio.py"]:::plugin
        PL9["leap.py"]:::plugin
        PL10["alphatracker.py"]:::plugin
        PL11["ultralytics.py"]:::plugin
        PL12["skeleton.py"]:::plugin
        PL13["utils.py"]:::plugin
    end

    subgraph "Video Backend Layer"
        VB1["video_reading.py"]:::optional
        VB2["video_writing.py"]:::optional
    end

    subgraph "CLI Entry Point"
        CLI["sleap-io CLI"]:::cli
    end

    subgraph "Tooling Scripts"
        S1["cov_summary.py"]:::tooling
        S2["gen_changelog.py"]:::tooling
        S3["gen_ref_pages.py"]:::tooling
        S4["reorder_versions.py"]:::tooling
    end

    subgraph "Documentation Site"
        D1["index.md"]:::docs
        D2["formats.md"]:::docs
        D3["model.md"]:::docs
        D4["merging.md"]:::docs
        D5["examples.md"]:::docs
        D6["assets/"]:::docs
        D7["mkdocstrings.css"]:::docs
    end

    subgraph "Tests & CI"
        T1["tests/io/"]:::tests
        T2["tests/model/"]:::tests
        T3["tests/data/"]:::tests
        T4["tests/fixtures/"]:::tests
        T5["conftest.py"]:::tests
        GH[".github/workflows/"]:::ci
        CC["codecov.yml"]:::ci
    end

    %% Relationships
    CLI -->|"invoke"| IOF
    IOF -->|"dispatch"| PL1
    IOF --> PL2
    IOF --> PL3
    IOF --> PL4
    IOF --> PL5
    IOF --> PL6
    IOF --> PL7
    IOF --> PL8
    IOF --> PL9
    IOF --> PL10
    IOF --> PL11
    IOF --> PL12
    IOF --> PL13

    PL1 -->|"load/save"| CM1
    PL2 --> CM1
    PL3 --> CM1
    PL4 --> CM1
    PL5 --> CM1
    PL6 --> CM1
    PL7 --> CM1
    PL8 --> CM1
    PL9 --> CM1
    PL10 --> CM1
    PL11 --> CM1
    PL12 --> CM1
    PL13 --> CM1

    CM9 -->|"uses"| VB1
    CM9 --> VB2

    S1 --> CM1
    S1 --> IOF
    S2 --> IOF
    S3 --> IOF
    S4 --> IOF

    T1 --> IOF
    T2 --> CM1
    T3 --> CM1
    T4 --> CM1
    T5 --> IOF
    T1 --> CM1
    T2 --> IOF
    GH --> IOF
    GH --> CM1
    CC --> IOF

    %% Click Events
    click CM1 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/model/camera.py"
    click CM2 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/model/instance.py"
    click CM3 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/model/labeled_frame.py"
    click CM4 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/model/labels.py"
    click CM5 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/model/labels_set.py"
    click CM6 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/model/matching.py"
    click CM7 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/model/skeleton.py"
    click CM8 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/model/suggestions.py"
    click CM9 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/model/video.py"

    click IOF "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/main.py"
    click IOCLI "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/cli.py"

    click PL1 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/slp.py"
    click PL2 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/nwb.py"
    click PL3 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/nwb_annotations.py"
    click PL4 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/nwb_predictions.py"
    click PL5 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/coco.py"
    click PL6 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/dlc.py"
    click PL7 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/jabs.py"
    click PL8 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/labelstudio.py"
    click PL9 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/leap.py"
    click PL10 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/alphatracker.py"
    click PL11 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/ultralytics.py"
    click PL12 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/skeleton.py"
    click PL13 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/utils.py"

    click VB1 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/video_reading.py"
    click VB2 "https://github.com/talmolab/sleap-io/blob/main/sleap_io/io/video_writing.py"

    click S1 "https://github.com/talmolab/sleap-io/blob/main/scripts/cov_summary.py"
    click S2 "https://github.com/talmolab/sleap-io/blob/main/scripts/gen_changelog.py"
    click S3 "https://github.com/talmolab/sleap-io/blob/main/scripts/gen_ref_pages.py"
    click S4 "https://github.com/talmolab/sleap-io/blob/main/scripts/reorder_versions.py"

    click D1 "https://github.com/talmolab/sleap-io/blob/main/docs/index.md"
    click D2 "https://github.com/talmolab/sleap-io/blob/main/docs/formats.md"
    click D3 "https://github.com/talmolab/sleap-io/blob/main/docs/model.md"
    click D4 "https://github.com/talmolab/sleap-io/blob/main/docs/merging.md"
    click D5 "https://github.com/talmolab/sleap-io/blob/main/docs/examples.md"
    click D6 "https://github.com/talmolab/sleap-io/tree/main/docs/assets/"
    click D7 "https://github.com/talmolab/sleap-io/blob/main/docs/css/mkdocstrings.css"

    click T1 "https://github.com/talmolab/sleap-io/tree/main/tests/io/"
    click T2 "https://github.com/talmolab/sleap-io/tree/main/tests/model/"
    click T3 "https://github.com/talmolab/sleap-io/tree/main/tests/data/"
    click T4 "https://github.com/talmolab/sleap-io/tree/main/tests/fixtures/"
    click T5 "https://github.com/talmolab/sleap-io/blob/main/tests/conftest.py"
    click GH "https://github.com/talmolab/sleap-io/tree/main/.github/workflows/"
    click CC "https://github.com/talmolab/sleap-io/blob/main/codecov.yml"

    %% Styles
    classDef model fill:#FFDDAA,stroke:#CC8833;
    classDef io fill:#AADDDD,stroke:#3399AA;
    classDef plugin fill:#88CCFF,stroke:#226699;
    classDef optional fill:#DDDDDD,stroke:#888888,stroke-dasharray: 5 5;
    classDef cli fill:#FFCC88,stroke:#CC9933;
    classDef tooling fill:#DDAAFF,stroke:#AA33AA;
    classDef docs fill:#CCEEAA,stroke:#66AA33;
    classDef tests fill:#FFAAAA,stroke:#CC3333;
    classDef ci fill:#FFAAAA,stroke:#CC3333,stroke-dasharray: 2 2;
```
