This commit introduces a specialized visualization for ADAS radar data and significantly
improves the Data Explorer's responsiveness at small window dimensions.
Key Changes:
- ADAS Visualization: Replaced the horizontal AG Grid for the ADAS tab with a custom
Vertical Property View. This uses a card-based layout with clean Key-Value tables,
optimizing for high-column counts and narrow panels.
- Layout Optimizations:
- Reduced minimum window dimensions for the Data Explorer from 400x300 to 250x200.
- Implemented horizontal scrolling for the tab navigation row to prevent UI breakage
at narrow widths.
- Added 'flex-shrink-0' guards to the panel header and tabs to ensure they remain
visible and stable during vertical resizing.
- UI Refinement: Cleaned up the ADAS view by removing redundant property IDs from
headers and centering all data within a structured 2-column grid.
- Documentation:
- Updated the /intel folder (readme.md, context.md, GEMINI.md) to reflect new features.
- Added "Rationale" comments to source code (index.html, dataExplorer.js) to document
architectural decisions and prevent future UI regressions.
Fixes: #ADAS-Explorer-Overhaul
- Decoupled 'God Mode' from GridStack into a standalone floating fixed overlay.
- Extracted 'makeDraggableAndResizable' utility with persistent localStorage memory.
- Implemented "Soft-Reload" for GridStack: restores panel positions by gs-id without destructive DOM replacement.
- Added viewport-aware "Rescue Logic" to pull off-screen panels back into view on window resize.
- Re-architected God Mode auto-hide sequence (5s delay + 3s countdown with visual warning).
- Implemented 'Auto-Focus' logic: clicking any floating panel populates it to the front (z-index: 40).
- Hardened all p5.js sketches with 0-width guards to prevent crashes during container shifts.
- Cleaned up redundant UI text overlays and unified the visual presentation.
- Extracted drag/resize logic from Data Explorer into reusable `ui.js` utility.
- Migrated Zoom Sketch from GridStack into a free-floating, draggable, and resizable `z-30` overlay (default size 900x455).
- Restored and optimized auto-hide timing lifecycle for Close-Up mode:
- 0-5s: Clean freeze for data inspection without hovering.
- 5-8s: Fading visual countdown warning prior to panel closure.
- Implemented state flag `zoomPanelExplicitlyClosed` guaranteeing the "X" button correctly masks rapid re-triggers.
- Bound 'g' toggle shortcut to aggressively wipe/close panels when exiting God Mode entirely.
- Added visual "Mouse pointer Out of Bounds" overlay when cursor exits main radar canvas.
- Downloaded GridStack.js and CSS assets (v10.1.2) to the vendor folder for offline support.
- Configured index.html with local-first script loading and CDN fallback logic.
- Hardened server.py to explicitly bind to 127.0.0.1 and anchor to the script directory.
- Optimized Visualization_Start.bat with working directory anchoring and a delayed browser launch to ensure the server is fully ready.
- Implemented GridStack.js as the core dashboard manager, enabling responsive dragging and resizing of the Radar, Video, and SpeedGraph panels.
- Replaced global windowResized events with debounced ResizeObserver instances attached to the specific panel containers.
- Fixed a massive memory leak in p5.js sketches by explicitly calling .remove() on old Graphics buffers before recreation.
- Optimized zoomSketch.js by removing destructive canvas teardown calls from radarSketch and using smoothed camera coordinates for tooltip bounding logic.
- Patched tooltip overflow bugs in drawUtils.js and speedGraphSketch.js to intelligently clamp within panel edges, even in narrow columns.
- Disabled native p5 windowResized triggers to prevent double-firing when moving the web app across multiple monitors.
Features & Enhancements:
- Stability: Implemented custom server.py with zero-cache headers and V3.3.0 asset versioning to ensure latest code availability.
- Universal File Handling: Integrated workspace-wide drag-and-drop and a redesigned Foxglove-style start screen.
- Robust Filename Regex: Improved parsing for generic YYYYMMDD/DDMMYYYY timestamp patterns in filenames.
- Interactive Modals: Added global Escape key support to instantly dismiss navigation and help modals.
- Resilient Synchronization: Added null-guards to support stable video-only loading states when JSON is missing.
Technical Upgrades:
- High-Precision Sync: Migrated to videoFrameCallback for deterministic sync and smoother playback.
- Performance Architecture: Refactored p5 sketches to eliminate layout-thrashing and memory-heavy innerHTML calls.
- Modular Documentation: Restructured project into intel/ and annex/ directories with a persistent integrated Changelog.
- Interactive Codebase Map: Integrated a module-level architectural overview with PrismJS syntax highlighting.
Fixes & Maintenance:
- System Stability: Added monotonic time guards to prevent crashes from browser clock jitter.
- Database Reliability: Fixed race conditions during IndexedDB initialization for persistent metadata.
- Management Utilities: Added simple_log_cfg.py for automated radar command extraction from logs.
- Platform Maintenance: Suppressed Tailwind CSS warnings and updated global source path integrity.
This release introduces a redesigned startup flow, universal drag-and-drop, and critical stability fixes for video-only telemetry.
---
**New Features**
* **Universal Drag-and-Drop:** Expanded functionality to allow file loading from any screen within the application.
* **Redesigned Startup Flow:** Implemented a Foxglove-style SPA loading screen for a smoother initialization experience.
* **In-App Changelog:** Added a dedicated button and modal to the header for viewing version updates directly.
* **Codebase Overview:** Enhanced the architectural view with a structured file system tree and improved map visibility.
**Fixes and Performance**
* **Video-Only Stability:** Fixed crashes occurring during video-only file loading and added regression tests to ensure long-term stability.
* **Render Pipeline:** Optimized the visualization engine and refined the zoom camera UX for more fluid interaction.
* **Robust Parsing:** Improved date-time parsing logic and overlay resilience.
* **UI Refinement:** Resized the visual map, hid redundant scrollbars, and updated the application favicon.
**Maintenance**
* **Infrastructure:** Restructured internal documentation into dedicated `annex/` and `intel/` directories.
* **Configuration:** Updated `.gitignore` and refined internal documentation paths.
- Expanded start screen card and drop zone visuals for better accessibility.
- Implemented a global #global-drag-overlay that appears on drag over the entire window.
- Attached drag-and-drop listeners to document.body for universal file loading.
- Refined dragCounter logic to prevent overlay flickering during child element transit.
- Added null check for appState.vizData in sync.js to prevent TypeError during visualization reset.
- Implemented key validation guards in db.js manual offset functions to avoid IndexedDB DataErrors.
- Updated fileLoader.js to bypass manual offset lookup when no JSON filename is available.
- Added regression test 'tests/regression_video_only.test.js' to verify stable partial load paths.
Ran command: `git diff -U0`
fix: resolve console warnings and add configurable debug logging
This commit addresses active console warnings and reduces logging noise in the SpeedGraph component.
### Changes:
- **index.html**: Fixed `[Deprecation]` warning by replacing the non-standard `-webkit-appearance: slider-vertical` with modern CSS properties (`writing-mode: vertical-lr; direction: rtl;`).
- **speedGraphSketch.js**:
- Resolved `pop() was called without matching push()` error by removing an orphaned `pop()` call in [drawStaticGraphToBuffer](cci//file:///d:/Work/Repo/refactor/steps/src/p5/speedGraphSketch.js:41:2-295:4).
- Muted "Density Info" messages by gating them behind a configurable debug flag.
- **debug.js**: Added a new [speedGraph](cci:1://file:///d:/Work/Repo/refactor/steps/src/p5/speedGraphSketch.js:7:0-538:2) flag (defaulted to `false`) to `debugFlags` to allow selective enabling of SpeedGraph logs.
IMPROVEMENTS:
- **utils.js**: Enhanced [extractTimestampInfo](cci//file:///d:/Work/Repo/refactor/steps/src/utils.js:36:0-70:1) with a robust, prefix-agnostic regular expression. It now identifies `YYYYMMDD_HHMMSS` and `DDMMYYYY_HHMMSS` patterns anywhere in a filename, enabling support for generic camera names like `cam_20260312_163310` or raw recordings.
- **dom.js**: Decoupled persistent overlays and debug diagnostics from mandatory video date-time metadata. The dashboard now remains fully functional even when loading generic video files (e.g., `output.mp4`).
- **Standardized Epoch Fallback**: Implemented a unified time-anchoring logic. If a filename lacks date-time information, the system now defaults to **January 1, 1970 (Unix Epoch)**, ensuring the absolute time clocks and sync diagnostics proceed without error or disappearance.
- **Bug Fixes**: Corrected syntax errors and structural scoping issues in the [updateDebugOverlay](cci:1://file:///d:/Work/Repo/refactor/steps/src/dom.js:200:0-291:1) function that were causing diagnostics to display inconsistently.
This commit refactors the initialization phase of the Visualizer to act as a Single Page Application (SPA). A persistent workspace shell is now initially hidden behind a "Data Synchronizer" Start Screen, which handles file ingestion before seamlessly revealing the canvas.
Part 1: Implement SPA Start Screen Modal and Data Routing
* steps/index.html: Added the full-screen `start-screen-modal` overlay to intercept the user on load. Removed text placeholders inside the video and canvas containers since the workspace is now exclusively visible when populated.
* steps/src/dom.js: Exported references for the new modal, drop zone, and primary load buttons.
* steps/src/main.js: Routed standard drag-and-drop and click events to target the new Start Screen elements rather than the legacy footer buttons, initiating the existing file pipeline.
Part 2: Integrate Loading Progress Natively
* steps/index.html: Added a hidden `start-progress-container` directly inside the Start Screen card to prevent overlapping popups.
* steps/src/dom.js: Exported references to the native progress bar and text elements.
* steps/src/modal.js: Refactored `showLoadingModal`, `updateLoadingModal`, and `hideModal` to dynamically route progress updates. If the Start Screen is active, it renders the inline progress bar and disables background buttons rather than spawning the generic popup modal.
* steps/src/fileLoader.js: Updated `processFilePipeline` to fully dismiss the `start-screen-modal` upon successful data ingestion and precomputation, seamlessly transitioning the user.
Part 3: Replicate Accessibility and Theme Controls
* steps/index.html: Duplicated the Quick Start Guide, Codebase Overview, What's New, and Theme Toggle buttons, positioning them in the top-right corner of the Start Screen. Also fixed a `-webkit-appearance` CSS warning on the range slider.
* steps/src/dom.js: Exported references for the new accessibility buttons and theme toggle SVGs.
* steps/src/ui.js: Attached existing `toggleGuideModal`, `toggleCodebaseModal`, and `toggleChangelogModal` event listeners to the new replicated buttons, granting users access to documentation before data load.
* steps/src/theme.js: Updated `initializeTheme()` so switching the theme from either the workspace or the Start Screen bidirectionally syncs the Light/Dark SVGs on both buttons simultaneously.
Refactors the rendering logic for both main radar and zoom views to support
high-refresh-rate monitors and 4K displays without performance loss.
Key Changes:
1. Performance & Display:
- Uncapped Frame Rate: Set `p.frameRate(144)` in both sketches. This removes
artificial throttling on high-refresh monitors (75Hz+), eliminating
beat-frequency judder.
- 4K Quality: Removed `p.pixelDensity(1)` restrictions. High-end PCs will
now render at full device resolution (Retina/4K) instead of being downscaled.
2. Zoom Sketch Optimization:
- Viewport Culling: Implemented background slicing logic to only render the
visible portion of the static background image, significantly reducing GPU
bandwidth usage during zoom.
3. UX & Animation:
- Camera Smoothing: Applied a frame-rate independent Lerp (factor 0.5) to the
zoom camera. This mimics the weight and feel of the main radar cursor.
- Visual "Lead": Added a `leadFactor` (0.2) to the dashed hover circle. It
now interpolates between the camera and mouse, making controls feel
instant/elastic even while the view smooths out.
- Coordinate Fixes: Updated tooltip and connector logic to map correctly
from the smoothed camera space to screen space.
Addresses performance bottlenecks on high-end PCs and refines the
zoom interaction model to eliminate jitter while maintaining responsiveness.
Performance Optimizations:
1. High-DPI Scaling Fix:
- Forced `p.pixelDensity(1)` in zoomSketch.
- Issue: Retinal/4K screens were defaulting to pixelDensity 2.0+, causing
the GPU to render 4x the necessary pixels (e.g., 1000x1000 for a 500x500 canvas).
This bandwidth saturation caused FPS drops on powerful GPUs.
2. Refresh Rate Uncap:
- Set `p.frameRate(144)` explicitly.
- Issue: p5.js often throttles to 60fps. On 75Hz+ monitors, this caused a
"beat frequency" judder where update cycles missed display refresh cycles.
UX & Animation Logic:
1. Camera Smoothing (The "Cinematic" Feel):
- Decoupled the Zoom Camera position from the Raw Mouse position.
- Applied a Lerp smoothing factor of 0.5 (aligned with main radarSketch
cursor logic) to create fluid motion without feeling sluggish.
2. Visual "Lead" / Elasticity:
- Introduced `zoomLeadFactor` (0.2) for the dashed hover circle.
- The circle position is interpolated between the Smoothed Camera and
the Raw Mouse.
- Benefit: This creates a visual cue that "leads" the camera, making the
controls feel responsive/instant even while the view smoothly catches up.
3. Coordinate System Fixes:
- Reverted manual world-to-screen reprojection for tooltips.
- Adopted a relative screen-space transform:
(ItemScreenPos - CameraPos) * ZoomFactor.
- This ensures connector lines lock perfectly to visual elements regardless
of camera lag.
- Expanded Visual Navigation Map to utilize full width and increased height by 30%.
- Removed visible scrollbar from the Project Files panel.
- Adjusted padding in the file tree view for better alignment.
- Clamp delta time to minimum of 0 to prevent negative interpolation.
- Add protection against division by zero in SNR color mapping.
- Ensure trajectory points exist before fading alpha calculation.
- Standardize p.deltaTime usage for cross-browser stability.
Refactors animation and interpolation logic to ensure consistent behavior
across different monitor refresh rates (e.g., 60Hz vs 144Hz).
Changes:
- Implement time-delta adjusted smoothing for FPS counter and mouse tracking.
- Update IFT graph scaling in 'dom.js' to use performance-based delta time.
- Remove hardcoded 60FPS limit in zoom sketch to allow native refresh rates.
- Fix vertical tooltip jitter in 'drawUtils.js' by using smoothed mouse coordinates.
- Add 'lastOverlayUpdateTime' to global state for cross-module time tracking.
Adds linear interpolation (lerp) to mouse coordinates in the zoom view
to prevent jitter and provide a smoother user experience when inspecting
radar points.
Changes:
- Add `smoothedMouseX` and `smoothedMouseY` state to `radarSketch.js`.
- Apply smoothing factor (0.5) to mouse movement in the main draw loop.
- Update `handleCloseUpDisplay` and zoom sketch drawing to use smoothed coordinates.
- Ensure coordinates snap to mouse position on the first frame to prevent visual jumping.
- Implemented smooth dynamic scaling for the Inter-Frame Timing (IFT) graph that remains active even when playback is paused.
- Added a conditional `requestAnimationFrame` loop to ensure the graph scale converges smoothly to the target value during scrubbing or pause states.
- Tuned animation speeds: fast convergence (0.1 smoothing) during playback, slower (0.033) when paused for a more polished visual transition.
- Fixed a layout thrashing (forced reflow) performance issue in `updatePersistentOverlays` by reading `clientWidth` before writing text updates to the DOM.
radar view (src/drawUtils.js):
- Refactored drawTrackMarkers with a smart collision-resolution algorithm for floating labels.
- Added leader lines and themed tooltips for track IDs and speed data to prevent overlapping.
- Optimized velocity vectors with arrowheads and reduced thickness for better clarity.
- Updated drawRegionsOfInterest to use ROI_CLOSE_Y_MAX constant.
speed graph (src/p5/speedGraphSketch.js):
- Implemented a MATLAB-style spectral color scheme (Blue-Cyan-Green-Yellow-Red) to visualize track density on the CAN speed
line.
- Added a vertical smooth gradient legend bar for track density.
- Switched to robust 95th percentile normalization for density mapping to mitigate outlier noise.
- Synchronized density calculations with the "Confirmed Only" toggle.
- Updated the horizontal legend to reflect density-based coloring.
zoom view (src/p5/zoomSketch.js):
- Adjusted tooltip vertical offset for improved diagonal positioning.
- Disabled internal track detail boxes to prioritize the specialized zoom tooltip system.
- Implement robust fallback and safety logic to prevent division-by-zero or invalid state crashes.
- Update scale calculations and drawing utilities to use dynamic boundaries from appState.
- Refine radar-info-overlay to match plot width and center text content for better alignment.
- Add double-click reset functionality to the range slider to revert to default constants.
- Fix hover detection bug in God Mode during scroll-zoom interactions.
- Ensure Regions of Interest (ROI) scale proportionally with the dynamic plot range.
2 Take a look at edge cases.
3 - Implement a "Living Documentation" tool integrated directly into the application.
4 - Create a 3D-styled visual navigation map representing UI components and data flow.
5 - Add a color-coded file explorer themed by architectural section (Core, Sync, UI, etc.).
6 - Implement smart "Mini-Map" UX: docks to corner on scroll with hover-to-expand.
7 - Add local PrismJS support for high-performance source code syntax highlighting.
8 - Optimize navigation with animation locks and automatic scroll-position resets.
