| --- |
| 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](main.py) - FastAPI application entry point and API routes |
| - [services/predictor.py](services/predictor.py) - model loading, preprocessing, and prediction logic |
| - [services/**init**.py](services/__init__.py) - package initializer |
| - [requirements.txt](requirements.txt) - Python dependencies |
| - [Dockerfile](Dockerfile) - container configuration for deployment |
| - [.github/workflows/deploy.yml](.github/workflows/deploy.yml) - GitHub Actions workflow for deployment to Hugging Face |
| - [test/](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: |
|
|
| ```json |
| { |
| "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 |
|
|
| ```json |
| { |
| "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](services/predictor.py). |
|
|
| --- |
|
|
| ## Local Setup |
|
|
| ### 1. Create a virtual environment |
|
|
| ```bash |
| python -m venv venv |
| source venv/bin/activate |
| ``` |
|
|
| ### 2. Install dependencies |
|
|
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| If needed, also install the runtime packages used by the API: |
|
|
| ```bash |
| pip install fastapi uvicorn python-multipart |
| ``` |
|
|
| ### 3. Run the server |
|
|
| ```bash |
| uvicorn main:app --reload |
| ``` |
|
|
| ### 4. Open the documentation |
|
|
| Visit: |
|
|
| ```text |
| http://127.0.0.1:8000/docs |
| ``` |
|
|
| This opens the interactive Swagger UI for testing the API. |
|
|
| --- |
|
|
| ## Example Requests |
|
|
| ### cURL example |
|
|
| ```bash |
| curl -X POST "http://127.0.0.1:8000/predict/wave" \ |
| -F "file=@test/wave.png" |
| ``` |
|
|
| ### Spiral example |
|
|
| ```bash |
| curl -X POST "http://127.0.0.1:8000/predict/spiral" \ |
| -F "file=@test/spiral.png" |
| ``` |
|
|
| ### Python example |
|
|
| ```python |
| 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](.github/workflows/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](main.py) |
|
|
| Contains: |
|
|
| - the FastAPI app |
| - startup model loading |
| - CORS configuration |
| - image prediction endpoints |
|
|
| ### [services/predictor.py](services/predictor.py) |
|
|
| Contains: |
|
|
| - Hugging Face model download logic |
| - image preprocessing |
| - wave and spiral prediction functions |
| - severity interpretation logic |
|
|
| ### [Dockerfile](Dockerfile) |
|
|
| Contains: |
|
|
| - Python base image |
| - OpenCV system libraries |
| - application startup command |
|
|
| ### [.github/workflows/deploy.yml](.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. |
|
|
