Repository navigation
Commands
All commands are python scripts/mpw.py <command> from the repository root. Every output below was printed by the v0.11.0 release on 2026-11-16. --json on most commands prints the same facts as JSON.
| Verb | Does | Page |
|---|---|---|
doctor |
Python, browser and optional extras | here |
explain |
a cartography term | here |
inspect, convert
|
read and convert map files | here |
measure, project
|
geodesic distance, area, scale; one point through a projection | here |
read, trace
|
what a map picture shows; picture to GeoJSON | here |
gen world, gen region, zoom
|
invented worlds and child regions | Generate worlds |
gen city, gen dungeon, gen battle
|
towns, dungeons, battle maps | Generate places |
gen sector, gen system, gen planet, gen deck
|
star maps, systems, planet textures, ship decks | Generate space |
check |
the proof bars, plus --chokepoints, --fair and --range
|
Proof bars, Paths and travel |
export |
engines, Tiled, Universal VTT, mesh, print, sphere, T5 | Export |
path, travel
|
cheapest route, Dijkstra field, travel time | Paths and travel |
find, fetch
|
open sources with licence and credit; one polite download | here |
names |
place names from a sound pattern | here |
render, label, legend, style, sheet, serve
|
drawing a recipe | here and Styles |
aistyle |
optional AI repaint on your ComfyUI server | here |
Python, a headless browser and the optional extras. Output is per machine; see Getting started.
Plain definitions of projections, symbols and methods.
python scripts/mpw.py explain web-mercatorweb-mercator: EPSG:3857. Spherical Mercator on the WGS84 radius used by web tiles. Conformal, area grows as sec^2(lat); cut at about 85.0511 deg. Never use it for area.
More: references/projections.md
python scripts/mpw.py explain listauthalic-sphere
bleed
contour
crop-marks
equal-earth
equirectangular
geodesic
geojson
hachures
heightmap
hillshade
jump-point-search
keys-and-locks
laea
mercator
mollweide
nav-export
priority-flood
rhumb-line
robinson
scale
tissot
tmj
utm
uvtt
voronoi
web-mercator
world-file
An unknown term exits 1 and names the files to search:
python scripts/mpw.py explain no-such-termNot in the built-in glossary: 'no-such-term'. Try `mpw.py explain list`, or search references/sources-and-terms.md and references/projections.md.
[exit 1]
What a map file holds: GeoJSON, GPX, KML, KMZ, shapefiles, dBASE, PNG (with a .pgw world file), GeoPackage, MBTiles. The CRS is reported only when the file states it.
python scripts/mpw.py inspect tests/fixtures/track.gpxformat GPX 1.1
features 2
geometry_types {"Point": 1, "LineString": 1}
extent [-122.3492774, 47.5951518, -122.3316393, 47.6205063]
crs WGS84 (by schema)
properties ["gpx", "name"]
points 4
python scripts/mpw.py inspect tests/fixtures/heights.pngformat PNG
width 16
height 12
bit_depth 16
colour greyscale
interlaced False
note 16-bit greyscale: likely a heightmap
value_range [0, 18300]
world_file heights.pgw
pixel_size [10.0, -10.0]
rotation [0.0, 0.0]
extent [500000.0, 4199880.0, 500160.0, 4200000.0]
crs not stated (world files carry no CRS)
A world file holds the centre of the top-left pixel, so the extent is half a pixel wider than the naive sum.
python scripts/mpw.py inspect tests/fixtures/square.geojson --json{
"format": "GeoJSON",
"features": 1,
"geometry_types": {
"Polygon": 1
},
"extent": [
0,
0,
1,
1
],
"crs": "WGS84 lon/lat (RFC 7946)",
"properties": [
"name"
]
}
Between GeoJSON, GPX and KML; shapefiles and KMZ are read. GPX holds points and lines only, so polygons are skipped with a count. Ring order is fixed on the way.
python scripts/mpw.py convert tests/fixtures/track.gpx track.geojsonwrote track.geojson: 2 features
python scripts/mpw.py convert tests/fixtures/route.geojson route.kmlwrote route.kml: 4 features
python scripts/mpw.py inspect route.kmlformat KML
features 4
geometry_types {"Point": 1, "LineString": 2, "GeometryCollection": 1}
extent [-0.1275862, 48.856614, 13.404954, 52.5200066]
crs WGS84 (by spec)
properties ["desc", "gpx", "name"]
Latitude first. Vincenty on WGS84 by default; --ellipsoid GRS80 or clarke1866.
python scripts/mpw.py measure distance -41.32 174.81 40.96 -5.50distance 19959679.267 m (19959.679 km)
bearing 161.067670 deg (initial)
final 18.825195 deg
method Vincenty (WGS84)
python scripts/mpw.py measure distance -37.95103342 144.42486789 -37.65282114 143.92649553 --ellipsoid GRS80distance 54972.271 m (54.972 km)
bearing 306.868159 deg (initial)
final 307.173631 deg
method Vincenty (GRS80)
The second is Geoscience Australia's worked Vincenty example, Flinders Peak to Buninyong; their published distance is 54972.271 m. The first is GeographicLib's Wellington to Salamanca example (19959679.267 m).
Polygon area on the ellipsoid, holes subtracted.
python scripts/mpw.py measure area tests/fixtures/square.geojsonarea 9231319412.4 m2 (9231.319412 km2)
method ellipsoid (WGS84) via authalic latitude; edges straight in cylindrical equal-area
python scripts/mpw.py measure scale 1:50000 --map 2cm2cm on the map = 1000 m = 1 km on the ground at 1:50000
python scripts/mpw.py measure scale 1:25000 --ground 3km3km on the ground = 12 cm on the map at 1:25000
One point forward, or back with --inverse. Options: --lon0, --lat0, --radius.
python scripts/mpw.py project --listwebmercator EPSG:3857 spherical Mercator on R = 6378137 m (metres; conformal)
equirectangular plate carree (lat0 = standard parallel; R units)
mollweide Mollweide, equal-area (R units)
laea Lambert azimuthal equal-area centred on lon0, lat0 (sphere, R units)
robinson Robinson, PROJ cubic-spline table (compromise; R units)
equalearth Equal Earth, equal-area (R units)
python scripts/mpw.py project mollweide 100 45x=1.266361139 y=0.8372734721
python scripts/mpw.py project webmercator 174.78 -41.29x=19456420.6 y=-5055211.16
python scripts/mpw.py project webmercator 19456639.5 -5057944.4 --inverselon=174.7819664 lat=-41.30844609
Mollweide and the other R-unit projections print on the unit sphere unless --radius is given.
What a map picture shows: size, colour classes, dominant colours, text when tesseract is installed, and a georeference only from control points you give. Anything it cannot know is "status": "not sure" with the reason, never a guess. Options: --gcp px,py,lon,lat (three or more, pixel from the top-left corner), --units deg|m, --world (write a world file from the fit), --prompt (a checklist for an agent's own vision), --answers FILE (check those answers against the picture).
python scripts/mpw.py read tests/fixtures/heights.png --gcp 0,0,500000,4200000 --gcp 16,0,500160,4200000 --gcp 0,12,500000,4199880 --units mThe georeference part of the JSON it prints, with the coefficient list joined onto one line:
"georeference": {
"method": "affine",
"coefficients": [10.0, 0.0, 500000.0, 0.0, -10.0, 4200000.0],
"units": "m",
"gcps": 3,
"rms_m": 0.0,
"max_m": 0.0,
"note": "3 points fit an affine exactly: residuals are zero by construction and prove nothing. Add a 4th.",
"metres_per_pixel_at_centre": 10.0
},
Without tesseract the text, printed scale, legend and names fields say so:
"reason": "tesseract is not on PATH, so no text was read; names, legend labels and printed scale are not sure. Install Tesseract, or use `read --prompt` and your own vision."
A colour class (water, vegetation, relief, light, ink, grey, other) or one colour (--colour #rrggbb --tol N) to GeoJSON polygons with holes, or centre lines with --mode lines, simplified by Douglas-Peucker (--epsilon, pixels). Coordinates are pixels unless --gcp or --world auto georeferences them. --clean N runs a majority filter first; --fill-holes N fills small holes such as label halos over the sea.
python scripts/mpw.py render isles.map -o isles-atlas.png --style atlas
python scripts/mpw.py trace isles-atlas.png --class water --min-area 50 -o water.geojson{"source": "isles-atlas.png", "width": 1000, "height": 1000, "mode": "polygons", "class": "water", "epsilon_px": 1.0, "coordinates": "pixel", "mask_share": 0.5341, "features": 37, "out": "water.geojson"}
python scripts/mpw.py inspect water.geojsonformat GeoJSON
features 37
geometry_types {"Polygon": 37}
extent [1, 1, 999, 999]
crs WGS84 lon/lat (RFC 7946)
properties ["area_px", "class", "holes"]
inspect reports the RFC 7946 default for any GeoJSON; this file is in pixels, as trace said. Tracing an ink-and-parchment PNG for water finds nothing, since that look paints the sea in parchment tones: trace an atlas or topographic render.
Names from a sound pattern. names DIR prints a world's names; with --style or --pattern it renames the world (zoom its children again after).
python scripts/mpw.py names --listdesert long vowels, sh/kh/q (C=b d h j k m n q r s sh t z kh; V=a i u aa; S=CV CVF CV)
harsh clustered stops, closed syllables (C=k g d t r z kr gr dr th b; V=a o u i; S=CVF CV CVF CCVF)
isle no codas, small inventory (C=h k l m n p w; V=a e i o u; S=CV V CV)
latinate open syllables, -a/-um/-is feel (C=b c d f l m n p r s t v qu; V=a e i o u ia io; S=CV CV CVF V)
nordic short, consonant final (C=b d f g h k l m n r s t v sk st; V=a e i o u y aa ei; S=CVF CV CVF)
soft flowing, vowel rich (C=l m n r s v th h f y w; V=a e i o u ae ei ia; S=CV CVF V CV)
python scripts/mpw.py names --sample 6 --style desert --seed 3Qabur
Raami
Ribud
Saashi
Khijish
Hunhi
A custom pattern: C consonants, V vowels, F finals, S syllable shapes, N syllables per name.
python scripts/mpw.py names --sample 4 --pattern 'C=k t r s;V=a o i;F=n r;S=CV CVF;N=2-3' --seed 1Rakosir
Sitoror
Kansiron
Karto
Maps and data for a place, a time or a subject from a catalogue of 25 open sources, each with its licence and credit line. Offline by default; --online also asks Nominatim, Wikimedia Commons and the Library of Congress (not run for this wiki). --list prints the catalogue.
python scripts/mpw.py find "Iceland elevation"query: Iceland elevation (kinds: subject, place)
- [copernicus-dem] Copernicus DEM GLO-30/90
https://registry.opendata.aws/copernicus-dem/
licence: Copernicus WorldDEM licence (free, notice + no-liability)
credit: © DLR e.V. 2010-2014 and © Airbus 2014-2018, provided under COPERNICUS by the European Union and ESA
- [lola] Moon LOLA
https://pds-geosciences.wustl.edu/missions/lro/lola.htm
licence: public domain
credit: NASA/GSFC/LOLA Science Team
The answer goes on with Mars MOLA, OpenTopography (key: missing: set OPENTOPOGRAPHY_API_KEY), SRTM, USGS 3DEP, geoBoundaries and GeoNames. The catalogue matches words, not places: "elevation" brings in the Moon and Mars too.
Downloads one file politely: a generic mapwright/<version> User-Agent, a per-source rate limit kept on disk, a cache (MAPWRIGHT_CACHE, default ~/.cache/mapwright), a 200 MB cap (--max-mb), and refusals for the never-scrape list and whole-planet sets. It writes sources.json and CREDITS.txt beside the file. A host not in the catalogue needs --licence and --credit. API keys come from the environment and never reach the cache name or the credit files. Not run for this wiki (it makes a request).
python scripts/mpw.py fetch URL -o data --licence "CC BY 4.0" --credit "Example credit"The six looks; see Styles.
python scripts/mpw.py style --listatlas biome colours, soft hillshade, flat sea, serif labels
blueprint white line work on blueprint blue, monospace
ink-and-parchment parchment land, ink lines, old serif
satellite dark natural colour with strong relief, white labels
star-chart night palette with a star field (palette only for now)
topographic hypsometric tints, hillshade, depth-tinted sea
Recipe folder to .svg, .png or .pdf. Options: --style, --title, --font F.ttf (its widths measure the labels), --view scale for a system drawn to scale. PNG and PDF need Chrome or Edge. Every recipe kind renders: cities, dungeons and battle maps in ink-and-parchment or blueprint, space maps in their own drawing; see the generate pages.
python scripts/mpw.py render isles.map -o isles.svg --style atlaswrote isles.svg: style atlas, 78 labels (62 dropped), 21 legend entries, 0.60 s
python scripts/mpw.py render isles.map -o isles.pdf --style blueprint --title "The Isles"wrote isles.pdf: style blueprint, 83 labels (57 dropped), 10 legend entries, 0.64 s
Places the labels and runs the three label bars without drawing.
python scripts/mpw.py label isles.map82 labels placed, 58 dropped (no free spot)
PASS: labels: none overlap (82 labels, 0 overlapping pairs)
PASS: labels: none cut by the edge (0 cut)
SKIP: labels: read back by OCR (skipped: tesseract not found (install it to run this bar))
Only the symbols this map uses. -o legend.svg also draws it.
python scripts/mpw.py legend isles.map --style topographic -o legend.svgswatch 0-200 m
swatch 200-500 m
swatch 500-1000 m
swatch 1000-2000 m
swatch 2000-3000 m
swatch 3000-4500 m
swatch 4500 m+
swatch sea
line coast
line river
swatch lake
line major road
line minor road
dot city
dot town
dot village
Several styles, or several seeds, side by side in one SVG, PNG or PDF.
python scripts/mpw.py sheet isles.map --styles atlas,blueprint,star-chart -o pick.pngwrote pick.png: 3 maps
python scripts/mpw.py sheet isles.map --seeds 1,2,3,4 --cols 2 -o seeds.svgwrote seeds.svg: 4 maps
A pan and zoom page of the rendered map, bound to 127.0.0.1 only. Ctrl+C stops it.
python scripts/mpw.py serve isles.map --port 8765serving http://127.0.0.1:8765/ (127.0.0.1 only; Ctrl+C stops)
Optional. Repaints a world or region on your own ComfyUI server and keeps the geography: the model gets the map without text, then lakes, rivers, roads, symbols, labels, the legend, the scale bar and the north arrow are set in code on top, and the coast is measured against the recipe. The server comes from --host or MAPWRIGHT_COMFYUI; there is no default. --denoise defaults to 0.45, the measured ceiling. --dry-run writes the control picture and the workflow JSON and contacts nothing.
Since 0.24.0 --control canny or --control depth adds a ControlNet hint drawn from the recipe itself (canny: the coast edge; depth: grey from the heights) through the Z-Image Fun ControlNet Union model, with --strength (default 0.9). Measured on a seed 3 world over two looks and two seeds, canny at 0.9 kept the coast inside the bar on every picture up to denoise 0.75 (land IoU 0.95 to 0.96) and on 3 of 4 at 0.9; without control only denoise 0.45 passed. The command warns above 0.75 with control on.
python scripts/mpw.py aistyle --listink-and-parchment over ink-and-parchment brown ink on aged parchment, hachures, shore lines
painted-atlas over atlas gouache atlas plate: soft greens, painted relief, pale blue sea
satellite over satellite natural-colour orbital picture: deep ocean, forest, bare ground, relief
watercolour over topographic loose washes on cold-press paper
python scripts/mpw.py aistyle isles.map --look painted-atlas --dry-rundry run: wrote isles.map\aistyle-painted-atlas.control.png and isles.map\aistyle-painted-atlas.workflow.json (1024x1024, painted-atlas, seed 0, denoise 0.45 runs as 0.450); no server contacted
The path separator is the machine's (this run was on Windows). A real pass was not run for this wiki; check adds one bar per *.aistyle.json sidecar it finds in the folder.
This wiki describes mapwright 0.24.0 (released 2026-11-16) and was last updated on 2026-11-16. mapwright is MIT licensed. Report problems in the issues.