Suzipu Human Annotation Baseline Study GUI

A Django web application used in a user study to determine the human baseline performance of classifying suzipu 俗字谱 notation (samples from the Shanghai MS edition of Baishidaoren Gequ 白石道人歌曲).

Participants log in, annotate image samples, and their actions are timestamped. The collected data can later be evaluated to derive annotation accuracy and timing statistics.

See also the user instruction (German), the informed consent sheet (German), and the Chapter 6.7 in my dissertation for more information about the user study.

---

Contents

• What this is
• Requirements
• Quick start (Docker)
• Environment configuration
• Running the app
• Create a superuser (admin)
• Import sample data
• Using the app (annotation flow)
• Admin dashboard and statistics export
• Project layout
• Domain model
• Troubleshooting

---

What this is

• Framework: Django 5
• Database: SQLite by default (via DATABASE_URL)
• Containerization: Docker and docker compose
• Media and static directories mounted in the container at /app/media and /app/static

Requirements

• Docker and Docker Compose (v2)
• Optional: Python 3.12+ if you want to run locally without Docker (not covered here)

Quick start (Docker)

1. Copy the example environment to a local file:

   • Create a file named .env.development in the repository root with the following content (adjust as needed):

   SECRET_KEY=dev-secret-key-change-me
   DEBUG=True
   ALLOWED_HOSTS=["*"]
   DATABASE_URL=sqlite:////app/media/db.sqlite3
   

2. Start the development server:

   docker compose up --build

   This will:

   • Build the Django image (development)
   • Mount the repository at /app inside the container
   • Run python manage.py runserver 0.0.0.0:8000 from /app/src

3. Access the app at:

   • http://localhost:8000

Environment configuration

• The app uses django-environ to read variables from the environment and .env.development (via docker-compose.yml).
• Key variables:
  • SECRET_KEY: Django secret key
  • DEBUG: True/False
  • ALLOWED_HOSTS: JSON-like list of hosts, e.g. ["*"] or ["localhost","127.0.0.1"]
  • DATABASE_URL: e.g. sqlite:////app/media/db.sqlite3 (default path under the mounted volume)

Running the app

• Start: docker compose up -d

• Stop: docker compose stop

• Run one-off Django commands:

  docker compose run --rm django python manage.py migrate
  docker compose run --rm django python manage.py createsuperuser

Create a superuser (admin)

Run:

docker compose run --rm django python manage.py createsuperuser

Then log in at /admin/ to view data and statistics.

Import sample data

Two bundled datasets exist:

• Full demo with grouped samples: /app/sample_data/dataset_grouped.json (expects images next to it in sample_data/images)
• Smaller demo images: sample_data/images_demo (if you prepare your own JSON against these images)

Run the import command (from the repository root):

• Full dataset (recommended):

docker compose run --rm django python manage.py import_samples --data-file /app/sample_data/dataset_grouped.json

Notes:

• The importer resolves image paths relative to the JSON file’s directory.
• If a Sample with the same real_name exists, it will be updated.

Using the app (annotation flow)

1. Navigate to the root / and log in (non-authenticated users are redirected to login).
2. You will be directed to annotate samples assigned to your group.
3. Choose:
   • Pitch component
   • Secondary component (or none)
4. Navigation:
   • Use the on-screen Previous/Next buttons
   • Keyboard shortcuts: Left/right arrows to move between samples
5. The progress indicator shows percent completed (where pitch != None).

Admin dashboard and statistics export

• Admin site: /admin/ (requires superuser)
• The dashboard displays per-user and aggregate statistics (computed in core.build_statistics).
• Export raw statistics JSON: GET /download_statistics/ (superuser only). The response is served as a file attachment statistics.json.

Project layout

• src/manage.py – Django entrypoint
• src/suziai_human_annotation/settings/base.py – base settings (uses environment variables)
• src/suziai_human_annotation/core/ – app with models, forms, views, admin, templates
• src/suziai_human_annotation/core/management/commands/import_samples.py – sample data importer
• docker/ – Dockerfiles and entrypoint
• requirements/ – pip requirement sets for dev/prod
• sample_data/ – JSON and images for import

Domain model

classDiagram
    direction LR

    class User {
      +id
      +username
      +is_superuser
      ...
    }

    class Sample {
      +id
      +image : ImageField
      +real_name : str (unique)
      +real_pitch : PitchChoices
      +real_secondary : SecondaryChoices
      +group : smallint
      +get_annotation_state(annotations) : str
    }

    class Annotation {
      +id
      +user : FK(User)
      +sample : FK(Sample)
      +pitch : PitchChoices
      +secondary : SecondaryChoices
      __unique_together__(user, sample)
    }

    class Action {
      +id
      +annotation : FK(Annotation)
      +timestamp : datetime (auto_now_add)
    }

    User "1" --> "*" Annotation : author
    Sample "1" --> "*" Annotation : annotated by
    Annotation "1" --> "*" Action : produces

Loading

Troubleshooting

• App doesn’t start / 500 on boot:
  • Ensure .env.development is present and SECRET_KEY/DATABASE_URL are set.
• Import complains about image files:
  • The importer expects image paths relative to the JSON file. Make sure sample_data/images exists and matches the JSON entries.
• Static or media not accessible in development:
  • In dev, django.contrib.staticfiles serves static. Media is exposed by urls.py using static(settings.MEDIA_URL, ...) when DEBUG is true.