hardware_control_3i

This module contains the class to control specific hardware for 3i Microscopes. This class is the link between the workflow and sample components of the Microscope Automation Software. It extends class BaseMicroscope(object)

The class uses an API to interact with connect_slidebook. We strongly recommend to always access hardware functionality through the API exposed by hardware_control_3i.

The classes are built around a list of objects of class MicroscopeComponent(object). These objects are defined in module hardware_components. Most of these objects implement methods to control the hardware and store its state.

class SpinningDisk3i(BaseMicroscope)

Class to control a 3i spinning disk microscope with a CSU-W1 confocal head from Yokogawa using the vendor software, Slidebook. Slidebook does not allow a direct external control of microscope hardware components. Instead, 3i provided a custom modification of their hierarchical and conditional capture functionality to the Allen Institute for Cell Science.

This allows to call MATLAB functions of the form:

function [N, L, C, P] = find_locations_of_interest(I, X, Y, Z,
                                                   xy_pixel_size,
                                                   z_spacing,
                                                   x_stage_direction,
                                                   y_stage_direction,
                                                   z_stage_direction)

after a hierarchical capture or

function is_continue = continue_time_lapse(I)

after a time lapse capture.

The function called after a hierarchical capture can return a list with new imaging positions and “capture settings” that describe experiments to be performed at these locations. “Capture settings” are defined through a graphical user interface within Slidebook and are saved to disk at the microscope control computer. They are equivalient to “experiments” within Zeiss ZEN blue software.

Microservices commands_service and data_service facilitate the communication between class SpinningDisk3i(BaseMicroscope) and the Slidebook software that controls the 3i spinning disk microscope.

  • commands_service implements a queue with commands to be executed by the microscope. SpinningDisk3i writes to this queue and the MATLAB code invoked by Slidebook pulls from it.

  • data_service implements a queue with image data from the microscope. Slidebook writes to this queue and class SpinningDisk3i(BaseMicroscope) pulls from it. Other microservices (at this moment mainly for visualizations and position selection) can pull from the queue.

The class SpinningDisk3i(BaseMicroscope) uses objects from hardware_components that call the Slidebook specific class ConnectMicroscope() as defined in the module connect_slidebook.

The most important methods are:

microscope_automation.hardware.hardware_control_3i.SpinningDisk3i.add_control_software(self, control_software_object)

Add object that connects this code to the vendor specific microscope control code to Microscope.

Input:

controlSoftwareObject: single object connecting to vendor software

Output:

none

microscope_automation.hardware.hardware_control_3i.SpinningDisk3i.add_microscope_object(self, component_objects)

Add component to microscope.

Input:

component_objects: object of a component class (e.g. Stage, Camera) or list of component classes

Output:

none

microscope_automation.hardware.hardware_control_3i.SpinningDisk3i.create_experiment_path(self, experiment)

Creates complete path to capture settings (Slidebook). Raises exception if experiment does not exist.

Input:

experiment: string with name of capture settings (with or w/o extension .exp.prefs)

Output:

experiment_path: path to experiment or capture settings

microscope_automation.hardware.hardware_control_3i.SpinningDisk3i.execute_experiment(self, capture_settings=None, file_path=None, position_list=None, interactive=False)

Trigger microscope to execute experiment defined within vendor software. Class ImageAICS is a container for meta and image data. To add image data use method load_image. Do not try to recover from exceptions on this level.

Input:

capture_settings: string or list of strings with names of capture settings as defined within 3i Slidebook software. If one capture setting is provided execute same settings at all positions. If list with capture settings is provided, execute each setting on each position. The number of positions has to be identical as the number of capture strings.

file_path: string with path to save image to. Do not save if None (default)

position_list: list with stage coordinates for images

interactive: if True, allow user to modify file name if file exists

Output:

image: image of class ImageAICS to hold metadata. Does not contain image data at this moment.

microscope_automation.hardware.hardware_control_3i.SpinningDisk3i.load_image(self, image, get_meta=False)

Load image and return it as class ImageAICS. Methods ads image and meta data to image. Methods passes load image to microscope specific load method.

Input:

communication_object: Object that connects to microscope specific software

image: image object of class ImageAICS. Holds meta data at this moment, no image data.

get_meta: if true, retrieve meta data from file. Default is False

Output:

image: image with data and meta data as ImageAICS class

microscope_automation.hardware.hardware_control_3i.SpinningDisk3i.move_to_abs_pos(self, stage_id=None, focus_drive_id=None, objective_changer_id=None, auto_focus_id=None, safety_id=None, safe_area='Compound', x_target=None, y_target=None, z_target=None, z_focus_preset=None, reference_object_id=None, load=True, trials=3, verbose=False)

Move stage and focus drive to position (x, y, z) in absolute system coordinates.

Input:

stage_id, focus_drive_id: strings to identify stage and focus drive

objective_changer_id: string to identify objective changer

safety_id: string to identify safety object

safe_area: name of safe area withing safety object (default: ‘compound’ = combine all areas)

x_target, y_target: coordinates of stage after movement (none = do not move stage)

z_target: coordinate for focus position after movement (none = do not move focus, but engage auto-focus)

z_focus_preset: z position for focus before focus recall to make autofocus more reliable. (Default: None, do not use feature)

reference_object_id: ID of object of Sample class used to correct for xyz offset between different objectives

load: Move focus in load position before move. Default: True

trials: number of trials to retrieve z position before procedure is aborted

Ouput:

x_final, y_final, z_final: coordinates after move

microscope_automation.hardware.hardware_control_3i.SpinningDisk3i.remove_images(self)

Remove all images from queue on data service.

Input:

communication_object: Object that connects to microscope specific software

Output:

none

microscope_automation.hardware.hardware_control_3i.SpinningDisk3i.stop_microscope(self)

Stop Microscope immediately in emergency situation

Input:

none

Output:

none