egui_map/lib.rs
1//! # egui-map
2//!
3//! An [`egui`](https://docs.rs/egui) widget that renders an interactive 2D map
4//! on screen.
5//!
6//! The [`map::Map`] widget displays a set of nodes connected by lines, with
7//! support for:
8//!
9//! - Panning (click and drag) and zooming (mouse wheel; hold `Ctrl` — or `Cmd`
10//! on macOS — to zoom faster).
11//! - Spatial indexing of nodes through a kd-tree, so only the nodes inside the
12//! current viewport are painted each frame.
13//! - Node names and free-floating text labels with configurable visibility
14//! rules (see [`map::objects::VisibilitySetting`]).
15//! - Pulsing notifications and blinking markers attached to nodes.
16//! - Custom node rendering and right-click context menus through the
17//! [`map::objects::NodeTemplate`] and [`map::objects::ContextMenuManager`]
18//! traits.
19//! - Built-in color themes with independent light and dark variants, or a
20//! custom palette installed through [`map::theme::MapTheme`] (see
21//! [`map::objects::MapSettings`] for the rest of the visual style).
22//!
23//! ## Quick start
24//!
25//! ```no_run
26//! use egui_map::map::Map;
27//! use egui_map::map::objects::MapPoint;
28//! use std::collections::HashMap;
29//!
30//! // Build the node set, keyed by node id.
31//! let mut points: HashMap<usize, MapPoint> = HashMap::new();
32//! points.insert(1, MapPoint::new(1, [0.0, 0.0]));
33//! points.insert(2, MapPoint::new(2, [100.0, 50.0]));
34//!
35//! let mut map = Map::new();
36//! map.add_hashmap_points(points);
37//!
38//! // Then, on every frame of your egui update loop:
39//! // ui.add(&mut map);
40//! ```
41//!
42//! ## Profiling
43//!
44//! The widget's hot paths (rendering, viewport culling, point/line loading)
45//! are instrumented with [`tracing`](https://docs.rs/tracing) spans. These
46//! are cheap no-ops unless a `tracing` subscriber is installed somewhere in
47//! the final binary; this crate never needs a feature of its own for that —
48//! a consumer that installs a subscriber (e.g. `tracing_tracy::TracyLayer`,
49//! for the [Tracy](https://github.com/wolfpld/tracy) profiler) picks up
50//! these spans for free, because `tracing` is a normal, unconditional
51//! dependency shared across the whole dependency graph.
52
53#![forbid(unsafe_code)]
54#![warn(missing_docs)]
55
56pub mod map;