Initialize camera image gain to a consistent ISO of 150

.github/workflows/release-channel-beta.yml

@@ -4,7 +4,7 @@ on:
   push:
     tags:
       - 'v[0-9]+.[0-9]+.[0-9]+-beta.*'
-      # We want to advance the beta to the latest stable release, too:
+      # We want to advance the beta branch to the latest stable release, too:
       - 'v[0-9]+.[0-9]+.[0-9]+'
 
 jobs:

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project uses [Calendar Versioning](https://calver.org/) with a `YYYY.minor.patch` scheme.
 All dates in this file are given in the [UTC time zone](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).
 
+## Unreleased
+
+### Changed
+
+- (Hardware controller) The default image gain used to initialize the camera module is now set to match a default equivalent ISO value of 150 across all camera sensor types, instead of being hard-coded to 1.0 (which corresponds to an ISO of around 40 or 50 depending on the camera sensor type).
+
 ## v2024.0.0-beta.1 - 2024-06-24
 
 ### Added

control/adafruithat/planktoscope/camera/hardware.py

@@ -314,7 +314,7 @@ def settings(self, updates: SettingsValues) -> None:
         """Update adjustable camera settings from all provided non-`None` values.
 
         Fields provided with `None` values are ignored. If any of the provided non-`None` values is
-        invalid (e.g. out-of-range), none of the settinsg will be changed.
+        invalid (e.g. out-of-range), none of the settings will be changed.
 
         Raises:
             RuntimeError: the method was called before the camera was started, or after it was

control/adafruithat/planktoscope/camera/mqtt.py

@@ -33,7 +33,7 @@ def __init__(self, mjpeg_server_address: tuple[str, int] = ("", 8000)) -> None:
         settings = hardware.SettingsValues(
             auto_exposure=False,
             exposure_time=125,  # the default (minimum) exposure time in the PlanktoScope GUI
-            image_gain=1.0,  # the default ISO of 100 in the PlanktoScope GUI
+            image_gain=1.0,  # image gain is reinitialized after the image sensor is determined
             brightness=0.0,  # the default "normal" brightness
             contrast=1.0,  # the default "normal" contrast
             auto_white_balance=False,  # the default setting in the PlanktoScope GUI
@@ -83,6 +83,21 @@ def run(self) -> None:
             return
         self._camera_checked.set()
 
+        default_iso = 150
+        loguru.logger.debug(f"Setting camera image gain for default ISO value of {default_iso}...")
+        # 100 is the default calibration because that's what's used in the Pi Camera v1 Module, and
+        # it's a round number:
+        calibration = ISO_CALIBRATIONS.get(self._camera.sensor_name, 100)
+        changes = hardware.SettingsValues(image_gain=default_iso / calibration)
+        try:
+            _validate_settings(changes)
+        except (TypeError, ValueError) as e:
+            raise ValueError("Invalid default ISO") from e
+        self._camera.settings = changes
+        loguru.logger.debug(
+            f"Set image gain to {changes.image_gain} for sensor {self._camera.sensor_name}!",
+        )
+
         loguru.logger.info("Starting the MJPEG streaming server...")
         streaming_server = mjpeg.StreamingServer(self._preview_stream, self._mjpeg_server_address)
         streaming_thread = threading.Thread(target=streaming_server.serve_forever)
@@ -220,6 +235,16 @@ def _convert_settings(
     return converted
 
 
+# Refer to https://picamera.readthedocs.io/en/release-1.13/fov.html#sensor-gain for
+# details on how ISO values correspond to image gains with the Pi Camera v2 Module,
+# and refer to https://forums.raspberrypi.com/viewtopic.php?t=282760 for details on ISO
+# vs. image gain calibration for the Pi HQ Camera Module:
+ISO_CALIBRATIONS = {  # this is ISO / image-gain
+    "IMX219": 100 / 1.84,  # Pi Camera v2 Module
+    "IMX477": 100 / 2.3125,  # Pi HQ Camera Module
+}
+
+
 def _convert_image_gain_settings(
     command_settings: dict[str, typing.Any],
     camera_sensor_name: str,
@@ -253,17 +278,9 @@ def _convert_image_gain_settings(
             iso = float(command_settings["iso"])
         except (TypeError, ValueError) as e:
             raise ValueError("Iso number not valid") from e
-        # Refer to https://picamera.readthedocs.io/en/release-1.13/fov.html#sensor-gain for
-        # details on how ISO values correspond to image gains with the Pi Camera v2 Module,
-        # and refer to https://forums.raspberrypi.com/viewtopic.php?t=282760 for details on ISO
-        # vs. image gain calibration for the Pi HQ Camera Module:
-        iso_calibrations = {  # this is ISO / image-gain
-            "IMX219": 100 / 1.84,  # Pi Camera v2 Module
-            "IMX477": 100 / 2.3125,  # Pi HQ Camera Module
-        }
         # 100 is the default calibration because that's what's used in the Pi Camera v1 Module, and
         # it's a round number:
-        calibration = iso_calibrations.get(camera_sensor_name, 100)
+        calibration = ISO_CALIBRATIONS.get(camera_sensor_name, 100)
         converted = converted._replace(image_gain=iso / calibration)
 
     return converted

control/planktoscopehat/planktoscope/camera/hardware.py

@@ -314,7 +314,7 @@ def settings(self, updates: SettingsValues) -> None:
         """Update adjustable camera settings from all provided non-`None` values.
 
         Fields provided with `None` values are ignored. If any of the provided non-`None` values is
-        invalid (e.g. out-of-range), none of the settinsg will be changed.
+        invalid (e.g. out-of-range), none of the settings will be changed.
 
         Raises:
             RuntimeError: the method was called before the camera was started, or after it was

control/planktoscopehat/planktoscope/camera/mqtt.py

@@ -33,7 +33,7 @@ def __init__(self, mjpeg_server_address: tuple[str, int] = ("", 8000)) -> None:
         settings = hardware.SettingsValues(
             auto_exposure=False,
             exposure_time=125,  # the default (minimum) exposure time in the PlanktoScope GUI
-            image_gain=1.0,  # the default ISO of 100 in the PlanktoScope GUI
+            image_gain=1.0,  # image gain is reinitialized after the image sensor is determined
             brightness=0.0,  # the default "normal" brightness
             contrast=1.0,  # the default "normal" contrast
             auto_white_balance=False,  # the default setting in the PlanktoScope GUI
@@ -83,6 +83,21 @@ def run(self) -> None:
             return
         self._camera_checked.set()
 
+        default_iso = 150
+        loguru.logger.debug(f"Setting camera image gain for default ISO value of {default_iso}...")
+        # 100 is the default calibration because that's what's used in the Pi Camera v1 Module, and
+        # it's a round number:
+        calibration = ISO_CALIBRATIONS.get(self._camera.sensor_name, 100)
+        changes = hardware.SettingsValues(image_gain=default_iso / calibration)
+        try:
+            _validate_settings(changes)
+        except (TypeError, ValueError) as e:
+            raise ValueError("Invalid default ISO") from e
+        self._camera.settings = changes
+        loguru.logger.debug(
+            f"Set image gain to {changes.image_gain} for sensor {self._camera.sensor_name}!",
+        )
+
         loguru.logger.info("Starting the MJPEG streaming server...")
         streaming_server = mjpeg.StreamingServer(self._preview_stream, self._mjpeg_server_address)
         streaming_thread = threading.Thread(target=streaming_server.serve_forever)
@@ -220,6 +235,16 @@ def _convert_settings(
     return converted
 
 
+# Refer to https://picamera.readthedocs.io/en/release-1.13/fov.html#sensor-gain for
+# details on how ISO values correspond to image gains with the Pi Camera v2 Module,
+# and refer to https://forums.raspberrypi.com/viewtopic.php?t=282760 for details on ISO
+# vs. image gain calibration for the Pi HQ Camera Module:
+ISO_CALIBRATIONS = {  # this is ISO / image-gain
+    "IMX219": 100 / 1.84,  # Pi Camera v2 Module
+    "IMX477": 100 / 2.3125,  # Pi HQ Camera Module
+}
+
+
 def _convert_image_gain_settings(
     command_settings: dict[str, typing.Any],
     camera_sensor_name: str,
@@ -253,17 +278,9 @@ def _convert_image_gain_settings(
             iso = float(command_settings["iso"])
         except (TypeError, ValueError) as e:
             raise ValueError("Iso number not valid") from e
-        # Refer to https://picamera.readthedocs.io/en/release-1.13/fov.html#sensor-gain for
-        # details on how ISO values correspond to image gains with the Pi Camera v2 Module,
-        # and refer to https://forums.raspberrypi.com/viewtopic.php?t=282760 for details on ISO
-        # vs. image gain calibration for the Pi HQ Camera Module:
-        iso_calibrations = {  # this is ISO / image-gain
-            "IMX219": 100 / 1.84,  # Pi Camera v2 Module
-            "IMX477": 100 / 2.3125,  # Pi HQ Camera Module
-        }
         # 100 is the default calibration because that's what's used in the Pi Camera v1 Module, and
         # it's a round number:
-        calibration = iso_calibrations.get(camera_sensor_name, 100)
+        calibration = ISO_CALIBRATIONS.get(camera_sensor_name, 100)
         converted = converted._replace(image_gain=iso / calibration)
 
     return converted