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_calibrated Raise an exception if the image_to_stage_displacement matrix is 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 move_in_image_coordinates Move by a given number of pixels on the camera.
Instance Variable last_calibration The most recent CSM calibration.
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.
def assert_calibrated(self): (source)

Raise an exception if the image_to_stage_displacement matrix is not set.

@lt.thing_action
def calibrate_1d(self, camera: CameraClient, stage: Stage, logger: lt.deps.InvocationLogger, direction: tuple[float, float, float]) -> DenumpifyingDict: (source)

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

@lt.thing_action
def calibrate_xy(self, camera: CameraClient, stage: Stage, logger: lt.deps.InvocationLogger) -> DenumpifyingDict: (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.thing_action
def move_in_image_coordinates(self, stage: Stage, 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 = (source)

The most recent CSM calibration.

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

The image size used to calibrate the image_to_stage_displacement_matrix.

@lt.thing_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(image_to_stage_displacement_matrix),
    np.array([dy,dx]),
)
@lt.thing_property
thing_state: dict[str, Any] = (source)

Summary metadata describing the current state of the Thing.