Spaces:
Sleeping
Sleeping
File size: 4,143 Bytes
ab494a5 5161b99 ab494a5 907c840 3ca29bf 907c840 3ca29bf 907c840 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 |
---
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`.
|