Key Takeaways
- A scanned map is only a picture: a computer cannot tell which real place it shows. AI geology tools need to know it. Only then can they look up earthquakes, faults (cracks in the Earth’s crust) or mineral finds in the area.
- Georeferencing pins the picture to the Earth, like dropping a pin on an online map. You give it a few control points. These are spots whose position you know on both the picture and the ground, such as the numbers printed at its corners.
- Two or three points always fit perfectly, the way any two dots can be joined by a straight line. So a mistyped number goes unnoticed. With four or more, the tool can check its own work and warn you that one point is probably wrong.
TL;DR
This step turns a scanned map into a map that knows where it is on Earth. You read a few known positions off it, usually the coordinates printed at its corners. The tool then works out where every other spot lies. Give it at least four, so it can warn you when one was typed wrong.
What Is geomap_georeference?
geomap_georeference is the georeferencing tool in Stratigraphic Amenity, Eigenform’s open-source (MIT) MCP server for scanned geologic maps. It fits an affine transform, six numbers that turn a pixel position into a map coordinate, then reports the map’s bounds in longitude and latitude, the coordinates most AI geology tools expect.
It needs a coordinate reference system (CRS) and at least two ground control points (GCPs). The CRS can be an EPSG code or UTM text as printed on a map, such as “UTM N83 Zone 15”. The tool resolves that to EPSG:26915. Each GCP gives a pixel position (pixel_x, pixel_y) and the matching world position (world_x, world_y) in that CRS.
The server does not read coordinates off the map itself. The numbers come from the user, or from a separate OCR or vision model reading the corner crops that map part detection produces.
How Do I Georeference a Scanned Map With AI?
Three choices decide whether the result can be trusted.
Tell it which part of the image is the map
It also needs the pixel extent of the map panel, to turn the panel’s corners into longitude and latitude. It takes the first one it finds: an explicit pixel_extent, the box of a named main-map crop, or the main map stored when the map was processed. With none of them, the call fails with invalid_bounds.
Pass map_id or map_uri when the map is registered, so the result is saved against it. Without one, the tool calculates the fit but stores nothing.
Two, three or four-plus control points
The number of points decides the fitting method.
| Control points | Fit method | What the error figures mean |
|---|---|---|
| 2 | axis-aligned-exact-2gcp (scale and offset, no rotation) | Always zero; the points must differ in both pixel x and pixel y |
| 3 | affine-exact-3gcp | Effectively zero; the points must not lie on one line |
| 4 or more | affine-least-squares | Meaningful, and a leave-one-out check runs |
With fewer than four points the result sets residual_diagnostic: false and warns: “an exact fit has no independent error check; supply at least 4 well-distributed GCPs”.
Read residual_m and holdout_error together
residual_m is the fit’s root-mean-square error in metres. holdout_error leaves out each point in turn, predicts it from the others, and reports the worst miss. When holdout_error is much larger than residual_m, one point was probably read wrong.
In our worked georeferencing example, an easting misread by 300 m gave a residual of only 75 m, spread across all four points. The holdout error came back at 300.03 m. Warnings also flag a map that looks upside down or strongly rotated, which usually means a mistyped sign or swapped points.
Georeference Revisions and What Comes Next
Each call on a registered map writes a new, permanent revision, geomap://maps/<id>/georef/<N>.json, and points the alias geomap://maps/<id>/georef.json at it. Later tools read that alias. Older revisions stay on disk, so an agent can compare fits or cite the one it relied on.
The tool is not idempotent: running it twice creates two revisions, so fix the points first.
The fit is affine only. A warped or folded scan cannot be corrected, a map crossing the 180th meridian produces one very wide box, and several later steps assume north is up. For most AI geology work, such as finding faults or earthquakes inside a map sheet, those limits rarely matter.
FAQs
How many ground control points do I need?
Two is the minimum and four is the practical answer. Two or three points always fit exactly, so the error figure is zero even when a point is wrong. Four or more well-spread points allow a leave-one-out check that can reveal a single misread coordinate.
What is the difference between residual_m and holdout_error?
residual_m is how far the fitted transform misses the control points overall, as a root-mean-square error in metres. holdout_error refits without each point in turn and reports the worst prediction error. Least squares spreads one bad point across all points, so a holdout error far above the residual usually exposes a single mistake.
Where do the control point coordinates come from?
They come from the map itself: grid ticks and coordinate labels printed around the map frame, usually near the corners. The server reads no text, so the user or a separate OCR or vision model in the AI geology workflow supplies the numbers. Map part detection saves a crop of the four corners to make that reading easier.
What happens when I georeference the same map again?
The tool writes a new revision instead of overwriting the old one, and points the georef.json alias at it. Every earlier revision keeps its own URI, so an agent can show which fit an answer used.
Try It With Geocluster
Stratigraphic Amenity is one of the Geocluster tools, MCP servers that let AI agents work with geology data and maps.
Before this step, an agent checks what the map server can do, so it knows georeferencing is installed and ready.
