# Cartograph GPS Art Route Designer (shape → roads → GPX)

> Snap a heart, star or other shape to the streets of your OSM extract and get a GPX route. Places a shape (heart, star, circle, square, triangle, arrow or zigzag) at a point, size and rotation, samples it into waypoints, snaps them to the walkable or rideable roads of your own OpenStreetMap extract and joins them with shortest paths that stay close to the shape. Returns the route as GPX with its length and how closely it follows the drawing. Routing runs on the extract itself — no routing service is used. It is the GPS-art engine of the Cartograph app.

Part of usefulweb.app (https://usefulweb.app/). Part of [Cartograph](https://cartograph.usefulweb.app/) (ownerApp: cartograph). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://cartographrouteart.usefulweb.app/ (interactive tool at https://cartographrouteart.usefulweb.app/tool)
- JSON API: POST https://cartographrouteart.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://cartographrouteart.usefulweb.app/api/v1/tool)
- OpenAPI: https://cartographrouteart.usefulweb.app/openapi.json
- MCP (Streamable HTTP): https://cartographrouteart.usefulweb.app/mcp - tool `cartograph_route_art`

## Inputs
- file (file): OpenStreetMap extract (.osm, .osm.pbf or GeoJSON) - Up to 25 MB. Leave empty to use the built-in Vaduz sample. Download extracts from your own OpenStreetMap export, Geofabrik or BBBike; Cartograph never fetches map data itself.
- shape (select): Shape
- center (text): Shape centre - Empty: the middle of the extract.
- widthM (number): Shape width
- rotationDeg (number): Rotation (clockwise)
- profile (select): Travel mode
- spacingM (number): Waypoint spacing - 0 = automatic (shape length ÷ 60, at least 30 m).
- guidance (number): Stay-on-shape weight - 0 = plain shortest paths between waypoints; higher values prefer streets close to the drawn line.

## Method
- The shape is placed with geodesics: every outline point keeps its direction and distance from the centre (Karney’s direct problem on WGS84), so the size is true on the ground.
- The road graph is built from the extract: highway ways usable on foot or by bike (motorways and trunk roads, access=no/private and explicit foot=no/bicycle=no excluded; bikes avoid steps and footways unless allowed and follow one-way streets). Junctions are shared coordinates; edge lengths are great-circle distances.
- The outline is sampled into waypoints; each is snapped to the nearest graph node within twice the spacing (dead ends avoided where possible). Consecutive waypoints are joined by A* shortest paths whose cost adds “stay-on-shape weight × distance from the shape segment ÷ spacing” per metre, so routes prefer streets that hug the drawing. Out-and-back spurs are removed.
- Quality: mean distance of the route from the shape, the largest gap in either direction (Hausdorff-style) and the share of the shape that has the route within 25 m — measured every 10 m in a local equirectangular frame.