connect_zen_blue

The communication layer of the ZenBlue API. This software is used to control Zeiss spinning disk microscopes. ZEN Blue uses Iron Python as macro language. This macro interface allows fine grained control of almost all aspects of the microscope. A subset of the classes used in the macro language are exposed as dll and are called by the class ConnectMicroscope() in module connect_zen_blue.

class ConnectMicroscope()

Class to control Zeiss hardware through the Zeiss software Zen Blue. To use this class dll have to be exported.

To be able to use ZEN services in a COM environment, the ZEN functionality must be registered as follows as administrator (right click when opening command prompt to run as administrator (you might have to update versions)):

pushd "C:\Windows\Microsoft.NET\Framework64\v4.0.30319"
SET dll-1="C:\Program Files\Carl Zeiss\ZEN 2\ZEN 2 (blue edition)\Zeiss.Micro.Scripting.dll"
regasm /u /codebase /tlb %dll-1%
regasm /codebase /tlb %dll-1%

SET dll-2="C:\Program Files\Carl Zeiss\ZEN 2\ZEN 2 (blue edition)\Zeiss.Micro.LM.Scripting.dll"

regasm /u /codebase /tlb %dll-2%
regasm /codebase /tlb %dll-2%
popd

Methods for Experiment Settings

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.create_experiment_path(self, experiment, experiment_folder)

Creates complete path to experiment. Raises exception if experiment does not exist

Input:

experiment: string with name of experiment (with or w/o extension .czexp)

experiment_folder: folder for capture settings

Output:

experiment_path: path to experiment

Methods to Save and Load Images

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.save_image(self, fileName)

Save last acquired ImageAICS in original file format using microscope software.

Input:

file: file name and path for ImageAICS save

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.load_image(self, image, get_meta=False)

Load image using aicsimage and return it a class ImageAICS

Input:

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

Methods to Acquire Images

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.snap_image(self, experiment=None)

Snap image with parameters defined in experiment. Image object is stored in self.image. Acquires single image from experiment (e.g. single slice of stack).

Input:

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

Output:

none

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.close_experiment(self, experiment=None)

Closes experiment and forces reload.

Input:

experiment: string with name of experiment defined within Microscope software

Output:

none

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_experiment_folder(self)

Return path to user specific experiment file.

Input:

none

Output:

experiment_path: path to experiment file

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.wait_for_experiment(self, experiment)

Wait until experimentis active experiment.

Input:

experiment: string with name of experiment defined within Microscope software.

Output:

none

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.wait_for_objective(self, target_objective)

Wait until objective is in place.

Input:

target_objective: string with name of objective.

Output:

None

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.execute_experiment(self, experiment=None, pos_list=None)

Execute experiments with parameters defined in experiment. Image object is stored in self.image. Takes all images that are part of experiment (e.g. all slices).

Input:

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

pos_list: if experiment has tiles enabled execute experiment at positions [(x1, y1, z1), (x2 …]. Supports only one block experiments.

Output:

none

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.live_mode_start(self, experiment=None)

Start live mode of ZEN software.

Input:

experiment: name of ZEN experiment (default = None)

Output:

imgLive: image of type ZenImage

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.live_mode_stop(self, experiment=None)

Stop live mode of ZEN software.

Input:

experiment: name of ZEN experiment (default = None)

Output:

none

Methods to Interact with Image Display

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.show_image(self)

Display last acquired image in ZEN software.

Input:

none

Output:

none

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.remove_all(self)

Remove all images from display within ZEN software.

Input:

none

Output:

none

Methods to Control XY Stage

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_stage_pos(self)

Return current position of Microscope stage.

Input:

none

Output:

xPos, yPos: x and y position of stage in micrometer

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.move_stage_to(self, xPos, yPos, zPos=None, experiment=None, test=False)

Move stage to new position.

Input:

xPos, yPos: new stage position in micrometers.

zPos, experiment: not used but included for consistency with Slidebook API

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

Output:

xPos, yPos: x and y position of stage in micrometer after stage movement (if test = False)

x_path, y_path: projected travel path (if test = True)

Methods to Control Focus

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.set_autofocus_ready(self)

Set flag that auto focus position for DF2 was stored and recall_focus should work.

Input:

none

Output:

none

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.set_autofocus_not_ready(self)

Set flag that auto focus position for DF2 is not ready and recall_focus will not work.

Input:

none

Output:

none

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_autofocus_ready(self)

Check if auto focus position for DF2 was stored and recall_focus should work.

Raises AutofocusNotSetError if not ready. Raises AutofocusObjectiveChangedError if there is an issue with objective_name

Input:

none

Output:

ready: True if DF2 was initialized and recall_focus should work.

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.set_last_known_focus_position(self, focusPostion)

Stores focus position used for recovery if autofocus fails.

Input:

focusPostion: position in um to be used for autofocus recovery

Output:

none.

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_last_known_focus_position(self)

Retrieves focus position used for recovery if autofocus fails. Will raise AutofocusNotSetError exception if not defined

Input:

focusPostion: position in um to be used for autofocus recovery

Output:

none.

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.recover_focus(self)

Try to recover from autofocus failure.

Input:

none

Output:

none

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.find_autofocus(self, experiment)

Focus with ZEN software autofocus.

Input:

experiment: string with name for experiment defined in ZEN

Output:

zPos: position of focus drive after autofocus

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.find_surface(self)

Find cover slip using Definite Focus 2.

Input:

none

Output:

z: position of focus drive after find surface

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.store_focus(self)

Store actual focus position as offset from coverslip. Stored focus position is lost when switching objective, even when returning to original objective.

Input:

none

Output:

z: position of focus drive after store focus

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.recall_focus(self, pre_set_focus=True)

Find stored focus position as offset from coverslip. Stored focus position is lost when switching objective, even when returning to original objective.

Input:

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

Output:

z: position of focus drive after recall focus

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_focus_pos(self)

Return current position of focus drive.

Input:

none

Output:

zPos: position of focus drive in micrometer

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.move_focus_to(self, zPos)

Move focus to new position.

Input:

zPos, yPos: new focus position in micrometers.

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.z_relative_move(self, delta)

Move focus relative to current position.

Input:

delta: distance in mum

Output:

z: new position of focus drive

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.z_down_relative(self, delta)

Move focus relative to current position away from sample.

Input:

delta: absolute distance in mum

Output:

z: new position of focus drive

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.z_up_relative(self, delta)

Move focus relative to current position towards sample.

Input:

delta: absolute distance in mum

Output:

z: new position of focus drive

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.set_focus_work_position(self)

retrieve current position and set as work position.

Input:

none

Output:

z_work: current focus position in mum

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.set_focus_load_position(self)

retrieve current position and set as load position.

Input:

none

Output:

zLoad: current focus position in mum

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.move_focus_to_load(self)

Move focus to load position if defined.

Input:

zPos, yPos: new focus position in micrometers.

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.move_focus_to_work(self)

Move focus to work position if defined.

Input:

zPos, yPos: new focus position in micrometers.

Output:

none

Methods to Interact with Objectives

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_all_objectives(self, n_positions)

Retrieve name and magnification of all objectives. Warning! The objectives will move.

Input:

n_positions: number of objective positions

Output:

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

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.switch_objective(self, targetPosition, load=True)

Switches objective.

Input:

targetPosition: Position of new objective on objective switcher

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

Output:

objectiveName: name of new objective

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_objective_magnification(self)

Get magnification of actual objective.

Input:

none

Output:

magnification: magnification of actual objective, objective in imaging position

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_objective_name(self)

Get name of actual objective.

Input:

none

Output:

name: name of actual objective, objective in imaging position

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_objective_position(self)

Get position of actual objective.

Input:

none

Output:

position: position of actual objective, objective in imaging position

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.run_macro(self, macro_name, macro_param=None, trials=3)

Function to run a given Zen Blue Macro

Input:

macro_name: name of the macro

macro_param: parameters to pass into the macro

trials: maximum number of attempts to run the macro. Gives user the option to fix any errors that arise.

Output:

none

Methods to Control Immersion Water Delivery

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.trigger_pump(self, seconds, port='COM1', baudrate=19200)

Trigger pump

Input:

seconds: the number of seconds pump is activated

port: com port, default = ‘COM1’

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

Output:

none

Methods to Collect Microscope Information

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_microscope_name(self)

Returns name of the microscope from hardware that is controlled by this class.

Input:

none

Output:

Microscope: name of Microscope

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.stop(self)

Stop Microscope immediately

Methods to Collect Experiment Information

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.validate_experiment(self, experiment_path=None, experiment_name=None)

Function to check if the experiment is defined in the Zen blue software

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

valid_experiment: bool describing if the experiment is valid

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.is_z_stack(self, experiment_path=None, experiment_name=None)

Function to check if the experiment is a z-stack experiment

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

z_stack_experiment: bool describing if the experiment acquires a z stack

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.z_stack_range(self, experiment_path=None, experiment_name=None)

Function to get the range of first z-stack in experiment.

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

zstack_range: range of the z-stack

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.is_tile_scan(self, experiment_path=None, experiment_name=None)

Function to check if the experiment is a tile scan

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

tile_scan_bool: bool describing if the experiment contains a tile scan

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.update_tile_positions(self, experiment_path, experiment_name, x_value, y_value, z_value)

Function to define the position of the tile

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

x_value: float (x - coordinate)

y_value: float (y - coordinate)

z_value: float (z - coordinate)

Output:

none

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_objective_position_from_experiment_file(self, experiment_path, experiment_name)

Function to get the position of the objective used in the experiment

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

position: the integer position of the objective

microscope_automation.connectors.connect_zen_blue.ConnectMicroscope.get_focus_settings(self, experiment_path, experiment_name)

Function to get the focus settings used in the experiment

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

focus_settings: All instances of focus settings in experiment file

Testing

The following functions were written to test the connect_zen_blue module.

microscope_automation.connectors.connect_zen_blue.test_definite_focus(microscope, interactive=False)[source]

Test DefiniteFocus 2 with ZEN Blue on spinning disk.

Input:

microscope: instance of class ConnectMicroscope interactive: if true allow input from microscope

Output:

success: True when test was passed

microscope_automation.connectors.connect_zen_blue.test_connect_zen_blue(test=['test_definite_focus', 'execute_experiment', 'snap_image', 'get_all_objectives', 'trigger_pump', 'test_focus', 'save_image', 'test_stage'])[source]

Test suite to test module with Zeiss SD hardware or test hardware.

Input:

test: list with tests to perform

Output:

success: True when test was passed