io.github.mapsmith-ai/mapsmith

Aspect from a DEM: downslope azimuth in degrees, 0 = north. GeoTIFF in/out. FLAT CELLS ARE -1, not nodata — mask them before averaging aspect over an area, or the average is plausibly wrong. DEMs in a geographic CRS are refused (see slope): reproject to a projected CRS first. Requires the [whitebox] extra.

Buffer all features by a distance in meters. Geographic-CRS inputs are reprojected to an estimated UTM zone for the metric operation and back; the decision is recorded in the provenance manifest. A `warnings` key in the result flags a suspicious-but-valid outcome with a hint — e.g. a negative distance that eroded every geometry away.

One point per feature: the geometric centroid, computed in a metric CRS. Geographic-CRS inputs are measured in an estimated UTM zone (decision recorded in the manifest) and returned in the input CRS — a planar centroid of degree coordinates lands in the wrong place, quietly. The output is verified: same feature count, Point geometry, input CRS. Note the manifest's caveat: the centroid of a concave or multi-part feature can fall outside it. Inputs without a CRS are refused.

Clip a layer to the area of a mask layer. CRS are aligned automatically. A `warnings` key in the result means the analysis ran but something is worth your attention (typically an empty result, or inputs whose extents do not overlap); each entry carries a hint. Inputs without a CRS are refused.

Convert a vector dataset between formats; the target is chosen by the output extension (.parquet, .gpkg, .geojson). The output is re-read and verified: same feature count, same CRS. Two conversions are refused with the reason: shapefile (field names truncated to 10 characters, silently) and GeoJSON for non-WGS84 layers (RFC 7946 is WGS84 by definition — reproject first). Invalid geometry carried through is repaired deterministically and reported in a 'repairs' key.

Inspect a dataset, vector or raster, before analysing it. Vector: CRS, geometry types, schema, extent, feature count. A MULTI-LAYER container (e.g. a GeoPackage holding several layers) is described per layer — name, feature count, geometry type, CRS — because operations refuse containers with no chosen layer: extract the layer you mean first (run_sql: SELECT * FROM ST_Read(path, layer='name') with an output_path). Raster (.tif): CRS, grid size, resolution, bands with dtype, nodata and masked statistics (nodata cells counted separately). Call this first on any dataset you have not inspected yet — most silent GIS errors start with wrong assumptions about CRS, units, nodata or which layer you are on. Raster inspection requires the [raster] extra.

Merge features into one geometry per value of `by` (or one feature in all). aggfunc — first (default), last, sum, mean, median, min, max or count — is applied to the other columns and RECORDED in the manifest: a sum reported where a mean was meant is a plausible wrong number nobody can see. Features with a null `by` key are dropped by the grouping and the manifest counts them. The output feature count is verified against the number of distinct keys, so a wrong grouping fails loudly instead of shipping.

Validate, then execute a geoprocessing plan step by step. The plan is re-validated first (an invalid plan runs nothing). Steps run in order; "$step_id" references resolve to the outputs of earlier steps. Every step writes its own provenance manifest, and a plan-level manifest (<last output>.plan.json, with the plan sha256 and per-step outcomes) ties them together. Execution stops at the first failing step; outputs already produced stay on disk with their manifests. Same plan format as validate_plan — validate first, then execute. A `step_warnings` key in the response means the plan ran but some step produced a suspicious result (an empty output, non-overlapping inputs): read it before treating a completed plan as a correct one.

Split multi-part geometries into one feature per part (attributes copied). The output feature count is verified against the number of parts counted before the engine ran, so a lost part fails loudly instead of shipping. Inputs without a CRS are refused.

D8 flow accumulation from a DEM (GeoTIFF in/out). Depressions are filled first. out_type: 'cells' (upslope cell count, includes the cell itself) or 'sca' (specific catchment area). log_transform=True for visualization-friendly values. Requires the [whitebox] extra.

Return the manifest of the ONE operation that wrote this dataset. Its inputs with their digests, the exact parameters, the CRS decisions with reasons, engine and version, and every deterministic check with its result. One step, in full. For the whole chain that led here — the operations behind the inputs, and the ones behind those — the catalogue operation `get_lineage` walks it and returns each step summarised instead of one step complete; run it through `run_operation`. It is not a tool of its own on purpose: two exposed tools answering the same question about the same file is the overlap that makes an agent pick wrong.

Shaded relief from a DEM: GeoTIFF in, GeoTIFF out (values scaled 0-32767). azimuth = sun direction in degrees (default 315, NW); altitude = sun angle above the horizon (default 30). DEMs without a CRS are rejected. Requires the [whitebox] extra.

Find the operation you need. **Say what you have and what you want** — it matters more than the words you search with. Ranking alone does not scale, and this is measured rather than assumed. Over 118 requests written by other models against this catalog, searching by words alone finds the right operation in the top 3 a quarter of the time. Declaring what you already know does not make the ranking better — it makes the ranking unnecessary, because few enough operations survive that you get all of them: facets you declare candidates left ranked@3 in the answer (none) 51 25% 25% input_kind 33 29% 43% input_kind + produces 21 48% 100% That last column is not an accuracy figure. It is what happens when nothing is dropped: the right operation was in the answer for all 118 requests, by construction rather than by ranking. So fill these in whenever you know them, and you usually do: - **input_kind** — what you are holding: 'vector' (points, lines, polygons), 'raster' (a grid, a GeoTIFF), 'dataset' (either), 'plan', or 'none'. - **produces** — what you want back: 'dataset:vector', 'dataset:raster', 'answer' (a number, nothing written), 'description' (what something IS, rather than a computation over it), 'plan_result'. - **category** — the family, when you know it: vector, raster, terrain, hydrology, inspection, sql, network, planning, provenance, visualization, bridge. Unlike the others this one only ORDERS the results — a wrong guess about our families costs you positions, never the answer, so guessing is safe. - **projected** — pass False if your data is in a geographic CRS (degrees), and every operation that would refuse it disappears from the results. - **dataset_inputs** — how many datasets you are holding for this step: 1 if you have one layer, 2 if the operation…

Area per feature in SQUARE METRES, written to a named column, with the total in the result. method='geodesic' (default) measures ground area on the ellipsoid the layer's CRS names: no map plane, so no projection distortion. method= 'planar' measures in the layer's own CRS and converts with its declared linear unit — a layer in US survey feet is not assumed to be in metres — and is refused on a geographic CRS, where an area would be in square degrees. Two things this tool does that a bare area call cannot: invalid geometry is repaired BEFORE measuring (the planar area of a self-intersecting ring is the signed shoelace, a number matching no region, returned without complaint) and every repair is recorded; and a planar measurement is compared against the ground area, so a plane that is not equal-area here comes back with a `warnings` entry carrying the ratio — Web Mercator at 42° reports 1.80× the land it covers.

Append two or more layers into one (schema union, attributes aligned by name). Layers are reprojected to the FIRST layer's CRS when they differ; the decision is recorded in the provenance manifest. Columns present in only some inputs are null-filled in the others and the manifest names them — data that looks measured and is actually absent is a silent error. The output feature count is verified against the sum of the input counts. Inputs without a CRS are refused. This is an append, not a geometric union: use dissolve_layer to merge geometries afterwards.

Attach each feature's nearest neighbour from another layer, with the distance IN METERS in a named column. Geographic-CRS inputs are measured in an estimated UTM zone (decision recorded in the manifest) and returned in the input CRS — a nearest distance in degrees is the classic silent error of this operation, and it cannot happen here. max_distance_meters drops pairs farther than that; an emptied result comes back with a `warnings` entry, never silently.

Set-theoretic overlay of two layers: intersection (default), union, identity, symmetric_difference or difference. The overlay layer is reprojected to the input CRS when they differ; the decision is recorded in the provenance manifest. Overlay pieces of lower dimension than the inputs (shared edges, corner contacts) are dropped, and the manifest says so. Inputs without a CRS are refused; an empty result comes back with a `warnings` entry, never as a silent success.

Show datasets on the interactive in-chat map panel (MCP Apps). Pass the paths of one or more MapSmith outputs or source datasets (vector or GeoTIFF). Layers are previewed in EPSG:4326 with simplified geometry and capped feature counts sized to fit client limits; each layer card shows its provenance summary and verification status. Read-only: the datasets of record stay on disk. On clients without MCP Apps support the same payload is returned as structured data.

Reproject a layer to a target CRS, e.g. 'EPSG:32632' or a WKT string. Inputs without a CRS are refused. Geometry passes through unchanged, so an invalid input yields an invalid output: mechanically broken geometry is repaired deterministically and reported in a `repairs` key — read it, the geometry type may have changed.

Run ANY catalog operation by name, including the ones with no tool of their own — which is most of them, and increasingly so. The tools above are the handful an agent reaches for constantly. The catalog holds every operation MapSmith can perform, and it grows faster than the tool list on purpose: tool-selection accuracy degrades past a few dozen exposed tools, while capability count has no such ceiling. Discover with list_operations (use detail=true to get parameters and worked examples), then call it here. Arguments are validated against the catalog BEFORE anything runs — unknown operation, missing or misnamed argument, wrong type, path outside the workspace — and the errors come back with stable codes, so a failed call tells the planner what to fix instead of what went wrong. Execution goes through the same path as execute_plan, so an operation cannot behave one way here and another way in a plan.

Run spatial SQL (DuckDB dialect, ST_* functions, read_parquet/ST_Read for files). Without output_path: returns up to 50 preview rows. With output_path (.parquet): materializes the full result as GeoParquet with a provenance manifest.

MapSmith version, licensing, and available engines.

Simplify geometries (Douglas-Peucker, topology preserved) with the drift measured: the manifest records total area and length before and after. Geographic-CRS inputs are simplified in an estimated UTM zone (decision recorded) and returned in the input CRS — a tolerance in degrees is a different distance at every latitude. On projected CRS the tolerance is interpreted in the CRS units. The feature count is verified unchanged; vertex counts before/after are in the result. Inputs without a CRS are refused.

Slope gradient from a DEM: GeoTIFF in, GeoTIFF out. units: degrees (default), percent or radians. DEMs in a geographic CRS are refused — degree cells with meter elevations give plausible but wrong values everywhere; reproject to a projected CRS first. The CRS decision is recorded in the provenance manifest. Requires the [whitebox] extra.

Join by spatial predicate (intersects/within/contains). engine='auto' routes to the fastest available engine for the inputs: SedonaDB (heavy joins, 10-180x) > DuckDB (GeoParquet fast path) > GeoPandas. A `warnings` key in the result flags an empty join or inputs whose extents do not overlap, each with a hint. Inputs without a CRS are refused.

Statically validate a multi-step geoprocessing plan BEFORE running anything. Write the plan as steps in execution order; each step has a unique id, an operation name from list_operations, and its arguments. Use "$step_id" as an argument value to consume the output dataset of an earlier step. Checks: operations exist and are installed, arguments complete and well-typed, references resolve backwards (mis-ordered steps are rejected), input files exist, outputs don't collide, and CRS flow is simulated end-to-end from the real input files. Returns machine-actionable errors/warnings/notes plus the simulated output CRS per step. Nothing is executed and nothing is written. Example plan: {"goal": "wells at risk", "steps": [ {"id": "buf", "operation": "buffer_layer", "arguments": {"input_path": "wells.gpkg", "distance_meters": 300, "output_path": "buf.parquet"}}, {"id": "cut", "operation": "clip_layer", "arguments": {"input_path": "$buf", "mask_path": "zone.gpkg", "output_path": "risk.parquet"}}]}

Watershed of each pour point: DEM + points in, basin raster out (GeoTIFF). Basins get 1-based IDs following the pour-point feature order; cells not draining to any point stay nodata. Points are aligned to the DEM CRS automatically (decision recorded). Requires the [whitebox] extra.

Statistics of a raster within each vector zone (exact fractional pixel coverage). stats: subset of count/sum/mean/median/min/max/stdev/variance/majority/minority/ variety (default: count, mean, min, max). Zones are aligned to the raster CRS automatically; the decision is recorded in the provenance manifest. weights_path: a single-band raster of weights on the SAME grid as the values (same CRS, cells and registration; otherwise refused with how to align it), for weighted_mean/weighted_sum/weighted_stdev/weighted_variance/weighted_frac -- e.g. mean heat per zone weighted by population (default stats then: count, mean, weighted_mean). A cell with a value and no weight counts with weight 0, and the record names the zones where that happened. Zones without a CRS are refused; `warnings` and `repairs` keys in the result flag a suspicious outcome or geometry MapSmith had to repair. Requires the [raster] extra.