packages/firebird-core/README.md

0001 # @dexvis/firebird-core
0002
0003 The worker-safe core of the Firebird event display: the event model, DEX io,
0004 loader contracts, data catalog types and painters. Plain TypeScript with no
0005 Angular injector and no bootstrap, so web workers, node scripts and the
0006 Angular application run the same code. It uses Angular signals (peer
0007 `@angular/core`) and renders with three.js (peer `three`).
0008
0009 ```bash
0010 npm install @dexvis/firebird-core @angular/core three
0011 ```
0012
0013 ## Subpaths
0014
0015 | Import | Holds | Imports three.js |
0016 |---|---|---|
0017 | `@dexvis/firebird-core` | everything below, plus the painters | yes |
0018 | `@dexvis/firebird-core/model` | event model, DEX io, piece factory registry | no |
0019 | `@dexvis/firebird-core/loaders` | loader contracts, `matchesFileExtensions`, `sourceName` | types only |
0020 | `@dexvis/firebird-core/data-catalog` | data catalog types and merge helpers | no |
0021
0022 A class is the same class whichever subpath imports it. In modules an
0023 application loads at startup, import the subpaths: the root pulls three.js
0024 in through the painters.
0025
0026 ## Paint an event without DI
0027
0028 Registration is explicit; importing the package has no side effects.
0029
0030 ```ts
0031 import { Scene } from 'three';
0032 import { DataExchange, DataModelPainter, initPieceFactories, registerDefaultPainters } from '@dexvis/firebird-core';
0033
0034 initPieceFactories();
0035 const dex = DataExchange.fromDexObj(dexDocument);   // a parsed DEX 1.0 document
0036
0037 const scene = new Scene();
0038 const painter = new DataModelPainter();
0039 registerDefaultPainters(painter);
0040 painter.setThreeSceneParent(scene);
0041 painter.setEntry(dex.events[0]);
0042 painter.paint(null);                                 // null: draw everything, no time filter
0043 ```
0044
0045 A custom piece type extends `EventPiece` with a factory registered through
0046 `registerEventPieceFactory()`, and a custom painter extends
0047 `EventPiecePainter`. The base `dispose()` frees the geometries and materials
0048 of everything under the painter's node; override it only to free resources
0049 held elsewhere, and call `super.dispose()`.
0050
0051 ## Build and test
0052
0053 ```bash
0054 npm test -w @dexvis/firebird-core
0055 npm run build -w @dexvis/firebird-core     # dist/ with one bundled .d.ts per subpath
0056 ```