KAHIBARO
36.8. Common Visualization Commands
Table of Contents
Overview
Geant4 provides a command based visualization system that you control at runtime, usually from macro files. For beginners it is helpful to have a compact list of the most common commands and to understand what each one does in practice. This appendix collects frequently used visualization commands, grouped by purpose, and shows typical usage patterns you will meet in examples and in your own applications.
Throughout this appendix, commands always start with /vis/ or another Geant4 UI prefix, and you enter them either interactively at the Geant4 prompt or inside .mac macro files.
Important rule: Visualization commands do not create or change geometry or physics. They only control how the existing simulation state is drawn and viewed.
Starting and Managing the Visualization System
Visualization must be initialized and a driver selected before you can draw anything. This usually happens after you have defined geometry and physics and called /run/initialize.
The most common way to start the visualization system is:
/vis/initialize
This command sets up the visualization manager and prepares it to accept further /vis/ commands. Many example macros call it early, often immediately after /run/initialize.
To open a specific visualization driver, you use:
/vis/open OGL # or another driver nameFor example, to open an OpenGL viewer with Qt support, you might use:
/vis/open OGL 600x600-0+0
The exact string after /vis/open depends on which drivers were built and enabled when you installed Geant4. Common driver names include OGL, OGLI, and Qt based variants. For batch usage without an interactive window, you can use a file based driver such as:
/vis/open HepRepFileTo close all open viewers and cleanly reset the visualization system, you can use:
/vis/disableThis does not change your geometry or physics, only the visualization state.
Always call /vis/initialize before any other /vis/ commands in a macro, otherwise many visualization commands have no effect.
Drawing Geometry
Once the visualization system is initialized and a driver is open, you can draw your world and detector geometry. The essential command is:
/vis/drawVolumeThis draws the full geometry starting from the world volume. If you want to draw only a particular logical or physical volume, you can specify its name:
/vis/drawVolume myDetectorPV
where myDetectorPV is the name of a physical volume defined in your geometry code.
If you change geometry or reconstruction parameters and want to force a redraw, use:
/vis/scene/create
/vis/scene/add/volume
The first command creates a new scene, and the second adds your full geometry to that scene, equivalent to drawVolume but more explicit.
To limit the drawn region you can define a visualization cut in world coordinates:
/vis/scene/add/volume
/vis/scene/add/axes 0 0 0 1 m
/vis/viewer/set/target 0 0 0 mThis does not clip geometry by itself, but it helps center and orient the view on the region you care about.
Creating and Controlling Viewers
Viewers show scenes. After /vis/open you can create or switch scenes and attach them to viewers.
To create a new scene and attach it to the current viewer:
/vis/scene/create
/vis/scene/add/volume
/vis/sceneHandler/attachYou can open more than one viewer on the same scene, for instance different projections:
/vis/open OGL
/vis/open OGL
Each /vis/open call usually creates a new window. You can switch the active viewer with:
/vis/viewer/list
/vis/viewer/select viewer-0
The exact viewer names appear in the output of /vis/viewer/list.
Some drivers allow you to save the current view to an image file directly:
/vis/viewer/save myDetectorView.pngThe supported output formats depend on the driver.
Changing View and Camera
You control the camera and projection purely through /vis/viewer/set/... commands. These do not change the geometry, only how it is displayed.
To choose a projection:
/vis/viewer/set/projection orthographicor
/vis/viewer/set/projection perspectiveTo define the camera target, that is the point at the center of the view, use:
/vis/viewer/set/target 0 0 0 mmTo set the camera position via a direction and distance:
/vis/viewer/set/viewpointThetaPhi 90 0 degHere the first angle is the polar angle $\theta$ from the positive z axis, and the second angle is the azimuthal angle $\phi$ around the z axis.
You can also zoom in or out. Two useful commands are:
/vis/viewer/zoom 1.2
/vis/viewer/zoom 0.8where factors greater than 1 zoom in and factors less than 1 zoom out.
To make the viewer automatically fit the entire scene, use:
/vis/viewer/resize
/vis/viewer/centreOn 0 0 0 mmDrivers with interactive GUIs usually allow rotation and zoom with the mouse. The commands above are especially useful when running in batch mode or when generating reproducible views from macros.
If the view looks empty, check that you have called /vis/scene/add/volume or /vis/drawVolume and that the camera target and zoom are reasonable for the size of your world.
Visualization Attributes
Visualization attributes control how objects are drawn, for example their color, line style, or whether you see them as wireframes or solid shapes.
A straightforward way to set global drawing style is:
/vis/viewer/set/style wireframeor
/vis/viewer/set/style surfaceWireframe mode is very useful to inspect overlaps or internal structure, while surface mode gives a more realistic compact view.
To control transparency of individual logical volumes, Geant4 supports:
/vis/geometry/set/visibility myDetectorLV true
/vis/geometry/set/colour myDetectorLV 0 1 0 0.3The last argument is alpha, so 0.3 means the object is 30 percent opaque. The three preceding numbers are red, green, and blue components, each between 0 and 1.
You can also hide parts of the geometry to clarify the view:
/vis/geometry/set/visibility shieldingLV falseThis leaves the geometry intact for the simulation, but prevents that volume from being drawn.
For axes and reference markers, you can use:
/vis/scene/add/axes 0 0 0 50 cmwhich draws coordinate axes centered at the origin, with the given length for each axis.
Displaying Particle Trajectories
Once you start running events, you often want to see the paths of particles. Geant4 calls these trajectories or tracks in visualization.
To enable drawing of trajectories, first create a scene that includes them:
/vis/scene/create
/vis/scene/add/volume
/vis/scene/add/trajectories smooth
/vis/sceneHandler/attach
The smooth option interpolates the drawn tracks for a visually smooth curve. Another option is rich, which includes more detailed representation.
To control whether trajectories are drawn for all events or only the most recent event, use:
/vis/scene/endOfEventAction accumulateor
/vis/scene/endOfEventAction refresh
accumulate keeps tracks from multiple events on the screen, while refresh clears the previous ones.
You can filter which particles have their trajectories drawn, for instance:
/vis/filtering/trajectories/create/particleFilter gammaFilter
/vis/filtering/trajectories/particleFilter-0/add gammaThen you attach the filter to the scene:
/vis/scene/add/trajectories richwith the filter active.
Track coloring is controlled by trajectory model settings. For default coloring by particle type, a typical command is:
/vis/modeling/trajectories/create/drawByParticleID
/vis/modeling/trajectories/drawByParticleID-0/set 1Electrons, photons, protons, and other particles will then appear in different colors according to the standard scheme built into Geant4.
Drawing trajectories for a very large number of events can slow down visualization and consume a lot of memory. Use accumulate with care, and consider running with fewer events when inspecting tracks.
Displaying Hits and Digits
Sensitive detectors produce hits, and sometimes digitization code produces digits. Geant4 can visualize both.
To draw hits from sensitive detectors, you add them to the scene:
/vis/scene/add/hitsIf your application defines drawing attributes for hits, they will appear as markers at their recorded positions. For example, energy depositions may be shown as colored dots whose size reflects deposited energy.
To filter hits, you can use hit filters similar to trajectory filters, for example by detector name or energy threshold. The exact commands depend on the hit types registered with the visualization system, but a typical sequence starts with:
/vis/filtering/hits/listto see available filters, and then:
/vis/filtering/hits/create/energyFilter hitEFilter
/vis/filtering/hits/hitEnergyFilter-0/setMin 1 keVand finally:
/vis/scene/add/hitswith the filter now active.
For digits, the commands are analogous:
/vis/scene/add/digitsprovided your application uses the Geant4 digitization classes.
Controlling Event and Run Display
Geant4 allows you to visualize events as they are simulated. This is controlled with a few central commands.
To control how many events are drawn during a run, you can use:
/vis/verbose 2
/vis/scene/endOfEventAction accumulate
/vis/scene/endOfRunAction refreshThe verbosity level determines how much text feedback you get about visualization actions.
You can trigger drawing manually for a specific event using:
/vis/scene/endOfEventAction drawThisEventThen, when you run:
/run/beamOn 1that single event will be propagated to the visualization system and drawn according to your current scene settings.
For stepping through events one at a time while watching the viewer, a common pattern is:
/vis/scene/endOfEventAction refresh
/run/beamOn 1
and then repeat /run/beamOn 1 as needed.
To automatically start the viewer at the beginning of a session, you can place something like this in your main macro:
/vis/initialize
/vis/open OGL
/vis/drawVolume
/vis/scene/add/trajectories smooth
/vis/scene/add/hits
Then you only need to call /run/beamOn to see events drawn.
Visualization is independent of the physics simulation. Changing how many events are drawn does not change how many events are actually simulated unless you change /run/beamOn.
Saving Images and Scenes
Many users want static images of geometry or tracks for documentation and publications. Depending on the driver, Geant4 can export images or scene descriptions.
For OpenGL and some other drivers, a minimal image export command is:
/vis/viewer/save myView.epsor:
/vis/viewer/save myView.pngThe supported formats depend on the chosen visualization driver and its capabilities.
If you open a file based driver such as HepRep, you can produce a file that external programs know how to display:
/vis/open HepRepFile
/vis/drawVolume
/run/beamOn 10This will create a HepRep file in your working directory that you can open with the HepRApp viewer.
For batch images in many angles, you can loop over viewing angles in a macro, for example:
/vis/viewer/set/viewpointThetaPhi 90 0 deg
/vis/viewer/save view_0deg.png
/vis/viewer/set/viewpointThetaPhi 90 45 deg
/vis/viewer/save view_45deg.pngwhich allows you to script reproducible sets of images.
Typical Minimal Visualization Macro
To conclude, here is a compact example of a minimal and practical visualization macro that you can adapt to many applications. It assumes your run manager and geometry are already initialized elsewhere:
/control/verbose 2
/run/verbose 2
/vis/verbose 2
/run/initialize
/vis/initialize
/vis/open OGL
/vis/drawVolume
/vis/scene/add/trajectories smooth
/vis/scene/add/hits
/vis/viewer/set/style surface
/vis/viewer/set/target 0 0 0 mm
/vis/viewer/zoom 1.0
/vis/scene/endOfEventAction accumulate
/run/beamOn 10This small set of commands starts visualization, draws the geometry, displays trajectories and hits, and simulates 10 events for inspection. By learning and reusing this pattern and the command families described in this appendix, you can control most everyday visualization tasks in Geant4 without changing your C++ code.
Views: 10