Skip to content

Commit bf5de82

Browse files
woshimajintaowoshimajintao
authored
Update README.md of UI
1 parent 0fcd465 commit bf5de82

1 file changed

Lines changed: 55 additions & 46 deletions

File tree

‎annotation_tool/ui/README.md‎

Lines changed: 55 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,25 @@
1-
# User Interface (UI) Module
1+
# 🎨 User Interface (UI) Module
22

3-
This directory contains the **View layer** of the application's MVC architecture. It is responsible solely for the graphical presentation and user interaction components.
3+
This directory contains the **View layer** of the application's MVC architecture. It is responsible solely for graphical presentation and user interaction.
44

5-
**Note:** No business logic or data manipulation is performed here. All user interactions (clicks, edits) are emitted as Qt Signals to be handled by the `controllers` module.
5+
**Note:** No business logic or data manipulation is performed here. All user interactions (clicks, edits, playback controls) are emitted as **Qt Signals** to be handled by the `controllers` module.
66

77
## 📂 Directory Structure
88

9-
The UI is organized by functional domain rather than spatial position:
9+
The UI is organized by functional domain, with a robust **Common** library supporting four distinct annotation modes:
1010

1111
```text
1212
ui/
13-
├── common/ # Reusable widgets and dialogs shared across different tasks
14-
│ ├── dialogs.py
15-
│ └── project_controls.py
16-
├── classification/ # UI components specific to the Classification task
17-
└── localization/ # UI components specific to the Localization task
13+
├── common/ # Shared architecture (Main Window, Workspace Skeleton, Dialogs)
14+
│ ├── main_window.py # Top-level Stacked Layout orchestrator
15+
│ ├── workspace.py # Unified 3-column layout skeleton
16+
│ ├── video_surface.py # Shared video rendering widget
17+
│ └── ...
18+
│
19+
├── classification/ # [Mode 1] Whole-Video Classification
20+
├── localization/ # [Mode 2] Action Spotting (Timestamps)
21+
├── description/ # [Mode 3] Global Description (Captions)
22+
└── dense_description/ # [Mode 4] Dense Description (Timestamped Text)
1823
1924
```
2025

@@ -24,66 +29,70 @@ ui/
2429

2530
### 1. Common (`ui/common/`)
2631

27-
Contains widgets and windows that are standardized and used across multiple modes to ensure a consistent user experience.
32+
The backbone of the application, ensuring a consistent user experience across all modes.
2833

29-
* **`dialogs.py`**: Contains modal dialog windows used throughout the application lifecycle:
30-
* `ProjectTypeDialog`: Forces the user to choose between Classification and Localization modes.
31-
* `CreateProjectDialog`: A wizard for setting up new tasks and defining the initial Label Schema.
32-
* `FolderPickerDialog`: A custom file tree that allows selecting multiple folders without holding the Ctrl key.
34+
* **`main_window.py`**: The application entry point. It manages a `QStackedLayout` to switch between the **Welcome Screen** and the four **Workspaces** without destroying state.
35+
* **`workspace.py`**: Defines the `UnifiedTaskPanel`. This is the generic 3-column skeleton (Left Tree | Center Player | Right Editor) used by **every** mode to maintain layout consistency.
36+
* **`video_surface.py`**: A pure rendering widget wrapping `QMediaPlayer` and `QVideoWidget`. It handles video output while leaving playback logic to the controllers.
37+
* **`clip_explorer.py`**: The **Left Sidebar**. Refactored to use **Qt Model/View** (`QTreeView`) for high performance. It handles file navigation and filtering (e.g., "Show Labelled Only").
38+
* **`dialogs.py`**:
39+
* `ProjectTypeDialog`: Updated wizard allowing selection of **Classification**, **Localization**, **Description**, or **Dense Description**.
40+
* `FolderPickerDialog`: A custom file tree allowing multi-folder selection.
3341

3442

35-
* **`project_controls.py`**:
36-
* Defines the **Unified 3x2 Control Grid** (New, Load, Add Data, Close, Save, Export).
37-
* Contains the **Unified Clip Explorer**, providing a consistent video list and filter interface for both modes.
3843

44+
### 2. Classification (`ui/classification/`)
3945

46+
Implements the interface for **Whole-Video Classification** (assigning categories to an entire clip).
4047

41-
### 2. Classification (`ui/classification/`)
48+
* **`media_player/`**: Standard player with basic seek controls.
49+
* **`event_editor/`**: Dynamic form generation (Radio buttons/Checkboxes) based on the project Schema.
4250

43-
Implements the interface for **Whole-Video Classification** (assigning global labels to an entire video clip).
51+
### 3. Localization (`ui/localization/`)
4452

45-
* **`panels.py`**: Defines the high-level layout:
46-
* `LeftPanel`: Navigation tree and Project Controls.
47-
* `CenterPanel`: Video player and basic navigation controls.
48-
* `RightPanel`: Dynamic form generation based on the project Schema.
53+
Implements the interface for **Action Spotting** (identifying specific timestamps).
4954

55+
* **`media_player/`**:
56+
* Features the **Zoomable Timeline**, visual event markers, and frame-stepping tools.
5057

51-
* **`widgets.py`**: Contains specialized input widgets:
52-
* `DynamicSingleLabelGroup`: Generates Radio Buttons for single-choice categories.
53-
* `DynamicMultiLabelGroup`: Generates Checkboxes for multi-choice categories.
54-
* `VideoViewAndControl`: A wrapper for the video player and slider.
5558

59+
* **`event_editor/`**:
60+
* **Spotting Tabs:** Rapid-fire buttons for defining event categories.
61+
* **Annotation Table:** A spreadsheet view for editing timestamps and labels.
5662

5763

58-
### 3. Localization (`ui/localization/`)
5964

60-
Implements the interface for **Action Spotting** (identifying specific timestamps within a video).
65+
### 4. Description (`ui/description/`) [NEW]
6166

62-
* **`panels.py`**: The layout container that assembles the following functional widgets.
63-
* **`clip_explorer.py`**:
64-
* Displays the list of video clips (Sequences) using the shared explorer logic.
65-
* Handles filtering (Done/Not Done) and visual status indicators.
67+
Implements the interface for **Global Captioning** (one text description per video).
6668

69+
* **`media_player/`**:
70+
* **Composite Player:** Combines the video surface with a specialized navigation toolbar.
71+
* **Behavior:** Defaults to **Infinite Loop** to allow repeated viewing while typing.
6772

68-
* **`media_player.py`**:
69-
* Contains the `MediaPreviewWidget`.
70-
* Features a custom, zoomable **Timeline** with visual event markers.
71-
* Includes frame-stepping and speed control playback tools.
7273

74+
* **`event_editor/`**:
75+
* **Text Input:** A large `QTextEdit` for free-form text.
76+
* **Actions:** Simple "Confirm" and "Clear" workflow.
7377

74-
* **`event_editor.py`**:
75-
* `Spotting Tabs`: A multi-tab interface for defining different event categories (Heads).
76-
* `Annotation Table`: A spreadsheet-like view for editing event timestamps and labels.
7778

7879

80+
### 5. Dense Description (`ui/dense_description/`) [NEW]
7981

80-
---
82+
Implements the interface for **Dense Captioning** (text descriptions anchored to specific timestamps).
8183

82-
## 🎨 Design Principles
84+
* **`event_editor/`**:
85+
* **Input Widget:** A specialized panel showing the current video time alongside a text input area.
86+
* **Dense Table:** A subclass of the Localization table. It replaces the "Label" column with a "Description" column and auto-sizes to a **2:1:4 ratio** (Time : Lang : Text).
8387

84-
1. **Passive View**: These classes do not modify the `model` directly. They only display data provided by the controller and emit signals when the user acts.
85-
2. **Dynamic Generation**: The annotation forms (buttons/checkboxes) are not hardcoded; they are generated dynamically based on the loaded JSON schema.
86-
3. **Functional Naming**: Files are named after what they *do* (e.g., `media_player.py`), not where they are located (e.g., `center_widgets.py`), allowing for flexible layout changes in the future.
8788

89+
* **Reuse:** This mode reuses the **Localization Center Panel** (Timeline + Player) to allow precise navigation between text events.
8890

89-
```
91+
---
92+
93+
## 🎨 Design Principles
94+
95+
1. **Passive View:** These classes do not modify data directly. They display data provided by the controller and emit signals (e.g., `confirm_clicked`, `request_remove_item`) when the user acts.
96+
2. **Unified Skeleton:** All modes inherit the same `UnifiedTaskPanel` structure. This ensures that the Sidebar and Media Player always appear in the same relative locations, reducing cognitive load for the user.
97+
3. **Composite Design:** Complex widgets (like the Description Player) are built by composing smaller, single-purpose widgets (VideoSurface + Controls + Slider) rather than monolithic classes.
98+
4. **Dynamic Generation:** Where possible, forms and tables adjust their content dynamically based on the loaded JSON schema or data model.

0 commit comments

Comments
 (0)