🎉 feat(PiGear): Added official support for new Picamera2 API (Fixes #342)

.github/workflows/deploy_docs.yml

@@ -47,7 +47,9 @@ jobs:
         if: success()
       - name: install_dependencies
         run: |
-          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy          
+          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin          
+          pip install -U mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy
+          pip install -U mkdocs-git-authors-plugin
           pip install jinja2==3.0.*
         if: success()
       - name: git configure
@@ -88,7 +90,9 @@ jobs:
         if: success()
       - name: install_dependencies
         run: |
-          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy
+          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin          
+          pip install -U mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy
+          pip install -U mkdocs-git-authors-plugin          
           pip install jinja2==3.0.*
         if: success()
       - name: git configure
@@ -131,7 +135,9 @@ jobs:
         if: success()
       - name: install_dependencies
         run: |
-          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy          
+          pip install -U mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin          
+          pip install -U mkdocs-exclude mike mkdocstrings mkdocstrings-python-legacy
+          pip install -U mkdocs-git-authors-plugin          
           pip install jinja2==3.0.*
         if: success()
       - name: git configure

.gitignore

@@ -7,6 +7,7 @@ venv
 Pipfile.lock
 env3.*
 env
+.cache
 .coverage
 coverage.xml
 .netlify

README.md

@@ -39,7 +39,7 @@ limitations under the License.
 
  
 
-VidGear is a **High-Performance Video Processing Python Library** that provides an easy-to-use, highly extensible, thoroughly optimised **Multi-Threaded + Asyncio API Framework** on top of many state-of-the-art specialized libraries like _[OpenCV][opencv], [FFmpeg][ffmpeg], [ZeroMQ][zmq], [picamera][picamera], [starlette][starlette], [yt_dlp][yt_dlp], [pyscreenshot][pyscreenshot], [dxcam][dxcam], [aiortc][aiortc] and [python-mss][mss]_ serving at its backend, and enable us to flexibly exploit their internal parameters and methods, while silently delivering **robust error-handling and real-time performance 🔥**
+VidGear is a **High-Performance Video Processing Python Library** that provides an easy-to-use, highly extensible, thoroughly optimised **Multi-Threaded + Asyncio API Framework** on top of many state-of-the-art specialized libraries like _[OpenCV][opencv], [FFmpeg][ffmpeg], [ZeroMQ][zmq], [picamera2][picamera2], [starlette][starlette], [yt_dlp][yt_dlp], [pyscreenshot][pyscreenshot], [dxcam][dxcam], [aiortc][aiortc] and [python-mss][mss]_ serving at its backend, and enable us to flexibly exploit their internal parameters and methods, while silently delivering **robust error-handling and real-time performance 🔥**
 
 VidGear primarily focuses on simplicity, and thereby lets programmers and software developers to easily integrate and perform Complex Video Processing Tasks, in just a few lines of code.
 
@@ -122,7 +122,7 @@ Each API is designed exclusively to handle/control/process different data-specif
 **A. Video-Capture Gears:**
 
 - [**CamGear:**](#camgear) Multi-Threaded API targeting various IP-USB-Cameras/Network-Streams/Streaming-Sites-URLs.
-- [**PiGear:**](#pigear) Multi-Threaded API targeting various Raspberry-Pi Camera Modules.
+- [**PiGear:**](#pigear) Multi-Threaded API targeting various Camera Modules and _(limited)_ USB cameras on Raspberry Pis :grapes:.
 - [**ScreenGear:**](#screengear) High-performance API targeting rapid Screencasting Capabilities.
 - [**VideoGear:**](#videogear) Common Video-Capture API with internal [Video Stabilizer](https://abhitronix.github.io/vidgear/latest/gears/stabilizer/overview/) wrapper.
 
@@ -265,27 +265,35 @@ stream_stab.stop()
   <img src="https://abhitronix.github.io/vidgear/latest/assets/images/picam2.webp" alt="PiGear" width="50%" />
 </p>
 
-> _PiGear is similar to CamGear but made to support various Raspberry Pi Camera Modules _(such as [OmniVision OV5647 Camera Module][ov5647-picam] and [Sony IMX219 Camera Module][imx219-picam])_._
+> _PiGear is a specialized API similar to the [CamGear API](#camgear) but optimized for **Raspberry Pi :grapes: Boards**, offering comprehensive **support for camera modules** _(e.g., [OmniVision OV5647 Camera Module][ov5647-picam], [Sony IMX219 Camera Module][imx219-picam])_, along with **limited compatibility for USB cameras**._
 
-PiGear provides a flexible multi-threaded framework around complete [picamera](https://picamera.readthedocs.io/en/release-1.13/index.html) python library, and provide us the ability to exploit almost all of its parameters like `brightness, saturation, sensor_mode, iso, exposure, etc.` effortlessly. Furthermore, PiGear also supports multiple camera modules, such as in the case of Raspberry-Pi Compute Module IO boards.
+PiGear implements a seamless and robust wrapper around the [picamera2][picamera2] python library, simplifying integration with minimal code changes and ensuring a smooth transition for developers already familiar with the Picamera2 API. PiGear leverages the `libcamera` API under the hood with multi-threading, providing high-performance :fire:, enhanced control and functionality for Raspberry Pi camera modules. 
+
+PiGear handles common configuration parameters and non-standard settings for various camera types, simplifying the integration process. PiGear currently supports PiCamera2 API parameters such as `sensor`, `controls`, `transform`, and `format` etc., with internal type and sanity checks for robust performance.
+
+While primarily focused on Raspberry Pi camera modules, PiGear also provides **basic functionality for USB webcams** only with Picamera2 API, along with the ability to accurately differentiate between USB and Raspberry Pi cameras using metadata. 
+
+PiGear seamlessly switches to the legacy [picamera][picamera] library if the `picamera2` library is unavailable, ensuring seamless backward compatibility. For this, PiGear also provides a flexible multi-threaded framework around complete `picamera` API, allowing developers to effortlessly exploit a wide range of parameters, such as `brightness`, `saturation`, `sensor_mode`, `iso`, `exposure`, and more. 
+
+Furthermore, PiGear supports the use of multiple camera modules, including those found on Raspberry Pi Compute Module IO boards and USB cameras _(only with Picamera2 API)_.
 
 Best of all, PiGear contains **Threaded Internal Timer** - that silently keeps active track of any frozen-threads/hardware-failures and exit safely, if any does occur. That means that if you're running PiGear API in your script and someone accidentally pulls the Camera-Module cable out, instead of going into possible kernel panic, API will exit safely to save resources.
 
-**Code to open picamera stream with variable parameters in PiGear API:**
+**Code to open picamera2 stream with variable parameters in PiGear API:**
 
 ```python
 # import required libraries
 from vidgear.gears import PiGear
+from libcamera import Transform
 import cv2
 
-# add various Picamera tweak parameters to dictionary
+# formulate various Picamera2 API 
+# configurational parameters
 options = {
-    "hflip": True,
-    "exposure_mode": "auto",
-    "iso": 800,
-    "exposure_compensation": 15,
-    "awb_mode": "horizon",
-    "sensor_mode": 0,
+    "controls": {"Brightness": 0.5, "ExposureValue": 2.0},
+    "transform": Transform(hflip=1),
+    "sensor": {"output_size": (480, 320)},  # will override `resolution`
+    "format": "RGB888", # 8-bit BGR
 }
 
 # open pi video stream with defined parameters
@@ -316,7 +324,6 @@ cv2.destroyAllWindows()
 
 # safely close video stream
 stream.stop()
-
 ```
 
 ### PiGear API Guide:
@@ -650,7 +657,7 @@ It is something I am doing with my own free time. But so much more needs to be d
 
 Here is a Bibtex entry you can use to cite this project in a publication:
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8174694.svg)](https://doi.org/10.5281/zenodo.8174694)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8332548.svg)](https://doi.org/10.5281/zenodo.8332548)
 
 ```BibTeX
 @software{vidgear,
@@ -660,18 +667,19 @@ Here is a Bibtex entry you can use to cite this project in a publication:
                   Christian Hollinger and
                   Ian Max Andolina and
                   Vincent Boivin and
-                  enarche-ahn and
+                  Kyle Ahn and
                   freol35241 and
                   Benjamin Lowe and
                   Mickaël Schoentgen and
-                  Renaud Bouckenooghe},
-  title        = {abhiTronix/vidgear: VidGear v0.3.1},
-  month        = jul,
+                  Renaud Bouckenooghe and
+                  Ibtsam Ahmad},
+  title        = {abhiTronix/vidgear: VidGear Stable v0.3.2},
+  month        = sep,
   year         = 2023,
   publisher    = {Zenodo},
-  version      = {vidgear-0.3.1},
-  doi          = {10.5281/zenodo.8174694},
-  url          = {https://doi.org/10.5281/zenodo.8174694}
+  version      = {vidgear-0.3.2},
+  doi          = {10.5281/zenodo.8332548},
+  url          = {https://doi.org/10.5281/zenodo.8332548}
 }
 ```
 
@@ -807,5 +815,6 @@ External URLs
 [zmq-req-rep]: https://learning-0mq-with-pyzmq.readthedocs.io/en/latest/pyzmq/patterns/client_server.html
 [zmq-pub-sub]: https://learning-0mq-with-pyzmq.readthedocs.io/en/latest/pyzmq/patterns/pubsub.html
 [zmq-pull-push]: https://learning-0mq-with-pyzmq.readthedocs.io/en/latest/pyzmq/patterns/pushpull.html#push-pull
+[picamera2]:https://github.com/raspberrypi/picamera2
 [picamera-setting]: https://picamera.readthedocs.io/en/release-1.13/quickstart.html
 [webrtc]: https://webrtc.org/

azure-pipelines.yml

@@ -66,11 +66,11 @@ steps:
     displayName: "Prepare dataset"
 
   - script: |
-      python -m pip install --upgrade pip wheel
-      pip install --upgrade .[asyncio] six codecov yt_dlp httpx mpegdash paramiko m3u8 async-asgi-testclient
-      pip install --upgrade deffcode
-      pip install cryptography==38.0.4
-      pip install --upgrade pytest pytest-asyncio pytest-cov pytest-azurepipelines
+      python -m pip install -U pip wheel numpy
+      python -m pip install -U .[asyncio] 
+      python -m pip install -U six codecov httpx pytest pytest-asyncio pytest-cov yt_dlp mpegdash paramiko m3u8 async-asgi-testclient
+      python -m pip install -U deffcode
+      python -m pip install cryptography==38.0.4
     displayName: "Install pip dependencies"
 
   - script: |

codecov.yml

@@ -32,6 +32,7 @@ ignore:
   - "scripts"
   - "vidgear/gears/__init__.py" #trivial
   - "vidgear/gears/asyncio/__main__.py" #trivial
+  - "vidgear/gears/pigear.py" #HW limits
   - "setup.py"
   - "**/*.md"
   - "**/*.html"

docs/changelog.md

@@ -92,6 +92,9 @@ limitations under the License.
     * PR #375
     * PR #370
 
+??? new "New Contributors"
+    * @ibtsam3301
+
   
 
   
@@ -374,6 +377,10 @@ limitations under the License.
     * PR #350
     * PR #351
 
+??? new "New Contributors"
+    * @sueskind
+
+
   
 
   

docs/contribution.md

@@ -42,22 +42,22 @@ limitations under the License.
 
 ## Submission Contexts
 
-### Got a question or problem?
+### Got a question or problem? :material-lightbulb-question:
 
 For quick questions, please refrain from opening an issue, instead read our [FAQ & Troubleshooting](../help/get_help/#frequently-asked-questions) section or you can reach us on [Gitter](https://gitter.im/vidgear/community) community channel.
 
 
-### Found a typo?
+### Found a typo? :material-eraser:
 
 There's no need to contribute for some typos. Just reach us on [Gitter ➶](https://gitter.im/vidgear/community) community channel, We will correct them in (less than) no time. 
 
 
-### Found a bug?
+### Found a bug? :material-bug-outline: 
 
 If you encountered a bug, you can help us by [submitting an issue](../contribution/issue/) in our GitHub repository. Even better, you can submit a Pull Request(PR) with a fix, but make sure to read the [guidelines ➶](#submission-guidelines).
 
 
-### Request for a feature/improvement?
+### Request for a feature/improvement? :material-new-box: 
 
 ??? tip "Subscribe to Github Repository"
 

docs/gears.md

@@ -27,7 +27,7 @@ limitations under the License.
 
 ## Gears :octicons-gear-24:, What are these?
 
-VidGear is built on Standalone APIs - also known as **Gears**, each with some unique functionality. Each Gears is designed exclusively to handle/control/process different data-specific & device-specific video streams, network streams, and media encoders/decoders. 
+VidGear is built on Standalone APIs - also known as **Gears :fontawesome-solid-gears:**, each with some unique functionality. Each Gears is designed exclusively to handle/control/process different data-specific & device-specific video streams, network streams, and media encoders/decoders. 
 
 Gears allows users to work with an inherently optimized, easy-to-use, extensible, and exposed API Framework on top of many state-of-the-art libraries, while silently delivering robust error handling and unmatched real-time performance.
 
@@ -40,7 +40,7 @@ These Gears can be classified as follows:
 > **Basic Function:** Retrieves [`numpy.ndarray`](https://numpy.org/doc/1.18/reference/generated/numpy.ndarray.html#numpy-ndarray) frames from various sources.
 
 * [CamGear](camgear/overview/): Multi-Threaded API targeting various IP-USB-Cameras/Network-Streams/Streaming-Sites-URLs.
-* [PiGear](pigear/overview/): Multi-Threaded API targeting various Raspberry-Pi Camera Modules.
+* [PiGear](pigear/overview/): Multi-Threaded API targeting various Camera Modules and _(limited)_ USB cameras on Raspberry Pis :fontawesome-brands-raspberry-pi:.
 * [ScreenGear](screengear/overview/): High-performance API targeting rapid Screencasting Capabilities.
 * [VideoGear](videogear/overview/): Common Video-Capture API with internal [Video Stabilizer](stabilizer/overview/) wrapper. 
 

docs/gears/camgear/overview.md

@@ -46,23 +46,13 @@ CamGear internally implements [`yt_dlp`][yt_dlp] backend class for seamlessly pi
 
   
 
-## Importing
-
-You can import CamGear API in your program as follows:
-
-```python
-from vidgear.gears import CamGear
-```
-
- 
-
 ## Usage Examples
 
 <div>
 <a href="../usage/">See here 🚀</a>
 </div>
 
-!!! experiment "After going through CamGear Usage Examples, Checkout more of its advanced configurations [here ➶](../../../help/camgear_ex/)"
+!!! example "After going through CamGear Usage Examples, Checkout more of its advanced configurations [here ➶](../../../help/camgear_ex/)"
 
 ## Parameters
 

docs/gears/camgear/usage.md

@@ -20,7 +20,7 @@ limitations under the License.
 
 # CamGear API Usage Examples:
 
-!!! experiment "After going through following Usage Examples, Checkout more of its advanced configurations [here ➶](../../../help/camgear_ex/)"
+!!! example "After going through following Usage Examples, Checkout more of its advanced configurations [here ➶](../../../help/camgear_ex/)"
 
  
 
@@ -79,7 +79,7 @@ The complete usage example for Dailymotion and Twitch URLs are as follows:
 
     **Checkout [this FAQ ➶](../../../help/camgear_faqs/#how-to-compile-opencv-with-gstreamer-support) for compiling OpenCV with GStreamer support.**
 
-    !!! fail "Not all resolutions are supported with GStreamer Backend. See issue #244"
+    !!! failure "Not all resolutions are supported with GStreamer Backend. See issue #244"
 
 ???+ info "Exclusive CamGear Attributes for `yt_dlp` backend"
 
@@ -224,7 +224,7 @@ The complete usage example for Dailymotion and Twitch URLs are as follows:
 
 CamGear API also provides out-of-the-box support for pipelining live video-frames and metadata from **:fontawesome-brands-youtube: YouTube (Livestream + Normal) Videos**. 
 
-!!! fail "YouTube Playlists :material-youtube-subscription: are not supported yet."
+!!! failure "YouTube Playlists :material-youtube-subscription: are not supported yet."
 
 The complete usage example is as follows:
 
@@ -234,7 +234,7 @@ The complete usage example is as follows:
 
     **Checkout [this FAQ ➶](../../../help/camgear_faqs/#how-to-compile-opencv-with-gstreamer-support) for compiling OpenCV with GStreamer support.**
 
-    !!! fail "Not all resolutions are supported with GStreamer Backend. See issue #244"
+    !!! failure "Not all resolutions are supported with GStreamer Backend. See issue #244"
 
 
 ??? info "Exclusive CamGear Attributes for `yt_dlp` backend"
@@ -377,10 +377,10 @@ CamGear API also supports **Direct Colorspace Manipulation**, which is ideal for
 
 !!! info "A more detailed  information on colorspace manipulation can be found [here ➶](../../../bonus/colorspace_manipulation/)"
 
-In following example code, we will start with [**HSV**](https://en.wikipedia.org/wiki/HSL_and_HSV) as source colorspace, and then we will switch to [**GRAY**](https://en.wikipedia.org/wiki/Grayscale)  colorspace when `w` key is pressed, and then [**LAB**](https://en.wikipedia.org/wiki/CIELAB_color_space) colorspace when `e` key is pressed, finally default colorspace _(i.e. **BGR**)_ when `s` key is pressed. Also, quit when `q` key is pressed:
+In following example code, we will start with [**HSV**](https://en.wikipedia.org/wiki/HSL_and_HSV) as source colorspace, and then we will switch to [**GRAY**](https://en.wikipedia.org/wiki/Grayscale)  colorspace when ++"W"++ key is pressed, and then [**LAB**](https://en.wikipedia.org/wiki/CIELAB_color_space) colorspace when ++"E"++ key is pressed, finally default colorspace _(i.e. **BGR**)_ when ++"S"++ key is pressed. Also, quit when ++"Q"++ key is pressed:
 
 
-!!! fail "Any incorrect or None-type value, will immediately revert the colorspace to default i.e. `BGR`."
+!!! failure "Any incorrect or None-type value, will immediately revert the colorspace to default i.e. `BGR`."
 
 
 ```python hl_lines="7 30 34 38"

docs/gears/netgear/advanced/ssh_tunnel.md

@@ -73,7 +73,7 @@ SSH Tunnel Mode requires [`pexpect`](http://www.noah.org/wiki/pexpect) or [`para
 
 === "Pexpect"
 
-    !!! fail "`pexpect` is NOT compatible with Windows Machines."
+    !!! failure "`pexpect` is NOT compatible with Windows Machines."
 
     ```sh
     # install pexpect
@@ -91,7 +91,7 @@ For implementing SSH Tunneling Mode, NetGear API currently provide following exc
 
 * **`ssh_tunnel_mode`** (_string_) : This attribute activates SSH Tunneling Mode and assigns the `"<ssh-username>@<client-public-ip-address>:<tcp-forwarded-port>"` SSH URL for tunneling at Server end. Its usage is as follows:
 
-    !!! fail "On Server end, NetGear automatically validates if the `port` is open at specified Client's Public IP Address or not, and if it fails _(i.e. port is closed)_, NetGear will throw `AssertionError`!"
+    !!! failure "On Server end, NetGear automatically validates if the `port` is open at specified Client's Public IP Address or not, and if it fails _(i.e. port is closed)_, NetGear will throw `AssertionError`!"
 
     === "With Default Port"
 
@@ -230,7 +230,7 @@ Open a terminal on Client System _(A Regular PC where you want to display the in
     For more information on Forwarding Port in Popular Home Routers. See [this document ➶](https://www.noip.com/support/knowledgebase/general-port-forwarding-guide/)
 
 
-??? fail "Secsh channel X open FAILED: open failed: Administratively prohibited"
+??? failure "Secsh channel X open FAILED: open failed: Administratively prohibited"
 
     **Error:** This error means that installed OpenSSH is preventing connections to forwarded ports from outside your Client Machine. 
 

docs/gears/netgear/overview.md

@@ -125,16 +125,6 @@ In addition to the primary modes, NetGear API also offers application-specific E
 
  
 
-## Importing
-
-You can import NetGear API in your program as follows:
-
-```python
-from vidgear.gears import NetGear
-```
-
- 
-
 ## Usage Examples
 
 <div>