PhysioTracker

An Edge-Optimized Biomechanical Monitoring Framework for Automated Posture Correction & Physical Therapy.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
   • Core Features
2. Getting Started
   • Prerequisites
   • Installation
3. System Architecture
4. Roadmap
5. Contributing
6. License
7. Acknowledgments

About The Project

PhysioTracker is a full-stack tele-rehabilitation system designed to provide objective, real-time biomechanical feedback to patients in their homes. It bridges the gap in remote physical therapy by converting standard monocular webcams into high-precision, AI-powered skeletal trackers.

By pushing heavy Deep Learning inference entirely to the Edge (Client's Browser), the system achieves zero-latency classification while preserving patient privacy and massively reducing cloud computing costs.

(back to top)

Built With

• 
• 
• 
• 
• 
• 

(back to top)

Core Features

• Zero-Latency Edge AI Inference: Deep learning classification (BiLSTM) is executed entirely within the browser via TensorFlow.js (WebGL), eliminating backend network latency and massive RAM usage.
• Ambient Fall Detection: Optical, zero-wearable safety monitoring that calculates $dy/dt$ nose drop velocity combined with 33-point bounding box horizontal aspect ratio collapse to detect medical emergencies. Includes a 10-second therapist alert protocol.
• Adaptive Hysteresis-Based Form Tracking: Incorporates a 10-second mandatory calibration phase to calculate personal Range of Motion (ROM) baselines. Uses an Exponential Moving Average (EMA) and dual-threshold state machine to guarantee true repetition counts.
• Virtual Lower-Body Landmark Imputation: For close-up or seated views, the frontend dynamically imputes neutral standing leg coordinates scaled to the shoulders via bi-acromial measurement, keeping classification accuracy exceptionally high (>80%).
• Fatigue & Asymmetry Detection: Automatically monitors repetition velocity degradation (>30% slowdown) and tracks left-right joint angular variance (e.g., uneven elbow angles) to ensure biomechanical symmetry.
• Intelligent API Fallback: The frontend automatically detects remote backend timeouts and seamlessly falls back to a healthy local backend (http://localhost:5000) if available.

(back to top)

Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

For deployment on Render or local execution, Python 3.10 is required. Node.js is required for the frontend.

• npm

  npm install npm@latest -g

Installation

1. Clone the repo

   git clone https://github.com/NotArsal/Physiotherapy.git
   cd Physiotherapy

2. Backend Setup

   cd backend
   python -m venv .venv
   .venv\Scripts\activate   # (On Mac/Linux: source .venv/bin/activate)
   pip install -r requirements.txt
   python run.py

   The backend will start on http://localhost:5000. It acts as a lightweight, stateless MongoDB session logger.

3. Frontend Setup

   cd ../frontend
   npm install

4. Create a .env file in the frontend directory and enter your Firebase config:

   VITE_FIREBASE_API_KEY=your_api_key
   VITE_FIREBASE_AUTH_DOMAIN=your_domain
   VITE_FIREBASE_PROJECT_ID=your_project_id
   VITE_FIREBASE_STORAGE_BUCKET=your_bucket
   VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
   VITE_FIREBASE_APP_ID=your_app_id

5. Start the React development server

   npm start

(back to top)

System Architecture

Our repository layout cleanly separates the Edge AI React Engine from the Microservice Backend:

Physiotherapy-project-main/
|-- backend/
|   |-- app.py                  # Core Flask & MongoDB routes
|   |-- run.py                  # Entry point
|   `-- requirements.txt        # Stripped of heavy ML packages
|-- frontend/
|   |-- public/
|   |   `-- model/              # WebGL converted Edge AI Models
|   |-- src/
|   |   |-- components/         # React UI & Canvas Rendering
|   |   |-- services/           # TF.js & API integrations
|   |   `-- utils/              # Pose Extraction & Heuristics
|   |-- package.json
|   `-- tsconfig.json
|-- docs/                       # IEEE drafts, Patents, & Design Docs
`-- CHANGELOG_AUDIT.md          # History of audits & optimizations

For deeper insights into the mathematical methodology and patent claims, refer to the System Architecture Diagrams and Design Documentation.

(back to top)

Roadmap

• Integrate MediaPipe spatial extraction
• Develop BiLSTM Temporal Classifier
• Decouple backend ML and migrate to TensorFlow.js (Edge AI)
• Implement Wearable-Free Ambient Fall Detection
• Add MongoDB Atlas persistent cloud logging
• Add automated API and UI testing suites
• Build the final Therapist Dashboard to close the prescription loop

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Acknowledgments

• MediaPipe Pose
• TensorFlow.js
• Best-README-Template

(back to top)