root2dex/src/dex.ts

0001 /**
0002  * Firebird DEX format version 1.0: the document shape this package emits.
0003  *
0004  * DEX v1 is columnar - an event holds `pieces`, each piece holds parallel
0005  * `columns` arrays where the entity id equals the array index. A writer
0006  * declares only the columns it has: simulation output has no reconstruction
0007  * columns and vice versa.
0008  *
0009  * These are the plain JSON structures, not the runtime model classes. The app
0010  * hands the document to `DataExchange.fromDexObj()`; batch tools write it out
0011  * as JSON.
0012  */
0013
0014 export const DEX_TYPE = 'firebird-dex-json';
0015 export const DEX_VERSION = '1.0';
0016 export const PIECE_VERSION = '1.0';
0017
0018 /** One named block of typed entity data inside an event. */
0019 export interface DexPiece {
0020   name: string;
0021   type: string;
0022   version: string;
0023   /** Free-form provenance: which ROOT collection and C++ type this came from. */
0024   origin?: unknown;
0025   count: number;
0026   /** Parallel arrays; a fixed-width vector column is flattened (pos = xyz per entity). */
0027   columns: Record<string, unknown[]>;
0028   /** Index columns into other pieces of the same event; -1 means "no reference". */
0029   refs?: Record<string, string>;
0030   /** PointTrajectory: the names of the per-point tuple values. */
0031   pointColumns?: string[];
0032   /** PointTrajectory: ragged payload, one point list per entity. */
0033   points?: number[][][];
0034 }
0035
0036 export interface DexEvent {
0037   id: string | number;
0038   pieces: DexPiece[];
0039 }
0040
0041 export interface DexDocument {
0042   type: string;
0043   version: string;
0044   origin: unknown;
0045   events: DexEvent[];
0046 }
0047
0048 /** Wraps a list of event objects into a complete DEX v1 document. */
0049 export function makeDex(events: DexEvent[], origin: unknown = null): DexDocument {
0050   return {
0051     type: DEX_TYPE,
0052     version: DEX_VERSION,
0053     origin,
0054     events,
0055   };
0056 }