Picam Cameras

Installation

This module requires the Picam SDK and the NiceLib package. Tested to work on Windows and Linux.

On Linux, you must set the GENICAM_ROOT_V2_4 environment variable to the path to genicam (probably /opt/pleora/ebus_sdk/x86_64/lib/genicam) and ensure that Picam’s lockfile directory exists (the Picam SDK installer isn’t good about doing this).

On Windows, the DLLs Picam.dll, Picc.dll, Pida.dll, and Pidi.dll must be copied to a directory on the system path. Note that the DLLs found first on the system path must match the version of the headers installed with the Picam SDK.

Module Reference

In addition to the documented methods, instances of PicamCamera have a params attribute which contains the camera’s Picam parameters. Each parameter implements get_value(), set_value(), can_set(), and get_default() methods that call the underlying Picam SDK functions. For example,

>>> cam.params.ShutterTimingMode.get_value()  #  => gives ShutterTimingMode.AlwaysOpen
>>> cam.params.ShutterTimingMode.set_value(PicamEnums.ShutterTimingMode.AlwaysClosed)
>>> cam.params.ShutterTimingMode.get_value()  #  verify the change
class instrumental.drivers.cameras.picam.PicamCamera(inst=None, **kwds)

A Picam Camera

commit_parameters()

Commits camera parameters

get_captured_image(timeout='1s', copy=True)

Get the image array(s) from the last capture sequence.

Returns an image numpy array (or tuple of arrays for a multi-exposure sequence). The array has shape (height, width) for grayscale images, and (height, width, 3) for RGB images. Typically the dtype will be uint8, or sometimes uint16 in the case of 16-bit monochromatic cameras.

Parameters:

  • timeout (Quantity([time]) or None, optional) – Max time to wait for wait for the image data to be ready. If None, will block forever. If timeout is exceeded, a TimeoutError will be raised.

  • copy (bool, optional) – Whether to copy the image memory or directly reference the underlying buffer. It is recommended to use True (the default) unless you know what you’re doing.

grab_image(timeout='1s', copy=True, **kwds)

Perform a capture and return the resulting image array(s).

This is essentially a convenience function that calls start_capture() then get_captured_image(). See get_captured_image() for information about the returned array(s).

Parameters:

  • timeouts (Quantity([time]) or None, optional) – Max time to wait for wait for the image data to be ready. If None, will block forever. If timeout is exceeded, a TimeoutError will be raised.

  • copy (bool, optional) – Whether to copy the image memory or directly reference the underlying buffer. It is recommended to use True (the default) unless you know what you’re doing.

  • include (You can specify other parameters of the capture as keyword arguments. These) –

  • n_frames (int) – Number of exposures in the sequence

  • vbin (int) – Vertical binning

  • hbin (int) – Horizontal binning

  • exposure_time (Quantity([time])) – Duration of each exposure

  • width (int) – Width of the ROI

  • height (int) – Height of the ROI

  • cx (int) – X-axis center of the ROI

  • cy (int) – Y-axis center of the ROI

  • left (int) – Left edge of the ROI

  • right (int) – Right edge of the ROI

  • top (int) – Top edge of the ROI

  • bot (int) – Bottom edge of the ROI

latest_frame(copy=True)

Get the latest image frame in live mode.

Returns the image array received on the most recent successful call to wait_for_frame().

Parameters:

copy (bool, optional) – Whether to copy the image memory or directly reference the underlying buffer. It is recommended to use True (the default) unless you know what you’re doing.

set_roi(x=None, y=None, width=None, height=None, x_binning=None, y_binning=None)

Set one or more fields of the ROI

If there are multiple ROIs, only applies to the first. Any args not given are left unmodified.

start_capture(**kwds)

Start a capture sequence and return immediately.

Depending on your camera-specific shutter/trigger settings, this will either start the exposure immediately or ready the camera to start on an explicit (hardware or software) trigger.

It can be useful to invoke start_capture() and get_captured_image() explicitly if you expect the capture sequence to take a long time and you’d like to perform some operations while you wait for the camera:

>>> cam.start_capture()
>>> do_other_useful_stuff()
>>> arr = cam.get_captured_image()

See grab_image() for the set of available kwds.

start_live_video(**kwds)

Start live video mode.

Once live video mode has been started, images will automatically and continuously be acquired. You can check if the next frame is ready by using wait_for_frame(), and access the most recent image’s data with get_captured_image().

See grab_image() for the set of available kwds.

stop_live_video()

Stop live video mode.

wait_for_frame(timeout=None)

Wait until the next frame is ready (in live mode).

Blocks and returns True once the next frame is ready, False if the timeout was reached. Using a timeout of 0 simply polls to see if the next frame is ready.

Parameters:

timeout (Quantity([time]), optional) – How long to wait for wait for the image data to be ready. If None (the default), will block forever.

Returns:

frame_ready – True if the next frame is ready, False if the timeout was reached.

Return type:

bool

property height

Height of the camera image in pixels

property max_height

Max settable height of the camera image, given current binning/subpixel settings

property max_width

Max settable width of the camera image, given current binning/subpixel settings

property width

Width of the camera image in pixels

picam.PicamEnums = <instrumental.drivers.cameras.picam.EnumTypes object>
class instrumental.drivers.cameras.picam.PicamError(msg, code=None)
__init__(msg, code=None)

Picam Data Types

These data types are returned by the API and are not meant to be created directly by users. They provide a wrapped interface to Picam’s data types and automatically handle memory cleanup.

class instrumental.drivers.cameras.picam.PicamCameraID(base_ptr, index)

Picam CameraID

to_params()

Get an instrumental ParamSet describing this PicamCameraID

class instrumental.drivers.cameras.picam.PicamPulse(pulse_ptr)
property delay
property width
class instrumental.drivers.cameras.picam.PicamRois(rois_ptr)

List-like group of PicamRoi objects

Supports index-based access, e.g. roi = rois[0].

class instrumental.drivers.cameras.picam.PicamRoi(parent, item_ptr)
property height
property width
property x
property x_binning
property y
property y_binning
class instrumental.drivers.cameras.picam.PicamModulations(mods_ptr)

List-like group of PicamModulation objects

Supports index-based access, e.g. mod = mods[0].

class instrumental.drivers.cameras.picam.PicamModulation(parent, item_ptr)
property duration
property frequency
property output_signal_frequency
property phase

Parameter Types

All Picam Parameters accessible through PicamCamera.params are instances of one of these classes.

class instrumental.drivers.cameras.picam.IntegerParameter(dev: <Mock object at 0x7fac005d92e0>[], parameter)
can_set(value: int) → bool
get_default() → int
get_value() → int
set_value(value: int)
class instrumental.drivers.cameras.picam.LargeIntegerParameter(dev: <Mock object at 0x7fac005ab760>[], parameter)
can_set(value: int) → bool
get_default() → int
get_value() → int
set_value(value: int)
class instrumental.drivers.cameras.picam.FloatingPointParameter(dev: <Mock object at 0x7fac008d78b0>[], parameter)
can_set(value: float) → bool
get_default() → float
get_value() → float
set_value(value: float)
class instrumental.drivers.cameras.picam.BooleanParameter(dev: <Mock object at 0x7fac0096d940>[], parameter)
get_default()
get_value()
class instrumental.drivers.cameras.picam.EnumerationParameter(dev, parameter)
__init__(dev, parameter)
get_default_value()
get_value()
class instrumental.drivers.cameras.picam.ModulationsParameter(dev: <Mock object at 0x7fac00593730>[], parameter)
can_set(value: PicamModulations) → bool
get_default() → PicamModulations
get_value() → PicamModulations
set_value(value: PicamModulations)
class instrumental.drivers.cameras.picam.RoisParameter(dev: <Mock object at 0x7fac00559340>[], parameter)
can_set(value: PicamRois) → bool
get_default() → PicamRois
get_value() → PicamRois
set_value(value: PicamRois)
class instrumental.drivers.cameras.picam.PulseParameter(dev: <Mock object at 0x7fac005951f0>[], parameter)
can_set(value: PicamPulse) → bool
get_default() → PicamPulse
get_value() → PicamPulse
set_value(value: PicamPulse)
class instrumental.drivers.cameras.picam.Parameter(dev: <Mock object at 0x7fac0056cf40>[], parameter)

Base class for Picam Parameters

Low Level Interface

The NicePicamLib class provides a more direct wrapping of the Picam SDK’s C interface—what the NiceLib package calls a “Mid-level” interface. See the NiceLib documentation for more information on how to use this kind of interface.