Clarity, second review @sk1p

Thx! :-)

src/microscope_calibration/util/stem_overfocus_sim.py

@@ -78,28 +78,48 @@ def detector_px_to_specimen_px(
     '''
     Model Figure 2 of https://arxiv.org/abs/2403.08538
 
+    The pixel coordinates refer to the center of a pixel: In :func:`_project`
+    they are rounded to the nearest integer. This function is just transforming
+    coordinates independent of actual scan and detector sizes. Rounding and
+    bounds checks are performed in :func:`_project`.
+
+    The specimen pixel coordinates calculated by this function are combined with
+    the scan coordinates in :func:`_project` to model the scan.
+
     Parameters
     ----------
 
     y_px, x_px : float
-        Detector pixel coordinates to project
+        Detector pixel coordinates to project. They are relative to (cy, cx),
+        where specifying pixel coordinates (0.0, 0.0) maps to physical
+        coordinates (-cy * detector_pixel_size, -cx *detector_pixel_size), and
+        pixel coordinates (cy, cx) map to physical coordinates (0.0. 0.0).
     cy, cx : float
-        Detector center in detector pixel coordinates
+        Detector center in detector pixel coordinates. This defines the position
+        of the "straight through" beam on the detector.
     detector_pixel_size, scan_pixel_size : float
-        Physical pixel sizes. This assumes a uniform scan and detector grid in x
-        and y direction
+        Physical pixel sizes in m. This assumes a uniform scan and detector grid
+        in x and y direction
     camera_length : float
-        Virtual distance from specimen to detector
+        Virtual distance from specimen to detector in m
     overfocus : float
-        Virtual distance from focus point to specimen. Underfocus is specified
-        as a negative overfocus.
+        Virtual distance from focus point to specimen in m. Underfocus is
+        specified as a negative overfocus.
     transformation_matrix : np.ndarray[float]
-        2x2 transformation matrix for detector coordinates. This is used to
-        specify rotation and handedness change consistent with other methods in
-        LiberTEM. It can be calculated with :fun:`get_transformation_matrix`.
+        2x2 transformation matrix for detector coordinates. It acts around (cy,
+        cx). This is used to specify rotation and handedness change consistent
+        with other methods in LiberTEM. It can be calculated with
+        :fun:`get_transformation_matrix`.
     fov_size_y, fov_size_x : float
         Size of the scan area (field of view) in scan pixels. The scan
-        coordinate system is centered in the middle of the field of view.
+        coordinate system is centered in the middle of this field of view,
+        meaning that the "straight through" beam (y_px, x_px) == (cy, cx) is
+        mapped to (fov_size_y/2, fov_size_x/2)
+
+    Returns
+    -------
+    specimen_px_y, specimen_px_x : float
+        Beam position on the specimen in scan pixel coordinates.
     '''
     position_y, position_x = (y_px - cy) * detector_pixel_size, (x_px - cx) * detector_pixel_size
     position_y, position_x = transformation_matrix @ np.array((position_y, position_x))

tests/test_overfocus.py

@@ -61,13 +61,35 @@ def test_get_transformation_matrix(params):
                 'cx': 0,
                 'y_px': 0.,
                 'x_px': 0.,
+                # fov_size_* == 0 means that (0, 0) in scan coordinates is
+                # (0, 0) in physical coordinates.
                 'fov_size_y': 0,
                 'fov_size_x': 0,
                 'transformation_matrix': np.array(((1., 0.), (0., 1.))),
             },
             # Straight through central beam
             (0, 0)
         ),
+        (
+            {
+                'overfocus': 0.1234,
+                'scan_pixel_size': 0.987,
+                'camera_length': 2.34,
+                'detector_pixel_size': 0.71,
+                'cy': 13,
+                'cx': 14,
+                'y_px': 13.,
+                'x_px': 14.,
+                'fov_size_y': 5,
+                'fov_size_x': 6,
+                'transformation_matrix': np.array(((0., 1.), (-1., 0.))),
+            },
+            # Straight through central beam goes through center of fov. The
+            # straight through beam is not affected by scan rotation, flip_y,
+            # overfocus, scan pixel size, detector pixel size, or camera length
+            # fov_size_y/2, fov_size_x/2
+            (2.5, 3)
+        ),
         (
             {
                 'overfocus': 1,
@@ -363,10 +385,10 @@ def test_project_scale():
         detector_shape=(detector_size, detector_size),
         sim_params=params,
     )
-    # Center of the scan, severy second detector pixel
+    # Center of the scan, every second detector pixel
     assert_allclose(obj, projected[size//2, size//2, ::2, ::2])
     # Scan area, trace of center of detector
-    assert_allclose(obj, projected[:, :, size*2//2, size*2//2])
+    assert_allclose(obj, projected[:, :, detector_size//2, detector_size//2])
 
 
 def test_project_2():