MapReader is an end-to-end computer vision (CV) pipeline designed by the Living with Machines project. It has two main components: preprocessing/annotation and training/inference:
MapReader provides a set of tools to:
- load images/maps stored locally or retrieve maps via web-servers (e.g., tileservers which can be used to retrieve maps from OpenStreetMap (OSM), the National Library of Scotland (NLS), or elsewhere).
⚠️ Refer to the credits and re-use terms section if you are using digitized maps or metadata provided by NLS. - preprocess images/maps (e.g., divide them into patches, resampling the images, removing borders outside the neatline or reprojecting the map).
- annotate images/maps or their patches (i.e. slices of an image/map) using an interactive annotation tool.
- train, fine-tune, and evaluate various CV models.
- predict labels (i.e., model inference) on large sets of images/maps.
- Other functionalities include:
- various plotting tools using, e.g., matplotlib, cartopy, Google Earth, and kepler.gl.
- compute mean/standard-deviation pixel intensity of image patches.
Below is an example of MapReader CV model output (see the paper on MapReader for more details):
British 'railspace' and buildings as predicted by a MapReader computer vision model. ~30.5M patches from ~16K nineteenth-century Ordnance Survey map sheets were used (courtesy of the National Library of Scotland). (a) Predicted railspace; (b) predicted buildings; (c) and (d) predicted railspace (red) and buildings (black) in and around Middlesbrough and London, respectively. MapReader extracts information from large images or a set of images at a patch level, as depicted in the insets. For both railspace and buildings, we removed those patches that had no other neighboring patches with the same label within a distance of 250 meters.
- Installation and setup
- Tutorials are organized in Jupyter Notebooks as follows:
- Classification
- classification_one_inch_maps_001
- Goal: train/fine-tune PyTorch CV classifiers on historical maps.
- Dataset: from National Library of Scotland: OS one-inch, 2nd edition layer.
- Data access: tileserver
- Annotations are done on map patches (i.e., slices of each map).
- Classifier: train/fine-tuned PyTorch CV models.
- classification_one_inch_maps_001
- Classification
- How to cite MapReader
- Credits and re-use terms
- Digitized maps: MapReader can retrieve maps from NLS via tileserver. Read the re-use terms in this section.
- Metadata: the metadata files are stored at mapreader/persistent_data. Read the re-use terms in this section.
- Acknowledgements
We strongly recommend installation via Anaconda:
-
Create a new environment for
mapreadercalledmr_py38:
conda create -n mr_py38 python=3.8- Activate the environment:
conda activate mr_py38- Install
mapreader:
pip install git+https://github.com/Living-with-machines/MapReader.git- On Windows, you might need to do:
# activate the environment
conda activate mr_py38
# install rasterio and fiona manually
conda install -c conda-forge rasterio=1.2.10
conda install -c conda-forge fiona=1.8.20
# install git
conda install git
# install MapReader
pip install git+https://github.com/Living-with-machines/MapReader.git
# open Jupyter Notebook (if you want to test/work with the notebooks in "examples" directory)
cd /path/to/MapReader
jupyter notebook- We have provided some Jupyter Notebooks to show how different components in MapReader can be run. To allow the newly created
mr_py38environment to show up in the notebooks:
python -m ipykernel install --user --name mr_py38 --display-name "Python (mr_py38)"- Continue with the Tutorials!
- Clone
mapreadersource code:
git clone https://github.com/Living-with-machines/MapReader.git - Install using poetry:
cd /path/to/MapReader
poetry install
poetry shell- Continue with the Tutorials!
Please consider acknowledging MapReader if it helps you to obtain results and figures for publications or presentations, by citing:
Link: https://arxiv.org/abs/2111.15592
Kasra Hosseini, Daniel C. S. Wilson, Kaspar Beelen and Katherine McDonough (2021), MapReader: A Computer Vision Pipeline for the Semantic Exploration of Maps at Scale, arXiv:2111.15592.
and in BibTeX:
@misc{hosseini2021mapreader,
title={MapReader: A Computer Vision Pipeline for the Semantic Exploration of Maps at Scale},
author={Kasra Hosseini and Daniel C. S. Wilson and Kaspar Beelen and Katherine McDonough},
year={2021},
eprint={2111.15592},
archivePrefix={arXiv},
primaryClass={cs.CV}
}MapReader can retrieve maps from NLS (National Library of Scotland) via webservers. For all the digitized maps (retrieved or locally stored), please note the re-use terms:
We have provided some metadata files in mapreader/persistent_data. For all these file, please note the re-use terms:
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.