Welcome to the lichtblick wiki!

Lichtblick is a Floxglove fork. All dev documentation from foxglove can be found here: https://docs.foxglove.dev/docs For new increments done to Lichtblick, user documentation will be added soon.

Stay tunned 🚀

Introduction

To begin visualizing data, navigate to the Lichtblick dashboard and and select a data source option.

Data Sources

Connect to a live data source or load local and imported files to visualize their data.

Live data

"open connection" - inspect real-time data from an active robotics stack or a remote source (e.g. S3 bucket)
Supported Formats
ROS 1, ROS 2, Custom, MCAP, Velodyne

Local data

"open local file" - examine data stored locally on your computer
Supported Formats
ROS 1, MCAP, PX4 ULog

Once connected, Lichtblick will display the data source's topics in the sidebar:

Live Data

Connect to live data sources using Lichtblick's WebSocket, Rosbridge, and Velodyne Lidar integrations. Additionally, you can load remote data files via URL.

Supported Formats

Lichtblick supports the following formats for live data connections:

Limitations

When connecting to a live robotics stack, each connection type offers different capabilities:

Local Data

Lichtblick enables you to load local data files for visualization.

Supported formats

Getting Started

To load local files for visualization, you can:

• Click "Open local file..." in the dashboard or left-hand menu.
• Open or drag-and-drop the file from your operating system's file manager (desktop only).

Introduction

Enhance Lichtblick's functionality with custom extensions tailored to your team's specific workflows. Create personalized panels, transform custom messages into Lichtblick-compatible schemas, and map topic names for improved visualization.

After developing and installing your extension, navigate to your app settings to view all available and installed extensions.

Settings API

The Panel Settings API allows users to link settings to message converters based on panel types.

PanelSettings Interface

The PanelSettings<ExtensionSettings> interface defines the structure for managing custom settings associated with message converters and panels. It allows users to define settings that can be dynamically applied to specific topics or schemas, enabling flexible configuration of message processing behavior.

Generic Type Parameter

• ExtensionSettings: Represents the type of the custom settings object. This is user-defined and should match the structure of the settings you want to configure.

Properties

1. settings

settings: (config?: ExtensionSettings) => SettingsTreeNode;

• Purpose: Defines how the settings should be rendered in the settings UI.

• Parameters:

  • config: An optional object containing the current configuration values. Its type is inferred from the defaultConfig property.

• Returns: A SettingsTreeNode that describes the structure of the settings UI. This node will be merged with the settings tree for the associated topic (under the path ["topics", "__topic_name__"]).

• Example:

settings: (config) => ({
  fields: {
    threshold: {
      input: "number",
      value: config?.threshold,
      label: "Threshold Value",
    },
  },
}),

2. handler

handler: (action: SettingsTreeAction, config?: ExtensionSettings) => void;

• Purpose: Handles changes to the settings made by the user in the UI.

• Parameters:

  • action: A SettingsTreeAction object describing the user's action (e.g., updating a field).
  • config: A mutable object representing the current configuration. Modifying this object updates the state.

• Behavior:

  • This function is called after the default settings handler.
  • It allows you to validate or transform the settings before they are applied.

• Example:

handler: (action, config) => {
  if (action.action === "update" && action.payload.path[1] === "threshold") {
    // Ensure threshold is within valid range
    config.threshold = Math.max(0, Math.min(1, action.payload.value));
  }
},

3. defaultConfig

defaultConfig?: ExtensionSettings;

• Purpose: Provides default values for the settings. These values are used when no configuration is explicitly set.

• Type: Must match the ExtensionSettings type.

• Example:

defaultConfig: {
  threshold: 0.5,
  enableFeature: true,
},

Expected Behavior

When implementing this interface:

1. Settings UI: The settings function defines how the settings are displayed in the UI. It creates a settings tree node that is merged into the topic's settings.
2. Configuration Management: The handler function processes user interactions with the settings UI, allowing you to validate or transform the configuration.
3. Defaults: The defaultConfig provides initial values for the settings, ensuring the panel or converter has a valid configuration even if the user hasn't customized it.

Possible Outcomes

1. Dynamic Settings UI:

   • The settings defined in the settings function will appear in the UI under the associated topic.
   • Users can modify these settings, and changes will be handled by the handler function.

2. Custom Configuration:

   • The handler function allows you to enforce constraints or transform values before they are applied.
   • For example, you can ensure a threshold value stays within a valid range.

3. Default Behavior:

   • If no custom configuration is provided, the defaultConfig values are used.
   • This ensures the panel or converter works out of the box without requiring user input.

Example Implementation:

type Schema1Schema = {
  value: number;
}

type Schema2Schema = {
  value: number;
}

// Define the configuration type
type Config = { threshold: number };

// Helper function to cast PanelSettings to the correct type
const generatePanelSettings = <T>(obj: PanelSettings<T>) =>
  obj as PanelSettings<unknown>;

export function activate(extensionContext: ExtensionContext): void {

  // Register the message converter
  extensionContext.registerMessageConverter({
    fromSchemaName: "schema1",
    toSchemaName: "schema2",

    converter: (msg: Schema1Schema, event): Schema2Schema | undefined => {

      // Access the threshold setting for the current topic
      const config = event.topicConfig as Config | undefined;
      const threshold = config?.threshold;

      // Filter messages based on the threshold
      if (threshold && msg.value > threshold) {
        return { value: msg.value }; // Forward the message if it exceeds the threshold
      }

      return undefined; // Ignore the message if it doesn't meet the threshold
    },
    // Define the settings for the threshold
    panelSettings: {
      ThresholdPanel: generatePanelSettings({
        settings: (config) => ({
          fields: {
            threshold: {
              label: "Threshold Value",
              input: "number",
              value: config?.threshold,
              placeholder: "Enter a threshold value",
            },
          },
        }),

        handler: (action, config) => {
          if (config == undefined) {
            return;
          }

          // Update the threshold setting when the user changes it in the UI
          if (
            action.action === "update" &&
            action.payload.path[2] === "threshold"
          ) {
            config.threshold = action.payload.value as number;
          }
        },
        defaultConfig: {
          threshold: 0.5, // Default threshold value
        },
      }),
    },
  });
}

Use Case

This interface is typically used when registering a message converter:

extensionContext.registerMessageConverter({
  fromSchemaName: "schema1",
  toSchemaName: "schema2",

  converter: (msg: Schema1Schema, event): Schema2Schema | undefined => {

      // Access the threshold setting for the current topic
      const config = event.topicConfig as Config | undefined;
      const threshold = config?.threshold;

      // Filter messages based on the threshold
      if (msg.value > threshold) {
        return { value: msg.value }; // Forward the message if it exceeds the threshold
      }

      return undefined; // Ignore the message if it doesn't meet the threshold
},

Summary

The PanelSettings<ExtensionSettings> interface provides a structured way to:

1. Define custom settings for panels or message converters.
2. Render these settings in the UI.
3. Handle user interactions with the settings.
4. Provide default values for the settings.

By implementing this interface, you enable users to configure their panel or converter dynamically, making it more flexible and adaptable to different use cases.

Lichtblick empowers robotics teams to efficiently explore, collaborate on, and interpret their robots' data, leading to smarter iterations and faster development cycles.

Workflows

Lichtblick offers a comprehensive suite of developer tools tailored for each phase of the robotics development lifecycle:

Recording

• Capture multimodal data across various supported encoding formats, including MCAP, ROS 1, ROS 2, Protobuf, and more.

Ingestion

• Import recordings from local devices and Edge Sites into a centralized cloud repository for streamlined access.

Processing

• Organize imported data recordings by device, timestamp, and topic for structured analysis.
• Implement retention policies to effectively manage your team's data storage.
• Set up webhooks to seamlessly integrate with your existing data pipeline.

Visualization

• Stream imported data to Lichtblick and third-party tools like Jupyter Notebooks for comprehensive analysis.
• Configure panels to gain insights into your robots' sensory inputs, decision-making processes, and actions.
• Develop shared layouts to facilitate recurring visualization and debugging tasks.

Collaboration

• Enhance logs with metadata and events to simplify search and discovery.
• Leverage collective expertise to triage incidents and conduct root cause analyses.

Settings

General

Here you can find the general settings that allows you to configure core preferences, such as language, appearance, and default behaviors. These settings help customize your experience to better fit your needs.

Below is a list of all available options and their purposes:

Extensions

The Extensions menu allows users to manage and install additional features to Lichtblick. Under the LOCAL section, you’ll find extensions that are already installed. The DEFAULT section lists available extensions that can be installed to enhance functionality.

Recently we added a search bar to the extensions menu to facilitate the experience when managing extensions.

When an extension is selected, a menu opens with options to install or uninstall the extension. This menu also allows users to view the extension's README and Changelog.

Experimental features

The Experimental Features section includes early-stage functionalities that could be unstable and are not recommended for daily use. Options here allow users to test new capabilities, such as memory usage indicators, before they become part of the stable release. Use with caution, as these features may impact performance or cause unexpected behavior.

• When the Memory usage indicator checkbox is selected, an indicator appears on the top bar showing the percentage of memory in use. Hovering over the indicator displays the actual memory usage in MB.

About

This section provides information about the software version and legal details. Here, you can check the current version and access the license terms

Introduction

Lichtblick offers a comprehensive suite of visualization tools to help you analyze and interpret your robotics data effectively.

Getting Started

To begin visualizing your data, connect to a data source and open a panel.

Open Data Source:

• Click "Open data source" in the left-hand menu.
• Choose from available options: live data or local file.

Opening a Panel:

• Click "Add panel" in the dashboard or left-hand menu.
• Select the desired panel type (e.g., 3D, Raw Message, Image).

Desktop-only features

Connecting to data

• open a native ROS 1 connection
• connect to a Velodyne LIDAR hardware
• load local URDF and mesh resources in your 3D panel using package:// prefixed in the URLs

Extensions

• Install via registry
• Install locally

Interface Overview

Lichtblick's interface is designed for intuitive navigation:

App Menu: Connect to a data source, toggle sidebars, or access resources.
Add Panel: Add a new panel to your current layout.
Layout Menu: Save your workspace view as a layout and share it with teammates.
Left Sidebar: Edit panel settings, view data source topics, and troubleshoot connection issues.
Right Sidebar: Set layout-wide variables, view playback metrics.

Sidebars

Panel sidebar

Edit settings for any selected panel

Topics sidebar

View all topics available in the data source, along with their data types and message rates

Problems sidebar

See a list of playback errors to troubleshoot

Variables sidebar

set layout-wide variables that can be used in different panels with the message path syntax

System Requirements

Lichtblick supports Windows, macOS, and Linux on both web and desktop platforms.

For the web application, use Chrome v111 or later.

For the desktop application, download the latest version for your operating system - check our latest release.

Playback

When visualizing local or remote data files, you can navigate their contents using the playback controls.

Message Ordering

Lichtblick orders and plays messages based on their log time. Log time typically refers to when the message was recorded but can be set to the timestamp that best reflects the reality you wish to visualize for time-critical signals. It's important to choose your log times carefully and consider sources of time skew such as network latency, batching, and buffering.

Robotics data is often associated with other timestamps, in addition to the log time. The Plot and State Transitions panels can be configured to order data using alternative timestamp fields:

Message Loading

Lichtblick optimizes how it loads complex robotics data for more streamlined seeking and playback.

Message "lookback"

When seeking to an arbitrary point in your loaded data, it's unlikely that every topic you are visualizing has a message at exactly the time you jumped to. To ensure that your layout still displays reasonable data, Lichtblick performs a "lookback" on your data. It looks for the most recent message on each subscribed topic, ensuring that even when seeking to an arbitrary point, Lichtblick will still display reasonable data for all the panels in your layout.

Latched Topics

By default, ROS 1 .bag files, MCAP files, and Lichtblick data streams will play back using message latching. When seeking within your data, Lichtblick fetches the last message on all subscribed topics, even if they occurred multiple minutes before your seek location. Every panel in the layout will then automatically display the last data it saw for that topic, even if that data is infrequently published or was not published at that exact moment in time. Message latching allows panels to accurately display data from infrequently published topics, even while seeking around to multiple points in your data at random.

Preloading

While most Lichtblick panels display just the most recent message for a given topic, others like the Plot and Map panels benefit from visualizing messages across the data's entire time range. Preloading data allows these panels to access all their historical data throughout playback, making it easier to spot anomalies, summarize robot behavior, and recognize trends and patterns.

Even panels that visualize their most recently seen data can benefit from preloading. For example, the 3D panel preloads its transform messages to accurately position its markers. Robots often have many coordinate frames (e.g., joints of a robot arm, cameras on a self-driving car), each with their own markers. To render markers from different frames in a single 3D scene, the panel needs to use transforms to calculate the position of these visual elements in a common coordinate space. Since transforms accumulate and update over time, preloading ensures that the 3D panel has access to all necessary transform data for accurate visualization.

Shortcuts

Space - pause or play
shift + ⬅️ - seek backward 10ms
shift + ➡️ - seek forward 10 ms
⬅️ - seek backward 100ms
➡️ - seek forward 100ms
Alt + ⬅️ - seek backward 500ms
Alt + ➡️ - seek forward 500ms

Message schemas

Introduction

Lichtblick requires incoming messages to conform to specific structures for proper visualization. Utilizing schemas allows you to fully leverage the platform's built-in visualizations.

Supported Formats

• Protobuf
• JSON schema
• ROS 1
• ROS 2
• TypeScript
• FlatBuffers

If you've already developed custom messages, you can transform them into Lichtblick-supported schemas using a message converter extension.

WIP

Protobuf and JSON schema

Layouts

Panels

Variables

Message path syntax

Extensions

Shareable links

Open via CLI

Shortcuts

Annotate ROS enum fields

Open va CLI

Easily open local files using the command line by installing the Lichtblick desktop application. This allows you to quickly access .mcap files without manually navigating through the interface.

Local Files

Once the desktop application is installed, Lichtblick will automatically be set as the default handler for .mcap files. You can open files directly from the command line based on your operating system:

lichtblick /path/to/your/file.mcap

# Open multiple .mcap files simultaneously
lichtblick /path/to/your/file1.mcap /path/to/your/file2.mcap

# Open all .mcap files from a specific directory
lichtblick /path/to/your/files/*.mcap

open /path/to/your/file.mcap

# To open multiple .mcap files, either execute the binary directly or use the --source parameter

start /path/to/your/file.mcap

# To open multiple .mcap files, either execute the binary directly or use the --source parameter

Flags and Parameters

Lichtblick supports several command-line parameters to streamline your workflow by preloading specific configurations, eliminating the need for manual adjustments.

• --defaultLayout: Loads a predefined layout upon opening Lichtblick. This does not upload or modify the layout—only selects an existing one.

  lichtblick --defaultLayout="my-custom-layout"
  

• --source: Opens one or multiple .mcap files, or an entire directory, directly upon launch.

  lichtblick --source="path/to/your/file.mcap"
  
  # For multiple mcaps
  lichtblick --source="path/to/your/file1.mcap,path/to/your/file2.mcap"
  
  # For a directory
  lichtblick --source="path/to/your/files/"
  

• --time: Opens Lichtblick player at a specific timestamp.

  # Specify the time as a UNIX timestamp (in seconds)
  lichtblick --time=1633046400  # Interpreted as 2021-10-01 12:00:00 AM UTC
  
  # Specify the time using a string format
  lichtblick --time="2024-12-02 11:45"
  lichtblick --time="2020-04-07 04:45:21 PM"
  lichtblick --time="2020-04-07 04:45:21 PM CET"  # Lichtblick will attempt to convert this to the timezone used in the MCAP file
  

  These parameters help optimize the user experience by enabling quicker access to files and configurations without navigating through the UI manually.

Important Note

Multiple files are available only to .mcap files at the moment.