Skip to main content

A computer vision pipeline for the semantic exploration of maps/images at scale

Project description


MapReader

A computer vision pipeline for exploring and analyzing images at scale

PyPI License Integration Tests badge DOI

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 generalizable computer vision pipeline which can be applied to any images in a wide variety of domains.

Overview

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 use by historians, for example in our Journal of Victorian Culture and Geospatial Humanities 2022 SIGSPATIAL workshop 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

MapReader pipeline

The MapReader pipeline consists of a linear sequence of tasks which, together, can be used to train a computer vision (CV) classifier to recognize visual features within maps and identify patches containing these features across entire map collections.

See our About MapReader page to learn more.

Documentation

The MapReader documentation can be found at https://mapreader.readthedocs.io/en/latest/index.html.

New users should refer to the Installation instructions and Input guidance for help with 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 illustrating use cases such as:

  • Geospatial images (i.e. maps)
  • Non-geospatial images

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.

Join our Slack workspace! Please fill out this form to receive an invitation to the Slack workspace.

What is included in this repo?

The MapReader package provides a set of tools to:

  • Download images/maps and metadata stored on web-servers (e.g. tileservers which can be used to retrieve maps from OpenStreetMap (OSM), the National Library of Scotland (NLS), or elsewhere).
  • Load images/maps and metadata stored locally.
  • Pre-process images/maps:
    • patchify (create patches from a parent image),
    • resample (use image transformations to alter pixel-dimensions/resolution/orientation/etc.),
    • remove borders outside the neatline,
    • reproject between coordinate reference systems (CRS).
  • Annotate images/maps (or their patches) using an interactive annotation tool.
  • Train or fine-tune Computer Vision (CV) models and use these to predict labels (i.e. model inference) on large sets of images/maps.

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

How to cite MapReader

If you use MapReader in your work, please cite both the MapReader repo and our SIGSPATIAL paper:

  • Kasra Hosseini, Daniel C. S. Wilson, Kaspar Beelen, and Katherine McDonough. 2022. MapReader: a computer vision pipeline for the semantic exploration of maps at scale. In Proceedings of the 6th ACM SIGSPATIAL International Workshop on Geospatial Humanities (GeoHumanities '22). Association for Computing Machinery, New York, NY, USA, 8โ€“19. https://doi.org/10.1145/3557919.3565812
  • Kasra Hosseini, Rosie Wood, Andy Smith, Katie McDonough, Daniel C.S. Wilson, Christina Last, Kalle Westerling, and Evangeline Mae Corcoran. โ€œLiving-with-machines/mapreader: End of Lwmโ€. Zenodo, July 27, 2023. https://doi.org/10.5281/zenodo.8189653.

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.

Maps above reproduced with the permission of the National Library of Scotland https://maps.nls.uk/index.html

Contributors

All Contributors

Katie McDonough
Katie McDonough

๐Ÿ”ฌ ๐Ÿค” ๐Ÿ“– ๐Ÿ“‹ ๐Ÿ“† ๐Ÿ‘€ ๐Ÿ“ข โœ…
Daniel C.S. Wilson
Daniel C.S. Wilson

๐Ÿ”ฌ ๐Ÿค” ๐Ÿ“ข ๐Ÿ“– ๐Ÿ“‹
Kasra Hosseini
Kasra Hosseini

๐Ÿ’ป ๐Ÿค” ๐Ÿ”ฌ ๐Ÿ‘€ ๐Ÿ“ข
Rosie Wood
Rosie Wood

๐Ÿ’ป ๐Ÿ“– ๐Ÿค” ๐Ÿ“ข โœ… ๐Ÿ‘€ ๐Ÿšง ๐Ÿ”ฌ
Kalle Westerling
Kalle Westerling

๐Ÿ’ป ๐Ÿ“– ๐Ÿšง ๐Ÿ‘€ ๐Ÿ“ข
Chris Fleet
Chris Fleet

๐Ÿ”ฃ
Kaspar Beelen
Kaspar Beelen

๐Ÿค” ๐Ÿ‘€ ๐Ÿ”ฌ
Andy Smith
Andy Smith

๐Ÿ’ป ๐Ÿ“– ๐Ÿง‘โ€๐Ÿซ ๐Ÿ‘€

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mapreader-1.1.4.tar.gz (116.6 kB view hashes)

Uploaded Source

Built Distribution

mapreader-1.1.4-py3-none-any.whl (97.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page