rerun-data-model

Rerun のデータモデル

データセットを取り込む際に難しいのは、API 呼び出しではなく、モデルの決定です。 モデルが正しければどのような仕組みでも機能しますが、間違っていればクエリ、ビュー、トレーニングのすべてに支障が出ます。 このスキルで扱うのは、決定事項だけです。 仕組みの詳細については、rerun-chunk-processing（パイプラインの仕組み）と、そこから案内されるインポータースキル（rerun-mcap、rerun-urdf、rerun-parquet、rerun-mp4、rerun-lerobot）を参照してください。 正確なシグネチャについては、rerun.io/docs/concepts/logging-and-ingestion のドキュメントを参照してください。

変換コードを書く前に、以下のマッピング表を埋めてください。 これが設計となり、人間が数秒でレビューできます。

バイト列をモデル化する前に、仕組みを選択する

モデル化によって各データが 何に なるかを決め、仕組みによってそれが どのように 実現されるかを決めます。デフォルトはチャンクを手作業で構築するのではなく、リーダーとレンズを使うことです。

• このソースに対応するリーダーはありますか？ MCAP→McapReader、URDF→UrdfTree、parquet→ParquetReader、HDF5→Hdf5Reader、RRD→RrdReader、LeRobot ディレクトリ→log_file_from_path。ある場合 → reader.stream() とレンズを使用します。チャンクを生成するのはリーダーであり、あなたではありません。
• ない場合、真の外部メタデータ（JSON のキャリブレーション、オフセット）または汎用リーダーでは対応できない特定のカスタム用途である場合**→** Chunk.from_columns を使用します。
• それ以外の場合：リーダーやレンズが生成すべきものを手作業で構築しようとしていないかを確認し、不明点があれば説明を求めてください。

特に MCAP の場合：Foxglove または ROS でデコード可能なファイルは、サポート対象のメッセージスキーマの一部について、Transform3D、Pinhole、VideoStream などのアーキタイプをすでに出力します。それらはそのまま渡し、決して再導出しないでください。レンズが必要なのは、カスタム protobuf 信号トピックだけです。判断の全体像とアンチパターンの一覧は、rerun-chunk-processing にあります。

モデル

Dataset → Segment → Layer → Recording → Entity → Component → Chunk

• エンティティ = パス（/robot/arm/camera）で名前を付けた対象です。 コンポーネント = その対象に属する、型付きのフィールド（位置、画像、スカラー）です。 アーキタイプ = 一緒にログ記録され、レンダリングされるコンポーネントの標準的なまとまり（Points3D、Image、Transform3D）です。
• ログに記録するすべての値は、2 つの軸上に位置します。場所（エンティティパス + コンポーネント）と、時刻（どのタイムラインか、または 静的 = 常時）です。
• セグメント = 1 つのエピソードです。登録時に、その recording_id が segment_id になります。レイヤー = セグメントの上に重ねる追加の .rrd です。セグメントの recording_id と一致することでのみ関連付けられます。この共有 ID だけがレイヤー化の仕組みです。

判断基準

既存のエンティティに新しいエンティティを作るか、コンポーネントを追加するか 独自の空間座標系（Transform3D／Pinhole）や注釈コンテキストを持つ場合、または個別に表示・クリア・共有する必要がある場合（各ロボットリンク、各カメラ、各センサー）は、新しいエンティティを作成します。同じインスタンスに付随するデータ（点ごとの信頼度など）の場合は、同じエンティティに追加のコンポーネントを追加します。 標準外のフィールドには AnyValues を使用します。

プロパティとコンポーネントとレイヤーの違い（最もよく混同されます）

• コンポーネント：タイムライン上のタイムスタンプごとの信号（関節角度、画像）。
• セグメントプロパティ：カタログのフィルタリングや検索に使う、エピソードごとに 1 つのメタデータ（オペレーター、ロボット、サイト、タスク、日付）。タイムスタンプごとのデータではありません。
• レイヤー：ベースセグメントに重ねる、派生データを含む .rrd ファイル全体（FK 変換、点群、グリッパー状態、ラベル、品質スコア）。ベースの一部であるかのようにクエリできます。

静的データと時間データ 静的データはすべてのタイムラインに属し、同じエンティティ上の同じコンポーネントの時間データを上書きします。キャリブレーション、座標系、ロボットメッシュ、注釈コンテキスト、動画アセットなどの不変データに使用します。フレームごとのデータを静的データにしてはいけません。

タイムラインの選択 センサー間のクロックを同期するには timestamp タイムライン（エポックからのナノ秒）を、フレームや序数を揃えるには sequence タイムラインを使用します。有用な場合は両方にタイムスタンプを設定します。 共通のレートにリサンプリングしないでください。 Latest-at は、各コンポーネントの最新サンプルを保持することで、クエリ時に複数のレートのストリームを調整します（補間は行いません）。

ベースとレイヤーの違い ベース＝元のストリームを忠実に変換したもの。計算されたデータは含みません。 レイヤー＝派生データすべて（URDF＋関節状態からの FK、深度＋内部パラメーターからの点群など）。 別々の .rrd ファイルに保持します。

マッピングテーブル（コーディング前に作成）

ソース（トピック／列／キー）	エンティティパス	アーキタイプ	コンポーネント	タイムライン	静的／時間データ	ベース／レイヤー	プロパティ？
mcap /joint_states	/robot/<joint>	Scalars	scalars	sensor_time	時間データ	ベース	いいえ
cam0/color.mp4	/camera/cam0/video	VideoStream	codec＋sample	video_time	codec は静的、sample は時間データ	ベース	いいえ
calibration.json	/camera/cam0	Pinhole（＋Transform3D 外部パラメーター）	image_from_camera	—	静的データ	ベース	いいえ
URDF＋関節（計算値）	/robot/<link>	Transform3D	translation/rotation	sensor_time	時間データ	レイヤー	いいえ
episode.json の operator	セグメント	—	—	—	—	—	はい

知っておくべきパターン

• Transform / FK ツリー：各リンクエンティティに Transform3D をログ記録します。これは親パスに関連付けられ、ツリーに沿って合成されます。（トポロジを柔軟なグラフにする必要がある場合に限り、CoordinateFrame と child_frame／parent_frame を指定します。）
• カメラ：カメラエンティティに外部パラメーター（Transform3D）と内部パラメーター（Pinhole）を設定し、画像／深度を子として設定すると、投影が継承されます。
• 動画：圧縮サンプルには VideoStream を使用します。これは mp4（rerun-mp4）のデフォルトであり、Foxglove デコーダーがすでに渡す形式です。VideoStream で表現できないコーデックの場合は、AssetVideo+VideoFrameReference を代替として使用します。
• 列指向の取り込み：既存の ファイル には、対応するリーダー（rerun-mcap／-parquet／-mp4／-lerobot）を使用します。リーダーはチャンクを直接生成するため、カスタムパーサーから send_columns を手動で組み立てないでください。ライブロギングで列を直接ログ記録する場合、send_columns はタイムラインを自動追加しないため、必要なタイムラインをすべて渡してください。
• カスタムデータ：未対応のデータを無関係なアーキタイプに無理に当てはめないでください。代わりに DynamicArchetype または AnyValues を検討してください。DynamicArchetype は意味のあるカスタムコンポーネントのグループ向けです。AnyValues は、認識可能なオブジェクトやソースの型を構成しない、雑多な値向けです。

実際の障害につながる落とし穴

1. クエリではコンポーネント列が ListArray として返されます。[0]／[0][0] でインデックスを指定してください（DataFrame では 0 起点、SQL では 1 起点）。rerun-catalog-queries を参照してください。
2. レイヤーをアタッチするには、セグメントと同じ recording_id を使用する必要があります。application_id は登録時に破棄されます。
3. send_columns／send_chunks は log_time／log_tick を追加しません。存在するのは渡したタイムラインだけです。
4. 静的データは、そのコンポーネントのすべての時間的データを永続的に上書きします。ビューワーでは静的データが上書きされますが、rerun rrd optimize を実行するまで、書き込みはすべてディスクに残ります。
5. フレームペアごとに関連付けられる Transform3D／Pinhole は 1 つだけです。同じ関連付けを別のエンティティにログ記録すると拒否されます。
6. エンティティパスはファイルパスではありません（.. に意味はなく、__ は予約されています）。
7. デフォルトの RecordingStream で書き込まれたカタログレイヤーは、/__(properties)（RecordingInfo）チャンクを挿入します。カタログが recording_id でレイヤーをマージすると、ベースセグメントのプロパティと衝突する可能性があります。その場合、データセットのデフォルトのブループリントが開いたときに適用されなくなります。レイヤーのストリームは send_properties=False を指定して構築してください。