# sea-ai/seametrics architecture

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

- Interactive diagram: https://gitdiagram.com/sea-ai/seametrics
- Repository: https://github.com/sea-ai/seametrics

## Overview

##### Project Type and Purpose
- Type: Open-source Python library (no separate frontend or backend service).
- Purpose: Provide modular implementations of computer-vision and related metrics (detection, panoptic, tracking, horizon, payload processing, user-friendly wrappers).

##### File Structure and Key Modules
At top level you have:
- Configuration & CI:
– .github/workflows/*.yml (CI pipelines, tests, SonarCloud)
– pyproject.toml, requirements.txt, sonar-project.properties
- Notebooks: Jupyter notebooks for demos & experiments.
- Seametrics package:
– seametrics/annotations (softmin, label utils)
– seametrics/detection (cocoeval-based mAP, pr-rec-f1)
– seametrics/panoptic (PQ metric, TM implementations)
– seametrics/tracking (track metrics)
– seametrics/horizon (horizon metrics computations)
– seametrics/payload (payload processing utilities)
– seametrics/user_friendly (high-level wrappers)
– seametrics/constants.py, seametrics/customMAP (AP wrapper)
- Tests: Unit tests mirror each submodule under tests/*.

##### README for Additional Insights
- Core functionality outlined: PrecisionRecallF1Support for detection, hugging-face integration hints.
- Optional dependencies (e.g., fiftyone) for extended workflows.

##### Main Components & Their Interactions
A. Library Core Modules (group into logical layers):
1. Core Utilities
– utils modules (shared utilities, constant definitions)
– compute_softmin, label2id mappings
2. Metric Implementations
– Detection metrics (cocoeval‐wrapped, pure numpy, torchmetrics adapter)
– Panoptic Quality (PQ) metrics
– Tracking metrics
– Horizon metrics
– Payload processor
3. User-Friendly Interface
– seametrics/user_friendly (one-line calls, simplified APIs)
B. External Dependencies
– numpy (numerical arrays)
– torchmetrics (optional)
– fiftyone (optional)
– pytest (testing)
C. CI/CD & Quality
– GitHub Actions pipelines (unit tests, linting, SonarCloud upload)

- User code → imports seametrics/user_friendly → internally calls specific metric modules → utils & constants → returns results.
- Notebooks → import seametrics modules directly for experimentation.
- CI pipelines → run tests against seametrics modules.

##### Architectural Patterns & Design Principles
- Modular subpackages per metric domain (separation of concerns).
- Shared utility layer for code reuse.
- Adapter pattern for wrapping external evaluation code (e.g., COCOeval → torchmetrics → numpy).
- Optional-dependency gates (fiftyone integration only if installed).
- Test-first / test-driven structure: one test folder per submodule.

##### Essential Elements to Capture
– Subpackage boundaries and roles.
– Utility/core library relationships.
– Entry points for end users (user_friendly API, notebooks).
– External dependencies and optional integrations.
– CI/CD pipelines and their relation to code/test artifacts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CI/CD & Configuration"
        ActionsA[".github/workflows/actions.yml"]:::ci
        ActionsB[".github/workflows/sonar-cloud.yaml"]:::ci
        Pyproject["pyproject.toml"]:::ci
        Requirements["requirements.txt"]:::ci
        SonarProps["sonar-project.properties"]:::ci
    end

    subgraph "Core Utilities"
        Constants["seametrics/constants.py"]:::utils
        AnnotationUtils["seametrics/annotations/utils.py"]:::utils
        Softmin["seametrics/annotations/compute_softmin.py"]:::utils
        Label2ID["seametrics/annotations/label2id.json"]:::utils
        FOUtils["seametrics/fo_utils/utils.py"]:::utils
    end

    subgraph "Custom AP Wrapper" 
        AP_WRAPPER["seametrics/customMAP/AP.py"]:::core
    end

    subgraph "Metric Implementations"
        subgraph Detection
            DE_Coco["seametrics/detection/cocoeval.py"]:::core
            DE_Imports["seametrics/detection/imports.py"]:::core
            DE_NP_PR["seametrics/detection/np/pr_rec_f1.py"]:::core
            DE_NP_UTIL["seametrics/detection/np/utils.py"]:::core
            DE_TM_PR["seametrics/detection/tm/pr_rec_f1.py"]:::core
            DE_UTIL["seametrics/detection/utils.py"]:::core
        end
        subgraph Panoptic
            PA_CONST["seametrics/panoptic/consts.py"]:::core
            PA_PQ["seametrics/panoptic/pq.py"]:::core
            PA_TM_FUN["seametrics/panoptic/tm/functionalities.py"]:::core
            PA_UTIL["seametrics/panoptic/utils.py"]:::core
        end
        subgraph Tracking
            TR_IMPORT["seametrics/tracking/imports.py"]:::core
            TR_TRACK["seametrics/tracking/track.py"]:::core
            TR_UTIL["seametrics/tracking/utils.py"]:::core
        end
        subgraph Horizon
            HO_HZ["seametrics/horizon/horizon.py"]:::core
            HO_UTIL["seametrics/horizon/utils.py"]:::core
            HO_README["seametrics/horizon/README.md"]:::core
        end
        subgraph Payload
            PL_PROC["seametrics/payload/processor.py"]:::core
        end
    end

    subgraph "User Interface" 
        UF_UTIL["seametrics/user_friendly/utils.py"]:::ui
    end

    subgraph "Consumers/Demos"
        Notebooks["notebooks/*.ipynb"]:::cons
    end

    subgraph "Tests"
        DET_TEST["tests/detection/"]:::test
        PAN_TEST["tests/panoptic/"]:::test
        HORIZ_TEST["tests/horizon/"]:::test
        PAY_TEST["tests/payload/"]:::test
        UF_TEST["tests/user_friendly/"]:::test
    end

    subgraph "External Dependencies"
        Numpy["numpy"]:::ext
        Torch["torchmetrics"]:::ext
        Fifty["fiftyone"]:::ext
        Pytest["pytest"]:::ext
    end

    %% Relationships
    UF_UTIL -->|calls detection metrics| DE_Coco
    UF_UTIL -->|calls panoptic metrics| PA_PQ
    UF_UTIL -->|calls tracking metrics| TR_TRACK
    UF_UTIL -->|calls horizon metrics| HO_HZ
    UF_UTIL -->|calls payload processor| PL_PROC
    Notebooks -->|imports| DE_Coco
    Notebooks -->|imports| PA_PQ
    Notebooks -->|imports| TR_TRACK
    Notebooks -->|imports| HO_HZ
    Notebooks -->|imports| PL_PROC
    DE_Imports -->|uses constants| Constants
    PA_UTIL -->|uses constants| Constants
    TR_UTIL -->|uses constants| Constants
    HO_UTIL -->|uses constants| Constants
    PL_PROC -->|uses constants| Constants
    AP_WRAPPER -->|wraps metrics| DE_Coco
    AP_WRAPPER -->|wraps metrics| PA_PQ
    AP_WRAPPER -->|wraps metrics| TR_TRACK
    AP_WRAPPER -->|wraps metrics| HO_HZ
    AP_WRAPPER -->|wraps metrics| PL_PROC
    Torch -.->|adapter support| DE_TM_PR
    Torch -.->|adapter support| PA_TM_FUN
    Fifty -.->|optional integration| UF_UTIL
    Numpy -->|core computation| DE_NP_PR
    Pytest -->|runs tests| DET_TEST
    Pytest -->|runs tests| PAN_TEST
    Pytest -->|runs tests| HORIZ_TEST
    Pytest -->|runs tests| PAY_TEST
    Pytest -->|runs tests| UF_TEST
    ActionsA -->|triggers| DET_TEST
    ActionsA -->|triggers| PAN_TEST
    ActionsA -->|triggers| HORIZ_TEST
    ActionsA -->|triggers| PAY_TEST
    ActionsA -->|triggers| UF_TEST

    %% Click Events
    click ActionsA "https://github.com/sea-ai/seametrics/blob/develop/.github/workflows/actions.yml"
    click ActionsB "https://github.com/sea-ai/seametrics/blob/develop/.github/workflows/sonar-cloud.yaml"
    click Pyproject "https://github.com/sea-ai/seametrics/blob/develop/pyproject.toml"
    click Requirements "https://github.com/sea-ai/seametrics/blob/develop/requirements.txt"
    click SonarProps "https://github.com/sea-ai/seametrics/blob/develop/sonar-project.properties"
    click Constants "https://github.com/sea-ai/seametrics/blob/develop/seametrics/constants.py"
    click AnnotationUtils "https://github.com/sea-ai/seametrics/blob/develop/seametrics/annotations/utils.py"
    click Softmin "https://github.com/sea-ai/seametrics/blob/develop/seametrics/annotations/compute_softmin.py"
    click Label2ID "https://github.com/sea-ai/seametrics/blob/develop/seametrics/annotations/label2id.json"
    click FOUtils "https://github.com/sea-ai/seametrics/blob/develop/seametrics/fo_utils/utils.py"
    click AP_WRAPPER "https://github.com/sea-ai/seametrics/blob/develop/seametrics/customMAP/AP.py"
    click DE_Coco "https://github.com/sea-ai/seametrics/blob/develop/seametrics/detection/cocoeval.py"
    click DE_Imports "https://github.com/sea-ai/seametrics/blob/develop/seametrics/detection/imports.py"
    click DE_NP_PR "https://github.com/sea-ai/seametrics/blob/develop/seametrics/detection/np/pr_rec_f1.py"
    click DE_NP_UTIL "https://github.com/sea-ai/seametrics/blob/develop/seametrics/detection/np/utils.py"
    click DE_TM_PR "https://github.com/sea-ai/seametrics/blob/develop/seametrics/detection/tm/pr_rec_f1.py"
    click DE_UTIL "https://github.com/sea-ai/seametrics/blob/develop/seametrics/detection/utils.py"
    click PA_CONST "https://github.com/sea-ai/seametrics/blob/develop/seametrics/panoptic/consts.py"
    click PA_PQ "https://github.com/sea-ai/seametrics/blob/develop/seametrics/panoptic/pq.py"
    click PA_TM_FUN "https://github.com/sea-ai/seametrics/blob/develop/seametrics/panoptic/tm/functionalities.py"
    click PA_UTIL "https://github.com/sea-ai/seametrics/blob/develop/seametrics/panoptic/utils.py"
    click TR_IMPORT "https://github.com/sea-ai/seametrics/blob/develop/seametrics/tracking/imports.py"
    click TR_TRACK "https://github.com/sea-ai/seametrics/blob/develop/seametrics/tracking/track.py"
    click TR_UTIL "https://github.com/sea-ai/seametrics/blob/develop/seametrics/tracking/utils.py"
    click HO_HZ "https://github.com/sea-ai/seametrics/blob/develop/seametrics/horizon/horizon.py"
    click HO_UTIL "https://github.com/sea-ai/seametrics/blob/develop/seametrics/horizon/utils.py"
    click HO_README "https://github.com/sea-ai/seametrics/blob/develop/seametrics/horizon/README.md"
    click PL_PROC "https://github.com/sea-ai/seametrics/blob/develop/seametrics/payload/processor.py"
    click UF_UTIL "https://github.com/sea-ai/seametrics/blob/develop/seametrics/user_friendly/utils.py"
    click Notebooks "https://github.com/sea-ai/seametrics/blob/develop/notebooks/*.ipynb"

    %% Styles
    classDef ci fill:#bbbbbb,stroke:#333,stroke-width:1px
    classDef utils fill:#88cc88,stroke:#333,stroke-width:1px
    classDef core fill:#88aaff,stroke:#333,stroke-width:1px
    classDef ui fill:#ffcc88,stroke:#333,stroke-width:1px
    classDef ext fill:#dddddd,stroke:#333,stroke-width:1px
    classDef cons fill:#ffeecc,stroke:#333,stroke-width:1px
    classDef test fill:#eeeeee,stroke:#333,stroke-width:1px
```
