5 * Revision 1.1.1.1 1995/10/24 10:20:18 cernlib
9 #include "geant321/pilot.h"
10 #if defined(CERNLIB_DOC)
11 *CMZ : 3.21/02 29/03/94 15.41.25 by S.Giani
14 ************************************************************************
16 * Introduction to the Drawing package *
17 * ----------------------------------- *
20 * THE DRAWING PACKAGE *
22 * The drawing package has been designed mainly to: *
24 * - draw the detector *
25 * - draw the detector geometrical tree *
26 * - draw particle trajectories *
29 * DRAWING THE DETECTOR *
31 * The detector can be looked at from any view point and with any *
32 * scale factor (GDRAW, GDRVOL); appropriate attributes can be set in *
33 * order to see only selected objects (so avoiding messy pictures); *
34 * hidden line removal is available as well as surface shading. *
35 * 'Cut' views, i.e. intersections of a given plane with the *
36 * detector, can also be displayed (GDRAWC, GDRAWX). This feature is *
37 * very useful to see internal details that the routine GDRAW would *
39 * When hidden line removal is used, the possibility exists to cut *
40 * the volume to be drawn with various shapes, to visualise the inner *
43 * DRAWING THE GEOMETRICAL TREE *
45 * The geometrical tree (GDTREE) is a representation of the overall *
46 * structure of the detector, namely the mother-daughter relationship *
47 * among the various objects composing it. Several types of *
48 * additional information are available on request: multiplicity of a *
49 * given volume (i.e. how many times it is positioned in other *
50 * places, or number of subdivisions), detector nature, visibility *
51 * flag, etc. This drawing tree capability can be very useful when *
52 * tuning the detector geometry. If used interactively, this *
53 * facility allow to invoke via a click of the mouse the GDSPEC *
54 * utility (see below) for any node of the tree. *
56 * DRAWING THE GEOMETRICAL SPECIFICATIONS *
58 * The geometrical specifications (GDSPEC) give a detailed picture *
59 * of one particular piece of the detector. Three drawings of the *
60 * volume (a projection view and two cut views), its shape type and *
61 * numerical parameters (i.e. dimensions), and a scale to aid *
62 * geometric calculations, are presented together in a single *
63 * graphics frame. The set of geometrical specifications of all the *
64 * descendants of a given node on the tree, can easily be obtained *
65 * with the routine GDFSPC. *
67 * DRAWING PARTICLE TRAJECTORIES *
69 * The tracks generated by the tracking package, and stored in the *
70 * data structure JXYZ, can be easily drawn with the routine GDXYZ. *
71 * The names of the particles and/or the track numbers can be drawn *
73 * Four types of representations are used to display the classes of *
74 * particles, with different colour and line style: *
76 * - red solid lines for charged particles (GTELEC, GTHADR) *
77 * - green dashed lines for muons (GTMUON) *
78 * - black blank/dotted lines for neutral particles (GTNEUT) *
79 * - blue dotted lines for gammas (GTGAMA) *
81 * A special routine has been provided to display the tracks online *
82 * (GDCXYZ), if called under the DEBUG/SWITCH control from GUSTEP. *
83 * That routine shows the tracks exactly at the same time they are *
84 * trasorted by the tracking package of GEANT3, giving so a useful *
85 * interactive debugging tool. *
89 * The hits generated by the tracking package and stored in the *
90 * data structure JHITS, can be displayed by the hits routines, *
91 * with different functionality: *
93 * - draw one hit (GDAHIT); called by user routines *
94 * - draw all the hits of trajectory type sets/detectors (GDHITS) *
95 * - draw all the hits of calorimeter type sets/detectors (GDCHIT) *
97 * Different symbols for every subdetector can be used, chosen among *
98 * hardware characters (dots), software crosses, or from the HPLOT *
99 * table of software characters. The size of the software characters *
100 * and crosses is given as an argument to GDAHIT/GDHITS, while it is *
101 * computed as a function of the hits value in GDCHIT. *
105 * The basic detector drawing routines (GDRAW, GDRAWC, GDRAWX) have *
106 * to scan the data structure JVOLUM repeatedly. When the detector *
107 * is described in a very detailed way, the time spent in the *
108 * interpretation of the JVOLUM bank and in the 3D transformations *
109 * can increase dramatically. For a detector with more than 100 *
110 * different volume names, for example, this time can reach real time *
111 * minutes on some machines, whereas the specific time required just *
112 * by the drawing would be only a few seconds. If the hidden line *
113 * removal option is active, this time can reach several minutes and *
114 * even hours, depending on the speed of the machine and the *
115 * complexity of the drawing requested. *
116 * In order to alleviate this problem the 'bank-mode' routines have *
117 * been developed. The basic idea is to separate the interpretation *
118 * (i.e. the JVOLUM scanning to convert the 3D geometry structure *
119 * into a set of 2D lines) from the drawing itself. In this way, the *
120 * interpretation is performed only once and all the 2D information *
121 * is stored in view banks (data structure JDRAW) [DRAW 399]. These *
122 * views can then be looked at in a quicker way, having only to draw *
123 * all 2D vectors previously stored. For a detector with more than *
124 * 100 different volume names, for example, this is achieved at the *
125 * cost of only a few thousand words of memory for each view bank. *
126 * One can therefore open a view bank (GDOPEN), identified by a *
127 * number, perform appropriate drawings (only interpretation will be *
128 * made, of course), close the bank (GDCLOS) and finally look at the *
129 * picture stored in it (GDSHOW). When a view bank has been closed *
130 * it cannot be modified anymore, but it can be displayed as many *
131 * times as wanted (GDSHOW) or deleted (GDELET). *
135 * The user can control some drawing options (GDOPT), by selecting *
136 * for instance to have either parallel or perspective projection, *
137 * either Y-Z or R-Z projection, hidden line removal, surface *
139 * There is a routine (GDZOOM) that, if called, applies a zoom to *
140 * everything (volumes, tracks, hits, etc.) will be drawn from then. *
141 * This feature, in conjunction with the interactive command MEASURE *
142 * [XINT 110], can be used for detailed viewing. *
143 * Another tool that could help in the interactive debugging or *
144 * tuning of the detector geometry is the routine GEDITV [DRAW 600], *
145 * by which it is possible to modify interactively some geometrical *
146 * parameters set by the user routines defining the detector *
148 * It is possible to draw the axes of the 3D MAster Reference System *
149 * (GDAXIS) oriented in agreement with the current view point. *
150 * Two other routines draw a scale (GDSCAL) or a profile of a man *
151 * (GDMAN) in 2D user coordinates to give an idea of the dimensions *
152 * within current scale factors. A 2D text (GDRAWT) using software *
153 * characters (hardware characters should be implemented later on), *
154 * 2D vectors (GDRAWV) or a frame header (GDHEAD) are also available. *
155 * Attributes like colour (GDCOL) and line width (GDLW) can be *
156 * globally set for all 2D drawings (i.e. text, vectors, man, etc.); *
157 * they are overridden in 3D drawings by volume attributes set by the *
158 * GSATT routine with 'COLO' or 'LWID' option. *
159 * A graphics input is available (GDCURS) to fetch the 2D user *
160 * coordinates of the graphics cursor on the screen, allowing an *
161 * immediate user interface with the interactive version of GEANT3. *
162 * In particular there are interactive commands to zoom, measure, *
163 * pick tracks or hits points that make use of that routine. *
164 * Various conversions from 3D to 3D, and 3D to 2D coordinates are *
165 * performed by GDFR3D and GD3D3D. *
167 * BASIC AND ADVANCED GRAPHICS *
169 * The underlying graphics system is completely hidden from the *
170 * GEANT program. All graphics call are made via the HIGZ package. *
171 * Various implementations of the HIGZ package are available, notably *
172 * for X11, GKS, DI3000 and, shortly, PHIGS. *
174 * RUNNING INSTRUCTIONS *
176 * Thanks to the HIGZ package, it is possible to produce postscript *
177 * metafiles from the drawings. When the GKS implementation of HIGZ *
178 * is used, the possibility is there to produce also a GKS metafile. *
182 * The drawing package is initialized by (in the order): *
183 * IGINIT to initialize the HIGZ package and the underlying basic *
184 * graphics software *
185 * GDINIT to initialize the GEANT drawing package *
187 * Main drawing routines are: *
188 * GDRAW to draw a projection view of the detector *
189 * GDRVOL to draw a projection view of the detector *
190 * GDRAWC to draw a cut view of the detector (along one axis) *
191 * GDRAWX to draw a cut view of the detector (from any point) *
192 * GDXYZ to draw tracks at the end of the event *
193 * GDCXYZ to draw tracks while the event is running *
194 * GDPART to draw particle names and track numbers on tracks *
195 * GDAHIT to draw one single hit *
196 * GDHITS to draw hits for trajectory type detectors *
197 * GDCHIT to draw hits for calorimeter type detectors *
199 * Routines that show how the detector has been modeled are: *
200 * GDTREE to draw a picture with the geometrical tree *
201 * GDSPEC to draw a picture with volume specifications *
202 * GDFSPC to draw several GDSPEC pictures *
204 * Routines that perform control operations on view banks are: *
205 * GDOPEN to open a given view bank, identified by a view number; *
206 * in this way we enter in bank-mode *
207 * GDCLOS to close current view bank, i.e. the last one opened, *
208 * and restore screen-mode *
209 * GDSHOW to show all graphics information contained in a given *
211 * GDELET to delete a given view bank from memory *
213 * Other routines are: *
214 * GDOPT to set drawing options *
215 * GDZOOM to set the zoom parameters *
216 * GDAXIS to draw the axes of the MARS, oriented according *
217 * to the current view parameters *
218 * GDSCAL to draw the current scale *
219 * GDMAN to draw a profile of a man (or a woman) at the current *
221 * GDRAWT to draw text, with software characters *
222 * GDRAWV to draw polylines in 2D user coordinates *
223 * GDHEAD to draw a frame header *
224 * GDCOL to set colour code *
225 * GDLW to set line width *
226 * GDCURS to have an input from the graphics cursor *
227 * GDFR3D to convert from 3D coordinates (either in MARS or DRS) *
228 * to 2D user coordinates *
229 * GD3D3D to convert from 3D MARS coordinates to 3D Projection *
230 * Reference System coordinates. *
232 * Labelled COMMON blocks related to section DRAW *
233 * ---------------------------------------------- *
235 * COMMON/GCDRAW/NUMNOD,MAXNOD,NUMND1,LEVVER,LEVHOR,MAXV,IPICK, *
236 * + MLEVV,MLEVH,NWCUT,JNAM,JMOT,JXON,JBRO,JDUP,JSCA,JDVM,JPSM, *
237 * + JNAM1,JMOT1,JXON1,JBRO1,JDUP1,JSCA1,JULEV,JVLEV, *
239 * + GRMAT0(10),GTRAN0(3),IDRNUM,GSIN(41),GCOS(41),SINPSI,COSPSI, *
240 * + GTHETA,GPHI,GPSI,GU0,GV0,GSCU,GSCV,NGVIEW, *
241 * + ICUTFL,ICUT,CTHETA,CPHI,DCUT,NSURF,ISURF, *
242 * + GZUA,GZVA,GZUB,GZVB,GZUC,GZVC,PLTRNX,PLTRNY, *
243 * + LINATT,LINATP,ITXATT,ITHRZ,IPRJ,DPERS,ITR3D,IPKHIT,IOBJ,LINBUF, *
244 * + MAXGU,MORGU,MAXGS,MORGS,MAXTU,MORTU,MAXTS,MORTS, *
245 * + IGU,IGS,ITU,ITS,NKVIEW,IDVIEW, *
246 * + NOPEN,IGMR,IPIONS,ITRKOP,IHIDEN, *
249 * NUMNOD number of nodes in non-optimized tree *
250 * MAXNOD max. number of nodes of non-optimized tree. *
251 * NUMND1 number of nodes in optimized tree *
252 * LEVVER vertical level in the tree currently scanned *
253 * LEVHOR horizontal node in the tree currently scanned *
254 * MAXV max vertical levels in the tree to be scanned *
255 * IPICK node selected by GDTREE *
256 * MLEVV number of vertical levels in the last tree scanned *
257 * MLEVH number of horizontal nodes in the last tree scanned *
258 * NWCUT max. workspace allocated by cut routines *
259 * JNAM-JVLEV pointers used by the tree routines *
260 * LOOKTB colour look-up table, LOOKTB(I)=I,I=1,16 *
261 * GRMAT0 rotation matrix saved by GDRVOL *
262 * GTRAN0 translation matrix saved by GDRVOL *
263 * IDRNUM flag for GDRAW, set to 1 when called by GDRVOL *
265 * GCOS cosine table *
266 * SINPSI SIN(GPSI*DEGRAD) *
267 * COSPSI COS(GPSI DEGRAD) *
268 * GTHETA Theta angle of the parallel projection of 3-D images *
269 * GPHI Phi angle of the parallel projection of 3-D images *
270 * GPSI Psi angle of rotation of the image on the screen *
271 * GU0 U position (X in screen coordinates) of the origin *
272 * GV0 V position (Y in screen coordinates) of the origin *
273 * GSCU scale factor for the U screen coordinate *
274 * GSCV scale factor for the V screen coordinate *
275 * NGVIEW flag for GDFR3D and GD3D3D if view point has changed *
276 * ICUTFL flag for GDRAW if it was called by cut routines *
277 * ICUT axis along which the cut is performed *
278 * CTHETA Theta angle of cut supplied to GDRAWX *
279 * CPHI Phi angle of cut supplied to GDRAWX *
280 * DCUT coordinate value at which the cut is performed *
281 * NSURF number of surfaces stored in SURF *
282 * ISURF pointer for array SURF *
283 * GZUA zoom parameter (horizontal scale factor) *
284 * GZVA zoom parameter (vertical scale factor) *
285 * GZUB zoom parameter *
286 * GZVB zoom parameter *
287 * GZUC zoom parameter *
288 * GZVC zoom parameter *
289 * PLTRNX screen and plotter X range *
290 * PLTRNY screen and plotter Y range *
291 * LINATT current line attributes *
292 * LINATP permanent line attributes *
293 * ITXATT current text attributes *
294 * ITHRZ string containing the status of THRZ option *
295 * IPRJ string containing the status of PROJ option *
296 * DPERS distance from the origin for perspective view *
297 * ITR3D track being scanned *
298 * IPKHIT flag for GPHITS, if>0 then print only hit number *
299 * IOBJ type of the object being drawn *
300 * LINBUF flag for GDRAWV if line buffering is active *
301 * MAXGU current physical number of words for graphic unit banks *
302 * MORGU number of words to be pushed in graphic unit banks *
303 * MAXGS current physical number of words for graphic segment banks *
304 * MORGS number of words to be pushed in graphic segment banks *
305 * MAXTU current physical number of words for text unit banks *
306 * MORTU number of words to be pushed in text unit banks *
307 * MAXTS current physical number of words for text segment banks *
308 * MORTS number of words to be pushed in text segment banks *
309 * IGU pointer to current graphic unit bank *
310 * IGS pointer to current graphic segment bank *
311 * ITU pointer to current text unit bank *
312 * ITS pointer to current text segment bank *
313 * NKVIEW number of view data banks *
314 * IGVIEW current view bank number or 0 for screen *
318 * ITRKOP status of TRAK option of GDOPT *
319 * DDUMMY array of dummy words *
323 * The View data structure JDRAW *
324 * ----------------------------- *
326 * NKVIEW Number of views *
327 * IVIEW Current view selected *
328 * IGU Current graphic unit pointer *
329 * MAXGU Number of graphic units *
330 * MORGU Number of words to push in graphic unit bank *
331 * IGS Current graphic segment pointer *
332 * MAXGS Number of graphic segments *
333 * MORGS Number of words to push in graphic segment bank *
334 * ITU Current text unit pointer *
335 * MAXTU Number of text units *
336 * MORTU Number of words to push in text unit bank *
337 * ITS Current text segment pointer *
338 * MAXTS Number of text segments *
339 * MORTS Number of words to push in text segment bank *
340 * LENGU Array containing: lengths for each graphic unit + LINATT *
341 * (line attributes) *
342 * ADDGU Array containing addresses for each graphic unit *
343 * ADDTU Array containing addresses for each text unit *
344 * X Array containing u-coordinates of graphic segments *
345 * Y Array containing v-coordinates of graphic segments *
346 * ICUT Cut axis (1,2,3 or 0 if no cut) of the view *
347 * LINWID Text line width + ITXATT (text attributes) *
348 * GTHETA, GPHI, GPSI, GU0, GV0, GSCU, GSCV, are the viewing *
349 * parameters stored in /GCDRAW/. *
350 * U0, V0, SIZE, ANGLE, IOPT, ITEXT have the same meaning of those *
351 * given as parameters in HPLSOF or GDRAWT routines. *
352 * A control word is stored in Q(JDRAW+IVIEW), to identify the view *
353 * banks among three classes: *
355 * =1 for empty banks (created just to avoid gaps) or for deleted *
357 * =2 for all previously created banks (i.e. opened); *
358 * =3 for protected banks (all banks that can't be deleted by the *
359 * user with GDELET, because reserved for internal use). *
363 * NKVIEW IVIEW v NKVIEW *
364 * ........................................ *
365 * | | | | | Control words | *
366 * ........................................ *
368 * | JV = LQ(JDRAW-IVIEW) *
370 * ............................................................ *
371 * | | | | | | | |igu,maxgu,morgu,igs,maxgs,morgs,itu,maxtu, | *
372 * | | | | | | | | mortu,its,maxts,morts,gtheta,gphi, | *
373 * | | | | | | | | gpsi,gu0,gv0,gscu,gscv,-,-,icut | *
374 * ............................................................ *
376 * | | | | | | JV1 = LQ(JV-1) *
377 * | | | | | v MAXGU *
378 * | | | | |.................................................. *
379 * | | | | || | lengu(1) | .... | lengu(igu) | .... | lengu(mgu) *
380 * | | | | |.................................................. *
382 * | | | | | JV2 = LQ(JV-2) *
384 * | | | |.................................................... *
385 * | | | || | addgu(1) | ..... | addgu(igu) | ..... | addgu(mgu) *
386 * | | | |.................................................... *
388 * | | | | JV3 = LQ(JV-3) *
390 * | | |...................................................... *
391 * | | || | addtu(1) | ...... | addtu(itu) | ...... | addtu(mtu) *
392 * | | |...................................................... *
394 * | | | JV4 = LQ(JV-4) *
396 * | |........................................................ *
397 * | || | x(1) | ...... | x(igs) | ...... | x(mgs) | *
398 * | |........................................................ *
400 * | | JV5 = LQ(JV-5) *
402 * |.......................................................... *
403 * || | y(1) | ...... | y(igs) | ...... | y(mgs) | *
404 * |.......................................................... *
408 * ............................................................ *
409 * | |u0(1)|v0(1)|size(1)|angle(1)|linwid(1)|iopt(1)|itext(1)|nchar(1)|.*
410 * ............................................................ *
412 ************************************************************************