ARCHIVED: This repo will not be updated with new changes to the MapReader code.

MapReader Autumn Workshop 2024

This repo contains worked examples of running MapReader, designed for the Data/Culture Autumn Workshop 2024.

There are three notebooks in this repository:

1. mapreader-autumn-workshop-2024-part1.ipynb: A quick run-through of MapReader's classification pipeline.
2. mapreader-autumn-workshop-2024-part2.ipynb: A worked example of MapReader's text spotting pipeline.
3. mapreader-autumn-workshop-2024-part3-explore_text_on_maps.ipynb: Some examples of how to work with the MapReader classification and text spotting outputs.

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

Table of contents

• Set up - Docker
  • Creating the Docker image
  • Running the Docker container
• Set up - Local
• Set up - Google Colab (short version)
• Detailed instructions for setting up on Google Colab
  • Optional: Change the runtime type

Set up - 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-autumn-workshop-2024
cd mapreader-autumn-workshop-2024

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.

Set up - Local

To run the notebook locally, follow the instructions here to set up your MapReader python environment.

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

pip install torch==2.2.2 torchvision==0.17.2 -f https://download.pytorch.org/whl/torch_stable.html
pip install 'git+https://github.com/facebookresearch/detectron2.git'
pip install 'git+https://github.com/maps-as-data/DeepSolo.git'
pip install -r requirements.txt

For running the text spotting, you will need to clone the DeepSolo repository and download the weights file for the text spotting model. To do this, run the following commands:

git clone https://github.com/maps-as-data/DeepSolo.git
wget https://huggingface.co/rwood-97/DeepSolo_ic15_res50/resolve/main/ic15_res50_finetune_synth-tt-mlt-13-15-textocr.pth

You can then run the notebooks by running:

jupyter notebook

Set up - Google Colab (short version)

If you are familiar with Google Colab, you can set up the notebook by following these steps. If you are new to Google Colab, please refer to the detailed instructions below.

• Open Google Colab
• In the "Open notebook" window, click the "GitHub" option
• Paste the URL of this repository into the search bar and press Enter
• Open one of the notebooks (e.g. mapreader-autumn-workshop-2024-part1.ipynb)

Detailed instructions for setting up on Google Colab

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.

   

4. After pressing Enter, a list of notebooks in the repository should appear. Click on one of the notebooks (e.g. mapreader-autumn-workshop-2024-part1.ipynb) to open it.

   

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

   

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

   The first cells of the notebook will set up everything you need to run on Google Colab.

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

   

   • A pop up will ask if you want to connect to Google Drive. If you are happy with this, click Connect to Google Drive:

   

   • You will be asked to sign in:

   

   • And then to allow Google Colab to access your Google Drive. You should click Continue:

   

7. You should then be able to run all the cells in the notebook. A green tick to the left of the cell indicates that the cell has run successfully.

   Note that the second 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.

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.