♻️ Docs: Refactored documentation

- 🧑‍💻 Refactored all APIs and bonus examples to use linenums and hl_lines - Makes it easier to highlight specific lines in code blocks - 📝 Updated remaining code examples for picamera2 and legacy picamera backends - 🐛 Replaced buggy kofi widget with a button image in `help.md` - 💄 Update announcement icon in `main.html` - 💄 Change system mode toggle icon and name in `mkdocs.yml`
abhiTronix · May 19, 2024 · 89b1c65 · 89b1c65
1 parent e40855f
commit 89b1c65
Show file tree

Hide file tree

Showing 38 changed files with 1,089 additions and 547 deletions.
diff --git a/docs/gears/camgear/usage.md b/docs/gears/camgear/usage.md
@@ -28,7 +28,7 @@ limitations under the License.
 
 Following is the bare-minimum code you need to get started with CamGear API:
 
-```python
+```python linenums="1"
 # import required libraries
 from vidgear.gears import CamGear
 import cv2
@@ -124,7 +124,8 @@ The complete usage example for Dailymotion and Twitch URLs are as follows:
     ```
 
 === "Dailymotion :fontawesome-brands-dailymotion:"
-    ```python  hl_lines="12-13"
+
+    ```python linenums="1"  hl_lines="12-13"
     # import required libraries
     from vidgear.gears import CamGear
     import cv2
@@ -172,7 +173,7 @@ The complete usage example for Dailymotion and Twitch URLs are as follows:
 
     !!! warning "If Twitch user is offline, CamGear will throw ValueError."
 
-    ```python  hl_lines="12-13"
+    ```python linenums="1"  hl_lines="12-13"
     # import required libraries
     from vidgear.gears import CamGear
     import cv2
@@ -274,7 +275,7 @@ The complete usage example is as follows:
     print(video_metadata["title"])
     ```
 
-```python hl_lines="8-9"
+```python linenums="1" hl_lines="8-9"
 # import required libraries
 from vidgear.gears import CamGear
 import cv2
@@ -325,7 +326,7 @@ The complete usage example is as follows:
 
 !!! tip "All the supported Source Tweak Parameters can be found [here ➶](../advanced/source_params/#source-tweak-parameters-for-camgear-api)"
 
-```python hl_lines="8-10"
+```python linenums="1" hl_lines="8-10"
 # import required libraries
 from vidgear.gears import CamGear
 import cv2
@@ -383,7 +384,7 @@ In following example code, we will start with [**HSV**](https://en.wikipedia.org
 !!! failure "Any incorrect or None-type value, will immediately revert the colorspace to default i.e. `BGR`."
 
 
-```python hl_lines="7 30 34 38"
+```python linenums="1" hl_lines="7 30 34 38"
 # import required libraries
 from vidgear.gears import CamGear
 import cv2

diff --git a/docs/gears/netgear/advanced/bidirectional_mode.md b/docs/gears/netgear/advanced/bidirectional_mode.md
@@ -96,7 +96,7 @@ Open your favorite terminal and execute the following python code:
 
 !!! tip "You can terminate both sides anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="9 31"
+```python linenums="1" hl_lines="9 31"
 # import required libraries
 from vidgear.gears import VideoGear
 from vidgear.gears import NetGear
@@ -151,7 +151,7 @@ Then open another terminal on the same system and execute the following python c
 
 !!! tip "You can terminate client anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="6 18"
+```python linenums="1" hl_lines="6 18"
 # import required libraries
 from vidgear.gears import NetGear
 import cv2
@@ -219,7 +219,7 @@ Open a terminal on Client System _(where you want to display the input frames re
 
 !!! tip "You can terminate client anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="11-17"
+```python linenums="1" hl_lines="11-17"
 # import required libraries
 from vidgear.gears import NetGear
 import cv2
@@ -290,73 +290,160 @@ Now, Open the terminal on another Server System _(a Raspberry Pi with Camera Mod
 
 !!! tip "You can terminate stream on both side anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="25-30"
-# import required libraries
-from vidgear.gears import VideoGear
-from vidgear.gears import NetGear
-from vidgear.gears import PiGear
+!!! new "Backend PiGear API now fully supports the newer [`picamera2`](https://github.com/raspberrypi/picamera2) python library under the hood for Raspberry Pi :fontawesome-brands-raspberry-pi: camera modules. Follow this [guide ➶](../../installation/pip_install/#picamera2) for its installation."
 
-# add various Picamera tweak parameters to dictionary
-options = {
-    "hflip": True,
-    "exposure_mode": "auto",
-    "iso": 800,
-    "exposure_compensation": 15,
-    "awb_mode": "horizon",
-    "sensor_mode": 0,
-}
+!!! 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 backend, otherwise nothing will work."
 
-# open pi video stream with defined parameters
-stream = PiGear(resolution=(640, 480), framerate=60, logging=True, **options).start()
 
-# activate Bidirectional mode
-options = {"bidirectional_mode": True}
+=== "New Picamera2 backend"
 
-# Define NetGear server at given IP address and define parameters 
-# !!! change following IP address '192.168.x.xxx' with client's IP address !!!
-server = NetGear(
-    address="192.168.x.xxx",
-    port="5454",
-    protocol="tcp",
-    pattern=1,
-    logging=True,
-    **options
-)
+    ```python linenums="1" hl_lines="25-30"
+    # import required libraries
+    from vidgear.gears import VideoGear
+    from vidgear.gears import NetGear
+    from vidgear.gears import PiGear
+    from libcamera import Transform
 
-# loop over until KeyBoard Interrupted
-while True:
+    # add various Picamera2 API tweaks
+    options = {
+        "queue": True,
+        "buffer_count": 4,
+        "controls": {"Brightness": 0.5, "ExposureValue": 2.0},
+        "transform": Transform(hflip=1),
+        "auto_align_output_config": True,  # auto-align camera configuration
+    }
 
-    try:
-        # read frames from stream
-        frame = stream.read()
+    # open pi video stream with defined parameters
+    stream = PiGear(resolution=(640, 480), framerate=60, logging=True, **options).start()
 
-        # check for frame if Nonetype
-        if frame is None:
+    # activate Bidirectional mode
+    options = {"bidirectional_mode": True}
+
+    # Define NetGear server at given IP address and define parameters 
+    # !!! change following IP address '192.168.x.xxx' with client's IP address !!!
+    server = NetGear(
+        address="192.168.x.xxx",
+        port="5454",
+        protocol="tcp",
+        pattern=1,
+        logging=True,
+        **options
+    )
+
+    # loop over until KeyBoard Interrupted
+    while True:
+
+        try:
+            # read frames from stream
+            frame = stream.read()
+
+            # check for frame if Nonetype
+            if frame is None:
+                break
+
+            # {do something with the frame here}
+
+            # prepare data to be sent(a simple text in our case)
+            target_data = "Hello, I am a Server."
+
+            # send frame & data and also receive data from Client
+            recv_data = server.send(frame, message=target_data) # (1)
+
+            # print data just received from Client
+            if not (recv_data is None):
+                print(recv_data)
+
+        except KeyboardInterrupt:
             break
 
-        # {do something with the frame here}
+    # safely close video stream
+    stream.stop()
 
-        # prepare data to be sent(a simple text in our case)
-        target_data = "Hello, I am a Server."
+    # safely close server
+    server.close()
+    ```
 
-        # send frame & data and also receive data from Client
-        recv_data = server.send(frame, message=target_data) # (1)
+    1.  :warning: Everything except [numpy.ndarray](https://numpy.org/doc/1.18/reference/generated/numpy.ndarray.html#numpy-ndarray) datatype data is accepted as `target_data` in `message` parameter.
 
-        # print data just received from Client
-        if not (recv_data is None):
-            print(recv_data)
+
+=== "Legacy Picamera backend"
 
-    except KeyboardInterrupt:
-        break
+    ??? info "Under the hood, Backend PiGear API _(version `0.3.3` onwards)_ prioritizes the new [`picamera2`](https://github.com/raspberrypi/picamera2) API backend."
 
-# safely close video stream
-stream.stop()
+        However, the API seamlessly switches to the legacy [`picamera`](https://picamera.readthedocs.io/en/release-1.13/index.html) backend, if the `picamera2` library is unavailable or not installed.
+        
+        !!! tip "It is advised to enable logging(`logging=True`) to see which backend is being used."
 
-# safely close server
-server.close()
-```
+        !!! 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"
+    # import required libraries
+    from vidgear.gears import VideoGear
+    from vidgear.gears import NetGear
+    from vidgear.gears import PiGear
+
+    # add various Picamera tweak parameters to dictionary
+    options = {
+        "hflip": True,
+        "exposure_mode": "auto",
+        "iso": 800,
+        "exposure_compensation": 15,
+        "awb_mode": "horizon",
+        "sensor_mode": 0,
+    }
+
+    # open pi video stream with defined parameters
+    stream = PiGear(resolution=(640, 480), framerate=60, logging=True, **options).start()
+
+    # activate Bidirectional mode
+    options = {"bidirectional_mode": True}
+
+    # Define NetGear server at given IP address and define parameters 
+    # !!! change following IP address '192.168.x.xxx' with client's IP address !!!
+    server = NetGear(
+        address="192.168.x.xxx",
+        port="5454",
+        protocol="tcp",
+        pattern=1,
+        logging=True,
+        **options
+    )
+
+    # loop over until KeyBoard Interrupted
+    while True:
+
+        try:
+            # read frames from stream
+            frame = stream.read()
+
+            # check for frame if Nonetype
+            if frame is None:
+                break
+
+            # {do something with the frame here}
+
+            # prepare data to be sent(a simple text in our case)
+            target_data = "Hello, I am a Server."
+
+            # send frame & data and also receive data from Client
+            recv_data = server.send(frame, message=target_data) # (1)
+
+            # print data just received from Client
+            if not (recv_data is None):
+                print(recv_data)
+
+        except KeyboardInterrupt:
+            break
+
+    # safely close video stream
+    stream.stop()
+
+    # safely close server
+    server.close()
+    ```
+
+    1.  :warning: Everything except [numpy.ndarray](https://numpy.org/doc/1.18/reference/generated/numpy.ndarray.html#numpy-ndarray) datatype data is accepted as `target_data` in `message` parameter.
 
-1.  :warning: Everything except [numpy.ndarray](https://numpy.org/doc/1.18/reference/generated/numpy.ndarray.html#numpy-ndarray) datatype data is accepted as `target_data` in `message` parameter.
 
 &nbsp; 
 
@@ -380,7 +467,7 @@ Open your favorite terminal and execute the following python code:
 
 !!! tip "You can terminate both side anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="35-45"
+```python linenums="1" hl_lines="35-45"
 # import required libraries
 from vidgear.gears import NetGear
 from vidgear.gears.helper import reducer
@@ -447,7 +534,7 @@ Then open another terminal on the same system and execute the following python c
 
 !!! tip "You can terminate client anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="29"
+```python linenums="1" hl_lines="29"
 # import required libraries
 from vidgear.gears import NetGear
 from vidgear.gears.helper import reducer

diff --git a/docs/gears/netgear/advanced/compression.md b/docs/gears/netgear/advanced/compression.md
@@ -117,7 +117,7 @@ Open your favorite terminal and execute the following python code:
 
 !!! tip "You can terminate both sides anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="11-14"
+```python linenums="1" hl_lines="11-14"
 # import required libraries
 from vidgear.gears import VideoGear
 from vidgear.gears import NetGear
@@ -173,7 +173,7 @@ Then open another terminal on the same system and execute the following python c
 
 !!! note "If compression is enabled at Server, then Client will automatically enforce Frame Compression with its performance attributes."
 
-```python
+```python linenums="1"
 # import required libraries
 from vidgear.gears import NetGear
 import cv2
@@ -230,7 +230,7 @@ Open your favorite terminal and execute the following python code:
 
 !!! tip "You can terminate both sides anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="7 11"
+```python linenums="1" hl_lines="7 11"
 # import required libraries
 from vidgear.gears import VideoGear
 from vidgear.gears import NetGear
@@ -288,7 +288,7 @@ Then open another terminal on the same system and execute the following python c
 
 !!! info "Client's end also automatically enforces Server's colorspace, there's no need to define it again."
 
-```python
+```python linenums="1"
 # import required libraries
 from vidgear.gears import NetGear
 import cv2
@@ -340,7 +340,7 @@ Open a terminal on Client System _(where you want to display the input frames re
 
 !!! tip "You can terminate client anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="9-15"
+```python linenums="1" hl_lines="9-15"
 # import required libraries
 from vidgear.gears import NetGear
 import cv2
@@ -395,7 +395,7 @@ Now, Open the terminal on another Server System _(with a webcam connected to it
 
 !!! tip "You can terminate stream on both side anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="20-25"
+```python linenums="1" hl_lines="20-25"
 # import required libraries
 from vidgear.gears import VideoGear
 from vidgear.gears import NetGear
@@ -475,7 +475,7 @@ Open your favorite terminal and execute the following python code:
 
 !!! tip "You can terminate both side anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="12-16 42"
+```python linenums="1" hl_lines="12-16 42"
 # import required libraries
 from vidgear.gears import NetGear
 from vidgear.gears.helper import reducer
@@ -548,7 +548,7 @@ Then open another terminal on the same system and execute the following python c
 
 !!! tip "You can terminate client anytime by pressing ++ctrl+"C"++ on your keyboard!"
 
-```python hl_lines="8-12 35"
+```python linenums="1" hl_lines="8-12 35"
 # import required libraries
 from vidgear.gears import NetGear
 from vidgear.gears.helper import reducer