source: trunk/Documentation/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch08s06.html @ 901

Last change on this file since 901 was 901, checked in by garnier, 16 years ago

Add Geant4 Documentation at 8.12.2008
File size: 23.7 KB
Line 
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>8.6.  Visualization Attributes</title><link rel="stylesheet" href="../xml/XSLCustomizationLayer/G4HTMLStylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"><link rel="start" href="index.html" title="Geant4 User's Guide for Application Developers"><link rel="up" href="ch08.html" title="Chapter 8.  Visualization"><link rel="prev" href="ch08s05.html" title="8.5.  Controlling Visualization from Compiled Code"><link rel="next" href="ch08s07.html" title="8.7.  Enhanced Trajectory Drawing"><script language="JavaScript">
2function remote_win(fName)
3{
4   var url = "AllResources/Detector/geometry.src/" + fName;
5   RemoteWin=window.open(url,"","resizable=no,toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=0,copyhistory=0,width=520,height=520")
6   RemoteWin.creator=self
7}
8</script></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">8.6. 
9Visualization Attributes
10</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch08s05.html"><img src="AllResources/IconsGIF/prev.gif" alt="Prev"></a> </td><th width="60%" align="center">Chapter 8. 
11Visualization
12</th><td width="20%" align="right"> <a accesskey="n" href="ch08s07.html"><img src="AllResources/IconsGIF/next.gif" alt="Next"></a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect.VisAtt"></a>8.6. 
13Visualization Attributes
14</h2></div></div></div><p>
15Visualization attributes are extra pieces of information associated
16with the visualizable objects. This information is necessary only
17for visualization, and is not included in geometrical information
18such as shapes, position, and orientation. Typical examples of
19visualization attributes are Color, Visible/Invisible,
20Wireframe/Solid. For example, in visualizing a box, the
21Visualization Manager must know its colour. If an object to be
22visualized has not been assigned a set of visualization attributes,
23then an appropriate default set is used automatically.
24</p><p>
25A set of visualization attributes is held by an instance of
26class <span class="emphasis"><em>G4VisAttributes</em></span> defined in the
27<code class="literal">graphics_reps</code> category. In the following, we
28explain the main fields of the <span class="emphasis"><em>G4VisAttributes</em></span> 
29one by one.
30</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAtt.Vsblty"></a>8.6.1. 
31Visibility
32</h3></div></div></div><p>
33Visibility is a boolean flag to control the visibility of objects
34that are passed to the Visualization Manager for visualization.
35Visibility is set with the following access function:
36
37</p><div class="informalexample"><pre class="programlisting">
38     void G4VisAttributes::SetVisibility (G4bool visibility);
39</pre></div><p>
40</p><p>
41If you give <code class="literal">false</code> to the argument, and if culling is
42activated (see below), visualization is skipped for objects for
43which this set of visualization attributes is assigned. The default
44value of visibility is <code class="literal">true</code>.
45</p><p>
46Note that whether an object is visible or not is also affected
47by the current culling policy, which can be tuned with
48visualization commands.
49</p><p>
50By default the following public static function is defined:
51
52</p><div class="informalexample"><pre class="programlisting">
53     static const G4VisAttributes&amp; GetInvisible();
54</pre></div><p>
55
56which returns a reference to a const object in which visibility is
57set to <code class="literal">false</code>. It can be used as follows:
58
59</p><div class="informalexample"><pre class="programlisting">
60     experimentalHall_logical -&gt; SetVisAttributes (G4VisAttributes::GetInvisible());
61</pre></div><p>
62</p><p>
63Direct access to the public static const data member
64<code class="literal">G4VisAttributes::Invisible</code> is also possible but deprecated
65on account of initialisation issues with dynamic libraries.
66</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAtt.Colr"></a>8.6.2. 
67Colour
68</h3></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect.VisAtt.Colr.Cnstr"></a>8.6.2.1. 
69Construction
70</h4></div></div></div><p>
71Class <span class="emphasis"><em>G4Colour</em></span> (an equivalent class name,
72<span class="emphasis"><em>G4Color</em></span>, is also available) has 4 fields,
73which represent the RGBA (red, green,
74blue, and alpha) components of colour. Each component takes a value
75between 0 and 1. If an irrelevant value, i.e., a value less than 0
76or greater than 1, is given as an argument of the constructor, such
77a value is automatically clipped to 0 or 1. Alpha is opacity, which
78is not used at present. You can use its default value <code class="literal">1</code>,
79which means "opaque" in instantiation of <span class="emphasis"><em>G4Colour</em></span>.
80</p><p>
81A <span class="emphasis"><em>G4Colour</em></span> object is instantiated by giving red, green,
82and blue components to its constructor, i.e.,
83
84</p><div class="informalexample"><pre class="programlisting">
85     G4Colour::G4Colour ( G4double r = 1.0,
86                          G4double g = 1.0,
87                          G4double b = 1.0,
88                          G4double a = 1.0);
89                                  // 0&lt;=red, green, blue &lt;= 1.0
90</pre></div><p>
91</p><p>
92The default value of each component is 1.0. That is to say, the
93default colour is "white" (opaque).
94</p><p>
95For example, colours which are often used can be instantiated as
96follows:
97
98</p><div class="informalexample"><pre class="programlisting">
99     G4Colour  white   ()              ;  // <span class="color_white">white</span>
100     G4Colour  white   (1.0, 1.0, 1.0) ;  // <span class="color_white">white</span>
101     G4Colour  gray    (0.5, 0.5, 0.5) ;  // <span class="color_gray">gray</span>
102     G4Colour  black   (0.0, 0.0, 0.0) ;  // <span class="color_black">black</span>
103     G4Colour  red     (1.0, 0.0, 0.0) ;  // <span class="color_red">red</span>
104     G4Colour  green   (0.0, 1.0, 0.0) ;  // <span class="color_green">green</span>
105     G4Colour  blue    (0.0, 0.0, 1.0) ;  // <span class="color_blue">blue</span>
106     G4Colour  cyan    (0.0, 1.0, 1.0) ;  // <span class="color_cyan">cyan</span>
107     G4Colour  magenta (1.0, 0.0, 1.0) ;  // <span class="color_magenta">magenta</span>
108     G4Colour  yellow  (1.0, 1.0, 0.0) ;  // <span class="color_yellow">yellow</span>
109</pre></div><p>
110</p><p>
111It is also possible to instantiate common colours through static
112public data member functions:
113
114</p><div class="informalexample"><pre class="programlisting">
115     static const G4Colour&amp; White   (); 
116     static const G4Colour&amp; Gray    (); 
117     static const G4Colour&amp; Grey    ();
118     static const G4Colour&amp; Black   ();
119     static const G4Colour&amp; Red     ();
120     static const G4Colour&amp; Green   ();
121     static const G4Colour&amp; Blue    ();
122     static const G4Colour&amp; Cyan    ();
123     static const G4Colour&amp; Magenta ();
124     static const G4Colour&amp; Yellow  ();
125</pre></div><p>
126</p><p>
127For example, a local <span class="emphasis"><em>G4Colour</em></span> could be constructed
128as:
129
130</p><div class="informalexample"><pre class="programlisting">
131     G4Colour myRed(G4Colour::Red());
132</pre></div><p>
133</p><p>
134After instantiation of a <span class="emphasis"><em>G4Colour</em></span> object, you can access
135to its components with the following access functions:
136
137</p><div class="informalexample"><pre class="programlisting">
138     G4double G4Colour::GetRed   () const ; // Get the red   component.
139     G4double G4Colour::GetGreen () const ; // Get the green component.
140     G4double G4Colour::GetBlue  () const ; // Get the blue  component.
141</pre></div><p>
142</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect.VisAtt.Colr.ColrMap"></a>8.6.2.2. 
143Colour Map
144</h4></div></div></div><p>
145<span class="emphasis"><em>G4Colour</em></span> also provides a static colour map, giving access to
146predefined <span class="emphasis"><em>G4Colour</em></span>'s through a
147<span class="emphasis"><em>G4String</em></span> 
148key. The default mapping is:
149</p><p>
150
151</p><div class="informalexample"><pre class="programlisting">
152     G4String           G4Colour
153     ---------------------------------------
154     white              G4Colour::White   ()
155     gray               G4Colour::Gray    ()
156     grey               G4Colour::Grey    ()
157     black              G4Colour::Black   ()
158     red                G4Colour::Red     ()
159     green              G4Colour::Green   ()
160     blue               G4Colour::Blue    ()
161     cyan               G4Colour::Cyan    ()
162     magenta            G4Colour::Magenta ()
163     yellow             G4Colour::Yellow  ()
164</pre></div><p>
165</p><p>
166Colours can be retrieved through the GetColour method:
167
168</p><div class="informalexample"><pre class="programlisting">
169     bool G4Colour::GetColour(const G4String&amp; key, G4Colour&amp; result)
170</pre></div><p>
171</p><p>
172For example:
173
174</p><div class="informalexample"><pre class="programlisting">
175    G4Colour myColour(G4Colour::Black());
176    if (G4Colour::GetColour("red", myColour)) {
177      // Successfully retrieved colour "red". myColour is now red
178    }
179    else {
180      // Colour did not exist in map. myColour is still black
181    }
182</pre></div><p>
183</p><p>
184If the key is not registered in the colour map, a warning
185message is printed and the input colour is not changed. The colour
186map is case insensitive.
187</p><p>
188It is also possible to load user defined <span class="emphasis"><em>G4Colour</em></span>'s into
189the map through the public AddToMap method. For example:
190
191</p><div class="informalexample"><pre class="programlisting">
192    G4Colour myColour(0.2, 0.2, 0.2, 1);
193    G4Colour::AddToMap("custom", myColour);
194</pre></div><p>
195</p><p>
196This loads a user defined <span class="emphasis"><em>G4Colour</em></span> with key "custom" into
197the colour map.
198</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect.VisAtt.Colr.G4VisAtt"></a>8.6.2.3. 
199Colour and G4VisAttributes
200</h4></div></div></div><p>
201Class <span class="emphasis"><em>G4VisAttributes</em></span> holds its colour entry as an object of
202class <span class="emphasis"><em>G4Colour</em></span>. A <span class="emphasis"><em>G4Colour</em></span> object is
203passed to a <span class="emphasis"><em>G4VisAttributes</em></span> object with the following
204access
205functions:
206
207</p><div class="informalexample"><pre class="programlisting">
208     //----- Set functions of G4VisAttributes.
209     void G4VisAttributes::SetColour (const G4Colour&amp; colour);
210     void G4VisAttributes::SetColor (const G4Color&amp; color );
211</pre></div><p>
212</p><p>
213We can also set RGBA components directly:
214
215</p><div class="informalexample"><pre class="programlisting">
216     //----- Set functions of G4VisAttributes
217     void G4VisAttributes::SetColour ( G4double red   ,
218                                       G4double green ,
219                                       G4double blue  ,
220                                       G4double alpha = 1.0);
221 
222     void G4VisAttributes::SetColor  ( G4double red   ,
223                                       G4double green ,
224                                       G4double blue  ,
225                                       G4double alpha = 1.);
226</pre></div><p>
227</p><p>
228The following constructor with <span class="emphasis"><em>G4Colour</em></span> as its argument is
229also supported:
230
231</p><div class="informalexample"><pre class="programlisting">
232     //----- Constructor of G4VisAttributes
233     G4VisAttributes::G4VisAttributes (const G4Colour&amp; colour);
234</pre></div><p>
235</p><p>
236Note that colour assigned to a <span class="emphasis"><em>G4VisAttributes</em></span> object is
237not always the colour that ultimately appears in the visualization.
238The ultimate appearance may be affected by shading and lighting
239models applied in the selected visualization driver or stand-alone
240graphics system.
241</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAtt.FrcAtt"></a>8.6.3. 
242Forcing attributes
243</h3></div></div></div><p>
244As you will see later, you can select a "drawing style" from
245various options. For example, you can select your detector
246components to be visualized in "wireframe" or with "surfaces". In
247the former, only the edges of your detector are drawn and so the
248detector looks transparent. In the latter, your detector looks
249opaque with shading effects.
250</p><p>
251The forced wireframe and forced solid styles make it possible to
252mix the wireframe and surface visualization (if your selected
253graphics system supports such visualization). For example, you can
254make only the outer wall of your detector "wired" (transparent) and
255can see inside in detail.
256</p><p>
257Forced wireframe style is set with the following access
258function:
259
260</p><div class="informalexample"><pre class="programlisting">
261     void G4VisAttributes::SetForceWireframe (G4bool force);
262</pre></div><p>
263</p><p>
264If you give <code class="literal">true</code> as the argument, objects for which this
265set of visualization attributes is assigned are always visualized
266in wireframe even if in general, the surface drawing style has been
267requested. The default value of the forced wireframe style is
268<code class="literal">false</code>.
269</p><p>
270Similarly, forced solid style, i.e., to force that objects are
271always visualized with surfaces, is set with:
272
273</p><div class="informalexample"><pre class="programlisting">
274     void G4VisAttributes::SetForceSolid (G4bool force);
275</pre></div><p>
276</p><p>
277The default value of the forced solid style is <code class="literal">false</code>, too.
278</p><p>
279You can also force auxiliary edges to be visible. Normally they
280are not visible unless you set the appropriate view parameter.
281Forcing the auxiliary edges to be visible means that auxiliary
282edges will be seen whatever the view parameters.
283</p><p>
284Auxiliary edges are not genuine edges of the volume. They may be
285in a curved surface made out of polygons, for example, or in plane
286surface of complicated shape that has to be broken down into
287simpler polygons. HepPolyhedron breaks all surfaces into triangles
288or quadrilaterals. There will be auxiliary edges for any volumes
289with a curved surface, such as a tube or a sphere, or a volume
290resulting from a Boolean operation. Normally, they are not shown,
291but sometimes it is useful to see them. In particular, a sphere,
292because it has no egdes, will not be seen in wireframe mode in some
293graphics systems unless requested by the view parameters or forced,
294as described here.
295</p><p>
296To force auxiliary edges to be visible, use:
297
298</p><div class="informalexample"><pre class="programlisting">
299     void G4VisAttributes::SetForceAuxEdgeVisible (G4bool force);
300</pre></div><p>
301</p><p>
302The default value of the force auxiliary edges visible flag is
303<code class="literal">false</code>.
304</p><p>
305For volumes with edges that are parts of a circle, such as a
306tube (G4Tubs), etc., it is possible to force the precision of
307polyhedral representation for visualisation. This is recommended
308for volumes containing only a small angle of circle, for example, a
309thin tube segment.
310</p><p>
311For visualisation, a circle is represented by an N-sided
312polygon. The default is 24 sides or segments. The user may change
313this for all volumes in a particular viewer at run time with
314/vis/viewer/set/lineSegmentsPerCircle; alternatively it can be
315forced for a particular volume with:
316
317</p><div class="informalexample"><pre class="programlisting">
318     void G4VisAttributes::SetForceLineSegmentsPerCircle (G4int nSegments);
319</pre></div><p>
320</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAtt.CnstAtt"></a>8.6.4. 
321Constructors of G4VisAttributes
322</h3></div></div></div><p>
323The following constructors are supported for class
324<span class="emphasis"><em>G4VisAttributes</em></span>:
325
326</p><div class="informalexample"><pre class="programlisting">
327     //----- Constructors of class G4VisAttributes
328     G4VisAttributes (void);
329     G4VisAttributes (G4bool visibility);
330     G4VisAttributes (const G4Colour&amp; colour);
331     G4VisAttributes (G4bool visibility, const G4Colour&amp; colour);
332</pre></div><p>
333</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAtt.AssgLgVol"></a>8.6.5. 
334How to assign G4VisAttributes to a logical volume
335</h3></div></div></div><p>
336In constructing your detector components, you may assign a set of
337visualization attributes to each "logical volume" in order to
338visualize them later (if you do not do this, the graphics system
339will use a default set). You cannot make a solid such as
340<span class="emphasis"><em>G4Box</em></span> hold a set of visualization attributes; this is
341because a solid should hold only geometrical information. At
342present, you cannot make a physical volume hold one, but there are
343plans to design a memory-efficient way to do it; however, you can
344visualize a transient piece of solid or physical volume with a
345temporary assigned set of visualization attributes.
346</p><p>
347Class <span class="emphasis"><em>G4LogicalVolume</em></span> holds a pointer of
348<span class="emphasis"><em>G4VisAttributes.</em></span> This field is set and referenced with the
349following access functions:
350
351</p><div class="informalexample"><pre class="programlisting">
352     //----- Set functions of G4VisAttributes
353     void G4VisAttributes::SetVisAttributes (const G4VisAttributes* pVA);
354     void G4VisAttributes::SetVisAttributes (const G4VisAttributes&amp; VA);
355
356     //----- Get functions of G4VisAttributes
357     const G4VisAttributes* G4VisAttributes::GetVisAttributes () const;
358</pre></div><p>
359</p><p>
360The following is sample C++ source codes for assigning a set of
361visualization attributes with cyan colour and forced wireframe
362style to a logical volume:
363
364</p><div class="informalexample"><pre class="programlisting">
365     //----- C++ source codes: Assigning G4VisAttributes to a logical volume
366     ...
367          // Instantiation of a logical volume
368     myTargetLog = new G4LogicalVolume( myTargetTube,BGO, "TLog", 0, 0, 0);
369     ...
370          // Instantiation of a set of visualization attributes with cyan colour
371     G4VisAttributes * calTubeVisAtt = new G4VisAttributes(G4Colour(0.,1.,1.));
372          // Set the forced wireframe style
373     calTubeVisAtt-&gt;SetForceWireframe(true);
374          // Assignment of the visualization attributes to the logical volume
375     myTargetLog-&gt;SetVisAttributes(calTubeVisAtt);
376
377     //----- end of C++ source codes
378</pre></div><p>
379</p><p>
380Note that the life of the visualization attributes must be at
381least as long as the objects to which they are assigned; it is the
382users' responsibility to ensure this, and to delete the
383visualization attributes when they are no longer needed (or just
384leave them to die at the end of the job).
385</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.VisAtt.AddUdefAtt"></a>8.6.6. 
386Additional User-Defined Attributes
387</h3></div></div></div><p>
388Geant4 Trajectories and Hits can be assigned additional arbitrary
389attributes that will be displayed when you click on the relevant
390object in the WIRED or FRED HepRep browsers. WIRED then lets you
391label objects by any of these attributes or cut visibility based on
392these attributes.
393</p><p>
394Define the attributes with lines such as:
395
396</p><div class="informalexample"><pre class="programlisting">
397     std::map&lt;G4String,G4AttDef&gt;* store = G4AttDefStore::GetInstance("G4Trajectory",isNew);     
398     G4String PN("PN");   
399     (*store)[PN] = G4AttDef(PN,"Particle Name","Physics","","G4String");     
400     G4String IMom("IMom");     
401     (*store)[IMom] = G4AttDef(IMom, "Momentum of track at start of trajectory", "Physics", "",
402                                     "G4ThreeVector");
403</pre></div><p>
404</p><p>
405Then fill the attributes with lines such as:
406
407</p><div class="informalexample"><pre class="programlisting">
408     std::vector&lt;G4AttValue&gt;* values = new std::vector&lt;G4AttValue&gt;;
409     values-&gt;push_back(G4AttValue("PN",ParticleName,""));
410     s.seekp(std::ios::beg);
411     s &lt;&lt; G4BestUnit(initialMomentum,"Energy") &lt;&lt; std::ends;
412     values-&gt;push_back(G4AttValue("IMom",c,""));
413</pre></div><p>
414</p><p>
415See geant4/source/tracking/src/G4Trajectory.cc for a good example.
416</p><p>
417<span class="emphasis"><em>G4AttValue</em></span> objects are light, containing just the value;
418for the long description and other sharable information the
419<span class="emphasis"><em>G4AttValue</em></span> object refers to a <span class="emphasis"><em>G4AttDef</em></span> 
420object. They are based on the HepRep standard described at
421<a href="http://www.slac.stanford.edu/~perl/heprep/" target="_top">
422http://www.slac.stanford.edu/~perl/heprep/
423</a>.
424Geant4 also provides an <span class="emphasis"><em>G4AttDefStore</em></span>.
425</p><p>
426Geant4 provides some default examples of the use of this
427facility in the trajectory classes in /source/tracking such as
428<span class="emphasis"><em>G4Trajectory</em></span>, <span class="emphasis"><em>G4SmoothTrajectory</em></span>.
429<span class="emphasis"><em>G4Trajectory::CreateAttValues</em></span> shows how
430<span class="emphasis"><em>G4AttValue</em></span> objects can be made and
431<span class="emphasis"><em>G4Trajectory::GetAttDefs</em></span> shows how
432to make the corresponding <span class="emphasis"><em>G4AttDef</em></span> objects and use the
433<span class="emphasis"><em>G4AttDefStore</em></span>. Note that the "user" of CreateAttValues
434guarantees to destroy them; this is a way of allowing creation on
435demand and leaving the <span class="emphasis"><em>G4Trajectory</em></span> object, for example,
436free of such objects in memory. The comments in
437<span class="emphasis"><em>G4VTrajectory.hh</em></span> explain further and additional insights
438might be obtained by looking at two methods which use them, namely
439<span class="emphasis"><em>G4VTrajectory::DrawTrajectory</em></span> and
440<span class="emphasis"><em>G4VTrajectory::ShowTrajectory</em></span>.
441</p><p>
442Hits classes in examples /extended/analysis/A01 and
443/extended/runAndEvent/RE01 show how to do the same for your hits.
444The base class no-action methods CreateAttValues and GetAttDefs
445should be overridden in your concrete class. The comments in
446<span class="emphasis"><em>G4VHit.hh</em></span> explain further.
447</p><p>
448In addition, the user is free to add a
449<span class="emphasis"><em>G4std::vector&lt;G4AttValue&gt;*</em></span> and a
450<span class="emphasis"><em>G4std::vector&lt;G4AttDef&gt;*</em></span> to a
451<span class="emphasis"><em>G4VisAttributes</em></span> object as could, for example,
452be used by a <span class="emphasis"><em>G4LogicalVolume</em></span> object.
453</p><p>
454At the time of writing, only the HepRep graphics systems are
455capable of displaying the G4AttValue information, but this
456information will become useful for all Geant4 visualization systems
457through improvements in release 8.1 or later.
458</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch08s05.html"><img src="AllResources/IconsGIF/prev.gif" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ch08.html"><img src="AllResources/IconsGIF/up.gif" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch08s07.html"><img src="AllResources/IconsGIF/next.gif" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">8.5. 
459Controlling Visualization from Compiled Code
460 </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="AllResources/IconsGIF/home.gif" alt="Home"></a></td><td width="40%" align="right" valign="top"> 8.7. 
461Enhanced Trajectory Drawing
462</td></tr></table></div></body></html>
Note: See TracBrowser for help on using the repository browser.