Visualization Built In Commands =============================== The old /vis~/ commands are no longer available. Here is some guidance on the new commands available from Geant4 4.0. Note particularly the new compound commands: /vis/drawTree /vis/drawVolume /vis/drawView /vis/open /vis/specify Introduction ============ See also the Users Guide For Application Developers, GettingStarted, Visualization. For using the visualization commands, it is useful to know the concept of "scene", "scene handler", and "viewer". A "scene" is a set of visualizable objects. A "scene handler" is a graphics-data modeler, which processes raw data in a scene for later visualization. And a "viewer" generates images based on data processed by a scene handler. Roughly speaking, a set of a scene handler and a viewer corresponds to a visualization driver. The typical steps of performing Geant4 visualization are: Step 1. Create a scene handler and a viewer. Step 2. Create an empty scene. Step 3. Add raw 3D data (e.g., geometrical objects, axes, options to draw trajectories, etc.) to the created scene. Step 4. Attach the current scene handler to the current scene. Step 5. Set camera parameters, drawing style (wireframe/surface), etc. Step 6. Refresh the viewer. Step 7. Draw transients (trajectories, hits, etc) Step 8. Flush the viewer if necessary, i.e., those viewers which need to render a view after all data is assembled and pseudo-viewers, e.g., file writers that need to close files. Note that the above list does not mean that you have to execute 8 commands for visualization. You can use "compound commands" which can execute several visualization commands at one time. A scene handler can handle only one scene at any one time but can have any number of viewers. A scene can be attached to any number of scene handlers. It is important to realise that there is also the concept of a "current" scene, "current" scene handler and "current" viewer which are maintained by the G4VisManager. It is usually the last object created or selected or operated upon. Note that there is also a concept of a "standard view" which is that which comfortably includes all components of the scene. From this follow the concept of standard target point, etc. It is the responsibility of each viewer to apply its view parameters relatively, taking into account the scene it represents. This is a dynamic operation and the scene handler and its viewers must be smart enough to know when to recalculate graphics-system-dependent quantities when the scene or the view parameters change. See below for a more extended description. NI means "not implemented". Scenes ====== A scene is a list of visualizable objects, such as detector components, hits, trajectories, axes, etc. Scenes are graphics-system-independent. The G4VisManager has a list of scenes. Unless otherwise stated, commands affect the current scene only. /vis/scene/add/axes [] [] [] [] [] default: 0 0 0 1 m Draws axes at (x0, y0, z0) of given length. NI /vis/scene/add/ghost [] [] NI [] [] /vis/scene/add/ghosts [] default: all Adds ghost volumes (G4FlavoredParallelWorld) to the current scene. Selects by particle. /vis/scene/add/hits [] default: (argument not impl'd yet.) Causes hits, if any, to be drawn at the end of processiing an event. /vis/scene/add/logicalVolume [] default: 1 Draws a logical volume in its own coordinate system, showing voxels and boolean components (if any). /vis/scene/add/scale [ ] [x|y|z] [] [] [] [auto|manual] [ ] default: 1 m x 1 0 0 auto 0 0 0 m Adds an annotated scale line to the current scene. See G4Scale.hh for further description. /vis/scene/add/text x y z unit font_size x_offset y_offset text Adds text at (x*unit, y*unit, z*unit) with font_size x_offset y_offset Font size and offsets in pixels. /vis/scene/add/trajectories [drawing-mode] [] default: 0 (this argument not impl'd yet.) Causes trajectories, if any, to be drawn at the end of processiing an event. The drawing mode is an integer that is passed to the DrawTrajectory method. The default implementation in G4VTrajectory, if drawing-mode > 0, draws the trajectory as a polyline and, if drawing-mode != 0, draws markers of screen size abs(drawing-mode)/1000 in pixels at each step and auxiliary point, if any. So drawing-mode == 5000 is a good choice. (Enable storing with "/tracking/storeTrajectory 1".) See also "/vis/scene/endOfEventAction" and "/vis/scene/endOfRunAction". /vis/scene/add/volume [] [] [] default: world -1 -1 Adds physical volume to current scene. If copy-no is negative, first occurrence of physical-volume-name is selected. If depth is negative, search is made to all depths. /vis/scene/create [] default auto-generated name This scene becomes current. /vis/scene/endOfEventAction [accumulate|refresh] default: refresh The scene handler for this scene will, when a viewer of this scene is current, be requested: a) (accumulate) to accumulate "transient" objects, such as hits and trajectories event by event, or b) (refresh) to show them at end of event or, for direct-screen viewers, refresh the screen just before drawing the next event. Any "run-persistent" objects, such as dectector geometry components, are unaffected or are redrawn. /vis/scene/endOfRunAction [accumulate|refresh] default: refresh As endOfEventAction, but for end of run. /vis/scene/list [] [] default: all 0 Current scene remains current. /vis/scene/notifyHandlers [] [r[efresh]]|f[lush]] default: current scene name refresh Clears and refreshes all viewers of current scene and forces a reconstruction of any graphical databases. The default action "refresh" does not issue "update" (see /vis/viewer/update). If "flush" is specified, it issues an "update" as well as "refresh". Useful for refreshing and initiating post-processing for graphics systems which need post-processing. /vis/scene/remove Current scene can change or become invalid. /vis/scene/select [] default: current scene name This scene becomes current. Scene Handlers ============== A scene handler is an object which knows how to interpret a scene for a specific graphics system. Each scene handler handles one scene and has, in general, any number of viewers. The G4VisManager has a list of scene handlers. /vis/sceneHandler/attach [] default: current scene name Attaches scene to current scene handler. /vis/sceneHandler/create [] [] default: error auto-generated name (The first default simply triggers a list of possibilities.) This scene handler becomes current. The current scene, if any, is attached. /vis/sceneHandler/list [] [] default: all 0 Current scene handler remains current. NI /vis/sceneHandler/notifyEndOfProcessing Issues "update" for each viewer of current scene handler. NI /vis/sceneHandler/processScene Refreshes all viewers of current scene handler. Does not issue "update" (see /vis/viewer/update). /vis/sceneHandler/remove Current scene handler can change or become invalid. /vis/sceneHandler/select [] default: current scene handler name This scene handler becomes current. Viewers ======= A viewer opens windows and draws to the screen or writes to file for off-line viewing or hardcopy, etc. It can be dumb (a non-interactive window) or intelligent (respond to mouse clicks, spawn other windows, change viewpoint, etc.). Most viewer commands respond to the viewer "short name", which is the name up to the first space character, if any. Thus, a viewer name can contain spaces but must be unique up to the first space. Unless otherwise stated, commands affect the current viewer only. /vis/viewer/clear NI /vis/viewer/clone Creates a clone. Clone becomes current viewer. /vis/viewer/create [] [] [] default: current scene handler name auto-generated name 600 Pixel size of square window (hint only). This viewer becomes current. /vis/viewer/dolly [] [] default: current-value m Moves the camera incrementally in by this distance. /vis/viewer/dollyTo [] [] default: current-value m Moves the camera in this distance relative to standard target point. /vis/viewer/flush [] Compound command: /vis/viewer/refresh [] /vis/viewer/update [] Useful for refreshing and initiating post-processing for graphics systems which need post-processing. This viewer becomes current. /vis/viewer/list [] [] default: all 0 Current viewer remains current. /vis/viewer/pan [] [] [] default: 0 0 Moves the camera incrementally right and up by these amounts. /vis/viewer/panTo [] [] [] default: 0 0 Moves the camera to this position right and up relative to standard target point. /vis/viewer/refresh [] default: current viewer name Re-traverses graphical data, which is enough in some cases to refresh the view. In some cases post-processing is required to complete the view - see /vis/viewer/update. This viewer becomes current. /vis/viewer/remove default: no default Current viewer can change or become invalid. /vis/viewer/reset [] default: current viewer name Resets view parameters to defaults. This viewer becomes current. /vis/viewer/select default: no default This viewer becomes current. /vis/viewer/zoom [] default: 1 Multiplies magnification by this factor. /vis/viewer/zoomTo [] default: 1 Magnifies by this factor relative to standard view. /vis/viewer/set/all Copies view parameters (except the autoRefresh status) from from-viewer to current viewer. /vis/viewer/set/autoRefresh [true|false] default: false View is automatically refreshed after a change of view parameters. /vis/viewer/set/culling g[lobal]|c[overedDaughters]|i[nvisible]|d[ensity] [true|false] [density] [unit] default: none true 0.01 g/cm3 NI /vis/viewer/set/cutawayPlane ... Set plane(s) for cutaway views. /vis/viewer/set/edge [true|false] default: true /vis/viewer/set/globalMarkerScale [] default: 1 /vis/viewer/set/hiddenEdge [true|false] default: true /vis/viewer/set/hiddenMarker [true|false] default: true /vis/viewer/set/lightsMove with-camera|with-object /vis/viewer/set/lightsThetaPhi [] [] [deg|rad] default: 60 45 deg after first use: and use "current as default". /vis/viewer/set/lightsVector [] [] [] default: 1 1 1 after first use: current as default. Set direction of main lighting. /vis/viewer/set/lineSegmentsPerCircle [] default: 24 Number of sides per circle in polygon/polyhedron graphical representation of objects with curved lines/surfaces. /vis/viewer/set/projection o[rthogonal]|p[erspective] [] [deg|rad] default: none 30 deg /vis/viewer/set/sectionPlane ... Set plane for drawing section (DCUT). Specify plane by x y z units nx ny nz, e.g., for a y-z plane at x = 1 cm: /vis/viewer/set/sectionPlane on 1 0 0 cm 1 0 0 /vis/viewer/set/style w[ireframe]|s[urface] /vis/viewer/set/upThetaPhi [] [] [deg|rad] default: 90 90 deg after first use: and use "current as default". /vis/viewer/set/upVector [] [] [] default: 0 1 0 after first use: current as default. Set up vector. Viewer will attempt always to show this direction upwards. /vis/viewer/set/viewpointThetaPhi [] [] [deg|rad] default: 0 0 deg after first use: and use "current as default". /vis/viewer/set/viewpointVector [] [] [] default: 0 0 1 after first use: current as default. Set direction from target to camera. Also changes lightpoint direction if lights are set to move with camera. /vis/viewer/update [] default: current viewer name Initiates post-processing if required. This viewer becomes current. Attributes (nothing implemented yet) ========== The G4VisManager also keeps a list of visualization attributes which can be created and changed and attributed to visualizable objects. Unless otherwise stated, commands affect the visualization attributes of the current viewer only. NI /vis/attributes/create [] default: auto-generated name These attributes are passed to the current viewer??????????? NI /vis/attributes/set/colour [] [] [] [] [] NI /vis/attributes/set/color [] [] [] [] [] default: current attributes name 1 1 1 1 Sets colour (red, green, blue, opacity). NI /vis/scene/set/attributes Associates current vis attributes with logical volume. (Do we need to provide possibility of resetting to original attributes?) (Move to scene when implemented.) General Commands ================ /vis/enable [true|false] default: true /vis/disable Enables/disables visualization system. /vis/verbose [] default: warnings Simple graded message scheme - give first letter or a digit: 0) quiet, // Nothing is printed. 1) startup, // Startup and endup messages are printed... 2) errors, // ...and errors... 3) warnings, // ...and warnings... 4) confirmations, // ...and confirming messages... 5) parameters, // ...and parameters of scenes and views... 6) all // ...and everything available. Compound Commands ================= NI /vis/draw clashes with old /vis~/draw/, so... /vis/drawTree [] [] default: world ATree /vis/open $2 /vis/drawVolume $1 /vis/drawVolume [] default: world /vis/scene/create /vis/scene/add/volume $1 /vis/sceneHandler/attach /vis/drawView [] [] [] [] [] [] [] [] default: 0 0 0 0 cm 1 0 cm /vis/viewer/viewpointThetaPhi $1 $2 deg /vis/viewer/panTo $3 $4 $5 /vis/viewer/zoomTo $6 /vis/viewer/dollyTo $7 $8 /vis/open [] [<[pixels>] default: error 600 /vis/sceneHandler/create $1 /vis/viewer/create ! ! $2 /vis/specify /geometry/print $1 /vis/scene/create /vis/scene/add/logicalVolume $1 /vis/sceneHandler/attach Appendix ======== About the Visualization Manager: G4VisManager is a "Singleton", i.e., only one instance of it or any derived class may exist. A G4Exception is thrown if an attempt is made to instantiate more than one. It is also an abstract class, so the user must derive his/her own class from G4VisManager, implement the pure virtual function RegisterGraphicsSystems, and instantiate an object of the derived class - for an example see visualization/include/MyVisManager.hh/cc. The recommended way for users to obtain a pointer to the vis manager is with G4VVisManager::GetConcreteInstance (), being always careful to test for non-zero. This pointer is non-zero only when (a) an object of the derived class exists and (b) when there is a valid viewer available. The VisManager creates graphics systems, scenes, scene handlers and viewers and manages them. You can have any number. It has the concept of a "current viewer", and the "current scene handler", the "current scene" and the "current graphics system" which go with it. You can select the current viewer. Most of the the operations of the VisManager take place with the current viewer, in particular, the Draw operations. Each scene comprises drawable objects such as detector components and hits when appropriate. A scene handler translates a scene into graphics-system-specific function calls and, possibly, a graphics-system-dependent database - display lists, scene graphs, etc. Each viewer has its "view parameters" (see class description of G4ViewParameters for available parameters and also for a description of the concept of a "standard view" and all that). A friend class G4VisStateDependent is "state dependent", i.e., it is notified on change of state (G4ApplicationState). This is used to message the G4VisManager to draw hits and trajectories in the current scene at the end of event, as required. About Views and View Parameters: THE STANDARD VIEW AND ALL THAT. In GEANT4 visualization, we have the concept of a "Standard View". This is the view when the complete set of objects being viewed is comfortably in view from any viewpoint. It is defined by the "Bounding Sphere" of "visible" objects when initially registered in the scene, and by the View Parameters. There is also the "Standard Target Point", which is the centre of the Bounding Sphere (note that this belongs to the scene and is stored in the G4Scene object). The "Current Target Point", defined relative to the Standard Target Point, is changed by the "dolly" and "zoom" commands, and can be reset to the Standard Target Point with the "/vis/viewer/reset" command. Also, the "Standard Camera Position" is the "Standard Camera Distance" along the Viewpoint Direction vector from the Standard Target Point. The Standard Camera Distance is the radius of the Bounding Sphere divided by fFieldHalfAngle. It is not stored explicitly because of the singularity at fFieldHalfAngle = 0, which implies parallel projection. Similarly, the "Current Camera Position" is the "Current Camera Distance" along the Viewpoint Direction vector from the Current Target Point. The Current Camera Distance is given by the formulae below, but note that it can be negative, meaning that the camera has moved *beyond* the Current Target Point, which is conceptually possible, but which might give some problems when setting up the view matrix - see, for example, G4OpenGLView::SetView (). All viewers are expected to keep the "Up Vector" vertical. Finally, the view is magnified by the "Zoom Factor" which is reset to 1 by the "/vis/viewer/reset" command.