Skip to content

Commit 5c042d1

Browse files
woshimajintaowoshimajintao
authored
Update README.md
Update the smart annotation control
1 parent a1ee1cd commit 5c042d1

1 file changed

Lines changed: 48 additions & 57 deletions

File tree

‎annotation_tool/controllers/README.md‎

Lines changed: 48 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,18 @@
11
# ⚙️ Controllers Module (Logic Layer)
22

3-
This directory contains the business logic of the **SoccerNet Pro Annotation Tool**. following the **MVC (Model-View-Controller)** architecture, these scripts act as the bridge between the data (`models.py`) and the interface (`ui/`). They handle user input, data processing, file I/O, and application state management.
3+
This directory contains the business logic of the **SoccerNet Pro Annotation Tool**. Following the **MVC (Model-View-Controller)** architecture, these scripts act as the bridge between the central data (`models.py`) and the user interface (`ui/`). They handle user input, data processing, file I/O, application state management, and the newly integrated **AI Model Inference & Training**.
44

55
## 📂 Directory Structure
66

77
```text
88
controllers/
9-
├── media_controller.py # [NEW] Unified Video Playback Manager
10-
├── history_manager.py # Universal Undo/Redo logic
9+
├── media_controller.py # Unified Video Playback Manager (Anti-freeze logic)
10+
├── history_manager.py # Universal Undo/Redo logic (Supports Batch AI Actions)
1111
├── router.py # Application routing and mode switching
12-
├── classification/ # Logic specific to Whole-Video Classification
13-
├── localization/ # Logic specific to Action Spotting (Timestamps)
12+
├── classification/ # Logic specific to Whole-Video Classification & AI
13+
├── localization/ # Logic specific to Action Spotting (Timestamps) & AI
1414
├── description/ # Logic specific to Global Captioning (Text)
1515
└── dense_description/ # Logic specific to Dense Captioning (Timestamped Text)
16-
1716
```
1817

1918
---
@@ -25,82 +24,74 @@ controllers/
2524
These controllers provide foundational functionality used across the entire application to ensure stability and consistency.
2625

2726
* **`media_controller.py`**
28-
* **Role**: The centralized video playback engine used by all modes.
29-
* **Responsibilities**:
30-
* **Robust State Management**: Implements a strict `Stop -> Clear -> Load -> Delay -> Play` sequence to prevent black screens and buffer artifacts.
31-
* **Race Condition Prevention**: Uses an internal `QTimer` that is explicitly cancelled upon stop, preventing videos from starting in the background after a user has closed a project.
32-
* **Visual Clearing**: Forces the `QVideoWidget` to repaint/update on stop, ensuring no "stuck frames" remain visible.
33-
34-
35-
27+
* **Role**: The centralized video playback engine used by all modes.
28+
* **Responsibilities**:
29+
* **Robust State Management**: Implements a strict `Stop -> Clear -> Load -> Delay -> Play` sequence to prevent black screens and buffer artifacts.
30+
* **Race Condition Prevention**: Uses an internal `QTimer` that is explicitly cancelled upon stop, preventing videos from starting in the background after a user has closed a project.
31+
* **Visual Clearing**: Forces the `QVideoWidget` to repaint/update on stop, ensuring no "stuck frames" remain visible.
3632

3733
* **`router.py`**
38-
* **Role**: The "Traffic Cop" of the application.
39-
* **Responsibilities**:
40-
* Handles the "Create Project" and "Load Project" flows.
41-
* Analyzes input JSON files (keys like `events`, `captions`, `labels`) to automatically detect the project mode.
42-
* Initializes the appropriate specific managers and switches the UI view.
43-
44-
45-
34+
* **Role**: The "Traffic Cop" of the application.
35+
* **Responsibilities**:
36+
* Handles the "Create Project" and "Load Project" flows.
37+
* Analyzes input JSON files (keys like `events`, `captions`, `labels`, `smart_labels`) to automatically detect the project mode.
38+
* Initializes the appropriate specific managers and switches the UI view.
4639

4740
* **`history_manager.py`**
48-
* **Role**: The "Time Machine" (Undo/Redo System).
49-
* **Responsibilities**:
50-
* Implements the **Command Pattern** to manage the Undo/Redo stacks in `AppStateModel`.
51-
* Executes operations and triggers the necessary UI refreshes (`_refresh_active_view`) for all four modes.
52-
53-
54-
41+
* **Role**: The "Time Machine" (Undo/Redo System).
42+
* **Responsibilities**:
43+
* Implements the **Command Pattern** to manage the Undo/Redo stacks in `AppStateModel`.
44+
* **[NEW] AI Batch Support**: Handles complex state reversions for massive batch smart annotations across multiple videos simultaneously.
45+
* Executes operations and triggers the necessary UI refreshes (`_refresh_active_view`) for all four modes.
5546

47+
---
5648

5749
### 2. Classification Controllers (`controllers/classification/`)
5850

59-
Logic dedicated to the **Whole-Video Classification** task (assigning attributes to an entire video clip).
51+
Logic dedicated to the **Whole-Video Classification** task, now supercharged with AI workflows.
6052

61-
* **`class_file_manager.py`**: Handles JSON I/O and relative path calculations.
62-
* **`navigation_manager.py`**: Manages the "Action List" (Left Panel), auto-play logic, and filtering.
63-
* **`annotation_manager.py`**: Manages dynamic schema logic (Radio/Checkbox generation) and saves class selections.
53+
* **`inference_manager.py` [NEW]**: Orchestrates AI predictions via `soccernetpro`. Dynamically parses `config.yaml`, handles background threading (`QThread`), and manages both Single and Batch video inference without freezing the UI.
54+
* **`train_manager.py` [NEW]**: Manages the background training loop. Injects user-defined UI hyperparameters into a runtime config, runs `myModel.train()`, and intercepts PyTorch logs to drive the UI progress bar and console.
55+
* **`class_file_manager.py`**: Handles JSON I/O, relative path calculations, and the seamless preservation of `smart_labels` and confidence scores.
56+
* **`class_navigation_manager.py`**: Manages the dataset tree, playback synchronization, and advanced 4-state AI visibility filtering (All / Hand Labelled / Smart Labelled / No Labelled).
57+
* **`class_annotation_manager.py`**: Manages dynamic schema logic, saves manual class selections, and handles the confirmation workflow for AI-generated batch predictions.
6458

65-
### 3. Localization Controllers (`controllers/localization/`)
59+
---
6660

67-
Logic dedicated to the **Action Spotting** task (pinpointing specific timestamps).
61+
### 3. Localization Controllers (`controllers/localization/`)
6862

69-
* **`loc_file_manager.py`**: Handles JSON I/O with path fallback logic (checking local directories if absolute paths fail).
70-
* **`localization_manager.py`**:
71-
* Synchronizes the **Video Player**, **Timeline Widget**, and **Event Table**.
72-
* Captures timestamps for spotting events and manages the multi-tab interface.
63+
Logic dedicated to the **Action Spotting** task, utilizing temporal AI models.
7364

65+
* **`loc_inference.py` [NEW]**: Runs the heavy OpenSportsLib AI localization models in the background. Features dynamic FFmpeg sub-clipping to speed up targeted inference, automatic CPU fallback configuration, and absolute timestamp compensation.
66+
* **`loc_file_manager.py`**: Handles JSON I/O with path fallback logic (checking local directories if absolute paths fail) and preserves `smart_localization_events` during export.
67+
* **`localization_manager.py`**:
68+
* Synchronizes the Video Player, Timeline Widget, and Event Table.
69+
* **[NEW] Smart Spotting Flow**: Manages the dual-state UI of unconfirmed AI predictions (Gold markers) vs. confirmed/manual events (Blue markers), including batch confirmations.
7470

71+
---
7572

76-
### 4. Description Controllers (`controllers/description/`) [NEW]
73+
### 4. Description Controllers (`controllers/description/`)
7774

7875
Logic dedicated to the **Global Captioning** task (one text description per video action).
7976

8077
* **`desc_navigation_manager.py`**:
81-
* Manages **Multi-Clip Actions** (navigating logical "Actions" that may contain multiple video files).
82-
* Wraps the `MediaController` to ensure smooth loading of large video files.
83-
84-
78+
* Manages **Multi-Clip Actions** (navigating logical "Actions" that may contain multiple video files).
79+
* Wraps the `MediaController` to ensure smooth loading of large video files.
8580
* **`desc_annotation_manager.py`**:
86-
* Handles **Q&A Formatting**: Parses JSON "questions" into a readable Q&A format in the editor.
87-
* **Flattening**: Consolidates text into a single description block upon save.
88-
89-
81+
* Handles **Q&A Formatting**: Parses JSON "questions" into a readable Q&A format in the editor.
82+
* **Flattening**: Consolidates text into a single description block upon save.
9083
* **`desc_file_manager.py`**:
91-
* Manages JSON I/O specific to the captioning schema, ensuring `inputs` and `captions` fields are preserved correctly.
92-
84+
* Manages JSON I/O specific to the captioning schema, ensuring `inputs` and `captions` fields are preserved correctly.
9385

86+
---
9487

95-
### 5. Dense Description Controllers (`controllers/dense_description/`) [NEW]
88+
### 5. Dense Description Controllers (`controllers/dense_description/`)
9689

9790
Logic dedicated to the **Dense Captioning** task (text descriptions anchored to specific timestamps).
9891

9992
* **`dense_manager.py`**:
100-
* **Editor-Timeline Sync**: Continuously synchronizes the text input field with the video playback position. If the video hits an event, the text loads automatically.
101-
* **CRUD**: Handles creating, updating, and deleting timestamped text events.
102-
103-
93+
* **Editor-Timeline Sync**: Continuously synchronizes the text input field with the video playback position. If the video hits an event, the text loads automatically.
94+
* **CRUD**: Handles creating, updating, and deleting timestamped text events.
10495
* **`dense_file_manager.py`**:
105-
* **Metadata Preservation**: Ensures global and item-level metadata is retained during Load/Save cycles.
106-
* **Data Mapping**: Maps the flat `dense_captions` JSON list to the internal application model.
96+
* **Metadata Preservation**: Ensures global and item-level metadata is retained during Load/Save cycles.
97+
* **Data Mapping**: Maps the flat `dense_captions` JSON list to the internal application model.

0 commit comments

Comments
 (0)