A computer vision pipeline for exploring and analyzing images at scale

View the Project on GitHub Living-with-machines/MapReader


A computer vision pipeline for exploring and analyzing images at scale

PyPI License Integration Tests badge

What is MapReader?

Annotated Map with Prediction Outputs

MapReader is an end-to-end computer vision (CV) pipeline for exploring and analyzing images at scale.

MapReader was developed in the Living with Machines project to analyze large collections of historical maps but is a generalisable computer vision pipeline which can be applied to any images in a wide variety of domains.


MapReader is a groundbreaking interdisciplinary tool that emerged from a specific set of geospatial historical research questions. It was inspired by methods in biomedical imaging and geographic information science, which were adapted for annotation and use by historians, for example in JVC and MapReader papers. The success of the tool subsequently generated interest from plant phenotype researchers working with large image datasets, and so MapReader is an example of cross-pollination between the humanities and the sciences made possible by reproducible data science.

MapReader pipeline

The MapReader pipeline consists of two main components:

  1. preprocessing/annotation
  2. training/inference

MapReader pipeline

What is included?

The MapReader package provides a set of tools to:

Various plotting and analysis functionalities are also included (based on packages such as matplotlib, cartopy, Google Earth, and


The MapReader documentation can be found here.

New users should refer to the Installation instructions and Input guidance for guidance on the initial set up of MapReader.

All users should refer to our User Guide for guidance on how to use MapReader. This contains end-to-end instructions on how to use the MapReader pipeline, plus a number of worked examples illustratng use cases such as:

Developers and contributors may also want to refer to the API documentation and Contribution guide for guidance on how to contribute to the MapReader package.

How to cite MapReader

If you use MapReader in your work, please consider acknowledging us by citing our paper:


This work was supported by Living with Machines (AHRC grant AH/S01179X/1) and The Alan Turing Institute (EPSRC grant EP/N510129/1).

Living with Machines, funded by the UK Research and Innovation (UKRI) Strategic Priority Fund, is a multidisciplinary collaboration delivered by the Arts and Humanities Research Council (AHRC), with The Alan Turing Institute, the British Library and the Universities of Cambridge, East Anglia, Exeter, and Queen Mary University of London.

Maps above reproduced with the permission of the National Library of Scotland