update

README.md

@@ -1,15 +1,111 @@
+# Thyroid Nodule Analysis Pipeline
+
+An automated pipeline for thyroid nodule analysis in ultrasound images, covering detection, segmentation, malignancy classification, and ACR TI-RADS risk scoring, all in a single inference flow through a web interface.
+
 ---
-title: Thyroid Pipeline
-emoji: 🚀
-colorFrom: red
-colorTo: indigo
-sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.12'
-app_file: app.py
-pinned: false
-license: mit
-short_description: Automated thyroid nodule detection, segmentation, classifica
+
+## What it does
+
+Given one or more thyroid ultrasound images, the system runs four sequential steps:
+
+1. **Detection** - localises nodules with bounding boxes (YOLOv8s)
+2. **Segmentation** - produces a pixel-level mask of each nodule (UNet++ with SCSE attention)
+3. **Malignancy classification** - estimates benign/malignant probability with a Grad-CAM visual explanation (ResNet50)
+4. **TI-RADS scoring** - assigns an ACR TI-RADS category (TR1–TR5) from 25 radiomic descriptors (Random Forest)
+
+When multiple images of the same patient are uploaded, the results are automatically aggregated at patient level.
+
+> **Note:** Results are intended as decision support for a specialist and do not replace clinical judgement.
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Project structure
+
+```
+thyroid-pipeline/
+├── models/                              # Trained model weights
+│   ├── yolo_finetuned_thyroidxl.pt
+│   ├── best_unet_finetuned.pth
+│   ├── resnet50_finetuned_thyroidxl.pth
+│   ├── best_model_expB_RandomForest.pkl
+│   └── train_features_patient_level_unetmask.csv
+│
+├── pipeline/
+│   ├── detector.py          # YOLOv8s nodule detection
+│   ├── segmentor.py         # UNet++ pixel-level segmentation
+│   ├── classifier.py        # ResNet50 malignancy classification + Grad-CAM
+│   ├── feature_extractor.py # 25 radiomic descriptors
+│   ├── tirads_scorer.py     # Random Forest TI-RADS scoring (TR1–TR5)
+│   └── aggregator.py        # Patient-level aggregation
+│
+├── utils/
+│   └── visualization.py     # Detection and segmentation overlays
+│
+├── app.py                   # Gradio web interface
+├── config.py                # Paths, thresholds, TI-RADS lookup tables
+├── thyroid_pipeline.py      # Main pipeline orchestrator
+└── requirements.txt
+```
+
+---
+
+## Installation
+
+**Requirements:** Python 3.10+, and a CUDA-capable GPU (recommended) or CPU.
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd thyroid-pipeline
+
+# Create and activate a virtual environment
+python -m venv venv
+# Windows:
+venv\Scripts\activate
+# Linux / macOS:
+source venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+Download the model weights and place them in the `models/` folder.
+
+---
+
+## Running the app
+
+```bash
+python app.py
+```
+
+The interface will be available at `http://localhost:7860`.
+
+The app is also deployed on Hugging Face Spaces: https://huggingface.co/spaces/Ale22M/thyroid-pipeline and can be used without any local setup.
+
+---
+
+## Usage
+
+**Single image mode** — upload one `.png` / `.jpg` / `.jpeg` ultrasound image and click *Analyze*. The interface returns:
+- Detection overlay (bounding box)
+- Segmentation overlay (nodule mask)
+- Nodule crop fed to the classifier
+- Grad-CAM heatmap
+- Malignancy probability and label
+- Top radiomic features
+
+**Patient mode** - upload multiple images of the same patient. In addition to per-image results, the system aggregates everything at patient level and returns a final malignancy classification and an ACR TI-RADS category with the corresponding biopsy recommendation.
+
+---
+
+## Dependencies
+
+ultralytics -> YOLOv8 detection
+segmentation-models-pytorch -> UNet++ with pretrained encoders
+grad-cam -> Grad-CAM explanations
+scikit-learn -> Random Forest TI-RADS classifier
+scikit-image, scipy, opencv-python -> radiomic feature extraction
+gradio -> web interface
+
+Full pinned versions are in requirements.txt.

app.py

@@ -8,7 +8,7 @@ Supports two analysis modes:
                   feature aggregation.
 
 File validation:
-  Only images are accepted (.png, .jpg, .jpeg, .bmp, .tiff, .webp).
+  Only images are accepted (.png, .jpg, .jpeg).
   Invalid formats produce a clear error message before any model inference.
 
 Partial-failure handling:
@@ -21,7 +21,7 @@ import os
 # ZeroGPU
 _ON_HF = os.environ.get("SPACE_ID") is not None
 if _ON_HF:
-    import spaces
+    import spaces # type: ignore
 
 import time
 import numpy as np
@@ -431,6 +431,14 @@ figure figcaption {
     border-top: none !important;
     padding-top: 4px !important;
 }
+
+#gallery-no-scroll,
+#gallery-no-scroll .grid-wrap,
+#gallery-no-scroll .grid-container {
+    max-height: none !important;
+    height: auto !important;
+    overflow: visible !important;
+}
 """
 
 with gr.Blocks(title="Thyroid Nodule Analysis Pipeline") as demo:
@@ -455,7 +463,7 @@ with gr.Blocks(title="Thyroid Nodule Analysis Pipeline") as demo:
             input_files = gr.File(
                 label       = "Upload ultrasound image(s) - single image or multiple views of the same patient",
                 file_count  = "multiple",
-                file_types  = [".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif", ".webp"],
+                file_types  = [".png", ".jpg", ".jpeg"],
                 elem_id     = "file-upload-box",
             )
             run_btn = gr.Button("Analyze", variant="primary", size="lg")
@@ -478,8 +486,9 @@ with gr.Blocks(title="Thyroid Nodule Analysis Pipeline") as demo:
         label       = "Pipeline outputs",
         show_label  = True,
         columns     = 5,
-        height      = 730,
+        height      = "auto",
         object_fit  = "contain",
+        elem_id     = "gallery-no-scroll",
     )
 
     gr.Markdown("---")

config.py

@@ -109,5 +109,5 @@ TIRADS_FNAB = {
 }
 
 # Accepted image formats for upload validation
-ACCEPTED_EXTENSIONS = {".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".tif", ".webp"}
-ACCEPTED_MIME_TYPES = {"image/png", "image/jpeg", "image/bmp", "image/tiff", "image/webp"}
+ACCEPTED_EXTENSIONS = {".png", ".jpg", ".jpeg"}
+ACCEPTED_MIME_TYPES = {"image/png", "image/jpeg"}

pipeline/thyroid_pipeline.py

@@ -275,7 +275,7 @@ class ThyroidPipeline:
         result.label         = label
         result.image_crop    = Image.fromarray(crop_rgb)
         result.image_gradcam = Image.fromarray(cam_img)
-        print(f"[Pipeline] ResNet50 → {label} (p={prob_malign:.3f})")
+        print(f"[Pipeline] ResNet50 -> {label} (p={prob_malign:.3f})")
 
         # Update detection overlay with classification colour
         result.image_detection = Image.fromarray(
@@ -312,7 +312,7 @@ class ThyroidPipeline:
         feats_list        : list[dict]        = []
 
         for idx, pil_img in enumerate(images_pil):
-            print(f"[ThyroidPipeline] ── Image {idx + 1}/{len(images_pil)}")
+            print(f"[ThyroidPipeline] - Image {idx + 1}/{len(images_pil)}")
             res = self._process_single(pil_img)
             per_image_results.append(res)
 
@@ -348,7 +348,7 @@ class ThyroidPipeline:
             patient.tirads_class        = tr_class
             patient.tirads_risk         = self.scorer.get_risk_label(tr_class)
             patient.fnab_recommendation = self.scorer.get_fnab_recommendation(tr_class)
-            print(f"[ThyroidPipeline] Patient TI-RADS → TR{tr_class}")
+            print(f"[ThyroidPipeline] Patient TI-RADS -> TR{tr_class}")
 
         patient.elapsed_total_s = time.perf_counter() - t0
         print(f"[ThyroidPipeline] Patient session done in "