Contents

• hardware_components

  • class Experiment(object)

  • class MicroscopeComponent(object)

  • class ControlSoftware(MicroscopeComponent)

  • class Safety(MicroscopeComponent)

  • class Camera(MicroscopeComponent, ImageAICS)

  • class Stage(MicroscopeComponent)

  • class ObjectiveChanger(MicroscopeComponent)

  • class FocusDrive(MicroscopeComponent)

  • class AutoFocus(MicroscopeComponent)

  • class Pump(MicroscopeComponent)

  • Logging

hardware_components

The hardware_components module contains abstract classes that define common microscope components. These components are system independent, so not all microscopes implement all classes. They are the bridge between automation software and hardware specific implementations. These classes should only be called by the hardware_control modules like hardware_control_3i and hardware_control_zeiss.

class Experiment(object)

This class contains methods which validate and edit experiment files.

class microscope_automation.hardware.hardware_components.Experiment(experiment_path=None, name=None, microscope_object=None)

Class to validate, read, and write to experiment files They are handled in different ways in Zen Blue and Black. Hence this feature was moved to hardware level

get_focus_settings()

Function to get focus settings to test focus setup in test_zen_experiment.py Raises ExperimentNotExistError for invalid experiments.

Input:

none

Output:

focus_settings: All instances of focus settings in experiment file

get_objective_position()

Function to get the position of the objective used in the experiment. Raises ExperimentNotExistError for invalid experiments.

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

position: the integer position of the objective

is_tile_scan()

Function to check if the experiment contains a tile scan. Raises ExperimentNotExistError for invalid experiments.

Input:

none

Output:

is_tilescan: bool

is_z_stack()

Function to check if the experiment contains z-stack acquisition. Raises ExperimentNotExistError for invalid experiments.

Input:

none

Output:

is_zstack: bool

update_tile_positions(x_value, y_value, z_value)

Function to set the tile position. Raises ExperimentNotExistError for invalid experiments.

Input:

x_value: x coordinate

y_value: y coordinate

z_value: z coordinate

Output:

none

validate_experiment()

Function to check if the experiment is defined and valid

Input:

none

Output:

valid_experiment: bool describing if the experiment is valid or not

z_stack_range()

Function to calculate the range of the first experiment. Raises ExperimentNotExistError for invalid experiments.

Input:

none

Output:

zstack_range: range

class MicroscopeComponent(object)

Base class which all microscope component subclasses will inherit.

class microscope_automation.hardware.hardware_components.MicroscopeComponent(component_id)

Base class for all microscope components.

get_id()

Get unique id for component.

Input:

none

Output:

component_id: string with unique component id

get_information(communication_object)

Catch get_information method if not defined in sub class.

Input:

communication_object: Object that connects to microscope specific software (not used)

Output:

None

get_init_experiment(communication_object=None)

Get experiment that will be used for initialization.

Input:

communication_object: not usesd

Output:

init_experiment: string with experiment name defined within microscope software

initialize(communication_object, action_list=[], reference_object_id=None, verbose=True)

Catch initialization method if not defined in sub class.

Input:

communication_object: Object that connects to microscope specific software (not used)

action_list: will not be processed

reference_object_id: ID of plate the hardware is initialized for. Used for setting up of autofocus

verbose: if True print debug information (Default = True)

Output:

none

set_component(settings)

Catch settings method if not defined in sub class.

Input:

settings: dictionary with flags

Output:

new_settings: dictionary with updated flags flags

set_id(component_id)

Set unique id for microscope component.

Input:

component_id: string with unique component id

Output:

none

set_init_experiment(experiment)

Set experiment that will be used for initialization.

Input:

experiment: string with experiment name as defined within microscope software

Output:

none

class ControlSoftware(MicroscopeComponent)

This class imports the correct control software based on what microscope is being used.

class microscope_automation.hardware.hardware_components.ControlSoftware(software)

Connect to software that controls specific Microscope. Import correct module based on Microscope software.

connect_to_microscope_software()

Import connect module based on software name and connect to microscope.

Input:

none

Output:

none

class Safety(MicroscopeComponent)

This class contains methods to avoid damaging the microscope’s hardware, such as determining a safe area and whether a position is within that area.

class microscope_automation.hardware.hardware_components.Safety(safety_id)

Class with methods to avoid hardware damage of microscope.

add_safe_area(safe_vertices, safe_area_id, z_max)

Set safe travel area for microscope stage.

Input:

safe_vertices: coordinates in absolute stage positions that define safe area in the form [(x_0, y_0), (x_1, y_1),c(x_2, y_2), …).

safe_area_id: unique string to identify safe area

z_max: maximum z value in focus drive coordinates within safe area

Output:

none

get_safe_area(safe_area_id='Compound')

Get safe travel area for microscope stage. Create compound area if requested. This compound area is a union of the x-y plane’s areas with the minimum z value.

Input:

safe_area_id: unique string to identify safe area. Default: ‘Compound’ = combination of all safe areas

Output:

safe_area: dictionary of the form:

path: matplotlib path object of safe area’s perimeter

z_max: maximum value the microscope can safely move in the z direction

is_safe_move_from_to(safe_area_id, xy_path, z_max_pos, x_current, y_current, z_current, x_target, y_target, z_target, verbose=True)

Test if it is safe to travel from current to target position.

Input:

safe_area_id: string id for safe area

xy_path: matplotlib path object that describes travel path of stage

z_max_pos: the highest position for z focus during travel

x_current, y_current, z_current: current x, y, z positions of stage in um

x_target, y_target, z_target: target x, y, z positions of stage in um

verbose: if True, show tavel path and safe area (default = True)

Output:

is_safe: True if travel path is safe, otherwise False

is_safe_position(x, y, z, safe_area_id='Compound')

Test if absolute position is safe. Compound area is a union of the x-y plane’s areas with the minimum z value.

Input:

x, y: absolute stage position in um to be tested

z: absolute focus position in um to be tested

safe_area_id: unique string to identify safe area. Default: ‘Compound’ = combination of all safe areas

Output:

is_safe: True if position is safe, otherwise False

is_safe_travel_path(path, z, safe_area_id='Compound', verbose=True)

Test if intended travel path is safe. Compound area is a union of the x-y plane’s areas with the minimum z value.

Input:

path: travel path to be tested as matplotlib.Path object

z: maximum focus position in um of the travel path

safe_area_id: unique string to identify safe area. Default: ‘Compound’ = combination of all safe areas

verbose: if True, show travel path and safe area. Default: True

Output:

is_safe: True if path is safe, otherwise False

show_safe_areas(path=None, point=None)

Show all safe areas defined in this class instance.

Input:

path: travel path to overlay with safe areas as matplotlib.Path object

point: point to overlay with safe area as (x, y) tuple

Output:

none

class Camera(MicroscopeComponent, ImageAICS)

This class defines and operates the microscope camera. To accomplish this, it inherits the class ImageAICS in addition to the class MicroscopeComponent(object)

class microscope_automation.hardware.hardware_components.Camera(camera_id, pixel_size=(None, None), pixel_number=(None, None), pixel_type=None, name=None, detector_type='generic', manufacturer=None, model=None)

Class to describe and operate microscope camera

get_information(communication_object)

Get camera status

Input:

communication_object: Object that connects to microscope specific software. Not used by Camera class, but maintained for consistency with parent class MicroscopeComponent

Output:

camera_dict: dictionary {‘live’: True/False, ‘settings’: dict with settings}

live_mode_start(communication_object, experiment=None)

Start live mode of ZEN software.

Input:

communication_object: Object that connects to microscope specific software

experiment: name of ZEN experiment (default = None)

Output:

none

live_mode_stop(communication_object, experiment=None)

Stop live mode of ZEN software.

Input:

communication_object: Object that connects to microscope specific software

experiment: name of ZEN experiment (default = None). If None use actual experiment.

Output:

none

snap_image(communication_object, experiment=None)

Snap image with parameters defined in experiment. Class ImageAICS is a container for meta and image data. To add image data use method load_image.

Input:

communication_object: Object that connects to microscope specific software

experiment: string with name of experiment defined within Microscope software. If None uses active/default experiment.

Return:

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

class Stage(MicroscopeComponent)

This class contains methods which define and operate the microscope’s stage.

class microscope_automation.hardware.hardware_components.Stage(stage_id, safe_area=None, safe_position=None, objective_changer=None, microscope_object=None, default_experiment=None)

Class to describe and operate microscope stage

get_information(communication_object)

Get actual stage position from hardware in mum

Input:

communication_object: Object that connects to microscope specific software

Output:

positions_dict: dictionary with stage position in mum of the form:

{‘absolute’: (x, y, z), ‘centricity_corrected’: ()}

z is optional depending on microscope used.

initialize(communication_object, action_list=[], reference_object_id=None, verbose=True, test=False)

Initialize stage.

Input:

communication_object: Object that connects to microscope specific software

action_list: not used

reference_object_id: not used

verbose: if True print debug information (Default = True)

test: if True do not move stage

Output:

none

move_to_position(communication_object, x, y, z=None, experiment=None, test=False)

Set stage position in mum and move stage

Input:

communication_object: Object that connects to microscope specific software

x, y, z: stage position in mum

experiment: experiment (ZEN) of capture settings (Slidebook) to use when operation stage (not allways required). None: use default experiment

test: if True return travel path and do not move stage

Output:

xStage, yStage: position of stage after movement in mum

zStage: position of stage after movement in mum (optional depending on whether a z value was input)

class ObjectiveChanger(MicroscopeComponent)

This class contains a wide array of methods to view and modify objectives.

class microscope_automation.hardware.hardware_components.ObjectiveChanger(objective_changer_id, n_positions=None, objectives=None, ref_objective=None, microscope_object=None)

Class to describe and change objectives

change_magnification(communication_object, magnification, sample_object, use_safe_position=True, verbose=True, load=True)

Change to objective with given magnification.

Input:

communication_object: object that connects to microscope specific software

magnification: magnification of selected objective as float. Not well defined if multiple objectives with identical magnification exist.

sample_object: object that has safe coordinates attached. If use_safe_position == True than stage and focus drive will move to this position before magnification is changed to avoid collision between objective and stage.

use_safe_position: move stage and focus drive to safe position before switching magnification to minimize risk of collision (Default: True)

verbose: if True print debug information (Default = True)

load: if True, move objective to load position before switching (Default: True)

Output:

objective_name: name of new objective

change_position(position, communication_object, load=True)

Change to objective at given position. Requires self.get_all_objectives run once before usage.

Input:

position: position of objective

communication_object: Object that connects to microscope specific software

load: if True, move objective to load position before switching (Default: True)

Output:

objective_name: name of new objective

get_all_objectives(communication_object)

Retrieve name and magnification of all objectives. Required when using self.change_magnification(magnification)

Warning! Objectives will move!

Input:

communication_object: Object that connects to microscope specific software

Output:

objectives_dict: dictionary of all objectives mounted at microscope in form {‘magnification’: {‘Position’: position, ‘Name’: name}

get_information(communication_object)

Get name and magnification of actual objective.

Input:

communication_object: Object that connects to microscope specific software

Output:

name, magnification, position, and experiment of objective in imaging position

get_number_positions()

Get the number of objective positions.

Input:

none

Output:

n_positions: number of objective positions

get_objective_information(communication_object)

Get offset to correct for parfocality and parcentrality for current objective

Input:

communication_object: Object that connects to microscope specific software

Output:

objective_information: dictionary for the current objective in the form:

‘x_offset’: x

‘y_offset’: y

‘z_offset’: z

‘magnification’: m

‘immersion’: ‘type’

‘experiment’: ‘name’

get_objective_magnification(communication_object)

Get magnification of actual objective.

Input:

none

Output:

magnification: magnification of actual objective, objective in imaging position

get_objectives_dict()

Retrieves dictionary with all names and magnifications of objectives.

Requires to run self.get_all_objectives once before usage.

Input:

none

Output:

objectives_dict: dictionary of all objectives mounted at microscope in form {‘magnification’: {‘Position’: position, ‘Name’: name}

initialize(communication_object, action_list=[], reference_object_id=None, verbose=True)

Initialize objective changer and set reference positions.

Input:

communication_object: Object that connects to microscope specific software

action_list: list with item ‘set_reference’. If empty no action.

reference_object_id: ID of plate, plate holder, or other sample object the hardware is initialized for. Used for setting up of autofocus

verbose: if True print debug information (Default = True)

Output:

none

set_number_positions(n_positions)

Sets the number of objective positions.

Input:

n_positions: number of objective positions

Output:

none

update_objective_offset(communication_object, x_offset, y_offset, z_offset, objective_name=None)

Update offset to correct for parfocality and parcentrality

Input:

communication_object: Object that connects to microscope specific software

x_offset, y_offset, z_offset: new offset values in absolute coordinates

objective_name: string with unique name for objective. If None use current objective

Output:

objective_information: dictionary for the current objective in the form:

‘x_offset’: x

‘y_offset’: y

‘z_offset’: z

‘magnification’: m

‘immersion’: ‘type’

‘experiment’: ‘name’

class FocusDrive(MicroscopeComponent)

This class controls focus drive.

class microscope_automation.hardware.hardware_components.FocusDrive(focus_drive_id, max_load_position=0, min_work_position=10, auto_focus_id=None, objective_changer=None, microscope_object=None)

Class to describe and operate focus drive

define_load_position(communication_object)

Define current focus position as load position for focus drive.

Input:

communication_object: Object that connects to microscope specific software

Output:

z_load: load postion in mum

define_work_position(communication_object)

Define current focus position as work position for focus drive.

Input:

communication_object: Object that connects to microscope specific software

Output:

z_work: load postion in mum

get_abs_position(communication_object)

get absolute focus position from hardware in mum

Input:

communication_object: Object that connects to microscope specific software

Output:

z: focus position in mum

get_information(communication_object)

get absolute and absolute position after drift correction for focus drive.

Input:

communication_object: Object that connects to microscope specific software

Output:

positions_dict: dictionary with

‘absolute’: absolute position of focus drive as shown in software

‘z_focus_offset’: parfocality offset

‘focality_corrected’: absolute focus position - z_focus_offset

‘load_position’: load position of focus drive

‘work_position’: work position of focus drive

with focus positions in um

get_load_position()

Get load position for focus drive.

Input:

none

Output:

z_load: load position in mum

get_work_position()

Get work position for focus drive.

Input:

none

Output:

z_work: load position in mum

goto_load(communication_object)

Set focus position to load position.

Input:

communication_object: Object that connects to microscope specific software

Output:

z_load: load position in mum

goto_work(communication_object)

Set focus position to work position.

Input:

communication_object: Object that connects to microscope specific software

Output:

z_work: work position in mum

initialize(communication_object, action_list=[], reference_object_id=None, verbose=True, test=False)

Initialize focus drive.

Input:

communication_object: Object that connects to microscope specific software

action_list: list with items ‘set_load’ and/or ‘set_work’. If empty no action.

microscope_object: microscope component is attached to

reference_object_id: not used

verbose: if True print debug information (Default = True)

Output:

none

move_to_position(communication_object, z)

Set focus position in mum and move focus drive. If use_autofocus is set, correct z value according to new autofocus position.

Raises HardwareCommandNotDefinedError for Slidebook connections.

Input:

communication_object: Object that connects to microscope specific software

z: focus drive position in mum

Output:

zFocus: position of focus drive after movement in mum

class AutoFocus(MicroscopeComponent)

This class obtains autofocus settings from the microscope and sets new autofocus configurations.

class microscope_automation.hardware.hardware_components.AutoFocus(auto_focus_id, default_camera=None, objective_changer_instance=None, default_reference_position=[[50000, 37000, 6900]], microscope_object=None)

Class to describe and operate hardware autofocus.

find_surface(communication_object)

Find cover slip using Definite Focus 2. Does not store found position.

Input:

communication_object: Object that connects to microscope specific software

Output:

z: position of focus drive after find surface

get_autofocus_ready(communication_object)

Check if auto-focus is ready

Input:

communication_object: Object that connects to microscope specific software

Output:

is_ready: True, if auto-focus is ready

get_focus_reference_obj_id()

Get object from class ImagingSystem (module samples) used as zero plane for autofocus.

Input:

none

Output:

focus_reference_obj_id: Sample object used as reference for autofocus

get_information(communication_object)

get status of auto-focus.

Input:

communication_object: Object that connects to microscope specific software

Output:

positions_dict: dictionary with focus position in mum of the form:

{‘absolute’: z_abs, ‘focality_corrected’: z_cor}

get_init_experiment(communication_object)

Get experiment used for initialization based on current objective.

Input:

communication_object: Object that connects to microscope specific software

Output:

init_experiment: string with name of experiment used for initialization

get_use_autofocus()

Return flag about autofocus usage

Input:

none

Output:

use_autofocus: boolean varaible indicating if autofocus should be used

initialize(communication_object, action_list=['find_surface'], reference_object_id=None, verbose=True)

Initialize auto-focus (default: do nothing if already initialized).

Input:

communication_object: Object that connects to microscope specific software

action_list: if list includes ‘no_find_surface’ auto-focus will not try to find cover slip before operator refocuses

no_interaction: no user interaction, no live image

force_initialization: initialize even if already initialized. If empty no action

sample_object: ID of plate, plate holder or other sample object the hardware is initialized for. Used for setting up of autofocus

verbose: if True, print debug messages (Default: True)

Output:

none

recall_focus(communication_object, reference_object_id=None, verbose=False, pre_set_focus=True)

Find difference between stored focus position and actual autofocus position. Recall focus will move the focus drive to it’s stored position. Will try to recover if autofocus failed.

Input:

communication_object: Object that connects to microscope specific software

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

verbose: if True, print debug messages (Default: False)

pre_set_focus: Move focus to previous auto-focus position. This makes definite focus more robust

Output:

delta_z: difference between stored z position of focus drive and position after recall focus

set_component(settings)

Switch on/off the use of auto-focus

Input:

settings: dictionary {use_auto_focus: True/False}. If empty do not change setting

Output:

new_settings: dictionary with updated status

set_focus_reference_obj_id(focus_reference_obj_id)

Set object from class ImagingSystem (module samples) used as zero plane for autofocus.

Input:

focus_reference_obj_id: Sample object used as reference for autofocus

Output:

none

set_use_autofocus(flag)

Set flag to enable the use of autofocus. If no autofocus position is stored, store current position.

Input:

flag: if True, use autofocus

Output:

use_autofocus: status of use_autofocus

store_focus(communication_object, focus_reference_obj_id, verbose=False)

Store actual focus position as offset from coverslip.

Input:

communication_object: Object that connects to microscope specific software

focus_reference_obj_id: ID of Sample object used as reference for autofocus

Output:

z: position of focus drive after store focus

class Pump(MicroscopeComponent)

This class describes, sets up, and triggers pump operation.

class microscope_automation.hardware.hardware_components.Pump(pump_id, seconds=1, port='COM1', baudrate=19200)

Class to describe and operate pump

get_connection()

Get communication parameters for pump.

Input:

none

Output:

conPar: dictionary with

port: com port, default = ‘COM1’

baudrate: baudrate for connection, can be set on pump, typically = 19200

get_time()

Get communication parameters for pump.

Input:

none

Output:

seconds: time in seconds

set_connection(port, baudrate)

Set communication parameters for pump.

Input:

port: com port, default = ‘COM1’

baudrate: baudrate for connection, can be set on pump, typically = 19200

Output:

none

set_time(seconds)

Set time pump is activated.

Input:

seconds: time in seconds

Output:

none

trigger_pump(communication_object)

Trigger pump.

Input:

communication_object: Object that connects to microscope specific software

Output:

none

Logging

The module includes the following functions to log various information:

microscope_automation.hardware.hardware_components.log_message(message, methodName=None)

Shows message if logging level is INFO.

Input:

message: string with message methodName: string with name of method

Output:

none

microscope_automation.hardware.hardware_components.log_method(self, methodName=None)

Log name of module and method if logging level is DEBUG.

Input:

methodName: string with name of method

Output:

none

microscope_automation.hardware.hardware_components.log_warning(message, methodName=None)

Shows message if logging level is WARNING.

Input:

message: string with message methodName: string with name of method

Output:

none