# The NYPL map vectorizer turns georectified atlas sheets into shapefiles

> map-vectorizer is a MIT licensed Python and R pipeline that automates polygon and attribute extraction from georectified historical maps, built on a workflow suggested by Michael Resig. It suits institutions digitising scanned atlases, and it assumes a working R, GIMP and GDAL stack.

**nypl-spacetime/map-vectorizer** — An open-source map vectorizer

- Repository: https://github.com/nypl-spacetime/map-vectorizer
- Stars: 660 · Forks: 57
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nypl-spacetime-map-vectorizer

## The problem is the manual tracing of atlases nobody can afford

The New York Public Library holds hundreds of atlases with tens of thousands of sheets, and the README states plainly that there is no way to extract the data manually in a reasonable amount of time. To give the scale, staff coordinating a group of volunteers took three years to produce 170,000 polygons with attributes, and that covered just four of the hundreds of atlases. The pipeline described here generates a comparable number of polygons with some basic metadata in a period closer to 24 hours. That comparison is the whole argument for the project, and it is also the reason the output is described as having some basic metadata rather than complete attributes. The target inputs are georectified images, which the README explains are geographically normalized versions of the original sheets.

## The pipeline is Python at the edges and R in the middle

The repository layout makes the architecture clear enough to reason about. vectorize_map.py is the entry point, vectorize_verify.r is the R counterpart, simplify_map.R handles simplification, and the map_vectorizer directory and bin directory hold the Python internals. requirements.txt lists four dependencies, Pillow, gdal at version 1.11.2, numpy and opencv-python, which tells you image handling comes from OpenCV and Pillow while GDAL does the geospatial IO. R supplies the geometric heavy lifting: alphahull for the concave hull of extracted shapes, igraph for graph work on the detected features, shapefiles for the output format and rgdal for the spatial data handling. The Python side does the image processing and the R side does the geometry.

## R, GIMP and GDAL have to be on the machine before anything runs

The dependency list is the honest part of this project. R must be on your PATH so you can run it from the command line, and four R packages have to be installed, alphahull with tripack, sgeostat and splancs as its dependencies, plus igraph, shapefiles and rgdal. The README gives an OS X route through the Packages and Data installer and also a command line route.

```
    install.packages('rgdal')
    install.packages('alphahull')
    install.packages('igraph')
    install.packages('shapefiles')
```

GIMP is needed as well, because the vectorizer drives GIMP as a subprocess to trace the shapes. On OS X the default path baked into the tool points at the old GIMP 2.8 bundle, so the location has to be supplied unless your install matches. GDAL Tools must be on the PATH as well, and on OS X that takes an extra step, appending the framework path to your shell profile.

```
    echo 'export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH' >> ~/.bash_profile
    source ~/.bash_profile
```

The README notes the whole setup was tested on Mac OS X Lion, so the instructions apply to that configuration only.

## The command line takes a file or a folder and a GIMP path

The vectorizer is driven from vectorize_map.py and its usage is short. One argument is required and one is effectively required in practice.

```bash
usage: vectorize_map.py [-h] --gimp-path GIMP_PATH [--chunksize CHUNKSIZE]
                        [--image-processing-configuration-file VECTORIZE_CONFIG]
                        <input file or dir>
```

The input argument accepts a single file or a folder of files, which is how you would run it over a whole atlas. The GIMP path defaults to the Mac OS X location and has to be overridden when GIMP lives somewhere else. The image processing configuration file defaults to vectorize_config_default.txt, and the README is explicit that you will want your own because your maps do not look like the test map. The chunksize option exists and the documentation tells you to ignore it. The first run on the bundled test.tif is the point at which the tool asks you to accept or replace the GIMP folder location.

## Output is a shapefile set next to two log files, and it takes about 70 seconds

When a run succeeds you get a folder named after the input, in the case of the bundled example a test folder, containing a traced set of files with the .shp, .dbf, .prj and .shx extensions, plus two log files. The .shp, .shx and .dbf trio is the classic ESRI shapefile layout, and the .prj holds the projection. The README gives a runtime expectation of about 70 seconds for the test image and warns that a much faster run may indicate an error. That is a useful debugging heuristic for a pipeline with a GIMP subprocess, a set of R libraries and a GDAL write step, since any of them can fail quietly. Two log files are produced alongside the data, and reading them is the difference between a failed run and a successful one.

## Filenames with spaces break the vectorizer, and the shape list is capped

The documented failure mode is blunt. The vectorizer has problems with filenames that contain spaces, and the README says this will be supported eventually. For a batch tool meant to run over tens of thousands of scanned sheets, that is not a minor annoyance, it is a preprocessing obligation: names have to be normalised before the tool sees them, and any renaming has to be mirrored back on the output side. There is a second constraint in the features the project aims to extract. Shape and colour are marked as mostly solved. Dot presence, dot count and dot type, meaning full versus outline, are marked as in progress. Skylights are not solved, and extracting the numbers printed on the sheet is explicitly described as not optimistic.

## MIT licensing and no releases, with the last push in June 2026

The licence is MIT, which makes the code easy to reuse inside an institution that wants to modify it, and the project was published by NYPL Labs as is. There are no GitHub releases, so there is no versioned artefact to pin and no changelog of tagged improvements to point at; the last push was on 2026-06-05 and the repository is not archived. A paper on the process was published in the MapInteract '13 proceedings of the first ACM SIGSPATIAL international workshop on MapInteraction, where it won a best paper award, and the paper is included in the repository as map-poly-paper.pdf. Output can be checked by volunteers with the separate Building Inspector project, which is a useful arrangement for an institution that wants human verification of machine output without building the review tool itself.

## Conclusion

Adopt map-vectorizer if you hold a pile of georectified scanned sheets, as the New York Public Library does with hundreds of atlases, and want polygon outlines and basic colour attributes produced by a repeatable pipeline rather than by volunteers tracing each building. Do not adopt it if you need finished vector data with verified attributes today, since dot count, dot type and the numbers on the sheet are still listed as work in progress and skylights are not solved. Verify first that your runtime can install the R packages alphahull, igraph, shapefiles and rgdal and that GIMP and the GDAL command line tools are on your PATH, then run the shipped test.tif and confirm the output folder appears before you point the tool at your own scans.

## FAQ

### What does map-vectorizer do?

It automates the extraction of geographic polygon and attribute data from georectified map images, producing shapefiles with .shp, .dbf, .prj and .shx files. The README compares it to OCR for maps.

### What does map-vectorizer need installed?

Python with OpenCV and Pillow, R with the alphahull, igraph, shapefiles and rgdal packages, GIMP, and the GDAL command line tools on the PATH. The instructions were tested on Mac OS X Lion.

### How do I run map-vectorizer on a test image?

Run python vectorize_map.py test.tif from the repository, accept the GIMP folder location or enter your own, and a test folder with the traced shapefile set and two log files appears after roughly 70 seconds.

### Can map-vectorizer read the numbers printed on old map sheets?

Not yet. Shape and colour are marked as mostly solved, while dot presence, dot count and dot type are in progress, and the README says extracting numbers is not optimistic.

## Sources

- [Issues](https://github.com/nypl-spacetime/map-vectorizer/issues)
- [License: MIT](https://github.com/nypl-spacetime/map-vectorizer/blob/master/LICENSE)
- [nypl-spacetime/map-vectorizer on GitHub](https://github.com/nypl-spacetime/map-vectorizer)
- [README](https://github.com/nypl-spacetime/map-vectorizer/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nypl-spacetime-map-vectorizer