Welcome to AndorSDK2’s documentation!

Object-oriented, high-level interface for Andor cameras (SDK2), written in Cython.

Note

  • This is not a stand-alone driver. Andor’s proprietary drivers must be installed. The setup script expects to find libandor.so in /usr/local/lib/ (the driver’s default installation directory).

  • Andor provides a low-level, ctypes wrapper on their SDK, called atcmd. If available, it will be imported as Andor._sdk.

  • This documentation should be read along Andor’s Software Development Kit manual.

  • To build the extension:

    $ python2.7 setup_extension.py build_ext --inplace

Warning

This module is not thread-safe. If AcqMode.wait() is blocking a background thread, and another function call is made from the main thread, the main will block too.

Usage:

The camera is controlled via the top-level class Andor:

>>> from andor2 import Andor
>>> cam = Andor()

The Andor instance is just a container for other objects that control various aspect of the camera:

  • Info : camera information and available features
  • Temperature : cooler control
  • Shutter : shutter control
  • EM: electron-multiplying gain control
  • Detector: CCD control, including:
    • VSS: vertical shift speed
    • HSS: horizontal shift speed
    • ADC: analog-to-digital converter
    • OutputAmp: the output amplifier
    • PreAmp: pre-amplifier control
  • ReadMode: select the CCD read-out mode (full frame, vertical binning, tracks, etc.)
  • Acquire: control the acquisition mode (single shot, video, accumulate, kinetic)
Examples: 
>>> from andor2 import Andor
>>> cam = Andor()
>>> cam.Temperature.setpoint = -74  # start cooling
>>> cam.Temperature.cooler = True  
>>> cam.Detector.OutputAmp(1)       # use conventional CCD amplifier instead of electron multiplying
>>> cam.PreAmp(2)                   # set pre-amplifier gain to 4.9
>>> cam.exposure = 10               # set exposure time to 10 ms
>>> cam.ReadMode.SingleTrack(590,5) # set readout mode: single track, 5 pixels wide, centered at 590 pixels

>>> cam.Acquire.Video()             # set acquisition mode to video (continuous)
>>> data = cam.Acquire.Newest(10)   # collect latest 10 images as numpy array
>>> cam.Acquire.stop()

>>> cam.Acquire.Kinetic(10, 0.1, 5, 0.01)    # set up kinetic sequence of 10 images every 100ms
                                             # with each image being an accumulation of 5 images
                                             # taken 10ms apart
>>> cam.Acquire.start()                      # start acquiring
>>> cam.Acquire.wait()                       # block until acquisition terminates
>>> data = cam.Acquire.GetAcquiredData()     # collect all data
class andor2.ADC(self, HSS=None)

The analog-to-digital converter.

Some cameras have more than one ADC with a different dynamic range (e.g. 14 and 16 bits). The choice of ADC will affect the allowed horizontal shift speeds: see the ADConverters property for a list of valid comninations.

Usage: 
>>> adc.bit_depth   # dynamic range with current setting
>>> adc.channel     # currently selected ADC
>>> adc.channel = 1 # select other ADC
bit_depth

Returns the dynamic range of the currently selected AD converter.

channel

Set or query the currently selected AD converter.

list_ADConverters(self)
number

Returns the number of analog-to-digital converters.

class andor2.AcqMode(self, typ, name, code, caps)

Base class for acquisition modes AcqMode_XXX.

Accumulate(self, numberAccumulation, accumulationCycleTime, safe=True)

Switch to and configure Accumulate acquisition.

Kinetic(self, numberKinetics, kineticCycleTime, numberAccumulation=1, accumulationCycleTime=0, safe=True)

Switch to and configure Kinetic acquisition.

Newest(self, n=1, type=16)

Returns a data array with the most recently acquired image(s) in any acquisition mode.

Parameters:
  • number – number of images to retrieve
  • type – whether to return the data as 16 or 32-bits integers (16 [default] or 32)
Single(self)

Switch to Single mode.

Video(self)

Switch to Video mode and start acquiring.

images_in_buffer

Return information on the number of available images in the circular buffer.

This information can be used with GetImages to retrieve a series of images. If any images are overwritten in the circular buffer they no longer can be retrieved and the information returned will treat overwritten images as not available.

max_exposure

Return the maximum settable exposure time, in seconds.

new_images

Return information on the number of new images (i.e. images which have not yet been retrieved) in the circular buffer.

This information can be used with GetImages to retrieve a series of the latest images. If any images are overwritten in the circular buffer they can no longer be retrieved and the information returned will treat overwritten images as having been retrieved.

running

Query whether the camera is busy (ongoing acquisition or video).

save(self, filename, dataset, data, metadata_func=None)

Save data and associated metadata to an HDF5 file.

Parameters:
  • filename (string) – name of the H5 file (must already exist).
  • dataset_name (string) – name of the dataset (must not already exist).
  • data – any HDF5 compatible data (eg cam.Acquire.Newest())
The following metadata are also recorded:
  • acquisition mode
  • exposure time
  • EM gain
  • time (string).
size_of_circular_buffer

Return the maximum number of images the circular buffer can store based on the current acquisition settings.

start(self)

Start the acquisition.

status

Return the camera status code and corresponding message.

stop(self)

Stop an ongoing acquisition.

take_multiple_exposures(self, exposures)

Take a series of single images with varying exposure time.

Parameters:exposures – a tuple of exposure times.
Returns:a numpy array of length len(exposures).
wait(self, new_data=False)

Wait either for new data to be available or for the whole acquisition sequence (default) to terminate.

Parameters:new_data (bool) – if True, pause until a new image is available in the buffer. if False, pause until the whole acquisition terminates.

Press Ctrl+C to stop waiting.

Warning

This is not thread-safe!

class andor2.AcqMode_Accumulate(self, typ, name, code, caps)

Set the camera in Accumulate mode.

It’s a good idea to retrieve the data as 32bits integers.

save(self, filename, dataset_name, metadata_func=None)

Save data and associated metadata from the last completed acquisition to an HDF5 file.

Parameters:
  • filename (string) – name of the H5 file (must already exist).
  • dataset_name (string) – name of the dataset (must not already exist).
  • metadata_func – optional function to save more metadata. Takes a h5py.Group as unique argument.
The following metadata are also recorded:
  • acquisition mode
  • exposure time
  • EM gain
  • time (string)
  • accumulation number and cycle time
class andor2.AcqMode_Kinetic(self, typ, name, code, caps)

Kinetic mode.

Callable.

save(self, filename, dataset_name)

Save data and associated metadata from the last completed acquisition to an HDF5 file.

Parameters:
  • filename (string) – name of the H5 file (must already exist).
  • dataset_name (string) – name of the dataset (must not already exist).
  • metadata_func – optional function to save more metadata. Takes a Group as unique argument.
The following metadata are also recorded:
  • acquisition mode
  • exposure time
  • EM gain
  • time (string)
  • accumulation number and cycle time
  • Kineatic number and cycle time
class andor2.AcqMode_Single(self, typ, name, code, caps)

Set the camera in Single Acquisition mode.

The snapshot_count counter is reset when Single() is called, and incremented every time snap() (or equivalently start()) is called.

Arguments: None

snap(self, wait=True, type=16)

Take a single image.

Parameters:
  • wait – if True, wait for the acquisition to complete and return the data.
  • type – (16 or 32) whether to return the data as 16 or 32-bits integers (default: 16)
class andor2.AcqMode_Video(self, typ, name, code, caps)

Set the camera in Video (Run Till Abort) mode.

Arguments: None

class andor2.AcqModes(self, caps, ref={})

Container for the available AcqMode_XXX classes.

class andor2.Andor(self, init=True, lib='/usr/local/etc/andor/')

High-level, object-oriented interface for Andor cameras (SDK v2).

Usage:

The UI contains the following objects, most of which are self-explanatory:

  • Info : camera information and available features
  • Temperature : cooler control
  • Shutter : shutter control
  • EM: electron-multiplying gain control
  • Detector: CCD control, including:
    • VSS: vertical shift speed
    • HSS: horizontal shift speed
    • ADC: analog-to-digital converter
    • OutputAmp: the output amplifier
    • PreAmp: pre-amplifier control
  • ReadMode: select the CCD read-out mode (full frame, vertical binning, tracks, etc.)
  • Acquire: control the acquisition mode (single shot, video, accumulate, kinetic)
Upon initialisation, the camera is set by default to:
  • Acquisition mode: single shot
  • Readout mode: full image
  • EM gain: off
  • Vertical shift speed: maximum recommanded
  • Horizontal shift speed: second fastest.

Initialize the camera and returns a user-friendly interface.

Parameters:
  • init (bool) – set to False to skip the camera initialisation (if it has been initialised already).
  • lib – location of the Andor library.
acquisitionTimings

Returns the actual exposure, accumulation and kinetic cycle times, in seconds.

exposure

Query or set the exposure time, in ms.

andor2.AvailableCameras()

Return the total number of Andor cameras currently installed.

It is possible to call this function before any of the cameras are initialized.

class andor2.Capabilities(self)

Container for camera capabilities.

Retrieves and parses the SDK’s AndorCapabilities struct, returning dictionaries indicating which capabilities are available.

The following sets of capabilities are completely parsed:
  • AcqModes
  • ReadModes
  • ReadModesWithFrameTransfer
  • TriggerModes
  • CameraType
  • PixelMode
  • PCICard
  • EMGain
The following are only partially parsed:
  • SetFunctions (see also Fan and Temperature)
  • GetFunctions (see also Fan and Temperature)
  • Features

and some of the relevant capabilities are present in the Fan and Temperature dictionaries.

Finally, when available, AcqMode, ReadMode and TriggerMode objects are created as the properties _AcqModes, _ReadModes and _TriggerModes.

class andor2.Capability(self, typ, name, code, caps)

A general class for camera capabilities.

This is mostly a convenience class that allows to programmatically declare the available capabilities.

Parameters:
  • typ – Capability type (eg ReadMode, AcqMode...)
  • name – Capability name
  • code – the Capability identifier (eg sdk.AC_READMODE_FVB)
  • caps – the element of the Capability structure corresponding to typ (eg caps.ulReadModes)
class andor2.Detector(self)

Represents the EMCCD sensor.

In addition to providing properties to access the pixel size (in um), sensor dimensions (in pixels), and bit depth, this class is also a container for:

  • the horizontal shift speed
  • the vertical shift speed
  • the output amplifier
  • the preamplifier
  • the A/D converter
bit_depth
class andor2.EM(self, cam)

Controls the electron multiplying gain.

Usage: 
>>> EMGain.on()       # Turn EM gain on 
>>> EMGain.gain = 123 # Set gain
>>> EMGain.off()       # Turn EM gain off

Note: setting the gain to 0 is the same as switching it off.

advanced

Turns on and off access to higher EM gain levels.

Typically optimal signal to noise ratio and dynamic range is achieved between x1 to x300 EM Gain. Higher gains of > x300 are recommended for single photon counting only. Before using higher levels, you should ensure that light levels do not exceed the regime of tens of photons per pixel, otherwise accelerated ageing of the sensor can occur.

gain

Set or query the current setting.

is_on

Query whether the EM gain is on.

mode

The EM Gain mode can be one of the following possible settings:

  • 0: The EM Gain is controlled by DAC settings in the range 0-255. Default mode.
  • 1: The EM Gain is controlled by DAC settings in the range 0-4095.
  • 2: Linear mode.
  • 3: Real EM gain

To access higher gain values (if available) it is necessary to enable advanced EM gain, see SetEMAdvanced.

range

Query the range of valid EM gains.

status
class andor2.HSS(self, OutAmp)

Controls the horizontal shift speed.

The HSS depends on the output amplifier (which must be passed to the constructor) and on the analog-to-digital converters (which is created within the HSS object).

Usage: 
>>> print hss.speeds  # query available settings
>>> hss(0)            # set speed to hss.speeds[0]
Parameters:OutAmp – OutputAmp instance.
info
number

Return the number of HS speeds available.

speeds

Return a dictionary of available speeds {index: speed (MHz),... }.

class andor2.Info(self)

Information about the camera.

Includes:
  • serial number
  • controller card model
  • capabilities (see Capabilities for details)
class andor2.OutputAmp(self)

The output amplifier.

Some cameras have a conventional CCD amplifier in addition to the EMCCD amplifier, although often the EMCCD amplifier is used even with the gain switched off, as it is faster.

active

Return the index of the current output amplifier.

description(self, index=None)

Return a string with the description of the currently selected amplifier.

Options: - index: select a different amplifier

max_speed

Maximum available horizontal shift speed for the amplifier currently selected.

number

Returns the number of available amplifier.

class andor2.PreAmp(self)

The pre-amplifier gain.

Callable.

Usage: 
>>> preamp.gain # current setting
>>> preamp()    # choose the gain from a menu
gain

Current pre-amplifier gain.

list_gains(self)

Return a dictionary {index: gain, ...} of the available settings.

class andor2.ReadMode(self, typ, name, code, caps)

Base class for ReadMode_XXX classes.

See also

class andor2.ReadMode_FullVerticalBinning(self, typ, name, code, caps)

Full Vertical Binning mode.

class andor2.ReadMode_Image(self, typ, name, code, caps)

Full image mode.

class andor2.ReadMode_MultiTrack(self, typ, name, code, caps)

Multi-track mode.

class andor2.ReadMode_RandomTrack(self, typ, name, code, caps)

RandomTrack mode.

data_to_image(self, data)

Forms an image from Random Track data.

class andor2.ReadMode_SingleTrack(self, typ, name, code, caps)

Single Track mode.

centre

Set or query the track centre (can be called during acquisition).

height

Set or query the track height (can be called during acquisition).

position

Return a tuple (centre, height).

class andor2.ReadModes(self, caps, ref={})

This class is just container for the available ReadMode_XXX classes

class andor2.Shutter(self, cam)

Controls the internal shutter.

Use Open(), Closed() or Auto(), or Set(TTL, mode. closingtime openingtime) for custom operation. The opening/closing times ar set to minimum by default.

Auto(self)
MinTransferTimes
Set(self, mode, ttl=None, closingtime=None, openingtime=None)
class andor2.Temperature(self, cam)

Manages the camera cooler.

Default temperature setpoint is -65C.

cooler

Query or set the state of the TEC cooler (True: ON, False: OFF).

precision

Return the number of decimal places to which the sensor temperature can be returned.

range

Return the valid range of temperatures in centigrade to which the detector can be cooled.

read

Returns the temperature of the detector to the nearest degree, and the status of cooling process.

setpoint

Return the current setpoint.

class andor2.VSS(self)

Controls the vertical shift speed (VSS).

Upon initialisation, it defaults to the fastest recommanded speed. Call the class with no arguments to select a different speed.

Usage: 
>>> vss.speeds      # Available settings
>>> vss(7)          # Set speed to no 7 (fastest)
>>> vss.voltage = 4 # Increase clock voltage to redude CIC noise at high speed.
fastestRecommended

Query the fastest recommended speed (in us).

info
voltage

Set or query the vertical clock voltage.

If you choose a high readout speed (a low readout time), then you should also consider increasing the amplitude of the Vertical Clock Voltage. There are five levels of amplitude available for you to choose from: Normal (0); +1, +2, +3, +4. Exercise caution when increasing the amplitude of the vertical clock voltage, since higher clocking voltages may result in increased clock-induced charge (noise) in your signal. In general, only the very highest vertical clocking speeds are likely to benefit from an increased vertical clock voltage amplitude.

andor2.andorError(error_code, ignore=(), info=())

andorError(error_code, ignore = (), info = ())

Wrap each SDK function in andorError to catch errors. Error codes in ‘ignore’ will be silently ignored, while those is ‘info’ will trigger and AndorInfo exception. ??? not for now, not sure what to do with those... for now they will just print the error message

andor2.rollover(func)

Decorator that correct for the ADC roll-over by replacing zeros with 2**n-1 in image data.

andor2.while_acquiring(func)

Decorator that allows calling SDK functions while the camera is acquiring in Video mode (acquisition will stopped and restarted).

Indices and tables