README.md

metadata

title: Two-Button Image Labeler
emoji: 🏷️
colorFrom: yellow
colorTo: green
sdk: streamlit
app_file: app.py
pinned: false

Two-Button Image Labeler (HuggingFace Spaces)

A zero-install app for collaborators to label images with two buttons (left/right). Perfect for quick yes/no or binary classification tasks with doctors or non-technical users.

Features

• Shows one image at a time.
• Two big buttons (configurable labels).
• Keyboard shortcuts: A for left, L for right.
• "Skip" button.
• Captures annotator's name.
• Saves to labels.csv and (optionally) auto-uploads it back to your Space repository after every label.
• Hides already-labeled images by default (configurable).
• Works with multiple annotators at once (file lock ensures safe writes).

---

Quick Start (HuggingFace Spaces)

1. Create a new Space → Gradio.
2. Upload the files from this repo (app.py, requirements.txt). You can use the zip attached or drag & drop.
3. Create a folder images/ in the Space and upload your images there (PNG/JPG/etc.).
4. (Optional but recommended) Set secrets in the Space Settings → Variables and secrets:
   • HF_TOKEN — a write token from your Hugging Face account.
   • HF_SPACE_REPO — your Space repo id, e.g. yourname/your-space.
   • With these set, the app will push updates to labels.csv back into the repo automatically so you always have the latest labels.
5. Share the Space link with your doctors. They:
   • Enter their name
   • Click Start
   • Press ← Class A or Class B → (or A/L keys)

You can download the latest labels at any time with the Download CSV button (Admin section).

---

Configuration (Environment Variables)

Variable	Default	Description
IMAGE_DIR	images	Folder containing images (can include subfolders).
LABELS_CSV	labels.csv	Path to the CSV file saved by the app.
LABEL_A	Class A	Text on the left button.
LABEL_B	Class B	Text on the right button.
APP_TITLE	Two-Button Image Labeler	Title at the top of the app.
APP_DESCRIPTION	(see app.py)	Instructions shown under the title.
SHOW_ALREADY_LABELED	0	If 1, includes images that already have a label.
SHUFFLE_IMAGES	1	If 1, randomize image order per session.
HF_TOKEN	(none)	Your HF write token. If set with HF_SPACE_REPO, labels are auto-pushed to the repo.
HF_SPACE_REPO	(none)	Your Space repo id, e.g. yourname/your-space.
UPLOAD_TO_REPO	1	If 1, attempt to push labels to the repo on every write.
AUTH_USER, AUTH_PASS	(none)	If set, password-protect the app (basic auth). Useful if your Space is public.

Note: If you keep SHOW_ALREADY_LABELED=0, the app hides any image that appears at least once in labels.csv (regardless of annotator). Set to 1 if you want multiple independent labels per image.

---

CSV Format

The app appends one row per click with these columns:

• image — relative path to the image from IMAGE_DIR
• label — the chosen label (LABEL_A or LABEL_B)
• annotator — whatever the user entered under "Your name"
• timestamp — ISO 8601 UTC time

---

Deploy Locally (Optional)

pip install -r requirements.txt
python app.py

Then open http://localhost:7860 and start labeling. To add a password:

export AUTH_USER=myuser
export AUTH_PASS=mypassword
python app.py

---

Tips for Medical Data

• If images are sensitive, keep the Space private (available on paid HF plans) or enable basic auth via AUTH_USER/AUTH_PASS.
• You can also host the same app on your institution's intranet server; it’s just a Gradio Python script.

---

Troubleshooting

• No images found: Make sure your Space repo has an /images folder with JPG/PNG files.
• CSV not updating in Git: Set both HF_TOKEN and HF_SPACE_REPO secrets. The app uploads labels.csv using huggingface_hub on each write.
• Multiple annotators: Supported. A file lock prevents collisions when writing labels.csv.