//////////////////////////////////////////////////
/////  Fukui Renderer                        /////
/////  DAWN (Drawer for Academic WritiNgs)   /////
/////                                        /////
//////////////////////////////////////////////////

              Authors:
                 Satoshi   Tanaka    (Ritsumeikan University (Rits), JAPAN)
                 Minato    Kawaguti  (Fukui University, JAPAN)
                 Hiroshi   Hasui     (Fukui University, JAPAN)
                 Yoshitaka Kawabata  (Fukui University, JAPAN)
                 Takeshi   Konya     (Fukui University, JAPAN)
                 Tetsuji   Nishimura (Fukui University, JAPAN)
                 Masahiro  Noguchi   (Fukui University, JAPAN)
                 Kensuke   Ohtubo    (Fukui University, JAPAN)
                 Yasuhide  Sawada    (Fukui University, JAPAN)
                 Masayasu  Kawabata  (Fukui University, JAPAN)                 

               E-mail:
                 stanaka@media.ritsumei.ac.jp

               Download:
               http://geant4.kek.jp/~tanaka
               (File name: dawn_VERSION.tar.gz (Linux/Unix), 
                           WinDAWNVersion      (Windows) )
                                   

 What's new? 





<< What is DAWN? >>

  Fukui  Renderer   DAWN (Drawer for Academic WritiNgs) 
  is a renderer, which reads 3D geometrical data and visualize them.  
  It is a vectorized 3D PostScript processor with analytical 
  hidden line/surface removal. 
  It aims at precise technical drawing of complicated objects.  
  It performs geometrical hidden line/surface removal and calculates 
  out all visible parts of the 3D data before drawing.  This drawing 
  algorithm realizes device-independent technical high quality of
  vectorized graphics.
    3D Data files should be generated by a modeler or by hands 
  separately.  If you use DAWN as a visualizer of, 
  say, a simulator of physical experiments, 
  the simulator application itself is recognized as a modeler.
    An important feature of DAWN is that
  it has been developed to visualize 3D data generated by
  a high-energy experimental detector simulator "GEANT4" 
  ( http://geant4.web.cern.ch/geant4 , http://geant4.kek.jp ).  

<< Platform >>

  In order to use DAWN, the following softwares and libraries 
  should be installed beforehand.

  (1) Linux/UNIX with X-Window or Windows XP/2000/NT/98 
  (2) Tcl/Tk 
      ( http://dev.scriptics.com/software/tcltk )
  (3) Ghostscript, Ghostview
      ( http://www.cs.wisc.edu/~ghost/index.html )
  (4) OpenGL or Mesa  (optional)
      ( http://www.mesa3d.org )
      
<< How to compile and install DAWN in Linux/UNIX >>

  In order to compile DAWN, you need a C++ compiler 
  and  "make" utility for it. 

  Decompose the DAWN parckage dawn_VERSION.tar.gz, 
  go to the directory "dawn_VERSION", 
  and do the followings.

  (Case 1) In case you want to use OpenGL/Mesa:

           % make clean
           % make guiclean
           % configure 
            (* Answer all questions properly.)
           % make 

  (Case 2) In case you do NOT want to use OpenGL/Mesa, 
           and only want to use X-Window and 
           PostScript-file-generation modes:

           % make clean
           % make guiclean
           % configure_xwin 
            (* Answer all questions properly.)
           % make 

  (Case 3) In case you want to use neither OpenGL, X Window, ghostscript, 
           nor socket connection, 
           and are only interested in viewing generated EPS files with your 
           PostScript-file viewer, do the followings:

           % make clean
           % make guiclean
           % configure_min
             (* Answer all questions properly.)
           % make 

           Also, before executing DAWN, set the environmental
           variable "DAWN_PS_PREVIEWER" to the name of your 
           PostScript-file viewer:

           % setenv DAWN_PS_PREVIEWER "viewer_name"

           In the Linux/Unix version of DAWN, the default value of the 
           DAWN_PS_PREVIEWER is "gv".  
           Set this variable to "NONE" if you want to skip previewing:

           % setenv DAWN_PS_PREVIEWER "NONE"

  In all the above cases, "make" generates executable files 
  "dawn" and "DAWN_GUI_menu".  
  You need both of them for executing DAWN.
  The former is the DAWN executable and the latter is the 
  Tcl/Tk script for GUI. 
  
  Next, do "make install". (You may have to become root beforehand.)

            % make install

  Then "dawn",  "DAWN_GUI_menu",
  and shell scripts "dawninetd", "dawn_unixd" are 
  installed (copied) to the directory specified 
  in executing the configure script.

  You can test your compiled DAWN before performing the installation. 
  See below.

<< How to compile DAWN in Windows XP/2000/NT/98/Me >>

 You can compile and install DAWN with Microsoft Visual C++ version 6.0.

 Once installed,  DAWN can be invoked either from DOS or 
 Cygnus windows ( http://sources.redhat.com/cygwin ). 
 How to compile and install DAWN is as follows.

 (0) Install Visual C++ 6.0, and set the PATH environmental variable to
     its "bin" directory, e.g. 
     "C:\Program Files\Microsoft Visual Studio\VC98\Bin".
     (For Windows XP/2000/NT, use control panel (system). 
      For Windows 98/Me, add a proper description for the PATH variable
      to "c:\autoexec.bat".)

 (1) Install Tcl/Tk for Windows /XP/2000/NT/98/Me.
     Check if the window shell name is "wish.exe".
     (You can obtain Tcl/Tk from the following site:  
      http://dev.scriptics.com/software/tcltk )

 (2) Install your favorite PostScript viewer.
     We recommend to install Gsview, which also needs Ghostscript,  
     (You can obtain GSview and Ghostscript from the following site:  
      http://www.cs.wisc.edu/~ghost/index.html        )

 (3) Make the PATH variable include the path of the directory 
     where the Tcl/Tk window shell "wish.exe" is placed. 
     By default, the directory is "c:\tcl\bin".
     Similarly, set the path to the PostScript viewer.  
     In case of Gsview, set the path to the directory where 
     "gsview32.exe" is placed.

 (4) Open DOS Window

 (5) DOS> cd dawn_VERSION

 (6) DOC> config_vc.bat

 (7) Execute vcvars32.bat placed in the "bin" directory of Visual C++, e.g.,
     DOS> vcvars32.bat

 (8) DOS> nmake

 (9) DOS> dawn_install.bat
     (DAWN is installed into "C:\Program Files\DAWN". 
      You CANNOT change the place.)

 (10) Reboot PC

 You can obtain the executable binary package from 
 our ftp site.

<< How to test DAWN >>

  In order to test DAWN, go to the directory 
  "dawn_VERSION/PRIM_DATA": 

   % cd dawn_VERSION/PRIM_DATA

  In PRIM_DATA, there are several g4.prim-format test data 
  files with an extension ".prim".  You can visualize 
  each data file with DAWN.  For example:

     % ../dawn  primitives.prim 
     % ../dawn  primitives2.prim 

  Files  "primitives.prim"  and "primitives2.prim" display 
  all kinds of 3D primitives which are visualizable by DAWN. 
  Try other data files, too.  Some of them are generated by GEANT4.

  Note: 
    A suitable camera distance is different 
    in each data.  We recommend to use the "AUTO"
    mode by simply giving a value "0" to the 
    Camera Distance entry (the top entry of the GUI menu).
    
<< X-event handling>>

  In visualization of the X-window and OpenGL modes, the following 
  mouth operations are available on DAWN windows:
  
  Middle Button: A new DAWN window.
  Right Button : Terminate the DAWN window.  

<< Data file format: g4.prim format >>

  The "g4.prim format", which has been developed for GEANT4 visualization, 
  is described in  "dawn_VERSION/DOC/G4PRIM_FORMAT.tex".
  There are sample data files in the directory  dawn_VERSION/PRIM_DATA.
  A g4.prim-format data file can be visualized as follows: 

    % dawn [option(s)] filename

<< Supported options >>

 The following options are supported:

    -d: Skip invoking GUI menu, and use the 
        previous parameter stored in a file
        ".DAWN_1.history" in the current directory 
        (see "History mechanism" below). 
    -g: inter-process-communication mode 
        (Unix domain (named pipe) used by dawnunixd)
    -G: inter-process-communication mode 
        (INET domain, used by dawninetd)
    -h: Help
    -t: swap on/off of forceible wireframe attribute 
        assigned to each 3D primitive
    -v: g4.prim-format-viewer mode (default)

<< History mechanism >>

   DAWN remembers parameters (camera distance etc) used
   in the previous execution, and display them on GUI panel as the 
   initial values. The parameters are stored in ".DAWN_1.history"
   in the current directory.  File ".DAWN_1.default"
   stores default parameters.  Contents of these files 
   can be different in different directories, i.e., 
   in different kinds of works.

<< How to customize DAWN with environmental variables >>

  DAWN can be customized by setting proper environmental variables.
  See the file "dawn_VERSION/DOC/CUSTOMIZE" for the variations.   
  You can edit (, rename) and source the file CUSTOMIZE 
  for your own customization.  Default values for the environmental 
  variables are also described there.  

<< Visualization of g4.prim-format data >>

  DAWN can visualize the so-called "g4.prim-format" data.
  This data format is developed for efficient visualization of 
  GEANT4 simulation.  
  Details of the g4.prim format is described in 
  "dawn_VERSION/DOC/G4PRIM_FORMAT_XX.tex".
  In the dawn_VERSION/PRIM_DATA directory, 
  there are several g4.prim-format test 
  data files with an extension ".prim".  
  You can visualize each data file with DAWN:

      % cd dawn_VERSION/PRIM_DATA
      % dawn  filename

<< Inter-process visualization >>

  DAWN can also read g4.prim-format data by receiving them 
  from other process.  The process can be either 
  in the same host or in a remote host.
  That is to say, DAWN supports "remote graphics".
  There are several ways to visualize g4.prim-format data
  sent via inter-process communication.

  Before performing the following test, compile the test program
  "g4test_inet" and "g4test_unix" and go to the directory PRIM_DATA.

     % cd dawn_VERSION
     % make g4test_inet
     % make g4test_unix
     % cd PRIM_DATA

  (Way 1)  You can use daemon mode in INET domain.
           By default, hostname is automatically set to
           the local host name.
           The default port number is "40701".
           If a selected port is already in use,
           the port number is automatically incremented 
           one by one up to 40710.

          ===== Example =====
           % dawninetd 

           And in a different window,

           % g4test_inet filename

  (Way 2)  You can use daemon mode in INET domain,
           and run g4test_inet at a remote host.

           Hostname is set by setting the environmental 
           variable "G4DAWN_HOST_NAME".
           The default port number is "40701"
           If a selected port is already in use,
           the port number is automatically incremented 
           one by one upto 40710.

         ===== Example =====
         DAWN        Host (Local ) : i1dec2.fuis.fukui-u.ac.jp
         g4test_inet Host (Remote) : cernsp.cern.ch

         ------------ DAWN Host  -----------
         i1dec2 % dawninetd
      
         ------------ g4test_inet Host ------------
         cernsp % setenv G4DAWN_HOST_NAME i1dec2.fuis.fukui-u.ac.jp
         cernsp % g4test_inet filename.prim

  (Way 3) If your system supports Unix domain connection,
          i.e., named pipe connection,
	      you can use daemon mode of Unix domain.
          Sun path is "FR_TMP3".

          ===== Example =====
           % dawnunixd

           And in a different window,

           % g4test_unix filename


<< Drawing edges >>

  Sharp drawing of edges is one of the most characteristic 
  features of DAWN. 
  At rendering time, DAWN automatically distinguishes 
  (1) ordinary edges, (2) auxiliary edges, and (3) outline edges. 

   (1) The "ordinary edge" is a line segment formed between
       two facets, whose normal vector makes an angle greater
       than a given threshold angle.

   (2) The "auxiliary edge" is a line segment formed between
       two facets, whose normal vector makes an angle smaller 
       than a given threshold angle.

   (3) The "outline edge" means a line segment formed between
       two facets, one of which is shows its front face to camera and 
       the other shows its back face.

  The threshold angle can be given on the GUI panel. 
  Its default value is 70.0 degrees.
  Each kind of edge can be assigned different style and width on 
  the GUI panel.  

<< Associated Tools >> 

   We are developing tools to assist DAWN users.
   It is included in dawn_XXX/TOOLS.
   You can use them by invoking make there:

   % cd dawn_XXX/TOOLS
   % make

   Note that you have to install the tools by hands, e.g.,

   % cp dawn_epsclipper /usr/local/bin

   Tools included in dawn_XXX/TOOLS are:
     (A) DAWN EPS clipper: This tool clips EPS figures generated 
                           by DAWN with a given rectangle.
     (B) dawn_eps2ps       : This tool convert EPS file to PS file.

   For details, read dawn_XXX/TOOLS/README.

<< Copy right>>

  The copy right belongs to Satoshi Tanaka.
  He cannot be responsible for any kinds of damages 
  caused by DAWN.

=============== END of README ===============