Agent Skills
› lichtblick-suite/lichtblick
› deserialization
deserialization
GitHub将原始二进制消息数据转换为结构化 JavaScript 对象。支持 ROS1/2、Protobuf、Flatbuffers 等多种格式的解码，通过 parseChannel 分发并封装为 DeserializingIterableSource 实现流式反序列化与 WASM 解压。
Trigger Scenarios
需要将 MCAP 等二进制源数据解析为 JS 对象
处理不同 schema 编码的通道反序列化
需要配置 WASM 压缩格式（zstd/lz4/bz2）的解压器
Install
npx skills add lichtblick-suite/lichtblick --skill deserialization -g -y
SKILL.md
Frontmatter
{
"name": "deserialization",
"description": "Deep deserialization knowledge: parseChannel schema dispatch, ros1msg\/ros2msg\/ros2idl\/jsonschema\/protobuf\/flatbuffer decoders, WASM decompression handlers, and the DeserializingIterableSource wrapping pattern."
}
Deserialization Skill
Converts raw binary message data into structured JavaScript objects.
Flow
Raw bytes (from source)
│
▼
DeserializingIterableSource (applies parseChannel-based decode)
│
▼
Decoded message objects (ready for panels)
Schema Encodings
| Encoding | Schema Format | Deserializer |
|---|---|---|
ros1msg |
ROS 1 message definition text | @lichtblick/rosmsg-serialization MessageReader |
ros2msg |
ROS 2 message definition text | @lichtblick/rosmsg2-serialization MessageReader |
ros2idl |
OMG IDL text | @lichtblick/omgidl-serialization MessageReader |
jsonschema |
JSON Schema object | JSON.parse + postprocessValue (base64 decode) |
protobuf |
FileDescriptorSet binary |
protobufjs Root.fromDescriptor |
flatbuffer |
Binary reflection schema | flatbuffers_reflection Parser |
Core Entry Point: parseChannel()
packages/mcap-support/src/parseChannel.ts:
function parseChannel(channel: Channel): ParsedChannel {
// Returns { deserialize: (data: ArrayBufferView) => unknown, datatypes: Map }
// Dispatches based on channel.schema.encoding
}
This is the single function that resolves any channel's schema into a deserializer.
Per-encoding parsers
packages/mcap-support/src/parseProtobufSchema.tspackages/mcap-support/src/parseFlatbufferSchema.tspackages/mcap-support/src/parseJsonSchema.ts
DeserializingIterableSource
packages/suite-base/src/players/IterablePlayer/DeserializingIterableSource.ts:
- Wraps a serialized source (
ISerializedIterableSource) - Applies
parseChannel()to each channel's schema at initialization - Deserializes messages on-the-fly as they are iterated
- Produces
IDeserializedIterableSource(messages are JS objects, not raw bytes) - Supports sampling (
setSamplingWindowEnd()for latest-per-render-tick mode)
⚠️ This wrapper is only inserted for serialized sources. Sources that already implement
IDeserializedIterableSourceskip it.
WASM Decompression Handlers
packages/mcap-support/src/decompressHandlers.ts:
- zstd:
@lichtblick/wasm-zstd— best compression ratio - lz4:
@lichtblick/wasm-lz4— fastest decompression - bz2:
@lichtblick/wasm-bz2— legacy support
Handlers are loaded once (singleton promise) and shared across all readers.
Performance Notes
- Deserialization is CPU-bound — runs in a Worker via
WorkerIterableSource - Protobuf:
root.lookupType()is cached after first call - JSON:
postprocessValuehandles base64 →Uint8Arrayforbytesfields - Flatbuffers: zero-copy read from the shared buffer (fastest)
- ROS:
MessageReaderprecompiles field offsets at schema-parse time
Skills Reference
- For MCAP chunk structure: load
mcap-formatskill - For Worker patterns: load
web-workersskill - For the iterator layering: load
player-internalsskill
Version History
- cab9317 Current 2026-07-24 12:16
