Library overview

The mapterm command is a thin app over the mapterm crate. Everything the viewer does (styles, GeoJSON, rasters, inspect, interaction) is library API, so you can put a map in your own ratatui app: a dashboard with vehicle positions, a log viewer that plots requests, a field tool that works over SSH.

The API follows MapLibre GL JS: if you have written a web map, the names will be familiar.

Adding it

cargo add mapterm

or in Cargo.toml, with the crates the examples use:

[dependencies]
mapterm = "0.1"
ratatui = "0.30"
crossterm = "0.29"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
serde_json = "1"
anyhow = "1"

Loading tiles is async (tokio and reqwest); drawing is synchronous and happens in ratatui’s normal render pass.

The pieces

Type	Role
Map	Named sources plus an ordered list of layers. Load a style, add data, change paint and filters.
MapSource	Vector tiles, GeoJSON, or raster tiles.
StyleLayer	Draws one source as fill, line, circle, symbol, raster or background, with expressions.
CustomLayer	Your own drawing code: lines, fills, markers and labels through a DrawContext.
MapView	The ratatui widget, from map.view(&camera).
Camera	Center (lon, lat) and zoom.
Controller	MapLibre-style mouse and keyboard handling, easing, inertia, fly_to.
events::Events	Layer click, enter and leave events, and hover highlights with feature state.
Pick	A feature found under a spot, with properties and measurements.
Source	A tile source: PMTiles (file or HTTP), XYZ, TileJSON, with caching and limits.
formats, geojson	CSV, GPX, KML and FlatGeobuf read as GeoJSON; overlay styles for data layers.
export	A drawn map as text, ANSI or HTML.

Coordinates

• lon/lat in degrees, everywhere in the public API that takes a place.
• Cells are terminal columns and rows.
• Dots are braille dots: 2 per column and 4 per row, relative to the map’s area. Queries take a dot position, so a click at cell (col, row) is dot ((col - area.x) * 2 + 1, (row - area.y) * 4 + 2), the middle of the cell.

Next

Start with your first map, a complete app in about 60 lines, or browse the Rust API docs on docs.rs: every public item is documented, and the examples in them are compiled, so they match the API.

Pre-1.0, a minor version (0.2.0) may change the API; see the changelog.