Update README

Rouast-Labs · Nov 14, 2024 · d36f665 · d36f665
1 parent 15e7130
commit d36f665
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -57,6 +57,7 @@ It can be configured using the following parameters:
 | Parameter               | Description                                                                        | Default            |
 |-------------------------|------------------------------------------------------------------------------------|--------------------|
 | method                  | Inference method. {`Method.VITALLENS`, `Method.POS`, `Method.CHROM` or `Method.G`} | `Method.VITALLENS` |
+| mode                    | Operation mode. {`Mode.BATCH` for indep. videos or `Mode.BURST` for video stream}  | `Mode.BATCH`       |
 | api_key                 | Usage key for the VitalLens API (required for `Method.VITALLENS`)                  | `None`             |
 | detect_faces            | `True` if faces need to be detected, otherwise `False`.                            | `True`             |
 | estimate_running_vitals | Set `True` to compute running vitals (e.g., `running_heart_rate`).                 | `True`             |
@@ -66,7 +67,8 @@ It can be configured using the following parameters:
 | export_dir              | The directory to which json files are written.                                     | `.`                |
 
 Once instantiated, `vitallens.VitalLens` can be called to estimate vitals.
-This can also be configured using the following parameters:
+In `Mode.BATCH` calls are assumed to be working on independent videos, whereas in `Mode.BURST` we expect the subsequent calls to pass the next frames of the same video (stream) as `np.ndarray`.
+Calls are configured using the following parameters:
 
 | Parameter           | Description                                                                           | Default |
 |---------------------|---------------------------------------------------------------------------------------|---------|
@@ -148,16 +150,33 @@ If the video is long enough and `estimate_running_vitals=True`, the results addi
 ]
 ```
 
+## Example: Live test with webcam in real-time
+
+Test `vitallens` in real-time with your webcam using the script `examples/live.py`.
+This uses `Mode.BURST` to update results continuously (approx. every 2 seconds for `Method.VITALLENS`).
+Some options are available:
+
+- `method`: Choose from [`VITALLENS`, `POS`, `G`, `CHROM`] (Default: `VITALLENS`)
+- `api_key`: Pass your API Key. Required if using `method=VITALLENS`.
+
+May need to install requirements first: `pip install opencv-python`
+
+```
+python examples/live.py --method=VITALLENS --api_key=YOUR_API_KEY
+```
+
 ### Example: Compare results with gold-standard labels using our example script
 
-There is an example Python script in `examples/test.py` which lets you run vitals estimation and plot the predictions against ground truth labels recorded with gold-standard medical equipment.
+There is an example Python script in `examples/test.py` which uses `Mode.BATCH` to run vitals estimation and plot the predictions against ground truth labels recorded with gold-standard medical equipment.
 Some options are available:
 
 - `method`: Choose from [`VITALLENS`, `POS`, `G`, `CHROM`] (Default: `VITALLENS`)
 - `video_path`: Path to video (Default: `examples/sample_video_1.mp4`)
 - `vitals_path`: Path to gold-standard vitals (Default: `examples/sample_vitals_1.csv`)
 - `api_key`: Pass your API Key. Required if using `method=VITALLENS`.
 
+May need to install requirements first: `pip install matplotlib pandas`
+
 For example, to reproduce the results from the banner image on the [VitalLens API Webpage](https://www.rouast.com/api/):
 
 ```

diff --git a/examples/README.md b/examples/README.md
@@ -1,19 +1,38 @@
-# Sample videos with ground truth labels
+# Example ways to test `vitallens`
+
+## Live test with webcam in real-time
+
+Test `vitallens` in real-time with your webcam using the script `live.py`.
+This uses `Mode.BURST` to update results continuously (approx. every 2 seconds for `Method.VITALLENS`).
+Some options are available:
+
+- `method`: Choose from [`VITALLENS`, `POS`, `G`, `CHROM`] (Default: `VITALLENS`)
+- `api_key`: Pass your API Key. Required if using `method=VITALLENS`.
+
+May need to install requirements first: `pip install opencv-python`
+
+```
+python examples/live.py --method=VITALLENS --api_key=YOUR_API_KEY
+```
+
+## Sample videos with ground truth labels
 
 In this folder, you can find two sample videos to test `vitallens` on.
 Each video has ground truth labels recorded with gold-standard medical equipment.
 
 - `sample_video_1.mp4` which has ground truth labels for PPG Waveform (`ppg`), ECG Waveform (`ecg`), Respiratory Waveform (`resp`), Blood Pressure (`sbp` and `dbp`), Blood Oxygen (`spo2`), Heart Rate (`hr_ecg` - derived from ECG and `hr_ppg` - derived from PPG), Heart Rate Variability (`hrv_sdnn_ecg`), and Respiratory Rate (`rr`).
 - `sample_video_2.mp4` which has ground truth labels for PPG Waveform (`ppg`). This sample is kindly provided by the [VitalVideos](http://vitalvideos.org) dataset.
 
-There is a test script in `test.py` which lets you run vitals estimation and plot the predictions against the ground truth labels.
+There is a test script in `test.py` which uses `Mode.BATCH` to run vitals estimation and plot the predictions against the ground truth labels. This uses `vitallens.Mode.BATCH` mode.
 Some options are available:
 
 - `method`: Choose from [`VITALLENS`, `POS`, `G`, `CHROM`] (Default: `VITALLENS`)
 - `video_path`: Path to video (Default: `examples/sample_video_1.mp4`)
 - `vitals_path`: Path to gold-standard vitals (Default: `examples/sample_vitals_1.csv`)
 - `api_key`: Pass your API Key. Required if using `method=VITALLENS`.
 
+May need to install requirements first: `pip install matplotlib pandas`
+
 For example, to reproduce the results from the banner image on the [VitalLens API Webpage](https://www.rouast.com/api/):
 
 ```