Spaces:
Sleeping
Sleeping
| 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`. | |