chest-xray-disease-classifier-resnet18

KO | EN

gitlite — search

#javascript #python #hacktoberfest #typescript #golang #android #deep-learning #macos #windows #awesome #vue #ios #mcp #open-source

chest-xray-disease-classifier-resnet18

(★ 5)

No description available.

chest-xray-disease-classifier-resnet18 Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Chest X‑Ray Disease Classifier (ResNet‑18 + FastAPI)

This repository provides a lightweight FastAPI service and a simple Python inference script to classify chest X‑ray images using a ResNet‑18 model. It also includes a notebook to prepare train/validation splits from the COVID‑ChestXray dataset.

- Inference service: `main.py` (FastAPI endpoint `/predict/`)
- Standalone script: `inference.py` (local image → prediction)
- Pretrained weights: `resnet18_final.pth` (used by the API) and `resnet_covid.pth` (used by the script)
- Dataset split artifacts: `train_split.csv`, `val_split.csv`
- Notebook: `XRAY.ipynb`

Suggested GitHub repository name: `chest-xray-disease-classifier-resnet18`.

## Features
- ResNet‑18 backbone with a custom classification head
- CPU‑friendly inference (CUDA not required)
- FastAPI endpoint for easy integration with web or mobile clients
- Minimal local inference script
- Simple data split workflow in the notebook

## Requirements
- Python 3.9+ (3.10 recommended)
- PyTorch
- torchvision
- FastAPI
- Uvicorn
- Pillow
- pandas (for the notebook)
- scikit-learn (for the notebook)

Install core runtime dependencies:
```bash
pip install torch torchvision fastapi uvicorn pillow
```

Notebook utilities:
```bash
pip install pandas scikit-learn
```

## Project structure
```text
.
├─ main.py                # FastAPI app exposing /predict/
├─ inference.py           # Standalone inference function for local images
├─ resnet18_final.pth     # Model weights used by the API (FastAPI)
├─ resnet_covid.pth       # Model weights used by the standalone script
├─ train_split.csv        # Example training split (from the notebook)
├─ val_split.csv          # Example validation split (from the notebook)
└─ XRAY.ipynb             # Notebook for data prep/splitting
```

## Model and classes
There are two usages in the repo with potentially different class sets:

- API (`main.py`) uses 8 classes with `resnet18_final.pth`:
  ```
  ['Bacterial Pneumonia', 'COVID-19', 'Fungal Pneumonia', 'Lipoid Pneumonia', 'Normal', 'Pneumonia', 'Tuberculosis', 'Viral Pneumonia']
  ```
- Script (`inference.py`) currently uses `resnet_covid.pth` with:
  ```
  ['Pneumonia']
  ```

Ensure your weight file matches the number and order of classes defined in its corresponding script. If you retrain or change classes, update both the weights and the `class_names` in code.

## Running the FastAPI service
1) Ensure `./resnet18_final.pth` exists.
2) Start the server:
```bash
uvicorn main:app --host 0.0.0.0 --port 8000
```
3) Send a request with an X‑ray image:
```bash
curl -X POST \
  -F "file=@/path/to/image.jpg" \
  http://localhost:8000/predict/
```
Expected JSON:
```json
{"prediction": "COVID-19"}
```
Errors return:
```json
{"error": "..."}
```

## Using the standalone inference script
- Ensure `./resnet_covid.pth` exists.
- Example:
```python
from inference import predict

label = predict("/path/to/image.jpg")
print(label)
```

## Data preparation notebook
`XRAY.ipynb` demonstrates how to:
- Load COVID‑ChestXray metadata
- Filter to valid classes and X‑ray modality
- Create label mappings and image paths
- Split into train/validation and export `train_split.csv` and `val_split.csv`

Adjust dataset paths in the notebook to your local layout before running.

## Notes
- Preprocessing uses `Resize((224, 224))` and `ToTensor()`. If training used normalization, add the same normalization at inference.
- Both scripts run on CPU by default (`map_location=torch.device('cpu')`). For GPU, move model/tensors to CUDA and use compatible weights.
- Keep large weight files out of version control; see `.gitignore` below.

## Troubleshooting
- Shape mismatch on `load_state_dict`: your class count in code does not match training. Update `class_names` and the final `Linear` layer.
- Image open errors: ensure the file is a valid RGB image. The code converts to RGB during load.
- FastAPI 422 errors: send a form field named `file`.

## License
Choose and add a license (e.g., MIT) if you intend to share or distribute.

## Acknowledgments
- `torchvision.models` ResNet‑18
- COVID‑ChestXray dataset (referenced in the notebook)

chest-xray-disease-classifier-resnet18

chest-xray-disease-classifier-resnet18 Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

chest-xray-disease-classifier-resnet18

chest-xray-disease-classifier-resnet18 Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README