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

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Proof read by: Joe Chuma,  5-Jul-1999                 -->
<!--    Changed by: Katsuya Dosanjh, 15-Jul-2000              -->
<!--    Changed by: Dennis Wright, 27-Nov-2001                -->
<!--    Changed by: Satoshi Tanaka,  8-Dec-2002               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--                                                          -->
<!-- ******************************************************** -->


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

<para>
Visualization attributes are extra pieces of information associated
with the visualizable objects. This information is necessary only
for visualization, and is not included in geometrical information
such as shapes, position, and orientation. Typical examples of
visualization attributes are Color, Visible/Invisible,
Wireframe/Solid. For example, in visualizing a box, the
Visualization Manager must know its colour. If an object to be
visualized has not been assigned a set of visualization attributes,
then an appropriate default set is used automatically.
</para>

<para>
A set of visualization attributes is held by an instance of
class <emphasis>G4VisAttributes</emphasis> defined in the 
<literal>graphics_reps</literal> category. In the following, we 
explain the main fields of the <emphasis>G4VisAttributes</emphasis> 
one by one.
</para>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAtt.Vsblty">
<title>
Visibility
</title> 

<para>
Visibility is a boolean flag to control the visibility of objects
that are passed to the Visualization Manager for visualization.
Visibility is set with the following access function:

<informalexample>
<programlisting>
     void G4VisAttributes::SetVisibility (G4bool visibility);
</programlisting>
</informalexample>
</para>

<para>
If you give <literal>false</literal> to the argument, and if culling is
activated (see below), visualization is skipped for objects for
which this set of visualization attributes is assigned. The default
value of visibility is <literal>true</literal>.
</para>

<para>
Note that whether an object is visible or not is also affected
by the current culling policy, which can be tuned with
visualization commands.
</para>

<para>
By default the following public static function is defined:

<informalexample>
<programlisting>
     static const G4VisAttributes&amp; GetInvisible();
</programlisting>
</informalexample>

which returns a reference to a const object in which visibility is
set to <literal>false</literal>. It can be used as follows:

<informalexample>
<programlisting>
     experimentalHall_logical -&gt; SetVisAttributes (G4VisAttributes::GetInvisible());
</programlisting>
</informalexample>
</para>

<para>
Direct access to the public static const data member
<literal>G4VisAttributes::Invisible</literal> is also possible but deprecated
on account of initialisation issues with dynamic libraries.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAtt.Colr">
<title>
Colour
</title>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.VisAtt.Colr.Cnstr">
<title>
Construction
</title>

<para>
Class <emphasis>G4Colour</emphasis> (an equivalent class name, 
<emphasis>G4Color</emphasis>, is also available) has 4 fields, 
which represent the RGBA (red, green,
blue, and alpha) components of colour. Each component takes a value
between 0 and 1. If an irrelevant value, i.e., a value less than 0
or greater than 1, is given as an argument of the constructor, such
a value is automatically clipped to 0 or 1. Alpha is opacity, which
is not used at present. You can use its default value <literal>1</literal>,
which means "opaque" in instantiation of <emphasis>G4Colour</emphasis>.
</para>

<para>
A <emphasis>G4Colour</emphasis> object is instantiated by giving red, green,
and blue components to its constructor, i.e.,

<informalexample>
<programlisting>
     G4Colour::G4Colour ( G4double r = 1.0, 
                          G4double g = 1.0, 
                          G4double b = 1.0, 
                          G4double a = 1.0);
                                  // 0&lt;=red, green, blue &lt;= 1.0 
</programlisting>
</informalexample>
</para>

<para>
The default value of each component is 1.0. That is to say, the
default colour is "white" (opaque).
</para>

<para>
For example, colours which are often used can be instantiated as
follows:

<informalexample>
<programlisting>
     G4Colour  white   ()              ;  // <emphasis role="color_white">white</emphasis>
     G4Colour  white   (1.0, 1.0, 1.0) ;  // <emphasis role="color_white">white</emphasis>
     G4Colour  gray    (0.5, 0.5, 0.5) ;  // <emphasis role="color_gray">gray</emphasis>
     G4Colour  black   (0.0, 0.0, 0.0) ;  // <emphasis role="color_black">black</emphasis>
     G4Colour  red     (1.0, 0.0, 0.0) ;  // <emphasis role="color_red">red</emphasis>
     G4Colour  green   (0.0, 1.0, 0.0) ;  // <emphasis role="color_green">green</emphasis>
     G4Colour  blue    (0.0, 0.0, 1.0) ;  // <emphasis role="color_blue">blue</emphasis>
     G4Colour  cyan    (0.0, 1.0, 1.0) ;  // <emphasis role="color_cyan">cyan</emphasis>
     G4Colour  magenta (1.0, 0.0, 1.0) ;  // <emphasis role="color_magenta">magenta</emphasis>
     G4Colour  yellow  (1.0, 1.0, 0.0) ;  // <emphasis role="color_yellow">yellow</emphasis>
</programlisting>
</informalexample>
</para>

<para>
It is also possible to instantiate common colours through static
public data member functions:

<informalexample>
<programlisting>
     static const G4Colour&amp; White   ();  
     static const G4Colour&amp; Gray    ();  
     static const G4Colour&amp; Grey    (); 
     static const G4Colour&amp; Black   (); 
     static const G4Colour&amp; Red     (); 
     static const G4Colour&amp; Green   (); 
     static const G4Colour&amp; Blue    (); 
     static const G4Colour&amp; Cyan    (); 
     static const G4Colour&amp; Magenta (); 
     static const G4Colour&amp; Yellow  (); 
</programlisting>
</informalexample>
</para>

<para>
For example, a local <emphasis>G4Colour</emphasis> could be constructed
as:

<informalexample>
<programlisting>
     G4Colour myRed(G4Colour::Red());
</programlisting>
</informalexample>
</para>

<para>
After instantiation of a <emphasis>G4Colour</emphasis> object, you can access
to its components with the following access functions:

<informalexample>
<programlisting>
     G4double G4Colour::GetRed   () const ; // Get the red   component. 
     G4double G4Colour::GetGreen () const ; // Get the green component.
     G4double G4Colour::GetBlue  () const ; // Get the blue  component.
</programlisting>
</informalexample>
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.VisAtt.Colr.ColrMap">
<title>
Colour Map
</title>

<para>
<emphasis>G4Colour</emphasis> also provides a static colour map, giving access to
predefined <emphasis>G4Colour</emphasis>'s through a
<emphasis>G4String</emphasis> 
key. The default mapping is:
</para><para>

<informalexample>
<programlisting>
     G4String           G4Colour
     ---------------------------------------
     white              G4Colour::White   ()
     gray               G4Colour::Gray    ()
     grey               G4Colour::Grey    ()
     black              G4Colour::Black   ()
     red                G4Colour::Red     ()
     green              G4Colour::Green   ()
     blue               G4Colour::Blue    ()
     cyan               G4Colour::Cyan    ()
     magenta            G4Colour::Magenta ()
     yellow             G4Colour::Yellow  ()
</programlisting>
</informalexample>
</para>

<para>
Colours can be retrieved through the GetColour method:

<informalexample>
<programlisting>
     bool G4Colour::GetColour(const G4String&amp; key, G4Colour&amp; result)
</programlisting>
</informalexample>
</para>

<para>
For example:

<informalexample>
<programlisting>
    G4Colour myColour(G4Colour::Black());
    if (G4Colour::GetColour("red", myColour)) {
      // Successfully retrieved colour "red". myColour is now red
    }
    else {
      // Colour did not exist in map. myColour is still black
    }
</programlisting>
</informalexample>
</para>

<para>
If the key is not registered in the colour map, a warning
message is printed and the input colour is not changed. The colour
map is case insensitive.
</para>

<para>
It is also possible to load user defined <emphasis>G4Colour</emphasis>'s into
the map through the public AddToMap method. For example:

<informalexample>
<programlisting>
    G4Colour myColour(0.2, 0.2, 0.2, 1);
    G4Colour::AddToMap("custom", myColour);
</programlisting>
</informalexample>
</para>

<para>
This loads a user defined <emphasis>G4Colour</emphasis> with key "custom" into
the colour map.
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.VisAtt.Colr.G4VisAtt">
<title>
Colour and G4VisAttributes
</title>

<para>
Class <emphasis>G4VisAttributes</emphasis> holds its colour entry as an object of
class <emphasis>G4Colour</emphasis>. A <emphasis>G4Colour</emphasis> object is 
passed to a <emphasis>G4VisAttributes</emphasis> object with the following
access 
functions:

<informalexample>
<programlisting>
     //----- Set functions of G4VisAttributes.
     void G4VisAttributes::SetColour (const G4Colour&amp; colour);
     void G4VisAttributes::SetColor (const G4Color&amp; color );
</programlisting>
</informalexample>
</para>

<para>
We can also set RGBA components directly:

<informalexample>
<programlisting>
     //----- Set functions of G4VisAttributes
     void G4VisAttributes::SetColour ( G4double red   , 
                                       G4double green , 
                                       G4double blue  , 
                                       G4double alpha = 1.0);
  
     void G4VisAttributes::SetColor  ( G4double red   , 
                                       G4double green , 
                                       G4double blue  , 
                                       G4double alpha = 1.);
</programlisting>
</informalexample>
</para>

<para>
The following constructor with <emphasis>G4Colour</emphasis> as its argument is
also supported:

<informalexample>
<programlisting>
     //----- Constructor of G4VisAttributes
     G4VisAttributes::G4VisAttributes (const G4Colour&amp; colour);
</programlisting>
</informalexample>
</para>

<para>
Note that colour assigned to a <emphasis>G4VisAttributes</emphasis> object is
not always the colour that ultimately appears in the visualization.
The ultimate appearance may be affected by shading and lighting
models applied in the selected visualization driver or stand-alone
graphics system.
</para>

</sect3>
</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAtt.FrcAtt">
<title>
Forcing attributes
</title> 

<para>
As you will see later, you can select a "drawing style" from
various options. For example, you can select your detector
components to be visualized in "wireframe" or with "surfaces". In
the former, only the edges of your detector are drawn and so the
detector looks transparent. In the latter, your detector looks
opaque with shading effects.
</para>

<para>
The forced wireframe and forced solid styles make it possible to
mix the wireframe and surface visualization (if your selected
graphics system supports such visualization). For example, you can
make only the outer wall of your detector "wired" (transparent) and
can see inside in detail.
</para>

<para>
Forced wireframe style is set with the following access
function:

<informalexample>
<programlisting>
     void G4VisAttributes::SetForceWireframe (G4bool force);
</programlisting>
</informalexample>
</para>

<para>
If you give <literal>true</literal> as the argument, objects for which this
set of visualization attributes is assigned are always visualized
in wireframe even if in general, the surface drawing style has been
requested. The default value of the forced wireframe style is
<literal>false</literal>.
</para>

<para>
Similarly, forced solid style, i.e., to force that objects are
always visualized with surfaces, is set with:

<informalexample>
<programlisting>
     void G4VisAttributes::SetForceSolid (G4bool force);
</programlisting>
</informalexample>
</para>

<para>
The default value of the forced solid style is <literal>false</literal>, too.
</para>

<para>
You can also force auxiliary edges to be visible. Normally they
are not visible unless you set the appropriate view parameter.
Forcing the auxiliary edges to be visible means that auxiliary
edges will be seen whatever the view parameters.
</para>

<para>
Auxiliary edges are not genuine edges of the volume. They may be
in a curved surface made out of polygons, for example, or in plane
surface of complicated shape that has to be broken down into
simpler polygons. HepPolyhedron breaks all surfaces into triangles
or quadrilaterals. There will be auxiliary edges for any volumes
with a curved surface, such as a tube or a sphere, or a volume
resulting from a Boolean operation. Normally, they are not shown,
but sometimes it is useful to see them. In particular, a sphere,
because it has no egdes, will not be seen in wireframe mode in some
graphics systems unless requested by the view parameters or forced,
as described here.
</para>

<para>
To force auxiliary edges to be visible, use:

<informalexample>
<programlisting>
     void G4VisAttributes::SetForceAuxEdgeVisible (G4bool force);
</programlisting>
</informalexample>
</para>

<para>
The default value of the force auxiliary edges visible flag is
<literal>false</literal>.
</para>

<para>
For volumes with edges that are parts of a circle, such as a
tube (G4Tubs), etc., it is possible to force the precision of
polyhedral representation for visualisation. This is recommended
for volumes containing only a small angle of circle, for example, a
thin tube segment.
</para>

<para>
For visualisation, a circle is represented by an N-sided
polygon. The default is 24 sides or segments. The user may change
this for all volumes in a particular viewer at run time with
/vis/viewer/set/lineSegmentsPerCircle; alternatively it can be
forced for a particular volume with:

<informalexample>
<programlisting>
     void G4VisAttributes::SetForceLineSegmentsPerCircle (G4int nSegments);
</programlisting>
</informalexample>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAtt.CnstAtt">
<title>
Constructors of G4VisAttributes
</title>

<para>
The following constructors are supported for class
<emphasis>G4VisAttributes</emphasis>:

<informalexample>
<programlisting>
     //----- Constructors of class G4VisAttributes
     G4VisAttributes (void);
     G4VisAttributes (G4bool visibility);
     G4VisAttributes (const G4Colour&amp; colour);
     G4VisAttributes (G4bool visibility, const G4Colour&amp; colour);
</programlisting>
</informalexample>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAtt.AssgLgVol">
<title>
How to assign G4VisAttributes to a logical volume
</title>

<para>
In constructing your detector components, you may assign a set of
visualization attributes to each "logical volume" in order to
visualize them later (if you do not do this, the graphics system
will use a default set). You cannot make a solid such as
<emphasis>G4Box</emphasis> hold a set of visualization attributes; this is
because a solid should hold only geometrical information. At
present, you cannot make a physical volume hold one, but there are
plans to design a memory-efficient way to do it; however, you can
visualize a transient piece of solid or physical volume with a
temporary assigned set of visualization attributes.
</para>

<para>
Class <emphasis>G4LogicalVolume</emphasis> holds a pointer of
<emphasis>G4VisAttributes.</emphasis> This field is set and referenced with the
following access functions:

<informalexample>
<programlisting>
     //----- Set functions of G4VisAttributes
     void G4VisAttributes::SetVisAttributes (const G4VisAttributes* pVA);
     void G4VisAttributes::SetVisAttributes (const G4VisAttributes&amp; VA);

     //----- Get functions of G4VisAttributes
     const G4VisAttributes* G4VisAttributes::GetVisAttributes () const;
</programlisting>
</informalexample>
</para>

<para>
The following is sample C++ source codes for assigning a set of
visualization attributes with cyan colour and forced wireframe
style to a logical volume:

<informalexample>
<programlisting>
     //----- C++ source codes: Assigning G4VisAttributes to a logical volume
     ...
          // Instantiation of a logical volume
     myTargetLog = new G4LogicalVolume( myTargetTube,BGO, "TLog", 0, 0, 0);
     ...
          // Instantiation of a set of visualization attributes with cyan colour
     G4VisAttributes * calTubeVisAtt = new G4VisAttributes(G4Colour(0.,1.,1.));
          // Set the forced wireframe style 
     calTubeVisAtt-&gt;SetForceWireframe(true);
          // Assignment of the visualization attributes to the logical volume
     myTargetLog-&gt;SetVisAttributes(calTubeVisAtt);

     //----- end of C++ source codes
</programlisting>
</informalexample>
</para>

<para>
Note that the life of the visualization attributes must be at
least as long as the objects to which they are assigned; it is the
users' responsibility to ensure this, and to delete the
visualization attributes when they are no longer needed (or just
leave them to die at the end of the job).
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisAtt.AddUdefAtt">
<title>
Additional User-Defined Attributes
</title>

<para>
Geant4 Trajectories and Hits can be assigned additional arbitrary
attributes that will be displayed when you click on the relevant
object in the WIRED or FRED HepRep browsers. WIRED then lets you
label objects by any of these attributes or cut visibility based on
these attributes.
</para>

<para>
Define the attributes with lines such as:

<informalexample>
<programlisting>
     std::map&lt;G4String,G4AttDef&gt;* store = G4AttDefStore::GetInstance("G4Trajectory",isNew);     
     G4String PN("PN");    
     (*store)[PN] = G4AttDef(PN,"Particle Name","Physics","","G4String");     
     G4String IMom("IMom");     
     (*store)[IMom] = G4AttDef(IMom, "Momentum of track at start of trajectory", "Physics", "",
                                     "G4ThreeVector");
</programlisting>
</informalexample>
</para>

<para>
Then fill the attributes with lines such as:

<informalexample>
<programlisting>
     std::vector&lt;G4AttValue&gt;* values = new std::vector&lt;G4AttValue&gt;;
     values-&gt;push_back(G4AttValue("PN",ParticleName,""));
     s.seekp(std::ios::beg);
     s &lt;&lt; G4BestUnit(initialMomentum,"Energy") &lt;&lt; std::ends;
     values-&gt;push_back(G4AttValue("IMom",c,""));
</programlisting>
</informalexample>
</para>

<para>
See geant4/source/tracking/src/G4Trajectory.cc for a good example.
</para>

<para>
<emphasis>G4AttValue</emphasis> objects are light, containing just the value;
for the long description and other sharable information the
<emphasis>G4AttValue</emphasis> object refers to a <emphasis>G4AttDef</emphasis> 
object. They are based on the HepRep standard described at 
<ulink url="http://www.slac.stanford.edu/~perl/heprep/">
http://www.slac.stanford.edu/~perl/heprep/
</ulink>.
Geant4 also provides an <emphasis>G4AttDefStore</emphasis>.
</para>

<para>
Geant4 provides some default examples of the use of this
facility in the trajectory classes in /source/tracking such as
<emphasis>G4Trajectory</emphasis>, <emphasis>G4SmoothTrajectory</emphasis>.
<emphasis>G4Trajectory::CreateAttValues</emphasis> shows how 
<emphasis>G4AttValue</emphasis> objects can be made and 
<emphasis>G4Trajectory::GetAttDefs</emphasis> shows how
to make the corresponding <emphasis>G4AttDef</emphasis> objects and use the
<emphasis>G4AttDefStore</emphasis>. Note that the "user" of CreateAttValues
guarantees to destroy them; this is a way of allowing creation on
demand and leaving the <emphasis>G4Trajectory</emphasis> object, for example,
free of such objects in memory. The comments in
<emphasis>G4VTrajectory.hh</emphasis> explain further and additional insights
might be obtained by looking at two methods which use them, namely
<emphasis>G4VTrajectory::DrawTrajectory</emphasis> and
<emphasis>G4VTrajectory::ShowTrajectory</emphasis>.
</para>

<para>
Hits classes in examples /extended/analysis/A01 and
/extended/runAndEvent/RE01 show how to do the same for your hits.
The base class no-action methods CreateAttValues and GetAttDefs
should be overridden in your concrete class. The comments in
<emphasis>G4VHit.hh</emphasis> explain further.
</para>

<para>
In addition, the user is free to add a
<emphasis>G4std::vector&lt;G4AttValue&gt;*</emphasis> and a
<emphasis>G4std::vector&lt;G4AttDef&gt;*</emphasis> to a 
<emphasis>G4VisAttributes</emphasis> object as could, for example, 
be used by a <emphasis>G4LogicalVolume</emphasis> object.
</para>

<para>
At the time of writing, only the HepRep graphics systems are
capable of displaying the G4AttValue information, but this
information will become useful for all Geant4 visualization systems
through improvements in release 8.1 or later.
</para>


</sect2>
</sect1>