@6river/rosbag 中文文档教程

Question

rosbag

rosbag 是一个 node.js & 用于读取 rosbag 二进制数据文件的浏览器兼容模块。

Installation

npm install rosbag

或者

yarn add rosbag

Quick start

与 rosbag 交互的最常见方式是读取一组特定主题的数据记录。 rosbag格式编码主题的类型信息，rosbag读取此类型信息并将数据记录解析为JavaScript 对象和数组。

下面是一个从 node.js 中的 rosbag 读取消息的示例：

const { open } = require('rosbag');

// open a new bag at a given file location:
const bag = await open('../path/to/ros.bag');

// read all messages from both the '/foo' and '/bar' topics:
await bag.readMessages({ topics: ['/foo', '/bar'] }, (result) => {
  // topic is the topic the data record was in
  // in this case it will be either '/foo' or '/bar'
  console.log(result.topic);

  // message is the parsed payload
  // this payload will likely differ based on the topic
  console.log(result.message);
});

API

Opening a new rosbag reader

// @flow signature
function open(fileOrPath: File | string) => Promise<Bag>

打开一个新的 rosbag 阅读器是使用 open 函数完成的。 在浏览器中，该函数采用一个文件实例，您通常会从文件输入中获取该实例元素。 在 node.js 中，该函数采用一个字符串，该字符串应该是 rosbag 文件的完整路径。 Node.js 将从磁盘读取文件。 如果打开文件时出现问题或文件格式无效，承诺将拒绝，否则将使用 Bag 的实例解决。

Bag instance

// @flow signature
class Bag {
  // the time of the earliest message in the bag
  startTime: Time,

  // the time of the last message in the bag
  endTime: Time,

  // a hash of connection records by their id
  connections: { [number]: Connection },

  // an array of ChunkInfos describing the chunks within the bag
  chunkInfos: Array<ChunkInfo>,

  // call to consume from the bag - see 'Consuming messages from the bag instance' below
  readMessages(options: BagOptions, cb: (result: ReadResult) => void) => Promise<void>
}

Consuming messages from the bag instance

bag.readMessages 方法返回一个 Promise，它在读取操作完成时解析，或者在读取错误时拒绝。 在读取操作期间，各个ReadResult 对象被传递给提供给open 函数的回调。 callback 可能会在同一个 tick 上被多次调用，因为多个数据记录可以在 bag 读取器读取的单个二进制块中进行编码。

BagOptions

// @flow signature
const bagOptions = {

  // an optional array of topics used to filter down
  // which data records will be read
  // the default is all records on all topics
  topics?: Array<string>,

  // an optional Time instance used to filter data records
  // to only those which start on or after the given start time
  // the default is undefined which will apply no filter
  startTime?: Time,

  // an optional Time instance used to filter data records
  // to only those which end on or before the given end time
  // the default is undefined which will apply no filter
  endTime? Time,

  // decompression callbacks
  // if your bag is compressed you can supply a callback to decompress
  // based on the compression type. The callback should accept a buffer of compressed bytes
  // and return a buffer of uncompressed bytes
  decompress?: {|
    bz2?: (buffer: Buffer) => Buffer,
    lz4?: (buffer: Buffer) => Buffer,
  |}

  // by default the individual parsed binary messages will be parsed based on their [ROS message definition](http://wiki.ros.org/msg)
  // if you set noParse to true the read operation will skip the message parsing step
  noParse?: boolean
}

所有选项都是可选的，用于从 rosbag 中有时庞大而多样的数据记录中过滤下来。 可以省略所有选项 & 在 readMessages 回调中过滤内存中的消息； 然而，由于 rosbag 格式的优化可以在读取和读取期间进行。 如果您提前指定主题和/或日期范围，解析将产生显着性能和内存增益。

ReadResult

// @flow signature
const readResult {

  // the topic from which the current record was read
  topic: string,

  // the parsed message contents as a JavaScript object
  // this can contain nested complex types
  // and arrays of complex & simple types
  // this will be undefined if you supply { noParse: true } to `bag.readMessages`
  message: { [string]: any },

  // a Time instance - the receive time of the message
  timestamp: Time

  // the raw buffer data from the data record
  // a node.js buffer in node & an array buffer in the browser
  data: Array<int8>,

  // the offset of the chunk being read
  // starts at 0 and eventually increments to totalChunks
  // useful for computing read progress as a percentage
  chunkOffset: number,

  // the total chunks to eventually be consumed
  // during the current read operation
  totalChunks: number,
}

Connection

// @flow signature
class Connection {
  // the id of the connection
  conn: number,

  // the topic for the connection
  topic: string,

  // the md5 hash for the connection message definition
  md5sum: string,

  // the rosbag formatted message definition for records on this connection's topic
  messageDefinition: string,
}

Time

ROS 格式代表纳秒级的时间。 在 JavaScript 中，它存储为 Time 类的实例。 时间类有转换辅助方法来往返于 JavaScript 日期。

// @flow signature
class Time {
  // the seconds portion of the unix epoc
  sec: number,

  // the number of nanoseconds past the second of the unix epoc
  nsec: number,

  // the constructor expects a number for both the sec and nsec values
  constructor(sec: number, nsec: number),

  // convert this Time instance to a JavaScript date object
  // note: this is a lossy conversion as JavaScript dates do not store nanoseconds
  toDate(): Date,

  // helper method to build a time instance from a JavaScript date object
  static fromDate(Date): Time,

  // returns a positive number if left is greater than right
  // returns a negative number if right is greater than left
  // returns 0 if the times are the same
  // useful to sort an array of times:
  // const times = [new Time(1, 1000), new Time(2, 2000), new Time(0, 100)]
  // const sortedTimes = times.sort(Time.compare)
  static compare(left: Time, right: Time): number,

  // returns true if left is less than right, otherwise false
  static isLessThan(left: Time, right: Time): boolean,

  // returns true if left is greater than right, otherwise false
  static isGreaterThan(left: Time, right: Time): boolean,

  // returns true if the times are the same, otherwise false
  static areSame(left: Time, right: Time): boolean,

  // computes the sum of two times and returns a new time
  static add(left: Time, right: Time): Time,
}

您可以像这样导入 Time 模块：const { Time } = require('rosbag')

Supported platforms

> 在 node@8.x 和 google chrome（通过 webpack）中经过严格测试。 它也应该在所有具有 FileReader 和 类型化数组 API 可用。 如果您在使用 Firefox、Edge 或 Safari 时遇到问题，请随时提出问题或提交包含修复的拉取请求。

LICENSE

本软件根据下面引用的 Apache 许可证版本 2（“ALv2”）获得许可。

版权所有 2017-2018 GM Cruise

根据 Apache 许可证 2.0 版（“许可证”）获得许可； 你不可以 使用此文件，除非符合许可证。 您可以获得一份 许可

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则 根据许可证分发是在“按原样”的基础上分发的，没有 任何明示或暗示的保证或条件。 见 下的特定语言管理权限和限制的许可 许可证。