Skip to content

CHANGELOG.md

Latest commit

 

History

History
433 lines (358 loc) · 14 KB

CHANGELOG.md

File metadata and controls

433 lines (358 loc) · 14 KB

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Planned

  • Phase 6: Data loading (CSV, Parquet)
  • Phase 7: Performance optimization
  • Phase 8: Additional plot types
  • Phase 9: WASM support
  • Phase 10: Examples & documentation

[0.5.0] - 2025-10-08

Added - Phase 5: Colormap System ✅

Color Module (viz-core/color/)

  • Colormap trait - Interface for mapping [0,1] → RGBA colors

    • sample(t: f32) → Vec4 method for color lookup
    • name() → &str for colormap identification
    • Send + Sync for thread safety

  • Scientific Colormaps (4 total)

    • Viridis - 256-entry LUT, perceptually uniform, colorblind-friendly
    • Plasma - 8-entry LUT, vibrant perceptually uniform gradient
    • Inferno - 8-entry LUT, warm tones with high contrast
    • Turbo - 8-entry LUT, improved rainbow, colorblind-friendly
    • All use linear interpolation for smooth gradients
    • Fast lookup via LUT (<1μs per sample)

  • ColorScale utilities - Data value to colormap domain mapping

    • map_linear(value, min, max) → [0,1] for linear scaling
    • map_log(value, min, max) → [0,1] for logarithmic scaling
    • map() with ScaleType enum (Linear | Log)
    • Handles degenerate ranges gracefully

  • ScaleType enum - Linear and Log scaling modes

Data Integration

  • PointCloud::apply_colormap() method
    • Maps metadata fields to colors using any colormap
    • Supports both linear and log scaling
    • Returns Result for error handling
    • Automatically finds min/max for normalization

UI Enhancements

  • ControlPanel colormap controls
    • Colormap selector dropdown (Viridis, Plasma, Inferno, Turbo)
    • Live colormap preview strip (64-step gradient)
    • Log scale toggle checkbox
    • Visual feedback with colormap preview rendering

Examples

  • scatter_3d_ui enhanced with colormap demo
    • Spiral dataset with height and radius metadata
    • Random cube dataset with distance and height metadata
    • Dynamic colormap switching via UI
    • Demonstrates both linear and log scaling
    • Real-time colormap application

Testing

  • 17 new tests for color system (52 tests total)
    • Colormap boundary tests (t=0.0, 0.5, 1.0)
    • Gradient smoothness verification (no NaN/Inf)
    • ColorScale linear/log mapping tests
    • Scale clamping and degenerate range handling

Metrics

  • Lines of Code: 430 (250 colormap.rs, 100 scale.rs, 80 UI)
  • Performance: <1μs color lookup via LUT interpolation
  • Memory: Minimal overhead (LUTs stored as const arrays)
  • Tests: 52 passing (17 new colormap/scale tests)

Changed

  • Updated viz-core exports to include color types
  • Enhanced scatter_3d_ui example with metadata and colormaps

[0.4.0] - 2025-10-08

Added - Phase 4: UI Integration ✅

UI System (viz-core/ui/)

  • UiContext - egui-wgpu integration

    • Manages egui rendering pipeline
    • Handles window events and input
    • Proper event consumption (UI vs 3D controls)
    • wants_pointer_input() and wants_keyboard_input() for input routing
    • Renders UI on top of 3D visualization without clearing scene

  • PerformanceMetrics - FPS and frame time tracking

    • Real-time FPS calculation
    • Frame time averaging with configurable window (default 100 frames)
    • Min/Max frame time tracking
    • Total frames and elapsed time
    • overall_average_fps() for session statistics
    • reset() for clearing metrics
    • 4 comprehensive tests

  • performance_panel() - Performance metrics UI

    • Live FPS display with averaging
    • Frame time statistics (average, min, max)
    • Total frames counter
    • Elapsed time display (MM:SS format)
    • Frame time graph using egui_plot
    • Compact, non-intrusive design

  • ControlPanel - Visualization controls

    • Point size slider (1-20 pixels)
    • Dataset selector dropdown
    • Grid toggle (prepared for future grid rendering)
    • Background color picker with live preview
    • background_wgpu_color() helper for wgpu integration
    • Returns bool when settings change

Examples

  • scatter_3d_ui - Full UI demonstration
    • Integrates all Phase 1-4 features
    • Performance panel with live FPS
    • Control panel with interactive sliders
    • Two datasets: Spiral (1K) and Cube (10K points)
    • Real-time dataset switching
    • Live point size adjustment
    • Background color customization
    • H key toggles UI visibility
    • All Phase 3 camera controls preserved
    • 375 lines of code

Performance Results

UI Rendering

  • 60+ FPS with UI enabled (1K points)
  • 60+ FPS with UI enabled (10K points)
  • UI rendering: <1ms additional overhead
  • egui efficiently updates only changed widgets
  • No impact on 3D rendering performance

Technical Details

Dependencies Added

  • egui 0.26 - Immediate mode GUI framework
  • egui-wgpu 0.26 - wgpu integration for egui
  • egui-winit 0.26 - winit event handling for egui
  • egui_plot 0.26 - Plotting library for performance graphs

Code Statistics

  • UiContext: ~130 LOC
  • PerformanceMetrics: ~180 LOC
  • Panels (performance_panel + ControlPanel): ~190 LOC
  • scatter_3d_ui example: ~375 LOC
  • Total Phase 4: ~875 LOC

Architecture Decisions

  1. Event Routing: UI gets first priority on events, 3D controls only if UI doesn't consume
  2. Separate Render Passes: 3D scene rendered first (with clear), UI rendered second (load previous)
  3. Immediate Mode: egui's immediate mode paradigm simplifies state management
  4. Performance First: Metrics tracking has minimal overhead (<0.1ms per frame)

[0.3.0] - 2025-10-07

Added - Phase 3: Basic Data & Rendering ✅

Data Structures (viz-core/data/)

  • Dataset trait - Generic interface for all data types
    • bounds() for spatial queries
    • len() and is_empty() for size info
    • name() for identification
    • Send + Sync for multi-threading
  • PointCloud - 3D point data structure
    • Positions (Vec3) storage
    • Optional per-point colors (Vec4)
    • Optional per-point sizes (f32)
    • Metadata storage (HashMap<String, Vec>)
    • Automatic bounds calculation
    • Builder pattern API (with_colors, with_sizes, with_metadata)
    • generate_height_colors() for rainbow gradient based on Y axis
    • 8 comprehensive tests

Rendering Pipeline (viz-plots/)

  • Scatter3D - GPU-accelerated point cloud renderer
    • Efficient vertex buffer management
    • Camera uniform buffer binding
    • WGSL shader integration
    • Point primitive rendering
    • Alpha blending support
    • Configurable point size
    • update_camera() for real-time camera updates
    • render() for drawing to render pass

GPU Uniforms (viz-core/renderer/)

  • CameraUniforms - GPU-compatible camera data
    • 4×4 view-projection matrix (64 bytes)
    • Camera position for lighting (12 bytes)
    • Proper padding for GPU alignment (4 bytes)
    • Total size: 80 bytes (validated)
    • Pod + Zeroable for safe bytemuck casting
    • 4 tests for size/alignment verification

Shaders

  • scatter.wgsl - Point rendering shader
    • Vertex shader with camera transform
    • Distance-based point fading
    • Per-vertex color support
    • Point size control
    • Fragment shader with alpha blending
    • 66 lines of WGSL code

Examples

  • scatter_3d - Interactive 3D scatter plot demonstration
    • Spiral generator (1000 points) - structured pattern
    • Cube generator (10,000 points) - random distribution
    • Full camera integration (Phase 2)
    • Keyboard shortcuts:
      • 1: Load spiral (1000 points)
      • 2: Load cube (10,000 points)
      • R: Reset camera view
      • ESC: Exit application
    • Mouse controls (from Phase 2):
      • Drag: Rotate camera
      • Shift+Drag: Pan camera
      • Scroll: Zoom in/out
    • Height-based rainbow coloring
    • Real-time FPS counter
    • Performance metrics logging
    • 323 lines of code

Performance Results

Scatter Plot Rendering

  • 1,000 points: 120 FPS (Apple M1 Max, Metal)
  • 10,000 points: 60+ FPS (exceeds target)
  • GPU vertex buffer creation: ~370ms for initial upload
  • Frame time: <8ms per frame @ 120 FPS
  • Camera update: <0.01ms per frame

Memory Usage

  • Base overhead: ~68MB
  • PointCloud (1K points): ~48KB (positions + colors)
  • PointCloud (10K points): ~480KB
  • GPU buffers scale linearly with point count

Technical Details

Test Coverage

  • Dataset trait: 8 tests (bounds, colors, metadata)
  • CameraUniforms: 4 tests (size, alignment, creation)
  • All tests passing (35 total across all phases)

Code Statistics

  • PointCloud: ~329 LOC
  • Scatter3D renderer: ~229 LOC
  • scatter.wgsl shader: ~66 LOC
  • CameraUniforms: ~89 LOC
  • scatter_3d example: ~323 LOC
  • Total Phase 3: ~1,036 LOC

Pipeline Validation

  • ✅ CPU → GPU data flow working
  • ✅ Camera matrices properly uploaded to GPU
  • ✅ Shader compiles and runs on Metal
  • ✅ Alpha blending functional
  • ✅ Interactive controls responsive
  • ✅ Performance targets exceeded

Architecture Decisions

  1. Dataset Trait: Generic interface allows future plot types to work with any data structure
  2. Builder Pattern: PointCloud uses fluent API for optional data (colors, sizes, metadata)
  3. Vertex Format: Position + Color packed efficiently for GPU transfer
  4. Point Primitives: Using GPU point primitives (not instanced quads) for maximum performance
  5. Uniform Buffers: Separate buffer for camera data allows easy per-frame updates

[0.2.0] - 2025-10-07

Added - Phase 2: Camera & Math ✅

Math Utilities (viz-core/math/)

  • Bounds3D - Axis-aligned bounding box (AABB)
    • from_points() for automatic bounds calculation
    • Intersection and containment tests
    • Union and padding operations
    • Corner extraction for rendering
    • 8 comprehensive tests
  • Transform - TRS (Translation, Rotation, Scale) transforms
    • Matrix conversion for GPU usage
    • Point and vector transformation
    • Inverse transforms
    • look_at() helper for camera positioning
    • 6 tests for transform operations

Camera System (viz-core/camera/)

  • OrbitalCamera - Production-grade 3D camera
    • Orbit around target with yaw/pitch control
    • Zoom in/out with distance clamping
    • Pan to move target point
    • Automatic framing of bounding boxes
    • View and projection matrix computation
    • FOV and aspect ratio management
    • Reset to default view
    • Gimbal lock prevention (pitch clamping)
    • 11 comprehensive tests

Examples

  • camera_movement - Interactive camera demonstration
    • Left mouse drag: Rotate camera
    • Shift + left mouse drag: Pan camera
    • Mouse wheel: Zoom in/out
    • R key: Reset camera
    • Real-time FPS and camera state logging
    • Running at 120 FPS (2x above 60 FPS target)

Technical Details

Test Coverage

  • All 23 tests passing (8 Bounds3D + 6 Transform + 11 Camera - 2 total)
  • Manual epsilon comparisons (approx crate doesn't support glam)
  • Comprehensive coverage of edge cases

Performance

  • Camera calculations <0.01ms
  • 120 FPS in camera_movement example
  • Zero performance impact from camera system
  • Smooth controls with no input lag

Code Statistics

  • Math utilities: ~400 LOC
  • Camera: ~310 LOC
  • Example: ~260 LOC
  • Tests: ~150 LOC
  • Total Phase 2: ~1,120 LOC

[0.1.0] - 2025-10-06

Added - Phase 1: Foundation & GPU Context ✅

Infrastructure

  • Workspace structure with 5 crates (viz-core, viz-plots, viz-app, viz-wasm, examples)
  • Complete dependency configuration
  • MIT License
  • .gitignore for Rust projects
  • Professional documentation (README, ARCHITECTURE, this CHANGELOG)

Core Library (viz-core)

  • RenderContext - GPU device, queue, and surface management
    • Automatic GPU adapter selection with high-performance preference
    • Surface configuration with proper format detection
    • Window resize handling
    • Comprehensive error handling with RenderError
  • Module structure:
    • renderer/ - GPU rendering infrastructure
    • camera/ - Camera systems (stub for Phase 2)
    • data/ - Data structures (stub for Phase 3)
    • color/ - Color mapping (stub for Phase 5)
    • math/ - Math utilities (stub for Phase 2)

Examples

  • basic_window - GPU initialization test
    • Creates window with winit
    • Initializes GPU context
    • Renders clear color (dark blue)
    • Handles events (resize, close)
    • Maintains 60 FPS render loop

Development Tools

  • Structured logging with tracing
  • Workspace optimization profiles
  • Example binaries infrastructure

Technical Details

Dependencies

  • wgpu 0.19 - WebGPU API (cross-platform GPU)
  • winit 0.29 - Window management
  • bytemuck 1.14 - Safe GPU buffer casting
  • glam 0.25 - Fast SIMD math
  • pollster 0.3 - Block on async
  • egui 0.26 - Immediate mode GUI (configured)
  • arrow 50.0, parquet 50.0 - Columnar data (configured)
  • tokio 1.35, rayon 1.8 - Async/parallel (configured)
  • anyhow 1.0, thiserror 1.0 - Error handling
  • tracing 0.1 - Structured logging

Tested Platforms

  • ✅ macOS (Darwin 24.6.0)
    • GPU: Apple M1 Max
    • Backend: Metal
    • Surface: 2560×1440, Bgra8UnormSrgb
    • Status: Working perfectly

Performance Baseline

  • GPU init: ~100ms
  • Surface config: ~3ms
  • Frame time: <1ms (clear only)
  • Memory: ~68MB base

Architecture Decisions

  1. Arc Pattern: Used to satisfy wgpu's Surface<'static> requirement
  2. Modular Crates: Separated core, plots, app, and wasm for clean dependencies
  3. Error Types: thiserror for ergonomic error handling
  4. Logging: tracing for structured, filterable logs

Code Statistics

  • Core implementation: ~250 LOC
  • Example code: ~100 LOC
  • Documentation: ~450 LOC
  • Total: ~800 LOC

Known Issues

  • None - Phase 1 complete with all objectives met

Migration Notes

  • No migrations needed - this is the initial release

Version History

  • 0.1.0 (2025-10-06) - Phase 1 Complete: Foundation & GPU Context
  • Next: 0.2.0 - Phase 2: Camera & Math System

Git Workflow

Starting from Phase 2, development will follow this pattern:

  • main branch - stable, completed phases
  • phase-N branches - active development for each phase
  • Feature branches - feature/description for specific features
  • Merge to main only when phase is complete and tested