Bone-Fracture-Detection

KO | EN

gitlite — search

#hacktoberfest #golang #machine-learning #deep-learning #macos #nodejs #java #windows #cli #kubernetes #vue #awesome-list #mcp #open-source

Bone-Fracture-Detection

(★ 15)

Detecting fractures on top of X-ray imaging modalities using various state-of-the-art techniques of deep learning

Bone-Fracture-Detection Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Bone Fracture Detection

This repository began as a 2021 notebook-based deep learning project for fracture detection on X-ray images. It has now been rebuilt as a modular Python project with a command-line pipeline, a doctor-style prediction dashboard, configurable transfer learning backbones, experiment tracking hooks, tests, and a cleaner production-style layout.

## Why this refactor

The original project was built in Colab notebooks, which worked well for experimentation but made it harder to:

- reuse code across training and prediction
- run experiments from the command line
- document setup clearly for new contributors
- maintain and extend the project over time

The new structure keeps the same spirit of the original DenseNet-based pipeline while moving the core logic into reusable Python modules.

## Project layout

Key directories:

- `data/raw/`: source dataset in MURA-style layout
- `data/metadata/`: CSV manifests and dataset indexes
- `configs/`: YAML configuration files
- `scripts/`: shell entry points for common tasks
- `tests/`: lightweight regression tests
- `src/bone_fracture_detection/web.py`: Streamlit dashboard
- `src/bone_fracture_detection/recommendation.py`: rule-based and optional Ollama-backed recommendation layer

## What the CLI supports

- `index`: generate a metadata CSV by scanning a MURA-style dataset or adapting an existing image-path CSV
- `train`: train a binary fracture classifier with a selectable transfer-learning backbone
- `evaluate`: score a saved model on the validation split
- `predict`: run inference on a single image
- `list-backbones`: show all supported model families and presets
- `export-tflite`: export a trained Keras model for lightweight dashboard inference

## Web dashboard

The project now includes a doctor-style prediction dashboard for single-image fracture screening. It provides:

- an upload workflow for X-ray images
- automatic model discovery from `artifacts/`
- auto-loaded image size and backbone hints from `run_config.json`
- a professional clinical UI for previewing predictions
- a confidence score and triage-style recommendation block
- an optional local `Ollama` summary mode with safe fallback to rule-based recommendations

Install the UI dependency and launch it with:

```bash
pip install -e ".[ui]"
scripts/run_dashboard.sh
```

By default, the dashboard prefers available `.tflite` exports and then falls back to `final_model.keras` files inside [`artifacts/`](/Users/md686119/Documents/New%20project/Bone-Fracture-Detection/artifacts).

### How to predict in the dashboard

1. Launch the dashboard with `scripts/run_dashboard.sh`.
2. Open the localhost URL shown by Streamlit.
3. Leave the default saved model selected, or choose another saved artifact from the sidebar.
4. Upload a single X-ray image.
5. Click `Run Fracture Prediction`.
6. Review the fracture probability, urgency, confidence band, and workflow recommendation.

Example validation images already in the repository:

- positive: [`data/raw/valid/XR_HUMERUS/patient11248/study1_positive/image1.png`](/Users/md686119/Documents/New%20project/Bone-Fracture-Detection/data/raw/valid/XR_HUMERUS/patient11248/study1_positive/image1.png)
- negative: [`data/raw/valid/XR_HUMERUS/patient11251/study1_negative/image1.png`](/Users/md686119/Documents/New%20project/Bone-Fracture-Detection/data/raw/valid/XR_HUMERUS/patient11251/study1_negative/image1.png)

Notes:

- the bundled artifacts are smoke-test models meant to validate the pipeline and UI
- the dashboard is for research and demo use, not clinical deployment
- I could not embed a true live browser screenshot automatically from this CLI environment, so the README includes a clear browser workflow instead

### Optional Ollama summaries

If you want a locally generated LLM summary without using a cloud API, run an Ollama model on your machine and switch the dashboard `Recommendation mode` to `Ollama`.

Example:

```bash
ollama pull llama3.2:3b
ollama serve
```

The dashboard sends only structured prediction fields such as label, probability, threshold, and study type. If Ollama is unavailable, the app falls back automatically to the built-in rule-based recommendation engine.

## Supported backbones

The training pipeline now supports these transfer-learning model families:

- ResNet via `resnet` or `resnet50`
- Inception via `inception`, `googlenet`, or `inception_v3`
- VGG via `vgg` or `vgg16`
- EfficientNet via `efficientnet` or `efficientnet_b0`
- DenseNet via `densenet` or `densenet169`
- MobileNet via `mobilenet` or `mobilenet_v2`
- NASNet via `nasnet` or `nasnet_mobile`
- Xception via `xception`
- AlexNet via `alexnet`
- Vision Transformers via `vit` or `vit_base_patch16_224_imagenet`

To inspect them from the CLI:

```bash
bone-fracture list-backbones
```

Notes:

- most CNN backbones use `tf.keras.applications` ImageNet weights
- `alexnet` is included as a configurable architecture, but does not ship with built-in ImageNet weights in this project
- `vit` requires `keras-hub`, which you can install with `pip install -e ".[vision]"`
- the training pipeline has been smoke-tested locally with DenseNet and ResNet paths, and model initialization has been validated for AlexNet and ViT

## Dataset expectations

The CLI assumes a MURA-style directory layout like this:

Labels are inferred from folder names such as `study1_positive` and `study1_negative`.

Legacy CSV indexes now live under [`data/metadata/`](/Users/md686119/Documents/New%20project/Bone-Fracture-Detection/data/metadata) and can still be reused with the CLI.

## Installation

Create and activate a virtual environment, then install the project in editable mode:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .
```

This installs the `bone-fracture` command. For reproducibility, prefer running the included shell scripts so the repo-local `.venv` is used automatically when available.

## Quickstart

### 1. Review the default config

The baseline configuration is stored in [`configs/default.yaml`](/Users/md686119/Documents/New%20project/Bone-Fracture-Detection/configs/default.yaml).

For a very small end-to-end verification run, use [`configs/smoke_test.yaml`](/Users/md686119/Documents/New%20project/Bone-Fracture-Detection/configs/smoke_test.yaml). It uses:

- a smaller image size
- only a few train and validation images
- random backbone initialization instead of downloading ImageNet weights
- short patience values so early stopping and checkpointing can be exercised quickly

### 2. Build metadata

Scan the dataset directory directly:

```bash
bone-fracture index \
  --data-dir data/raw \
  --split train \
  --study-type XR_HUMERUS \
  --output data/metadata/train_humerus_metadata.csv
```

Or adapt an existing image-path CSV:

```bash
bone-fracture index \
  --data-dir data/raw \
  --input-csv data/metadata/train_image_paths1.csv \
  --output data/metadata/train_metadata_from_csv.csv
```

### 3. Train a model

```bash
bone-fracture train \
  --data-dir data/raw \
  --backbone densenet169 \
  --study-type XR_HUMERUS \
  --output-dir artifacts/humerus_run \
  --epochs 5 \
  --batch-size 8
```

To switch architectures, change `--backbone`. For example:

```bash
bone-fracture train --config configs/default.yaml --backbone resnet
bone-fracture train --config configs/default.yaml --backbone efficientnet
bone-fracture train --config configs/default.yaml --backbone xception --image-size 299
```

Or use the production-style wrapper script and YAML config:

```bash
scripts/train.sh
```

For a fast smoke test:

```bash
scripts/smoke_train.sh
```

Artifacts are written to the output directory, including:

- `best_model.keras`
- `final_model.keras`
- `metrics.json`
- `run_config.json`
- `training_log.csv`
- `logs/` for TensorBoard

### 4. Evaluate a saved model

```bash
bone-fracture evaluate \
  --model-path artifacts/humerus_run/final_model.keras \
  --data-dir data/raw \
  --study-type XR_HUMERUS
```

Or:

```bash
scripts/evaluate.sh
```

### 5. Predict a single image

```bash
bone-fracture predict \
  --model-path artifacts/humerus_run/final_model.keras \
  --image-path data/raw/valid/XR_HUMERUS/patient11248/study1_positive/image1.png
```

Or:

```bash
scripts/predict.sh
```

## Experiment tracking

TensorBoard logging is enabled by default for training runs. After training:

```bash
scripts/tensorboard.sh artifacts
```

Optional Weights & Biases support is available through the `experiment` extra:

```bash
pip install -e ".[experiment]"
bone-fracture train --config configs/default.yaml --use-wandb
```

Vision Transformer support is available through the `vision` extra:

```bash
pip install -e ".[vision]"
bone-fracture train --config configs/default.yaml --backbone vit
```

UI support is available through the `ui` extra:

```bash
pip install -e ".[ui]"
scripts/run_dashboard.sh
```

## Smoke-test checklist

If you want to validate the pipeline end to end with minimal cost:

```bash
scripts/smoke_train.sh
PYTHONPATH=src python3 -m bone_fracture_detection evaluate --config configs/smoke_test.yaml
PYTHONPATH=src python3 -m bone_fracture_detection predict --config configs/smoke_test.yaml
```

### 6. Run tests

```bash
PYTHONPATH=src pytest
```

## Verification

The current refactor has been verified with:

- metadata indexing from the CLI
- smoke training in a local `.venv`
- checkpoint saving and reload
- evaluation and single-image prediction
- backbone registry tests via `pytest`

## Development notes

- The package is designed as a clean baseline for future improvements such as richer augmentation, more metrics, additional body-part support, experiment tracking, and CI.
- The notebook-era code has been removed so the repository has a single maintainable path forward.

## Suggested next steps

- add automated tests for metadata generation and CLI behavior
- add support for training across all study types, not only a single body part at a time
- export confusion matrix plots and classification reports as files
- add Docker support for reproducible community usage

## Citation

If you build on this project, please cite the original repository:

```@misc{hossain2026bonefracturedetection,
  author       = {Elias Hossain},
  title        = {Bone Fracture Detection: A Modular Deep Learning Framework with a Clinical-Style Inference Dashboard},
  month        = apr,
  year         = {2026},
  doi          = {10.13140/RG.2.2.21509.92648},
  note         = {ResearchGate preprint}
}
```

Bone-Fracture-Detection

Bone-Fracture-Detection Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Bone-Fracture-Detection

Bone-Fracture-Detection Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README