Skip to content

Commands

m4bwav edited this page Nov 16, 2026 · 4 revisions

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.

The verbs

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

doctor

Python, a headless browser and the optional extras. Output is per machine; see Getting started.

explain

Plain definitions of projections, symbols and methods.

python scripts/mpw.py explain web-mercator
web-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 list
authalic-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-term
Not 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]

inspect

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.gpx
format          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.png
format          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"
  ]
}

convert

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.geojson
wrote track.geojson: 2 features
python scripts/mpw.py convert tests/fixtures/route.geojson route.kml
wrote route.kml: 4 features
python scripts/mpw.py inspect route.kml
format          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"]

measure

distance

Latitude first. Vincenty on WGS84 by default; --ellipsoid GRS80 or clarke1866.

python scripts/mpw.py measure distance -41.32 174.81 40.96 -5.50
distance  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 GRS80
distance  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).

area

Polygon area on the ellipsoid, holes subtracted.

python scripts/mpw.py measure area tests/fixtures/square.geojson
area  9231319412.4 m2 (9231.319412 km2)
method ellipsoid (WGS84) via authalic latitude; edges straight in cylindrical equal-area

scale

python scripts/mpw.py measure scale 1:50000 --map 2cm
2cm on the map = 1000 m = 1 km on the ground at 1:50000
python scripts/mpw.py measure scale 1:25000 --ground 3km
3km on the ground = 12 cm on the map at 1:25000

project

One point forward, or back with --inverse. Options: --lon0, --lat0, --radius.

python scripts/mpw.py project --list
webmercator      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 45
x=1.266361139  y=0.8372734721
python scripts/mpw.py project webmercator 174.78 -41.29
x=19456420.6  y=-5055211.16
python scripts/mpw.py project webmercator 19456639.5 -5057944.4 --inverse
lon=174.7819664  lat=-41.30844609

Mollweide and the other R-unit projections print on the unit sphere unless --radius is given.

read

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 m

The 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."

trace

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.geojson
format          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

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 --list
desert    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 3
Qabur
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 1
Rakosir
Sitoror
Kansiron
Karto

find

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.

fetch

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"

style

The six looks; see Styles.

python scripts/mpw.py style --list
atlas              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

render

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 atlas
wrote 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

label

Places the labels and runs the three label bars without drawing.

python scripts/mpw.py label isles.map
82 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))

legend

Only the symbols this map uses. -o legend.svg also draws it.

python scripts/mpw.py legend isles.map --style topographic -o legend.svg
swatch 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

sheet

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.png
wrote pick.png: 3 maps
python scripts/mpw.py sheet isles.map --seeds 1,2,3,4 --cols 2 -o seeds.svg
wrote seeds.svg: 4 maps

serve

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 8765
serving http://127.0.0.1:8765/ (127.0.0.1 only; Ctrl+C stops)

aistyle

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 --list
ink-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-run
dry 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.

Clone this wiki locally