# bladeszasza/sowlv2 architecture

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

- Interactive diagram: https://gitdiagram.com/bladeszasza/sowlv2
- Repository: https://github.com/bladeszasza/sowlv2

## Overview

##### Project Type and Purpose
- This is a Python‐based, open‐source command‐line tool (CLI application) named SOWLv2.
- It performs text‐prompted object segmentation on images, sequences of frames, or videos.

##### File Structure Highlights
- Top‐level:
- CLI scaffolding and project metadata (setup.py, pyproject.toml, requirements.txt).
- config/config_example.yaml for YAML‐based configuration.
- assets/ (logos, example images).
- docs/architecture.md (detailed architecture write‐up).
- notebooks/ (Colab & Jupyter demos).
- sowlv2/ package:
- cli.py: entrypoint, argument parsing, config loading.
- pipeline.py: orchestrator that routes to image or video pipeline.
- image_pipeline.py, video_pipeline.py: per‐input‐type processing.
- models/: wrappers for OWLv2 and SAM 2 (owl.py, sam2_wrapper.py).
- data/config.py & utils/path_config.py: configuration handling.
- utils/: filesystem IO, frame extraction, video utilities, pipeline helpers.
- tests/: unit and integration tests covering CLI, utils, end‐to‐end behavior.

##### Extracted Architectural Pattern
- Pipeline pattern with two sequential stages:
b. Segmentation stage (SAM 2) → produces masks & overlays.
- Configuration layer (CLI args or YAML) decoupled from pipeline logic.
- Modularized wrappers for each external model, making it extensible.
- Utilities for I/O operations and output assembly (images, masks, videos).

##### Main Components
A. Input Layer
- “User” via CLI or “Config File” (YAML).
- Supported inputs: single image, directory of frames, video file.
B. Configuration Loader
- Module: sowlv2/cli.py & data/config.py
- Parses args, loads YAML, resolves model names, thresholds, paths.
C. Pipeline Orchestrator
- Module: sowlv2/pipeline.py
- Routes to Image Pipeline or Video Pipeline based on input type.
D. Image Pipeline
- Module: image_pipeline.py
- Loop over frames/images: invokes Detection → Segmentation → I/O.
E. Video Pipeline
- Module: video_pipeline.py
- Extracts frames (via utils/frame_utils), runs image pipeline logic, reassembles videos (via utils/video_utils).
F. OWLv2 Detection Wrapper
- Module: sowlv2/models/owl.py
G. SAM 2 Segmentation Wrapper
- Module: sowlv2/models/sam2_wrapper.py
H. Output Generator / Filesystem
- Modules: utils/filesystem_utils.py, utils/pipeline_utils.py
- Writes binary masks, overlay images, merged outputs, and final videos to disk under structured directories.
I. External Dependencies / Services
- Transformers library (OWLv2), sam2 library (SAM 2), OpenCV + NumPy + Pillow for image/video I/O, PyTorch for model execution.
J. Storage
- Local filesystem (no external databases) with structured directories: binary/, overlay/, video/.

##### Relationships and Data Flow
- User ➔ CLI Parser ➔ Configuration Loader ➔ Pipeline Orchestrator
- Pipeline Orchestrator ➔ [Image Pipeline or Video Pipeline]
- For each frame/image:
└─➔ Output Generator writes mask files and overlay images
- Video Pipeline additionally: Frame extraction ➔ per‐frame pipeline ➔ video assembly.

##### Architectural Patterns and Principles
- Separation of concerns: parsing/configuration vs. orchestration vs. model invocation vs. I/O.
- Modular wrappers around external systems (OWL, SAM) for ease of swapping models.
- Pipeline abstraction supporting both image and video flows.
- High cohesion: each module has a clear single responsibility.
- Extensibility: new detectors or segmenters can be plugged in by adding wrappers and updating orchestrator.

##### Essential Elements to Capture
- Component labels exactly matching module names.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User and Config File
    User["User"]:::external
    CLIFile["config/config_example.yaml"]:::externalStorage

    %% Configuration Layer
    subgraph "Configuration Layer"
        CLI["sowlv2/cli.py"]:::internal
        ConfigLoader["sowlv2/data/config.py"]:::internal
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Orchestrator["sowlv2/pipeline.py"]:::internal
    end

    %% Pipelines
    subgraph "Image Pipeline"
        ImagePipeline["sowlv2/image_pipeline.py"]:::internal
    end
    subgraph "Video Pipeline"
        VideoPipeline["sowlv2/video_pipeline.py"]:::internal
    end

    %% Model Layer
    subgraph "Model Layer"
        OWL["sowlv2/models/owl.py"]:::internal
        SAM["sowlv2/models/sam2_wrapper.py"]:::internal
    end

    %% I/O Layer
    subgraph "I/O Layer"
        FSUtils["sowlv2/utils/filesystem_utils.py"]:::internal
        PipelineUtils["sowlv2/utils/pipeline_utils.py"]:::internal
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Transformers(["Transformers<br/>HuggingFace"]):::external
        SAM2Lib(["sam2 Library"]):::external
        CVLib(["OpenCV, NumPy, Pillow"]):::external
        Torch(["PyTorch"]):::external
    end

    %% Storage
    FileSystem(["Local Filesystem<br/>binary/, overlay/, video/"]):::storage

    %% Data Flow
    User -->|"CLI args"| CLI
    CLIFile -->|"YAML config"| CLI
    CLI -->|"args & config"| ConfigLoader
    ConfigLoader -->|"resolved settings"| Orchestrator

    Orchestrator -->|"image input"| ImagePipeline
    Orchestrator -->|"video input"| VideoPipeline

    ImagePipeline -->|"frames/images"| OWL
    OWL -->|"boxes"| SAM
    SAM -->|"masks & overlays"| FSUtils
    FSUtils -->|"writes files"| FileSystem
    PipelineUtils -->|"organizes outputs"| FileSystem

    VideoPipeline -->|"extract frames"| PipelineUtils
    VideoPipeline --> ImagePipeline
    VideoPipeline -->|"assemble video"| FSUtils

    OWL --> Transformers
    OWL --> Torch
    SAM --> SAM2Lib
    FSUtils --> CVLib

    %% Click Events
    click CLI "https://github.com/bladeszasza/sowlv2/blob/main/sowlv2/cli.py"
    click CLIFile "https://github.com/bladeszasza/sowlv2/blob/main/config/config_example.yaml"
    click ConfigLoader "https://github.com/bladeszasza/sowlv2/blob/main/sowlv2/data/config.py"
    click Orchestrator "https://github.com/bladeszasza/sowlv2/blob/main/sowlv2/pipeline.py"
    click ImagePipeline "https://github.com/bladeszasza/sowlv2/blob/main/sowlv2/image_pipeline.py"
    click VideoPipeline "https://github.com/bladeszasza/sowlv2/blob/main/sowlv2/video_pipeline.py"
    click OWL "https://github.com/bladeszasza/sowlv2/blob/main/sowlv2/models/owl.py"
    click SAM "https://github.com/bladeszasza/sowlv2/blob/main/sowlv2/models/sam2_wrapper.py"
    click FSUtils "https://github.com/bladeszasza/sowlv2/blob/main/sowlv2/utils/filesystem_utils.py"
    click PipelineUtils "https://github.com/bladeszasza/sowlv2/blob/main/sowlv2/utils/pipeline_utils.py"

    %% Styles
    classDef internal fill:#E0F7FA,stroke:#006064,color:#004D40;
    classDef external fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20;
    classDef storage fill:#FFF3E0,stroke:#EF6C00,color:#E65100;
    classDef externalStorage fill:#FFF3E0,stroke:#EF6C00,color:#E65100;
```
