rocket-welder-sdk 1.1.0__py3-none-any.whl → 1.1.26__py3-none-any.whl

rocket_welder_sdk/external_controls/contracts_old.py

@@ -0,0 +1,105 @@
+"""External Controls event contracts for RocketWelder SDK (legacy - for backward compatibility)."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from uuid import UUID, uuid4
+
+from rocket_welder_sdk.ui.value_types import ControlType
+
+
+class ArrowDirection(Enum):
+    """Arrow directions for ArrowGrid control."""
+
+    UP = "Up"
+    DOWN = "Down"
+    LEFT = "Left"
+    RIGHT = "Right"
+
+
+# Container → UI Commands (Stream: ExternalCommands-{SessionId})
+
+
+@dataclass
+class DefineControl:
+    """Command to define a new control in the UI."""
+
+    control_id: str
+    type: ControlType
+    properties: dict[str, str]
+    region_name: str
+    id: UUID = field(default_factory=uuid4)
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dictionary for EventStore."""
+        return {
+            "Id": str(self.id),
+            "ControlId": self.control_id,
+            "Type": self.type.value,
+            "Properties": self.properties,
+            "RegionName": self.region_name,
+        }
+
+
+@dataclass
+class DeleteControl:
+    """Command to delete a control from the UI."""
+
+    control_id: str
+    id: UUID = field(default_factory=uuid4)
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert to dictionary for EventStore."""
+        return {"Id": str(self.id), "ControlId": self.control_id}
+
+
+@dataclass
+class ChangeControls:
+    """Command to update properties of multiple controls."""
+
+    updates: dict[str, dict[str, str]]  # ControlId -> { PropertyId -> Value }
+    id: UUID = field(default_factory=uuid4)
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dictionary for EventStore."""
+        return {"Id": str(self.id), "Updates": self.updates}
+
+
+# UI → Container Events (Stream: ExternalEvents-{SessionId})
+
+
+@dataclass
+class ButtonDown:
+    """Event when button is pressed."""
+
+    control_id: str
+    id: UUID = field(default_factory=uuid4)
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert to dictionary for EventStore."""
+        return {"Id": str(self.id), "ControlId": self.control_id}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> "ButtonDown":
+        """Create from EventStore data."""
+        return cls(
+            control_id=str(data["ControlId"]), id=UUID(str(data["Id"])) if "Id" in data else uuid4()
+        )
+
+
+@dataclass
+class ButtonUp:
+    """Event when button is released."""
+
+    control_id: str
+    id: UUID = field(default_factory=uuid4)
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert to dictionary for EventStore."""
+        return {"Id": str(self.id), "ControlId": self.control_id}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> "ButtonUp":
+        """Create from EventStore data."""
+        return cls(
+            control_id=str(data["ControlId"]), id=UUID(str(data["Id"])) if "Id" in data else uuid4()
+        )

rocket_welder_sdk/gst_metadata.py

@@ -6,9 +6,13 @@ Matches C# GstCaps and GstMetadata functionality.
 from __future__ import annotations
 
 import json
-from dataclasses import dataclass, field
+import re
+from dataclasses import dataclass
 from typing import Any
 
+import numpy as np
+import numpy.typing as npt
+
 
 @dataclass
 class GstCaps:
@@ -16,172 +20,312 @@ class GstCaps:
     GStreamer capabilities representation.
 
     Represents video format capabilities including format, dimensions, framerate, etc.
+    Matches the C# GstCaps implementation with proper parsing and numpy integration.
     """
 
-    format: str | None = None
-    width: int | None = None
-    height: int | None = None
-    framerate: str | None = None  # e.g., "30/1" or "25/1"
-    pixel_aspect_ratio: str | None = None  # e.g., "1/1"
-    interlace_mode: str | None = None  # e.g., "progressive"
+    width: int
+    height: int
+    format: str
+    depth_type: type[np.uint8] | type[np.uint16]
+    channels: int
+    bytes_per_pixel: int
+    framerate_num: int | None = None
+    framerate_den: int | None = None
+    interlace_mode: str | None = None
     colorimetry: str | None = None
-    chroma_site: str | None = None
+    caps_string: str | None = None
+
+    @property
+    def frame_size(self) -> int:
+        """Calculate the expected frame size in bytes."""
+        return self.width * self.height * self.bytes_per_pixel
 
-    # Additional fields can be stored here
-    extra_fields: dict[str, Any] = field(default_factory=dict)
+    @property
+    def framerate(self) -> float | None:
+        """Get framerate as double (FPS)."""
+        if (
+            self.framerate_num is not None
+            and self.framerate_den is not None
+            and self.framerate_den > 0
+        ):
+            return self.framerate_num / self.framerate_den
+        return None
 
     @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> GstCaps:
+    def parse(cls, caps_string: str) -> GstCaps:
         """
-        Create GstCaps from dictionary.
+        Parse GStreamer caps string.
+        Example: "video/x-raw, format=(string)RGB, width=(int)640, height=(int)480, framerate=(fraction)30/1"
 
         Args:
-            data: Dictionary containing caps data
+            caps_string: GStreamer caps string
 
         Returns:
             GstCaps instance
+
+        Raises:
+            ValueError: If caps string is invalid
         """
-        # Extract known fields
-        caps = cls(
-            format=data.get("format"),
-            width=data.get("width"),
-            height=data.get("height"),
-            framerate=data.get("framerate"),
-            pixel_aspect_ratio=data.get("pixel-aspect-ratio"),
-            interlace_mode=data.get("interlace-mode"),
-            colorimetry=data.get("colorimetry"),
-            chroma_site=data.get("chroma-site"),
-        )
+        if not caps_string or not caps_string.strip():
+            raise ValueError("Empty caps string")
 
-        # Store any extra fields
-        known_fields = {
-            "format",
-            "width",
-            "height",
-            "framerate",
-            "pixel-aspect-ratio",
-            "interlace-mode",
-            "colorimetry",
-            "chroma-site",
-        }
+        caps_string = caps_string.strip()
 
-        for key, value in data.items():
-            if key not in known_fields:
-                caps.extra_fields[key] = value
+        # Check if it's a video caps
+        if not caps_string.startswith("video/x-raw"):
+            raise ValueError(f"Not a video/x-raw caps string: {caps_string}")
 
-        return caps
+        try:
+            # Parse width
+            width_match = re.search(r"width=\(int\)(\d+)", caps_string)
+            if not width_match:
+                raise ValueError("Missing width in caps string")
+            width = int(width_match.group(1))
+
+            # Parse height
+            height_match = re.search(r"height=\(int\)(\d+)", caps_string)
+            if not height_match:
+                raise ValueError("Missing height in caps string")
+            height = int(height_match.group(1))
+
+            # Parse format
+            format_match = re.search(r"format=\(string\)(\w+)", caps_string)
+            format_str = format_match.group(1) if format_match else "RGB"
+
+            # Parse framerate (optional)
+            framerate_num = None
+            framerate_den = None
+            framerate_match = re.search(r"framerate=\(fraction\)(\d+)/(\d+)", caps_string)
+            if framerate_match:
+                framerate_num = int(framerate_match.group(1))
+                framerate_den = int(framerate_match.group(2))
+
+            # Parse interlace mode (optional)
+            interlace_mode = None
+            interlace_match = re.search(r"interlace-mode=\(string\)(\w+)", caps_string)
+            if interlace_match:
+                interlace_mode = interlace_match.group(1)
+
+            # Parse colorimetry (optional)
+            colorimetry = None
+            colorimetry_match = re.search(r"colorimetry=\(string\)([\w:]+)", caps_string)
+            if colorimetry_match:
+                colorimetry = colorimetry_match.group(1)
+
+            # Map format to numpy dtype and get channel info
+            depth_type, channels, bytes_per_pixel = cls._map_gstreamer_format_to_numpy(format_str)
+
+            return cls(
+                width=width,
+                height=height,
+                format=format_str,
+                depth_type=depth_type,
+                channels=channels,
+                bytes_per_pixel=bytes_per_pixel,
+                framerate_num=framerate_num,
+                framerate_den=framerate_den,
+                interlace_mode=interlace_mode,
+                colorimetry=colorimetry,
+                caps_string=caps_string,
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to parse caps string: {caps_string}") from e
 
     @classmethod
-    def from_string(cls, caps_string: str) -> GstCaps:
+    def from_simple(cls, width: int, height: int, format: str = "RGB") -> GstCaps:
         """
-        Parse GStreamer caps string.
+        Create GstCaps from simple parameters.
 
         Args:
-            caps_string: GStreamer caps string (e.g., "video/x-raw,format=RGB,width=640,height=480")
+            width: Frame width
+            height: Frame height
+            format: Pixel format (default: "RGB")
 
         Returns:
             GstCaps instance
         """
-        if not caps_string:
-            return cls()
+        depth_type, channels, bytes_per_pixel = cls._map_gstreamer_format_to_numpy(format)
+        return cls(
+            width=width,
+            height=height,
+            format=format,
+            depth_type=depth_type,
+            channels=channels,
+            bytes_per_pixel=bytes_per_pixel,
+        )
 
-        # Remove media type prefix if present
-        if "/" in caps_string and "," in caps_string:
-            # Has media type prefix (e.g., "video/x-raw,format=RGB")
-            _, params = caps_string.split(",", 1)
-        else:
-            # No media type prefix (e.g., "format=RGB,width=320")
-            params = caps_string
-
-        # Parse parameters
-        data: dict[str, Any] = {}
-        for param in params.split(","):
-            if "=" in param:
-                key, value = param.split("=", 1)
-                key = key.strip()
-                value_str = value.strip()
-
-                # Try to parse numeric values
-                if value_str.isdigit():
-                    data[key] = int(value_str)
-                elif key in ["width", "height"] and value_str.startswith("(int)"):
-                    data[key] = int(value_str[5:].strip())
-                else:
-                    data[key] = value_str
-
-        return cls.from_dict(data)
+    @staticmethod
+    def _map_gstreamer_format_to_numpy(
+        format: str,
+    ) -> tuple[type[np.uint8] | type[np.uint16], int, int]:
+        """
+        Map GStreamer format strings to numpy dtype.
+        Reference: https://gstreamer.freedesktop.org/documentation/video/video-format.html
 
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary representation."""
-        result: dict[str, Any] = {}
-
-        if self.format is not None:
-            result["format"] = self.format
-        if self.width is not None:
-            result["width"] = self.width
-        if self.height is not None:
-            result["height"] = self.height
-        if self.framerate is not None:
-            result["framerate"] = self.framerate
-        if self.pixel_aspect_ratio is not None:
-            result["pixel-aspect-ratio"] = self.pixel_aspect_ratio
-        if self.interlace_mode is not None:
-            result["interlace-mode"] = self.interlace_mode
-        if self.colorimetry is not None:
-            result["colorimetry"] = self.colorimetry
-        if self.chroma_site is not None:
-            result["chroma-site"] = self.chroma_site
+        Args:
+            format: GStreamer format string
 
-        # Add extra fields
-        result.update(self.extra_fields)
+        Returns:
+            Tuple of (numpy dtype, channels, bytes_per_pixel)
+        """
+        format_upper = format.upper() if format else "RGB"
+
+        format_map = {
+            # RGB formats
+            "RGB": (np.uint8, 3, 3),
+            "BGR": (np.uint8, 3, 3),
+            "RGBA": (np.uint8, 4, 4),
+            "BGRA": (np.uint8, 4, 4),
+            "ARGB": (np.uint8, 4, 4),
+            "ABGR": (np.uint8, 4, 4),
+            "RGBX": (np.uint8, 4, 4),  # RGB with padding
+            "BGRX": (np.uint8, 4, 4),  # BGR with padding
+            "XRGB": (np.uint8, 4, 4),  # RGB with padding
+            "XBGR": (np.uint8, 4, 4),  # BGR with padding
+            # 16-bit RGB formats
+            "RGB16": (np.uint16, 3, 6),
+            "BGR16": (np.uint16, 3, 6),
+            # Grayscale formats
+            "GRAY8": (np.uint8, 1, 1),
+            "GRAY16_LE": (np.uint16, 1, 2),
+            "GRAY16_BE": (np.uint16, 1, 2),
+            # YUV planar formats (Y plane only for simplicity)
+            "I420": (np.uint8, 1, 1),
+            "YV12": (np.uint8, 1, 1),
+            "NV12": (np.uint8, 1, 1),
+            "NV21": (np.uint8, 1, 1),
+            # YUV packed formats
+            "YUY2": (np.uint8, 2, 2),
+            "UYVY": (np.uint8, 2, 2),
+            "YVYU": (np.uint8, 2, 2),
+            # Bayer formats (raw sensor data)
+            "BGGR": (np.uint8, 1, 1),
+            "RGGB": (np.uint8, 1, 1),
+            "GRBG": (np.uint8, 1, 1),
+            "GBRG": (np.uint8, 1, 1),
+        }
 
-        return result
+        # Default to RGB if unknown
+        return format_map.get(format_upper, (np.uint8, 3, 3))
 
-    def to_string(self) -> str:
-        """Convert to GStreamer caps string format."""
-        params = []
-
-        if self.format:
-            params.append(f"format={self.format}")
-        if self.width is not None:
-            params.append(f"width={self.width}")
-        if self.height is not None:
-            params.append(f"height={self.height}")
-        if self.framerate:
-            params.append(f"framerate={self.framerate}")
-        if self.pixel_aspect_ratio:
-            params.append(f"pixel-aspect-ratio={self.pixel_aspect_ratio}")
-        if self.interlace_mode:
-            params.append(f"interlace-mode={self.interlace_mode}")
+    def create_array(
+        self, data: bytes | memoryview | npt.NDArray[np.uint8] | npt.NDArray[np.uint16]
+    ) -> npt.NDArray[np.uint8] | npt.NDArray[np.uint16]:
+        """
+        Create numpy array with proper format from data.
+
+        Args:
+            data: Frame data as bytes, memoryview, or existing numpy array
+
+        Returns:
+            Numpy array with proper shape and dtype
+
+        Raises:
+            ValueError: If data size doesn't match expected frame size
+        """
+        # Convert memoryview to bytes if needed
+        if isinstance(data, memoryview):
+            data = bytes(data)
+
+        # If it's already a numpy array, check size and reshape if needed
+        if isinstance(data, np.ndarray):
+            if data.size * data.itemsize != self.frame_size:
+                raise ValueError(
+                    f"Data size mismatch. Expected {self.frame_size} bytes for "
+                    f"{self.width}x{self.height} {self.format}, got {data.size * data.itemsize}"
+                )
+            # Reshape if needed
+            if self.channels == 1:
+                return data.reshape((self.height, self.width))
+            else:
+                return data.reshape((self.height, self.width, self.channels))
+
+        # Check data size
+        if len(data) != self.frame_size:
+            raise ValueError(
+                f"Data size mismatch. Expected {self.frame_size} bytes for "
+                f"{self.width}x{self.height} {self.format}, got {len(data)}"
+            )
+
+        # Create array from bytes
+        arr = np.frombuffer(data, dtype=self.depth_type)
+
+        # Reshape based on channels
+        if self.channels == 1:
+            return arr.reshape((self.height, self.width))
+        else:
+            # For multi-channel images, reshape to (height, width, channels)
+            total_pixels = self.width * self.height * self.channels
+            if self.depth_type == np.uint16:
+                # For 16-bit formats, we need to account for the item size
+                arr = arr[:total_pixels]
+            return arr.reshape((self.height, self.width, self.channels))
+
+    def create_array_from_pointer(
+        self, ptr: int, copy: bool = False
+    ) -> npt.NDArray[np.uint8] | npt.NDArray[np.uint16]:
+        """
+        Create numpy array from memory pointer (zero-copy by default).
 
-        # Add extra fields
-        for key, value in self.extra_fields.items():
-            params.append(f"{key}={value}")
+        Args:
+            ptr: Memory pointer as integer
+            copy: If True, make a copy of the data; if False, create a view
 
-        if params:
-            return "video/x-raw," + ",".join(params)
+        Returns:
+            Numpy array with proper shape and dtype
+        """
+        # Calculate total elements based on depth type
+        if self.depth_type == np.uint16:
+            total_elements = self.width * self.height * self.channels
         else:
-            return "video/x-raw"
+            total_elements = self.frame_size
 
-    @property
-    def framerate_tuple(self) -> tuple[int, int] | None:
-        """Get framerate as a tuple of (numerator, denominator)."""
-        if not self.framerate or "/" not in self.framerate:
-            return None
+        # Create array from pointer using ctypes
+        import ctypes
 
-        try:
-            num, denom = self.framerate.split("/")
-            return (int(num), int(denom))
-        except (ValueError, AttributeError):
-            return None
+        # Create a buffer from the pointer
+        buffer_size = total_elements * self.depth_type.itemsize
+        c_buffer = (ctypes.c_byte * buffer_size).from_address(ptr)
+        arr = np.frombuffer(c_buffer, dtype=self.depth_type)
 
-    @property
-    def fps(self) -> float | None:
-        """Get framerate as floating-point FPS value."""
-        fr = self.framerate_tuple
-        if fr and fr[1] != 0:
-            return fr[0] / fr[1]
-        return None
+        # Reshape based on channels
+        if self.channels == 1:
+            shaped = arr.reshape((self.height, self.width))
+        else:
+            shaped = arr.reshape((self.height, self.width, self.channels))
+
+        return shaped.copy() if copy else shaped
+
+    def __str__(self) -> str:
+        """String representation."""
+        # If we have the original caps string, return it for perfect round-tripping
+        if self.caps_string:
+            return self.caps_string
+
+        # Otherwise build a simple display string
+        fps = f" @ {self.framerate:.2f}fps" if self.framerate else ""
+        return f"{self.width}x{self.height} {self.format}{fps}"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary representation."""
+        result = {
+            "width": self.width,
+            "height": self.height,
+            "format": self.format,
+            "channels": self.channels,
+            "bytes_per_pixel": self.bytes_per_pixel,
+        }
+
+        if self.framerate_num is not None:
+            result["framerate_num"] = self.framerate_num
+        if self.framerate_den is not None:
+            result["framerate_den"] = self.framerate_den
+        if self.interlace_mode:
+            result["interlace_mode"] = self.interlace_mode
+        if self.colorimetry:
+            result["colorimetry"] = self.colorimetry
+
+        return result
 
 
 @dataclass
@@ -190,6 +334,7 @@ class GstMetadata:
     GStreamer metadata structure.
 
     Matches the JSON structure written by GStreamer plugins.
+    Compatible with C# GstMetadata record.
     """
 
     type: str
@@ -207,24 +352,46 @@ class GstMetadata:
 
         Returns:
             GstMetadata instance
+
+        Raises:
+            ValueError: If JSON is invalid or missing required fields
         """
-        data = json.loads(json_data) if isinstance(json_data, (str, bytes)) else json_data
+        # Parse JSON if needed
+        if isinstance(json_data, (str, bytes)):
+            if isinstance(json_data, bytes):
+                json_data = json_data.decode("utf-8")
+            try:
+                data = json.loads(json_data)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"Invalid JSON: {e}") from e
+        else:
+            data = json_data
+
+        # Validate required fields
+        if not isinstance(data, dict):
+            raise ValueError("JSON must be an object/dictionary")
+
+        # Get required fields
+        type_str = data.get("type", "")
+        version = data.get("version", "")
+        element_name = data.get("element_name", "")
 
-        # Parse caps
-        caps_data = data.get("caps", {})
+        # Parse caps - it's a STRING in the JSON!
+        caps_data = data.get("caps")
         if isinstance(caps_data, str):
-            caps = GstCaps.from_string(caps_data)
+            # This is the normal case - caps is a string that needs parsing
+            caps = GstCaps.parse(caps_data)
         elif isinstance(caps_data, dict):
-            caps = GstCaps.from_dict(caps_data)
+            # Fallback for dict format (shouldn't happen with real GStreamer)
+            # Create a simple caps from dict
+            width = caps_data.get("width", 640)
+            height = caps_data.get("height", 480)
+            format_str = caps_data.get("format", "RGB")
+            caps = GstCaps.from_simple(width, height, format_str)
         else:
-            caps = GstCaps()
+            raise ValueError(f"Invalid caps data type: {type(caps_data)}")
 
-        return cls(
-            type=data.get("type", ""),
-            version=data.get("version", ""),
-            caps=caps,
-            element_name=data.get("element_name", ""),
-        )
+        return cls(type=type_str, version=version, caps=caps, element_name=element_name)
 
     def to_json(self) -> str:
         """Convert to JSON string."""
@@ -235,6 +402,10 @@ class GstMetadata:
         return {
             "type": self.type,
             "version": self.version,
-            "caps": self.caps.to_dict(),
+            "caps": str(self.caps),  # Caps as string for C# compatibility
             "element_name": self.element_name,
         }
+
+    def __str__(self) -> str:
+        """String representation."""
+        return f"GstMetadata(type={self.type}, element={self.element_name}, caps={self.caps})"