Warning, /firebird/README.md is written in an unsupported language. File is not indexed.
0001 # Electron Ion Collider dynamic visualization
0002 **(aka EIC Event Display)**
0003
0004 [](https://github.com/eic/firebird/actions/workflows/frontend.yaml)
0005
0006 - Event display: [seeeic.org](https://seeeic.org)
0007 - Documentation and tutorials: [eic.github.io/firebird](https://eic.github.io/firebird/)
0008
0009 <a href="https://eic.github.io/firebird/">
0010 <img src="docs/media/eic_dis_animation_v7.gif" alt="An EIC ePIC DIS event in Firebird" title="EIC ePIC DIS event" width="600" />
0011 </a>
0012
0013 ## Project overview
0014
0015 **Firebird** is a web-based event display framework for particle physics
0016 experiments, designed for the Electron-Ion Collider (EIC). It shows detector
0017 geometries, detector responses (hits), particle trajectories and physics
0018 processes as they develop in time, for research, debugging and quality
0019 control, and education.
0020
0021 ## Repository structure
0022
0023 This is a monorepo with npm workspaces (run `npm install` at the repository
0024 root, never inside a member):
0025
0026 - **firebird-ng/** - the Firebird application (Angular, zoneless): its
0027 configuration, routes and developer pages, built from the library below
0028 - **packages/firebird-ng/** - `@dexvis/firebird-ng`: the Angular library
0029 (`provideFirebird()` and its features, the display pages and
0030 `<firebird-display>`, the display services, the worker code)
0031 - **packages/firebird-core/** - `@dexvis/firebird-core`: the worker-safe event
0032 model, DEX input and output, and painters
0033 - **packages/epic/** - `@dexvis/firebird-epic`: the ePIC experiment pack,
0034 `withEpic()`, which the Firebird app installs
0035 - **packages/root2dex/** - `@dexvis/root2dex`: EDM4eic/EDM4hep ROOT to DEX
0036 conversion in the browser, the TypeScript twin of `pyrobird convert`
0037 - **packages/firebird-example-extension/** - a template for out-of-tree feature
0038 packs
0039 - **dexvis/** - the generic [dexvis](https://github.com/dexvis) packages
0040 (geometry tree editors, the app shell, the navigation cube, the app feature
0041 machinery), mostly as git submodules
0042 - **pyrobird/** - the Python Flask backend: local file server, ROOT
0043 conversion, batch screenshots
0044 - **dd4hep-plugin/** - the C++ Geant4/DD4hep plugin that records trajectories
0045 during simulation
0046 - **docs/** - the VitePress documentation site, deployed to
0047 [eic.github.io/firebird](https://eic.github.io/firebird/)
0048 - **dex-schema/** - the JSON Schema of the Firebird data exchange format (DEX)
0049
0050 ## Development
0051
0052 The supported Node.js major version is in `.nvmrc`.
0053
0054 ```bash
0055 npm install # at the repository root
0056 cd firebird-ng && npm run serve # http://localhost:4200
0057 npm run test:headless --workspace=firebird-ng
0058 npm test -w @dexvis/firebird-ng # the library's suite
0059 python build.py full # build, all tests, pyrobird package
0060 ```
0061
0062 `CLAUDE.md` lists every test suite and the verification steps;
0063 [pyrobird/README.md](pyrobird/README.md) covers the backend.
0064
0065 ## License
0066
0067 The Firebird application (`firebird-ng/`), pyrobird and the DD4hep plugin are
0068 licensed under GPL-3.0-or-later ([LICENSE](LICENSE)); the DD4hep-derived
0069 sources of the plugin keep their CERN notices. The libraries in `packages/`
0070 and the dexvis packages are MIT licensed, each with its own `LICENSE` file.
