==============================================================
DAVID version 1.36a
September 20, 2005
Satoshi Tanaka and Kunihiro Hashimoto
Department of Information Science,
Ritsumeikan University, Japan
Information:
http://geant4.kek.jp/~tanaka/DAWN/About_DAVID.html
Download version 1.36a
===============================================================
[0] What's new?
(Version 1.35a) May 30, 2005
* Ported to g++ 3.X
(Version 1.34a) October 6, 1999
* Improvement of reliability removing too delicate warnings
between /Tubs /Cons and /Column.
(Max-Min tests in R-direction are improved.)
(Version 1.33a) October 5, 1999
* Improvement of reliability removing too delicate warnings
between /Tubs /Cons, /Trd, /Column, and /Box.
(Max-Min tests in Z-direction are improved.)
(Version 1.32a) October 4, 1999
* Improvement of reliability removing too delicate warnings
for /Tubs vs /Tubs
(Version 1.31a)
* Improvement of reliability removing too delicate warnings.
(Version 1.20a)
* VRML 2.0 visualization is supported, which supports
interactive displaying of shape names
(physical-volume names in Geant4 terminology),
customization of transparency, etc.
* The default value of tolerance is tuned to 1.0e-3.
(In the old version, it was 1.0e-6.)
[1] Introduction: What is DAVID?
DAVID (DAwn's Visual Intersection Debugger) is a visual tool to investigate
polygon intersection of shapes (physical volumes in Geant4 terminology)
described in a DAWN-format (g4.prim-format) file.
Details of the DAWN format are described at the following place:
http://geant4.kek.jp/~tanaka/DAWN/G4PRIM_FORMAT_24
DAVID reads a DAWN-format file given as an argument and outputs
the following two files.
(1) File "g4david.log" in which detailed information of intersection are
described
(2) File "g4david.prim" (DAWN format file) in the DAWN mode,
or file "g4david.wrl" (VRML 2.0 format file) in the VRML mode.
The file "g4david.prim" or "g4david.wrl" describes a 3D scene
with intersected shapes highlighted.
The default is the DAWN mode.
Switching of modes is done by setting the environmental variable
DAVID_OUT_MODE to either "DAWN" or "VRML".
For details, see "[7] Customization" of this document.
When intersection of shapes is detected, DAVID can visualize
the output file "g4david.prim" or "g4david.wrl" with its proper viewer
automatically. For details, see "[7] Customization" of this document.
You can obtain many kinds of excellent VRML viewers for free.
You can also obtain Fukui Renderer DAWN at the following place.
http://geant4.kek.jp/~tanaka/DAWN/About_DAWN.html
ftp://i1nws2.fuis.fukui-u.ac.jp/pub/graphics/fukui_graphics_system/
[2] Compilation, Test, and Installation at UNIX platform
(2-1) Compilation
For compilation of DAVID, select a proper Makefile for your machine
from Makefile.VENDER_COMPILER's.
The default Makefile with no extension is a copy of
Makefile.GNU_g++, which is available at Linux machines etc.
The DAVID package includes the following Makefile's:
Makefile.COMPAQ_cxx, Makefile.GNU_g++, Makefile.HP_aCC,
Makefile.HP_CC , Makefile.IBM_xlC, Makefile.SGI_CC
Makefile.SUN_CC
The procedure of compilation is as follows:
(1) % gzip -dc david_1_20a.taz | tar xvf -
(2) % cd david_1_20a
(3) % make -f Makefile.VENDER_COMPILER
(4) % ls -F david
(Please check if a binary file named "david" is created.)
(2-2) Test (Tutorial of DAVID)
Please perform the following test before going on to installation.
In order to perform the test, Fukui Renderer DAWN should be
installed beforehand. DAWN is used to visualize highlighted shapes.
You can obtain DAWN from our ftp site or home page (see above).
You can test the compiled executable binary "david" as follows
and can see how DAVID works to investigate intersection of shapes.
Note that the following description is based on DAWN
after version 3.40a, released May 9, 1998.
(1) Go to the directory "david_1_20a/TESTDATA" and initialize
camera parameters of DAWN.
% cd TESTDATA
% dawn -c
The latter deletes DAWN's parameter-history files ".DAWN.history"
and ".DAWN.default".
(2) Set an environmental variable "DAVID_DAWN_PVNAME" to 1:
% setenv DAVID_DAWN_PVNAME 1
This makes DAWN visualize names of intersected shapes.
You can skip this process if you need not visualize the shape names.
(Names of intersected shapes are also output to a file "g4david.log".
See below.)
(3) Invoke david with an argument "david_boxes.prim":
% ../david david_boxes.prim
(4) See if DAWN's GUI panel is invoked. If so, DAWN is invoked properly
reading the file "g4david.prim", which is generated by DAVID
automatically.
You may skip (5) --- (10), in the second trial of this tutorial,
if all viewing parameters remain unchanged.
(5) Go to page 1 of the DAWN's GUI panel.
(6) Click the "Load Default" button.
This process set rendering parameters of DAWN to default values.
(7) On the DAWN's GUI panel, select "Surface" for the "viewing mode" menu.
This makes DAWN visualize non-intersected shapes with their surfaces
and with light gray color, and intersected shapes with forced
wire frame style and with the highlight color (red).
You can skip this process. Then the visualized 3D view may
look different.
(8) On the DAWN's GUI panel, set "Display Parameters and Axes" to "Yes".
This makes DAWN visualize coordinate axes and camera parameters.
You can skip this process, too.
(9) On the DAWN's GUI panel, set camera parameters on GUI if necessary.
You can skip this process, too.
(10) Go to page 4 of the DAWN's GUI panel, and select "EPS" in the menu of
the "Device Selection".
This make DAWN generate a EPS file, "g4david.eps",
and invoke ghostview automatically to visualize it.
In ghostview, you can enlarge a part of the view by clicking the part.
which may be useful for you to read the displayed shape names.
You can skip this process, too.
(11) On the DAWN's GUI panel, click the "OK" button.
(12) Then a 3D scene is visualized by DAWN.
Confirm the followings:
(a) Two of three boxes, named Box1 and Box2, are highlighted
with "red color" and with forced wireframe style.
These two boxes are "intersected" with each other.
(b) The remaining one box is visualized with gray and with surfaces.
(13) Exit from ghostview. Then you exit from DAWN, too.
(14) See if "g4david.log" is generated properly:
% cat g4david.log
.....
!!! INTERSECTED VOLUMES !!!
Box1: Box: line 17
Box2: Box: line 25
Here in the second line, "Box1" is the shape name,
"Box" is the shape type, and "line 17" is the line where
Box1 is described in the data file "david_boxes.prim".
(15) Go back to (3), and try other DAWN-format files in TESTDATA/
directory if you wish.
(2-3) Installation
(1) Edit "INSTALL_DIR" macro of your selected Makefile.
Its default value is "/usr/local/bin".
(2) Here, you may have to become a root user:
% su
(3) Type as follows:
% make install
Then the binary file "david" is copied to the directory
INSTALL_DIR specified in (1).
[3] Compilation, Test, and Installation at Windows NT/98 platform
DAVID can be compiled with Microsoft VC++ 5.0 with Service Pack 3 and
VC++ 6.0. You should install WinDAWN (Windows version of DAWN) beforehand:
http://geant4.kek.jp/~tanaka/DAWN/About_DAWN.html
(3-1) Compilation and installation
(0) Defrost the tar-gzip file david_1_20a.taz with WinZip etc.
Then you obtain a directory named "david_1_20a"
where sources and sample data files are placed.
(1) Open the MS-DOS window, and go to the directory "david_1_20a".
DOS> cd david_1_20a
(2) Set up configurations for VC++ by executing the batch file
"vcvars32.bat" included in the "bin" directory of VC++:
DOS> C:\Progra~1\Micros~1\VC98\bin\vcvars32.bat
(3) Execute the configuration batch file "config_vc.bat"
to generate the Makefile for VC++ \nmake:
DOS> config_vc.bat
(4) Invoke VC++ nmake:
DOS> nmake
Then the executable david.exe is created.
(5) Execute the batch file for installation:
DOS> david_install.bat
Then the executable "david.exe" is copied to
the directory, C:\Program Files\DAWN
If this directory does not exist, it is automatically created.
(6) Set the PATH variable to C:\Program Files\DAWN.
For example, add the following line to "autoexec.bat" and reboot
the PC:
SET PATH=%PATH%;C:\Progra~1\DAWN
This step should be able to be skipped, if you have already installed
DAWN.
(3-2) Test (Tutorial of DAVID)
See section (2-2)
[4] Usages
You can invoke DAVID as follows:
% david input_file.prim
Example:
% david david_boxes.prim
[5] Supported shapes
The following shapes defined in the DAWN format
are supported at present:
Box, Column, Cons, Parallelepiped, Sphere, Trd, Trap, Tubs
For details of the DAWN format, see G4PRIM_FORMAT_24.tex
included in DAWN package or go to the following page:
http://geant4.kek.jp/~tanaka/DAWN/G4PRIM_FORMAT_24
DAVID recognizes a special comment line of the form,
#/PVName shape_name
as a shape name. The argument "shape_name" is assigned to a shape
which appears first after the special comment line.
For example, the following lines define a box with name "MyBox" and a
Tubs with name "MyTubes":
#/PVName MyBox
.... (color, coordinate, etc) ...
/Box 1 1 1
....
#/PVName MyTubs
.... (color, coordinate, etc) ...
/Tubs 0.5 1.0 1.0 0.0 3.0
Once a shape name is assigned to a shape, this shape name is consumed.
If no shape name is assigned for a shape,
the default shape name "NONAME" is assigned automatically.
[6] Usage with Geant4
Geant4 is the detector simulator for high energy physics.
For details, see the following page:
http://wwwinfo.cern.ch/asd/geant/geant4.html (Geant4 Home Page at CERN)
http://geant4.kek.jp/GEANT4/index.html(Geant4 Home Page at KEK)
http://geant4.kek.jp/~tanaka(Geant4 Fukui University Group Home Page at KEK)
The current version of DAVID supports the following shapes defined in the
DAWN format.
Box, Column, Cons, Parallelepiped, Sphere, Trd, Trap, Tubs
It means that the following Geant4 shapes are supported:
G4Box, G4Cons, G4Para, G4Sphere, G4Trd, G4Trap, G4Tubs
(As for G4Sphere, only a full sphere is supported by DAVID.)
It is quite easy to use DAVID with Geant4. All you have to do is
to install DAVID and DAWN and perform visualization using the Geant4
DAWNFILE visualization driver.
How to use DAVID with Geant4 is as follows:
(0) Install DAVID and Fukui Renderer DAWN.
Also, you have to compile Geant4 with setting environmental
variables as follows:
% setenv G4VIS_BUILD_DAWNFILE_DRIVER 1
% setenv G4VIS_USE_DAWNFILE 1
The former is necessary when you build Geant4 libraries,
and the latter is necessary when you compile your Geant4
executables.
(1) Set an environmental variable to switch the viewer for
the Geant4 DAWNFILE visualization from the default one
(DAWN) to DAVID:
% setenv G4DAWNFILE_VIEWER david
(2) Visualize the detector geometry with the Geant4 DAWNFILE visualization
driver. For example, do as follows:
% my_geant4
PreInit> /run/initialize
Idle > /vis/scene/create
Idle > /vis/sceneHandler/create DAWNFILE
Idle > /vis/viewer/create
Idle > /vis/refresh/view
Then Geant4 dose the followings:
(a) Geant4 generates a file "g4.prim", where the detector geometry
is described with the DAWN format.
(b) Geant4 invokes DAVID and makes it read the file g4.prim.
Then the visual intersection debugging with DAVID and DAWN is
performed for the detector geometry. Namely, intersected parts
are detected and visualized with highlighted color (red, by default).
You can repeat the same intersection debugging by invoking DAVID
by hand:
% david g4.prim
(3) Read detailed informations on the intersection described in the output
log file "g4david.log". Shape names described there have the following
form:
PhysicalVolumeName.CopyNumber.
For example, a physical volume with name "exp_Hall" and
with copy number "0" is assigned the following shape name:
exp_Hall.0
which is described in the file g4.prim as
#/PVName exp_Hall.0
(4) The 3D scene with intersected shapes highlighted
is saved to a DAWN-format file "g4david.prim".
You can re-visualize it by invoking DAWN by hand:
% dawn g4david.prim
[7] Customization
You can customize DAVID with environmental variables. See below.
(1) Tolerance (IMPORTANT!!!)
DAVID does not warn intersection if it is within the value of
"tolerance". The default value of the tolerance is 1.0e-3.
(WARNING: In DAVID version 1.00a, the default value was 1.0e-6.)
You can customize this value by setting an environmental variable
as follows:
% setenv DAVID_EPSILON_3D tolerance
For example,
% setenv DAVID_EPSILON_3D 1.0e-6
(2) Customization of precision in polygonizing a curve (IMPORTANT!!!)
DAVID decomposes a curved surface into 3D polygons and investigates
intersection of each polygon with other shapes. This causes finite
discretization errors to some extent.
But the precision of the decomposition is customizable.
One way of the customization is to use the Geant4 visualization
command, if you are using DAVID to debug Geant4 geometry.
The following command can reset the precision:
Idle> /vis/set/sides Ndiv
where "Ndiv" is an integer number greater than or equal to 3.
If this command is executed, the value of "Ndiv" is stored in the
Geant4 output file, "g4.prim", to be investigated by DAVID.
Then, reading the file, DAVID decomposes 2*pi radian
(a closed curved surface) into Ndiv number of 3D polygons.
The default value of "Ndiv" is 24.
The value of "Ndiv" is also customizable by editing the DAVID's
input file (g4.prim in case of Geant4 visualization) directly.
For example, if you want to change the value of "Ndiv" from
the default 24 into 48, edit the line,
/Ndiv 24
which is just after the line "!BeginModeling", to
/Ndiv 48
If this line does not exist, DAVID assumes that "Ndiv" is 24.
(3) Selection of output mode (NEW!!!)
DAVID supports two modes of outputting 3D data for visually
highlighting intersected shapes.
Switching of the output modes can be done by setting an
environmental variable "DAVID_OUT_MODE" as follows:
(a) DAWN mode (default):
The following setting makes DAVID output the DAWN-format file,
"g4david.prim" and the log file "g4david.log".
% setenv DAVID_OUT_MODE DAWN
In this case, by default, Fukui Renderer DAWN is automatically
invoked to visualize the output file "g4david.prim".
If you want to use a different DAWN-format file viewer,
set an additional environmental variable as follows:
% setenv DAVID_DAWN_VIEWER viewer_name
Of course the command path to the viewer should be properly set.
If you want to skip visualization, set the environmental variable
as follows:
% setenv DAVID_DAWN_VIEWER NONE
In this case, the files "g4david.prim" and "g4david.log" are
generated, but visualization of "g4david.prim" is skipped.
(b) VRML mode:
The following setting makes DAVID output the VRML 2.0 format file,
"g4david.wrl" and the log file "g4david.log".
% setenv DAVID_OUT_MODE VRML
By default no VRML viewer is invoked automatically.
In order to make a VRML viewer invoked automatically to visualize
the file "g4david.wrl", set an additional environmental variable
as follows:
% setenv DAVID_VRML_VIEWER viewer_name
Of course the command path to the VRML viewer should be
properly set.
The default setting in which visualization is skipped is
equivalent to set the environmental variable as follows:
% setenv DAVID_VRML_VIEWER NONE
In this case, the files "g4david.wrl" and "g4david.log" are
generated, but visualization of "g4david.wrl" is skipped.
In the VRML visualization of DAVID, back faces are culled.
(4) Customization of transparency
(a) In DAWN mode:
Not supported.
(b) In VRML mode:
In VRML mode, the 3D shapes are made half-transparent in the
output file "g4david.wrl". The ratio of transparency is
customizable as follows:
% setenv DAVID_VRML_PV_TRANSPARENCY t
% setenv DAVID_VRML_IPV_TRANSPARENCY t
where t is a real value between 0 and 1.
The default value of t is 0.5.
The environmental variable
"DAVID_PV_TRANSPARENCY" is for non-intersected shapes,
while "DAVID_IPV_TRANSPARENCY" is for intersected
shapes.
If the value of DAVID_VRML_PV_TRANSPARENCY is 1, i.e.
in the case of full transparency,
data of the non-intersected 3D shapes are NOT generated into
the file "g4david.wrl", and so they are not visualized at all.
Data for intersected shapes are always output into the file
"g4david.wrl", even if the value of DAVID_VRML_IPV_TRANSPARENCY
is 1 and so they are fully transparent.
(5) Displaying shape names
DAVID supports a function of displaying shape names in visualization.
(a) In DAWN mode:
In the DAWN mode, names of intersected shapes are displayed
if an environmental variable is set as follows:
% setenv DAVID_DAWN_PVNAME 1
The font size is fixed to 8 pixels (8 pt on printed-out figures
on paper). This size may be too small on a laptop PC.
We recommend that you display shape names with EPS mode
of DAWN in which ghostview is invoked and so you can enlarge
the displayed shape names.
The default setting is equivalent to setting the environmental
variable as
% setenv DAVID_DAWN_PVNAME 0
for which shape names are not displayed.
(b) In VRML mode:
In VRML mode, displaying shape names can be done interactively:
A name of of a mouse-focused shape is displayed using the
"Anchor" node of the VRML 2.0 format.
(Your VRML 2.0 viewer should support visualization of
"description" field of the "Anchor" node.)
Note that this function is made inactive in the default setting.
In order to make this function active, set the environmental
variable as follows:
% setenv DAVID_VRML_PV_PICKABLE 1
The default setting is equivalent to setting this environmental
variable as
% setenv DAVID_VRML_PV_PICKABLE 0
for which shape names cannot be displayed.
The setting of DAVID_VRML_PV_PICKABLE effects on both
intersected and non-intersected shapes.
For complicated 3D scenes, it is a effective to use this function
together with the above mentioned customization of transparency.
Setting the environmental variable as
% setenv DAVID_VRML_PV_TRANSPARENCY 1.0
makes all non-intersected shapes culled from the scene,
which reduces pickable shapes, and simplify your analysis
and navigation in the scene.
(6) Customization of highlight color.
By default, intersected shapes are visually highlighted with red color.
Setting the following set of environmental variables customize
the highlight color:
% setenv DAVID_HIGHLIGHT_COLOR_R r
% setenv DAVID_HIGHLIGHT_COLOR_G g
% setenv DAVID_HIGHLIGHT_COLOR_G b
where r, g, b are real values between 0 and 1.
For example, the followings make the highlight color green:
% setenv DAVID_HIGHLIGHT_COLOR_R 0.0
% setenv DAVID_HIGHLIGHT_COLOR_G 1.0
% setenv DAVID_HIGHLIGHT_COLOR_G 0.0
Note that you have to set all the three environmental variables
to make the customization effective.
Also note that these setting is ignored in the rainbow-color option
explained below.
(7) Rainbow-color option
You can use the rainbow-color option by setting an environmental
variable as follows:
% setenv DAVID_RAINBOW_FLAG 1
In this option, different highlight colors are assigned to shapes
depending on how many times the shapes are intersected:
Number of Intersection for a shape and its assigned color:
0 gray
1 red
2 green
3 blue
4 magenta
5 cyan
>=6 yellow
For example, try the following:
% cd david_1_20a/TESTDATA
% setenv DAVID_RAINBOW_FLAG 1
% ../david david_rainbow.prim
(Note: The visualization may take some time with the X and EPS
modes of DAWN. You can perform visualization much faster
with the OpenGL mode. The menu is in the Page 4 of the
DAWN's GUI panel. )
In order to switch off this option, set the environmental variable
as follows:
% setenv DAVID_RAINBOW_FLAG 0
Enjoy!
======= end of README =========