foxglove-sdk 0.14.2__cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl → 0.16.3__cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl

foxglove/__init__.py

@@ -9,20 +9,34 @@ from __future__ import annotations
 
 import atexit
 import logging
+from typing import TYPE_CHECKING
 
 from . import _foxglove_py as _foxglove
 
 # Re-export these imports
-from ._foxglove_py import Context, Schema, open_mcap
+from ._foxglove_py import (
+    ChannelDescriptor,
+    Context,
+    Schema,
+    SinkChannelFilter,
+    open_mcap,
+)
 from .channel import Channel, log
 
 # Deprecated. Use foxglove.mcap.MCAPWriter instead.
 from .mcap import MCAPWriter
 
+if TYPE_CHECKING:
+    from .notebook.notebook_buffer import NotebookBuffer
+
 atexit.register(_foxglove.shutdown)
 
 
 try:
+    from ._foxglove_py.cloud import CloudSink
+
+    # from ._foxglove_py.cloud import start_cloud_sink as _start_cloud_sink
+    from .cloud import CloudSinkListener
     from .websocket import (
         AssetHandler,
         Capability,
@@ -43,6 +57,8 @@ try:
         asset_handler: AssetHandler | None = None,
         context: Context | None = None,
         session_id: str | None = None,
+        channel_filter: SinkChannelFilter | None = None,
+        playback_time_range: tuple[int, int] | None = None,
     ) -> WebSocketServer:
         """
         Start a websocket server for live visualization.
@@ -61,6 +77,11 @@ try:
         :param session_id: An ID which allows the client to understand if the connection is a
             re-connection or a new server instance. If None, then an ID is generated based on the
             current time.
+        :param channel_filter: A `Callable` that determines whether a channel should be logged to.
+            Return `True` to log the channel, or `False` to skip it. By default, all channels
+            will be logged.
+        :param playback_time_range: Time range of data being played back, in absolute nanoseconds.
+            Implies `Capability.RangedPlayback` if set.
         """
         return _foxglove.start_server(
             name=name,
@@ -73,6 +94,36 @@ try:
             asset_handler=asset_handler,
             context=context,
             session_id=session_id,
+            channel_filter=channel_filter,
+            playback_time_range=playback_time_range,
+        )
+
+    def start_cloud_sink(
+        *,
+        listener: CloudSinkListener | None = None,
+        supported_encodings: list[str] | None = None,
+        context: Context | None = None,
+        session_id: str | None = None,
+    ) -> CloudSink:
+        """
+        Connect to Foxglove Agent for live visualization and teleop.
+
+        Foxglove Agent must be running on the same host for this to work.
+
+        :param capabilities: A list of capabilities to advertise to the agent.
+        :param listener: A Python object that implements the
+            :py:class:`cloud.CloudSinkListener` protocol.
+        :param supported_encodings: A list of encodings to advertise to the agent.
+        :param context: The context to use for logging. If None, the global context is used.
+        :param session_id: An ID which allows the agent to understand if the connection is a
+            re-connection or a new connection instance. If None, then an ID is generated based on
+            the current time.
+        """
+        return _foxglove.start_cloud_sink(
+            listener=listener,
+            supported_encodings=supported_encodings,
+            context=context,
+            session_id=session_id,
         )
 
 except ImportError:
@@ -123,13 +174,72 @@ def _level_names() -> dict[str, int]:
     }
 
 
+def init_notebook_buffer(context: Context | None = None) -> NotebookBuffer:
+    """
+    Create a NotebookBuffer object to manage data buffering 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.
+
+    Args:
+        context: The Context used to log the messages. If no Context is provided, the global
+            context will be used. Logged messages will be buffered.
+
+    Returns:
+        NotebookBuffer: A NotebookBuffer object that can be used to manage the data buffering
+            and visualization.
+
+    Raises:
+        Exception: If the notebook extra package is not installed. Install it
+            with `pip install foxglove-sdk[notebook]`.
+
+    Note:
+        This function is only available when the `notebook` extra package
+        is installed. Install it with `pip install foxglove-sdk[notebook]`.
+
+    Example:
+        >>> import foxglove
+        >>>
+        >>> # Create a basic viewer using the default context
+        >>> nb_buffer = foxglove.init_notebook_buffer()
+        >>>
+        >>> # Or use a specific context
+        >>> nb_buffer = foxglove.init_notebook_buffer(context=my_ctx)
+        >>>
+        >>> # ... log data as usual ...
+        >>>
+        >>> # Display the widget in the notebook
+        >>> nb_buffer.show()
+    """
+    try:
+        from .notebook.notebook_buffer import NotebookBuffer
+
+    except ImportError:
+        raise Exception(
+            "NotebookBuffer is not installed. "
+            'Please install it with `pip install "foxglove-sdk[notebook]"`'
+        )
+
+    return NotebookBuffer(context=context)
+
+
 __all__ = [
     "Channel",
+    "ChannelDescriptor",
     "Context",
     "MCAPWriter",
     "Schema",
+    "SinkChannelFilter",
+    "CloudSink",
+    "CloudSinkListener",
+    "start_cloud_sink",
     "log",
     "open_mcap",
     "set_log_level",
     "start_server",
+    "init_notebook_buffer",
 ]

foxglove/_foxglove_py/__init__.pyi

@@ -1,8 +1,27 @@
 from pathlib import Path
-from typing import Any
+from typing import Any, BinaryIO, Callable, Protocol
 
 from foxglove.websocket import AssetHandler
 
+class McapWritable(Protocol):
+    """A writable and seekable file-like object.
+
+    This protocol defines the minimal interface required for writing MCAP data.
+    """
+
+    def write(self, data: bytes | bytearray) -> int:
+        """Write data and return the number of bytes written."""
+        ...
+
+    def seek(self, offset: int, whence: int = 0) -> int:
+        """Seek to position and return the new absolute position."""
+        ...
+
+    def flush(self) -> None:
+        """Flush any buffered data."""
+        ...
+
+from .cloud import CloudSink
 from .mcap import MCAPWriteOptions, MCAPWriter
 from .websocket import Capability, Service, WebSocketServer
 
@@ -15,7 +34,7 @@ class BaseChannel:
         self,
         topic: str,
         message_encoding: str,
-        schema: Schema | None = None,
+        schema: "Schema" | None = None,
         metadata: dict[str, str] | None = None,
     ) -> None: ...
     def id(self) -> int:
@@ -115,6 +134,26 @@ class Context:
         """
         ...
 
+    @staticmethod
+    def default() -> "Context":
+        """
+        Returns the default context.
+        """
+        ...
+
+class ChannelDescriptor:
+    """
+    Information about a channel
+    """
+
+    id: int
+    topic: str
+    message_encoding: str
+    metadata: dict[str, str]
+    schema: "Schema" | None
+
+SinkChannelFilter = Callable[[ChannelDescriptor], bool]
+
 def start_server(
     *,
     name: str | None = None,
@@ -127,12 +166,26 @@ def start_server(
     asset_handler: AssetHandler | None = None,
     context: Context | None = None,
     session_id: str | None = None,
+    channel_filter: SinkChannelFilter | None = None,
+    playback_time_range: tuple[int, int] | None = None,
 ) -> WebSocketServer:
     """
     Start a websocket server for live visualization.
     """
     ...
 
+def start_cloud_sink(
+    *,
+    listener: Any = None,
+    supported_encodings: list[str] | None = None,
+    context: Context | None = None,
+    session_id: str | None = None,
+) -> CloudSink:
+    """
+    Connect to Foxglove Agent for remote visualization and teleop.
+    """
+    ...
+
 def enable_logging(level: int) -> None:
     """
     Forward SDK logs to python's logging facility.
@@ -152,17 +205,24 @@ def shutdown() -> None:
     ...
 
 def open_mcap(
-    path: str | Path,
+    path: str | Path | BinaryIO | McapWritable,
     *,
     allow_overwrite: bool = False,
     context: Context | None = None,
+    channel_filter: SinkChannelFilter | None = None,
     writer_options: MCAPWriteOptions | None = None,
 ) -> MCAPWriter:
     """
-    Creates a new MCAP file for recording.
+    Open an MCAP writer for recording.
+
+    If a path is provided, the file will be created and must not already exist (unless
+    allow_overwrite is True). If a file-like object is provided, it must support write(),
+    seek(), and flush() methods; the allow_overwrite parameter is ignored.
 
     If a context is provided, the MCAP file will be associated with that context. Otherwise, the
     global context will be used.
+
+    You must close the writer with close() or the with statement to ensure the file is correctly finished.
     """
     ...
 

foxglove/_foxglove_py/cloud.pyi

@@ -0,0 +1,9 @@
+class CloudSink:
+    """
+    A cloud sink for remote visualization and teleop.
+    """
+
+    def __init__(self) -> None: ...
+    def stop(self) -> None:
+        """Gracefully disconnect from the cloud sink, waiting for shutdown to complete."""
+        ...

foxglove/_foxglove_py/mcap.pyi

@@ -23,6 +23,10 @@ class MCAPWriteOptions:
     :param emit_message_indexes: Specifies whether to write message index records after each chunk.
     :param emit_chunk_indexes: Specifies whether to write chunk index records in the summary
         section.
+    :param disable_seeking: Specifies whether to disable seeking backwards/forwards when writing.
+        Use this when writing to a non-seekable file-like object (e.g. a wrapped pipe or network
+        socket). The seek() implementation must still support `seek(0, SEEK_CUR)` and
+        `seek(current_position, SEEK_SET)`.
     :param repeat_channels: Specifies whether to repeat each channel record from the data section
         in the summary section.
     :param repeat_schemas: Specifies whether to repeat each schema record from the data section in
@@ -45,6 +49,7 @@ class MCAPWriteOptions:
         emit_summary_offsets: bool = True,
         emit_message_indexes: bool = True,
         emit_chunk_indexes: bool = True,
+        disable_seeking: bool = False,
         repeat_channels: bool = True,
         repeat_schemas: bool = True,
         calculate_chunk_crcs: bool = True,
@@ -82,3 +87,39 @@ class MCAPWriter:
         exiting the context manager.
         """
         ...
+
+    def write_metadata(self, name: str, metadata: dict[str, str]) -> None:
+        """
+        Write metadata to the MCAP file.
+
+        Metadata consists of key-value string pairs associated with a name.
+        If the metadata dictionary is empty, this method does nothing.
+
+        :param name: Name identifier for this metadata record
+        :param metadata: Dictionary of key-value pairs to store
+        """
+        ...
+
+    def attach(
+        self,
+        *,
+        log_time: int,
+        create_time: int,
+        name: str,
+        media_type: str,
+        data: bytes,
+    ) -> None:
+        """
+        Write an attachment to the MCAP file.
+
+        Attachments are arbitrary binary data that can be stored alongside messages.
+        Common uses include storing configuration files, calibration data, or other
+        reference material related to the recording.
+
+        :param log_time: Time at which the attachment was logged, in nanoseconds since epoch.
+        :param create_time: Time at which the attachment data was created, in nanoseconds since epoch.
+        :param name: Name of the attachment (e.g., "config.json").
+        :param media_type: MIME type of the attachment (e.g., "application/json").
+        :param data: Binary content of the attachment.
+        """
+        ...

foxglove/_foxglove_py/websocket.pyi

@@ -15,7 +15,7 @@ class Capability(Enum):
     ClientPublish = ...
     """Allow clients to advertise channels to send data messages to the server."""
 
-    Connectiongraph = ...
+    ConnectionGraph = ...
     """Allow clients to subscribe and make connection graph updates"""
 
     Parameters = ...
@@ -27,6 +27,9 @@ class Capability(Enum):
     Time = ...
     """Inform clients about the latest server time."""
 
+    RangedPlayback = ...
+    """Indicates that the server is sending data within a fixed time range."""
+
 class Client:
     """
     A client that is connected to a running websocket server.
@@ -187,6 +190,70 @@ class ParameterValue:
 
         def __init__(self, value: dict[str, AnyParameterValue]) -> None: ...
 
+class PlaybackCommand(Enum):
+    """The command for playback requested by the client player"""
+
+    Play = ...
+    Pause = ...
+
+class PlaybackControlRequest:
+    """
+    A request to control playback from the client
+
+    :param playback_command: The command for playback requested by the client player
+    :type playback_command: PlaybackCommand
+    :param playback_speed: The speed of playback requested by the client player
+    :type playback_speed: float
+    :param seek_time: The time the client player is requesting to seek to, in nanoseconds. None if no seek is requested.
+    :type seek_time: int | None
+    :param request_id: Unique string identifier, used to indicate that a PlaybackState is in response to a particular request from the client.
+    :type request_id: str
+    """
+
+    playback_command: PlaybackCommand
+    playback_speed: float
+    seek_time: int | None
+    request_id: str
+
+class PlaybackState:
+    """
+    The state of data playback on the server
+
+    :param status: The status of server data playback
+    :type status: PlaybackStatus
+    :param current_time: The current time of playback, in absolute nanoseconds
+    :type current_time: int
+    :param playback_speed: The speed of playback, as a factor of realtime
+    :type playback_speed: float
+    :param did_seek: Whether a seek forward or backward in time triggered this message to be emitted
+    :type did_seek: bool
+    :param request_id: If this message is being emitted in response to a PlaybackControlRequest message, the request_id from that message. Set this to an empty string if the state of playback has been changed by any other condition.
+    :type request_id: str | None
+    """
+
+    status: PlaybackStatus
+    current_time: int
+    playback_speed: float
+    did_seek: bool
+    request_id: str | None
+
+    def __init__(
+        self,
+        status: PlaybackStatus,
+        current_time: int,
+        playback_speed: float,
+        did_seek: bool,
+        request_id: str | None,
+    ): ...
+
+class PlaybackStatus(Enum):
+    """The status of server data playback"""
+
+    Playing = ...
+    Paused = ...
+    Buffering = ...
+    Ended = ...
+
 class ServiceRequest:
     """
     A websocket service request.
@@ -278,6 +345,12 @@ class WebSocketServer:
         """
         ...
 
+    def broadcast_playback_state(self, playback_state: PlaybackState) -> None:
+        """
+        Publish the current playback state to all clients.
+        """
+        ...
+
     def broadcast_time(self, timestamp_nanos: int) -> None:
         """
         Publishes the current server timestamp to all clients.

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/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 = []