users.md

User manual

• Getting started
  • The demo grid
  • The Phoenix standard UI
  • The Phoenix menu
  • The Phoenix iconbar
    • Collections info panel
  • Keyboard controls
  • AR/VR mode
  • Event display state
  • Labels
  • URL options
• Using Phoenix with your own data
  • Event data
    • Format
    • Supported object types
  • Geometry

Getting started

The demo grid

When you first open the Phoenix demo (see the developer instructions for how to check it out and run locally) you will see a grid of Phoenix demos:

• Playground : a blank canvas where you can load 3D objects, move them around and generally experiment with Phoenix
• Geometry display : a simple demo of generating geometry procedurally/programmatically with Phoenix
• ATLAS : the ATLAS experiment demo. Here you can load Phoenix JSON or JiveXML event data files, and visualise physics objects such as Jets, Tracks, Calo cells etc within the ATLAS geometry.
• LHCb : the LHCb experiment demo shows a detailed view of the LHCb geometry, as well as tracks passing through it.
• CMS : the CMS experiment demo. Here you select from various event data files, and visualise physics objects such as Jets, Tracks, Calo cells etc within the CMS geometry. One special feature of the CMS demo is the visualisation of Muon Chambers.
• TrackML : this shows the imaginary detector created for the TrackML challenges.

The Phoenix standard UI

Since Phoenix is configurable, it is not guaranteed that all demos/implementations will look the same, but a typical Phoenix view is shown below:

In the centre, you see the 3D view of the experiment and event data.

Around it, you have:

1. The (configurable) experiment logo and event data
2. The Phoenix logo (which is also a link back to the demo grid)
3. The Phoenix menu (see below for more details)
4. The Phoenix iconbar (see below for more details)
5. The frames-per-second (FPS) graph

In general the Phoenix menu is used to determine what geometry and event data is shown (and how), whilst the iconbar determines how you interact with the geometry and event data.

The Phoenix menu

All items in the Phoenix menu have the same basic layout:

From left-to-right:

• A slider, which determines if the item (or the sub-items beneath it) is visible
• The name of the item
• A gear icon, to open the options for this item
• And an arrow to open/collapse sub items.

As an example of options, here is an expanded geometry view:

you can see that we can change the opacity and colour of the geometry item.

Another example of options: here is an expanded event data view, showing how you can apply cuts to track collections:

Another important point: clicking on the gear icon at the very top allows you to save/load the menu configuration.

The Phoenix iconbar

At the bottom of the main view you have the Phoenix iconbar (which can be shown/hidden by clicking on the arrow on top):

From left to right, you can access the following functions:

• Zoom : the plus/minus icons allow you to zoom in and out, respectively
• View options : clicking on this will allow you to access some preset views, and to view/hide the axes
• Auto rotate : clicking on this will set the camera orbiting the origin
• Dark/light theme : switches between dark and light themes
• Geometry clipping : allows you to 'slice' away parts of the geometry in order to view the event data/geometry inside
• Orthographic/perspective view : allows you to switch between different view modes
• Overlay : enables/disables the view overlay (a separate overlaid view of the detector)
• Object selection : once enabled, a new window will pop up which will display information about selected objects
• Info panel : shows a window displaying relevant information from Phoenix (for example, about events opened)
• Collision animation : starts a simple animation, simulating a collision and subsequent event data appearing
• Preset animations : shows a list of preset animations that can be triggered by clicking on the preset
• Collection information : displays a panel showing textual information about the event data collections (see below)
• Performance mode : clicking on this will turn on performance mode which makes Phoenix faster but decreases quality
• VR mode : will make Phoenix enter Virtual Reality (VR) mode
• AR mode : will make Phoenix enter Augmented Reality (AR) mode
• Screenshot mode : will enter screenshot mode by hiding all overlays
• Import/export : allows you to load new event data, or detector geometry (depending on configuration)
• Create shareable link : opens a dialog for creating a shareable link/URL to the experiment

The AR and VR mode will only be available if your device (or headset) supports AR or VR.

Collections info panel

This displays some more details about the various collections. And under the Selection column are two icons, which allow you to either zoom the camera to the object, or to select (and highlight) it.

Keyboard controls

Phoenix support various keyboard controls:

• Shift-T : change theme
• Shift-Number : switch to that numbered preset view
• Shift-R : rotate view
• +/- : zoom
• Shift-C : enable clipping
• Shift-V : switch between orthographic and perspective

AR/VR mode

Phoenix relies on the WebXR functionality of three.js, so before trying it in Phoenix, it would be a good idea to test the VR/AR demos there.

VR: Currently the VR has been tested on the following devices:

• Android smartphones
• Oculus Quest (make sure you use the Oculus browser - Firefox reality is currently unusably slow)
• Oculus Rift S (as of writing, the best option seems to be to use google Chrome canary i.e. beta)

AR: On Android you will need the latest version of Chrome. On iOS, you will need to use the WebXR Viewer from Mozilla to make AR work.
Make sure your device supports AR and is listed here: https://developers.google.com/ar/devices

The situation here is rapidly changing, so please let us know if this is out-of-date. Also please note that some features of Phoenix need to be disabled in VR, and it is currently very much a work in progress (help is very much welcomed!).

Event display state

Phoenix keeps track of the event display state which can be saved as a JSON file and loaded later either from the Phoenix menu or through the URL.

The state includes:

• Phoenix menu configuration
• Geometry clipping
• Camera position

The "Save state" and "Load state" buttons are in the options of top level Phoenix menu node.

Labels

Labels can be added to individual physics objects from the collections info panel. The configurable options for each label are in the Phoenix menu.

You can also save the added labels in a JSON file from the options of "Labels" Phoenix menu node and load them later.

URL options

Some options can be passed to the event display through the URL parameters. They are passed through the URL like this:

http://localhost:4200/#/atlas?<option_1>=<option_1_value>&<option_2>=<option_2_value>

Available options are:

• file : path or URL to the event data file you want to load (requires type option)
• type : type of the event data file (for example, jivexml or json)
• config : path or URL to the config or state file (this is the JSON file you get when you save state from the Phoenix menu)
• hideWidgets : hide all overlay widgets including Phoenix menu and iconbar

For example, event from a JSON event data file served through /assets/event_data/data.json can be loaded through the following URL:

http://localhost:4200/#/atlas?file=assets/event_data/data.json&type=json

Using Phoenix with your own data

The JSON format is pretty simple, but we're still in the process of documenting it (and it might evolve).

Caveats aside, here are some rough outlines:

Event data

Format

Currently Phoenix supports loading .JSON files containing multiple events. The format is the following.

{
  "EVENT_KEY_1": event_object,
  "EVENT_KEY_2": event_object,
  ...
  "EVENT_KEY_N": event_object
}

EVENT_KEY is an identifier for each event, and the format of each event_object would be as follows:

{
  "event number": XXX,
  "run number": YYY,
  "OBJECT_TYPE_1": {
    "COLLECTION_NAME_X" : [ OBJECTS ]
  },
  "OBJECT_TYPE_2": {
    "COLLECTION_NAME_Y" : [ OBJECTS ],
    "COLLECTION_NAME_Z" : [ OBJECTS ]
  }
}

Where:

• event number and run number are hopefully obvious,
• OBJECT_TYPE is one of the supported types that will be mentioned below,
• COLLECTION_NAME is an arbitrary name used to label this particular collection (you can have as many collections of each OBJECT_TYPE as you like).

You can find various examples in the files folder:

• atlaseventdump2.json is an small multiple event file containing the various objects.
• EventData.json is a bigger file containing more events and objects.

Supported object types

Currently Phoenix supports the following physics objects:

• Tracks - the trajectory of a charged particle (usually in a magnetic field)
• Calorimeter cells - deposits of energy in a calorimeter (planar and cylindrical are supported).
• Jets - cones of activity within the detector
• Hits - individual measurements, which can either be points or lines
• Vertices - optionally linked to tracks
• Compound objects (i.e. 'Muons', which link 'Tracks' and 'Clusters')

(other shapes will be supported soon)

What follows in the list of objects depends on the type:

• 'Tracks' have the following information:
  • 'chi2' - the chi2 of the fit, i.e. a number
  • 'dof' - the degrees of freedom of the fit, i.e. a number (not necessarily an integer)
  • 'params' - the parameters of the tracks, defined as d0,z0, ABC
  • 'pos' - further positions along the track (a possible extension is to store positions and directions, to permit bezier curves, and perhaps a simple extrapolation system which would further reduce the amount of information needing to be stored)
  • 'color' - (Optional) Hexadecimal string representing the color to draw the track.
• 'Clusters' have the following information:
  • 'phi' - phi direction
  • 'eta' - eta direction
• 'Jets' have the following information:
  • 'coneR' - the radius of the jet cone
  • 'phi'- phi direction
  • 'eta' - eta direction
  • 'energy'
• Hits can be defined in one of two ways:
  • [ [x,y,z], [x,y,z], [x,y,z], ] - i.e. an array of 3-dim arrays containing Cartesian coordinate. These will be rendered as points.
  • [ hit, hit, hit ] - i.e. an array of hit objects, where the hit objects must Where hit needs to have a pos attribute, and optionally a type ( ‘Point’ || ‘Line’ - if not specified the default is 'Point'). Everything else is decoration.

Geometry

Phoenix currently supports loading .obj, .gltf, .root, .json.gz and .json files containing 3D objects.