Introduction to MapReader Workshop

This repo contains 3 worked examples for using MapReader.

1. Patch Classification (XYZ tiles): mapreader_classification_2025_colab.ipynb. Task: automatically classify regions of historical maps from the National Library of Scotland OS collection.
2. Patch Classification (IIIF): iiif_classification_2025_colab.ipynb & iiif_classification_2025_local.ipynb. Task: automatically classify regions of historical maps available as IIIF resources (using an example from the Leventhal Map & Education Center).
3. Text Spotting: iiif_textspotting_geor_2025_colab.ipynb & iiif_textspotting_geor_2025_local.ipynb. Task: detect and recognize text on historical maps using a pre-trained text spotting model. This notebook uses the same Leventhal Collection IIIF map as the previous notebook.

Today, we are only going to review the Patch Classification (XYZ tiles) and Text Spotting notebooks, but you can try notebook #2 later!

First, let's get the notebooks set up.

Setup

Follow the instructions below to set up the notebook on Google Colab (recommended), in Docker, or locally.

There are Colab versions for all notebooks. Use these unless you are familiar with using notebooks locally or via Docker.

There are also local version for both iiif notebooks (patch classification & text spotting). In the Colab versions of both iiif notebooks, there may be errors depending on your Colab runtime. You also cannot scale up your text spotting to the entire image, or the notebook will likely crash :) Use the local versions if you want more flexibility.

• Option 1: Google Colab
• Detailed instructions for setting up Colab
  • Optional: Change the runtime type
• Option 2: Docker
  • Creating the Docker image
  • Running the Docker container
• Option 3: Local

Option 1: Google Colab

Set up a notebook by following these steps.

1. In your browser, navigate to Google Colab.

   An "Open notebook" window should appear automatically. If it doesn't, click File > Open notebook....

   

2. In the "Open notebook" window, click the "GitHub" option:

   

3. Paste the URL of this repository into the search bar and press Enter. URL = https://github.com/maps-as-data/mapreader-workshop

   

4. After pressing Enter, a list of notebooks in the repository should appear. Click on mapreader_classification_2025_colab.ipynb to open it.

   

NB: When testing a different notebook, e.g. the iiif_text_spotting notebook, you should open the link for that notebook instead, e.g. iiif_textspotting_2025_colab.ipynb.

![Select the notebook](images/1-open-notebook-link.png)

5. The notebook should now be open and look like this:

   

   Note that Google may display a warning that the notebook is not authored by Google. You can ignore this warning.

   

6. You can now run the notebook by clicking the play button on the left of each cell.

   Note that the first cell will install all requirements for the notebook to run. It will take some time, and will display some warnings. Those can be ignored. At the bottom, you will see a message that the installation was successful.

   

Optional: Change the runtime type

By default, Google Colab uses a CPU runtime. If you want to use a GPU runtime, you can change this by clicking Runtime > Change runtime type and selecting GPU from the Hardware accelerator dropdown.

Patch classification - CPU is fine.

Text spotting - Change runtine to a GPU option.

1. Click Runtime > Change runtime type.

   

2. In the "Change runtime type" window, select GPU from the Hardware accelerator dropdown. Click Save to apply the changes.

   

   After you save the changes, the runtime will be changed to GPU and the core needs to be restarted. Click OK to restart the runtime.

   

3. The runtime type should now be changed to GPU.

   

Option 2: Docker

Creating the Docker image

Clone the repository and navigate to the root directory of the repository.

git clone https://github.com/maps-as-data/mapreader-workshop.git
cd mapreader-workshop

To create the Docker image, run the following command:

docker build -t mapreader-workshop .

Running the Docker container

To run the Docker container, run the following command:

docker run -p 8888:8888 --mount source=workshop_outputs,target=/app mapreader-workshop

Click the link that appears in the terminal to open the notebook in your browser.

Option 3: Local

To run the notebook locally, follow the instructions for Step 1 & Step 3 ONLY here to set up your MapReader python environment. You do not need to run commands for Step 2, instead run the commands below.

You can now install the required packages for this notebook by running:

pip install torch
pip install -r requirements.txt

You can then run any of the notebooks by running jupyter + [notebook name]. For example, to run the patch classification notebook, run:

jupyter notebook mapreader_classification_2025_local.ipynb