diff --git a/docs/device/4-device-collector.md b/docs/device/4-device-collector.md index 6306fd6d8..2f8364152 100644 --- a/docs/device/4-device-collector.md +++ b/docs/device/4-device-collector.md @@ -31,17 +31,17 @@ sidebar_position: 4 ![org-dev-rule-save](./img/4-3-device-save-collector.png) -## 数采规则格式详解 +## 数采规则格式详解 {#device-collector-format} 数采规则主要对 5 个模块进行设置： | 模块名称 | 功能描述 | | --------------------------- | -------------------------------------------------------------- | -| 数据收集器设置（collector） | 完成数据采集后，是否删除数采客户端在设备端生成的缓存数据 | +| 数据收集器设置（collector） | 完成数据采集后，是否删除数采客户端在设备端生成的缓存数据 | | 存储设置（mod） | 设备 ID 存放位置；监听目录；客户端初始化监听时间范围；采集目录 | | 设备事件属性（device） | 事件的属性值 | | 规则触发话题（topic） | 规则触发话题 | -| 更新设置（updater） | 数采客户端是否开启自动更新 | +| 更新设置（updater） | 数采客户端是否开启自动更新 | 示例模板如下： diff --git a/docs/use-case/data-diagnosis/2-get-started.md b/docs/use-case/data-diagnosis/2-get-started.md index 0a10172bd..e045e336b 100644 --- a/docs/use-case/data-diagnosis/2-get-started.md +++ b/docs/use-case/data-diagnosis/2-get-started.md @@ -14,7 +14,7 @@ sidebar_position: 2 1. 请准备好一台设备 -2. 请创建名为 auto-upload 的项目，详情参见[创建新项目](https://docs.coscene.cn/docs/recipes/project)。 +2. 请创建名为 auto-upload 的项目 3. 请确认你在 coScene 的组织角色为「管理员」。若不是管理员，请联系组织管理员更新你的组织角色。 @@ -96,7 +96,7 @@ sidebar_position: 2 enabled: false ``` - \*更多配置参见[数采规则格式](https://docs.coscene.cn/docs/recipes/device/device-collector/#%E6%95%B0%E9%87%87%E8%A7%84%E5%88%99%E6%A0%BC%E5%BC%8F) + 更多配置参见[数采规则格式](../../device/4-device-collector.md#device-collector-format) 3. 点击【保存编辑】按钮 diff --git a/docs/viz/8-extensions/5-api/5-topic-aliases/2-topic-alias.md b/docs/viz/8-extensions/5-api/5-topic-aliases/2-topic-alias.md index 9d8e77ab2..3dc56d9f0 100644 --- a/docs/viz/8-extensions/5-api/5-topic-aliases/2-topic-alias.md +++ b/docs/viz/8-extensions/5-api/5-topic-aliases/2-topic-alias.md @@ -20,4 +20,4 @@ name: string; ```typescript sourceTopicName: string; -``` \ No newline at end of file +``` diff --git a/docs/viz/8-extensions/5-api/5-topic-aliases/3-topic-alias-function.md b/docs/viz/8-extensions/5-api/5-topic-aliases/3-topic-alias-function.md index 1202202e1..003196f99 100644 --- a/docs/viz/8-extensions/5-api/5-topic-aliases/3-topic-alias-function.md +++ b/docs/viz/8-extensions/5-api/5-topic-aliases/3-topic-alias-function.md @@ -12,10 +12,10 @@ TopicAliasFunction 接收数据源主题和变量列表，并输出别名主题 ## 参数 -| 参数 | 类型 | -| --- | --- | +| 参数 | 类型 | +| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | args | [Immutable](../6-other/2-immutable.md)\<\{ topics: [BaseTopic](./1-base-topic.md)[]; globalVariables: Readonly\\>; \}\> | ## 返回值 -TopicAlias[] \ No newline at end of file +TopicAlias[] diff --git a/docs/viz/8-extensions/5-api/6-other/2-immutable.md b/docs/viz/8-extensions/5-api/6-other/2-immutable.md index a2488dd9e..3f582cac7 100644 --- a/docs/viz/8-extensions/5-api/6-other/2-immutable.md +++ b/docs/viz/8-extensions/5-api/6-other/2-immutable.md @@ -12,5 +12,5 @@ type Immutable = Type extends Exclude ? Type : Type extend ## 类型参数 | 类型参数 | -| -------------- | -| Type | \ No newline at end of file +| -------- | +| Type | diff --git a/docs/viz/8-extensions/5-api/6-other/8-variable-value.md b/docs/viz/8-extensions/5-api/6-other/8-variable-value.md index 10f03cc42..3acf2f772 100644 --- a/docs/viz/8-extensions/5-api/6-other/8-variable-value.md +++ b/docs/viz/8-extensions/5-api/6-other/8-variable-value.md @@ -7,5 +7,3 @@ sidebar_position: 8 ```typescript type VariableValue = undefined | boolean | number | string | VariableValue[] | {}; ``` - -变量的有效类型 \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 682862192..d97fa1bfa 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -9,7 +9,7 @@ import { themes } from 'prism-react-renderer'; const defaultExclude = ['**/_*.{js,jsx,ts,tsx,md,mdx}', '**/_*/**', '**/*.test.{js,jsx,ts,tsx}', '**/__tests__/**']; // some docs are not translated, so we need to exclude them in en -const excludeInEn = ['**/viz/8-extensions/**', '**/viz/9-message-schemas/**']; +const excludeInEn = []; /** @type {import('@docusaurus/types').Config} */ const config = { diff --git a/i18n/en/code.json b/i18n/en/code.json index 60fa2fe40..e722da6e4 100644 --- a/i18n/en/code.json +++ b/i18n/en/code.json @@ -598,5 +598,11 @@ }, "home.catalogue.apt-source-install": { "message": "Installing coScene Software via APT" + }, + "home.catalogue.extensions": { + "message": "Extensions" + }, + "home.catalogue.message-schemas": { + "message": "Message Schemas" } -} +} \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current.json b/i18n/en/docusaurus-plugin-content-docs/current.json index 2b89be6f0..01f2f6450 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current.json +++ b/i18n/en/docusaurus-plugin-content-docs/current.json @@ -5,7 +5,7 @@ }, "sidebar.tutorialSidebar.category.新手入门": { "message": "Getting Started", - "description": "The label for category 快速开始 in sidebar tutorialSidebar" + "description": "The label for category 新手入门 in sidebar tutorialSidebar" }, "sidebar.tutorialSidebar.category.协作": { "message": "Collaboration", @@ -117,6 +117,46 @@ }, "sidebar.tutorialSidebar.category.客户端": { "message": "Desktop Apps", - "description": "The label for category 客户端 in the sidebar" + "description": "The label for category 客户端 in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.插件": { + "message": "Extensions", + "description": "The label for category 插件 in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.最佳实践": { + "message": "Best Practices", + "description": "The label for category 最佳实践 in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.指南": { + "message": "Guide", + "description": "The label for category 指南 in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.API 参考": { + "message": "API References", + "description": "The label for category API 参考 in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.入口": { + "message": "Entry Point", + "description": "The label for category 入口 in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.自定义面板": { + "message": "Custom Panels", + "description": "The label for category 自定义面板 in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.消息转换器": { + "message": "Message Converters", + "description": "The label for category 消息转换器 in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.话题别名": { + "message": "Topic Aliases", + "description": "The label for category 话题别名 in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.其他": { + "message": "Others", + "description": "The label for category 其他 in sidebar tutorialSidebar" + }, + "sidebar.tutorialSidebar.category.消息架构": { + "message": "Message Schema", + "description": "The label for category 消息架构 in sidebar tutorialSidebar" } } \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/collaboration/integration/1-jira-integration.md b/i18n/en/docusaurus-plugin-content-docs/current/collaboration/integration/1-jira-integration.md index a07ac2452..a28733ea6 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/collaboration/integration/1-jira-integration.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/collaboration/integration/1-jira-integration.md @@ -3,49 +3,53 @@ sidebar_position: 1 --- # Jira Integration + ## Introduction + After configuring Jira integration, you can synchronize project tasks to Jira for unified task management on the enterprise ticketing platform. Here are typical use cases: + 1. When device issues occur, automatically upload data and create tasks in Jira 2. During data visualization analysis, create tasks at key timestamps and sync them to Jira ## Operation Process + ### Configure Integration > Each project is configured independently, and only project administrators can edit 1. Enter the project that needs integration configuration, go to Project Settings - Service Integration - Jira, and click the [Add Config] button. - ![jira_1](./img/jira_1.png) + ![jira_1](./img/jira_1.png) 2. Fill in the integration configuration and save. Field descriptions are as follows: - ```yaml - enabled: true # Enable configuration - - endpoint: https://jira.com/ # Jira URL - httpBasicAuthorization: - usernameAndPassword: - username: root # Jira username - password: admin # Jira password - - projectKey: TEST # Jira project Key - issueType: 'Bug' # Jira issue type - issueTitleTemplate: '{{task.title}}' # Jira issue title, e.g., task name - issueDescriptionTemplate: | # Issue description - [Task Name]: {{task.title}} - [Device ID]: {{device.id}} - [Record Link]: {{record.link}} - - customFields: # Issue custom fields - customfield_1: - id: '88888' # Field 1 (dropdown style), select option with id 88888 - customfield_2: TEST # Field 2 (text box style), enter content as TEST - customfield_3: # Field 3, enter P1 - value: P1 - ``` + ```yaml + enabled: true # Enable configuration + + endpoint: https://jira.com/ # Jira URL + httpBasicAuthorization: + usernameAndPassword: + username: root # Jira username + password: admin # Jira password + + projectKey: TEST # Jira project Key + issueType: 'Bug' # Jira issue type + issueTitleTemplate: '{{task.title}}' # Jira issue title, e.g., task name + issueDescriptionTemplate: | # Issue description + [Task Name]: {{task.title}} + [Device ID]: {{device.id}} + [Record Link]: {{record.link}} + + customFields: # Issue custom fields + customfield_1: + id: '88888' # Field 1 (dropdown style), select option with id 88888 + customfield_2: TEST # Field 2 (text box style), enter content as TEST + customfield_3: # Field 3, enter P1 + value: P1 + ``` - **enabled** - + Jira integration status, enable/disable (true/false). Enabled by default, when disabled tasks cannot be synced to Jira - **endpoint** @@ -53,11 +57,11 @@ After configuring Jira integration, you can synchronize project tasks to Jira fo Jira URL, e.g., `https://www.atlassian.com/` - **username** - + Jira username, used to create issues and get issue information in Jira projects with this user's identity - **password** - + Password corresponding to the Jira username - **projectKey** @@ -77,18 +81,19 @@ After configuring Jira integration, you can synchronize project tasks to Jira fo ``` Where: + - `{jira_endpoint}`: Jira URL, e.g., https://www.atlassian.com/ - `{projectKey}`: Jira project Key 2. After getting all issue type information, use ctrl + f shortcut to quickly find the id corresponding to the issue type you need to configure, e.g., find the id value for `issuetype` `Bug` - ![jira_2](./img/jira_2.png) + ![jira_2](./img/jira_2.png) 3. After finding the id corresponding to the issue type, configure it in the `issueType` field. - - ```yaml - issueType: '10004' # Jira issue type - ``` + + ```yaml + issueType: '10004' # Jira issue type + ``` - **issueTitleTemplate** @@ -109,37 +114,40 @@ After configuring Jira integration, you can synchronize project tasks to Jira fo ``` Where: + - `{jira_endpoint}`: Jira URL, e.g., https://www.atlassian.com/ - `{projectKey}`: Jira project Key 2. After getting all field information, use ctrl + f shortcut to quickly find the custom field name you need to configure, e.g., find the name and value of field `test1-type` - ![jira_3](./img/jira_3.png) + ![jira_3](./img/jira_3.png) 3. Enter the corresponding field format according to the [Jira Official Documentation](https://developer.atlassian.com/server/jira/platform/rest/v10000/intro/#field-input-formats), enter the field name and value in the Jira configuration. Taking the multi-select box `test1-type` as an example: + - Find "Multi-select Type" in the Jira official documentation, copy the format ![jira_4](./img/jira_4.png) - Under custom fields in the Jira configuration, paste the "Multi-select Type" format, replace the content with the previously found `test1-type` field name and value - ```yaml - customFields: - "customfield_10187" : [ { "value": "n1" }, { "value": "n2" } ] - ``` + ```yaml + customFields: + 'customfield_10187': [{ 'value': 'n1' }, { 'value': 'n2' }] + ``` ### Variable Description + Task information in integration supports using variables, see the table below: -| Variable Name | Meaning | -|--------|------| -| `{{task.title}}` | Task name | -| `{{record.title}}` | Record name | +| Variable Name | Meaning | +| ------------------------ | ------------------ | +| `{{task.title}}` | Task name | +| `{{record.title}}` | Record name | | `{{record.description}}` | Record description | -| `{{record.labels}}` | Record labels | -| `{{record.link}}` | Record link | -| `{{device.id}}` | Device ID | -| `{{device.title}}` | Device name | +| `{{record.labels}}` | Record labels | +| `{{record.link}}` | Record link | +| `{{device.id}}` | Device ID | +| `{{device.title}}` | Device name | ### Synchronize Tasks to Jira @@ -147,14 +155,16 @@ Task information in integration supports using variables, see the table below: 1. Enter the project's "General Tasks" page, click the [Sync Task] button corresponding to the task - ![jira_5](./img/jira_5.png) + ![jira_5](./img/jira_5.png) 2. After successful synchronization, the created Jira link and status will be displayed. Click the status button to jump to Jira to view issue details. ## Managing Jira Integration + > Only project administrators can manage Jira integration ### Edit Integration + 1. In the project, go to "Project Settings - Service Integration" page, click [Edit Config] for Jira. ![jira_6](./img/jira_6.png) @@ -164,10 +174,11 @@ Task information in integration supports using variables, see the table below: ![jira_7](./img/jira_7.png) ### Delete Integration + 1. In the project, go to "Project Settings - Service Integration" page, click [Edit Config] for Jira. ![jira_6](./img/jira_6.png) 2. Click [Delete], confirm again to delete the integration information. After deletion, tasks cannot be synchronized to Jira. - ![jira_8](./img/jira_8.png) \ No newline at end of file + ![jira_8](./img/jira_8.png) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/collaboration/organization/1-organizations.md b/i18n/en/docusaurus-plugin-content-docs/current/collaboration/organization/1-organizations.md index b426c444d..2eacfffa0 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/collaboration/organization/1-organizations.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/collaboration/organization/1-organizations.md @@ -3,33 +3,36 @@ sidebar_position: 1 --- # Organizations + An organization is a logical concept that represents a team or a company. An organization can have multiple projects and members. ## Organization Management Interface + On the "Organization Management" page, you can view information about the organization's projects, members, devices, images, billing, and more. -| Name | Description | -| --- | --- | -| Projects | Manage all projects within the organization in the project list. Projects are the units of data management, see [Projects](../project-collaboration/1-project.md) | -| Members | Manage all users and their permissions within the organization in the member list | -| Devices | Centrally manage all devices within the organization in the organization device list. Devices can establish connections with physical devices, see [Devices](../../device/1-device.md) | -| Images | The platform provides a professional private image registry to centrally manage all images within the organization, see [Images](../../image/1-about-docker-image.md) | -| Usage & Billing | Display information about the organization's storage, number of devices, computation time, etc. | +| Name | Description | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Projects | Manage all projects within the organization in the project list. Projects are the units of data management, see [Projects](../project-collaboration/1-project.md) | +| Members | Manage all users and their permissions within the organization in the member list | +| Devices | Centrally manage all devices within the organization in the organization device list. Devices can establish connections with physical devices, see [Devices](../../device/1-device.md) | +| Images | The platform provides a professional private image registry to centrally manage all images within the organization, see [Images](../../image/1-about-docker-image.md) | +| Usage & Billing | Display information about the organization's storage, number of devices, computation time, etc. | ![org_1](./img/org_1.png) ## Creating an Organization + 1. Access [coScene Platform https://www.coscene.io/](https://www.coscene.io) through your browser, click [Login] in the upper right corner to enter the login interface - - ![org_2](./img/org_2.png) + + ![org_2](./img/org_2.png) 2. Choose a login method to enter the platform: Email or Google Workspace - ![org_3](./img/org_3.png) + ![org_3](./img/org_3.png) 3. Fill in "Organization Name" and "Organization ID", check "Agree", and click the [Create Organization] button - - ![org_4](./img/org_4.png) + + ![org_4](./img/org_4.png) 4. After successful creation, you will automatically enter the organization homepage @@ -38,8 +41,11 @@ On the "Organization Management" page, you can view information about the organi Please refer to the [Projects](../project-collaboration/1-project.md) section ## Adding Organization Members + The method of adding members differs depending on how the organization was created: + - **Organizations created with email login**: + - Organization administrators can click the [Invite Members] button on the "Organization Management-Members" page to invite members to join the organization via email. ![org_5](./img/org_5.png) @@ -55,11 +61,13 @@ The method of adding members differs depending on how the organization was creat Please refer to the [Adding Devices](../../device/2-create-device.md) section ## Adding Images + > Images in the organization can be used in various projects for [Automation](../../workflow/1-quick-start-workflow.md) or [Cloud Test](../../sim-and-tests/regression/1-intro.md). Please refer to the [Images](../../image/1-about-docker-image.md) section ## Usage & Billing + > Only organization administrators can view organization usage information. Organization usage information includes: organization storage, number of active devices, computation time, etc. @@ -70,4 +78,4 @@ On the "Organization Management-Usage & Billing" page, you can view organization On the homepage, you can view the number of organization records, projects, and devices. -![org_7](./img/org_7.png) \ No newline at end of file +![org_7](./img/org_7.png) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/use-case/data-diagnosis/2-get-started.md b/i18n/en/docusaurus-plugin-content-docs/current/use-case/data-diagnosis/2-get-started.md index d0bb244ee..2029e9d30 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/use-case/data-diagnosis/2-get-started.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/use-case/data-diagnosis/2-get-started.md @@ -11,7 +11,7 @@ Using the following scenario as an example, let's setup your automatic data coll ## Prerequisites 1. Have a device ready. -2. Create a project named `auto-upload`. See [Cerate New Project](https://docs.coscene.cn/en/docs/recipes/project) for details. +2. Create a project named `auto-upload`. 3. Make sure your role in the coScene organization is "Administrator". If you're not an administrator, contact your organizational admin to update your role. ![org-role](./img/org-role.png) @@ -191,6 +191,3 @@ Using the following scenario as an example, let's setup your automatic data coll 2. View the automatically created record, and check the data uploaded in the record. ![auto-record-1](./img/auto-record-1.png) - - - diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/1-introduction.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/1-introduction.md new file mode 100644 index 000000000..e03aa003f --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/1-introduction.md @@ -0,0 +1,63 @@ +--- +sidebar_position: 1 +--- + +# Extensions Introduction + +Extend visualization capabilities through custom extensions to better support your team's unique workflows. Build custom panels, convert custom messages into visualization-supported schemas, and create aliases for topic names to facilitate visualization. + +Once you develop and install extensions, you can enable them in the application settings to display all available and installed extensions. + +## Custom Panels + +While visualization provides a set of built-in panels for robot data visualization and debugging, many users have domain-specific requirements that our out-of-the-box product cannot meet. + +Custom panel extensions allow you to build complete panels. Custom panels can subscribe to messages on various topics, publish and receive messages, and display message information in a form that best suits your workflow. + +Custom panels are ideal when your visualization or interaction requirements are customized and not easily addressed through built-in panels. + +### Links and Resources + +- Guide: Creating Custom Panels +- Building Custom Panel Extensions (React) + +## Message Converters + +Message converter extensions allow you to transform messages from one schema to another. By converting messages to schemas supported by visualization, you can inspect them using visualization's built-in visualization features. For example, you can use a message converter to transform custom GPS messages into foxglove.LocationFix messages for visualization in the map panel. + +> Note: Message converters only run on-demand when panels subscribe to topics. + +### Links and Resources + +- Guide: Creating Message Converters +- Writing Message Converter Extensions (Map Panel) +- Writing Message Converter Extensions (3D Panel) + +## Topic Aliases + +Topic alias extensions allow you to alias topics from your data source to new topics. Visualization panels can subscribe to both aliased topics and topics from the original data source. + +## Writing Extensions + +You can write extensions using JavaScript or TypeScript and package them into `.coe` files. You can distribute these files privately within your organization or publicly through our registry (in development) - installing extensions through the registry is only supported in the desktop application. A single extension can contain multiple panels or converters. + +coScene provides a set of starter templates and commands in the [create-coscene-extension](https://github.com/coscene-io/create-coscene-extension) package to simplify extension writing. + +Requirements: + +- Node.js 14+ + +To set up your extension project, navigate to the directory where you want your source code to reside, and run the following command in a terminal window: + +``` +npm init coscene-extension@latest my-extension-name +``` + +This will set up the extension directory structure. Your extension entry point is the `index.ts` file. + +The entry point script must export an ExtensionModule — a function named `activate` that accepts a single `ExtensionContext` parameter. + +## API Reference + +- [ExtensionContext](/docs/viz/extensions/api/entry-point/extension-context) +- @coscene/coscene-extension diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/2-local-development.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/2-local-development.md new file mode 100644 index 000000000..47356df88 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/2-local-development.md @@ -0,0 +1,24 @@ +--- +sidebar_position: 2 +--- + +# Local Development + +Build and test your custom visualization extensions locally before publishing. + +## Installation + +To build and install your extension to the local coStudio extensions folder, run `npm run local-install`. This will create a folder under your user home directory (e.g., `~/.coStudio/extensions/unknown.myExtensionName-0.0.0`) containing your compiled extension. + +Open the latest version of the coStudio desktop application. You should now see `myExtensionName` in the list of installed extensions in the application settings. + +After installation, you should be able to open the "Add Panel" menu and see an option called `ExamplePanel`. You have successfully loaded your first visualization extension! + +(🏗️ Work in progress, expected to launch in May 2025) +To install local extensions on the web application, you must first package your extension, then drag and drop the `.coe` file onto an open visualization page. You can also open `.coe` files in the desktop application by dragging and dropping or double-clicking. + +## Development + +Every time you make changes to your extension, you must run `npm run local-install` to build it into the local extensions folder. + +Reload or restart coStudio to execute the latest version of your extension code in the application. Alternatively, you can simply run `npm run build` to confirm that your code compiles without installing it locally. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/1-using-message-converters-to-display-3d-markers-in-3d-panel.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/1-using-message-converters-to-display-3d-markers-in-3d-panel.md new file mode 100644 index 000000000..5a9f67efe --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/1-using-message-converters-to-display-3d-markers-in-3d-panel.md @@ -0,0 +1,162 @@ +--- +sidebar_position: 1 +--- + +# Using Message Converters to Display 3D Markers in 3D Panel + +By writing your own message converter, you can use coScene's existing panels to visualize your custom messages, even if these message definitions are not supported by the existing panels. + +## Why Use Message Converters + +While you could build a custom panel every time you want to visualize certain specific data, writing a message converter can save you a lot of time and effort. Message converters transform data into supported formats, allowing existing panels to handle the visualization without having to build another panel from scratch. + +## Our Goal + +We will create a message converter that transforms custom `my.Marker` messages into `foxglove.SceneUpdate` messages, then use the 3D panel to display these markers. You can download the [example mcap file](https://download.coscene.cn/assets/bags/example.mcap) for this tutorial. + +## Prerequisites + +Before we begin, you should be familiar with or have installed: + +- Basic robotics concepts +- Basic usage of coScene visualization features +- [Basic JavaScript/TypeScript syntax](https://www.typescriptlang.org/docs/handbook/basic-types.html) +- [Basic usage of frontend package managers like npm](https://docs.npmjs.com/) +- [Node.js version 14 or higher installed on your current device](https://nodejs.org/en/download/) + +## Initialize the Project + +Create a project using [create-coscene-extension](https://github.com/coscene-io/create-coscene-extension): + +```bash +npm init coscene-extension@latest mySceneUpdateConverter +``` + +This command will create a `mySceneUpdateConverter` directory containing some template source code. + +## Write the Converter + +src/index.ts is the entry point for the plugin source code. It exports an `activate` function that accepts a single parameter of type [`ExtensionContext`](/docs/viz/extensions/api/entry-point/extension-context). + +First, let's add the `@foxglove/schemas` package to our project. `@foxglove/schemas` is foxglove's schema definition library, where you can find all foxglove-supported schema definitions: + +```bash +npm install @foxglove/schemas +``` + +Then, open the `src/index.ts` file and import the following packages: + +```ts +// Import coScene's plugin context +import { ExtensionContext } from '@coscene/extension'; +// Import foxglove's schema definitions +import { CubePrimitive, SceneUpdate } from '@foxglove/schemas'; +// Import foxglove's time type definition +import { Time } from '@foxglove/schemas/schemas/typescript/Time'; +``` + +And declare our custom `my.Marker` message type: + +```ts +// Declare our custom `my.Marker` message type +type DetectedObject = { + position: [number, number, number]; + markerType: 'adult' | 'car' | 'truck'; + scale: [number, number, number]; + timestamp: Time; + frameId: string; +}; +``` + +To register the message converter, we need to call the `registerMessageConverter` function from `extensionContext`. The `registerMessageConverter` function requires three parameters: + +- fromSchemaName: The message type defined in mcap that needs to be converted +- toSchemaName: The target message type after conversion +- converter: The function that performs the conversion, which accepts the message registered in fromSchemaName. We need to convert the message to the type registered in toSchemaName + +```ts +// Register the message converter +export function activate(extensionContext: ExtensionContext) { + extensionContext.registerMessageConverter({ + fromSchemaName: 'my.Marker', + toSchemaName: 'foxglove.SceneUpdate', + converter: (inputMessage: DetectedObject): SceneUpdate => { + // Conversion logic from my.Marker to foxglove.SceneUpdate + }, + }); +} +``` + +Fill in the converter function to transform `my.Marker` messages into `foxglove.SceneUpdate` messages. We'll display all detected objects as colored cubes: + +- Blue for adults +- Red for cars +- Green for trucks + +```ts +converter: (inputMessage: DetectedObject): SceneUpdate => { + const { position, scale, markerType, timestamp, frameId } = inputMessage; + const colorMap = { + adult: { r: 0, g: 0, b: 1, a: 1 }, + car: { r: 1, g: 0, b: 0, a: 1 }, + truck: { r: 0, g: 1, b: 0, a: 1 }, + }; + + const cubePrimitive: CubePrimitive = { + pose: { + position: { x: position[0], y: position[1], z: position[2] }, + orientation: { x: 0, y: 0, z: 0, w: 1 }, + }, + size: { x: scale[0], y: scale[1], z: scale[2] }, + color: colorMap[markerType], + }; + + const sceneUpdateMessage = { + deletions: [], + entities: [ + { + id: 'detectedObjects-entities', + timestamp, + frame_id: frameId, + lifetime: { sec: 10, nsec: 0 }, + frame_locked: false, + metadata: [], + arrows: [], + cubes: [cubePrimitive], + spheres: [], + cylinders: [], + lines: [], + triangles: [], + texts: [], + models: [], + }, + ], + }; + + return sceneUpdateMessage; +}; +``` + +## Test the Plugin + +To build and install the plugin for local testing in coStudio, run the following command in the plugin directory: + +```bash +npm run local-install +``` + +In coStudio, open the plugin list on the right side, and you'll now see `mySceneUpdateConverter` in the list of installed plugins: +![extensionList](./img/extensionList.png) + +Now, open our example mcap file, and you can open the 3D panel to see all detected objects displayed as colored cubes: +![3dPanel](./img/3dPanel.png) + +## Share Your Plugin + +To share your plugin with others, you need to package it as a .coe file. To do this, run the following command in the plugin directory: + +```bash +npm run package +``` + +You'll find an `unknown.mySceneUpdateConverter-0.0.0.coe` file in the plugin directory. You can distribute this to others, and they can install it in their coStudio by dragging and dropping it. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/2-custom-panel.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/2-custom-panel.md new file mode 100644 index 000000000..f21687852 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/2-custom-panel.md @@ -0,0 +1,398 @@ +--- +sidebar_position: 2 +--- + +# Custom Panel + +By writing your own panel, you can have more flexible control over the panel's appearance and behavior to meet your specific needs. + +## Why Use Custom Panels + +Custom panels are very useful when existing panels don't support your visualization needs. You have complete control over the panel's appearance and behavior to meet your specific requirements. + +## Our Goal + +We will create a custom panel that simulates the original message panel, using [react-json-view](https://github.com/microlinkhq/react-json-view) to display the raw messages for the corresponding topic. + +## Before You Begin + +Before starting, you need to understand/install some basic concepts/environments: + +- Basic robotics concepts +- Basic usage of coScene visualization features +- [Basic JS/TS syntax](https://www.typescriptlang.org/docs/handbook/basic-types.html) +- [Basic React usage](https://react.dev/) +- [Basic usage of frontend package managers like npm](https://docs.npmjs.com/) +- [Node.js version 14 or higher installed on your current device](https://nodejs.org/en/download/) + +## Initialize Project + +Create a project using [create-coscene-extension](https://github.com/coscene-io/create-coscene-extension): + +```bash +npm init coscene-extension@latest custom-raw-message-panel +``` + +This command will create a `custom-raw-message-panel` directory containing some template source code. + +Then, we need to install some dependencies in our project: + +- `@microlink/react-json-view` is a React component for displaying JSON data +- `immer` is a JavaScript library for handling immutable state +- `lodash` is a well-known JavaScript utility library that provides many useful functions, including array operations, object operations, etc. + +```bash +npm install @microlink/react-json-view immer lodash +``` + +Then we open the `package.json` file and modify the `displayName` and `description` fields to `custom raw message panel`. The modified `package.json` file should look like this: + +```json +{ + "name": "custom-raw-message-panel", + "displayName": "custom raw message panel", + "description": "custom raw message panel", + ... +} +``` + +## Write Custom Panel + +Now open the `custom-raw-message-panel` folder in your chosen editor, then open the `src/index.ts` file. You'll see that the file already registers an example panel as `example-panel`. First, we need to change this example panel's name to `custom-raw-message-panel`. The modified `index.ts` file should look like this: + +```ts +import { ExtensionContext } from '@coscene/extension'; + +import { initExamplePanel } from './ExamplePanel'; + +export function activate(extensionContext: ExtensionContext): void { + extensionContext.registerPanel({ + name: 'custom-raw-message-panel', + initPanel: initExamplePanel, + }); +} +``` + +Then we open the `src/ExamplePanel.tsx` file. In the `src/ExamplePanel.tsx` file, you'll see a simple panel component. We need to first explain the code in this file, then modify it according to our needs. This file uses React's state management to track subscribed topics, messages, and their rendering state. + +```ts +function ExamplePanel({ context }: { context: PanelExtensionContext }): JSX.Element { + const [topics, setTopics] = useState(); + const [messages, setMessages] = useState[] | undefined>(); + + const [renderDone, setRenderDone] = useState<() => void | undefined>(); +``` + +In the example, when relevant updates are detected, the `onRender` event will run: + +```ts +useLayoutEffect(() => { + context.onRender = (renderState: RenderState, done) => { + setRenderDone(() => done); + setTopics(renderState.topics); + setMessages(renderState.currentFrame); + }; +}, [context]); +``` + +The onRender function receives the latest panel state: + +- `done` is a callback function after the new rendering is complete. When rendering is complete, you need to call the `done` function to indicate that the panel has completed the previous rendering cycle +- `renderState.topics` is the latest topic list +- `renderState.currentFrame` contains new messages for subscribed topics + +Next, use the `context.watch` function to tell the context which states need to be monitored. When the state changes, it will trigger the `onRender` event. `context.watch` is used to monitor key values in [`RenderState`](/docs/viz/extensions/api/custom-panels/render-state). You can view all monitorable key values from [`RenderState`](/docs/viz/extensions/api/custom-panels/render-state) + +```ts +context.onRender = (renderState: RenderState, done) => { + // ... +}; +// Tell the panel context we care about changes in the _topic_ field in RenderState +context.watch('topics'); +// Tell the panel context we want to subscribe to messages in the current frame +context.watch('currentFrame'); +``` + +Then we need to use the `context.subscribe` function to subscribe to the topic array. Messages from these topics will be populated into `renderState.currentFrame` + +```ts +context.subscribe(['/some/topic']); +``` + +Finally, when the panel finishes rendering, we need to call the `renderDone` function to indicate that the panel has completed the previous rendering cycle + +```ts +useEffect(() => { + renderDone?.(); +}, [renderDone]); +``` + +At the bottom of the function, we can see how to use all this logic to render a table of data source topics and schema names + +```ts +return ( +
+

Welcome to your new extension panel!

+ {/* ... */} + {(topics ?? []).map((topic) => ( + <> +
{topic.name}
+
{topic.datatype}
+ + ))} + {/* ... */} +
+); +``` + +According to our needs, in the settings we need to let users choose the topic to display, and let users choose the theme supported by `@microlink/react-json-view`, indentation, and whether to display data types. + +So we need to first define the TypeScript types for settings: State, and the themes supported by `@microlink/react-json-view` `ThemeOptions`. + +```ts +// Themes supported by @microlink/react-json-view +const ThemeOptions = [ + 'apathy', + 'apathy:inverted', + 'ashes', + 'bespin', + 'brewer', + 'bright:inverted', + 'bright', + 'chalk', + 'codeschool', + 'colors', + 'eighties', + 'embers', + 'flat', + 'google', + 'grayscale', + 'grayscale:inverted', + 'greenscreen', + 'harmonic', + 'hopscotch', + 'isotope', + 'marrakesh', + 'mocha', + 'monokai', + 'ocean', + 'paraiso', + 'pop', + 'railscasts', + 'rjv-default', + 'shapeshifter', + 'shapeshifter:inverted', + 'solarized', + 'summerfruit', + 'summerfruit:inverted', + 'threezerotwofour', + 'tomorrow', + 'tube', + 'twilight', +].map((key) => ({ value: key, label: key })); + +// This is the type we'll use when rendering the panel and persist to the layout. +type State = { + data: { + label: string; + topic?: string; + visible: boolean; + }; + appearance: { + displayDataTypes: boolean; + indentWidth: string; + theme: string; + }; +}; +``` + +Then we need to use React's `useState` to manage the settings state and declare a function to update the settings state. + +```ts +import { produce } from 'immer'; +import { set } from 'lodash'; + +// Build our panel state from the context's initialState, filling in any missing values. +const [state, setState] = useState(() => { + const partialState = context.initialState as Partial; + return { + data: { + label: partialState.data?.label ?? 'Data', + topic: partialState.data?.topic ?? '/pose', + visible: partialState.data?.visible ?? true, + }, + appearance: { + displayDataTypes: partialState.appearance?.displayDataTypes ?? true, + theme: partialState.appearance?.theme ?? 'rjv-default', + indentWidth: partialState.appearance?.indentWidth ?? '2', + }, + }; +}); + +// Update our state in response to edit operations from the settings panel. +const actionHandler = useCallback( + (action: SettingsTreeAction) => { + if (action.action === 'update') { + const { path, value } = action.payload; + + // We combine immer and lodash to generate a new state object, so React can re-render the panel. + // Since our data node contains label and visibility properties, this combination can automatically handle label editing and node visibility toggling, + // without needing to write special handling logic. + setState(produce((draft) => set(draft, path, value))); + + // If the topic is changed, update our subscription. + if (path[1] === 'topic') { + context.subscribe([{ topic: value as string }]); + } + } + }, + [context], +); +``` + +Next, we use `context.updatePanelSettingsEditor` to register settings in our panel, and when the settings state changes, use `context.saveState` to save the state to the layout. + +```ts +// Update the settings editor each time our state or available topic list changes. +useEffect(() => { + // Save current state to layout + context.saveState(state); + + const topicOptions = (topics ?? []).map((topic) => ({ value: topic.name, label: topic.name })); + + // We set up the settings tree to mirror the shape of our panel state, so we can use paths from the settings tree to directly update our state. + context.updatePanelSettingsEditor({ + actionHandler, + nodes: { + data: { + // Our label comes from the label in state, and will update to reflect changes in the state value. + label: state.data.label, + // Setting this to true allows users to edit this node's label. + renamable: true, + // A non-undefined value here allows users to toggle this node's visibility. + visible: state.data.visible, + icon: 'Cube', + fields: { + topic: { + label: 'Topic', + input: 'select', + options: topicOptions, + value: state.data.topic, + }, + }, + }, + appearance: { + label: 'Appearance', + icon: 'Shapes', + fields: { + theme: { + label: 'Theme', + input: 'select', + value: state.appearance.theme, + options: ThemeOptions, + }, + indentWidth: { + label: 'Indent Width', + input: 'select', + value: state.appearance.indentWidth, + options: [ + { value: '2', label: '2' }, + { value: '4', label: '4' }, + { value: '8', label: '8' }, + ], + }, + displayDataTypes: { + label: 'Display DataTypes', + input: 'boolean', + value: state.appearance.displayDataTypes, + }, + }, + }, + }, + }); +}, [context, actionHandler, state, topics]); +``` + +Then we need to make two small changes: + +- Check if `renderState.currentFrame` is undefined, if it is undefined, keep the data from the previous frame, don't clear the message. +- Listen to the topic set in settings during initialization + +```ts +useLayoutEffect(() => { + context.onRender = (renderState, done) => { + ... + + // If currentFrame is undefined, keep the data from the previous frame, don't clear the message. + if (renderState.currentFrame) { + setMessages(renderState.currentFrame); + } + }; + + // After adding the render handler, you must specify which fields in the render state (RenderState) will trigger updates. + // If you don't monitor any fields, the panel context will think you don't need any updates, so the panel won't render. + + // Tell the panel context we care about changes in the _topic_ field in RenderState + context.watch("topics"); + + // Tell the panel context we want to subscribe to messages in the current frame + context.watch("currentFrame"); + + // Subscribe to our initial topic + if (state.data.topic) { + context.subscribe([{ topic: state.data.topic }]); + } +}, [context, state.data.topic]); +``` + +Finally, just use `@microlink/react-json-view` to draw the corresponding messages in the `return`. + +```ts +return ( +
+

{state.data.topic ?? "Choose a topic in settings"}

+
+ +
+
+); +``` + +> You can find the complete code [here](https://github.com/coscene-io/create-coscene-extension/tree/main/examples/panel-settings) + +## Test Plugin + +To build and install the plugin for local testing in coStudio, run the following command in the plugin directory: + +```bash +npm run local-install +``` + +In coStudio, open the plugin list on the right side, and you'll now see `custom raw message panel` in the list of installed plugins: +![extensionList](./img/customRawMessageExtensionList.png) + +The panel list will also have a new `custom-raw-message-panel` panel. Add our panel and open any file, and you can use our custom `custom-raw-message-panel` panel: +![customRawMessagePanel](./img/customRawMessagePanelList.png) + +You can choose the topic you want to view in the settings and customize the panel's appearance to view messages for the corresponding topic in the panel: +![customRawMessagePanel](./img/customRawMessagePanel.png) + +## Share Your Plugin + +To share your plugin with others, you need to package it as a .coe file. To do this, run the following command in the plugin directory: + +```bash +npm run package +``` + +You'll find an `unknown.custom-raw-message-panel-0.0.0.coe` file in the plugin directory. You can distribute this to others, and they can install it in their coStudio instance by dragging and dropping it. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/_category_.json b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/_category_.json new file mode 100644 index 000000000..7c603b002 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Best Practices", + "position": 3, + "collapsible": true, + "link": { + "type": "generated-index", + "slug": "/category/extensions/best-practices" + } +} \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/3dPanel.png b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/3dPanel.png new file mode 100644 index 000000000..e4e02b663 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/3dPanel.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/customRawMessageExtensionList.png b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/customRawMessageExtensionList.png new file mode 100644 index 000000000..30a9c333f Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/customRawMessageExtensionList.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/customRawMessagePanel.png b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/customRawMessagePanel.png new file mode 100644 index 000000000..a47a8fa80 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/customRawMessagePanel.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/customRawMessagePanelList.png b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/customRawMessagePanelList.png new file mode 100644 index 000000000..afe153807 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/customRawMessagePanelList.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/extensionList.png b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/extensionList.png new file mode 100644 index 000000000..f083d125b Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/3-best-practices/img/extensionList.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/4-guides/1-create-custom-panel.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/4-guides/1-create-custom-panel.md new file mode 100644 index 000000000..340acab00 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/4-guides/1-create-custom-panel.md @@ -0,0 +1,59 @@ +--- +sidebar_position: 1 +--- + +# Create a Custom Panel + +Build a simple panel extension that subscribes to a topic, then register it so you can add it to your visualization layout. + +## Setup + +In your terminal window, `cd` to the directory where your source code resides, then run the following command: + +``` +npm init coscene-extension@latest myExtensionName +``` + +This will use create-coscene-extension to create a `myExtensionName` directory containing the source code for a sample custom panel. + +### `index.ts` + +**`index.ts` is the entry point for your extension source code.** + +It must export an `activate` function that: + +- **Accepts an `extensionContext` parameter** – For more information about the `ExtensionContext` type, see @coscene/extension +- **Registers the extension's panel** – In this case, `ExamplePanel` + +``` +export function activate(extensionContext: ExtensionContext) { + extensionContext.registerPanel({ name: "example-panel", initPanel: initExamplePanel }); +} +``` + +### `ExamplePanel.tsx` + +The panel file referenced in `index.ts` defines the behavior and UI of the custom panel your extension will install. + +While `ExamplePanel.tsx` is written in React, panels are framework-agnostic – meaning they can be written using DOM primitives, React, or any other frontend framework. See the custom-image-extension for an example panel not written in React. + +The `initPanel` function accepts a `PanelExtensionContext` parameter, which contains properties and methods for accessing panel data and rendering UI updates. It can also return an optional cleanup function that runs when the extension's `panelElement` is unmounted. + +### `PanelExtensionContext` + +For available properties and methods, see the PanelExtensionContext documentation. + +## Troubleshooting Memory Leaks + +Panels in visualization often process continuous data streams at 60 fps or higher. This processing can expose memory issues more quickly than in other "web apps." + +Memory or reference issues can quickly consume available memory and lead to out-of-memory (OOM) errors. When this happens, you'll see a tab crash page (in the web app) or a crash report page (in the desktop app). If you notice the entire app crashes more frequently when using your extension, your extension may have a memory leak. + +Here are some best practices for extensions to help prevent memory leaks: + +- Minimize references to past message data, or aggregate message data over time. +- When aggregating message data over time, always set a maximum limit on the amount of data stored. +- Dereference large objects or arrays that are no longer needed to ensure they are garbage collected. +- Avoid storing data in the global scope. + +If you encounter memory leak issues, please contact us via GitHub, Feishu, DingTalk, or other channels and provide your extension code. We are happy to help you debug the problem. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/4-guides/2-create-message-converter.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/4-guides/2-create-message-converter.md new file mode 100644 index 000000000..f9c5b08b7 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/4-guides/2-create-message-converter.md @@ -0,0 +1,79 @@ +--- +sidebar_position: 2 +--- + +# Create a Message Converter + +Build a simple message converter to transform custom GPS messages into messages conforming to the `foxglove.LocationFix` schema, so they can be visualized in the map panel of the visualization. + +## Setup + +In your terminal window, `cd` to the directory where your source code resides, then run the following command: + +``` +npm init coscene-extension@latest myExtensionName +``` + +This will use create-coscene-extension to create a `myExtensionName` directory containing the source code for a sample message converter. + +## Registering the Converter + +The `index.ts` file in your project's `src` folder is the entry point for your extension source code. It must export an `activate` function that accepts an `extensionContext` parameter of type ExtensionContext. + +To register a message converter, call `registerMessageConverter` on the `extensionContext` parameter, passing three arguments: the source schema type, the target schema type, and the actual `converter` function. + +``` +import { MessageEvent } from "@coscene/extension"; + +export function activate(extensionContext: ExtensionContext) { + extensionContext.registerMessageConverter({ + fromSchemaName: "...", + toSchemaName: "...", + converter: (inputMessage: MyInputType, messageEvent: MessageEvent) => { + // ... + }, + }); +} +``` + +The `converter` function accepts two arguments – the input topic message and the full message event. The message event can be used to access other relevant information, such as the message's `publishTime`, `receiveTime`, and `topic` name. + +## Writing the Converter + +Suppose our data contains GPS messages of type `sensors.MyGps`, which include `lat` and `lon` fields. + +``` +type MyGps = { + lat: number; + lon: number; +}; +``` + +To visualize GPS coordinates, the map panel requires messages in the foxglove.LocationFix format. In short, our converter needs to transform `MyGps` messages into messages conforming to the `foxglove.LocationFix` schema. + +First, specify the _from_ schema (`sensors.MyGps`) and the _to_ schema (`foxglove.LocationFix`) to inform the visualization that the converter we register will convert `sensors.MyGps` messages into `foxglove.LocationFix` messages. + +Then, write the `converter` function. In our example, we remap the `lat` and `lon` fields to the `latitude` and `longitude` fields expected by the `foxglove.LocationFix` schema: + +``` +export function activate(extensionContext: ExtensionContext) { + extensionContext.registerMessageConverter({ + fromSchemaName: "sensors.MyGps", + toSchemaName: "foxglove.LocationFix", + converter: (myGps: MyGps, messageEvent: MessageEvent) => { + return { + latitude: myGps.lat, + longitude: myGps.lon, + }; + }, + }); +} +``` + +## Testing + +Once you have packaged and installed the extension, load any data source containing `sensors.MyGps` messages in the visualization, and visualize them in the map panel or raw message panel by clicking the schema dropdown and selecting the output schema you returned as `toSchema`. + +Note + +Message converters only run on-demand when panels subscribe to topics. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/4-guides/3-optimize-extension-performance.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/4-guides/3-optimize-extension-performance.md new file mode 100644 index 000000000..fe0bb5c5e --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/4-guides/3-optimize-extension-performance.md @@ -0,0 +1,45 @@ +--- +sidebar_position: 3 +--- + +# Optimize Extension Performance + +Optimize your extension to improve performance in production and reduce load times. + +## Combine Multiple Extensions + +Combining multiple extensions that share code or dependencies can reduce file size, speed up installation, and decrease load times when the application starts. + +A single extension's `activate` function can call multiple registration functions to add different features: + +```typescript +export function activate(extensionContext: ExtensionContext) { + extensionContext.registerPanel({ name: 'my-panel', initPanel: initCustomPanel }); + extensionContext.registerPanel({ name: 'my-other-panel', initPanel: initAnotherCustomPanel }); + extensionContext.registerMessageConverter({ + fromSchemaName: '...', + toSchemaName: '...', + converter: (inputMessage: MyInputType, messageEvent: MessageEvent) => { + // ... + }, + }); + extensionContext.registerTopicAliases((args) => { + // ... + }); +} +``` + +## Disable Source Maps + +By default, extensions are bundled with source maps to improve the debugging experience. However, source maps take up extra space and may slow down extension installation and load times. + +If your extension is getting large, consider disabling source maps by adding a file named `config.ts` with the following content: + +```typescript +module.exports = { + webpack: (config) => { + config.devtool = undefined; // Disable source maps to reduce bundle size + return config; + }, +}; +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/1-introduction.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/1-introduction.md new file mode 100644 index 000000000..d9a995401 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/1-introduction.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 1 +--- + +# coScene Extension API + +`@coscene/extension` contains the type definitions required to write coScene extensions. + +See [Extension Introduction](../introduction) for more information. + +## Getting Started + +Your extension's default export must be an `ExtensionModule`. When the extension is loaded, the `activate` function will be called, and you can use the functionality of `ExtensionContext`. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/2-entry-point/1-extension-context.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/2-entry-point/1-extension-context.md new file mode 100644 index 000000000..30bc0a433 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/2-entry-point/1-extension-context.md @@ -0,0 +1,91 @@ +--- +sidebar_position: 1 +--- + +# ExtensionContext + +The first parameter of the `activate` function is `ExtensionContext` — this context allows you to extend the visualization to support custom workflows. + +```typescript +export function activate(extensionContext: ExtensionContext) { + // ... call methods on extensionContext to extend the visualization +} +``` + +## Methods + +### registerPanel() + +```typescript +registerPanel(params): void +``` + +`registerPanel` adds a new panel to the visualization interface. To register a panel, you need to provide a `name` and an `initPanel` function. + +The `initPanel` function accepts a `PanelExtensionContext` parameter, which contains properties and methods for accessing panel data and rendering UI updates. It also returns an optional cleanup function that runs when the extension `panelElement` is unmounted. + +For more information, see the [Creating Custom Panels](/docs/viz/extensions/guides/create-custom-panel) guide. + +#### Parameters + +| Parameter | Type | +| --------- | ------------------------------------------------------------------------------------------------- | +| params | [ExtensionPanelRegistration](/docs/viz/extensions/api/custom-panels/extension-panel-registration) | + +#### Returns + +`void` + +--- + +### registerMessageConverter() + +```typescript +registerMessageConverter(args): void +``` + +`registerMessageConverter` registers a function to convert messages from one schema to another. + +Message converters allow you to leverage the visualization's built-in visualization panels by converting messages to formats that match the schemas supported by the visualization — for example, you can convert custom GPS messages to `foxglove.LocationFix` messages for visualization in the map panel. + +The converter function runs on the original message and outputs the converted message whenever a panel subscribes to a topic using the `convertTo` option. The converted message is then provided to the panel. If the function returns `undefined`, the output is ignored and no message is provided to the panel. This is useful when you want to selectively output converted messages based on the content of the input message. + +For more information, see the [Creating Message Converters](/docs/viz/extensions/guides/create-message-converter) guide. + +#### Type Parameters + +| Type Parameter | +| -------------- | +| `Src` | + +#### Parameters + +| Parameter | Type | +| --------- | ------------------------------------------------------------------------------------------------------------ | +| args | [RegisterMessageConverterArgs](/docs/viz/extensions/api/custom-panels/extension-panel-registration)`\` | + +#### Returns + +`void` + +--- + +### registerTopicAliases() + +```typescript +registerTopicAliases(aliasFunction): void +``` + +`registerTopicAliases` registers a function to compute topic aliases. The provided alias function should accept a parameter containing two fields — `topics` (containing the data source's original topics) and `globalVariables` (containing the current layout's variables) — and return a list of alias topics. + +Your alias function runs whenever the data source topics or variables change. Any aliases it returns are added to the data source topics (replacing any previously returned aliases) and can be used for subscriptions or in message paths just like real topics. + +#### Parameters + +| Parameter | Type | +| ------------- | --------------------------------------------------------------------------------- | +| aliasFunction | [TopicAliasFunction](/docs/viz/extensions/api/topic-aliases/topic-alias-function) | + +#### Returns + +`void` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/2-entry-point/2-extension-module.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/2-entry-point/2-extension-module.md new file mode 100644 index 000000000..e076b2dae --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/2-entry-point/2-extension-module.md @@ -0,0 +1,42 @@ +--- +sidebar_position: 2 +--- + +# ExtensionModule + +ExtensionModule describes the interface that your extension module must export. This typically corresponds to your `index.ts` file. + +You can use either the `default` export or named export syntax: + +```typescript +export function activate(context: ExtensionContext) { + // ... call methods on extensionContext to extend Foxglove +} +``` + +```typescript +function activate(context: ExtensionContext) { + // ... call methods on extensionContext to extend Foxglove +} +export default { activate }; +``` + +## Properties + +### activate() + +```typescript +activate: (extensionContext) => void; +``` + +This function will be called when your extension is loaded. Within this function, you can register your custom panels or other types of extension functionality. + +#### Parameters + +| Parameter | Type | +| ---------------- | -------------------------------------------------------------------------- | +| extensionContext | [ExtensionContext](/docs/viz/extensions/api/entry-point/extension-context) | + +#### Return Value + +`void` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/2-entry-point/_category_.json b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/2-entry-point/_category_.json new file mode 100644 index 000000000..c3c190e12 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/2-entry-point/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Entry Point", + "position": 2, + "collapsible": true, + "link": { + "type": "generated-index", + "slug": "/category/extensions/entry-point" + } +} \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/1-extension-panel-registration.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/1-extension-panel-registration.md new file mode 100644 index 000000000..015193a81 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/1-extension-panel-registration.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 1 +--- + +# ExtensionPanelRegistration + +```typescript +type ExtensionPanelRegistration = object; +``` + +This type represents the parameter you pass to `ExtensionContext.registerPanel`. + +## Properties + +### name + +```typescript +name: string; +``` + +The unique name of the panel in your extension. + +**Note**: Panel names must be unique within your extension. The panel name is used to identify the panel in layouts. Changing the panel name will cause layouts using the old name to be unable to load your panel. + +### initPanel() + +```typescript +initPanel: (context) => void | () => void; +``` + +This function is called when your panel is initialized. + +#### Parameters + +| Parameter | Type | +| --------- | ------------------------------------------------------- | +| context | [PanelExtensionContext](./3-panel-extension-context.md) | + +#### Return Value + +`void` | () => `void` + +(Optional) A function that will be called when the panel is removed or replaced. Perform any cleanup logic here to gracefully dismantle your panel. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/10-settings-tree-fields.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/10-settings-tree-fields.md new file mode 100644 index 000000000..47c61b630 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/10-settings-tree-fields.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 10 +--- + +# SettingsTreeFields + +```typescript +type SettingsTreeFields = Record; +``` + +A map of field names to SettingsTreeField objects. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/11-settings-tree-field-value.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/11-settings-tree-field-value.md new file mode 100644 index 000000000..d035447b7 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/11-settings-tree-field-value.md @@ -0,0 +1,216 @@ +--- +sidebar_position: 11 +--- + +# SettingsTreeFieldValue + +```typescript +type SettingsTreeFieldValue = object; +``` + +SettingsTreeFieldValue represents the value and input type of a settings field. The exact object properties depend on the input type. + +## Boolean Input + +```typescript +{ + input: 'boolean'; + value: boolean; +} +``` + +A checkbox input that can be either true or false. + +## Number Input + +```typescript +{ + input: "number"; + value: number; + min?: number; + max?: number; + step?: number; + precision?: number; +} +``` + +A numeric input field. + +| Property | Description | +| --------- | ------------------------------------------------- | +| min | Optional minimum value | +| max | Optional maximum value | +| step | Optional step size when incrementing/decrementing | +| precision | Optional number of decimal places to display | + +## Select Input + +```typescript +{ + input: 'select'; + value: string | number | boolean; + options: { + value: string | number | boolean; + label: string; + } + []; +} +``` + +A dropdown select input with predefined options. + +## String Input + +```typescript +{ + input: "string"; + value: string; + placeholder?: string; +} +``` + +A single-line text input field. + +| Property | Description | +| ----------- | ------------------------- | +| placeholder | Optional placeholder text | + +## Text Input + +```typescript +{ + input: "text"; + value: string; + placeholder?: string; + rows?: number; +} +``` + +A multi-line text input field. + +| Property | Description | +| ----------- | ---------------------------------- | +| placeholder | Optional placeholder text | +| rows | Optional number of rows to display | + +## Toggle Input + +```typescript +{ + input: 'toggle'; + value: string | number; + options: { + value: string | number; + label: string; + } + []; +} +``` + +A set of toggle buttons with predefined options. + +## Vec2 Input + +```typescript +{ + input: "vec2"; + value: [number, number]; + labels?: [string, string]; + min?: number | [number, number]; + max?: number | [number, number]; + step?: number | [number, number]; + precision?: number | [number, number]; +} +``` + +An input for a 2D vector. + +| Property | Description | +| --------- | -------------------------------------------- | +| labels | Optional labels for each component | +| min | Optional minimum value(s) | +| max | Optional maximum value(s) | +| step | Optional step size(s) | +| precision | Optional number of decimal places to display | + +## Vec3 Input + +```typescript +{ + input: "vec3"; + value: [number, number, number]; + labels?: [string, string, string]; + min?: number | [number, number, number]; + max?: number | [number, number, number]; + step?: number | [number, number, number]; + precision?: number | [number, number, number]; +} +``` + +An input for a 3D vector. + +| Property | Description | +| --------- | -------------------------------------------- | +| labels | Optional labels for each component | +| min | Optional minimum value(s) | +| max | Optional maximum value(s) | +| step | Optional step size(s) | +| precision | Optional number of decimal places to display | + +## RGB Input + +```typescript +{ + input: 'rgb'; + value: [number, number, number]; +} +``` + +A color picker for RGB values (red, green, blue). Values range from 0 to 1. + +## RGBA Input + +```typescript +{ + input: 'rgba'; + value: [number, number, number, number]; +} +``` + +A color picker for RGBA values (red, green, blue, alpha). Values range from 0 to 1. + +## MessagePath Input + +```typescript +{ + input: "message-path"; + value: string; + validTypes?: readonly string[]; + supportDatasets?: boolean; +} +``` + +An input for selecting a message path. + +| Property | Description | +| --------------- | ------------------------------------- | +| validTypes | Optional array of valid message types | +| supportDatasets | Optional flag to enable dataset paths | + +## Autocomplete Input + +```typescript +{ + input: "autocomplete"; + value: string; + items: string[]; + placeholder?: string; +} +``` + +A text input with autocompletion suggestions. + +| Property | Description | +| ----------- | --------------------------------- | +| items | Array of autocomplete suggestions | +| placeholder | Optional placeholder text | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/12-settings-tree-node.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/12-settings-tree-node.md new file mode 100644 index 000000000..e87c8a777 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/12-settings-tree-node.md @@ -0,0 +1,154 @@ +--- +sidebar_position: 12 +--- + +# SettingsTreeNode + +```typescript +type SettingsTreeNode = object; +``` + +SettingsTreeNode represents a node in a settings tree. Nodes can contain fields and child nodes. + +## Properties + +### label + +```typescript +label: string; +``` + +The label displayed for the node. + +### children? + +```typescript +optional children: SettingsTreeChildren; +``` + +Child nodes of this node. + +### fields? + +```typescript +optional fields: SettingsTreeFields; +``` + +Fields contained in this node. + +### defaultExpansionState? + +```typescript +optional defaultExpansionState: "collapsed" | "expanded"; +``` + +The default expansion state of the node. + +### error? + +```typescript +optional error: string; +``` + +Error message to display if there's an issue with the node. + +### visible? + +```typescript +optional visible: boolean; +``` + +Whether the node is visible in the UI. + +### renamable? + +```typescript +optional renamable: boolean; +``` + +Whether the node can be renamed by the user. + +### actions? + +```typescript +optional actions: SettingsTreeNodeAction[]; +``` + +Actions that can be performed on the node, displayed as buttons. + +### handler? + +```typescript +optional handler: (action: SettingsTreeNodeAction) => void; +``` + +Handler for node actions. + +## Example + +```typescript +const node: SettingsTreeNode = { + label: 'Camera Settings', + fields: { + fov: { + label: 'Field of View', + input: 'number', + value: 60, + min: 10, + max: 120, + }, + near: { + label: 'Near Clip', + input: 'number', + value: 0.1, + }, + far: { + label: 'Far Clip', + input: 'number', + value: 1000, + }, + }, + children: { + advanced: { + label: 'Advanced', + defaultExpansionState: 'collapsed', + fields: { + antialiasing: { + label: 'Anti-aliasing', + input: 'select', + value: 'msaa', + options: [ + { value: 'none', label: 'None' }, + { value: 'fxaa', label: 'FXAA' }, + { value: 'msaa', label: 'MSAA' }, + ], + }, + }, + }, + }, +}; +``` + +--- + +### order? + +```typescript +optional order: number | string; +``` + +Optional sorting order used to override natural object ordering. All nodes with a sort order will be rendered before nodes without a sort order. + +Nodes without an explicit order will be sorted according to ECMA object sorting rules. + +https://262.ecma-international.org/6.0/#sec-ordinary-object-internal-methods-and-internal-slots-ownpropertykeys + +--- + +### enableVisibilityFilter? + +```typescript +optional enableVisibilityFilter: boolean; +``` + +Filter child nodes by visibility state. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/13-settings-tree-node-action.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/13-settings-tree-node-action.md new file mode 100644 index 000000000..34096ec41 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/13-settings-tree-node-action.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 13 +--- + +# SettingsTreeNodeAction + +```typescript +type SettingsTreeNodeAction = object; +``` + +SettingsTreeNodeAction represents an action that can be performed on a node in a settings tree. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/14-settings-tree-node-action-divider.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/14-settings-tree-node-action-divider.md new file mode 100644 index 000000000..0748cbf95 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/14-settings-tree-node-action-divider.md @@ -0,0 +1,21 @@ +--- +sidebar_position: 14 +--- + +# SettingsTreeNodeActionDivider + +```typescript +type SettingsTreeNodeActionDivider = { + type: 'divider'; +}; +``` + +SettingsTreeNodeActionDivider represents a visual divider in a node action menu. + +## 属性 + +### type + +```typescript +type: 'divider'; +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/15-settings-tree-node-action-item.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/15-settings-tree-node-action-item.md new file mode 100644 index 000000000..11fddd4de --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/15-settings-tree-node-action-item.md @@ -0,0 +1,59 @@ +--- +sidebar_position: 15 +--- + +# SettingsTreeNodeActionItem + +```typescript +type SettingsTreeNodeActionItem = { + type: 'action'; + id: string; + label: string; + icon?: SettingsIcon; + tooltip?: string; +}; +``` + +SettingsTreeNodeActionItem represents an action item in a node action menu. + +## Properties + +### type + +```typescript +type: 'action'; +``` + +The type of the action item. + +### id + +```typescript +id: string; +``` + +The unique identifier for the action. + +### label + +```typescript +label: string; +``` + +The label displayed for the action. + +### icon? + +```typescript +optional icon: SettingsIcon; +``` + +The icon to display for the action. + +### tooltip? + +```typescript +optional tooltip: string; +``` + +The tooltip to display when hovering over the action. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/16-subscribe-message-range-args.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/16-subscribe-message-range-args.md new file mode 100644 index 000000000..f62a07417 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/16-subscribe-message-range-args.md @@ -0,0 +1,133 @@ +--- +sidebar_position: 16 +--- + +# SubscribeMessageRangeArgs + +```typescript +type SubscribeMessageRangeArgs = object; +``` + +This type represents the arguments passed to PanelExtensionContext.subscribeMessageRange. + +## Properties + +### topic + +```typescript +topic: string; +``` + +The topic to subscribe to. + +### convertTo? + +```typescript +optional convertTo: string; +``` + +Convert messages to this schema before passing to the subscriber. + +Subscribed MessageEvents will contain the converted message and an `originalMessageEvent` field containing the original message event. If no `convertTo` schema is specified, no message converter will be used. If there is no message converter from the original schema to the `convertTo` schema, no messages will be passed for this subscription. + +### preload? + +```typescript +optional preload: boolean; +``` + +If true, data will begin loading immediately, even before the iterator is accessed. Default is false. + +### start? + +```typescript +optional start: Time; +``` + +The start time for the subscription range. If not provided, it will use the beginning of the data source. + +### end? + +```typescript +optional end: Time; +``` + +The end time for the subscription range. If not provided, it will use the end of the data source. + +## Functions + +### onNewRangeIterator() + +```typescript +onNewRangeIterator: (itemIterator: AsyncIterableIterator<Range<MessageEvent>>) => void; +``` + +`onNewRangeIterator` is a function that receives an async iterable when message data is available on the subscription. + +To read messages, your function should iterate through the provided async iterable. Each item from the iterable is a batch of message events for the subscribed topic. These batches and messages are ordered by _log time_. The iterator will end when there are no more messages to read. + +```typescript +async function onNewRangeIterator(batchIterator) { + for await (const batch of batchIterator) { + //... + } +} +``` + +`onNewRangeIterator` will be called again when upstream topic data changes. For example, when a user script changes for a user script output topic subscription, or when an alias changes for an alias topic subscription. When topic data changes, the previous iterator will end, and its data is no longer valid. When `onNewRangeIterator` is called, you should discard previously received data. + +If your `onNewRangeIterator` function throws an error, the iterator will end, and you will not receive any more messages until `onNewRangeIterator` is called again. Your error will be shown in the problems sidebar for the user to see. + +#### Parameters + +| Parameter | Type | +| ------------ | ------------------------------------------------------ | +| itemIterator | AsyncIterableIterator<Range<MessageEvent>> | + +#### Returns + +`void` + +## Example + +```typescript +function ExampleSubscription(context) { + // Subscribe to a specific topic's message range + const unsubscribe = context.subscribeMessageRange({ + topic: '/robot/sensors/imu', + start: { sec: 10, nsec: 0 }, + end: { sec: 20, nsec: 0 }, + onNewRangeIterator: async (iterator) => { + // Process message ranges as they come in + for await (const range of iterator) { + for (const message of range.items) { + console.log('Received message:', message); + } + } + }, + }); + + // Later, you can unsubscribe when done + // unsubscribe(); +} +``` + +### ~~onReset()?~~ + +```typescript +optional onReset: (batchIterator) => Promise; +``` + +#### Parameters + +| Parameter | Type | +| ------------- | ------------------------------------------------------------------------ | +| batchIterator | AsyncIterable of Array of MessageEvent objects (using Immutable wrapper) | + +#### Returns + +`Promise` + +#### Deprecated + +This method has been renamed. Use `onNewRangeIterator` instead. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/17-subscription.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/17-subscription.md new file mode 100644 index 000000000..954f43ead --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/17-subscription.md @@ -0,0 +1,75 @@ +--- +sidebar_position: 17 +--- + +# Subscription + +```typescript +type Subscription = object; +``` + +A Subscription represents a connection to a data source for receiving messages on a specific topic. + +## Methods + +### unsubscribe() + +```typescript +unsubscribe(): void +``` + +Unsubscribes from the topic, stopping the flow of messages. + +#### Returns + +`void` + +## Example + +```typescript +// Subscribe to a topic +const subscription = context.subscribe(['/robot/status']); + +// Later, unsubscribe when you no longer need the data +subscription.unsubscribe(); +``` + +## Remarks + +Subscriptions are created using the `PanelExtensionContext.subscribe()` method. The returned subscription object can be used to unsubscribe when the panel no longer needs to receive updates on that topic. + +Make sure to unsubscribe from topics when your panel is unmounted or when you no longer need the data to avoid memory leaks and unnecessary processing. + +## Properties + +### topic + +```typescript +topic: string; +``` + +--- + +### convertTo? + +```typescript +optional convertTo: string; +``` + +If a topic has an additional schema name, specifying the schema name will use the registered message converter to convert messages on that topic to the convertTo schema. The MessageEvents for this subscription will include the converted message and an originalMessageEvent field containing the original message event. + +--- + +### ~~preload?~~ + +```typescript +optional preload: boolean; +``` + +Setting preload to _true_ hints to the data source that it should attempt to load all available messages for the topic. The default behavior is to only load messages for the current frame. + +**Only** topics with `preload: true` can be used in the `allFrames` render state. + +#### Deprecated + +Please use `PanelExtensionContext.subscribeMessageRange` instead. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/2-layout-actions.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/2-layout-actions.md new file mode 100644 index 000000000..071a439ec --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/2-layout-actions.md @@ -0,0 +1,110 @@ +--- +sidebar_position: 2 +--- + +# LayoutActions + +```typescript +type LayoutActions = object; +``` + +The LayoutActions interface provides methods for interacting with the current layout. + +## Methods + +### setSelectedPanels() + +```typescript +setSelectedPanels(panelIds): void +``` + +Sets the currently selected panels. + +#### Parameters + +| Parameter | Type | +| --------- | ----------------- | +| panelIds | readonly string[] | + +#### Returns + +`void` + +--- + +### getCurrentLayoutActions() + +```typescript +getCurrentLayoutActions(type): any[] | undefined +``` + +Gets the available actions for the current layout type. + +#### Parameters + +| Parameter | Type | +| --------- | ------ | +| type | string | + +#### Returns + +`any[] | undefined` + +--- + +### callCurrentLayoutAction() + +```typescript +callCurrentLayoutAction(type, actionId, payload): void +``` + +Calls an action for the current layout type. + +#### Parameters + +| Parameter | Type | +| --------- | ------ | +| type | string | +| actionId | string | +| payload | any | + +#### Returns + +`void` + +### addPanel() + +```typescript +addPanel(params): void +``` + +Use `context.layout.addPanel` to add a new panel next to the current panel. + +The value of `position` must be set to `"sibling"`. + +The value of `type` can reference a panel in a custom extension in the format `extensionname.panelname`, where `extensionname` is the extension name in `package.json`, and `panelname` is the name provided when registering the panel in the extension. + +`getState` is set to a function that returns the state of the new panel (also known as panel settings), or returns `undefined` to use the default settings of the new panel. + +```typescript +// Add a new panel +context.layout.addPanel({ + position: 'sibling', + type: 'MyExtension.MyPanel', + getState: () => ({}), +}); +``` + +#### Parameters + +| Parameter | Type | Description | +| ---------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| params | \{ position: "sibling"; type: string; updateIfExists: boolean; getState: unknown; \} | - | +| params.position | "sibling" | The position of the panel. Currently only "sibling" is supported, indicating that the new panel will be adjacent to the calling panel. | +| params.type | string | The type of panel to open. For extension panels, the format is "extensionName.panelName", where extensionName is the name field in the extension package.json, and panelName is the name provided to registerPanel(). | +| params.updateIfExists? | boolean | Whether to update an existing adjacent panel of the same type. If false or omitted, a new panel will always be added. (**Deprecated** This parameter currently only supports built-in panels.) | +| params.getState | - | - | + +#### Returns + +`void` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/3-panel-extension-context.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/3-panel-extension-context.md new file mode 100644 index 000000000..c492426cf --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/3-panel-extension-context.md @@ -0,0 +1,666 @@ +--- +sidebar_position: 3 +--- + +# PanelExtensionContext + +```typescript +type PanelExtensionContext = object; +``` + +`PanelExtensionContext` exposes properties and methods used for writing custom panels. The context provides methods for subscribing to messages, receiving updates, configuring panel settings, and rendering the panel to the UI. + +The `initPanel` function used in `registerPanel` accepts a `PanelExtensionContext` parameter. This parameter contains properties and methods for accessing panel data and rendering UI updates. The `initPanel` function can also return an optional cleanup function that runs when the extension's `panelElement` unmounts. + +For detailed information, see the [Creating Custom Panels Guide](../../../../category/extensions/custom-panels). + +## Properties + +### panelElement + +```typescript +readonly panelElement: HTMLDivElement; +``` + +The root element of the panel. Add panel elements as children to this element. + +--- + +### initialState + +```typescript +readonly initialState: unknown; +``` + +The initial panel state. + +--- + +### layout + +```typescript +readonly layout: LayoutActions; +``` + +Actions that the panel can perform related to the user's current layout. See [LayoutActions](./2-layout-actions.md) for details. + +--- + +### dataSourceProfile? + +```typescript +readonly optional dataSourceProfile: string; +``` + +Identifies the semantics of the data being played, such as which topics or parameters are semantically meaningful, or which normalization conventions are used. This typically maps to a shorthand identifier for a robotics framework like "ros1", "ros2", or "ulog". See [MCAP profiles concept](https://mcap.dev/spec/registry#well-known-profiles) for details. + +--- + +### onRender()? + +```typescript +optional onRender: (renderState, done) => void; +``` + +Set this property to a function during panel initialization. + +The visualization will run `context.onRender` when it needs to re-render the panel during playback. The function accepts `renderState` and `done` callback as parameters. Render events occur frequently (60hz, 30hz, etc.). + +**Note**: Your `onRender` function **must** call `done` after rendering to indicate the panel is ready to render the next set of data. The exact placement of the `done` call will vary by framework and the logic of different extensions. + +```typescript +context.onRender = (renderState, done) => { + // Render UI updates using fields from RenderState + + // Call done when you have rendered all UI for this renderState. + // If your UI framework delays rendering, call done after the rendering has actually occurred. + done(); +}; +``` + +#### Parameters + +| Parameter | Type | +| ----------- | --------------------------------------------------------------------------------------------- | +| renderState | [Immutable](../6-other/2-immutable.md)\<[RenderState](../3-custom-panels/4-render-state.md)\> | +| done | () => void | + +#### Returns + +`void` + +--- + +### subscribeMessageRange()? + +```typescript +optional subscribeMessageRange: (args) => () => void; +``` + +Subscribe to receive messages for the entire time range of the given topic in the current data source. + +See [SubscribeMessageRangeArgs](../3-custom-panels/16-subscribe-message-range-args.md) for details on behavior. + +Note: This does not read messages from live sources like foxglove_bridge, rosbridge, or ROS 1 native connections. For those messages, you still need to use `context.subscribe()` and `watch("currentFrame")`. + +#### Parameters + +| Parameter | Type | +| --------- | ---------------------------------------------------------------------------------- | +| args | [SubscribeMessageRangeArgs](../3-custom-panels/16-subscribe-message-range-args.md) | + +#### Returns + +`Function` + +A function that will unsubscribe from the topic, cancel the active async iterator, and prevent onNewRangeIterator from being called again. + +##### Returns + +`void` + +--- + +### ~~UNSTABLE_subscribeMessageRange()?~~ + +```typescript +optional UNSTABLE_subscribeMessageRange: (args) => () => void; +``` + +#### Parameters + +| Parameter | Type | +| --------- | ---------------------------------------------------------------------------------- | +| args | [SubscribeMessageRangeArgs](../3-custom-panels/16-subscribe-message-range-args.md) | + +#### Returns + +`Function` + +##### Returns + +`void` + +#### Deprecated + +Renamed to `subscribeMessageRange`. Please use that method instead. + +## Methods + +### watch() + +#### Call Signature + +```typescript +watch(field): void +``` + +Subscribe to updates for this field in the render state. It will only be called when this field changes. + +Use `context.watch` to indicate which fields in the RenderState (such as `currentFrame`, `currentTime`, `previewTime`, `parameters`, `topics`) should trigger panel re-rendering when their values change. + +```typescript +context.watch('topics'); +context.watch('currentFrame'); +context.watch('parameters'); +context.watch('currentTime'); +``` + +##### Parameters + +| Parameter | Type | +| --------- | --------------------------------------------------------- | +| field | keyof [RenderState](../3-custom-panels/4-render-state.md) | + +##### Returns + +`void` + +#### Call Signature + +```typescript +watch(field): void +``` + +Subscribe to updates for this field in the render state. It will only be called when this field changes. + +##### Parameters + +| Parameter | Type | +| --------- | ----------- | +| field | "allFrames" | + +##### Returns + +`void` + +##### Deprecated + +Calling `watch` with `allFrames` is deprecated. Please use PanelExtensionContext.subscribeMessageRange instead. + +--- + +### saveState() + +```typescript +saveState(state): void +``` + +Use `context.saveState` to persist any object as panel settings (also called panel settings) in the current layout. + +```typescript +context.initialState = undefined; // The initial state of the panel + +context.saveState({ myNum: 2, myBool: false, myStr: 'abc' }); +``` + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------------------ | ---------------------------------------------------------- | +| state | Partial\ | The state to save. This value should be JSON serializable. | + +##### Returns + +`void` + +--- + +### setParameter() + +```typescript +setParameter(name, value): void +``` + +Use `context.setParameter` to set the parameter `name` to any valid `value` (i.e., basic types, dates, `Uint8Array`, and arrays or objects containing these values). + +```typescript +context.setParameter('/param1', 'value1'); +``` + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------------------- | --------------------------------- | +| name | string | The name of the parameter to set. | +| value | [ParameterValue](../6-other/4-parameter-value.md) | The new value of the parameter. | + +##### Returns + +`void` + +--- + +### setSharedPanelState() + +```typescript +setSharedPanelState(state): void +``` + +Set temporary state shared by the same type of panel calling this function. This will not be saved in the layout. + +##### Parameters + +| Parameter | Type | +| --------- | -------------------------------------- | +| state | undefined \| Record\ | + +##### Returns + +`void` + +--- + +### setVariable() + +```typescript +setVariable(name, value): void +``` + +Use `context.setVariable` to set the variable `name` to any valid variable `value`. + +```typescript +context.setVariable('myVar', 55); + +context.onRender = (renderState: RenderState, done) => { + // Read variable values from renderState + const variableValues = renderState.variables; + const myVarValue = variableValues.myVar; + + // Call done when you have rendered all UI for this renderState. + // If your UI framework delays rendering, call done after the rendering has actually occurred. + done(); +}; +``` + +##### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------------------------------- | -------------------------------- | +| name | string | The name of the variable to set. | +| value | [VariableValue](../6-other/8-variable-value.md) | The new value of the variable. | + +##### Returns + +`void` + +--- + +### setPreviewTime() + +```typescript +setPreviewTime(time): void +``` + +Set active preview time. Setting preview time to undefined will clear the preview time. + +##### Parameters + +| Parameter | Type | +| --------- | ------------------- | +| time | undefined \| number | + +##### Returns + +`void` + +--- + +### seekPlayback()? + +```typescript +optional seekPlayback(time): void +``` + +Move playback to the given time. The behavior is like the user clicking the play bar to seek. + +##### Parameters + +| Parameter | Type | +| --------- | ------ | +| time | number | + +##### Returns + +`void` + +--- + +### subscribe() + +```typescript +subscribe(topic, options): () => void +``` + +Use `context.subscribe` to subscribe to a topic to receive messages. Returns an unsubscribe function that will be called when messages are no longer needed. + +```typescript +const unsubscribe = context.subscribe('/my_topic', { + preload: true, +}); + +// Unsubscribe later +unsubscribe(); +``` + +##### Parameters + +| Parameter | Type | Description | +| --------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| topic | string | The name of the topic to subscribe to. | +| options | [SubscribeOptions](../3-custom-panels/17-subscription.md) \| undefined | Subscription options. For more information, see [SubscribeOptions](../3-custom-panels/17-subscription.md). | + +##### Returns + +`Function` + +A function that will unsubscribe from the topic when called. + +--- + +### unsubscribeAll() + +```typescript +unsubscribeAll(): void +``` + +Unsubscribe from all topics. + +```typescript +context.unsubscribeAll(); +``` + +##### Returns + +`void` + +--- + +### subscribeAppSettings() + +```typescript +subscribeAppSettings(): () => void +``` + +Use `context.subscribeAppSettings` to subscribe to application settings updates. Returns an unsubscribe function that will be called when settings updates are no longer needed. + +```typescript +const unsubscribe = context.subscribeAppSettings(); + +// Unsubscribe later +unsubscribe(); +``` + +##### Returns + +`Function` + +A function that will unsubscribe from application settings updates when called. + +--- + +### advertise()? + +```typescript +optional advertise(topic, datatype, options): void +``` + +Use `context.advertise` to publish messages on a topic. This must be called before using `context.publish` to publish messages. + +```typescript +context.advertise('/my_topic', 'std_msgs/String'); +``` + +##### Parameters + +| Parameter | Type | Description | +| ---------- | ------------------------- | ------------------------------------------------------------------------ | +| topic | string | The name of the topic to publish messages on. | +| schemaName | string | The name of the pattern the published messages will follow. | +| options | Record\ | Options to pass to the current data source for additional configuration. | + +##### Returns + +`void` + +--- + +### unadvertise()? + +```typescript +optional unadvertise(topic): void +``` + +Indicates that you no longer want to publish on this topic. + +```typescript +context.unadvertise('/my_image_topic'); +``` + +If the current data source does not support publishing, this property may be `undefined`. + +##### Parameters + +| Parameter | Type | +| --------- | ------ | +| topic | string | + +##### Returns + +`void` + +--- + +### publish()? + +```typescript +optional publish(topic, message): void +``` + +Use `context.publish` to publish messages on a topic that has been previously published. (You must first call advertise to publish the topic before you can publish.) If the topic has not been published or is otherwise incorrectly formatted, the function will throw an error. + +```typescript +context.advertise('/my_color_topic', 'std_msgs/ColorRGBA'); +context.publish('/my_color_topic', { r: 0, g: 1, b: 0, a: 1 }); +``` + +If the current data source does not support publishing, this property may be `undefined`. + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------- | --------------------------------------------- | +| topic | string | The name of the topic to publish messages on. | +| message | unknown | The message to publish. | + +##### Returns + +`void` + +--- + +### callService()? + +```typescript +optional callService(service, request): Promise +``` + +Use `context.callService` to send a service call to the specified `service` with a request payload. + +```typescript +context.callService('my_service', { foo: 'bar' }); +``` + +If the current data source does not support services, this property may be `undefined`. + +##### Parameters + +| Parameter | Type | Description | +| --------- | ------- | ----------------------------------------- | +| service | string | The name of the service to call. | +| request | unknown | The request payload for the service call. | + +##### Returns + +`Promise`\<`unknown`\> + +A Promise that resolves when the result is available or rejects if an error occurs + +--- + +### updatePanelSettingsEditor() + +```typescript +updatePanelSettingsEditor(settings): void +``` + +Call the `updatePanelSettingsEditor` method on the PanelExtensionContext instance to define or update its settings. + +```typescript +const panelSettings: SettingsTree = { + nodes: { ... }, + actionHandler: (action: SettingsTreeAction) => { ... } +}; + +context.updatePanelSettingsEditor(panelSettings); +``` + +`settings` parameter must be a valid SettingsTree and must contain 2 required properties – `nodes` and `actionHandler`: + +- `nodes` - A hierarchy where each node can contain input fields, display fields, or even other nodes +- `actionHandler` - A function that will be called when a user interacts with the settings UI; it contains logic to handle interactions and update the panel or settings tree + +It can also contain the following optional properties: + +- `enableFilter` – A boolean to set whether a filter control should be displayed +- `focusedPath` – A node to scroll to and highlight in the editor (temporary one-time effect) + +The following example tree has a `title` text input field within the `General` section, and an `actionHandler` to respond to updates to the `title` field. + +```typescript +const panelSettings: SettingsTree = { + nodes: { + general: { + label: 'General', + fields: { + title: { + label: 'Title', + input: 'string', + // `panelTitle` refers to the value in the panel configuration + value: panelTitle, + }, + }, + }, + }, + actionHandler: (action: SettingsTreeAction) => { + switch (action.action) { + case 'perform-node-action': + // Handle user actions defined for nodes in the settings tree + break; + case 'update': + if (action.payload.path[0] === 'general' && action.payload.path[1] === 'title') { + // Read action.payload.value for the new panel title value + panelTitle = action.payload.value; + + // Update panel state accordingly + } + break; + } + }, +}; + +context.updatePanelSettingsEditor(panelSettings); +``` + +#### `SettingsTreeAction` + +SettingsTreeAction describes how the settings UI should update when a user interacts with a field. + +Each `SettingsTreeAction` has a `payload` with a `path` pointing to the field to be updated (e.g., `["general", "title"]`). + +The `update` operation corresponds to a user setting a new value for a field (e.g., "My new title"). + +#### Special Node Attributes + +There are two special SettingsTreeNode attributes, `label` and `visibility`. The value you specify for `label` will control the label displayed in the settings editor. If you set the `renamable` node attribute to `true`, users can edit the node `label` – you will receive an `update` `SettingsTreeAction` with a path ending in `label`. + +Also, if you specify a boolean for the node `visibility`, the settings editor will provide a button to toggle the node's visibility, and you will receive an `update` operation with a path ending in `visibility`. + +For examples of how to use these special attributes, see the panel settings example extension. + +#### Input Types + +In addition to the `string` input type in the above example, the panel API provides multiple types for extending panel input fields. + +Each input type has different properties you can configure: + +- `autocomplete` +- `boolean` +- `rgb` +- `rgba` +- `gradient` +- `messagepath` +- `select` +- `string` +- `toggle` +- `vec3` +- `vec2` + +#### Parameters + +| Parameter | Type | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| settings | \{ actionHandler: (action) => void; enableFilter: boolean; focusedPath: readonly string\[\]; nodes: \{\}; \} | - | +| settings.actionHandler | (action) => void | The handler for all operations on the settings tree initiated by the UI. | +| settings.enableFilter? | boolean | If the settings editor should display a filter control, then true. | +| settings.focusedPath? | readonly string\[\] | This will have a one-time effect, scrolling the editor to the node at the path and highlighting it. This is a temporary effect, so it does not need to be subsequently un-set. | +| settings.nodes | {} | The root node of the settings tree. Updates to these will automatically reflect in the editor UI. | + +#### Returns + +`void` + +--- + +### setDefaultPanelTitle() + +```typescript +setDefaultPanelTitle(defaultTitle): void +``` + +Use `context.setDefaultPanelTitle` to override the default title of the panel. Users can always override the default title manually. If no override is set or the default title, the panel will only display its type (e.g., "Image"). + +```typescript +// Override default panel title +context.setDefaultPanelTitle(`Plot of ${config.topicName}`); +``` + +##### Parameters + +| Parameter | Type | +| ------------ | ------------------- | +| defaultTitle | undefined \| string | + +##### Returns + +`void` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/4-render-state.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/4-render-state.md new file mode 100644 index 000000000..8e1763553 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/4-render-state.md @@ -0,0 +1,151 @@ +--- +sidebar_position: 4 +--- + +# RenderState + +```typescript +type RenderState = object; +``` + +RenderState is the information passed to a panel's `onRender` function. + +To receive updates for specific parts of the RenderState, you must first call the `watch` function and specify the field name. For example, call `watch("currentTime")` to receive updates for `currentTime`. + +If a field is missing from the RenderState, it could be because the value hasn't changed since the last `onRender` call, or you haven't called `watch` for that field. + +## Properties + +### currentFrame? + +```typescript +optional currentFrame: MessageEvent[]; +``` + +The latest messages for the current render frame. These are new messages since the previous render frame. + +--- + +### didSeek? + +```typescript +optional didSeek: boolean; +``` + +True if the data source performed a seek operation. This indicates that some data may have been skipped (never appeared in `currentFrame`), so the panel should clear any stale state to avoid displaying incorrect data. + +--- + +### ~~allFrames?~~ + +```typescript +optional allFrames: MessageEvent[]; +``` + +All available messages. Lists all available messages when possible. + +#### Deprecated + +Please use PanelExtensionContext.subscribeMessageRange instead. + +--- + +### parameters? + +```typescript +optional parameters: Map; +``` + +A map of current parameter values. Parameters are key/value pairs associated with a data source, and may not be supported by all data sources. For example, ROS 1 live connections support parameters via the parameter server. + +--- + +### sharedPanelState? + +```typescript +optional sharedPanelState: Record; +``` + +Temporary panel state shared between panels of the same type. This can be any data that panel authors wish to share between panels. + +--- + +### variables? + +```typescript +optional variables: Map; +``` + +A map of current Studio variables. Variables are key/value pairs that are globally accessible by panels and scripts in the current layout. + +--- + +### topics? + +```typescript +optional topics: Topic[]; +``` + +A list of available topics. This list includes both subscribed and unsubscribed topics. + +--- + +### currentTime? + +```typescript +optional currentTime: Time; +``` + +A timestamp value representing the current playback time. + +--- + +### startTime? + +```typescript +optional startTime: Time; +``` + +The starting timestamp of the current data source playback range. For offline files, this value is expected to be present. For live connections, the start time may or may not be present depending on the data source. + +--- + +### endTime? + +```typescript +optional endTime: Time; +``` + +The ending timestamp of the current data source playback range. For offline files, this value is expected to be present. For live connections, the end time may or may not be present depending on the data source. + +--- + +### previewTime? + +```typescript +optional previewTime: number; +``` + +A value in seconds representing the preview time. Preview time is set when a user hovers over the seek bar or when a panel explicitly sets the preview time. The preview time is a value in seconds within the playback range. + +For example, a chart panel might set the preview time when the user hovers over the chart, signaling to other panels where the user is currently hovering and allowing them to render accordingly. + +--- + +### colorScheme? + +```typescript +optional colorScheme: "dark" | "light"; +``` + +The color scheme currently used throughout the application. + +--- + +### appSettings? + +```typescript +optional appSettings: Map; +``` + +Application settings. This will only include key/values subscribed to with @PanelExtensionContext.subscribeAppSettings. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/5-settings-icon.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/5-settings-icon.md new file mode 100644 index 000000000..34f051c35 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/5-settings-icon.md @@ -0,0 +1,69 @@ +--- +sidebar_position: 5 +--- + +# SettingsIcon + +```typescript +type SettingsIcon = string; +``` + +SettingsIcon is a string that specifies an icon to use for a settings field. The icon will be rendered next to the field's label. + +## Values + +The following named icons are available: + +- ArrowDown +- ArrowLeft +- ArrowRight +- ArrowUp +- Bug +- Cancel +- Close +- Database +- DragIndicator +- Error +- ErrorOutline +- Expand +- Flag +- Font +- Gauge +- Global +- Grid +- Group +- Help +- Image +- Info +- Label +- LinkOff +- Locate +- Maximize +- Minimize +- Pin +- PinOff +- Place +- Publish +- Redo +- Relate +- Reset +- Settings +- Share +- Spline +- SplitHorizontal +- SplitVertical +- Telescope +- TimeFormat +- Timeline +- Translate +- Undo +- Warning +- XS + +## Remarks + +Additionally, base64-encoded PNG or SVG data URLs can be used. For example: + +``` +"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHN0cm9rZT0iY3VycmVudENvbG9yIiBmaWxsPSJjdXJyZW50Q29sb3IiIHN0cm9rZS13aWR0aD0iMCIgdmlld0JveD0iMCAwIDI0IDI0IiBoZWlnaHQ9IjFlbSIgd2lkdGg9IjFlbSI+CiAgPGNpcmNsZSBjeD0iMTIiIGN5PSIxMiIgcj0iOCIgLz4KPC9zdmc+Cg==" +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/6-settings-tree.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/6-settings-tree.md new file mode 100644 index 000000000..10cfa4b55 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/6-settings-tree.md @@ -0,0 +1,94 @@ +--- +sidebar_position: 6 +--- + +# SettingsTree + +```typescript +type SettingsTree = { + actionHandler: (action: SettingsTreeAction) => void; + nodes: Record; +}; +``` + +SettingsTree is a data structure used to define panel settings. + +## Properties + +### actionHandler + +```typescript +actionHandler: (action: SettingsTreeAction) => void; +``` + +The action handler is called when a user interacts with a settings field, such as changing a value or clicking a button. + +#### Parameters + +| Parameter | Type | +| --------- | ------------------------------------------------- | +| action | [SettingsTreeAction](./7-settings-tree-action.md) | + +#### Returns + +`void` + +--- + +### nodes + +```typescript +nodes: Record; +``` + +A map of settings tree node IDs to nodes. Each node represents a group of related settings. + +## Example + +```typescript +const settingsTree: SettingsTree = { + nodes: { + general: { + label: 'General', + fields: { + displayMode: { + label: 'Display Mode', + input: 'select', + options: [ + { label: 'Auto', value: 'auto' }, + { label: 'Light', value: 'light' }, + { label: 'Dark', value: 'dark' }, + ], + value: 'auto', + }, + showLabels: { + label: 'Show Labels', + input: 'boolean', + value: true, + }, + }, + }, + advanced: { + label: 'Advanced', + fields: { + maxPoints: { + label: 'Maximum Points', + input: 'number', + value: 100, + min: 1, + max: 1000, + step: 1, + }, + }, + }, + }, + actionHandler: (action) => { + // Handle settings changes + if (action.action === 'update') { + // Update panel state based on the changed settings + const { path, value } = action.payload; + console.log(`Setting ${path.join('.')} changed to ${value}`); + } + }, +}; +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/7-settings-tree-action.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/7-settings-tree-action.md new file mode 100644 index 000000000..fb402c205 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/7-settings-tree-action.md @@ -0,0 +1,38 @@ +--- +sidebar_position: 7 +--- + +# SettingsTreeAction + +```typescript +type SettingsTreeAction = object; +``` + +SettingsTreeAction represents an action that can be performed on a settings tree. + +## Update + +```typescript +{ + action: "update"; + payload: { + path: string[]; + value: SettingsTreeFieldValue; + }; +} +``` + +The update action is triggered when a user changes the value of a settings field. + +## Call + +```typescript +{ + action: "call"; + payload: { + path: string[]; + }; +} +``` + +The call action is triggered when a user clicks a button in the settings tree. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/8-settings-tree-children.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/8-settings-tree-children.md new file mode 100644 index 000000000..33479d995 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/8-settings-tree-children.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 8 +--- + +# SettingsTreeChildren + +```typescript +type SettingsTreeChildren = Record; +``` + +A map of child node names to SettingsTreeNode objects. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/9-settings-tree-field.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/9-settings-tree-field.md new file mode 100644 index 000000000..deda24884 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/9-settings-tree-field.md @@ -0,0 +1,80 @@ +--- +sidebar_position: 9 +--- + +# SettingsTreeField + +```typescript +type SettingsTreeField = object; +``` + +SettingsTreeField represents a field in a settings tree. Each field has a specific input type, such as text, number, or boolean. + +## Properties + +### label + +```typescript +label: string; +``` + +The label displayed for the field. + +### input + +```typescript +input: 'boolean' | + 'number' | + 'select' | + 'string' | + 'text' | + 'toggle' | + 'vec2' | + 'vec3' | + 'rgb' | + 'rgba' | + 'message-path' | + 'autocomplete'; +``` + +The type of input control to display for the field. + +### help? + +```typescript +optional help: string; +``` + +Help text to display alongside the field. + +### error? + +```typescript +optional error: string; +``` + +Error message to display if the field value is invalid. + +### disabled? + +```typescript +optional disabled: boolean; +``` + +Whether the field is disabled and cannot be edited. + +### hidden? + +```typescript +optional hidden: boolean; +``` + +Whether the field is hidden from view. + +### icon? + +```typescript +optional icon: SettingsIcon; +``` + +The icon to display alongside the field label. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/_category_.json b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/_category_.json similarity index 53% rename from i18n/en/docusaurus-plugin-content-docs/current/viz/_category_.json rename to i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/_category_.json index 95b243a0f..b57cf61f3 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/viz/_category_.json +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/3-custom-panels/_category_.json @@ -1,9 +1,9 @@ { - "label": "可视化", + "label": "Custom Panels", "position": 3, "collapsible": true, "link": { "type": "generated-index", - "slug": "/category/viz" + "slug": "/category/extensions/custom-panels" } -} +} \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/4-message-converters/1-register-message-converter-args.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/4-message-converters/1-register-message-converter-args.md new file mode 100644 index 000000000..56a8bfda7 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/4-message-converters/1-register-message-converter-args.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 1 +title: RegisterMessageConverterArgs +--- + +# RegisterMessageConverterArgs\ + +```typescript +type RegisterMessageConverterArgs = object; +``` + +This type represents the parameters passed to `ExtensionContext.registerMessageConverter`. + +## Type Parameters + +| Type Parameter | +| -------------- | +| Src | + +## Properties + +### fromSchemaName + +```typescript +fromSchemaName: string; +``` + +--- + +### toSchemaName + +```typescript +toSchemaName: string; +``` + +--- + +### converter() + +```typescript +converter: (msg, event) =\> unknown; +``` + +#### Parameters + +| Parameter | Type | +| --------- | ---------------------------------------------------------------------------------------------- | +| msg | Src | +| event | [Immutable](../6-other/2-immutable.md)\<[MessageEvent](../6-other/3-message-event.md)\\> | + +#### Returns + +`unknown` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/4-message-converters/_category_.json b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/4-message-converters/_category_.json new file mode 100644 index 000000000..a0a830bbb --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/4-message-converters/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Message Converters", + "position": 4, + "collapsible": true, + "link": { + "type": "generated-index", + "slug": "/category/extensions/message-converters" + } +} \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/1-base-topic.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/1-base-topic.md new file mode 100644 index 000000000..cfa2a5f45 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/1-base-topic.md @@ -0,0 +1,25 @@ +--- +sidebar_position: 1 +--- + +# BaseTopic + +```typescript +type BaseTopic = object; +``` + +## Properties + +### name + +```typescript +name: string; +``` + +--- + +### schemaName? + +```typescript +optional schemaName: string; +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/2-topic-alias.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/2-topic-alias.md new file mode 100644 index 000000000..220d5d0e6 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/2-topic-alias.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 2 +--- + +# TopicAlias + +```typescript +type TopicAlias = object; +``` + +## Properties + +### name + +```typescript +name: string; +``` + +### sourceTopicName + +```typescript +sourceTopicName: string; +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/3-topic-alias-function.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/3-topic-alias-function.md new file mode 100644 index 000000000..db6b5898e --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/3-topic-alias-function.md @@ -0,0 +1,21 @@ +--- +sidebar_position: 3 +--- + +# TopicAliasFunction() + +```typescript +type TopicAliasFunction = (args) => TopicAlias[]; +``` + +TopicAliasFunction receives a data source topic and variable list, and outputs a list of alias topics. Register this function using ExtensionContext.registerTopicAliases. + +## Parameters + +| Parameter | Type | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| args | [Immutable](../6-other/2-immutable.md)\<\{ topics: [BaseTopic](./1-base-topic.md)[]; globalVariables: Readonly\\>; \}\> | + +## Return Value + +[TopicAlias](./2-topic-alias.md)[] diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/_category_.json b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/_category_.json new file mode 100644 index 000000000..e3f279fb8 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/5-topic-aliases/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Topic Aliases", + "position": 5, + "collapsible": true, + "link": { + "type": "generated-index", + "slug": "/category/extensions/topic-aliases" + } +} \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/1-app-setting-value.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/1-app-setting-value.md new file mode 100644 index 000000000..c68f85c25 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/1-app-setting-value.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +--- + +# AppSettingValue + +```typescript +type AppSettingValue = string | number | boolean | undefined; +``` + +The valid types for application settings. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/2-immutable.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/2-immutable.md new file mode 100644 index 000000000..17fb18854 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/2-immutable.md @@ -0,0 +1,16 @@ +--- +sidebar_position: 2 +title: Immutable +--- + +# Immutable\ + +```typescript +type Immutable = Type extends Exclude ? Type : Type extends Map ? ReadonlyMap, Immutable> : Type extends ReadonlyMap ? ReadonlyMap, Immutable> : Type extends WeakMap ? WeakMap, Immutable> : Type extends Set ? ReadonlySet> : Type extends ReadonlySet ? ReadonlySet> : Type extends WeakSet ? WeakSet> : Type extends Promise ? Promise> : Type extends AnyArray ? Type extends IsTuple<...> ? { readonly [Key in (...)]: (...) } : ReadonlyArray<...> : Type extends object ? { readonly [Key in (...)]: (...) } : ... extends ... ? ... : ...; +``` + +## Type Parameters + +| Type Parameter | +| -------------- | +| `Type` | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/3-message-event.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/3-message-event.md new file mode 100644 index 000000000..11f013c3c --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/3-message-event.md @@ -0,0 +1,90 @@ +--- +sidebar_position: 3 +title: MessageEvent +--- + +# MessageEvent\ + +```typescript +type MessageEvent = object; +``` + +MessageEvent represents a single message and its metadata. + +Remember to import MessageEvent from `@coscene/extension`. This is different from the DOM MessageEvent class. + +## Type Parameters + +| Type Parameter | Default Type | +| -------------- | ------------ | +| T | unknown | + +## Properties + +### topic + +```typescript +topic: string; +``` + +The name of the topic on which this message was received, e.g. "/some/topic" + +--- + +### schemaName + +```typescript +schemaName: string; +``` + +schemaName is the identifier for the message schema in the message event. + +--- + +### receiveTime + +```typescript +receiveTime: Time; +``` + +The time (in nanoseconds) at which this message was received. This may be set by the local system clock or by the data source, depending on the data source being used and whether time is being simulated via a /clock topic or similar mechanism. Timestamps are typically nanoseconds since the UNIX epoch, but may be relative to another event (such as system start time or simulation start time) depending on context. + +--- + +### publishTime? + +```typescript +optional publishTime: Time; +``` + +The time (in nanoseconds) at which this message was originally published. This is only available in some data sources. Timestamps are typically nanoseconds since the UNIX epoch, but may be relative to another event (such as system start time or simulation start time) depending on context. + +--- + +### message + +```typescript +message: T; +``` + +The deserialized message as a JavaScript object. + +--- + +### sizeInBytes + +```typescript +sizeInBytes: number; +``` + +The approximate size of this message event in its deserialized form. This is useful for statistics tracking and cache eviction. + +--- + +### originalMessageEvent? + +```typescript +optional originalMessageEvent: MessageEvent; +``` + +When subscribing to a topic with a `convertTo` option, the message event's `message` contains the converted message, and the `originalMessageEvent` field contains the original unconverted message event. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/4-parameter-value.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/4-parameter-value.md new file mode 100644 index 000000000..bafdc5541 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/4-parameter-value.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 4 +--- + +# ParameterValue + +```typescript +type ParameterValue = undefined | boolean | number | string | Date | Uint8Array | ParameterValue[] | {}; +``` + +The valid types for parameter data (e.g. rosparams). diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/5-time.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/5-time.md new file mode 100644 index 000000000..5ef0c5dcb --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/5-time.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 5 +--- + +# Time + +```typescript +type Time = object; +``` + +A timestamp with nanosecond precision. + +Timestamps are typically nanoseconds since the UNIX epoch, but may be relative to another event (such as system start time or simulation start time) depending on context. + +## Properties + +### sec + +```typescript +sec: number; +``` + +--- + +### nsec + +```typescript +nsec: number; +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/6-topic.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/6-topic.md new file mode 100644 index 000000000..0588e0bdc --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/6-topic.md @@ -0,0 +1,49 @@ +--- +sidebar_position: 6 +--- + +# Topic + +```typescript +type Topic = object; +``` + +A named message channel. + +## Properties + +### name + +```typescript +name: string; +``` + +The name of the topic, e.g. "/some/topic" + +### ~~datatype~~ + +```typescript +datatype: string; +``` + +#### Deprecated + +Renamed to `schemaName`. `datatype` will be removed in a future version. + +### schemaName + +```typescript +schemaName: string; +``` + +The schema name is the identifier for the message type on this topic. Typically this is the fully qualified name of the message schema. The fully qualified name depends on the data source and the data loaded by the data source. + +For example, `package.Message` in protobuf class serialization or `pkg/Msg` in ROS systems. + +### convertibleTo? + +```typescript +optional convertibleTo: readonly string[]; +``` + +List any other schema names that the topic subscribers may be interested in. When subscribing to a topic, the panel can use the Subscription.convertTo option to request message auto-conversion from schemaName to one of the schemas in convertibleTo. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/7-variable-struct.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/7-variable-struct.md new file mode 100644 index 000000000..c8d2421fc --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/7-variable-struct.md @@ -0,0 +1,15 @@ +--- +sidebar_position: 7 +--- + +# VariableStruct + +```typescript +type VariableStruct = object; +``` + +## Index Signature + +```typescript +[key: string]: VariableValue +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/8-variable-value.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/8-variable-value.md new file mode 100644 index 000000000..3acf2f772 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/8-variable-value.md @@ -0,0 +1,9 @@ +--- +sidebar_position: 8 +--- + +# VariableValue + +```typescript +type VariableValue = undefined | boolean | number | string | VariableValue[] | {}; +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/_category_.json b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/_category_.json new file mode 100644 index 000000000..e8f29f070 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/6-other/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Other", + "position": 6, + "collapsible": true, + "link": { + "type": "generated-index", + "slug": "/category/extensions/other" + } +} \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/_category_.json b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/_category_.json new file mode 100644 index 000000000..d5591b4c1 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/8-extensions/5-api/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "API Reference", + "position": 5, + "collapsible": true, + "link": { + "type": "generated-index", + "slug": "/category/extensions/api" + } +} \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/_category_.json b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/_category_.json new file mode 100644 index 000000000..3773ea288 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Message Schemas", + "position": 9, + "collapsible": true, + "link": { + "type": "generated-index", + "slug": "/viz/message-schemas" + } +} \ No newline at end of file diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/arrow-primitive.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/arrow-primitive.md new file mode 100644 index 000000000..92203c486 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/arrow-primitive.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 3 +title: ArrowPrimitive +--- + +# Primitive Representing an Arrow + +`ArrowPrimitive` is a primitive that represents an arrow. + +## Parent Schema + +`ArrowPrimitive` appears in the [`SceneEntity`](./scene-entity) message schema. + +## Schema Definition + +| Field | Type | Description | +| ---------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `pose` | [`Pose`](./pose) | Position of the arrow tail and orientation of the arrow. Unit orientation means the arrow points in the +x direction. | +| `shaft_length` | [`float64`](./built-in%20types#float64) | Length of the arrow shaft | +| `shaft_diameter` | [`float64`](./built-in%20types#float64) | Diameter of the arrow shaft | +| `head_length` | [`float64`](./built-in%20types#float64) | Length of the arrow head | +| `head_diameter` | [`float64`](./built-in%20types#float64) | Diameter of the arrow head | +| `color` | [`Color`](./color) | Color of the arrow | + +## References + +coScene's schema types are framework-independent and can be implemented using any supported message encoding format. +| Encoding Format | Schema Name | +|------|--------------------------------| +| ROS 1 | [`foxglove_msgs/ArrowPrimitive`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/ArrowPrimitive.msg) | +| ROS 2 | [`foxglove_msgs/msg/ArrowPrimitive`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/ArrowPrimitive.msg)| +| JSON | [`foxglove.ArrowPrimitive`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/ArrowPrimitive.json) | +| Protobuf | [`foxglove.ArrowPrimitive`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/ArrowPrimitive.proto) | +| FlatBuffers | [`foxglove.ArrowPrimitive`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/ArrowPrimitive.fbs) | +|OMG IDL | [`foxglove::ArrowPrimitive`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/ArrowPrimitive.idl) | + +> **Note**: You must use the schema names specified above for coScene to recognize them correctly. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/built-in types.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/built-in types.md new file mode 100644 index 000000000..21d8407d9 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/built-in types.md @@ -0,0 +1,60 @@ +--- +sidebar_position: 2 +title: Built-in Types +--- + +# Built-in Types + +Built-in types are the building blocks of coScene's message schemas. + +Each field in a message has a type. This type can be another message schema type, an enum, or one of the following built-in types: + +### `boolean` + +A boolean value, which can be `true` or `false`. + +### `bytes` + +Raw binary data, represented as a `Uint8Array` in JavaScript. + +### `enum` + +An enum, which is a set of named constants. + +### `float64` + +A 64-bit floating-point number. + +### `string` + +A string value encoded in UTF-8. + +### `time` + +| Field | Type | Required | Description | +| ------ | ------ | -------- | ---------------------------- | +| `sec` | uint32 | ✓ | Seconds since the Unix epoch | +| `nsec` | uint32 | ✓ | Additional nanoseconds | + +> **Note**: + +coScene's Protobuf schema uses [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) to represent the `time` type, with fields `seconds` and `nanos`. However, in [user scripts](/), [message converters](/), and other parts of coScene, the values will be represented as `sec` and `nsec` fields to maintain consistency with other data formats. + +### `duration` + +| Field | Type | Required | Description | +| ----- | ------ | -------- | ----------------------------- | +| sec | int32 | ✓ | Seconds offset | +| nsec | uint32 | ✓ | Additional nanoseconds offset | + +> **Note**: + +coScene's Protobuf schema uses [`google.protobuf.Duration`](https://protobuf.dev/reference/protobuf/google.protobuf/#duration) to represent the `duration` type, with fields `seconds` and `nanos`. However, in [user scripts](/), [message converters](/), and other parts of coScene, the values will be represented as `sec` and `nsec` fields to maintain consistency with other data formats. + +### `uint32` + +A non-negative integer ranging from `0` to `4294967295` (2^32 - 1). + +### `int32` + +An integer ranging from `-2147483648` (2^31) to `2147483647` (2^31 - 1). diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/camera-calibration.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/camera-calibration.md new file mode 100644 index 000000000..4709e15a2 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/camera-calibration.md @@ -0,0 +1,88 @@ +--- +sidebar_position: 4 +title: CameraCalibration +--- + +# CameraCalibration + +## Panel Support + +`CameraCalibration` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Field Definitions + +| Field Name | Type | Description | +| ------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `timestamp` | [`time`](./built-in%20types#time) | Timestamp of the calibration data | +| `frame_id` | [`string`](./built-in%20types#string) | Reference coordinate system of the camera. The origin of this coordinate system is the optical center of the camera, with +x pointing to the right in the image, +y pointing down, and +z pointing into the image plane. | +| `width` | [`uint32`](./built-in%20types#uint32) | Image width | +| `height` | [`uint32`](./built-in%20types#uint32) | Image height | +| `distortion_model` | [`string`](./built-in%20types#string) | Distortion model name | +| `D` | [`float64[]`](./built-in%20types#float64) | Distortion parameters | +| `K` | [`float64[9]`](./built-in%20types#float64) | Intrinsic matrix (3x3 row-major storage) | +| `R` | [`float64[9]`](./built-in%20types#float64) | Rectification matrix (only used for stereo cameras, 3x3 row-major storage) | +| `P` | [`float64[12]`](./built-in%20types#float64) | Projection/camera matrix (3x4 row-major storage) | + +### `distortion_model` + +- `plumb_bob`: Parameters are k1, k2, p1, p2, k3 +- `rational_polynomial`: Parameters are k1, k2, p1, p2, k3, k4, k5, k6 + +This model is based on [OpenCV's](https://docs.opencv.org/2.4/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html) [pinhole camera model](https://en.wikipedia.org/wiki/Distortion_%28optics%29#Software_correction) and is consistent with [the implementation in ROS](https://docs.ros.org/en/diamondback/api/image_geometry/html/c++/pinhole__camera__model_8cpp_source.html). + +### `K` Intrinsic Matrix + +K is a 3x3 row-major matrix for the original (uncorrected) image. + +It uses the focal lengths (fx, fy) and principal point (cx, cy) to project 3D points in the camera coordinate system to 2D pixel coordinates. + +``` + [fx 0 cx] +K = [ 0 fy cy] + [ 0 0 1] +``` + +### `R` Rectification Matrix + +Rotation matrix that aligns the camera coordinate system with the ideal stereo image plane, making epipolar lines in the two stereo images parallel. + +### `P` Projection Matrix + +``` + [fx' 0 cx' Tx] +P = [ 0 fy' cy' Ty] + [ 0 0 1 0] +``` + +This matrix specifies the intrinsic (camera) matrix of the processed (rectified) image. That is, the left 3x3 part is the normal camera intrinsic matrix for the rectified image. + +It uses the focal lengths (fx', fy') and principal point (cx', cy') to project 3D points in the camera coordinate system to 2D pixel coordinates — these may differ from the values in K. + +For a monocular camera: Tx = Ty = 0, and typically R is the identity matrix with P[1:3,1:3] = K. + +For a stereo pair, the fourth column [Tx Ty 0]' relates to the position of the optical center of the second camera in the coordinate system of the first camera. We assume Tz = 0 so that the two cameras are in the same stereo image plane. Tx is always 0 and Ty = 0 for the first camera. For the right (second) camera of a horizontal stereo pair, Ty = 0 and Tx = -fx' \* B, where B is the baseline between the cameras. + +Given a 3D point [X Y Z]', the projection (x, y) of the point on the rectified image is calculated as: + +``` +[u v w]' = P * [X Y Z 1]' +x = u / w +y = v / w +``` + +This applies to both images of a stereo pair. + +## References + +coScene's schema types are framework-independent and can be implemented using any supported message encoding format. + +| Encoding Format | Schema Name | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [`foxglove_msgs/CameraCalibration`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/CameraCalibration.msg) | +| ROS 2 | [`foxglove_msgs/msg/CameraCalibration`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/CameraCalibration.msg) | +| JSON | [`foxglove.CameraCalibration`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/CameraCalibration.json) | +| Protobuf | [`foxglove.CameraCalibration`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/CameraCalibration.proto) | +| FlatBuffers | [`foxglove.CameraCalibration`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/CameraCalibration.fbs) | +| OMG IDL | [`foxglove::CameraCalibration`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/CameraCalibration.idl) | + +> **Note**: You must use the schema names specified above for coScene to recognize them correctly. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/circle-annotation.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/circle-annotation.md new file mode 100644 index 000000000..54e1c93e8 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/circle-annotation.md @@ -0,0 +1,42 @@ +--- +sidebar_position: 5 +title: CircleAnnotation +--- + +# Circle Annotation + +A circular annotation on a 2D image. + +## Parent Schema + +`CircleAnnotation` appears in the [`ImageAnnotations`](../message-schemas/image-annotations) message schema. + +## Field Definitions + +| Field Name | Type | Description | +| :-------------- | :-------------------------------------- | :----------------------------------------------------------------- | +| `timestamp` | [`time`](./built-in%20types#time) | Timestamp of the circle | +| `position` | [`Point2`](./point-2) | Position of the circle center in 2D pixel coordinates in the image | +| `diameter` | [`float64`](./built-in%20types#float64) | Diameter of the circle (in pixels) | +| `thickness` | [`float64`](./built-in%20types#float64) | Thickness of the line (in pixels) | +| `fill_color` | [`Color`](./color) | Fill color | +| `outline_color` | [`Color`](./color) | Outline color | + +### `position` + +The coordinate system has its origin at the top-left corner of the top-left pixel of the image. + +## References + +coScene's schema types are framework-independent and can be implemented using any supported message encoding format. + +| Encoding Format | Schema Name | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [`foxglove_msgs/CircleAnnotation`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/CircleAnnotation.msg) | +| ROS 2 | [`foxglove_msgs/msg/CircleAnnotation`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/CircleAnnotation.msg) | +| JSON | [`foxglove.CircleAnnotation`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/CircleAnnotation.json) | +| Protobuf | [`foxglove.CircleAnnotation`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/CircleAnnotation.proto) | +| FlatBuffers | [`foxglove.CircleAnnotation`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/CircleAnnotation.fbs) | +| OMG IDL | [`foxglove::CircleAnnotation`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/CircleAnnotation.idl) | + +> **Note**: You must use the schema names specified above for coScene to recognize them correctly. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/color.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/color.md new file mode 100644 index 000000000..c23a5c261 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/color.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 6 +title: Color +--- + +# Color + +Color in RGBA format. + +## Panel Support + +`Color` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Parent Schema + +`Color` appears in the [`ArrowPrimitive`](./arrow-primitive), [`CircleAnnotation`](./circle-annotation), [`CubePrimitive`](./cube-primitive), [`CylinderPrimitive`](./cylinder-primitive), [`LinePrimitive`](./line-primitive), [`ModelPrimitive`](./model-primitive), [`PointsAnnotation`](./points-annotation), [`SpherePrimitive`](./sphere-primitive), [`TextAnnotation`](./text-annotation), [`TextPrimitive`](./text-primitive), [`TriangleListPrimitive`](./triangle-list-primitive) message schemas. + +## Field Definitions + +| Field Name | Type | Description | +| ---------- | --------------------------------------- | ------------------------------------------- | +| `r` | [`float64`](./built-in%20types#float64) | Red, value between 0 and 1 | +| `g` | [`float64`](./built-in%20types#float64) | Green, value between 0 and 1 | +| `b` | [`float64`](./built-in%20types#float64) | Blue, value between 0 and 1 | +| `a` | [`float64`](./built-in%20types#float64) | Alpha (transparency), value between 0 and 1 | + +## References + +coScene's schema types are framework-independent and can be implemented using any supported message encoding format. + +| Encoding Format | Schema Name | +| --------------- | --------------------------------------------------------------------------------------------------------- | +| ROS 1 | [`foxglove_msgs/Color`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/Color.msg) | +| ROS 2 | [`foxglove_msgs/msg/Color`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/Color.msg) | +| JSON | [`foxglove.Color`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/Color.json) | +| Protobuf | [`foxglove.Color`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/Color.proto) | +| FlatBuffers | [`foxglove.Color`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/Color.fbs) | +| OMG IDL | [`foxglove::Color`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/Color.idl) | + +> **Note**: You must use the schema names specified above for coScene to recognize them correctly. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/compressed-image.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/compressed-image.md new file mode 100644 index 000000000..38d3fa200 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/compressed-image.md @@ -0,0 +1,38 @@ +--- +sidebar_position: 6 +title: CompressedImage +--- + +# Compressed Image + +## Panel Support + +`CompressedImage` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Field Definitions + +| Field Name | Type | Description | +| ----------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `timestamp` | [`time`](./built-in%20types#time) | Timestamp of the image | +| `frame_id` | [`string`](./built-in%20types#string) | Reference coordinate system of the image. The origin of the coordinate system is the optical center of the camera. +x points to the right in the image, +y points down, and +z points into the image plane. | +| `data` | [`byte`](./built-in%20types#bytes) | Compressed image data | +| `format` | [`string`](./built-in%20types#string) | Image format | + +### `format` + +Supported values: Picture media types supported by Chrome, such as `webp`, `jpeg`, `png` + +## References + +coScene's schema types are framework-independent and can be implemented using any supported message encoding format. + +| Encoding Format | Schema Name | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [`foxglove_msgs/CompressedImage`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/CompressedImage.msg) | +| ROS 2 | [`foxglove_msgs/msg/CompressedImage`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/CompressedImage.msg) | +| JSON | [`foxglove.CompressedImage`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/CompressedImage.json) | +| Protobuf | [`foxglove.CompressedImage`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/CompressedImage.proto) | +| FlatBuffers | [`foxglove.CompressedImage`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/CompressedImage.fbs) | +| OMG IDL | [`foxglove::CompressedImage`](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/CompressedImage.idl) | + +> **Note**: You must use the schema names specified above for coScene to recognize them correctly. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/compressed-video.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/compressed-video.md new file mode 100644 index 000000000..c884738a3 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/compressed-video.md @@ -0,0 +1,52 @@ +# CompressedVideo + +A single frame of a compressed video bitstream + +## Panel Support + +`CompressedVideo` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Data Structure + +| Field | Type | Description | +| ----------- | ------------------------------------- | ---------------------------------------- | +| `timestamp` | [`time`](./built-in%20types#time) | Timestamp of the video frame | +| `frame_id` | [`string`](./built-in%20types#string) | Reference coordinate system of the video | +| `data` | [`bytes`](./built-in%20types#bytes) | Compressed video frame data | +| `format` | [`string`](./built-in%20types#string) | Video format | + +### `frame_id` + +The origin of the frame is the optical center of the camera. +x points to the right side of the video, +y points downward, and +z points into the video plane. + +### `data` + +For packet-based video codecs, this data must begin and end on packet boundaries (no partial packets), and must contain enough video packets to decode exactly one image (key frame or incremental frame). Note: Foxglove does not support video streams that contain B-frames because they require lookahead. + +Specifically, the requirements for different `format` values are as follows: + +- `h264` + - Data using Annex B format + - Each CompressedVideo message should contain enough NAL units to decode exactly one video frame + - Each message containing a key frame (IDR) must also include the SPS NAL unit + +### `format` + +Supported values: `h264`. + +Note: Compressed video support is affected by hardware limitations and patent licensing, so not all platforms support all encodings. + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | --------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/CompressedVideo](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/CompressedVideo.msg) | +| ROS 2 | [foxglove_msgs/msg/CompressedVideo](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/CompressedVideo.msg) | +| JSON | [foxglove.CompressedVideo](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/CompressedVideo.json) | +| Protobuf | [foxglove.CompressedVideo](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/CompressedVideo.proto) | +| FlatBuffers | [foxglove.CompressedVideo](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/CompressedVideo.fbs) | +| OMG IDL | [foxglove::CompressedVideo](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/CompressedVideo.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/cube-primitive.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/cube-primitive.md new file mode 100644 index 000000000..0a7bcf23e --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/cube-primitive.md @@ -0,0 +1,30 @@ +# CubePrimitive + +Represents a primitive for a cube or rectangular prism + +## Parent Data Structure + +`CubePrimitive` appears in the [`SceneEntity`](./scene-entity) message data structure. + +## Data Structure + +| Field | Type | Description | +| ----- | ----------------------- | ------------------------------------------------------- | +| pose | [`Pose`](./pose) | Position of the cube center and orientation of the cube | +| size | [`Vector3`](./vector-3) | Dimensions of the cube along each axis | +| color | [`Color`](./color) | Color of the cube | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/CubePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/CubePrimitive.msg) | +| ROS 2 | [foxglove_msgs/msg/CubePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/CubePrimitive.msg) | +| JSON | [foxglove.CubePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/CubePrimitive.json) | +| Protobuf | [foxglove.CubePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/CubePrimitive.proto) | +| FlatBuffers | [foxglove.CubePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/CubePrimitive.fbs) | +| OMG IDL | [foxglove::CubePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/CubePrimitive.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/cylinder-primitive.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/cylinder-primitive.md new file mode 100644 index 000000000..fefcc3c81 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/cylinder-primitive.md @@ -0,0 +1,32 @@ +# CylinderPrimitive + +Represents a primitive for a cylinder, elliptical cylinder, or truncated cone. + +## Parent Data Structure + +`CylinderPrimitive` appears in the [`SceneEntity`](./scene-entity) message data structure. + +## Data Structure + +| Field | Type | Description | +| :----------- | :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | +| pose | [`Pose`](./pose) | Position of the cylinder center and orientation of the cylinder. Planes (faces) are perpendicular to the z axis. | +| size | [`Vector3`](./vector-3) | Size of the cylinder's bounding box | +| bottom_scale | [`float64`](./built-in%20types#float64) | 0-1, ratio of the cylinder bottom face (minimum z value) diameter to the bottom of the bounding box | +| top_scale | [`float64`](./built-in%20types#float64) | 0-1, ratio of the cylinder top face (maximum z value) diameter to the top of the bounding box | +| color | [`Color`](./color) | Color of the cylinder | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/CylinderPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/CylinderPrimitive.msg) | +| ROS 2 | [foxglove_msgs/msg/CylinderPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/CylinderPrimitive.msg) | +| JSON | [foxglove.CylinderPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/CylinderPrimitive.json) | +| Protobuf | [foxglove.CylinderPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/CylinderPrimitive.proto) | +| FlatBuffers | [foxglove.CylinderPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/CylinderPrimitive.fbs) | +| OMG IDL | [foxglove::CylinderPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/CylinderPrimitive.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-line-type.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-line-type.md new file mode 100644 index 000000000..c5541ee4c --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-line-type.md @@ -0,0 +1,19 @@ +--- +title: Enum LineType +--- + +# LineType + +An enumeration type used to indicate how input points should be interpreted to create lines + +## Parent Data Structure + +`LineType` appears in the [`LinePrimitive`](./line-primitive) data structure. + +## Values + +| Name | Value | Description | +| ---------- | ----- | ----------------------------------------------- | +| LINE_STRIP | 0 | Connected line segments: 0-1, 1-2, ..., (n-1)-n | +| LINE_LOOP | 1 | Closed polygon: 0-1, 1-2, ..., (n-1)-n, n-0 | +| LINE_LIST | 2 | Independent line segments: 0-1, 2-3, 4-5, ... | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-log-level.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-log-level.md new file mode 100644 index 000000000..727b145f8 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-log-level.md @@ -0,0 +1,22 @@ +--- +title: Enum LogLevel +--- + +# LogLevel + +Log level + +## Parent Type + +`LogLevel` appears in the [`Log`](./log) data structure. + +## Values + +| Name | Value | Description | +| ------- | ----- | ----------------- | +| UNKNOWN | 0 | Unknown level | +| DEBUG | 1 | Debug level | +| INFO | 2 | Information level | +| WARNING | 3 | Warning level | +| ERROR | 4 | Error level | +| FATAL | 5 | Fatal error level | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-numeric-type.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-numeric-type.md new file mode 100644 index 000000000..17142aed8 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-numeric-type.md @@ -0,0 +1,21 @@ +# NumericType + +Numeric type + +## Parent Type + +`NumericType` appears in the [`PackedElementField`](./packed-element-field) data structure. + +## Values + +| Name | Value | Description | +| ------- | ----- | ----------------------- | +| UNKNOWN | 0 | Unknown type | +| UINT8 | 1 | 8-bit unsigned integer | +| INT8 | 2 | 8-bit signed integer | +| UINT16 | 3 | 16-bit unsigned integer | +| INT16 | 4 | 16-bit signed integer | +| UINT32 | 5 | 32-bit unsigned integer | +| INT32 | 6 | 32-bit signed integer | +| FLOAT32 | 7 | 32-bit floating point | +| FLOAT64 | 8 | 64-bit floating point | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-points-annotation-type.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-points-annotation-type.md new file mode 100644 index 000000000..95577acb6 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-points-annotation-type.md @@ -0,0 +1,17 @@ +# PointsAnnotationType + +Points annotation type + +## Parent Type + +`PointsAnnotationType` appears in the [`PointsAnnotation`](./points-annotation) data structure. + +## Values + +| Name | Value | Description | +| ---------- | ----- | ----------------------------------------------- | +| UNKNOWN | 0 | Unknown type | +| POINTS | 1 | Independent points: 0, 1, 2, ... | +| LINE_LOOP | 2 | Closed polygon: 0-1, 1-2, ..., (n-1)-n, n-0 | +| LINE_STRIP | 3 | Connected line segments: 0-1, 1-2, ..., (n-1)-n | +| LINE_LIST | 4 | Independent line segments: 0-1, 2-3, 4-5, ... | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-position-covariance-type.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-position-covariance-type.md new file mode 100644 index 000000000..c9f30c10f --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-position-covariance-type.md @@ -0,0 +1,16 @@ +# PositionCovarianceType + +Position covariance type + +## Parent Type + +`PositionCovarianceType` appears in the [`LocationFix`](./location-fix) data structure. + +## Values + +| Name | Value | Description | +| -------------- | ----- | ------------------ | +| UNKNOWN | 0 | Unknown type | +| APPROXIMATED | 1 | Approximated value | +| DIAGONAL_KNOWN | 2 | Diagonal known | +| KNOWN | 3 | Fully known | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-scene-entity-deletion-type.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-scene-entity-deletion-type.md new file mode 100644 index 000000000..225bbc63b --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/enum-scene-entity-deletion-type.md @@ -0,0 +1,14 @@ +# SceneEntityDeletionType + +An enumeration type used to indicate which entities should match the [`SceneEntityDeletion`](./scene-entity-deletion) command. + +## Parent Type + +`SceneEntityDeletionType` appears in the [`SceneEntityDeletion`](./scene-entity-deletion) data structure. + +## Values + +| Name | Value | Description | +| ----------- | ----- | ---------------------------------------------------------------- | +| MATCHING_ID | 0 | Delete existing entities with the specified ID on the same topic | +| ALL | 1 | Delete all existing entities on the same topic | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/frame-transform.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/frame-transform.md new file mode 100644 index 000000000..d4dba06f5 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/frame-transform.md @@ -0,0 +1,36 @@ +# FrameTransform + +Transformation between two reference coordinate systems in 3D space + +## Panel Support + +`FrameTransform` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Parent Data Structure + +`FrameTransform` appears in the [`FrameTransforms`](./frame-transforms) message data structure. + +## Data Structure + +| Field | Type | Description | +| :-------------- | :------------------------------------ | :------------------------------------------ | +| timestamp | [`time`](./built-in%20types#time) | Timestamp of the transformation | +| parent_frame_id | [`string`](./built-in%20types#string) | Name of the parent coordinate system | +| child_frame_id | [`string`](./built-in%20types#string) | Name of the child coordinate system | +| translation | [`Vector3`](./vector-3) | Translation component of the transformation | +| rotation | [`Quaternion`](./quaternion) | Rotation component of the transformation | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/FrameTransform](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/FrameTransform.msg) | +| ROS 2 | [foxglove_msgs/msg/FrameTransform](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/FrameTransform.msg) | +| JSON | [foxglove.FrameTransform](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/FrameTransform.json) | +| Protobuf | [foxglove.FrameTransform](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/FrameTransform.proto) | +| FlatBuffers | [foxglove.FrameTransform](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/FrameTransform.fbs) | +| OMG IDL | [foxglove::FrameTransform](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/FrameTransform.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/frame-transforms.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/frame-transforms.md new file mode 100644 index 000000000..e013213c4 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/frame-transforms.md @@ -0,0 +1,24 @@ +# FrameTransforms + +An array of [`FrameTransform`](./frame-transform) messages + +## Data Structure + +| Field | Type | Description | +| ---------- | --------------------------------------- | ------------------------ | +| transforms | [FrameTransform\[\]](./frame-transform) | Array of transformations | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | --------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/FrameTransforms](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/FrameTransforms.msg) | +| ROS 2 | [foxglove_msgs/msg/FrameTransforms](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/FrameTransforms.msg) | +| JSON | [foxglove.FrameTransforms](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/FrameTransforms.json) | +| Protobuf | [foxglove.FrameTransforms](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/FrameTransforms.proto) | +| FlatBuffers | [foxglove.FrameTransforms](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/FrameTransforms.fbs) | +| OMG IDL | [foxglove::FrameTransforms](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/FrameTransforms.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/geo-json.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/geo-json.md new file mode 100644 index 000000000..4c7f7fc0e --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/geo-json.md @@ -0,0 +1,28 @@ +# GeoJSON + +GeoJSON data for annotations on maps + +## Panel Support + +`GeoJSON` is used in the Map Panel. + +## Data Structure + +| Field | Type | Description | +| ------- | ------------------------------------- | -------------------------------------- | +| geojson | [`string`](./built-in%20types#string) | GeoJSON data encoded as a UTF-8 string | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/GeoJSON](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/GeoJSON.msg) | +| ROS 2 | [foxglove_msgs/msg/GeoJSON](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/GeoJSON.msg) | +| JSON | [foxglove.GeoJSON](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/GeoJSON.json) | +| Protobuf | [foxglove.GeoJSON](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/GeoJSON.proto) | +| FlatBuffers | [foxglove.GeoJSON](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/GeoJSON.fbs) | +| OMG IDL | [foxglove::GeoJSON](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/GeoJSON.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/grid.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/grid.md new file mode 100644 index 000000000..de872c9ab --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/grid.md @@ -0,0 +1,40 @@ +--- +title: Grid +--- + +# Grid + +A two-dimensional grid of data. + +## Panel Support + +`Grid` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Data Structure + +| Field | Type | Description | +| ------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Timestamp of the grid | +| frame_id | [`string`](./built-in%20types#string) | Reference coordinate system | +| pose | [`Pose`](./pose) | Position of the grid origin relative to the reference coordinate system; the grid is positioned in the x-y plane relative to this origin | +| column_count | [`uint32`](./built-in%20types#uint32) | Number of columns in the grid | +| cell_size | [`Vector2`](./vector-2) | Size of a single grid cell along the x and y axes, relative to the pose | +| row_stride | [`uint32`](./built-in%20types#uint32) | Number of bytes between rows in the data | +| cell_stride | [`uint32`](./built-in%20types#uint32) | Number of bytes between cells within a row in the data | +| fields | [`PackedElementField[]`](./packed-element-field) | Fields in the data. red, green, blue, and alpha are optional for customizing the color of the grid | +| data | [`bytes`](./built-in%20types#bytes) | Grid cell data, interpreted using fields, arranged in row-major (y-major) order | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/Grid](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/Grid.msg) | +| ROS 2 | [foxglove_msgs/msg/Grid](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/Grid.msg) | +| JSON | [foxglove.Grid](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/Grid.json) | +| Protobuf | [foxglove.Grid](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/Grid.proto) | +| FlatBuffers | [foxglove.Grid](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/Grid.fbs) | +| OMG IDL | [foxglove::Grid](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/Grid.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/image-annotations.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/image-annotations.md new file mode 100644 index 000000000..12d924fc5 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/image-annotations.md @@ -0,0 +1,34 @@ +--- +title: ImageAnnotations +--- + +# ImageAnnotations + +An array of annotations for 2D images + +## Panel Support + +`ImageAnnotations` is used in the [Image Panel](../panel/image-panel). + +## Data Structure + +| Field | Type | Description | +| ------- | --------------------------------------------- | ------------------ | +| circles | [`CircleAnnotation\[\]`](./circle-annotation) | Circle annotations | +| points | [`PointsAnnotation\[\]`](./points-annotation) | Point annotations | +| texts | [`TextAnnotation\[\]`](./text-annotation) | Text annotations | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/ImageAnnotations](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/ImageAnnotations.msg) | +| ROS 2 | [foxglove_msgs/msg/ImageAnnotations](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/ImageAnnotations.msg) | +| JSON | [foxglove.ImageAnnotations](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/ImageAnnotations.json) | +| Protobuf | [foxglove.ImageAnnotations](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/ImageAnnotations.proto) | +| FlatBuffers | [foxglove.ImageAnnotations](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/ImageAnnotations.fbs) | +| OMG IDL | [foxglove::ImageAnnotations](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/ImageAnnotations.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/introduction.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/introduction.md new file mode 100644 index 000000000..d60f8f37c --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/introduction.md @@ -0,0 +1,88 @@ +--- +sidebar_position: 1 +title: Introduction +--- + +# Introduction + +coScene typically requires messages to follow specific structures for proper visualization. Using the [Foxglove Schema](https://github.com/foxglove/foxglove-sdk) allows you to take full advantage of the platform's built-in visualization capabilities. + +## Supported Formats + +- [Protobuf](https://github.com/foxglove/foxglove-sdk/tree/main/schemas/proto/foxglove) +- [JSON Schema](https://github.com/foxglove/foxglove-sdk/tree/main/schemas/jsonschema) +- [ROS 1](https://github.com/foxglove/foxglove-sdk/tree/main/schemas/ros1) +- [ROS 2](https://github.com/foxglove/foxglove-sdk/tree/main/schemas/ros2) +- [TypeScript](https://github.com/foxglove/foxglove-sdk/tree/main/typescript/schemas/src/types) +- [FlatBuffers](https://github.com/foxglove/foxglove-sdk/tree/main/schemas/flatbuffer) + +If you have written custom messages, you can use [Message Converter](../8-extensions/4-guides/2-create-message-converter.md) extensions to convert them into schemas supported by coScene. + +## Protobuf and JSON Schema Types + +Copy the required [`.proto` files](https://github.com/foxglove/foxglove-sdk/tree/main/schemas/proto/foxglove) or [`.json` files](https://github.com/foxglove/foxglove-sdk/tree/main/schemas/jsonschema) directly into your project and publish data through the coScene WebSocket connection or record to [MCAP files](https://mcap.dev/). + +**Note:** + +For Protobuf data, time values of type [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) or [`google.protobuf.Duration`](https://protobuf.dev/reference/protobuf/google.protobuf/#duration) will be represented with `sec` and `nsec` fields instead of `seconds` and `nanos` in [User Scripts](/), [Message Converters](/), and other parts of coScene to maintain consistency with time and duration types in other data formats. + +You can also import JSON schemas through the [`@foxglove/schemas` npm package](https://www.npmjs.com/package/@foxglove/schemas): + +```typescript +import { CompressedImage } from '@foxglove/schemas/jsonschema'; +``` + +We provide WebSocket libraries for real-time data ([Python](https://github.com/foxglove/ws-protocol/tree/main/python), [JavaScript](https://github.com/foxglove/ws-protocol/tree/main/typescript/ws-protocol-examples), [C++](https://github.com/foxglove/ws-protocol/tree/main/cpp)), as well as MCAP writers for pre-recorded data files ([Python](https://github.com/foxglove/mcap/tree/main/python), [JavaScript](https://github.com/foxglove/mcap/tree/main/typescript), [C++](https://github.com/foxglove/mcap/tree/main/cpp)). + +See the example blog post about recording your Protobuf data using the MCAP C++ writer: [Recording Robocar Data with MCAP](https://foxglove.dev/blog/recording-robocar-data-with-mcap). + +## JSON Without Schema Type + +MCAP supports writing JSON messages without specifying a schema type. To write JSON message data without a schema type, set the channel's message encoding to `json` and the schema type ID to 0. This indicates that the channel has no schema type. For details, see: [https://mcap.dev/spec#channel-op0x04](https://mcap.dev/spec#channel-op0x04) + +## ROS + +Install the `foxglove_msgs` package: + +```bash +sudo apt install ros-noetic-foxglove-msgs # For ROS 1 +sudo apt install ros-galactic-foxglove-msgs # For ROS 2 +``` + +Then, import the required schemas in your ROS project to start publishing data: + +```python +from foxglove_msgs.msg import Vector2 + +msg = Vector2() +msg.x = 0.5 +msg.y = 0.7 +``` + +## TypeScript + +Import coScene message schemas as TypeScript types for type checking. + +In coScene's [User Script Panel](/), you can specify the required schema type using `Message<"foxglove.[SchemaName]">`: + +```typescript +import { Input, Message } from './types'; + +type Output = Message<'foxglove.Point2'>; + +export const inputs = ['/input/topic']; +export const output = '/studio_script/output_topic'; + +export default function script(event: Input<'/input/topic'>): Output { + return { x: 1, y: 2 }; +} +``` + +For your own TypeScript projects, you can import types directly from the [@foxglove/schemas](https://www.npmjs.com/package/@foxglove/schemas) npm package: + +```typescript +import { Point2 } from '@foxglove/schemas'; +const myPoint: Point2 = { x: 1, y: 2 }; +``` + +Import these types when working with JavaScript WebSocket or MCAP projects, or when writing custom data transformation scripts in coScene's User Script Panel. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/key-value-pair.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/key-value-pair.md new file mode 100644 index 000000000..86607c40a --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/key-value-pair.md @@ -0,0 +1,29 @@ +# KeyValuePair + +A key-value pair containing a key and its associated value. + +## Parent Data Structure + +`KeyValuePair` appears in the [`SceneEntity`](./scene-entity) message data structure. + +## Data Structure + +| Field | Type | Description | +| ----- | ------------------------------------- | ----------- | +| key | [`string`](./built-in%20types#string) | Key | +| value | [`string`](./built-in%20types#string) | Value | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | --------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/KeyValuePair](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/KeyValuePair.msg) | +| ROS 2 | [foxglove_msgs/msg/KeyValuePair](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/KeyValuePair.msg) | +| JSON | [foxglove.KeyValuePair](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/KeyValuePair.json) | +| Protobuf | [foxglove.KeyValuePair](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/KeyValuePair.proto) | +| FlatBuffers | [foxglove.KeyValuePair](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/KeyValuePair.fbs) | +| OMG IDL | [foxglove::KeyValuePair](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/KeyValuePair.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/laser-scan.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/laser-scan.md new file mode 100644 index 000000000..0212891c3 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/laser-scan.md @@ -0,0 +1,34 @@ +# LaserScan + +Single scan data from a planar laser rangefinder + +## Panel Support + +`LaserScan` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Data Structure + +| Field | Type | Description | +| ----------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Timestamp of the scan | +| frame_id | [`string`](./built-in%20types#string) | Reference coordinate system | +| pose | [`Pose`](./pose) | Scan origin relative to the reference coordinate system; points lie in the x-y plane relative to this origin; angles are interpreted as counterclockwise rotations around the z axis, with 0 radians pointing in the +x direction | +| start_angle | [`float64`](./built-in%20types#float64) | Azimuth of the first point in radians | +| end_angle | [`float64`](./built-in%20types#float64) | Azimuth of the last point in radians | +| ranges | [`float64[]`](./built-in%20types#float64) | Distances from the origin to detected points; assumed to be evenly distributed between `start_angle` and `end_angle` | +| intensities | [`float64[]`](./built-in%20types#float64) | Intensities of the detected points | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | --------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/LaserScan](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/LaserScan.msg) | +| ROS 2 | [foxglove_msgs/msg/LaserScan](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/LaserScan.msg) | +| JSON | [foxglove.LaserScan](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/LaserScan.json) | +| Protobuf | [foxglove.LaserScan](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/LaserScan.proto) | +| FlatBuffers | [foxglove.LaserScan](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/LaserScan.fbs) | +| OMG IDL | [foxglove::LaserScan](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/LaserScan.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/line-primitive.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/line-primitive.md new file mode 100644 index 000000000..0e4691ba9 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/line-primitive.md @@ -0,0 +1,39 @@ +# LinePrimitive + +A primitive representing a series of points connected by lines + +## Parent Data Structure + +`LinePrimitive` appears in the [`SceneEntity`](./scene-entity) message data structure. + +## Data Structure + +| Field | Type | Description | +| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| type | [`LineType`](./enum-line-type) | Drawing primitive used for the lines | +| pose | [`Pose`](./pose) | Origin of the lines relative to the reference frame | +| thickness | [`float64`](./built-in%20types#float64) | Thickness of the lines | +| scale_invariant | [`boolean`](./built-in%20types#boolean) | Indicates whether thickness is fixed size in screen pixels (true) or specified in world coordinates and scales with camera distance (false) | +| points | [`Point3[]`](./point-3) | Points on the lines | +| color | [`Color`](./color) | Solid color for the entire line. Either color or colors must be provided. | +| colors | [`Color[]`](./color) | Color for each point (if specified, length must match points). Either color or colors must be provided. | +| indices | [`uint32[]`](./built-in%20types#uint32) | Indices into the points and colors attribute arrays, which can be used to avoid duplicating attribute data. | + +### `indices` + +If omitted or empty, no indices are used. This default behavior is equivalent to specifying [0, 1, ..., N-1] for indices (where N is the number of `points` provided). + +## Reference Implementation + +The visualization schema is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/LinePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/LinePrimitive.msg) | +| ROS 2 | [foxglove_msgs/msg/LinePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/LinePrimitive.msg) | +| JSON | [foxglove.LinePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/LinePrimitive.json) | +| Protobuf | [foxglove.LinePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/LinePrimitive.proto) | +| FlatBuffers | [foxglove.LinePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/LinePrimitive.fbs) | +| OMG IDL | [foxglove::LinePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/LinePrimitive.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/location-fix.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/location-fix.md new file mode 100644 index 000000000..38093e49b --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/location-fix.md @@ -0,0 +1,34 @@ +# LocationFix + +Navigation satellite positioning information for any Global Navigation Satellite System. + +## Panel Support + +`LocationFix` is used in the Map Panel. + +## Data Structure + +| Field | Type | Description | +| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Timestamp of the message | +| frame_id | [`string`](./built-in%20types#string) | Coordinate system of the sensor. The latitude and longitude readings are at the origin of this coordinate system. | +| latitude | [`float64`](./built-in%20types#float64) | Latitude (degrees) | +| longitude | [`float64`](./built-in%20types#float64) | Longitude (degrees) | +| altitude | [`float64`](./built-in%20types#float64) | Altitude (meters) | +| position_covariance | [`float64[9]`](./built-in%20types#float64) | Position covariance (square meters) relative to the tangent plane defined through the reported position. Components are ordered in row-major order as east, north, up (ENU). | +| position_covariance_type | [`PositionCovarianceType`](./enum-position-covariance-type) | If position_covariance is provided, position_covariance_type must be set to indicate the type of covariance. | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/LocationFix](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/LocationFix.msg) | +| ROS 2 | [foxglove_msgs/msg/LocationFix](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/LocationFix.msg) | +| JSON | [foxglove.LocationFix](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/LocationFix.json) | +| Protobuf | [foxglove.LocationFix](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/LocationFix.proto) | +| FlatBuffers | [foxglove.LocationFix](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/LocationFix.fbs) | +| OMG IDL | [foxglove::LocationFix](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/LocationFix.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/log.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/log.md new file mode 100644 index 000000000..3f4cd5477 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/log.md @@ -0,0 +1,33 @@ +# Log + +Log message + +## Panel Support + +The `Log` message type is used in the [Log Panel](../panel/log-panel). + +## Data Structure + +| Field | Type | Description | +| --------- | ------------------------------------- | ---------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Timestamp of the log message | +| level | [`LogLevel`](./enum-log-level) | Log level | +| message | [`string`](./built-in%20types#string) | Log message content | +| name | [`string`](./built-in%20types#string) | Process or node name | +| file | [`string`](./built-in%20types#string) | Filename | +| line | [`uint32`](./built-in%20types#uint32) | Line number in file | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | --------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/Log](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/Log.msg) | +| ROS 2 | [foxglove_msgs/msg/Log](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/Log.msg) | +| JSON | [foxglove.Log](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/Log.json) | +| Protobuf | [foxglove.Log](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/Log.proto) | +| FlatBuffers | [foxglove.Log](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/Log.fbs) | +| OMG IDL | [foxglove::Log](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/Log.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/model-primitive.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/model-primitive.md new file mode 100644 index 000000000..534d6b9e8 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/model-primitive.md @@ -0,0 +1,34 @@ +# ModelPrimitive + +Represents the original type of a 3D model file loaded from an external URL or embedded data + +## Parent Data Structure + +`ModelPrimitive` appears in the [`SceneEntity`](./scene-entity) message data structure. + +## Data Structure + +| Field | Type | Description | +| -------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| pose | [`pose`](./pose) | The origin of the model relative to the reference frame | +| scale | [`Vector3`](./vector-3) | The scale factor applied to the model along each axis | +| color | [`color`](./color) | The pure color used for the entire model if `override_color` is true | +| override_color | [`boolean`](./built-in%20types#boolean) | Whether to use the color specified in `color` instead of any embedded materials in the original model | +| url | [`string`](./built-in%20types#string) | The URL pointing to the model file. Either `url` or `data` must be provided. | +| media_type | [`string`](./built-in%20types#string) | The [media type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the embedded model (e.g. `model/gltf-binary`). If `data` is provided instead of `url`, this field is required. If `url` is provided, it overrides the inferred media type. | +| data | [`bytes`](./built-in%20types#bytes) | The embedded model. Either `url` or `data` must be provided. If `data` is provided, `media_type` must be set to indicate the type of data. | + +## Reference Implementation + +Visualization data structures are framework-agnostic and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/ModelPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/ModelPrimitive.msg) | +| ROS 2 | [foxglove_msgs/msg/ModelPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/ModelPrimitive.msg) | +| JSON | [foxglove.ModelPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/ModelPrimitive.json) | +| Protobuf | [foxglove.ModelPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/ModelPrimitive.proto) | +| FlatBuffers | [foxglove.ModelPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/ModelPrimitive.fbs) | +| OMG IDL | [foxglove::ModelPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/ModelPrimitive.idl) | + +You must use the data structure name specified above so that the visualization can recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/packed-element-field.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/packed-element-field.md new file mode 100644 index 000000000..58688ed0c --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/packed-element-field.md @@ -0,0 +1,30 @@ +# PackedElementField + +Defines a field within each element of a packed byte array + +## Parent Data Structure + +`PackedElementField` appears in the [`Grid`](./grid) and [`PointCloud`](./point-cloud) message data structures. + +## Data Structure + +| Field | Type | Description | +| ------ | ------------------------------------- | ------------------------------------------------------------------------------- | +| name | [`string`](./built-in%20types#string) | The name of the field | +| offset | [`uint32`](./built-in%20types#uint32) | The byte offset from the data buffer | +| type | [`NumericType`](./enum-numeric-type) | The type of data in the field. Integers are stored in little-endian byte order. | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | --------------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/PackedElementField](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/PackedElementField.msg) | +| ROS 2 | [foxglove_msgs/msg/PackedElementField](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/PackedElementField.msg) | +| JSON | [foxglove.PackedElementField](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/PackedElementField.json) | +| Protobuf | [foxglove.PackedElementField](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/PackedElementField.proto) | +| FlatBuffers | [foxglove.PackedElementField](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/PackedElementField.fbs) | +| OMG IDL | [foxglove::PackedElementField](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/PackedElementField.idl) | + +You must use the data structure name specified above so that the visualization can recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/point-2.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/point-2.md new file mode 100644 index 000000000..bc874cc3b --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/point-2.md @@ -0,0 +1,29 @@ +# Point2 + +Represents a position point in two-dimensional space + +## Parent Schema + +`Point2` appears in the [`CircleAnnotation`](./circle-annotation), [`PointsAnnotation`](./points-annotation), and [`TextAnnotation`](./text-annotation) message schemas. + +## Schema Definition + +| Field | Type | Description | +| ----- | --------------------------------------- | --------------------- | +| x | [`float64`](./built-in%20types#float64) | x coordinate position | +| y | [`float64`](./built-in%20types#float64) | y coordinate position | + +## Reference Implementation + +The visualization schema is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Schema | +| ----------- | --------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/Point2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/Point2.msg) | +| ROS 2 | [foxglove_msgs/msg/Point2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/Point2.msg) | +| JSON | [foxglove.Point2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/Point2.json) | +| Protobuf | [foxglove.Point2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/Point2.proto) | +| FlatBuffers | [foxglove.Point2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/Point2.fbs) | +| OMG IDL | [foxglove::Point2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/Point2.idl) | + +You must use the schema names specified above for the visualization to recognize the schema. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/point-3.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/point-3.md new file mode 100644 index 000000000..1c7ff3e7b --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/point-3.md @@ -0,0 +1,30 @@ +# Point3 + +Represents a point position in three-dimensional space + +## Parent Data Structure + +`Point3` appears in the [`LinePrimitive`](./line-primitive) and [`TriangleListPrimitive`](./triangle-list-primitive) message data structures. + +## Data Structure + +| Field | Type | Description | +| ----- | --------------------------------------- | --------------------- | +| x | [`float64`](./built-in%20types#float64) | x coordinate position | +| y | [`float64`](./built-in%20types#float64) | y coordinate position | +| z | [`float64`](./built-in%20types#float64) | z coordinate position | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | --------------------------------------------------------------------------------------------------------- | +| ROS 1 | [geometry_msgs/Point](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Point.html) | +| ROS 2 | [geometry_msgs/msg/Point](https://docs.ros2.org/galactic/api/geometry_msgs/msg/Point.html) | +| JSON | [foxglove.Point3](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/Point3.json) | +| Protobuf | [foxglove.Point3](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/Point3.proto) | +| FlatBuffers | [foxglove.Point3](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/Point3.fbs) | +| OMG IDL | [foxglove::Point3](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/Point3.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/point-cloud.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/point-cloud.md new file mode 100644 index 000000000..0aa1cc0e8 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/point-cloud.md @@ -0,0 +1,33 @@ +# PointCloud + +A collection of N-dimensional points, possibly with additional field information such as normals or intensities. + +## Panel Support + +`PointCloud` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Data Structure + +| Field | Type | Description | +| ------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Point cloud timestamp | +| frame_id | [`string`](./built-in%20types#string) | Reference coordinate system | +| pose | [`pose`](./pose) | Point cloud origin position relative to the reference coordinate system | +| point_stride | [`uint32`](./built-in%20types#uint32) | Number of bytes between adjacent points in the data | +| fields | [`PackedElementField[]`](./packed-element-field) | Fields in `data`. Each point must have at least 2 coordinate fields from x, y, z; red, green, blue, and alpha are optional for customizing the color of each point. | +| data | [`bytes`](./built-in%20types#bytes) | Point data, interpreted using fields | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/PointCloud](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/PointCloud.msg) | +| ROS 2 | [foxglove_msgs/msg/PointCloud](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/PointCloud.msg) | +| JSON | [foxglove.PointCloud](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/PointCloud.json) | +| Protobuf | [foxglove.PointCloud](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/PointCloud.proto) | +| FlatBuffers | [foxglove.PointCloud](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/PointCloud.fbs) | +| OMG IDL | [foxglove::PointCloud](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/PointCloud.idl) | + +You must use the data structure name specified above so that the visualization can recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/points-annotation.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/points-annotation.md new file mode 100644 index 000000000..de483dc2d --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/points-annotation.md @@ -0,0 +1,38 @@ +# PointsAnnotation + +An array of points on a 2D image. + +## Parent Data Structure + +`PointsAnnotation` appears in the [`ImageAnnotations`](./image-annotations) message data structure. + +## Data Structure + +| Field | Type | Description | +| -------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Annotation timestamp | +| type | [`PointsAnnotationType`](./enum-points-annotation-type) | Type of point annotation to draw | +| points | [`Point2[]`](./point-2) | Points in 2D image coordinates (pixels) | +| outline_color | [`color`](./color) | Outline color | +| outline_colors | [`Color[]`](./color) | Outline color for each point if `type` is `POINTS`; outline color for each line segment if `type` is `LINE_LIST`, `LINE_STRIP`, or `LINE_LOOP`. | +| fill_color | [`color`](./color) | Fill color | +| thickness | [`float64`](./built-in%20types#float64) | Outline thickness (pixels) | + +### `points` + +These coordinates use the top-left pixel of the image as the origin. + +## Reference Implementation + +Foxglove data structures are framework agnostic and can be implemented in any message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/PointsAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/PointsAnnotation.msg) | +| ROS 2 | [foxglove_msgs/msg/PointsAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/PointsAnnotation.msg) | +| JSON | [foxglove.PointsAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/PointsAnnotation.json) | +| Protobuf | [foxglove.PointsAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/PointsAnnotation.proto) | +| FlatBuffers | [foxglove.PointsAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/PointsAnnotation.fbs) | +| OMG IDL | [foxglove::PointsAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/PointsAnnotation.idl) | + +You must use the data structure name specified above so that Foxglove can recognize it. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/pose-in-frame.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/pose-in-frame.md new file mode 100644 index 000000000..e1bc0852f --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/pose-in-frame.md @@ -0,0 +1,30 @@ +# PoseInFrame + +Represents a pose in 3D space with a timestamp + +## Panel Support + +`PoseInFrame` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Data Structure + +| Field | Type | Description | +| --------- | ------------------------------------- | --------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Pose timestamp | +| frame_id | [`string`](./built-in%20types#string) | Reference frame for pose position | +| pose | [`pose`](./pose) | Pose in 3D space | + +## Reference Implementation + +Visualization data structures are framework-agnostic and can be implemented using any supported message encoding method: + +| Encoding Method | Data Structure | +| --------------- | ------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/PoseInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/PoseInFrame.msg) | +| ROS 2 | [foxglove_msgs/msg/PoseInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/PoseInFrame.msg) | +| JSON | [foxglove.PoseInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/PoseInFrame.json) | +| Protobuf | [foxglove.PoseInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/PoseInFrame.proto) | +| FlatBuffers | [foxglove.PoseInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/PoseInFrame.fbs) | +| OMG IDL | [foxglove::PoseInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/PoseInFrame.idl) | + +You must use the data structure names specified above so that the visualization can recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/pose.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/pose.md new file mode 100644 index 000000000..b7ebad121 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/pose.md @@ -0,0 +1,29 @@ +# Pose + +Represents the position and orientation of an object or reference frame in three-dimensional space + +## Parent Data Structure + +`Pose` appears in the following data structures: [`ArrowPrimitive`](./arrow-primitive), [`CubePrimitive`](./cube-primitive), [`CylinderPrimitive`](./cylinder-primitive), [`Grid`](./grid), [`LaserScan`](./laser-scan), [`LinePrimitive`](./line-primitive), [`ModelPrimitive`](./model-primitive), [`PointCloud`](./point-cloud), [`PoseInFrame`](./pose-in-frame), [`PosesInFrame`](./poses-in-frame), [`SpherePrimitive`](./sphere-primitive), [`TextPrimitive`](./text-primitive), and [`TriangleListPrimitive`](./triangle-list-primitive). + +## Data Structure + +| Field | Type | Description | +| ----------- | ---------------------------- | ------------------------------------------------- | +| position | [`Vector3`](./vector-3) | Represents the position point in 3D space | +| orientation | [`Quaternion`](./quaternion) | Represents the orientation quaternion in 3D space | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------- | +| ROS 1 | [geometry_msgs/Pose](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Pose.html) | +| ROS 2 | [geometry_msgs/msg/Pose](https://docs.ros2.org/galactic/api/geometry_msgs/msg/Pose.html) | +| JSON | [foxglove.Pose](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/Pose.json) | +| Protobuf | [foxglove.Pose](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/Pose.proto) | +| FlatBuffers | [foxglove.Pose](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/Pose.fbs) | +| OMG IDL | [foxglove::Pose](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/Pose.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/poses-in-frame.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/poses-in-frame.md new file mode 100644 index 000000000..275689be5 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/poses-in-frame.md @@ -0,0 +1,30 @@ +# PosesInFrame + +Represents a series of poses in 3D space with timestamps + +## Panel Support + +`PosesInFrame` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Data Structure + +| Field | Type | Description | +| --------- | ------------------------------------- | -------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Pose timestamp | +| frame_id | [`string`](./built-in%20types#string) | Pose reference coordinate system | +| poses | [`Pose[]`](./pose) | Poses in 3D space | + +## Reference Implementation + +Visualization data structures are framework-agnostic and can be implemented using any supported message encoding method: + +| Encoding Method | Data Structure | +| --------------- | --------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/PosesInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/PosesInFrame.msg) | +| ROS 2 | [foxglove_msgs/msg/PosesInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/PosesInFrame.msg) | +| JSON | [foxglove.PosesInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/PosesInFrame.json) | +| Protobuf | [foxglove.PosesInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/PosesInFrame.proto) | +| FlatBuffers | [foxglove.PosesInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/PosesInFrame.fbs) | +| OMG IDL | [foxglove::PosesInFrame](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/PosesInFrame.idl) | + +You must use the data structure name specified above so that the visualization can recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/quaternion.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/quaternion.md new file mode 100644 index 000000000..aac5dd58e --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/quaternion.md @@ -0,0 +1,31 @@ +# Quaternion + +Represents a quaternion for rotation in three-dimensional space + +## Parent Data Structure + +`Quaternion` appears in the [`FrameTransform`](./frame-transform) and [`Pose`](./pose) message data structures. + +## Data Structure + +| Field | Type | Description | +| ----- | --------------------------------------- | ----------- | +| x | [`float64`](./built-in%20types#float64) | x value | +| y | [`float64`](./built-in%20types#float64) | y value | +| z | [`float64`](./built-in%20types#float64) | z value | +| w | [`float64`](./built-in%20types#float64) | w value | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [geometry_msgs/Quaternion](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Quaternion.html) | +| ROS 2 | [geometry_msgs/msg/Quaternion](https://docs.ros2.org/galactic/api/geometry_msgs/msg/Quaternion.html) | +| JSON | [foxglove.Quaternion](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/Quaternion.json) | +| Protobuf | [foxglove.Quaternion](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/Quaternion.proto) | +| FlatBuffers | [foxglove.Quaternion](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/Quaternion.fbs) | +| OMG IDL | [foxglove::Quaternion](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/Quaternion.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/raw-image.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/raw-image.md new file mode 100644 index 000000000..bc9ec4487 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/raw-image.md @@ -0,0 +1,38 @@ +# RawImage + +Raw image data + +## Panel Support + +`RawImage` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Data Structure + +| Field | Type | Description | +| --------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Image timestamp | +| frame_id | [`string`](./built-in%20types#string) | Image reference coordinate system. The origin of the coordinate system is the optical center of the camera. +x points to the right of the image, +y points down, and +z points into the image plane. | +| width | [`uint32`](./built-in%20types#uint32) | Image width | +| height | [`uint32`](./built-in%20types#uint32) | Image height | +| encoding | [`string`](./built-in%20types#string) | Original image data encoding format | +| step | [`uint32`](./built-in%20types#uint32) | Length of a single line in bytes | +| data | [`bytes`](./built-in%20types#bytes) | Original image data | + +### `encoding` + +Supported formats: `8UC1`, `8UC3`, `16UC1` (Little Endian), `32FC1` (Little Endian), `bayer_bggr8`, `bayer_gbrg8`, `bayer_grbg8`, `bayer_rggb8`, `bgr8`, `bgra8`, `mono8`, `mono16`, `rgb8`, `rgba8`, `uyvy` or `yuv422`, `yuyv` or `yuv422_yuy2` + +## Reference Implementation + +Visualization data structures are framework-agnostic and can be implemented using any supported message encoding method: + +| Encoding Method | Data Structure | +| --------------- | ------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/RawImage](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/RawImage.msg) | +| ROS 2 | [foxglove_msgs/msg/RawImage](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/RawImage.msg) | +| JSON | [foxglove.RawImage](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/RawImage.json) | +| Protobuf | [foxglove.RawImage](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/RawImage.proto) | +| FlatBuffers | [foxglove.RawImage](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/RawImage.fbs) | +| OMG IDL | [foxglove::RawImage](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/RawImage.idl) | + +You must use the data structure names specified above so that the visualization can recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/scene-entity-deletion.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/scene-entity-deletion.md new file mode 100644 index 000000000..265cd13f9 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/scene-entity-deletion.md @@ -0,0 +1,30 @@ +# SceneEntityDeletion + +Command used to delete previously published entities + +## Parent Data Structure + +`SceneEntityDeletion` appears in the [`SceneUpdate`](./scene-update) message data structure. + +## Data Structure + +| Field | Type | Description | +| --------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Timestamp of the deletion operation. Only matching entities earlier than this timestamp will be deleted. | +| type | [`SceneEntityDeletionType`](./enum-scene-entity-deletion-type) | Type of deletion operation to perform | +| id | [`string`](./built-in%20types#string) | Identifier that must match when `type` is `MATCHING_ID`. | + +## Reference Implementation + +Visualization data structures are framework-agnostic and can be implemented using any supported message encoding method: + +| Encoding Method | Data Structure | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/SceneEntityDeletion](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/SceneEntityDeletion.msg) | +| ROS 2 | [foxglove_msgs/msg/SceneEntityDeletion](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/SceneEntityDeletion.msg) | +| JSON | [foxglove.SceneEntityDeletion](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/SceneEntityDeletion.json) | +| Protobuf | [foxglove.SceneEntityDeletion](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/SceneEntityDeletion.proto) | +| FlatBuffers | [foxglove.SceneEntityDeletion](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/SceneEntityDeletion.fbs) | +| OMG IDL | [foxglove::SceneEntityDeletion](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/SceneEntityDeletion.idl) | + +You must use the data structure names specified above so that the visualization can recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/scene-entity.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/scene-entity.md new file mode 100644 index 000000000..efa83b951 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/scene-entity.md @@ -0,0 +1,41 @@ +# SceneEntity + +A visual element in a 3D scene. An entity can be composed of multiple primitives that share the same reference frame. + +## Parent Data Structure + +`SceneEntity` appears in the [`SceneUpdate`](./scene-update) message data structure. + +## Data Structure + +| Field | Type | Description | +| ------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Entity timestamp | +| frame_id | [`string`](./built-in%20types#string) | Reference frame | +| id | [`string`](./built-in%20types#string) | Entity identifier. An entity will replace any previous entity with the same id on the same topic. | +| lifetime | [`duration`](./built-in%20types#duration) | The length of time the entity should be automatically removed (relative to the timestamp). Zero value means the entity should remain visible until it is replaced or deleted. | +| frame_locked | [`boolean`](./built-in%20types#boolean) | Whether the entity should remain in a fixed frame (false) or follow the frame specified in frame_id (true) relative to a fixed frame. | +| metadata | [`KeyValuePair[]`](./key-value-pair) | Additional user-provided metadata associated with the entity. Keys must be unique. | +| arrows | [`ArrowPrimitive[]`](./arrow-primitive) | Arrow primitives | +| cubes | [`CubePrimitive[]`](./cube-primitive) | Cube primitives | +| spheres | [`SpherePrimitive[]`](./sphere-primitive) | Sphere primitives | +| cylinders | [`CylinderPrimitive[]`](./cylinder-primitive) | Cylinder primitives | +| lines | [`LinePrimitive[]`](./line-primitive) | Line primitives | +| triangles | [`TriangleListPrimitive[]`](./triangle-list-primitive) | Triangle list primitives | +| texts | [`TextPrimitive[]`](./text-primitive) | Text primitives | +| models | [`ModelPrimitive[]`](./model-primitive) | Model primitives | + +## Reference Implementation + +Visualization data structures are framework-agnostic and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/SceneEntity](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/SceneEntity.msg) | +| ROS 2 | [foxglove_msgs/msg/SceneEntity](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/SceneEntity.msg) | +| JSON | [foxglove.SceneEntity](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/SceneEntity.json) | +| Protobuf | [foxglove.SceneEntity](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/SceneEntity.proto) | +| FlatBuffers | [foxglove.SceneEntity](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/SceneEntity.fbs) | +| OMG IDL | [foxglove::SceneEntity](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/SceneEntity.idl) | + +You must use the data structure names specified above so that visualizations can recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/scene-update.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/scene-update.md new file mode 100644 index 000000000..f446b0f9b --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/scene-update.md @@ -0,0 +1,29 @@ +# SceneUpdate + +Updates to entities displayed in the 3D scene. + +## Panel Support + +`SceneUpdate` is used in the [3D Panel](../panel/2-3d-panel) and [Image Panel](../panel/image-panel). + +## Data Structure + +| Field | Type | Description | +| --------- | -------------------------------------------------- | -------------------------------- | +| deletions | [`SceneEntityDeletion[]`](./scene-entity-deletion) | Scene entities to delete | +| entities | [`SceneEntity[]`](./scene-entity) | Scene entities to add or replace | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/SceneUpdate](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/SceneUpdate.msg) | +| ROS 2 | [foxglove_msgs/msg/SceneUpdate](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/SceneUpdate.msg) | +| JSON | [foxglove.SceneUpdate](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/SceneUpdate.json) | +| Protobuf | [foxglove.SceneUpdate](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/SceneUpdate.proto) | +| FlatBuffers | [foxglove.SceneUpdate](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/SceneUpdate.fbs) | +| OMG IDL | [foxglove::SceneUpdate](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/SceneUpdate.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/sphere-primitive.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/sphere-primitive.md new file mode 100644 index 000000000..91c38de64 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/sphere-primitive.md @@ -0,0 +1,30 @@ +# SpherePrimitive + +A primitive representing a sphere or ellipsoid + +## Parent Data Structure + +`SpherePrimitive` appears in the [`SceneEntity`](./scene-entity) message data structure. + +## Data Structure + +| Field | Type | Description | +| ----- | ----------------------- | --------------------------------------------- | +| pose | [`pose`](./pose) | Position and orientation of the sphere center | +| size | [`Vector3`](./vector-3) | Size of the sphere along each axis (diameter) | +| color | [`color`](./color) | Color of the sphere | + +## Reference Implementation + +Visualization data structures are framework-agnostic and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | --------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/SpherePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/SpherePrimitive.msg) | +| ROS 2 | [foxglove_msgs/msg/SpherePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/SpherePrimitive.msg) | +| JSON | [foxglove.SpherePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/SpherePrimitive.json) | +| Protobuf | [foxglove.SpherePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/SpherePrimitive.proto) | +| FlatBuffers | [foxglove.SpherePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/SpherePrimitive.fbs) | +| OMG IDL | [foxglove::SpherePrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/SpherePrimitive.idl) | + +You must use the data structure names specified above so that visualizations can recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/text-annotation.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/text-annotation.md new file mode 100644 index 000000000..28dfa79e8 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/text-annotation.md @@ -0,0 +1,37 @@ +# TextAnnotation + +Text labels on 2D images + +## Parent Data Structure + +`TextAnnotation` appears in the [`ImageAnnotations`](./image-annotations) message data structure. + +## Data Structure + +| Field | Type | Description | +| ---------------- | --------------------------------------- | -------------------------------------------------------------------- | +| timestamp | [`time`](./built-in%20types#time) | Timestamp of the annotation | +| position | [`Point2`](./point-2) | Lower-left origin of the text label in 2D image coordinates (pixels) | +| text | [`string`](./built-in%20types#string) | Text to display | +| font_size | [`float64`](./built-in%20types#float64) | Font size (pixels) | +| text_color | [`color`](./color) | Text color | +| background_color | [`color`](./color) | Background fill color | + +### `position` + +Coordinates use the top-left corner of the top-left pixel of the image as the origin. + +## Reference Implementation + +Visualization data structures are framework-agnostic and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/TextAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/TextAnnotation.msg) | +| ROS 2 | [foxglove_msgs/msg/TextAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/TextAnnotation.msg) | +| JSON | [foxglove.TextAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/TextAnnotation.json) | +| Protobuf | [foxglove.TextAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/TextAnnotation.proto) | +| FlatBuffers | [foxglove.TextAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/TextAnnotation.fbs) | +| OMG IDL | [foxglove::TextAnnotation](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/TextAnnotation.idl) | + +You must use the data structure names specified above so that visualizations can recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/text-primitive.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/text-primitive.md new file mode 100644 index 000000000..fd69559ad --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/text-primitive.md @@ -0,0 +1,33 @@ +# TextPrimitive + +A primitive representing text labels + +## Parent Data Structure + +`TextPrimitive` appears in the [`SceneEntity`](./scene-entity) message data structure. + +## Data Structure + +| Field | Type | Description | +| --------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| pose | [`pose`](./pose) | Position of the text box center and orientation of the text. Unit orientation means text flows in the xy-plane, from -x toward +x | +| billboard | [`boolean`](./built-in%20types#boolean) | Whether the text should follow pose.orientation (false) or always face the camera (true) | +| font_size | [`float64`](./built-in%20types#float64) | Font size (height of a line of text) | +| scale_invariant | [`boolean`](./built-in%20types#boolean) | Indicates whether font_size is a fixed size in screen pixels (true), or specified in world coordinates and scales with camera distance (false) | +| color | [`color`](./color) | Text color | +| text | [`string`](./built-in%20types#string) | Text content | + +## Reference Implementation + +Visualization data structures are framework-agnostic and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/TextPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/TextPrimitive.msg) | +| ROS 2 | [foxglove_msgs/msg/TextPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/TextPrimitive.msg) | +| JSON | [foxglove.TextPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/TextPrimitive.json) | +| Protobuf | [foxglove.TextPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/TextPrimitive.proto) | +| FlatBuffers | [foxglove.TextPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/TextPrimitive.fbs) | +| OMG IDL | [foxglove::TextPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/TextPrimitive.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/triangle-list-primitive.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/triangle-list-primitive.md new file mode 100644 index 000000000..023336fae --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/triangle-list-primitive.md @@ -0,0 +1,36 @@ +# TriangleListPrimitive + +Represents a primitive that consists of a set of triangles or a surface tiled with triangles. + +## Parent Data Structure + +`TriangleListPrimitive` appears in the [`SceneEntity`](./scene-entity) message data structure. + +## Data Structure + +| Field | Type | Description | +| ------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| pose | [`pose`](./pose) | Origin of the triangles relative to the reference coordinate frame | +| points | [`Point3[]`](./point-3) | Vertices for the triangles, interpreted as a list of triplets (0-1-2, 3-4-5, ...) | +| color | [`color`](./color) | Solid color for the entire shape. Either color or colors must be provided. | +| colors | [`Color[]`](./color) | Color for each vertex (if specified, must be the same length as points). Either color or colors must be provided. | +| indices | [`uint32[]`](./built-in%20types#uint32) | Indices into the points and colors attribute arrays, which can be used to avoid duplicating attribute data. | + +### `indices` + +If omitted or empty, no indices are used. This default behavior is equivalent to specifying [0, 1, ..., N-1] for the indices (where N is the number of `points` provided). + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/TriangleListPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/TriangleListPrimitive.msg) | +| ROS 2 | [foxglove_msgs/msg/TriangleListPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/TriangleListPrimitive.msg) | +| JSON | [foxglove.TriangleListPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/TriangleListPrimitive.json) | +| Protobuf | [foxglove.TriangleListPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/TriangleListPrimitive.proto) | +| FlatBuffers | [foxglove.TriangleListPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/TriangleListPrimitive.fbs) | +| OMG IDL | [foxglove::TriangleListPrimitive](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/TriangleListPrimitive.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/vector-2.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/vector-2.md new file mode 100644 index 000000000..44eee94b3 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/vector-2.md @@ -0,0 +1,29 @@ +# Vector2 + +Represents a vector in two-dimensional space that indicates direction only. + +## Parent Data Structure + +`Vector2` appears in the [`Grid`](./grid) message data structure. + +## Data Structure + +| Field | Type | Description | +| ----- | --------------------------------------- | ------------------- | +| x | [`float64`](./built-in%20types#float64) | x coordinate length | +| y | [`float64`](./built-in%20types#float64) | y coordinate length | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------------- | +| ROS 1 | [foxglove_msgs/Vector2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros1/Vector2.msg) | +| ROS 2 | [foxglove_msgs/msg/Vector2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/ros2/Vector2.msg) | +| JSON | [foxglove.Vector2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/Vector2.json) | +| Protobuf | [foxglove.Vector2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/Vector2.proto) | +| FlatBuffers | [foxglove.Vector2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/Vector2.fbs) | +| OMG IDL | [foxglove::Vector2](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/Vector2.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/vector-3.md b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/vector-3.md new file mode 100644 index 000000000..b6368f719 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/viz/9-message-schemas/vector-3.md @@ -0,0 +1,30 @@ +# Vector3 + +Represents a three-dimensional vector in space that contains only direction. + +## Parent Data Structure + +`Vector3` appears in the following data structures: [`CubePrimitive`](./cube-primitive), [`CylinderPrimitive`](./cylinder-primitive), [`FrameTransform`](./frame-transform), [`ModelPrimitive`](./model-primitive), [`pose`](./pose), and [`SpherePrimitive`](./sphere-primitive). + +## Data Structure + +| Field | Type | Description | +| ----- | --------------------------------------- | ------------------- | +| x | [`float64`](./built-in%20types#float64) | x coordinate length | +| y | [`float64`](./built-in%20types#float64) | y coordinate length | +| z | [`float64`](./built-in%20types#float64) | z coordinate length | + +## Reference Implementation + +The visualization data structure is framework-independent and can be implemented using any supported message encoding: + +| Encoding | Data Structure | +| ----------- | ----------------------------------------------------------------------------------------------------------- | +| ROS 1 | [geometry_msgs/Vector3](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Vector3.html) | +| ROS 2 | [geometry_msgs/msg/Vector3](https://docs.ros2.org/galactic/api/geometry_msgs/msg/Vector3.html) | +| JSON | [foxglove.Vector3](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/jsonschema/Vector3.json) | +| Protobuf | [foxglove.Vector3](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/proto/foxglove/Vector3.proto) | +| FlatBuffers | [foxglove.Vector3](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/flatbuffer/Vector3.fbs) | +| OMG IDL | [foxglove::Vector3](https://github.com/foxglove/foxglove-sdk/blob/main/schemas/omgidl/foxglove/Vector3.idl) | + +You must use the data structure names specified above for the visualization to recognize the data structure. diff --git a/i18n/en/docusaurus-plugin-content-pages/changelog.md b/i18n/en/docusaurus-plugin-content-pages/changelog.md index 05283699a..cc69920a0 100644 --- a/i18n/en/docusaurus-plugin-content-pages/changelog.md +++ b/i18n/en/docusaurus-plugin-content-pages/changelog.md @@ -131,7 +131,7 @@ id: changelog - Fixed an issue where record search results were not sorted by time. - Fixed an issue where the index generation status was not correctly displayed in the visualization page. - Fixed an issue with abnormal display of test suite lists in batch testing. -- Fixed an issue with abnormal device traffic statistics. This can be resolved by updating the data collection client to version v1.0.2. [View update instructions](https://docs.coscene.cn/docs/recipes/device/device-collector#%E6%9B%B4%E6%96%B0%E8%AE%BE%E7%BD%AE) +- Fixed an issue with abnormal device traffic statistics. This can be resolved by updating the data collection client to version v1.0.2. --- diff --git a/i18n/en/docusaurus-theme-classic/footer.json b/i18n/en/docusaurus-theme-classic/footer.json index bfa1812d2..7352bcd4c 100644 --- a/i18n/en/docusaurus-theme-classic/footer.json +++ b/i18n/en/docusaurus-theme-classic/footer.json @@ -29,19 +29,19 @@ }, "link.item.label.隐私政策": { "message": "Privacy Policy", - "description": "The label of footer link with label=隐私政策 linking to /legal/privacy/zh/privacy.html" + "description": "The label of footer link with label=隐私政策 linking to /legal/privacy" }, "link.item.label.服务协议": { "message": "Terms of Service", - "description": "The label of footer link with label=服务协议 linking to /legal/terms/zh/terms.html" + "description": "The label of footer link with label=服务协议 linking to /legal/terms" }, "link.item.label.刻行数据安全白皮书": { "message": "coScene Data Security White Paper", - "description": "The label of footer link with label=刻行数据安全白皮书 linking to /security/security-white-paper/en/security-white-paper.html" + "description": "The label of footer link with label=刻行数据安全白皮书 linking to /security/security-white-paper" }, "link.item.label.刻行数据安全方案": { "message": "coScene Data Security Solution", - "description": "The label of footer link with label=刻行数据安全方案 linking to /security/data-security-solution/en/data-security-solution.html" + "description": "The label of footer link with label=刻行数据安全方案 linking to /security/data-security-solution" }, "link.title.法律协议": { "message": "Legel", diff --git a/package.json b/package.json index 8c9596774..f0d2e3187 100644 --- a/package.json +++ b/package.json @@ -4,6 +4,7 @@ "author": "minico", "scripts": { "start": "docusaurus start", + "dev": "docusaurus start", "start:en": "pnpm run start --locale en", "clear": "docusaurus clear", "build": "docusaurus build", @@ -50,4 +51,4 @@ "engines": { "node": ">= 20" } -} +} \ No newline at end of file diff --git a/src/components/homeCatalogue/catalogue.ts b/src/components/homeCatalogue/catalogue.ts index c6c49ef6d..052b58c8e 100644 --- a/src/components/homeCatalogue/catalogue.ts +++ b/src/components/homeCatalogue/catalogue.ts @@ -1,6 +1,6 @@ import { translate } from '@docusaurus/Translate'; -export const CATALOGUE = [ +export const CATALOGUE = (local: string) => [ { header: { title: translate({ id: 'home.catalogue.getting-started', message: '新手入门' }) }, docs: [ @@ -52,13 +52,15 @@ export const CATALOGUE = [ docLink: '/viz/frame-rate-optimization', title: translate({ id: 'home.catalogue.frame-rate-optimization', message: '帧率优化选项' }), }, - ...(typeof process !== 'undefined' && process.env.DOCUSAURUS_CURRENT_LOCALE === 'zh' ? [ - { docLink: '/category/extensions', title: translate({ id: 'home.catalogue.extensions', message: '插件' }) }, - { - docLink: '/viz/message-schemas', - title: translate({ id: 'home.catalogue.message-schemas', message: '消息架构' }), - }, - ] : []), + ...(local === 'zh' + ? [ + { docLink: '/category/extensions', title: translate({ id: 'home.catalogue.extensions', message: '插件' }) }, + { + docLink: '/viz/message-schemas', + title: translate({ id: 'home.catalogue.message-schemas', message: '消息架构' }), + }, + ] + : []), ], }, { diff --git a/src/components/homeCatalogue/index.tsx b/src/components/homeCatalogue/index.tsx index 59caa4821..a169dc17d 100644 --- a/src/components/homeCatalogue/index.tsx +++ b/src/components/homeCatalogue/index.tsx @@ -1,6 +1,7 @@ import React from 'react'; import { CATALOGUE } from './catalogue'; import Link from '@docusaurus/Link'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; interface DocSlugProps { title: string; @@ -53,9 +54,11 @@ function Card({ catalogue }: { catalogue: { header: { title: string }; docs: Doc } export default function HomeCatalogue() { + const { i18n } = useDocusaurusContext(); + return (
- {CATALOGUE.map((item, index) => ( + {CATALOGUE(i18n.currentLocale).map((item, index) => ( ))}
diff --git a/src/pages/changelog.md b/src/pages/changelog.md index d509325d9..ba4a7d51e 100644 --- a/src/pages/changelog.md +++ b/src/pages/changelog.md @@ -230,7 +230,7 @@ id: changelog - 新增「可视化图表按当前时间戳播放」功能：在可视化图表的「面板设置-X 轴-值」中，切换为「时间戳（当前）」，即可跟随时间轴同步播放曲线数据 - 新增「关联项目数量」功能：在组织设备列表中，展示关联项目数量 - 新增「项目按星标排序」功能：在组织项目列表中，支持按照是否星标对项目进行排序 -- 新增「复制项目 Slug 与网址」功能：在首页的项目卡片-更多操作中，支持复制项目 Slug 用于 [coCLI 本地命令行工具](https://docs.coscene.cn/docs/category/cocli)；支持复制项目网址分享项目 +- 新增「复制项目 Slug 与网址」功能：在首页的项目卡片-更多操作中，支持复制项目 Slug 用于 [命令行工具 coCLI](/docs/category/cocli)；支持复制项目网址分享项目 ### 【改变】 @@ -271,7 +271,7 @@ id: changelog - 修复记录搜索时未按时间排序的问题 - 修复可视化页面中未正确展示索引生成状态的问题 - 修复批量测试中测试套件列表显示异常的问题 -- 修复设备流量统计异常的问题，更新数采客户端到 v1.0.2 版本即可解决该问题，[查看更新说明文档](https://docs.coscene.cn/docs/recipes/device/device-collector#%E6%9B%B4%E6%96%B0%E8%AE%BE%E7%BD%AE) +- 修复设备流量统计异常的问题，更新数采客户端到 v1.0.2 版本即可解决该问题 --- @@ -419,7 +419,7 @@ id: changelog - 新增「关联动作」过滤功能：在调用日志页面，支持按照关联动作过滤调用历史 - 新增「触发器支持修改系统动作参数」功能：在创建 / 编辑触发器时，使用系统动作后可以修改默认参数 - 新增「隐藏文件」的显示功能：在记录文件列表、自动化输出、批量测试输出的文件中，支持显示 / 隐藏以点开头的文件或文件夹 -- 新增「命令行工具」：支持在本地执行命令实现：创建记录、上传下载文件、给记录打标签、过滤记录、对记录执行动作等操作，详情请参见文档：[命令行工具 CLI](https://docs.coscene.cn/docs/category/cocli) +- 新增「命令行工具」：支持在本地执行命令实现：创建记录、上传下载文件、给记录打标签、过滤记录、对记录执行动作等操作，详情请参见文档：[命令行工具 CLI](/docs/category/cocli) ### 【改变】