nigig-org/crates/apps/map/README.md

# Nigig Map

A high-performance, offline-capable map rendering widget for Makepad applications.

## Overview

Nigig Map is a vector tile renderer designed for Makepad applications. It supports both offline (MBTiles) and online (Overpass API) map data sources, with comprehensive label placement, style customization, and smooth pan/zoom interactions.

## Features

- **Offline Maps**: Load and render MBTiles files for offline map display
- **Online Maps**: Fetch and render map data from Overpass API
- **Vector Tiles**: Render vector tiles with fill, stroke, and label layers
- **Label Placement**: Intelligent label placement with collision detection
- **Style Customization**: Comprehensive style system with zoom-dependent styles
- **Smooth Interactions**: Smooth pan, zoom, and pinch gestures
- **Performance Optimized**: Optimized for 60 FPS rendering with efficient caching

## Architecture

The map renderer follows a modular architecture with clear separation of concerns:

```
view.rs (1115 lines) - Main widget, orchestrates rendering
├── viewport.rs (538 lines) - Viewport state and transformations
├── cache.rs (786 lines) - Tile caching with LRU eviction
├── scheduler.rs (849 lines) - Tile loading scheduler
├── render_graph.rs - Render graph execution
├── tessellation.rs (597 lines) - Geometry tessellation
├── mvt_parser.rs (711 lines) - MVT tile parsing
├── overpass_parser.rs (282 lines) - Overpass API parsing
├── style.rs (496 lines) - Style compilation
├── label.rs (1098 lines) - Label extraction
├── label_state.rs (487 lines) - Label placement
├── sprite.rs (433 lines) - Sprite rendering
├── tile.rs (303 lines) - Tile types
├── tile_decode.rs (361 lines) - Tile decoding
└── tile_disk.rs (204 lines) - Disk cache
```

## Usage

### Basic Usage

```rust
use makepad_widgets::*;
use nigig_map::MapView;

live_design!{
    use mod.prelude.widgets.*;
    
    MyApp = {{App}} {
        ui: <Window> {
            map_view = <MapView> {
                center_lon: 36.8219,  // Nairobi
                center_lat: -1.2921,
                zoom: 14.0,
                min_zoom: 10.0,
                max_zoom: 18.0,
                use_local_mbtiles: true,
                local_mbtiles_path: "kenya-shortbread-1.0.mbtiles",
            }
        }
    }
}
```

### Offline Maps (MBTiles)

```rust
map_view = <MapView> {
    use_local_mbtiles: true,
    local_mbtiles_path: "kenya-shortbread-1.0.mbtiles",
    use_network: false,
}
```

### Online Maps (Overpass API)

```rust
map_view = <MapView> {
    use_local_mbtiles: false,
    use_network: true,
}
```

### Style Customization

```rust
map_view = <MapView> {
    style_light: MapThemeStyle {
        background: #xeaf0f5,
        label: #x1f2937,
        
        MapFillRule { group: "building", color: #xd7dee7 },
        MapFillRule { group: "water", color: #xbfe7fb },
        
        MapRoadRule {
            kind: "motorway",
            sort_rank: 700,
            casing_color: #xc1782f,
            casing_width: 6.2,
            center_color: #xffc266,
            center_width: 4.2,
        },
    },
}
```

### Programmatic Control

```rust
// Load style from JSON
map_view.load_style_json(style_json)?;

// Enable/disable render passes
map_view.enable_pass(PassType::Label);
map_view.disable_pass(PassType::POI);

// Set zoom range for a pass
map_view.set_pass_zoom_range(PassType::Label, 14.0, 20.0);

// Access render graph
let graph = map_view.render_graph();
```

## API Reference

### MapView

The main map widget.

#### Properties

- `center_lon: f64` - Center longitude (default: 4.9041)
- `center_lat: f64` - Center latitude (default: 52.3676)
- `zoom: f64` - Zoom level (default: 14.0)
- `min_zoom: f64` - Minimum zoom level (default: 11.0)
- `max_zoom: f64` - Maximum zoom level (default: 17.0)
- `dark_theme: bool` - Use dark theme (default: false)
- `use_network: bool` - Enable network requests (default: true)
- `use_local_mbtiles: bool` - Use local MBTiles (default: true)
- `local_mbtiles_path: String` - Path to MBTiles file
- `local_tile_cache_dir: String` - Path to tile cache directory
- `style_light: MapThemeStyle` - Light theme style
- `style_dark: MapThemeStyle` - Dark theme style

#### Methods

- `load_style_json(json_str: &str) -> Result<(), String>` - Load style from JSON
- `recompile_style_for_zoom(zoom: f64)` - Recompile style for zoom level
- `render_graph() -> &RenderGraph` - Get render graph reference
- `enable_pass(pass_type: PassType)` - Enable render pass
- `disable_pass(pass_type: PassType)` - Disable render pass
- `set_pass_zoom_range(pass_type: PassType, min_zoom: f64, max_zoom: f64)` - Set zoom range for pass

### MapThemeStyle

Style configuration for map rendering.

#### Properties

- `background: Vec4f` - Background color
- `label: Vec4f` - Label color
- `status_text: Vec4f` - Status text color
- `fill_rules: Vec<MapFillRule>` - Fill rules
- `road_rules: Vec<MapRoadRule>` - Road rules
- `waterway_rules: Vec<MapWaterwayRule>` - Waterway rules
- `rail_rules: Vec<MapRailRule>` - Rail rules

### MapFillRule

Fill rule for polygon features.

#### Properties

- `group: String` - Feature group (e.g., "building", "water")
- `value: String` - Feature value (e.g., "residential", "yes")
- `color: Vec4f` - Fill color

### MapRoadRule

Road rendering rule.

#### Properties

- `kind: String` - Road kind (e.g., "motorway", "primary")
- `sort_rank: i32` - Sort rank (higher = drawn on top)
- `casing_color: Vec4f` - Casing color
- `casing_width: f32` - Casing width
- `casing_shape_id: f32` - Casing shape ID
- `center_color: Vec4f` - Center color
- `center_width: f32` - Center width
- `center_shape_id: f32` - Center shape ID

### PassType

Render pass types.

- `PassType::Fill` - Fill pass (polygons)
- `PassType::Stroke` - Stroke pass (lines)
- `PassType::Label` - Label pass (text)
- `PassType::POI` - POI pass (points of interest)

## Performance

The map renderer is optimized for 60 FPS rendering:

- **Efficient Caching**: LRU cache with configurable size (default: 640 tiles)
- **Async Loading**: Tiles loaded asynchronously in background threads
- **Deferred Eviction**: Tile eviction deferred to prevent use-after-free
- **Optimized Tessellation**: Efficient geometry tessellation with signed area calculation
- **Label Placement**: Intelligent label placement with collision detection

## Testing

The map crate has comprehensive test coverage (80%+):

```bash
# Run all tests
cargo test -p nigig-map

# Run specific module tests
cargo test -p nigig-map mvt_parser
cargo test -p nigig-map tessellation
cargo test -p nigig-map style
cargo test -p nigig-map overpass_parser
cargo test -p nigig-map asset_loader
```

## Dependencies

- `makepad-widgets` - Makepad widget framework
- `makepad-mbtile-reader` - MBTiles file reader
- `makepad-fast-inflate` - Fast decompression

## License

This project is licensed under the MIT License.

## Contributing

Contributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Authors

- Nigig Team

## Acknowledgments

- Map data from OpenStreetMap contributors
- MBTiles format from MapBox
- Makepad framework for widget system