Thorlabs DCx (UC480) Cameras¶
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
, orueye_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 withinC:\Program Files\Thorlabs\Scientific Imaging\DCx Camera Support\Develop\Lib
.Run
pip install pywin32 nicelib
on the command line to install thepywin32
andnicelib
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 sometimesuint16
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:
- 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()
thenget_captured_image()
. Seeget_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. ThisChangeEvent
is a namedtuple withname
,old
, andnew
fields.name
is the facet’s name,old
is the old value, andnew
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. Ifforce
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()
andget_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 withget_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:
- 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.
- gamma¶
The gamma correction value (1.0-10.0)
- property height¶
Height of the camera image in pixels
- property id¶
uEye camera ID number. Read-only
- master_gain¶
The master gain factor; 1.0 is the lowest gain.
- property max_height¶
Max settable height of the camera image, given current binning/subpixel settings
- property max_master_gain¶
Max value that
master_gain
can take
- property max_width¶
Max settable width of the camera image, given current binning/subpixel settings
- property model¶
Camera model number string. Read-only
- pixelclock¶
- pixelclock_default¶
- property serial¶
Camera serial number string. Read-only
- property trigger_mode¶
Trigger mode string. Read-only
- property width¶
Width of the camera image in pixels
Changelog¶
Unreleased¶
Added
gain_boost
,master_gain
,gamma
,blacklevel
, and manyauto-x
Facets/propertiesMade sure framerate is set before exposure time
Version 0.4.1¶
Fixed AOI-related error on calling
start_live_video()
Version 0.4¶
Converted to use new-style Instrument initialization
Added error code to UC480 errors
Converted to use new-style Params
Version 0.3¶
Removed deprecated usage of ‘is_SetImageSize’
Ported driver to use
NiceLib
instead ofctypes
Added subsampling support
Added gain setting
Added triggering support
Added support for using IDS library
Version 0.2¶
Initial driver release