README¶

Woogle Maps Logo

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.