Merge back 'chore_release-8.8.0' into 'edge' (#20140)

Resolved conflicts:
- app/src/organisms/ODD/QuickTransferFlow/utils/createQuickTransferFile.ts

Author: ddcc4

.github/workflows/api-test-lint-deploy.yaml

@@ -214,6 +214,10 @@ jobs:
       - uses: './.github/actions/python/setup'
         with:
           project: 'api'
+      - name: 'build api distributables'
+        shell: bash
+        run: make -C api sdist wheel
+
       # creds and repository configuration for deploying python wheels
       - if: ${{ !env.OT_TAG }}
         name: 'upload to test pypi'

.github/workflows/shared-data-test-lint-deploy.yaml

@@ -184,6 +184,10 @@ jobs:
           script: |
             const { buildComplexEnvVars, } = require(`${process.env.GITHUB_WORKSPACE}/.github/workflows/utils.js`)
             buildComplexEnvVars(core, context)
+      - name: 'build shared-data wheel'
+        shell: bash
+        run: make -C shared-data dist-py
+
       # creds and repository configuration for deploying python wheels
       - if: ${{ !env.OT_TAG }}
         name: 'upload to test pypi'

api/src/opentrons/hardware_control/backends/ot3controller.py

@@ -664,11 +664,11 @@ def _build_move_node_axis_runner(
             return None, False
         # Create a target that doesn't incorporate the plunger into a joint axis with the gantry
         plunger_axes = [Axis.P_L, Axis.P_R]
-        move_target = self._move_manager.devectorize_axes(
-            origin, target, speed, plunger_axes
-        )
 
         try:
+            move_target = self._move_manager.devectorize_axes(
+                origin, target, speed, plunger_axes
+            )
             _, movelist = self._move_manager.plan_motion(
                 origin=origin, target_list=[move_target]
             )

api/src/opentrons/protocol_api/labware.py

@@ -822,8 +822,8 @@ def set_calibration(self, delta: Point) -> None:
     def set_offset(self, x: float, y: float, z: float) -> None:
         """Set the labware's position offset.
 
-        The offset is an x, y, z vector in deck coordinates
-        (see :ref:`protocol-api-deck-coords`).
+        An offset of `(x=0, y=0, z=0)` means the labware's uncalibrated position before
+        any offset from Labware Position Check is applied.
 
         How the motion system applies the offset depends on the API level of the protocol.
 
@@ -882,6 +882,9 @@ def set_offset(self, x: float, y: float, z: float) -> None:
     def calibrated_offset(self) -> Point:
         """The front-left-bottom corner of the labware, including its labware offset.
 
+        The offset is an x, y, z vector in deck coordinates
+        (see :ref:`protocol-api-deck-coords`).
+
         When running a protocol in the Opentrons App or on the touchscreen, Labware
         Position Check sets the labware offset.
         """

api/src/opentrons/protocol_engine/commands/capture_image.py

@@ -19,6 +19,7 @@
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
 from ..errors import (
     CameraDisabledError,
+    CameraSettingsInvalidError,
     FileNameInvalidError,
 )
 from ..errors.error_occurrence import ErrorOccurrence
@@ -193,6 +194,26 @@ async def execute(
                 message=f"Capture image filename cannot contain character(s): {SPECIAL_CHARACTERS.intersection(set(params.fileName))}"
             )
 
+        # Validate the image filter parameters
+        if params.brightness is not None and (
+            params.brightness < 0 or params.brightness > 100
+        ):
+            raise CameraSettingsInvalidError(
+                message="Capture image brightness must be a percentage from 0% to 100%."
+            )
+        if params.contrast is not None and (
+            params.contrast < 0 or params.contrast > 100
+        ):
+            raise CameraSettingsInvalidError(
+                message="Capture image contrast must be a percentage from 0% to 100%."
+            )
+        if params.saturation is not None and (
+            params.saturation < 0 or params.saturation > 100
+        ):
+            raise CameraSettingsInvalidError(
+                message="Capture image saturation must be a percentage from 0% to 100%."
+            )
+
         # Handle capturing an image with the CameraProvider - Engine camera settings take priority
         camera_settings = await self._camera_provider.get_camera_settings()
         engine_camera_settings = self._state_view.camera.get_enablement_settings()

api/src/opentrons/protocol_engine/execution/command_executor.py

@@ -155,6 +155,7 @@ async def execute(self, command_id: str) -> None:
         log.debug(
             f"Executing {running_command.id}, {running_command.commandType}, {running_command.params}"
         )
+        error_occurred = False
         try:
             result = await command_impl.execute(
                 running_command.params  # type: ignore[arg-type]
@@ -191,7 +192,7 @@ async def execute(self, command_id: str) -> None:
                     type=error_recovery_type,
                 )
             )
-            await self.capture_error_image(running_command)
+            error_occurred = True
 
         else:
             if isinstance(result, SuccessData):
@@ -227,6 +228,10 @@ async def execute(self, command_id: str) -> None:
                         type=error_recovery_type,
                     )
                 )
+                error_occurred = True
+        finally:
+            # Handle error image capture if appropriate
+            if error_occurred:
                 await self.capture_error_image(running_command)
 
     def cancel_tasks(self, message: str | None = None) -> None:
@@ -236,7 +241,10 @@ def cancel_tasks(self, message: str | None = None) -> None:
     async def capture_error_image(self, running_command: Command) -> None:
         """Capture an image of an error event."""
         try:
-            camera_enablement = await self._camera_provider.get_camera_settings()
+            camera_enablement = self._state_store.camera.get_enablement_settings()
+            if camera_enablement is None:
+                # Utilize the global camera settings
+                camera_enablement = await self._camera_provider.get_camera_settings()
             # Only capture photos of errors if the setting to do so is enabled
             if (
                 camera_enablement.cameraEnabled

api/src/opentrons/protocol_engine/resources/file_provider.py

@@ -22,7 +22,6 @@
     "<",
     ">",
     "*",
-    " ",
     "$",
     "!",
     "?",

api/src/opentrons/system/camera.py

@@ -37,6 +37,8 @@
 ]
 
 # Camera Parameter Globals
+RESOLUTION_MIN = (320, 240)
+RESOLUTION_MAX = (7680, 4320)
 RESOLUTION_DEFAULT = (1920, 1080)
 ZOOM_MIN = 1.0
 ZOOM_MAX = 2.0
@@ -277,7 +279,7 @@ def write_stream_configuration_file_data(data: Dict[str, str]) -> None:
         fd.writelines(file_lines)
 
 
-async def image_capture(
+async def image_capture(  # noqa: C901
     robot_type: RobotType, parameters: ImageParameters
 ) -> bytes | CameraError:
     """Process an Image Capture request with a Camera utilizing a given set of parameters."""
@@ -305,8 +307,16 @@ async def image_capture(
         parameters.saturation < SATURATION_MIN or parameters.saturation > SATURATION_MAX
     ):
         potential_invalid_param = "Saturation"
+    elif parameters.resolution is not None and (
+        parameters.resolution[0] < RESOLUTION_MIN[0]
+        or parameters.resolution[1] < RESOLUTION_MIN[1]
+        or parameters.resolution[0] > RESOLUTION_MAX[0]
+        or parameters.resolution[1] > RESOLUTION_MAX[1]
+    ):
+        potential_invalid_param = "Resolution"
     else:
         potential_invalid_param = None
+
     if potential_invalid_param is not None:
         return CameraError(
             message=f"{potential_invalid_param} parameter is outside the boundaries allowed for image capture.",
@@ -363,3 +373,9 @@ def get_boot_id() -> str:
         return Path("/proc/sys/kernel/random/boot_id").read_text().strip()
     else:
         return "SIMULATED_BOOT_ID"
+
+
+def camera_exists() -> bool:
+    """Validate whether or not the camera device exists."""
+    return os.path.exists(DEFAULT_SYSTEM_CAMERA)
+    # todo(chb, 2025-11-10): Eventually when we support multiple cameras this should accept a camera parameter to check for

api/tests/opentrons/hardware_control/backends/test_ot3_controller.py

@@ -1454,6 +1454,32 @@ def move_group_run_side_effect(
             },
             None,
         ],
+        [
+            {
+                Axis.X: 0,
+                Axis.Y: 0,
+                Axis.Z_L: 0,
+                Axis.Z_R: 0,
+                Axis.P_L: 0,
+            },
+            {
+                Axis.X: 0,  # Zero Length Move, make sure it doesn't raise an error
+                Axis.Y: 0,
+                Axis.Z_L: 0,
+                Axis.P_L: 0,
+            },
+            {
+                Axis.X: 0,
+                Axis.Y: 0,
+                Axis.Z_L: 0,
+                Axis.Z_R: 0,
+                Axis.P_L: 0,
+                Axis.P_R: 0,
+                Axis.Z_G: 0,
+                Axis.G: 0,
+            },
+            None,
+        ],
     ],
 )
 async def test_controller_move(

api/tests/opentrons/protocol_engine/commands/test_capture_image.py

@@ -240,8 +240,8 @@ async def test_ensure_camera_used_precondition_set(
             50,
         ],
         [
-            (1, 2),
-            (1, 2),
+            (320, 240),
+            (320, 240),
             1.5,
             1.5,
             (3, 4),
@@ -254,8 +254,8 @@ async def test_ensure_camera_used_precondition_set(
             75,
         ],
         [
-            (1, 2),
-            (1, 2),
+            (320, 240),
+            (320, 240),
             2.0,
             2.0,
             (3, 4),
@@ -268,8 +268,8 @@ async def test_ensure_camera_used_precondition_set(
             25,
         ],
         [
-            (9999999, 9999999),
-            (9999999, 9999999),
+            (7680, 4320),
+            (7680, 4320),
             1.0,
             1.0,
             (25, 45),
@@ -389,3 +389,56 @@ async def test_raises_filename_error(
         params = CaptureImageParams(fileName="badname" + char)
         with pytest.raises(FileNameInvalidError):
             await subject.execute(params=params)
+
+
+@pytest.mark.parametrize(
+    argnames=[
+        "zoom",
+        "contrast",
+        "brightness",
+        "saturation",
+        "resolution",
+    ],
+    argvalues=[
+        [0.9, 1, 1, 1, (1920, 1080)],
+        [2.1, 1, 1, 1, (1920, 1080)],
+        [1, -1, 1, 1, (1920, 1080)],
+        [1, 101, 1, 1, (1920, 1080)],
+        [1, 1, -1, 1, (1920, 1080)],
+        [1, 1, 101, 1, (1920, 1080)],
+        [1, 1, 1, -1, (1920, 1080)],
+        [1, 1, 1, 101, (1920, 1080)],
+        [1, 1, 1, 1, (0, 0)],
+        [1, 1, 1, 1, (10000, 10000)],
+    ],
+)
+async def test_raises_image_parameter_error(
+    decoy: Decoy,
+    state_view: StateView,
+    file_provider: FileProvider,
+    camera_provider_image_capture: CameraProvider,
+    zoom: float,
+    contrast: float,
+    brightness: float,
+    saturation: float,
+    resolution: Tuple[int, int],
+) -> None:
+    """It should raise CameraSettingsInvalidError when the capture image command is provided bad filter params."""
+    subject = CaptureImageImpl(
+        state_view=state_view,
+        file_provider=file_provider,
+        camera_provider=camera_provider_image_capture,
+    )
+    params = CaptureImageParams(
+        resolution=resolution,
+        zoom=zoom,
+        contrast=contrast,
+        brightness=brightness,
+        saturation=saturation,
+    )
+
+    decoy.when(state_view.files.get_filecount()).then_return(0)
+
+    with mock.patch("os.path.exists", mock.Mock(return_value=True)):
+        with pytest.raises(CameraSettingsInvalidError):
+            await subject.execute(params=params)