andor3.utils module

Utility methods for image data processing.

If the (optional) numba library is installed, some methods are able to be accelerated using the numba just-in-time (JIT) compiler. In the absence of the library, alternative numpy-based implementations are used. The _np_ and _nb_ prefixes denote the numpy or numba implementations, respectively. These should not be called directly, instead, use the non-prefixed version of the methods documented here which will choose the appropriate implementation for you.

class andor3.utils.FrameDump(cam, completion_callback, fvb=False)

Bases: object

Class which can start an acquisition, then notify on the conclusion of the acquisition event with all the acquired data.

This acquisition style pre-allocates all memory for the frame data and thus can use a large amount of RAM. Ensure your system has the available RAM for the number and size of images you wish to acquire.

The callback method should take the form of completion_callback(data, timestamps), where data is a numpy array of the image data, and timestamps is a numpy array of timestamps for the data if metadata is enabled (zeros otherwise).

If fvb=True, then the data provided to the callback method is a 2-dimensional numpy array, with axes being (n, column). Otherwise, the data is a 3-dimensional numpy array with axes (n, row, column).

Parameters

• cam – Andor3 camera to use for frame acquisition.

• completion_callback – Function to call when acquisition is completion.

• fvb – Perform full-vertical-binning on the image data.

start(n_images=None, fvb=None)

Start the acquisition process.

A maximum of n_images frames will be acquired. If set to None (default), the number of images will be determined by the camera’s FrameCount and AccumulateCount properties.

Full-vertical binning can be enabled or disabled using the fvb parameter.

Parameters

• n_images – Maximum number of images to capture.

• fvb – Perform full-vertical-binning on the image data.

stop()

Stop the camera.

class andor3.utils.FrameServer(cam, frame_callback, completion_callback=None, fvb=False, frame_rate_max=None)

Bases: object

Class which can start an acquisition, then serve each frame to a given function.

The frame callback method should take the form of frame_callback(n, data, timestamp), where n is the frame number (zero-based) in the acquisition series, data is the image data, and timestamp is the metadata timestamp if metadata is enabled, else zero.

The optional completion callback method should take the form of completion_callback(n), where n is the number of frames which were acquired.

If fvb=True, then the data provided to the callback method is a 1-dimensional numpy array. Otherwise, the data is a 2-dimensional numpy array with axes (row, column).

The rate that frames are served can be limited using the frame_rate_max parameter. A value of zero or None will not restrict the frame rate. Note that this is the rate of frames served, not the actual acquisition rate.

Parameters

• cam – Andor3 camera to use for frame acquisition.

• frame_callback – Function to call on each frame acquisition event.

• completion_callback – Function to call when acquisition is completed.

• fvb – Perform full-vertical-binning on the image data.

• frame_rate_max – Maximum frame serving rate in frames per second.

start(nbuffers=10, fvb=None, frame_rate_max=None)

Start the camera and begin serving acquired frames.

A circular series of nbuffers buffers are used, and the returned image data may be only a view of the raw camera buffer memory (not copied). If the image data is to be retained for long periods, it should be copied into its own memory, either indirectly by a mathematical operation or explicitly by something like img = data.copy(). If the fvb=True option is used, the served data is computed from the buffer and so this is not an issue.

Full-vertical binning can be enabled by setting fvb=True.

The rate that frames are served can be limited using the frame_rate_max parameter. A value of zero or None will not restrict the frame rate. Note that this is the rate of frames served, not the actual acquisition rate.

Parameters

• nbuffers – Number of frames in the circular image buffer.

• fvb – Perform full-vertical-binning on the image data.

• frame_rate_max – Maximum acquisition rate in frames per second.

stop()

Stop the FrameServer.

andor3.utils.decode_image_data(data_raw, encoding, width, height, stride)

Decode raw bytes into an image.

The decoding process needs to know the encoding of the data, which should be one of "Mono12", "Mono12Packed", "Mono16", or "Mono32".

The height and width parameters determine the shape of the returned image data in pixels. There may be redundant padding bytes at the end of rows of pixels, in which case the stride parameter (in bytes) may be larger than expected given the width and bit-depth of the image. Additionally, padding at the end of the image data may be optionally be present, which is used by the Andor subsystem to align the data to 8-byte boundaries.

If metadata is enabled and present in data_raw it will be ignored. To preserve information in the metadata, see the decode_image_with_metadata() function.

Parameters

• data_raw – Raw image byte data.

• encoding – String describing the image encoding method.

• width – Width of the resulting image, in pixels.

• height – Height of the resulting image, in pixels.

• stride – Number of bytes used to encode a single row of pixels.

Returns

Image as 2D numpy array with shape (width, height).

andor3.utils.decode_image_with_metadata(data_raw)

Decode raw bytes into an image, using the included frame info and timestamp metadata.

A tuple of the decoded image (as 2D numpy array) and timestamp (in clock ticks) will be returned.

Note that this function may be useless, as it is not clear that any camera supports the MetadataFrameInfo property, and thus there may never be the metadata required to determine the image dimensions etc.

Parameters

data_raw – Raw byte data containing image and metadata.

Returns

Image and metadata timestamp.

andor3.utils.decode_metadata(metadata_raw)

Decode a frame metadata block.

If metadata is enabled for image frames, then the image data contains additional fields appended to the pixel data. The information is contained in three different block types:

• FrameInfo (16 bytes) Height (uint16), width (uint16), [unused] (byte), encoding (uint8),

  stride (uint16), chunk_id=7 (uint32), chunk_length (uint32).

• Ticks (16 bytes) Ticks (uint64), chunk_id=1 (uint32), chunk_length (uint32).

• FrameData (variable size) Image (stride × height + padding bytes), chunkid=0 (uint32),

  chunk_length (uint32).

Values are stored as little-endian. The values of chunk_length do not include the length field itself, so are 4-bytes less than the actual chunk size.

The timestamp is stored as clock ticks since the camera startup. The frequency of the camera clock (in Hz) can be obtained using the TimeStampClockFrequency property.

This function should be able to handle the image data being missing, in the case where the image data has been split from the appended metadata. If the image data is missing, None will be returned in place of the image data.

The returned dictionary of metadata will have the fields height, width, stride, encoding (as string), and timestamp. The image data will be the raw byte stream as a numpy array of size (stride × height + padding bytes). The fields will only be present in the dictionary if the relevant blocks have been enabled, for example, buy settings the Metadata and MetadataTimestamp properties to True.

Note that the MetadataFrameInfo property and data block format is documented in the metadata section of the Andor SDK3 documentation, but is not actually listed as a valid feature for any camera model. The Zyla used for testing did not implement MetadataFrameInfo, but the decoding of the FrameInfo block should work if a camera happens to support it.

Parameters

metadata_raw – Image data containing metadata.

Returns

Tuple of dictionary of metadata and bytes of raw image data.

andor3.utils.fvb(image)

Perform full-vertical-binning (FVB) of image data.

image is a 2-dimensional numpy array of image data in uint16 or uint32 format, where the first dimension indexes the column (width, x-coordinate) of the image, the second the row (height, y-coordinate).

The vertically binned data will be returned as the mean as a 1-dimensional array of float32.

Parameters

image – Numpy array of image data in uint16 or uint32 format.

Returns

Vertically binned array of np.float32.

andor3.utils.fvb_images(images)

Perform full-vertical-binning (FVB) of a set of image data.

images is a 3-dimensional numpy array of image data in uint16 or uint32 format, where the first dimension indexes the image number, the second the column (width, x-coordinate) of the image, the third the row (height, y-coordinate).

The vertically binned data will be returned as the mean as a 2-dimensional array of float32.

Parameters

image – Numpy array of image data in uint16 or uint32 format.

Returns

Vertically binned array of np.float32.

andor3.utils.unpack_uint12(packed_data)

Unpacks the 12BitPacked image format into an array of unsigned 16-bit integers.

packed_data is numpy array of np.uint8, consisting of pairs of 12-bit numbers packed into 3 byte sequences.

Parameters

packed_data – Numpy array of np.uint8 containing 12BitPacked image data.

Returns

Image data as a numpy array of np.uint16.