Important!!!! Read Explainable AI project - pneumonia diagnosis from a dataset of x-rays.pdf for complete and easy to understand project documentation!

AI-Powered Chest X-Ray Pneumonia Diagnosis System

A comprehensive deep learning system for pneumonia diagnosis from chest X-ray images using three state-of-the-art CNN architectures (EfficientNetB0, DenseNet121, ResNet50) with Explainable AI (XAI) capabilities through Grad-CAM visualizations.

📋 Table of Contents

• Overview
• Features
• Architecture
• Prerequisites
• Installation
• Project Structure
• Usage
• Testing
• API Documentation
• Troubleshooting
• Documentation
• License

🎯 Overview

This project implements an end-to-end machine learning system for automated pneumonia detection from chest X-ray images. The system employs an ensemble approach using three pre-trained and fine-tuned deep learning models to provide robust and accurate diagnoses, enhanced with explainable AI visualizations to help medical professionals understand model predictions.

For comprehensive documentation including methodology, experimental results, model architecture details, and in-depth analysis, please refer to the PDF document: Explainable AI project - pneumonia diagnosis from a dataset of x-rays.pdf

✨ Features

• Multi-Model Ensemble: Three state-of-the-art CNN architectures for robust predictions

  • EfficientNetB0
  • DenseNet121
  • ResNet50 (Fine-tuned)

• Explainable AI (XAI): Grad-CAM visualizations showing which image regions influence predictions

• Web Interface: User-friendly Django frontend for image upload and result visualization

• RESTful API: FastAPI backend providing programmatic access to the diagnosis service

• Real-time Processing: Instant predictions with visual feedback

• Best Model Selection: Automatic identification of the highest-confidence prediction

🏗️ Architecture

The system follows a client-server architecture:

┌─────────────────┐
│  Django Frontend │ (Port 8001)
│   (UI/UX)        │
└────────┬────────┘
         │ HTTP/REST
         ▼
┌─────────────────┐
│  FastAPI Backend │ (Port 8002)
│   (API Server)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Diagnosis Service │
│  - EfficientNetB0 │
│  - DenseNet121    │
│  - ResNet50       │
│  - Grad-CAM XAI   │
└─────────────────┘

📦 Prerequisites

• Python: 3.10 or higher
• Operating System: Windows, Linux, or macOS
• Memory: Minimum 8GB RAM (16GB recommended for model loading)
• Storage: ~500MB for dependencies + ~300MB for model files
• GPU: Optional but recommended for faster inference (CUDA-compatible GPU)

🔧 Installation

1. Clone the Repository

git clone <repository-url>
cd xai-chest-xray-pneumonia

2. Create Virtual Environment

Windows:

python -m venv .venv
.venv\Scripts\activate

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate

3. Install Backend Dependencies

pip install -r model_api/requirements.txt

Backend dependencies include:

• fastapi>=0.104.0 - Web framework for API
• uvicorn[standard]>=0.24.0 - ASGI server
• python-multipart>=0.0.6 - File upload support
• tensorflow>=2.13.0 - Deep learning framework
• numpy>=1.24.0 - Numerical computations
• pillow>=10.0.0 - Image processing
• matplotlib>=3.7.0 - Visualization for Grad-CAM
• pydantic>=2.0.0 - Data validation

4. Install Frontend Dependencies

pip install -r Django_frontend/requirements.txt

Frontend dependencies include:

• Django>=4.2.7 - Web framework
• Pillow>=10.0.0 - Image handling
• numpy>=1.24.0 - Array operations
• tensorflow>=2.15.0 - (Optional, for client-side processing if needed)

5. Verify Model Files

Ensure all three trained models are present in saved_models/successful_models/:

• efficientnetb0_fixed.keras
• densenet121_qai.keras
• FINETUNED_resnet50_mc_pneumonia_classifier.keras

📁 Project Structure

xai-chest-xray-pneumonia/
├── Django_frontend/           # Django web application
│   ├── diagnosis/             # Main app
│   │   ├── templates/         # HTML templates
│   │   ├── static/            # CSS, JavaScript, images
│   │   └── views.py           # View handlers
│   ├── proiectpy/             # Django project settings
│   └── manage.py              # Django management script
│
├── model_api/                 # FastAPI backend
│   ├── main.py                # FastAPI application
│   └── requirements.txt       # Backend dependencies
│
├── Services/                  # Core ML services
│   ├── xray_diagnosis_service.py  # Main diagnosis service
│   └── test_service.py        # Service testing utilities
│
├── Notebooks/                 # Jupyter notebooks
│   ├── 1_EDA_Data_Prep_and_Model_Training.ipynb
│   ├── 2_Fine_Tuning_All_Models.ipynb
│   └── 3_XAI_Grad-CAM.ipynb
│
├── saved_models/              # Trained model files
│   ├── successful_models/     # Production models
│   └── unsuccessful_models/   # Experimental models
│
├── initial_model_results/     # Training metrics and visualizations
│
├── run_fastapi.py             # FastAPI launcher script
├── start_fastapi.bat          # Windows batch file for FastAPI
├── start_django.bat           # Windows batch file for Django
│
└── Explainable AI project - pneumonia diagnosis from a dataset of x-rays.pdf
    └── **Complete project documentation (READ THIS!)**

🚀 Usage

Quick Start (Windows)

1. Start FastAPI Backend:

   start_fastapi.bat

   Or manually:

   python run_fastapi.py

   Server will start on http://127.0.0.1:8002

2. Start Django Frontend (in a new terminal):

   start_django.bat

   Or manually:

   cd Django_frontend
   python manage.py runserver 8001

   Server will start on http://127.0.0.1:8001

3. Access the Application:

   • Open your browser and navigate to http://127.0.0.1:8001
   • Upload a chest X-ray image
   • View diagnosis results from all three models with XAI visualizations

Manual Start (Linux/macOS)

Terminal 1 - FastAPI:

cd xai-chest-xray-pneumonia
python run_fastapi.py

Terminal 2 - Django:

cd xai-chest-xray-pneumonia/Django_frontend
python manage.py runserver 8001

🧪 Testing

1. Backend Health Check

Visit http://127.0.0.1:8002/ in your browser or use curl:

curl http://127.0.0.1:8002/

Expected response:

{
  "status": "ok",
  "message": "XAI Chest X-Ray API is running and models are loaded."
}

2. API Documentation

Interactive API documentation is available at:

• Swagger UI: http://127.0.0.1:8002/docs
• ReDoc: http://127.0.0.1:8002/redoc

3. Test API Endpoint

Using curl:

curl -X POST "http://127.0.0.1:8002/diagnosis" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/xray_image.jpeg"

4. Frontend Testing

1. Navigate to http://127.0.0.1:8001
2. Upload a chest X-ray image (JPEG or PNG)
3. Click "Analyze Image"
4. Verify results show:
   • Three model predictions (EfficientNetB0, DenseNet121, ResNet50)
   • Diagnosis labels (NORMAL or PNEUMONIA)
   • Confidence percentages
   • XAI heatmap visualizations
   • Best model indicator

5. Expected Output

{
  "results": [
    {
      "model_name": "EfficientNetB0",
      "diagnosis": "PNEUMONIA",
      "confidence": 0.838,
      "xai_image_base64": "base64_encoded_image_data..."
    },
    {
      "model_name": "DenseNet121",
      "diagnosis": "PNEUMONIA",
      "confidence": 0.572,
      "xai_image_base64": "base64_encoded_image_data..."
    },
    {
      "model_name": "ResNet50",
      "diagnosis": "PNEUMONIA",
      "confidence": 0.999,
      "xai_image_base64": "base64_encoded_image_data..."
    }
  ],
  "best_model_name": "ResNet50"
}

📚 API Documentation

Endpoints

GET /

Health check endpoint.

Response:

{
  "status": "ok",
  "message": "XAI Chest X-Ray API is running and models are loaded."
}

POST /diagnosis

Process a chest X-ray image through all three models.

Request:

• Method: POST
• Content-Type: multipart/form-data
• Body: file (image file)

Response:

• Status: 200 OK
• Body: JSON with results from all three models

See http://127.0.0.1:8002/docs for interactive API documentation.

🔍 Troubleshooting

Models Not Loading

Issue: FastAPI shows errors loading models

• Solution: Verify model files exist in saved_models/successful_models/
• Check file permissions
• Ensure sufficient memory (models are ~100-200MB each)

Port Conflicts

Issue: Port 8002 or 8001 already in use

• Solution:
  • Kill existing processes: netstat -ano | findstr :8002 (Windows)
  • Change ports in run_fastapi.py and Django_frontend/static/js/main.js

CORS Errors

Issue: Browser console shows CORS errors

• Solution: CORS is already configured in model_api/main.py. Verify:

  allow_origins=["http://127.0.0.1:8001", "http://localhost:8001"]

Image Upload Fails

Issue: "Failed to fetch" error

• Solution:
  1. Verify FastAPI is running on port 8002
  2. Check browser console (F12) for detailed errors
  3. Ensure image is valid JPEG/PNG format
  4. Check firewall settings

Models Predict Incorrectly

Issue: All predictions show NORMAL or incorrect results

• Solution:
  • Verify image preprocessing matches training pipeline
  • Check that models loaded successfully (see FastAPI startup logs)
  • Ensure correct class mapping (0=NORMAL, 1=PNEUMONIA)

Grad-CAM Generation Errors

Issue: Error generating heatmaps

• Solution:
  • Models use binary classification (sigmoid output), which is handled automatically
  • Check console logs for specific layer errors
  • Verify TensorFlow version compatibility

📖 Documentation

⚠️ IMPORTANT: For complete project documentation, methodology, experimental setup, results analysis, and technical deep-dive, please read:

Explainable AI project - pneumonia diagnosis from a dataset of x-rays.pdf

This PDF document contains:

• Complete project overview and objectives
• Dataset description and preprocessing steps
• Model architecture details for all three CNNs
• Training methodology and hyperparameters
• Fine-tuning strategies
• Experimental results and performance metrics
• XAI (Explainable AI) implementation details
• Model comparison and analysis
• Future work and conclusions

The PDF provides comprehensive documentation that complements this technical setup guide.

🔬 Model Details

Model Architectures

• EfficientNetB0: Efficient CNN with compound scaling
• DenseNet121: Densely connected convolutional network
• ResNet50: Residual network with 50 layers (fine-tuned)

All models were:

• Pre-trained on ImageNet
• Fine-tuned on chest X-ray pneumonia dataset
• Trained with binary cross-entropy loss
• Using sigmoid activation for binary classification

Performance

See the PDF documentation for detailed performance metrics, confusion matrices, ROC curves, and comparison charts.

🛠️ Development

Running Tests

# Test the diagnosis service
python Services/test_service.py

# Test API endpoints
curl http://127.0.0.1:8002/

Modifying Models

Models can be retrained using the Jupyter notebooks in the Notebooks/ directory:

1. 1_EDA_Data_Prep_and_Model_Training.ipynb - Initial training
2. 2_Fine_Tuning_All_Models.ipynb - Fine-tuning
3. 3_XAI_Grad-CAM.ipynb - XAI visualization

📝 Notes

• First model load takes 30-60 seconds (models are loaded lazily on first request)
• Models are loaded into memory and persist for subsequent requests
• Image preprocessing is model-specific (EfficientNet, DenseNet, ResNet50 preprocessing functions)
• Grad-CAM visualizations show which image regions influence predictions

🤝 Contributing

This is a research/academic project. For questions or contributions, please refer to the PDF documentation.

📄 License

[Specify your license here]

👤 Author

[Your name/institution]

🙏 Acknowledgments

• Chest X-Ray dataset providers
• TensorFlow/Keras team
• FastAPI and Django communities
• All contributors to open-source ML libraries

---

Remember to read Explainable AI project - pneumonia diagnosis from a dataset of x-rays.pdf for complete project documentation!