Crate rustial_engine 

rustial-engine

Framework-agnostic 2.5D map engine for the rustial geospatial library.

This crate owns the core logic of the map: camera control, layer management, tile fetching, terrain elevation, vector tessellation, 3D model placement, and the per-frame update loop that produces a FrameOutput consumed by renderers.

Design principles

Principle	How it is enforced
No GPU code	Zero dependency on wgpu, bevy, or any graphics API. Renderers live in separate crates.
No windowing	No winit, no event loop. Input arrives via InputEvent values pushed by the host.
No async runtime	Tile I/O uses a synchronous send/poll pattern (HttpClient, TileSource) so the engine can be embedded anywhere.
Thread-safe	All public types are Send + Sync. MapState is designed to sit behind an RwLock.
Precision	Coordinates are f64 (meters, WGS-84). Camera-relative rendering avoids f32 jitter at large Mercator values.

Module map

Module / File	Visibility	Purpose
[camera]	private	Camera, CameraConstraints, CameraController, CameraMode
[camera_animator]	private	CameraAnimator – smooth zoom, rotation, and pan momentum
[geometry]	private	OGC-style geometry model (Feature, Geometry, Polygon, …)
[input]	private	InputEvent enum (Pan, Zoom, Rotate, Resize)
interaction	public	Canonical interaction event and target types layered on top of picking
io	public	HttpClient, HttpRequest, HttpResponse, SharedHttpClient, FetchPool, DiskCache*
[layer]	private	Layer trait + LayerId
layers	public	LayerStack, TileLayer, VectorLayer, ModelLayer
[map_state]	private	MapState, FrameOutput
models	public	ModelMesh, ModelInstance, AltitudeMode
[simplify]	private	Douglas-Peucker line simplification
terrain	public	TerrainManager, TerrainConfig, elevation sources, mesh building
[tessellator]	private	Polygon triangulation + thick-line stroking
[tile_cache]	private	LRU tile cache
[tile_manager]	private	Tile request scheduling with parent-tile fallback
[tile_request_coordinator]	private	Cross-source tile request coordination and global budget allocation
[tile_source]	private	TileSource trait, TileData, TileDecoder
[tile_source_http]	private	HttpTileSource (URL-template HTTP fetcher)
geojson	public*	GeoJSON parser (behind the geojson feature flag)
style	public	Map style system – layer configuration, paint, and update logic
symbols	public	Symbol and cartography foundation – sprite atlases, placement, and collision

*Items marked with * require a Cargo feature flag.

Feature flags

Flag	Default	Description
geojson	off	Enables the GeoJSON parser (parse_geojson) and its serde/serde_json dependencies.
shapefile	off	Enables the Shapefile parser (parse_shapefile) and its shapefile dependency.
gltf	off	Enables ModelMesh::from_gltf for GLTF/GLB 3D model loading.
obj	off	Enables ModelMesh::from_obj for Wavefront OBJ 3D model loading.
disk-cache	off	Enables DiskCache for flat-file on-disk tile persistence.

Re-exported dependency

This crate depends on glam (workspace version) for matrix and vector math. The glam types appear in public signatures (e.g. FrameOutput::view_projection is a glam::DMat4). Downstream crates that interact with these values should use the same glam version declared in the workspace Cargo.toml.

Re-exports

pub extern crate self as rustial_math;

pub use interaction::InteractionButton;

pub use interaction::InteractionEvent;

pub use interaction::InteractionEventKind;

pub use interaction::InteractionModifiers;

pub use interaction::InteractionTarget;

pub use interaction::InteractionTargetKind;

pub use interaction::PointerKind;

pub use interaction::ScreenPoint;

pub use interaction_manager::InteractionConfig;

pub use interaction_manager::InteractionManager;

pub use expression::BoolExpression;

pub use expression::ExprEvalContext;

pub use expression::Expression;

pub use expression::NumericExpression;

pub use expression::StringExpression;

pub use layers::BackgroundLayer;

pub use layers::CallbackFrameProvider;

pub use layers::CircleInstanceData;

pub use layers::DynamicImageOverlayLayer;

pub use layers::FrameData;

pub use layers::FrameProvider;

pub use layers::FrameProviderFactory;

pub use layers::HillshadeLayer;

pub use layers::HillshadeParams;

pub use layers::ImageOverlayData;

pub use layers::ImageOverlayLayer;

pub use layers::LayerStack;

pub use layers::ModelLayer;

pub use layers::PatternImage;

pub use layers::TileLayer;

pub use layers::VectorLayer;

pub use layers::VectorMeshData;

pub use layers::VectorRenderMode;

pub use layers::VectorStyle;

pub use style::atmospheric_clear_color;

pub use style::circle_style_with_state;

pub use style::compute_fog;

pub use style::compute_lighting;

pub use style::compute_shadow_cascades;

pub use style::compute_sky;

pub use style::fill_extrusion_style_with_state;

pub use style::fill_style_with_state;

pub use style::heatmap_style_with_state;

pub use style::line_style_with_state;

pub use style::symbol_style_with_state;

pub use style::vector_style_with_state;

pub use style::AmbientLight;

pub use style::BackgroundStyleLayer;

pub use style::CanvasSource;

pub use style::CircleStyleLayer;

pub use style::ComputedFog;

pub use style::ComputedLighting;

pub use style::ComputedShadow;

pub use style::ComputedSky;

pub use style::DirectionalLight;

pub use style::FillExtrusionStyleLayer;

pub use style::FillStyleLayer;

pub use style::FogConfig;

pub use style::FromFeatureStateProperty;

pub use style::GeoJsonSource;

pub use style::HeatmapStyleLayer;

pub use style::HillshadeStyleLayer;

pub use style::ImageSource;

pub use style::LayerTransitionState;

pub use style::LightConfig;

pub use style::LightingMode;

pub use style::LineStyleLayer;

pub use style::MapStyle;

pub use style::ModelSource;

pub use style::ModelStyleLayer;

pub use style::RasterSource;

pub use style::RasterStyleLayer;

pub use style::ResolvedTransitions;

pub use style::ShadowConfig;

pub use style::SkyConfig;

pub use style::SkyType;

pub use style::StyleDocument;

pub use style::StyleError;

pub use style::StyleEvalContext;

pub use style::StyleEvalContextFull;

pub use style::StyleLayer;

pub use style::StyleLayerId;

pub use style::StyleLayerMeta;

pub use style::StyleProjection;

pub use style::StyleSource;

pub use style::StyleSourceId;

pub use style::StyleSourceKind;

pub use style::StyleValue;

pub use style::SymbolStyleLayer;

pub use style::TerrainSource;

pub use style::TransitionSpec;

pub use style::Transitioning;

pub use style::VectorStyleLayer;

pub use style::VectorTileSource;

pub use style::VideoSource;

pub use style_json::parse_style_json;

pub use style_json::StyleSourceRegistry;

pub use style_json::StyleSpecDocument;

pub use style_json::StyleSpecError;

pub use style_json::StyleSpecLayer;

pub use style_json::StyleSpecLayerType;

pub use style_json::StyleSpecProjection;

pub use style_json::StyleSpecProjectionType;

pub use style_json::StyleSpecSource;

pub use style_json::StyleSpecSourceType;

pub use style_json::StyleSpecTerrain;

pub use style_json::StyleSpecTransition;

pub use event_emitter::EventEmitter;

pub use event_emitter::ListenerId;

pub use loading_placeholder::LoadingPlaceholder;

pub use loading_placeholder::PlaceholderGenerator;

pub use loading_placeholder::PlaceholderStyle;

pub use regression::TilePipelineRegressionEvaluation;

pub use regression::TilePipelineRegressionParseError;

pub use regression::TilePipelineRegressionSample;

pub use regression::TilePipelineRegressionSummary;

pub use regression::TilePipelineRegressionThresholds;

pub use regression::TilePipelineRegressionViolation;

pub use regression::TILE_PIPELINE_REGRESSION_CSV_HEADER;

pub use cluster::ClusterOptions;

pub use cluster::PointCluster;

pub use gesture::GestureRecognizer;

pub use geojson::parse_geojson;

pub use geojson::GeoJsonError;

pub use shapefile_parser::parse_shapefile;

pub use shapefile_parser::ShapefileError;

pub use geometry_ops::bearing;

pub use geometry_ops::geometry_bbox;

pub use geometry_ops::geometry_centroid;

pub use geometry_ops::initial_bearing;

pub use geometry_ops::interpolate_great_circle;

pub use geometry_ops::linestring_length;

pub use geometry_ops::polygon_area;

pub use geometry_ops::ring_area;

pub use io::FetchPool;

pub use io::HttpClient;

pub use io::HttpRequest;

pub use io::HttpResponse;

pub use io::SharedHttpClient;

pub use io::DiskCache;

pub use io::DiskCacheError;

pub use terrain::build_terrain_descriptor;

pub use terrain::build_terrain_descriptor_with_source;

pub use terrain::build_terrain_mesh;

pub use terrain::build_terrain_mesh_with_source;

pub use terrain::elevation_region_in_texture_space;

pub use terrain::expand_with_clamped_border;

pub use terrain::interior_dims;

pub use terrain::materialize_terrain_mesh;

pub use terrain::patch_border_edge;

pub use terrain::patch_changed_tiles;

pub use terrain::prepare_hillshade_raster;

pub use terrain::skirt_height;

pub use terrain::BackfillState;

pub use terrain::ElevationSource;

pub use terrain::ElevationSourceDiagnostics;

pub use terrain::ElevationSourceFailureDiagnostics;

pub use terrain::FlatElevationSource;

pub use terrain::HttpElevationSource;

pub use terrain::PreparedHillshadeRaster;

pub use terrain::QuantizedMeshSource;

pub use terrain::TerrainConfig;

pub use terrain::TerrainDiagnostics;

pub use terrain::TerrainElevationTexture;

pub use terrain::TerrainError;

pub use terrain::TerrainManager;

pub use terrain::TerrainMeshData;

pub use terrain::TerrainRgbEncoding;

pub use terrain::NEIGHBOR_OFFSETS;

pub use models::AltitudeMode;

pub use models::ModelInstance;

pub use models::ModelLoadError;

pub use models::ModelMesh;

pub use symbols::cross_tile_index::CrossTileSymbolIndex;

pub use symbols::cross_tile_index::SymbolCandidateEntry;

pub use symbols::layout_symbol_glyphs;

pub use symbols::GlyphAtlas;

pub use symbols::GlyphAtlasEntry;

pub use symbols::GlyphKey;

pub use symbols::GlyphProvider;

pub use symbols::GlyphQuad;

pub use symbols::GlyphRaster;

pub use symbols::ImageManager;

pub use symbols::PlacedSymbol;

pub use symbols::ProceduralGlyphProvider;

pub use symbols::SpriteImage;

pub use symbols::SpriteSheet;

pub use symbols::SymbolAnchor;

pub use symbols::SymbolAssetDependencies;

pub use symbols::SymbolAssetRegistry;

pub use symbols::SymbolCandidate;

pub use symbols::SymbolCollisionBox;

pub use symbols::SymbolIconTextFit;

pub use symbols::SymbolPlacement;

pub use symbols::SymbolPlacementConfig;

pub use symbols::SymbolPlacementEngine;

pub use symbols::SymbolTextJustify;

pub use symbols::SymbolTextTransform;

pub use symbols::SymbolWritingMode;

pub use query::geometry_intersects_bbox;

pub use query::FeatureState;

pub use query::FeatureStateId;

pub use query::GeoBBox;

pub use query::QueriedFeature;

pub use query::QueryOptions;

pub use picking::HitCategory;

pub use picking::HitProvenance;

pub use picking::NonPickableLayerKind;

pub use picking::PickHit;

pub use picking::PickOptions;

pub use picking::PickQuery;

pub use picking::PickResult;

pub use picking::PickableLayerKind;

pub use visualization::ColorRamp;

pub use visualization::ColorStop;

pub use visualization::ColumnInstance;

pub use visualization::ColumnInstanceSet;

pub use visualization::ExtrusionParams;

pub use visualization::GeoGrid;

pub use visualization::GridExtrusionLayer;

pub use visualization::GridScalarLayer;

pub use visualization::InstancedColumnLayer;

pub use visualization::LabeledStop;

pub use visualization::LegendSpec;

pub use visualization::NormalizationMode;

pub use visualization::PointCloudLayer;

pub use visualization::PointInstance;

pub use visualization::PointInstanceSet;

pub use visualization::ScalarField2D;

pub use visualization::VisualizationOverlay;

pub use image_compare::compute_rmse;

pub use image_compare::count_differing_pixels;

pub use image_compare::differing_pixel_fraction;

pub use tilejson::parse_tilejson;

pub use tilejson::parse_tilejson_value;

pub use tilejson::TileJson;

pub use tilejson::TileJsonError;

pub use tilejson::TileScheme;

pub use tilejson::VectorLayerMeta;

pub use mvt::decode_mvt;

pub use mvt::DecodedVectorTile;

pub use mvt::MvtDecodeOptions;

pub use mvt::MvtError;

pub use async_data::partition_features_by_tile;

pub use async_data::AsyncVisualizationPipeline;

pub use async_data::DataTaskPool;

pub use async_data::DataTaskResultReceiver;

pub use async_data::MvtDecodeOutput;

pub use async_data::TerrainCacheKey;

pub use async_data::TerrainTaskInput;

pub use async_data::TerrainTaskOutput;

pub use async_data::ThreadDataTaskPool;

pub use async_data::VectorBucketKey;

pub use async_data::VectorCacheKey;

pub use async_data::VectorTaskInput;

pub use async_data::VectorTaskOutput;

pub use async_data::VisualizationTaskOutput;

Modules

async_data

Async retained data pipeline (worker-equivalent architecture.

cluster

Point clustering engine (supercluster-equivalent).

event_emitter

Callback-based event subscription for MapState.

expression

Typed expression engine for data-driven style evaluation.

geojson

GeoJSON parser.

geometry_ops

Geometry operations – spatial computations on geographic geometries

gesture

Multi-touch gesture recognizer

image_compare

Image comparison utilities for cross-renderer parity tests.

interaction

Canonical interaction event and target types for Rustial.

interaction_manager

Engine-owned interaction manager that automates hover, leave, click, and selection lifecycle bookkeeping.

io

Runtime-agnostic I/O abstractions for networking and caching.

layers

Layer system for the map engine.

loading_placeholder

Loading placeholders and skeleton rendering

models

3D model loading and placement.

mvt

Mapbox Vector Tile (MVT / PBF) binary decoder.

picking

Canonical picking contract for Rustial v1.0.

precision_invariants

Meter-Based Precision Invariants

query

Interaction and query API primitives.

regression

Tile-pipeline regression harness utilities.

shapefile_parser

Shapefile parser.

shapes

Shape generators – create geographic geometries from parameters

style

Style/runtime model for style-document-driven map construction.

style_json

JSON style-spec parsing and resolution for the style runtime.

symbols

Symbol/cartography foundations: asset dependencies and placement.

terrain

Terrain elevation subsystem.

tilejson

TileJSON metadata model for vector and raster tile sources.

visualization

Reusable geospatial visualization primitives.

Structs

Camera

The map camera state.

CameraAnimator

Drives smooth camera transitions.

CameraConstraints

Per-frame clamps applied to the camera by CameraController.

CameraController

Stateless helper that maps InputEvents to camera mutations.

CoordinatorConfig

Configuration for the cross-source request coordinator.

CoordinatorStats

Per-frame cross-source coordination diagnostics.

CoveringCamera

Camera state needed by the covering-tiles traversal.

CoveringTilesOptions

Options controlling the covering-tiles quadtree traversal.

DecodedImage

Decoded raster image data (RGBA8, row-major).

EaseToOptions

Options for the ease_to animation.

ElevationGrid

A regular grid of elevation samples aligned to a slippy-map tile.

Ellipsoid

A reference ellipsoid defined by its semi-major axis and flattening.

Equirectangular

Equirectangular projection: trivial linear mapping of lon/lat to meters.

Feature

A geographic feature: geometry + key-value properties.

FeatureCollection

A collection of Features.

FitBoundsOptions

Options for MapState::fit_bounds.

FitBoundsPadding

Padding in logical pixels for MapState::fit_bounds.

FlatTileSelectionConfig

Policy knobs for footprint-aware flat raster tile selection.

FlatTileView

Camera parameters needed to select flat raster tiles for a pitched perspective map view.

FlyToOptions

Options for the fly_to animation.

FrameOutput

Bundled per-frame snapshot produced by MapState::update for renderers.

Frustum

Six-plane view frustum extracted from a view-projection matrix.

GeoBounds

A geographic bounding box defined by its southwest and northeast corners in WGS-84 degrees.

GeoCoord

A geographic coordinate in WGS-84 (latitude / longitude in degrees, altitude in meters).

GeodesicResult

Result of the inverse geodesic problem.

Globe

Geocentric globe projection using the WGS-84 ellipsoid.

HttpTileSource

A TileSource that fetches raster tiles over HTTP.

HttpVectorTileSource

A TileSource that fetches and decodes Mapbox Vector Tiles (PBF) over HTTP.

LayerId

A globally unique, opaque identifier for a map layer.

LineString

An ordered sequence of coordinates forming a line.

MapState

The central state object consumed by renderers each frame.

MultiLineString

A collection of line strings.

MultiPoint

A collection of points.

MultiPolygon

A collection of polygons.

Plane

A plane in Hessian normal form: ax + by + cz + d = 0.

Point

A single geographic point.

Polygon

A polygon with an exterior ring and optional interior rings (holes).

PooledRasterTileSourceConfig

Renderer-agnostic configuration for a pooled HTTP raster tile source.

PooledTileSource

A TileSource that fetches tiles over HTTP with concurrency limiting and viewport-center priority ordering via FetchPool.

RasterMipChain

Full generated mip chain for an RGBA8 raster image.

RasterMipLevel

One generated mip level of an RGBA8 raster image.

RawVectorPayload

Raw (undecoded) vector tile payload.

RevalidationHint

Hints passed to TileSource::request_revalidate so that the implementation can build conditional-request headers.

StrokeLineResult

Output of stroke_line_styled.

TileCache

A fixed-capacity LRU in-memory tile cache.

TileCacheStats

Snapshot counts for the current cache state.

TileCoord

A fractional position within the tile grid at a given zoom level.

TileFreshness

Freshness metadata attached to a fetched tile payload.

TileId

A tile identifier in a slippy-map tile grid (zoom / x / y).

TileLifecycleDiagnostics

Snapshot of current lifecycle diagnostics.

TileLifecycleEvent

One lifecycle transition observed for a tile.

TileLifecycleRecord

Per-tile lifecycle record with first-observed timings.

TileManager

Orchestrates tile fetching, caching, and visible-set computation.

TileManagerCounters

Cumulative counters for long-running tile-manager diagnostics.

TilePipelineDiagnostics

Snapshot of the active tile-layer pipeline for debug/telemetry use.

TilePixelRect

Integer pixel-space crop rectangle derived from a fallback texture region.

TileRequestCoordinator

Centralises tile-request scheduling across all active sources.

TileResponse

A completed tile payload plus optional cache-freshness metadata.

TileSelectionConfig

Engine-side policy controlling visible tile selection.

TileSelectionStats

Per-frame diagnostics for the most recent tile-selection/update pass.

TileSourceDiagnostics

Optional runtime diagnostics exposed by a tile source.

TileSourceFailureDiagnostics

Optional runtime diagnostics exposed by a tile source.

TileTextureRegion

Normalized texture-space region within an actual tile image that maps to a target tile.

TouchContact

A single touch contact point.

VectorTileData

Decoded vector tile payload: per-source-layer feature collections.

VerticalPerspective

Near-sided vertical perspective projection onto a tangent plane.

VincentyConvergenceError

Error returned when a geodesic computation fails to converge.

VisibleTile

A single visible tile, either the exact tile, a parent fallback, or a child fallback (underzoom).

VisibleTileSet

The complete set of tiles that should be rendered for the current frame.

WebMercator

Web Mercator projection utilities.

WorldBounds

An axis-aligned bounding box in projected world space (meters).

WorldCoord

A position in projected world space (meters, typically EPSG:3857).

Enums

CameraMode

Projection mode for the map camera.

CameraProjection

Camera-facing map projection selection.

Geometry

Any supported geometry type (OGC Simple Features).

InputEvent

An input event that can be dispatched to the engine.

LayerKind

Discriminant for concrete layer types known to the engine.

PropertyValue

A value in a feature’s property map.

SourcePriority

Priority class for a tile source.

TileCacheEntry

State of a tile in the cache.

TileData

The payload of a fetched tile.

TileError

Error type for tile fetching operations.

TileLifecycleEventKind

Lifecycle transition kind.

TouchPhase

Phase of a touch contact’s lifecycle.

Constants

DEFAULT_RASTER_TILE_URL

Default shared raster tile URL used by built-in examples and integrations.

DEFAULT_RASTER_TILE_USER_AGENT

Default shared User-Agent header for built-in HTTP tile requests.

MAX_ZOOM

Maximum zoom level for slippy-map tiles.

PLANE_BOTTOM

Bottom frustum plane index.

PLANE_FAR

Far frustum plane index.

PLANE_LEFT

Index constant for the left frustum plane.

PLANE_NEAR

Near frustum plane index.

PLANE_RIGHT

Right frustum plane index.

PLANE_TOP

Top frustum plane index.

Traits

Layer

A named, renderable layer in the map scene.

Projection

A map projection that converts between geographic and projected coordinates.

TileDecoder

Decodes raw HTTP response bytes into a DecodedImage.

TileSource

A tile source that can fetch tiles by ID.

Functions

geo_to_tile

Convert a geographic coordinate to a fractional tile coordinate at the given zoom.

geo_to_tile_checked

Checked variant of geo_to_tile.

geodesic_destination

Solve the direct geodesic problem: given a start point, azimuth (radians, 0 = north, clockwise), and distance (meters), compute the destination point on the WGS-84 ellipsoid.

geodesic_destination_on

Solve the direct geodesic problem on an arbitrary ellipsoid.

geodesic_distance

Compute the geodesic distance and azimuths between two geographic coordinates on the WGS-84 ellipsoid using the Vincenty inverse formula.

geodesic_distance_on

Compute the geodesic distance on an arbitrary ellipsoid.

simplify_douglas_peucker

Simplify a polyline using the Douglas-Peucker algorithm.

simplify_polygon_ring

Simplify a closed polygon ring using Douglas-Peucker.

stroke_line

Expand a polyline into a thick triangle-strip ribbon.

stroke_line_styled

Expand a polyline into a thick triangle ribbon with proper line caps, line joins, per-vertex extrusion normals, and cumulative distances.

tile_bounds_world

Return the world-space bounding box (Web Mercator meters) for a tile.

tile_to_geo

Convert a tile ID (top-left corner) to the geographic coordinate of its north-west corner.

tile_xy_to_geo

Convert fractional tile coordinates to geographic.

triangulate_polygon

Triangulate a simple polygon (no holes) into a list of triangle indices.

triangulate_polygon_with_holes

Triangulate a polygon with interior rings (holes).

visible_tiles

Return all tiles that intersect the given world-space bounding box at a zoom level.

visible_tiles_checked

Checked variant of visible_tiles.

visible_tiles_covering

Return visible tiles using MapLibre-equivalent depth-first quadtree traversal with per-tile variable zoom heuristics and frustum culling.

visible_tiles_flat_view

Return visible flat raster tiles for a pitched perspective view.

visible_tiles_flat_view_capped

Return visible flat raster tiles for a pitched perspective view, capped to a maximum count and prioritised by distance to the camera target.

visible_tiles_flat_view_capped_with_config

Return visible flat raster tiles for a pitched perspective view, capped to a maximum count and prioritised by distance to the camera target, using an explicit flat-tile selection policy.

visible_tiles_flat_view_refined_capped

Return visible flat raster tiles for a pitched perspective view with an extra near-camera refinement pass, capped to a maximum count.

visible_tiles_flat_view_refined_capped_with_config

Configurable form of visible_tiles_flat_view_refined_capped.

visible_tiles_flat_view_with_config

Return visible flat raster tiles for a pitched perspective view using an explicit flat-tile selection policy.

visible_tiles_frustum

Return visible tiles by depth-first quadtree traversal with frustum culling.

visible_tiles_lod

Return tiles at multiple zoom levels based on distance from the camera.