source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Visualization/commandcontrol.xml @ 904

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


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.VisCntCmmd">
<title>
Controlling Visualization from Commands
</title>

<para>
This section describes just a few of the more commonly used
visualization commands. 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>

<para>
For simplicity, this section assumes that the Geant4 executable
was compiled incorporating the DAWNFILE and the OpenGL-Xlib
drivers. For details on creating an executable for visualization
see <xref linkend="sect.VisAddExe" />.
</para>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.ScnHndVw">
<title>
Scene, scene handler, and viewer
</title>

<para>
In using the visualization commands, it is useful to know the
concept of "scene", "scene handler", and "viewer". A "scene" is a
set of visualizable raw 3D data. A "scene handler" is a
graphics-data modeler, which processes raw data in a scene for
later visualization. And a "viewer" generates images based on data
processed by a scene handler. Roughly speaking, a set of a scene
handler and a viewer corresponds to a visualization driver.
</para>

<para>
The steps of performing Geant4 visualization are explained
below, though some of these steps may be done for you so that in
practice you may use as few as just two commands (such as /vis/open
OGLIX plus /vis/drawVolume) The seven steps of visualization are:

<itemizedlist spacing="compact">
   <listitem><para>
     Step 1. Create a scene handler and a viewer.
   </para></listitem>
   <listitem><para>
     Step 2. Create an empty scene.
   </para></listitem>
   <listitem><para>
     Step 3. Add raw 3D data to the created scene.
   </para></listitem>
   <listitem><para>
     Step 4. Attach the current scene handler to the current scene.
   </para></listitem>
   <listitem><para>
     Step 5. Set camera parameters, drawing style (wireframe/surface), etc.
   </para></listitem>
   <listitem><para>
     Step 6. Make the viewer execute visualization.
   </para></listitem>
   <listitem><para>
     Step 7. Declare the end of visualization for flushing.
   </para></listitem>
</itemizedlist>
</para>

<para>
These seven steps can be controlled explicitly to create
multiple scenes and multiple viewers, each with its own set of
parameters, with easy switching from one scene to another. But for
the most common case of just having one scene and one viewer, many
steps are handled implicitly for you.
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.CrtScnVw">
<title>
Create a scene handler and a viewer: <literal>/vis/open</literal> command
</title>

<para>
Command "<literal>/vis/open</literal>" creates a scene handler and a viewer,
which corresponds to Step 1.
</para>

<para>
<emphasis role="bold">Command: </emphasis>
<literal>/vis/open [driver_tag_name]</literal>
</para>

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Argument</emphasis>
    <para>
    A name of (a mode of) an available visualization driver.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Action</emphasis>
    <para>
    Create a visualization driver, i.e. a set of a scene hander and a
    viewer.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Example: Create the OpenGL-Xlib driver with its 
    immediate mode</emphasis>
    <para>
    <literal>Idle&gt; /vis/open OGLIX</literal>
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Additional notes</emphasis>
    <para>
    For immediate viewers, such as OGLIX, your geometry will
    immediately be rendered in the new GL window
    </para>    
  </para></listitem>
</itemizedlist>

<para>
How to list available driver_tag_name:

<programlisting>
Idle&gt; help /vis/open
</programlisting>

or

<informalexample>
<programlisting>
Idle&gt; help /vis/sceneHandler/create
</programlisting>
</informalexample>

The list is, for example, displayed as follows:

<informalexample>
<programlisting>
.....
Candidates : DAWNFILE OGLIX OGLSX
.....
</programlisting>
</informalexample>
</para>

<para>
For additional 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.VisCntCmmd.CrtEmp">
<title>
Create an empty scene: <literal>/vis/scene/create</literal> command
</title>

<para>
Command "<literal>/vis/scene/create</literal>" creates an empty scene, 
which corresponds to Step 2.
</para>

<para>
<emphasis role="bold">Command: </emphasis>
<literal>
/vis/scene/create [scene_name]
</literal>
</para>

<itemizedlist spacing="compact">
  <listitem><para><emphasis role="bold">Argument</emphasis>
    <para>
    A name for this scene. Created for you if you don't specify one.
    </para>
  </para></listitem>
</itemizedlist>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.PhyVol">
<title>
Visualization of a physical volume: <literal>/vis/drawVolume</literal> command
</title>

<para>
Command "<literal>/vis/drawVolume</literal>" adds a physical volume to the
scene. It also does some of the other steps, if you haven't done
them explicitly. It takes care of steps 2, 3, 4 and 6. Command
"<literal>/vis/viewer/flush</literal>" should follow in order to do the final
Step 7.
</para>

<para>
<emphasis role="bold">Commands:</emphasis>
</para>
<para>
<informalexample>
<programlisting>
/vis/drawVolume [physical-volume-name]
.....
Idle&gt; /vis/viewer/flush
</programlisting>
</informalexample>
</para>

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Argument</emphasis>
    <para>
    A physical-volume name. The default value is "world", which is
    omittable.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Action</emphasis>
    <para>
    Creates a scene consisting of the given physical volume and asks
    the current viewer to draw it. The scene becomes current. Command
    "<literal>/vis/viewer/flush</literal>" should follow this command in order to
    declare end of visualization.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Example: Visualization of the whole world with 
    coordinate axes</emphasis>
    <informalexample>
    <programlisting>
    Idle&gt; /vis/drawVolume
    Idle&gt; /vis/scene/add/axes 0 0 0 500 mm
    Idle&gt; /vis/viewer/flush
    </programlisting>
    </informalexample>
  </para></listitem>
</itemizedlist>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.LogVol">
<title>
Visualization of a logical volume: <literal>/vis/specify</literal> command
</title>

<para>
Command "<literal>/vis/specify</literal>" visualizes a logical volume. If
allows you to control how much details is shown and whether to show
booleans, voxels and readout geometries. It also does some of the
other steps, if you haven't done them explicitly. It takes care of
steps 2, 3, 4 and 6. Command "<literal>/vis/viewer/flush</literal>" should
follow the command in order to do the final Step 7.
</para>

<para>
<emphasis role="bold">Command: </emphasis>
<literal>/vis/specify [logical-volume-name][depth-of-descent]
[booleans-flag] [voxels-flag] [readout-flag]</literal>
</para>

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Argument</emphasis>
    <para>
    A logical-volume name.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Action</emphasis>
    <para>
    Creates a scene consisting of the given logical volume and asks the
    current viewer to draw it. The scene becomes current.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Example (visualization of a selected logical 
    volume with coordinate axes)</emphasis>

    <informalexample>
    <programlisting>
    Idle&gt; /vis/specify Absorber
    Idle&gt; /vis/scene/add/axes 0 0 0 500 mm
    Idle&gt; /vis/scene/add/text 0 0 0 mm 40 -100 -200 LogVol:Absorber
    Idle&gt; /vis/viewer/flush
    </programlisting>
    </informalexample>
  </para></listitem>
</itemizedlist>

<para>
For more 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.VisCntCmmd.Traj">
<title>
Visualization of trajectories: <literal>/vis/scene/add/trajectories</literal> command
</title>

<para>

Command "<literal>/vis/scene/add/trajectories [smooth] [rich]</literal>"
adds trajectories to the current scene. The optional
parameters "smooth" and/or "rich" (you may specify either, both or
neither) invoke, if "smooth" is specified, the storing and displaying
of extra points on curved trajectories and, if "rich" is specified,
the storing, for possible subsequent selection and display, of
additional information, such as volume names, creator process, energy
deposited, global time. Be aware, of course, that this imposes
computational and memory overheads.  Note that this automatically
issues the appropriate
"<literal>/tracking/storeTrajectory</literal>" command so that trajectories are
stored (by default they are not). The visualization is performed
with the command "<literal>/run/beamOn</literal>" unless you have non-default
values for /vis/scene/endOfEventAction or /vis/scene/endOfRunAction
(described below).
</para>

<para>
<emphasis role="bold">Command: </emphasis>
<literal>/vis/scene/add/trajectories [smooth] [rich]</literal>
</para>

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Action</emphasis>
    <para>
    The command adds trajectories to the current scene. Trajectories
    are drawn at end of event when the scene in which they are added is
    current.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Example: Visualization of trajectories</emphasis>
    <informalexample>
    <programlisting>
    Idle&gt; /vis/scene/add/trajectories
    Idle&gt; /run/beamOn 10
    </programlisting>
    </informalexample>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Additional note 1</emphasis>
    <para>
    See the section 
    <xref linkend="sect.VisEnhTrj.CntlComm" /> 
    Enhanced Trajectory Drawing
    for details on how to control how trajectories are
    color-coded.
    </para>
  </para></listitem>
</itemizedlist>

<para>
For more 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.VisCntCmmd.Hits">
<title>
Visualization of hits: <literal>/vis/scene/add/hits</literal> command
</title>

<para>
Command "<literal>/vis/scene/add/hits</literal>" adds hits to the current
scene, assuming that you have a hit class and that the hits have
visualization information. The visualization is performed with the
command "<literal>/run/beamOn</literal>" unless you have non-default values
for /vis/scene/endOfEventAction or /vis/scene/endOfRunAction
(described above).
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.HrAtHits">
<title>
HepRep Attributes for Hits
</title>

<para>
The HepRep file formats, HepRepFile and HepRepXML, attach various
attributes to hits such that you can view these attributes, label
trajectories by these attributes or make visibility cuts based on
these attributes. Examples of adding HepRep attributes to hit
classes can be found in examples /extended/analysis/A01 and
/extended/runAndEvent/RE01.
</para>

<para>
For example, in example RE01's class RE01CalorimeterHit.cc,
available attributes will be:

<itemizedlist spacing="compact">
  <listitem><para>
    Hit Type
  </para></listitem>
  <listitem><para>
    Track ID
  </para></listitem>
  <listitem><para>
    Z Cell ID
  </para></listitem>
  <listitem><para>
    Phi Cell ID
  </para></listitem>
  <listitem><para>
    Energy Deposited
  </para></listitem>
  <listitem><para>
    Energy Deposited by Track
  </para></listitem>
  <listitem><para>
    Position
  </para></listitem>
  <listitem><para>
    Logical Volume
  </para></listitem>
</itemizedlist>
</para>

<para>
You can add additional attributes of your choosing by modifying the
relevant part of the hit class (look for the methods GetAttDefs and
CreateAttValues).
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.BscCmrWrk">
<title>
Basic camera workings: <literal>/vis/viewer/</literal> commands
</title>

<para>
Commands in the command directory "<literal>/vis/viewer/</literal>" set
camera parameters and drawing style of the current viewer, which
corresponds to Step 5. Note that the camera parameters and the
drawing style should be set separately for each viewer. They can be
initialized to the default values with command
"<literal>/vis/viewer/reset</literal>". Some visualization systems, such as
the VRML and HepRep browsers also allow camera control from the
standalone graphics application.
</para>

<para>
Just a few of the camera commands are described here. For more
commands, see the 
<ulink url="./AllResources/Control/UIcommands/_vis_.html">
Control...UICommands</ulink> section of this user guide.
</para>

<para>
<para><emphasis role="bold">Command: </emphasis>
<literal>/vis/viewer/set/viewpointThetaPhi [theta] [phi]
[deg|rad]</literal>
</para>

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Arguments</emphasis>
    <para>
    Arguments "theta" and "phi" are polar and azimuthal camera angles,
    respectively. The default unit is "degree".
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Action</emphasis>
    <para>
    Set a view point in direction of (theta, phi).
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Example: Set the viewpoint in direction of (70 deg, 
    20 deg)</emphasis>

    /<informalexample>
    <programlisting>
    Idle&gt; /vis/viewer/set/viewpointThetaPhi 70 20
    </programlisting>
    </informalexample>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Additional notes</emphasis>
    <para>
    Camera parameters should be set for each viewer. They are
    initialized with command "<literal>/vis/viewer/reset</literal>".
    </para>
  </para></listitem>
</itemizedlist>

<para>
<emphasis role="bold">Command: </emphasis>
<literal>/vis/viewer/zoom [scale_factor]</literal>
</para>

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Argument</emphasis>
    <para>
    The scale factor. The command multiplies magnification of the view
    by this factor.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Action</emphasis>
    <para>
    Zoom up/down of view.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Example: Zoom up by factor 1.5</emphasis>
    <informalexample>
    <programlisting>
    Idle&gt; /vis/viewer/zoom 1.5
    </programlisting>
    </informalexample>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Additional notes</emphasis>
    <para>
    Camera parameters should be set for each viewer. They are
    initialized with command "<literal>/vis/viewer/reset</literal>".
    </para>
    <para>
    A similar pair of commands, scale and scaleTo allow non-uniform
    scaling (i.e., zoom differently along different axes). For details,
    see the 
    <ulink url="./AllResources/Control/UIcommands/_vis_.html">
    Control...UICommands</ulink> section of this user guide.
    </para>
  </para></listitem>
</itemizedlist>
</para>

<para>
<emphasis role="bold">Command: </emphasis>
<literal>/vis/viewer/set/style [style_name]</literal>
</para>

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Arguments</emphasis>
    <para>
    Candidate values of the argument are "wireframe" and "surface".
    ("w" and "s" also work.)
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Action</emphasis>
    <para>
    Set a drawing style to wireframe or surface.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Example: Set the drawing style to "surface"</emphasis>
    <informalexample>
    <programlisting>
    Idle&gt; /vis/viewer/set/style surface
    </programlisting>
    </informalexample>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Additional notes</emphasis>
    <para>
    The style of some geometry components may have been forced one way
    or the other through calls in compiled code. The set/style command
    will NOT override such force styles.
    </para>
    <para>
    Drawing style should be set for each viewer. The drawing style is
    initialized with command "<literal>/vis/viewer/reset</literal>".
    </para>
  </para></listitem>
</itemizedlist>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.DclEndFlsh">
<title>
Declare the end of visualization for flushing: <literal>/vis/viewer/flush</literal> command
</title>

<para>
<emphasis role="bold">Command: </emphasis>
<literal>/vis/viewer/flush</literal>
</para>

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Action</emphasis>
    <para>
    Declare the end of visualization for flushing.
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Additional notes</emphasis>
    <para>
    Command "<literal>/vis/viewer/flush</literal>" should follow
    "<literal>/vis/drawVolume</literal>", "<literal>/vis/specify</literal>", 
    etc in order to complete visualization. It corresponds to Step 7.
    </para>
    <para>
    The flush is done automatically after every /run/beamOn command
    unless you have non-default values for /vis/scene/endOfEventAction
    or /vis/scene/endOfRunAction (described above).
    </para>
  </para></listitem>
</itemizedlist>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.EndEvtRun">
<title>
End of Event Action and End of Run Action:
<literal>/vis/viewer/endOfEventAction</literal> and
<literal>/vis/viewer/endOfEventAction</literal> commands
</title>

<para>
By default, a separate picture is created for each event. You can
change this behavior to accumulate multiple events, or even
multiple runs, in a single picture.
</para>

<para>
<emphasis role="bold">Command: </emphasis>
<literal>/vis/scene/endOfEventAction [refresh|accumulate]</literal>
</para>

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Action</emphasis>
    <para>
    Control how often the picture should be cleared.
    <literal>refresh</literal> means each event will be written to a new
    picture.
    <literal>accumulate</literal> means events will be accumulated into a single
    picture. Picture will be flushed at end of run, unless you have
    also set <literal>/vis/scene/endOfRunAction accumulate</literal>
    </para>
  </para></listitem>
  <listitem><para>
    <emphasis role="bold">Additional note</emphasis>
    <para>
    You may instead choose to use update commands from your
    BeginOfRunAction or EndOfEventAction, as in early examples, but now
    the vis manager ia able to do most of what most users require
    through the above commands.
    </para>    
  </para></listitem>
</itemizedlist>

<para>
<emphasis role="bold">Command: </emphasis>
<literal>/vis/scene/endOfRunAction [refresh|accumulate]</literal>
</para>

<itemizedlist spacing="compact">
  <listitem><para>
    <emphasis role="bold">Action</emphasis>
    <para>
    Control how often the picture should be cleared.
    <literal>refresh</literal> means each run will be written to a new
    picture.
    <literal>accumulate</literal> means runs will be accumulated into a single
    picture. To start a new picture, you must explicitly issue
    <literal>/vis/viewer/refresh</literal>, <literal>/vis/viewer/update</literal> 
    or <literal>/vis/viewer/flush</literal>
    </para>
  </para></listitem>
</itemizedlist>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.HpRpTraj">
<title>
HepRep Attributes for Trajectories
</title>

<para>
The HepRep file formats, HepRepFile and HepRepXML, attach various
attributes to trajectories such that you can view these attributes,
label trajectories by these attributes or make visibility cuts
based on these attributes. If you use the default Geant4 trajectory
class from /tracking/src/G4Trajectory.cc (this is what you get with
the plain <literal>/vis/scene/add/trajectories</literal> command),
available attributes will be:

<itemizedlist spacing="compact">
  <listitem><para>
    Track ID
  </para></listitem>
  <listitem><para>
    Parent ID
  </para></listitem>
  <listitem><para>
    Particle Name
  </para></listitem>
  <listitem><para>
    Charge
  </para></listitem>
  <listitem><para>
    PDG Encoding
  </para></listitem>
  <listitem><para>
    Momentum 3-Vector
  </para></listitem>
  <listitem><para>
    Momentum magnitude
  </para></listitem>
  <listitem><para>
    Number of points
  </para></listitem>
</itemizedlist>
</para>

<para>
Using <literal>/vis/scene/add/trajectories rich</literal> will get you
additional attributes.
You may also add additional attributes of your choosing by modifying the
relevant part of G4Trajectory (look for the methods GetAttDefs and
CreateAttValues). If you are using your own trajectory class, you
may want to consider copying these methods from G4Trajectory.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.SvVwPs">
<title>
How to save a visualized views to PostScript files
</title>

<para>
Most of the visualization drivers offer ways to save visualized
views to PostScript files (or Encapsulated PostScript (EPS) files)
by themselves.
</para>

<para>
The DAWNFILE driver, which co-works with Fukui Renderer DAWN,
generates "vectorized" PostScript data with "analytical
hidden-line/surface removal", and so it is well suited for
technical high-quality outputs for presentation, documentation, and
debugging geometry. In the default setting of the DAWNFILE drivers,
EPS files named "<literal>g4_00.eps, g4_01.eps, g4_02.eps</literal>,..." are
automatically generated in the current directory each time when
visualization is performed, and then a PostScript viewer
"<literal>gv</literal>"is automatically invoked to visualize the generated
EPS files.
</para>

<para>
For large data sets, it may take time to generate the vectorized
PostScript data. In such a case, visualize the 3D scene with a
faster visualization driver beforehand for previewing, and then use
the DAWNFILE drivers. For example, the following visualizes the
whole detector with the OpenGL-Xlib driver (immediate mode) first,
and then with the DAWNFILE driver to generate an EPS file
<literal>g4_XX.eps</literal> to save the visualized view:

<informalexample>
<programlisting>
# Invoke the OpenGL visualization driver in its immediate mode
/vis/open OGLIX 

# Camera setting
/vis/viewer/set/viewpointThetaPhi 20 20

# Camera setting
/vis/drawVolume 
/vis/viewer/flush

# Invoke the DAWNFILE visualization driver 
/vis/open DAWNFILE

# Camera setting
/vis/viewer/set/viewpointThetaPhi 20 20

# Camera setting
/vis/drawVolume 
/vis/viewer/flush
</programlisting>
</informalexample>
</para>

<para>
This is a good example to show that the visualization drivers are
complementary to each other.
</para>

<para>
In the OpenInventor drivers, you can simply click the "Print"
button on their GUI to generate a PostScript file as a hard copy of
a visualized view.
</para>

<para>
The OpenGL X drivers can also generate PostScript files, either from
a pull-down menu (Motif drivers) or with <literal>/vis/ogl/printEPS</literal>.
It can generate either vectorized or rasterized PostScript
data. In generating vectorized PostScript data, hidden-surface
removal is performed, based on the painter's algorithm after
dividing facets of shapes into small sub-triangles.
</para>

<para>
The WIRED3 HepRep Browser and WIRED4 JAS Plug-In can generate a
wide variety of bitmap and vector output formats including
PostScript and PDF.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.Cull">
<title>
Culling
</title>

<para>
"Culling" means to skip visualizing parts of a 3D scene. Culling is
useful for avoiding complexity of visualized views, keeping
transparent features of the 3D scene, and for quick visualization.
</para>

<para>
Geant4 Visualization supports the following 3 kinds of
culling:

<itemizedlist spacing="compact">
  <listitem><para>
    Culling of invisible physical volumes
  </para></listitem>
  <listitem><para>
    Culling of low density physical volumes.
  </para></listitem>
  <listitem><para>
    Culling of covered physical volumes by others
  </para></listitem>
</itemizedlist>
</para>

<para>
In order that one or all types of the above culling are on, i.e.,
activated, the global culling flag should also be on.
</para>

<para>
<xref linkend="table.VisCntCmmd_1" /> summarizes the default culling policies.

<table id="table.VisCntCmmd_1" align="center">
<title>
The default culling policies.
</title>

<tgroup cols="2">
  <tbody>
  <row>
    <entry>
      <emphasis role="bold">Culling Type</emphasis>
    </entry>
    <entry>
      <emphasis role="bold">Default Value</emphasis>
    </entry>
  </row>
  <row>
    <entry>
      global
    </entry>
    <entry>
      ON
    </entry>
  </row>
  <row>
    <entry>
      invisible
    </entry>
    <entry>
      ON
    </entry>
  </row>
  <row>
    <entry>
      low density
    </entry>
    <entry>
      OFF
    </entry>
  </row>
  <row>
    <entry>
      covered daughter
    </entry>
    <entry>
      OFF
    </entry>
  </row>
  </tbody>
</tgroup>
</table>
</para>

<para>
The default threshold density of the low-density culling is 0.01
g/cm<superscript>3</superscript>.
</para>

<para>
The default culling policies can be modified with the following
visualization commands. (Below the argument <literal>flag</literal> takes a
value of <literal>true</literal> or <literal>false</literal>.)

<informalexample>
<programlisting>
     # global
     /vis/viewer/set/culling  global  flag

     # invisible
     /vis/viewer/set/culling  invisible  flag

     # low density
     #   "value" is a proper value of a treshold density
     #   "unit" is either g/cm3, mg/cm3 or kg/m3
     /vis/viewer/set/culling  density  flag  value  unit 

     # covered daughter
     /vis/viewer/set/culling  coveredDaughters  flag     density
</programlisting> 
</informalexample>
</para>

<para>
The HepRepFile graphic system will, by default, include culled
objects in the file so that they can still be made visible later
from controls in the HepRep browser. If this behavior would cause
files to be too large, you can instead choose to have culled
objects be omitted from the HepRep file. See details in the
HepRepFile Driver section of this user guide.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.CutVw">
<title>
Cut view
</title> 

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

<para>
"Sectioning" means to make a thin slice of a 3D scene around a
given plane. At present, this function is supported by the OpenGL
drivers. The sectioning is realized by setting a sectioning plane
before performing visualization. The sectioning plane can be set by
the command,

<informalexample>
<programlisting>
     /vis/viewer/set/sectionPlane on x y z units nx ny nz
</programlisting>
</informalexample>

where the vector (x,y,z) defines a point on the sectioning plane,
and the vector (nx,ny,nz) defines the normal vector of the
sectioning plane. For example, the following sets a sectioning
plane to a yz plane at x = 2 cm:

<informalexample>
<programlisting>
     Idle&gt; /vis/viewer/set/sectionPlane  on  2.0  0.0  0.0  cm  1.0  0.0  0.0
</programlisting>
</informalexample>
</para>

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

<para>
"Cutting away" means to remove a half space, defined with a plane,
from a 3D scene.

<itemizedlist spacing="compact">
  <listitem><para>
    Cutting away is supported by the DAWNFILE driver "off-line". Do
    the following:

    <itemizedlist spacing="compact">
      <listitem><para>
        Perform visualization with the DAWNFILE driver to generate a
        file <literal>g4.prim</literal>, describing the whole 3D scene.
      </para></listitem>
      <listitem><para>
        Make the application "DAWNCUT" read the generated file to make
        a view of cutting away.
      </para></listitem>
    </itemizedlist>

    See the following WWW page for details: 
    <ulink url="http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAWNCUT.html">
    http://geant4.kek.jp/GEANT4/vis/DAWN/About_DAWNCUT.html
    </ulink>
  </para></listitem>
  <listitem><para>
    Alternatively, add up to three cutaway planes:

    <informalexample>
    <programlisting>
     /vis/viewer/addCutawayPlane 0 0 0 m 1 0 0
     /vis/viewer/addCutawayPlane 0 0 0 m 0 1 0
     ...
    </programlisting>
    </informalexample>
    and, for more that one plane, you can change the mode to

    <itemizedlist spacing="compact">
      <listitem><para>
        (a) "add" or, equivalently, "union" (default) or
      </para></listitem>
      <listitem><para>
        (b) "multiply" or, equivalently, "intersection":
      </para></listitem>
    </itemizedlist>

    <informalexample>
    <programlisting>
     /vis/viewer/set/cutawayMode multiply
    </programlisting>
    </informalexample>

    To de-activate:

    <informalexample>
    <programlisting>
     /vis/viewer/clearCutawayPlanes
    </programlisting>
    </informalexample>

    OpenGL supports this feature.
  </para></listitem>
</itemizedlist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisCntCmmd.TutMac">
<title>
Tutorial macros
</title>

<para>
The followings are tutorial macros in the directory
<literal>examples/novice/N03/visTutor/</literal>:

<itemizedlist spacing="compact">
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis0_mac.html">
    exN03Vis0.mac:</ulink>
    <para>
    A basic macro for visualization of detector geometry and events
    using OpenGL in Immediate mode and DAWN.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis1_mac.html">
    exN03Vis1.mac:</ulink>
    <para>
    A basic macro for visualization of detector geometry using OpenGL
    in Stored mode and DAWN.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis2_mac.html">
    exN03Vis2.mac:</ulink>
    <para>
    A basic macro for visualization of detector geometry and events
    using OpenGL in Stored mode and DAWN.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis3_mac.html">
    exN03Vis3.mac:</ulink>
    <para>
    A basic macro for demonstrating various drawing styles using OpenGL
    in Immediate mode and DAWN.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis4_mac.html">
    exN03Vis4.mac:</ulink>
    <para>
    An example of visualizing specific logical volumes using OpenGL in
    Immediate mode and DAWN.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis5_mac.html">
    exN03Vis5.mac:</ulink>
    <para>
    A basic macro for visualization of detector geometry and events
    using OpenInventor on Unix.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis6_mac.html">
    exN03Vis6.mac:</ulink>
    <para>
    A basic macro for visualization of detector geometry and events
    using VRML.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis7_mac.html">
    exN03Vis7.mac:</ulink>
    <para>
    A macro to demonstrate "batch" visualization to generate PostScript
    files with the DAWNFILE driver
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis8_mac.html">
    exN03Vis8.mac:</ulink>
    <para>
    A macro to demonstrate creation of a "multi-page" PostScript file
    with the DAWNFILE driver
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis9_mac.html">
    exN03Vis9.mac:</ulink>
    <para>
    A basic macro for visualization of detector geometry and events
    using OpenGL for Windows.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis10_mac.html">
    exN03Vis10.mac:</ulink>
    <para>
    A basic macro for visualization of detector geometry and events
    using OpenInventor on Windows.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis11_mac.html">
    exN03Vis11.mac:</ulink>
    <para>
    A basic macro for visualization of detector geometry and events
    using OpenGL in Stored Motif mode and DAWN.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis12_mac.html">
    exN03Vis12.mac:</ulink> and
    <ulink url="./Visualization/visTutor/exN03Vis12_loop.html">
    exN03Vis12.loop:</ulink>
    <para>
    A basic macro for demonstrating time slicing.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Vis13_mac.html">
    exN03Vis13.mac:</ulink> and
    <ulink url="./Visualization/visTutor/exN03Vis13_loop.html">
    exN03Vis3.loop:</ulink>
    <para>
    Time development of an electrmagnetic shower.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Tree0_mac.html">
    exN03Tree0.mac:</ulink>
    <para>
    A macro to demonstrate ASCII tree.
    </para>
  </para></listitem>
  <listitem><para>
    <ulink url="./Visualization/visTutor/exN03Tree1_mac.html">
    exN03Tree1.mac:</ulink>
    <para>
    A macro to demonstrate GAG tree.
    </para>
  </para></listitem>
</itemizedlist>
</para>


</sect2>
</sect1>