rahix/openflexure-microscope-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Single line summaries of docstrings

Browse source
This commit is contained in:
Julian Stirling 2025-07-10 01:58:14 +01:00
parent 35d47fe3ed
commit 4dc41bb008
20 changed files with 153 additions and 115 deletions
Download patch file Download diff file Expand all files Collapse all files

5
check_version_sync.py
View file

@ -1,8 +1,5 @@
#! /usr/bin/env python3
"""A script to check that the npm version string matches the python
version string exactly.
"""
"""Check that the npm version string matches the Python version string exactly."""
import json
import tomllib

5
hardware-specific-tests/picamera2/test_acquisition.py
View file

@ -32,8 +32,9 @@ def test_calibration(client):
def test_jpeg_and_array(client):
"""Check that grabbing a jpeg from the stream results in the same size
image as a array capture or a jpeg capture.
"""Check that a jpeg grabbed from the stream is the same size as other captures.
Compare it to an array capture and a jpeg capture.
"""
# Grab a jpeg from the stream
blob = client.grab_jpeg()

4
hardware-specific-tests/picamera2/test_tuning.py
View file

@ -46,7 +46,9 @@ def print_tuning(read_file: bool = False):
def _test_bad_tuning_after_good_tuning(configure: bool = False):
"""Load the default tuning file into the camera, re-load with a broken tuning file,
"""Test loading good, bad, then another good tuning files in sequence.
Load the default tuning file into the camera, re-load with a broken tuning file,
check it errors. Finally check the default tuning file will load again afterwards.
:param configure: Boolean, set true to configure the camera on initial loading

3
pyproject.toml
View file

@ -127,10 +127,9 @@ ignore = [
"E501", # Ignore long lines for now
"D203", # incompatible with D204
"D213", # incompatible with D212
"D400", # A stricter version of #415
# Below are checkers to be turned on gradually
"D205", # Force single line summary!
"D415",
"D400",
"D200",
# These should be turned on before this MR is complete
"D100",

5
scripts/zenodo/zenodo.py
View file

@ -1,8 +1,9 @@
"""Copyright (c) 2020 Bath Open Instrumentation Group
"""A script for uploading to zenodo.
Copyright (c) 2020 Bath Open Instrumentation Group
Adapted from: https://gitlab.com/schlauch/zenodo-api-test/
Copyright (c) 2018 German Aerospace Center (DLR). All rights reserved.
SPDX-License-Identifier: MIT-DLR
"""
import json

11
src/openflexure_microscope_server/logging.py
View file

@ -68,9 +68,7 @@ def retrieve_log_from_file() -> PlainTextResponse:
class OFMHandler(logging.Handler):
"""A child class of logging.Handler. This class handles storing the most recent
logs for access by the server.
"""
"""A logging.Handler that stores the most recent logs for access by the server."""
def __init__(self, level=logging.INFO, max_logs=250):
super().__init__(level=level)
@ -78,8 +76,11 @@ class OFMHandler(logging.Handler):
self._max_logs = max_logs
def append_record(self, record):
"""Use the built in formatter to format the record, then save
it to an array. Pop any in excess of the maximum number of logs
"""Format message and append it to a list of records.
The built in formatter is used to format the record.
Any records in excess of the maximum number of logs are removed.
"""
self._log.append(self.format(record))
while len(self._log) > self._max_logs:

5
src/openflexure_microscope_server/scan_directories.py
View file

@ -224,8 +224,9 @@ class ScanDirectory:
@property
def images_dir(self) -> Optional[str]:
"""The path to the images directory. None is returned if no images directory
was created
"""The path to the images directory.
None is returned if no images directory was created.
"""
im_path = os.path.join(self.dir_path, IMG_DIR_NAME)
if os.path.isdir(im_path):

31
src/openflexure_microscope_server/scan_planners.py
View file

@ -155,8 +155,7 @@ class ScanPlanner:
return tuple(position) in self._remaining_locations
def get_next_location_and_z_estimate(self) -> tuple[XYPos, Optional[int]]:
"""Return the next location to scan, and the estimated z-position
for this location.
"""Return the next location to scan and its estimated z-position.
Note z-position may be None! This indicates that the current z, position
should be used.
@ -176,9 +175,12 @@ class ScanPlanner:
return next_location, z
def closest_focus_site(self, xy_pos: XYPos) -> Optional[XYZPos]:
"""Return the xyz position of the closest site where focus was achieved
to the input xy_position, with the most recently taken image returned in
the case of a tie
"""Return the xyz position of the closest site where focus was achieved.
The most recently taken image is returned in the case of a tie.
:param xy_pos: The xy_position which the returned position should be closest
to.
Returns None if there if no focussed locations are present
"""
@ -338,9 +340,10 @@ class SmartSpiral(ScanPlanner):
self._remaining_locations.sort(key=sort_key)
def get_next_location_and_z_estimate(self) -> tuple[XYPos, Optional[int]]:
"""Return the next location to scan, and the estimated z-position
for this location. This overrides the default behaviour of ScanPlanner
to take the lowest value of nearest neighbours as this works best for smart stack
"""Return the next location to scan and its estimated z-position.
This overrides the default behaviour of ScanPlanner to take the lowest value of
nearest neighbours as this works best for smart stack.
Note z-position may be None! This indicates that the current z position
should be used.
@ -361,9 +364,11 @@ class SmartSpiral(ScanPlanner):
def select_nearby_focus_site(self, xy_pos: XYPos) -> Optional[XYZPos]:
"""Return the xyz position of the nearby site with the lowest z position.
Lowest position is best, as starting too high causes smart stacking to
autofocus and restart. Starting too low just requires extra movements in +z.
Nearby is defined as within NEIGHBOUR_CUTOFF times the distance to the closest neighbour.
Nearby is defined as within NEIGHBOUR_CUTOFF times the distance to the closest
neighbour.
Returns None if there if no focused locations are present
"""
@ -397,12 +402,10 @@ class SmartSpiral(ScanPlanner):
starting_pos: XYPos | np.ndarray,
ending_pos: XYPos | np.ndarray,
) -> float:
"""Return the number of moves between two xy positions in the x or y direction
whichever is largest
"""Return the larger of x moves or y moves between two xy positions.
Args:
starting_pos: the position to measure from
ending_pos: the position to measure to
:param starting_pos: the position to measure from
:param ending_pos: the position to measure to
"""
move_size = np.array([self._dx, self._dy])

3
src/openflexure_microscope_server/server/serve_static_files.py
View file

@ -9,7 +9,8 @@ THIS_DIR = os.path.dirname(os.path.abspath(__file__))
def add_static_file(app: FastAPI, fname: str, folder: str) -> None:
"""Add a single file to the root of the FastAPI app
"""Add a single file to the root of the FastAPI app.
The file with name ``fname`` will be mounted at ``/fname`` - the
``folder`` does not affect where it is mounted in the app.

37
src/openflexure_microscope_server/things/autofocus.py
View file

@ -159,8 +159,7 @@ def _get_capture_by_id(captures: list[CaptureInfo], buffer_id: int) -> CaptureIn
def _get_capture_index_by_id(captures: list[CaptureInfo], buffer_id: int) -> int:
"""Return the index of the capture with the matching id from a list of CaptureInfo
objects
"""Return the index of the capture with the matching id.
:param captures: A list of capture objects
:param buffer_id: The buffer id of the image to return
@ -432,10 +431,13 @@ class AutofocusThing(lt.Thing):
autofocus_dz: int,
save_resolution: tuple[int, int],
) -> tuple[bool, int]:
"""Run a smart stack, which captures images offset in z, testing
whether the sharpest image is towards the centre of the stack.
The sharpest image, and optionally images around the sharpest,
will be saved using their coordinates to images_dir
"""Run a smart stack.
A smart stack captures images offset in z, testing whether the sharpest image
is towards the centre of the stack.
The sharpest image, and optionally images around the sharpest, will be saved
to the images_dir with their coordinates in the filename.
:param cam: Camera Dependency supplied by LabThings dependency injection
@ -506,15 +508,13 @@ class AutofocusThing(lt.Thing):
stage: Stage,
sharpness_monitor: SharpnessMonitorDep,
) -> None:
"""Return to the initial height of the current stack, and run
a looping autofocus.
"""Return to the initial z position and run a looping autofocus.
:param initial_z_pos: The initial z positions of previous captures
:param autofocus_dz: the range in steps to autofocus
``stage`` and ``sharpness_monitor`` are Thing dependencies passed through
from the calling action
from the calling action.
"""
stage.move_absolute(z=initial_z_pos)
self.looping_autofocus(
@ -530,8 +530,10 @@ class AutofocusThing(lt.Thing):
stack_parameters: StackParams,
cam: WrappedCamera,
) -> int:
"""Save the required captures to disk. Will save the sharpest image,
and any images either side of focus.
"""Save the required captures to disk.
This will save the sharpest image, and optionally extra images either
side of focus (see ``stack_parameters.images_to_save``).
:param sharpest_id: the buffer id index of the sharpest image
:param captures: a list of captures, including file name, image data and
@ -559,8 +561,12 @@ class AutofocusThing(lt.Thing):
cam: WrappedCamera,
stage: Stage,
) -> tuple[bool, list[CaptureInfo], Optional[int]]:
"""Capture a series of images offset by stack_parameters.stack_dz, and test whether
the sharpest image is towards the centre of the stack.
"""Capture a series of images checking that sharpest image central
The images are seperated in z offset by stack_parameters.stack_dz, as they
are captured the last stack_parameters.min_images_to_test images are checked
to see if the sharpest image is central enough in the stack. If it is the stack
completes.
:param stack_parameters: a StackParams object holding stack parameters
:param cam: Camera Dependency to be passed through from the calling action
@ -644,8 +650,7 @@ class AutofocusThing(lt.Thing):
def check_stack_result(
self, captures: list[CaptureInfo]
) -> tuple[Literal["success", "continue", "restart"], int]:
"""Test a list of captures, to decide whether the sharpest image from a
stack is centrally enough in the stack
"""Check if the sharpest image in a list of captures is central enough.
:param captures: a list of the capture objects to for testing if the
sharpness has converged in the centre

14
src/openflexure_microscope_server/things/camera/__init__.py
View file

@ -156,8 +156,10 @@ class BaseCamera(lt.Thing):
def start_streaming(
self, main_resolution: tuple[int, int], buffer_count: int
) -> None:
"""Start (or stop and restart) the camera with the given resolution
for the main stream, and buffer_count number of images in the buffer
"""Start (or stop and restart) the camera.
:param main_resolution: the resolution to use for the main stream.
:param buffer_count: number of images in the stream buffer.
"""
raise NotImplementedError(
"CameraThings must define their own start_streaming method"
@ -342,12 +344,14 @@ class BaseCamera(lt.Thing):
metadata_getter: lt.deps.GetThingStates,
logger: lt.deps.InvocationLogger,
) -> Image:
"""Capture an image in memory and return it with metadata
CaptureError raised if the capture fails for any reason
returns tuple with PIL Image, and dict of metadata.
"""Capture an image in memory and return it with metadata.
This robust capturing method attempts to capture the image five times
each time with a 5 second timeout set.
:raises CaptureError: if the capture fails for any reason
:returns: tuple with PIL Image, and dictionary of metadata.
"""
for capture_attempts in range(5):
try:

12
src/openflexure_microscope_server/things/camera/picamera.py
View file

@ -62,8 +62,9 @@ class PicameraStreamOutput(Output):
class SensorMode(BaseModel):
"""A Pydantic model holding all the information about a specific
sensor mode as reported by the PiCamera.
"""A Pydantic model holding all the information about a specific sensor mode.
This data is as reported by the PiCamera2 module.
"""
unpacked: str
@ -76,10 +77,11 @@ class SensorMode(BaseModel):
class SensorModeSelector(BaseModel):
"""A Pydantic model holding the two values needed to select a PiCamera
Sensor mode. The output size and the bit depth.
"""A Pydantic model holding the two values needed to select a PiCamera Sensor mode.
This is a Pydantic modell so that it can be saved to the disk.
Theses values are the output size and the bit depth.
This is a Pydantic model so that it can be saved to disk.
"""
output_size: tuple[int, int]

14
src/openflexure_microscope_server/things/camera/picamera_recalibrate_utils.py
View file

@ -477,12 +477,16 @@ def set_static_geq(
tuning: dict,
offset: int = 65535,
) -> None:
"""Update the ``rpi.geq`` section of a camera tuning dict to always use green
equalisation that averages the green pixels in the red and blue rows.
"""Update the ``rpi.geq`` section of a camera tuning dict.
``tuning`` will be updated in-place to set the geq offest to the given value.
The default 65535 is the maximum allowed value. This means
the brightness will always be below the threshold where averaging is used.
:param tuning: the raspberry pi tuning file. This will be updated in-place to
set the geq offest to the given value.
:param offset: The desired green equalisation offset. Default 65535. The default is
the maximum allowed value. This means the brightness will always be below the
threshold where averaging is used. This is default as we always need the green
equalisation to averages the green pixels in the red and blue rows due to the
chief ray angle compensation issue when the the stock lens is replaced by an
objective.
"""
geq = Picamera2.find_tuning_algo(tuning, "rpi.geq")
geq["offset"] = offset # max out offset to disable the adaptive green equalisation

29
src/openflexure_microscope_server/things/smart_scan.py
View file

@ -311,8 +311,9 @@ class SmartScanThing(lt.Thing):
@_scan_running
def _save_scan_inputs_json(self):
"""Save scan inputs as a JSON file in the scan folder, to allow
the user to review the settings used in the scan
"""Save scan inputs as a JSON file in the scan folder.
This file allows the user to review the settings used in the scan.
"""
# Should this be a method of the scan_data dataclass?
@ -335,11 +336,10 @@ class SmartScanThing(lt.Thing):
@_scan_running
def _update_scan_data_json(self, scan_result: str):
"""Update scan data as a JSON file in the scan folder, with
data only known at the end of the scan.
"""Update scan data JSON file with data only known at the end of the scan.
Takes scan_result, a string that is either "success",
"cancelled by user", or the error that ended the scan.
Takes scan_result, a string that is either "success", "cancelled by user",
or the error that ended the scan.
"""
# Should this be a method of the scan_data dataclass?
current_time = datetime.now().replace(microsecond=0)
@ -378,10 +378,11 @@ class SmartScanThing(lt.Thing):
@_scan_running
def _run_scan(self):
"""Prepare and run the main scan, handling the threads performing
stitching. Uses the result (or exception) from the scanning to
determine whether the scan should be stitched and the microscope
should return to the starting x,y,z position
"""Prepare and run the main scan, and perform final actions on completion.
The result (or exception) from the main scan loop determines whether the
scan should be stitched and whether the microscope should return to the
starting x,y,z position.
"""
# Used to check if finally was reached via exception (except
# cancel by user)
@ -765,8 +766,7 @@ class SmartScanThing(lt.Thing):
@_scan_running
def _preview_stitch_start(self, overlap: float) -> None:
"""Start stitching a preview of the scan in a background subprocess
"""Start stitching a preview of the scan in a background subprocess.
This uses popen and returns immediately
@ -954,8 +954,9 @@ class SmartScanThing(lt.Thing):
self,
scan_name: str,
):
"""Update the zip to include the files left until the end, then return the
zip file as a Blob
"""Return zip after including any files left until the end.
The zipfile is returned as a Blob.
"""
zip_fname = self._scan_dir_manager.zip_scan(scan_name, final_version=True)
return ZipBlob.from_file(zip_fname)

6
src/openflexure_microscope_server/utilities.py
View file

@ -43,8 +43,10 @@ class ErrorCapturingThread(Thread):
)
def join(self, timeout=None):
"""Join when the thread is complete. If the thread ended due to an unhandled exception,
the exception will be raised when this method is called.
"""Join when the thread is complete.
If the thread ended due to an unhandled exception, the exception will be raised
when this method is called.
"""
super().join(timeout)
# If there is an error in the error buffer clear the buffer and raise it

4
tests/test_scan_directories.py
View file

@ -183,9 +183,7 @@ def test_scan_sequence_and_listing():
def test_scan_name_non_sequential():
"""Check created scans is the correct name if the directories
are not sequential
"""
"""Check new scan has the correct name if the directories are not sequential"""
_clear_scan_dir()
os.makedirs(os.path.join(BASE_SCAN_DIR, "fake_scan_0001"))
os.makedirs(os.path.join(BASE_SCAN_DIR, "fake_scan_0002"))

21
tests/test_scan_planners.py
View file

@ -222,8 +222,10 @@ def test_mark_wrong_location():
def test_closest_focus_wth_large_numbers():
"""The number of steps gets very large in reality runs some tests to check
that everything works well with huge numbers of steps
"""Tests to check that everything works well with huge numbers of steps.
The number of steps gets very large on the micorscope. But most of the tests
above use smaller numbers for clarity.
"""
intial_position = (0, 0)
# Set this up, but we won't use the settings
@ -247,11 +249,18 @@ def test_closest_focus_wth_large_numbers():
def test_example_smart_spiral():
"""Test the smart spiral scan algorithm on the sample types listed
below and defined in scan_test_helpers.load_sample_points
"""Test the smart spiral scan algorithm on the different sample types.
Will fail if the locations or path between locations visited has changed
for any of the samples listed
The sample types:
* ``regular``
* ``lobed``
* ``core"``
These are defined in scan_test_helpers.load_sample_points
This will fail if the locations or path between locations visited has changed
for any of the samples listed.
"""
example_samples = [
"regular",

6
tests/test_smart_scan.py
View file

@ -63,8 +63,10 @@ def test_initial_properties(smart_scan_thing):
def test_inaccessible_scan_methods(smart_scan_thing):
"""The @_scan_running decorator should make some methods
inaccessible unless a scan is running
"""Test that method with @_scan_running decorator is inaccessible.
The @_scan_running decorator makes these functions inacessible unless
a scan is running.
"""
with pytest.raises(ScanNotRunningError):
smart_scan_thing._run_scan()

7
tests/test_stack.py
View file

@ -46,7 +46,7 @@ def even_integers(min_value=0, max_value=1000):
extra_ims=even_integers(min_value=0, max_value=10),
)
def test_stack_params_validation(save_ims, extra_ims):
"""Tests specifically the validation on the image numbers
"""Test the validation of the image numbers for a stack.
save_ims is the number to save (must be odd and positive)
extra_ims is how many more images there are in min_images_to_test than
@ -68,8 +68,9 @@ def test_stack_params_validation(save_ims, extra_ims):
extra_ims=even_integers(min_value=-10, max_value=-1),
)
def test_stack_params_not_enough_test_images(save_ims, extra_ims):
"""Set the extra_ims negative so that min_images_to_test is smaller
than images_to_save.
"""Test error is raised if min_images_to_test is smaller than images_to_save.
``extra_ims`` negative so that min_images_to_test is smaller than images_to_save.
For arguments see test_stack_params_validation
"""

46
tests/utilities/scan_test_helpers.py
View file

@ -14,23 +14,23 @@ THIS_DIR = os.path.dirname(os.path.realpath(__file__))
class FakeSample:
"""A fake sample to test scan algorithms. The sample is able to return
whether a given position is sample, no image associated with the sample
"""A fake sample to test scan algorithms.
The sample is able to return whether a given position is sample, there is no image
associated with the sample
"""
def __init__(self, xy_points: list[tuple[int, int]]):
"""Create the sample from a spline interpolation around
the given points.
"""
"""Create the sample from a spline interpolation around the given points."""
self._sample_perimeter = interp_closed_path(xy_points, 500)
def is_sample(self, pos: tuple[int, int], im_size: tuple[int, int]) -> bool:
"""Return whether an image at a given location with a given image size
is on the sample
"""Return True if an image at a given location is on the sample.
This doesn't check the entire image field as this is designed to be used
where the fake sample is much larger than the image and has smooth edges
It just checks the 4 corners
The image size is specified to check if it overlaps the sample. It doesn't
check the entire image field as this is designed to be used where the fake
sample is much larger than the image and has smooth edges. It just checks the
4 corners.
"""
img_corners = [
(pos[0] + im_size[0], pos[1] + im_size[1]),
@ -77,8 +77,9 @@ def visualise_scan(sample: FakeSample, planner: scan_planners.ScanPlanner) -> Fi
def interp_closed_path(xy_points: list[tuple[int, int]], n_points: int) -> MatPath:
"""Given a lists of xy_points interpolate an n_point closed curve. This can be used
to create an arbitrary sample shape plan a scan.
"""Interpolate an n_point closed curve from a lists of xy_points.
This can be used to create an arbitrary sample shape for testing a scan planner.
Modified from:
https://stackoverflow.com/questions/33962717/interpolating-a-closed-curve-using-scipy
@ -105,8 +106,9 @@ def interp_closed_path(xy_points: list[tuple[int, int]], n_points: int) -> MatPa
def example_smart_spiral(
sample_name: str = "lobed",
) -> tuple[FakeSample, scan_planners.ScanPlanner]:
"""Run an example scan and return the sample scanned and the planner object
after scan is complete
"""Run an example scan.
:returns: The sample scanned and the planner object after scan is complete.
"""
xy_sample_points = load_sample_points(sample_name)
sample = FakeSample(xy_sample_points)
@ -126,11 +128,11 @@ def example_smart_spiral(
def profile_and_save_plot_for_example_smart_spiral():
"""Run the example scan and save a plot and the profile data
Also print the cumulative stats
"""Run the example scan and save a plot and the profile data.
Also print the cumulative stats.
This runs if you run this file directly
This runs if you run this file directly.
"""
import pstats
import cProfile
@ -152,8 +154,9 @@ def profile_and_save_plot_for_example_smart_spiral():
def update_example_smart_spiral_pickle(sample_name: str):
"""Pickle the ScanPlanner for the example_smart_spiral(),
this is done so the history can be compared by testing to check
"""Pickle the ScanPlanner for the example_smart_spiral().
This is done so the history can be compared by testing to check
the algorithm is unchanged.
If the algorithm is purposefully changed then this will need to be
@ -171,8 +174,9 @@ def update_example_smart_spiral_pickle(sample_name: str):
def get_expected_result_for_example_smart_spiral(
sample_name: str,
) -> scan_planners.ScanPlanner:
"""Return the expected ScanPlanner object for the example_smart_spiral(),
this is pickled, so that it can be committed.
"""Return the expected ScanPlanner object for the example_smart_spiral().
This is loaded from a pickle so that the object can be committed to the repo.
"""
pkl_fname = os.path.join(THIS_DIR, f"example_smart_spiral_{sample_name}.pkl")
with open(pkl_fname, "rb") as pkl_file_obj: