streamvision 0.1.0__py3-none-any.whl

streamvision/__init__.py

@@ -0,0 +1 @@
+"""Camera acquisition, InferencePipeline, and the stream-manager client and runtime."""

streamvision/__main__.py

@@ -0,0 +1,108 @@
+"""Run the stream manager standalone: `python -m streamvision --host-factory ...`."""
+
+import argparse
+import importlib.util
+from typing import List, Optional, Tuple
+
+from streamvision.stream.configuration import get_configuration
+from streamvision.stream_manager.manager_app.bootstrap import install_process_settings
+from streamvision.stream_manager.manager_app.host import (
+    PipelineHostDescriptor,
+    import_attribute,
+)
+
+
+def _parse_setting(value: str) -> Tuple[str, str]:
+    key, separator, setting = value.partition("=")
+    if not (key and separator):
+        raise argparse.ArgumentTypeError(f"expected KEY=VALUE, got {value!r}")
+
+    return key, setting
+
+
+def _non_negative_int(value: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(
+            f"expected a non-negative integer, got {value!r}"
+        )
+    if parsed < 0:
+        raise argparse.ArgumentTypeError(
+            f"expected a non-negative integer, got {value!r}"
+        )
+
+    return parsed
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser of the standalone stream manager.
+
+    Returns:
+        The parser.
+    """
+    parser = argparse.ArgumentParser(prog="python -m streamvision")
+    parser.add_argument(
+        "--host-factory",
+        required=True,
+        help="Pipeline host factory as 'package.module:attribute'.",
+    )
+    parser.add_argument(
+        "--host-setting",
+        type=_parse_setting,
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="String keyword argument for the host factory (repeatable).",
+    )
+    parser.add_argument(
+        "--warm-pipelines",
+        type=_non_negative_int,
+        default=0,
+        help="Number of idle pipeline processes kept ready.",
+    )
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    """Launch the stream manager; its address comes from `STREAM_MANAGER_*` env.
+
+    Args:
+        argv: Command-line arguments; `sys.argv[1:]` when `None`.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if importlib.util.find_spec("aiortc") is None:
+        parser.error(
+            "the stream manager needs the webrtc extra: pip install 'streamvision[webrtc]'"
+        )
+    if importlib.util.find_spec("roboflow_workflows") is None:
+        parser.error(
+            "the stream manager needs the workflows extra: "
+            "pip install 'streamvision[webrtc,workflows]'"
+        )
+    host_descriptor = PipelineHostDescriptor(
+        factory=args.host_factory,
+        settings=dict(args.host_setting),
+    )
+
+    # The host module may install its own configuration on import, so import it first.
+    import_attribute(host_descriptor.factory)
+    # Returns what the host installed, else installs and returns the defaults.
+    configuration = get_configuration()
+    install_process_settings(
+        configuration=configuration,
+        host_descriptor=host_descriptor,
+    )
+
+    from streamvision.stream_manager.manager_app.app import start
+
+    start(
+        expected_warmed_up_pipelines=args.warm_pipelines,
+        host_descriptor=host_descriptor,
+    )
+
+
+if __name__ == "__main__":
+    main()

streamvision/camera/buffer_strategies.py

@@ -0,0 +1,28 @@
+"""Buffer strategies of a video source, importable without the decoder.
+
+Request entities validate these values without needing cv2 or the video
+source itself. `video_source` re-exports both enums, and each class keeps the
+`__module__` it was historically defined in, so signatures, annotations and
+pickles still name `video_source` exactly as before the extraction.
+"""
+
+from enum import Enum
+
+_HISTORICAL_MODULE = f"{__name__.rsplit('.', 1)[0]}.video_source"
+
+
+class BufferFillingStrategy(str, Enum):
+    WAIT = "WAIT"
+    DROP_OLDEST = "DROP_OLDEST"
+    ADAPTIVE_DROP_OLDEST = "ADAPTIVE_DROP_OLDEST"
+    DROP_LATEST = "DROP_LATEST"
+    ADAPTIVE_DROP_LATEST = "ADAPTIVE_DROP_LATEST"
+
+
+class BufferConsumptionStrategy(str, Enum):
+    LAZY = "LAZY"
+    EAGER = "EAGER"
+
+
+BufferFillingStrategy.__module__ = _HISTORICAL_MODULE
+BufferConsumptionStrategy.__module__ = _HISTORICAL_MODULE

streamvision/camera/camera.py

@@ -0,0 +1,138 @@
+import logging
+import os
+import time
+from threading import Thread
+
+import cv2
+from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+
+class WebcamStream:
+    """Class to handle webcam streaming using a separate thread.
+
+    Attributes:
+        stream_id (int): The ID of the webcam stream.
+        frame_id (int): A counter for the current frame.
+        vcap (VideoCapture): OpenCV video capture object.
+        width (int): The width of the video frame.
+        height (int): The height of the video frame.
+        fps_input_stream (int): Frames per second of the input stream.
+        grabbed (bool): A flag indicating if a frame was successfully grabbed.
+        frame (array): The current frame as a NumPy array.
+        pil_image (Image): The current frame as a PIL image.
+        stopped (bool): A flag indicating if the stream is stopped.
+        t (Thread): The thread used to update the stream.
+    """
+
+    def __init__(self, stream_id=0, enforce_fps=False):
+        """Initialize the webcam stream.
+
+        Args:
+            stream_id (int, optional): The ID of the webcam stream. Defaults to 0.
+        """
+        self.stream_id = stream_id
+        self.enforce_fps = enforce_fps
+        self.frame_id = 0
+        self.vcap = cv2.VideoCapture(self.stream_id)
+
+        for key in os.environ:
+            if key.startswith("CV2_CAP_PROP"):
+                opencv_prop = key[4:]
+                opencv_constant = getattr(cv2, opencv_prop, None)
+                if opencv_constant is not None:
+                    value = int(os.getenv(key))
+                    self.vcap.set(opencv_constant, value)
+                    logger.info(f"set {opencv_prop} to {value}")
+                else:
+                    logger.warning(f"Property {opencv_prop} not found in cv2")
+
+        self.width = int(self.vcap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        self.height = int(self.vcap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        self.file_mode = self.vcap.get(cv2.CAP_PROP_FRAME_COUNT) > 0
+        if self.enforce_fps and not self.file_mode:
+            logger.warning(
+                "Ignoring enforce_fps flag for this stream. It is not compatible with streams and will cause the process to crash"
+            )
+            self.enforce_fps = False
+        self.max_fps = None
+        if self.vcap.isOpened() is False:
+            logger.debug("[Exiting]: Error accessing webcam stream.")
+            exit(0)
+        self.fps_input_stream = int(self.vcap.get(cv2.CAP_PROP_FPS))
+        logger.debug(
+            "FPS of webcam hardware/input stream: {}".format(self.fps_input_stream)
+        )
+        self.grabbed, self.frame = self.vcap.read()
+        self.pil_image = Image.fromarray(cv2.cvtColor(self.frame, cv2.COLOR_BGR2RGB))
+        if self.grabbed is False:
+            logger.debug("[Exiting] No more frames to read")
+            exit(0)
+        self.stopped = True
+        self.t = Thread(target=self.update, args=())
+        self.t.daemon = True
+
+    def start(self):
+        """Start the thread for reading frames."""
+        self.stopped = False
+        self.t.start()
+
+    def update(self):
+        """Update the frame by reading from the webcam."""
+        frame_id = 0
+        next_frame_time = 0
+        t0 = time.perf_counter()
+        while True:
+            t1 = time.perf_counter()
+            if self.stopped is True:
+                break
+
+            self.grabbed = self.vcap.grab()
+            if self.grabbed is False:
+                logger.debug("[Exiting] No more frames to read")
+                self.stopped = True
+                break
+            frame_id += 1
+            # We can't retrieve each frame on nano and other lower powered devices quickly enough to keep up with the stream.
+            # By default, we will only retrieve frames when we'll be ready process them (determined by self.max_fps).
+            if t1 > next_frame_time:
+                ret, frame = self.vcap.retrieve()
+                if frame is None:
+                    logger.debug("[Exiting] Frame not available for read")
+                    self.stopped = True
+                    break
+                logger.debug(
+                    f"retrieved frame {frame_id}, effective FPS: {frame_id / (t1 - t0):.2f}"
+                )
+                self.frame_id = frame_id
+                self.frame = frame
+                while self.file_mode and self.enforce_fps and self.max_fps is None:
+                    # sleep until we have processed the first frame and we know what our FPS should be
+                    time.sleep(0.01)
+                if self.max_fps is None:
+                    self.max_fps = 30
+                next_frame_time = t1 + (1 / self.max_fps) + 0.02
+            if self.file_mode:
+                t2 = time.perf_counter()
+                if self.enforce_fps:
+                    # when enforce_fps is true, grab video frames 1:1 with inference speed
+                    time_to_sleep = next_frame_time - t2
+                else:
+                    # otherwise, grab at native FPS of the video file
+                    time_to_sleep = (1 / self.fps_input_stream) - (t2 - t1)
+                if time_to_sleep > 0:
+                    time.sleep(time_to_sleep)
+        self.vcap.release()
+
+    def read_opencv(self):
+        """Read the current frame using OpenCV.
+
+        Returns:
+            array, int: The current frame as a NumPy array, and the frame ID.
+        """
+        return self.frame, self.frame_id
+
+    def stop(self):
+        """Stop the webcam stream."""
+        self.stopped = True

streamvision/camera/capture_properties.py

@@ -0,0 +1,121 @@
+"""Apply ``cv2.VideoCapture`` properties in a camera-safe order.
+
+The order in which capture properties are set matters for V4L2 / USB cameras.
+Many UVC cameras (e.g. Logitech C920) open in an uncompressed pixel format
+(YUYV) whose frame-rate ceiling at high resolutions is very low. Setting
+``fps`` while the device is still in that format clamps the frame interval,
+and a later ``fourcc`` switch (e.g. to MJPG) keeps the clamped interval.
+
+Properties often arrive as dictionaries built from JSON payloads whose key
+order is not guaranteed, so they are applied in a fixed order:
+
+1. ``fourcc`` first - selects the pixel format,
+2. every other property in the order given (e.g. frame size),
+3. ``fps`` last - negotiated against the final format and frame size.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import cv2
+from streamvision.camera.fourcc import FOURCC_PROPERTY, parse_fourcc
+
+logger = logging.getLogger(__name__)
+
+FPS_PROPERTY = "fps"
+
+
+def apply_capture_properties(
+    stream: cv2.VideoCapture,
+    *,
+    properties: Optional[Dict[str, Union[float, int, str]]],
+) -> None:
+    """Set capture properties on ``stream`` with ``fourcc`` first and ``fps`` last.
+
+    Properties other than ``fourcc`` and ``fps`` keep their given order.
+    ``fourcc`` may be a four-character code such as ``"MJPG"`` or its numeric
+    value. Codes are case-sensitive and used exactly as given, so ``"mjpg"`` is
+    a different format from ``"MJPG"``. An invalid ``fourcc`` is logged and
+    skipped, and a ``fourcc`` the device rejects is logged as a warning. When
+    ``fourcc`` or ``fps`` is requested, the effective format is read back and
+    logged.
+
+    Args:
+        stream (cv2.VideoCapture): Opened capture to configure.
+        properties (Optional[Dict[str, Union[float, int, str]]]): Mapping of
+            ``cv2.CAP_PROP_*`` suffixes (case-insensitive) to values.
+
+    Raises:
+        AttributeError: If a property name has no ``cv2.CAP_PROP_*`` constant.
+    """
+    if not properties:
+        return
+
+    for property_id, value in _order_capture_properties(properties=properties):
+        is_fourcc = property_id.lower() == FOURCC_PROPERTY
+        if is_fourcc:
+            parsed_fourcc = parse_fourcc(value)
+            if parsed_fourcc is None:
+                logger.warning(
+                    f"Ignoring invalid fourcc video source property: {value!r}. "
+                    "Expected a case-sensitive four-character code (e.g. 'MJPG') "
+                    "or its numeric value."
+                )
+                continue
+            value = parsed_fourcc
+        cv2_id = getattr(cv2, "CAP_PROP_" + property_id.upper())
+        if not stream.set(cv2_id, value):
+            # A rejected fourcc leaves the device in its default pixel format,
+            # which usually caps the frame rate, so it is surfaced by default.
+            log = logger.warning if is_fourcc else logger.debug
+            log(f"Video source did not accept property {property_id}={value!r}")
+
+    requested_ids = {property_id.lower() for property_id in properties}
+    if requested_ids & {FOURCC_PROPERTY, FPS_PROPERTY}:
+        _log_effective_format(stream)
+
+
+def _order_capture_properties(
+    properties: Dict[str, Any],
+) -> List[Tuple[str, Any]]:
+    fourcc, others, fps = [], [], []
+    for property_id, value in properties.items():
+        normalised_id = property_id.lower()
+        if normalised_id == FOURCC_PROPERTY:
+            fourcc.append((property_id, value))
+        elif normalised_id == FPS_PROPERTY:
+            fps.append((property_id, value))
+        else:
+            others.append((property_id, value))
+
+    ordered_properties = fourcc + others + fps
+
+    return ordered_properties
+
+
+def _decode_fourcc(value: float) -> str:
+    code = int(value)
+    if code <= 0:
+        return ""
+
+    decoded = "".join(chr((code >> (8 * i)) & 0xFF) for i in range(4))
+
+    return decoded
+
+
+def _log_effective_format(stream: cv2.VideoCapture) -> None:
+    # Diagnostics only: surfaces drivers that silently ignore or clamp a
+    # requested format / frame rate (e.g. MJPG applied but fps left at 5).
+    try:
+        fourcc = _decode_fourcc(stream.get(cv2.CAP_PROP_FOURCC))
+        fps = stream.get(cv2.CAP_PROP_FPS)
+        width = int(stream.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(stream.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    except Exception as error:  # noqa: BLE001 - diagnostics must never fail startup
+        logger.debug(f"Could not read back video source format: {error!r}")
+        return
+
+    logger.info(
+        "Video source format after applying properties: "
+        f"fourcc={fourcc!r}, fps={fps}, size={width}x{height}"
+    )