README.md

metadata

title: Parkinson's Motor Impairment Predictor
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860

Parkinson's Motor Impairment Score API

This project is a FastAPI service that predicts Parkinson's-related motor impairment from patient drawing images.

It accepts two drawing styles:

• Wave drawings
• Spiral drawings

Each image is preprocessed and passed into a deep learning model to produce:

• a raw model logit
• a sigmoid probability
• a normalized motor impairment score from 0 to 100
• a severity label
• a human-readable description

The project is designed for local development, Docker deployment, and Hugging Face Spaces.

The service is intended to:

1. receive an uploaded image
2. preprocess it consistently
3. run inference using a pretrained model
4. return a structured prediction response

---

Key Features

1. FastAPI-based service

The API uses FastAPI for fast request handling, automatic validation, and interactive documentation.

2. Two prediction routes

• Wave drawings use a VGG19-based model
• Spiral drawings use a ResNet101-based model

3. Startup model loading

Both models are loaded during application startup so the first request is faster.

4. Custom preprocessing pipeline

The image pipeline reproduces the original training preprocessing using:

• OpenCV
• NumPy
• Pillow

5. Hugging Face model download

The trained .h5 models are downloaded from Hugging Face Hub when needed.

6. CORS support

The API is configured to accept cross-origin requests from browser-based clients.

7. Docker-ready deployment

The repository includes a Dockerfile for Hugging Face Spaces deployment.

---

Repository Structure

• main.py - FastAPI application entry point and API routes
• services/predictor.py - model loading, preprocessing, and prediction logic
• services/init.py - package initializer
• requirements.txt - Python dependencies
• Dockerfile - container configuration for deployment
• .github/workflows/deploy.yml - GitHub Actions workflow for deployment to Hugging Face
• test/ - sample images for testing and experimentation

---

How the API Works

Request flow

1. A client uploads a drawing image using multipart form data
2. The API validates that the file is an image
3. The image is converted into a consistent tensor-like NumPy array
4. The correct model is loaded if not already cached
5. The model returns a raw logit
6. The logit is converted to a sigmoid probability
7. The result is normalized into a motor impairment score
8. A severity label and description are returned

Preprocessing pipeline

The preprocessing logic performs the following steps:

1. load the image
2. convert to grayscale
3. apply Otsu thresholding with inversion
4. resize to 224 × 224
5. replicate grayscale into 3 channels
6. apply normalization logic compatible with the training setup
7. add a batch dimension

---

API Endpoints

Health check

GET /

Returns a simple status response.

Example response:

{
  "status": "ok",
  "message": "Welcome to the Motor Impairment Score API"
}

Predict wave drawing

POST /predict/wave

Accepts a wave drawing image and returns a prediction.

Predict spiral drawing

POST /predict/spiral

Accepts a spiral drawing image and returns a prediction.

Input format

Both prediction endpoints expect:

• multipart/form-data
• a single file field named file

Example response

{
  "drawing_type": "wave",
  "raw_logit": 8.7809,
  "sigmoid_probability": 0.9998,
  "motor_impairment_score": 43.98,
  "severity_level": "Mild",
  "description": "Slight motor irregularities observed.",
  "is_parkinson": true
}

Response fields

• drawing_type - either wave or spiral
• raw_logit - raw model output before sigmoid
• sigmoid_probability - probability converted from the logit
• motor_impairment_score - normalized score between 0 and 100
• severity_level - severity category
• description - human-readable interpretation
• is_parkinson - boolean indicator derived from the severity level

---

Severity Levels

The API classifies the result into one of these labels:

• Normal Pattern - no motor impairment detected
• Mild - slight motor irregularities observed
• Moderate - noticeable motor impairment detected
• High - significant motor impairment observed
• Severe - strong Parkinsonian motor patterns detected

The exact score thresholds are defined in services/predictor.py.

---

Local Setup

1. Create a virtual environment

python -m venv venv
source venv/bin/activate

2. Install dependencies

pip install -r requirements.txt

If needed, also install the runtime packages used by the API:

pip install fastapi uvicorn python-multipart

3. Run the server

uvicorn main:app --reload

4. Open the documentation

Visit:

http://127.0.0.1:8000/docs

This opens the interactive Swagger UI for testing the API.

---

Example Requests

cURL example

curl -X POST "http://127.0.0.1:8000/predict/wave" \
   -F "file=@test/wave.png"

Spiral example

curl -X POST "http://127.0.0.1:8000/predict/spiral" \
   -F "file=@test/spiral.png"

Python example

import requests

url = "http://127.0.0.1:8000/predict/wave"

with open("test/wave.png", "rb") as f:
      files = {"file": f}
      response = requests.post(url, files=files)

print(response.json())

---

Deployment

Docker

The repository contains a Dockerfile that:

• installs system dependencies required by OpenCV
• installs the Python dependencies
• runs the API on port 7860

Hugging Face Spaces

The repository is set up for deployment as a Docker Space on Hugging Face.

Deployment flow:

1. Push changes to the main branch
2. GitHub Actions runs the workflow in deploy.yml
3. The workflow pushes the repository to the Hugging Face Space repository
4. Hugging Face rebuilds and redeploys the Space

Target Hugging Face repository:

https://huggingface.co/spaces/xplorers/MIS_API

Required secret

The GitHub Actions workflow needs this secret:

• HF_TOKEN - Hugging Face write token

Make sure the token has permission to push to the target Space.

---

Important Files

main.py

Contains:

• the FastAPI app
• startup model loading
• CORS configuration
• image prediction endpoints

services/predictor.py

Contains:

• Hugging Face model download logic
• image preprocessing
• wave and spiral prediction functions
• severity interpretation logic

Dockerfile

Contains:

• Python base image
• OpenCV system libraries
• application startup command

.github/workflows/deploy.yml

Contains:

• GitHub Actions deployment logic
• authenticated push to Hugging Face Spaces

---

License and Usage

No explicit license file is currently included in the repository.

If you plan to publish or share the project publicly, add a license file and review the Hugging Face model and deployment permissions.