camera_stage_mapping.camera_stage_calibration_1d

1D calibration of the relationship between a stage and a camera.

This module provides code that will move a microscope stage in 1D, and calibrate its step size and backlash against the camera. The main calibration is done by calibrate_backlash_1d(). To perform a 2D calibration, perform 1D calibrations in two different (ideally orthogonal, though this is not a requirement) directions, and then use image_to_stage_displacement_from_1d() to combine them. This will yield a 2x2 transformation matrix in the same form as calibrate_xy_grid(). Use two 1D calibrations in preference to the grid: it should be more robust and requires less knowledge of the system thanks to its built-in step size estimation.

Copyright Richard Bowman 2019, released under GNU GPL v3

Module Contents

Functions

get_logger(→ logging.Logger)	Get a logger, if the supplied one is None
displacements(positions)	Calculate the absolute distance of each point from the first point.
direction_from_points(points)	Figure out the axis of motion from an Nx2 array of points.
apply_backlash(x[, backlash, start_unwound])	Apply a basic model of backlash to a set of coordinates.
fit_backlash(moves)	Given a set of linear moves forwards and back, estimate backlash.
calibrate_backlash_1d(tracker, move[, direction, ...])	Figure out reasonable step sizes for calibration, and estimate the backlash.
plot_1d_backlash_calibration(results)	Plot the results of a calibration run
image_to_stage_displacement_from_1d(calibrations)	Combine X and Y calibrations

camera_stage_mapping.camera_stage_calibration_1d.get_logger(logger: logging.Logger | None = None) → logging.Logger

Get a logger, if the supplied one is None

camera_stage_mapping.camera_stage_calibration_1d.displacements(positions)

Calculate the absolute distance of each point from the first point.

camera_stage_mapping.camera_stage_calibration_1d.direction_from_points(points)

Figure out the axis of motion from an Nx2 array of points.

The return value is a normalised vector that points along the direction with the most motion. This is the first principal component of the points.

camera_stage_mapping.camera_stage_calibration_1d.apply_backlash(x, backlash=0, start_unwound=True)

Apply a basic model of backlash to a set of coordinates.

The output (y) will lag behind the input by up to backlash

start_unwound (default: True) assumes we change direction at the start of the time series, so you will get no motion until x[i] has moved by at least 2*backlash.

camera_stage_mapping.camera_stage_calibration_1d.fit_backlash(moves)

Given a set of linear moves forwards and back, estimate backlash.

The result is an estimate of the amount of backlash, and the ratio of steps to pixels. The moves should be a camera_stage_tracker.TrackerHistory object.

We use a very basic fitting method: we do a brute-force search for the backlash value, and for each value of backlash we fit a line to the relationship between stage position (after modelling backlash) and image position. We then pick the value of backlash that gets the lowest residuals. Currently the backlash values tried will start at 0 and increase by 1 or by a factor of 1.33 each time.

Returns:

• The return value is a dictionary with the following keys

• backlash (float) – the estimated backlash, in motor steps

• pixels_per_step (float) – the gradient of pixels to steps

• fractional_error (float) – an estimate of the goodness of fit

• stage_direction (numpy.ndarray) – unit vector in the direction of stage motion

• image_direction (numpy.ndarray) – unit vector in the direction of the motion measured on the camera

• pixels_per_step_vector (numpy.ndarray) – The displacement in 2D on the camera resulting from one step in stage_direction. This is equal to the product of pixels_per_step and image_direction.

camera_stage_mapping.camera_stage_calibration_1d.calibrate_backlash_1d(tracker: camera_stage_mapping.camera_stage_tracker.Tracker, move: Callable, direction: numpy.ndarray = np.array([1, 0, 0]), return_data_on_failure: bool = False, logger: logging.Logger | None = None)

Figure out reasonable step sizes for calibration, and estimate the backlash.

Parameters:

• direction (3-element ndarray) – The direction to move in (this is a 1D calibration along an arbitrary axis)

• return_data_on_failure (bool, default False) – Set this to True to suppress exceptions from fitting, and return the data even if the fit fails. Useful when developing things, less helpful when using in production!

camera_stage_mapping.camera_stage_calibration_1d.plot_1d_backlash_calibration(results)

Plot the results of a calibration run

The input parameter should be the dictionary of calibration data that is output by calibrate_backlash_1d. There are a few type conversion functions in here (to_tracker_history and np.ndarray) so that it should still work even if the dictionary has been converted to JSON and back (and thus the np.ndarray objects have been cast to lists).

camera_stage_mapping.camera_stage_calibration_1d.image_to_stage_displacement_from_1d(calibrations)

Combine X and Y calibrations

This uses the output from calibrate_backlash_1d(), run at least twice with orthogonal (or at least different) direction parameters. The resulting 2x2 transformation matrix should map from image to stage coordinates. Currently, the backlash estimate given by this function is only really trustworthy if you’ve supplied two orthogonal calibrations - that will usually be the case.

Returns:

A dictionary of the resulting calibration, including:

• image_to_stage_displacement: (numpy.ndarray) - a 2x2 matrix mapping image displacement to stage displacement

• backlash_vector: (numpy.ndarray) - representing the estimated backlash in each direction

• backlash: (number) - the highest element of backlash_vector

Return type:

dict