Pickle Parser

@ticos/pickle is a high-performance library for handling Python Pickle data within the Ticos ecosystem. In robotics, sensor data, movement trajectories, and perception results are often serialized using Python’s Pickle format. This library allows you to parse this data directly in the browser or Node.js environment without needing a Python backend.

Why Use It?

• Cross-Language Collaboration: Robot perception and planning typically use Python (ROS/PyTorch), while web frontends or cloud services use TypeScript.
• High Performance: Parses binary data directly in JavaScript, eliminating the overhead of converting to intermediate formats like JSON.
• NumPy Support: Optimized for NumPy arrays, automatically recovering shapes and converting them to TypedArrays.

Core Features

• ✅ Supports all Pickle protocols (0-5)
• ✅ Automatic detection and conversion of NumPy arrays and shapes
• ✅ Handles float32, float64, int32, int64, and other data types
• ✅ Compatible with both Browser and Node.js environments

Installation

Install the workspace package in your project:

pnpm add @ticos/pickle

Quick Start

Usage in Node.js

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

// Read a .pkl file
const fileBuffer = fs.readFileSync("sensor_data.pkl");
const data = parsePickle(fileBuffer);

console.log(data); // Outputs the deserialized JavaScript object

Usage in the Browser

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);

  // Parse the data
  const data = parsePickle(uint8Array);
  console.log("Parsed Data:", data);
};

API Reference

parsePickle(data: Buffer | Uint8Array): any

Parses Pickle binary data and returns the deserialized JavaScript object.

Parameters:

• data: A Buffer (Node.js) or Uint8Array (browser) containing the Pickle data.

Returns:

• The deserialized JavaScript object. NumPy arrays are converted into objects with data (TypedArray) and shape (Array) properties.

Interactive Debugging

The Ticos platform includes built-in visualization tools. You can upload local .pkl files to the Lab → Rewind page for real-time parsing and visualization.

Lab Environment: Using the Pickle parser to replay historical robot trajectories