mapterm/
lib.rs

1//! mapterm: a map in your terminal. This is the library behind the `mapterm` viewer: a
2//! [`Map`] holds named sources and an ordered list of style layers, and draws as a
3//! [ratatui](https://ratatui.rs) widget with braille lines, cell-color fills and
4//! collision-free labels.
5//!
6//! ```
7//! use mapterm::{Camera, Map, MapSource, StyleLayer};
8//! use ratatui::{buffer::Buffer, layout::Rect, widgets::Widget};
9//! use serde_json::json;
10//!
11//! let mut map = Map::new();
12//! map.add_source("sites", MapSource::geojson(&json!({
13//!     "type": "Feature", "properties": {"name": "Washington Monument"},
14//!     "geometry": {"type": "Point", "coordinates": [-77.0353, 38.8895]}
15//! }))?)?;
16//! map.add_layer(StyleLayer::symbol("sites", "sites").glyph("◆").text("{name}").color("cyan"))?;
17//!
18//! // Draw it 60x10 cells, centered on the monument at zoom 15.
19//! let area = Rect::new(0, 0, 60, 10);
20//! let mut buf = Buffer::empty(area);
21//! map.view(&Camera::new(-77.0353, 38.8895, 15.0)).render(area, &mut buf);
22//! let row: String = (0..60).map(|x| buf[(x, 5)].symbol().to_string()).collect();
23//! assert!(row.contains("◆ Washington Monument"));
24//! # Ok::<(), anyhow::Error>(())
25//! ```
26//!
27//! For a basemap, [`Map::from_style`] loads any MapLibre style (`"liberty"` and the other
28//! OpenFreeMap styles by name, a URL or a file), or [`Map::terminal`] draws a vector tile
29//! [`Source`] with mapterm's built-in terminal style. Tiles load with [`Map::load_tiles`], or
30//! in the background with [`Map::tile_requests`] and [`Map::insert_loaded`].
31//! `examples/hello_map.rs` is a complete pan-and-zoom app in about 60 lines.
32//!
33//! ## The map
34//!
35//! - [`map`]: [`Map`], its sources ([`MapSource`]: vector tiles, GeoJSON, raster), style and
36//!   custom layers, feature state, [`Map::query_rendered_features`] and
37//!   [`Map::query_features`] (every feature under a spot, drawn or not, as [`Pick`]s).
38//! - [`spec`]: [`StyleLayer`] and the style properties a terminal can show (a table in its docs).
39//! - [`expr`]: MapLibre expressions and legacy filters.
40//! - [`stylejson`]: MapLibre style documents and the built-in terminal styles.
41//! - [`layer`]: custom layers drawing through a [`DrawContext`]; [`Markers`] is one.
42//! - [`icons`]: style icons as one-cell symbols.
43//!
44//! ## Interaction
45//!
46//! - [`interact`]: [`Controller`], MapLibre-style mouse and keyboard handling (wheel zoom,
47//!   drag with inertia, double-click and box zoom, eased keys, `fly_to`, `fit_bounds`).
48//! - [`events`]: layer click, enter and leave events, and hover highlights with feature state.
49//! - [`geocode`]: place search with Photon or Nominatim.
50//!
51//! ## Data
52//!
53//! - [`source`]: vector tiles from PMTiles (file or HTTP range requests), XYZ URLs or
54//!   TileJSON, with timeouts, size caps and a disk cache.
55//! - [`raster`]: image tile sources (XYZ, TMS, PMTiles, named providers) for raster layers,
56//!   drawn as [`kitty`] graphics ([`Map::kitty_commands`]) or as cell colors.
57//! - [`geojson`]: GeoJSON files or URLs, and ready-made overlay style layers for them.
58//! - [`formats`]: CSV, GPX, KML and FlatGeobuf ([`fgb`]) as GeoJSON.
59//! - [`index`] and [`cluster`]: the spatial index and point clustering behind GeoJSON sources.
60//!
61//! ## Output and the rest
62//!
63//! - [`export`]: a drawn map as plain text, ANSI-colored text or HTML.
64//! - [`smooth`]: opt-in pixel-smooth panning for the Ghostty smooth-scroll fork.
65//! - [`render`]: [`Camera`], [`Viewport`] and Web Mercator helpers.
66//! - Lower level: [`mvt`] (vector tile decoding), [`pbf`] (protobuf), [`pmtiles`] (the
67//!   archive format), [`store`] (decoded features), [`pick`] (hit testing and measurements).
68
69#![warn(missing_docs)]
70
71pub mod export;
72pub mod cluster;
73pub mod events;
74pub mod expr;
75pub mod fgb;
76pub mod formats;
77pub mod geocode;
78pub mod geojson;
79pub mod icons;
80pub mod index;
81pub mod interact;
82pub mod kitty;
83pub mod layer;
84pub mod map;
85pub mod mvt;
86pub mod pbf;
87pub mod pick;
88pub mod pmtiles;
89pub mod raster;
90pub mod render;
91pub mod smooth;
92pub mod source;
93pub mod spec;
94pub mod store;
95pub mod stylejson;
96
97pub use interact::{Click, Controller};
98pub use pick::Pick;
99pub use layer::{CustomLayer, DrawContext, Markers, PickContext};
100pub use map::{KittyState, Map, MapSource, MapView, RasterMode, TileRequest};
101pub use spec::StyleLayer;
102pub use render::{Camera, Overlay, Viewport};
103pub use source::Source;
104pub use store::TileId;
mapterm/lib.rs

mapterm/
lib.rs
