foxglove-sdk 0.15.1__cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl → 0.15.2__cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

foxglove/__init__.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import atexit
 import logging
+from typing import TYPE_CHECKING
 
 from . import _foxglove_py as _foxglove
 
@@ -25,6 +26,9 @@ 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)
 
 
@@ -166,6 +170,59 @@ 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",
@@ -180,4 +237,5 @@ __all__ = [
     "open_mcap",
     "set_log_level",
     "start_server",
+    "init_notebook_buffer",
 ]

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

foxglove/notebook/static/widget.js

@@ -0,0 +1 @@
+var y=EventTarget,c="https://embed.foxglove.dev/",p="foxglove.default-layout",h=class extends y{#e;#s;#n;#i=!1;#t={dataSource:void 0,layout:void 0,selectLayout:void 0,extension:[]};#a=!1;constructor(e){super();let{parent:a,src:i,orgSlug:o,initialDataSource:s,initialLayout:n,initialLayoutParams:r,initialExtensions:l,colorScheme:u="auto"}=e;this.#n=o;let d=i??c;try{this.#s=new URL(d)}catch{throw new Error(`[FoxgloveViewer] Invalid server URL: ${d}`)}window.addEventListener("message",this.#l),s&&this.setDataSource(s),n!=null&&r==null&&this.setLayoutData(n),r!=null&&this.selectLayout(r),l&&this.installExtensions(l),this.#e=document.createElement("iframe"),this.#e.src=d,this.#e.title="Foxglove",this.#e.allow="cross-origin-isolated",this.#e.style.width="100%",this.#e.style.height="100%",this.#e.style.border="none",this.setColorScheme(u),a.appendChild(this.#e)}setDataSource(e){this.#o({type:"set-data-source",payload:e})}selectLayout(e){this.#o({type:"select-layout",payload:e})}setLayoutData(e){this.selectLayout({storageKey:p,opaqueLayout:e,force:!0})}installExtensions(e){this.#o({type:"install-extension",payload:e})}isReady(){return this.#i}destroy(){this.#a=!0,this.#e.remove(),window.removeEventListener("message",this.#l)}isDestroyed(){return this.#a}setColorScheme(e){this.#e.style.colorScheme=e==="auto"?"normal":e}#o(e){e.type==="install-extension"?this.#t.extension.push(e):e.type==="set-data-source"?this.#t.dataSource=e:e.type==="set-layout"&&!this.#t.selectLayout?this.#t.layout=e:e.type==="select-layout"&&(this.#t.layout=void 0,this.#t.selectLayout=e),this.#i&&this.#r(e)}#r(e){if(this.#a){console.warn("[FoxgloveViewer] Unable to post command. Frame has been destroyed.");return}f(this.#e.contentWindow,"Invariant: iframe should be loaded."),this.#e.contentWindow.postMessage(e,this.#s.href)}#l=e=>{let a=new URL(e.origin);if(!(e.source!==this.#e.contentWindow||a.href!==this.#s.href)){if(this.#a){console.warn("[FoxgloveViewer] Unable to handle message. Frame has been destroyed.");return}switch(e.data.type){case"foxglove-origin-request":this.#r({type:"origin-ack"});break;case"foxglove-handshake-request":{this.#i=!0,this.#r({type:"handshake-ack",payload:{orgSlug:this.#n,initialDataSource:this.#t.dataSource?.payload,initialLayoutParams:this.#t.selectLayout?.payload,initialExtensions:this.#t.extension.flatMap(i=>i.payload)}});break}case"foxglove-handshake-complete":{this.dispatchEvent(new Event("ready"));break}case"foxglove-error":{this.dispatchEvent(new CustomEvent("error",{detail:e.data.payload}));break}default:{console.warn("[FoxgloveViewer] Unhandled message type:",e.data);break}}}}};function f(t,e="no additional info provided"){if(!t)throw new Error("Assertion Error: "+e)}function g({model:t,el:e}){let a=document.createElement("div"),i=t.get("_layout_params"),o=new h({parent:a,src:t.get("src"),orgSlug:void 0,initialLayoutParams:i?{storageKey:i.storage_key,opaqueLayout:i.opaque_layout,force:i.force}:void 0});o.addEventListener("ready",()=>{t.send({type:"ready"})}),t.on("msg:custom",(s,n)=>{if(s.type==="update-data"){let r=n.map((l,u)=>new File([l.buffer],`data-${u}.mcap`));o.setDataSource({type:"file",file:r})}}),a.style.width=t.get("width")==="full"?"100%":`${t.get("width")}px`,a.style.height=`${t.get("height")}px`,t.on("change:width",()=>{a.style.width=t.get("width")==="full"?"100%":`${t.get("width")}px`}),t.on("change:height",()=>{a.style.height=`${t.get("height")}px`}),t.on("change:_layout_params",()=>{let s=t.get("_layout_params");s&&o.selectLayout({storageKey:s.storage_key,opaqueLayout:s.opaque_layout,force:s.force})}),e.appendChild(a)}var _={render:g};export{_ as default};

{foxglove_sdk-0.15.1.dist-info → foxglove_sdk-0.15.2.dist-info}/METADATA

@@ -1,8 +1,12 @@
 Metadata-Version: 2.4
 Name: foxglove-sdk
-Version: 0.15.1
+Version: 0.15.2
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
+Requires-Dist: anywidget ; extra == 'notebook'
+Requires-Dist: mcap ; extra == 'notebook'
+Requires-Dist: traitlets ; extra == 'notebook'
+Provides-Extra: notebook
 Summary: Foxglove Python SDK
 Author-email: Foxglove <support@foxglove.dev>
 License-Expression: MIT

{foxglove_sdk-0.15.1.dist-info → foxglove_sdk-0.15.2.dist-info}/RECORD

@@ -1,5 +1,5 @@
-foxglove/__init__.py,sha256=rCUvW1RL_ns_WfzufCUlvsa_7Exikfoza_VNgjmgVNk,6111
-foxglove/_foxglove_py.cpython-312-aarch64-linux-gnu.so,sha256=uLFWKMihb3SeLh18wKaUj5B8ChbfQ8trd9NwYx7xcVQ,6578488
+foxglove/__init__.py,sha256=07Fz3ZZJdqsXRl0uKpIOID8ysa1HpQ741pQlvz1yA3I,8222
+foxglove/_foxglove_py.cpython-312-aarch64-linux-gnu.so,sha256=5PXYSPgFrxuJdMPN9Ah8oDBjYavY47H3YMYN5vAvL0o,6583544
 foxglove/_foxglove_py/__init__.pyi,sha256=lh2gtNThduHDOIO1pQ7NaGnjAPr6s_VlbdBMRKM2dns,5201
 foxglove/_foxglove_py/channels.pyi,sha256=c3WXhK5FfeCJ1aDGB-AsayIossnC8v8qFij0XWl1AEA,67327
 foxglove/_foxglove_py/cloud.pyi,sha256=9Hqj7b9S2CTiWeWOIqaAw3GSmR-cGoSL4R7fi5WI-QA,255
@@ -12,6 +12,10 @@ foxglove/channel.py,sha256=MRiiOm09ZNATOvVCFuvn19KB9HkVCtsDTJYiqE7LQlA,8452
 foxglove/channels/__init__.py,sha256=qTr5-HKlr4e386onX9OiYBPWUsS1n2vO23PncL0TiPY,2398
 foxglove/cloud.py,sha256=eOHV8ZCnut59uBLiw1c5MiwbIALeVwPzxo2Yb-2jbII,1942
 foxglove/mcap.py,sha256=LR9TSyRlDWuHZpXR8iglmDp-S-4BRqgmvTOiUKHwlsA,200
+foxglove/notebook/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+foxglove/notebook/foxglove_widget.py,sha256=mOXElZLZSIQfvzbZfMd2jtvmWA-H4Z8j7fa39Vwns34,3418
+foxglove/notebook/notebook_buffer.py,sha256=ooQIb8xcyNeuCoRm7CL0Uhnh9VPcd41YMUNYRu15FYg,3801
+foxglove/notebook/static/widget.js,sha256=LAmo9HlxLgNAgDSROag8_3KWFLVc7gcE8EGU1ZaFjMk,3639
 foxglove/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 foxglove/schemas/__init__.py,sha256=bqYBLc0HXRe-BMRP3VnF9IUB2yKYsvku3pZnulss3GY,3232
 foxglove/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -24,6 +28,6 @@ foxglove/tests/test_schemas.py,sha256=4empQg8gqS7MD63ibU3kdQgJUSsUpnNQQWQ7oAf-4x
 foxglove/tests/test_server.py,sha256=PHraaIt4m27MXn1UveV6BRpzYCMFOQfjQD4d4ZHRjIY,2893
 foxglove/tests/test_time.py,sha256=By_sM5r87s9iu4Df12r6p9DJrzTeZSLys3XGUGhvUps,4661
 foxglove/websocket.py,sha256=oPcI2dttjr-RdL7z30MKEEF1cswyoDu_VetEaxAiwtQ,5812
-foxglove_sdk-0.15.1.dist-info/METADATA,sha256=wqa9FsF_BeDMJ9TwFLfZvZafO2rLUoJXga-oAV0w1Rk,1553
-foxglove_sdk-0.15.1.dist-info/WHEEL,sha256=Zh2Nm9_KPw53ft3ii58WjPmMCU4Yjeq6NqKuwRR6qU4,131
-foxglove_sdk-0.15.1.dist-info/RECORD,,
+foxglove_sdk-0.15.2.dist-info/METADATA,sha256=Iz7-5YqTaMpdYHLi-lpy-qzKOPfvqm38pHrDUC2sn_E,1714
+foxglove_sdk-0.15.2.dist-info/WHEEL,sha256=Zh2Nm9_KPw53ft3ii58WjPmMCU4Yjeq6NqKuwRR6qU4,131
+foxglove_sdk-0.15.2.dist-info/RECORD,,