foxglove-sdk 0.16.3__cp314-cp314t-musllinux_1_2_i686.whl

foxglove/channel.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from base64 import b64encode
+from typing import Any, cast
+
+from . import Context
+from . import _foxglove_py as _foxglove
+from . import channels as _channels
+from . import schemas as _schemas
+
+JsonSchema = dict[str, Any]
+JsonMessage = dict[str, Any]
+
+
+class Channel:
+    """
+    A channel that can be used to log binary messages or JSON messages.
+    """
+
+    __slots__ = ["base"]
+    base: _foxglove.BaseChannel
+
+    def __init__(
+        self,
+        topic: str,
+        *,
+        schema: JsonSchema | _foxglove.Schema | None = None,
+        message_encoding: str | None = None,
+        context: Context | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> None:
+        """
+        Create a new channel for logging messages on a topic.
+
+        :param topic: The topic name. You should choose a unique topic name per channel.
+        :param message_encoding: The message encoding. Optional if :py:param:`schema` is a
+            dictionary, in which case the message encoding is presumed to be "json".
+        :param schema: A definition of your schema. Pass a :py:class:`Schema` for full control. If a
+            dictionary is passed, it will be treated as a JSON schema.
+        :param metadata: A dictionary of key/value strings to add to the channel. A type error is
+            raised if any key or value is not a string.
+
+        If both message_encoding and schema are None, then the channel will use JSON encoding, and
+        allow any dict to be logged.
+        """
+        message_encoding, schema = _normalize_schema(message_encoding, schema)
+
+        if context is not None:
+            self.base = context._create_channel(
+                topic, message_encoding=message_encoding, schema=schema
+            )
+        else:
+            self.base = _foxglove.BaseChannel(
+                topic,
+                message_encoding,
+                schema,
+                metadata,
+            )
+
+        _channels_by_id[self.base.id()] = self
+
+    def __repr__(self) -> str:
+        return f"Channel(id={self.id()}, topic='{self.topic()}', schema='{self.schema_name()}')"
+
+    def id(self) -> int:
+        """The unique ID of the channel"""
+        return self.base.id()
+
+    def topic(self) -> str:
+        """The topic name of the channel"""
+        return self.base.topic()
+
+    @property
+    def message_encoding(self) -> str:
+        """The message encoding for the channel"""
+        return self.base.message_encoding
+
+    def metadata(self) -> dict[str, str]:
+        """
+        Returns a copy of the channel's metadata.
+
+        Note that changes made to the returned dictionary will not be applied to
+        the channel's metadata.
+        """
+        return self.base.metadata()
+
+    def schema(self) -> _foxglove.Schema | None:
+        """
+        Returns a copy of the channel's metadata.
+
+        Note that changes made to the returned object will not be applied to
+        the channel's schema.
+        """
+        return self.base.schema()
+
+    def schema_name(self) -> str | None:
+        """The name of the schema for the channel"""
+        return self.base.schema_name()
+
+    def has_sinks(self) -> bool:
+        """Returns true if at least one sink is subscribed to this channel"""
+        return self.base.has_sinks()
+
+    def log(
+        self,
+        msg: JsonMessage | list[Any] | bytes | str,
+        *,
+        log_time: int | None = None,
+        sink_id: int | None = None,
+    ) -> None:
+        """
+        Log a message on the channel.
+
+        :param msg: the message to log. If the channel uses JSON encoding, you may pass a
+            dictionary or list. Otherwise, you are responsible for serializing the message.
+        :param log_time: The optional time the message was logged.
+        """
+        if self.message_encoding == "json" and isinstance(msg, (dict, list)):
+            return self.base.log(json.dumps(msg).encode("utf-8"), log_time)
+
+        if isinstance(msg, str):
+            msg = msg.encode("utf-8")
+
+        if isinstance(msg, bytes):
+            return self.base.log(msg, log_time, sink_id)
+
+        raise TypeError(f"Unsupported message type: {type(msg)}")
+
+    def close(self) -> None:
+        """
+        Close the channel.
+
+        You can use this to explicitly unadvertise the channel to sinks that subscribe to
+        channels dynamically, such as the :py:class:`foxglove.websocket.WebSocketServer`.
+
+        Attempts to log on a closed channel will elicit a throttled warning message.
+        """
+        self.base.close()
+
+
+_channels_by_id: dict[int, Channel] = {}
+
+
+def log(
+    topic: str,
+    message: JsonMessage | list[Any] | bytes | str | _schemas.FoxgloveSchema,
+    *,
+    log_time: int | None = None,
+    sink_id: int | None = None,
+) -> None:
+    """Log a message on a topic.
+
+    Creates a new channel the first time called for a given topic.
+    For Foxglove types in the schemas module, this creates a typed channel
+    (see :py:mod:`foxglove.channels` for supported types).
+    For bytes and str, this creates a simple schemaless channel and logs the bytes as-is.
+    For dict and list, this creates a schemaless json channel.
+
+    The type of the message must be kept consistent for each topic or an error will be raised.
+    This can be avoided by creating and using the channels directly instead of using this function.
+
+    Note: this raises an error if a channel with the same topic was created by other means.
+    This limitation may be lifted in the future.
+
+    :param topic: The topic name.
+    :param message: The message to log.
+    :param log_time: The optional time the message was logged.
+    """
+    base_channel = _foxglove.get_channel_for_topic(topic)
+    channel = _channels_by_id.get(base_channel.id(), None) if base_channel else None
+
+    if channel is None:
+        schema_name = type(message).__name__
+        if isinstance(message, (bytes, str)):
+            channel = Channel(topic)
+        elif isinstance(message, (dict, list)):
+            channel = Channel(topic, message_encoding="json")
+        else:
+            channel_name = f"{schema_name}Channel"
+            channel_cls = getattr(_channels, channel_name, None)
+            if channel_cls is not None:
+                channel = channel_cls(topic)
+        if channel is None:
+            raise ValueError(
+                f"No Foxglove schema channel found for message type {schema_name}"
+            )
+
+        channel_id = channel.base.id() if hasattr(channel, "base") else channel.id()
+        _channels_by_id[channel_id] = channel
+
+    # mypy isn't smart enough to realize that when channel is a Channel, message a compatible type
+    channel.log(
+        cast(Any, message),
+        log_time=log_time,
+        sink_id=sink_id,
+    )
+
+
+def _normalize_schema(
+    message_encoding: str | None,
+    schema: JsonSchema | _foxglove.Schema | None = None,
+) -> tuple[str, _foxglove.Schema | None]:
+    if isinstance(schema, _foxglove.Schema):
+        if message_encoding is None:
+            raise ValueError("message encoding is required")
+        return message_encoding, schema
+
+    if schema is None and (message_encoding is None or message_encoding == "json"):
+        # Schemaless support via JSON encoding; same as specifying an empty dict schema
+        schema = {}
+        message_encoding = "json"
+
+    if isinstance(schema, dict):
+        # Dicts default to json encoding. An empty dict is equivalent to the empty schema (b"")
+        if message_encoding and message_encoding != "json":
+            raise ValueError("message_encoding must be 'json' when schema is a dict")
+        if schema and schema.get("type") != "object":
+            raise ValueError("Only object schemas are supported")
+
+        data = json.dumps(schema).encode("utf-8") if schema else b""
+        name = schema["title"] if "title" in schema else _default_schema_name(data)
+
+        return (
+            "json",
+            _foxglove.Schema(
+                name=name,
+                encoding="jsonschema",
+                data=data,
+            ),
+        )
+
+    raise TypeError(f"Invalid schema type: {type(schema)}")
+
+
+def _default_schema_name(data: bytes) -> str:
+    # Provide a consistent, readable, and reasonably unique name for a given schema so the app can
+    # identify it to the user.
+    hash = hashlib.shake_128(data).digest(6)
+    return "schema-" + b64encode(hash, b"-_").decode("utf-8")

foxglove/channels/__init__.py

@@ -0,0 +1,94 @@
+"""
+This module defines channels to easily log messages conforming to well-known Foxglove schemas.
+
+See the :py:mod:`foxglove.schemas` module for available definitions.
+"""
+
+# Generated by https://github.com/foxglove/foxglove-sdk
+from foxglove._foxglove_py.channels import (
+    ArrowPrimitiveChannel,
+    CameraCalibrationChannel,
+    CircleAnnotationChannel,
+    ColorChannel,
+    CompressedImageChannel,
+    CompressedVideoChannel,
+    CubePrimitiveChannel,
+    CylinderPrimitiveChannel,
+    FrameTransformChannel,
+    FrameTransformsChannel,
+    GeoJsonChannel,
+    GridChannel,
+    ImageAnnotationsChannel,
+    KeyValuePairChannel,
+    LaserScanChannel,
+    LinePrimitiveChannel,
+    LocationFixChannel,
+    LocationFixesChannel,
+    LogChannel,
+    ModelPrimitiveChannel,
+    PackedElementFieldChannel,
+    Point2Channel,
+    Point3Channel,
+    PointCloudChannel,
+    PointsAnnotationChannel,
+    PoseChannel,
+    PoseInFrameChannel,
+    PosesInFrameChannel,
+    QuaternionChannel,
+    RawAudioChannel,
+    RawImageChannel,
+    SceneEntityChannel,
+    SceneEntityDeletionChannel,
+    SceneUpdateChannel,
+    SpherePrimitiveChannel,
+    TextAnnotationChannel,
+    TextPrimitiveChannel,
+    TriangleListPrimitiveChannel,
+    Vector2Channel,
+    Vector3Channel,
+    VoxelGridChannel,
+)
+
+__all__ = [
+    "ArrowPrimitiveChannel",
+    "CameraCalibrationChannel",
+    "CircleAnnotationChannel",
+    "ColorChannel",
+    "CompressedImageChannel",
+    "CompressedVideoChannel",
+    "CubePrimitiveChannel",
+    "CylinderPrimitiveChannel",
+    "FrameTransformChannel",
+    "FrameTransformsChannel",
+    "GeoJsonChannel",
+    "GridChannel",
+    "ImageAnnotationsChannel",
+    "KeyValuePairChannel",
+    "LaserScanChannel",
+    "LinePrimitiveChannel",
+    "LocationFixChannel",
+    "LocationFixesChannel",
+    "LogChannel",
+    "ModelPrimitiveChannel",
+    "PackedElementFieldChannel",
+    "Point2Channel",
+    "Point3Channel",
+    "PointCloudChannel",
+    "PointsAnnotationChannel",
+    "PoseChannel",
+    "PoseInFrameChannel",
+    "PosesInFrameChannel",
+    "QuaternionChannel",
+    "RawAudioChannel",
+    "RawImageChannel",
+    "SceneEntityChannel",
+    "SceneEntityDeletionChannel",
+    "SceneUpdateChannel",
+    "SpherePrimitiveChannel",
+    "TextAnnotationChannel",
+    "TextPrimitiveChannel",
+    "TriangleListPrimitiveChannel",
+    "Vector2Channel",
+    "Vector3Channel",
+    "VoxelGridChannel",
+]

foxglove/cloud.py

@@ -0,0 +1,61 @@
+from typing import Protocol
+
+from ._foxglove_py.websocket import (
+    ChannelView,
+    Client,
+    ClientChannel,
+)
+
+
+class CloudSinkListener(Protocol):
+    """
+    A mechanism to register callbacks for handling client message events.
+    """
+
+    def on_subscribe(self, client: Client, channel: ChannelView) -> None:
+        """
+        Called when a client subscribes to a channel.
+
+        :param client: The client (id) that sent the message.
+        :param channel: The channel (id, topic) that the message was sent on.
+        """
+        return None
+
+    def on_unsubscribe(self, client: Client, channel: ChannelView) -> None:
+        """
+        Called when a client unsubscribes from a channel or disconnects.
+
+        :param client: The client (id) that sent the message.
+        :param channel: The channel (id, topic) that the message was sent on.
+        """
+        return None
+
+    def on_client_advertise(self, client: Client, channel: ClientChannel) -> None:
+        """
+        Called when a client advertises a channel.
+
+        :param client: The client (id) that sent the message.
+        :param channel: The client channel that is being advertised.
+        """
+        return None
+
+    def on_client_unadvertise(self, client: Client, client_channel_id: int) -> None:
+        """
+        Called when a client unadvertises a channel.
+
+        :param client: The client (id) that is unadvertising the channel.
+        :param client_channel_id: The client channel id that is being unadvertised.
+        """
+        return None
+
+    def on_message_data(
+        self, client: Client, client_channel_id: int, data: bytes
+    ) -> None:
+        """
+        Called when a message is received from a client.
+
+        :param client: The client (id) that sent the message.
+        :param client_channel_id: The client channel id that the message was sent on.
+        :param data: The message data.
+        """
+        return None

foxglove/mcap.py

@@ -0,0 +1,12 @@
+# Re-export these imports
+from ._foxglove_py.mcap import (
+    MCAPCompression,
+    MCAPWriteOptions,
+    MCAPWriter,
+)
+
+__all__ = [
+    "MCAPCompression",
+    "MCAPWriter",
+    "MCAPWriteOptions",
+]

foxglove/notebook/foxglove_widget.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import pathlib
+from typing import TYPE_CHECKING, Any, Literal
+
+import anywidget
+import traitlets
+
+if TYPE_CHECKING:
+    from .notebook_buffer import NotebookBuffer
+
+
+class FoxgloveWidget(anywidget.AnyWidget):
+    """
+    A widget that displays a Foxglove viewer in a notebook.
+
+    :param buffer: The NotebookBuffer object that contains the data to display in the widget.
+    :param layout_storage_key: The storage key of the layout to use for the widget.
+    :param width: The width of the widget. Defaults to "full".
+    :param height: The height of the widget in pixels. Defaults to 500.
+    :param src: The source URL of the Foxglove viewer. Defaults to "https://embed.foxglove.dev/".
+    """
+
+    _esm = pathlib.Path(__file__).parent / "static" / "widget.js"
+    width = traitlets.Union(
+        [traitlets.Int(), traitlets.Enum(values=["full"])], default_value="full"
+    ).tag(sync=True)
+    height = traitlets.Int(default_value=500).tag(sync=True)
+    src = traitlets.Unicode(default_value=None, allow_none=True).tag(sync=True)
+    _layout_params = traitlets.Dict(
+        per_key_traits={
+            "storage_key": traitlets.Unicode(),
+            "opaque_layout": traitlets.Dict(allow_none=True, default_value=None),
+            "force": traitlets.Bool(False),
+        },
+        allow_none=True,
+        default_value=None,
+    ).tag(sync=True)
+
+    def __init__(
+        self,
+        buffer: NotebookBuffer,
+        layout_storage_key: str,
+        width: int | Literal["full"] | None = None,
+        height: int | None = None,
+        src: str | None = None,
+        **kwargs: Any,
+    ):
+        super().__init__(**kwargs)
+        if width is not None:
+            self.width = width
+        else:
+            self.width = "full"
+        if height is not None:
+            self.height = height
+        if src is not None:
+            self.src = src
+
+        self.select_layout(layout_storage_key, **kwargs)
+
+        # Callback to get the data to display in the widget
+        self._buffer = buffer
+        # Keep track of when the widget is ready to receive data
+        self._ready = False
+        # Pending data to be sent when the widget is ready
+        self._pending_data: list[bytes] = []
+        self.on_msg(self._handle_custom_msg)
+        self.refresh()
+
+    def select_layout(self, storage_key: str, **kwargs: Any) -> None:
+        """
+        Select a layout in the Foxglove viewer.
+        """
+        opaque_layout = kwargs.get("opaque_layout", None)
+        force_layout = kwargs.get("force_layout", False)
+
+        self._layout_params = {
+            "storage_key": storage_key,
+            "opaque_layout": opaque_layout if isinstance(opaque_layout, dict) else None,
+            "force": force_layout,
+        }
+
+    def refresh(self) -> None:
+        """
+        Refresh the widget by getting the data from the callback function and sending it
+        to the widget.
+        """
+        data = self._buffer.get_data()
+        if not self._ready:
+            self._pending_data = data
+        else:
+            self.send({"type": "update-data"}, data)
+
+    def _handle_custom_msg(self, msg: dict, buffers: list[bytes]) -> None:
+        if msg["type"] == "ready":
+            self._ready = True
+
+            if len(self._pending_data) > 0:
+                self.send({"type": "update-data"}, self._pending_data)
+                self._pending_data = []

foxglove/notebook/notebook_buffer.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import os
+import uuid
+from tempfile import TemporaryDirectory
+from typing import Any, Literal
+
+from mcap.reader import make_reader
+
+from .._foxglove_py import Context, open_mcap
+from .foxglove_widget import FoxgloveWidget
+
+
+class NotebookBuffer:
+    """
+    A data buffer to collect and manage messages and visualization in Jupyter notebooks.
+
+    The NotebookBuffer object will buffer all data logged to the provided context. When you
+    are ready to visualize the data, you can call the :meth:`show` method to display an embedded
+    Foxglove visualization widget. The widget provides a fully-featured Foxglove interface
+    directly within your Jupyter notebook, allowing you to explore multi-modal robotics data
+    including 3D scenes, plots, images, and more.
+
+    :param context: The Context used to log the messages. If no Context is provided, the global
+        context will be used. Logged messages will be buffered.
+    """
+
+    def __init__(self, context: Context | None = None):
+        """
+        Initialize a new NotebookBuffer for collecting logged messages.
+        """
+        # We need to keep the temporary directory alive until the writer is closed
+        self._temp_directory = TemporaryDirectory()
+        self._context = context
+        self._files: list[str] = []
+        self._create_writer()
+
+    def show(
+        self,
+        layout_storage_key: str,
+        width: int | Literal["full"] | None = None,
+        height: int | None = None,
+        src: str | None = None,
+        **kwargs: Any,
+    ) -> FoxgloveWidget:
+        """
+        Show the Foxglove viewer. Call this method as the last step of a notebook cell
+        to display the viewer.
+        """
+        widget = FoxgloveWidget(
+            buffer=self,
+            width=width,
+            height=height,
+            src=src,
+            layout_storage_key=layout_storage_key,
+            **kwargs,
+        )
+        return widget
+
+    def clear(self) -> None:
+        """
+        Clear the buffered data.
+        """
+        self._writer.close()
+        # Delete the temporary directory and all its contents
+        self._temp_directory.cleanup()
+        # Reset files list
+        self._files = []
+        # Create a new temporary directory
+        self._temp_directory = TemporaryDirectory()
+        self._create_writer()
+
+    def get_data(self) -> list[bytes]:
+        """
+        Retrieve all collected data.
+        """
+        # close the current writer
+        self._writer.close()
+
+        if len(self._files) > 1:
+            if is_mcap_empty(self._files[-1]):
+                # If the last file is empty, remove the last file since it won't add any new data
+                # to the buffer
+                os.remove(self._files[-1])
+                self._files.pop()
+            elif is_mcap_empty(self._files[0]):
+                # If the first file is empty, remove the first file since it won't add any new data
+                # to the buffer
+                os.remove(self._files[0])
+                self._files.pop(0)
+
+        # read the content of the files
+        contents: list[bytes] = []
+        for file_name in self._files:
+            with open(file_name, "rb") as f_read:
+                contents.append(f_read.read())
+
+        self._create_writer()
+
+        return contents
+
+    def _create_writer(self) -> None:
+        random_id = uuid.uuid4().hex[:8]
+        file_name = f"{self._temp_directory.name}/log-{random_id}.mcap"
+        self._files.append(file_name)
+        self._writer = open_mcap(path=file_name, context=self._context)
+
+
+def is_mcap_empty(file_name: str) -> bool:
+    with open(file_name, "rb") as f_read:
+        iter = make_reader(f_read).iter_messages()
+        is_empty = next(iter, None) is None
+
+    return is_empty