openflexure_microscope_server.things.camera_stage_mapping.CameraStageMapper

class documentation

class CameraStageMapper(OFMThing): (source)

View In Hierarchy

A Thing to manage mapping between image and stage coordinates.

To use this Thing, the stage must have axes named "x", "y", and "z", or must override the get_xyz_position() and move_to_xyz_position() methods.

Method assert_calibration Return image_to_stage_displacement matrix or raise error if it's not set.
Method calibrate_xy Measure the relationship between camera and stage coordinates.
Method convert_image_to_stage_coordinates Convert image coordinates to stage coordinates. Only x and y are returned.
Method convert_stage_to_image_coordinates Convert stage coordinates to image coordinates. Only x and y are returned.
Method move_in_image_coordinates Move by a given number of pixels on the camera.
Instance Variable image_resolution The image size used to calibrate the image_to_stage_displacement_matrix.
Instance Variable image_to_stage_displacement_matrix A 2x2 matrix that converts displacement in image coordinates to stage coordinates.
Instance Variable last_cal_timestamp The timestamp of the last calibration. This can be used to get the data file.
Property calibration_required Whether the camera stage mapper needs calibrating.
Property can_calibrate Whether the Thing permits calibration.
Property last_calibration The most recent CSM calibration.
Property thing_state Summary metadata describing the current state of the Thing.
Method _detect_motion_on_axis Move the stage in increasing steps until motion is detected.
Method _fit_all_csm_runs Fit all runs from the camera stage.
Method _fit_backlash Fit the backlash in this run.
Method _fit_csm_matrix Fit the camera stage mapping matrix from all the displacements recorded.
Method _measure_axis_displacement Measure camera vs stage displacement in 1 direction on one axis.
Method _measure_single_axis Measure a single axis, and return the measurement data in a dictionary.
Method _write_csm_data_to_disk Write the CSM data to disk and return the timestamp.
Class Variable _cam Undocumented
Class Variable _class_settings Undocumented
Class Variable _stage Undocumented

Inherited from OFMThing:

Method __enter__ Set the data directory when the Thing is entered.
Method __exit__ Close the OFMThing.
Method create_data_path Create a RelativeDataPath object with this Thing set as the saving Thing.
Property data_dir The data directory for this thing.
Property show_data_in_gallery Whether to show in the Gallery.
Class Variable _show_data_in_gallery Undocumented
Instance Variable _data_dir Undocumented
def assert_calibration(self) -> list[list[float]]: (source)

Return image_to_stage_displacement matrix or raise error if it's not set.

@lt.action
def calibrate_xy(self): (source)

Measure the relationship between camera and stage coordinates.

Note: this is the method used by camera_stage_mapping to measure the CSM matrix, calling this directly will perform a measurement but not set the measurement, for use.

@lt.action
def convert_image_to_stage_coordinates(self, x: float, y: float, **_kwargs: float) -> Mapping[str, int]: (source)

Convert image coordinates to stage coordinates. Only x and y are returned.

@lt.action
def convert_stage_to_image_coordinates(self, x: int, y: int, **_kwargs: int) -> Mapping[str, float]: (source)

Convert stage coordinates to image coordinates. Only x and y are returned.

@lt.action
def move_in_image_coordinates(self, x: float, y: float): (source)

Move by a given number of pixels on the camera.

NB x and y here refer to what is usually understood to be the horizontal and vertical axes of the image. In many toolkits, "matrix indices" are used, which swap the order of these coordinates. This includes opencv and PIL. So, don't be surprised if you find it necessary to swap x and y around.

As a general rule, x usually corresponds to the longer dimension of the image, and y to the shorter one. Checking what shape your chosen toolkit reports for an image usually helps resolve any ambiguity.

image_resolution: tuple[float, float] | None = (source)

The image size used to calibrate the image_to_stage_displacement_matrix.

image_to_stage_displacement_matrix: list[list[float]] | None = (source)

A 2x2 matrix that converts displacement in image coordinates to stage coordinates.

Note that this matrix is defined using "matrix coordinates", i.e. image coordinates are (y,x). To make a move in image coordinates (dy, dx), where dx is horizontal, you should move the stage by:

stage_disp = np.dot(
    np.array([dy,dx]),
    np.array(image_to_stage_displacement_matrix),
)
last_cal_timestamp: str | None = (source)

The timestamp of the last calibration. This can be used to get the data file.

@lt.property
calibration_required: bool = (source)

Whether the camera stage mapper needs calibrating.

@lt.property
can_calibrate: bool = (source)

Whether the Thing permits calibration.

@lt.property
last_calibration: dict | None = (source)

The most recent CSM calibration.

@lt.property
thing_state: Mapping[str, Any] = (source)

Summary metadata describing the current state of the Thing.

def _detect_motion_on_axis(self, axis: Literal['x', 'y'], target_movement_px: int) -> tuple[list[tuple[int, int, int]], list[tuple[float, float]]]: (source)

Move the stage in increasing steps until motion is detected.

The stage is moved in one axis. This will complete if motion is detected in any direction in the camera coordinates.

Returns
tuple[list[tuple[int, int, int]], list[tuple[float, float]]]Two lists, One of absolute x positions and camera .
def _fit_all_csm_runs(self, csm_data: dict[str, Any]) -> tuple[np.ndarray, float]: (source)

Fit all runs from the camera stage.

Parameters
csm_data:dict[str, Any]The dictionary created by calibrate_xy
Returns
tuple[np.ndarray, float]The camera stage mapping matrix and the magnitude of the backlash.
def _fit_backlash(self, axis: Literal['x', 'y'], stage_pos: np.ndarray, cam_pos: np.ndarray) -> tuple[float, int]: (source)

Fit the backlash in this run.

Start with the full fit and remove the initial points until the standard error minimises. Then use the displacement between the first point and the extrapolated fit to calculate the backlash.

Parameters
axis:Literal['x', 'y']Undocumented
stage_pos:np.ndarrayA nx3 matrix of stage positions.
cam_pos:np.ndarrayA nx2 matrix of camera positions.
Returns
tuple[float, int]The estimated backlash, and the number of points to exclude due to backlash.
def _fit_csm_matrix(self, all_stage_displacements: list[np.ndarray], all_cam_displacements: list[np.ndarray]) -> np.ndarray: (source)

Fit the camera stage mapping matrix from all the displacements recorded.

Parameters
all_stage_displacements:list[np.ndarray]A list of nx3 matrixies with the camera displacements for each run.
all_cam_displacements:list[np.ndarray]A list of nx3 matrixies with the stage displacements for each run.
Returns
np.ndarrayThe camera stage mapping matrix.
def _measure_axis_displacement(self, axis: Literal['x', 'y'], step_size: int, n_moves: int = 10) -> tuple[list[tuple[int, int, int]], list[tuple[float, float]]]: (source)

Measure camera vs stage displacement in 1 direction on one axis.

def _measure_single_axis(self, axis: Literal['x', 'y'], *, target_movement_px: int, starting_position: Mapping[str, int]) -> dict[str, Any]: (source)

Measure a single axis, and return the measurement data in a dictionary.

def _write_csm_data_to_disk(self, data: dict[str, Any]) -> str: (source)

Write the CSM data to disk and return the timestamp.

_cam: BaseCamera = (source)

Undocumented

_class_settings: dict[str, bool] = (source)

Undocumented

_stage: BaseStage = (source)

Undocumented