Mcap writer layout metadata

[surbina]

Changelog

Added write_layout method to the Python MCAP writer for storing Foxglove layouts in file metadata.

Docs

Updated MCAPWriter and open_mcap documentation to reflect the new write_layout method and the Python wrapper class.

Description

The Python SDK's MCAP writer previously lacked a direct method to embed Foxglove Layout objects into the MCAP file's metadata. This PR introduces a write_layout method to the MCAPWriter class, allowing users to easily serialize a foxglove.layouts.Layout object to JSON and store it under the "foxglove.layout" metadata key.

To achieve this, the underlying Rust-backed _MCAPWriter is now wrapped by a new Python MCAPWriter class. The foxglove.open_mcap function has been updated to return this Python wrapper, ensuring that all existing MCAPWriter functionality remains available while adding the new write_layout capability. This change provides a more consistent and convenient API for embedding visualization layouts directly into MCAP files, improving their self-describing nature for Foxglove Studio.

Verified by running existing MCAP tests and a new dedicated test case for write_layout that confirms correct serialization and metadata storage.

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[surbina]

@cursor let's add a layout_name parameter to the write_layout function. Use layout_name as the key here instead of an empty string.

[cursor]

Done! I've added the layout_name parameter to the write_layout function.

Changes

Rust (python/foxglove-sdk/src/mcap.rs)

fn write_layout(&self, py: Python<'_>, layout: Py<PyAny>, layout_name: String) -> PyResult<()> {
    let json_str: String = layout.call_method0(py, "to_json")?.extract(py)?;
    
    let mut metadata = std::collections::BTreeMap::new();
    metadata.insert(layout_name, json_str);  // Uses layout_name as the key
    // ...
}

Type stub (mcap.pyi)

def write_layout(self, layout: "Layout", layout_name: str) -> None:
    """
    :param layout: A Layout object from foxglove.layouts.
    :param layout_name: The name to use as the key in the metadata record.
    """

Test updated

layout_name = "my_test_layout"
writer.write_layout(layout, layout_name)
# Verifies that layout_name is used as the key in the metadata
assert layout_name in record.metadata

 

[surbina]

@cursor this creates a new metadata object each time we call write_layout, so only the last layout will be saved. Can you ensure no layouts are lost if there are multiple calls to write_layout?

[cursor]

Done! I've updated McapWriterHandle to accumulate layouts and write them all when closing.

Changes

rust/foxglove/src/mcap_writer.rs:

Added a layouts field with interior mutability to accumulate layouts:

pub struct McapWriterHandle<W: Write + Seek + Send + 'static> {
    sink: Arc<McapSink<W>>,
    context: Weak<Context>,
    layouts: Mutex<BTreeMap<String, String>>,  // New field
}

Updated write_layout to add to the internal map instead of writing immediately:

pub fn write_layout(&self, layout_name: &str, layout: &str) {
    self.layouts
        .lock()
        .unwrap()
        .insert(layout_name.to_string(), layout.to_string());
}

Updated finish() to write all accumulated layouts before closing:

fn finish(&self) -> Result<Option<W>, FoxgloveError> {
    if let Some(context) = self.context.upgrade() {
        context.remove_sink(self.sink.id());
    }
    // Write all accumulated layouts as a single metadata record
    let layouts = std::mem::take(&mut *self.layouts.lock().unwrap());
    if !layouts.is_empty() {
        self.sink.write_metadata("foxglove.layouts", layouts)?;
    }
    self.sink.finish()
}

Now multiple calls to write_layout will accumulate all layouts and write them together as a single metadata record when the writer is closed.