lung-disease-detection

Lung Disease Detection

A multi-model chest X-ray analysis system for lung segmentation, healthy/unhealthy screening, and disease subtype classification.

This repository contains the deployable Keras and ONNX artifacts used by the public Lung Disease Detection web application and FastAPI inference service.

Live Resources

Model Pipeline

The system uses a multi-stage inference pipeline:

Chest X-ray
    |
    v
U-Net/Xception lung segmentation
    |
    |-- binary lung mask
    |-- lung ROI
    |-- mask overlay
    v
Healthy/unhealthy ensemble
    |
    |-- DenseNet121
    |-- EfficientNetV2B3
    |-- InceptionV3
    |-- MobileNetV3
    v
Final binary prediction
    |
    +-- Healthy
    |
    +-- Unhealthy
            |
            v
        DenseNet121 disease classifier
            |
            |-- COVID-19
            |-- Viral Pneumonia
            +-- Lung Opacity

The four binary classifiers produce unhealthy probabilities that are averaged to create the final ensemble probability.

Disease subtype classification runs only when the ensemble predicts an unhealthy chest X-ray.

Included Models

Repository Structure

healthy_unhealthy/
|-- densenet/
|-- efficientnet/
|-- inception/
+-- mobilenet/

diseases/
+-- densenet/

segmentation/
+-- unet_xception/

Each model directory contains:

• a Keras model artifact
• an ONNX model artifact
• a metadata.yaml inference contract

The metadata defines model paths, preprocessing, input dimensions, thresholds, output labels, and reported metrics.

Input

The pipeline accepts chest X-ray images in common formats such as:

• PNG
• JPEG
• WebP

Images are:

1. decoded as RGB
2. resized to 256 x 256
3. segmented to identify the lung region
4. transformed according to each model's metadata
5. passed through the classification pipeline

DICOM input is not currently supported.

Output

The complete API response can contain:

• healthy/unhealthy probability
• final binary label
• individual ensemble model results
• optional disease subtype probabilities
• predicted lung mask
• cropped lung ROI
• source image
• mask overlay image
• artifact URLs and storage paths

Classes

Binary Classification

Disease Classification

Segmentation

Reported Metrics

These values come from the metadata associated with each individual model. They are not combined ensemble metrics.

Lung Segmentation

Healthy/Unhealthy Classification

Disease Classification

Dataset

The models were developed using the COVID-19 Radiography Database.

The source dataset contains four classes:

• COVID
• Normal
• Viral Pneumonia
• Lung Opacity

For binary classification, the labels are remapped as:

Normal -> Healthy

COVID
Viral Pneumonia
Lung Opacity -> Unhealthy

For disease subtype classification, normal samples are excluded and the three abnormal classes are remapped to contiguous labels.

Users must review and comply with the original dataset license and terms separately from this model repository's MIT software license.

Training

The models were trained and evaluated using TensorFlow and Keras.

The research workflow includes:

• TFRecord-based data pipelines
• image and mask preprocessing
• synchronized augmentation
• lung ROI extraction
• class weighting
• transfer learning
• staged backbone unfreezing
• early stopping
• Optuna architecture and hyperparameter experiments
• per-class metric evaluation
• segmentation overlap evaluation

Research artifacts and methodology are available in the Research Lab.

Downloading the Models

Download the complete model repository with huggingface_hub:

from huggingface_hub import snapshot_download

model_root = snapshot_download(
    repo_id="a1mohamadd/lung-disease-detection",
    repo_type="model",
)

print(model_root)

Download into a specific local directory:

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="a1mohamadd/lung-disease-detection",
    repo_type="model",
    local_dir="saved_models",
)

Using the Complete Pipeline

The recommended way to use these artifacts is through the deployed API or source repository because the full pipeline coordinates segmentation, model-specific preprocessing, binary ensembling, disease classification, and artifact generation.

• Interactive Web App
• Hugging Face API Space
• GitHub Repository

Intended Use

This model collection is intended for:

• medical-imaging research
• machine-learning education
• software-engineering demonstrations
• MLOps and deployment experiments
• chest X-ray model benchmarking
• human-reviewed decision-support research

Out-of-Scope Use

The models must not be used:

• as a standalone clinical diagnostic system
• as a replacement for a qualified radiologist
• for emergency medical decisions
• without independent validation on the target population
• as a certified medical device
• to make fully automated treatment decisions

Limitations

Model performance may be affected by:

• dataset imbalance
• hospital and scanner differences
• image acquisition protocols
• demographic distribution
• image compression and resizing
• non-standard chest positioning
• artifacts, implants, or annotations
• domain shift outside the training dataset
• segmentation errors propagated to classifiers

The reported metrics were obtained from the project's evaluation workflow and do not establish clinical validity.

External, prospective, and institution-specific validation would be required before any real clinical deployment.

Ethical Considerations

Chest X-ray models can reproduce biases present in their training data. Predictions should be reviewed by qualified professionals alongside patient history, clinical findings, and additional diagnostic evidence.

Generated masks and overlays are visual review aids. They do not prove that a prediction is correct or provide a complete clinical explanation.

Model Formats

Both formats are included:

• Keras: useful for training, fine-tuning, evaluation, and MLflow workflows
• ONNX: recommended for lightweight CPU-oriented production inference

ONNX releases are numerically validated against their source Keras models before publication.

License

The software and model repository are released under the MIT License.

Dataset rights remain governed by the original dataset provider.

Author

Amir Mohammad Askari

• Website
• GitHub
• LinkedIn
• Kaggle