Skip to content

Latest commit

 

History

History
266 lines (183 loc) · 11.7 KB

users.md

File metadata and controls

266 lines (183 loc) · 11.7 KB
Raw

User manual

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:

Main view of Phoenix

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:

Phoenix menu item

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:

Phoenix geometry menu item

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:

Phoenix event menu item

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

Phoenix menu options

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):

Phoenix iconbar

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

  • Zoom : the plus/minus icons allow you to zoom in and out, respectively
  • Pre-defined views : 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
  • Event animation : starts a simple animation, flying through the detector
  • Collection information : displays a panel showing textual information about the event data collections (see below)
  • Import/export : allows you to load new event data, or detector geometry (depending on configuration)

And if you have a AR/VR headset plugged in (or are using it on a smartphone browser which supports this) then you will also see a VR headset icon, which will take you into the Phoenix VR mode (see below)

Collections info panel

Phoenix collections info

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

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.

Currently it 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)

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.

Event display state

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.

Phoenix labels

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:

Supported object types

Currently Phoenix supports the following physics objects:

  • Tracks - the trajectory of a charged particle (usually in a magnetic field)
  • Calorimeter clusters - deposits of energy in a calorimeter
  • Jets - cones of activity within the detector
  • Hits - individual measurements, which can either be points or lines
  • Vertices

And coming soon:

  • Vertices
  • 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’ Everything else is decoration

Geometry

sample geometry

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