Pickle 解析器

@ticos/pickle 是 Ticos 生态中用于处理 Python Pickle 数据格式的高效解析库。在机器人领域，许多传感器数据、运动轨迹和感知结果通常以 Python 的 Pickle 格式序列化。该库允许你在浏览器或 Node.js 环境中直接解析这些数据，而无需依赖 Python 环境。

为什么需要它？

• 跨语言协同：机器人底层的感知与规划通常使用 Python (ROS/PyTorch)，而前端 Web 界面或云端服务通常使用 TypeScript。
• 高性能：直接在 JavaScript 中解析二进制数据，减少了通过中间格式（如 JSON）转换的开销。
• NumPy 支持：专门针对 NumPy 数组进行了优化，能自动恢复数组形状（Shape）并转换为 TypedArray。

核心特性

• ✅ 支持所有 Pickle 协议 (0-5)
• ✅ 自动检测并转换 NumPy 数组与形状
• ✅ 处理 float32, float64, int32, int64 等多种数据类型
• ✅ 兼容浏览器与 Node.js 环境

安装

在你的项目中安装该 Workspace 包：

pnpm add @ticos/pickle

快速上手

在 Node.js 中使用

import { parsePickle } from "@ticos/pickle";
import fs from "fs";

// 读取 .pkl 文件
const fileBuffer = fs.readFileSync("sensor_data.pkl");
const data = parsePickle(fileBuffer);

console.log(data); // 输出解析后的 JavaScript 对象

在浏览器中使用

import { parsePickle } from "@ticos/pickle";

const handleFileChange = async (event) => {
  const file = event.target.files[0];
  const arrayBuffer = await file.arrayBuffer();
  const uint8Array = new Uint8Array(arrayBuffer);

  // 解析数据
  const data = parsePickle(uint8Array);
  console.log("Parsed Data:", data);
};

API 参考

parsePickle(data: Buffer | Uint8Array): any

解析 Pickle 二进制数据并返回反序列化后的 JavaScript 对象。

参数：

• data: 包含 Pickle 数据的 Buffer (Node.js) 或 Uint8Array (浏览器)。

返回值：

• 反序列化后的 JavaScript 对象。NumPy 数组将被转换为包含 data (TypedArray) 和 shape (Array) 属性的对象。

交互式调试

Ticos 平台内置了可视化调试工具。你可以将本地的 .pkl 文件上传到 Lab → Rewind 页面进行实时解析与可视化展示。

实验室环境：使用 Pickle 解析器回放机器人历史轨迹