@ -7,16 +7,18 @@ High-precision, browser-based tool for visualizing radar point cloud data, objec
This project is a modular ES6 JavaScript application refactored from a monolithic codebase. It provides a sophisticated interface for multi-sensor data playback and analysis.
### Core Technologies
- **Rendering**: [p5.js](https://p5js.org/) for main radar and speed graph visualizations.
- **Rendering**: [p5.js](https://p5js.org/) for main radar, speed graph, and "GOD MODE" visualizations. Hardened with Triple-Buffer protection.
- **Parsing**: Web Workers using [Clarinet.js](https://github.com/dscape/clarinet) for non-blocking, streaming JSON parsing of large datasets.
- **Storage**: IndexedDB for persistent caching of radar and video files to avoid repeated uploads.
- **Styling**: Tailwind CSS for a responsive, modern UI.
- **Data Exploration**: [AG Grid](https://www.ag-grid.com/) and [Chart.js](https://www.chartjs.org/) for detailed data inspection.
- **Storage**: **IndexedDB** for persistent file caching; **localStorage** for user workspace state and layout persistence.
- **Layout Engine**: [GridStack.js](https://gridstackjs.com/) for the modular, resizable dashboard interface.
- **Styling**: Tailwind CSS for a premium, dark-mode-first UI.
- **Data Exploration**: [AG Grid](https://www.ag-grid.com/) and [Chart.js](https://www.chartjs.org/) for forensic data inspection.
### Architecture
- **State Management**: Centralized in `src/state.js` via the `appState` object.
- **Synchronization**: `src/sync.js` uses a high-resolution master clock (`performance.now()`) to align radar frames with video playback, correcting for drift and user-defined offsets.
- **Modular Design**: Separated into functional modules for DOM references, file parsing, drawing utilities, keyboard handling, and UI components.
- **Synchronization**: `src/sync.js` uses high-resolution `performance.now()` to perfectly align radar frames with video playback.
- **Workspace Engine**: `src/ui.js` manages a Hybrid Dashboard (GridStack + Standalone Floating Windows) with auto-focus and viewport rescue logic.
- **Modular Design**: Functional decomposition into specialized modules for Sync, Data, UI, and Visualizations.
## Building and Running
@ -37,12 +39,14 @@ Since this is a static project using ES6 modules directly in the browser:
## Key Directories and Files
- `src/`: Main source code directory.
- `p5/`: p5.js sketches for Radar, Speed Graph, and Zoom ("GOD MODE").
- `p5/`: p5.js sketches for Radar, Speed Graph, and Standalone "GOD MODE" Zoom.
- `ui.js`: Unified UI/Workspace engine with layout memory.
This is a high-precision, browser-based tool for visualizing radar point cloud data, object tracks, and CAN bus speed data, synchronized with a corresponding video file. Originally a monolithic HTML application (V14_inliner_Stationary.html), it has been refactored into a modern, modular JavaScript application using ES6 Modules. This structure enhances maintainability, performance (especially with large datasets), and extensibility.
This is a high-precision, browser-based tool for visualizing radar point cloud data, object tracks, and CAN bus speed data, synchronized with a corresponding video file. Originally a monolithic HTML application, it has been refactored into a modern, modular JavaScript application using ES6 Modules.
The application leverages p5.js for rendering visualizations, a Web Worker with the Clarinet.js streaming parser for efficient background JSON processing, IndexedDB for persistent file caching, Tailwind CSS for styling, and introduces a Data Explorer panel using AG Grid and Chart.js for in-depth data inspection.
The application leverages **p5.js** for rendering, **Web Workers** for background streaming JSON parsing, **IndexedDB** for persistent file caching, and **Tailwind CSS** for a professional, responsive UI.
Core Features Detailed
---
Synchronized Playback (sync.js):
## โ๏ธ Core Architecture
Utilizes performance.now() for a high-resolution master clock, independent of potentially imprecise video events.
### `sync.js` (Synchronized Playback)
- **Master Clock**: Utilizes `performance.now()` for a high-resolution timer independent of imprecise video events.
- **Dynamic Mapping**: Maps the target media time (adjusted by user offsets) to the corresponding radar frame via binary search (`utils.js::findRadarFrameIndexForTime`).
- **Drift Correction**: Periodically checks for sync drift (>150ms) and forces video seeks to maintain frame-perfect alignment.
Calculates the target media time based on playback speed (speedSlider.value) and elapsed real time.
### `fileLoader.js` (Unified File Loading)
- **Multi-Input**: Supports both button-based selection and global Drag & Drop.
- **Pipeline Processing**: Identifies file types and triggers the appropriate caching and parsing workers.
- **Auto-Offset**: Automatically calculates time offsets based on standardized filenames (e.g., `fHist_...json` and `WIN_...mp4`).
Maps the target media time (adjusted by the user-defined offsetInput.value) to the corresponding radar frame timestamp (timestampMs).
### `parser.worker.js` (Streaming JSON Parser)
- **Off-Thread Processing**: Uses a Web Worker to keep the UI responsive during large file loads.
- **Streaming Logic**: Utilizes the `Clarinet.js` event-driven parser to reconstruct large datasets in memory without blocking the main thread.
- **Progress Reporting**: Sends real-time percentage updates back to the UI.
Uses a binary search (utils.js::findRadarFrameIndexForTime) to efficiently find the correct radar frame index for the calculated timestamp.
---
Periodically checks for drift (>150ms) between the master clock's calculated time and videoPlayer.currentTime, forcing a video seek if needed to maintain sync.
## ๐จ Visualizations (p5.js)
Unified File Loading (fileLoader.js):
### `radarSketch.js` (Primary Radar Canvas)
- **Radar Rendering**: Draws point clouds, tracks, ego-vehicle representation, and cluster centroids.
- **Interactive Layers**: Manages toggleable overlays for SNR, TTC, predicted positions, and covariance ellipses.
- **Hardening**: Features **Triple-Buffer Protection** against 0-width crashes and a master timer for God Mode auto-visibility.
Handles loading JSON (radar data) and Video files through both button clicks (loadJsonBtn, loadVideoBtn) and drag-and-drop onto the main content area (<main>).
### `speedGraphSketch.js` (Telemetry Graph)
- **Time-Series Analysis**: Renders Ego Speed and CAN Speed lines synchronized with the video playback.
- **Visual Indicators**: Draws a vertical tracking line aligned with the current active frame.
The handleFiles function identifies file types (.json, video/*) and triggers the processFilePipeline.
### `zoomSketch.js` (Magnified "GOD MODE")
- **Standalone Window [NEW]**: A decoupled, floating overlay that provides high-fidelity zoom.
- **Auto-Hide UX [NEW]**: 8-second sequence (5s analysis period + 3s visual countdown) before fading.
- **Safety Indicators**: Includes "Out of Bounds" warnings and "Closing in..." countdown status labels.
Note: Dedicated CAN log loading (loadCanBtn, canFileInput) has been removed. CAN speed data (canVehSpeed_kmph) is now expected within the JSON structure, associated with each radarFrame.
- **Smart Focus**: Prevents shortcuts from firing when the user is typing in number or text inputs.
Clarinet.js (clarinet.min.js loaded locally via importScripts in the worker) parses the incoming JSON stream event-by-event (onopenobject, onkey, onvalue, etc.), reconstructing the full JavaScript object in memory off the main thread.
---
Progress updates (percent) are sent back to the main thread via postMessage.
On completion, the fully parsed object (data) is sent back.
The main thread receives the parsed data and passes it to fileParsers.js::parseVisualizationJson for post-processing (calculating relative timestampMs, determining global SNR range).
Interactive Visualization (p5/, drawUtils.js):
radarSketch.js: The primary p5 sketch.
Manages the main canvas within #canvas-container.
Calculates plot scales (plotScaleX, plotScaleY) based on canvas size and constants.js boundaries.
Draws axes, ego vehicle representation (drawUtils.js::drawEgoVehicle).
Draws dynamic elements: point clouds (drawUtils.js::drawPointCloud), tracks (drawUtils.js::drawTrajectories), track markers (drawUtils.js::drawTrackMarkers), predicted positions (now drawn for the current frame currentFrame, not currentFrame + 1), covariance ellipses (drawUtils.js::drawCovarianceEllipse), cluster centroids (drawUtils.js::drawClusterCentroids), and regions of interest (drawUtils.js::drawRegionsOfInterest).
Handles hover interactions for the Zoom Mode ("GOD MODE") tooltip via drawUtils.js::handleCloseUpDisplay.
Draws legends (SNR, Track TTC).
speedGraphSketch.js: The secondary p5 sketch for the speed graph.
Manages the canvas within #speed-graph-container.
Draws time-series lines for Ego Speed (frame.egoVelocity[1] * 3.6) and CAN Speed (frame.canVehSpeed_kmph) from the JSON vizData.
Draws axes and legends.
Draws a vertical red line indicator synchronized with the current frame's timestamp (frameData.timestampMs).
zoomSketch.js: p5 sketch for the magnified "GOD MODE" view.
Manages a separate canvas within #zoom-canvas-container.
Receives mouse coordinates and hovered items from radarSketch.js.
Redraws a scaled and translated portion of the main scene, providing a high-fidelity zoom.
Includes detailed tooltip drawing logic (drawZoomTooltip) showing extensive info for points, clusters, tracks (with speed), and predictions (with velocity).
Handles mouse wheel events for adjusting appState.zoomFactor.
drawUtils.js: Contains numerous helper functions responsible for the actual drawing logic (shapes, lines, colors, text) used by radarSketch.js and zoomSketch.js. Defines color palettes (snrColors, ttcColors, clusterColors). Refined tooltip data generation in handleCloseUpDisplay.
Data Explorer (dataExplorer.js, main.js, index.html):
A dedicated panel (#data-explorer-panel) for inspecting raw data of the current frame (appState.currentFrame).
Activated by pressing the <kbd>I</kbd> key or clicking on the main radar canvas (#canvas-container).
Features four views selectable via tabs:
Tree View (#tab-panel-tree): Displays the current frame's data structure as a formatted JSON string.
Grid View (#tab-panel-grid): Uses AG Grid (ag-grid-community.min.js) to display array data (e.g., pointCloud) in a sortable, filterable table. Populated via displayInGrid(data, title).
Track Grid View (#tab-panel-track-grid): Displays object tracking data for the current frame in a dedicated grid.
Plot View (#tab-panel-plot): Uses Chart.js (chart.js CDN) to generate a line plot of the numeric data from a column selected in the Grid View (by clicking the column header).
Panel Features: The Data Explorer panel is **draggable** (via the header) and **resizable** (via edges/corners).
Allows users to directly examine the underlying numerical values being visualized.
Checkboxes in the sidebar (#collapsible-menu) control boolean flags in appState (via main.js event listeners).
drawUtils.js functions read these flags (toggleSnrColor.checked, toggleConfirmedOnly.checked, etc.) to determine:
Which color palette/logic to apply to points and tracks.
Whether to show certain elements (tracks, velocity vectors, predicted positions, covariance).
SNR range inputs (snrMinInput, snrMaxInput) update appState.globalMinSnr/MaxSnr for color scaling.
TTC coloring mode (ttcModeDefault, ttcModeCustom) and custom inputs (ttcColorCritical, ttcTimeCritical, etc.) update appState.useCustomTtcScheme and appState.customTtcScheme respectively (dom.js event listeners). drawUtils.js::drawTrajectories uses this state to color tracks.
Standard buttons (playPauseBtn, stopBtn) modify appState.isPlaying and call videoPlayer.play/pause/currentTime.
timelineSlider input event updates appState.currentFrame and calls dom.js::updateFrame(frame, true) (forcing video seek). Throttled for performance during drag, debounced for final sync on release.
timelineSlider wheel event calculates scroll speed and dynamically seeks frames, also debounced for final sync (sync.js).
timelineSlider mousemove event calculates hover position to display frame/time in #timeline-tooltip (sync.js).
Sidebar (#collapsible-menu) visibility toggled by toggleMenuBtn, closeMenuBtn, and clicks on the #menu-scrim overlay (ui.js).
Fullscreen toggled via fullscreenBtn and monitored using the fullscreenchange event (ui.js).
Persistent overlays (#radar-info-overlay, #video-info-overlay) updated by dom.js::updatePersistentOverlays with frame index, absolute time, color mode, and sync drift.
Dark/Light theme managed by theme.js::setTheme, saving preference to localStorage, and triggering redraws in p5 sketches.
**Startup Guide, Shortcuts, & Changelog**:
* Includes a "First Run" experience with a loading screen and Quick Start Guide modal (ui.js).
* A "Shortcuts" modal (toggle with <kbd>K</kbd> or via the UI) provides a reference for all keyboard interactions (ui.js).
* A **Changelog** modal ("What's New?") provides a history of updates and refactors (ui.js).
Session Management (session.js, main.js, db.js):
Files are cached in IndexedDB using db.js::saveFileWithMetadata upon loading. Metadata (filename, size) is stored alongside the blob.
On DOMContentLoaded, main.js retrieves expected filenames from localStorage and attempts to load corresponding blobs using db.js::loadFreshFileFromDB. This function verifies filename and size match before returning the blob, ensuring cache validity.
saveSessionBtn (handled in session.js) gathers current state (appState filenames, offsetInput.value, toggle states) into a JSON object and triggers a browser download.
loadSessionBtn (handled in session.js) reads a chosen session JSON file. It verifies that the files mentioned in the session currently exist and are valid in IndexedDB using loadFreshFileFromDB before applying settings to localStorage and reloading the page.
Keyboard Shortcuts (keyboard.js):
A comprehensive keydown listener intercepts keys (Space, Arrows, 1-4, S, T, D, G, P, A, M, Q, R, C, I).
It programmatically triggers .click() events on corresponding buttons or directly updates appState/calls functions (like showExplorer/hideExplorer).
Note: <kbd>K</kbd> (Shortcuts) and <kbd>Esc</kbd> (Close Modals) are handled globally in `ui.js`.
Includes a check to prevent shortcuts firing when focus is on text/number inputs (offsetInput, snrMinInput, etc.).
How to Run Locally
(Instructions remain the same - requires Python 3 and running python -m http.server 8000 or the provided .bat script in the steps directory).
Check Python Installation: Run python_check.bat or python --version. Need Python 3.x in PATH.
Navigate to Project Directory: cd to the steps directory containing index.html.
Start Local Server: Run Visualization_Start.bat or python -m http.server 8000. Keep terminal open.
Open in Browser: Navigate to http://localhost:8000.
Project Structure
## ๐ Project Structure
```text
โโโ index.html # Main HTML shell
โโโ Visualization_Start.bat # Script to start the local server
โโโ python_check.bat # Script to check Python installation
@ -195,30 +83,30 @@ Project Structure
โโโ intel/ # Project documentation and AI context
โ โโโ readme.md # This documentation
โ โโโ context.md # Detailed technical overview for AI assistance
โ โโโ GEMINI.md # High-level project overview for AI
โ โโโ GEMINI.md # High-level project overview for AI
