Update README and docs for optional GPU defaults and CUDA helper

README.md

@@ -53,6 +53,8 @@ v.pose(model='body_25', device='cpu')
 - `pose()` downloads OpenPose weights on first use if they are missing.
 - In notebooks and other non-interactive runs, missing pose weights are downloaded automatically when possible.
 - If `device='gpu'` is requested but OpenCV CUDA support is unavailable, `pose()` falls back to CPU execution.
+- `flow.dense()`, `flow.sparse()`, and `blur_faces()` use CPU by default (`use_gpu=False`). Set `use_gpu=True` to opt into CUDA acceleration with automatic CPU fallback.
+- `get_cuda_device_count()` is available to quickly check whether OpenCV sees CUDA devices.
 - `blur_faces()` returns the generated result object consistently, including when `save_data=True`.
 
 ### Try Online

docs/README.md

@@ -55,6 +55,8 @@ v.pose(model='body_25', device='cpu')
 - `pose()` downloads OpenPose weights on first use if they are missing.
 - In notebooks and other non-interactive runs, missing pose weights are downloaded automatically when possible.
 - If `device='gpu'` is requested but OpenCV CUDA support is unavailable, `pose()` falls back to CPU execution.
+- `flow.dense()`, `flow.sparse()`, and `blur_faces()` use CPU by default (`use_gpu=False`). Set `use_gpu=True` to opt into CUDA acceleration with automatic CPU fallback.
+- `get_cuda_device_count()` is available to quickly check whether OpenCV sees CUDA devices.
 - `blur_faces()` returns the generated result object consistently, including when `save_data=True`.
 
 ### Try Online

docs/index.md

@@ -96,6 +96,8 @@ spectrogram = audio.spectrogram()
 - `pose()` downloads missing OpenPose model weights on demand.
 - In notebook and batch execution, pose weight downloads are attempted automatically instead of prompting for stdin.
 - If CUDA-backed OpenCV DNN support is unavailable, `pose(device='gpu')` falls back to CPU.
+- `flow.dense()`, `flow.sparse()`, and `blur_faces()` run on CPU by default (`use_gpu=False`); pass `use_gpu=True` to attempt CUDA acceleration with automatic CPU fallback.
+- `get_cuda_device_count()` can be used to check CUDA visibility from OpenCV.
 - `blur_faces()` returns the generated `MgVideo` result consistently, including when exporting face-coordinate data.
 
 ## Academic Background

docs/musicalgestures/_blurfaces.md

@@ -43,6 +43,7 @@ def mg_blurfaces(
     save_data=True,
     data_format='csv',
     color=(0, 0, 0),
+    use_gpu=False,
     target_name=None,
     overwrite=False,
 ):
@@ -67,6 +68,7 @@ Credits: `centerface.onnx` (original) and `centerface.py` are based on https://g
 - `save_data` *bool, optional* - Whether to save the scaled coordinates of the face mask (time (ms), x1, y1, x2, y2) for each frame to a file. Defaults to True.
 - `data_format` *str, optional* - Specifies format of blur_faces-data. Accepted values are 'csv', 'tsv' and 'txt'. For multiple output formats, use list, e.g. ['csv', 'txt']. Defaults to 'csv'.
 - `color` *tuple, optional* - Customized color of the rectangle boxes. Defaults to black (0, 0, 0).
+- `use_gpu` *bool, optional* - Whether to attempt GPU (CUDA) acceleration for face detection. Falls back to CPU automatically if CUDA is unavailable. Defaults to False.
 - `target_name` *str, optional* - Target output name. Defaults to None (which assumes that the input filename with the suffix "_blurred" should be used).
 - `overwrite` *bool, optional* - Whether to allow overwriting existing files or to automatically increment target filenames to avoid overwriting. Defaults to False.
 

docs/musicalgestures/_flow.md

@@ -42,6 +42,7 @@ def dense(
     angle_of_view=0,
     scaledown=1,
     skip_empty=False,
+    use_gpu=False,
     target_name=None,
     overwrite=False,
 ):
@@ -66,6 +67,7 @@ Renders a dense optical flow video of the input video file using `cv2.calcOptica
 - `angle_of_view` *int, optional* - angle of view of camera, for reporting flow in meters per second. Defaults to 0.
 - `scaledown` *int, optional* - factor to scaledown frame size of the video. Defaults to 1.
 - `skip_empty` *bool, optional* - If True, repeats previous frame in the output when encounters an empty frame. Defaults to False.
+- `use_gpu` *bool, optional* - Whether to attempt GPU (CUDA) acceleration using `cv2.cuda.FarnebackOpticalFlow`. When `True`, falls back to CPU automatically if CUDA is unavailable or the required OpenCV CUDA modules are not installed. When `False`, CPU processing is used unconditionally. Defaults to False.
 - `target_name` *str, optional* - Target output name for the video. Defaults to None (which assumes that the input filename with the suffix "_flow_dense" should be used).
 - `overwrite` *bool, optional* - Whether to allow overwriting existing files or to automatically increment target filenames to avoid overwriting. Defaults to False.
 
@@ -111,6 +113,7 @@ def sparse(
     of_win_size=(15, 15),
     of_max_level=2,
     of_criteria=(cv2.TERM_CRITERIA_EPS | cv2.TERM_CRITERIA_COUNT, 10, 0.03),
+    use_gpu=False,
     target_name=None,
     overwrite=False,
 ):
@@ -128,6 +131,7 @@ Renders a sparse optical flow video of the input video file using `cv2.calcOptic
 - `of_win_size` *tuple, optional* - Size of the search window at each pyramid level. Defaults to (15, 15).
 - `of_max_level` *int, optional* - 0-based maximal pyramid level number. If set to 0, pyramids are not used (single level), if set to 1, two levels are used, and so on. If pyramids are passed to input then the algorithm will use as many levels as pyramids have but no more than `maxLevel`. Defaults to 2.
 - `of_criteria` *tuple, optional* - Specifies the termination criteria of the iterative search algorithm (after the specified maximum number of iterations criteria.maxCount or when the search window moves by less than criteria.epsilon). Defaults to (cv2.TERM_CRITERIA_EPS | cv2.TERM_CRITERIA_COUNT, 10, 0.03).
+- `use_gpu` *bool, optional* - Whether to attempt GPU (CUDA) acceleration using `cv2.cuda.SparsePyrLKOpticalFlow`. When `True`, falls back to CPU automatically if CUDA is unavailable or the required OpenCV CUDA modules are not installed. When `False`, CPU processing is used unconditionally. Defaults to False.
 - `target_name` *str, optional* - Target output name for the video. Defaults to None (which assumes that the input filename with the suffix "_flow_sparse" should be used).
 - `overwrite` *bool, optional* - Whether to allow overwriting existing files or to automatically increment target filenames to avoid overwriting. Defaults to False.
 

docs/musicalgestures/_utils.md

@@ -41,6 +41,7 @@
     - [get_frame_planecount](#get_frame_planecount)
     - [get_framecount](#get_framecount)
     - [get_length](#get_length)
+    - [get_cuda_device_count](#get_cuda_device_count)
     - [get_widthheight](#get_widthheight)
     - [has_audio](#has_audio)
     - [in_colab](#in_colab)
@@ -727,6 +728,20 @@ Gets the length (in seconds) of a video using FFprobe.
 
 - `float` - The length of the input video file in seconds.
 
+## get_cuda_device_count
+
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1649)
+
+```python
+def get_cuda_device_count():
+```
+
+Returns the number of CUDA-capable GPU devices visible to OpenCV.
+
+#### Returns
+
+- `int` - Number of available CUDA devices, or 0 if the OpenCV CUDA module is unavailable or no devices are detected.
+
 ## get_widthheight
 
 [[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1117)
@@ -766,7 +781,7 @@ Checks if video has audio track using FFprobe.
 
 ## in_colab
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1619)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_utils.py#L1663)
 
 ```python
 def in_colab():

docs/quickstart.md

@@ -143,13 +143,31 @@ print(f"Descriptors: {descriptors}")
 ```python
 mv = mg.MgVideo(examples.dance)
 
-# Uses GPU if available, otherwise falls back to CPU automatically.
+# Explicit GPU request with CPU fallback when CUDA is unavailable.
 pose_video = mv.pose(model='mpi', device='gpu', downsampling_factor=2)
 pose_video.show(mode='notebook')
 ```
 
 On first use, pose estimation downloads the requested model weights if they are not already present.
 
+### 5. Optional GPU Acceleration
+
+```python
+mv = mg.MgVideo(examples.dance)
+
+# CPU is the default for flow and blur_faces.
+dense_cpu = mv.flow.dense()
+blur_cpu = mv.blur_faces()
+
+# Opt in to CUDA acceleration (falls back to CPU automatically).
+dense_gpu = mv.flow.dense(use_gpu=True)
+sparse_gpu = mv.flow.sparse(use_gpu=True)
+blur_gpu = mv.blur_faces(use_gpu=True)
+
+# Check CUDA availability reported by OpenCV.
+print(mg.get_cuda_device_count())
+```
+
 ## Working with Your Own Videos
 
 ### Supported Formats