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

Nigig Map API Reference

Complete API reference for the Nigig Map crate.

Modules

nigig_map

Main module containing the map widget and related types.

Re-exports

pub use makepad_fast_inflate;
pub use makepad_mbtile_reader;

Submodules

• geometry - Geometry types and transformations
• label - Label extraction and placement
• label_state - Label placement state
• renderer - Rendering logic
• render_graph - Render graph execution
• scheduler - Tile loading scheduler
• sprite - Sprite rendering
• style - Style compilation
• tile - Tile types
• tile_decode - Tile decoding
• tile_disk - Disk cache
• viewport - Viewport state
• mvt_parser - MVT tile parsing
• overpass_parser - Overpass API parsing
• asset_loader - Asset loading

Types

MapView

Main map widget for rendering maps.

#[derive(Script, Widget)]
pub struct MapView {
    // ... fields ...
}

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
style_light	MapThemeStyle	(default)	Light theme style
style_dark	MapThemeStyle	(default)	Dark theme style

Methods

load_style_json

Load style from JSON string.

pub fn load_style_json(&mut self, json_str: &str) -> Result<(), String>

Parameters:

• json_str - JSON string containing Mapbox GL style

Returns:

• Ok(()) on success
• Err(String) on error

Example:

let style_json = r#"{"version": 8, "sources": {...}, "layers": [...]}"#;
map_view.load_style_json(style_json)?;

recompile_style_for_zoom

Recompile style for specific zoom level.

pub fn recompile_style_for_zoom(&mut self, zoom: f64)

Parameters:

• zoom - Zoom level to compile for

Example:

map_view.recompile_style_for_zoom(14.0);

render_graph

Get reference to render graph.

pub fn render_graph(&self) -> &RenderGraph

Returns:

• Reference to RenderGraph

Example:

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

enable_pass

Enable a render pass.

pub fn enable_pass(&mut self, pass_type: PassType)

Parameters:

• pass_type - Pass type to enable

Example:

map_view.enable_pass(PassType::Label);

disable_pass

Disable a render pass.

pub fn disable_pass(&mut self, pass_type: PassType)

Parameters:

• pass_type - Pass type to disable

Example:

map_view.disable_pass(PassType::POI);

set_pass_zoom_range

Set zoom range for a render pass.

pub fn set_pass_zoom_range(&mut self, pass_type: PassType, min_zoom: f64, max_zoom: f64)

Parameters:

• pass_type - Pass type to configure
• min_zoom - Minimum zoom level (inclusive)
• max_zoom - Maximum zoom level (inclusive)

Example:

map_view.set_pass_zoom_range(PassType::Label, 14.0, 20.0);

MapThemeStyle

Style configuration for map rendering.

#[derive(Script, ScriptHook, Clone, Default)]
pub struct MapThemeStyle {
    pub background: Vec4f,
    pub label: Vec4f,
    pub status_text: Vec4f,
    pub fill_rules: Vec<MapFillRule>,
    pub road_rules: Vec<MapRoadRule>,
    pub waterway_rules: Vec<MapWaterwayRule>,
    pub rail_rules: Vec<MapRailRule>,
}

Properties

Property	Type	Default	Description
background	Vec4f	#xddd7cc	Background color
label	Vec4f	#x000000	Label color
status_text	Vec4f	#xdee9f4	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.

#[derive(Script, ScriptHook, Clone, Default)]
pub struct MapFillRule {
    pub group: String,
    pub value: String,
    pub color: Vec4f,
}

Properties

Property	Type	Default	Description
group	String	""	Feature group (e.g., "building", "water")
value	String	""	Feature value (e.g., "residential", "yes")
color	Vec4f	#x000000	Fill color

Example:

MapFillRule {
    group: "building",
    value: "yes",
    color: #xd7dee7,
}

MapRoadRule

Road rendering rule.

#[derive(Script, ScriptHook, Clone, Default)]
pub struct MapRoadRule {
    pub kind: String,
    pub sort_rank: i32,
    pub casing_color: Vec4f,
    pub casing_width: f32,
    pub casing_shape_id: f32,
    pub center_color: Vec4f,
    pub center_width: f32,
    pub center_shape_id: f32,
}

Properties

Property	Type	Default	Description
kind	String	""	Road kind (e.g., "motorway", "primary")
sort_rank	i32	0	Sort rank (higher = drawn on top)
casing_color	Vec4f	#x000000	Casing color
casing_width	f32	0.0	Casing width
casing_shape_id	f32	0.0	Casing shape ID
center_color	Vec4f	#x000000	Center color
center_width	f32	0.0	Center width
center_shape_id	f32	0.0	Center shape ID

Example:

MapRoadRule {
    kind: "motorway",
    sort_rank: 700,
    casing_color: #xc1782f,
    casing_width: 6.2,
    casing_shape_id: 0.0,
    center_color: #xffc266,
    center_width: 4.2,
    center_shape_id: 0.0,
}

MapWaterwayRule

Waterway rendering rule.

#[derive(Script, ScriptHook, Clone, Default)]
pub struct MapWaterwayRule {
    pub kind: String,
    pub sort_rank: i32,
    pub casing_color: Vec4f,
    pub casing_width: f32,
    pub casing_shape_id: f32,
    pub center_color: Vec4f,
    pub center_width: f32,
    pub center_shape_id: f32,
}

Properties

Property	Type	Default	Description
kind	String	""	Waterway kind (e.g., "river", "stream")
sort_rank	i32	0	Sort rank (higher = drawn on top)
casing_color	Vec4f	#x000000	Casing color
casing_width	f32	0.0	Casing width
casing_shape_id	f32	0.0	Casing shape ID
center_color	Vec4f	#x000000	Center color
center_width	f32	0.0	Center width
center_shape_id	f32	0.0	Center shape ID

MapRailRule

Rail rendering rule.

#[derive(Script, ScriptHook, Clone, Default)]
pub struct MapRailRule {
    pub sort_rank: i32,
    pub casing_color: Vec4f,
    pub casing_width: f32,
    pub casing_shape_id: f32,
    pub center_color: Vec4f,
    pub center_width: f32,
    pub center_shape_id: f32,
}

Properties

Property	Type	Default	Description
sort_rank	i32	0	Sort rank (higher = drawn on top)
casing_color	Vec4f	#x000000	Casing color
casing_width	f32	0.0	Casing width
casing_shape_id	f32	0.0	Casing shape ID
center_color	Vec4f	#x000000	Center color
center_width	f32	0.0	Center width
center_shape_id	f32	0.0	Center shape ID

PassType

Render pass types.

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum PassType {
    Fill,
    Stroke,
    Label,
    POI,
}

Variants

• Fill - Fill pass (polygons)
• Stroke - Stroke pass (lines)
• Label - Label pass (text)
• POI - POI pass (points of interest)

TileKey

Tile key for identifying tiles.

#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct TileKey {
    pub z: u32,
    pub x: u32,
    pub y: u32,
}

Properties

Property	Type	Description
z	u32	Zoom level
x	u32	X coordinate
y	u32	Y coordinate

TileLoadState

Tile loading state.

#[derive(Debug)]
pub enum TileLoadState {
    Loading,
    Ready {
        fill_geometry: Option<Geometry>,
        stroke_geometry: Option<Geometry>,
        feature_count: usize,
        labels: Vec<TileLabel>,
        pois: Vec<PoiFeature>,
    },
    Failed {
        error: String,
    },
}

Variants

• Loading - Tile is being loaded
• Ready - Tile is ready with geometry and labels
• Failed - Tile failed to load

TileEntry

Tile entry in cache.

pub struct TileEntry {
    pub state: TileLoadState,
    pub last_used: u64,
    pub attempts: u8,
}

Properties

Property	Type	Description
state	TileLoadState	Tile loading state
last_used	u64	Last used timestamp
attempts	u8	Number of load attempts

RenderGraph

Render graph for managing render passes.

pub struct RenderGraph {
    passes: Vec<RenderPass>,
}

Methods

passes

Get list of render passes.

pub fn passes(&self) -> &[RenderPass]

Returns:

• Slice of render passes

ViewportState

Viewport state for managing view transformations.

pub struct ViewportState {
    pub center: Vec2d,
    pub zoom: f64,
    pub min_zoom: f64,
    pub max_zoom: f64,
    pub rotation: f64,
}

Properties

Property	Type	Description
center	Vec2d	Center coordinates
zoom	f64	Zoom level
min_zoom	f64	Minimum zoom level
max_zoom	f64	Maximum zoom level
rotation	f64	Rotation angle

Methods

view_zoom

Get clamped zoom level.

pub fn view_zoom(&self) -> f64

Returns:

• Clamped zoom level

world_size

Get world size at current zoom.

pub fn world_size(&self) -> f64

Returns:

• World size in pixels

center_world

Get center in world coordinates.

pub fn center_world(&self) -> Vec2d

Returns:

• Center in world coordinates

map_offset

Get map offset for rendering.

pub fn map_offset(&self) -> Vec2f

Returns:

• Map offset in pixels

apply_pinch

Apply pinch gesture.

pub fn apply_pinch(
    &mut self,
    initial_zoom: f64,
    initial_center: Vec2d,
    initial_distance: f64,
    current_distance: f64,
    midpoint: Vec2d,
)

Parameters:

• initial_zoom - Initial zoom level
• initial_center - Initial center
• initial_distance - Initial pinch distance
• current_distance - Current pinch distance
• midpoint - Pinch midpoint

apply_scroll

Apply scroll gesture.

pub fn apply_scroll(&mut self, scroll: f64, anchor: Vec2d)

Parameters:

• scroll - Scroll amount
• anchor - Scroll anchor point

visible_tile_keys

Get visible tile keys.

pub fn visible_tile_keys(&self) -> Vec<TileKey>

Returns:

• List of visible tile keys

TileCache

Tile cache for storing loaded tiles.

pub struct TileCache {
    tiles: HashMap<TileKey, TileEntry>,
    max_tiles: usize,
    frame_counter: u64,
}

Methods

get

Get tile from cache.

pub fn get(&self, key: TileKey) -> Option<&TileEntry>

Parameters:

• key - Tile key

Returns:

• Tile entry if found

insert_loading

Insert tile as loading.

pub fn insert_loading(&mut self, key: TileKey, state: TileLoadState)

Parameters:

• key - Tile key
• state - Tile load state

insert_ready

Insert tile as ready.

pub fn insert_ready(&mut self, cx: &mut Cx, key: TileKey, buffers: TileBuffers)

Parameters:

• cx - Makepad context
• key - Tile key
• buffers - Tile buffers

mark_failed

Mark tile as failed.

pub fn mark_failed(&mut self, key: TileKey, error: String)

Parameters:

• key - Tile key
• error - Error message

evict

Evict tiles from cache.

pub fn evict(&mut self, cx: &mut Cx, visible: &HashSet<TileKey>, target_zoom: u32)

Parameters:

• cx - Makepad context
• visible - Visible tile keys
• target_zoom - Target zoom level

TileScheduler

Tile loading scheduler.

pub struct TileScheduler {
    visible_tiles: Vec<TileKey>,
    pending_tiles: HashSet<TileKey>,
    current_generation: u64,
}

Methods

schedule

Schedule tile loading.

pub fn schedule(
    &mut self,
    cache: &TileCache,
    config: &SchedulerConfig,
    style_epoch: u64,
) -> Vec<TileAction>

Parameters:

• cache - Tile cache
• config - Scheduler configuration
• style_epoch - Style epoch

Returns:

• List of tile actions

update_visible

Update visible tiles.

pub fn update_visible(&mut self, viewport: &mut ViewportState) -> bool

Parameters:

• viewport - Viewport state

Returns:

• True if visible tiles changed

SchedulerConfig

Scheduler configuration.

pub struct SchedulerConfig {
    pub use_network: bool,
    pub use_local_mbtiles: bool,
    pub max_pending_requests: usize,
    pub max_local_tile_batch: usize,
    pub max_tile_retries: u8,
    pub local_mbtiles_path: String,
    pub local_tile_cache_dir: String,
}

Properties

Property	Type	Default	Description
use_network	bool	true	Enable network requests
use_local_mbtiles	bool	true	Use local MBTiles
max_pending_requests	usize	6	Maximum pending requests
max_local_tile_batch	usize	10	Maximum local tile batch size
max_tile_retries	u8	3	Maximum tile retries
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

TileAction

Tile loading action.

pub enum TileAction {
    LoadLocalBatch {
        mbtiles_path: PathBuf,
        cache_dir: String,
        requested: Vec<TileKey>,
        style_epoch: u64,
        generation: u64,
    },
    LoadFromDiskCache {
        tile_key: TileKey,
        cache_path: PathBuf,
        style_epoch: u64,
        generation: u64,
    },
    LoadFromNetwork {
        request_id: LiveId,
        http_request: HttpRequest,
        tile_key: TileKey,
        generation: u64,
    },
    Nothing,
}

Variants

• LoadLocalBatch - Load batch of tiles from local MBTiles
• LoadFromDiskCache - Load tile from disk cache
• LoadFromNetwork - Load tile from network
• Nothing - No action

Functions

Geometry Functions

lon_lat_to_normalized

Convert lon/lat to normalized coordinates.

pub fn lon_lat_to_normalized(lon: f64, lat: f64) -> Vec2d

Parameters:

• lon - Longitude
• lat - Latitude

Returns:

• Normalized coordinates (0-1)

normalized_to_lon_lat

Convert normalized coordinates to lon/lat.

pub fn normalized_to_lon_lat(normalized: Vec2d) -> (f64, f64)

Parameters:

• normalized - Normalized coordinates (0-1)

Returns:

• (longitude, latitude)

tile_world_size_zoom

Get tile world size at zoom level.

pub fn tile_world_size_zoom(zoom: f64) -> f64

Parameters:

• zoom - Zoom level

Returns:

• Tile world size in pixels

Style Functions

fill_color_for_tags

Get fill color for tags.

pub fn fill_color_for_tags(
    tags: &HashMap<String, String>,
    theme: &CompiledMapTheme,
) -> Option<u32>

Parameters:

• tags - Feature tags
• theme - Compiled theme

Returns:

• Fill color if found

stroke_style_for_tags

Get stroke style for tags.

pub fn stroke_style_for_tags(
    tags: &HashMap<String, String>,
    theme: &CompiledMapTheme,
    zoom: u32,
) -> Option<StrokeStyle>

Parameters:

• tags - Feature tags
• theme - Compiled theme
• zoom - Zoom level

Returns:

• Stroke style if found

Label Functions

extract_way_label

Extract label from way.

pub fn extract_way_label(
    tags: &HashMap<String, String>,
    points: &[(f32, f32)],
) -> Option<TileLabel>

Parameters:

• tags - Way tags
• points - Way points

Returns:

• Tile label if found

get_label_priority

Get label priority.

pub fn get_label_priority(tags: &HashMap<String, String>) -> i32

Parameters:

• tags - Feature tags

Returns:

• Label priority

MVT Parser Functions

decode_vector_tile_payload

Decode vector tile payload.

pub fn decode_vector_tile_payload(raw: &[u8]) -> Result<Vec<u8>, String>

Parameters:

• raw - Raw tile data

Returns:

• Decoded tile data or error

parse_mvt_tile

Parse MVT tile.

pub fn parse_mvt_tile(
    tile_data: &[u8],
    tile_key: TileKey,
    builder: &mut MvtTileJsonBuilder,
) -> Result<(), String>

Parameters:

• tile_data - Tile data
• tile_key - Tile key
• builder - MVT tile JSON builder

Returns:

• Ok(()) on success or error

Overpass Parser Functions

build_tile_buffers_from_body

Build tile buffers from Overpass response body.

pub fn build_tile_buffers_from_body(
    tile_key: TileKey,
    body: &str,
    theme: &CompiledMapTheme,
) -> Result<TileBuffers, String>

Parameters:

• tile_key - Tile key
• body - Overpass response body
• theme - Compiled theme

Returns:

• Tile buffers or error

mbtiles_tile_to_overpass_response

Convert MBTiles tile to Overpass response.

pub fn mbtiles_tile_to_overpass_response(
    tile_key: TileKey,
    raw_tile_data: &[u8],
) -> Result<OverpassResponse, String>

Parameters:

• tile_key - Tile key
• raw_tile_data - Raw tile data

Returns:

• Overpass response or error

Constants

Tile Constants

pub const TILE_SIZE: f64 = 256.0;
pub const TILE_SIZE_U32: u32 = 256;
pub const TILE_BUFFER_SIZE: usize = 8;

Label Constants

pub const LABEL_PLACEMENT_MAX_ITERATIONS: usize = 100;
pub const LABEL_COLLISION_PADDING: f32 = 2.0;
pub const LABEL_MIN_DISTANCE: f32 = 10.0;

Style Constants

pub const STYLE_MAX_ZOOM: u32 = 22;
pub const STYLE_MIN_ZOOM: u32 = 0;

Error Types

ParseError

Error type for parsing errors.

#[derive(Debug)]
pub enum ParseError {
    InvalidFormat(String),
    InvalidData(String),
    IoError(std::io::Error),
}

Variants

• InvalidFormat - Invalid format error
• InvalidData - Invalid data error
• IoError - I/O error

See Also

• README.md - Main documentation
• ARCHITECTURE.md - Architecture documentation
• USER_GUIDE.md - User guide