MapReader
A computer vision pipeline for the semantic exploration of maps at scale
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.
Table of contents
- 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
Installation
Set up a conda environment
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
Method 1
- Install
mapreader:
pip install git+https://github.com/Living-with-machines/MapReader.git
- 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!
Method 2
- 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!
How to cite MapReader
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}
}
Credits and re-use terms
Digitized maps
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:
Metadata
We have provided some metadata files in mapreader/persistent_data. For all these file, please note the re-use terms:
Acknowledgements
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.
11 Jan 07, 2022
72 Dec 30, 2022
971 Dec 25, 2022
329 Dec 05, 2022
39 Jan 03, 2023
48 Dec 21, 2022
2.9k Jan 06, 2023
1 Jan 04, 2022
12 Aug 30, 2022
1 Jan 23, 2022
560 Jan 03, 2023
1 Feb 07, 2022
6.3k Jan 08, 2023
1 Dec 14, 2021
18 Nov 28, 2022
5 Sep 27, 2021
96 Jan 01, 2023
104 Nov 27, 2022
65 Dec 09, 2022
3 Jun 27, 2021