VideoGear API

VideoGear API provides a special internal wrapper around VidGear's exclusive Video Stabilizer class. Furthermore, VideoGear API can provide internal access to both CamGear and PiGear APIs separated by a special enablePiCamera flag. Thereby, this API holds the exclusive power for any incoming VideoStream from any source, whether it is real-time or not, to stabilize it directly with minimum latency and memory requirements.

Tip:

• It is advised to turn logging parameter ON (i.e logging =True) on the first run, to easily identify runtime errors!

Importing:

You can import VideoGear as follows:

from vidgear.gears import VideoGear

Usage:

1. Basic Usage:

VideoGear contains special enablePiCamera flag that provide internal access to both CamGear and PiGear APIs and thereby only one of them can be accessed at a given instance. Also, the additional attributes and parameters of VideoGear are based on one of the API currently being accessed. Those parameters for PiGear API is discussed here and CamGear API here can be substituted directly as shown below:

In this example code we are accessing the Raspberry Pi camera module stream through VideoGear API directly by using enablePiCamera flag.

# import libraries
from vidgear.gears import VideoGear
import cv2

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

stream = VideoGear(enablePiCamera = True, resolution=(320, 240), framerate=60, time_delay=2, logging = True, **options).start() # define various attributes and start the stream

# infinite loop
while True:
	
	frame = stream.read()
	# read frames

	# check if frame is None
	if frame is None:
		#if True break the infinite loop
		break
	
	# do something with frame here
	
	cv2.imshow("Output Frame", frame)
	# Show output window

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

cv2.destroyAllWindows()
# close output window

stream.stop()
# safely close video stream.

2. Using Real-Time Video Stabilizer:

Below is a snapshot of a VideoGear Stabilizer in action:

_{Original Video Courtesy @SIGGRAPH2013}

Code to generate above VideoGear API Stabilized Video (See more details and usage examples here) :

# import libraries
from vidgear.gears import VideoGear
import numpy as np
import cv2

stream_stab = VideoGear(source='test.mp4', stabilize = True).start() # To open any valid video stream with `stabilize` flag set to True.
stream_org = VideoGear(source='test.mp4').start() # open same stream without stabilization for comparison

# infinite loop
while True:
  
  frame_stab = stream_stab.read()
  # read stabilized frames

  # check if frame is None
  if frame_stab is None:
    #if True break the infinite loop
    break
  
  #read original frame
  frame_org = stream_org.read()

  #concatenate both frames
  output_frame = np.concatenate((frame_org, frame_stab), axis=1)

  #put text
  cv2.putText(output_frame, "Before", (10, output_frame.shape[0] - 10),cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0,255,0), 2)
  cv2.putText(output_frame, "After", (output_frame.shape[1]//2+10, frame.shape[0] - 10),cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0,255,0), 2)
  
  cv2.imshow("Stabilized Frame", output_frame)
  # Show output window

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

cv2.destroyAllWindows()
# close output window
stream_org.stop()
stream_stab.stop()
# safely close video streams.

Attributes and Parameters:

• enablePiCamera(boolean): set this flag to access PiGear or CamGear API respectively. This means the if enablePiCamera flag is True, PiGear API will be accessed and if False, the CamGear API will be accessed. Its default value is False. See usage example above

• Plus any of parameters available with PiGear API and CamGear API based on which API is currently being accessed by the user. See usage example above

• Video Stabilizer specific flags:

  • stabilize:(boolean) set this flag to enable access to VidGear's Stabilizer Class. This flag can be easily set to True(to enable) or unset to False(to disable) this mode. Its default value is False.

  • ** options:(dict) can be used in addition, to pass user-defined parameter parameter supported by VidGear's Stabilizer class. These parameters can be used to alter the properties of Stabilizer Class On-the-Fly.

    • Supported valid dict keys are:

      • SMOOTHING_RADIUS (int) : to alter averaging window size. It handles the quality of stabilization at the expense of latency and sudden panning. Larger its value, less will be panning, more will be latency and vice-versa.

      • BORDER_SIZE (int) : to change extended border size that compensates for stabilized output video frames motions. It's default value is 0(no borders).

      • CROP_N_ZOOM(bool): enables the feature where it crops and zooms frames(to original size) to reduce the black borders from stabilization being too noticeable (similar to the feature available in Adobe AfterEffects) . It works in conjunction with the BORDER_SIZE attribute, i.e. when this attribute is enabled BORDER_SIZE will be used for cropping border instead of making them.

      • BORDER_TYPE (string) : to change the extended border style. Valid border types are 'black', 'reflect', 'reflect_101', 'replicate' and 'wrap'. You can learn more about it here.

      Altering BORDER_TYPE parameter is disabled while CROP_N_ZOOM is enabled!

    • Usage: You can easily pass these parameter to **options dict as follows:

    options = {'SMOOTHING_RADIUS': 25, 'BORDER_SIZE': 10, 'CROP_N_ZOOM' : True,  'BORDER_TYPE': 'black'}

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