source: trunk/documents/UserDoc/UsersGuides/ForApplicationDeveloper/html/Visualization/attributes.html @ 1231

Last change on this file since 1231 was 1208, checked in by garnier, 15 years ago

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