infinite-agents-public/mapbox_test/mapbox_globe_9/CLAUDE.md

CLAUDE.md - Globe Visualization 9

Project Guidelines for Claude Code

Local Development

Starting a Local Server

# From the mapbox_globe_9 directory:

# Python 3 (recommended)
python -m http.server 8000

# Python 2
python -m SimpleHTTPServer 8000

# Node.js
npx http-server -p 8000

Access at: http://localhost:8000

Project Structure

mapbox_globe_9/
├── index.html              # Main HTML with UI overlays
├── src/
│   ├── index.js           # Mapbox initialization & choropleth logic
│   └── data/
│       └── data.js        # Educational funding GeoJSON data
├── README.md              # Full documentation
└── CLAUDE.md              # This file

Code Organization Patterns

Mapbox Token

• Uses public token: pk.eyJ1IjoibGludXhpc2Nvb2wiLCJhIjoiY2w3ajM1MnliMDV4NDNvb2J5c3V5dzRxZyJ9.wJukH5hVSiO74GM_VSJR3Q
• Configured in src/index.js

Data Structure

Country Educational Data (educationalFundingData):

{
    type: "FeatureCollection",
    features: [{
        type: "Feature",
        geometry: { type: "Point", coordinates: [lng, lat] },
        properties: {
            country: "Country Name",
            iso: "ISO",
            spendingPerCapita: 2850,
            budgetPercent: 5.4,
            avgTeacherSalary: 62000,
            teacherStudentRatio: 16,
            educationIndex: 0.92,
            trainingCenters: 15
        }
    }]
}

Training Centers (trainingCentersData):

• Generated dynamically from country data
• Distributed around country coordinates with random offset

Key Mapbox Techniques

Choropleth Color Interpolation:

'circle-color': [
    'interpolate',
    ['linear'],
    ['get', 'spendingPerCapita'],
    0, '#440154',      // Purple
    500, '#31688e',    // Blue
    1000, '#35b779',   // Green
    2000, '#fde724'    // Yellow
]

Size Scaling:

'circle-radius': [
    'interpolate',
    ['linear'],
    ['get', 'spendingPerCapita'],
    0, 3,
    5000, 25
]

Zoom-Based Opacity:

'text-opacity': [
    'interpolate',
    ['linear'],
    ['zoom'],
    1.5, 0,
    2.5, 0.7
]

Mapbox Layers

1. education-circles: Main choropleth layer with size + color encoding
2. training-centers-layer: Red point markers for training facilities
3. training-centers-halo: Glow effect around centers
4. country-labels: Country name labels (zoom-dependent)

Data Processing Pipeline

1. Load GeoJSON data from data.js
2. Process features to calculate derived metrics:
   • Funding gap classification
   • Efficiency scores
   • Salary gap tiers
3. Sort for rankings (top countries by spending)
4. Calculate statistics (avg, max, min)
5. Generate training centers from country data
6. Add to map as GeoJSON sources
7. Apply data-driven styling with expressions

Interactive Features

Hover Events:

• Countries: Show comprehensive funding metrics popup
• Training Centers: Show facility details popup

Click Events:

• Countries: Fly to location with camera animation

Toggle Controls:

• Training centers visibility
• Country labels visibility

Leaderboard:

• Top 10 countries by spending
• Click to navigate

Globe Configuration

map.setFog({
    color: 'rgba(10, 15, 35, 0.9)',
    'high-color': 'rgba(25, 50, 100, 0.5)',
    'horizon-blend': 0.3,
    'space-color': '#000814',
    'star-intensity': 0.7
});

Animation

Auto-Rotation:

• Smooth continuous rotation when user not interacting
• Pauses on mouse down/drag/pitch/rotate
• Resumes on interaction end

Styling Guidelines

Color Palette:

• Background: #000814 (deep blue-black)
• Primary accent: #fde724 (bright yellow)
• Secondary accent: #35b779 (green)
• Training centers: #ff6b6b (coral red)
• Choropleth: Viridis scale (purple → blue → green → yellow)

Typography:

• Font family: 'Inter' (Google Fonts)
• Weights: 300, 400, 600, 700

UI Patterns:

• Glassmorphism: rgba(0, 8, 20, 0.92) + backdrop-filter: blur(10px)
• Border accents: rgba(253, 231, 36, 0.2)
• Shadows: 0 8px 32px rgba(0, 0, 0, 0.5)

Responsive Design

Mobile Breakpoint: @media (max-width: 768px)

• Hides legend and leaderboard
• Repositions controls to bottom
• Reduces font sizes
• Adjusts padding

Performance Considerations

• Single-pass data processing on load
• Efficient GeoJSON structure
• Optimized layer ordering
• Smooth animations with requestAnimationFrame
• Minimal DOM manipulation

Browser Console Logging

On successful load, logs:

Globe loaded successfully!
Total countries: [count]
Total training centers: [count]
Average spending: $[amount]
Top 5 countries by spending: [list]

Common Tasks

Add a New Country:

1. Add feature to educationalFundingData.features in data.js
2. Include all required properties
3. Training centers will auto-generate

Modify Color Scale:

1. Edit circle-color interpolate expression in src/index.js
2. Adjust color stops and values
3. Update legend in index.html

Change Globe Style:

1. Modify style parameter in map initialization
2. Options: dark-v11, light-v11, satellite-v9, streets-v12

Adjust Rotation Speed:

1. Change rotationSpeed variable or modify timestamp divisor in rotateCamera()
2. Current: (timestamp / 200) % 360

Web Learning Applied

This iteration implements choropleth data visualization techniques learned from:

• Mapbox GL JS Documentation: Update a choropleth layer by zoom level

Key learnings applied:

1. Interpolate expressions for continuous color scaling
2. Linear interpolation for smooth gradients
3. Data-driven property access with ['get', 'property']
4. Multi-stop color ramps for choropleth maps
5. Layer-based data visualization architecture

Quality Standards

Code:

• Clear variable naming
• Commented sections
• Consistent formatting
• Error-free execution

Visual:

• Professional color scheme
• Clear data hierarchy
• Smooth animations
• Readable typography

Data:

• Realistic values
• Complete coverage (180+ countries)
• Proper coordinate format
• Meaningful correlations

Future Enhancement Ideas

1. Add time-series slider for historical data
2. Implement 3D extrusions for total budget
3. Add filter controls for regions/income levels
4. Include comparison mode (side-by-side countries)
5. Real-time data integration from APIs
6. Export functionality for charts/data
7. Accessibility improvements (ARIA labels, keyboard nav)

---

This iteration demonstrates intermediate-to-advanced Mapbox techniques with a focus on choropleth data visualization, multi-layer composition, and rich interactivity on a 3D globe projection.