Thorlabs DCx (UC480) Cameras¶

Installation
- Summary
- Details
Module Reference
Changelog

Installation ¶

Summary ¶

Install the uc480 API provided by Thorlabs.
Add the DLL to your PATH environment variable.
Run pip install pywin32 nicelib.
Call list_instruments(), which will auto-build the API bindings.

Details ¶

Download and install ThorCam from the Thorlabs website, which comes with the uc480 API libraries. (Since these cameras are rebranded IDS cameras, you may instead install the IDS uEye software)
Make sure the path to the shared library (uc480.dll, uc480_64.dll, ueye_api.dll, or ueye_api_64.dll) is added to your PATH. The library will usually be located in the Thorlabs or IDS folder inside your Program Files folder. On my system they are located within C:\Program Files\Thorlabs\Scientific Imaging\DCx Camera Support\Develop\Lib.
Run pip install pywin32 nicelib on the command line to install the pywin32 and nicelib packages.
Use list_instruments() to see if your camera shows up. This will automatically build the bindings to the DLL. If this doesn’t work (and your camera is plugged in an works with the ThorCam software), try to import the driver module directly: from instrumental.drivers.cameras import uc480. If this fails, the error should give you information about what went wrong. Be sure to check out the FAQs page for more information, and you can use the mailing list or GitHub if you need additional help.

Module Reference ¶

Driver for Thorlabs DCx cameras. May be compatible with iDS cameras that use uEye software. Currently Windows-only, but Linux support should be possible to implement if desired.

class instrumental.drivers.cameras.uc480.UC480_Camera(inst=None, **kwds)¶

A uc480-supported Camera

__init__()¶

close(force=False)¶

Close the camera and release the associated image memory.

Parameters: force (bool) – If True, run the close routine even if the camera is already closed (self.is_open is False).

fill_all_coords(kwds, names)¶

find_hot_pixels(stddevs=10, **kwds)¶: Generate the list of hot pixels on the camera sensor.

get(facet_name, use_cache=False)¶

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.

get_trigger_delay()¶

Get the trigger delay in [time] units.

Returns: Trigger delay
Return type: string

get_trigger_level()¶

Get the current hardware trigger level.

Returns: A value of 0 indicates trigger signal is low (not triggered)
Return type: int

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.

load_params(filename=None)¶

Load camera parameters from file or EEPROM.

Parameters: filename (str, optional) – By default, loads the parameters from the camera’s EEPROM. Otherwise, loads it from the specified parameter file. If filename is the empty string ‘’, will open a ‘Load’ dialog to select the file.

observe(name, callback)¶

Add a callback to observe changes in a facet’s value

The callback should be a callable accepting a ChangeEvent as its only argument. This ChangeEvent is a namedtuple with name, old, and new fields. name is the facet’s name, old is the old value, and new is the new value.

open(num_bufs=1, force=False)¶

Connect to the camera and set up the image memory.

Parameters: force (bool) – If True, run the open routine even if the camera is already open (self.is_open is True).

save_hot_pixels(path=None)¶: Save a file listing the hot pixels.

save_instrument(name, force=False)¶

Save an entry for this instrument in the config file.

Parameters

name (str) – The name to give the instrument, e.g. ‘myCam’
force (bool, optional) – Force overwrite of the old entry for instrument name. By default, Instrumental will raise an exception if you try to write to a name that’s already taken. If force is True, the old entry will be commented out (with a warning given) and a new entry will be written.

set_auto_exposure(enable=True)¶: Enable or disable the auto exposure shutter.

set_defaults(**kwds)¶

set_trigger(mode='software', edge='rising')¶

Set the camera trigger mode.

Parameters

mode (string) – Either ‘off’, ‘software’(default), or ‘hardware’.
edge (string) – Hardware trigger is either on the ‘rising’(default) or ‘falling’ edge.

set_trigger_delay(delay)¶

Set the time to delay a hardware trigger.

Parameters: delay ([time]-dimensioned Quantity) – The delay time after trigger signal is received to trigger the camera. Has microsecond resolution.

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(framerate=None, **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

DEFAULT_KWDS = {'bot': None, 'cx': None, 'cy': None, 'exposure_time': <Quantity(10, 'millisecond')>, 'fix_hotpixels': False, 'gain': 0, 'hbin': 1, 'height': None, 'hsub': 1, 'left': None, 'n_frames': 1, 'right': None, 'top': None, 'vbin': 1, 'vsub': 1, 'width': None}¶

auto_blacklevel¶: Whether auto-blacklevel correction is turned on

auto_exposure¶: Whether auto exposure is enabled

auto_framerate¶: Whether auto framerate is enabled

auto_gain¶: Whether auto gain is enabled

auto_sensor_exposure¶: Whether sensor-based auto exposure is enabled

auto_sensor_framerate¶: Whether sensor-based auto framerate is enabled

auto_sensor_gain¶: Whether sensor-based auto gain is enabled

auto_sensor_whitebalance¶: Whether sensor-based auto whitebalance is enabled

auto_whitebalance¶: Whether auto whitebalance is enabled

blacklevel_offset¶: The blacklevel offset value (an int)

property bytes_per_line¶: Number of bytes used by each line of the image. Read-only

property color_mode¶: Color mode string. Read-only

exposure¶

property framerate¶: Current framerate, in [time]⁻¹ units. Read-only

gain_boost¶

Whether the analog gain boost is enabled

A change to the gain boost will not affect the very next image captured. It’s unclear whether this is an inadequacy of Instrumental, or an underlying bug/feature of the library.