Hamamatsu Driver

Original 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.

This file was adapted to Python 3 and documented in the numpy style by Aquiles Carattino <aquiles@uetke.com>

copyright

Hazen Babcock

license

The MIT License

exception pynta.controller.devices.hamamatsu.hamamatsu_camera.DCAMException(message)

Bases: Exception

Monitor exceptions.

class pynta.controller.devices.hamamatsu.hamamatsu_camera.DCAM_PARAM_PROPERTYATTR

Bases: _ctypes.Structure

The dcam property attribute structure.

attribute

Structure/Union member

attribute2

Structure/Union member

cbSize

Structure/Union member

iGroup

Structure/Union member

iProp

Structure/Union member

iPropStep_Element

Structure/Union member

iProp_ArrayBase

Structure/Union member

iProp_NumberOfElement

Structure/Union member

iReserved1

Structure/Union member

iReserved3

Structure/Union member

iUnit

Structure/Union member

nMaxChannel

Structure/Union member

nMaxView

Structure/Union member

option

Structure/Union member

valuedefault

Structure/Union member

valuemax

Structure/Union member

valuemin

Structure/Union member

valuestep

Structure/Union member

class pynta.controller.devices.hamamatsu.hamamatsu_camera.DCAM_PARAM_PROPERTYVALUETEXT

Bases: _ctypes.Structure

The dcam text property structure.

cbSize

Structure/Union member

iProp

Structure/Union member

text

Structure/Union member

textbytes

Structure/Union member

value

Structure/Union member

class pynta.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.

copyData(address)

getData()

getDataPtr()

class pynta.controller.devices.hamamatsu.hamamatsu_camera.HamamatsuCamera(camera_id)

Bases: object

CAPTUREMODE_SEQUENCE = 1

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.

CAPTUREMODE_SNAP = 0

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? @return 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. @return 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. @return [frames, [frame x size, frame y size]].

getModelInfo(camera_id)

Returns the model of the camera @param camera_id The (integer) camera id number. @return 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. @return A dictionary of camera properties.

getPropertyAttribute(property_name)

Return the attribute structure of a particular property. FIXME (OPTIMIZATION): Keep track of known attributes? @param property_name The name of the property to get the attributes of. @return A DCAM_PARAM_PROPERTYATTR object.

getPropertyRW(property_name)

Return if a property is readable / writeable. @return [True/False (readable), True/False (writeable)].

getPropertyRange(property_name)

Return the range for an attribute. @param property_name The name of the property (as a string). @return [minimum value, maximum value].

getPropertyText(property_name)

Return the text options of a property (if any). @param property_name The name of the property to get the text values of. @return A dictionary of text properties (which may be empty).

getPropertyValue(property_name)

Return the current setting of a particular property. @param property_name The name of the property. @return [the property value, the property type].

initCamera()

isCameraProperty(property_name)

Check if a property name is supported by the camera. @param property_name The name of the property. return 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. @return [id of the first frame, .. , id of the last frame]

setPropertyValue(property_name, property_value)

Set the value of a property. @param property_name The name of the property. @param 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.

settrigger(mode)

shutdown()

Close down the connection to the camera.

startAcquisition()

Start data acquisition.

stopAcquisition()

Stop data acquisition.

class pynta.controller.devices.hamamatsu.hamamatsu_camera.HamamatsuCameraMR(camera_id)

Bases: pynta.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 new frames available when it is called.

Todo

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

Return list

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

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.

pynta.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.