Woogle Maps is a tool for structuring documents in multiple clear storylines, visualizing the relationships between them.

On the basis of a list of PDF documents as input, Woogle Maps automatically generates a TimeFlow as output. This TimeFlow – a timeline with a graphical structure – describes the events that underlie these documents, and attaches every document to at least one event. Woogle Maps encompasses an extension of the original Narrative Maps algorithm created by Brian Keith Norambuena.

Getting started

This section contains the steps that need to be taken to get started with our project and fully reproduce our results.

Prerequisites

The project was developed using Python 3.12.3, Pip 24.0, and Poetry 1.8.2. Make sure all these are installed on your machine first.

Clone the repository with your favourite git client or using the following command:

git clone https://github.com/TeamEpochGithub/woogle-maps.git

Installing dependencies

Run the following command to install all the dependencies:

poetry install

Alternatively, you can install the dependencies from requirements.txt using the following command:

pip install -r requirements.txt

Then activate the virtual environment:

poetry shell

Running the Web App

To run the web app, simply run following command:

python dashapp/app.py

This will start the web app on http://localhost:8060/.

Google Colab

Instead of running the code locally, you can also run the code in Google Colab. Upload the Google Colab Preview.ipynb file to Google Colab and run all cells. Once all cells except the last one are done, you can access the app in the link provided at the end of Step 4.

Pytest coverage report

To generate pytest coverage report run:

poetry run pytest --cov=src --cov-branch --cov-report=html:coverage_re

Documentation

The documentation is hosted on GitHub Pages.

Documentation is generated using Sphinx.

To rebuild it, make sure to install the dependencies for generating the documentation first:

poetry install --with docs

Run make html with docs as the working directory. The documentation can then be found in docs/_build/html/index.html.

Here's a short command to make the documentation and open it in Google Chrome:

cd ./docs/;
./make.bat html; start chrome file://$PWD/_build/html/index.html
cd ../

Contributors

Woogle Maps was created by Team Epoch IV, based in the Dream Hall of the Delft University of Technology. This project was commisioned by Nationaal Archief and financed by i-Partnerschap.

Read more about this here.

• Team Lead: Jeffrey Lim (Epoch IV)
• Team Members: Daniel de Dios Allegue (Epoch IV), Kristóf Sándor (Epoch IV), and Gregoire Dumont (Epoch IV)
• Supervisor: Max Muller (Nationaal Archief)
• Advisors: Erik Saaman (Nationaal Archief) and Paul van den Akker (Nationaal Archief)
• Relationship managers: Evelien Christiaanse (i-Partnerschap), Arlette Wegman (i-Partnerschap), Robert van Poeteren (Epoch IV), Brian Witmer (Epoch IV), and Emiel Witting (Epoch IV)