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
• Basic Usage
• Offline Maps
• Online Maps
• Style Customization
• Programmatic Control
• Performance Tuning
• Troubleshooting

Getting Started

Prerequisites

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

Installation

Add the following to your Cargo.toml:

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

Basic Example

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

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:

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 or Geofabrik
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

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:

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

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:

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:

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:

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:

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:

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:

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:

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

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

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

Setting Zoom Range for Passes

// 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

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

Recompiling Style for Zoom

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

Performance Tuning

Cache Size

Configure tile cache size:

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

Network Configuration

Configure network requests:

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:

// 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

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

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

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 - Main documentation
• API.md - API reference
• ARCHITECTURE.md - Architecture documentation