Skip to content

VideoGear API References

VideoGear API usage examples can be found here ➶

VideoGear API parameters are explained here ➶

VideoGear API provides a special internal wrapper around VidGear's exclusive Video Stabilizer class. VideoGear also acts as a Common Video-Capture API that provides internal access for both CamGear and PiGear APIs and their parameters with an exclusive enablePiCamera boolean flag.

VideoGear is ideal when you need to switch to different video sources without changing your code much. Also, it enables easy stabilization for various video-streams (real-time or not) with minimum effort and writing way fewer lines of code.

Source code in vidgear/gears/videogear.py 
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
class VideoGear:
    """
    VideoGear API provides a special internal wrapper around VidGear's exclusive Video Stabilizer class.
    VideoGear also acts as a Common Video-Capture API that provides internal access for both CamGear and PiGear APIs and
    their parameters with an exclusive enablePiCamera boolean flag.

    VideoGear is ideal when you need to switch to different video sources without changing your code much. Also, it enables
    easy stabilization for various video-streams (real-time or not)
    with minimum effort and writing way fewer lines of code.
    """

    def __init__(
        self,
        # VideoGear parameters
        enablePiCamera: bool = False,
        stabilize: bool = False,
        # PiGear parameters
        camera_num: int = 0,
        resolution: Tuple[int, int] = (640, 480),
        framerate: Union[int, float] = 30,
        # CamGear parameters
        source: Any = 0,
        stream_mode: bool = False,
        backend: int = 0,
        # common parameters
        time_delay: int = 0,
        colorspace: str = None,
        logging: bool = False,
        **options: dict
    ):
        """
        This constructor method initializes the object state and attributes of the VideoGear class.

        Parameters:
            enablePiCamera (bool): provide access to PiGear(if True) or CamGear(if False) APIs respectively.
            stabilize (bool): enable access to Stabilizer Class for stabilizing frames.
            camera_num (int): selects the camera module index which will be used as Rpi source.
            resolution (tuple): sets the resolution (i.e. `(width,height)`) of the Rpi source.
            framerate (int/float): sets the framerate of the Rpi source.
            source (based on input): defines the source for the input stream.
            stream_mode (bool): controls the exclusive YouTube Mode.
            backend (int): selects the backend for OpenCV's VideoCapture class.
            colorspace (str): selects the colorspace of the input stream.
            logging (bool): enables/disables logging.
            time_delay (int): time delay (in sec) before start reading the frames.
            options (dict): provides ability to alter Tweak Parameters of CamGear, PiGear & Stabilizer.
        """
        # enable logging if specified
        self.__logging = logging if isinstance(logging, bool) else False

        # print current version
        logcurr_vidgear_ver(logging=self.__logging)

        # initialize stabilizer
        self.__stabilization_mode = stabilize

        # reformat dictionary
        options = {str(k).strip(): v for k, v in options.items()}

        if self.__stabilization_mode:
            from .stabilizer import Stabilizer

            s_radius = options.pop("SMOOTHING_RADIUS", 25)
            if not isinstance(s_radius, int):
                s_radius = 25

            border_size = options.pop("BORDER_SIZE", 0)
            if not isinstance(border_size, int):
                border_size = 0

            border_type = options.pop("BORDER_TYPE", "black")
            if not isinstance(border_type, str):
                border_type = "black"

            crop_n_zoom = options.pop("CROP_N_ZOOM", False)
            if not isinstance(crop_n_zoom, bool):
                crop_n_zoom = False

            self.__stabilizer_obj = Stabilizer(
                smoothing_radius=s_radius,
                border_type=border_type,
                border_size=border_size,
                crop_n_zoom=crop_n_zoom,
                logging=logging,
            )
            self.__logging and logger.debug(
                "Enabling Stabilization Mode for the current video source!"
            )  # log info

        if enablePiCamera:
            # only import the pigear module only if required
            from .pigear import PiGear

            # initialize the picamera stream by enabling PiGear API
            self.stream = PiGear(
                camera_num=camera_num,
                resolution=resolution,
                framerate=framerate,
                colorspace=colorspace,
                logging=logging,
                time_delay=time_delay,
                **options
            )
        else:
            # otherwise, we are using OpenCV so initialize the webcam
            # stream by activating CamGear API
            self.stream = CamGear(
                source=source,
                stream_mode=stream_mode,
                backend=backend,
                colorspace=colorspace,
                logging=logging,
                time_delay=time_delay,
                **options
            )

        # initialize framerate variable
        self.framerate = self.stream.framerate

    def start(self) -> T:
        """
        Launches the internal *Threaded Frames Extractor* daemon of API in use.

        **Returns:** A reference to the selected class object.
        """
        self.stream.start()
        return self

    def read(self) -> NDArray:
        """
        Extracts frames synchronously from selected API's monitored deque, while maintaining a fixed-length frame
        buffer in the memory, and blocks the thread if the deque is full.

        **Returns:** A n-dimensional numpy array.
        """
        while self.__stabilization_mode:
            frame = self.stream.read()
            if frame is None:
                break
            frame_stab = self.__stabilizer_obj.stabilize(frame)
            if not (frame_stab is None):
                return frame_stab
        return self.stream.read()

    def stop(self) -> None:
        """
        Safely terminates the thread, and release the respective multi-threaded resources.
        """
        self.stream.stop()
        # logged
        self.__logging and logger.debug("Terminating VideoGear.")
        # clean queue
        self.__stabilization_mode and self.__stabilizer_obj.clean()

__init__(enablePiCamera=False, stabilize=False, camera_num=0, resolution=(640, 480), framerate=30, source=0, stream_mode=False, backend=0, time_delay=0, colorspace=None, logging=False, **options) ¶

This constructor method initializes the object state and attributes of the VideoGear class.

Parameters:

Name Type Description Default
enablePiCamera bool

provide access to PiGear(if True) or CamGear(if False) APIs respectively.

 False
stabilize bool

enable access to Stabilizer Class for stabilizing frames.

 False
camera_num int

selects the camera module index which will be used as Rpi source.

 0
resolution tuple

sets the resolution (i.e. (width,height)) of the Rpi source.

 (640, 480)
framerate int / float

sets the framerate of the Rpi source.

 30
source based on input

defines the source for the input stream.

 0
stream_mode bool

controls the exclusive YouTube Mode.

 False
backend int

selects the backend for OpenCV's VideoCapture class.

 0
colorspace str

selects the colorspace of the input stream.

 None
logging bool

enables/disables logging.

 False
time_delay int

time delay (in sec) before start reading the frames.

 0
options dict

provides ability to alter Tweak Parameters of CamGear, PiGear & Stabilizer.

 {}
Source code in vidgear/gears/videogear.py 
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
def __init__(
    self,
    # VideoGear parameters
    enablePiCamera: bool = False,
    stabilize: bool = False,
    # PiGear parameters
    camera_num: int = 0,
    resolution: Tuple[int, int] = (640, 480),
    framerate: Union[int, float] = 30,
    # CamGear parameters
    source: Any = 0,
    stream_mode: bool = False,
    backend: int = 0,
    # common parameters
    time_delay: int = 0,
    colorspace: str = None,
    logging: bool = False,
    **options: dict
):
    """
    This constructor method initializes the object state and attributes of the VideoGear class.

    Parameters:
        enablePiCamera (bool): provide access to PiGear(if True) or CamGear(if False) APIs respectively.
        stabilize (bool): enable access to Stabilizer Class for stabilizing frames.
        camera_num (int): selects the camera module index which will be used as Rpi source.
        resolution (tuple): sets the resolution (i.e. `(width,height)`) of the Rpi source.
        framerate (int/float): sets the framerate of the Rpi source.
        source (based on input): defines the source for the input stream.
        stream_mode (bool): controls the exclusive YouTube Mode.
        backend (int): selects the backend for OpenCV's VideoCapture class.
        colorspace (str): selects the colorspace of the input stream.
        logging (bool): enables/disables logging.
        time_delay (int): time delay (in sec) before start reading the frames.
        options (dict): provides ability to alter Tweak Parameters of CamGear, PiGear & Stabilizer.
    """
    # enable logging if specified
    self.__logging = logging if isinstance(logging, bool) else False

    # print current version
    logcurr_vidgear_ver(logging=self.__logging)

    # initialize stabilizer
    self.__stabilization_mode = stabilize

    # reformat dictionary
    options = {str(k).strip(): v for k, v in options.items()}

    if self.__stabilization_mode:
        from .stabilizer import Stabilizer

        s_radius = options.pop("SMOOTHING_RADIUS", 25)
        if not isinstance(s_radius, int):
            s_radius = 25

        border_size = options.pop("BORDER_SIZE", 0)
        if not isinstance(border_size, int):
            border_size = 0

        border_type = options.pop("BORDER_TYPE", "black")
        if not isinstance(border_type, str):
            border_type = "black"

        crop_n_zoom = options.pop("CROP_N_ZOOM", False)
        if not isinstance(crop_n_zoom, bool):
            crop_n_zoom = False

        self.__stabilizer_obj = Stabilizer(
            smoothing_radius=s_radius,
            border_type=border_type,
            border_size=border_size,
            crop_n_zoom=crop_n_zoom,
            logging=logging,
        )
        self.__logging and logger.debug(
            "Enabling Stabilization Mode for the current video source!"
        )  # log info

    if enablePiCamera:
        # only import the pigear module only if required
        from .pigear import PiGear

        # initialize the picamera stream by enabling PiGear API
        self.stream = PiGear(
            camera_num=camera_num,
            resolution=resolution,
            framerate=framerate,
            colorspace=colorspace,
            logging=logging,
            time_delay=time_delay,
            **options
        )
    else:
        # otherwise, we are using OpenCV so initialize the webcam
        # stream by activating CamGear API
        self.stream = CamGear(
            source=source,
            stream_mode=stream_mode,
            backend=backend,
            colorspace=colorspace,
            logging=logging,
            time_delay=time_delay,
            **options
        )

    # initialize framerate variable
    self.framerate = self.stream.framerate

read() ¶

Extracts frames synchronously from selected API's monitored deque, while maintaining a fixed-length frame buffer in the memory, and blocks the thread if the deque is full.

Returns: A n-dimensional numpy array.

Source code in vidgear/gears/videogear.py 
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def read(self) -> NDArray:
    """
    Extracts frames synchronously from selected API's monitored deque, while maintaining a fixed-length frame
    buffer in the memory, and blocks the thread if the deque is full.

    **Returns:** A n-dimensional numpy array.
    """
    while self.__stabilization_mode:
        frame = self.stream.read()
        if frame is None:
            break
        frame_stab = self.__stabilizer_obj.stabilize(frame)
        if not (frame_stab is None):
            return frame_stab
    return self.stream.read()

start() ¶

Launches the internal Threaded Frames Extractor daemon of API in use.

Returns: A reference to the selected class object.

Source code in vidgear/gears/videogear.py 
161
162
163
164
165
166
167
168
def start(self) -> T:
    """
    Launches the internal *Threaded Frames Extractor* daemon of API in use.

    **Returns:** A reference to the selected class object.
    """
    self.stream.start()
    return self

stop() ¶

Safely terminates the thread, and release the respective multi-threaded resources.

Source code in vidgear/gears/videogear.py 
186
187
188
189
190
191
192
193
194
def stop(self) -> None:
    """
    Safely terminates the thread, and release the respective multi-threaded resources.
    """
    self.stream.stop()
    # logged
    self.__logging and logger.debug("Terminating VideoGear.")
    # clean queue
    self.__stabilization_mode and self.__stabilizer_obj.clean()

 

Was this page helpful?