Commonplace

Viewport-Based Data Streaming and Level-of-Detail Rendering

This document describes the architecture for efficiently handling large collections in Commonplace through viewport-based data streaming and level-of-detail (LOD) rendering, particularly in spatial mode.

Overview

Commonplace collections can contain millions of cards. Loading all cards to the client would be inefficient and impractical. Instead, we use a viewport-based streaming approach similar to game engines that only load visible geometry, or mapping applications that progressively load detail based on zoom level.

The system ensures that only cards visible to the user (or likely to become visible soon) are loaded and rendered, while maintaining smooth interaction and navigation experiences.

Core Principles

Viewport-Driven Loading

The fundamental principle is that data loading is driven by what the user can actually see:

  • List Mode: Load cards within the visible scroll range plus a buffer
  • Spatial Mode: Load cards within the visible canvas bounds plus a margin
  • Predictive Loading: Anticipate user movement and preload likely-needed content
  • Progressive Detail: Load summary information first, full details on demand

Level-of-Detail Rendering

In spatial mode, the system adapts the visual representation based on zoom level:

  • High Zoom (Zoomed In): Individual cards with full detail
  • Medium Zoom: Individual cards with reduced detail
  • Low Zoom (Zoomed Out): Clustered representations of card groups
  • Very Low Zoom: Regional summaries and aggregate visualizations

Viewport Management

List Mode Viewport

In list mode, the viewport is a one-dimensional range representing visible items:

  • Visible Range: Currently displayed card indices
  • Buffer Range: Extended range including preloaded items above and below
  • Dynamic Sizing: Buffer size adapts to scroll velocity
  • Efficient Calculation: Simple arithmetic to determine needed cards

Spatial Mode Viewport

In spatial mode, the viewport is a two-dimensional area with zoom level:

  • Visible Bounds: Current view rectangle in world coordinates
  • Buffer Bounds: Extended area including margin for smooth panning
  • Zoom Level: Current magnification affecting detail requirements
  • Spatial Indexing: Efficient queries using spatial data structures

Data Streaming Protocol

Progressive Detail Levels

Cards are loaded in stages based on need:

  1. Summary Level: Title, basic metadata, position information
  2. Preview Level: Summary plus key fields and thumbnail images
  3. Full Level: Complete card data including all fields and full-size media
  4. Connected Level: Full card plus immediate connection information

Request Batching

Multiple data requests are batched and coalesced for efficiency:

  • Spatial Coalescing: Nearby individual requests combined into area queries
  • Temporal Batching: Rapid viewport changes result in single optimized request
  • Priority Ordering: Visible content prioritized over predictive loading
  • Cancellation: Obsolete requests cancelled when viewport changes rapidly

Differential Updates

When cards change on the server, only deltas are transmitted:

  • Field-Level Changes: Only modified fields sent, not entire cards
  • Position Updates: Spatial position changes sent separately
  • Bulk Operations: Efficient handling of operations affecting many cards
  • Version Vectors: Track client/server synchronization state

Level-of-Detail System

Zoom-Based Detail Transitions

The system defines zoom ranges that trigger different rendering approaches:

  • Individual Card Rendering: When cards are large enough to be readable
  • Simplified Card Rendering: Reduced detail when cards become small
  • Cluster Rendering: Group nearby cards when individual rendering becomes ineffective
  • Regional Rendering: Area-based representations for very low zoom levels

Clustering Algorithms

When cards need to be grouped, multiple clustering approaches are available:

  • Spatial Clustering: Group cards based on physical proximity
  • Semantic Clustering: Group related cards (same schema, connected, similar content)
  • Hierarchical Clustering: Pre-computed cluster hierarchies for smooth transitions
  • Hybrid Clustering: Combination of spatial and semantic factors

Cluster Representations

Clustered cards can be visualized in several ways:

  • Card Stacks: Overlapping cards showing a few representative items
  • Compact Summaries: Text-based summaries with counts and key information
  • Bubble Representations: Circles sized by card count, colored by dominant schema
  • Icon Grids: Small icons arranged in grids for dense areas
  • Heatmaps: Color-coded regions showing card density

Performance Optimizations

Client-Side Caching

The client maintains hierarchical caches for different detail levels:

  • Summary Cache: Large capacity for basic card information
  • Preview Cache: Medium capacity for extended card previews
  • Full Cache: Small capacity for complete card data
  • Spatial Index Cache: Fast spatial queries for cached cards

Memory Management

Intelligent eviction policies ensure efficient memory usage:

  • Distance-Based Eviction: Cards far from current viewport evicted first
  • Detail-Level Priority: Full cards evicted before summaries
  • Usage-Based Retention: Frequently accessed cards retained longer
  • Predictive Retention: Cards in predicted movement direction retained

Server-Side Indexing

The server maintains multiple indexes for efficient queries:

  • Spatial Indexes: R-trees or quadtrees for geometric queries
  • Ordered Indexes: Sorted lists for list mode range queries
  • Content Indexes: Full-text and field-based search indexes
  • Connection Indexes: Graph structures for relationship queries

Interaction Handling

Smooth Navigation

The system ensures responsive interaction during navigation:

  • Immediate Response: UI updates immediately using cached data
  • Progressive Enhancement: Additional detail loaded asynchronously
  • Smooth Transitions: Animated transitions between detail levels
  • Gesture Prediction: Touch and mouse gestures predict movement direction

Cluster Interaction

Users can interact with clustered representations:

  • Zoom to Expand: Zoom in to see individual cards within clusters
  • In-Place Expansion: Temporarily expand clusters without changing zoom
  • Cluster Navigation: Browse cluster contents without full expansion
  • Context Preservation: Maintain spatial context during cluster operations

Link-Aware Loading

Visual Link Requirements

Connected cards may need special loading consideration:

  • Link Endpoints: Ensure both ends of visible connections are loaded
  • Link Paths: Load intermediate cards for multi-hop connections
  • Link Metadata: Load connection labels and properties for display
  • Link Clustering: Group connections when cards are clustered

Event Flow Optimization

Links that carry events require careful management:

  • Active Link Prioritization: Prioritize loading for active event flows
  • Link State Caching: Cache connection states for responsive updates
  • Event Batching: Batch related events for efficient processing
  • Link Validation: Ensure connection endpoints remain synchronized

Future Considerations

3D Spatial Mode

The architecture anticipates future 3D spatial capabilities:

  • 3D Viewport Management: Extension to three-dimensional viewports
  • 3D Clustering: Volumetric clustering algorithms for 3D space
  • Cross-Dimensional Compatibility: Maintain compatibility between 2D and 3D representations
  • VR/AR Integration: Support for immersive viewing environments

Advanced Clustering

Future enhancements to the clustering system:

  • Machine Learning Clustering: AI-driven semantic grouping
  • User-Defined Clustering: Custom clustering rules and preferences
  • Temporal Clustering: Time-based grouping for historical data
  • Cross-Collection Clustering: Clustering across collection boundaries

This viewport-based approach ensures that Commonplace can scale to handle massive collections while maintaining responsive, intuitive user interactions across all viewing modes.