README.md

metadata

title: Liver and Tumor Segmentation (2.5D U-Net)
emoji: ⚕️
colorFrom: green
colorTo: blue
sdk: docker
app_port: 5000
tags:
  - medical-imaging
  - pytorch
  - u-net
  - celery
  - flask
  - docker
license: apache-2.0
short_description: Performed liver tumor segmentation using LITS dataset.

👨‍⚕️ Liver and Tumor Segmentation App

This Hugging Face Space hosts a complete, production-ready application for asynchronously segmenting the liver and tumors from 3D CT scans (NIfTI format).

The application is deployed using a custom Docker image, optimized for the Hugging Face environment, to run a complex, multi-service architecture within a single container.

---

💻 How to Use the Demo

1. Upload File: Click the "Click to upload" box and select a single NIfTI file (.nii or .nii.gz) containing a CT scan.
2. Start Segmentation: Click the Start Segmentation button. This sends the file to the Flask app, which dispatches the processing task to the Celery queue.
3. Monitor Status: The client-side interface polls the Flask endpoint /status/<task_id> to report the current status (PENDING, RUNNING, or COMPLETE).
4. View Results: Upon completion, the page displays:
   • A 2D Prediction Slice highlighting the segmented liver (cyan) and tumor (red).
   • An Interactive 3D Plot (Plotly) of the segmented structures.

---

🧠 Technical Architecture (Supervisor Single-Container)

To deploy the asynchronous Flask/Celery application on Hugging Face Spaces (which does not support docker-compose.yml), we use Supervisor as the entry point to manage all necessary services in one container.

Service	Technology	Configuration (in supervisord.conf)	Role
Container Manager	Supervisor	nodaemon=true	The primary process that ensures all underlying services are launched and managed.
Web App	Flask / Gunicorn	command=gunicorn -w 4 -b 0.0.0.0:5000 app:app	Serves the web interface on app_port: 5000.
Task Queue	Redis	command=redis-server	Acts as the local message broker and result backend.
Inference Worker	Celery / PyTorch	environment=CELERY_BROKER_URL="redis://localhost:6379/0"	Pulls tasks, runs the 2.5D U-Net model using PyTorch, and connects to Redis via localhost.

Model Details

The application utilizes a 2.5D U-Net 2-Stage Cascade approach, with each stage using a 5-channel input tensor (center slice plus 2 context slices on each side).

Data Management

Uploaded files and generated results are stored temporarily. A delayed Celery task (cleanup_files) is scheduled upon successful inference to automatically delete the files after 60 minutes to manage storage and ensure privacy.

---

📁 Repository Structure

├── README.md # This file, including the YAML header 
├── Dockerfile # Defines the Supervisor CMD and environment setup 
├── requirements.txt # Includes 'supervisor', 'celery', 'redis', 'torch', etc. 
├── supervisord.conf # Configuration file for running all three services 
├── trained_models/ # Directory containing Git LFS-tracked model files (*.pth) 
├── web_app/ 
│ ├── app.py # Flask endpoints 
│ ├── index.html # Front-end UI with polling logic 
│ ├── model_2_5d.py # U-Net architecture definition 
│ └── tasks.py # Celery task definitions (including cleanup_files) 
└── .dockerignore # Excludes local environments and large temporary files