UUTrack.Controller.devices.hamamatsu.hamamatsu_camera.py

File taken from ZhuangLab

A ctypes based interface to Hamamatsu cameras. (tested on a sCMOS Flash 4.0).

The documentation is a little confusing to me on this subject.. I used c_int32 when this is explicitly specified, otherwise I use c_int.

Todo

I’m using the “old” functions because these are documented. Switch to the “new” functions at some point.

Todo

How to stream 2048 x 2048 at max frame rate to the flash disk? The Hamamatsu software can do this.

Section author: Hazen Babcock 10/13

exception UUTrack.Controller.devices.hamamatsu.hamamatsu_camera.DCAMException(message)

Bases: Exception

Camera exceptions.

class UUTrack.Controller.devices.hamamatsu.hamamatsu_camera.DCAM_PARAM_PROPERTYATTR

Bases: _ctypes.Structure

The dcam property attribute structure.

class UUTrack.Controller.devices.hamamatsu.hamamatsu_camera.DCAM_PARAM_PROPERTYVALUETEXT

Bases: _ctypes.Structure

The dcam text property structure.

class UUTrack.Controller.devices.hamamatsu.hamamatsu_camera.HCamData(size)

Bases: object

Hamamatsu camera data object.

Initially I tried to use create_string_buffer() to allocate storage for the data from the camera but this turned out to be too slow. The software kept falling behind the camera and create_string_buffer() seemed to be the bottleneck.

class UUTrack.Controller.devices.hamamatsu.hamamatsu_camera.HamamatsuCamera(camera_id)

Bases: object

Basic camera interface class. This version uses the Hamamatsu library to allocate camera buffers. Storage for the data from the camera is allocated dynamically and copied out of the camera buffers.

captureSetup()

Capture setup (internal use only). This is called at the start of new acquisition sequence to determine the current ROI and get the camera configured properly.

checkStatus(fn_return, fn_name='unknown')

Check return value of the dcam function call. Throw an error if not as expected?

Returns:The return value of the function.

fireTrigger()

Triggers the camera when in software mode.

getCameraProperties()

Return the ids & names of all the properties that the camera supports. This is used at initialization to populate the self.properties attribute.

Returns:A python dictionary of camera properties.

getFrames()

Gets all of the available frames. This will block waiting for new frames even if there new frames available when it is called.

Returns:[frames, [frame x size, frame y size]].

getModelInfo(camera_id)

Returns the model of the camera

Parameters:camera_id (int) – The camera id number. Returns:A string containing the camera name.

getProperties()

Return the list of camera properties. This is the one to call if you want to know the camera properties.

Returns:A dictionary of camera properties.

getPropertyAttribute(property_name)

Return the attribute structure of a particular property.

Parameters:property_name – The name of the property to get the attributes of. Returns:A DCAM_PARAM_PROPERTYATTR object.

Todo

FIXME (OPTIMIZATION): Keep track of known attributes?

getPropertyRW(property_name)

Return if a property is readable / writeable.

Returns:[True/False (readable), True/False (writeable)].

getPropertyRange(property_name)

Return the range for an attribute.

Parameters:property_name – The name of the property (as a string). Returns:[minimum value, maximum value].

getPropertyText(property_name)

Return the text options of a property (if any).

Parameters:property_name – The name of the property to get the text values of. Returns:A dictionary of text properties (which may be empty).

getPropertyValue(property_name)

Return the current setting of a particular property.

Parameters:property_name – The name of the property. Returns:[the property value, the property type].

initCamera()

Initialization. In this function the DCAM-API is called. :return:

isCameraProperty(property_name)

Check if a property name is supported by the camera.

Parameters:property_name – The name of the property. Returns:True/False if property_name is a supported camera property.

newFrames()

Return a list of the ids of all the new frames since the last check. This will block waiting for at least one new frame.

Returns:[id of the first frame, .. , id of the last frame]

setPropertyValue(property_name, property_value)

Set the value of a property.

Parameters:

• property_name – The name of the property.
• property_value – The value to set the property to.

setSubArrayMode()

This sets the sub-array mode as appropriate based on the current ROI.

setmode(mode)

Sets the acquisition mode of the camera.

shutdown()

Close down the connection to the camera.

startAcquisition()

Start data acquisition.

stopAcquisition()

Stop data acquisition.

class UUTrack.Controller.devices.hamamatsu.hamamatsu_camera.HamamatsuCameraMR(camera_id)

Bases: UUTrack.Controller.devices.hamamatsu.hamamatsu_camera.HamamatsuCamera

Memory recycling camera class.

This version allocates “user memory” for the Hamamatsu camera buffers. This memory is also the location of the storage for the np_array element of a HCamData() class. The memory is allocated once at the beginning, then recycled. This means that there is a lot less memory allocation & shuffling compared to the basic class, which performs one allocation and (I believe) two copies for each frame that is acquired.

Warning

There is the potential here for chaos. Since the memory is now shared there is the possibility that downstream code will try and access the same bit of memory at the same time as the camera and this could end badly.

Todo

Use lockbits (and unlockbits) to avoid memory clashes? This would probably also involve some kind of reference counting scheme.

getFrames()

Gets all of the available frames. This will block waiting for new frames even if there are new frames

Returns:[frames, [frame x size, frame y size]]

Todo

It does not always seem to block? The length of frames available when it is called can be zero. Are frames getting dropped? Some sort of race condition?

startAcquisition()

Allocate as many frames as will fit in 2GB of memory and start data acquisition.

stopAcquisition()

Stops the acquisition and releases the memory associated with the frames.

UUTrack.Controller.devices.hamamatsu.hamamatsu_camera.convertPropertyName(p_name)

“Regularizes” a property name. We are using all lowercase names with the spaces replaced by underscores. @param p_name The property name string to regularize. @return The regularized property name.