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:
The complete usage example demonstrating the usage of the camera_num
parameter is available here ➶.
resolution
¶
This parameter controls the resolution - a tuple (i.e. (width,height)
) of two values giving the width and height of the output frames.
Make sure both width and height values should be at least 64
.
When using the Picamera2 backend, the resolution
parameter will be OVERRIDDEN, if the user explicitly defines the output_size
property of the sensor
configurational parameter in PiGear API.
Data-Type: Tuple
Default Value: Its default value is (640,480)
.
Usage:
framerate
¶
This parameter controls the framerate of the source.
Data-Type: integer/float
Default Value: Its default value is 30
.
Usage:
colorspace
¶
This parameter controls the colorspace of the output frames.
With the Picamera2 backend, you can also define a custom format
(format of output frame pixels) in PiGear API. Checkout this bonus example ➶
Data-Type: String
Default Value: Its default value is None
(i.e. Default BGR
colorspace).
Usage:
All supported colorspace
values are described here ➶
Its complete usage example is given here ➶
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, ifTrue
, forces the use of the legacypicamera
backend in PiGear API, even if the newerpicamera2
backend is available on the system. It's default value isFalse
. Its usage is as follows:PiGear API will verify if the
picamera
Python library is installed before enabling theenforce_legacy_picamera
parameter. -
enable_verbose_logs
(bool): [picamera2
backend only] Thispicamera2
backend specific parameter, ifTrue
, 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 isFalse
(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. -
auto_align_output_size
(bool): [picamera2
backend only] The Picamera2 backend in PiGear API has certain hardware restrictions and optimal frame size (orresolution
) 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, ifTrue
, will request these optimal frame size adjustments from Picamera2. It's default value isFalse
(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.Explanation: In the example code, Picamera2 adjusts the requested output resolution of# 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.
(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 aSystemError
to save resources. Its value can only be set between1.0
(min) and10.0
(max), with a default value of2.0
. Its usage is as follows:
-
Data-Type: Dictionary
Default Value: Its default value is {}
Usage:
The complete usage example demonstrating the usage of the options
parameter is available here ➶.
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:
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: