microscope_automation.hardware package

Submodules

microscope_automation.hardware.RS232 module

Communicate with RS232 interface Based on pySerial Install with pip install pyserial https://pypi.python.org/pypi/pyserial/2.7 http://pythonhosted.org/pyserial/

Created on Sep 6, 2016

@author: winfriedw

class microscope_automation.hardware.RS232.Braintree(port='COM1', baudrate=19200)

Bases: object

Control Braintree BS-8000/9000 syringe pump through RS232. http://www.braintreesci.com/prodinfo.asp?number=BS-8000 http://www.braintreesci.com/images/BS8000.pdf

close_connection()

Stop pump and close connection.

Input:

none

Output:

none

start_pump()

Start pump.

Input:

none

Output:

none

stop_pump()

Stop pump.

Input:

none

Output:

none

microscope_automation.hardware.RS232_dummy module

Dummy functions to replace RS232 for dummy functions Created on Sep 23, 2016

@author: winfriedw

class microscope_automation.hardware.RS232_dummy.Braintree(port='COM1', baudrate=19200)

Bases: object

Control Braintree BS-8000/9000 syringe pump through RS232. http://www.braintreesci.com/prodinfo.asp?number=BS-8000 http://www.braintreesci.com/images/BS8000.pdf

close_connection()

Stop pump and close connection.

Input:

none

Output:

none

start_pump()

Start pump.

Input:

none

Output:

none

stop_pump()

Stop pump.

Input:

none

Output:

none

microscope_automation.hardware.hardware_components module

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 hardware_control.Microscope. Created on Jul 7, 2016 Split into hardware_control and hardware_components on May 25, 2020

@author: winfriedw

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)

Bases: microscope_automation.hardware.hardware_components.MicroscopeComponent

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 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)

Bases: microscope_automation.hardware.hardware_components.MicroscopeComponent, microscope_automation.util.image_AICS.ImageAICS

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 microscope_automation.hardware.hardware_components.ControlSoftware(software)

Bases: microscope_automation.hardware.hardware_components.MicroscopeComponent

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 microscope_automation.hardware.hardware_components.Experiment(experiment_path=None, name=None, microscope_object=None)

Bases: object

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 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)

Bases: microscope_automation.hardware.hardware_components.MicroscopeComponent

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 microscope_automation.hardware.hardware_components.MicroscopeComponent(component_id)

Bases: object

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 microscope_automation.hardware.hardware_components.ObjectiveChanger(objective_changer_id, n_positions=None, objectives=None, ref_objective=None, microscope_object=None)

Bases: microscope_automation.hardware.hardware_components.MicroscopeComponent

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 microscope_automation.hardware.hardware_components.Pump(pump_id, seconds=1, port='COM1', baudrate=19200)

Bases: microscope_automation.hardware.hardware_components.MicroscopeComponent

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

class microscope_automation.hardware.hardware_components.Safety(safety_id)

Bases: microscope_automation.hardware.hardware_components.MicroscopeComponent

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 microscope_automation.hardware.hardware_components.Stage(stage_id, safe_area=None, safe_position=None, objective_changer=None, microscope_object=None, default_experiment=None)

Bases: microscope_automation.hardware.hardware_components.MicroscopeComponent

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)

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

microscope_automation.hardware.hardware_control module

Classes to describe and control hardware. Bridge between automation software and hardware specific implementations. Created on Jul 7, 2016 Split into hardware_control and hardware_components on May 25, 2020

@author: winfriedw

class microscope_automation.hardware.hardware_control.BaseMicroscope(name=None, control_software_object=None, experiments_folder=None, microscope_components=None)

Bases: object

Minimum set of attributes and methods required by Automation Software

add_control_software(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

add_microscope_object(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

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

Change to objective with given magnification.

Input:

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

get_load_position(focus_drive_id)

Get load position of focus drive.

Input:

focus_drive_id: id of focus drive to get load position of

Output:

z_load: load position in mum

goto_load(focus_drive_id)

Set focus position to load position.

Input:

focus_drive_id: id of focus drive to set load position on

Output:

z_load: load position in mum

live_mode(camera_id, experiment=None, live=True)

Start/stop live mode of ZEN software.

Input:

camera_id: string id for camera

experiment: name of ZEN experiment (default = None)

live: switch live mode on (True = default) or off (False)

Output:

None

microscope_is_ready(experiment, component_dict, focus_drive_id, objective_changer_id, safety_object_id, reference_object_id=None, load=True, make_ready=True, trials=3, verbose=True)

Check if microscope is ready and setup up for data acquisition.

Input:

experiment: string with name of experiment as defined in microscope software

compenent_dict: dictionary with component_id as key and list of actions

focus_drive_id: string id for focus drive

objective_changer_id: string id for objective changer parfocality

and parcentricity has to be calibrated

safety_object_id: string id for safety area

reference_object_id: ID of object used to set parfocality and parcentricity

load: move objective into load position before moving stage

make_ready: if True, make attempt to ready microscope, e.g. setup autofocus (Default: True)

trials: maximum number of attempt to initialize microscope. Will allow user to make adjustments on microscope. (Default: 3)

verbose: print debug messages (Default: True)

Output:

ready: True if microscope is ready for use, False if not

not_implemented(method_name)

Raise exception if method is not implemented.

Input:

method_name: method that calls this method

recall_focus(auto_focus_id, reference_object_id=None, 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.

Input:

auto_focus_id: string id for camera

reference_object_id: name of ZEN experiment (default = None)

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

recover_hardware(error)

Try to recover from failure of a hardware function

Input:

error: exception to recover from

Output:

return_dialog: value of the error dialog

trigger_pump(pump_id)

Triggers pump of pump_id.

Raises HardwareDoesNotExistError if pump is not attached to microscope

Input:

pump_id: pump to trigger

Output:

none

microscope_automation.hardware.hardware_control_3i module

Classes to describe and control 3i spinning disk hardware. Bridge between automation software and hardware specific implementations. Created on Jul 7, 2016 Split into hardware_control and hardware_components on May 25, 2020 Split into hardware_control and hardware_control_3i on Aug. 15, 2020 by Winfried

@author: winfriedw

class microscope_automation.hardware.hardware_control_3i.SpinningDisk3i(name=None, control_software_object=None, experiments_folder=None, microscope_components=None)

Bases: microscope_automation.hardware.hardware_control.BaseMicroscope

Collection class to describe and operate 3i spinning disk microscope

create_experiment_path(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

execute_experiment(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.

get_information(components_list=[])

Get positions for hardware components.

Input:

components_list: list with names of components to retrieve positions Default: None = get positions for all components

Output:

positions_dict: dictionary {component_id: positions}. Positions are dictionaries if multiple positions can be retrieved

get_z_position(focus_drive_id=None, auto_focus_id=None, force_recall_focus=False, trials=3, reference_object_id=None, verbose=True)

Get current position of focus drive.

Input:

focus_drive_id: string id for focus drive to get the position for

auto_focus_id: string id for auto focus to use (None: do not use auto-focus)

force_recall_focus: if True, recall focus, otherwise use old values. Default: False

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

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)

Output:

positions_dict: dictionary {component_id: positions}.

positions are dictionaries with

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

‘z_focus_offset’: parfocality offset

‘focality_corrected’: absolute focus position - z_focus_offset

‘auto_focus_offset’: change in autofocus position

‘focality_drift_corrected’: focality_corrected position - auto_focus_offset

‘load_position’: load position of focus drive

‘work_position’: work position of focus drive

with focus positions in um

initialize_hardware(initialize_components_ordered_dict=None, reference_object_id=None, trials=3, verbose=True)

Initialize all hardware components.

Input:

component_OrderedDict: directory with names of components to initialize and list of initialization steps. Default: None = initialize all components in order as assigned to microscope object

reference_object_id: Used for setting up of autofocus

trials: number of trials before initialization is aborted

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

Output:

none

load_image(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

move_to_abs_pos(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

reference_position(find_surface=False, reference_object_id=None, verbose=True)

Included for parity with ZEN Microscopes. Raises HardwareCommandNotDefinedError.

Input:

find_surface: if True auto-focus will try to find cover slip before operator refocuses. Default: False

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

remove_images()

Remove all images from queue on data service.

Input:

communication_object: Object that connects to microscope specific software

Output:

none

save_image(file_path, image, interactive=False)

Save last Microscope ImageAICS taken from within Microscope software. Method adds file_path to meta data.

Input:

file_path: filename with path to save ImageAICS

image: image of class ImageAICS

interactive: if True, allow update of filename if it already exists

Output:

image: image of class ImageAICS

set_microscope(settings_dict={})

Set status flags for microscope.

Input:

settings_dict: dictionary {component_id: {settings}}

supported flags:

autofocus_id: {use_auto_focus: True/False}

Output:

new_settings_dict: return all current settings

setup_microscope_for_initialization(component_object, experiment=None, before_initialization=True)

Setup microscope before initialization of individual components. Method starts and stops live image mode.

Input:

component_object: instance of component class

experiment: Name of experiment setting in ZEN blue used for microscope initialization (e.g. used for live mode)

before_initialization: if True setup microscope, if False reset

Output:

none

stop_microscope()

Stop Microscope immediately in emergency situation

Input:

none

Output:

none

microscope_automation.hardware.hardware_control_zeiss module

Classes to describe and control 3i spinning disk hardware. Bridge between automation software and hardware specific implementations. Created on Jul 7, 2016 Split into hardware_control and hardware_components on May 25, 2020 Split into hardware_control and hardware_control_zeiss on Sept. 22 2020

@author: fletcher.chapin

class microscope_automation.hardware.hardware_control_zeiss.SpinningDiskZeiss(name=None, control_software_object=None, experiments_folder=None, safeties=None, microscope_components=None)

Bases: microscope_automation.hardware.hardware_control.BaseMicroscope

Collection class to describe and operate Zeiss spinning disk microscope

change_objective(experiment, objective_changer_object, trials=3)

Switch to objective used in experiment.

Input:

experiment: string with name of experiment as defined in microscope software

objective_changer_object: object for objective changer objective is mounted to

trials: number of times system tries to recover

Output:

objective_name: name of objective in new position

create_experiment_path(experiment)

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

Input:

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

Output:

experiment_path: path to experiment or capture settings

execute_experiment(experiment=None, file_path=None, z_start='C', 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:

experiment: string with name of experiment defined within Microscope software. If None use actual experiment.

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

z_start: define where to start z-stack (‘F’= first slice, ‘C’ = center, ‘L’ = last slice). Default: ‘F’

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.

get_information(components_list=[])

Get positions for hardware components.

Input:

components_list: list with names of components to retrieve positions Default: None = get positions for all components

Output:

positions_dict: dictionary {component_id: positions}. Positions are dictionaries if multiple positions can be retrieved

get_objective_is_ready(objective_position, reference_object_id=None)

Test if objective was initialized.

Input:

objective_position: position of objective in objective changer

reference_object_id: ID of reference object (e.g. well) which objective was initialized for

Output:

objective_is_ready: True, if offset for objective was set

get_z_position(focus_drive_id=None, auto_focus_id=None, force_recall_focus=False, trials=3, reference_object_id=None, verbose=True)

Get current position of focus drive.

Input:

focus_drive_id: string id for focus drive to get the position for

auto_focus_id: string id for auto focus to use (None: do not use auto-focus)

force_recall_focus: if True, recall focus, otherwise use old values. Default: False

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

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)

Output:

positions_dict: dictionary {component_id: positions}.

positions are dictionaries with

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

‘z_focus_offset’: parfocality offset

‘focality_corrected’: absolute focus position - z_focus_offset

‘auto_focus_offset’: change in autofocus position

‘focality_drift_corrected’: focality_corrected position - auto_focus_offset

‘load_position’: load position of focus drive

‘work_position’: work position of focus drive

with focus positions in um

initialize_hardware(initialize_components_ordered_dict=None, reference_object_id=None, trials=3, verbose=True)

Initialize all hardware components.

Input:

initialize_components_ordered_dict: directory with names of components to initialize and list of initialization steps. Default: None = initialize all components in order as assigned to microscope object

reference_object_id: Used for setting up of autofocus

trials: number of trials before initialization is aborted

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

Output:

none

live_mode(camera_id, experiment=None, live=True)

Start/stop live mode of ZEN software.

Input:

camera_id: string id for camera

experiment: name of ZEN experiment (default = None)

live: switch live mode on (True = default) or off (False)

Output:

none

load_image(image, get_meta=False)

Load image and return it as class ImageAICS. Methods adds 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_is_ready(experiment, component_dict, focus_drive_id, objective_changer_id, safety_object_id, reference_object_id=None, load=True, make_ready=True, trials=3, verbose=True)

Check if microscope is ready and setup up for data acquisition.

Input:

experiment: string with name of experiment as defined in microscope software

compenent_dict: dictionary with component_id as key and list actions

focus_drive_id: string id for focus drive

objective_changer_id: string id for objective changer parfocality and parcentricity has to be calibrated

safety_object_id: string id for safety area

reference_object_id: ID object used to set parfocality and parcentricity

load: move objective into load position before moving stage

make_ready: if True, make attempt to ready microscope, e.g. setup autofocus (Default: True)

trials: maximum number of attempt to initialize microscope. Will allow user to make adjustments on microscope. (Default: 3)

verbose: print debug messages (Default: True)

Output:

is_ready: dictionary of all components that are ready

move_to_abs_pos(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 type sample (ImagingSystem). 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

recover_hardware(error)

Try to recover from failure of a hardware function

Input:

error: exception to recover from

Output:

return_dialog: value of the error dialog

reference_position(find_surface=False, reference_object_id=None, verbose=True)

Initialize and update reference position to correct for xyz offset between different objectives.

Input:

find_surface: if True auto-focus will try to find cover slip before operator refocuses. Default: False

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

remove_images()

Remove all images from display in microscope software

Input:

communication_object: Object that connects to microscope specific software

Output:

none

run_macro(macro_name=None, macro_param=None)

Function to run a given Macro in the Zen Software

Input:

macro_name: Name of the Macro

Output:

none

save_image(file_path, image, interactive=False)

Save last Microscope ImageAICS taken from within Microscope software. Methods adds file_path to meta data.

Input:

file_path: filename with path to save ImageAICS

image: image of class ImageAICS

interactive: if True, allow update of filename if it already exists

Output:

image: image of class ImageAICS

set_microscope(settings_dict={})

Set status flags for microscope.

Input:

settings_dict: dictionary {component_id: {settings}}

supported flags:

autofocus_id: {use_auto_focus: True/False}

Output:

new_settings_dict: return all current settings

set_objective_is_ready(objective_info, reference_object_id=None)

Create list with all objective positions initialized for reference_object.

Input:

objective_info: information for objective that was initialized

reference_object_id: ID of reference object (e.g. well) which objective was initialized for

Output:

none

setup_microscope_for_initialization(component_object, experiment=None, before_initialization=True)

Setup microscope before initialization of individual components. Method starts and stops live image mode.

Input:

component_object: instance of component class

experiment: Name of experiment setting in ZEN blue used for microscope initialization (e.g. used for live mode)

before_initialization: if True setup microscope, if False reset

Output:

None

stop_microscope()

Stop Microscope immediately in emergency situation

microscope_automation.hardware.setup_microscope module

Function to setup microscope hardware based on reference files Created on Aug 1, 2016 Split into it’s own module: May 21, 2020

@author: winfriedw

microscope_automation.hardware.setup_microscope.setup_autofocus(specs, microscope, obj_changer=None)

Setup autofocus and add to microscope object

Input:

specs: hardware specifications which info on autofocus will be retrieved from

microscope: microscope object which autofocus will be added to

obj_changer: objective changer object to attach to this autofocus (Defult: None)

Output:

none

microscope_automation.hardware.setup_microscope.setup_cameras(specs, microscope)

Setup cameras and add to microscope object

Input:

specs: hardware specifications which info on cameras will be retrieved from

microscope: microscope object which cameras will be added to

Output:

none

microscope_automation.hardware.setup_microscope.setup_focus_drive(specs, microscope, obj_changer_id=None)

Setup focus drive and add to microscope object

Input:

specs: hardware specifications which info on focus drive will be retrieved from

microscope: microscope object which focus drive will be added to

Output:

none

microscope_automation.hardware.setup_microscope.setup_microscope(prefs)

Create object of class Microscope from module hardware.

Input:

prefs: preferences with information about microscope hardware

Output:

microscope: object of class Microscope

microscope_automation.hardware.setup_microscope.setup_obj_changer(specs, microscope)

Setup objective changer and add to microscope object

Input:

specs: hardware specification from which info on objective changer is retrieved

microscope: microscope object which objective changer will be added to

Output:

objective_changer_object: instance of ObjectiveChanger which was just added to microscope

microscope_automation.hardware.setup_microscope.setup_pump(specs, microscope)

Setup autofocus and add to microscope object

Input:

specs: hardware specifications which info on autofocus will be retrieved from

microscope: microscope object which autofocus will be added to

obj_changer: objective changer object to attach to this autofocus (Defult: None)

Output:

none

microscope_automation.hardware.setup_microscope.setup_safe_areas(specs, microscope)

Setup safe area to prevent crashes between stage and objective. Adds safe areas to microscope object

Input:

specs: hardware specifications which info on safe areas will be retrieved from

microscope: microscope object which safe areas will be added to

Output:

none

microscope_automation.hardware.setup_microscope.setup_stages(specs, microscope)

Setup stages and add to microscope object

Input:

specs: hardware specifications which info on stages will be retrieved from

microscope: microscope object which stages will be added to

Output:

none

Module contents

Hardware package for Microscope Automation.