foxglove-sdk 0.16.2__cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl

foxglove/_foxglove_py/schemas_wkt.pyi

@@ -0,0 +1,85 @@
+import datetime
+
+class Duration:
+    """
+    A duration in seconds and nanoseconds
+    """
+
+    def __init__(
+        self,
+        sec: int,
+        nsec: int | None = None,
+    ) -> None: ...
+    @property
+    def sec(self) -> int: ...
+    @property
+    def nsec(self) -> int: ...
+    @staticmethod
+    def from_secs(secs: float) -> "Duration":
+        """
+        Creates a :py:class:`Duration` from seconds.
+
+        Raises `OverflowError` if the duration cannot be represented.
+
+        :param secs: Seconds
+        """
+        ...
+
+    @staticmethod
+    def from_timedelta(td: datetime.timedelta) -> "Duration":
+        """
+        Creates a :py:class:`Duration` from a timedelta.
+
+        Raises `OverflowError` if the duration cannot be represented.
+
+        :param td: Timedelta
+        """
+        ...
+
+class Timestamp:
+    """
+    A timestamp in seconds and nanoseconds
+    """
+
+    def __init__(
+        self,
+        sec: int,
+        nsec: int | None = None,
+    ) -> None: ...
+    @property
+    def sec(self) -> int: ...
+    @property
+    def nsec(self) -> int: ...
+    @staticmethod
+    def from_epoch_secs(timestamp: float) -> "Timestamp":
+        """
+        Creates a :py:class:`Timestamp` from an epoch timestamp, such as is
+        returned by :py:func:`time.time` or :py:func:`datetime.datetime.timestamp`.
+
+        Raises `OverflowError` if the timestamp cannot be represented.
+
+        :param timestamp: Seconds since epoch
+        """
+        ...
+
+    @staticmethod
+    def from_datetime(dt: datetime.datetime) -> "Timestamp":
+        """
+        Creates a UNIX epoch :py:class:`Timestamp` from a datetime object.
+
+        Naive datetime objects are presumed to be in the local timezone.
+
+        Raises `OverflowError` if the timestamp cannot be represented.
+
+        :param dt: Datetime
+        """
+        ...
+
+    @staticmethod
+    def now() -> "Timestamp":
+        """
+        Creates a :py:class:`Timestamp` from the current system time.
+
+        Raises `OverflowError` if the timestamp cannot be represented.
+        """
+        ...

foxglove/_foxglove_py/websocket.pyi

@@ -0,0 +1,394 @@
+from enum import Enum
+
+from foxglove import Schema
+from foxglove.websocket import (
+    AnyNativeParameterValue,
+    AnyParameterValue,
+    ServiceHandler,
+)
+
+class Capability(Enum):
+    """
+    An enumeration of capabilities that the websocket server can advertise to its clients.
+    """
+
+    ClientPublish = ...
+    """Allow clients to advertise channels to send data messages to the server."""
+
+    ConnectionGraph = ...
+    """Allow clients to subscribe and make connection graph updates"""
+
+    Parameters = ...
+    """Allow clients to get & set parameters."""
+
+    Services = ...
+    """Allow clients to call services."""
+
+    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.
+    """
+
+    id: int = ...
+
+class ChannelView:
+    """
+    Information about a channel.
+    """
+
+    id: int = ...
+    topic: str = ...
+
+class ClientChannel:
+    """
+    Information about a channel advertised by a client.
+    """
+
+    id: int = ...
+    topic: str = ...
+    encoding: str = ...
+    schema_name: str = ...
+    schema_encoding: str | None = ...
+    schema: bytes | None = ...
+
+class ConnectionGraph:
+    """
+    A graph of connections between clients.
+    """
+
+    def __init__(self) -> None: ...
+    def set_published_topic(self, topic: str, publisher_ids: list[str]) -> None:
+        """
+        Set a published topic and its associated publisher ids. Overwrites any existing topic with
+        the same name.
+
+        :param topic: The topic name.
+        :param publisher_ids: The set of publisher ids.
+        """
+        ...
+
+    def set_subscribed_topic(self, topic: str, subscriber_ids: list[str]) -> None:
+        """
+        Set a subscribed topic and its associated subscriber ids. Overwrites any existing topic with
+        the same name.
+
+        :param topic: The topic name.
+        :param subscriber_ids: The set of subscriber ids.
+        """
+        ...
+
+    def set_advertised_service(self, service: str, provider_ids: list[str]) -> None:
+        """
+        Set an advertised service and its associated provider ids Overwrites any existing service
+        with the same name.
+
+        :param service: The service name.
+        :param provider_ids: The set of provider ids.
+        """
+        ...
+
+class MessageSchema:
+    """
+    A service request or response schema.
+    """
+
+    encoding: str
+    schema: Schema
+
+    def __init__(
+        self,
+        *,
+        encoding: str,
+        schema: Schema,
+    ) -> None: ...
+
+class Parameter:
+    """
+    A parameter which can be sent to a client.
+
+    :param name: The parameter name.
+    :type name: str
+    :param value: Optional value, represented as a native python object, or a ParameterValue.
+    :type value: None|bool|int|float|str|bytes|list|dict|ParameterValue
+    :param type: Optional parameter type. This is automatically derived when passing a native
+                 python object as the value.
+    :type type: ParameterType|None
+    """
+
+    name: str
+    type: ParameterType | None
+    value: AnyParameterValue | None
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        value: AnyNativeParameterValue | None = None,
+        type: ParameterType | None = None,
+    ) -> None: ...
+    def get_value(self) -> AnyNativeParameterValue | None:
+        """Returns the parameter value as a native python object."""
+        ...
+
+class ParameterType(Enum):
+    """
+    The type of a parameter.
+    """
+
+    ByteArray = ...
+    """A byte array."""
+
+    Float64 = ...
+    """A floating-point value that can be represented as a `float64`."""
+
+    Float64Array = ...
+    """An array of floating-point values that can be represented as `float64`s."""
+
+class ParameterValue:
+    """
+    A parameter value.
+    """
+
+    class Integer:
+        """An integer value."""
+
+        def __init__(self, value: int) -> None: ...
+
+    class Bool:
+        """A boolean value."""
+
+        def __init__(self, value: bool) -> None: ...
+
+    class Float64:
+        """A floating-point value."""
+
+        def __init__(self, value: float) -> None: ...
+
+    class String:
+        """
+        A string value.
+
+        For parameters of type :py:attr:ParameterType.ByteArray, this is a
+        base64 encoding of the byte array.
+        """
+
+        def __init__(self, value: str) -> None: ...
+
+    class Array:
+        """An array of parameter values."""
+
+        def __init__(self, value: list[AnyParameterValue]) -> None: ...
+
+    class Dict:
+        """An associative map of parameter values."""
+
+        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.
+    """
+
+    service_name: str
+    client_id: int
+    call_id: int
+    encoding: str
+    payload: bytes
+
+class Service:
+    """
+    A websocket service.
+    """
+
+    name: str
+    schema: ServiceSchema
+    handler: ServiceHandler
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        schema: ServiceSchema,
+        handler: ServiceHandler,
+    ): ...
+
+class ServiceSchema:
+    """
+    A websocket service schema.
+    """
+
+    name: str
+    request: MessageSchema | None
+    response: MessageSchema | None
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        request: MessageSchema | None = None,
+        response: MessageSchema | None = None,
+    ): ...
+
+class StatusLevel(Enum):
+    """A level for `WebSocketServer.publish_status`"""
+
+    Info = ...
+    Warning = ...
+    Error = ...
+
+class WebSocketServer:
+    """
+    A websocket server for live visualization.
+    """
+
+    def __init__(self) -> None: ...
+    @property
+    def port(self) -> int:
+        """Get the port on which the server is listening."""
+        ...
+
+    def app_url(
+        self,
+        *,
+        layout_id: str | None = None,
+        open_in_desktop: bool = False,
+    ) -> str | None:
+        """
+        Returns a web app URL to open the websocket as a data source.
+
+        Returns None if the server has been stopped.
+
+        :param layout_id: An optional layout ID to include in the URL.
+        :param open_in_desktop: Opens the foxglove desktop app.
+        """
+        ...
+
+    def stop(self) -> None:
+        """Explicitly stop the server."""
+        ...
+
+    def clear_session(self, session_id: str | None = None) -> None:
+        """
+        Sets a new session ID and notifies all clients, causing them to reset their state.
+        If no session ID is provided, generates a new one based on the current timestamp.
+        If the server has been stopped, this has no effect.
+        """
+        ...
+
+    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.
+        If the server has been stopped, this has no effect.
+        """
+        ...
+
+    def publish_parameter_values(self, parameters: list[Parameter]) -> None:
+        """Publishes parameter values to all subscribed clients."""
+        ...
+
+    def publish_status(
+        self, message: str, level: StatusLevel, id: str | None = None
+    ) -> None:
+        """
+        Send a status message to all clients. If the server has been stopped, this has no effect.
+        """
+        ...
+
+    def remove_status(self, ids: list[str]) -> None:
+        """
+        Remove status messages by id from all clients. If the server has been stopped, this has no
+        effect.
+        """
+        ...
+
+    def add_services(self, services: list[Service]) -> None:
+        """Add services to the server."""
+        ...
+
+    def remove_services(self, names: list[str]) -> None:
+        """Removes services that were previously advertised."""
+        ...
+
+    def publish_connection_graph(self, graph: ConnectionGraph) -> None:
+        """
+        Publishes a connection graph update to all subscribed clients. An update is published to
+        clients as a difference from the current graph to the replacement graph. When a client first
+        subscribes to connection graph updates, it receives the current graph.
+        """
+        ...

foxglove/benchmarks/test_mcap_serialization.py

@@ -0,0 +1,160 @@
+import json
+import math
+import os
+import struct
+import time
+from pathlib import Path
+from typing import Generator, List
+
+import pytest
+from foxglove import Channel, open_mcap
+from foxglove.channels import PointCloudChannel, SceneUpdateChannel
+from foxglove.schemas import (
+    Color,
+    CubePrimitive,
+    Duration,
+    PackedElementField,
+    PackedElementFieldNumericType,
+    PointCloud,
+    Pose,
+    Quaternion,
+    SceneEntity,
+    SceneUpdate,
+    Vector3,
+)
+from pytest_benchmark.fixture import BenchmarkFixture  # type: ignore
+
+
+@pytest.fixture
+def tmp_mcap(tmpdir: os.PathLike[str]) -> Generator[Path, None, None]:
+    dir = Path(tmpdir)
+    mcap = dir / "test.mcap"
+    yield mcap
+    mcap.unlink()
+    dir.rmdir()
+
+
+def build_entities(entity_count: int) -> List[SceneEntity]:
+    assert entity_count > 0
+    return [
+        SceneEntity(
+            id=f"box_{i}",
+            frame_id="box",
+            lifetime=Duration(10, nsec=int(100 * 1e6)),
+            cubes=[
+                CubePrimitive(
+                    pose=Pose(
+                        position=Vector3(x=0.0, y=0.0, z=3.0),
+                        orientation=Quaternion(x=0.0, y=0.0, z=0.0, w=1.0),
+                    ),
+                    size=Vector3(x=1.0, y=1.0, z=1.0),
+                    color=Color(r=1.0, g=0.0, b=0.0, a=1.0),
+                )
+            ],
+        )
+        for i in range(entity_count)
+    ]
+
+
+def write_scene_entity_mcap(
+    tmp_mcap: Path, channel: SceneUpdateChannel, entities: List[SceneEntity]
+) -> None:
+    with open_mcap(tmp_mcap, allow_overwrite=True):
+        for _ in range(100):
+            channel.log(SceneUpdate(entities=entities))
+
+
+def make_point_cloud(point_count: int) -> PointCloud:
+    """
+    https://foxglove.dev/blog/visualizing-point-clouds-with-custom-colors
+    """
+    point_struct = struct.Struct("<fffBBBB")
+    f32 = PackedElementFieldNumericType.Float32
+    u32 = PackedElementFieldNumericType.Uint32
+
+    t = time.time()
+    count = math.ceil(math.sqrt(point_count))
+    points = [
+        (x + math.cos(t + y / 5), y, 0) for x in range(count) for y in range(count)
+    ]
+
+    buffer = bytearray(point_struct.size * len(points))
+    for i, point in enumerate(points):
+        x, y, z = point
+        r = g = b = a = 128
+        point_struct.pack_into(buffer, i * point_struct.size, x, y, z, b, g, r, a)
+
+    return PointCloud(
+        frame_id="points",
+        pose=Pose(
+            position=Vector3(x=0, y=0, z=0),
+            orientation=Quaternion(x=0, y=0, z=0, w=1),
+        ),
+        point_stride=16,  # 4 fields * 4 bytes
+        fields=[
+            PackedElementField(name="x", offset=0, type=f32),
+            PackedElementField(name="y", offset=4, type=f32),
+            PackedElementField(name="z", offset=8, type=f32),
+            PackedElementField(name="rgba", offset=12, type=u32),
+        ],
+        data=bytes(buffer),
+    )
+
+
+def write_point_cloud_mcap(
+    tmp_mcap: Path, channel: PointCloudChannel, point_cloud: PointCloud
+) -> None:
+    with open_mcap(tmp_mcap, allow_overwrite=True):
+        for _ in range(10):
+            channel.log(point_cloud)
+
+
+def write_untyped_channel_mcap(
+    tmp_mcap: Path, channel: Channel, messages: List[bytes]
+) -> None:
+    with open_mcap(tmp_mcap, allow_overwrite=True):
+        for message in messages:
+            channel.log(message)
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("entity_count", [1, 2, 4, 8])
+def test_write_scene_update_mcap(
+    benchmark: BenchmarkFixture,
+    entity_count: int,
+    tmp_mcap: Path,
+) -> None:
+    channel = SceneUpdateChannel(f"/scene_{entity_count}")
+    entities = build_entities(entity_count)
+    benchmark(write_scene_entity_mcap, tmp_mcap, channel, entities)
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("point_count", [100, 1000, 10000])
+def test_write_point_cloud_mcap(
+    benchmark: BenchmarkFixture,
+    point_count: int,
+    tmp_mcap: Path,
+) -> None:
+    print("test_write_point_cloud_mcap")
+    channel = PointCloudChannel(f"/point_cloud_{point_count}")
+    point_cloud = make_point_cloud(point_count)
+    benchmark(write_point_cloud_mcap, tmp_mcap, channel, point_cloud)
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("message_count", [10, 100, 1000])
+def test_write_untyped_channel_mcap(
+    benchmark: BenchmarkFixture,
+    message_count: int,
+    tmp_mcap: Path,
+) -> None:
+    channel = Channel(
+        f"/untyped_{message_count}",
+        schema={"type": "object", "additionalProperties": True},
+    )
+    messages = [
+        json.dumps({"message": f"hello_{i}"}).encode("utf-8")
+        for i in range(message_count)
+    ]
+    benchmark(write_untyped_channel_mcap, tmp_mcap, channel, messages)