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

# Nigig Map User Guide

User guide for using the Nigig Map widget in Makepad applications.

## Table of Contents

- [Getting Started](#getting-started)
- [Basic Usage](#basic-usage)
- [Offline Maps](#offline-maps)
- [Online Maps](#online-maps)
- [Style Customization](#style-customization)
- [Programmatic Control](#programmatic-control)
- [Performance Tuning](#performance-tuning)
- [Troubleshooting](#troubleshooting)

## Getting Started

### Prerequisites

- Rust toolchain (stable)
- Makepad framework
- Nigig Map crate

### Installation

Add the following to your `Cargo.toml`:

```toml
[dependencies]
nigig-map = { path = "../path/to/nigig-map" }
makepad-widgets = { git = "https://github.com/makepad/makepad", branch = "rik" }
```

### Basic Example

```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,
            }
        }
    }
}
```

## Basic Usage

### Creating a Map

```rust
map_view = <MapView> {
    center_lon: 36.8219,  // Longitude
    center_lat: -1.2921,  // Latitude
    zoom: 14.0,           // Zoom level (0-22)
    min_zoom: 10.0,       // Minimum zoom
    max_zoom: 18.0,       // Maximum zoom
}
```

### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `center_lon` | `f64` | 4.9041 | Center longitude |
| `center_lat` | `f64` | 52.3676 | Center latitude |
| `zoom` | `f64` | 14.0 | Zoom level |
| `min_zoom` | `f64` | 11.0 | Minimum zoom level |
| `max_zoom` | `f64` | 17.0 | Maximum zoom level |
| `dark_theme` | `bool` | false | Use dark theme |
| `use_network` | `bool` | true | Enable network requests |
| `use_local_mbtiles` | `bool` | true | Use local MBTiles |
| `local_mbtiles_path` | `String` | "local/mbtiles/kenya-shortbread-1.0.mbtiles" | Path to MBTiles file |
| `local_tile_cache_dir` | `String` | "local/tilecache_v5" | Path to tile cache directory |

### User Interactions

The map widget supports the following user interactions:

- **Pan**: Click and drag to pan the map
- **Zoom**: Scroll wheel or pinch gesture to zoom
- **Pinch**: Two-finger pinch to zoom in/out

## Offline Maps

### Using MBTiles Files

MBTiles files provide offline map data. To use MBTiles:

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

### Preparing MBTiles Files

1. Download MBTiles file from [OpenMapTiles](https://openmaptiles.org/) or [Geofabrik](https://download.geofabrik.de/)
2. Place the file in your application's data directory
3. Set `local_mbtiles_path` to the file path

### Supported MBTiles Formats

- Vector tiles (MVT format)
- Zoom levels 0-14 (typical)
- OpenMapTiles schema

### Example: Kenya Offline Map

```rust
map_view = <MapView> {
    center_lon: 36.8219,  // Nairobi
    center_lat: -1.2921,
    zoom: 14.0,
    use_local_mbtiles: true,
    local_mbtiles_path: "kenya-shortbread-1.0.mbtiles",
    use_network: false,
}
```

## Online Maps

### Using Overpass API

The Overpass API provides online map data from OpenStreetMap:

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

### Network Requirements

- Internet connection required
- Overpass API endpoint: https://overpass-api.de/api/interpreter
- Rate limiting: 2 requests per second (configurable)

### Example: Online Map with Fallback

```rust
map_view = <MapView> {
    center_lon: 36.8219,
    center_lat: -1.2921,
    zoom: 14.0,
    use_local_mbtiles: true,
    use_network: true,
    local_mbtiles_path: "kenya-shortbread-1.0.mbtiles",
}
```

## Style Customization

### MapThemeStyle

The map style is configured using `MapThemeStyle`:

```rust
map_view = <MapView> {
    style_light: MapThemeStyle {
        background: #xeaf0f5,
        label: #x1f2937,
        status_text: #x64748b,
        
        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,
        },
    },
}
```

### Fill Rules

Fill rules define colors for polygon features:

```rust
MapFillRule {
    group: "building",      // Feature group
    value: "yes",           // Feature value (optional)
    color: #xd7dee7,        // Fill color
}
```

**Supported groups:**
- `building` - Buildings
- `water` - Water bodies
- `landuse` - Land use areas
- `leisure` - Leisure areas

### Road Rules

Road rules define road rendering:

```rust
MapRoadRule {
    kind: "motorway",           // Road kind
    sort_rank: 700,             // Sort rank (higher = drawn on top)
    casing_color: #xc1782f,     // Casing color
    casing_width: 6.2,          // Casing width
    casing_shape_id: 0.0,       // Casing shape ID
    center_color: #xffc266,     // Center color
    center_width: 4.2,          // Center width
    center_shape_id: 0.0,       // Center shape ID
}
```

**Supported road kinds:**
- `motorway` - Motorways
- `trunk` - Trunk roads
- `primary` - Primary roads
- `secondary` - Secondary roads
- `tertiary` - Tertiary roads
- `residential` - Residential roads
- `service` - Service roads
- `cycleway` - Cycle paths
- `footway` - Foot paths
- `path` - Generic paths

### Waterway Rules

Waterway rules define waterway rendering:

```rust
MapWaterwayRule {
    kind: "river",              // Waterway kind
    sort_rank: 140,             // Sort rank
    casing_color: #x2f6188,     // Casing color
    casing_width: 1.5,          // Casing width
    casing_shape_id: 0.0,       // Casing shape ID
    center_color: #x4f93c8,     // Center color
    center_width: 1.22,         // Center width
    center_shape_id: 0.0,       // Center shape ID
}
```

**Supported waterway kinds:**
- `river` - Rivers
- `stream` - Streams
- `canal` - Canals

### Rail Rules

Rail rules define railway rendering:

```rust
MapRailRule {
    sort_rank: 180,             // Sort rank
    casing_color: #x3f4650,     // Casing color
    casing_width: 0.96,         // Casing width
    casing_shape_id: 0.0,       // Casing shape ID
    center_color: #x707783,     // Center color
    center_width: 0.62,         // Center width
    center_shape_id: 10.0,      // Center shape ID (10.0 = dashed)
}
```

### Dark Theme

Configure dark theme style:

```rust
map_view = <MapView> {
    dark_theme: true,
    
    style_dark: MapThemeStyle {
        background: #x161b22,
        label: #xe5eaf1,
        status_text: #x94a3b8,
        
        MapFillRule { group: "building", color: #x383d46 },
        MapFillRule { group: "water", color: #x204f74 },
        
        MapRoadRule {
            kind: "motorway",
            sort_rank: 700,
            casing_color: #x8f6937,
            casing_width: 6.0,
            center_color: #xd29b54,
            center_width: 4.0,
        },
    },
}
```

### Loading Style from JSON

Load Mapbox GL style from JSON:

```rust
let style_json = r#"
{
    "version": 8,
    "sources": {
        "openmaptiles": {
            "type": "vector",
            "url": "https://api.maptiler.com/tiles/v3/tiles.json?key=YOUR_KEY"
        }
    },
    "layers": [
        {
            "id": "water",
            "type": "fill",
            "source": "openmaptiles",
            "source-layer": "water",
            "paint": {
                "fill-color": "#bfe7fb"
            }
        }
    ]
}
"#;

map_view.load_style_json(style_json)?;
```

## Programmatic Control

### Enabling/Disabling Passes

```rust
// Enable label rendering
map_view.enable_pass(PassType::Label);

// Disable POI rendering
map_view.disable_pass(PassType::POI);
```

### Setting Zoom Range for Passes

```rust
// Only show labels at zoom 14-20
map_view.set_pass_zoom_range(PassType::Label, 14.0, 20.0);

// Only show POIs at zoom 15-20
map_view.set_pass_zoom_range(PassType::POI, 15.0, 20.0);
```

### Accessing Render Graph

```rust
let graph = map_view.render_graph();
println!("Number of passes: {}", graph.passes().len());
```

### Recompiling Style for Zoom

```rust
// Recompile style for zoom level 14
map_view.recompile_style_for_zoom(14.0);
```

## Performance Tuning

### Cache Size

Configure tile cache size:

```rust
// In code
let mut cache = TileCache::new(1000); // Cache up to 1000 tiles
```

### Network Configuration

Configure network requests:

```rust
let config = SchedulerConfig {
    use_network: true,
    use_local_mbtiles: true,
    max_pending_requests: 6,          // Maximum pending requests
    max_local_tile_batch: 10,         // Maximum local tile batch size
    max_tile_retries: 3,              // Maximum tile retries
    local_mbtiles_path: "kenya-shortbread-1.0.mbtiles".to_string(),
    local_tile_cache_dir: "local/tilecache_v5".to_string(),
};
```

### Performance Tips

1. **Use MBTiles for offline maps** - Faster than network requests
2. **Limit zoom range** - Reduces number of tiles to load
3. **Disable unnecessary passes** - Reduces rendering overhead
4. **Increase cache size** - Reduces tile reload times
5. **Use appropriate tile batch size** - Balances memory and performance

### Performance Monitoring

Monitor performance using status text:

```rust
// Status text shows:
// - Ready tiles
// - Loading tiles
// - Failed tiles
// - Retrying tiles
// - Exhausted tiles
// - Feature count
// - Label statistics
```

## Troubleshooting

### Map Not Rendering

**Problem:** Map shows blank or black screen

**Solutions:**
- Check MBTiles file exists at `local_mbtiles_path`
- Check network connection if using online maps
- Check zoom level is within `min_zoom` and `max_zoom`
- Check style is configured correctly

### Tiles Not Loading

**Problem:** Tiles show as loading but never load

**Solutions:**
- Check MBTiles file is valid
- Check network connection if using online maps
- Check tile cache directory is writable
- Check tile cache size is sufficient

### Labels Not Showing

**Problem:** Labels not visible on map

**Solutions:**
- Check label pass is enabled
- Check zoom level is within label zoom range (default: 14-20)
- Check label color is visible against background
- Check label style is configured

### Performance Issues

**Problem:** Map rendering is slow or laggy

**Solutions:**
- Reduce zoom range
- Disable unnecessary passes
- Increase cache size
- Use MBTiles instead of network requests
- Reduce label density

### Style Not Applying

**Problem:** Style changes not visible

**Solutions:**
- Check style is configured correctly
- Recompile style for current zoom: `map_view.recompile_style_for_zoom(zoom)`
- Check style rules match feature tags

## Examples

### Complete Example: Nairobi Map

```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,
                center_lat: -1.2921,
                zoom: 14.0,
                min_zoom: 10.0,
                max_zoom: 18.0,
                use_local_mbtiles: true,
                use_network: false,
                local_mbtiles_path: "kenya-shortbread-1.0.mbtiles",
                
                style_light: MapThemeStyle {
                    background: #xeaf0f5,
                    label: #x1f2937,
                    status_text: #x64748b,
                    
                    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,
                    },
                },
            }
        }
    }
}
```

### Example: Dark Theme Map

```rust
map_view = <MapView> {
    center_lon: 36.8219,
    center_lat: -1.2921,
    zoom: 14.0,
    dark_theme: true,
    
    style_dark: MapThemeStyle {
        background: #x161b22,
        label: #xe5eaf1,
        status_text: #x94a3b8,
        
        MapFillRule { group: "building", color: #x383d46 },
        MapFillRule { group: "water", color: #x204f74 },
        
        MapRoadRule {
            kind: "motorway",
            sort_rank: 700,
            casing_color: #x8f6937,
            casing_width: 6.0,
            center_color: #xd29b54,
            center_width: 4.0,
        },
    },
}
```

### Example: Online Map with Fallback

```rust
map_view = <MapView> {
    center_lon: 36.8219,
    center_lat: -1.2921,
    zoom: 14.0,
    use_local_mbtiles: true,
    use_network: true,
    local_mbtiles_path: "kenya-shortbread-1.0.mbtiles",
}
```

## See Also

- [README.md](README.md) - Main documentation
- [API.md](API.md) - API reference
- [ARCHITECTURE.md](ARCHITECTURE.md) - Architecture documentation