DOCSEARCHbyAlgolia
Submit Docs

XVIZ Protocol

repository·master·Indexed 22 days ago

https://github.com/aurora-opensource/xviz

A protocol and set of libraries for the real-time transfer and visualization of autonomy data. It provides tools for encoding, validation, and decoding of the XVIZ protocol, serving as the data layer for the Autonomy Visualization System (AVS). The ecosystem includes JavaScript libraries for building and validating data, an XVIZ Server for data delivery, and converters for datasets such as KITTI and nuTonomy, as well as support for ROS data conversion.

Tokens
102.1K
Snippets
334
Records
538
Agent score
73%

What's inside xviz

  1. Overview of XVIZ packages

    master

    XVIZ is a protocol for real-time transfer and visualization of autonomy data. The repository is organized into several specialized packages:

    • @xviz/builder: Node.js utilities for converting data to the XVIZ protocol.
    • @xviz/cli: CLI utilities for the XVIZ protocol.
    • @xviz/io: Library for loading, accessing, and manipulating XVIZ data.
    • @xviz/parser: Client-side decoder and synchronizer for consuming XVIZ data.
    • @xviz/schema: Validation and schemas for the XVIZ protocol.
    • @xviz/server: A complete server module supporting the full XVIZ protocol.

  3. Overview of the XVIZ Protocol

    master
    XVIZ is a protocol designed for the real-time transfer and visualization of autonomy data. It serves as the data layer for AVS (Autonomy Visualization System). The protocol allows developers to declaratively describe visual elements, including geometry, point clouds, images, text, and metrics, along with associated stylesheets and data bindings for a declarative user interface. The protocol is backed by a machine-readable JSON schema provided in the @xviz/schema package.

  4. Understand XVIZ versioning and support policy

    master

    The XVIZ protocol follows Semantic Versioning (SemVer) principles to communicate the nature of updates:

    • Major versions: Released for breaking API changes.
    • Minor versions: Released for new API additions (e.g., new primitives or additional fields in existing primitives).
    • Patch versions: Released for non-API-changing updates.

    Support Lifecycle: Support is focused on the most recent revision of the current major version and the most recent revision of the previous major version. For example, if the current version is v3.0.1, support will focus on v3.0.1 and, if necessary, the latest revision of the previous major version (e.g., v2.2.1).

    Backwards Propagation: Improvements (such as performance enhancements) made in a newer major version are back-propagated to the latest supported version of the previous major version.

  7. Convert ROS messages to XVIZ with @xviz/ros

    master

    The @xviz/ros module enables reading ROS Bag files and converting ROS messages into the XVIZ data format. It supports both offline conversion and run-time conversion. While primarily focused on ROS 1, the workflow is largely compatible with ROS 2.

    Key capabilities include:

    • Reading ROS Bag files.
    • Configuration-based conversion workflows.
    • Custom message conversion for unsupported types.
    • Integration with the broader XVIZ ecosystem via the ROSBagProvider abstraction.

  8. Structure of an XVIZ converter class

    master

    When implementing a custom data converter for XVIZ, you should follow a consistent class structure to handle data dependencies, loading, metadata generation, and message conversion. A standard converter class implements the following four functional areas:

    1. Dependency Injection: Accept necessary dependencies via the constructor.
    2. Data Loading: Use a load method to ingest and parse the source data.
    3. Metadata Generation: Use a getMetadata method to define the XVIZ stream metadata produced by the converter.
    4. Message Conversion: Use a convertMessage method to transform the current data state into XVIZ streams for a specific point in time (a "message").
    // #1 Accept dependencies during construction
constructor(...) {}

// #2 Load and parse data
load(...) {}

// #3 Generate the XVIZ stream metadata for streams output from this converter
getMetadata(...) {}

// #4 Generate XVIZ stream data for the current message
convertMessage(...) {}

  9. Use Sources and Sinks for simple IO

    master

    Sources and Sinks provide a simplified abstraction for reading and writing data. Use these when you need straightforward access to data streams. @xviz/io provides synchronous implementations for:

    • File: For reading from or writing to the filesystem.
    • Memory: For reading from or writing to in-memory buffers.

  10. Define a Declarative UI for your data source

    master

    XVIZ uses a Declarative UI schema to map data to visual elements. This schema defines how UI components—such as plots, controls, tables, and video panels—are rendered and how they bind to specific stream names.

    Best Practice: Send the Declarative UI schema within the Metadata of your source. This ensures the UI layout remains closely coupled with the data source it describes.

  11. How to load and parse XVIZ data

    master

    XVIZ data can be consumed in several ways depending on your application's needs:

    1. Network/Socket: Designed to be served over a socket in GLB file-sized message chunks.
    2. File: Can be read directly from local files.
    3. Network Requests: Can be fetched via standard network requests.

    When working with XVIZ stored in the binary GLB file format, the parsing process involves two main stages:

    1. Unpacking and Rehydration: The binary GLB file is unpacked, and its binary chunks are rehydrated into JavaScript objects and typed arrays.
    2. Post-processing: The rehydrated data is standardized into an easy-to-work-with format. This stage is also where application-specific configurations (such as filtering specific data streams) are applied.

  12. Understand XVIZ styling precedence

    master

    XVIZ allows you to define visual styles for elements at different levels of granularity. When multiple styles are applied to the same element, they follow a specific order of precedence (from highest to lowest):

    1. Inline object styles: Defined directly on the individual element using the .style() method.
    2. Stream metadata style class: Defined in the stream metadata using .styleClass() and applied via .classes() on the element.
    3. Stream metadata stream style: Defined in the stream metadata using .streamStyle() and applied to all elements in that stream.

    Understanding this hierarchy is essential for creating complex visualizations where you want global defaults but specific overrides for certain object types or individual instances.