7.8 KiB

Raw Blame History

CLAUDE.md - Globe Visualization 7 Project Guidelines

Project Context

This is Iteration 7 of the Mapbox Globe Progressive Web-Enhanced Learning series. This iteration focuses on timeline animation techniques for temporal data visualization, learning from Mapbox's timeline animation example.

Quick Start Commands

Local Development Server

# Python 3
cd /home/ygg/Workspace/sandbox/infinite-agents/mapbox_test/mapbox_globe_7
python -m http.server 8000

# Python 2
python -m SimpleHTTPServer 8000

# Node.js (if installed)
npx http-server -p 8000

Access at: http://localhost:8000

VS Code Live Server

Install "Live Server" extension
Right-click index.html
Select "Open with Live Server"

File Structure

mapbox_globe_7/
├── index.html              # Main HTML with timeline UI
├── src/
│   ├── index.js           # Timeline animation logic
│   └── data/
│       └── data.js        # 80 education platforms, 8 years
├── README.md              # Full documentation
└── CLAUDE.md              # This file

Architecture Overview

Timeline Animation Pattern (Learned from Web)

Source: https://docs.mapbox.com/mapbox-gl-js/example/timeline-animation/

Key Pattern:

Preprocess temporal data → Add year index to each feature
Use setFilter() → Apply time-based filters efficiently
Range slider control → Manual timeline scrubbing
Interval-based playback → Automatic progression
Synchronized updates → UI state matches map state

Data Transformation Flow

// Input: Nested year data
feature.properties.yearData = {
  "2010": { enrollment, courses, completionRate },
  "2012": { ... }
}

// Processing: Flatten to temporal features
processedFeatures = features × years with yearIndex

// Filtering: Efficient year selection
map.setFilter('layer', ['==', 'yearIndex', selectedYearIndex])

Key Implementation Details

Timeline Control System

Slider Input: HTML5 range input (0-7 for 8 years)
Event Handling: Input event triggers filterByYear()
Auto-pause: Scrubbing stops playback automatically
Play/Pause: setInterval() for 1.5s per year progression

Visual Encoding Strategy

Size: Exponential scale based on enrollment
Color: Growth rate gradient (red → yellow → green → blue)
Stroke: White highlight for 10M+ platforms
Labels: Conditional visibility (5M+ threshold)

Performance Optimizations

Preprocessed data - Calculations done once at load
Filter-based animation - No layer recreation
Conditional labeling - Only major platforms labeled
Efficient expressions - Interpolate/step for styling

Mapbox-Specific Patterns

Globe Projection Setup

const map = new mapboxgl.Map({
    projection: 'globe',
    style: 'mapbox://styles/mapbox/dark-v11',
    zoom: 1.8,
    pitch: 20
});

Timeline Filtering

map.setFilter('education-circles', ['==', 'yearIndex', yearIndex]);
map.setFilter('education-labels', ['==', 'yearIndex', yearIndex]);

Data-Driven Styling

'circle-radius': [
    'interpolate',
    ['exponential', 1.5],
    ['get', 'enrollment'],
    0, 3,
    50000000, 22,
    150000000, 32
]

Code Quality Standards

JavaScript Style

ES6+ features (const/let, arrow functions, template literals)
Clear function names (filterByYear, calculateGrowthRate)
Comment blocks for major sections
Error handling for edge cases

Data Quality

Realistic enrollment numbers
Accurate geographic coordinates
Consistent property naming
Complete temporal coverage (8 years per platform)

UI/UX Considerations

Responsive timeline controls
Clear year display
Intuitive slider interaction
Real-time statistics feedback
Informative hover popups

Debugging Tips

Timeline Not Updating

Check yearIndex assignment in preprocessing
Verify filter expression syntax
Confirm slider value range (0-7)
Test filterByYear() function in console

Visual Encoding Issues

Inspect feature properties in console
Check Mapbox expression syntax
Verify data ranges for interpolation
Test with simplified expressions

Performance Problems

Check feature count (should be ~640)
Verify filter efficiency
Monitor frame rate during animation
Simplify visual expressions if needed

Browser Console Testing

// Check processed data
console.log(processedData.features.length); // Should be ~640

// Test filtering manually
filterByYear(3); // Jump to 2016

// Inspect current year
console.log(currentYearIndex, years[currentYearIndex]);

// Toggle playback
togglePlayback();

Extension Ideas

Easy Additions

Speed control for playback (0.5x, 1x, 2x)
Year range selector (start/end)
Platform type filter (MOOC, University, etc.)
Keyboard shortcuts (space = play/pause, arrows = navigate)

Medium Complexity

Multi-metric visualization (enrollment vs courses)
Regional comparison mode
Growth trend charts
Search functionality for platforms

Advanced Features

Export timeline as video/GIF
Custom data upload
Side-by-side year comparison
3D bar charts for enrollment

Web Learning Application

What Was Learned

Timeline preprocessing pattern - Transform nested temporal data
Filter-based animation - Efficient layer updates
Range slider integration - Map state synchronization
Playback control system - setInterval management
Aggregate calculation - Real-time statistics

How It Was Applied

Transformed 80 platforms with nested yearData into 640 flat features
Implemented year-based filtering with yearIndex property
Built play/pause system with auto-pause on scrubbing
Created synchronized UI (slider, year display, statistics)
Added growth rate calculation for temporal analysis

Innovation Beyond Source

Multi-metric temporal data (enrollment, courses, completion)
Growth rate calculation and visualization
Aggregate statistics panel
Exponential size scaling for better hierarchy
Auto-rotation with interaction detection

Mapbox Token

Working Token: pk.eyJ1IjoibGludXhpc2Nvb2wiLCJhIjoiY2w3ajM1MnliMDV4NDNvb2J5c3V5dzRxZyJ9.wJukH5hVSiO74GM_VSJR3Q

This token is included in the source code and works for this visualization.

Success Metrics

This iteration successfully demonstrates:

✓ Timeline animation learned from web source
✓ Temporal data preprocessing pattern
✓ Filter-based animation approach
✓ Manual timeline scrubbing control
✓ Automatic playback functionality
✓ Real-time aggregate statistics
✓ Multi-year growth visualization
✓ 80+ education platforms worldwide
✓ Globe-appropriate temporal visualization

Iteration Evolution

Previous Focus (Iterations 1-6):

Basic globe setup and styling
Single-layer visualizations
Static data snapshots
Simple interactivity

This Iteration (7):

Timeline animation system
Temporal data exploration
Multi-year data processing
Playback controls
Growth rate analysis

Future Directions (8+):

3D extrusions for temporal depth
Custom animations and transitions
Real-time data integration
Advanced temporal analysis
Multi-view coordination

Generated by: Sub Agent 3 Date: 2025-10-09 Web Source: Mapbox Timeline Animation Example Iteration: 7 of Progressive Mapbox Globe Series

7.8 KiB Raw Blame History Unescape Escape