# serycjon/woft architecture

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

- Interactive diagram: https://gitdiagram.com/serycjon/woft
- Repository: https://github.com/serycjon/woft

## Overview

##### Project type and purpose
- This is a Python-based research library and demo application for planar object tracking using weighted optical flow, built around the WOFT method from the WACV 2023 paper.
- It bundles custom tracker implementations, configuration management, pre-trained optical-flow networks (RAFT, LiteFlowNet2 via mmflow), utility functions, and a simple CLI demo.

##### File structure
Top-level:
- WOFT_demo.py – command-line entry point for running demos
- demo/ – sample sequences (POT-210) for evaluation
- pytracking/ – core library
- setup.cfg, .gitignore, LICENSE, README.org

Inside pytracking/:
- configs/ – Python modules defining experiment configurations (choice of network, downscaling, optimizer, hyperparameters)
- external/ – vendored optical-flow libraries
– RAFT/ (modified RAFT implementation)
– mmflow/ (slightly patched mmflow submodule)
- optical_flow/ – wrappers around external flow libs, unified API
- tracker/ – planar-tracking algorithms (WOFT, YAOF variants)
- utils/ – I/O, caching, geometry, interpolation, logging, timing, notifications
- weights/ – pre-trained network checkpoints

##### README insights
- Lists required Python dependencies (torch, torchvision, kornia, mmcv, openmim, opencv, etc.)
- Instructions to prepare virtualenv, install submodules, download checkpoints
- Demo usage via WOFT_demo.py, passing path + optional config

a. Main components
- CLI / Demo Runner (WOFT_demo.py)
- Configuration Manager (pytracking/configs + utils/config)
- Data Loader (reads image sequences from demo/ or user path)
- Model Loader (loads pre-trained flow networks from pytracking/weights)
- Optical Flow Module
– RAFT subsystem (pytracking/external/RAFT)
– mmflow-LiteFlowNet2 subsystem (pytracking/external/mmflow)
- Tracker Engine (pytracking/tracker: WOFT, YAOF)
- Geometry & Solver (least_squares_H, geom_utils)
- Visualization & Output (pytracking/utils/vis_utils, OpenCV, matplotlib)
- Logging & Notifications (pytracking/utils/timing, telegram_notification)

b. Relationships and interactions
1. The CLI invokes the Config Manager.
2. Config Manager instantiates Data Loader + selects Optical Flow model + tracker parameters.
3. Data Loader streams frames to Optical Flow Module.
4. Optical Flow Module invokes either RAFT or mmflow submodule to compute per-frame flow fields.
5. Tracker Engine consumes flow fields and previous homography estimate, uses Geometry & Solver to compute new planar transform.
6. Updated pose passed back to visualization for overlay or metrics computation.
7. Throughout, utility modules handle caching, I/O, logging, and optional Telegram alerts.

c. Architectural patterns and design principles
- Modular layering: separation of flow estimation, tracking logic, config management, utilities.
- Plug-in architecture for flow back-ends (RAFT vs mmflow) via a unified wrapper in optical_flow/.
- Configuration-driven experiments: each .py config selects models, hyperparameters, evaluation protocol.
- Lightweight CLI orchestration with a single entry point.

d. Key technologies/frameworks
- Python 3.x, PyTorch
- RAFT (deep flow), mmflow (LiteFlowNet2)
- kornia, einops for tensor ops
- OpenCV, matplotlib for visualization
- pandas, scipy for logging and metrics
- virtualenv, openmim, mmcv for environment management

##### Capturing essential architectural elements
- Be exhaustive in listing core subdirectories as logical components: configs, optical_flow, tracker, utils.
- Weights folder as a “Model Zoo” datastore from which the Model Loader fetches.
- That the demo folder is a read-only data source and that logs directory collects run outputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI and Data Source
    CLI["CLI Runner\n(WOFT_demo.py)"]:::cli
    DemoData["Demo Dataset\n(demo/)"]:::cli
    CLI -->|"reads sample sequences"| DemoData

    %% Core Configuration and Management
    subgraph "Core Library" 
        direction TB
        ConfigManager["Config Manager"]:::core
        ConfigManager -->|instantiates| DataLoader
        ConfigManager -->|selects model & params| ModelLoader
        DataLoader["Data Loader\n(pytracking/utils/io.py)"]:::util
        ModelLoader["Model Loader\n(pytracking/weights/)"]:::datastore
        DataLoader -->|streams frames| OpticalFlowModule
        ModelLoader -->|provides checkpoints| OpticalFlowModule

        %% Optical Flow Module with plugin subsystems
        subgraph "Optical Flow Module" 
            direction TB
            OFModule["Optical Flow Module\n(pytracking/optical_flow/)"]:::core
            OFModule -->|invokes| RAFTSub
            OFModule -->|invokes| MMFlowSub
        end

        %% Tracker Engine
        subgraph "Tracker Engine" 
            direction TB
            WOFT["WOFT Tracker\n(pytracking/tracker/WOFT.py)"]:::core
            YAOF["YAOF Tracker\n(pytracking/tracker/YAOF_tracker_single_control.py)"]:::core
        end

        %% Geometry & Solver
        GeometrySolver["Geometry & Solver"]:::core
        %% Visualization & Output
        Visualization["Visualization & Output\n(pytracking/utils/vis_utils.py)"]:::util

        %% Utilities
        subgraph "Utilities" 
            direction TB
            IO["I/O Utils\n(io.py)"]:::util
            Caching["Caching\n(caching.py)"]:::util
            Interp["Interpolation\n(interpolation.py)"]:::util
            Misc["Miscellaneous\n(misc.py)"]:::util
            VarUtils["Various Utils\n(various_utils.py)"]:::util
            Timing["Logging & Timing\n(timing.py)"]:::util
            Telegram["Notifications\n(telegram_notification.py)"]:::util
        end
        %% Logging outputs
        Logs["Logs & Metrics\n(logs/)"]:::datastore
    end

    %% External Submodules
    subgraph "External Flow Backends" 
        direction TB
        RAFTSub["RAFT Submodule\n(pytracking/external/RAFT/)"]:::external
        MMFlowSub["mmflow Submodule\n(pytracking/external/mmflow/)"]:::external
    end

    %% Weights Zoo
    WeightsZoo["Weights Zoo\n(pytracking/weights/)"]:::datastore

    %% Data & Flow connections
    DataLoader -->|reads frames| DemoData
    OpticalFlowModule -->|flows| TrackerEngine
    TrackerEngine -->|uses| GeometrySolver
    GeometrySolver -->|pose| Visualization
    Visualization -->|outputs to| Logs

    %% Utility dependencies
    DataLoader --> IO
    ModelLoader --> IO
    ConfigManager --> IO
    TrackerEngine --> Caching
    TrackerEngine --> Interp
    TrackerEngine --> Misc
    TrackerEngine --> VarUtils
    TrackerEngine --> Timing
    Visualization --> Timing
    Visualization --> Telegram

    %% Click Events
    click CLI "https://github.com/serycjon/woft/blob/master/WOFT_demo.py"
    click ConfigManager "https://github.com/serycjon/woft/tree/master/pytracking/configs/"
    click ConfigManager "https://github.com/serycjon/woft/blob/master/pytracking/utils/config.py"
    click DataLoader "https://github.com/serycjon/woft/blob/master/pytracking/utils/io.py"
    click ModelLoader "https://github.com/serycjon/woft/tree/master/pytracking/weights/"
    click OFModule "https://github.com/serycjon/woft/blob/master/pytracking/optical_flow/__init__.py"
    click OFModule "https://github.com/serycjon/woft/blob/master/pytracking/optical_flow/mm.py"
    click OFModule "https://github.com/serycjon/woft/blob/master/pytracking/optical_flow/raft.py"
    click RAFTSub "https://github.com/serycjon/woft/tree/master/pytracking/external/RAFT/"
    click MMFlowSub "https://github.com/serycjon/woft/tree/master/pytracking/external/mmflow/"
    click WOFT "https://github.com/serycjon/woft/blob/master/pytracking/tracker/WOFT.py"
    click WOFT "https://github.com/serycjon/woft/blob/master/pytracking/tracker/WOFT_window.py"
    click YAOF "https://github.com/serycjon/woft/blob/master/pytracking/tracker/YAOF_tracker_single_control.py"
    click GeometrySolver "https://github.com/serycjon/woft/blob/master/pytracking/utils/least_squares_H.py"
    click GeometrySolver "https://github.com/serycjon/woft/blob/master/pytracking/utils/geom_utils.py"
    click Visualization "https://github.com/serycjon/woft/blob/master/pytracking/utils/vis_utils.py"
    click Timing "https://github.com/serycjon/woft/blob/master/pytracking/utils/timing.py"
    click Telegram "https://github.com/serycjon/woft/blob/master/pytracking/utils/telegram_notification.py"
    click Caching "https://github.com/serycjon/woft/blob/master/pytracking/utils/caching.py"
    click Interp "https://github.com/serycjon/woft/blob/master/pytracking/utils/interpolation.py"
    click Misc "https://github.com/serycjon/woft/blob/master/pytracking/utils/misc.py"
    click VarUtils "https://github.com/serycjon/woft/blob/master/pytracking/utils/various_utils.py"

    %% Styles
    classDef core fill:#D0E6F6,stroke:#3182CE,stroke-width:1px
    classDef util fill:#FFE4B5,stroke:#DD8C00,stroke-width:1px
    classDef external fill:#D5F5E3,stroke:#28A745,stroke-width:1px
    classDef cli fill:#E2E3E5,stroke:#6C757D,stroke-width:1px
    classDef datastore fill:#F0F0F0,stroke:#888888,stroke-width:1px,stroke-dasharray: 5 5
```
