- 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.
Vehicle Dimensions:
- Added "Show Dimensions" toggle to the display settings.
- Implemented `drawObjectDimensions` in `drawUtils.js` to render object extents as oriented rectangles based on `objectExtentRadii` and `objectExtentAngle`.
- Updated `radarSketch.js` to draw dimensions when enabled.
- Ensured dimensions and covariance ellipses are drawn at the `correctedPosition` for accurate alignment with track markers.
Track Visualization:
- Updated `drawTrajectories` to prioritize the `risk` property on track logs for coloring (0=Low/Blue, 1=Medium/Orange, 2=High/Red).
- Added fallback to `ttcCategoryTimeline` for backward compatibility.
- Fixed off-by-one error in trajectory history filtering to prevent drawing future points.
Frame Synchronization & UI:
- Refactored frame number display logic across Overlays, Data Explorer, and Timeline.
- UI now displays the actual `frameIdx` from the data source instead of the internal array index, resolving discrepancies between the Data Explorer and the main view.
This commit introduces several improvements to the radar visualization, focusing on responsiveness, error handling, and clearer data representation.
**Key Changes:**
* **Responsive Radar Overlay:** The persistent radar information overlay (`ift-dot-matrix` canvas) in `dom.js` is no longer a fixed size. It now dynamically adjusts its width to match the radar plot's size, ensuring a consistent visual experience across different screen resolutions and resize events. The internal drawing logic has been updated to dynamically calculate column counts based on the canvas's current dimensions.
* **Improved Error Handling in Drawing Utilities:** Comprehensive `try...catch` blocks have been added to all major drawing functions within `drawUtils.js`. This significantly enhances the application's robustness by gracefully handling potential errors during rendering, preventing crashes and providing better debugging insights.
* **TTC Category Fallback:** In `drawUtils.js`, the trajectory drawing logic for Time-to-Collision (TTC) now includes a fallback mechanism. If a track's `ttcCategory` is undefined or invalid, it will default to a neutral gray color, ensuring that trajectories are always rendered with a clear visual state.
