From 92ba79ef7aa760592bd6cc5e7c3ede6fa0ee08d6 Mon Sep 17 00:00:00 2001 From: Richard Bowman Date: Thu, 2 Nov 2023 10:27:27 +0000 Subject: [PATCH] Improved docstrings --- .../things/camera_stage_mapping.py | 23 +++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/src/openflexure_microscope_server/things/camera_stage_mapping.py b/src/openflexure_microscope_server/things/camera_stage_mapping.py index ad44a7c5..bbc45db6 100644 --- a/src/openflexure_microscope_server/things/camera_stage_mapping.py +++ b/src/openflexure_microscope_server/things/camera_stage_mapping.py @@ -137,7 +137,10 @@ class CameraStageMapper(Thing): @thing_action def calibrate_xy(self, hw: HardwareInterfaceDep) -> DenumpifyingDict: - """Move the microscope's stage in X and Y, to calibrate its relationship to the camera""" + """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. + """ logging.info("Calibrating X axis:") cal_x: dict = self.calibrate_1d(hw, (1, 0, 0)) logging.info("Calibrating Y axis:") @@ -161,7 +164,23 @@ class CameraStageMapper(Thing): @thing_property def image_to_stage_displacement_matrix(self) -> List[List[float]]: # 2x2 integer array - """A 2x2 matrix that converts displacement in image coordinates to stage coordinates.""" + """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]), + ) + ``` + """ displacement_matrix = self.thing_settings.get("image_to_stage_displacement") if not displacement_matrix: raise ValueError("The microscope has not yet been calibrated.")