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
¶ A uc480-supported Camera
-
close
()¶ Close the camera and release the associated image memory.
-
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: 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()
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.
- can specify other parameters of the capture as keyword arguments. These include (You) –
Other Parameters: - 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.
-
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
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.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: 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}¶
-
__init__
¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
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)
-
bytes_per_line
¶ Number of bytes used by each line of the image. Read-only
-
color_mode
¶ Color mode string. Read-only
-
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)
-
height
¶ Height of the camera image in pixels
-
id
¶ uEye camera ID number. Read-only
-
master_gain
¶ The master gain factor; 1.0 is the lowest gain.
-
max_height
¶ Max settable height of the camera image, given current binning/subpixel settings
-
max_master_gain
¶ Max value that
master_gain
can take
-
max_width
¶ Max settable width of the camera image, given current binning/subpixel settings
-
model
¶ Camera model number string. Read-only
-
serial
¶ Camera serial number string. Read-only
-
trigger_mode
¶ Trigger mode string. Read-only
-
width
¶ Width of the camera image in pixels
-
Changelog¶
Unreleased¶
- Added
gain_boost
,master_gain
,gamma
,blacklevel
, and manyauto-x
Facets/properties - Made 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