source: trunk/documents/UserDoc/DocBookUsersGuides/ForToolkitDeveloper/xml/OOAnalysisDesign/Visualization/visualization.xml @ 1345

<!-- ******************************************************** -->
<!--  Docbook Version:  For Toolkit Developers Guide          -->
<!-- ******************************************************** -->

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.DsgnFuncVis">
<title>
Visualisation
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncVis.DsgPhlsp">
<title>
Design Philosophy
</title>

<para>
The visualisation category consists of the classes required to display
detector geometry, particle trajectories, tracking steps, and hits.  It also 
provides visualisation drivers, which are interfaces to external graphics 
systems.  
</para>

<para>
A wide variety of user requirements went into the design of the visualisation 
category, for example:

<itemizedlist spacing="compact">
  <listitem><para>
    very quick response in surveying successive events,
  </para></listitem>
  <listitem><para>
    high-quality output for presentation and documentation,
  </para></listitem>
  <listitem><para>
    flexible camera control for debugging detector geometry and physics,
  </para></listitem>
  <listitem><para>
    selection of visualisable objects,
  </para></listitem>
  <listitem><para>
    interactive picking of graphical objects for attribute editing or 
    feedback to the associated data,
  </para></listitem>
  <listitem><para>
    highlighting incorrect intersections of physical volumes,
  </para></listitem>
  <listitem><para>
    co-working with graphical user interfaces.
  </para></listitem>
</itemizedlist>
</para>

<para>
Because it is very difficult to respond to all of these requirements
with only one built-in visualiser, an abstract interface was developed
which supports several complementary graphics systems.  Here the term
<emphasis role="bold">graphics system</emphasis> means either an 
application running as a process independent of Geant4 or a graphics 
library to be compiled with Geant4.  A concrete implementation of the
interface is called a <emphasis role="bold">visualisation driver</emphasis>, 
which can use a graphics library directly, communicate with an 
independent process via pipe or socket, or simply write an intermediate 
file for a separate viewer.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncVis.GrphIntrf">
<title>
The Graphics Interfaces
</title>

<para>
<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold"></emphasis>G4VVisManager: 
    All user code writes to the graphics systems
    through this pure abstract interface.  It contains Draw methods for
    all the graphics primitives in the graphics_reps category
    (G4Polyline, G4Circle, etc.), geometry objects (through their base
    classes, G4VSolid, G4PhysicalVolume and G4LogicalVolume) and hits and
    trajectories (through their base classes, G4VHit and G4VTrajectory).
    </para>
    <para>
    Since this is an abstract interface, all user code must check that
    there exists a concrete instantiation of it.  A static method is
    provided, so a typical user code fragment is:

    <informalexample><programlisting>
  G4VVisManager* pVVisManager = G4VVisManager::GetConcreteInstance();
  if(pVVisManager) {
    pVVisManager-&gt;Draw(G4Circle...
    ...
    </programlisting></informalexample>
    </para>
    <para>
    Note that this allows the building an application without a concrete
    implementation, for example for a batch job, even if some code, like
    the above, is still included.  Most of the novice examples can be
    built this way if G4VIS_NONE is specified.
    </para>
    <para>
    The concrete implementation of this interface is hereafter
    referred to as the <emphasis role="bold">visualisation manager</emphasis>.
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4VGraphicsScene</emphasis>: 
    The visualisation manager must also
    provide a concrete implementation of the subsidiary interface,
    G4VGraphicsScene.  It is only for use by the kernel and the modeling
    category.  It offers direct access to a ``scene handler'' through a
    reference provided by the visualisation manager.  It is described in
    more detail in the section on extending the toolkit functionality.
  </para></listitem>
</itemizedlist>
</para>

<para>
The Geant4 distribution includes implementations of the above
interfaces, namely <emphasis role="bold">G4VisManager</emphasis> 
and <emphasis role="bold">G4VSceneHandler</emphasis>
respectively, and their associated classes.  These define further
abstract base classes for visualisation drivers.  Together they form
the <emphasis role="bold">Geant4 Visualisation System</emphasis>.  
A variety of concrete visualisation drivers are also included 
in the distribution.  Details of how to implement a visualisation 
driver are given in <xref linkend="sect.ExtdFuncVis" />.
Of course, it is always possible for
a user to implement his or her own concrete implementations of
G4VVisManager and G4VGraphicsScene replacing the Geant4 Visualisation
System altogether.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncVis.VisSystm">
<title>
The Geant4 Visualisation System
</title>

<para>
The Geant4 Visualisation System consists of

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">G4VisManager</emphasis>: An implementation 
    of the G4VVisManager
    interface.  It manages multiple graphics systems and defines three
    more concepts -- the <emphasis role="bold">scene</emphasis> (G4Scene), 
    the <emphasis role="bold">scene handler</emphasis>
    (base class G4VSceneHandler, itself a sub-class of G4VGraphicsScene)
    and the <emphasis role="bold">viewer</emphasis> (base class G4VViewer) 
    -- see below.
    G4VisManager is a singleton and an abstract class, requiring the
    user to derive from it a concrete visualisation manager
    (G4VisExecutive is provided -- see below).  Roles and structure of
    the visualisation manager are described in Chapter 8 of the User's
    Guide for Application Developers.
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4VisExecutive</emphasis>: A concrete visualisation 
    manager that implements the virtual functions RegisterGraphicsSystems and
    RegisterModelFactories.  These functions must be in the users'
    domain, since the graphics systems and models that are instantiated
    by them are, in many cases, provided by the user (graphics
    libraries, etc.).  It is therefore implemented as a .hh-.icc
    combination that is designed to be included in the users' code.  Of
    course, the user may write his or her own.
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4Scene</emphasis> The scene is a list if 
    models for physical
    volumes, axes, hits, trajectories, etc. - see Section
    <xref linkend="sect.DsgnFuncVis.MdlCat" />. 
    They are distinguished according to their
    lifetime -- ``run-duration'' for physical volumes, etc.,
    ``end-of-event'' for hits and trajectories, etc.  The end-of-event
    models are only to be used when the Geant4 state indicates the end
    of event has been reached.  The scene has an 
    <emphasis role="bold">extent</emphasis> (G4VisExtent), 
    which is updated by the scene when a new model is
    added (each model itself has an extent), and a ``standard'' target
    point; these are used to define the standard view -- see
    below.  In addition, the scene keeps flags which indicate whether
    end-of-event objects should be accumulated or refreshed for each
    event or run.
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4VGraphicsSystem</emphasis>: This is an 
    abstract base class for scene
    handler and viewer factories.  It is used by the visualisation
    manager to create scene handlers and viewers on request.
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4VSceneHandler</emphasis>: A sub-class of 
    G4VGraphicsScene, itself an abstract base class for specific scene 
    handlers, whose job is to
    convert the scene into graphics-system-specific code for the viewer.
    For example, the scene handler may create a graphical database,
    taking care to separate run-duration (persistent) and end-of-event
    (transient) information (this is described further in 
    <xref linkend="sect.ExtdFuncVis.CrtGrpDrv.DlgTrnsObj" />.
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4VViewer</emphasis>: An abstract base class 
    for specific viewers.
    Its job is to create windows or files and identify where and how the
    final view should be rendered.  It has 
    <emphasis role="bold">view parameters</emphasis>
    (G4ViewParameters) which specify viewpoint direction, type of
    rendering (wireframe or surface), etc.  It is the view's
    responsibility, noting the scene's extent and target point, to
    choose a camera position and magnification that ensures that the
    scene is automatically and comfortably rendered in the viewing
    window.  This is then the <emphasis role="bold">standard view</emphasis>, 
    and any further
    operations requested by the user - zoom, pan, etc. - are
    relative to this standard view.  The class G4ViewParameters has
    utility routines to assist this procedure; it is strongly advised
    that toolkit developers writing a viewer should study the
    G4ViewParameters class, whose header file contains much useful
    information (also preserved in the Software Reference Manual).
    </para>
    <para>
    The viewer is messaged by the vis manager when the user issues
    commands, such as <literal>/vis/viewer/refresh</literal>.  
    This invokes methods
    such as SetView, ClearView and DrawView.  A detailed description of
    the call sequences is given in 
    <xref linkend="sect.ExtdFuncVis.CrtGrpDrv.ImpCmdAct" />-
    <xref linkend="sect.ExtdFuncVis.CrtGrpDrv.WhtPrcScn" />.
  </para></listitem>
</itemizedlist>
</para>

<para>
Note there is no restriction on the number or type of scene handlers
or viewers.  There may be several scene handlers processing the same
or different scenes, each with several viewers (for example, the same
scene from differing viewpoints).
</para>

<para>
By defining a set of three C++ classes inheriting from the virtual
base classes - G4VGraphicsSystem, G4VSceneHandler and G4VViewer - an
arbitrary graphics system can easily be plugged in to Geant4.
The plugged-in graphics system is then available for visualising
detector simulations.  Together, this set of three concrete classes is
called a "visualisation driver".  The DAWN-File driver, for example,
is the interface to the Fukui Renderer DAWN, and is implemented by the
following set of classes:

<orderedlist spacing="compact">
  <listitem><para>
    G4DAWNFILE : public G4VGraphicsSystem for creation of the 
    scene handlers and viewers 
  </para></listitem>
  <listitem><para>
    G4DAWNFILESceneHandler : public G4VSceneHandler for 
    modeling 3D scenes
  </para></listitem> 
  <listitem><para>
    G4DAWNFILEView : public G4VView for rendering 3D scenes 
  </para></listitem>
</orderedlist>
</para>

<para>
Several visualisation drivers are distributed with Geant4.  They are 
complementary to each other in many aspects. For details, see Chapter 8 of 
the User's Guide for Application Developers. 
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncVis.MdlCat">
<title>
Modeling sub-category
</title>

<para>
<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">G4VModel</emphasis> - 
    a base class for visualisation models.  A model is a
    graphics-system-independent description of a Geant4 component.
    </para>
    <para>
    The sub-category visualisation/modeling defines how to model a 3D
    scene for visualisation. The term "3D scene" indicates a set of
    visualisable component objects put in a 3D world. A concrete class
    inheriting from the abstract base class G4VModel defines a "model",
    which describes how to visualise the corresponding component object
    belonging to a 3D scene. G4ModelingParameters defines various
    associated parameters.
    </para>
    <para>
    For example, G4PhysicalVolumeModel knows how to visualise 
    a physical volume. It describes a physical volume
    and its daughters to any desired depth. G4HitsModel knows 
    how to visualise hits. G4TrajectoriesModel
    knows how to visualise trajectories.
    </para>
    <para>
    The main task of a model is to describe itself to a 3D scene by 
    giving a concrete implementation of the following virtual
    method of G4VModel: 

    <informalexample><programlisting>
    virtual void DescribeYourselfTo (G4VGraphicsScene&amp;) = 0;
    </programlisting></informalexample>
    </para>
    <para>
    The argument class G4VGraphicsScene is a minimal abstract 
    interface of a 3D scene for the Geant4 kernel defined in the
    graphics_reps category. Since G4VSceneHandler and its concrete 
    descendants inherit from G4VGraphicsScene, the
    method DescribeYourselfTo() can pass information of a 3D scene 
    to a visualisation driver. 
    </para>
    <para>
    It is easy for a toolkit developer of Geant4 to add a new kind 
    of visualisable component object. It is done by implementing a
    new class inheriting from G4VModel.
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4VTrajectoryModel</emphasis> - 
    an abstract base class for trajectory drawing models. 
    </para>
    <para>
    A trajectory model governs how an individual trajectory is drawn. 
    Concrete models inheriting from G4VTrajectoryModel must implement 
    two pure virtual functions:

    <informalexample><programlisting>
    virtual void Draw(const G4VTrajectory&amp;, G4int i_mode = 0) const = 0;
    virtual void Print(std::ostream&amp; ostr) const = 0;
    </programlisting></informalexample>
    </para>
    <para>
    See for example G4TrajectoryDrawByParticleID.
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">G4VModelFactory</emphasis> - 
    an abstract base class for factories creating models and associated 
    messengers.
    </para>
    <para>
    It is not necessary to generate messengers for a trajectory model 
    that will be constructed and configured directly in compiled code. 
    If the user requires model creation and configuration features through 
    interactive commands, however, there must be a mechanism to generate 
    both models and their associated messengers. This is the role of 
    G4VModelFactory. Concrete factories inheriting from G4VModelFactory 
    are responsible for creating a concrete model and concrete messengers. 
    To help ensure a type safe messenger to model interaction on the 
    command line, the messengers should inherit from G4VModelCommand.
    </para>
    <para>
    Concrete factories must implement one pure virtual function:

    <informalexample><programlisting>
    virtual ModelAndMessengers 
    Create(const G4String&amp; placement, const G4String&amp; modelName) = 0;
    </programlisting></informalexample>

    where placement indicates which directory space the commands should 
    occupy. See for example G4TrajectoryDrawByParticleIDFactory.
  </para></listitem>
</itemizedlist>
</para>


</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncVis.ViewParam">
<title>
View parameters
</title>

<para>
View parameters such as camera parameters, drawing styles
(wireframe/surface etc) are held by G4ViewParameters.  Each
viewer holds a view parameters object which can be changed
interactively and a default object (for use in the
<literal>/vis/viewer/reset</literal> command).
</para>

<para>
If a toolkit developer of Geant4 wants to add entries of view 
parameters, he should add fields and methods to G4ViewParameters. 
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.DsgnFuncVis.VisAttr">
<title>
Visualisation Attributes
</title>

<para>
All drawable objects (should) have a method:

<informalexample><programlisting>
  const G4VisAttributes* GetVisAttributes() const;
</programlisting></informalexample>
</para>

<para>
A drawable object might be:

<itemizedlist spacing="compact">
  <listitem><para>
    a "visible" (i.e., inheriting G4Visible), such as a polyhedron,
    polyline, circle, etc. (note that text is a slightly special case
    - see below) or
  </para></listitem>
  <listitem><para>
    a solid whose vis attributes are held in its logical volume.
  </para></listitem>
</itemizedlist>
</para>



<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.DsgnFuncVis.VisAttr.FndAppAtt">
<title>
Finding the applicable vis attributes
</title>

<para>
This is an issue for all scene handlers.  The scene handler is where
the colour, style, auxiliary edge visibility, marker size, etc., of
individual drawable objects are needed.
</para>


<!-- ******************* Section (Level#4) ****************** -->
<sect4 id="sect.DsgnFuncVis.VisAttr.FndAppAtt.Vsbl">
<title>
Visibles
</title>

<para>
If the vis attributes pointer is zero, drivers should pick up the
default vis attributes from the viewer:

<informalexample><programlisting>
  const G4VisAttributes* pVisAtts = visible.GetVisAttributes();
  if (!pVisAtts) 
    pVisAtts = fpViewer-&gt;GetViewParameters().GetDefaultVisAttributes();
</programlisting></informalexample>

where visible denotes any visible object (polyhedron, circle, etc.).
</para>

<para>
There is a utility function G4VViewer::GetApplicableVisAttributes
which does this, so an alternative is:

<informalexample><programlisting>
  const G4VisAttributes* pVisAtts =
    fpViewer-&gt;GetApplicableVisAttributes(visible.GetVisAttributes());
</programlisting></informalexample>
</para>

<para>
Confusingly, there is a utility function G4VSceneHandler::GetColour
which also does this, so if it's only colour you need, the following
suffices:

<informalexample><programlisting>
  const G4Colour&amp; colour GetColour(visible);
</programlisting></informalexample>

but equally well:

<informalexample><programlisting>
  const G4VisAttributes* pVisAtts =
    fpViewer-&gt;GetApplicableVisAttributes(visible.GetVisAttributes());
  const G4Colour&amp; colour pVisAtts-&gt;GetColour();
</programlisting></informalexample>

or even:

<informalexample><programlisting>
  const G4VisAttributes* pVisAtts = visible.GetVisAttributes();
  if (!pVisAtts) 
    pVisAtts = fpViewer-&gt;GetViewParameters().GetDefaultVisAttributes();
  const G4Colour&amp; colour pVisAtts-&gt;GetColour();
</programlisting></informalexample>
</para>

</sect4>

<!-- ******************* Section (Level#4) ****************** -->
<sect4 id="sect.DsgnFuncVis.VisAttr.FndAppAtt.Txt">
<title>
Text
</title>

<para>
Text is a special case because it has its own default vis attributes:

<informalexample><programlisting>
  const G4VisAttributes* pVisAtts = text.GetVisAttributes();
  if (!pVisAtts) 
    pVisAtts = fpViewer-&gt;GetViewParameters().GetDefaultTextVisAttributes();
  const G4Colour&amp; colour pVisAtts-&gt;GetColour();
</programlisting></informalexample>

and there is a utility function G4VSceneHandler::GetTextColour:

<informalexample><programlisting>
  const G4Colour&amp; colour GetTextColour(text);
</programlisting></informalexample>
</para>

</sect4>

<!-- ******************* Section (Level#4) ****************** -->
<sect4 id="sect.DsgnFuncVis.VisAttr.FndAppAtt.Slds">
<title>
Solids
</title>

<para>
For specific solids, the G4PhysicalVolumeModel that provides the
solids also provides, via PreAddSolid, a pointer to its vis
attributes.  If the vis attribites pointer in the logical volume is
zero, it provides a pointer to the default vis attributes in the
model, which in turn is (currently) provided by the viewer's vis
attributes (see G4VSceneHandler::CreateModelingParameters).  So the
vis attributes pointer is guaranteed to be pertinent.
</para>

<para>
If the concrete driver does not implement AddSolid for any particular
solid, the base class converts it to primitives (usually a
G4Polyhedron) and again, the vis attributes pointer is guaranteed.
</para>

</sect4>

<!-- ******************* Section (Level#4) ****************** -->
<sect4 id="sect.DsgnFuncVis.VisAttr.FndAppAtt.DrwStyl">
<title>
Drawing style
</title>

<para>
The drawing style is normally determined by the view parameters but
for individual drawable objects it may be overridden by the forced
drawing style flags in the vis attributes.  A utility function
G4ViewParameters::DrawingStyle G4VSceneHandler::GetDrawingStyle is
provided:

<informalexample><programlisting>
  G4ViewParameters::DrawingStyle drawing_style = GetDrawingStyle(pVisAtts);
</programlisting></informalexample>
</para>

</sect4>

<!-- ******************* Section (Level#4) ****************** -->
<sect4 id="sect.DsgnFuncVis.VisAttr.FndAppAtt.AxlEdg">
<title>
Auxiliary edges
</title>

<para>
Similarly, the visibility of auxiliary/soft edges is normally
determined by the view parameters but may be overridden by the forced
auxiliary edge visible flag in the vis attributes.  Again, a utility
function G4VSceneHandler::GetAuxEdgeVisible is provided:

<informalexample><programlisting>
  G4bool isAuxEdgeVisible = GetAuxEdgeVisible (pVisAtts);
</programlisting></informalexample>
</para>

</sect4>

<!-- ******************* Section (Level#4) ****************** -->
<sect4 id="sect.DsgnFuncVis.VisAttr.FndAppAtt.LnSgmCrc">
<title>
LineSegmentsPerCircle
</title>

<para>
Also, the precision of rendering curved edges in the polyhedral
representation of volumes is normally determined by the view
parameters but may be overridden by a forced attribute.  A utility
function that respects this, G4VSceneHandler::GetNoOfSides, is
provided.  For example:

<informalexample><programlisting>
  G4Polyhedron::SetNumberOfRotationSteps (GetNoOfSides (pVisAttribs));
</programlisting></informalexample>
</para>

</sect4>

<!-- ******************* Section (Level#4) ****************** -->
<sect4 id="sect.DsgnFuncVis.VisAttr.FndAppAtt.MrkSz">
<title>
Marker size
</title>

<para>
These have nothing to do with vis attributes; they are an extra
property of markers, i.e., objects that inherit G4VMarker (circles,
squares, text, etc.).  However, the algorithm for the actual size is
quite complicated and a utility function
G4VSceneHandler::GetMarkerSize is provided:

<informalexample><programlisting>
  MarkerSizeType sizeType;
  G4double size = GetMarkerSize (text, sizeType);
</programlisting></informalexample>

sizeType is world or screen, signifying that the size is in world
coordinates or screen coordinates respectively.
</para>

</sect4>

</sect3>
</sect2>

<!-- ******* Bridgehead ******* -->
<bridgehead role="revisionHistory" renderas="sect4">
[Status of this chapter]
</bridgehead>
<para>
<simplelist type="var">
  <member>
    27.06.05 partially re-organized and section on design philosophy added (from 
    Geant4 general paper) by D.H. Wright
  </member>
  <member>
    13.10.05 Section on vis attributes added by John Allison.
  </member>
  <member>
    06.01.06 Re-write of ``Design Philosphy'' and introduction of ``The Graphics
    Interfaces'' and ``The Geant4 Visualisation System'' by John Allison.
  </member>
  <member>
    Dec. 2006 Conversion from latex to Docbook verson by K. Amako
  </member>
</simplelist>
</para>
    



</sect1>