Upload 5 files

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.10-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    libgl1 \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /app/requirements.txt
+RUN python -m pip install --upgrade pip && \
+    python -m pip install -r /app/requirements.txt
+
+COPY . /app
+
+EXPOSE 7860
+
+CMD ["sh", "-c", "python web_demo/app.py --host 0.0.0.0 --port ${PORT:-7860}"]

LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) [2025]
+
+## Licensing Notice
+
+This repository includes source code and tools released under the [MIT License](LICENSE).
+
+However, **pretrained models and model configurations** provided in this repository 
+are the intellectual property of their respective authors and are licensed under the 
+terms specified by the **original papers**. Please refer to the respective publications 
+and their repositories for license details before using these models in your work.
+We do **not** claim ownership or rights to redistribute third-party models unless explicitly 
+stated.
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+copies of the Software, and to permit persons to whom the Software is  
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in  
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN  
+THE SOFTWARE.

README.md

@@ -1,12 +1,248 @@
----
-title: Rppgdemo
-emoji: 🐠
-colorFrom: green
-colorTo: blue
-sdk: docker
-pinned: false
-license: apache-2.0
-short_description: a short demo
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Open-rppg
+
+Open-rppg is a comprehensive Python toolbox designed for Remote Photoplethysmography (rPPG) inference. It provides a unified interface for state-of-the-art deep learning models, enabling physiological signal measurement (such as heart rate and heart rate variability) from facial videos. The toolkit supports both offline video processing and low-latency real-time inference using JAX. 
+
+> API document [https://kegangwangccnu.github.io/open-rppg/](https://kegangwangccnu.github.io/open-rppg/)
+
+<img width="948" height="250" alt="image" src="https://github.com/user-attachments/assets/5c945368-67bf-4ccb-8822-fa359a787cdd" />
+
+## Installation
+
+This package requires Python 3.9 through 3.13.
+
+To install the standard version:
+
+```bash
+pip install open-rppg
+```
+
+To enable GPU acceleration (Linux/CUDA), install the CUDA-supported version of JAX:
+
+```bash
+pip install jax[cuda]
+```
+
+## Quick Start
+
+The core interface is managed through the `Model` class. By default, it initializes a robust, general-purpose model (`FacePhys.rlap`).
+
+```python
+import rppg
+
+# Initialize the model
+model = rppg.Model()
+
+# Process a video file
+results = model.process_video("path/to/video.mkv")
+
+# Display the heart rate
+print(f"Estimated Heart Rate: {results['hr']} BPM")
+```
+
+## Usage Guide
+
+### 1. Offline Video Processing
+To analyze a pre-recorded video file, use the `process_video` method. This method handles frame extraction, face detection, and signal inference automatically.
+
+```python
+results = model.process_video("subject_test.mkv")
+```
+
+**Output Structure:**
+The returned dictionary contains the following keys:
+
+* **hr**: Heart Rate estimated via the frequency domain (FFT).
+* **SQI**: Signal Quality Index (0.0 to 1.0), indicating the reliability of the measurement.
+* **latency**: Inference latency (primarily relevant for real-time streams).
+* **hrv**: A dictionary of Heart Rate Variability metrics calculated in the time domain:
+    * *bpm*: Heart rate derived from peak detection.
+    * *ibi*: Inter-Beat Interval (milliseconds).
+    * *sdnn*: Standard deviation of NN intervals.
+    * *rmssd*: Root mean square of successive differences.
+    * *pnn50*: Proportion of NN50 > 50ms.
+    * *LF/HF*: Ratio of Low Frequency to High Frequency power.
+    * *breathingrate*: Estimated respiration rate.
+
+### 2. Real-Time Inference
+Open-rppg includes a threaded pipeline optimized for real-time webcam inference. Use the `video_capture` context manager to handle the video stream safely.
+
+```python
+import rppg
+import time
+import cv2
+
+model = rppg.Model()
+# Open the default camera (index 0)
+with model.video_capture(0):
+    last_process_time = 0
+    current_hr = None
+    
+    # Iterate through the preview generator (this is the main loop)
+    for frame, box in model.preview:
+        frame = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
+        
+        # 1. Calculate HR every 1 second to avoid lag
+        now = time.time()
+        if now - last_process_time > 1.0:
+            result = model.hr(start=-10)
+            if result and result['hr']:
+                current_hr = result['hr']
+                print(f"Real-time HR: {current_hr:.1f} BPM")
+            last_process_time = now
+            
+        # 2. Visualization
+        if box is not None:
+            # box format: [[row_min, row_max], [col_min, col_max]]
+            y1, y2 = box[0]
+            x1, x2 = box[1]
+            cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 255, 0), 2)
+            
+            # Display HR on the frame if available
+            if current_hr is not None:
+                cv2.putText(frame, f"HR: {current_hr:.1f}", (x1, y1 - 10), 
+                           cv2.FONT_HERSHEY_SIMPLEX, 0.9, (0, 255, 0), 2)
+        
+        cv2.imshow("rPPG Monitor", frame)
+        
+        if cv2.waitKey(1) & 0xFF == ord('q'):
+            break
+```
+
+## Advanced API
+
+### Retrieving Raw Signals
+You can extract the underlying Blood Volume Pulse (BVP) waveform for further analysis or plotting.
+
+```python
+# Retrieve the full BVP signal and corresponding timestamps
+bvp, timestamps = model.bvp()
+
+# Retrieve the raw, unfiltered BVP signal
+raw_bvp, timestamps = model.bvp(raw=True)
+```
+
+### Time Slicing
+The toolbox allows specific time windows to be analyzed within the buffer.
+
+```python
+# Get signal from t=10s to t=20s
+bvp_slice, ts_slice = model.bvp(start=10, end=20)
+
+# Get metrics for the last 15 seconds
+metrics = model.hr(start=-15)
+```
+
+### Tensor Inputs
+For integration into existing pipelines where frames are already loaded as memory arrays, use the tensor processing methods.
+
+* **Input Format:** `uint8` array with shape `(Frames, Height, Width, 3)`.
+
+```python
+import numpy as np
+
+# tensor shape: (T, H, W, 3)
+video_tensor = np.zeros((300, 480, 640, 3), dtype='uint8') # 480p video
+
+result = model.process_video_tensor(video_tensor, fps=30.0)
+
+faces_tensor = np.zeros((300, 128, 128, 3), dtype='uint8') # face array
+
+result = model.process_faces_tensor(faces_tensor, fps=30.0)
+
+```
+
+### Model Selection
+You can specify different architectures during initialization. The models are categorized by architecture and training configuration (`rlap` or `pure`).
+
+```python
+# Example: Initialize the PhysMamba model
+model = rppg.Model('PhysMamba.pure')
+```
+
+## Model Zoo
+
+The following architectures are supported. 
+
+| Model Name | Description | Reference |
+| :--- | :--- | :--- |
+| **ME-chunk** | State-space model rPPG (chunk inference) | arXiv 2025 |
+| **ME-flow** | State-space model rPPG (low-latency flow) | arXiv 2025 |
+| **PhysMamba** | Dual-branch Mamba architecture | CCBR 2024 |
+| **RhythmMamba**| Frequency-domain constrained Mamba | AAAI 2025 |
+| **PhysFormer** | Temporal Difference Transformer | CVPR 2022 |
+| **TSCAN** | Temporal Shift Convolutional Attention Network | NeurIPS 2020 |
+| **EfficientPhys**| Self-attention variant of TSCAN | WACV 2023 |
+| **PhysNet** | 3D Convolutional Encoder-Decoder | BMVC 2019 |
+| **FacePhys** | Optimized state-space model | - |
+
+*Note: Suffixes `.rlap` and `.pure` indicate different training protocols/weights.*
+
+## Licensing
+
+The source code and tools in this repository are released under the **MIT License**.
+
+**Important:** Pretrained models and model configurations provided in this repository are derived from academic research. They are the intellectual property of their respective authors and are subject to the license terms specified in their original publications. Please refer to the citations below for details.
+
+## Citation
+
+If you use this toolkit or the included models in your research, please cite the relevant papers:
+
+```bibtex
+@article{yu2019remote,
+  title={Remote photoplethysmograph signal measurement from facial videos using spatio-temporal networks},
+  author={Yu, Zitong and Li, Xiaobai and Zhao, Guoying},
+  journal={arXiv preprint arXiv:1905.02419},
+  year={2019}
+}
+
+@article{liu2020multi,
+  title={Multi-task temporal shift attention networks for on-device contactless vitals measurement},
+  author={Liu, Xin and Fromm, Josh and Patel, Shwetak and McDuff, Daniel},
+  journal={Advances in Neural Information Processing Systems},
+  volume={33},
+  pages={19400--19411},
+  year={2020}
+}
+
+@inproceedings{liu2023efficientphys,
+  title={Efficientphys: Enabling simple, fast and accurate camera-based cardiac measurement},
+  author={Liu, Xin and Hill, Brian and Jiang, Ziheng and Patel, Shwetak and McDuff, Daniel},
+  booktitle={Proceedings of the IEEE/CVF winter conference on applications of computer vision},
+  pages={5008--5017},
+  year={2023}
+}
+
+@inproceedings{yu2022physformer,
+  title={Physformer: Facial video-based physiological measurement with temporal difference transformer},
+  author={Yu, Zitong and Shen, Yuming and Shi, Jingang and Zhao, Hengshuang and Torr, Philip HS and Zhao, Guoying},
+  booktitle={Proceedings of the IEEE/CVF conference on computer vision and pattern recognition},
+  pages={4186--4196},
+  year={2022}
+}
+
+@inproceedings{luo2024physmamba,
+  title={PhysMamba: Efficient Remote Physiological Measurement with SlowFast Temporal Difference Mamba},
+  author={Luo, Chaoqi and Xie, Yiping and Yu, Zitong},
+  booktitle={Chinese Conference on Biometric Recognition},
+  pages={248--259},
+  year={2024},
+  organization={Springer}
+}
+
+@inproceedings{zou2025rhythmmamba,
+  title={RhythmMamba: Fast, Lightweight, and Accurate Remote Physiological Measurement},
+  author={Zou, Bochao and Guo, Zizheng and Hu, Xiaocheng and Ma, Huimin},
+  booktitle={Proceedings of the AAAI Conference on Artificial Intelligence},
+  volume={39},
+  number={10},
+  pages={11077--11085},
+  year={2025}
+}
+
+@article{wang2025memory,
+  title={Memory-efficient Low-latency Remote Photoplethysmography through Temporal-Spatial State Space Duality},
+  author={Wang, Kegang and Tang, Jiankai and Fan, Yuxuan and Ji, Jiatong and Shi, Yuanchun and Wang, Yuntao},
+  journal={arXiv preprint arXiv:2504.01774},
+  year={2025}
+}
+```

dockerignore

@@ -0,0 +1,12 @@
+.git
+.github
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.DS_Store
+.pytest_cache
+.mypy_cache
+.venv
+venv
+node_modules

requirements.txt

@@ -0,0 +1,11 @@
+flask>=3.0
+numpy>=1.24
+heartpy>=1.2
+jax>=0.4.26
+keras>=3.5.0
+onnxruntime>=1.8
+opencv_python>=4.5.5.64
+scipy>=1.8
+einops>=0.8 
+av>=13 
+#matplotlib<=3.9