DAWN logo
Geant4 Visualization Tutorial using the DAWN Event Display

Introduction

This tutorial is designed for anyone 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:

When you run Geant4 visualization using

   /vis/open DAWNFILE
Your output comes in a graphics file in a format called .prim 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).

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 produced your own .prim file, this might be a good time to do so.

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

The commands to generate a .prim file from a typical example such as example A01 are:

  $G4BIN/A01app
  /vis/open DAWNFILE
  /vis/drawVolume 
  /vis/viewer/flush
  /vis/scene/add/trajectories
  /vis/scene/add/hits
  /run/beamOn 1
At the first "/vis/viewer/flush", a .prim file is produced that contains only detector geometry.
At the "/run/beamOn 1", a second .prim file is produced that contains geometry plus trajectories and hits. This file is produced because the "/run/beamOn" automatically does a "/vis/viewer/flush".

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

This tutorial assumes you have already done a basic Geant4 installation. If you need help with that, see the Geant4 Installation Guides.

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 Mac

Use the Tcl/Tk prebuild disk image from:

Select Mac OS X (Universal) and follow the prompts for standard Mac DMG installation.

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 on Mac

This step is not necessary on the Mac. Appropriate tools are already included in the X11 part of XCode.

Installing gsview and ghostscript on Linux/Unix

Use the gstools source code from:

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

   gtar zxf /path/to/ghostscript-8.54-gpl.tar.gz

You will also need gsview-4.8-1.i386.rpm (obtain and unpack the same way)

Installing gsview and ghostscript on Windows

Use the gstools source code from:

Obtain and run the self-extracting gs854w32-gpls.exe

Obtain and run the self-extracting gsv48w32.exe

Installing DAWN on Mac

Use the DAWN source code from the main DAWN repository:

The file will automatically unzip in your download area as:

   dawn_3_90b.tar

Double click on the file and it will untar to become a directory:

   dawn_3_90b

Move this directory to your Applications directory.

In a Terminal window, cd to this directory and run make:

   cd /Applications/dawn_3_90b
   make clean
   make guiclean
   make

You should then see a file called simply "dawn".

Last step is to put the DAWN directory into your command path, using something like:

  export PATH=/Applications/dawn_3_90b:$PATH$
DAWN is ready to run.

Installing DAWN on Linux

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

Use the DAWN source code from the main DAWN repository:

Unzip and Untar the file:

   tar -zxvf dawn_3_90b.taz

You should then have a directory called dawn_3_90b.

Proceed as follows:

   cd dawn_3_90b
   make clean
   make guiclean
   make

You should then see a file called simply "dawn".

Last step is to put the DAWN directory into your command path, using something like:

  export PATH=<my_dawn_directory>:$PATH$
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:

   tar -zxvf WinDAWN385cBin.taz

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/Mac 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:

   tar -zxvf primdata.taz

You will now have a subdirectory called PRIM_DATA.

Last step is to put the DAWN directory into your command path, using something like:

  set PATH=<my_dawn_directory>;$PATH$
DAWN is ready to run.

If you have any problems running DAWN on Windows, it may be that your pre-existing command path contains some conflicting code. Try simplifying your path to something like:

  set PATH=;C:\program files\gstools\gsview;C:\Tcl\bin;C:\WINNT\system32;C:\WINNT;C:\WINNT\System32\Wbem;c:\program files\dawn;

Running DAWN

The executable is in the directory "dawn_3_90b" (Linux/Mac) 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.90b...
***************************************


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

and the DAWN window should appear:

  • The DAWN GUI has problems on recent Windows versions. It crashes on startup. We are currently waiting for a fixed version, but for now there is no workaround.
  • 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".
  • 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.

    Speeding Up DAWN for Very Complex PRIM Files

    If your prim file is very complex, you may find that DAWN's performance is distressingly slow. This can make it very time consuming to find the best view angle.

    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:
      $G4BIN/A01app
      /vis/open DAWNFILE
      /vis/drawVolume
      /vis/viewer/flush
      /vis/scene/add/trajectories
      /vis/scene/add/hits
      /run/beamOn 1
    

    Further Resources

    Documents in this Visualization Tutorial Set:

    Other Resources:


    Tutorial by:
    Joseph Perl
    DAWN is by:
    Satoshi Tanaka

    30 December 2010