openflexure_microscope_server.things.camera_stage_mapping.CameraStageMapper

class documentation

class CameraStageMapper(lt.Thing): (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_1d Move a microscope's stage in 1D, and figure out the relationship with the camera.
Method calibrate_xy Move the microscope's stage in X and Y, to calibrate its relationship to the camera.
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 last_calibration The most recent CSM calibration.
Property calibration_required Whether the camera stage mapper needs calibrating.
Property image_resolution The image size used to calibrate the image_to_stage_displacement_matrix.
Property image_to_stage_displacement_matrix A 2x2 matrix that converts displacement in image coordinates to stage coordinates.
Property thing_state Summary metadata describing the current state of the Thing.
Class Variable _cam Undocumented
Class Variable _stage Undocumented
def assert_calibration(self) -> list[list[float]]: (source)

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

def calibrate_1d(self, direction: tuple[int, int, int]) -> dict: (source)

Move a microscope's stage in 1D, and figure out the relationship with the camera.

@lt.action
def calibrate_xy(self) -> dict: (source)

Move the microscope's stage in X and Y, to calibrate its relationship to the camera.

This performs two 1d calibrations in x and y, then combines their results.

@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.

last_calibration: dict | None = (source)

The most recent CSM calibration.

@lt.property
calibration_required: bool = (source)

Whether the camera stage mapper needs calibrating.

@lt.property
image_resolution: tuple[float, float] | None = (source)

The image size used to calibrate the image_to_stage_displacement_matrix.

@lt.property
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 may be (y,x). This is an artifact of the way numpy, opencv, etc. define images. If you are making use of this matrix in your own code, you will need to take care of that conversion.

It is often helpful to give a concrete example: to make a move in image coordinates (dy, dx), where dx is horizontal, i.e. the longer dimension of the image, you should move the stage by:

stage_disp = np.dot(
    np.array([dy,dx]),
    np.array(image_to_stage_displacement_matrix),
)
@lt.property
thing_state: Mapping[str, Any] = (source)

Summary metadata describing the current state of the Thing.

_cam: BaseCamera = (source)

Undocumented

_stage: BaseStage = (source)

Undocumented