GGE; GEANT4 Geometry Editor


2003 Feb. 22
Hajime YOSHIDA
Naruto University of Education

1) Overview


GGE, or GEANT4 Geometry Editor, is a visual tool to "create" a detector geometry of GEANT4. It generates a complete C++ class code for a relatively simple geometry. It is written in Java and runs on any platform running Java.

Java Web Start version is also supported. If user has installed Java Web Start, GGE(or as a part of MOMO) can be started directly from the web browser without typing java command on the console.

Characteristics

  1. It provides users with tables into which users can fill with their detector parameters.
  2. Using the data in the tables, even if they are partial and imcomplete, GGE can generate C++ source codes for a detector.
    The class name must be supplied to get C++ source code.
  3. When a user uses default functions of GGE, C++ codes generated by GGE is a complete description of a detector, including the definition of atoms, materials, solids, color attributes, logical volumes and physical volumes with rotations and translations.
  4. The C++ source codes are saved into files and can be compiled to make a GEANT4 executable.
  5. When GGE is used together with MOMO, an integrated environment, a minimum set of user mandatory classes can be generated. MOMO also generate the main program as well as GNU makefile for the GEANT4 to visualise the detector.
  6. GAG is helpful to run Geant4 and to visualise the whole detector. Simple macro files are associated, too, for visualisation.
GGE consists of two editors (material and volume) which are interrelated. Volume editor provides Single Positioned Volume, with incremental copy numbers (translational arrangement or axially symmetric arrangement), and Replicas (in any axis).

Tips!

  1. GGE is based on Java's MVC model, or Swing so that any change or input to the tables by a user are automatically reflected to the internal data structure of GGE and C++ codes. This is true at any moment, so that user can get even imcomplete C++ class files at any moment, even without any filled tabular cells)
  2. The whole detector description can be saved in a persistent file and can be loaded for later reuse.
  3. GGE employs own naming rules to generate C++ codes from the tables.

2) Functionalities of GGE

GGE has a top panel on which are placed menu buttons and fill-in text area.

Top menus

Tables


GGE has several tables on two "tabbed panes"; one pane for the material editor and another for the volumes editor. By clicking the tab, user can switch between both tables.

2.1) The Material Editor


The material editor is composed of two tables for
  1. "material from scratch" and
  2. "compound materials".
These tables can be enlengthened as will. The boundary of the two tables can be moved as will, too.

Every row represents a material.
The periodic table is popped up to the window, when "append" or "insert" a material button is pushed. The foundamental properties of atoms; Z, A, etc. are built in to the atomic table and are copied appropriately. The atomic table can be hidden by a menu button on its top.


Functionalities of the Material Editor


The functionalities implemented in this version are following;
  1. append, insert, edit and delete a material
    • material from scratch
      The name of an atom, numbers Z and A are taken from the atomic table. User has to specify its density, temperature and pressure. Canonical units and states can be choosen from the lists.
      The corresponding instance in C++ is named "elementX", where "X" represents element's symbol.
    • material by combination (number or fractional ratios).
      User has to type in the name of a compound material, its density etc.. A pop-up window is displayed when he focuses on a cell specifying composition.
    • periodic table of atoms automatically popped up to create a material. User can select upto eight atoms to specify a compound material.
    • default states (and their canonical names) and values are provided (material state, temperature, pressure).
    • canonical physical units of GEANT4 are shown in selectable combo-boxes.
  2. "in Use" mark for materials used in user's detector.
    • materials used in the logical volumes are automatically checked as "in Use" state.
    • user can add any materials "in Use" to have C++ constructors, even when they aren't used in logical volumes.
  3. input and output from/to persistent material file
    Material tables are saved to a Java's persistent file and can be reused.
    • load, append or save a material file
    • an exemplary persistent material database file "MaterialDB.g4mt" from the PDG
Not yet implemented are; material from materials, isotope and protection from duplicated "in Use" instances of the same materials.

2.2) The Volume Editor ; logical and physical volumes


The volume editor is composed of two major editors;
  1. logical volume editor and
  2. physical volume editors,
each is placed in the main scrollable panel. Physical editor is composed of five tables for physical volumes. They are placed on tabbed panes.

Functionalities to define Geant4 logical volumes

Following functionaliteis are implemented;

  1. Selecting a G4Solid
    All Geant4 solids can be selected from the solid list.
    • all CSG solids; box, tube segment, cone segment, symmetric trapezoid, sphere segment, parallel piped, torus segment, HYPE,
    • BREP solids; PolyCone segment and Polygone segment @@
    After selecting a solid tyle, user pushes the "append" or "insert" button in order to make a new row in the table. On focusing the "solid" cell, a pop up window appears for the specified solid. User can
    • specify parameters and canonical units of CSG solids
    • specify any number of nodes and facets with parameters and canonical units of BREP solids
    • preview with DAWN with automatically chosen world size
    • save DAWN format file of the specified solid
  2. Defining G4Color, or colour attributes, using a graphical color chooser from which RGB numbers are taken to generate C++ codes.
    Each color is given unique name and is listed in the editor panel.
  3. Defining G4LogicalVolumes
    Each row of the logical vulume table represents a G4LogicalVolume. User can append, insert or delete a row with corresponding buttons.
    The table has following columns;
    • The first column is to specify the name of the logical volume.
    • The second column is filled automatically by choosing a selectable G4Solid. Focusing on it allows user to edit its parameters and preview with DAWN.
    • The third column is type-in cell for material name listed in the material editor. (drag and drop is planned)
    • The fourth column is to specify the visualization attribute's name
  4. "Make the used materials" button.
    Clicking this button examins the materials specified in the logical volume table and marks "in Use" cell (the first one ) of the material tables accordingly. Note that only rows marked "in Use" are used to generate C++ codes.

Functionalities to define Physical volumes


Compared with the logical volume editor, the physical volume one has limited generality. So, if user aren't satisfied with the following simplistic way to place logical volumes, he can use partially generated C++ codes for logical volumes etc..

Constructors of G4PVPlacement
Following four types of constructor are implemented, according to the type of rotation and type of the mother volume.

  1. Type 1 constructor = rotation of the frame, physical mother volume
  2. Type 2 constructor = rotation of a body, physical mother volume
  3. Type 3 constructor = rotation of the frame, logical mother volume
  4. Type 4 constructor = rotation of a body, logical mother volume
Following simple placements are provided in GGE.
  1. Single Positioned Volume (SPV)
    Each row represents a physical volume. The world volume must be defined in the first row of this table.
    1. The first column specifies either body or frame rotation.
    2. The second column specofies the instance's name of the physical volume
    3. The third column specifies the name of the logical volume to be placed
    4. The fourth column specifies the type of the mother volume. The mother volume is either null(Master Reference System), logical or physical. The MARS or the world volume must be specified at the first row.
    5. The fifth column specifies the name of the mother volume, if it isn't NULL.
    6. The columns 7, 8 and 9-th specify the translation in the X, Y or Z direction (default is no translation) with a selectable unit of length
    7. The 11-th column specifies the axis of rotation (frame or body); rotation around X, Y or Z axis with an angle in the 12-th column
  2. Repeated Translationally Positioned Volumes (RTPV Arrangement) of any number of copies of a logical volume with incremental copy numbers
    Each row represent a physical volume.
    1. The first to 4-th columns are same as above.
    2. The columns 6, 7 and 8-th specify the position of the first copy
    3. The 10-th column specifies the direction of placement; X, Y or Z direction
    4. The 11-th column specifies the incremental step size
    5. The last column specifies the number of copies
  3. Repeated Rotationally Positioned Volumes; axially symmetric arrangement of any number of copies of a logical volume with incremental copy numbers (RRPV Arrangement)
    Each row represents a physical volume.
    1. The columns "move", "pName", "pLogic", "MomType" and "pMother" are same as above.
    2. (X0, Y0, Z0) column specify the position of the center of an axial rotation
    3. "Radius" column specifies a radius of axially symmetric arrangement
    4. "RotAxis" column specifies the rotational axis ; X, Y or Z
    5. "Phi_0" and "dPhi" column specify a starting angle and incremental step angle
    6. The last column specifies the number of copies
  4. Replica in the X, Y or Z direction
  5. Replica in rho, phi or Z direction
    1. width (in length or angle) and number of replicas
    2. offset (in length or angle)
    3. logical or physical mother volume
Planned but not implemented yet are paremetrised volumes with linear scaling or linear rotation.

3) Generation of C++ code

Here is a sample of automatically generated C++ code which is created from almost skelton tables.

3.1) Naming conventions in GGE

Knowing GGE's naming convention is helpful to read the generated C++ code as well as using GGE correctly. Look at relevant Geant4 constructors will be very suggestive.

  1. Elements and materials
    1. Elements are named "elementXXX", where XXX stands for the element's symbol in the periodic table.
    2. materials are named just as you have typed in the second column of the material window.
  2. solids and logical volumes
    The "Name" typed in the first (leftmost) column of the "Logical Volume" is used to name the corresponding solid. If the name "world" is given to a logical volume of a Box, the G4Solid has an instance "solidworld".
  3. logical and physical volumes
    1. The instance of a physical volume defined by "pName" has a name prefixed with "physical", i.,e., instance's name is "physical" + pName ( + => string concatenation). "logical" is added to the instance of a logical volume.
    2. In case of SPV (single positioned volume), the columns "pName" (instance of physical volume) and "pLogical" may have the same strings.
    3. In case of RVA (repeated volumes arrangement), "pName" is different from "pLogical" whose copies are repeatedly placed.
  4. All variables are named after their proper instances. See for example, the control variable used in the for loop in the RVA.
    Another examples are arrays to define BREP geometry.

3.2) Default values and combo-boxes

  1. Default optional values of materials GGE provides default values in a pre-filled columns or with the combo-boxes. "Use", "State" and "Unit" columns are equipped with combo-boxes. Temperature and pressure column are pre-filled with 273.15 * kelvin and 1 * atmosphere.
  2. Default values in volumes "Mother Type" is either NULL (mother of all), logical (type 2, 4 constructors) or physical (type 2 or 4 constructors) in G4PVPlacement.



WARNING: Materials below are obsolete. Updating them in conjunction with MOMO is planned now in March 2003

4) A First Lesson; how to use GGE.

Here is a walk-through of how to use GGE.

4.1) Visualize the prefabricated detector sample
	1) In a xterm, type %java gge
	2) In the "Volume window", select "Load a Volume file" menu
		and double click on "trumpetBREP.g4dt"
	3) Click "Makesource" and select "Make C++ code". Have a look of the generated C++ code.
	4) Save the C++ code (overwrite the existing one)
		in .../GGEmake/src/MyDetectorConstruction.cc" using the file chooser.
	5) In another xterm, go to the directory GGEmake/ and type
		%make G4TARGET=myGGEdetector

		Watch if there is any compilation error. At present,
		GGE is made so that it generates correct C++ codes,
		if a user uses GGE correctly.

		In the example of "trumpetBREP.g4dt", a few warnings are shown on BREP.
	6) Check that you have "myGGEdetector" executable, in $(G4INSTALL)/bin/$(G4SYSTEM)
	7) In another xterm, type 
		%java gag
		
		and with the "Run GEANT4" button, choose and run "myGGEdetector".
        8) Use /control/execute command and double click on "GGEdraw.g4m".
		To have a better view, use vis~ commands (camera/viewpoint, zoom etc).
		You can select DAWNFILE to  draw and have a PS hardcopy.

4.2) Modify the prefabricated detector
 Now let's change the detector configuration. Go to the "Volume" window
	and change any part of it, including material.

4.2.1) Changing materials
		
	1) First, you have to  "Clear Material" in the Material editor. 
	2) Then, select "Load material" and double click on "MaterialDB.g4mt". 
		    Now you have a list of materials.
	3) Then, in the "Logical Volume" panel, double click the box you want to change
		    and type in the name of the material in the material editor.
	4) Change as many materials as you like and push "Used Material" button.
		    You see that materials you have typed in are marked "Used" in red.
		    If not, you might have mistyped the name of a material.
	5) If you want to use additional materials, select  "Use" in the material 
		   editor (the leftmost column).
	6) Push "Makesource" and see your change has been realized in the C++ code.

	NOTE!! Be careful that there are no duplicated "Used" materials, when
		you load the material DB without "Clear Material".

4.2.2) Modifying the size parameters of solids

	To change the sizes of G4 solids
	1) click a "solid" box of the logical volume of your choice. 
	2) You have a pop-up window to edit the parameters. Change a parameter 
			or its unit, as you like.
	3) Push "Makesource" and see if your changes have been correctly applied 
			to C++ code.
	4) In case of BREP solids, the pop-up window has variable number of columns
			to accept any number of nodes.
	5) For complicated solids like BREPs, preview may be useful. Click "View"
			button and you have a view with the DAWN renderer. Its g4.prim file
			is also shown in an edit-able widget.

4.2.3) Changing the type of solid of an existing logical volume
   You may want to replace the current G4Solid with another one. In the 
    present GGE you can't do so directly. You have to "Create" a new logical
    volume with the type of solid you want and then delete the unnecessary volume.

	1) Choose your new solid with "Select Solid" combo-box.
	2) Push "Create" button and you have a pop-up window to input parameters.
	3) Type in numbers and select their units.  
	4) Preview if you like and then push "OK".
	5) Check the C++ code.

4.2.4) Changing visualization attributes (Color).
	1) You have to "Create" a new VisAttributes
	2) Upon the "Create" button, you have a Color Chooser.
	3) Select RGB (not HSV). Set your color with slide-bars.
	4) Give it a name, and push "OK". Then you have a color circle and name in the
		VisAttrib panel.
	5) Edit the VisAtb box in the LogicalVolume panel.
	6) See the C++ code.

4.2.5) Changing Repeated Volumes




"exampleN01.g4dt" contains three "single positioned volumes"
		and one "repeated volumes" in the X direction.
		Change the parameter of repetition such as the number
		or width, or you can add another "repeated volumes"
		in another direction.

		In "trumpetBREP.g4dt" you can edit BREPs, adding new faces etc..

	   b) making C++ code "MyDetectorConstruction.cc" and compile.

		Finally, back to the step 3 and recompile.


	Opening GGE, compile, GAG simultaneously, you can 
	test and improve the geometry, just like creating
	HTML or TeX documents.


 2.4) GGEmake; a directory containing the GEANT4 codes to compile and visualize the detector
     a) implemented
	+ GNUmakefile
	+ myDetector.cc ; main()  with GAG session and visualization manager
	+ src/ directory contains
		+ MyDetectorConstruction.cc
                + MyPhysicsList.cc
		+ MyPrimaryGeneratorAction.cc
		+ MyVisManager.cc
	+ include/ directory

 2.5) compile and visualize with Momo and GAG

    a) implemented

	+ canonical scheme of GEANT4 to compile
	   	+ make G4TARGET=myDetector
		+ the binary is created as $G4INSTALL/bin/G4SYSTEM/myDetector

	+ Momo (GAG, Compile and GGE buttons)
		+ rapid cycling of GGE and GAG to edit and view the geometry
		+ a macro file for visualization (OGLIX default) "DrawDAWN.g4m", etc..

     b) not implemented
		- automatic "calibration" of the detector with geantino

 2.6) exemplary persistent detector files with *.g4dt suffix 
	 + 3D array of lead plates using translational RVArrangement
	 + BREP Pcones trumpetss  using axially symmetric RVArrangement
	 + Replicas to form  cylinders

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



!!!!!OBSOLETE!!!!!

3) Installation

The minimum set to get C++ source code
	1) GGE.jar file
	2) Java interpreter ; java
Additional set to compile
	3) GEANT4 toolkit with compiled libraries
	4) GGEmake directory
Additional set to visualise and use GUI
	4) DAWN (plus Ghostview) or OGLIX or VRML
	5) GAG (Java version) or GAG.jar file
Additional too to make life easy
	6) Momo to use all the above ingredients; Momo.jar file
	 (without Momo, you have to invoke GGE, compile and GAG respectively in windows.)

3.1) Java and Swing
We have tested GGE on Unix-en (Linux and Solaris) and Windows (95/NT).

 3.1.1) Unix:

  + Linux: jdk1.1.3 or later(i.,e., jdk-1.1.6) + Swing-1.0.2
	1) jdk1.1.5 may have bugs, while jdk1.1.6 works
	2) GGE co-works with Swing-1.0.2 and not with 1.0.1 (or maybe not
		with 1.0.3).
	3) we are testing the current GGE with JRE1.2-beta04. The present source can be
		compiled but doesn't execute correctly. In any case
		Sun has announced on 17 August that JDK1.2 will be delayed
		till November!!
  + Solaris: jdk1.1.6 + swing-1.0.2


  We assume that you have 
	1)jdk1.1.6/bin/java (Java interpreter)  to which paths are set
	2)Swing-1.0.2 which is defreezed and placed in $HOME/swing/swingall.jar

 3.1.2) Windows:

	We use JBuilder2 with  Swing-1.0.2. Note that you have to 
	eliminate all other libraries than swing-1.0.2, after having
	copied it into JBuilder2.

	We are trying JDK1.2beta4 + JRE1.2 with JBuilder2.

	NOTE! At present we have not Momo/GAG for Windows. So,
	you can only create C++ code under the Windows.

3.2) GGE and related files
The latest product of GGE is that of Sep. 24.
All *.java, *.class and GGE.jar files are placed in 
		geant4beta/environments/Momo/java/Momo/GGE

Only "GGE.jar" file is necessary to run GGE. 

	GGE/*.java	GGE source files
	GGE/*.class	GGE byte code files
	GGE/GGE.jar	jar archive file to which CLASSPATH must be set
	GGE/*.g4mt	material database after PDG data
	GGE/*.g4dt	exampleN0x detector file
C++ source codes and GNUmakefiles to compile with GEANT4 are placed in
       		geant4beta/environments/Momo/GGEmake.

Only geantino is instantiated in the initialization of GEANT4, so that it is quite
rapid to have a visualization of the geometry. You can choose DAWN, OpenGL or VRML system.

	 GGEmake/myGGEdetector.cc		main() program
		/GNUmakefile
		/src
		/src/MyDetectorConstruction.cc	C++ generated by GGE
 		/src/MyPrimaryGeneratorAction.cc	geantino gun
		/src/MyVisManager.cc		DAWN, DAWNFILE, OGLIX, OGLSX, VRML1, VRML1FILE
		/src/MyPhysicsList.cc		geantino definition
		/include/*.hh
		/GGEdraw.g4m			default macro file to visualize with OGLIX

3.3) install, setenv and run

	%set path=($path jdk1.1.6/bin)  	<=== add the path to java and javac
	%setenv CLASSPATH .:$HOME/swing/swingall.jar:$HOME/geant4beta/environments/Momo/java/Momo/GGE/GGE.jar


  Then in any directory, you can invoke GGE.

	%java gge


3.4) DAWN, Tcl/Tk and Postscript for the preview of CSG or BREP solids
 If you don't use GGE's preview button, these are not necessary.

 If you want to  preview  G4Solids, you have to install
DAWN, Fukui renderer as well as Tcl/Tk wish (Tcl/Tk 8.0) for its GUI. 
DAWN uses also Postscript to draw *.prim files.  

For the visualization of the whole detector, DAWN or  Mesa (for OGLIX)
are necessary.

3.5) GEANT4 toolkit and its environments
The visualization manager instantiates DAWN, DAWNFILE, OPENGLIX,
OPENGLSX, VRML, VRMLFILE. So, you have to setenv accordingly.