Visualization of Instruments and Trajectories

# Reasons to use visualization

When you specify an instrument, it may be of great help if you visualize resulting neutron trajectories of a simulation alongside with instrument components.
If the placement of modules has been done correctly, trajectories are to be seen on their path from source to detectors. But if for example

- guide ends don't match
- optical devices like slits are misplaced
- energies / neutron velocities don't fit the geometry
- frames are incorrectly set etc...

neutrons will be lost and you may want to see where they get lost. So if you have build your instrument for the first time or you have changed some of the instrument components, it may be useful to look at its appearance first.

The visualization is done in steps, you just press the "Trajectories" button in the GUI, which starts the following process:

1. The instrument modules are executed in a pipe, to generate the overall instrument geometry.
2. The modules are executed to generate the trajectories.
3. The geometric information gained so far is converted to a 2D or 3D geometry file.
4. A geometry viewer is launched to show both the instrument geometry and neutron trajectories.

### Restrict the Number of Trajectories

We advise to restrict the number of trajectories - it will be overwhelming to see a million lines and your viewer might be very slow.

- Restrict the number of trajectories generated by the source module to some thousand at most, or
- Run first an extended simulation with (parts of) the instrument and use the module write_out to store all the trajectories reaching the final module in a file, which once again should be not more than thousand.
  Trajectories written out in this first run are then read in by using the raytracing option in the source module in a second run.
  Given the same random seed only those neutrons, which have a matching ID in the raytracing file, are propagated.
  This means that all these neutrons will propagate at least until the last module specified in the first run. This can be useful, e.g. if you are interested only in neutrons that propagate from source to the detector.

## Visualize X3D Scenes

X3D is a modern format for virtual reality scenes.
With third party viewers you may zoom in every detail of a generated scene. Modules are drawn with transparent outer surfaces, and the scene has the outlook and light effects known from virtual reality.

### X3D Tools

VITESS does not provide a virtual reality engine, but cooperates with an external X3D viewer.
The instantreality player of Fraunhofer IGD is available for all supported operating systems, download it as a binary to be used without fee in a non-commercial version. Note that the latest 2.2 version may not be supported by older Linux systems like Ubuntu 10.04. Please install InstantPlayer 2.1 or older in case you don't have the latest OS.
If you select (Options / Helper applications) an external X3D viewer installed on your system, it will be used to show the generated geometry file. If the default InstantPlayer is present on your system, this default will be found and used.
The visualisation is implemented for the most important instrument components including guides, choppers, slits etc. These components are visualised by their actual shape and are displayed in distinctive colors, i.e. sources are blue, guides are yellow etc. All components are labelled. Neutron trajectories are visualised by red lines, which connect their interaction (reflection, scattering, absorption) points.
The interaction with the 3D scene is very flexible. In the beginning the scene is shown with the source in the origin. In examine mode (key shortcut e) you may orient the scene with the mouse, left button pressed. It's like touching and turning a virtual ball around the origin. Use the mouse wheel to zoom in an out. Press the right mouse button and move the mouse to zoom in or out more gently. If you want to reset the origin to another module, switch to mode "look at" (key shortcut l) and click at the module you are interested in. Please note that this does not work for lines illustrating the neutron trajectories. After that switch back to mode examine. If you got lost, press R or r. If you press 'Space' an info screen appears, which in particular contains, among other information, the current position and the orientation of the camera. The camera position is in meters and is referreing to the origin at the source position. Select View --> Statistics --> Keyboard Mapping to get the complete list of all keyboard shortcuts.
When generating a X3D scene, VITESS looks for an option file. You may edit this file with the GUI, Options / X3D options. With Unix, this file is ~/.x3dopt, for Windows it's FILES\x3d.opt where VITESS has been installed.
When editing this file with the GUI, you may see what may be changed, and with what syntax. You may restrict the scene to some bounds, change the color and transparency of scene objects, and may switch off text annotation.

## Visualize SVG Graphics

As most modern browsers are capable to visualize Scalable Vector Graphics, you may select this format of two dimensional graphics. If you have firefox installed, this browser will show the SVG file.
The geometry is projected to a top view (x,y, default) or side view (x,z) as you select by Options / Trajectories. Trajectories are straight lines here, and module outlines are drawn as boxes of specific color.
As instruments are much longer than wide/high, you may select a region of interest to avoid long narrow stripes where all information is visually reduced to a line, and may scale the graphics to your need.

Back to VITESS overview
vitess@helmholtz-berlin.de