No description
  • Rust 67.8%
  • JavaScript 11.6%
  • CSS 10.2%
  • Python 7.3%
  • HTML 2.6%
  • Other 0.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
lea c3e1687039 Keep the map crisp, pick regions correctly, and fix colour editing
- 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.
2026-11-04 12:26:34 +01:00
crates Keep the map crisp, pick regions correctly, and fix colour editing 2026-11-04 12:26:34 +01:00
docs Build Mapper: pure-Rust map colouring studio 2026-11-01 23:25:43 +01:00
native Build Mapper: pure-Rust map colouring studio 2026-11-01 23:25:43 +01:00
scripts Build Mapper: pure-Rust map colouring studio 2026-11-01 23:25:43 +01:00
tools Build Mapper: pure-Rust map colouring studio 2026-11-01 23:25:43 +01:00
web Keep the map crisp, pick regions correctly, and fix colour editing 2026-11-04 12:26:34 +01:00
.gitignore Build Mapper: pure-Rust map colouring studio 2026-11-01 23:25:43 +01:00
Cargo.lock Build Mapper: pure-Rust map colouring studio 2026-11-01 23:25:43 +01:00
Cargo.toml Build Mapper: pure-Rust map colouring studio 2026-11-01 23:25:43 +01:00
LICENSE Build Mapper: pure-Rust map colouring studio 2026-11-01 23:25:43 +01:00
README.md Render the live map on canvas for fast pan, zoom, and painting 2026-11-02 16:29:04 +01:00

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.

Example map made with Mapper: countries coloured by continent with a legend

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

  1. Pick a map from the map library (top-left map name).
  2. Click regions. On a fresh map the first click creates the first colour group; use Add color to create groups in advance.
  3. Name groups — they become legend entries automatically.
  4. Style the legend/title in the right Style and Legend tabs.
  5. 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-unknown target
  • wasm-bindgen-cli 0.2.130 (match the wasm-bindgen crate in Cargo.lock)
  • A native linker (cc/clang). On systems without one, zig-cc works and scripts/build_web.sh picks 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_svg produces the standalone vector file used for .svg downloads; 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.