Contents

• connect_slidebook

  • Slidebook and MatLab

  • commands_service

  • Experiment

  • class ConnectMicroscope()

connect_slidebook

Rest API calls to control 3i spinning disk microscopes. The 3i Slidebook software control 3i microscopes. It uses Matlab as macro language. The macro language is mainly used for image processing. The options to control the hardware are very limited.

To use this module additional microservices and MatLab code are required. MatLab receives information about the last image acquire through Slidebook. The MatLab code communicates by REST API with several microservices:

• commands_service: Automation software (via connect_slidebook) post commands (experiments). MatLab pulls them and hands information back to Slidebook.

• data_service: MatLab posts image and limited meta data. Automation Software and other micro-services can get images and meta data.

• imageviewer: Pulls and displays image from data-service. User can select positions. Automation Software pulls the selected position for further processing.

Slidebook and MatLab

To control 3i Slidebook open Slidebook and configure advanced capture. Setup a script that calls MatLab code after an image (or a series of images) was captured.

The MatLab function find_location_of_interest receives an image from MatLab and posts the stage position to commands_service. Than it gets the next experiment in the experiments queue from commands_service. The script can execute the following actions:

• snap: snap image at current location

• move: move stage and objective in x, y, z. Do not take image.

• move_snap: move stage and objective in x, y, z and take image.

• exit: stop execution. To continue script has to be started manually within Slidebook.

commands_service

commands_service can be accessed on http://localhost:5000. The service implements a queue with experiments. It uses the following API:

• /about, /cmd/about: get information about server

• /cmd/experiments: post experiment as last entry on queue or get dictionary with all experiments on queue

• /cmd/experiments/clear: delete all experiments from queue

• /cmd/experiments/count: get number of experiments on queue

• /cmd/experiments/next: get next (oldest) experiment on queue

• /cmd/experiments/{experiment_id}: get or delete experiment with id

• /cmd/microscope/microscope: post information about microscope

• /cmd/recent_position: post and get most recent position returned by microscope

Experiment

An experiment is send as payload when posting or getting data from /cmd/experiments/*. It is a dictionary that instructs Slidebook how to acquire images.

experiment = server.api.model (‘Experiment’, {

‘experiment_id’: fields.String (description = ‘Unique id returned from commands queue’),

‘microscope’: fields.String (required = True, min_length = 1, max_length = 200, description=’Name of microscope’),

‘number_positions’: fields.Integer(required = True, description = ‘Number N of positions to image’),

‘stage_locations’: fields.List (fields.List(fields.Integer), required = True, description = ‘(x,y,z) tuples of N imaging positions’),

‘stage_locations_filter’: fields.List(fields.Boolean, required = False, description = ‘(x,y,z) tuples of N True/False filter’),

‘capture_settings’: fields.List (fields.String, required = True, description = ‘Slidebook experiment names for N positions’),

‘centers_of_interest’: fields.List (fields.List(fields.Integer), description = ‘(x,y,z) tuples of N centers of interest (optional)’),

‘objective’: fields.String (required = True, min_length = 0, max_length = 200, description = ‘Name of objective used for imaging’),

‘time_stamp’: fields.String(required = True, description = ‘Time stamp when request was send’),

‘microscope_action’: fields.String (required = True,

min_length = 1,

max_length = 20,

description = ‘’’list of actions microscope should perform:

snap: take image without moving stage

move: move without snapping image

move_snap: move to new position and execute experiment

exit: exit automation workflow’’’),

‘id_counter’: fields.Integer(description = ‘Counter assigned by service’),

‘status’: fields.String (min_length = 0, max_length = 20, description = ‘Processing status assigned by service’)

})

class ConnectMicroscope()

Class to control 3i hardware through SlideBook software.

class microscope_automation.connectors.connect_slidebook.ConnectMicroscope(cmd_url='http://127.0.0.1:5000', data_url='http://127.0.0.1:5100', microscope='3iW1-0', dummy=False)

clear_experiments()

Clear experiments queue

count_experiments()

Return number of experiments inqueue

create_experiment_path(experiment, experiment_folder)

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

Input:

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

experiment_folder: folder for capture settings

Output:

experiment_path: path to experiment

delete_experiment(experiment_id)

Delete experiment by id

execute_experiment(capture_settings, locations, objective='')

Execute experiments with parameters defined in experiment on multiple positions.

Input:

capture_settings: string with name of experiment as defined within Microscope software

objective: objective used to acquire image. If none keep objective.

locations: list with (x,y,z) stage locations

Output:

success: True when experiment was successfully posted on command server

get_about_command_service()

Retrieve information about command service

get_about_data_service()

Retrieve information about data service

get_experiment(experiment_id)

Return experiment by id

get_experiment_dict()

Retrieve dictionary with all experiments on queue

get_focus_pos()

Return current position of focus drive.

Input:

none

Output:

zPos: position of focus drive in micrometer

get_focus_settings(experiment_path=None, experiment_name=None)

Get focus settings. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

none

get_microscope_name()

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

Input:

none

Output:

Microscope: name of Microscope

get_next_experiment()

Return next (oldest) experiments in queue

get_objective_position_from_experiment_file(experiment_path=None, experiment_name=None)

Function to get the position of the objective used in the experiment Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

none

get_stage_pos(repetitions=5, wait=1)

Return most recent position of Microscope stage.

Input:

repetitions: number of times to try to get a response

wait: wait time per repetition in sec

Output:

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

is_tile_scan(experiment_path=None, experiment_name=None)

Function to check if the experiment is a tile scan. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

none

is_z_stack(experiment_path=None, experiment_name=None)

Function to check if the experiment contains z-stack acquisition. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

none

live_mode_start(experiment)

Start live mode. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

experiment: name of experiment

Output:

none

live_mode_stop(experiment)

Stop live mode. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

experiment: name of experiment

Output:

none

load_image(image, get_meta_data=False)

Load most recent image from data service and return it a class ImageAICS

Input:

image: image object of class ImageAICS.

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

Output:

image: image with data and meta data as ImageAICS class

move_focus_to(zPos)

Move focus to new position. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

zPos, yPos: new focus position in micrometers.

Output:

zFocus: new position of focus drive

move_focus_to_load()

Move focus to load position if defined.

Input:

zPos, yPos: new focus position in micrometers.

Output:

zFocus: new position of focus drive

move_focus_to_work()

Move focus to work position if defined.

Input:

zPos, yPos: new focus position in micrometers.

Output:

zFocus: new position of focus drive

move_stage_to(xPos, yPos, zPos, capture_settings=None, test=False)

Move stage to new position.

Input:

xPos, yPos, zPos: new stage and objective position in micrometers.

capture_settings: capture settings in Slidebook Capture dialog to move stage

test: not used but included for consistency with ZEN Blue API

Output:

xPos, yPos, zPos: new stage and objective position in micrometers

not_implemented(method_name)

Raise exception if method is not implemented.

Input:

method_name: method that calls this method

Output:

none

post_experiment(experiment)

Post experiment as last entry on queue and return updated experiment

remove_all()

Remove all images from queue at data service.

Input:

none

Output:

none

save_image(fileName)

Save last acquired ImageAICS in original file format using microscope software

Raises HardwareCommandNotDefinedError

Input:

file: file name and path for ImageAICS save

Output:

none

set_focus_load_position()

Retrieve current position and set as load position.

Input:

none

Output:

zLoad: current focus position in mum

set_focus_work_position()

Retrieve current position and set as work position.

Input:

none

Output:

z_work: current focus position in mum

snap_image(capture_settings, objective='')

Snap image with parameters defined in experiment at current location. Raise exception if request was not successful

Input:

capture_settings: string with name of capture_settings as defined within Microscope software

objective: objective used to acquire image. If none keep objective.

Return:

response: Return dictionary with response from commands microservice

stop()

Stop Microscope immediately

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

update_tile_positions(experiment_path, experiment_name, x_value, y_value, z_value)

Function to define the position of the tile. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

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

validate_experiment(experiment_path=None, experiment_name=None)

Function to check if the experiment is defined in the Slidebook software

Input:

experiment_path: path of the experiment file - does not matter for Zen Black

experiment_name: name of the experiment

Output:

valid_experiment: bool describing if the experiment is valid

z_down_relative(delta)

Move focus relative to current position away from sample. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

delta: absolute distance in mum

Output:

z: new position of focus drive

z_relative_move(delta)

Move focus relative to current position. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

delta: distance in mum

Output:

z: new position of focus drive

z_stack_range(experiment_path=None, experiment_name=None)

Function to get the range of first z-stack in experiment. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

experiment_path: path of the experiment file

experiment_name: name of the experiment

Output:

none

z_up_relative(delta)

Move focus relative to current position towards sample. Included for parity between Microscope connections.

Raises HardwareCommandNotDefinedError.

Input:

delta: absolute distance in mum

Output:

z: new position of focus drive