---
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)

```bash
pip install -r requirements.txt
python app.py
```
Then open http://localhost:7860 and start labeling.
To add a password:
```bash
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`.