Skip to content

About

Research prototype: U-Net wound segmentation with image-derived metrics and a FastAPI dashboard. Not a medical device.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Wound Analysis (research prototype)

CI License: MIT

A FastAPI dashboard that segments a wound in a photograph with a U-Net, derives simple area / colour / shape metrics from the mask, and combines them into a heuristic score.

Not a medical device. This is experimental research software. The segmentation model and the risk score have not been clinically validated, and nothing here should be used to diagnose or make treatment decisions.

Dashboard

What it does

  1. Segmentation - U-Net with a ResNet34 encoder (segmentation-models-pytorch), 384x384 input, sigmoid output thresholded at 0.3, cleaned with morphological open/close and reduced to the largest connected region.
  2. Metrics computed from the mask at the original image resolution:
    • area in pixels and as a fraction of the image
    • redness index (mean R / mean G inside the mask)
    • compactness (perimeter² / 4π·area; 1.0 for a circle, higher for irregular shapes)
    • mean model probability inside the mask
  3. Heuristic score - a hand-tuned weighted sum: 0.40·area + 0.35·redness + 0.20·irregularity + 0.05·(1 − confidence), mapped to Mild / Moderate / Severe / Critical bands. The weights are design choices, not fitted to clinical outcomes.
  4. Plain-language summary - optionally generated by a local Ollama model; a fixed template is used when Ollama is not running.
Original Mask Overlay

Two execution modes

The API response always states which path produced the result ("mode"), and the dashboard shows a warning banner in fallback mode.

Mode When What it is
model PyTorch installed and models/best_model.pth present The trained U-Net
fallback PyTorch or the weights are unavailable An Otsu-threshold heuristic on the image centre. It is not a model prediction and exists only so the UI can be exercised without the ML stack

Model

  • Architecture: U-Net, ResNet34 encoder, 1 output class
  • Weights: models/best_model.pth (about 98 MB, stored in the repository)
  • Training data, as reported by the author: 1500 images for training and 500 for evaluation.

The training script, the dataset and an evaluation report are not part of this repository, so no accuracy, IoU or Dice figures are published here. Adding a reproducible evaluation is the first item on the roadmap.

Quick start

Requires Python 3.10+.

git clone https://github.com/projectbin07-stack/wound-analysis-aiml.git
cd wound-analysis-aiml
python -m venv .venv
# Windows: .venv\Scripts\activate    Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python app.py

Open the URL printed in the terminal (default http://127.0.0.1:8001) and upload an image. The server binds to localhost only; set HOST=0.0.0.0 to expose it on your network.

To try the interface without installing PyTorch, install requirements-dev.txt instead; the app then runs in the labelled fallback mode.

Configuration

Variable Default Purpose
HOST 127.0.0.1 Bind address
PORT 8001 First port to try
OLLAMA_URL http://localhost:11434/api/generate Local LLM endpoint
OLLAMA_MODEL llama3 Model used for the summary
OLLAMA_TIMEOUT_S 5 Timeout before the template summary is used
LOG_LEVEL INFO Python logging level

API

POST /analyze (multipart field file; jpg, png, bmp or webp up to 15 MB). The numbers below only illustrate the response shape.

{
  "success": true,
  "mode": "model",
  "model_used": true,
  "metrics": {"area": 5025, "area_pct": 8.38, "redness": 4.39, "compactness": 1.07,
              "confidence": 90.0, "risk": 41.2, "severity": "Moderate", "...": "..."},
  "explanation": "SUMMARY: ...",
  "image": "<base64 jpeg>", "overlay": "<base64 jpeg>", "mask": "<base64 png>"
}

GET /health returns {"status": "ok", "model_ready": true|false}.

Uploads are written under a random filename, analysed and deleted immediately; nothing is retained on disk.

Project layout

app.py                FastAPI app, upload validation, response assembly
model.py              U-Net definition
core/inference.py     model loading, post-processing, labelled fallback
core/analysis.py      metrics, heuristic score, summary text
static/, templates/   dashboard (vanilla JS + Chart.js)
models/best_model.pth trained weights
tests/                pytest suite

Development

pip install -r requirements-dev.txt
ruff check . && ruff format --check .
pytest

CI runs these on Python 3.10 and 3.13. The test suite covers the metrics (against hand-computed values on synthetic shapes), mask post-processing, upload validation and the API in fallback mode. It does not run the neural network: PyTorch is not installed in CI, so the model path is currently verified only by manual runs.

Known limitations

  • No published evaluation of the segmentation model (see above).
  • The redness index depends on lighting and camera white balance; no colour calibration is performed.
  • Pixel areas are not converted to physical units; there is no scale reference.
  • Only the largest connected region is kept, so images with several wounds are under-reported.
  • Performance across skin tones has not been assessed.
  • The model weights are committed directly to git rather than stored as a release asset.

Roadmap

  • Evaluation script reporting Dice / IoU on a documented, held-out set
  • Model card describing the data and intended use
  • CI job that runs the real model on a sample image
  • Weights distributed as a release asset with a checksum
  • Optional physical-scale calibration from a reference marker

License

MIT - see LICENSE. See CONTRIBUTING.md and SECURITY.md. Please never post identifiable patient images in issues or pull requests.

Author

Navaneeth KG

About

Research prototype: U-Net wound segmentation with image-derived metrics and a FastAPI dashboard. Not a medical device.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages