holypipette.devices.manipulator.calibratedunit module

A class to handle a manipulator unit with coordinates calibrated to the reference system of a camera. It contains methods to calibrate the unit.

Should messages be issued? Also ranges should be taken into account

Should this be in devices/ ? Maybe in a separate calibration folder

class holypipette.devices.manipulator.calibratedunit.CalibratedStage(unit, stage=None, microscope=None, camera=None, config=None)

Bases: CalibratedUnit

A horizontal stage calibrated to a fixed reference coordinate system. The optional stage refers to a platform on which the unit is mounted, which can be None. The stage is assumed to be parallel to the focal plane (no autofocus needed)

Parameters:

• unit (ManipulatorUnit for this stage)

• stage (CalibratedUnit for a stage on which this stage might be mounted)

• microscope (ManipulatorUnit for the microscope (single axis))

• camera (a camera, ie, object with a snap() method (optional, for visual calibration))

calibrate()

Automatic calibration for a horizontal XY stage

equalize_matrix(M=None)

Equalizes the length of columns in a matrix, by default the current transformation matrix

mosaic(width=None, height=None)

Takes a photo mosaic. Current position corresponds to the top left corner of the collated image. Stops when the unit’s position is out of range, unless width and height are specified.

Parameters:

• width (total width in pixel (optional))

• height (total height in pixel (optional))

Return type:

A large image of the mosaic.

reference_move(r)

Moves the unit to position r in reference camera system, without moving the stage.

Parameters:

• r (XYZ position vector in um)

• safe (if True, moves the Z axis first or last, so as to avoid touching the coverslip)

reference_relative_move(r)

Moves the unit by vector r in reference camera system, without moving the stage.

Parameters:

r (XYZ position vector in um)

class holypipette.devices.manipulator.calibratedunit.CalibratedUnit(unit, stage=None, microscope=None, camera=None, config=None)

Bases: ManipulatorUnit

analyze_calibration()

Analyzes calibration matrices.

auto_recalibrate(center=True)

Recalibrates the unit by shifting the reference frame (r0). The pipette is visually identified using a stack of photos.

Parameters:

center (if True, move stage and focus to center the pipette)

calculate_up_directions(M)

Calculates up directions for all axes and microscope from the matrix.

calibrate(rig=1)

Automatic calibration. Starts without moving the stage, then moves the stage (unless it is fixed).

calibrate2()

Automatic calibration. Second algorithm: moves along axes of the reference system.

delete_state()

Delete any previously saved state. By default, overwrites the saved_state attribute with None.

equalize_matrix(M=None)

Normalizes the transformation matrix so that each column corresponds to a 1 um move. By default the current transformation matrix is used. This requires a calibrated stage.

focus()

Move the microscope so as to put the pipette tip in focus

load_configuration(config)

Loads configuration from dictionary config. Variables not present in the dictionary are untouched.

locate_pipette(threshold=None, depth=None, return_correlation=False)

Locates the pipette on screen, using photos previously taken.

Parameters:

• threshold (correlation threshold)

• depth (maximum distance in z to search; if None, only uses the depth of the photo stack)

• return_correlation (if True, returns the best correlation in the template matching)

Returns:

x,y,z

Return type:

position on screen relative to center

manual_calibration(landmarks)

Calibrates the unit based on 4 landmarks. The stage must be properly calibrated.

move_and_track(distance, axis, M, move_stage=False)

Moves along one axis and track the pipette with microscope and optionally the stage.

Parameters:

• distance (distance to move)

• axis (axis number)

Returns:

x,y,z

Return type:

pipette position on screen and focal plane

move_back(z0, u0, us0=None)

Moves back up to original position, refocus and locate pipette

Parameters:

• z0 (microscope position)

• u0 (unit position)

• us0 (stage position)

Returns:

x,y,z

Return type:

pipette position on screen and focal plane

move_new_pipette_back()

Moves a new (uncalibrated) pipette back under the microscope

normalize_axis(column)

Normalizes a column so that it corresponds to a 1 um move. This requires a calibrated stage.

pixel_per_um(M=None)

Returns the objective magnification in pixel per um, calculated for each manipulator axis.

recalibrate(xy=(0, 0))

Recalibrates the unit by shifting the reference frame (r0). It assumes that the pipette is centered on screen.

recover_state()

Recover the state (e.g. the position of the manipulators) after a failure or abort. Has to be overwritten in subclasses.

reference_move(r, safe=False)

Moves the unit to position r in reference camera system, without moving the stage.

Parameters:

• r (XYZ position vector in um)

• safe (if True, moves the Z axis first or last, so as to avoid touching the coverslip)

reference_move_not_X(r, safe=False)

Moves the unit to position r in reference camera system, without moving the stage, but without moving the X axis (so this can be done last).

Parameters:

• r (XYZ position vector in um)

• safe (if True, moves the Z axis first or last, so as to avoid touching the coverslip)

reference_move_not_Z(r, safe=False)

Moves the unit to position r in reference camera system, without moving the stage, but without moving the Z axis (so this can be done last).

Parameters:

• r (XYZ position vector in um)

• safe (if True, moves the Z axis first or last, so as to avoid touching the coverslip)

reference_position()

Position in the reference camera system.

Return type:

The current position in um as an XYZ vector.

reference_relative_move(r)

Moves the unit by vector r in reference camera system, without moving the stage.

Parameters:

r (XYZ position vector in um)

refine()

Refine the calibration by iterating over large movements.

safe_move(r, withdraw=0.0, recalibrate=False)

Moves the device to position x (an XYZ vector) in a way that minimizes interaction with tissue.

If the movement is down, the manipulator is first moved horizontally, then along the pipette axis. If the movement is up, a direct move is done.

Parameters:

• r (target position in um, an (X,Y,Z) vector)

• withdraw (in um; if not 0, the pipette is withdrawn by this value from the target position x)

• recalibrate (if True, pipette is recalibrated 1 mm before its target)

save_configuration()

Outputs configuration in a dictionary.

save_state()

Save the current state (e.g. the position of the manipulators) for later recovery in the case of a failure or abort. Has to be overwritten in subclasses. Should save the state to the saved_state variable or overwrite has_saved_state as well.

take_photos(rig=1)

Take photos of the pipette. It is assumed that the pipette is centered and in focus.

withdraw()

Withdraw the pipette to the upper end position

exception holypipette.devices.manipulator.calibratedunit.CalibrationError(message='Device is not calibrated')

Bases: Exception