ui/_docs/ui_design/README.md

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 (includes GPS-Denied panel via toggle)
Annotations	annotations.html
Dataset Explorer	dataset_explorer.html
Admin	admin.html
Settings	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). 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 below)
• Combat readiness indicator (see 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 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 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 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 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.

---

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)