- Rust 67.8%
- JavaScript 11.6%
- CSS 10.2%
- Python 7.3%
- HTML 2.6%
- Other 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
- Validate picking hits against the actual geometry. Antialiased border pixels blend two region colours, so the decoded index pointed at an unrelated country (e.g. Gambia while hovering Croatia). Border pixels now fall back to nearby pixels and are checked with isPointInPath. - Render at rest in screen space at device resolution instead of stretching a fixed bitmap with CSS; a correctly sized preview bitmap is used only while panning/zooming so gestures stay smooth. - Stop re-rendering the palette when a group is selected. Doing so destroyed the native colour input mid-pick, so colour changes were never received (and group-name inputs lost focus). - Rebuild web/pkg. |
||
| crates | ||
| docs | ||
| native | ||
| scripts | ||
| tools | ||
| web | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| LICENSE | ||
| README.md | ||
Mapper
A fast, private map-colouring studio — a MapChart-style editor written in pure Rust.
Colour countries, states, provinces or counties, build a legend, style the map and download a high-resolution image. The editor, projections, SVG renderer, CSV engine and state management are all Rust. The web build compiles to WebAssembly with no JavaScript map library; the same core crate can back desktop and mobile shells.
Try it
The compiled web app is in web/ and only needs a static file server:
./scripts/serve.sh
# open http://localhost:8080
Or manually:
cd web
python3 -m http.server 8080
No build step or account is required. Maps are loaded on demand from
web/maps/.
What you can do
| 35 maps | World, continents, the Americas, Europe, Asia, Africa, Oceania, Middle East, US states, US counties, Canada, Australia, Brazil, China, India, Indonesia, Japan, Mexico, Argentina, Russia, Germany, France, Italy, Spain, UK, Ireland, Poland, Netherlands, Sweden, Norway, Ukraine, Türkiye, South Africa, and world subdivisions. |
| Painting | Click to paint, drag to paint many regions, right-click to erase. Paint/erase/hide/pan/select tools. Paint a whole country or state at once from a subdivision map. |
| Colour system | No pre-generated palette: groups are created as you paint (or with Add color). Unlimited groups, 11 optional palettes, colour picker, counts, reorder, delete. Nine fill patterns (dots, stripes, crosshatch, checkerboard…). |
| Legend | Editable title and group names, four corners, offsets, font, size, colours, opacity, corner radius, optional counts and empty groups. |
| Title | Optional map title and subtitle, alignment, font, size and colours. Included in exports. |
| Map style | Seven style presets plus full control of background, land, borders, border width, hover colour, graticule and map shadow. |
| Projections | Natural Earth, Robinson, Mercator and equirectangular for geographic maps. |
| Navigation | Wheel/pinch zoom around the cursor, pan tool, hold-space pan, fit, zoom slider, region search and “zoom to region”. |
| Region management | Search/filter the region list, hide regions, show hidden, clear colours, inspect assignments. |
| Bulk tools | Colour by continent or parent, randomise, CSV import. |
| Data import | Paste CSV as region,group name, region,#hexcolour, or region,numeric value. Numeric values become quantile classes on a chosen colour ramp. |
| Export | PNG at 1×–4× (up to 6400×4000), crisp SVG, project JSON, data CSV and region-name template. Transparent PNG background. |
| Save/share | Autosave per map in local storage, downloadable project files, and share links that encode the whole project in the URL. |
| Editing | Undo/redo, keyboard shortcuts, duplicate-safe group handling, map-specific saved projects. |
| Responsive | Desktop three-pane layout; tablet/phone drawers, touch painting, pinch zoom, readable scaled legend/title. |
| Private | No accounts, no analytics, no remote calls. Your map never leaves the browser unless you export or share it. |
Screens and workflow
- Pick a map from the map library (top-left map name).
- Click regions. On a fresh map the first click creates the first colour group; use Add color to create groups in advance.
- Name groups — they become legend entries automatically.
- Style the legend/title in the right Style and Legend tabs.
- Export PNG/SVG, save a project file, or copy a share link.
New projects start with an empty palette — there are no template groups to clean up. Switch maps at any time: Mapper keeps a separate autosaved project for every map, so you can jump between the world map and a country map without losing work.
Build from source
Requirements
- Rust 1.81+ (edition 2021)
wasm32-unknown-unknowntargetwasm-bindgen-cli0.2.130 (match thewasm-bindgencrate inCargo.lock)- A native linker (
cc/clang). On systems without one,zig-ccworks andscripts/build_web.shpicks it up automatically.
rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.130
./scripts/build_web.sh
./scripts/serve.sh
build_web.sh runs:
cargo build -p mapper-web --target wasm32-unknown-unknown --release
wasm-bindgen target/wasm32-unknown-unknown/release/mapper_web.wasm \
--out-dir web/pkg --target web --no-typescript
Tests
./scripts/test.sh
The tests parse and prepare every map asset, check geometry, exercise CSV import (named groups and numeric classes), and render a world map with patterns and a legend.
Regenerate map data
web/maps/*.json, web/thumbs/*.svg and web/maps/index.json are generated
from Natural Earth and US Atlas:
python3 tools/build_maps.py
The script downloads the sources if necessary, simplifies and quantises the geometry, splits the US into an Albers USA layout with Alaska/Hawaii insets, and writes compact int16 assets plus thumbnails. Outputs are committed so the web app runs without Python.
Architecture
crates/mapper-core/ Pure Rust. No browser dependencies.
model.rs Project, groups, style, legend, title, view, undo-friendly state
mapdata.rs GeoJSON-style asset model, projections, canvas fitting
render.rs SVG export renderer, grouped screen paths, projections
data.rs CSV parser, group/numeric import, CSV export
presets.rs Palettes, ramps, style presets, fonts
tests/core.rs Asset/rendering/import tests
examples/ Native preview and documentation-map generators
crates/mapper-web/ Rust + WebAssembly UI (web-sys; no UI framework)
lib.rs Boot, map fetching, share/project loading
app.rs State, editing operations, local storage, autosave
ui.rs DOM chrome, canvas viewport, fixed title/legend overlay
canvas.rs Canvas map renderer (solid fills, patterns, borders, masks)
picking.rs Off-screen colour-index canvas for O(1) region hit testing
events.rs Pointer painting, zoom/pan/pinch, keyboard, delegated events
export.rs PNG rasterisation, SVG/JSON/CSV downloads, clipboard
dom.rs / icons.rs Small browser helpers and inline icon set
web/ Static shell, CSS, compiled WASM, map assets
native/ Tauri 2 desktop/mobile shell (same web bundle)
tools/build_maps.py Data pipeline
docs/ Documentation assets
Why this architecture?
- Canvas for editing, SVG for export. The live map is a single canvas bitmap
built from grouped paths, so panning/zooming is a CSS transform of a bitmap and
painting redraws only a handful of grouped shapes.
mapper_core::render_svgproduces the standalone vector file used for.svgdownloads; PNG export rasterises that SVG. The editor stays responsive while downloads remain pixel-perfect. - Platform-neutral core. State, projections and rendering do not depend on
web-sys, so a desktop/mobile shell can reuse them. The included Tauri target reuses the whole web bundle; a future native UI could reuse the core directly. - On-demand map data. Only the selected map JSON is fetched. The world asset is ~850 KB, US counties ~840 KB and the full world-subdivision map ~3 MB; everything else is smaller.
- Constant-cost interaction. Region hit testing reads one pixel from an off-screen colour-index canvas, so hover/click cost is independent of how many regions a map has. Pan/zoom moves a cached bitmap, not thousands of DOM nodes. The legend/title are a fixed SVG overlay and are updated separately from the map. This is why the 4,437-region world subdivisions map pans at the same speed as the 232-country world map.
Desktop and mobile
native/ contains a ready Tauri 2 shell. Build the web bundle, then:
cd native
cargo tauri dev # desktop
cargo tauri build
Tauri 2 also supports Android and iOS:
cargo tauri android init && cargo tauri android dev
cargo tauri ios init && cargo tauri ios dev # macOS only
The shell embeds web/ and uses the platform webview (WebKitGTK, WebView2,
WKWebView, Android WebView). See native/README.md for
prerequisites and icon generation. The web target is the primary, fully tested
build.
Keyboard shortcuts
| Key | Action |
|---|---|
B / E / H / V / S |
Paint / erase / hide / pan / select tool |
Space (hold) |
Temporarily pan |
+ / − |
Zoom in / out |
F or 0 |
Fit map |
1–9, 0 |
Select colour group 1–10 |
[ / ] |
Previous / next colour group |
G |
Toggle graticule |
Ctrl/Cmd+Z |
Undo |
Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y |
Redo |
Ctrl/Cmd+S |
Download project JSON |
? |
Help |
Esc |
Close dialog / clear panels |
Mouse: click paints, drag paints continuously, right-click erases, wheel zooms. Touch: tap paints, two-finger pinch zooms, pan tool moves; all side panels become drawers.
Map data and licensing
- Code: MIT.
- Geometry: Natural Earth (public domain) for world countries and first-level subdivisions.
- US states/counties: US Atlas (ISC), derived from Census Bureau data.
- Inspiration: Mapper is an independent implementation inspired by the workflow of tools like MapChart. It is not affiliated with MapChart.
Country borders are generalised cartographic data, not legal or political advice. Some disputed areas, microstates and overseas territories are grouped according to the Natural Earth source.
Status / next steps
The web build is complete and usable. Natural extensions:
- more map packs (historical, election, fantasy/gaming worlds)
- label layers and region callouts
- custom SVG pattern uploads and per-region overrides
- multi-select and rectangular selection
- richer Excel/Sheets/GeoJSON import
- native menus, file dialogs and recent projects in the Tauri shell
- optional cloud projects/share hosting
Contributions and new map packs are welcome. The core is deliberately framework-free so new frontends and import formats can share the same project model.
