flutter_mcap_parser #

一个高性能的 Flutter MCAP 文件解析库。底层基于 Rust 开发，通过 flutter_rust_bridge 连接，专为处理机器人日志数据（如 ROS 2 / Foxglove）设计。

✨ 特性 #

• 🚀 高性能：核心解析逻辑由 Rust 编写，通过 FFI 调用，解析速度极快且内存安全。
• 🛠️ 全面支持：支持读取 Schema, Channel, Message, Metadata, Attachment 等所有 MCAP 核心记录。
• 📂 多种输入源：支持从 文件路径、内存二进制 (Uint8List) 或 Flutter Assets 读取。
• ⚡️ 按需解析：智能优化策略。只有当你传入了对应的回调函数时（例如 onMessage），底层才会去解析该类型的数据，最大化提升性能。
• 🌊 流式处理：基于 Dart Stream 和 Rust StreamSink，不会阻塞 UI 线程。

📦 安装 #

1. 在 pubspec.yaml 中添加依赖：

dependencies:
  flutter_mcap_parser: ^0.1.0 # 请替换为实际版本

2. 确保你的 Flutter 环境已经配置好 Rust 编译环境（如果你是从源码编译）。

🚀 快速开始 #

1. 初始化 #

在使用任何解析功能之前，必须先调用初始化方法。通常建议在 main() 函数中完成。

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 初始化底层 Rust 库
  await McapParser.init();

  runApp(const MyApp());
}

2. 读取本地文件 #

这是最常用的方式，适用于处理存储设备上的大文件。

import 'package:flutter_mcap_parser/flutter_mcap_parser.dart';

void parseFile() {
  McapParser.parseFromPath(
    "/sdcard/logs/robot_data.mcap",
    // 监听 Channel 信息
    onChannel: (channel) {
      print("发现话题: ${channel.topic} (SchemaID: ${channel.schemaId})");
    },
    // 监听 Schema 定义
    onSchema: (schema) {
      print("发现数据定义: ${schema.name} (${schema.encoding})");
    },
    // 监听具体消息
    onMessage: (message) {
      print("收到消息: 话题ID=${message.channelId}, 时间=${message.publishTime}");
      // message.data 是 Uint8List，需要根据 schema 解码
    },
    // 错误处理
    onError: (err) => print("解析出错: $err"),
    // [必填] 解析结束回调
    onEnd: () {
      print("✅ 文件解析完成");
    },
  );
}

3. 读取 Flutter Assets #

适用于读取打包在 App 内的示例数据或配置文件。

void parseAsset() {
  McapParser.parseFromAssets(
    "assets/sample.mcap",
    onMetadata: (meta) {
      print("元数据: ${meta.metadata}");
    },
    onEnd: () => print("Assets 解析结束"),
  );
}

4. 读取内存数据 (Bytes) #

适用于网络下载或通过其他方式获取到的二进制流。

void parseBytes(Uint8List mcapData) {
  McapParser.parseFromBytes(
    mcapData,
    onMessage: (msg) {
      // 处理消息...
    },
    onEnd: () => print("内存数据解析结束"),
  );
}

📖 API 参考 #

McapParser #

static Future init()

初始化 FFI 绑定。必须在使用前调用一次。

解析方法

所有解析方法都支持以下命名参数（回调函数）。注意：只有传入了非空的回调，底层才会解析对应的数据类型。

方法签名

1. parseFromPath(String path, { ... })

   • 直接在 Rust 层打开文件，性能最高，内存占用最低。推荐用于大文件。

2. parseFromAssets(String assetsKey, { ... })

   • 使用 rootBundle 加载 Asset 并转换为 Uint8List 传给底层。

3. parseFromBytes(Uint8List bytes, { ... })

   • 直接解析内存中的二进制数据。

⚠️ 注意事项 #

1. 性能优化提示：如果你只关心话题列表（Channel），请不要传入 onMessage 回调。这样解析器会直接跳过所有消息数据块（Chunk），解析速度会提升 100 倍以上。
2. 主线程阻塞：虽然解析是在 Rust 线程池或异步流中进行的，但在回调极其频繁的情况下（如每秒 10 万条消息），Dart 端的 onMessage 执行可能会占用较多 UI 线程资源。建议在回调中进行轻量级处理。

🤝 贡献 #

欢迎提交 Issue 和 Pull Request！