Module visualization 

Reusable geospatial visualization primitives.

This module provides map-coupled, simulation-agnostic data structures and layer implementations for scientific and analytical overlays:

• GeoGrid – georeferenced regular grid descriptor
• ScalarField2D – grid-aligned scalar values with generation tracking
• ColorRamp / ColorStop – interpolated colour transfer function
• LegendSpec / LabeledStop – legend metadata for client-side UI
• ColumnInstance / ColumnInstanceSet – instanced column descriptors
• PointInstance / PointInstanceSet – point-cloud / scatter descriptors
• VisualizationOverlay – tagged enum for FrameOutput integration
• GridScalarLayer – flat colour grid overlay (impl Layer)
• GridExtrusionLayer – extruded grid overlay (impl Layer)
• InstancedColumnLayer – instanced column overlay (impl Layer)
• PointCloudLayer – point-cloud / scatter overlay (impl Layer)

Design

All types are pure Rust data models with no Bevy or WGPU dependencies. Renderers consume these via [FrameOutput::visualization] or by downcasting through [Layer::as_any].

Client ownership model

Rustial provides the rendering and geo-anchoring side of the visualization stack. The following concerns belong in the host application, not in the map engine:

Concern	Belongs in
Domain-specific data transforms (aggregation, filtering, binning)	Host application
Simulation adapters (CFD, traffic, weather model connectors)	Host application
Legend / colour-bar UI rendering	Host application (use LegendSpec metadata)
Time-series animation orchestration	Host application (update_values() per frame)
KPI dashboards and non-geographic widgets	Host application
Colour ramp presets for specific domains	Host application (construct ColorRamp)

Rustial provides:

Concern	Provided by engine
Geo-referenced grid/column/point placement	GeoGrid, ColumnInstance, PointInstance
GPU-accelerated rendering (flat grid, extruded grid, instanced columns, point cloud)	Both WGPU and Bevy renderers
Value-only retained updates (no GPU resource rebuild)	ScalarField2D::update_values, ColumnInstanceSet / PointInstanceSet generation tracking
CPU picking with stable pick IDs	GeoGrid::cell_at_geo, nearest-column/point picking
Legend metadata for host UI	LegendSpec
Colour transfer functions	ColorRamp / ColorStop

Retained-update contract

The visualization pipeline distinguishes two update paths:

• Value-only update: call ScalarField2D::update_values or replace the ColumnInstanceSet/PointInstanceSet with a new generation. Renderers detect the generation bump and update only the data texture or instance buffer – no vertex/index/bind-group rebuild.

• Structural update: change grid geometry, colour ramp, or layer identity. This triggers a full GPU resource rebuild.

For large datasets, prefer value-only updates to stay within the 60 FPS frame budget. Structural updates are amortised across frames but may cause a one-frame stall for very large grids.

Async preprocessing

For very large visualization structural updates (>100k cells or >50k instances), use AsyncVisualizationPipeline to offload heavy data preparation (binning, normalisation, colour ramp evaluation) to a background thread. The pipeline integrates with the existing DataTaskPool infrastructure.

Picking

Grid layers support CPU-based picking via GeoGrid::cell_at_geo. Column layers support nearest-column picking. Both integrate with MapState::pick through the standard [Layer] trait.

Structs

ColorRamp

An interpolated colour transfer function defined by ordered stops.

ColorStop

A single stop in a ColorRamp.

ColumnInstance

A single column instance anchored to a geographic position.

ColumnInstanceSet

A collection of ColumnInstances with a generation counter.

ExtrusionParams

Extrusion rendering parameters.

GeoGrid

A georeferenced regular grid anchored to a geographic origin.

GridExtrusionLayer

An extruded georeferenced grid overlay.

GridScalarLayer

A flat georeferenced colour grid overlay.

InstancedColumnLayer

An instanced column overlay layer.

LabeledStop

A labeled stop in a legend.

LegendSpec

Legend metadata sufficient for client-side UI rendering.

PointCloudLayer

A point-cloud / scatter visualization layer.

PointInstance

A single point-cloud instance anchored to a geographic position.

PointInstanceSet

A collection of PointInstances with a generation counter.

ScalarField2D

A 2D scalar field aligned to a GeoGrid.

Enums

NormalizationMode

Normalization mode for legend value display.

VisualizationOverlay

A single visualization overlay collected from the layer stack during MapState::update_with_dt.