framesource 0.3.0__py3-none-any.whl

frame_processors/__init__.py

@@ -0,0 +1,37 @@
+"""Deprecated compatibility shim for the old ``frame_processors`` package.
+
+This package moved to :mod:`framesource.processors`. Importing
+``frame_processors`` still works for now but emits a
+:class:`DeprecationWarning` and will be removed in a future major release.
+Update imports to ``framesource.processors``.
+"""
+
+import importlib
+import sys
+import warnings
+
+warnings.warn(
+    "'frame_processors' is deprecated and will be removed in a future major "
+    "release; import from 'framesource.processors' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+import framesource.processors as _processors
+from framesource.processors import *  # noqa: F401,F403
+
+__all__ = getattr(_processors, "__all__", [])
+
+_SUBMODULE_ALIASES = {
+    "frame_processor": "framesource.processors.frame_processor",
+    "equirectangular360_processor": "framesource.processors.equirectangular360_processor",
+    "fisheye2equirectangular_processor": "framesource.processors.fisheye2equirectangular_processor",
+    "realsense_depth_processor": "framesource.processors.realsense_depth_processor",
+    "hyperspectral_processor": "framesource.processors.hyperspectral_processor",
+}
+
+for _alias, _target in _SUBMODULE_ALIASES.items():
+    try:
+        sys.modules[f"{__name__}.{_alias}"] = importlib.import_module(_target)
+    except Exception:
+        pass

frame_source/__init__.py

@@ -0,0 +1,50 @@
+"""Deprecated compatibility shim for the old ``frame_source`` package.
+
+This package was renamed to :mod:`framesource`. Importing ``frame_source``
+continues to work for now but emits a :class:`DeprecationWarning` and will be
+removed in a future major release. Update imports to ``framesource``.
+"""
+
+import importlib
+import sys
+import warnings
+
+warnings.warn(
+    "'frame_source' is deprecated and will be removed in a future major "
+    "release; import from 'framesource' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+import framesource as _framesource
+from framesource import *  # noqa: F401,F403
+from framesource import FrameSourceFactory, VideoCaptureBase  # noqa: F401
+
+__all__ = getattr(_framesource, "__all__", [])
+__version__ = getattr(_framesource, "__version__", "0.0.0")
+
+# Alias the old flat module paths (e.g. ``frame_source.webcam_capture``) onto
+# the new locations so existing deep imports keep working.
+_SUBMODULE_ALIASES = {
+    "factory": "framesource.factory",
+    "threading_utils": "framesource.threading_utils",
+    "video_capture_base": "framesource.sources.video_capture_base",
+    "webcam_capture": "framesource.sources.webcam_capture",
+    "ipcamera_capture": "framesource.sources.ipcamera_capture",
+    "basler_capture": "framesource.sources.basler_capture",
+    "genicam_capture": "framesource.sources.genicam_capture",
+    "realsense_capture": "framesource.sources.realsense_capture",
+    "ximea_capture": "framesource.sources.ximea_capture",
+    "huateng_capture": "framesource.sources.huateng_capture",
+    "video_file_capture": "framesource.sources.video_file_capture",
+    "folder_capture": "framesource.sources.folder_capture",
+    "screen_capture": "framesource.sources.screen_capture",
+    "audiospectrogram_capture": "framesource.sources.audiospectrogram_capture",
+}
+
+for _alias, _target in _SUBMODULE_ALIASES.items():
+    try:
+        sys.modules[f"{__name__}.{_alias}"] = importlib.import_module(_target)
+    except Exception:
+        # Optional/vendor backend unavailable; skip aliasing it.
+        pass

framesource/__init__.py

@@ -0,0 +1,93 @@
+import importlib
+import logging
+
+# Must be imported before any capture module pulls in cv2 (it configures the
+# OpenCV MSMF backend, which reads its env var at cv2-import time). The `_`
+# prefix sorts it first within this first-party import group.
+from . import _msmf_config as _msmf_config  # noqa: F401
+from .discovery import DeviceInfo
+from .errors import (
+    FrameSourceError,
+    MissingDependencyError,
+    NotConnectedError,
+    UnknownSourceTypeError,
+)
+from .factory import FrameSourceFactory
+from .sources.video_capture_base import Frame, FrameSourceProtocol, VideoCaptureBase
+from .threading_utils import (
+    AsyncFrameSource,
+    FrameProducer,
+    ProducerConsumer,
+    SharedProducer,
+    create_producer_consumer_pair,
+    multiprocess_frame_producer,
+    simple_frame_producer,
+)
+
+logger = logging.getLogger(__name__)
+
+try:
+    from ._version import version as __version__  # generated by setuptools_scm
+except Exception:  # pragma: no cover - fallback when not built/installed
+    try:
+        from importlib.metadata import version as _pkg_version
+
+        __version__ = _pkg_version("framesource")
+    except Exception:
+        __version__ = "0.0.0"
+
+
+# Import capture classes with graceful handling for missing optional
+# dependencies. Unavailable classes are set to None and logged at debug level.
+_OPTIONAL_CLASSES = {
+    "WebcamCapture": "webcam_capture",
+    "AudioSpectrogramCapture": "audiospectrogram_capture",
+    "BaslerCapture": "basler_capture",
+    "GenicamCapture": "genicam_capture",
+    "IPCameraCapture": "ipcamera_capture",
+    "VideoFileCapture": "video_file_capture",
+    "FolderCapture": "folder_capture",
+    "RealsenseCapture": "realsense_capture",
+    "ScreenCapture": "screen_capture",
+    "XimeaCapture": "ximea_capture",
+    "HuatengCapture": "huateng_capture",
+}
+
+for _class_name, _module_name in _OPTIONAL_CLASSES.items():
+    try:
+        _module = importlib.import_module(f".sources.{_module_name}", __name__)
+        globals()[_class_name] = getattr(_module, _class_name)
+    except Exception as e:  # noqa: BLE001 - vendor SDKs may raise non-ImportError
+        globals()[_class_name] = None
+        logger.debug("%s unavailable: %s", _class_name, e)
+
+
+__all__ = [
+    "FrameSourceFactory",
+    "VideoCaptureBase",
+    "Frame",
+    "FrameSourceProtocol",
+    "DeviceInfo",
+    "FrameSourceError",
+    "MissingDependencyError",
+    "UnknownSourceTypeError",
+    "NotConnectedError",
+    "simple_frame_producer",
+    "FrameProducer",
+    "multiprocess_frame_producer",
+    "create_producer_consumer_pair",
+    "ProducerConsumer",
+    "AsyncFrameSource",
+    "SharedProducer",
+    "WebcamCapture",
+    "IPCameraCapture",
+    "BaslerCapture",
+    "GenicamCapture",
+    "RealsenseCapture",
+    "XimeaCapture",
+    "HuatengCapture",
+    "VideoFileCapture",
+    "FolderCapture",
+    "ScreenCapture",
+    "AudioSpectrogramCapture",
+]

framesource/_msmf_config.py

@@ -0,0 +1,26 @@
+"""Configure OpenCV's Media Foundation (MSMF) backend before ``cv2`` loads.
+
+On Windows, OpenCV's MSMF capture backend reads
+``OPENCV_VIDEOIO_MSMF_ENABLE_HW_TRANSFORMS`` **once, when cv2 is first
+imported**. With hardware transforms enabled (the default), opening some
+webcams stalls for 20+ seconds while Media Foundation initializes hardware
+transforms — even though frame throughput afterwards is fine. Disabling them
+makes the camera open near-instantly (measured 22.6s -> 0.33s) with no
+measurable throughput cost.
+
+Because the value is read at ``import cv2`` time, it must be set *before* cv2
+is imported anywhere in the process. This module carries no cv2 dependency and
+is imported first by :mod:`framesource`, ahead of any capture module, so the
+setting is in place in time. ``setdefault`` is used so a user who configured
+the variable explicitly (to ``"0"`` or ``"1"``) always wins.
+
+Caveat: if the host application runs ``import cv2`` and opens an MSMF device
+*before* importing :mod:`framesource`, cv2 has already cached the value and
+this has no effect; set the environment variable yourself in that case.
+"""
+
+import os
+import platform
+
+if platform.system() == "Windows":
+    os.environ.setdefault("OPENCV_VIDEOIO_MSMF_ENABLE_HW_TRANSFORMS", "0")

framesource/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
+
+__commit_id__ = commit_id = None

framesource/discovery.py

@@ -0,0 +1,109 @@
+"""Structured device descriptor returned by ``discover()`` implementations.
+
+Historically each capture type's :meth:`discover` returned a list of plain
+``dict`` objects with type-specific keys. :class:`DeviceInfo` replaces those
+dicts with a typed :mod:`dataclasses` dataclass while remaining fully
+dict-compatible (indexing, ``get``, ``in``, ``keys``/``items``) so existing
+consumers that treated discovery results as dictionaries keep working
+unchanged.
+
+The historical webcam dicts used an ``'id'`` key; that is preserved as an
+alias for :attr:`DeviceInfo.device_id`, and any extra type-specific keys are
+kept flat via :attr:`DeviceInfo.metadata` so ``dev['id']``, ``dev['name']``,
+``dev['index']`` and ``dev['backend_name']`` all still resolve.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class DeviceInfo:
+    """A discovered capture device.
+
+    Instances behave like the plain dicts previously returned by
+    ``discover()``: they support ``dev[key]``, ``dev.get(key)``,
+    ``key in dev``, ``dev.keys()`` and ``dev.items()``. The ``'id'`` key is an
+    alias for :attr:`device_id`, and :attr:`metadata` entries are exposed as
+    flat top-level keys.
+
+    Attributes:
+        device_id: String identifier used as the ``source`` when creating a
+            capture. Exposed under the alias ``'id'`` for dict-compatibility.
+        index: OS/enumeration index, if applicable.
+        name: Human-readable device name.
+        driver: Backend/driver that produced this entry (e.g. ``'opencv'`` or
+            ``'pyaudio'``).
+        id_stable: True when ``device_id`` is stable across reboots/replug
+            (e.g. a serial number); False for OS index-based identifiers.
+        metadata: Free-form extra fields, kept flat for dict-compatibility.
+    """
+
+    device_id: str
+    index: Optional[int] = None
+    name: str = ""
+    driver: str = ""
+    id_stable: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def _flat(self) -> dict[str, Any]:
+        """Return the flat, dict-compatible view (``'id'`` alias + metadata)."""
+        flat: dict[str, Any] = {
+            "id": self.device_id,
+            "index": self.index,
+            "name": self.name,
+            "driver": self.driver,
+            "id_stable": self.id_stable,
+        }
+        flat.update(self.metadata)
+        return flat
+
+    def __getitem__(self, key: str) -> Any:
+        if key in ("id", "device_id"):
+            return self.device_id
+        if key in ("index", "name", "driver", "id_stable"):
+            return getattr(self, key)
+        if key in self.metadata:
+            return self.metadata[key]
+        raise KeyError(key)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Dict-style ``get`` with alias/metadata fallback."""
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+    def __contains__(self, key: str) -> bool:
+        if key in ("id", "device_id", "index", "name", "driver", "id_stable"):
+            return True
+        return key in self.metadata
+
+    def keys(self):
+        """Return the flat top-level keys (``'id'`` alias + metadata keys)."""
+        return self._flat().keys()
+
+    def values(self):
+        """Return the flat top-level values."""
+        return self._flat().values()
+
+    def items(self):
+        """Return the flat ``(key, value)`` pairs."""
+        return self._flat().items()
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return a faithful dict of the dataclass fields.
+
+        Unlike the flat dict-compat view, this uses the canonical
+        ``'device_id'`` key and keeps ``metadata`` nested, so the result
+        round-trips: ``DeviceInfo(**info.as_dict())`` reconstructs an
+        equivalent instance.
+        """
+        return {
+            "device_id": self.device_id,
+            "index": self.index,
+            "name": self.name,
+            "driver": self.driver,
+            "id_stable": self.id_stable,
+            "metadata": dict(self.metadata),
+        }

framesource/errors.py

@@ -0,0 +1,82 @@
+"""Exception hierarchy for FrameSource.
+
+All library-specific errors derive from :class:`FrameSourceError` so callers
+that want to catch "anything FrameSource raises" have a single type to
+catch. At the same time, several of these exceptions are *also* subclassed
+from the built-in exception type that FrameSource historically raised at the
+same call site (e.g. ``ImportError`` for missing optional dependencies,
+``ValueError`` for bad/unknown arguments).
+
+This dual inheritance is deliberate: it preserves backwards compatibility.
+Existing user code written against earlier FrameSource versions may contain
+``except ImportError:`` or ``except ValueError:`` clauses around calls into
+this library. Because ``MissingDependencyError`` is-a ``ImportError`` and
+``UnknownSourceTypeError`` is-a ``ValueError``, that old code keeps working
+unchanged, while new code can catch the more specific FrameSource types (or
+the common ``FrameSourceError`` base) for finer-grained handling.
+"""
+
+from typing import Optional
+
+
+class FrameSourceError(RuntimeError):
+    """Base class for all errors raised by FrameSource.
+
+    Catch this to handle any FrameSource-specific failure without needing
+    to know which built-in exception type it also derives from.
+    """
+
+
+class MissingDependencyError(FrameSourceError, ImportError):
+    """Raised when an optional third-party dependency is not installed.
+
+    Inherits from :class:`ImportError` so existing ``except ImportError:``
+    handlers written against earlier FrameSource versions continue to catch
+    this exception unchanged.
+
+    Attributes:
+        package (str): Name of the missing package (or packages).
+        extra (Optional[str]): Name of the FrameSource extra that installs
+            the dependency (e.g. ``'audio'`` for ``pip install
+            framesource[audio]``), if applicable.
+    """
+
+    def __init__(self, package: str, extra: Optional[str] = None, details: Optional[str] = None):
+        """Initialize the error.
+
+        Args:
+            package: Name of the missing package (or packages).
+            extra: Name of the FrameSource extra that installs the
+                dependency, if any. When provided, the message includes an
+                install hint (``pip install framesource[<extra>]``).
+            details: Additional details to append to the message, such as
+                the original ``ImportError`` text.
+        """
+        self.package = package
+        self.extra = extra
+
+        message = f"{package} is required but not installed."
+        if extra:
+            message += f" Install with: pip install framesource[{extra}]"
+        if details:
+            message += f" ({details})"
+
+        super().__init__(message)
+
+
+class UnknownSourceTypeError(FrameSourceError, ValueError):
+    """Raised when a requested capture source type is not registered.
+
+    Inherits from :class:`ValueError` so existing ``except ValueError:``
+    handlers written against earlier FrameSource versions continue to catch
+    this exception unchanged.
+    """
+
+
+class NotConnectedError(FrameSourceError):
+    """Raised when an operation requires a connected source but it isn't.
+
+    Reserved for use by subclasses and downstream code that wants to signal
+    reads/operations attempted on a disconnected capture source. FrameSource
+    itself does not currently raise this from its read paths.
+    """