source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Visualization/visdrivers.xml @ 921

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Changed by: Dennis Wright, 27-Nov-2001                -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Updates for Qt and HepRApp: Joseph Perl, Dec-2008     -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.VisDrv">
<title>
The Visualization Drivers
</title>

<para>
As explained in the 
<!-- !!! xref linkend=""/ or ulink url="" -->
Introduction to Visualization
<!-- !! /ulink (remove this tag for xref) -->
, Geant4 provides many different choices of
visualization systems. Features and notes on each driver are
briefly described here along with links to detailed web pages for
the various drivers.
</para>

<para>
Details are given below for:

<itemizedlist spacing="compact">
  <listitem><para>
    <xref linkend="sect.VisDrv.OpenGL" />
    OpenGL
  </para></listitem>
  <listitem><para>
    <xref linkend="sect.VisDrv.Qt" />
    Qt
  </para></listitem>
  <listitem><para>
    <xref linkend="sect.VisDrv.OpenInv" />
    OpenInventor
  </para></listitem>
  <listitem><para>
    <xref linkend="sect.VisDrv.HepRep" />
    HepRepFile
  </para></listitem>
  <listitem><para>
    <xref linkend="sect.VisDrv.HepRepXML" />
    HepRepXML
  </para></listitem>
  <listitem><para>
    <xref linkend="sect.VisDrv.DAWN" />
    DAWN
  </para></listitem>
  <listitem><para>
    <xref linkend="sect.VisDrv.VRML" />
    VRML
  </para></listitem>
  <listitem><para>
    <xref linkend="sect.VisDrv.RayTrc" />
    RayTracer
  </para></listitem>
  <listitem><para>
    <xref linkend="sect.VisDrv.DetTree" />
    ASCIITree
  </para></listitem>
  <listitem><para>
    <xref linkend="sect.VisDrv.GAGTree" />
    GAGTree
  </para></listitem>
  <listitem><para>
    <xref linkend="sect.VisDrv.XMLTree" />
    XMLTree
  </para></listitem>
</itemizedlist>
</para>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.Avail">
<title>
Availability of drivers on the supported systems
</title>

<para>
<xref linkend="table.VisDrv_1" /> lists required graphics systems 
and supported platforms for the various visualization drivers

<table id="table.VisDrv_1">
<title>
Required graphics systems and supported platforms for the various 
visualization drivers.
</title>

<tgroup cols="3">
  <tbody>
  <row>
    <entry>
      <emphasis role="bold">Driver</emphasis>
    </entry>
    <entry>
      <emphasis role="bold">Required Graphics System</emphasis>
    </entry>
    <entry>
      <emphasis role="bold">Platform</emphasis>
    </entry>
  </row>
  <row>
    <entry>
      OpenGL-Xlib
    </entry>
    <entry>
      OpenGL
    </entry>
    <entry>
      Linux, UNIX, Mac with Xlib
    </entry>
  </row>
  <row>
    <entry>
      OpenGL-Motif
    </entry>
    <entry>
      OpenGL
    </entry>
    <entry>
      Linux, UNIX, Mac with Motif
    </entry>
  </row>
  <row>
    <entry>
      OpenGL-Win32
    </entry>
    <entry>
      OpenGL
    </entry>
    <entry>
      Windows
    </entry>
  </row>
  <row>
    <entry>
      Qt
    </entry>
    <entry>
      Qt, OpenGL
    </entry>
    <entry>
      Linux, UNIX, Mac, Windows
    </entry>
  </row>
  <row>
    <entry>
      OpenInventor-X
    </entry>
    <entry>
      OpenInventor, OpenGL
    </entry>
    <entry>
      Linux, UNIX, Mac with Xlib or Motif
    </entry>
  </row>
  <row>
    <entry>
      OpenInventor-Win32
    </entry>
    <entry>
      OpenInventor, OpenGL
    </entry>
    <entry>
      Windows
    </entry>
  </row>
  <row>
    <entry>
      HepRep
    </entry>
    <entry>
      HepRApp, FRED or WIRED4 HepRep Browser
    </entry>
    <entry>
      Linux, UNIX, Mac, Windows
    </entry>
  </row>
  <row>
    <entry>
      DAWNFILE
    </entry>
    <entry>
      Fukui Renderer DAWN
    </entry>
    <entry>
      Linux, UNIX, Mac, Windows
    </entry>
  </row>
  <row>
    <entry>
      DAWN-Network
    </entry>
    <entry>
      Fukui Renderer DAWN
    </entry>
    <entry>
      Linux, UNIX
    </entry>
  </row>
  <row>
    <entry>
      VRMLFILE
    </entry>
    <entry>
      any VRML viewer
    </entry>
    <entry>
      Linux, UNIX, Mac, Windows
    </entry>
  </row>
  <row>
    <entry>
      VRML-Network
    </entry>
    <entry>
      any network-enabled VRML viewer
    </entry>
    <entry>
      Linux, UNIX
    </entry>
  </row>
  <row>
    <entry>
      RayTracer
    </entry>
    <entry>
      any JPEG viewer
    </entry>
    <entry>
      Linux, UNIX, Mac, Windows
    </entry>
  </row>
  <row>
    <entry>
      ASCIITree
    </entry>
    <entry>
      none
    </entry>
    <entry>
      Linux, UNIX, Mac, Windows
    </entry>
  </row>
  <row>
    <entry>
      GAGTree
    </entry>
    <entry>
      GAG
    </entry>
    <entry>
      Linux, UNIX, Mac, Windows
    </entry>
  </row>
  <row>
    <entry>
      XMLTree
    </entry>
    <entry>
      any XML viewer
    </entry>
    <entry>
      Linux, UNIX, Mac, Windows
    </entry>
  </row>
  </tbody>
</tgroup>
</table>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.OpenGL">
<title>
OpenGL
</title>

<para>
These drivers have been developed by John Allison and Andrew
Walkden (University of Manchester). It is an interface to the de
facto standard 3D graphics library, OpenGL. It is well suited for
real-time fast visualization and demonstration. Fast visualization
is realized with hardware acceleration, reuse of shapes stored in a
display list, etc. NURBS visualization is also supported.
</para>

<para>
Several versions of the OpenGL drivers are prepared. Versions
for Xlib, Motif and Win32 platforms are available by default. For
each version, there are two modes: immediate mode and stored mode.
The former has no limitation on data size, and the latter is fast
for visualizing large data repetitively, and so is suitable for
animation.
</para>

<para>
Output can be exported to EPS (both vector and pixel graphics)
using vis/ogl/printEPS.
</para>

<para>
If you don't have Motif or Qt, all control is done from Geant4
commands:

<?soft-pagebreak ?>
<informalexample>
<programlisting>
     /vis/open OGLIX
     /vis/viewer/set/viewpointThetaPhi 70 20
     /vis/viewer/zoom 2
     etc.
</programlisting>
</informalexample>
</para>

<para>
But if you have Motif libraries, you can control Geant4 from Motif
widgets:

<informalexample>
<programlisting>
     /vis/open OGLIXm
</programlisting>
</informalexample>
</para>

<para>
If you have Qt, see the Qt section below.
</para>

<para>
The OpenGL driver added Smooth shading and Transparency since
Geant4 release 8.0.
</para>

<para>
<emphasis role="bold">Further information (OpenGL and Mesa):</emphasis>

<itemizedlist spacing="compact">
  <listitem><para>
    <ulink url="http://www.opengl.org/">
    http://www.opengl.org/
    </ulink>
  </para></listitem>
  <listitem><para>
    <ulink url="http://www.mesa3d.org">
    http://www.mesa3d.org
    </ulink>
  </para></listitem>
  <listitem><para>
    <ulink url="http://geant4.slac.stanford.edu/Presentations/vis/G4OpenGLTutorial/G4OpenGLTutorial.html">
    Geant4 Visualization Tutorial
    </ulink>
    using the OpenGL Graphics System
  </para></listitem>
</itemizedlist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.Qt">
<title>
Qt
</title>

<para>
This driver has been developed by Laurent Garnier (IN2P3, LAL Orsay).  
It is an interface to the powerful application framework, Qt, now free on most  
platforms. This driver also requires the OpenGL library.
</para><para>
The Qt driver is well suited for real-time fast visualization and demonstration.
Fast visualization is realized with hardware acceleration, reuse of shapes stored in a 
display list, etc. NURBS visualization is also supported. All OpenGL  
features are implemented in the Qt driver, but one also gets mouse
control of rotation/translation/zoom, the ability to save your scene in many formats
(both vector and pixel graphics) and an easy interface for making movies.
</para><para> 
Two display modes are available: immediate mode and stored mode. 
The former has no limitation on data size, and the latter is fast 
for visualizing large data repetitively, and so is suitable for 
animation. 
</para>

<para>
To see the visualization window : 

<?soft-pagebreak ?>
<informalexample>
<programlisting>
     /vis/open OGLSQt  (for Stored mode)
or
     /vis/open OGLIQt  (for Immediate mode)
</programlisting>
</informalexample>
</para>

<para>
<emphasis role="bold">Further information (Qt):</emphasis>
<itemizedlist spacing="compact">
  <listitem><para>
    <ulink url="http://trolltech.com/">
    Qt
    </ulink>
  </para></listitem>
  <listitem><para>
    <ulink url="http://users.lal.in2p3.fr/garnier/G4QtTutorial.html">
    Geant4 Visualization Tutorial
    </ulink>
    using the Qt Driver
  </para></listitem>
</itemizedlist>
</para>
</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.OpenInv">
<title>
OpenInventor
</title>

<para>
These drivers were developed by Jeff Kallenbach (FNAL) and Guy
Barrand (IN2P3) based on the 
<ulink url="http://www-pat.fnal.gov/graphics/HEPVis/www">
Hepvis class library
</ulink>
 originated by Joe Boudreau (Pittsburgh University). The
OpenInventor drivers and the Hepvis class library are based on the
well-established OpenInventor technology for scientific
visualization. They have high extendibility. They support high
interactivity, e.g., attribute e diting of picked objects. Some
OpenInventor viewers support "stereoscopic" effects.
</para>

<para>
It is also possible to save a visualized 3D scene as an
OpenInventor-formatted file, and re-visualize the scene
afterwards.
</para>

<para>
Because it is connected directly to the Geant4 kernel, using
same language as that kernel (C++), OpenInventor systems can have
direct access to Geant4 data (geometry, trajectories, etc.).
</para>

<para>
Because OpenInventor uses OpenGL for rendering, it supports
lighting and transparency.
</para>

<para>
OpenInventor provides thumbwheel control to rotate and zoom.
</para>

<para>
OpenInventor supports picking to ask about data. [Control
Clicking] on a volume turns on rendering of that volume's
daughters. [Shift Clicking] a daughter turns that rendering off: If
modeling opaque solid, effect is like opening a box to look
inside.
</para>

<para>
<emphasis role="bold">Further information (HEPVis and OpenScientist):</emphasis>

<itemizedlist spacing="compact">
  <listitem><para>
    Geant4 Inventor Visualization with OpenScientist 
    <ulink url="http://openscientist.lal.in2p3.fr/v15r0/html/osc_g4_vis_ui.html">
    http://openscientist.lal.in2p3.fr/v15r0/html/osc_g4_vis_ui.html
    </ulink>
  </para></listitem>
  <listitem><para>
    Overall OpenScientist Home 
    <ulink url="http://openscientist.lal.in2p3.fr/v15r0/html/osc_g4_vis_ui.html">
    http://openscientist.lal.in2p3.fr/v15r0/html/osc_g4_vis_ui.html
    </ulink>
  </para></listitem>
  <listitem><para>
    HEPVis
    <ulink url="http://www-pat.fnal.gov/graphics/HEPVis/www">
    http://www-pat.fnal.gov/graphics/HEPVis/www
    </ulink>
  </para></listitem>
</itemizedlist>
</para>

<para>
<emphasis role="bold">Further information (OpenInventor):</emphasis>

<itemizedlist spacing="compact">
  <listitem><para>
    <ulink url="http://oss.sgi.com/projects/inventor">
      http://oss.sgi.com/projects/inventor
    </ulink>
  </para></listitem>
  <listitem><para>
    Josie Wernecke, "The Inventor Mentor", Addison Wesley 
    (ISBN 0-201-62495-8)
  </para></listitem>
  <listitem><para>
    Josie Wernecke, "The Inventor Toolmaker", Addison Wesley 
    (ISBN 0-201-62493-1)
  </para></listitem>
  <listitem><para>
    "The Open Inventor C++ Reference Manual", Addison Wesley 
    (ISBN 0-201-62491-5)
  </para></listitem>
</itemizedlist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.HepRep">
<title>
HepRepFile
</title>

<para>
The HepRepFile driver creates a HepRep XML file in the HepRep1
format suitable for viewing with the 
<ulink url="http://www.slac.stanford.edu/~perl/HepRApp/">
HepRApp</ulink> HepRep Browser.
</para>

<para>
The HepRep graphics format is further described at 
<ulink url="http://www.slac.stanford.edu/~perl/heprep">
http://www.slac.stanford.edu/~perl/heprep
</ulink>
.
</para>

<para>
To write just the detector geometry to this file, use the
command:

<informalexample>
<programlisting>
     /vis/viewer/flush
</programlisting>
</informalexample>
</para>

<para>
Or, to also include trajectories and hits (after the appropriate
/vis/viewer/add/trajectories or /vis/viewer/add/hits commands),
just issue:

<informalexample>
<programlisting>
     /run/beamOn 1
</programlisting>
</informalexample>
</para>

<para>
HepRepFile will write a file called G4Data0.heprep to the
current directory. Each subsequent file will have a file name like
G4Data1.heprep, G4Data2.heprep, etc.
</para>

<para>
View the file using the HepRApp HepRep Browser, available from:
</para>
<para>
<ulink url="http://www.slac.stanford.edu/~perl/HepRApp/">
http://www.slac.stanford.edu/~perl/HepRApp/
</ulink>
.
</para>

<para>
HepRApp allows you to pick on volumes, trajectories and hits to
find out their associated HepRep Attributes, such as volume name,
particle ID, momentum, etc. These same attributes can be displayed
as labels on the relevant objects, and you can make visibility cuts
based on these attributes ("show me only the photons", or "omit any
volumes made of iron").
</para>

<para>
HepRApp can read heprep files in zipped format as well as
unzipped, so you can save space by applying gzip to the heprep
file. This will reduce the file to about five percent of its
original size.
</para>

<para>
Several environment variables are available to override some of
HepRepFile's defaults

<itemizedlist spacing="compact">
  <listitem><para>
    You can specify a different directory for the heprep output
    files by setting the environment variable G4HEPREPFILE_DIR, as in:

    <informalexample>
    <programlisting>
     export G4HEPREPFILE_DIR=someOtherDir/someOtherSubDir
    </programlisting>
    </informalexample>
  </para></listitem>
  <listitem><para>
    You can specify a different file name (the part before the
    number) by setting the environment variable G4HEPREPFILE_NAME, as in:

    <informalexample>
    <programlisting>
     export G4HEPREPFILE_NAME=myFileName
    </programlisting>
    </informalexample>

    which will produce files named myFileName0.heprep,
    myFileName1.heprep, etc.
  </para></listitem>
  <listitem><para>
    You can specify that each file should overwrite the previous
    file (always rewriting to the same file name) by setting the
    environment variable G4HEPREPFILE_OVERWRITE, as in:

    <informalexample>
    <programlisting>
     export G4HEPREPFILE_OVERWRITE=1
    </programlisting>
    </informalexample>

    This may be useful in some automated applications where you always
    want to see the latest output file in the same location.
  </para></listitem>
</itemizedlist>

<?soft-pagebreak ?>
<itemizedlist>
  <listitem><para>
    Geant4 visualization supports a concept called "culling", by
    which certain parts of the detector can be made invisible. Since
    you may want to control visibility from the HepRep browser, turning
    on visibility of detector parts that had defaulted to be invisible,
    the HepRepFile driver does not omit these invisible detector parts
    from the HepRep file. But for very large files, if you know that
    you will never want to make these parts visible, you can choose to
    have them left entirely out of the file. Set the environment
    variable G4HEPREPFILE_CULL, as in:

    <informalexample>
    <programlisting>
     export G4HEPREPFILE_CULL=1
    </programlisting>
    </informalexample>
  </para></listitem>
</itemizedlist>
</para>

<para>
<emphasis role="bold">Further information:</emphasis>

<itemizedlist spacing="compact">
  <listitem><para>
    HepRApp Users Home Page:
    <para>
    <ulink url="http://www.slac.stanford.edu/~perl/HepRApp/">
    http://www.slac.stanford.edu/~perl/HepRApp/
    </ulink>
    .
    </para>
  </para></listitem>
  <listitem><para>
    HepRep graphics format:
    <para>
    <ulink url="http://www.slac.stanford.edu/~perl/heprep">
    http://www.slac.stanford.edu/~perl/heprep
    </ulink>
    </para>
  </para></listitem>
  <listitem><para>
    Geant4 Visualization Tutorial using the HepRApp HepRep Browser
    <para>
    <ulink url="http://geant4.slac.stanford.edu/Presentations/vis/G4HepRAppTutorial/G4HepRAppTutorial.html">
    http://geant4.slac.stanford.edu/Presentations/vis/G4HepRAppTutorial/G4HepRAppTutorial.html
    </ulink>
    </para>
  </para></listitem>
</itemizedlist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.HepRepXML">
<title>
HepRepXML
</title>

<para>
The HepRepXML driver creates a HepRep file in the HepRep2 format
suitable for viewing with the 
<ulink url="http://wired.freehep.org/index.html">
WIRED4 
</ulink>
 Plugin to the JAS3 Analysis System or the 
<ulink url="http://www.fisica.uniud.it/~glast/FRED/">
FRED 
</ulink>
 event display.
</para>

<para>
This driver can write both Binary HepRep (.bheprep) and XML
HepRep (.heprep) files. Binary HepRep files are a one-to-one
translation of XML HepRep files, but they are considerably shorter
and faster to parse by a HepRepViewer such as WIRED 4.
</para>

<para>
Both Binary HepRep and XML HepRep can be compressed using the
standard zlib library if linked into Geant4 using G4LIB_USE_ZLIB.
If a standard zlib is not available (WIN32-VC for instance) you
should also set G4LIB_BUILD_ZLIB to build G4zlib included with
Geant4.
</para>

<para>
HepRep files (Binary and XML) can contain multiple HepRep
events/geometries. If the file contains more than one HepRep it is
not strictly XML anymore. Files can be written in .heprep.zip,
.heprep.gz or .heprep format and their binary versions
.bheprep.zip, .bheprep.gz or .bheprep.
</para>

<para>
The .heprep.zip is the default for file output, the .heprep is
the default for stdout and stderr.
</para>

<para>
(Optional) To set the filename with a particular extension such
as: .heprep.zip, .heprep.gz, .heprep, .bheprep.zip, .bheprep.gz or
.bheprep use for instance:

<informalexample>
<programlisting>
     /vis/scene/create filename.bheprep.zip
</programlisting>
</informalexample>
</para>

<para>
(Optional) To create separate files for each event, you can set
a suffix such as "-0001" to start writing files from
filename-0001.bheprep.zip to filename-9999.bheprep.zip (or up),
while "-55-sub" will start write files filename-55-sub.bheprep.zip
to filename-99-sub.bheprep.zip (or up).

<informalexample>
<programlisting>
     /vis/heprep/setEventNumberSuffix -0001
</programlisting>
</informalexample>
</para>

<para>
(Note: suffix has to contain at least one digit)
</para>

<para>
(Optional) To route the HepRep XML output to stdout (or stderr),
by default uncompressed, use:

<informalexample>
<programlisting>
     /vis/scene/create stdout
</programlisting>
</informalexample>
</para>

<para>
(Optional) To add attributes to each point on a trajectory, use:

<informalexample>
<programlisting>
     /vis/heprep/addPointAttributes 1
</programlisting>
</informalexample>
</para>

<para>
Be aware that this may increase the size of the output
dramatically.
</para>

<para>
(Optional) You may use the commands:

<informalexample>
<programlisting>
     /vis/viewer/zoom                            to set an initial zoom factor

     /vis/viewer/set/viewpointThetaPhi           to set an initial view point

     /vis/heprep/setCoordinateSystem uvw         to change the coordinate system, where uvw 
                                                 can be "xyz", "zxy", ...
</programlisting>
</informalexample>
</para>

<para>
(Optional) You may decide to write .zip files with events and
geometry separated (but linked). This results in a smaller zip
file, as the geometry is only written once. Use the command:

<informalexample>
<programlisting>
     /vis/heprep/appendGeometry false
</programlisting>
</informalexample>
</para>

<para>
(Optional) To close the file, remove the SceneHandler, use:

<informalexample>
<programlisting>
     /vis/sceneHandler/remove scene-handler-0
</programlisting>
</informalexample>
</para>

<para>
Limitations: Only one SceneHandler can exist at any time,
connected to a single Viewer. Since the HepRep format is a model
rather than a view this is not a real limitation. In WIRED 4 you
can create as many views (SceneHandlers) as you like.
</para>

<para>
<emphasis role="bold">Further information:</emphasis>

<itemizedlist spacing="compact">
  <listitem><para>
    <ulink url="http://wired.freehep.org/index.html">
    WIRED4</ulink> Plugin to the JAS3 Analysis System
  </para></listitem>
  <listitem><para>
    <ulink url="http://www.fisica.uniud.it/~glast/FRED/">
    FRED</ulink> event display
  </para></listitem>
  <listitem><para>
    HepRep graphics format:
    <para>
    <ulink url="http://www.slac.stanford.edu/~perl/heprep">
    http://www.slac.stanford.edu/~perl/heprep
    </ulink>
    </para>
  </para></listitem>
</itemizedlist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.DAWN">
<title>
DAWN
</title>

<para>
The DAWN drivers are interfaces to 
<ulink url="http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAWN.html">
Fukui Renderer DAWN</ulink>, which has been developed by Satoshi Tanaka,
Minato Kawaguti et al (Fukui University). It is a vectorized 3D
PostScript processor, and so well suited to prepare technical high
quality outputs for presentation and/or documentation. It is also
useful for precise debugging of detector geometry. Remote
visualization, off-line re-visualization, cut view, and many other
useful functions of detector simulation are supported. A DAWN
process is automatically invoked as a co-process of Geant4 when
visualization is performed, and 3D data are passed with
inter-process communication, via a file, or the TCP/IP socket.
</para>

<para>
When Geant4 Visualization is performed with the DAWN driver, the
visualized view is automatically saved to a file named
<literal>g4.eps</literal> in the current directory, which describes a
vectorized (Encapsulated) PostScript data of the view.
</para>

<para>
There are two kinds of DAWN drivers, the DAWNFILE driver and the
DAWN-Network driver. The DAWNFILE driver is usually recommended,
since it is faster and safer in the sense that it is not affected
by network conditions.
</para>

<para>
The DAWNFILE driver sends 3D data to DAWN via an intermediate
file, named <literal>g4.prim</literal> in the current directory. The file
<literal>g4.prim</literal> can be re-visualized later without the help of
Geant4. This is done by invoking DAWN by hand:

<informalexample>
<programlisting>
     % dawn g4.prim 
</programlisting>
</informalexample>
</para>

<para>
DAWN files can also serve as input to two additional programs:

<itemizedlist spacing="compact">
  <listitem><para>
    A standalone program, DAWNCUT, can perform a planar cut on a
    DAWN image. DAWNCUT takes as input a .prim file and some cut
    parameters. Its output is a new .prim file to which the cut has
    been applied.
  </para></listitem>
  <listitem><para>
    Another standalone program, DAVID, can show you any volume
    overlap errors in your geometry. DAVID takes as input a .prim file
    and outputs a new .prim file in which overlapping volumes have been
    highlighted. The use of DAVID is described in section 
    <xref linkend="sect.Geom.Overlap" /> of this manual.
  </para></listitem>
</itemizedlist>
</para>

<para>
The DAWN-Network driver is almost the same as the DAWNFILE
driver except that

<itemizedlist spacing="compact">
  <listitem><para>
    3D data are passed to DAWN via the TCP/IP the socket (default)
    or the named pipe, and that,
  </para></listitem>
</itemizedlist>
</para>

<para>
If you have not set up network configurations of your host machine,
set the environment variable <literal>G4DAWN_NAMED_PIPE</literal> to "1",
e.g., <literal>% setenv G4DAWN_NAMED_PIPE 1</literal>. This setting switches
the default socket connection to the named-pipe connection within
the same host machine. The DAWN-Network driver also saves the 3D
data to the file <literal>g4.prim</literal> in the current directory.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.RemDAWN">
<title>
Remote Visualization with the DAWN-Network Driver
</title>

<para>
Visualization in Geant4 is considered to be "remote" when it is
performed on a machine other than the Geant4 host. Some of the
visualization drivers support this feature.
</para>

<para>
Usually, the visualization host is your local host, while the
Geant4 host is a remote host where you log in, for example, with
the <literal>telnet</literal> command. This enables distributed 
processing of Geant4 visualization, avoiding the transfer of large 
amounts of visualization data to your terminal display via the 
network. This section describes how to perform remote Geant4 
visualization with the DAWN-Network driver. In order to do it, 
you must install the Fukui Renderer DAWN on your local host 
beforehand.
</para>

<para>
The following steps realize remote Geant4 visualization viewed
by DAWN.

<orderedlist spacing="compact">
  <listitem><para>
    Invoke DAWN with "-G" option on your local host:

    <informalexample>
    <programlisting>
       Local_Host&gt; dawn -G
    </programlisting>
    </informalexample>

    This invokes DAWN with the network connection mode.
  </para></listitem>
  <listitem><para>
    Login to the remote host where a Geant4 executable is placed.
  </para></listitem>
  <listitem><para>
    Set an environment variable on the remote host as follows:

    <informalexample>
    <programlisting>
       Remote_Host&gt; setenv G4DAWN_HOST_NAME local_host_name
    </programlisting>
    </informalexample>

    For example, if you are working in the local host named
    "arkoop.kek.jp", set this environment variable as follows:

    <informalexample>
    <programlisting>
       Remote_Host&gt; setenv G4DAWN_HOST_NAME arkoop.kek.jp
    </programlisting>
    </informalexample>

    This tells a Geant4 process running on the remote host where Geant4
    Visualization should be performed, i.e., where the visualized views
    should be displayed.
  </para></listitem>
  <listitem><para>
    Invoke a Geant4 process and perform visualization with the
    DAWN-Network driver. For example:

    <informalexample>
    <programlisting>
       Idle&gt; /vis/open DAWN
       Idle&gt; /vis/drawVolume 
       Idle&gt; /vis/viewer/flush
    </programlisting>
    </informalexample>      
  </para></listitem>
</orderedlist>
</para>

<para>
In step 4, 3D scene data are sent from the remote host to the
local host as 
<ulink url="http://geant4.kek.jp/GEANT4/vis/DAWN/G4PRIM_FORMAT_24/">
DAWN-formatted data</ulink>, and the local DAWN will visualize the data. The
transferred data are saved as a file named <literal>g4.prim</literal> in the
current directory of the local host.
</para>

<para>
<emphasis role="bold">Further information:</emphasis>

<itemizedlist spacing="compact">
  <listitem><para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAWN.html">
    http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAWN.html
    </ulink>
  </para></listitem>
  <listitem><para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/DAWN/G4PRIM_FORMAT_24/">
    http://geant4.kek.jp/GEANT4/vis/DAWN/G4PRIM_FORMAT_24/
    </ulink>
  </para></listitem>
</itemizedlist>
</para>

<para>
<emphasis role="bold">Further information:</emphasis>

<itemizedlist spacing="compact">
  <listitem><para>
    Fukui Renderer DAWN:
    <para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAWN.html">
    http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAWN.html
    </ulink>
    </para>
  </para></listitem>
  <listitem><para>
    The DAWNFILE driver:
    <para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/GEANT4/DAWNFILE_driver.html">
    http://geant4.kek.jp/GEANT4/vis/GEANT4/DAWNFILE_driver.html
    </ulink>
    </para>
  </para></listitem>
  <listitem><para>
    The DAWN-Network driver:
    <para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/GEANT4/DAWNNET_driver.html">
    http://geant4.kek.jp/GEANT4/vis/GEANT4/DAWNNET_driver.html
    </ulink>
    </para>
  </para></listitem>
  <listitem><para>
    Environmental variables to customize DAWN and DAWN drivers:
    <para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/DAWN/DAWN_ENV.html">
    http://geant4.kek.jp/GEANT4/vis/DAWN/DAWN_ENV.html
    </ulink>
    </para>
    <para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/GEANT4/g4vis_on_linux.html">
    http://geant4.kek.jp/GEANT4/vis/GEANT4/g4vis_on_linux.html
    </ulink>
    </para>
  </para></listitem>
  <listitem><para>
    DAWN format (g4.prim format) manual:
    <para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/DAWN/G4PRIM_FORMAT_24/">
    http://geant4.kek.jp/GEANT4/vis/DAWN/G4PRIM_FORMAT_24/
    </ulink>
    </para>
  </para></listitem>
  <listitem><para>
    Geant4 Fukui University Group Home Page:
    <para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/">
    http://geant4.kek.jp/GEANT4/vis/
    </ulink>
    </para>
  </para></listitem>
  <listitem><para>
    DAWNCUT:
    <para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAWNCUT.html">
    http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAWNCUT.html
    </ulink>
    </para>
  </para></listitem>
  <listitem><para>
   DAVID:
   <para>
   <ulink url="http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAVID.html">
   http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAVID.html
   </ulink>
   </para> 
  </para></listitem>
  <listitem><para>
    Geant4 Visualization Tutorial using the DAWN Renderer: 
    <para>
    <ulink url="http://geant4.slac.stanford.edu/Presentations/vis/GDAWNTutorial/G4DAWNTutorial.html">
    http://geant4.slac.stanford.edu/Presentations/vis/GDAWNTutorial/G4DAWNTutorial.html
    </ulink>
    </para>
  </para></listitem>
</itemizedlist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.VRML">
<title>
VRML
</title>

<para>
These drivers were developed by Satoshi Tanaka and Yasuhide Sawada
(Fukui University). They generate VRML files, which describe 3D
scenes to be visualized with a proper VRML viewer, at either a
local or a remote host. It realizes virtual-reality visualization
with your WWW browser. There are many excellent VRML viewers, which
enable one to perform interactive spinning of detectors, walking
and/or flying inside detectors or particle showers, interactive
investigation of detailed detector geometry etc.
</para>

<para>
There are two kinds of VRML drivers: the VRMLFILE driver, and
the VRML-Network driver. The VRMLFILE driver is usually
recommended, since it is faster and safer in the sense that it is
not affected by network conditions.
</para>

<para>
The VRMLFILE driver sends 3D data to your VRML viewer, which is
running on the same host machine as Geant4, via an intermediate
file named <literal>g4.wrl</literal> created in the current directory. This
file can be re-visualization afterwards. In visualization, the name
of the VRML viewer should be specified by setting the environment
variable <literal>G4VRML_VIEWER</literal> beforehand. For example,

<informalexample>
<programlisting>
     % setenv G4VRML_VIEWER  "netscape"
</programlisting>
</informalexample>
</para>

<para>
Its default value is <literal>NONE</literal>, which means that no viewer
is invoked and only the file <literal>g4.wrl</literal> is generated.
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Remote Visualization with the VRML-Network Driver
</bridgehead>

<para>
Visualization in Geant4 is considered to be "remote" when it is
performed on a machine other than the Geant4 host. Some of the
visualization drivers support this feature.
</para>

<para>
Usually, the visualization host is your local host, while the
Geant4 host is a remote host where you log in, for example, with
the <literal>telnet</literal> command. This enables distributed processing of
Geant4 visualization, avoiding the transfer of large amounts of
visualization data to your terminal display via the network.
</para>

<para>
In order to perform remote visualization with the VRML-Network
driver, the following must be installed on your local host
beforehand:

<orderedlist spacing="compact">
  <listitem><para>
    a VRML viewer
  </para></listitem>
  <listitem><para>
    the Java application <literal>g4vrmlview</literal>.
  </para></listitem>
</orderedlist>
</para>

<para>
The Java application <literal>g4vrmlview</literal> is included as part of the
Geant4 package and is located at:

<informalexample>
<programlisting>
     source/visualization/VRML/g4vrmlview/
</programlisting>
</informalexample>
</para>

<para>
Installation instructions for <literal>g4vrmlview</literal> can be found in
the <literal>README</literal> file there, or on the WWW page below.
</para>

<para>
The following steps realize remote Geant4 visualization
displayed with your local VRML browser:

<orderedlist spacing="compact">
  <listitem><para>
    Invoke the <literal>g4vrmlview</literal> on your local host, giving a
    VRML viewer name as its argument:

    <informalexample>
<programlisting>
       Local_Host&gt; java g4vrmlview  VRML_viewer_name
    </programlisting>
</informalexample>

    For example, if you want to use the Netscape browser as your VRML
    viewer, execute <literal>g4vrmlview</literal> as follows:

    <informalexample>
    <programlisting>
       Local_Host&gt; java g4vrmlview  netscape
    </programlisting>
    </informalexample>

    Of course, the command path to the VRML viewer should be properly set.
  </para></listitem>
  <listitem><para>
    Log in to the remote host where a Geant4 executable is placed.
  </para></listitem>
  <listitem><para>
    Set an environment variable on the remote host as follows:

    <informalexample>
    <programlisting>
       Remote_Host&gt; setenv G4VRML_HOST_NAME local_host_name
    </programlisting>
    </informalexample>

    For example, if you are working on the local host named
    "arkoop.kek.jp", set this environment variable as follows:

    <informalexample>
    <programlisting>
       Remote_Host&gt; setenv G4VRML_HOST_NAME arkoop.kek.jp
    </programlisting>
    </informalexample>

    This tells a Geant4 process running on the remote host where Geant4
    Visualization should be performed, i.e., where the visualized views
    should be displayed.
  </para></listitem>
  <listitem><para>
    Invoke a Geant4 process and perform visualization with the
    VRML-Network driver. For example:

    <informalexample>
    <programlisting>
       Idle&gt; /vis/open VRML2
       Idle&gt; /vis/drawVolume 
       Idle&gt; /vis/viewer/update
    </programlisting>
    </informalexample>       
  </para></listitem>
</orderedlist>
</para>

<para>
In step 4, 3D scene data are sent from the remote host to the
local host as VRML-formatted data, and the VRML viewer specified in
step 3 is invoked by the <literal>g4vrmlview</literal> process to visualize
the VRML data. The transferred VRML data are saved as a file named
<literal>g4.wrl</literal> in the current directory of the local host.
</para>

<para>
<emphasis role="bold">Further information:</emphasis>

<?soft-pagebreak ?>
<itemizedlist spacing="compact">
  <listitem><para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/GEANT4/VRML_net_driver.html">
    http://geant4.kek.jp/GEANT4/vis/GEANT4/VRML_net_driver.html
    </ulink>
  </para></listitem>
</itemizedlist>
</para>

<para>
<emphasis role="bold">Further information (VRML drivers):</emphasis>

<?soft-pagebreak ?>
<itemizedlist spacing="compact">
  <listitem><para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/GEANT4/VRML_file_driver.html">
    http://geant4.kek.jp/GEANT4/vis/GEANT4/VRML_file_driver.html
    </ulink>
  </para></listitem>
  <listitem><para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/GEANT4/VRML_net_driver.html">
    http://geant4.kek.jp/GEANT4/vis/GEANT4/VRML_net_driver.html
    </ulink>
  </para></listitem>
</itemizedlist>
</para>

<para>
<emphasis role="bold">Sample VRML files:</emphasis>

<?soft-pagebreak ?>
<itemizedlist spacing="compact">
  <listitem><para>
    <ulink url="http://geant4.kek.jp/GEANT4/vis/GEANT4/VRML2_FIG/">
    http://geant4.kek.jp/GEANT4/vis/GEANT4/VRML2_FIG/
    </ulink>
  </para></listitem>
</itemizedlist>
</para>

<para>
<emphasis role="bold">Further information (VRML language and browsers):</emphasis>

<itemizedlist spacing="compact">
  <listitem><para>
    <ulink url="http://www.vrmlsite.com/">http://www.vrmlsite.com/
    </ulink>
  </para></listitem>
</itemizedlist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.RayTrc">
<title>
RayTracer
</title>

<para>
This driver was developed by Makoto Asai and Minamimoto (Hirosihma
Instutute of Technology). It performs ray-tracing visualization
using the tracking routines of Geant4. It is, therefore, available
for every kinds of shapes/solids which Geant4 can handle. It is
also utilized for debugging the user's geometry for the tracking
routines of Geant4. It is well suited for photo-realistic high
quality output for presentation, and for intuitive debugging of
detector geometry. It produces a JPEG file. This driver is by
default listed in the available visualization drivers of user's
application.
</para>

<para>
Some pieces of geometries may fail to show up in other
visualization drivers (due to algorithms those drivers use to
compute visualizable shapes and polygons), but RayTracer can handle
any geometry that the Geant4 navigator can handle.
</para>

<para>
Because RayTracer in essence takes over Geant4's tracking
routines for its own use, RayTracer cannot be used to visualize
Trajectories or hits.
</para>

<para>
An X-Window version, called RayTracerX, can be selected by
setting <literal>G4VIS_BUILD_RATRACERX_DRIVER</literal> at Geant4 library
build time and <literal>G4VIS_USE_RAYTRACERX</literal> at application (user
code) build time (assuming you use the standard visualization
manager, <literal>G4VisExecutive</literal>, or an equally smart vis manager).
RayTracerX builds the same jpeg file as RayTracer, but
simultaneously renders to screen so you can watch as rendering
grows progressively smoother.
</para>

<para>
RayTracer has its own built-in commands -
<literal>/vis/rayTracer/</literal>.... Alternatively, you can treat it as a
normal vis system and use <literal>/vis/viewer/</literal>... commands,
e.g:

<informalexample>
<programlisting>
  /vis/open RayTracerX
  /vis/drawVolume
  /vis/viewer/set/viewpointThetaPhi 30 30
  /vis/viewer/refresh
</programlisting>
</informalexample>
</para>

<para>
The view parameters are translated into the necessary RayTracer
parameters.
</para>

<para>
RayTracer is compute intensive. If you are unsure of a good
viewing angle or zoom factor, you might be advised to choose them
with a faster renderer, such as OpenGL, and transfer the view
parameters with <literal>/vis/viewer/set/all</literal>:

<informalexample>
<programlisting>
  /vis/open OGLSXm  # or any of the OGL options.  Opens, say, viewer-0.
  /vis/drawVolume
  /vis/viewer/zoom  # plus any /vis/viewer/commands that get you the view you want.
  /vis/open RayTracerX
  /vis/viewer/set/all viewer-0
  /vis/viewer/refresh
</programlisting>
</informalexample>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.DetTree">
<title>
Visualization of detector geometry tree
</title>

<para>
ASCIITREE is a visualization driver that is not actually graphical
but that dumps the volume hierarchy as a simple text tree.
</para>

<para>
Each call to /vis/viewer/flush or /vis/drawTree will dump the
tree.
</para>

<para>
ASCIITree has command to control its verbosity,
<literal>/vis/ASCIITree/verbose</literal>. The verbosity value controls the
amount of information available, e.g., physical volume name alone,
or also logical volume and solid names. If the volume is
"sensitive" and/or has a "readout geometry", this may also be
indicated. Also, the mass of the physical volume tree(s) can be
printed (but beware - higher verbosity levels can be
computationally intensive).
</para>

<para>
At verbosity level 4, ASCIITree calculates the mass of the
complete geometry tree taking into account daughters up to the
depth specified for each physical volume. The calculation involves
subtracting the mass of that part of the mother that is occupied by
each daughter and then adding the mass of the daughter, and so on
down the hierarchy.

<informalexample>
<programlisting>
     /vis/ASCIITree/Verbose 4
     /vis/viewer/flush
     "HadCalorimeterPhysical":0 / "HadCalorimeterLogical" / "HadCalorimeterBox"(G4Box), 
                                  1.8 m3 , 11.35 g/cm3
     "HadCalColumnPhysical":-1 (10 replicas) / "HadCalColumnLogical" / "HadCalColumnBox"(G4Box), 
                                               180000 cm3, 11.35 g/cm3
     "HadCalCellPhysical":-1 (2 replicas) / "HadCalCellLogical" / "HadCalCellBox"(G4Box), 
                                            90000 cm3, 11.35 g/cm3
     "HadCalLayerPhysical":-1 (20 replicas) / "HadCalLayerLogical" / "HadCalLayerBox"(G4Box),
                                              4500 cm3, 11.35 g/cm3
     "HadCalScintiPhysical":0 / "HadCalScintiLogical" / "HadCalScintiBox"(G4Box), 
                                900 cm3, 1.032 g/cm3
     
     Calculating mass(es)...
     Overall volume of "worldPhysical":0, is 2400 m3
     Mass of tree to unlimited depth is 22260.5 kg
</programlisting>
</informalexample>
</para>

<para>
Some more examples of ASCIITree in action:

<informalexample>
<programlisting>
     Idle&gt; /vis/ASCIITree/verbose 1
     Idle&gt; /vis/drawTree
     #  Set verbosity with "/vis/ASCIITree/verbose 
     #    &lt;  10: - does not print daughters of repeated placements, does not repeat replicas.
     #    &gt;= 10: prints all physical volumes.
     #  The level of detail is given by verbosity%10:
     #  for each volume:
     #    &gt;=  0: physical volume name.
     #    &gt;=  1: logical volume name (and names of sensitive detector and readout geometry, if any).
     #    &gt;=  2: solid name and type.
     #    &gt;=  3: volume and density.
     #    &gt;=  5: daughter-subtracted volume and mass.
     #  and in the summary at the end of printing:
     #    &gt;=  4: daughter-included mass of top physical volume(s) in scene to depth specified.
     .....
     "Calorimeter", copy no. 0, belongs to logical volume "Calorimeter"
       "Layer", copy no. -1, belongs to logical volume "Layer" (10 replicas)
         "Absorber", copy no. 0, belongs to logical volume "Absorber"
           "Gap", copy no. 0, belongs to logical volume "Gap"
     .....
     Idle&gt; /vis/ASCIITree/verbose 15
     Idle&gt; /vis/drawTree
     ....
      "tube_phys":0 / "tube_L" / "tube"(G4Tubs), 395841 cm3, 1.782 mg/cm3, 
                                9.6539e-08 mm3, 1.72032e-10 mg
        "divided_tube_phys":0 / "divided_tube_L" / "divided_tube"(G4Tubs), 65973.4 cm3, 
                                1.782 mg/cm3, 7587.54 cm3, 13.521 g 
          "divided_tube_inset_phys":0 / "divided_tube_inset_L" / "divided_tube_inset"(G4Tubs), 
                                        58385.9 cm3, 1.782 mg/cm3, 6.03369e-09 mm3, 1.0752e-11 mg
            "sub_divided_tube_phys":0 / "sub_divided_tube_L" / "sub_divided_tube"(G4Tubs), 
                                        14596.5 cm3, 1.782 mg/cm3, 12196.5 cm3, 21.7341 g 
     .....
     Calculating mass(es)...
     Overall volume of "expHall_P":0, is 8000 m3  and the daughter-included mass to unlimited depth 
                                      is 78414 kg
     .....
</programlisting>
</informalexample>
</para>

<para>
For the complete list of commands and options, see the 
<ulink url="./AllResources/Control/UIcommands/_vis_.html">
Control...UICommands</ulink>  section of this user guide.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.GAGTree">
<title>
GAG Tree
</title>

<para>
The GAGTree driver provides a listing of the detector geometry tree
within GAG, the Geant Adaptive GUI, (
<ulink url="http://erpc1.naruto-u.ac.jp/~geant4">
http://erpc1.naruto-u.ac.jp/~geant4
</ulink>
). GAG allows "folding/un-folding" a part of the geometry tree, using
the <emphasis>Tree Widget</emphasis> in Java:

<informalfigure id="fig.VisDrv_1">
<mediaobject>
  <imageobject role="fo">
    <imagedata fileref="./AllResources/Visualization/visualization.src/gagtree.jpg" 
               format="JPG" contentwidth="12.0cm" align="center" />
  </imageobject>
  <imageobject role="html">
    <imagedata fileref="./AllResources/Visualization/visualization.src/gagtree.jpg"
               format="JPG" align="center" />
  </imageobject>
</mediaobject>
</informalfigure>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisDrv.XMLTree">
<title>
XML Tree
</title>

<para>
The XML description of the geometry tree can be created in Geant4
by the XML Tree driver. The XML source can also be edited on the
fly. The created XML files are visualizable with any XML browser
(in Windows, a good XML viewer is <emphasis>XML Notepad</emphasis>).

<itemizedlist spacing="compact">
  <listitem><para>
    Folding and un-folding:

    <informalfigure id="fig.VisDrv_2">
    <mediaobject>
      <imageobject role="fo">
        <imagedata fileref="./AllResources/Visualization/visualization.src/xmlnp.jpg" 
                   format="JPG" contentwidth="12.0cm" align="center" />
      </imageobject>
      <imageobject role="html">
        <imagedata fileref="./AllResources/Visualization/visualization.src/xmlnp.jpg"
                   format="JPG" align="center" />
        </imageobject>
    </mediaobject>
    </informalfigure>
  </para></listitem>
</itemizedlist>

<?soft-pagebreak ?>
<itemizedlist>
  <listitem><para>
    Searching a string:

    <informalfigure id="fig.VisDrv_3">
    <mediaobject>
      <imageobject role="fo">
        <imagedata fileref="./AllResources/Visualization/visualization.src/xmlnpfind.jpg" 
                   format="JPG" contentwidth="12.0cm" align="center" />
      </imageobject>
      <imageobject role="html">
        <imagedata fileref="./AllResources/Visualization/visualization.src/xmlnpfind.jpg"
                   format="JPG" align="center" />
      </imageobject>
    </mediaobject>
    </informalfigure>
  </para></listitem>
</itemizedlist>
</para>


</sect2>
</sect1>