XGRIDS文档
  • 简体中文
  • English
  • 繁體中文
  • 日本語
  • Deutsch
  • Español
  • Italiano
  • Français
  • Русский
  • 简体中文
  • English
  • 繁體中文
  • 日本語
  • Deutsch
  • Español
  • Italiano
  • Français
  • Русский
  • 灵视 P1

    • 产品概述
    • 设备基本操作
    • 使用 LCC Scan App
    • 维护及保养
    • 常见问题
  • 灵光 K 系列

    • 灵光 K1

      • 产品概述
      • 设备基本操作
      • 设备激活与连接
      • 设备采集
      • 获取绝对坐标点云数据
      • 地图融合
      • 典型场景路线规划建议
      • 注意事项
      • 常见问题
    • 灵光 K2

      • 产品概述
      • 设备基本操作
      • 设备激活与连接
      • 设备采集
      • 获取绝对坐标点云数据
      • 地图融合
      • 典型场景路线规划建议
      • 注意事项
      • 常见问题
  • 灵光 L 系列

    • 灵光 L2 Pro

      • 产品概述
      • 设备基本操作
      • 设备激活与连接
      • 设备采集
      • 获取绝对坐标点云数据
      • 实时测量功能
      • 附录
      • 常见问题
  • 配件

    • 补光灯

      • 安装指导
      • 基本操作
      • 常见问题
  • Lixel Studio

    • 版权
    • 安装与激活
    • 界面说明
    • 文件
    • 工程处理
    • 工具
    • 平面绘制
    • 行业应用
    • 设置
    • 设备感知
  • Lixel CyberColor

    • LCC Studio

      • 入门
      • 版本与更新
      • 下载与安装
      • 界面概览与导航
      • 重建前工作
      • 模型重建
      • 单模型重建
      • 地图融合
      • 空地融合
      • 航拍重建
      • 我的模型
      • 其他功能
      • 设置与账号
      • 转换工具
      • 视频重建
      • 常见问题 / FAQ
    • LCC Scene Editor

      • 版本与更新
      • 账号与登录
      • 产品概览与主页
      • 编辑器界面介绍
      • 三种场景漫游快捷操作
      • 文件
      • 设置
      • 编辑操作
      • 窗口
      • 视图工具栏
      • 资产与属性
      • 左侧工具栏
      • 视点
      • 跳转点
      • 天空盒
      • 标注
      • 测量
      • 场景漫游
      • 场景报告
      • 智能户型图(3D Layout)
      • 小地图
      • 预览模式(Viewer)
      • 帮助
      • 常见问题 / FAQ
      • 出生点
    • LCC Model Editor

      • 版本与更新
      • 新手指引
      • 概览与界面
      • 文件操作
      • 选择器
      • 编辑操作
      • 测量
      • 调色
      • 资产管理
      • 设置与帮助
      • 常见问题 / FAQ
    • 采集指南

      • 概述
      • 采集设备总览
      • 通用采集原则
      • 室内场景采集
      • 室外场景采集
      • 大场景采集(地图融合)
      • 空地融合采集
      • 物体采集
      • 人物采集
      • 视频重建采集
      • 高清补拍
      • 控制点(灵视 P1)
      • 常见问题与排查
    • LCC Studio Linux

      • 产品概要说明
      • 基本架构说明书
      • 安装部署说明书
      • 容器启动参数说明书
      • CodeMeter离线授权部署说明书
      • API指令集说明书
      • 附录-开发者数据说明书
      • 附录-错误码列表
      • 单机多卡集群部署QuickStart
    • 使用技巧

      • 多个大型 3DGS 模型融合工作流
    • 历史版本
  • Plugin & SDK

    • Unreal

      • 介绍
      • 快速入门 - Windows
      • 快速入门 - Linux
      • 快速入门 - Quest3
      • 版本与授权
      • 渲染
      • Tiled 光栅化(实验性)
      • 画面调节
      • 法线与光照
      • 场景编辑
      • 性能参数说明
      • 性能优化指南
      • 第三方与引擎插件集成
      • 代理网格
      • 加载动画
      • 碰撞
      • 寻路系统支持
      • 单层水支持
      • 本地化
      • 常见问题
      • 故障排查
      • 日志与诊断
      • 联系我们
      • 最佳实践

        • 用 LixelStudio 网格为 3DGS 重打光
      • API 参考

        • ALCCActorBase
        • ULCCComponentBase
        • ULCCComponent
        • ULCC2Component
        • SOG / SPZ / PLY Actors
        • ALCC2ProxyMesh
        • ALCCClippingVolume
        • ALCCSectionPlane
        • ALCCLoadVolume
        • ULCCUtilLibrary
        • Enums
        • Structs
      • 更新日志

        • v3.4.0
        • v3.3.1
        • v3.0.0
        • v2.2.1
        • v1.0.0
        • v0.9.0
        • v0.8.0
        • v0.7.1
        • v0.6.1
        • v0.5.2
        • v0.4.1
        • v0.4.0
        • v0.3.0
        • v0.0.5
        • v0.0.4
        • v0.0.3
        • v0.0.2
        • v0.0.1
    • X-Brain

      • 产品概述
      • 硬件接口
      • 快速开始
      • 核心概念
      • 集成指南
      • API 参考
      • 数据类型
      • ROS2 桥接
      • 示例程序
      • 部署与网络
      • 排障与 FAQ
      • 版本与发布
    • Web

      • 介绍
      • 渲染性能优化指南
      • 显卡配置
      • 常见开发问题
      • API参考

        • LCCRender::clearIndexDB
        • LCCRender::dispose
        • LCCRender::load
        • LCCRender::setCamera
        • LCCRender::unload
        • LCCRender::update
        • LCCObject::checkRenderNextFrame
        • LCCObject::clearRenderNextFrame
        • LCCObject::ecef2Prj
        • LCCObject::getBounds
        • LCCObject::getEnvInstancedMesh
        • LCCObject::getInstancedMesh
        • LCCObject::getLodInfos
        • LCCObject::getOriginPosition
        • LCCObject::getProjectionCoordinateSystemInfos
        • LCCObject::hasCollision
        • LCCObject::hasEnvironment
        • LCCObject::hasShcoef
        • LCCObject::intersectsCapsule
        • LCCObject::intersectsRayExt
        • LCCObject::intersectsRayFromOriginExt
        • LCCObject::intersectsSphere
        • LCCObject::lowerToBottom
        • LCCObject::prj2Ecef
        • LCCObject::raiseToTop
        • LCCObject::raycast
        • LCCObject::raycastFromOrigin
        • LCCObject::setAlpha
        • LCCObject::setClipBox
        • LCCObject::setClipPlane
        • LCCObject::setEndLod
        • LCCObject::setLodAutoLevelUp
        • LCCObject::setMaxDistance
        • LCCObject::setMaxNodeSplats
        • LCCObject::setMaxSplats
        • LCCObject::setOriginPosition
        • LCCObject::setPointsColor
        • LCCObject::setRenderState
        • LCCObject::setRotation
        • LCCObject::setScale
        • LCCObject::setSemantic
        • LCCObject::setSemanticColor
        • LCCObject::setSmooth
        • LCCObject::setStartLod
        • LCCObject::setTranslation
        • LCCObject::setVisible
        • LCCObject::togglePointsDisplayMode
        • LCCObject::useEnvironment
        • LCCObject::useShcoef
      • 更新日志

        • v0.6.3
        • v0.6.2
        • v0.6.1
        • v0.6.0
        • v0.5.5
        • v0.5.4
        • v0.5.3
        • v0.5.2
        • v0.5.1
        • v0.5.0
        • v0.4.1
        • v0.4.0
        • v0.3.1
        • v0.3.0
        • v0.2.0

快速开始

本篇带你从零跑通 XGRIDS 设备的数据订阅与录制控制,提供两条路径:

  • 路径 A — C/C++:直接链接 liblixel_sdk.so 调 API。
  • 路径 B — ROS2:用自带的桥接节点,把设备数据转成标准 ROS2 Topic。

逐字段接口契约见 API 参考;坐标系概念见 核心概念。

文档中的占位符

本手册的命令示例里有几个尖括号占位符,实际使用时请替换成你自己的值:

占位符含义替换示例
<sdk>你解压/放置 SDK 的根目录(里面有 include/、lib/、bin/ 等)/home/user/x-brain-sdk
<arch>目标机的 CPU 架构,取 x86_64 或 aarch64(用 uname -m 查)x86_64
<Device IP>X-Brain 设备的 IP 地址192.168.123.103

例如 -L<sdk>/lib/<arch> 在 x86_64 机器上、SDK 放在 /home/user/x-brain-sdk 时,实际是 -L/home/user/x-brain-sdk/lib/x86_64。

环境与前提

项要求
操作系统Linux x86_64 / aarch64
glibcx86_64 ≥ 2.34;aarch64 ≥ 2.30(ldd --version 查看)
网络主机与设备同一交换机直连,设备端口(默认 7448)可达(详见 部署与网络)
交付物include/(头文件)、lib/<arch>/liblixel_sdk.so、bin/<arch>/(预编译示例)、examples/、ros2/
ROS2(仅路径 B)Humble(Ubuntu 22.04)或 Foxy(Ubuntu 20.04),需 Eigen3

先做连通性自检(open() 超时最常见的原因就是这一步没过):

ping <Device IP>                 # 网络与网段(<Device IP> 换成你的设备 IP,如 192.168.123.103)
nc -z <Device IP> 7448 && echo OK # 设备端口可达

注:SDK 只连一个端口(默认 7448)。数据面(位姿/点云/IMU/图像/错误码)与命令面(录制启停、状态查询)都在同一会话。若设备端改过端口,把 Options.port / device_port 直接填其实际端口即可。网络与端口的完整说明见 部署与网络,连不上时见 排障与 FAQ。

读数据前必须知道的三件事

  1. 坐标系 = 设备(IMU)系:SDK 输出的位姿/点云,原点在设备 IMU 点,遵循右手系(x 前 / y 左 / z 上)。载体(机器狗/车/无人机)的安装变换由你自己补一层 TF。详见 核心概念 · 坐标系。
  2. 两种点云不是一回事:subscribeCloud 是重定位配准点云(~10Hz,设备系,NDT 产物);subscribeRawCloud 是原始的单帧雷达扫描(~10Hz,未去畸变、带运动畸变)。要每帧扫描用后者。详见 核心概念 · 两种点云。
  3. 录制启停只下发、不等待:startRecord() 返回成功仅表示命令被接受;进入 Recording 需轮询确认;而 Recording 也 不等于 定位就绪。详见 核心概念 · 录制语义。

路径 A — C/C++

编译

# <sdk>  取你放置 SDK 的根目录,如 /home/user/x-brain-sdk
# <arch> 取 x86_64 或 aarch64,与目标机架构一致(用 uname -m 查)
g++ -std=c++17 my_app.cpp \
    -I<sdk>/include \
    -L<sdk>/lib/<arch> -llixel_sdk \
    -Wl,-rpath,'$ORIGIN/lib/<arch>' \
    -o my_app

-rpath 已内嵌库路径;或运行前 export LD_LIBRARY_PATH=<sdk>/lib/<arch>。

命令里的 <sdk> / <arch> 是占位符,替换成你的实际值,含义见上方 文档中的占位符。更完整的编译链接说明见 集成指南。

最小示例:连接 → 订阅位姿 → 断开

#include "xg/robot_sdk.h"
#include <cstdio>
#include <thread>
#include <chrono>

int main() {
    xg::Options opts;
    opts.deviceIp = "192.168.123.103";   // 改成你的设备 IP
    // opts.port = 0;                     // 0 = 默认 7448
    // opts.connectTimeoutMs = 0;         // 0 = 默认 5000ms

    xg::Error err = xg::Error::Ok;
    auto dev = xg::Device::open(opts, &err);
    if (!dev) {
        std::printf("连接失败: %s\n", xg::toString(err));
        return 1;
    }

    // 回调在 SDK 内部线程触发,勿阻塞
    dev->subscribePose([](const xg::Pose& p) {
        std::printf("t=%.3f pos=(%.3f, %.3f, %.3f)\n",
                    p.timestampSec, p.posX, p.posY, p.posZ);
    });

    std::this_thread::sleep_for(std::chrono::seconds(10));
    return 0;   // dev 析构自动取消订阅并断开,无需手动 close
}
  • Device 由 unique_ptr 持有,析构自动收尾;禁止拷贝/移动,同一实例不可重入(多线程自行加锁)。

录制启停(只下发 + 轮询确认)

if (dev->startRecord() != xg::Error::Ok) {
    // Timeout 时命令可能已送达,禁止直接重发,先 queryRecordStatus 再决定
}
xg::RecordStatus st;
while (true) {
    std::this_thread::sleep_for(
        std::chrono::milliseconds(XG_RECOMMENDED_POLL_INTERVAL_MS));  // 500ms
    if (dev->queryRecordStatus(&st) != xg::Error::Ok) continue;
    if (st.state == xg::RecordState::Recording) break;
    if (st.state == xg::RecordState::Error)     break;   // 处理故障
}

完整状态机见示例 record_demo.cpp(示例程序)。

可订阅的数据

所有订阅同构:subscribeXxx(回调) / unsubscribeXxx(),每类占一个订阅槽,重复订阅返回 Rejected。各数据的频率、坐标系、结构体见 核心概念,逐接口契约见 API 参考。

dev->subscribeCloud([](const xg::CloudFrame& f) {
    // f.points 指向 SDK 内部缓冲,仅本次回调有效!留用须拷贝:
    // std::vector<xg_point_t> saved(f.points, f.points + f.count);
    std::printf("cloud: %zu points\n", f.count);
});
dev->subscribeImu([](const xg::Device::Imu& imu) {          // 纯标量,可按值保存
    std::printf("acc=(%.2f,%.2f,%.2f)\n", imu.accX, imu.accY, imu.accZ);
});
dev->subscribeImage(xg::Device::CameraId::Left,
    [](const xg::Device::ImageFrame& f) {                   // jpegData 仅回调内有效
        std::printf("jpeg: %zu bytes\n", f.jpegSize);
    });

回调内存三条铁律

回调在 SDK 内部线程触发:

  1. 不要阻塞(会拖住整个会话线程,影响所有订阅);重活拷贝后转交自己的线程。
  2. 变长指针只在回调期内有效(CloudFrame::points、ImageFrame::jpegData 指向复用缓冲,下一帧覆盖);留用必须回调内深拷贝。
  3. 不要 free/delete 回调里的任何指针(不是你分配的)。

按值类型(Pose/Imu)可整体保存。详见集成指南。

路径 B — ROS2

用自带桥接节点把数据转成标准 ROS2 Topic,适合已有 ROS2 工作流的用户。

编译

# <sdk> 取你放置 SDK 的根目录,如 /home/user/x-brain-sdk
mkdir -p ~/ros2_ws/src
ln -sf <sdk>/ros2 ~/ros2_ws/src/lixel_sdk_ros2

cd ~/ros2_ws
source /opt/ros/humble/setup.bash
colcon build --packages-select lixel_sdk_ros2

运行

source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash
# <sdk> 取 SDK 根目录,<arch> 取 x86_64 或 aarch64(与目标机架构一致)
export LD_LIBRARY_PATH=<sdk>/lib/<arch>:$LD_LIBRARY_PATH

ros2 launch lixel_sdk_ros2 sdk_bridge.launch.py device_ip:=192.168.123.103

节点启动后自动连接设备并启动录制,进入录制状态后开始发布数据;Ctrl+C 退出时自动停录并断开。

查看数据

ros2 topic list             # 查看话题
ros2 topic hz /lixel/odom   # 确认位姿在发
ros2 topic echo /lixel/odom # 查看位姿内容

完整 Topic 列表与 TF 结构见 ROS2 桥接。

下一步

  • 遇到 0 帧、连不上、坐标不对 → 排障与 FAQ
  • 理解坐标系与时基 → 核心概念
  • 逐接口契约 → API 参考