DAWN logo
Geant4 Workshop Visualization Tutorial using the DAWN Event Display

Introduction

This tutorial has been updated for use at the October 2003 Fermilab Geant4 Tutorial, but is also designed for use by anyone else who wants to learn DAWN Visualization for Geant4.

This tutorial can be used on its own, but gives the most comprehensive introduction to Geant4 visualization when used as part of the following full set of documents:

The basic Geant 4 Tutorial had users run a basic Geant 4 job contained in 

   geant4/source/examples/extended/analysis/A01
This job produced various kinds of output including a graphics file in a format called a .heprep file suitable for viewing with the WIRED event display. A one line change to that job will allow you to produce graphics files of a different format suitable for viewing with the DAWN Event Display. This visualization tutorial will show you how to use the DAWN Event Display to view that file (or an equivalent file included with this tutorial - see details later).

Rerun the A01 example as follows: 

../bin/$G4SYSTEM/A01app
/vis/open DAWNFILE
/vis/scene/create
/vis/scene/add/volume
/vis/sceneHandler/attach
/vis/viewer/flush
/vis/scene/add/trajectories
/vis/scene/add/hits
/tracking/storeTrajectory 1
/run/beamOn 1
You will then find that you have created two ".prim" files suitable for viewing in DAWN.

DAWN's full name is "Fukui Renderer DAWN (Drawer for Academic WritiNgs)". It was created by Satoshi Tanaka as a vectorized 3D PostScript processor with analytical hidden line/surface removal intended for precise technical drawing of complicated objects. Designed specifically for Geant4, DAWN calculates all visible parts of the 3D data before drawing and then produces device-independent vectorized graphics for high quality technical applications.

DAWN is a C++ application that in turn relies on the Tcl/Tk control language and gui toolkit. DAWN sends output for viewing either to a PostScript file, or directly to a PostScript viewer, or to an OpenGL viewer. Since the purpose of this tutorial is just to give you a quick feel for the power of DAWN, this tutorial will focus on just one of those modes, the easiest one to set up, sending output to a PostScript file. For information on the other modes, and for more complete and up to date information on other DAWN topics, see the DAWN Home Page at:
http://geant4.kek.jp/~tanaka/DAWN/About_DAWN.html

The .prim File

DAWN's input is something called a .prim file. The .prim file is a plain text file format that contains a full 3D description of what is to be drawn (geometry, trajectories, hits, markers - depending on what you chose to add from Geant4) plus visualization attributes (such as color and linestyle).

You don't really need to understand the details of the .prim file format to use DAWN, but in case you are interested:

The .prim file format is fairly easy to understand just by looking at it. Here are some lines from one example: 

##G4.PRIM-FORMAT-2.4

##### List of primitives 1 #####
/BoundingBox -1.0  -1.0 -5.0   8.0  4.0  6.0
!SetCamera
!OpenDevice 
!BeginModeling

# Box
/Origin   0.0  0.0  0.0 
/ColorRGB 1.0  0.0  0.0 
/Box 0.5  2.0  4.5 

# Column
/Origin   4.0  0.0  0.0 
/ColorRGB 0.0  1.0  0.0 
/Ndiv 50
/Column 1.5  2.0 

# Trd
/Origin   0.0  0.0  0.0 
/ColorRGB 0.0  1.0  1.0 
/Origin   7.0  0.0  0.0 
/Trd      1 0.5 1 0.5 4 

# Cone segment
/Origin   1.0  5.0  0.0 
/ColorRGB 0.0  1.0  1.0

If you have not yet run the A01 tutorial, this might be a good time to do so. You will then have a file called:
geant4\examples\extended\analysis\A01\g4_01.prim

You can also skip running Geant4 for now and instead find a copy of this file here.

The commands from that example that generated the .prim file were: 

../bin/$G4SYSTEM/A01app
/vis/open DAWNFILE
/vis/scene/create
/vis/scene/add/volume
/vis/sceneHandler/attach
/vis/viewer/flush
/vis/scene/add/trajectories
/vis/scene/add/hits
/tracking/storeTrajectory 1
/run/beamOn 1

The output appears as soon as the /run/beamOn is complete since an update command is included in this example's RunAction class. If you run some other example and find that the event doesn't draw automatically at the end of the run, just issue the following command: 
   /vis/viewer/flush

You can even put this command into a macro file and then cause this macro to be called at the end of each event by adding the macro name to the run command, as in: 
   /run/beamOn 1 my.mac

Other commands that might be useful are discussed in this document's section called Further Resources. Ignore any commands related to setting camera views, lighting or surface style. Those commands are only relevant to an immediate visualization driver such as OpenGL. When you work with a driver such as DAWN that has a 3D file format, you set these things later, from the visualizaton application, DAWN.

Installation

Before continuing with this DAWN tutorial, make sure you have the following underlying software:

Free versions of Tcl/Tk and gsview are available.

Installing Tcl/Tk on Linux/Unix

Use the Tcl/Tk source code from:

The download is a tar-gzipped archive. Unzip and Untar it as follows; 

   gtar zxf /path/to/ActiveTcl-download.tar.gz

Run ActiveTcl-linux/install.sh, which will select between a GUI or text-based installer. It uses the GUI version when it can connect to a display (requires local X installation).

After installation, make sure that the path to the installed executables is placed on your path. (Thanks to the ActiveState company for these instructions.)

Installing Tcl/Tk on Windows

Use the Tcl/Tk source code from:

The download is a self-extracting and installing executable. It is also a ZIP file should you choose to unzip it.

Run the install.bat to install ActiveTcl. On Windows 95/98/ME, ActiveTcl will not place the tclsh and wish on your path, although it will associate .tcl files to wish.

If the ActiveTcl installer complains that it cannot find the ActiveTcl package when trying to run, it is likely that the TCL_LIBRARY variable is set in your environment (the Ruby language does this, for example). This is an unnecessary setting, and should be removed. Windows 9* users can remove the entry from their 'autoexec.bat' file, and Windows NT/2000/XP users can remove it from the Environment Settings (right click on "My Computer"; select "Properties", go to the "Advanced" tab and select "Environment Variables..."). Windows 9* users may have to reboot to force the system to recognize the change in settings. Otherwise, just restart the Explorer or DOS shell and run the self-extracting executable again. (Thanks to the ActiveState company for these instructions.)

Installing gsview and ghostscript Linux/Unix

Use the gstools source code from:

Start by reading the Readme.htm file in ghostscript-8.11.tar.gz.

The download is a tar-gzipped archive. Unzip and Untar it as follows; 

   gtar zxf /path/to/ghostscript-8.11.tar.gz

You will also need ghostscript-fonts-std-8.11.tar.gz (obtain and unpack the same way)

You will also need gsview-4.4.i386.tar.gz (obtain and unpack the same way)

Installing gsview and ghostscript on Windows

Use the gstools source code from:

Obtain and run the self-extracting gs811w32.exe

Obtain and run the self-extracting gsv44w32.exe

Installing DAWN on Linux/Unix

You will need a C++ compiler and a make utility to proceed on this platform.

Use the DAWN source code from:

Unzip and Untar the file: 

   gunzip dawn_3_85e.taz
   tar -xvf dawn_3_85e.tar

You should then have a directory called dawn_3_85e. Proceed as follows: 

   cd dawn_3_85e
   make clean
   make guiclean
   make

You should then see a file called simply "DAWN". DAWN is ready to run.

Installing DAWN on Windows

DAWN is available for Windows as a precompiled binary. There is no need to compile.

Use the DAWN Windows binary from:

Unzip and untar the file: 

   gunzip WinDAWN385cBin.taz
   tar -xvf WinDAWN385cBin.tar

You should then have a directory called WinDAWN385cBin. This contains the executable, dawn.exe, and some related files.

Windows users need to add one more file to that directory (already included in the Linux/Unix version). Get the file prim1.prim from here.

Finally, add some more example prim files into your WinDAWN385cBin directory as follows. Take the file primdata.taz from here and insert it into your WinDAWN385cBin directory. Then unzip and untar the file: 

   gunzip WinDAWN385cBin.taz
   tar -xvf WinDAWN385cBin.tar

You will now have a subdirectory called PRIM_DATA.
DAWN is ready to run.

Running DAWN

The executable is in the directory "dawn_3_85e" (Linux/Unix) or "WinDAWN385cBin" (Windows).
Set a command window to that directory and then run DAWN on a simple prim file example by typing: 
   dawn prim1.prim

The console should respond with: 

perl@noric10 $ dawn prim1.prim

***************************************
          Fukui  Renderer
              DAWN
 (Drawer for Academic WritiNgs)
 ver 3.85...
***************************************


***** g4.prim viewer mode (default)
***** ("dawn -h" for help)

and the DAWN window should appear:

  • Note that DAWN remembers parameter settings and GUI settings from one session to the next, so the next time you start DAWN, the GUI may look a little different from what you see above (depending on how you had things when you last exited DAWN).
  • The DAWN GUI has several different "pages". To change from one page to another, use the arrow buttons from the second line of the GUI:
  • The three other pages are as follows:


  • For a first example, just go to page 4 and change "Device Selection" to "Eps":
  • Also on page 4 is an area where you can indicate your preferred "PostScript Previewer". DAWN will know how to automatically bring up new images in your PostScript viewer if you fill this in with the name of the command that you use to view PostScript, such as "gv". If you instead leave this blank, then DAWN will still generate PostScript output, but you will have to run the PostScript viewer by hand to actually view that file.
  • Then from the top left corner of any page, select "OK".
  • A file should be created with the name "prim1.eps".
  • If you specified a valid "PostSript Previewer" on page 4, your PostScript viewer will automatically run. Otherwise, just start it by hand, typing something like:
    gv prim1.eps
  • You should then see the DAWN image:
  • Remember that DAWN remembers your settings from one session to the next. This means that until you tell it otherwise, it will continue come up showing page 4 and will continue to use the "Device Selection" of "Eps".
  • Start DAWN again: 
       dawn prim1.prim
  • Go to the DAWN GUI's page 1 and change the "Viewing Mode" to "Surface":
  • Then from the top left corner of any page, select "OK".
  • A new file should be created with the same name as before, "prim1.eps".
  • If you specified a valid "PostSript Previewer" on page 4, your PostScript viewer will automatically run. Otherwise, just start it by hand, typing something like:
    gv prim1.eps
  • You should then see the previous DAWN image as surfaces rather than wireframe:
  • Start DAWN again, and this time try making a change on the lighting control page, page 2. Specifically, change the "Light Direction" "Polar" angle from its prevous value of 13 to a new value of 54.5.
  • The light that previous shone from the front will now shine from the top. We show here just how the sphere part of the picture looks in the two different ligthing setups:
  • This first prim file we've been using is really to simple to showcase DAWN's powerful drawing abilities. Many more prim data examples are in the PRIM_DATA subdirectory.
  • For example, try: 
       dawn PRIMDATA/pixel_cut0100.prim
    Let the "Lighting Direction" "Polar" angle back to 13, and hit "OK".
    Because this is a large prim file, DAWN will take a few minutes to process during which you will see console messages such as: 
     ***** 250  primitive are processed
 ***** 500  primitive are processed
 ***** 750  primitive are processed
 ***** 1000  primitive are processed
 ***** 1250  primitive are processed

--------------------------------------------------------------------------------

 upto OBJECT 1414 "POLYHEDRON":  Eliminating hidden parts of facets ...
--------------------------------------------------------------------------------

  ****** upto OBJECT 1414: 500 polygons are processed  ( 9 % )
  ****** upto OBJECT 1414: 1000 polygons are processed  ( 19 % )
  ****** upto OBJECT 1414: 1500 polygons are processed  ( 29 % )
  ****** upto OBJECT 1414: 2000 polygons are processed  ( 39 % )
  ****** upto OBJECT 1414: 2500 polygons are processed  ( 49 % )
  ****** upto OBJECT 1414: 3000 polygons are processed  ( 59 % )
  ****** upto OBJECT 1414: 3500 polygons are processed  ( 69 % )
  • Eventually, you will see the message: 
       ***** PostScript file "PRIM_DATA/pixel_cut0100.eps" is created.
  • The resulting EPS file looks like:
  • And here is a good time to discuss the important fact that this DAWN image is Vector graphics (not bitmapped graphics). As a result, you will find that if you use your PostScript viewer's zoom feature, the image will remain sharp and full of detail no matter how you zoom:
  • Now that you have some basic familiarity with DAWN, use it to view the prim file that you created during the previous tutorial when you ran Geant4's A01 example. You should have a file called:
    geant4\examples\extended\analysis\A01\g4_01.prim

    Or, if you skipped running Geant4 for now, you can instead find a copy of this file here.

  • Run DAWN on this file: 
       dawn g4_01.prim
  • Go to the DAWN GUI's page 1 and select "Load Default".
  • On the same page, change "Camera Angle"..."Polar" to 60 (the slider will get you close, or you can type in a specific number to clicking on the existing polar angle and then typing your new value).
  • You should end up with an image as follows:
  • DAWN has many more options that you can best learn by playing around. If you get into trouble (for example, bad values for "Camera Distance" can cause a crash), use the DAWN GUI's page 1 button "Load Default" to get back to a stable configuration.
  • This tutorial has only scratched the surface of DAWN. Its purpose was to give you a brief, hands on introduction to this powerful tool and to encourage you to further explore its abilities. Not only have we neglected many of the features in the DAWN GUI, but we have also neglected the many other modes in which it can be run (direct to XWindows, receiving prim files via sockets from other running applications, etc). A large range of problems involving very high quality technical rendering can be solved by DAWN.

    Recap of Geant4 Commands Used in this Tutorial

    If you need to quickly repeat the commands to generate the .prim file, it may be helpful to cut and paste a set of commands from this list: 
    ../bin/$G4SYSTEM/A01app
/vis/open DAWNFILE
/vis/scene/create
/vis/scene/add/volume
/vis/sceneHandler/attach
/vis/viewer/flush
/vis/scene/add/trajectories
/vis/scene/add/hits
/tracking/storeTrajectory 1
/run/beamOn 1

    Further Resources

    Tutorial by:
    Joseph Perl
    DAWN is by:
    Satoshi Tanaka

    14 October 2003