source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Visualization/enhanceddrawing.xml@ 1345

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.VisEnhTrj">
<title>
Enhanced Trajectory Drawing
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisEnhTrj.DflCnfg">
<title>
Default Configuration
</title>

<para>
Trajectory drawing styles are specified through trajectory drawing
models. Each drawing model has a default configuration provided
through a G4VisTrajContext object. The default context settings are
shown below.

<informaltable>
  <tgroup cols="2">
    <tbody>
    <row>
      <entry>
        <emphasis role="bold">Property</emphasis>
      </entry>
      <entry>
        <emphasis role="bold">Default Setting</emphasis>
      </entry>
    </row>
    <row>
      <entry>
        Line colour
      </entry>
      <entry>
        grey
      </entry>
    </row>
    <row>
      <entry>
        Line visibility
      </entry>
      <entry>
        true
      </entry>
    </row>
    <row>
      <entry>
        Draw line
      </entry>
      <entry>
        true
      </entry>
    </row>
    <row>
      <entry>
        Draw auxiliary points
      </entry>
      <entry>
        false
      </entry>
    </row>
    <row>
      <entry>
        Auxiliary point type
      </entry>
      <entry>
        squares
      </entry>
    </row>
    <row>
      <entry>
        Auxiliary point size
      </entry>
      <entry>
        2 pixels or mm*
      </entry>
    </row>
    <row>
      <entry>
        Auxiliary point size type
      </entry>
      <entry>
        screen
      </entry>
    </row>
    <row>
      <entry>
        Auxiliary point fill style
      </entry>
      <entry>
        filled
      </entry>
    </row>
    <row>
      <entry>
        Auxiliary point colour
      </entry>
      <entry>
        magenta
      </entry>
    </row>
    <row>
      <entry>
        Auxiliary point visibility
      </entry>
      <entry>
        true
      </entry>
    </row>
    <row>
      <entry>
        Draw step point
      </entry>
      <entry>
        false
      </entry>
    </row>
    <row>
      <entry>
        Step point type
      </entry>
      <entry>
        circles
      </entry>
    </row>
    <row>
      <entry>
        Step point size
      </entry>
      <entry>
        2 pixels or mm*
      </entry>
    </row>
    <row>
      <entry>
        Step point size type
      </entry>
      <entry>
        screen
      </entry>
    </row>
    <row>
      <entry>
        Step point fill style
      </entry>
      <entry>
        filled
      </entry>
    </row>
    <row>
      <entry>
        Step point colour
      </entry>
      <entry>
        yellow
      </entry>
    </row>
    <row>
      <entry>
        Step point visibility
      </entry>
      <entry>
        true
      </entry>
    </row>
    <row>
      <entry>
        Time slice interval
      </entry>
      <entry>
        0
      </entry>
    </row>
    </tbody>
  </tgroup>
</informaltable>
</para>

<para>
* Depending on size type.  If size type == screen, pixels are assumed and no unit need be supplied.  If size type == world, a unit must be supplied, e.g., 10 cm.
</para>

<para>
Points to note:

<itemizedlist spacing="compact">
  <listitem><para>
    The context approach is intended to replace the configuration
    through the imode parameter. The use of imode is depreciated and
    will be removed in Geant4 v10.0.
  </para></listitem>
  <listitem><para>
    Different visualisation drivers handle trajectory configuration
    in different ways, so trajectories may not necessarily get
    displayed as you have configured them.
  </para></listitem>
</itemizedlist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisEnhTrj.DrdMdl">
<title>
Trajectory Drawing Models
</title>

<para>
A trajectory drawing model can override the default context
according to the properties of a given trajectory. The following
models are supplied with the Geant4 distribution:

<itemizedlist spacing="compact">
  <listitem><para>
    G4TrajectoryGenericDrawer (generic)
  </para></listitem>
  <listitem><para>
    G4TrajectoryDrawByCharge (drawByCharge)
  </para></listitem>
  <listitem><para>
    G4TrajectoryDrawByParticleID (drawByParticleID)
  </para></listitem>
  <listitem><para>
    G4TrajectoryDrawByOriginVolume (drawByOriginVolume)
  </para></listitem>
  <listitem><para>
    G4TrajectoryDrawByAttribute (drawByAttribute)
  </para></listitem>
</itemizedlist>
</para>

<para>
Both the context and model properties can be configured by the
user. The models are described briefly below, followed by some
example configuration commands.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4TrajectoryGenericDrawer
</bridgehead>

<para>
This model simply draws all trajectories in the same style, with
the properties provided by the context.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4TrajectoryDrawByCharge
</bridgehead>

<para>
This is the default model - if no model is specified by the user,
this model will be constructed automatically. The trajectory lines
are coloured according to charge, with all other configuration
parameters provided by the default context. The default colouring
scheme is shown below.

<informalexample>
<programlisting>
        Charge          Colour  
        ----------------------
        1               Blue
        -1              Red
        0               Green
</programlisting>
</informalexample>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4TrajectoryDrawByParticleID
</bridgehead>

<para>
This model colours trajectory lines according to particle type. All
other configuration parameters are provided by the default context.
By default, all trajectories are coloured grey. Chosen particle
types can be highlighted with specified colours.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4TrajectoryDrawByOriginVolume
</bridgehead>

<para>
This model colours trajectory lines according to the trajectories
originating volume name. The volume can be either a logical or
physical volume. Physical volume takes precedence over logical
volume. All trajectories are coloured grey by default.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4TrajectoryDrawByAttribute
</bridgehead>

<para>
This model draws trajectories based on the HepRep style attributes 
associated with trajectories. Each attribute drawer can be configured 
with interval and/or single value data. A new context object is 
created for each interval/single value. This makes it possible to 
have different step point markers etc, as well as line colour for 
trajectory attributes falling into different intervals, or matching 
single values. The single value data should override the interval data, 
allowing specific values to be highlighted. Units should be specified 
on the command line if the attribute unit is specified either as a 
G4BestUnit or if the unit is part of the value string.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisEnhTrj.CntlComm">
<title>
Controlling from Commands
</title>

<para>
Multiple trajectory models can be created and configured using
commands in the "<literal>/vis/modeling/trajectories/</literal>" directory.
It is then possible to list available models and select one to be
current.
</para>

<para>
Model configuration commands are generated dynamically when a
model is instantiated. These commands apply directly to that
instance. This makes it possible to have multiple instances of the
drawByCharge model for example, each independently configurable
through it's own set of commands.
</para>

<para>
See the interactive help for more information on the available
commands.
</para>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.VisEnhTrj.CntlComm.ExpComm">
<title>
Example commands
</title>

<para>
#Create a generic model named generic-0 by default

<informalexample>
<programlisting>
/vis/modeling/trajectories/create/generic
</programlisting>
</informalexample>
</para>

<para>
#Configure context to colour all trajectories red

<informalexample>
<programlisting>
/vis/modeling/trajectories/generic-0/default/setLineColour red
</programlisting>
</informalexample>
</para>

<para>
#Create a drawByCharge model named drawCharge-0 by default
(Subsequent models will be named drawByCharge-1, drawByCharge-2,
etc.)

<informalexample>
<programlisting>
/vis/modeling/trajectories/create/drawByCharge
</programlisting>
</informalexample>
</para>

<para>
#Create a drawByCharge model named testChargeModel

<informalexample>
<programlisting>
/vis/modeling/trajectories/create/drawByCharge testChargeModel
</programlisting>
</informalexample>
</para>

<para>
#Configure drawByCharge-0 model

<informalexample>
<programlisting>
/vis/modeling/trajectories/drawByCharge-0/set 1 red
/vis/modeling/trajectories/drawByCharge-0/set -1 red
/vis/modeling/trajectories/drawByCharge-0/set 0 white
</programlisting>
</informalexample>
</para>

<para>
#Configure testCharge model through G4Colour components

<informalexample>
<programlisting>
/vis/modeling/trajectories/testChargeModel/setRGBA 1 0 1 1 1
/vis/modeling/trajectories/testChargeModel/setRGBA -1 0.5 0.5 0.5 1
/vis/modeling/trajectories/testChargeModel/setRGBA 0 1 1 0 1
</programlisting>
</informalexample>
</para>

<para>
#Create a drawByParticleID model named drawByParticleID-0

<informalexample>
<programlisting>
/vis/modeling/trajectories/create/drawByParticleID
</programlisting>
</informalexample>
</para>

<para>
#Configure drawByParticleID-0 model

<informalexample>
<programlisting>
/vis/modeling/trajectories/drawByParticleID-0/set gamma red
/vis/modeling/trajectories/drawByParticleID-0/setRGBA e+ 1 0 1 1
</programlisting>
</informalexample>
</para>

<para>
#List available models

<informalexample>
<programlisting>
/vis/modeling/trajectories/list
</programlisting>
</informalexample>
</para>

<para>
#select drawByParticleID-0 to be current

<informalexample>
<programlisting>
/vis/modeling/trajectories/select drawByParticleID-0
</programlisting>
</informalexample>
</para>

<para>
#Create a drawByAttribute model named drawByAttribute-0

<informalexample>
<programlisting>
/vis/modeling/trajectories/create/drawByAttribute
</programlisting>
</informalexample>
</para>

<para>
#Configure drawByAttribute-0 model

<informalexample>
<programlisting>
/vis/modeling/trajectories/drawByAttribute-0/verbose true
</programlisting>
</informalexample>
</para>

<para>
#Select attribute "CPN"

<informalexample>
<programlisting>
/vis/modeling/trajectories/drawByAttribute-0/setAttribute CPN
</programlisting>
</informalexample>
</para>

<para>
#Configure single value data

<informalexample>
<programlisting>
/vis/modeling/trajectories/drawByAttribute-0/addValue brem_key  eBrem
/vis/modeling/trajectories/drawByAttribute-0/addValue annihil_key annihil
/vis/modeling/trajectories/drawByAttribute-0/addValue decay_key Decay
/vis/modeling/trajectories/drawByAttribute-0/addValue muIon_key muIoni
/vis/modeling/trajectories/drawByAttribute-0/addValue eIon_key  eIoni

/vis/modeling/trajectories/drawByAttribute-0/brem_key/setLineColour     red
/vis/modeling/trajectories/drawByAttribute-0/annihil_key/setLineColour  green
/vis/modeling/trajectories/drawByAttribute-0/decay_key/setLineColour    cyan
/vis/modeling/trajectories/drawByAttribute-0/eIon_key/setLineColour     yellow
/vis/modeling/trajectories/drawByAttribute-0/muIon_key/setLineColour magenta
</programlisting>
</informalexample>
</para>

<para>
#Create a drawByAttribute model named drawByAttribute-1

<informalexample>
<programlisting>
/vis/modeling/trajectories/create/drawByAttribute
</programlisting>
</informalexample>
</para>

<para>
#Select "IMag" attribute

<informalexample>
<programlisting>
/vis/modeling/trajectories/drawByAttribute-1/setAttribute IMag
</programlisting>
</informalexample>
</para>

<para>
#Configure interval data

<informalexample>
<programlisting>
/vis/modeling/trajectories/drawByAttribute-1/addInterval interval1 0.0 keV 2.5MeV
/vis/modeling/trajectories/drawByAttribute-1/addInterval interval2 2.5 MeV 5 MeV
/vis/modeling/trajectories/drawByAttribute-1/addInterval interval3 5 MeV 7.5 MeV
/vis/modeling/trajectories/drawByAttribute-1/addInterval interval4 7.5 MeV 10 MeV
/vis/modeling/trajectories/drawByAttribute-1/addInterval interval5 10 MeV 12.5 MeV
/vis/modeling/trajectories/drawByAttribute-1/addInterval interval6 12.5 MeV 10000 MeV

/vis/modeling/trajectories/drawByAttribute-1/interval1/setLineColourRGBA 0.8 0 0.8 1
/vis/modeling/trajectories/drawByAttribute-1/interval2/setLineColourRGBA 0.23 0.41 1 1
/vis/modeling/trajectories/drawByAttribute-1/interval3/setLineColourRGBA 0 1 0 1
/vis/modeling/trajectories/drawByAttribute-1/interval4/setLineColourRGBA 1 1 0 1
/vis/modeling/trajectories/drawByAttribute-1/interval5/setLineColourRGBA 1 0.3 0 1
/vis/modeling/trajectories/drawByAttribute-1/interval6/setLineColourRGBA 1 0 0 1
</programlisting>
</informalexample>
</para>

</sect3>
</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisEnhTrj.CntlCmpl">
<title>
Controlling from Compiled Code
</title>

<para>
It is possible to use the enhanced trajectory drawing functionality
in compiled code as well as from commands. Multiple trajectory
models can be instantiated, configured and registered with
G4VisManager. Only one model may be current. For example:

<informalexample>
<programlisting>
  G4VisManager* visManager = new G4VisExecutive;
  visManager-&gt;Initialize();

  G4TrajectoryDrawByParticleID* model = new G4TrajectoryDrawByParticleID;
  G4TrajectoryDrawByParticleID* model2 = new G4TrajectoryDrawByParticleID("test");

  model-&gt;SetDefault("cyan");
  model-&gt;Set("gamma", "green");
  model-&gt;Set("e+", "magenta");
  model-&gt;Set("e-", G4Colour(0.3, 0.3, 0.3));

  visManager-&gt;RegisterModel(model);
  visManager-&gt;RegisterModel(model2);

  visManager-&gt;SelectTrajectoryModel(model-&gt;Name());
</programlisting>
</informalexample>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisEnhTrj.DrwByTime">
<title>
Drawing by time
</title>

<para>
To draw by time, you need to use G4RichTrajectory, for example:

<informalexample>
<programlisting>
/vis/scene/add/trajectories rich
</programlisting>
</informalexample>

or

<informalexample>
<programlisting>
/vis/scene/add/trajectories rich smooth
</programlisting>
</informalexample>
</para>

<para>
When you run, you need to create a trajectory model and set the
time slice interval (remembering that paticles are often
relativistic and travel 30 cm/ns):

<informalexample>
<programlisting>
/vis/modeling/trajectories/create/drawByCharge
/vis/modeling/trajectories/drawByCharge-0/default/setDrawStepPts true
/vis/modeling/trajectories/drawByCharge-0/default/setStepPtsSize 5
/vis/modeling/trajectories/drawByCharge-0/default/setDrawAuxPts true
/vis/modeling/trajectories/drawByCharge-0/default/setAuxPtsSize 5
/vis/modeling/trajectories/drawByCharge-0/default/setTimeSliceInterval 0.1 ns
/vis/modeling/trajectories/list
</programlisting>
</informalexample>

and use a graphics driver that can display by time:

<informalexample>
<programlisting>
/vis/open OGLSX
/vis/drawVolume
/vis/scene/add/trajectories rich
/vis/ogl/set/startTime 0.5 ns
/vis/ogl/set/endTime 0.8 ns
/run/beamOn
/vis/viewer/refresh
</programlisting>
</informalexample>
</para>

<para>
A good way to see the particles moving through the detector is:

<informalexample>
<programlisting>
/vis/ogl/set/fade 1
/vis/ogl/set/displayHeadTime true
/control/alias timeRange 1
/control/loop movie.loop -{timeRange} 40 0.1
</programlisting>
</informalexample>

where <literal>fade</literal> gives a vapour-trail effect,
<literal>displayHeadTime</literal> displays the time of the leading edge as
2D text, and <literal>movie.loop</literal> is a macro file:

<informalexample>
<programlisting>
/vis/ogl/set/startTime {startTime} ns {timeRange} ns
</programlisting>
</informalexample>
</para>

<para>
From there, it's straightforward to <xref linkend="sect.MkMovie" />
make a movie.
</para>


</sect2>
</sect1>