🩻 TB Chest X-Ray Classification Project

📋 Project Overview

A deep learning project for detecting Tuberculosis (TB) from chest X-ray images using convolutional neural networks (CNN). This project demonstrates the application of computer vision in medical diagnostics with exceptional performance metrics, featuring a complete web application with FastAPI backend and responsive frontend.

Video Demo: (https://youtu.be/mmjzrPZvU68)

👥 Team Members

• Masoud Ghasemi

  • GitHub: https://github.com/sorna-fast
  • Email: [email protected]
  • Edx Username: MG_2507_VSZB

• Samira Mashtizadeh

  • GitHub: https://github.com/samira-dev-star
  • Email: [email protected]
  • Edx Username: samira-dev-star

🏗️ Project Structure

tb_chest_xray_app/
├── app/                    # FastAPI Web Application
│   ├── api/               # API routes and endpoints
│   ├── core/              # Configuration and lifecycle
│   ├── utils/             # Utility functions
│   ├── static/            # Frontend assets
│   ├── main.py            # FastAPI application
│   ├── models.py          # ML model functions
│   └── schemas.py         # Pydantic schemas
├── datasets/              # Dataset storage
│   ├── tawsifurrahman/   # Original TB dataset
│   └── test/             # Independent test set
├── model/                # Trained model files
│   └── best_model_epoch.keras
├── notebooks/            # Jupyter notebooks for training
│   └── model_training.ipynb
├── plots/                # Visualization outputs
│   ├── class_distribution.png
│   ├── training_history.png
│   ├── confusion_matrix.png
│   ├── roc_curve.png
│   └── test_predictions_grid.png
├── requirements.txt      # Python dependencies
├── .gitignore
├── LICENSE
└── README.md

🧠 Model Architecture

📊 Complete Model Summary

Total params: 3,487,937
Trainable params: 3,485,761
Non-trainable params: 2,176

🏗️ Architecture Details

Layer Type	Output Shape	Parameters	Purpose
Input	(64, 64, 1)	0	Grayscale image input
Data Augmentation	(64, 64, 1)	0	Contrast & zoom variations
Conv2D Block 1	(64, 64, 64)	37,824	Feature extraction
BatchNorm + MaxPool	(32, 32, 64)	256	Normalization & downsampling
Conv2D Block 2	(32, 32, 256)	148,736	Intermediate features
BatchNorm + MaxPool	(16, 16, 256)	1,024	Normalization & downsampling
Conv2D Block 3	(16, 16, 384)	2,097,136	Deep feature extraction
BatchNorm + MaxPool	(8, 8, 256)	1,024	Final feature maps
Feature Fusion	(512)	0	GlobalAvg + GlobalMax pooling
BatchNorm + Dropout	(512)	2,048	Regularization
Dense Layers	(256) → (256)	197,120	Classification
Output	(1)	257	Binary prediction

🔧 Key Features

• Input: 64×64 grayscale X-ray images
• Data Augmentation: Random Contrast (0.08) + Random Zoom (0.05)
• Feature Extraction: 3 convolutional blocks with Batch Normalization
• Pooling Strategy: Combined Global Average + Global Max Pooling
• Regularization: Dropout (0.3) + Batch Normalization
• Output: Sigmoid activation for TB/Normal classification

📈 Training & Performance

🎯 Training Configuration

• Optimizer: Adagrad (lr=0.01)
• Loss Function: Binary Crossentropy
• Metrics: Accuracy, Precision, Recall, AUC
• Callbacks: ModelCheckpoint, EarlyStopping, ReduceLROnPlateau
• Training Time: ~40 minutes (20 epochs)

🏆 Exceptional Results

Metric	Training	Validation
AUC	1.0000	0.9991
Accuracy	99.88%	99.52%
Precision	99.65%	99.24%
Recall	99.65%	97.76%

📊 Visualization Results

Dataset class distribution analysis

Model training and validation metrics over epochs

Confusion matrix showing classification performance

ROC curve with exceptional AUC score

Model predictions on independent test set

🌐 Web Application Features

🚀 FastAPI Backend

• Modular Architecture with organized code structure
• RESTful API with automatic OpenAPI documentation
• Real-time predictions with image upload endpoint
• Health monitoring and model information endpoints
• Secure file handling with temporary file cleanup
• Modern lifespan management for efficient model loading

💻 Frontend Interface

• Responsive design compatible with desktop and mobile
• Drag & drop image upload functionality
• Real-time results with confidence visualization
• Professional medical UI with appropriate styling
• Error handling and user feedback systems

📡 API Endpoints

• GET / - Web interface
• POST /predict/ - TB detection from X-ray images
• GET /health - Service health check
• GET /model-info - Model specifications
• GET /docs - Interactive API documentation

🛠️ Technical Specifications

📦 Exact Package Versions

Core Machine Learning:

• TensorFlow == 2.20.0
• Keras == 3.11.3
• scikit-learn == 1.7.2
• NumPy == 2.3.3

Web Framework:

• FastAPI == 0.104.1
• Uvicorn == 0.24.0
• Pydantic == 2.5.0

Data Processing & Analysis:

• pandas == 2.3.3
• SciPy == 1.16.2
• joblib == 1.5.2

Visualization:

• matplotlib == 3.10.6
• seaborn == 0.13.2
• Pillow == 11.3.0

Data Management:

• kagglehub == 0.3.13
• h5py == 3.14.0

Development & Utilities:

• Jupyter == 6.30.1
• IPython == 9.6.0
• tqdm == 4.67.1

⚙️ Application Configuration

• Host: localhost
• Port: 8090
• Model Path: model/best_model_epoch.keras
• Debug Mode: Enabled

🔧 System Requirements

• Python: 3.8+ (tested with packages above)
• Memory: 8GB+ RAM recommended
• Storage: 2GB+ for dataset and models
• GPU: Optional but recommended for training

🚀 Current Status

✅ Project Completed - Ready for Use

✅ Implemented Features:

• Dataset download and preprocessing pipeline
• Advanced data augmentation strategies
• Custom CNN architecture with 3.4M parameters
• Comprehensive model training with callbacks
• Detailed model evaluation and visualization
• Independent test set validation
• Performance metrics analysis
• FastAPI backend with RESTful endpoints
• Responsive web frontend interface
• Real-time prediction capabilities
• Professional documentation
• Modular code architecture

🎯 Model Strengths:

• Exceptional Performance: AUC 0.9991 on validation
• Robust Architecture: Proper regularization prevents overfitting
• Medical Relevance: High precision and recall for TB detection
• Production Ready: Complete web application stack
• User Friendly: Intuitive interface for medical professionals
• Modular Design: Organized and maintainable codebase

📥 Installation & Usage

Prerequisites:

Python 3.8+

Installation:

git clone <repository-url>
cd tb_chest_xray_app
pip install -r requirements.txt

Running the Application:

# Start the FastAPI server on port 8090
uvicorn app.main:app --reload --host localhost --port 8090

# Or use the configured settings
uvicorn app.main:app --reload

Access Points:

• Web Application: http://localhost:8090
• API Documentation: http://localhost:8090/docs
• Health Check: http://localhost:8090/health

Quick API Usage:

import requests

# Make prediction on port 8090
with open("xray_image.png", "rb") as f:
    response = requests.post(
        "http://localhost:8090/predict/",
        files={"file": ("xray.png", f, "image/png")}
    )
result = response.json()
print(f"Prediction: {result['result']} ({result['confidence']}% confidence)")

🔧 API Reference

POST /predict/

Upload a chest X-ray image for TB detection.

Request:

• file: Image file (JPG, JPEG, PNG, TIF)

Response:

{
  "filename": "xray.png",
  "result": "Normal",
  "confidence": 95.5,
  "class_names": ["Normal", "Tuberculosis"]
}

GET /health

Check service status and model availability.

GET /model-info

Get technical details about the loaded model.

📝 Technical Insights

🎯 Model Performance Analysis

The model demonstrates exceptional performance with:

• Near-perfect AUC (0.9991) indicating excellent classification capability
• Minimal overfitting despite high training performance
• Balanced precision and recall crucial for medical applications
• Consistent performance across all evaluation metrics

🔍 Architecture Advantages

• Feature Fusion: Combined Global Average and Max Pooling captures both spatial and intensity information
• Progressive Complexity: Increasing filter sizes (64 → 256 → 384) for hierarchical feature learning
• Robust Regularization: Multiple dropout and batch normalization layers prevent overfitting
• Medical Focus: Grayscale processing preserves radiological information

🌐 Web Application Design

• Modular Architecture: Organized code structure for maintainability
• Modern Async Architecture: FastAPI with async/await support
• Type Safety: Pydantic schemas for request/response validation
• Professional UI: Medical-grade interface with accessibility considerations
• Security: Proper file handling and input validation

⚠️ Important Notes

🔬 Medical Application Disclaimer

This model is for research and educational purposes. For clinical use:

• Further validation on diverse datasets required
• Regulatory approval necessary
• Clinical trials recommended
• Consultation with medical professionals essential

📊 Performance Interpretation

While metrics are exceptional, continued evaluation is needed:

• Test on external datasets
• Evaluate generalization across different populations
• Monitor for dataset bias
• Regular model updates recommended

🌟 Conclusion

This project successfully demonstrates a complete, production-ready system for TB detection from chest X-rays. The custom CNN architecture achieves exceptional metrics (AUC: 0.9991) while the web application provides an intuitive interface for medical professionals. The modular codebase ensures maintainability and the system is configured for optimal local development on port 8090.

The system is now fully operational and ready for research and educational use, showcasing the potential of AI in medical diagnostics while maintaining appropriate safeguards and disclaimers for responsible deployment.

---

Project Status: Completed & Operational
Performance Level: Exceptional (AUC: 0.9991)
Web Interface: Fully Implemented
API: Production Ready
Port: 8090
Environment: Python 3.8+ with exact package versions specified

🚀 Project successfully completed with full web application implementation and modular architecture!