source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Visualization/filtering.xml

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

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

<para>
Trajectory filtering allows you to visualise a subset of available
trajectories. This can be useful if you only want to view
interesting trajectories and discard uninteresting ones. Trajectory
filtering can be run in two modes:

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Soft filtering</emphasis>: In this mode, 
    uninteresting trajectories are marked invisible. Hence, they are 
    still written, but (depending
    on the driver) will not be displayed. Some drivers, for example the
    HepRepFile driver, will allow you to selectively view these soft
    filtered trajectories
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Hard filtering</emphasis>: In this mode, 
    uninteresting trajectories are not drawn at all. 
    This mode is especially useful if the job
    produces huge graphics files, dominated by data from uninteresting
    trajectories.
  </para></listitem>
</itemizedlist>
</para>

<para>
Trajectory filter models are used to apply filtering according to
specific criteria. The following models are currently supplied with
the Geant4 distribution:

<itemizedlist spacing="compact">
  <listitem><para>
    G4TrajectoryChargeFilter (chargeFilter)
  </para></listitem>
  <listitem><para>
    G4TrajectoryParticleFilter (particleFilter)
  </para></listitem>
  <listitem><para>
    G4TrajectoryOriginVolumeFilter (originVolumeFilter)
  </para></listitem>
  <listitem><para>
    G4TrajectoryAttributeFilter (attributeFilter)
  </para></listitem>
</itemizedlist>
</para>

<para>
Multiple filters are automatically chained together, and can
configured either interactively or in commands or in compiled code.
The filters can be inverted, set to be inactive or set in a verbose
mode. The above models are described briefly below, followed by
some example configuration commands.
</para>

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

<para>
This model filters trajectories according to charge. In standard
running mode, only trajectories with charges matching those
registered with the model will pass the filter.
</para>

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

<para>
This model filters trajectories according to particle type. In
standard running mode, only trajectories with particle types
matching those registered with the model will pass the filter.
</para>

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

<para>
This model filters trajectories according to originating volume
name. In standard running mode, only trajectories with originating
volumes matching those registered with the model will pass the
filter.
</para>

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

<para>
This model filters trajectories based on the HepRep style attributes 
associated with trajectories. Each attribute drawer can be 
configured with interval and/or single value data. Single value data 
should override the interval data.
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>


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

<para>
Multiple trajectory filter models can be created and configured
using commands in the "<literal>/vis/filtering/trajectories/</literal>"
directory. All generated filter models are chained together
automatically.
</para>

<para>
Model configuration commands are generated dynamically when a
filter model is instantiated. These commands apply directly to that
instance.
</para>

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

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisFltr.ExpComm">
<title>
Example commands
</title>

<para>
#Create a particle filter. Configure to pass only gammas. Then
</para>

<para>
#invert to pass anything other than gammas. Set verbose
printout,
</para>

<para>
#and then deactivate filter

<informalexample>
<programlisting>
/vis/filtering/trajectories/create/particleFilter
/vis/filtering/trajectories/particleFilter-0/add gamma
/vis/filtering/trajectories/particleFilter-0/invert true
/vis/filtering/trajectories/particleFilter-0/verbose true
/vis/filtering/trajectories/particleFilter-0/active false
</programlisting>
</informalexample>
</para>

<para>
#Create a charge filter. Configure to pass only neutral
trajectories.
</para>

<para>
#Set verbose printout. Reset filter and reconfigure to pass
only
</para>

<para>
#negativly charged trajectories.

<informalexample>
<programlisting>
/vis/filtering/trajectories/create/chargeFilter
/vis/filtering/trajectories/chargeFilter-0/add 0
/vis/filtering/trajectories/chargeFilter-0/verbose true
/vis/filtering/trajectories/chargeFilter-0/reset true
/vis/filtering/trajectories/chargeFilter-0/add -1
</programlisting>
</informalexample>
</para>

<para>
#Create an attribute filter named attributeFilter-0

<informalexample>
<programlisting>
/vis/filtering/trajectories/create/attributeFilter
</programlisting>
</informalexample>
</para>

<para>
#Select attribute "IMag"

<informalexample>
<programlisting>
/vis/filtering/trajectories/attributeFilter-0/setAttribute IMag
</programlisting>
</informalexample>
</para>

<para>
#Select trajectories with 2.5 MeV &lt;= IMag&lt; 1000 MeV

<informalexample>
<programlisting>
/vis/filtering/trajectories/attributeFilter-0/addInterval 2.5 MeV 1000 MeV
</programlisting>
</informalexample>
</para>

<para>
#List filters

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

<para>
#Note that although particleFilter-0 and chargeFilter-0 are
automatically
</para>

<para>
#chained, particleFilter-0 will not have any effect since
</para>

<para>
#it is has been deactivated.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisFltr.HitFilt">
<title>
Hit Filtering
</title>

<para>
The attribute based filtering can be used on hits as well as trajectories. 
To active the interactive attribute based hit filtering, a filter call 
should be added to the "Draw" method of the hit class:

<informalexample>
<programlisting>
   void MyHit::Draw() 
   {
      ... 
      if (! pVVisManager->FilterHit(*this)) return;
      ...
   }
</programlisting>
</informalexample>
</para>

<para>
Interactive filtering can then be done through the commands in 
<literal>/vis/filtering/hits</literal>.
</para>


</sect2>
</sect1>