# Azaion UI Design

## Responsive Breakpoints

| Device | Min Width | Viewport | Aspect Ratio |
|--------|-----------|----------|--------------|
| Mobile | 640px | 390px | 32:20 |
| Tablet/PC | 1280px | 780px / 1280×800 | 16:10 |
| Mini Laptop | 1280px+ | 1280px | Responsive |

## Pages

| Page | Wireframe |
|------|-----------|
| Login | *(no wireframe — see Login Page Layout below)* |
| Flights | [flights.html](./flights.html) (includes GPS-Denied panel via toggle) |
| Annotations | [annotations.html](./annotations.html) |
| Dataset Explorer | [dataset_explorer.html](./dataset_explorer.html) |
| Admin | [admin.html](./admin.html) |
| Settings | [settings.html](./settings.html) |

## Global Header

All pages share a common header:

```
[AZAION Logo] [Flight Selector ▼] | Flights | Annotations | Dataset | Admin | [User] [Settings] [Logout]
```

### Flight Selector

The flight selector is a dropdown in the header. Clicking the selector opens a dropdown panel containing:

- Text filter input (search by flight name)
- Scrollable list of flights showing: flight name, created date
- Clicking a flight selects it and closes the dropdown

The selected flight is the **global context** for the application. When a flight is selected:

- **Annotations tab**: media list filters by `GET /media?flightId=<selectedFlightId>`
- **Dataset Explorer**: flight filter pre-selects the current flight
- **Flights tab**: the selected flight is highlighted in the flight list sidebar

The selector persists the selected flight in `UserSettings` (see [Database Schema](../00_database_schema.md)). On app load, the last selected flight is restored.

## Mobile Bottom Navigation

On mobile devices, a bottom navigation bar replaces the header tabs:

```
[ FL ] [ ANN ] [ DATA ] [ ADM ] [ ⚙ ]
```

## Flights Page Layout

Flights and GPS-Denied share a single page. The left panel toggles between Flight Parameters and GPS-Denied mode via a toggle button.

### Flight List Sidebar (far left, ~200px)
- List of flights (e.g. FL01, FL02, FL03) with created date
- "Create New" button
- Telemetry section with DatePicker

### Left Panel (~260px, toggleable)

**Flight Parameters mode** (default):
- Aircraft selector (dropdown)
- Default Height (input)
- Camera settings: FocalLength (mm), SensorWidth (mm), Altitude (m)
- Communication Address / Port
- Waypoints list: Start, Point1, Point2... (with labels), Finish
- **GPS-Denied toggle** button: switches this panel to GPS-Denied mode
- Upload action

**GPS-Denied mode** (toggled):
- **Orthophoto Upload**: List of uploaded photos with name and GPS coordinates, upload button
- **Live GPS**: Real-time GPS data via SSE (status, lat, lon, satellites)
- **GPS Correction**: Waypoint number input, corrected GPS input, apply button
- **Back to Flight** button: returns to Flight Parameters mode

### Map View (right, ~800px)
Interactive map displaying waypoints connected by the flight path.

In GPS-Denied mode, the map additionally shows:
- Original flight path (red dashed line)
- Corrected path (green solid line) overlay
- Waypoint markers with correction indicators

## Login Page Layout

Displayed before authentication. No header navigation — only the login form.

### Login Form (centered, ~400px wide)
- Email input
- Password input
- "Login" button
- Status / error message area

### Unlock Progress States

After successful login, the UI shows a progress screen while the binary-split unlock flow completes:

```
Authenticating → Downloading key → Decrypting → Starting services → Ready
```

Each state is displayed with a spinner or progress indicator. On **Ready**, the UI navigates to the main application.

---

## Annotations Tab Layout

All panels are separated by draggable splitters. Panel widths persist across sessions via `UserSettings` table.

### Left Panel (~250px)

#### Media List
- List of media files (photos, videos) for the selected flight
- Columns: File name, Duration (for videos)
- Files with existing annotations are highlighted (darker background)
- Clicking a media item loads it in the viewer; double-click starts playback
- Text filter input above the list to search by file name
- Context menu: "Delete media" (with confirmation dialog)
- Media files are loaded from the backend via `GET /media?flightId=`. The media sidebar shows files associated with the selected flight via the Media API.

#### Detection Classes (below media list)
- DataGrid with columns: Key (color + number), Name
- PhotoMode switcher at bottom: Regular (0) | Winter (20) | Night (40)
- Selecting a class sets the active drawing class; `yoloId = classId + photoModeOffset`
- Keyboard: press `1–9` to select class by number
- Captions hidden when panel width < 230px

### Main Viewer (center)

#### Canvas Editor
Interactive annotation drawing tool overlaid on the image/video frame:
- **Draw**: click-and-drag to create a bounding box
- **Resize**: 8 directional handles on selected box
- **Move**: drag a selected box to reposition
- **Multi-select**: Ctrl+click to select multiple boxes
- **Zoom**: Ctrl+mouse wheel to zoom in/out
- **Pan**: Ctrl+drag to pan when zoomed
- **Crosshair**: cursor shows crosshair with active class name hint
- All coordinates are clamped to image bounds (normalized 0.0–1.0)
- **Tile zoom**: when opening a tile-based detection result (from large image split processing), the editor automatically zooms and centers on the specific tile region within the full image

#### Bounding Box Labels
Each bounding box displays:
- Affiliation icon (see [Affiliation Icons](#affiliation-icons) below)
- Combat readiness indicator (see [Combat Readiness](#combat-readiness) below)
- Detection class name
- Confidence percentage (shown only when < 99.5%)

#### Video Controls
- Progress bar (click/drag to seek)
- Toolbar buttons: Play, Pause, Stop, Previous frame, Next frame, Save, Delete selected, Delete all, Mute/Unmute, Volume slider
- Frame-by-frame step buttons: 1, 5, 10, 30, 60 frames — these jump the exact number of frames forward (not time-based). The web video player must support frame-accurate seeking. Frame duration = 1 / video FPS.
- AI Detect button — triggers AI detection on the current frame/media
- GPS panel toggle — shows/hides the MapMatcher panel below the viewer
- Sound detections button (placeholder for future audio analysis)
- Drone maintenance button (placeholder for future UAV diagnostics)
- Status bar: current time / total time, help text, status messages

#### Video Annotation Time-Window Display

During video playback, annotations are displayed on the canvas based on their `Time` (video playback position). An annotation is visible when the current playback position falls within a time window around its `Time`:

| Threshold | Value | Description |
|-----------|-------|-------------|
| Before | 50 ms | Show annotation this much before its `Time` |
| After | 150 ms | Keep annotation visible this long after its `Time` |

The UI maintains an interval lookup (e.g. interval tree) keyed by `[Time - 50ms, Time + 150ms]` for each annotation. On each position update from the video player, the UI queries for all overlapping intervals and renders those annotations on the canvas. Annotations outside the window are cleared.

#### AI Detection Progress
When AI detection is triggered, a modal dialog appears showing:
- Scrolling log of detection progress
- Stop button (Esc to dismiss)
- Detection results are streamed via SSE (`DetectionEvent`)

#### Camera Config (per-session)
Camera settings are adjustable per annotation session. They are displayed when the user opens the current flight's settings panel (accessed from the Flight Parameters panel on the Flights tab). These override the global defaults for GSD-based detection size validation.
- Altitude: slider (0–10000 m) + numeric input (50–5000, step 10)
- FocalLength: numeric input (0.1–100 mm, step 0.05)
- SensorWidth: numeric input (0.1–100 mm, step 0.05)

See [Annotations — Camera Settings](../01_annotations.md#camera-settings-per-session) for API endpoints.

### Annotations List (right sidebar, ~200px)
- DataGrid with columns: Frame time (e.g. "00:12"), Class name
- Rows are colored with a gradient matching the detection class colors (see [Annotation Row Gradient](#annotation-row-gradient) below)
- Double-click a row to seek the video to that frame and zoom to the annotation
- Multi-select with Ctrl for bulk delete
- Selecting a row highlights the corresponding bounding box on the canvas

### Help System
- Menu: Help > "How to annotate" opens a help window (see [Annotation Quality Guidelines](#annotation-quality-guidelines) below)
- Step-by-step guidance in the status bar: Initial → Play Video → Pause for Annotations → Annotation Help

---

## Dataset Explorer Layout

### Left Panel (~250px)

#### Detection Classes
- Same DetectionClasses control as the Annotations tab (class list + PhotoMode switcher)
- Selecting a class filters the grid to show only annotations of that class

#### Filters
- "Show with objects only" checkbox — hides annotations with no detections
- Text search input — search by annotation name (throttled, 400ms debounce)

### Filter Bar (top of main area)
- Date range picker (from / to)
- Flight filter dropdown
- Status filter buttons: None, Created, Edited, Validated

### Main Area (tabbed)

#### Annotations Tab (default)
- Virtualized grid of annotation thumbnail tiles (responsive, min 180px per tile)
- Each tile shows: thumbnail image, annotation name, created date + creator email
- Seed annotations are highlighted with a red border (`IsSeed` flag)
- Double-click a tile to open it in the Editor tab
- Multi-select for bulk validation
- Keyboard: Del (delete), Enter (save), V (validate), Up/Down/PageUp/PageDown (navigate)

#### Editor Tab (hidden until opened)
- Full Canvas Editor (same as Annotations tab) for inline annotation editing
- Esc to close and return to grid
- Keyboard: 1–9 (class select), Enter (save), Del (delete selected), X (delete all)

#### Class Distribution Tab
- Horizontal bar chart showing annotation count per detection class
- Each bar is colored with the class color
- Displays: colored bar, class label, count

### Status Bar (bottom)
- Validate button (visible when annotations are selected) — bulk-validates selected annotations
- Refresh thumbnails button — regenerates the thumbnail database with progress bar
- Selected annotation name
- Status text

---

## Admin Tab Layout

### Detection Classes Table (left, ~340px)
- Numbered rows (0–16) with columns: #, Name, Icon, Delete
- Sample classes: Military Vehicle, Truck, Car, Artillery, Active Mine

### AI Recognition Settings (center)
- #Frames To Recognize (default: 4)
- Min Seconds Between Recognition (default: 2)
- Min Confidence Threshold % (default: 25)

### GPS Device Settings (center, below AI)
- Device Address, Port, Protocol

### Default Aircrafts Sidebar (right, ~280px)
- List of default aircraft with type indicator (P=Plane, C=Copter)
- Star icon for default selection

### User Management (separate section / sub-page)
User CRUD is hosted on the remote Admin API. In the React UI, this is a sub-section of the Admin tab or a separate page accessible from the Admin area. Full details are in a separate repository; the initial implementation provides basic user list and create/edit/deactivate functionality. See [Authentication — User Management](../10_auth.md#user-management-admin-only) for endpoints.

- User table: Name, Email, Role, Status (Active/Inactive)
- Create user form: Name, Email, Password, Role selector
- Edit user: inline edit or modal
- Deactivate user (soft delete — sets Status to Inactive)

---

## Settings Tab Layout

### Tenant Configuration (left column, ~300px)
- Military Unit
- Name
- Default Camera Width (px)
- Default Camera FoV (°)

### Directories (center column, ~300px)
- Images Dir
- Labels Dir
- Thumbnails Dir

### Aircrafts Table (right)
- Columns: Model, Type (Plane/Copter), Default toggle

---

## Resizable Panels

All multi-panel layouts (Annotations, Dataset Explorer) use draggable splitters between columns. Users can resize panels by dragging the splitter. Panel widths are saved to the `UserSettings` table in the database and restored on next session. Each user has their own stored layout preferences.

---

## Confirmation Dialogs

Destructive actions require a confirmation dialog before execution:

| Action | Dialog message |
|--------|---------------|
| Delete media file | "Delete this media file?" |
| Delete selected annotations | "Delete selected annotations?" |
| Delete all annotations | "Delete all annotations for this frame?" |
| Deactivate user | "Deactivate this user?" |

Dialogs use a standard modal with Cancel / Confirm buttons. Cancel is the default focused button.

---

## Annotation Quality Guidelines

The help window (accessible from Help > "How to annotate") contains the following annotation quality rules:

1. Annotations must contain objects of the best clarity and quality. Heavily blurred or smoke-obscured objects are not suitable.
2. The more angles of the same object the better. If the video shows an object small at first and then the camera zooms in, both the small and large views should be annotated. If an object is static and the angle doesn't change, one annotation is enough; if it moves and is visible from different sides, annotate once per angle.
3. Objects with shapes that significantly differ from a rectangle: do not include protruding parts (e.g. a tank's barrel) if it adds too much empty space to the bounding box. Similarly for trenches — if they span a large area, create several smaller annotations of the trench segments rather than one large box with too much background.
4. Any existing marks on the video (OSD overlays, HUD elements, etc.) must not be inside annotations. An annotation must contain only the specific object without lines or overlays on it.
5. Each video should have 2–3 empty frames saved without any objects or annotations, for better training (negative samples). Simply press Enter on a few different frames with nothing in them.
6. Objects of the same class must be visually similar, while objects of different classes must be visually distinct. Since this is a dataset for neural network training (not a military equipment catalog), class assignment should follow visual similarity for better recognition. For example, self-propelled artillery on tracks should be annotated as "Armored Vehicle" because it visually resembles a tank more than a mortar.

---

## Affiliation Icons

Bounding box labels display an affiliation icon using NATO MIL-STD-2525-style shapes:

| Affiliation | Shape | Color | Description |
|-------------|-------|-------|-------------|
| Friendly | Rectangle | Light blue (#87CEEB) | Blue filled rectangle with dark outline |
| Hostile | Diamond | Red (#FF0000) | Red filled diamond (rotated square) with dark outline |
| Unknown | Quatrefoil | Yellow (#FFD700) | Yellow filled four-lobed clover shape with dark outline |
| None | *(no icon)* | — | No affiliation icon displayed |

The React UI renders these as inline SVGs next to the class label inside each bounding box overlay.

---

## Combat Readiness

Bounding box labels display a combat readiness indicator alongside the affiliation icon:

| Value | Indicator | Description |
|-------|-----------|-------------|
| Ready | Green dot | Target is combat-ready |
| NotReady | Gray dot | Target is not combat-ready |
| Unknown | *(no indicator)* | Readiness not assessed |

The indicator is rendered as a small circle next to the affiliation icon inside the bounding box overlay.

---

## Annotation Row Gradient

In the Annotations list (right sidebar), each row's background is a horizontal linear gradient composed of the colors of all detections in that annotation:

- Each detection contributes a gradient stop using its class color
- The color opacity is modulated by the detection's confidence (higher confidence = more opaque)
- If no detections exist, the row has a subtle light gray background (`#40DDDDDD`)
- The gradient runs left-to-right, with equal-width stops per detection

This provides a quick visual summary of what classes are present in each annotation and how confident the detections are.

---

## Keyboard Shortcuts

### Annotations Tab

| Key | Action |
|-----|--------|
| `1–9` / `NumPad1–9` | Select detection class |
| `Space` | Pause / resume playback |
| `Left` | Previous frame |
| `Right` | Next frame |
| `Ctrl+Left` | Skip 5 seconds back |
| `Ctrl+Right` | Skip 5 seconds forward |
| `Enter` | Save annotations and continue |
| `Del` | Delete selected annotations |
| `X` | Delete all annotations |
| `R` | Trigger AI detection |
| `M` | Mute / unmute |
| `VolumeUp` / `VolumeDown` | Volume +/- 5 |
| `PageUp` / `PageDown` | Previous / next media file |

### Dataset Explorer

| Key | Action |
|-----|--------|
| `1–9` | Select detection class |
| `Enter` | Save annotations |
| `Del` | Delete selected annotations |
| `X` | Delete all annotations |
| `Esc` | Close editor, return to grid |
| `Up` / `Down` | Navigate thumbnails |
| `PageUp` / `PageDown` | Page navigation |
| `V` | Validate selected annotations |

---

## Localization

The UI supports Ukrainian (UA) and English (EN) localization. Language is selectable per user session.

Detection class names use Ukrainian display names from the seed data alongside the English `Name`. See [Admin — Default Seed Classes](../07_admin.md#default-seed-classes).

---

## Color Scheme

- Primary: Dark navy/blue (#343a40)
- Secondary: Orange/amber accents (#fd7e14)
- Background: Dark gray (#1e1e1e)
- Text: White/light gray (#ffffff, #adb5bd)
- Success: Green (#40c057)
- Primary buttons: Blue (#228be6)
- Danger: Red (#fa5252)
