Putting a scanned map on a live map

A lot of useful geography lives in pictures: a scanned 1960s survey, a PDF site plan from an architect, an aerial photo from a drone that never wrote a world file. None of it has coordinates, so none of it lines up with your data.

The georeferencer in the MapSocket dashboard fixes that. Upload the image, match points on it to points on the map, and publish. You get raster tiles that sit under your live vector layers, and a Cloud-Optimized GeoTIFF to download.

Matching points

A ground control point (GCP) pairs a pixel on your image with a longitude and latitude. You click a road junction on the scan, then the same junction on the map. Three points are enough to start; more points, spread across the whole image, give a better fit.

As soon as there are three, the image shows up on the map as a semi-transparent overlay, so you can see straight away whether things line up.

Choosing a transform

Transform	Points needed	Use it when
Affine	3	The image is only shifted, rotated and scaled
Polynomial	6	Old or folded paper with gentle, even warping
Thin-plate spline	3	The image needs to bend locally through every point

Affine is the right choice more often than people expect. A modern site plan or a clean scan of a printed map is usually just rotated and scaled. Polynomial and spline transforms can make a poor set of points look perfect while distorting everything between them.

How far off is each point?

For affine and polynomial fits, every point gets a residual: how far, in meters on the ground, the fitted transform puts that point from where you said it was. We fit in Web Mercator and convert back to ground meters, so a residual means the same thing in Oslo as in Singapore.

Each point is graded against the median residual of the set, not the average. With five or six points, one mistyped point can double the average and hide among the “normal” ones. Against the median, it stands out.

A thin-plate spline passes through every point exactly, so its own residuals are always zero and tell you nothing. For splines we show an affine check instead: the residuals the same points would have under an affine fit. A point that’s far off in the affine check is either genuine local distortion or a mistake, and it’s worth a second look.

Publishing

Publishing runs the image through GDAL:

1. Attach the GCPs to the image.
2. If you drew a crop, apply it so the map’s margin and legend don’t end up on the map.
3. Warp to Web Mercator with the transform you chose, writing a Cloud-Optimized GeoTIFF.
4. Cut PNG tiles from the image’s native resolution down eight zoom levels.

The new tiles replace the old ones in one step, so a republish never leaves a half-updated map. What gets published is exactly what you saved when you pressed Publish, even if you keep editing points while it runs.

In a recent test, a 4608 × 3072 px image stitched together from six map tiles of Paris was matched with residuals of 0.3–0.7 m, and the published tiles lined up with the basemap.

Using the tiles

Published maps get a TileJSON URL that works with any key in the project:

map.addSource("survey-1962", {
  type: "raster",
  url: "https://tiles.mapsocket.com/t/georef/<map-id>.json?key=pk_live_…",
  tileSize: 256,
});
map.addLayer({ id: "survey-1962", type: "raster", source: "survey-1962", paint: { "raster-opacity": 0.8 } });

Georeferenced maps are on every plan: one per project on the free plan, ten on Starter, a hundred on Pro. The guide and the API reference have the details.