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.

 

 

Importing:

You can import PiGear as follows:

from vidgear.gears import PiGear

 

 

---

Important 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

---

 

Usage: 🔨

1. Bare-Minimum Example:

# import libraries
from vidgear.gears import PiGear
import cv2

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

# loop
while True:
	# read frames
	frame = stream.read()
	
	# check if frame is None
	if frame is None: break
	

	# do something with frame here


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

	# check for 'q' key-press
	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 ScreenGear
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 video stream with defined parameters
stream = PiGear(resolution=(640, 480), framerate=60, logging = True, **options).start() 

# open video stream with default parameters
stream = ScreenGear().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: 🔧

1. camera_num(integer): selects the camera module index that will be used by API. 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.

2. resolution(tuple): sets the resolution (width,height). Its default value is (640,480). More information here.

3. framerate(integer): sets the framerate. Its default value is 30. More information here.

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

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

6. time_delay(int): set the time delay(in seconds) before start reading the frames. This delay is essentially required for the Raspi camera to warm-up. Its default value is 0.

7. **options(dict): can be used to tweak any parameter supported by PiCamera API to the input raspicam video stream. These attributes provide the flexibility to manipulate raspicam video stream various properties like brightness, saturation, senor_mode, resolution, etc. easily. These parameters can be passed using this **option dict as follows:

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

   • All supported dict attribute parameters are listed in PiCamera Docs.

   • User-specific additional attributes: A new threaded internal Timer function is introduced in PiGear API to handle any hardware failures/frozen threads robustly. This function will keep active track of the frozen threads and will exit safely if any failure occurs at a particular timeout value. This timeout can be controlled manually using following dict attribute:

     • HWFAILURE_TIMEOUT(integer/float): 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} #to sets timeout to 2.5seconds