viva-genicam 0.2.4__tar.gz

viva_genicam-0.2.4/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: viva-genicam
+Version: 0.2.4
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Multimedia :: Graphics :: Capture
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Dist: numpy>=1.23
+Requires-Dist: pytest>=7 ; extra == 'dev'
+Requires-Dist: maturin>=1.7 ; extra == 'dev'
+Provides-Extra: dev
+Summary: Pure-Rust GenICam stack for Python: discover, control, and stream GigE Vision / USB3 Vision cameras
+Keywords: genicam,gige,usb3-vision,camera,vision
+Home-Page: https://github.com/VitalyVorobyev/viva-genicam
+Author: Vitaly Vorobyev
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://vitalyvorobyev.github.io/viva-genicam/
+Project-URL: Homepage, https://github.com/VitalyVorobyev/viva-genicam
+Project-URL: Repository, https://github.com/VitalyVorobyev/viva-genicam
+
+# viva-genicam (Python)
+
+Pure-Rust GenICam stack with Python bindings. Discover, control, and stream GigE Vision and USB3 Vision cameras from Python — no aravis, no C toolchain, just a wheel.
+
+```bash
+pip install viva-genicam
+```
+
+```python
+import viva_genicam as vg
+
+cams = vg.discover(timeout_ms=500)
+cam = vg.connect_gige(cams[0])
+
+print(cam.get("DeviceModelName"))
+cam.set_exposure_time_us(10_000.0)
+
+with cam.stream() as frames:
+    for frame in frames:
+        arr = frame.to_numpy()          # NumPy (H, W) or (H, W, 3) uint8
+        print(frame.width, frame.height, frame.pixel_format)
+        break
+```
+
+See the [documentation](https://vitalyvorobyev.github.io/viva-genicam/python.html) for the full API.
+
+## Build from source
+
+```bash
+uv venv .venv
+uv pip install --python .venv/bin/python maturin numpy pytest
+uv run --python .venv/bin/python maturin develop -m crates/viva-pygenicam/Cargo.toml
+```
+

viva_genicam-0.2.4/README.md

@@ -0,0 +1,33 @@
+# viva-genicam (Python)
+
+Pure-Rust GenICam stack with Python bindings. Discover, control, and stream GigE Vision and USB3 Vision cameras from Python — no aravis, no C toolchain, just a wheel.
+
+```bash
+pip install viva-genicam
+```
+
+```python
+import viva_genicam as vg
+
+cams = vg.discover(timeout_ms=500)
+cam = vg.connect_gige(cams[0])
+
+print(cam.get("DeviceModelName"))
+cam.set_exposure_time_us(10_000.0)
+
+with cam.stream() as frames:
+    for frame in frames:
+        arr = frame.to_numpy()          # NumPy (H, W) or (H, W, 3) uint8
+        print(frame.width, frame.height, frame.pixel_format)
+        break
+```
+
+See the [documentation](https://vitalyvorobyev.github.io/viva-genicam/python.html) for the full API.
+
+## Build from source
+
+```bash
+uv venv .venv
+uv pip install --python .venv/bin/python maturin numpy pytest
+uv run --python .venv/bin/python maturin develop -m crates/viva-pygenicam/Cargo.toml
+```

viva_genicam-0.2.4/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["maturin>=1.7,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "viva-genicam"
+version = "0.2.4"
+description = "Pure-Rust GenICam stack for Python: discover, control, and stream GigE Vision / USB3 Vision cameras"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Vitaly Vorobyev" },
+]
+requires-python = ">=3.9"
+keywords = ["genicam", "gige", "usb3-vision", "camera", "vision"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Rust",
+    "Topic :: Multimedia :: Graphics :: Capture",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = [
+    "numpy>=1.23",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "maturin>=1.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/VitalyVorobyev/viva-genicam"
+Repository = "https://github.com/VitalyVorobyev/viva-genicam"
+Documentation = "https://vitalyvorobyev.github.io/viva-genicam/"
+
+[tool.maturin]
+module-name = "viva_genicam._native"
+features = ["pyo3/extension-module"]
+manifest-path = "viva-pygenicam/Cargo.toml"
+python-source = "python"

viva_genicam-0.2.4/python/viva_genicam/__init__.py

@@ -0,0 +1,59 @@
+"""Python bindings for viva-genicam.
+
+Pure-Rust GenICam stack for GigE Vision and USB3 Vision cameras.
+
+Quickstart:
+
+    import viva_genicam as vg
+
+    cams = vg.discover(timeout_ms=500)
+    cam = vg.connect_gige(cams[0])
+    print(cam.get("DeviceModelName"))
+
+    with cam.stream() as frames:
+        for frame in frames:
+            arr = frame.to_numpy()
+            break
+"""
+
+from __future__ import annotations
+
+from .camera import Camera
+from .discovery import DeviceInfo, GigeDeviceInfo, U3vDeviceInfo, discover, discover_u3v
+from .errors import (
+    GenApiError,
+    GenicamError,
+    MissingChunkFeatureError,
+    ParseError,
+    TransportError,
+    UnsupportedPixelFormatError,
+)
+from .frame import Frame
+from .node import NodeInfo, NodeKind
+from .stream import FrameStream
+
+# Lazy functional wrappers so the public API is a flat module.
+from .camera import connect_gige, connect_u3v
+
+__all__ = [
+    "Camera",
+    "DeviceInfo",
+    "GigeDeviceInfo",
+    "U3vDeviceInfo",
+    "Frame",
+    "FrameStream",
+    "NodeInfo",
+    "NodeKind",
+    "GenicamError",
+    "GenApiError",
+    "TransportError",
+    "ParseError",
+    "MissingChunkFeatureError",
+    "UnsupportedPixelFormatError",
+    "discover",
+    "discover_u3v",
+    "connect_gige",
+    "connect_u3v",
+]
+
+__version__ = "0.2.4"

viva_genicam-0.2.4/python/viva_genicam/_native.pyi

@@ -0,0 +1,102 @@
+"""Type stubs for the private native extension.
+
+End users should not import from this module directly — use the public
+``viva_genicam`` package instead.
+"""
+
+from typing import Any, Optional
+
+class GigeDeviceInfo:
+    ip: str
+    mac: str
+    manufacturer: Optional[str]
+    model: Optional[str]
+
+class U3vDeviceInfo:
+    bus: int
+    address: int
+    vendor_id: int
+    product_id: int
+    serial: Optional[str]
+    manufacturer: Optional[str]
+    model: Optional[str]
+
+class _Frame:
+    width: int
+    height: int
+    pixel_format: str
+    pixel_format_code: int
+    ts_dev: Optional[int]
+    ts_host: Optional[float]
+    def payload(self) -> bytes: ...
+    def to_numpy(self) -> Any: ...
+    def to_rgb8(self) -> Any: ...
+
+class _FrameStream:
+    def next_frame(self, timeout_ms: Optional[int] = None) -> Optional[_Frame]: ...
+    def close(self) -> None: ...
+    def __iter__(self) -> "_FrameStream": ...
+    def __next__(self) -> _Frame: ...
+
+class _Camera:
+    transport: str
+    xml: str
+    def get(self, name: str) -> str: ...
+    def set(self, name: str, value: str) -> None: ...
+    def set_exposure_time_us(self, value: float) -> None: ...
+    def set_gain_db(self, value: float) -> None: ...
+    def enum_entries(self, name: str) -> list[str]: ...
+    def nodes(self) -> list[str]: ...
+    def node_info(self, name: str) -> Optional[dict]: ...
+    def all_node_info(self) -> list[dict]: ...
+    def categories(self) -> dict[str, list[str]]: ...
+    def acquisition_start(self) -> None: ...
+    def acquisition_stop(self) -> None: ...
+    def open_stream(
+        self,
+        iface: Optional[str],
+        auto_packet_size: Optional[bool],
+        multicast: Optional[str],
+        destination_port: Optional[int],
+    ) -> _FrameStream: ...
+
+def discover_gige(
+    timeout_ms: int = 500,
+    iface: Optional[str] = None,
+    all: bool = False,
+) -> list[GigeDeviceInfo]: ...
+def discover_u3v() -> list[U3vDeviceInfo]: ...
+def connect_gige(
+    device_info: GigeDeviceInfo, iface: Optional[str] = None
+) -> _Camera: ...
+def connect_u3v(device_info: U3vDeviceInfo) -> _Camera: ...
+
+class GenicamError(Exception): ...
+class GenApiError(GenicamError): ...
+class TransportError(GenicamError): ...
+class ParseError(GenicamError): ...
+class MissingChunkFeatureError(GenicamError): ...
+class UnsupportedPixelFormatError(GenicamError): ...
+
+class _testing:
+    class FakeGigeCamera:
+        def __init__(
+            self,
+            width: int = 640,
+            height: int = 480,
+            fps: int = 30,
+            bind_ip: str = "127.0.0.1",
+            port: int = 3956,
+            pixel_format: str = "Mono8",
+        ) -> None: ...
+        @property
+        def ip(self) -> str: ...
+        @property
+        def port(self) -> int: ...
+        def start(self) -> None: ...
+        def stop(self) -> None: ...
+        def device_info(self, timeout_ms: int = 1500) -> GigeDeviceInfo: ...
+        def __enter__(self) -> "_testing.FakeGigeCamera": ...
+        def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool: ...
+
+testing: _testing

viva_genicam-0.2.4/python/viva_genicam/camera.py

@@ -0,0 +1,126 @@
+"""Camera facade: unified API over GigE and U3V transports."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from . import _native
+from .discovery import DeviceInfo, GigeDeviceInfo, U3vDeviceInfo
+from .node import NodeInfo
+from .stream import FrameStream
+
+
+class Camera:
+    """Unified camera handle.
+
+    Construct via ``connect_gige(device_info)`` or ``connect_u3v(device_info)``.
+    The class itself presents the same method surface regardless of transport.
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self, native: Any) -> None:
+        self._native = native
+
+    # ── class factories ──────────────────────────────────────────────────
+
+    @classmethod
+    def open(cls, device: DeviceInfo, **kwargs) -> "Camera":
+        """Connect to ``device`` using the appropriate transport."""
+        if isinstance(device, GigeDeviceInfo):
+            return connect_gige(device, **kwargs)
+        if isinstance(device, U3vDeviceInfo):
+            return connect_u3v(device)
+        raise TypeError(f"unsupported device type: {type(device).__name__}")
+
+    # ── metadata ─────────────────────────────────────────────────────────
+
+    @property
+    def transport(self) -> str:
+        """``"gige"`` or ``"u3v"``."""
+        return self._native.transport
+
+    @property
+    def xml(self) -> str:
+        """Raw GenICam XML fetched from the camera."""
+        return self._native.xml
+
+    # ── feature access ───────────────────────────────────────────────────
+
+    def get(self, name: str) -> str:
+        """Read a feature value, formatted as a string."""
+        return self._native.get(name)
+
+    def set(self, name: str, value: str) -> None:
+        """Set a feature value; the string is parsed per node type."""
+        self._native.set(name, value)
+
+    def set_exposure_time_us(self, value: float) -> None:
+        self._native.set_exposure_time_us(value)
+
+    def set_gain_db(self, value: float) -> None:
+        self._native.set_gain_db(value)
+
+    def enum_entries(self, name: str) -> list[str]:
+        """List allowed entries for an enumeration feature."""
+        return self._native.enum_entries(name)
+
+    # ── introspection ────────────────────────────────────────────────────
+
+    def nodes(self) -> list[str]:
+        """Names of every feature exposed by the camera."""
+        return self._native.nodes()
+
+    def node_info(self, name: str) -> Optional[NodeInfo]:
+        """Metadata for one feature, or ``None`` if not present."""
+        raw = self._native.node_info(name)
+        return NodeInfo.from_dict(raw) if raw is not None else None
+
+    def all_node_info(self) -> list[NodeInfo]:
+        """Metadata for every feature."""
+        return [NodeInfo.from_dict(d) for d in self._native.all_node_info()]
+
+    def categories(self) -> dict[str, list[str]]:
+        """Category → feature-name children."""
+        return dict(self._native.categories())
+
+    # ── control ──────────────────────────────────────────────────────────
+
+    def acquisition_start(self) -> None:
+        self._native.acquisition_start()
+
+    def acquisition_stop(self) -> None:
+        self._native.acquisition_stop()
+
+    # ── streaming ────────────────────────────────────────────────────────
+
+    def stream(
+        self,
+        iface: Optional[str] = None,
+        auto_packet_size: Optional[bool] = None,
+        multicast: Optional[str] = None,
+        destination_port: Optional[int] = None,
+    ) -> FrameStream:
+        """Open a frame stream (context-manager yielding ``Frame`` objects).
+
+        GigE-only parameters are ignored for U3V cameras.
+        """
+        native = self._native.open_stream(
+            iface, auto_packet_size, multicast, destination_port
+        )
+        return FrameStream(native, self)
+
+
+def connect_gige(device_info: GigeDeviceInfo, iface: Optional[str] = None) -> Camera:
+    """Connect to a GigE Vision camera."""
+    native = _native.connect_gige(device_info._handle, iface)
+    return Camera(native)
+
+
+def connect_u3v(device_info: U3vDeviceInfo) -> Camera:
+    """Connect to a USB3 Vision camera."""
+    native = _native.connect_u3v(device_info._handle)
+    return Camera(native)
+
+
+__all__ = ["Camera", "connect_gige", "connect_u3v"]

viva_genicam-0.2.4/python/viva_genicam/discovery.py

@@ -0,0 +1,110 @@
+"""Camera discovery: GigE Vision (network) and USB3 Vision (libusb)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional, Union
+
+from . import _native
+
+
+@dataclass(frozen=True)
+class GigeDeviceInfo:
+    """A discovered GigE Vision camera."""
+
+    ip: str
+    mac: str
+    manufacturer: Optional[str]
+    model: Optional[str]
+    transport: Literal["gige"] = "gige"
+    _handle: Any = field(default=None, repr=False, compare=False)
+
+    @classmethod
+    def _from_native(cls, native: Any) -> "GigeDeviceInfo":
+        return cls(
+            ip=native.ip,
+            mac=native.mac,
+            manufacturer=native.manufacturer,
+            model=native.model,
+            _handle=native,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "ip": self.ip,
+            "mac": self.mac,
+            "manufacturer": self.manufacturer,
+            "model": self.model,
+            "transport": self.transport,
+        }
+
+
+@dataclass(frozen=True)
+class U3vDeviceInfo:
+    """A discovered USB3 Vision camera."""
+
+    bus: int
+    address: int
+    vendor_id: int
+    product_id: int
+    serial: Optional[str]
+    manufacturer: Optional[str]
+    model: Optional[str]
+    transport: Literal["u3v"] = "u3v"
+    _handle: Any = field(default=None, repr=False, compare=False)
+
+    @classmethod
+    def _from_native(cls, native: Any) -> "U3vDeviceInfo":
+        return cls(
+            bus=native.bus,
+            address=native.address,
+            vendor_id=native.vendor_id,
+            product_id=native.product_id,
+            serial=native.serial,
+            manufacturer=native.manufacturer,
+            model=native.model,
+            _handle=native,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "bus": self.bus,
+            "address": self.address,
+            "vendor_id": self.vendor_id,
+            "product_id": self.product_id,
+            "serial": self.serial,
+            "manufacturer": self.manufacturer,
+            "model": self.model,
+            "transport": self.transport,
+        }
+
+
+DeviceInfo = Union[GigeDeviceInfo, U3vDeviceInfo]
+
+
+def discover(
+    timeout_ms: int = 500,
+    iface: Optional[str] = None,
+    all: bool = False,
+) -> list[GigeDeviceInfo]:
+    """Discover GigE Vision cameras on the local network.
+
+    Args:
+        timeout_ms: How long to wait for responses.
+        iface: If given, restrict discovery to the named NIC (e.g. ``"en0"``).
+        all: If True, enumerate all system interfaces and merge results.
+
+    Returns:
+        A list of ``GigeDeviceInfo`` — may be empty.
+    """
+    natives = _native.discover_gige(timeout_ms, iface, all)
+    return [GigeDeviceInfo._from_native(n) for n in natives]
+
+
+def discover_u3v() -> list[U3vDeviceInfo]:
+    """Enumerate USB3 Vision cameras connected to the system."""
+    natives = _native.discover_u3v()
+    return [U3vDeviceInfo._from_native(n) for n in natives]
+
+
+__all__ = ["GigeDeviceInfo", "U3vDeviceInfo", "DeviceInfo", "discover", "discover_u3v"]

viva_genicam-0.2.4/python/viva_genicam/errors.py

@@ -0,0 +1,26 @@
+"""Exception hierarchy for viva-genicam.
+
+All exceptions raised by the native extension subclass ``GenicamError``.
+They are defined on the Rust side and re-exported here so users can do
+``except vg.TransportError:`` without reaching into ``_native``.
+"""
+
+from __future__ import annotations
+
+from . import _native
+
+GenicamError = _native.GenicamError
+GenApiError = _native.GenApiError
+TransportError = _native.TransportError
+ParseError = _native.ParseError
+MissingChunkFeatureError = _native.MissingChunkFeatureError
+UnsupportedPixelFormatError = _native.UnsupportedPixelFormatError
+
+__all__ = [
+    "GenicamError",
+    "GenApiError",
+    "TransportError",
+    "ParseError",
+    "MissingChunkFeatureError",
+    "UnsupportedPixelFormatError",
+]

viva_genicam-0.2.4/python/viva_genicam/frame.py

@@ -0,0 +1,73 @@
+"""Frame wrapper around the native ``_Frame`` handle."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    import numpy as np
+
+
+class Frame:
+    """One image frame produced by the camera.
+
+    Wraps a native handle — the payload is only materialized into Python
+    memory when ``payload()``, ``to_numpy()``, or ``to_rgb8()`` is called.
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self, native: Any) -> None:
+        self._native = native
+
+    @property
+    def width(self) -> int:
+        return self._native.width
+
+    @property
+    def height(self) -> int:
+        return self._native.height
+
+    @property
+    def pixel_format(self) -> str:
+        """Human-readable PFNC name, e.g. ``"Mono8"`` or ``"BayerRG8"``."""
+        return self._native.pixel_format
+
+    @property
+    def pixel_format_code(self) -> int:
+        """Raw PFNC numeric code."""
+        return self._native.pixel_format_code
+
+    @property
+    def ts_dev(self) -> Optional[int]:
+        """Device tick timestamp (camera-local), if reported."""
+        return self._native.ts_dev
+
+    @property
+    def ts_host(self) -> Optional[float]:
+        """Host-mapped timestamp as POSIX seconds, if available."""
+        return self._native.ts_host
+
+    def payload(self) -> bytes:
+        """Raw payload as ``bytes`` (one copy)."""
+        return self._native.payload()
+
+    def to_numpy(self) -> "np.ndarray":
+        """Return a NumPy array shaped for the pixel format.
+
+        - Mono8 → ``(H, W) uint8``
+        - Mono16 → ``(H, W) uint16``
+        - RGB8 / BGR8 / Bayer8 → ``(H, W, 3) uint8``
+        - unknown → ``(N,) uint8``
+        """
+        return self._native.to_numpy()
+
+    def to_rgb8(self) -> "np.ndarray":
+        """Always return an ``(H, W, 3) uint8`` RGB array."""
+        return self._native.to_rgb8()
+
+    def __repr__(self) -> str:
+        return self._native.__repr__()
+
+
+__all__ = ["Frame"]