andor3.andor3 module

class andor3.andor3.Andor3(device_index: int = 0)

Bases: object

Initialise the Andor SDK3 and attempt to open a connection to a camera.

If device_index is None, camera initialisation won’t be attempted, however the number of cameras attached may be queried with device_count, and a camera subsequently opened with open().

Parameters

device_index – Index (zero-based) of attached camera to open.

close() → None

Close any currently opened camera.

command(feature: str) → None

Activate a command type camera feature.

A command is a camera feature which takes no parameters, for example "AcquisitionStart", or "SoftwareTrigger".

Parameters

feature – String describing the camera feature.

decode_image(data_raw)

Decode an image from the raw data byte stream.

A tuple of the decoded image and timestamp will be returned. If metadata is not present, the timestamp will be zero.

Parameters

data_raw – Raw image byte data, with optional metadata.

Returns

Tuple of image and timestamp.

describe_features()

Generate a string representation of all available camera features and their values.

flush()

Destroy any existing image buffers.

getBool(feature: str) → bool

Get the value for a given boolean feature.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

Value for the feature.

getEnumCount(feature: str) → int

Get the number of possible values available to an enumerated type feature.

See the FEATURES dictionary for possible feature values.

The methods :meth`isEnumIndexImplemented` and isEnumIndexAvailable() can be used to check if a value is implemented for the current camera model, and whether the camera is currently in a mode where the value is able to be selected. The string describing the option corresponding to the enumeration index can be obtained using getEnumStringByIndex().

Parameters

feature – String describing the camera feature.

Returns

Maximum value for the feature.

getEnumIndex(feature: str) → int

Get the numerical index value for a given enumerated type feature.

See the FEATURES dictionary for possible feature values.

To obtain the value in the form of its description string, use cam.getEnumStringByIndex(feature, cam.getEnumIndex(feature)).

Parameters

feature – String describing the camera feature.

Returns

Value for the feature.

getEnumStringByIndex(feature: str, index: int) → str

Get the string representation corresponding to the enumeration-type feature’s numerical index.

Parameters

• feature – String describing the camera feature.

• index – Index of enumeration for the feature.

Returns

String describing the enumeration index.

getFloat(feature: str) → float

Get the value for a given floating point number feature.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

Value for the feature.

getFloatMax(feature: str) → float

Get the maximum allowed value for a given floating point number feature.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

Maximum allowed value for the feature.

getFloatMin(feature: str) → float

Get the minimum allowed value for a given floating point number feature.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

Minimum allowed value for the feature.

getInt(feature: str) → int

Get the value for a given integer feature.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

Value for the feature.

getIntMax(feature: str) → int

Get the maximum allowed value for a given integer feature.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

Maximum allowed value for the feature.

getIntMin(feature: str) → int

Get the minimum allowed value for a given integer feature.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

Minimum allowed value for the feature.

getString(feature: str) → str

Get the value for a given string feature.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

Value for the feature.

getStringMaxLength(feature: str) → int

Get the maximum possible string length for a string-type feature’s values.

Parameters

feature – String describing the camera feature.

Returns

Maximum string length for feature values.

get_feature(feature: str, errors='warn')

Queries the value of a camera feature, without needing to know the particular data type.

Internally, calls the appropriate getBool(), getInt(), getFloat(), getString() or getEnumIndex()/getEnumStringByIndex() for feature and returns the value. Enum types return a tuple of (index, string).

See FEATURES for a list of camera features.

By default any errors when querying the value are warned about (errors="warn"). To instead raise exceptions, set errors="raise". To silence errors completely, set errors="ignore". If a value is unable to be queried and errors are ignored, None will be returned.

Parameters

• feature – String matching the camera feature to query.

• errors – Action to take on errors, either ignore, warn, or raise.

Returns

Value of the requested feature.

isEnumIndexAvailable(feature: str, index: int) → bool

Determine if a given value for an enumeration type feature is currently available to be selected.

See the FEATURES dictionary for possible feature values.

Use getEnumCount() to determine the maximum value allowed for the enumeration index. The method :meth`isEnumIndexImplemented` can be used to check if the value is implemented for the current camera model. The string describing the option corresponding to the enumeration index can be obtained using getEnumStringByIndex().

Parameters

• feature – String describing the camera feature.

• index – Index of enumeration for the feature.

Returns

Boolean describing if the value for the feature is currently available.

isEnumIndexImplemented(feature: str, index: int) → bool

Determine if a given value for an enumeration type feature is implemented for the current camera.

See the FEATURES dictionary for possible feature values.

The method isEnumIndexAvailable() can be used to check if the camera is currently in a mode where the value is able to be selected. The string describing the option corresponding to the enumeration index can be obtained using getEnumStringByIndex().

Parameters

• feature – String describing the camera feature.

• index – Index of enumeration for the feature.

Returns

Boolean describing if the value for the feature is implemented for the camera.

isImplemented(feature: str) → bool

Check if the given feature is implemented on the currently opened camera.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

True if feature is implemented, or False otherwise.

isReadOnly(feature: str) → bool

Check if the given feature is read-only.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

True if feature is read-only, or False otherwise.

isReadable(feature: str) → bool

Check if the given feature is currently readable.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

True if feature is readable, or False otherwise.

isWritable(feature: str) → bool

Check if the given feature is currently writable.

See the FEATURES dictionary for possible feature values.

Parameters

feature – String describing the camera feature.

Returns

True if feature is writable, or False otherwise.

max(feature: str, errors='warn')

Queries the maximum allowed value of a camera feature, without needing to know the particular data type.

Internally, calls the appropriate getIntMax or getFloatMax for feature and returns the value.

See FEATURES for a list of camera features.

By default any errors when querying the value are warned about (errors="warn"). To instead raise exceptions, set errors="raise". To silence errors completely, set errors="ignore". If a value is unable to be queried and errors are ignored, None will be returned.

Parameters

• feature – String matching the camera feature to query.

• errors – Action to take on errors, either ignore, warn, or raise.

Returns

Maximum allowed value of the requested feature.

min(feature: str, errors='warn')

Queries the minimum allowed value of a camera feature, without needing to know the particular data type.

Internally, calls the appropriate getIntMin or getFloatMin for feature and returns the value.

See FEATURES for a list of camera features.

By default any errors when querying the value are warned about (errors="warn"). To instead raise exceptions, set errors="raise". To silence errors completely, set errors="ignore". If a value is unable to be queried and errors are ignored, None will be returned.

Parameters

• feature – String matching the camera feature to query.

• errors – Action to take on errors, either ignore, warn, or raise.

Returns

Minimum allowed value of the requested feature.

open(device_index: int = 0) → None

Open an attached camera device by its numerical device index.

Parameters

device_index – Index (zero-based) of the camera to open.

queueBuffer(count: int = 1) → None

Prepare a memory buffer for image storage by the Andor SDK3.

Note that any previously prepared buffers will be destroyed. The Buffer sizes are created to match the currently set image size and bit depth, so the image settings should be configured prior to buffer creation.

Multiple buffers may be prepared in a single call by using the count parameter.

Parameters

count – Number of buffers to prepare.

registerFeatureCallback(feature: str, callback: Callable, args: tuple = (), kwargs: dict = {}) → None

Register a method to call when the selected event occurs.

The Andor library will call the callback immediately so that the callback handler can perform any action on the initial value etc. However, I think the Andor library ends up calling the callback function twice when triggered which is likely a bug.

Parameters

• feature – String describing the feature event.

• callback – Method to call when event occurs.

• args – Tuple of positional arguments to pass to callback.

• kwargs – Dictionary of keyword arguments to pass to callback.

setBool(feature: str, value: bool) → None

Set the value for a given boolean feature.

See the FEATURES dictionary for possible feature values.

Parameters

• feature – String describing the camera feature.

• value – New value for the feature.

setEnumIndex(feature: str, value: int) → None

Set the value for a given enumerated type feature by its numerical index.

See the FEATURES dictionary for possible feature values.

Use getEnumCount() to determine the maximum value allowed for the enumeration index. The methods :meth`isEnumIndexImplemented` and isEnumIndexAvailable() can be used to check if the value is implemented for the current camera model, and whether the camera is currently in a mode where the value is able to be selected. The string describing the option corresponding to the enumeration index can be obtained using getEnumStringByIndex().

Parameters

• feature – String describing the camera feature.

• value – New value for the feature.

setEnumString(feature: str, value: str) → None

Set the value for a given enumerated type feature using its string representation.

See the FEATURES dictionary for possible feature values.

The string describing the option corresponding to an enumeration index can be obtained using getEnumStringByIndex().

Parameters

• feature – String describing the camera feature.

• value – New value for the feature.

setFloat(feature: str, value: float) → None

Set the value for a given floating point number feature.

See the FEATURES dictionary for possible feature values.

Parameters

• feature – String describing the camera feature.

• value – New value for the feature.

setInt(feature: str, value: int) → None

Set the value for a given integer feature.

See the FEATURES dictionary for possible feature values.

Parameters

• feature – String describing the camera feature.

• value – New value for the feature.

setString(feature: str, value: str) → None

Set the value for a given string type feature.

See the FEATURES dictionary for possible feature values.

Parameters

• feature – String describing the camera feature.

• value – New value for the feature.

set_feature(feature: str, value, errors='warn')

Sets the value of a camera feature, without needing to know the particular data type.

Internally, calls the appropriate setBool, setInt, setFloat, setString or setEnum for feature. Enum types may be set using either the index or string representation.

See FEATURES for a list of camera features.

By default any errors when setting the value are warned about (errors="warn"). To instead raise exceptions, set errors="raise". To silence errors completely, set errors="ignore". If a value is unable to be set and errors are ignored, None will be returned.

Parameters

• feature – String matching the camera feature to set.

• value – New value of the feature to set.

• errors – Action to take on errors, either ignore, warn, or raise.

start()

A shortcut for calling cam.command("AcquisitionStart").

stop()

A shortcut for calling cam.command("AcquisitionStop").

Any errors will be ignored (for example, if the camera is already stopped).

unregisterFeatureCallback(feature: str, callback: Callable) → None

Unregister a previously registered callback method.

The callback must have been previously registered to the feature using registerFeatureCallback().

Parameters

• feature – String describing the feature event.

• callback – Method previously registered for callbacks.

waitBuffer(timeout: int = 4294967295, copy: bool = False, requeue: bool = False) → numpy.ndarray

Wait for the Andor SDK3 to fill a previously prepared memory buffer and return the data.

The timeout parameter specifies how long to wait (in milliseconds) for the buffer to be filled. A value of INFINITY will wait indefinitely, while a value of zero will return immediately if there is no buffer currently filled with new image data.

Setting the copy=True parameter will make a copy of the data from the memory buffer, otherwise only a reference to the buffer memory will be used. Copying is slower (and uses more memory), but may be useful if the memory buffer is at risk of being overwritten by new data, for example if requeue=True is set, or queueBuffer() is called to create a new buffer space.

Setting the requeue=True parameter will allow the Andor SDK3 to re-use the buffer space in a circular-buffer type arrangement. It’s may be a good idea to also set copy=True to ensure the data isn’t overwritten by the camera before it’s used.

The raw data is returned as a 1-dimensional numpy array of bytes (uint8).

Parameters

• timeout – Timeout (in milliseconds).

• copy – Copy the image data instead of returning a reference.

• requeue – Re-queue the image buffer for use again.

Returns

1-dimensional numpy array of raw image data.

camera_handle

The “camera handle” used by the SDK to identify the currently opened camera.

device_count

Number of detected cameras attached to the system.

property features

A list of feature names available to the currently opened camera.

software_version

Version number of the SDK3 library in use.