Merge pull request #507 from maps-as-data/rw_docs

Update README and docs with text spotting

README.md

@@ -1,24 +1,22 @@
 # MapReader
 
-**MapReader is a computer vision pipeline for exploring and analyzing images at scale.**
-
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square)](#contributors)
-<!-- ALL-CONTRIBUTORS-BADGE:END -->
-
 ![PyPI](https://img.shields.io/pypi/v/MapReader)
 ![License](https://img.shields.io/badge/License-MIT-yellow.svg)
 ![Integration Tests badge](https://github.com/Living-with-machines/MapReader/actions/workflows/mr_ci.yml/badge.svg)
 ![DOI](https://zenodo.org/badge/430661738.svg)
 ![CodeCov](https://codecov.io/github/Living-with-machines/MapReader/graph/badge.svg?token=38GQ3O1GB5)
+[![DOI](https://joss.theoj.org/papers/10.21105/joss.06434/status.svg)](https://doi.org/10.21105/joss.06434)
 
 ## Table of Contents
 
 - [MapReader](#mapreader)
   - [Table of Contents](#table-of-contents)
   - [What is MapReader?](#what-is-mapreader)
   - [Overview](#overview)
-    - [MapReader pipeline](#mapreader-pipeline)
+    - [MapReader classification pipeline](#mapreader-classification-pipeline)
+    - [MapReader text spotting pipeline](#mapreader-classification-pipeline)
   - [Documentation](#documentation)
   - [What is included in this repo?](#what-is-included-in-this-repo)
   - [How to cite MapReader](#how-to-cite-mapreader)
@@ -30,74 +28,79 @@
 
 ## What is MapReader?
 
-MapReader is an end-to-end computer vision (CV) pipeline for exploring and analyzing images at scale.
+**MapReader is a open-source python library for exploring and analyzing map images at scale.**
 
-<figure align="center">
-  <img src="https://raw.githubusercontent.com/Living-with-machines/MapReader/main/docs/source/_static/river_banner_8bit.png"
-      alt="Annotated Map with Prediction Outputs"
-      width="70%">
-</figure>
+It contains two different pipelines:
 
-MapReader was developed in the [Living with Machines](https://livingwithmachines.ac.uk/) 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.
+- Classification pipeline: This pipeline enables users to fine-tune a classification model and predict the labels of patches created from a parent image.
+- Text spotting pipeline: This pipeline enables users to detect and recognize text in map images.
 
-## Overview
+MapReader was developed in the [Living with Machines](https://livingwithmachines.ac.uk/) project to analyze large collections of historical maps but is a _**generalizable**_ computer vision tool 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 use by historians, for example in our [Journal of Victorian Culture](https://doi.org/10.1093/jvcult/vcab009) and [Geospatial Humanities 2022 SIGSPATIAL workshop](https://arxiv.org/abs/2111.15592) 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.
+## Overview
 
-### MapReader pipeline
+### MapReader classification 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:
+The MapReader classification pipeline enables users to train a classification model to recognize visual features within map images and to identify patches containing these features across entire map collections:
 
 <figure align="center">
-  <img src="https://raw.githubusercontent.com/Living-with-machines/MapReader/main/docs/source/_static/pipeline_explained.png"
+  <img src="https://raw.githubusercontent.com/maps-as-data/MapReader/main/docs/source/_static/pipeline_explained.png"
         alt="MapReader pipeline"
         width="70%">
 </figure>
 
-See our [Introduction to MapReader](https://mapreader.readthedocs.io/en/latest/introduction-to-mapreader/) page to learn more.
+### MapReader text spotting pipeline
+
+The MapReader text spotting pipeline enables users to detect and recognize text in map images using a pre-trained text spotting model:
+
+<figure align="center">
+  <img src="https://raw.githubusercontent.com/maps-as-data/MapReader/main/docs/source/_static/text-spotting-pipeline.png"
+        alt="MapReader text spotting pipeline"
+        width="70%">
+</figure>
 
 ## Documentation
 
 The MapReader documentation can be found at https://mapreader.readthedocs.io/en/latest/.
 
 **New users** should refer to the [Installation instructions](https://mapreader.readthedocs.io/en/latest/getting-started/installation-instructions/index.html) and [Input guidance](https://mapreader.readthedocs.io/en/latest/using-mapreader/input-guidance/) for help with the initial set up of MapReader.
 
-**All users** should refer to our [User Guide](https://mapreader.readthedocs.io/en/latest/using-mapreader/) 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
+**All users** should refer to our [User Guide](https://mapreader.readthedocs.io/en/latest/using-mapreader/) for guidance on how to use MapReader.
+This contains end-to-end instructions on how to use the MapReader pipeline.
 
  **Developers and contributors** may also want to refer to the [API documentation](https://mapreader.readthedocs.io/en/latest/in-depth-resources/api/mapreader/) and [Contribution guide](https://mapreader.readthedocs.io/en/latest/community-and-contributions/contribution-guide/) for guidance on how to contribute to the MapReader package.
 
+
+## Stay in touch
+
+**All users** are encouraged to join our community! Please refer to the [Community and contributions](https://mapreader.readthedocs.io/en/latest/community-and-contributions/events.html) page for information on ways to get involved.
+
 **Join our Slack workspace!**
 Please fill out [this form](https://forms.gle/dXjECHZQkwrZ3Xpt9) to receive an invitation to the Slack workspace.
 
 ## What is included in this repo?
 
-The MapReader package provides a set of tools to:
+This repository contains everything needed for running MapReader.
 
-- **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.
+The repository is structured as follows:
 
-Various **plotting and analysis** functionalities are also included (based on packages such as _matplotlib_, _cartopy_, _Google Earth_, and _[kepler.gl](https://kepler.gl/))_.
+- `mapreader/`: Contains the source code for the MapReader library.
+- `docs/`: Contains the documentation for the MapReader library.
+- `tests/` and `test_text_spotting/`: Contains the tests for the MapReader library.
+- `worked_examples/`: Contains worked examples of how to use the MapReader library.
 
 ## How to cite MapReader
 
-If you use MapReader in your work, please cite both the MapReader repo and [our SIGSPATIAL paper](https://dl.acm.org/doi/10.1145/3557919.3565812):
+If you use MapReader in your work, please cite:
+- Our [JOSS paper](https://doi.org/10.21105/joss.06434) - to acknowledge the software irrespective of the version you used.
+- Our [Zenodo record](https://zenodo.org/records/13643609) - to acknowledge the specific version of the software you used (or use the "Cite all versions?" option if your specific version isn't there).
+- Optionally, our [SIGSPATIAL paper](https://dl.acm.org/doi/10.1145/3557919.3565812) to acknowledge the development of the software and the research behind it.
 
-- 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.
+<!-- Add bibtext entries for the papers here -->
 
 ## Acknowledgements
 
-This work was supported by Living with Machines (AHRC grant AH/S01179X/1) and The Alan Turing Institute (EPSRC grant EP/N510129/1).
+This work was supported by Living with Machines (AHRC grant AH/S01179X/1), Data/Culture (AHRC grant AH/Y00745X/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.
 

docs/source/getting-started/installation-instructions/2-install-mapreader.rst

@@ -20,6 +20,8 @@ To install ``mapreader`` without the text spotting dependencies (i.e. just the c
 
 .. note:: To install the dev dependencies too, use ``pip install "mapreader[dev]"``.
 
+To install the text-spotting dependencies, head to the :doc:`Spot text </using-mapreader/step-by-step-guide/6-spot-text>` section of the user guide!
+
 Method 2: Install from source
 -----------------------------
 

docs/source/introduction-to-mapreader/what-is-mapreader.rst

@@ -1,7 +1,24 @@
 What is MapReader?
 ===================
 
-MapReader is an end-to-end computer vision (CV) pipeline for exploring and analyzing images at scale.
+MapReader is an open-source python library for exploring and analyzing images at scale.
+
+It contains two different pipelines:
+
+- Classification pipeline: This pipeline enables users to fine-tune a classification model and predict the labels of patches created from a parent image.
+- Text spotting pipeline: This pipeline enables users to detect and recognize text in map images.
+
+MapReader was developed in the `Living with Machines <https://livingwithmachines.ac.uk/>`__ project to analyze large collections of historical maps but is a *generalizable* computer vision tool which can be applied to *any images* in a wide variety of domains.
+
+Origin of MapReader
+-------------------
+
+MapReader was a groundbreaking interdisciplinary tool that emerged from a specific set of geospatial historical research questions.
+The classification pipeline 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 <https://doi.org/10.1093/jvcult/vcab009>`__ and `Geospatial Humanities 2022 SIGSPATIAL workshop <https://arxiv.org/abs/2111.15592>`__ 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.
+
+Since then, MapReader has expanded to include a text spotting pipeline, which enables users to detect and recognize text in map images.
+These text spotting elements of MapReader were inspired by the work completed during Machines Reading Maps (AHRC grant AH/V009400/1), whose team members at the University of Minnesota developed the first end-to-end text spotting pipeline used to find text on maps: mapKurator.
 
 What is unique about MapReader?
 --------------------------------
@@ -15,18 +32,32 @@ This unique way of pre-processing map images enables the use of image classifica
 What is 'the MapReader pipeline'?
 ---------------------------------
 
-The MapReader pipeline consists of a linear sequence of tasks:
+MapReader contains two different pipelines:
+
+- Classification pipeline: This pipeline enables users to fine-tune a classification model and predict the labels of patches created from a parent image.
+- Text spotting pipeline: This pipeline enables users to detect and recognize text in map images.
+
+Classification pipeline
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The classification pipeline was the original 'MapReader pipeline'.
+It enables users to train a classification model to recognize visual features within map images and to identify patches containing these features across entire map collections:
 
 .. image:: /_static/pipeline_explained.png
 
-Together, these tasks 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.
+Text spotting pipeline
+~~~~~~~~~~~~~~~~~~~~~~
+
+The MapReader text spotting pipeline enables users to detect and recognize text in map images using a pre-trained text spotting model:
+
+.. image:: /_static/text-spotting-pipeline.png
 
 What kind of visual features can MapReader help me identify?
 ------------------------------------------------------------
 
-In order to train a CV classifier to recognize visual features within your maps, your features must have a homogeneous visual signal across your map collection (i.e. always be represented in the same way).
+In order to train a CV classification model to recognize visual features within your maps, your features must have a homogeneous visual signal across your map collection (i.e. always be represented in the same way).
 
-What are the inputs and outputs of each stage in the MapReader pipeline?
+What are the inputs and outputs of each stage in the MapReader classification pipeline?
 ------------------------------------------------------------------------
 
 Download
@@ -48,3 +79,23 @@ Classify (Train and Predict)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. image:: /_static/in_out_classify.png
     :width: 600px
+
+What are the inputs and outputs of the MapReader text spotting pipeline?
+------------------------------------------------------------------------
+
+
+Download
+~~~~~~~~
+.. image:: /_static/in_out_download.png
+    :width: 600px
+
+Load
+~~~~
+.. image:: /_static/in_out_load.png
+    :width: 600px
+
+Spot Text
+~~~~~~~~~
+
+.. image:: /_static/in_out_text_spotting.png
+    :width: 600px

docs/source/introduction-to-mapreader/what-skills-do-i-need-to-use-mapreader.rst

@@ -6,5 +6,4 @@ What skills/knowledge do I need to use MapReader?
 - Basic Python
 - Basic understanding of machine learning and computer vision (CV) methodology
 
-..
-    Add something here about how we have resources for you to learn these skills.
+Users who are interested in using MapReader but do not yet have these skills are encourage to refer to our :doc:`in-depth-resources/coding-basics` section for resources on learning these skills.

docs/source/introduction-to-mapreader/who-might-be-interested-in-mapreader.rst

@@ -3,6 +3,6 @@ Who might be interested in using MapReader?
 
 MapReader might be useful to you if:
 
-- You have access to a large collection of maps and want to identify visual features within them without having to manually annotating each map.
+- You have access to a large collection of maps and want to identify visual features or text within them without having to manually annotate each map.
 - You want to quickly test different labels to help refine a research question that depends on identifying visual features within maps before/without committing to manual vector data creation.
 - Your maps were created before surveying accuracy reached modern standards, and therefore you do not want to create overly precise geolocated data based on the content of those maps.

docs/source/introduction-to-mapreader/why-should-you-use-mapreader.rst

@@ -10,7 +10,16 @@ This exact number will vary depending on:
 - the skills you (or your team) have,
 - the amount of time at your disposal.
 
-Deciding to use MapReader, which uses deep learning computer vision (CV) models to predict the class of content on patches across many sheets, means weighing the pros and cons of working with the data output that is inferred by the model.
-Inferred data can be evaluated against expert-annotated data to understand its general quality (are all instances of a feature of interest identified by the model? does the model apply the correct label to that feature?), but in the full dataset there *will necessarily be* some percentage of error.
+MapReader uses computer vision (CV) models to extract information (class labels and text) from map images.
+This enables users to generate datasets for large corpora of maps in a fraction of the time it would take to annotate them manually.
 
-MapReader creates output that you can link and analyze in relation to other geospatial datasets (e.g. census, gazetteers, toponyms in text corpora).
+If georeferencing information is available for the map images, MapReader can create georeferenced outputs that can be linked and analyzed in relation to other geospatial datasets (e.g. census, gazetteers, toponyms in text corpora).
+This allows users a new way to explore and analyze their map collections.
+
+Understanding the limitations of MapReader
+------------------------------------------
+
+Deciding to use MapReader means weighing the pros and cons of working with data that has been inferred by a computer vision model.
+
+This inferred data can be evaluated against expert-annotated data (i.e. ground truth data) to understand its general quality, but users should be aware that in the full dataset there *will necessarily be* some percentage of error.
+As such, MapReader may not be suitable for users who require completely accurate data.

docs/source/using-mapreader/index.rst

@@ -1,19 +1,12 @@
 Using MapReader
 ===============
 
-.. todo:: Add a bit of text explaining format of user guide.
-.. todo:: Explain what the user guide is for vs worked examples
+This user guide provides guidance to all users of MapReader on how to use the MapReader library.
 
-This user guide provides guidance to all users of MapReader on how to use the MapReader package.
-We have tried to split our guide logically, into smaller sub-tasks, which may be used as part of an end-to-end run of the MapReader pipeline (detailed :doc:`here </introduction-to-mapreader/what-is-mapreader>`).
-
-Throughout this user guide, we will use OS maps as examples.
-**These are provided for illustrative purposes only.**
-
-Please read this user guide **before** looking through the worked examples.
+Please read this guide **before** looking through the worked examples to ensure you understand the code.
 
 .. toctree::
    :maxdepth: 1
 
-   step-by-step-guide/index
    input-guidance/index
+   step-by-step-guide/index

docs/source/using-mapreader/step-by-step-guide/index.rst

@@ -1,7 +1,11 @@
 Step-by-step Guide to Using MapReader
 ======================================
 
-This guide will walk you through the steps to use MapReader to read and process a map.
+This step-by-step guide provides a logical breakdown of the steps and workflows needed for running the MapReader library.
+
+Users should refer to the :doc:`Introduction to MapReader </introduction-to-mapreader/what-is-mapreader>` page to understand the necessary workflows for the Classification and Text Spotting pipelines.
+
+.. note:: Throughout this user guide, we will use OS maps as examples. **These are provided for illustrative purposes only, users may need to change file paths etc. to suit their own needs.**
 
 .. toctree::
    :maxdepth: 2