# Globe Visualization 1: Global Population Distribution

An interactive 3D globe visualization showcasing the world's major urban centers using Mapbox GL JS. This project demonstrates fundamental globe projection techniques, atmospheric effects, and data-driven styling.

## Web Source

This visualization is based on techniques learned from:
- **Primary Source**: [Mapbox Globe Example](https://docs.mapbox.com/mapbox-gl-js/example/globe/)
- **API Documentation**: [Mapbox GL JS v3.0.1](https://docs.mapbox.com/mapbox-gl-js/api/)

## Techniques Learned

### 1. Globe Projection Setup
- Initialized map with `projection: 'globe'` for 3D spherical view
- Used `satellite-streets-v12` style optimized for globe visualization
- Configured initial zoom and center for optimal viewing

### 2. Atmosphere & Fog Configuration
- Implemented `map.setFog({})` for realistic atmospheric effects
- Customized atmosphere colors: horizon, sky, and space
- Added subtle star field for enhanced visual appeal

### 3. Data-Driven Styling
- Used Mapbox expressions for dynamic circle sizing based on population
- Implemented color interpolation for visual hierarchy
- Applied stroke styling for better visibility

### 4. Interactivity
- Auto-rotation with user interaction detection
- Hover popups with detailed city information
- Pause rotation on zoom or user interaction
- Navigation and fullscreen controls

## How to Run

### Prerequisites
1. Get a free Mapbox access token at [https://account.mapbox.com/](https://account.mapbox.com/)
2. Replace the placeholder token in `src/index.js`:
   ```javascript
   mapboxgl.accessToken = 'YOUR_ACTUAL_MAPBOX_TOKEN';
   ```

### Local Server
Run a local web server from this directory:

```bash
# Using Python 3
python -m http.server 8000

# Using Python 2
python -m SimpleHTTPServer 8000

# Using Node.js http-server
npx http-server -p 8000
```

Then open your browser to: `http://localhost:8000`

## What It Demonstrates

### Visual Features
- **3D Globe Projection**: Realistic spherical representation of Earth
- **Population Visualization**: 100 major cities represented as scaled circles
- **Color Encoding**: Population magnitude indicated by color intensity
- **Atmospheric Effects**: Fog, horizon glow, and space rendering
- **Auto-Rotation**: Gentle spinning animation with smart pause/resume

### Technical Features
- **Data-Driven Styling**: Circle size and color based on population data
- **Interactive Popups**: City details on hover
- **Responsive Controls**: Navigation, zoom, and fullscreen
- **Mobile Support**: Touch event handling
- **Performance Optimization**: Efficient rendering of 100+ data points

### Data Coverage
- **100 Cities** across all continents
- **Population Range**: 1M to 40M people
- **Geographic Diversity**: Cities from 50+ countries
- **Data Year**: 2024 estimates

## Data Sources

Population data compiled from:
- UN World Urbanization Prospects 2024
- City government statistics
- World Bank urban population data
- National census reports

## File Structure

```
mapbox_globe_1/
├── index.html              # Main HTML with UI overlays
├── src/
│   ├── index.js           # Globe initialization and interaction logic
│   └── data/
│       └── population-data.js  # GeoJSON with city population data
├── README.md              # This file
└── CLAUDE.md              # Development guidelines
```

## Key Code Patterns

### Globe Initialization
```javascript
const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/satellite-streets-v12',
    projection: 'globe',
    zoom: 1.5,
    center: [30, 20]
});
```

### Atmosphere Setup
```javascript
map.setFog({
    color: 'rgb(186, 210, 235)',
    'high-color': 'rgb(36, 92, 223)',
    'horizon-blend': 0.02,
    'space-color': 'rgb(11, 11, 25)',
    'star-intensity': 0.6
});
```

### Data-Driven Styling
```javascript
'circle-radius': [
    'interpolate',
    ['linear'],
    ['get', 'population'],
    1000000, 4,
    30000000, 24
]
```

## Browser Compatibility

- Chrome/Edge: Full support
- Firefox: Full support
- Safari: Full support (v15.4+)
- Mobile browsers: Full support with touch controls

## Performance Notes

- Optimized for 100-200 data points
- Globe projection may be GPU intensive on older devices
- Auto-rotation pauses automatically when needed
- Efficient event handling for smooth interaction

## Next Steps

This is the first in a series of globe visualizations. Future iterations will explore:
- Animated data flows between cities
- Time-series population changes
- 3D extruded buildings
- Custom globe textures
- Advanced camera animations
- Real-time data integration

## License

This is an educational example. Please review Mapbox's terms of service for production use.