🚑️ PiGear: Modify PiGear class behavior when `enforce_legacy_picame…

…ra=True` on unsupported system

- ⚡️ Instead of silently disabling `picamera2` API directly, PiGear now raises an error if `picamera` is unavailable or unsupported
- 🥅 Prevented incorrect initialization of `PiGear` class on unsupported 64-bit OS systems.

Docs:
- 📝 Add failure warning in various docs about `picamera` incompatibility on 64-bit OS

docs/gears/netgear/advanced/bidirectional_mode.md

@@ -374,6 +374,8 @@ Now, Open the terminal on another Server System _(a Raspberry Pi with Camera Mod
         
         !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../../gears/pigear/params) user-defined optional parameter boolean attribute."
 
     ```python linenums="1" hl_lines="25-30"

docs/gears/netgear/advanced/multi_client.md

@@ -591,6 +591,8 @@ Now, Open the terminal on a Server System _(with a webcam connected to it at ind
         
         !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../../gears/pigear/params) user-defined optional parameter boolean attribute."
 
     ```python linenums="1" hl_lines="47-60"
@@ -913,6 +915,8 @@ Now, Open the terminal on a Server System _(with a webcam connected to it at ind
         
         !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../../gears/pigear/params) user-defined optional parameter boolean attribute."
 
     ```python linenums="1" hl_lines="19 48-64"

docs/gears/netgear/advanced/multi_server.md

@@ -737,6 +737,8 @@ Finally, Open the terminal on another Server System _(this time a Raspberry Pi w
         
         !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../../gears/pigear/params) user-defined optional parameter boolean attribute."
 
     ```python linenums="1" hl_lines="50"
@@ -1075,6 +1077,8 @@ Finally, Open the terminal on another Server System _(this time a Raspberry Pi w
         
         !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../../gears/pigear/params) user-defined optional parameter boolean attribute."
 
     ```python linenums="1" hl_lines="20 46-54"

docs/gears/netgear_async/advanced/bidirectional_mode.md

@@ -409,6 +409,8 @@ Now, Open the terminal on another Server System _(a Raspberry Pi with Camera Mod
         
         !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../../gears/pigear/params) user-defined optional parameter boolean attribute."
 
 

docs/gears/pigear/usage.md

@@ -41,6 +41,8 @@ Following is the bare-minimum code you need to get started with PiGear API:
 
     !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+    !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
     !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../params/#b-user-defined-parameters) user-defined optional parameter boolean attribute."
 
 ??? danger "Disabling common `libcamera` API messages in silent mode."
@@ -204,6 +206,8 @@ stream.stop()
 
         It is advised to enable logging(`logging=True`) to see which backend is being used.
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../params/#b-user-defined-parameters) user-defined optional parameter boolean attribute."
 
     PiGear also supports almost every parameter available within [`picamera`](https://picamera.readthedocs.io/en/release-1.13/api_camera.html) python library. These parameters can be easily applied to the source stream in PiGear API through its [`options`](../params/#options) dictionary parameter by formatting them as its attributes. The complete usage example is as follows:
@@ -404,6 +408,8 @@ PiGear can be easily used with WriteGear API directly without any compatibility
 
         It is advised to enable logging(`logging=True`) to see which backend is being used.
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../params/#b-user-defined-parameters) user-defined optional parameter boolean attribute."
 
     ```python linenums="1"

docs/gears/videogear/usage.md

@@ -82,6 +82,8 @@ Following is the bare-minimum code you need to access PiGear API with VideoGear:
 
     !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+    !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
     !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../params) user-defined optional parameter boolean attribute."
 
 !!! warning "Make sure to [complete Raspberry Pi Camera Hardware-specific settings](https://www.raspberrypi.com/documentation/accessories/camera.html#installing-a-raspberry-pi-camera) prior using this API, otherwise nothing will work."
@@ -296,6 +298,8 @@ The usage example of VideoGear API with Variable Camera Properties is as follows
         
         !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../params) user-defined optional parameter boolean attribute."
 
     ```python linenums="1" hl_lines="8-13"

docs/help/pigear_ex.md

@@ -215,7 +215,7 @@ limitations under the License.
 
     # formulate initial configurational parameters
     # set brightness to -0.5 (dark)
-    options = "controls": {"Brightness": -0.5}
+    options = {"controls": {"Brightness": -0.5}}
 
     # open pi video stream with these parameters
     stream = PiGear(logging=True, **options).start() 
@@ -262,6 +262,8 @@ limitations under the License.
 
         It is advised to enable logging(`logging=True`) to see which backend is being used.
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../params/#options) optional parameter boolean attribute."
 
     In this example we will set initial Camera Module's `brightness` value `80` _(brighter)_, and will change it `30` _(darker)_ when ++"Z"++ key is pressed at runtime:
@@ -348,23 +350,28 @@ limitations under the License.
 
     !!! info "The PiGear API can accurately differentiate between USB and Raspberry Pi camera modules by utilizing the camera's metadata."
 
-    In this example, we will select the Camera Module connected at index `1` on the Raspberry Pi as the primary source for extracting frames in PiGear API:
+    In this example, we will select the USB Camera connected at index `1` on the Raspberry Pi as the primary source for extracting frames in PiGear API:
+
+    ??? failure "Limited support for USB Cameras"
+
+        This example also works with USB Cameras, However:
 
-    !!! alert "This example assumes a Camera Module is connected at index `1`, and some other camera connected at index `0` on your Raspberry Pi."
+        - Users should assume that features such as: **Camera controls** (`"controls"`), **Transformations** (`"transform"`), **Queue** (`"queue"`) , and **Buffer Count** (`"buffer_count"`) that are supported on Raspberry Pi cameras, and so forth, are not available on USB Cameras. 
+        - Hot-plugging of USB cameras is also **NOT** supported - PiGear API should be completely shut down and restarted when cameras are added or removed.
 
-    ```python linenums="1" hl_lines="19"
+    !!! alert "This example assumes a USB Camera is connected at index `1`, and some other camera connected at index `0` on your Raspberry Pi."
+
+    ```python linenums="1" hl_lines="15"
     # import required libraries
     from vidgear.gears import PiGear
     from libcamera import Transform
     import cv2
 
     # formulate various Picamera2 API 
-    # configurational parameters
+    # configurational parameters for USB camera
     options = {
-        "queue": True,
-        "buffer_count": 4,
-        "controls": {"Brightness": 0.5, "ExposureValue": 2.0},
-        "transform": Transform(hflip=1),
+        "sensor": {"output_size": (480, 320)},  # will override `resolution`
+        "format": "RGB888" # BGR format for this example
         "auto_align_output_config": True,  # auto-align camera configuration
     }
 
@@ -407,6 +414,8 @@ limitations under the License.
 
         It is advised to enable logging(`logging=True`) to see which backend is being used.
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../params/#options) optional parameter boolean attribute."
 
     In this example, we will select the Camera Module connected at index `1` on the Raspberry Pi as the primary source for extracting frames in PiGear API:

docs/help/streamgear_ex.md

@@ -108,6 +108,8 @@ In this example, we will be Live-Streaming video-frames from Raspberry Pi _(with
             
             !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+            !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
             !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../params) user-defined optional parameter boolean attribute."
 
         ```python linenums="1"
@@ -242,6 +244,8 @@ In this example, we will be Live-Streaming video-frames from Raspberry Pi _(with
             
             !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+            !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
             !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../params) user-defined optional parameter boolean attribute."
 
         ```python linenums="1"

docs/help/webgear_ex.md

@@ -77,6 +77,8 @@ Here's a bare-minimum example of using WebGear API with the Raspberry Pi camera
         
         !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../../gears/pigear/params) user-defined optional parameter boolean attribute."
 
     ```python linenums="1" hl_lines="21"

docs/help/webgear_rtc_ex.md

@@ -74,6 +74,8 @@ Here's a bare-minimum example of using WebGear_RTC API with the Raspberry Pi cam
         
         !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
+        !!! failure "The `picamera` library is built on the legacy camera stack that is NOT _(and never has been)_ supported on 64-bit OS builds."
+
         !!! note "You could also enforce the legacy picamera API backend in PiGear by using the [`enforce_legacy_picamera`](../../gears/pigear/params) user-defined optional parameter boolean attribute."
 
     ```python linenums="1" hl_lines="18"

vidgear/gears/pigear.py

@@ -151,12 +151,14 @@ def __init__(
                 logger.critical(
                     "Enforcing legacy picamera API for this run. picamera2 API access will be disabled!"
                 )
+                # disable picamera2
+                picamera2 = None
             else:
-                logger.warning(
-                    "`picamera` is unavailable on this system, `enforce_legacy_picamera` will be discarded!"
+                # raise error otherwise
+                logger.error(
+                    "`picamera` is unavailable or unsupported on this system, `enforce_legacy_picamera` will be discarded!"
                 )
-            # disable picamera2
-            picamera2 = None
+                import_dependency_safe("picamera")
 
         if picamera2:
             # handle logging