slmsuite.hardware.cameras.xenics.Cheetah640

class Cheetah640(virtual=False, temperature=None, pitch_um=(20, 20), verbose=True, **kwargs)

Bases: Camera

Xeneth’s Cheetah640 camera.

xeneth

Object to talk with the Xeneth SDK.

Type:

windll

cam

Object to talk with the desired camera.

Type:

ptr

profile

Current pre-configured operation mode.

'triggered' - Captures on external trigger

'free' - Continuous capture

Type:

{‘triggered’, ‘free’}

frame_size

Size of the frame in bytes for use in grabbing data for the buffer.

Type:

int

frame_buffer

Buffer used to grab data from the camera and sdk interface.

Type:

c_ushort array

last_capture

Previous capture by get_image()

Type:

numpy.ndarray

last_tag

Frame tag of last capture

Type:

numpy.uint16

last_process_time

Time to process last frame

Type:

float

filters

Dictionary with enabled filters. See Xeneth documentation for more information.

Type:

dict

Methods

abort_capture	Cancels any long, live frame captures
autoexpose_xenics	Adds Xenics autogain and offset filters to current filter stack.
autoexposure	Sets the exposure of the camera such that the maximum value is at set_fraction of the dynamic range.
autofocus	Finds optimal focus when scanning over some variable z.
autogain	Adds autogain and offset to current filter stack.
close	See Camera.close().
close_filters	Deletes all current tracked filters in the stack.
configure	Loads pre-stored imaging profile from XC_SaveSettings XCF file
enable_cooling	Enables/disables TEC and high fan speed.
enable_frametags	Adds captured frame number to first two pixels of an image.
flush	See Camera.flush()
get_exposure	Get the frame integration time in seconds.
get_frame_footer_length	Get the length of software frame tags.
get_frame_number	Get number of captured frames since start_capture().
get_image	Capture, process, and return images from a camera.
get_image_hdr	Often, the necessities of precision applications exceed the bitdepth of a camera.
get_image_hdr_analysis	Analyzes raw data for High Dynamic Range (HDR) imaging multiple exposures each with increasing exposure time.
get_images	Grab image_count images in succession.
get_property_status	List and get status of all addressable properties on camera.
get_temperature	Get the camera temperature setpoint.
info	Abstract method to load information about what cameras are available.
is_capturing	Checks if currently capturing
live	Creates and displays an IPython camera viewer.
pickle	Returns a dictionary containing selected attributes of this class.
plot	Plots the provided image.
save	Saves the dictionary returned from pickle() to a file like "path/name_id.h5".
set_buffer_api	Set the number of API-facing buffer frames.
set_exposure	Set the frame integration time in seconds.
set_framerate	Set the camera framerate.
set_low_gain	Enables or disables low gain mode.
set_readout_orientation	Sets direction of pixel readout from focal plane.
set_temperature	Set the camera temperature setpoint.
set_timeout_api	Set the get_frame time allowed before issuing E_NOFRAME error.
set_woi	See Camera.set_woi()
setup	Sample pre-configured imaging profiles.
setup_grabber	Setup frame grabber capture mode.
setup_input_trigger	Configure capture control via triggering.
setup_output_trigger	Configures output trigger.
snap	Start capture, grab image, stop capture.
start_capture	Initiates the current capture run
stop_capture	Terminates the current capture run
test	Tests the core hardware methods of Camera.

Attributes

bitresolution

__init__(virtual=False, temperature=None, pitch_um=(20, 20), verbose=True, **kwargs)

Initialize camera. Default profile is 'free'.

Parameters:

• virtual (bool) – Whether or not the camera is virtual.

• temperature (float or None) – Temperature in degrees celcius to set on startup. None defaults to no cooling.

• pitch_um ((float, float) OR None) – Fill in extra information about the pixel pitch in (dx_um, dy_um) form to use additional calibrations. Defaults to 20 micron square pixels.

• verbose (bool) – Whether or not to print camera initialization information.

• **kwargs – See Camera.__init__() for permissible options.

Raises:

RuntimeError – If the camera is not reachable.

close()

See Camera.close().

get_property_status(save_file_path=None, verbose=True)

List and get status of all addressable properties on camera.

Parameters:

• save_file_path (str or None) – If not None, the property status results will be saved to this path.

• verbose (True) – Prints property results if True.

configure(format_file)

Loads pre-stored imaging profile from XC_SaveSettings XCF file

Parameters:

format_file (str) – Path to XCF file containing format information

set_framerate(framerate)

Set the camera framerate.

Parameters:

frame (int) – The framerate in fps.

get_frame_footer_length()

Get the length of software frame tags.

Return type:

int

set_buffer_api(frames=64)

Set the number of API-facing buffer frames.

Parameters:

frames (int) – Number of buffer frames to allocate.

set_timeout_api(timeout_ms=10000)

Set the get_frame time allowed before issuing E_NOFRAME error.

Warning

Implementation unfinished and untested.

Parameters:

timeout_ms (int) – Time in ms to wait for blocking frame capture.

set_temperature(temp_c)

Set the camera temperature setpoint.

Parameters:

temp_c (float) – Temperature in degrees celcius to set on startup.

get_temperature()

Get the camera temperature setpoint.

Returns:

Temperature in degrees celcius to set on startup. -1 if the temperature could not be read.

Return type:

float

set_readout_orientation(flip_x=True, flip_y=True)

Sets direction of pixel readout from focal plane.

Parameters:

• flip_x (tuple(bool)) – Whether a flip will be applied in the X or Y directions.

• flip_y (tuple(bool)) – Whether a flip will be applied in the X or Y directions.

enable_frametags(enable=False)

Adds captured frame number to first two pixels of an image. Disabled by default to prevent issues with autoexposure.

Parameters:

enable (bool) – Whether to enable or disable.

setup_input_trigger(mode=0, delay=0, source=0, skip=0, fpt=1, verbose=False)

Configure capture control via triggering.

Parameters:

• mode (int) –

  Trigger properties.

  0 means free running.

  1 means level.

  2 means rising edge.

  3 means falling edge.

• delay (float) – Trigger delay in microseconds.

• source (int) –

  Source of the input trigger.

  0 means trigger in.

  1 means software.

  2 means CameraLink CC1.

• skip (int) – Number of frames to skip after trigger.

• fpt (int) – Frames per trigger.

• verbose (bool) – Enable debug printout.

setup_output_trigger(enable=1, mode=1, source=2, delay=0, width=10, verbose=False)

Configures output trigger.

Parameters:

• enable (bool) – Whether to enable the output trigger.

• mode (int) –

  Trigger properties.

  0 means active low.

  1 means active high.

• source (int) –

  Source of the input trigger.

  0 means integration start.

  1 means trigger input.

  2 means integration period.

• delay (float) – Trigger delay in microseconds.

• width (float) – Number of frames to skip after trigger.

• verbose (bool) – Enable debug printout.

setup_grabber(mode=0, frames=4000)

Setup frame grabber capture mode.

Parameters:

• mode (int) –

  Capture mode.

  0 means circular buffer.

  1 means waits till all frames grabbed before restarting capture.

  2 means non-circular (Stops grabbing when buffer filled).

• frames (int) – Number of frames to capture.

set_woi(woi=None, verbose=False)

See Camera.set_woi()

Parameters:

verbose (bool) – Enable debug printout.

set_low_gain(enable=True)

Enables or disables low gain mode.

Parameters:

enable (bool) – Whether to enable or disable.

enable_cooling(enable=True)

Enables/disables TEC and high fan speed.

Parameters:

enable (bool) – Whether to enable or disable.

setup(profile, fpt=1)

Sample pre-configured imaging profiles.

Likely to be reconfigured by end-user for various imaging tasks.

Parameters:

• profile – See profile.

• fpt (int) – Frames per trigger for intput trigger.

snap(conversion=False)

Start capture, grab image, stop capture.

Parameters:

conversion (bool) – Makes an internal 8 bit buffer for xeneth.SaveData() and xeneth.Blit()

get_frame_number()

Get number of captured frames since start_capture().

Returns:

Number of frames.

Return type:

int

start_capture()

Initiates the current capture run

stop_capture()

Terminates the current capture run

abort_capture()

Cancels any long, live frame captures

flush(timeout_s=1)

See Camera.flush()

is_capturing()

Checks if currently capturing

Returns:

True if capturing, False otherwise.

Return type:

bool

autogain(enable=True)

Adds autogain and offset to current filter stack. Makes use of full dynamic range.

Parameters:

enable (bool) – Enables autogain if True.

autoexpose_xenics(enable=True, t_settle=0)

Adds Xenics autogain and offset filters to current filter stack.

Makes use of the camera’s full dynamic range.

Parameters:

• enable (bool) – Enables autogain if True.

• t_settle (float) – Time to allow autoexposure to settle.

autoexposure(set_fraction=0.5, tol=0.05, exposure_bounds_s=None, window=None, timeout_s=5, verbose=True)

Sets the exposure of the camera such that the maximum value is at set_fraction of the dynamic range. Useful for mitigating over- or under- exposure.

Parameters:

• set_fraction (float) – Fraction of camera dynamic range to use as a target image maximum.

• tol (float) – Fractional tolerance for exposure adjustment.

• exposure_bounds_s ((float, float) OR None) – Shortest and longest allowable integration in seconds. If None, defaults to exposure_bounds_s. If this attribute was not set (or not available on a particular camera), then None instead defaults to unbounded.

• window (array_like or None) – See woi. If None, the full camera frame will be used.

• timeout_s (float) – Stop attempting adjusting exposure after timeout_s seconds.

• verbose (bool) – Whether to print exposure updates.

Returns:

Resulting exposure in seconds.

Return type:

float

autofocus(set_z, get_z=0, range_z=2, metric=None, plot=False, verbose=False)

Finds optimal focus when scanning over some variable z. This z often takes the form of a vertical stage to position a sample precisely at the plane of imaging of a lens or objective. The default metric is based on the Fourier contrast of the image, and works particularly well when combined with a projected spot array hologram.

Parameters:

• set_z (function OR SLM) – Sets the position of the focusing stage to a given float. If an SLM is passed, adds a lens phase to the SLM to focus the existing pattern. In this case, the units of z are in Zernike defocus terms (wavefronts). The optimal defocus is added to the wavefront calibration (source["phase"]) of the SLM.

• get_z (function OR float) – Gets the current position of the focusing stage. Should return a float. Can also pass a float representing the center of the search range.

• range_z (array_like OR float OR None) – z values to sweep over during search relative to the base position get_z. If a single float is passed, sweeps from -range_z to +range_z with 11 steps.

• metric (function OR None) – Function which evaluates the focus quality of an image. Should take in an image and return a scalar figure-of-merit (FoM). Defaults to Camera._autofocus_metric(), which approximates the sharpness of the images (implemented as the Fourier contrast of the image, the sum of the normalized Fourier amplitudes). The sharper the image, the higher the FoM.

• plot (bool) – Whether to provide illustrative plots.

Returns:

Optimal z value found.

Return type:

float

close_filters()

Deletes all current tracked filters in the stack.

get_exposure()

Get the frame integration time in seconds. Used in autoexposure().

Returns:

Integration time in seconds.

Return type:

float

get_image(timeout_s=1, transform=True, hdr=None, averaging=None)

Capture, process, and return images from a camera.

Tip

This function includes two advanced capture options:

• Multi-exposure High Dynamic Range (HDR) imaging and

• Software frame averaging (integrating).

These methods can aid the user in capturing more precise data, beyond the default raw (and bitdepth-limited) output of the camera.

Parameters:

• timeout_s (float) – The time in seconds to wait for the frame to be fetched. The frame exposure time is added to this timeout such that there is always enough time to expose.

• transform (bool) – Whether or not to transform the output image according to transform. Defaults to True.

• hdr (int OR (int, int) OR None OR False) –

  Exposure information for Multi-exposure High Dynamic Range (HDR) imaging If None, the value of hdr is used. If False, HDR is not used no matter the state of hdr.

  See also

  get_image_hdr() for more information.

• averaging (int OR None OR False) –

  If int, the number of frames to average over. If None, the value of averaging is used. If False, averaging is not used no matter the state of averaging.

  Tip

  The datatype is promoted to float if necessary but otherwise tries to stick with the default datatype. For instance, a camera that returns a 12-bit image as a 16-bit type has four more bits to use for averaging, i.e. \(2^4 = 16\) possible averages without risk of overflow. Requesting more than 16 averages would cause the return type to be promoted to float.

  Important

  This feature sums many measurements together (does not mean), thereby averaging without floating point operations. This is done such that integer datatypes (useful for memory compactness) can still be returned, whereas a general mean would need to be floating point.

Returns:

Array of shape shape.

Return type:

numpy.ndarray of int OR float

get_image_hdr(exposures=None, return_raw=False, **kwargs)

Often, the necessities of precision applications exceed the bitdepth of a camera. One way to recover High Dynamic Range (HDR) imaging is to use multiple exposures each with increasing exposure time. Then, these images can be stitched together as floating-point data, omitting data which is under- or over- exposed.

Tip

This feature can be accessed in get_image() using hdr or the hdr= flag. This function is exposed here also to reveal the raw data using return_raw= and to draw attention to this useful feature.

Caution

Camera exposure is sometimes poorly defined. This might cause incorrect assumptions of the exposure. In general, a larger base exposure will produce more accurate results as a greater number of sample clock periods are rounded to for smaller relative variation. Future modifications to get_image_hdr_analysis() might improve image stitching.

Parameters:

• exposures (int OR (int, int)) – The number of exposures to take. Each exposure increases in time multiplicatively from the base value (original get_exposure()) by a factor \(p\). The \(i\text{th}\) image has exposure time \(\tau \times p^i\), zero-indexed. The default base of \(p = 2\) leads to exposures being equivalent to spots. This base can be changed to another number by instead passing a tuple, where the second int defines the desired base.

• return_raw (bool) – If True, returns the raw data (stack of images with count exposures) instead of the processed data. The data can be processed using get_image_hdr_analysis()

• **kwargs – Passed to get_image().

Returns:

Array of shape shape.

Important

The scale of the returned image is the same as the original exposure.

Return type:

numpy.ndarray of float

static get_image_hdr_analysis(imgs, overexposure_threshold=None, exposure_power=2)

Analyzes raw data for High Dynamic Range (HDR) imaging multiple exposures each with increasing exposure time.

Parameters:

• imgs (array_like) – Stack of images with increasing exposure.

• overexposure_threshold (float OR None) – For each image (except the first), data is thrown out if values are above this threshold. If None, the threshold defaults to half the maximum.

• exposure_power (int or list of float) –

  Each exposure increases in time multiplicatively from the base value (original get_exposure()) by this factor \(p\). The \(i\text{th}\) image has exposure time \(\tau \times p^i\), zero-indexed. The default value of 2 leads to exposures being equivalent to spots.

Returns:

Array of shape shape.

Important

The scale of the returned image is the same as the original exposure.

Return type:

numpy.ndarray of float

get_images(image_count, timeout_s=1, out=None, transform=True, flush=False)

Grab image_count images in succession.

Important

This method does not support averaging or HDR features. Rather, it just returns a series of raw images.

Parameters:

• image_count (int) – Number of images to grab.

• timeout_s (float) – The time in seconds to wait for each frame to be fetched. The frame exposure time is added to this timeout such that there is always enough time to expose.

• out (None OR numpy.ndarray) – If not None, output data in this memory. Useful to avoid excessive allocation.

• transform (bool) – Whether or not to transform the output image according to transform. Defaults to True.

• flush (bool) – Whether to flush before grabbing.

Returns:

Array of shape (image_count, height, width).

Return type:

numpy.ndarray

static info(verbose=True)

Abstract method to load information about what cameras are available.

Parameters:

verbose (bool) – Whether or not to print display information.

Returns:

An empty list.

Return type:

list

live(activate=None, widgets=True, backend='ipython', **kwargs)

Creates and displays an IPython camera viewer. This viewer displays the result of get_image() or the last image of get_images() whenever these methods are called. Averaging and HDR are displayed with the same color scaling as without.

If True is passed to the widgets argument, this viewer is accompanied by a series of IPython widgets in the form of slides and buttons for controlling the color scale, colormap, viewer scale, and live viewing. By toggling the Live widget button, this viewer can be used as a realtime camera monitor within the jupyter notebook. Note that any user-execution will block the monitoring loop. Regardless, any image polling during the blocked period will still update the viewer, which provides useful active feedback for what is happening during the execution.

This limitation is imposed by the python Global Interpreter Lock (GIL) which restricts operation to a single thread, especially operation connecting to a diverse set of camera and SLM hardware. We use asyncio to allow the realtime monitoring loop to be interrupted by user-execution (e.g. running a cell in jupyter), blocking until the execution is finished.

Running multiple viewers at once might not play nicely right now.

Parameters:

• activate (bool OR None) – If True, creates a live viewer in the current cell, destroying any other attached viewer. If False, destroys any other attached viewer. If None, toggles the live viewer, destroying any attached viewer or creating one in the current cell if none is attached. Defaults to None.

• widgets (bool) – If True, also displays sliders and controls used to hone the display properties.

• backend (str) – Placeholder option for different types of viewers. The default is "ipython".

• **kwargs – Options passed to the _CameraViewer to customize the default settings. These features will be made less hidden in the future. Most things are customizable via these keywords. For instance, the user can pass a custom list of colormaps to appear in the widget dropdown as cmap_options=.

pickle(attributes=True, metadata=True)

Returns a dictionary containing selected attributes of this class.

Parameters:

• attributes (bool OR list of str) – If False, pickles only baseline attributes, usually single floats. If True, also pickles ‘heavy’ attributes such as large images and calibrations. If list of str, pickles the keys in the given list. By default, the chosen attributes should be things that can be written to .h5 files: scalars and lists of scalars.

• metadata (bool) – If True, package the dictionary as the "__meta__" value of a superdictionary which also contains: "__version__", the current slmsuite version, "__time__", the time formatted as a date string, and "__timestamp__", the time formatting as a floating point timestamp. This information is used as standard metadata for calibrations and saving.

plot(image=None, limits=None, title='Image', ax=None, cbar=True)

Plots the provided image.

Parameters:

• image (ndarray OR None OR bool) – Image to be plotted. If None, grabs an image from the camera. If False, uses the last_image attribute.

• limits (None OR float OR [[float, float], [float, float]]) – Scales the limits by a given factor or uses the passed limits directly.

• title (str) – Title the axis.

• ax (matplotlib.pyplot.axis OR None) – Axis to plot upon.

• cbar (bool) – Also plot a colorbar.

Returns:

Axis of the plotted image.

Return type:

matplotlib.pyplot.axis

save(path='.', name=None, **kwargs)

Saves the dictionary returned from pickle() to a file like "path/name_id.h5".

Parameters:

• path (str) – Path to directory to save in. Default is current directory.

• name (str OR None) – Name of the save file. If None, will use name + '-pickle'.

• **kwargs – Passed to pickle() to customize how and what data is saved.

Returns:

The file path that the pickled data was saved to.

Return type:

str

set_exposure(exposure_s)

Set the frame integration time in seconds. Used in autoexposure().

Parameters:

exposure_s (float) – The integration time in seconds.

Returns:

The resulting integration time in seconds (pulled from get_exposure()).

Return type:

float

test()

Tests the core hardware methods of Camera. Validates that the camera is connected correctly and all hardware features are supported.