opentrons 8.7.0a7__py3-none-any.whl → 8.8.0a7__py3-none-any.whl

opentrons/system/camera.py

@@ -1,10 +1,68 @@
 import asyncio
 import os
 from pathlib import Path
-
-from opentrons.config import ARCHITECTURE, SystemArchitecture
+import logging
+from functools import lru_cache
+from enum import Enum
+from typing import Dict, Optional
+from opentrons.config import ARCHITECTURE, SystemArchitecture, get_opentrons_path
 from opentrons_shared_data.errors.exceptions import CommunicationError
 from opentrons_shared_data.errors.codes import ErrorCodes
+from opentrons.config import IS_ROBOT
+from opentrons_shared_data.robot.types import RobotType, RobotTypeEnum
+from opentrons.protocol_engine.resources.camera_provider import (
+    CameraProvider,
+    ImageParameters,
+    CameraError,
+    CameraSettings,
+)
+from opentrons.system import ffmpeg
+
+log = logging.getLogger(__name__)
+
+# Default System Cameras
+DEFAULT_SYSTEM_CAMERA = "/dev/ot_system_camera"
+
+# Stream Globals
+DEFAULT_CONF_FILE = (
+    "/lib/systemd/system/opentrons-live-stream/opentrons-live-stream.env"
+)
+STREAM_CONF_FILE_KEYS = [
+    "BOOT_ID",
+    "STATUS",
+    "SOURCE",
+    "RESOLUTION",
+    "FRAMERATE",
+    "BITRATE",
+]
+
+# Camera Parameter Globals
+RESOLUTION_MIN = (320, 240)
+RESOLUTION_MAX = (7680, 4320)
+RESOLUTION_DEFAULT = (1920, 1080)
+ZOOM_MIN = 1.0
+ZOOM_MAX = 2.0
+ZOOM_DEFAULT = 1.0
+CONTRAST_MIN = 0.0
+CONTRAST_MAX = 2.0
+CONTRAST_DEFAULT = 1.0
+BRIGHTNESS_MIN = -128
+BRIGHTNESS_MAX = 128
+BRIGHTNESS_DEFAULT = 0
+SATURATION_MIN = 0.0
+SATURATION_MAX = 2.0
+SATURATION_DEFAULT = 1.0
+
+
+class StreamConfigurationKeys(str, Enum):
+    """The Configuration Key Types."""
+
+    BOOT_ID = "BOOT_ID"
+    STATUS = "STATUS"
+    SOURCE = "SOURCE"
+    RESOLUTION = "RESOLUTION"
+    FRAMERATE = "FRAMERATE"
+    BITRATE = "BITRATE"
 
 
 class CameraException(CommunicationError):
@@ -17,7 +75,7 @@ class CameraException(CommunicationError):
 
 
 async def take_picture(filename: Path) -> None:
-    """Take a picture and save it to filename
+    """Legacy method to take a picture and save it to filename
 
     :param filename: Name of file to save picture to
     :param loop: optional loop to use
@@ -49,3 +107,275 @@ async def take_picture(filename: Path) -> None:
         raise CameraException("Failed to communicate with camera", res)
     if not filename.exists():
         raise CameraException("Failed to save image", "")
+
+
+def get_stream_configuration_filepath() -> Path:
+    """Return the file path to the Opentrons Live Stream Configuration file."""
+    filepath = get_opentrons_path("live_stream_environment_file")
+    if IS_ROBOT and not os.path.exists(filepath):
+        # If the dynamic configuration file doesn't exist make it using our defaults file
+        with open(DEFAULT_CONF_FILE, "r") as default_config:
+            content = default_config.read()
+        with open(filepath, "w") as new_config_file:
+            new_config_file.write(content)
+    return filepath
+
+
+def robot_supports_livestream(robot_type: RobotType) -> bool:
+    """Validate whether or not robot supports live streaming service."""
+    robot = RobotTypeEnum.robot_literal_to_enum(robot_type)
+    if robot == RobotTypeEnum.OT2:
+        # If we are on an OT-2 we do not support live streams
+        return False
+    return True
+
+
+async def update_live_stream_status(
+    robot_type: RobotType,
+    stream_status: bool,
+    camera_provider: CameraProvider,
+    override_settings: Optional[CameraSettings] = None,
+) -> None:
+    """Update and handle a change in the Opentrons Live Stream status."""
+    if not IS_ROBOT or robot_supports_livestream(robot_type) is False:
+        # If we are not on a robot we simply no-op updating the stream
+        return None
+
+    contents = load_stream_configuration_file_data()
+    if contents is None:
+        log.error("Opentrons Live Stream Configuration file cannot be updated.")
+        return None
+
+    # Validate the stream status
+    if override_settings is not None:
+        camera_enable_settings = override_settings
+    else:
+        camera_enable_settings = await camera_provider.get_camera_settings()
+    status = "OFF"
+    if (
+        stream_status
+        and camera_enable_settings.cameraEnabled
+        and camera_enable_settings.liveStreamEnabled
+    ):
+        # Check to see if the camera device is available
+        raw_device = str(contents["SOURCE"])[1:-1]
+        if not os.path.exists(raw_device):
+            log.error(
+                f"Opentrons Live Stream cannot sample the camera. No video device found with device path: {raw_device}"
+            )
+        # Enable the stream
+        status = "ON"
+    # Overwrite the contents
+    contents["BOOT_ID"] = get_boot_id()
+    contents["STATUS"] = status
+    write_stream_configuration_file_data(contents)
+    await restart_live_stream(robot_type)
+
+
+async def stop_live_stream(robot_type: RobotType) -> None:
+    """Attempt to stop the Opentrons Live Stream service."""
+    if robot_supports_livestream(robot_type) is False:
+        # No-op on OT-2 since we don't have a live stream service there
+        return None
+
+    command = ["systemctl", "stop", "opentrons-live-stream"]
+    subprocess = await asyncio.create_subprocess_exec(
+        *command,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout, stderr = await subprocess.communicate()
+    if subprocess.returncode == 0:
+        log.info("Stopped the opentrons-live-stream service.")
+    else:
+        log.error(
+            f"Failed to stop opentrons-live-stream, returncode:{ subprocess.returncode}, stdout: {stdout.decode()}, stderr: {stderr.decode()}"
+        )
+
+
+async def restart_live_stream(robot_type: RobotType) -> None:
+    """Attempt to restart the Opentrons Live Stream service."""
+    if robot_supports_livestream(robot_type) is False:
+        # No-op on OT-2 since we don't have a live stream service there
+        return None
+
+    command = ["systemctl", "restart", "opentrons-live-stream"]
+    subprocess = await asyncio.create_subprocess_exec(
+        *command,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout, stderr = await subprocess.communicate()
+    if subprocess.returncode == 0:
+        log.info("Restarted opentrons-live-stream service.")
+    else:
+        log.error(
+            f"Failed to restart opentrons-live-stream, returncode:{ subprocess.returncode}, stdout: {stdout.decode()}, stderr: {stderr.decode()}"
+        )
+
+
+def load_stream_configuration_file_data() -> dict[str, str] | None:
+    """Load the Opentrons Live Stream Conf file and return parsed data or None if an error occurs."""
+    src = get_stream_configuration_filepath()
+    if not src.exists():
+        log.error(f"Opentrons Live Stream configuration file not found: {src}")
+        return None
+    with src.open("rb") as fd:
+        try:
+            return parse_stream_configuration_file_data(fd.read())
+        except Exception as e:
+            log.error(
+                f"Opentrons Live Stream status update file parsing failed with: {e}"
+            )
+    return None
+
+
+def parse_stream_configuration_file_data(data: bytes) -> Dict[str, str] | None:
+    """
+    Parse a collect of bytes for Opentrons Live Stream Configuration data and return a dictionary of
+    results keyed by configuration constants. Returns None if an error occurred during parsing.
+    """
+    contents: Dict[str, str] = {
+        key.decode("utf-8"): val.decode("utf-8")
+        for key, val in [line.split(b"=") for line in data.split(b"\n") if b"=" in line]
+    }
+
+    enum_stream_keys = {stream_key.value for stream_key in StreamConfigurationKeys}
+    if sorted(list(contents.keys())) != sorted(enum_stream_keys):
+        log.error(
+            "Opentrons Live Stream Configuration file data is incorrect or missing."
+        )
+        # We don't want to write bad or incomplete data to the file
+        return None
+
+    # Migrate old camera default file data to new uniform default
+    if contents[StreamConfigurationKeys.SOURCE] == "NONE":
+        contents[StreamConfigurationKeys.SOURCE] = DEFAULT_SYSTEM_CAMERA
+    return contents
+
+
+def write_stream_configuration_file_data(data: Dict[str, str]) -> None:
+    src = get_stream_configuration_filepath()
+    if not src.exists():
+        log.error(f"Opentrons Live Stream configuration file not found: {src}")
+        return None
+
+    enum_stream_keys = {stream_key.value for stream_key in StreamConfigurationKeys}
+    if sorted(list(data.keys())) != sorted(enum_stream_keys):
+        log.error(
+            "Data provided to write is not compatible with Opentrons Live Stream Configuration file."
+        )
+        return None
+
+    with src.open("w") as fd:
+        file_lines = [
+            f"{StreamConfigurationKeys.BOOT_ID}={data[StreamConfigurationKeys.BOOT_ID]}\n",
+            f"{StreamConfigurationKeys.STATUS}={data[StreamConfigurationKeys.STATUS]}\n",
+            f"{StreamConfigurationKeys.SOURCE}={data[StreamConfigurationKeys.SOURCE]}\n",
+            f"{StreamConfigurationKeys.RESOLUTION}={data[StreamConfigurationKeys.RESOLUTION]}\n",
+            f"{StreamConfigurationKeys.FRAMERATE}={data[StreamConfigurationKeys.FRAMERATE]}\n",
+            f"{StreamConfigurationKeys.BITRATE}={data[StreamConfigurationKeys.BITRATE]}\n",
+        ]
+        fd.writelines(file_lines)
+
+
+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."""
+    camera = DEFAULT_SYSTEM_CAMERA
+
+    # We must always validate the camera exists
+    if not os.path.exists(camera):
+        return CameraError(
+            message=f"No video device found with device path {camera}", code=None
+        )
+
+    if parameters.zoom is not None and (
+        parameters.zoom < ZOOM_MIN or parameters.zoom > ZOOM_MAX
+    ):
+        potential_invalid_param = "Zoom"
+    elif parameters.contrast is not None and (
+        parameters.contrast < CONTRAST_MIN or parameters.contrast > CONTRAST_MAX
+    ):
+        potential_invalid_param = "Contrast"
+    elif parameters.brightness is not None and (
+        parameters.brightness < BRIGHTNESS_MIN or parameters.brightness > BRIGHTNESS_MAX
+    ):
+        potential_invalid_param = "Brightness"
+    elif parameters.saturation is not None and (
+        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.",
+            code="IMAGE_SETTINGS",
+        )
+    try:
+        # Always stop the live stream service to ensure the Camera is always free when attempting an image capture
+        await stop_live_stream(robot_type)
+
+        zoom = parameters.zoom if parameters.zoom is not None else ZOOM_DEFAULT
+        contrast = (
+            parameters.contrast if parameters.contrast is not None else CONTRAST_DEFAULT
+        )
+        brightness = (
+            parameters.brightness
+            if parameters.brightness is not None
+            else BRIGHTNESS_DEFAULT
+        )
+        saturation = (
+            parameters.saturation
+            if parameters.saturation is not None
+            else SATURATION_DEFAULT
+        )
+        resolution = (
+            parameters.resolution
+            if parameters.resolution is not None
+            else RESOLUTION_DEFAULT
+        )
+
+        result = await ffmpeg.ffmpeg_capture_image_bytes(
+            robot_type=robot_type,
+            resolution=resolution,
+            camera=camera,
+            zoom=zoom,
+            pan=parameters.pan if parameters.pan is not None else (0, 0),
+            contrast=contrast,
+            brightness=brightness,
+            saturation=saturation,
+        )
+    except Exception:
+        result = CameraError(
+            message="Exception occured during execution of system image capture.",
+            code=None,
+        )
+    finally:
+        # Restart the live stream service
+        await restart_live_stream(robot_type)
+    return result
+
+
+@lru_cache(maxsize=1)
+def get_boot_id() -> str:
+    if IS_ROBOT:
+        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

opentrons/system/ffmpeg.py

@@ -0,0 +1,110 @@
+"""opentrons.system.ffmpeg: Functions and data for interacting with FFMPEG."""
+import asyncio
+import logging
+from typing import Tuple
+from opentrons.protocol_engine.resources.camera_provider import CameraError
+from opentrons_shared_data.robot.types import RobotType
+
+log = logging.getLogger(__name__)
+
+# === FFMPEG Filter Details ===
+# The following filters are utilized via the '-vf' flag to manipulate the final image returned:
+# 'crop' = [output_width]:[output_height]:x:y
+#   The crop is composed of a desired output width and height for the image, and
+#   an X/Y position to begin the crop at (becomes the top left of the new image).
+# 'scale' = [width]:[height]
+#   The resolution of the final image to export, scales up or down based on configuration.
+# 'lut' (Look-Up Table) = 'y' (Luminance) = 'val' (Current value of a given pixel from 0-255)
+#   The equation on the Look up table takes the current luminance value of an image per pixel
+#   and manipulates it using Contrast and Brightness settings. This is applied to the whole image.
+# 'hue' (Image color range) = 's' (Saturation) = [range]
+#   The hue flag uses the 's' (saturation) modifier to scale image color intensity, default is 1.
+
+# todo(chb, 2025-10-13): Right now we're just zooming towards the center of the frame. The 'pan'
+# setting should be used on the latter half of 'crop' to determine our cropping location instead.
+
+
+async def ffmpeg_capture_image_bytes(
+    robot_type: RobotType,
+    resolution: Tuple[int, int],
+    camera: str,
+    zoom: float,
+    pan: Tuple[int, int],
+    contrast: float,
+    brightness: int,
+    saturation: float,
+) -> bytes | CameraError:
+    """Execute an FFMPEG command to capture an image based on various image parameters."""
+    if robot_type == "OT-2 Standard":
+        ot2_brightness: float = (
+            brightness / 128
+        ) * -1  # OT-2's equilizer field takes a value of -1.0 to 1.0 for brightness
+        command = [
+            "ffmpeg",
+            "-hwaccel",
+            "auto",
+            "-video_size",
+            f"{resolution[0]}x{resolution[1]}",
+            "-f",
+            "v4l2",
+            "-i",
+            f"{camera}",
+            "-vf",
+            f"crop=iw/{zoom}:ih/{zoom}:(iw-iw/{zoom})/{zoom}:(ih-ih/{zoom})/{zoom},"
+            f"scale={resolution[0]}:{resolution[1]},"
+            f"eq=brightness={ot2_brightness}:contrast={contrast}:saturation={saturation}",
+            "-frames:v",
+            "1",
+            "-f",
+            "image2pipe",
+            "-vcodec",
+            "mjpeg",
+            "-",
+        ]
+    else:
+        command = [
+            "ffmpeg",
+            "-hwaccel",
+            "auto",
+            "-video_size",
+            f"{resolution[0]}x{resolution[1]}",
+            "-f",
+            "v4l2",
+            "-i",
+            f"{camera}",
+            "-vf",
+            f"crop=iw/{zoom}:ih/{zoom}:(iw-iw/{zoom})/{zoom}:(ih-ih/{zoom})/{zoom},"
+            f"scale={resolution[0]}:{resolution[1]},"
+            f"lut=y=(val-128)*{contrast}+128-{brightness},"
+            f"hue=s={saturation},format=nv12",
+            "-frames:v",
+            "1",
+            "-f",
+            "image2pipe",
+            "-vcodec",
+            "mjpeg",
+            "-",
+        ]
+
+    subprocess = await asyncio.create_subprocess_exec(
+        *command,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout: bytes
+    stderr: bytes
+    stdout, stderr = await subprocess.communicate()
+    if subprocess.returncode == 0:
+        log.info("Successfully captured an image with camera.")
+        # Upon success, dump our byte stream to the result
+        return stdout
+    else:
+        log.error(
+            f"Failed to capture an image with camera, returncode:{ subprocess.returncode}, stdout: {stdout.decode()}, stderr: {stderr.decode()}"
+        )
+        return CameraError(
+            message="Failed to return bytes from FFMPEG image capture.",
+            code=str(subprocess.returncode)
+            if subprocess.returncode is not None
+            else None,
+        )

{opentrons-8.7.0a7.dist-info → opentrons-8.8.0a7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opentrons
-Version: 8.7.0a7
+Version: 8.8.0a7
 Summary: The Opentrons API is a simple framework designed to make writing automated biology lab protocols easy.
 Project-URL: opentrons.com, https://www.opentrons.com
 Project-URL: Source Code On Github, https://github.com/Opentrons/opentrons/tree/edge/api
@@ -24,7 +24,7 @@ Requires-Dist: click<9,>=8.0.0
 Requires-Dist: importlib-metadata>=1.0; python_version < '3.8'
 Requires-Dist: jsonschema<4.18.0,>=3.0.1
 Requires-Dist: numpy<2,>=1.20.0
-Requires-Dist: opentrons-shared-data==8.7.0a7
+Requires-Dist: opentrons-shared-data==8.8.0a7
 Requires-Dist: packaging>=21.0
 Requires-Dist: pydantic-settings<3,>=2
 Requires-Dist: pydantic<3,>=2.0.0
@@ -32,6 +32,6 @@ Requires-Dist: pyserial>=3.5
 Requires-Dist: pyusb==1.2.1
 Requires-Dist: typing-extensions<5,>=4.0.0
 Provides-Extra: flex-hardware
-Requires-Dist: opentrons-hardware[flex]==8.7.0a7; extra == 'flex-hardware'
+Requires-Dist: opentrons-hardware[flex]==8.8.0a7; extra == 'flex-hardware'
 Provides-Extra: ot2-hardware
-Requires-Dist: opentrons-hardware==8.7.0a7; extra == 'ot2-hardware'
+Requires-Dist: opentrons-hardware==8.8.0a7; extra == 'ot2-hardware'