Update worked examples

.dockerignore

@@ -1,2 +1,21 @@
-maps
-test.ipynb
+# classification one inch
+notebooks/geospatial/*classification_one_inch_maps/*
+!notebooks/geospatial/*classification_one_inch_maps/Pipeline.ipynb
+!notebooks/geospatial/*classification_one_inch_maps/annotations_one_inch/rail_space_#rw#.csv
+
+# text spotting one inch
+notebooks/geospatial/text_spotting_one_inch_maps/*/*
+!notebooks/geospatial/text_spotting_one_inch_maps/*/*/Pipeline.ipynb
+
+# classification mnist
+notebooks/non-geospatial/classification_mnist/*
+!notebooks/non-geospatial/classification_mnist/Pipeline.ipynb
+!notebooks/non-geospatial/classification_mnist/annotations_mnist/mnist_#kasra#.csv
+!notebooks/non-geospatial/classification_mnist/small_mnist/
+
+# classification plant phenotype
+notebooks/non-geospatial/classification_plant_phenotype/*
+!notebooks/non-geospatial/classification_plant_phenotype/Pipeline.ipynb
+!notebooks/non-geospatial/classification_plant_phenotype/annotations_plant_phenotype_open_acess/phenotype_test_#kasra#.csv
+!notebooks/non-geospatial/classification_plant_phenotype/dataset/
+

.github/workflows/check_notebooks.yml

@@ -0,0 +1,60 @@
+---
+    name: Test notebooks
+
+    on: 
+      push:
+        branches:
+          - dev
+      schedule:
+        - cron: 0 0 1 * *
+
+    env:
+      DPTEXT_PATH: ${{ github.workspace }}/DPText-DETR
+      DEEPSOLO_PATH: ${{ github.workspace }}/DeepSolo
+      DPTEXT_MODEL_PATH: ${{ github.workspace }}/art_final.pth
+      DEEPSOLO_MODEL_PATH: ${{ github.workspace }}/ic15_res50_finetune_synth-tt-mlt-13-15-textocr.pth
+
+    jobs:
+      all_tests:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v2
+            with:
+              fetch-depth: 2
+
+          - name: Set up Python 3.11
+            uses: actions/setup-python@v2
+            with:
+              python-version: 3.11
+
+          - name: Update pip
+            run: |
+              python -m ensurepip
+              python -m pip install --upgrade pip
+
+          - name: Install dependencies
+            run: |
+              python -m pip install wheel
+              python -m pip install numpy==1.26.4 torch==2.2.2 torchvision==0.17.2 -f https://download.pytorch.org/whl/torch_stable.html
+              python -m pip install -r requirements.txt
+              pip install papermill
+
+          - name: Clone DPText-DETR
+            run: |
+              git clone https://github.com/maps-as-data/DPText-DETR.git
+
+          - name: Clone DeepSolo
+            run: |
+              git clone https://github.com/maps-as-data/DeepSolo.git
+
+          - name: Hugging Face CLI
+            run: |
+              pip install -U "huggingface_hub[cli]"
+              huggingface-cli download rwood-97/DPText_DETR_ArT_R_50_poly art_final.pth --local-dir .
+              huggingface-cli download rwood-97/DeepSolo_ic15_res50 ic15_res50_finetune_synth-tt-mlt-13-15-textocr.pth --local-dir .
+
+          - name: Run notebooks
+            run: |
+              find . -name "*.ipynb" -exec sed -Ei "s/num_epochs=.?.?/num_epochs=1/g" {} +
+              find . -name "*.ipynb" -exec sed -i "s/annotator.annotate/#annotator.annotate/g" {} +
+              find . -name "*.ipynb" -print0 | xargs -0 -I {} -t bash -c 'papermill --cwd $(dirname {}) --log-output {} {} || exit 255' 

.gitignore

@@ -1,6 +1,23 @@
-maps
-test.ipynb
-parent_df.csv
-patch_df.csv
-.maps
-patches_*_pixel
+# maps and patches
+notebooks/geospatial/patches_*_*/
+
+# classification one inch
+notebooks/geospatial/*classification_one_inch_maps/*
+!notebooks/geospatial/*classification_one_inch_maps/Pipeline.ipynb
+!notebooks/geospatial/*classification_one_inch_maps/annotations_one_inch/
+
+# text spotting one inch
+notebooks/geospatial/text_spotting_one_inch_maps/*/*
+!notebooks/geospatial/text_spotting_one_inch_maps/*/Pipeline.ipynb
+
+# classification mnist
+notebooks/non-geospatial/classification_mnist/*
+!notebooks/non-geospatial/classification_mnist/Pipeline.ipynb
+!notebooks/non-geospatial/classification_mnist/annotations_mnist/
+!notebooks/non-geospatial/classification_mnist/small_mnist/
+
+# classification plant phenotype
+notebooks/non-geospatial/classification_plant_phenotype/*
+!notebooks/non-geospatial/classification_plant_phenotype/Pipeline.ipynb
+!notebooks/non-geospatial/classification_plant_phenotype/annotations_phenotype_open_access/
+!notebooks/non-geospatial/classification_plant_phenotype/dataset/

Dockerfile

@@ -1,9 +1,9 @@
 # Use an official Python runtime as a parent image
-FROM python:3.9
+FROM python:3.11
 
 RUN apt-get update
 
-RUN apt-get install -y libgdal-dev
+RUN apt-get install -y libgdal-dev libgl1-mesa-glx
 
 # Set the working directory to /app
 WORKDIR /app
@@ -12,10 +12,20 @@ WORKDIR /app
 COPY . /app
 
 # Install any needed packages specified in requirements.txt
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Download all maps for example notebooks
-RUN python download-examples.py
+RUN python -m pip install --upgrade pip
+RUN python -m pip install numpy==1.26.4 torch==2.2.2 torchvision==0.17.2 -f https://download.pytorch.org/whl/torch_stable.html
+RUN python -m pip install --no-cache-dir -r requirements.txt
+
+# Clone text spotting repos
+RUN git clone https://github.com/maps-as-data/DPText-DETR.git
+RUN git clone https://github.com/maps-as-data/DeepSolo.git
+RUN git clone https://github.com/maps-as-data/MapTextPipeline.git
+
+# Get text spotting model weights
+RUN python -m pip install -U "huggingface_hub[cli]"
+RUN huggingface-cli download rwood-97/DPText_DETR_ArT_R_50_poly art_final.pth --local-dir .
+RUN huggingface-cli download rwood-97/DeepSolo_ic15_res50 ic15_res50_finetune_synth-tt-mlt-13-15-textocr.pth --local-dir .
+RUN huggingface-cli download rwood-97/MapTextPipeline_rumsey rumsey-finetune.pth --local-dir .
 
 # Make port 8888 available to the world outside this container
 EXPOSE 8888

README.md

@@ -1,40 +1,120 @@
 # MapReader Examples
 
-A containerised application for testing out the MapReader library.
+This repo contains worked examples of using the MapReader library for various geospatial and non-geospatial tasks. 
 
-## Creating the Docker image
+There are two ways to set up and run these worked examples:
 
-Clone the repository and navigate to the root directory of the repository.
+1. [Install MapReader on your machine and run the examples locally](#local-install)
+2. [Use the Docker container provided in this repo to install MapReader and run the examples in a containerized environment](#docker-container)
+
+## Local install
+
+As per the [MapReader installation instructions](https://mapreader.readthedocs.io/en/latest/getting-started/installation-instructions/index.html), to run these worked examples locally you will need to:
+
+1. Clone the `mapreader-examples` repository
+2. Set up a Python virtual environment
+3. Install the required dependencies (NOTE: for the worked examples, these are different from those in the MapReader installation instructions!)
+4. Add your Python virtual environment to Jupyter Notebook as a kernel
+5. Run the worked examples in Jupyter Notebook (or other IDE)
+
+### 1. Clone the `mapreader-examples` repository
+
+To clone the `mapreader-examples` repository, run the following command:
+
+```bash
+git clone https://github.com/maps-as-data/mapreader-examples.git
+```
+
+This will copy the code and worked examples into your current working directory. 
+
+### 2. Set up a Python virtual environment
+
+If you are using conda, run the following commands to set up a new conda environment:
+
+```bash
+conda create -n mapreader_examples python=3.12
+conda activate mapreader_examples
+```
+
+**Or**, if you want to use venv instead of conda, run the following commands:
+
+```bash
+python3 -m venv mapreader_examples
+source mapreader_examples/bin/activate
+```
+
+### 2. Install the required dependencies
+
+To install the dependencies for the worked examples, run the following commands:
+
+```bash
+cd mapreader-examples
+pip install -r requirements.txt
+```
+
+### 3. Add your Python virtual environment to Jupyter Notebook as a kernel
+
+To allow the newly created Python virtual environment to show up in Jupyter notebooks, run the following command:
 
 ```bash
-git clone https://github.com/Living-with-machines/MapReader-examples
-cd MapReader-examples
+python -m ipykernel install --user --name mapreader_examples"
 ```
 
+### 4. Run the worked examples in Jupyter Notebook
+
+Lastly, to open a Jupyter Notebook, run the following command:
+
+```bash
+jupyter notebook
+```
+
+This will open a Jupyter Notebook in your browser.
+If it doesn't open, copy the link shown in your terminal and paste it into a new tab. 
+From here, you can navigate to the `notebooks` directory and open the worked examples you are interested in and start running the code.
+Any changes you make will be saved locally to your files.
+
+## Docker container
+
+If you have issues with the local install, or would prefer to run the worked examples in a containerized environment, you can use the Docker container provided in this repo.
+You will need to have docker installed on your machine to run the container.
+
+### 1. Clone the `mapreader-examples` repository
+
+To clone the `mapreader-examples` repository, run the following command:
+
+```bash
+git clone https://github.com/maps-as-data/mapreader-examples.git
+```
+
+This will copy the code and worked examples into your current working directory. 
+
+### 2. Build the Docker image
+
 To create the Docker image, run the following command:
 
 ```bash
+cd mapreader-examples
 docker build -t mapreader-examples .
 ```
 
-Note: This will take a while to complete as the following activities complete:
+Note: This may take a while to complete (approx 10-15 minutes).
 
-- Python setup ~22s
-- pip install ~7min
-- Downloading maps from NLS ~22-28min
-- **Total: ~30-35min**
-
-## Running the Docker container
+### 3. Run the Docker container
 
 To run the Docker container, run the following command:
 
 ```bash
 docker run -p 8888:8888 mapreader-examples
 ```
 
-## Running the Docker container from Docker Hub
+This will start the Jupyter Notebook in the docker container and should pop up in your browser. 
+If it doesn't, copy the link provided in the terminal and paste it into a new tab.
+From here, you can navigate to the `notebooks` directory and open the worked examples you are interested in and start running the code.
+Any changes you make will be saved in the docker container, but won't be saved locally to your files unless you copy them over.
+
+## Docker Hub
 
-To run the Docker container from Docker Hub, run the following command:
+If you'd like to use the docker image hosted on Docker Hub, run the following command:
 
 ```bash
 docker run -p 8888:8888 kallewesterling/mapreader-examples