PiGear

PiGear API

PiGear is similar to CamGear but exclusively made to support various Raspberry Pi Camera Modules (such as OmniVision OV5647 Camera Module and Sony IMX219 Camera Module).

To interface with these modules correctly, PiGear provides a flexible multi-threaded wrapper around complete picamera python library and provides us the ability to exploit its various important parameters like brightness, saturation, sensor_mode, iso, exposure, etc. effortlessly and also supports multiple camera modules such as in case of Raspberry Pi 3/3+ compute modules.

 

Important Information: ⚠️

• Make sure to enable Raspberry Pi hardware-specific settings prior using this API.

• Because of its exception error-handling, If you pulled Camera cable out accidentally when running PiGear API in your script, it will terminate safely with SystemError to save resources, without going into a possible Kernel panic.

 

 

Table of Contents:

• Importing
• Usage
  • Bare-Minimum Example
  • PiGear API with Variable Properties
• Parameters and Attributes

 

 

Importing:

You can import PiGear as follows:

from vidgear.gears import PiGear

 

 

Usage: 🔨

 

---

Warning ⚠️

Due to a recently discovered logic bug in the PiGear color conversion, that makes PiGear try to perform said operation even though no colorspace was defined and thereby resulting in following Error:

PiGear :: ERROR :: an integer is required (got type NoneType)

Solution: Luckily, This bug is already patched in testing branch which can be cloned and thereby can installed easily as follows:

git clone https://github.com/abhiTronix/vidgear.git
cd vidgear
git checkout testing
sudo pip install .
cd

---

 

1. Bare-Minimum Example:

# import required libraries
from vidgear.gears import PiGear
import cv2


# open pi video stream with default parameters
stream = PiGear().start() 

# loop over
while True:

    # read frames from stream
    frame = stream.read()

    # check for frame if Nonetype
    if frame is None:
        break


    # {do something with the frame here}


    # Show output window
    cv2.imshow("Output Frame", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()

 

2. PiGear API with Variable Properties:

PiGear API supports all tweak parameters and attributes available within Picamera API which can be applied to the given camera stream through its **options dictionary when it's being initiated. The complete example is as follows:

# import required libraries
from vidgear.gears import PiGear
import cv2

# 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() 

# loop over
while True:

    # read frames from stream
    frame = stream.read()

    # check for frame if Nonetype
    if frame is None:
        break


    # {do something with the frame here}


    # Show output window
    cv2.imshow("Output Frame", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# safely close video stream
stream.stop()

 

 

Attributes and Parameters: 🔧

• camera_num (integer) : selects the camera module index which will be used as source. Its default value is 0 and ⚠️ shouldn't be altered until unless if you using Raspberry Pi 3/3+ compute module in your project along with multiple camera modules. Furthermore, Its value can only be greater than zero, otherwise, it will throw ValueError for any negative value.

• resolution (tuple) : sets the resolution (width,height) of stream. Its default value is (640,480). For more information read here ➶.

• framerate (integer) : sets the framerate. Its default value is 30. For more information read here ➶.

• colorspace (string) : set the colorspace of the source stream. Its default value is None. Check out its detailed Usage here ➶.

• logging (boolean) : set this flag to enable/disable logging, essential for debugging. Its default value is False.

• time_delay (integer) : set the time delay (in seconds) before start reading the frames. This delay is essentially required if the source required warm-up delay before starting up. Its default value is 0.

• **options (dict) : provides the ability to tweak any properties like brightness, saturation, senor_mode, resolution, etc. of input RasPi camera module source stream easily. Any PiCamera supported parameters can be passed to PiGear API for tweaking those properties, as follows:

  options = {"hflip": True, "exposure_mode": "auto", "iso": 800, "exposure_compensation": 15, "awb_mode": "horizon", "sensor_mode": 0} 

  💡 All supported parameters are listed in PiCamera Docs!

  User-specific attributes:

  A new Internal Threaded Timer is introduced in PiGear API to handle any hardware failures/frozen threads robustly.

  This Timer will keep active track of the frozen threads and will exit safely if any failure occurs at a particular timeout value. The given timeout value for this Timer can be controlled manually using following exclusive dictionary attribute:

  • HWFAILURE_TIMEOUT: can be used to control the maximum waiting time (in seconds) before the Internal Threaded Timer exits with a SystemError to save resources. Its value can only be between 1.0 (min) and 10.0 (max) and its default value is 2.0. It usage is as follows:

    options = {"HWFAILURE_TIMEOUT": 2.5} # sets timeout to 2.5 seconds