source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/GettingStarted/visualization.xml @ 921

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Update HepRApp reference: Joseph Perl, Dec-2008       -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Changed by: Katsuya Amako, 30-Nov-1998                -->
<!--    Changed by: Satoshi Tanaka,  1-Jun-2000               -->
<!--    Changed by: Dennis Wright, 29-Nov-2001                -->
<!--    Proof read by: Joe Chuma,  15-Jun-1999                -->
<!--                                                          -->
<!-- ******************************************************** -->

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.HowToVis">
<title>
How to Visualize the Detector and Events
</title>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToVis.Intro">
<title>
Introduction
</title>

<para>
This section briefly explains how to perform Geant4 Visualization.
The description here is based on the sample program
<literal>examples/novice/N03</literal>. More details are given in 
<xref linkend="chap.Visualization" /> "Visualization". 
Example macro files can be found in
<literal>examples/novice/N03/visTutor/exN03VisX.mac</literal>.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToVis.VisDrivers">
<title>
Visualization Drivers
</title>

<para>
The Geant4 visualization system was developed in response to a
diverse set of requirements:

<orderedlist spacing="compact">
  <listitem><para>
  Quick response to study geometries, trajectories and hits
  </para></listitem>
  <listitem><para>
  High-quality output for publications
  </para></listitem>
  <listitem><para>
  Flexible camera control to debug complex geometries
  </para></listitem>
  <listitem><para>
  Tools to show volume overlap errors in detector geometries
  </para></listitem>
  <listitem><para>
  Interactive picking to get more information on visualized objects
  </para></listitem>
</orderedlist>
</para>

<para>
No one graphics system is ideal for all of these requirements,
and many of the large software frameworks into which Geant4 has
been incorporated already have their own visualization systems, so
Geant4 visualization was designed around an abstract interface that
supports a diverse family of graphics systems. Some of these
graphics systems use a graphics library compiled with Geant4, such
as OpenGL, Qt or OpenInventor, while others involve a separate application, such as
HepRApp or DAWN.
</para>

<para>
You need not use all visualization drivers. You can select those
suitable to your purposes. In the following, for simplicity, we
assume that the Geant4 libraries are built (installed) with the
"OpenGL-Xlib driver" and the "DAWNFILE driver" incorporated.
</para>

<para>
In order to use the DAWNFILE driver, you need Fukui Renderer
DAWN, which is obtainable from the following Web site: 
<ulink url="http://geant4.kek.jp/GEANT4/vis">
http://geant4.kek.jp/GEANT4/vis</ulink>.
</para>

<para>
In order to use the the OpenGL drivers, you need the OpenGL
library, which is installed in many platforms by default. You also
need to set an environmental variable
<literal>G4VIS_BUILD_OPENGLX_DRIVER</literal> to <literal>1</literal> in 
building (installing) Genat4 libraries, and also set another environmental
variable <literal>G4VIS_USE_OPENGLX</literal> to <literal>1</literal> 
in compiling your Geant4 executable. You may also have to set an 
environmental variable <literal>OGLHOME</literal> to the OpenGL root 
directory. For example,

<informalexample>
<programlisting>
     setenv G4VIS_BUILD_OPENGLX_DRIVER 1
     setenv G4VIS_USE_OPENGLX 1
     setenv OGLHOME /usr/X11R6
</programlisting>
</informalexample>
</para>

<para>
Some other visualization drivers depending on external libraries
are also required to set the similar environmental variables,
<literal>G4VIS_BUILD_DRIVERNAME_DRIVER</literal> and
<literal>G4VIS_USE_DRIVERNAME</literal>, to <literal>1</literal>. All 
visualization drivers independent of external libraries, e.g. DAWNFILE and
VRMLFILE drivers, need not such setting. (But you must prepare a
proper visualization manager class and a proper <literal>main()</literal>
function, anyway. See below.)
</para>

<para>
For all visualization drivers available in your Geant4
executable, the C-pre-processor flags <literal>G4VIS_USE_DRIVERNAME</literal>
are automatically set by <literal>config/G4VIS_USE.gmk</literal> in
compilation. Similarly, for all visualization drivers incorporated
into the Geant4 libraries, the C-pre-processor flags
<literal>G4VIS_BUILD_DRIVERNAME_DRIVER</literal> are automatically set by
<literal>config/G4VIS_BUILD.gmk</literal> in installation.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToVis.IncorpVisDrivers">
<title>
How to Incorporate Visualization Drivers into an Executable
</title>

<para>
You can realize (use) visualization driver(s) you want in your
Geant4 executable. These can only be from the set installed in the
Geant4 libraries. You will be warned if the one you request is not
available.
</para>

<para>
In order to realize visualization drivers, you must instantiate
and initialize a subclass of <literal>G4VisManager</literal> that implements
the pure virtual function <literal>RegisterGraphicsSystems()</literal>. This
subclass must be compiled in the user's domain to force the loading
of appropriate libraries in the right order. The easiest way to do
this is to use <literal>G4VisExecutive</literal>, a provided class with
included implementation. <literal>G4VisExecutive</literal> is sensitive to
the <literal>G4VIS_USE...</literal> variables mentioned above.
</para>

<para>
If you do wish to write your own subclass, you may do so. You
will see how to do this by looking at <literal>G4VisExecutive.icc</literal>.
A typical extract is:

<informalexample>
<programlisting>
     ...
       RegisterGraphicsSystem (new G4DAWNFILE);
     ...
     #ifdef G4VIS_USE_OPENGLX
       RegisterGraphicsSystem (new G4OpenGLImmediateX);
       RegisterGraphicsSystem (new G4OpenGLStoredX);
     #endif
     ...
</programlisting>
</informalexample>
</para>

<para>
If you wish to use <literal>G4VisExecutive</literal> but register an
additional graphics system, <literal>XXX</literal> say, you may do so either
before or after initializing:

<informalexample>
<programlisting>
     visManager-&gt;RegisterGraphicsSytem(new XXX);
     visManager-&gt;Initialize();
</programlisting>
</informalexample>
</para>

<para>
An example of a typical <literal>main()</literal> function is given
below.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToVis.WritingMain">
<title>
Writing the <literal>main()</literal> Method to Include Visualization
</title>

<para>
Now we explain how to write a visualization manager and the
<literal>main()</literal> function for Geant4 visualization. In order that
your Geant4 executable is able to perform visualization, you must
instantiate and initialize <emphasis>your</emphasis> Visualization Manager 
in the <literal>main()</literal> function. The typical
<literal>main()</literal> 
function available for visualization is written in the following style:

<example id="programlist_HowToVis_1">
<title>
The typical <literal>main()</literal> routine available for visualization.
</title>
<programlisting>
 //----- C++ source codes: main() function for visualization
 #ifdef G4VIS_USE
 #include "G4VisExecutive.hh"
 #endif

 .....

 int main(int argc,char** argv) {

 .....

   // Instantiation and initialization of the Visualization Manager
 #ifdef G4VIS_USE
   // visualization manager
   G4VisManager* visManager = new G4VisExecutive;
   visManager-&gt;Initialize();
 #endif

 .....

   // Job termination
 #ifdef G4VIS_USE
   delete visManager;
 #endif

 .....

   return 0;
 }

 //----- end of C++
</programlisting>
</example>
</para>

<para>
In the instantiation, initialization, and deletion of the
Visualization Manager, the use of the macro <literal>G4VIS_USE</literal> is
recommended. This is set unless the environment variable
<literal>G4VIS_NONE</literal> is set. This allows one easily to build an
executable without visualization, if required, without changing the
code (but remember you have to force recompilation whenever you
change the environment). Note that it is your responsibility to
delete the instantiated Visualization Manager by yourself. A
complete description of a sample <literal>main()</literal> function is
described in <literal>examples/novice/N03/exampleN03.cc</literal>.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToVis.SampleVis">
<title>
Sample Visualization Sessions
</title>

<para>
In this section we present typical sessions of Geant4
visualization. You can test them with the sample program
geant4/examples/novice/N03. Run a binary executable "exampleN03"
without an argument, and then execute the commands below in the
"Idle&gt;" state. Explanation of each command will be described
later. (Note that the OpenGL-Xlib driver, Qt driver and the DAWNFILE driver
are incorporated into the executable, and that Fukui Renderer DAWN
is installed in your machine. )
</para>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToVis.SampleVis.VisDetector">
<title>
Visualization of detector components
</title>

<para>
The following session visualizes detector components with the
OpenGL-Xlib driver and then with the DAWNFILE driver. The former
exhibits minimal visualization commands to visualize detector
geometry, while the latter exhibits customized visualization
(visualization of a selected physical volume, coordinate axes,
texts, etc).

<informalexample>
<programlisting>
###################################################
#  vis1.mac:
#    A Sample macro to demonstrate visualization 
#    of detector geometry.
#
#  USAGE: 
#   Save the commands below as a macro file, say, 
#   "vis1.mac", and execute it as follows:
#
#   % $(G4BINDIR)/exampleN03
#   Idle&gt; /control/execute vis1.mac
#############################################

#############################################
# Visualization of detector geometry 
#  with the OGLIX (OpenGL Immediate X) driver
#############################################

# Invoke the OGLIX driver: 
#  Create a scene handler and a viewer for the OGLIX driver
/vis/open OGLIX

# Visualize the whole detector geometry 
#  with the default camera parameters.
#  Command "/vis/drawVolume" visualizes the detector geometry,
#  and command "/vis/viewer/flush" declares the end of visualization.
#  (The command /vis/viewer/flush  can be omitted for the OGLIX 
#   and OGLSX drivers.)
#  The default argument of "/vis/drawVolume" is "world".
/vis/drawVolume
/vis/viewer/flush

#########################################
# Visualization with the DAWNFILE driver
#########################################

# Invoke the DAWNFILE driver 
#  Create a scene handler and a viewer for the DAWNFILE driver
/vis/open DAWNFILE

# Bird's-eye view of a detector component (Absorber)
#  drawing style: hidden-surface removal
#  viewpoint  : (theta,phi) = (35*deg, 45*deg), 
#  zoom factor: 1.1 of the full screen size
#  coordinate axes:
#     x-axis:red,  y-axis:green,  z-axis:blue
#     origin: (0,0,0),  length: 500 mm
#
/vis/viewer/reset
/vis/viewer/set/style          surface
/vis/viewer/zoom               1.1 
/vis/viewer/set/viewpointThetaPhi  35 45
/vis/drawVolume                Absorber 
/vis/scene/add/axes            0 0 0 500 mm
/vis/scene/add/text            0 0 0 mm  40 -100 -140   Absorber 
/vis/viewer/flush

# Bird's-eye view of the whole detector components
#  * "/vis/viewer/set/culling global false" makes the invisible 
#    world volume visible.
#    (The invisibility of the world volume is set 
#     in ExN03DetectorConstruction.cc.)
/vis/viewer/set/style     wireframe
/vis/viewer/set/culling   global false
/vis/drawVolume
/vis/scene/add/axes       0 0 0 500 mm
/vis/scene/add/text       0 0 0 mm 50 -50 -200   world
/vis/viewer/flush
################### END of vis1.mac ###################
</programlisting>
</informalexample>
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToVis.SampleVis.VisEvents">
<title>
Visualization of events
</title>

<para>
The following session visualizes events (tajectories) with the
OpenGL-Xlib driver and then with the DAWNFILE driver. The former
exhibits minimal visualization commands to visualize events, while
the latter exhibits customized visualization. Note that the run
action and event action classes should be described properly. (See,
for example, the following classes:
"examples/novice/N03/src/ExN03RunAction.cc",

<informalexample>
<programlisting>
###################################################
#  vis2.mac:
#    A Sample macro to demonstrate visualization 
#    of events (trajectories).
#
#  USAGE: 
#   Save the commands below as a macro file, say, 
#   "vis2.mac", and execute it as follows:
#
#   % $(G4BINDIR)/exampleN03
#   Idle&gt; /control/execute vis1.mac
#############################################

#####################################################
# Store particle trajectories for visualization
/tracking/storeTrajectory 1
#####################################################

########################################################
# Visualization with the OGLSX (OpenGL Stored X) driver
########################################################

# Invoke the OGLSX driver 
#  Create a scene handler and a viewer for the OGLSX driver
/vis/open OGLSX

# Create an empty scene and add detector components to it
/vis/drawVolume

# Add trajectories to the current scene
#  Note: This command is not necessary in, e.g., 
#        examples/novice/N03, since the C++ method DrawTrajectory() 
#        is described in the event action.
#/vis/scene/add/trajectories

# Set viewing parameters
/vis/viewer/reset
/vis/viewer/set/viewpointThetaPhi  10 20

# Visualize one it.
/run/beamOn 1

##########################################################
# Visualization with the DAWNFILE driver
##########################################################

# Invoke the DAWNFILE driver 
#  Create a scene handler and a viewer for the DAWNFILE driver
/vis/open DAWNFILE

# Create an empty scene and add detector components to it
/vis/drawVolume

# Add trajectories to the current scene
#  Note: This command is not necessary in exampleN03,
#        since the C++ method DrawTrajectory() is 
#        described in the event action.
#/vis/scene/add/trajectories

# Visualize plural events (bird's eye view)
#  drawing style: wireframe
#  viewpoint  : (theta,phi) = (45*deg, 45*deg) 
#  zoom factor: 1.5 x (full screen size)
/vis/viewer/reset
/vis/viewer/set/style  wireframe
/vis/viewer/set/viewpointThetaPhi   45 45
/vis/viewer/zoom        1.5
/run/beamOn             2

# Set the drawing style to "surface" 
#  Candidates: wireframe, surface
/vis/viewer/set/style  surface

# Visualize plural events (bird's eye view) again
#  with another drawing style (surface)
/run/beamOn             2

################### END of vis2.mac ###################
</programlisting>
</informalexample>
</para>

</sect3>
</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToVis.MoreInfo">
<title>
For More Information on Geant4 Visualization
</title>

<para>
See the <xref linkend="chap.Visualization" /> "Visualization" 
part of this user guide.
</para>


</sect2>
</sect1>