PiGear API Parameters¶

camera_num¶

This parameter selects the camera index to be used as the source, allowing you to drive these multiple cameras simultaneously from within a single Python session. Its value can only be zero or greater, otherwise, PiGear API will throw ValueError for any negative value.

Data-Type: Integer

Default Value: Its default value is 0.

Usage:

# select Camera Module at index `1`
PiGear(camera_num=1)

resolution¶

This parameter controls the resolution - a tuple (i.e. (width,height)) of two values giving the width and height of the output frames.

Data-Type: Tuple

Default Value: Its default value is (640,480).

Usage:

PiGear(resolution=(1280,720)) # sets 1280x720 resolution

framerate¶

This parameter controls the framerate of the source.

Data-Type: integer/float

Default Value: Its default value is 30.

Usage:

PiGear(framerate=60) # sets 60fps framerate

colorspace¶

This parameter controls the colorspace of the output frames.

Data-Type: String

Default Value: Its default value is None (i.e. Default BGR colorspace).

Usage:

PiGear(colorspace="COLOR_BGR2HSV")

options¶

This dictionary parameter in the PiGear API allows you to control various camera settings for both the picamera2 and legacy picamera backends and some internal API tasks. These settings include:

A. Configurational Camera Parameters¶

• These parameters are provided by the underlying backend library (depending upon backend in use), and must be applied to the camera system before the camera can be started.
• These parameter include: Brightness, Contrast, Saturation, Exposure, Colour Temperature, Colour Gains, etc.
• All supported parameters are listed in this Usage example ➶

B. User-defined Parameters¶

• These user-defined parameters control specific internal behaviors of the API and perform certain tasks on the camera objects.

• All supported User-defined Parameters are listed below:

  • enforce_legacy_picamera (bool): This user-defined boolean parameter, if True, forces the use of the legacy picamera backend in PiGear API, even if the newer picamera2 backend is available on the system. It's default value is False. Its usage is as follows:

    PiGear API will verify if the picamera Python library is installed before enabling the enforce_legacy_picamera parameter.

    options = {"enforce_legacy_picamera": True}  # enforces `picamera` backend 
    

  • enable_verbose_logs (bool): [picamera2 backend only] This picamera2 backend specific parameter, if True, will set the logging level to output all debug messages from Picamera2 library. This parameter can be used in conjunction with enabling general logging (logging=True) in the PiGear API for even more granular control over logging output. It's default value is False (meaning only warning message will be outputted). Its usage is as follows:

    This parameter requires logging to be enabled (i.e. logging=True) in PiGear API, otherwise it will be discarded.

    options = {"enable_verbose_logs": True}  # enables debug logs from `picamera2` backend
    

  • auto_align_output_size (bool): [picamera2 backend only] The Picamera2 backend in PiGear API has certain hardware restrictions and optimal frame size (or resolution) for efficient processing. Although user-specified frame sizes are allowed, Picamera2 can make minimal adjustments to the configuration if it detects an invalid or inefficient size. This parameter, if True, will request these optimal frame size adjustments from Picamera2. It's default value is False (meaning no changes will be made to user-specified resolution). Its usage is explained in detail below:

    This parameter may override any invalid or inefficient size inputted by user through resolution parameter in PiGear API.

    # auto-aligns output resolution to optimal
    options = {"auto_align_output_size": True}
    
    # open pi video stream with user-specified resolution `(808, 606)`
    stream = PiGear(resolution=(808, 606), logging=True, **options).start()
    
    # read frame from stream
    frame = stream.read()
    
    # print final resolution of frame
    print('width: ', frame.shape[1]) # height: 800 (changed)
    print('height: ', frame.shape[0]) # height: 606
    # Picamera2 has decided an 800x606 image will be more efficient.
    

    Explanation: In the example code, Picamera2 adjusts the requested output resolution of (808, 606) to the more efficient (800, 606) size.

  • HWFAILURE_TIMEOUT (float): PiGear API provides a Threaded Internal Timer that silently keeps track of any frozen threads/hardware failures and exits safely if any occur at a timeout value. This parameter controls the timeout value, which is the maximum waiting time (in seconds) after which API exits itself with a SystemError to save resources. Its value can only be set between 1.0 (min) and 10.0 (max), with a default value of 2.0. Its usage is as follows:

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

Data-Type: Dictionary

Default Value: Its default value is {}

Usage:

You can format these user-defined and configurational parameters as attributes of this options dictionary parameter as follows:

# formulate various Picamera2 API parameters
options = {
    "queue": True,
    "buffer_count": 4,
    "controls": {"Brightness": 0.5, "ExposureValue": 2.0},
    "exposure_compensation": 15,
    "sensor": {"output_size": (480, 320)},  # !!! will override `resolution` !!!
}

# open pi video stream with defined parameters
stream = PiGear(resolution=(640, 480), framerate=60, logging=True, **options).start()

# formulate various Picamera API parameters
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()

logging¶

This parameter enables logging (if True), essential for debugging.

Data-Type: Boolean

Default Value: Its default value is False.

Usage:

PiGear(logging=True)

time_delay¶

This parameter set the time delay (in seconds) before the PiGear API start reading the frames. This delay is only required if the source required some warm-up delay before starting up.

Data-Type: Integer

Default Value: Its default value is 0.

Usage:

PiGear(time_delay=1)  # set 1 seconds time delay