How serycjon/woft works
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.