---
title: AI MedScan
emoji: π₯
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
---
# AI MedScan β Medical Image Intelligence Platform π₯π€
**Industry-grade AI-powered chest radiograph analysis using DenseNet121 architecture with Grad-CAM explainability**
[Features](#-features) β’ [Architecture](#-architecture) β’ [Quick Start](#-quick-start) β’ [API Docs](#-api-documentation) β’ [Research](#-research-references)
---
## π Features
| Feature | Description |
|---------|-------------|
| π§ **DenseNet121 Classification** | CheXNet-inspired multi-label classifier detecting 14 thoracic pathologies |
| ποΈ **Grad-CAM Explainability** | Visual attention maps showing diagnostic regions with anatomical localization |
| π **Clinical Reporting** | Automated DICOM SR-style reports with ICD-10 codes and differential diagnoses |
| π‘οΈ **Quality Assessment** | CLAHE-enhanced preprocessing with automated image quality scoring |
| β‘ **Real-Time Processing** | Sub-2-second analysis with FastAPI async backend |
| π **Risk Stratification** | Automated triage from CRITICAL to NORMAL with severity scoring |
## π¬ Detectable Pathologies (14)
| # | Pathology | ICD-10 | Urgency |
|---|-----------|--------|---------|
| 1 | Atelectasis | J98.11 | Moderate |
| 2 | Cardiomegaly | I51.7 | Moderate |
| 3 | Consolidation | J18.9 | High |
| 4 | Edema | J81.0 | High |
| 5 | Effusion | J90 | Moderate |
| 6 | Emphysema | J43.9 | Moderate |
| 7 | Fibrosis | J84.10 | Moderate |
| 8 | Hernia | K44.9 | Low |
| 9 | Infiltration | R09.89 | Moderate |
| 10 | Mass | R91.8 | Critical |
| 11 | Nodule | R91.1 | High |
| 12 | Pleural Thickening | J92.9 | Low |
| 13 | Pneumonia | J18.9 | High |
| 14 | Pneumothorax | J93.9 | Critical |
## ποΈ Architecture
```
βββββββββββββββ ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ
β Input ββββββΆβ Preprocess ββββββΆβ DenseNet121 ββββββΆβ Grad-CAM β
β Chest X-Ray β β CLAHE+Norm β β Classificationβ β Attention β
β (JPEG/PNG) β β (224Γ224Γ3) β β (14 classes) β β Maps β
βββββββββββββββ ββββββββββββββββ ββββββββββββββββ ββββββββ¬ββββββββ
β
ββββββββββββββββ ββββββββββββββββ β
β Clinical βββββββ Risk ββββββββββββββ
β Report β β Assessment β
β (ICD-10) β β (Triage) β
ββββββββββββββββ ββββββββββββββββ
```
### Tech Stack
| Component | Technology | Purpose |
|-----------|-----------|---------|
| **ML Backbone** | TensorFlow + DenseNet121 | Feature extraction & classification |
| **Explainability** | Grad-CAM | Visual attention mapping |
| **Image Processing** | OpenCV + PIL | CLAHE enhancement, preprocessing |
| **Backend API** | FastAPI + Uvicorn | REST API + async processing |
| **Frontend** | HTML5 + CSS3 + JavaScript | Interactive analysis dashboard |
| **Visualization** | Chart.js | Confidence charts & quality radar |
| **Computation** | NumPy + SciPy | Numerical operations |
## π Quick Start
### Prerequisites
- Python 3.10+
- pip package manager
### Installation
```bash
# 1. Clone the repository
git clone https://github.com/yourusername/ai-medscan.git
cd ai-medscan
# 2. Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/macOS
# OR
.\venv\Scripts\activate # Windows
# 3. Install dependencies
cd backend
pip install -r requirements.txt
# 4. Start the server
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
### Access
- **Web UI**: http://localhost:8000
- **API Docs**: http://localhost:8000/api/docs
- **ReDoc**: http://localhost:8000/api/redoc
- **Health Check**: http://localhost:8000/api/health
## π‘ API Documentation
### Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/analyze` | Analyze a medical image |
| `GET` | `/api/health` | System health check |
| `GET` | `/api/model/info` | Model architecture info |
| `GET` | `/api/pathologies` | List all detectable pathologies |
| `GET` | `/api/analysis/{id}` | Retrieve previous analysis |
| `GET` | `/api/stats` | Platform statistics |
### Example: Analyze Image
```bash
curl -X POST "http://localhost:8000/api/analyze?enhance=true&colormap=jet" \
-H "accept: application/json" \
-F "file=@chest_xray.jpg"
```
### Response Structure
```json
{
"analysis_id": "MEDSCAN-A1B2C3D4E5F6",
"status": "completed",
"processing_time_ms": 1245.3,
"quality_assessment": {
"quality_score": 82.5,
"quality_grade": "Good"
},
"predictions": {
"findings": [...],
"assessment": {
"risk_score": 45.2,
"status": "BORDERLINE - Follow-up Suggested",
"status_code": "borderline"
}
},
"heatmaps": {
"primary": {
"overlay": "",
"raw": "",
"contours": ""
}
},
"clinical_report": {...}
}
```
## π Research References
1. **CheXNet**: Rajpurkar et al., "Radiologist-Level Pneumonia Detection on Chest X-Rays with Deep Learning" (arXiv:1711.05225, 2017)
2. **Grad-CAM**: Selvaraju et al., "Visual Explanations from Deep Networks via Gradient-based Localization" (ICCV 2017)
3. **CheXpert**: Irvin et al., "A Large Chest Radiograph Dataset with Uncertainty Labels" (AAAI 2019)
4. **DenseNet**: Huang et al., "Densely Connected Convolutional Networks" (CVPR 2017)
## π Training Pipeline
### Download Real NIH Data & Train
```bash
cd backend
# 1. Download real NIH Chest X-Ray14 images (via MedMNIST)
python -m app.training.download_real_data --output_dir ./real_data --max_images 3000
# 2. Train DenseNet121 with two-phase strategy
python -m app.training.train_model --data_dir ./real_data --epochs 15 --batch_size 16 --loss focal
# 3. Model auto-deploys to trained_models/best_model.keras
```
### Training Results (Real NIH Data)
| Metric | Value |
|--------|-------|
| **Dataset** | 4,200 real NIH chest X-rays |
| **Best Val AUC** | 0.664 |
| **Test Mean AUROC** | 0.609 |
| **Top Pathology** | Cardiomegaly (0.789 AUROC) |
| **Training Time** | ~6 hours (CPU) |
## π Project Structure
```
ai-medscan/
βββ backend/
β βββ app/
β β βββ __init__.py
β β βββ main.py # FastAPI application
β β βββ models/
β β β βββ classifier.py # DenseNet121 classifier
β β βββ services/
β β β βββ gradcam.py # Grad-CAM implementation
β β β βββ report_generator.py # Clinical report generation
β β βββ utils/
β β β βββ preprocessing.py # Image preprocessing pipeline
β β βββ training/
β β βββ train_model.py # DenseNet121 training engine
β β βββ dataset.py # Multi-format dataset loader
β β βββ evaluate.py # AUROC evaluation
β β βββ prepare_data.py # Synthetic data generator
β β βββ download_real_data.py # Real NIH data downloader
β βββ trained_models/ # Trained model weights (.keras)
β βββ real_data/ # Real NIH training images
β βββ requirements.txt
βββ frontend/
β βββ index.html # Main application page
β βββ css/
β β βββ styles.css # Medical-grade dark UI
β βββ js/
β βββ app.js # Frontend application logic
βββ sample_images/ # Sample chest X-rays
βββ README.md
βββ .gitignore
```
## β οΈ Disclaimer
> **This application is for research and educational purposes ONLY.**
> It has NOT been validated for clinical use and should NOT be used for actual medical diagnosis or treatment decisions. Always consult qualified healthcare professionals for medical advice. The AI model may produce false positives or false negatives.
## π License
MIT License β See [LICENSE](LICENSE) for details.
---
Built with β€οΈ for advancing healthcare AI
**[β¬ Back to Top](#ai-medscan--medical-image-intelligence-platform-)**