Upload 12 files

.gitattributes

@@ -33,3 +33,11 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+images/BAS_0001.tiff filter=lfs diff=lfs merge=lfs -text
+images/KSC_0001.tiff filter=lfs diff=lfs merge=lfs -text
+images/LYT_0005.tiff filter=lfs diff=lfs merge=lfs -text
+images/MOB_0002.tiff filter=lfs diff=lfs merge=lfs -text
+images/MON_0002.tiff filter=lfs diff=lfs merge=lfs -text
+images/MYB_0003.tiff filter=lfs diff=lfs merge=lfs -text
+images/NGS_0002.tiff filter=lfs diff=lfs merge=lfs -text
+images/PMO_0002.tiff filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,12 +1,95 @@
+
+# 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.
+
 ---
-title: LabelingTest
-emoji: 🐠
-colorFrom: blue
-colorTo: green
-sdk: gradio
-sdk_version: 5.42.0
-app_file: app.py
-pinned: false
+
+## 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
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## 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`.

app.py

@@ -0,0 +1,241 @@
+
+import os
+import glob
+import random
+from datetime import datetime, timezone
+from pathlib import Path
+
+import gradio as gr
+import pandas as pd
+from filelock import FileLock
+from huggingface_hub import HfApi
+
+# ---------------------- Configuration via ENV ----------------------
+IMAGE_DIR = os.getenv("IMAGE_DIR", "images")  # folder inside repo
+LABELS_CSV = os.getenv("LABELS_CSV", "labels.csv")
+LABEL_A = os.getenv("LABEL_A", "Class A")
+LABEL_B = os.getenv("LABEL_B", "Class B")
+APP_TITLE = os.getenv("APP_TITLE", "Two-Button Image Labeler")
+APP_DESCRIPTION = os.getenv(
+    "APP_DESCRIPTION",
+    "Press the left or right button (or use keyboard shortcuts) to label each image. "
+    "Enter your name first so we can attribute labels."
+)
+SHOW_ALREADY_LABELED = os.getenv("SHOW_ALREADY_LABELED", "0") == "1"  # if 0, hide images that already have a label
+SHUFFLE_IMAGES = os.getenv("SHUFFLE_IMAGES", "1") == "1"
+
+# Hugging Face repo auto-sync (optional)
+HF_TOKEN = os.getenv("HF_TOKEN")  # add as a secret in Spaces
+HF_SPACE_REPO = os.getenv("HF_SPACE_REPO")  # e.g. "username/space-name"
+UPLOAD_TO_REPO = os.getenv("UPLOAD_TO_REPO", "1") == "1"
+
+# Optional basic auth
+AUTH_USER = os.getenv("AUTH_USER")
+AUTH_PASS = os.getenv("AUTH_PASS")
+
+SUPPORTED_EXTS = (".png", ".jpg", ".jpeg", ".bmp", ".gif", ".tif", ".tiff", ".webp")
+
+
+def list_images(image_dir: str):
+    paths = []
+    for p in glob.glob(os.path.join(image_dir, "**", "*"), recursive=True):
+        if p.lower().endswith(SUPPORTED_EXTS):
+            paths.append(p)
+    return sorted(paths)
+
+
+def read_labels():
+    if os.path.exists(LABELS_CSV):
+        try:
+            return pd.read_csv(LABELS_CSV)
+        except Exception:
+            # if corrupted for any reason, don't crash
+            return pd.DataFrame(columns=["image", "label", "annotator", "timestamp"])
+    return pd.DataFrame(columns=["image", "label", "annotator", "timestamp"])
+
+
+def rel_to_image_dir(p: str):
+    # Make relative paths for portability
+    try:
+        return str(Path(p).resolve().relative_to(Path(IMAGE_DIR).resolve()))
+    except Exception:
+        return p
+
+
+def write_label(record: dict):
+    # Append a single record to LABELS_CSV safely
+    os.makedirs(os.path.dirname(LABELS_CSV) or ".", exist_ok=True)
+    with FileLock(LABELS_CSV + ".lock", timeout=10):
+        exists = os.path.exists(LABELS_CSV)
+        df = pd.DataFrame([record])
+        df.to_csv(LABELS_CSV, mode="a", header=not exists, index=False)
+
+    # Optional: upload the CSV to the Space repo so you automatically receive results
+    if HF_TOKEN and HF_SPACE_REPO and UPLOAD_TO_REPO:
+        try:
+            api = HfApi()
+            api.upload_file(
+                path_or_fileobj=LABELS_CSV,
+                path_in_repo=LABELS_CSV,
+                repo_id=HF_SPACE_REPO,
+                repo_type="space",
+                token=HF_TOKEN,
+                commit_message=f"Update labels: {datetime.now(timezone.utc).isoformat()}",
+            )
+        except Exception as e:
+            print("Warning: upload to repo failed:", e)
+
+
+def start_session(annotator):
+    annotator = (annotator or "").strip()
+    if not annotator:
+        raise gr.Error("Please enter your name before starting.")
+
+    imgs = list_images(IMAGE_DIR)
+    if not imgs:
+        raise gr.Error("No images found. Upload images to the 'images' folder.")
+
+    labels_df = read_labels()
+    if not SHOW_ALREADY_LABELED and len(labels_df) > 0:
+        labeled = set(labels_df["image"].astype(str).tolist())
+        # Images in CSV are stored as relative paths (if possible). Normalize current list to relative too.
+        rel_imgs = [rel_to_image_dir(p) for p in imgs]
+        imgs = [p for p, r in zip(imgs, rel_imgs) if r not in labeled]
+
+    if not imgs:
+        raise gr.Error("All images appear to be labeled already.")
+
+    if SHUFFLE_IMAGES:
+        random.shuffle(imgs)
+
+    state = {
+        "annotator": annotator,
+        "order": imgs,
+        "idx": 0,
+        "total": len(imgs),
+    }
+    progress = f"0 / {state['total']}"
+    # Show the first image
+    return state, imgs[0], progress, gr.update(visible=True), gr.update(visible=True), gr.update(visible=False)
+
+
+def next_image(state):
+    if state["idx"] >= state["total"]:
+        return None  # triggers end
+    return state["order"][state["idx"]]
+
+
+def render_progress(state):
+    return f"{min(state['idx'], state['total'])} / {state['total']}"
+
+
+def label_and_next(state, choice):
+    if state is None:
+        raise gr.Error("Click 'Start' first.")
+
+    if state["idx"] >= state["total"]:
+        return state, None, "Done", gr.update(visible=False)
+
+    current_image = state["order"][state["idx"]]
+    record = {
+        "image": rel_to_image_dir(current_image),
+        "label": choice,
+        "annotator": state["annotator"],
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+    write_label(record)
+    state["idx"] += 1
+
+    nxt = next_image(state)
+    if nxt is None:
+        # Finished
+        return state, None, "All done 🎉 Thank you!", gr.update(visible=False)
+    else:
+        return state, nxt, render_progress(state), gr.update(visible=True)
+
+
+def skip_and_next(state):
+    if state is None:
+        raise gr.Error("Click 'Start' first.")
+    state["idx"] += 1
+    nxt = next_image(state)
+    if nxt is None:
+        return state, None, "All done 🎉 Thank you!", gr.update(visible=False)
+    else:
+        return state, nxt, render_progress(state), gr.update(visible=True)
+
+
+def download_labels():
+    if not os.path.exists(LABELS_CSV):
+        raise gr.Error("No labels yet.")
+    return LABELS_CSV
+
+
+with gr.Blocks(title=APP_TITLE, css=".gr-button {height: 64px; font-size: 18px;} .progress{font-weight:600}") as demo:
+    gr.Markdown(f"## {APP_TITLE}\n{APP_DESCRIPTION}")
+
+    with gr.Group():
+        with gr.Row():
+            annotator = gr.Textbox(label="Your name", placeholder="Type your name", scale=3)
+            start_btn = gr.Button("Start", variant="primary", scale=1)
+        with gr.Row():
+            info = gr.Markdown(
+                "1) Enter your name → 2) Click **Start** → 3) Use **Left / Right** buttons (shortcuts: **A** and **L**)."
+            )
+
+    image = gr.Image(label="Image", interactive=False)
+    progress = gr.Markdown("")
+    with gr.Row(visible=False) as buttons_row:
+        left = gr.Button(f"← {LABEL_A}", variant="secondary")
+        skip = gr.Button("Skip")
+        right = gr.Button(f"{LABEL_B} →", variant="secondary")
+
+    with gr.Accordion("Admin", open=False, visible=True) as admin:
+        with gr.Row():
+            download = gr.Button("Download CSV")
+            csv_file = gr.File(label="labels.csv", visible=False)
+
+        gr.Markdown(
+            "Tips: set `HF_TOKEN` and `HF_SPACE_REPO` secrets to automatically push `labels.csv` to the Space repository."
+        )
+
+    state = gr.State(None)
+
+    # Start flow
+    start_btn.click(
+        start_session,
+        inputs=[annotator],
+        outputs=[state, image, progress, buttons_row, admin, start_btn],
+    )
+
+    # Label buttons with shortcuts
+    left.click(
+        lambda s: label_and_next(s, LABEL_A),
+        inputs=[state],
+        outputs=[state, image, progress, buttons_row],
+        api_name="left_label",
+    )
+
+    right.click(
+        lambda s: label_and_next(s, LABEL_B),
+        inputs=[state],
+        outputs=[state, image, progress, buttons_row],
+        api_name="right_label",
+    )
+
+    skip.click(
+        skip_and_next,
+        inputs=[state],
+        outputs=[state, image, progress, buttons_row],
+    )
+
+    download.click(download_labels, outputs=[csv_file])
+
+demo = demo.queue(max_size=64)
+
+if __name__ == "__main__":
+    # Optional basic auth for local runs; on Spaces this will also work
+    if AUTH_USER and AUTH_PASS:
+        demo.launch(server_name="0.0.0.0", server_port=7860, auth=(AUTH_USER, AUTH_PASS))
+    else:
+        demo.launch(server_name="0.0.0.0", server_port=7860)

requirements.txt

@@ -0,0 +1,6 @@
+
+gradio>=4.26.0
+pandas>=2.1.0
+huggingface_hub>=0.24.0
+filelock>=3.13.0
+Pillow>=10.0.0