rustial 1.0.0

#![warn(missing_docs)]
#![cfg_attr(not(test), deny(clippy::unwrap_used))]
// ---------------------------------------------------------------------------
//! # Rustial
//!
//! Scientific-grade 2.5D geospatial map library for Rust.
//!
//! This crate is the **public API surface** of the rustial project.
//! It re-exports the types you need from the lower-level workspace
//! crates so that downstream users only ever need a single dependency:
//!
//! ```toml
//! [dependencies]
//! rustial = "1"
//! ```
//!
//! ## Workspace architecture
//!
//! ```text
//! rustial                          <-- you are here (facade)
//!   |
//!   +-- rustial-engine             framework-agnostic engine (math, camera, layers,
//!   |                              tiles, terrain, vectors, models, I/O abstractions)
//!   +-- rustial-renderer-wgpu      pure WGPU renderer (behind `wgpu-renderer` feature)
//!   +-- rustial-renderer-bevy      Bevy engine renderer (behind `bevy-renderer` feature)
//! ```
//!
//! ## Feature flags
//!
//! | Flag | Default | Description |
//! |------|---------|-------------|
//! | `wgpu-renderer` | **yes** | Enables [`WgpuMapRenderer`] and [`RenderParams`]. |
//! | `bevy-renderer` | no | Enables [`RustialBevyPlugin`], [`RustialBevyConfig`], and Bevy ECS components. |
//! | `terrain-rgb` | no | Enables [`AwsTerrainSource`] and [`MapboxTerrainSource`] (reqwest + image). |
//! | `geojson` | no | Enables the GeoJSON parser ([`parse_geojson`]). |
//! | `disk-cache` | no | Enables [`DiskCache`] for flat-file on-disk tile persistence. |
//!
//! ## Quick start (pure WGPU)
//!
//! ```rust,ignore
//! use rustial::{MapBuilder, MapState, WgpuMapRenderer};
//!
//! let mut state = MapBuilder::new()
//!     .center(51.1, 17.0)
//!     .zoom(10)
//!     .viewport(1280, 720)
//!     .build();
//! state.update();
//!
//! // Feed `state` and a wgpu::Device/Queue to WgpuMapRenderer::render().
//! ```
//!
//! ## Quick start (Bevy)
//!
//! ```rust,ignore
//! use bevy::prelude::*;
//! use rustial::{RustialBevyPlugin, RustialBevyConfig, default_plugins};
//!
//! App::new()
//!     .add_plugins(default_plugins("my map", (1280, 720)))
//!     .insert_resource(RustialBevyConfig {
//!         center: (51.1, 17.0),
//!         zoom: 10,
//!         ..default()
//!     })
//!     .add_plugins(RustialBevyPlugin)
//!     .run();
//! ```
// ---------------------------------------------------------------------------

// ---------------------------------------------------------------------------
// Facade-owned modules
// ---------------------------------------------------------------------------

mod builder;
mod error;
mod handle;

#[cfg(feature = "terrain-rgb")]
mod terrain_sources;

pub use builder::MapBuilder;
pub use error::RustialError;
pub use handle::MapHandle;

#[cfg(feature = "terrain-rgb")]
pub use terrain_sources::{AwsTerrainSource, MapboxTerrainSource};

// ---------------------------------------------------------------------------
// Re-exports -- Math primitives (rustial-engine)
//
// Coordinates, projections, ellipsoid, tile math, frustum culling,
// geodesic calculations, and elevation grids.
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    // Coordinate types
    GeoCoord, WorldCoord,
    // Bounds
    GeoBounds, WorldBounds,
    // Projections
    Projection, WebMercator, Equirectangular, Globe, VerticalPerspective,
    // Ellipsoid & geodesics
    Ellipsoid,
    geodesic_distance, geodesic_distance_on,
    geodesic_destination, geodesic_destination_on,
    GeodesicResult, VincentyConvergenceError,
    // Tile math
    TileId, TileCoord, FlatTileSelectionConfig, FlatTileView, MAX_ZOOM,
    geo_to_tile, geo_to_tile_checked,
    tile_to_geo, tile_bounds_world,
    visible_tiles, visible_tiles_checked, visible_tiles_flat_view,
    visible_tiles_flat_view_capped, visible_tiles_flat_view_capped_with_config,
    visible_tiles_flat_view_refined_capped,
    visible_tiles_flat_view_with_config, visible_tiles_lod,
    // Frustum culling
    Frustum, Plane,
    PLANE_LEFT, PLANE_RIGHT, PLANE_BOTTOM, PLANE_TOP, PLANE_NEAR, PLANE_FAR,
    // Elevation
    ElevationGrid,
};

// ---------------------------------------------------------------------------
// Re-exports -- Camera & input (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    Camera, CameraAnimator, CameraConstraints, CameraController, CameraMode,
    CameraProjection, EaseToOptions, FlyToOptions, InputEvent,
};

// ---------------------------------------------------------------------------
// Re-exports -- Layer system (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    Layer, LayerId, LayerStack,
    BackgroundLayer, DynamicImageOverlayLayer, HillshadeLayer, HillshadeParams,
    ImageOverlayLayer, TileLayer, VectorLayer, ModelLayer,
    VectorRenderMode, VectorStyle, VectorMeshData,
    // Dynamic frame provider system (video/canvas sources).
    CallbackFrameProvider, FrameData, FrameProvider, FrameProviderFactory,
};

// ---------------------------------------------------------------------------
// Re-exports -- Style/runtime breadth (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    BackgroundStyleLayer, CircleStyleLayer, FillExtrusionStyleLayer, FillStyleLayer,
    FromFeatureStateProperty, GeoJsonSource, HeatmapStyleLayer, HillshadeStyleLayer,
    LineStyleLayer, MapStyle, ModelSource, ModelStyleLayer, RasterSource, RasterStyleLayer,
    StyleDocument, StyleError, StyleEvalContext, StyleEvalContextFull, StyleLayer, StyleLayerId,
    StyleLayerMeta, StyleProjection, StyleSource, StyleSourceId, StyleSourceKind, StyleValue,
    SymbolStyleLayer, TerrainSource, VectorStyleLayer, VectorTileSource, ImageSource,
    VideoSource, CanvasSource,
    // Clustering.
    ClusterOptions, PointCluster,
    // Feature-state-driven style resolution helpers.
    circle_style_with_state, fill_extrusion_style_with_state, fill_style_with_state,
    heatmap_style_with_state, line_style_with_state, symbol_style_with_state,
    vector_style_with_state,
};

// ---------------------------------------------------------------------------
// Re-exports -- Expression engine (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    Expression, ExprEvalContext, NumericExpression, StringExpression, BoolExpression,
};

// ---------------------------------------------------------------------------
// Re-exports -- Map state & frame output (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{FrameOutput, FitBoundsOptions, FitBoundsPadding, MapState};

// ---------------------------------------------------------------------------
// Re-exports -- Geometry & vector data (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    Feature, FeatureCollection, Geometry,
    Point, LineString, Polygon,
    MultiPoint, MultiLineString, MultiPolygon,
    PropertyValue,
    simplify_douglas_peucker, simplify_polygon_ring,
    stroke_line, triangulate_polygon, triangulate_polygon_with_holes,
    bearing, geometry_bbox, geometry_centroid, initial_bearing,
    interpolate_great_circle, linestring_length, polygon_area, ring_area,
};

#[cfg(feature = "geojson")]
pub use rustial_engine::{parse_geojson, GeoJsonError};

#[cfg(feature = "shapefile")]
pub use rustial_engine::{parse_shapefile, ShapefileError};

// ---------------------------------------------------------------------------
// Re-exports -- Tile engine (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    TileSource, TileDecoder, TileData, TileError, TileFreshness, TileResponse,
    DecodedImage, RasterMipChain, RasterMipLevel,
    VectorTileData,
    HttpTileSource, HttpVectorTileSource, PooledTileSource,
    TileCache, TileCacheEntry,
    TileManager, TileManagerCounters, TilePixelRect, TileSelectionConfig,
    TileSelectionStats, TileTextureRegion, VisibleTile, VisibleTileSet,
};

// ---------------------------------------------------------------------------
// Re-exports -- I/O abstractions (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{FetchPool, HttpClient, HttpRequest, HttpResponse};

#[cfg(all(feature = "disk-cache", not(target_arch = "wasm32")))]
pub use rustial_engine::{DiskCache, DiskCacheError};

// ---------------------------------------------------------------------------
// Re-exports -- TileJSON metadata (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    TileJson, TileJsonError, TileScheme, VectorLayerMeta,
};

#[cfg(feature = "style-json")]
pub use rustial_engine::{parse_tilejson, parse_tilejson_value};

// ---------------------------------------------------------------------------
// Re-exports -- MVT decoder (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    decode_mvt, DecodedVectorTile, MvtDecodeOptions, MvtError,
};

// ---------------------------------------------------------------------------
// Re-exports -- Terrain & elevation (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    build_terrain_mesh, prepare_hillshade_raster, ElevationSource, FlatElevationSource,
    HttpElevationSource, PreparedHillshadeRaster, QuantizedMeshSource, TerrainConfig,
    TerrainError, TerrainManager, TerrainMeshData, TerrainRgbEncoding,
};

// ---------------------------------------------------------------------------
// Re-exports -- 3D models (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{AltitudeMode, ModelInstance, ModelLoadError, ModelMesh};

// ---------------------------------------------------------------------------
// Re-exports -- WGPU renderer (behind `wgpu-renderer` feature)
// ---------------------------------------------------------------------------

#[cfg(feature = "wgpu-renderer")]
pub use rustial_renderer_wgpu::{RenderParams, TerrainInteractionBuffers, WgpuMapRenderer};

// ---------------------------------------------------------------------------
// Re-exports -- Bevy renderer (behind `bevy-renderer` feature)
// ---------------------------------------------------------------------------

#[cfg(feature = "bevy-renderer")]
pub use rustial_renderer_bevy::{
    backends_from_env, default_plugins, geo_to_vec3,
    MapStateResource, RustialBevyConfig, RustialBevyPlugin, TerrainInteractionBuffersResource,
};

#[cfg(feature = "bevy-renderer")]
pub use rustial_renderer_bevy::components::{GeoAltitudeMode, GeoTransform, MapEntity};

pub use rustial_engine::{
    GlyphAtlas, GlyphAtlasEntry, GlyphKey, GlyphProvider, GlyphRaster, ImageManager,
    PlacedSymbol, ProceduralGlyphProvider, SpriteImage, SpriteSheet,
    SymbolAnchor, SymbolAssetDependencies, SymbolAssetRegistry, SymbolCandidate,
    SymbolCollisionBox, SymbolPlacementConfig, SymbolPlacementEngine,
    SymbolWritingMode,
};

pub use rustial_engine::{
    FeatureState, FeatureStateId, GeoBBox, QueriedFeature, QueryOptions,
    geometry_intersects_bbox,
};

pub use rustial_engine::{
    HitCategory, HitProvenance, NonPickableLayerKind, PickHit, PickOptions, PickQuery,
    PickResult, PickableLayerKind,
};

pub use rustial_engine::{
    InteractionButton, InteractionEvent, InteractionEventKind, InteractionModifiers,
    InteractionTarget, InteractionTargetKind, PointerKind, ScreenPoint,
};

pub use rustial_engine::{InteractionConfig, InteractionManager};

pub use rustial_engine::{EventEmitter, ListenerId};

// ---------------------------------------------------------------------------
// Re-exports -- Visualization primitives (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    ColorRamp, ColorStop, ColumnInstance, ColumnInstanceSet, ExtrusionParams,
    GeoGrid, GridExtrusionLayer, GridScalarLayer, InstancedColumnLayer,
    LabeledStop, LegendSpec, NormalizationMode, PointCloudLayer, PointInstance,
    PointInstanceSet, ScalarField2D, VisualizationOverlay,
};

// ---------------------------------------------------------------------------
// Re-exports -- Async data pipeline (rustial-engine)
// ---------------------------------------------------------------------------

pub use rustial_engine::{
    DataTaskPool, DataTaskResultReceiver, ThreadDataTaskPool,
    TerrainTaskInput, TerrainTaskOutput, TerrainCacheKey,
    VectorTaskInput, VectorTaskOutput, VectorCacheKey,
    VectorBucketKey, partition_features_by_tile,
    AsyncVisualizationPipeline, VisualizationTaskOutput,
};