From 6285688e5d2d4c924ca9f37095c39ab130004c63 Mon Sep 17 00:00:00 2001 From: abhiTronix Date: Mon, 20 May 2024 20:30:54 +0530 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=91=EF=B8=8F=20PiGear:=20Modify=20`PiG?= =?UTF-8?q?ear`=20class=20behavior=20when=20`enforce=5Flegacy=5Fpicamera?= =?UTF-8?q?=3DTrue`=20on=20unsupported=20system?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ⚡️ 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 --- .../netgear/advanced/bidirectional_mode.md | 2 ++ docs/gears/netgear/advanced/multi_client.md | 4 +++ docs/gears/netgear/advanced/multi_server.md | 4 +++ .../advanced/bidirectional_mode.md | 2 ++ docs/gears/pigear/usage.md | 6 +++++ docs/gears/videogear/usage.md | 4 +++ docs/help/pigear_ex.md | 27 ++++++++++++------- docs/help/streamgear_ex.md | 4 +++ docs/help/webgear_ex.md | 2 ++ docs/help/webgear_rtc_ex.md | 2 ++ vidgear/gears/pigear.py | 10 ++++--- 11 files changed, 54 insertions(+), 13 deletions(-) diff --git a/docs/gears/netgear/advanced/bidirectional_mode.md b/docs/gears/netgear/advanced/bidirectional_mode.md index 0deaef448..8cbcb56fd 100644 --- a/docs/gears/netgear/advanced/bidirectional_mode.md +++ b/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" diff --git a/docs/gears/netgear/advanced/multi_client.md b/docs/gears/netgear/advanced/multi_client.md index c41241bc9..101465cb6 100644 --- a/docs/gears/netgear/advanced/multi_client.md +++ b/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" diff --git a/docs/gears/netgear/advanced/multi_server.md b/docs/gears/netgear/advanced/multi_server.md index 205c31c57..c7ca3914a 100644 --- a/docs/gears/netgear/advanced/multi_server.md +++ b/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" diff --git a/docs/gears/netgear_async/advanced/bidirectional_mode.md b/docs/gears/netgear_async/advanced/bidirectional_mode.md index b5b38c961..0ba838c03 100644 --- a/docs/gears/netgear_async/advanced/bidirectional_mode.md +++ b/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." diff --git a/docs/gears/pigear/usage.md b/docs/gears/pigear/usage.md index 4cbae0e1e..1233b60b2 100644 --- a/docs/gears/pigear/usage.md +++ b/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" diff --git a/docs/gears/videogear/usage.md b/docs/gears/videogear/usage.md index 3ef8bcb32..6ddfb1616 100644 --- a/docs/gears/videogear/usage.md +++ b/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" diff --git a/docs/help/pigear_ex.md b/docs/help/pigear_ex.md index 74e6ac5ea..e7b15900c 100644 --- a/docs/help/pigear_ex.md +++ b/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: diff --git a/docs/help/streamgear_ex.md b/docs/help/streamgear_ex.md index e1fc6a81e..253b044c7 100644 --- a/docs/help/streamgear_ex.md +++ b/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" diff --git a/docs/help/webgear_ex.md b/docs/help/webgear_ex.md index 232af93bb..c3dc6c447 100644 --- a/docs/help/webgear_ex.md +++ b/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" diff --git a/docs/help/webgear_rtc_ex.md b/docs/help/webgear_rtc_ex.md index 55f1bb78e..5caa4b83b 100644 --- a/docs/help/webgear_rtc_ex.md +++ b/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" diff --git a/vidgear/gears/pigear.py b/vidgear/gears/pigear.py index 09e11056e..1a77b0230 100644 --- a/vidgear/gears/pigear.py +++ b/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