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.
229 Dec 29, 2022
2 Jan 20, 2022
1 Nov 18, 2021
17 Dec 05, 2022
3 Oct 23, 2022
5 Dec 22, 2021
8 Oct 18, 2022
1 Jan 12, 2022
0 Dec 22, 2021
0 Nov 10, 2021
1 Jan 19, 2022
7 Mar 15, 2022
1.2k Dec 27, 2022
102 Nov 10, 2022
7.2k Dec 30, 2022
0 Jul 05, 2022
2 Oct 23, 2021
1 Jan 26, 2022
107 Jan 04, 2023
95 Dec 13, 2022