Module picking 

Canonical picking contract for Rustial v1.0.

This module defines the stable engine-owned picking model that host applications should depend on. It exposes:

• Pick query types – PickQuery (screen, geo, or ray) with filtering options.
• Hit result types – PickHit with provenance, category, and priority.
• Layer queryability – PickableLayerKind documents which native layer families participate in normal feature picking.
• Hit provenance – HitProvenance distinguishes geometric approximation from renderer-assisted exact results.

Supported picking contract for v1.0

• Terrain – exact or near-exact surface recovery via screen-to-geo.
• Vector fill / line / circle / heatmap / fill-extrusion – CPU geometric hit-testing with tolerance.
• Symbols – collision-box-based hit-testing.
• Models – bounding-radius-based hit-testing with terrain-aware altitude.
• Raster / background / hillshade – explicitly not normal feature-pick targets. A future raster-value API may be introduced separately.

Result sorting rules

Pick results (PickResult) are sorted in two stages:

1. layer_priority (descending) – every PickHit carries a layer_priority derived from the layer’s position in the layer stack. Top-most layers receive the highest priority so the visually front-most feature appears first.

2. distance_meters (ascending, within the same priority) – when two hits share the same layer priority, the one closest to the query point wins. For point and line geometries this is the Euclidean distance in Web Mercator metres; for polygons that fully contain the query point the distance is 0.0.

Query results from query_rendered_features and the _at_screen / _at_geo / _along_ray convenience wrappers apply the same sort but only by distance_meters (ascending), because all features already come from a single layer-stack traversal in render order.

Box queries (query_rendered_features_in_box) return features in layer-stack order without distance-based sorting because every intersecting feature is equally “hit” by the rectangle.

Duplicate-suppression rules

Both point queries and box queries de-duplicate features that appear in multiple streamed-vector tile payloads (overlapping tile edges). De-duplication is keyed on the triple (source_id, source_layer, geometry_debug_string) so the same logical feature carried by two adjacent tiles is returned only once.

Symbol queries de-duplicate on (source_id, source_layer, feature_id) so a symbol that is placed on multiple tiles (due to label avoidance retries) is returned only once.

These rules guarantee stable, reproducible query results regardless of which tiles are currently loaded.

Cross-renderer parity

Both rustial-renderer-wgpu and rustial-renderer-bevy consume the same engine-owned picking surface via MapState. Both renderers expose identical pick(), pick_at_screen(), pick_at_geo(), and pick_along_ray() convenience methods that delegate to the canonical engine pipeline. The public API, result format, and prioritization rules are engine-defined and renderer-agnostic.

Regression coverage for the stable v1.0 picking surface now includes explicit tests across both CameraMode::Perspective and CameraMode::Orthographic and across both stable projections (WebMercator and Equirectangular), for both screen-coordinate and world-space-ray entry points.

Structs

PickHit

A single hit from a pick operation.

PickOptions

Filtering and behavior options for a pick operation.

PickResult

Complete result of a pick operation.

Enums

HitCategory

Broad category of a pick result.

HitProvenance

How a pick hit was resolved.

NonPickableLayerKind

Native layer families that are explicitly not normal feature-pick targets in v1.0.

PickQuery

Input for a pick operation.

PickableLayerKind

Native layer families that participate in normal feature picking.