firebird/docs/design.md

0001
0002 ### Firebird may be used with a server and has a server part.
0003
0004 While Firebird can run as a pure frontend in general. For the ePIC/EIC use case a backend server is now essential:
0005
0006 - **Data access**: Simulation campaign data are accessed via XRootD, which is not available from JavaScript.
0007   A small backend is needed to fetch data, convert it to Firebird format, and serve it to the frontend.
0008 - **Browser compatibility (CORS):** Firebird is served from one address, while geometry and other assets are loaded from GitHub CI artifacts.
0009   This triggers CORS (Cross-Origin Resource Sharing) restrictions.
0010   Chrome currently accepts this setup, but Firefox (the default browser on Linux) does not, which means Firebird does not reliably work in Firefox.
0011   A server cleanly resolves this by proxying all assets from a single origin.
0012 - **Geometry stability**: We use current DD4Hep geometry from the ePIC repository.
0013   When geometry formats change or temporarily break - so visualization is broken,
0014   the server allows us to keep multiple versions and quickly
0015   switch to a stable fallback, instead of the event display simply stopping to work.
0016 - **Local installation**: Firebird architecture supports local installation—users run the same server
0017   backend on their machines to work with their own geometry and files.
0018 - **Batch jobs**: such local installations with the server allows to use Firebird in batch jobs and CI
0019
0020
0021 ### Technical differences with Phoenix:
0022
0023 Internally, Phoenix uses three.js, which has its core primitives: camera, renderer, scene, etc.
0024 What Phoenix tried to do is create "Manager" classes that wrap and represent these primitives with more event display functionality.
0025 Unfortunately, they couldn't achieve clean separation. Different aspects of the application (effects, ray-tracing, etc.)
0026 require different groupings of primitives (scene + renderer, or renderer + controls + camera). To handle this, Phoenix Managers just reference each other, belong to each other, and are completely highly coupled.
0027
0028 The overlay feature illustrates this problem perfectly. Instead of creating a separate class to handle alternative views, they duplicated camera, renderer, and controls across these already-coupled managers.
0029
0030 ```ts
0031 /** Main renderer to be used by the event display. */
0032 private mainRenderer: WebGLRenderer;
0033 /** Overlay renderer for rendering a secondary overlay canvas. */
0034 private overlayRenderer: WebGLRenderer;
0035 And then something like
0036
0037 // Creates BOTH perspective and orthographic cameras
0038 const perspectiveCamera = new PerspectiveCamera(75, ...);
0039 const orthographicCamera = new OrthographicCamera(...);
0040
0041 // Creates controls for each
0042 this.perspectiveControls = this.setOrbitControls(perspectiveCamera, rendererElement);
0043 this.orthographicControls = this.setOrbitControls(orthographicCamera, rendererElement);
0044
0045 // Then assigns main vs overlay
0046 this.setMainControls(this.perspectiveControls);
0047 this.setOverlayControls(this.orthographicControls);
0048
0049 ```
0050
0051 The pattern repeats throughout—each "view" gets its own complete copy of three.js objects scattered across managers,
0052 requiring synchronization methods like transformSync() and updateSync() to keep them coordinated.
0053 My take is that it's impossible to untangle this without essentially making "Phoenix 2."
0054
0055 For Firebird, a lot of thinking went into avoiding this. I came up with the idea of "rendering heads."
0056 There's one flat interface that serves as a gate to three.js primitives (and can use Phoenix as a backend).
0057 If you need scene + camera, or controls + geometry—you take it from there. Then there are rendering heads (not yet fully implemented) that can attach to different things.
0058 One rendering head might be an overlay, another the main display, a third VR/AR.
0059 Or you could create classic projections (top/left/front/isometric) with different views on one screen, or pages with main view plus per-detector representations.
0060 It's not yet fully implemented, but the classes are organized with that architecture in mind.
0061
0062 Phoenix and Firebird also use different UI systems because Phoenix UI depends heavily on these Manager interconnections, making it inseparable.
0063 There are two libraries—you can use only the phoenix-event-display library (which we reference now), but if you start using PhoenixUI,
0064 you're basically locked into everything as-is.
0065
0066 Finally, one weakness of default three.js is raycasting performance—particularly for tasks like identifying particles from mouse pointer position.
0067 This is essential for VR work, since presumably looking around isn't enough; pointing at tracks and geometry needs to work well. Out of the box, it's just slow.
0068 There's a fast approach using Bounding Volume Hierarchy (BVH), and Firebird has started applying this library: https://github.com/gkjohnson/three-mesh-bvh
0069 Look at examples!
0070
0071
0072
0073
0074 Technically
0075 Phoenix - Highly coupled managers and sticking VR somewhere in between Main... and Overlay... everything
0076 Firebird - finishing rendering heads and attaching VR there
0077
0078 UI - different, but probably should be easy, but if one wants to have UI inside VR (and probably that is wanted) - Firebird would be easier to bring in something like https://github.com/pmndrs/uikit, because three.js interface is made simpler
0079
0080 Raytracing - interacting - done differently