CERN Accelerating science


Advanced graphical user interface for particle simulation programs

Geometry Editor Tutorial

author: Vasilis Vlachoudis
version: 3.0
last change: Nov 2019
The present tutorial is a step-by-step guide using the Geometry Editor to build a complex geometry of the following CERN beam dump
Final geometry in flair, cut with a rectangular clip body to see the interior
To follow this tutorial, you will need:
  1. Basic knowledge of FLUKA, especially the use of combinatorial geometry
  2. Basic knowledge of flair (see flair)

1.1. Geometry description

First thing you have to do is to collect all technical drawings, photos information concerning your geometry to build.
3D representation of the dump cut in half

External dump dimensions

AA cross section
Please pay attention to:
  1. The cylindrical symmetry
  2. All dimensions in mm, while FLUKA is using cm
  3. The beam is entering the dump from the right side through the 10cm long hole in order to minimize the back scatterings.
  4. The cooling water is entering from the center hole on the left side and it follows a spiral path around our dump. Since FLUKA do not have any spiral shaped body we need to approximated it with cylinders.
  1. Launch $ flair by typing the command, or from the system application menu
  2. Select the
    tab (if it is not already selected)
  3. Click on the label
    New ▼
    (not on the icon) of the button
    New ▼
    To open a drop downlist with the available templates.
  4. Select the
  5. The void template.
    The void template will generate a basic FLUKA input with two concentric spherical regions named BLKBODY and VOID
  6. Fill in the Title: field something like: LINAC4 main dump
  7. Click Yes on the popup-dialog asking you to update the TITLE card
  8. Optionally you can add also a small note describing the present project
  9. Finally click on the save icon on the left of the tab bar. Save it as maindump.flair preferably save it under a new directory. Please use this name to be consistent in all the following commands.
    You can create directories directly in the save dialog there is a dedicated button for it.
    Control-S key is a shortcut for save
as an image layer in the Geometry Editor to draw the geometry on top of it.
  1. Download main_dump.png technical drawing showing the AA cross section of the dump.png, and save it in the same directory with our project.
  2. Click on the
    tab to visualize the geometry
    The 4 viewports, clockwise from the top-left:
    • Top/Up: Red (Z:X)
    • 3D: Green
    • Front: magenta (X:Y)
    • Right: blue (Z:Y)
    The first thing to do is to choose the geometry coordinates. For this tutorial, the following coordinate system will be used:
    • Z: direction of the beam, horizontal
    • X: horizontal axis perpendicular to the beam
    • Y: vertical axis pointing upward
    Using the Middle mouse button and a combination of Shift, Control keys you can navigate very quickly in the geometry.
    • Panning press and hold the Middle mouse button in any viewport and drag the mouse.
    • Set pivot point click once the Middle mouse button the viewport will center to this location and set it as a pivot point for the rotations
    • Orbit press Control and the Middle mouse button the viewport will rotate. Useful only when displaying in 3D. It should be used with Setting the pivot point
    • Zoom In/Out rotate the Wheel of your mouse
    • Pan Backward/Forward press Control and rotate the mouse Wheel
    • Orientation Cube hover the Mouse over the orientation cube on the bottom-left corner of each viewport. The cube will become bigger and interactive. Click at any location, or the colored axis to change the orientation of the viewport and or align the axis
  3. Click on the
    tab on the left listbox. It will change to the layers definition
    There are 4 predefined layers
    • Borders - 2D display with only the boundaries of regions
    • Media - 2D display with the regions colored with their material
    • 3D - 3D basic display
    • Lattice - like the Media with the lattice viewing and voxel enabled
  4. Click the to create a new layer, automatically named Layer 01
  5. Click on the name and change it to Drawing
  6. Click on the <add> last-entry in the layer listbox Select the Image from the drop down list.
  7. Click on the button to load the drawing.

    The image shows the top cross section of the geometry therefore the image coordinates correspond to horizontal-Z, vertical-Y, according to the previous definition of our coordinate system. Since the beam is entering from the right-to-left the horizontal-Z is reversed moving to positive values from right-to-left.

    Any bitmap image can be imported (jpg, gif, png, bmp, ... directly converted from the technical image or even from paper scanning!)
  8. Click the button
    below the image one, to open the image calibration window

    In this window, the user has to provide minimum 4 points in order the program to be able calculate the conversion from the image coordinates to the geometry. 4 points is the minimum to calculate the position, orientation, aspect and the skewness of the image. The more points you provide the more accurate the calibration will be done.

    In case you provide only 3 points it will assume that the plot is perfectly orthogonal, no skewness and with an aspect ratio of 1

  9. Click the
    button. The mouse cursor will convert to a cross.
  10. Add the first point/marker at almost bottom-right of the image as shown
  11. Enter the coordinates for the [1] first marker: [X: -8.0, Y: 0.0, Z: 0.0].
    The drawing shows a diameter of the Dump Core as 160mm.
    Initially the points are not needed to be accurately placed, we will correct them later.
    You can Double Click on a marker to pop-up again the window with the coordinates to correct if needed.
  12. Add 3 more markers as shown in the drawing Markers coordinates:
    #  X   Y   Z 
    1 -8 0 0
    2 8 0 0
    3 8 0 40
    4 -8 0 40
  13. Click the
    it will open a window with all the markers pixel position xi,yi 3D coordinates x,y,z error and transformation matrix to be used.
    The fields xi,yi,x,y,z are editable in this window so you can fine tune if you want also here the parameters
  14. Close the Information window
  15. If the error is too big you can correct the calibration. by zooming in with the Mouse-wheel.

    Pan close to the markers and with the Middle mouse button or with the keyboard Arrows.

    Drag the marker using the left mouse button and place it to the center of the line intersection as accurate as possible

  16. Repeat the procedure for all markers
  17. Click again on the
    dialog and see how the Pixel error is decreasing (or increasing).
  18. In this specific case our image is from a image processing program (not scanned from paper), so the exact position of the markers should lie in the center of the pixels, with decimal .5 The pixels are perfectly aligned horizontal and vertical so convert all decimals values to .5.
    Markers 1,2 and 3,4 have the same xi,
    while 1,4 and 2,3 have the same yi, reducing the error to zero!

    To edit the table move the cursor/mouse to the pixel value xi,yi and click Enter.

    The error should be almost zero
  19. Click
    to close the calibration window
  20. Click on the Black: color button to remap the image "black" to some other color e.g. cyan. This is done since the image lines are black, and it will be confused with the bodies boundaries which are also black.
  21. Check the Prompt draw option
    Normally the background image is displayed when the viewport is idle. However, during the editing process the background image is convenient to be visible all times.
    The red text color of the option indicates a time consuming process, which when active delays the screen refreshing.
  22. Click on the
  23. Maximize the Red (Z:X) viewport.
  24. Select the Drawing layer from the drop-down list of the viewport Note that the image is reflected due to the coordinate system we used.
    Benefiting from the cylindrical symmetry of the geometry, only one viewport is needed, however the user should be careful while editing the geometry on the impact on the other viewports.
    After creating the layer, the 4 markers that have been used for the calibration are shown on the viewport (can be used as snapping points if needed) and they are also appearing on the list-box on the right with a Magenta color showing that the visible attribute is On.
  25. Hover to the mouse over the Orientation cube and click Twice the Left triangle as shown in the image in Yellow. so as to rotate the Z axis by 180 degrees.
  26. Press Control-S key to save the project
Firstly we need to create all necessary bodies. This can be done graphically, profiting from the snapping mechanism of flair.

The void template we used, generated two concentric spheres and defined two REGIONs, BLKBODY and VOID. It is easier to visually see the undefined regions than over-defined, so as a first step we will delete the expression of the VOID REGION and we will re-created it at the end.

It snaps on the grid, markers, other bodies and intersection points from bodies
  1. Click on the
    tab above the listboxes, and click the entry
    . The bottom listbox should populate the
    of the REGION VOID
  2. Click to select the
    zone01 | +void
  3. Press Delete key to delete the zone01. The viewport should look like that now. The red titled lines show that it is undefined the region, and the error message, complains since there is an empty expression.
  4. Add the infinite cylinders
    centered at zero. To add a body, any of the following steps can be used:
    1. From the ribbon
    2. Using shortcut [b] which opens the bodies menu.
    3. Using shortcut [B] (capital) which re-inserts the last inserted body type.
    4. Using [Spacebar] which opens the Insert pop-up menu
    5. Right-click and select the body insert
    When adding many bodies you can leave permanently the bodies insert menu by first opening the menu from the menu bar or the toolbar, and then clicking the ------ item to tear-off from the menu bar.
  5. Add a new body
    The status bar should display “Adding body 'ZCC'
    The color of the bodies in the menu reflects the axis direction (RGB):
    X: Red
    Y: Green
    z: blue
  6. [1] Left-click on any point close to the Z=0
    [2] drag the mouse upwards towards the border lines of the beam entrance cylinder and click the mouse again A new cylinder will be created with x=y=0 and radius close to 1.75cm. If it is not exactly 1.75cm, then you have to zoom-in and move the cylinder boundary to the exact location, or you can type in the radius on the left listbox
  7. Click the name: field on the bottom-left listbox of the
    Or press the n key and it will move the focus to the listbox on the left with the body properties.
    Rename the cylinder to cyl1
  8. Press the ESCape key to unselect the current body.
  9. Repeat the process for the remaining cylinders. For this tutorial the cooling spiral will be omitted at the back (left-side of the image)
    To repeat the last body addition use the shortcut [B] capital
    all subsequent bodies will use the same name prefix with an increasing number as suffix
  10. Add a Z-plane
    on the right of the geometry at Z = -4 cm
  11. Rename this body to z1
  12. Press B key (B-CAPITAL) to repeat adding Z-planes
    for each vertical line you see limiting the dump, cooling pipes etc.

    Since we cannot add a spiral in FLUKA we will emulate the surrounding cooling spiral as cylinders.

    Do not forget to add a plane also at the beam entrance

    Now the image should look like the above. With 5 cylinders (or more if you add the back ones) and 25 planes
  13. Press Control-S key to save the project
The geometry editor of flair has an advanced feature of editing graphically the regions, more correctly the “Zones” of the regions. Just to remind the concept, “zone” is a portion of space that is described by the + Intersection and - Difference operator, NO Union.
A REGION is defined as a union of zones.
Zone is a very fundamental concept in FLUKA since the particle tracking is performed always in a single zone. While the region is used to define the properties on a zone. Thus, the simpler the zone description is, the faster the simulation will go!

Overlaps of zones are permitted only if they belong to the same region. Actually zone overlaps is encouraged since it will result to simpler expression and bigger volumes therefore faster tracking and less zone switching.

With parenthesis the concept of zone doesn't exist. FLUKA will try to expand the parenthesis to a union of zones. It can fail when excessive parenthesis are used. Even though flair can accept both parenthesis and/or the expanded form, graphically the user can only edit/modify zones without parenthesis!

Zone Editing

Please note that zone editing in flair is completely different than all traditional CAD or CAD-like 3D programs. In flair the editing is done in 2D and the user has to ensure for the 3D outcome by controlling the other viewports. The idea behind this, is that each body splits the space in two zones, the inner and outer one. A selection of 2 bodies splits the space into 4 zones, and for n bodies to 2n zones, which many of them could be void. At this point the user needs to select graphically the zone he is interested in. The procedure (graphically) is the following: Please refer to the flair online manual or FLUKA course slides for a more detailed explanation on the zone editing.

Add Zone on a NEW REGION

If unsure, press the ESCape key to ensure that NOTHING is selected.
  1. Press the
    button from the ribbon. The Zone Edit dialog will appear
    Short: d (small d) for define
  2. Click on the Bodies in the dialog and Select the bodies that define the boundary of the zone.
    See flair manual slides for managing the selections.
  3. Since ONLY bodies are selected and nothing else, the Operation will change to Add Region
  4. Click on the Operation and hover the mouse in the geometry to select the zone you are interested
  5. Click on the zone and flair will create a new REGION and it will add a new Zone01 inside with the expression that it calculated from the location you clicked.


Same procedure as before with the addition that we need to select an existing REGION
  1. Press the
    button from the ribbon.
  2. Click on the Region: button in the dialog and select the region you want to ADD the zone to.
  3. Click on the Bodies and Select the bodies that define the boundary of the zone.
  4. Since there is a REGION and bodies selected the Operation will change to Add Zone
  5. Click on the Operation and hover the mouse in the geometry to select the zone you are interested
  6. Click on the zone and flair will ADD to the selected REGION a new ZoneXX

MODIFY an existing Zone

Same procedure as before with the addition that we need to select an existing REGION and an existing Zone##
  1. Press the
    button from the ribbon.
  2. Click on the Region: button in the dialog and select the REGION you want to add the zone to.
  3. Click on the Zone button in the dialog and select the Zone of the selected REGION you want to MODIFY.
    Selecting a Zone, flair will AUTOMATICALLY select all bodies of that zone.
  4. Click on the Bodies in the dialog, and Select the bodies that define the boundary of the zone
  5. Since there is a REGION, a Zone and bodies selected the Operation will change to Modify Zone
  6. Click on the Operation and hover the mouse in the geometry to select the zone you are interested
  7. Click on the zone and flair will MODIFY the ZONE on the selected REGION


  1. Select the region
  2. Select the zone (graphically or from the properties list-box)
  3. Press [Del] or [Backspace] and the zone will be deleted.
WARNING even though the region and the bodies are also selected, they will not be deleted at this moment.
Pressing [Del] for second time all the selected bodies will be deleted
Pressing [Del] for third time the selected region will be removed.

We start building the region of the “Core dump”. It should be composed by two zones, one on the right with the entrance hole and the rest.

  1. Hit Escape couple of times to be sure that no objects are selected.
  2. Press the
    button to open the Zone Edit dialog
  3. Click to select the Bodies of the dialog. (if it is not already selected)
  4. Move the mouse a bit outside of the upper-right corner of the first zone location 1
  5. Click at location [1] the Left-mouse button and keep pressing it.
  6. drag the mouse to location [2] to select the 3 bodies on the right side (two cylinders cyl1 and cyl2) and one plane z3. (Maybe the naming is different)
    The dialog should say that Bodies: 3 Selected
    The selected objects will appear as light magenta. While the visible objects appear as dark magenta
  7. Click to select the plane at the entrance location [3]
  8. On the Zone Edit dialog click the Operation button which should say
    Add Region
  9. Moving the mouse in the viewport will highlight the possible zones with the selected bodies. Click to select the zone as shown below Automatically a new REGION named REG1 will be created, with the zone expression assigned
    zone01 | +cyl2 +z24 -cyl1 -z3
    , and material assigned the last one used. Since we didn't use anything before it will be VACUUM

    Note: that the bodies names in the expression might be different in your case.

  10. Change the REGION name from REG1 to CORE
  11. Click on the Material in the listbox to change it to CARBON
  12. Press the
    button to open the Zone Edit dialog It should still have 1 Region and 4 Bodies selected.
  13. Click on the Bodies and modify the selection as follows: Unselect the right-most plane and the inner cylinder and select the left plane as shown below
  14. Click on the Operation button of the dialog which should show
    Add Zone
  15. Hover the mouse of the central core of the dump and click
  16. Continue the procedure to create the region JACKET with material COPPER as shown below
    In the JACKET, all the spiral pipes are modeled with cylinders. To add the zones select the region (if not selected) and drag a small rectangle around like below.
  17. Repeating the same procedure create the following regions,
    • COVER with IRON
    • BACK with IRON
    • COOLING with WATER
    until the image of the viewport looks like the following
  18. Press the ESCape key 3-4 times to unselect everything.
    The ESCape key is progressive as the selections. If you have a REGION, Zones and Bodies selected hitting once it will unselect the Zone, twice it will unselect the Bodies and the third time the REGION
  19. Click the
    Layout ▼
    to see all 4 viewports
  20. We need to correct the REGION VOID we destroyed in the first step. For this we don't need the visibility of the bodies. Click on the drop down menu of the
    Visibility ▼
    button on the ribbon, and select the
    Hide All
  21. When editing the expression of REGION VOID we need to use always the Body void. The big sphere which is visible when we zoom in.

    An easy way to avoid zooming-in/out is to Freeze some bodies, so they will appear in all expressions and we don't have to explicitly select them every time.

    Select the
    SPH | void
    body from the top-left listbox and click the
    Freeze ▼
    icon on the tool bar. The message objects frozen will appear.
  22. Select the
    from the top-left listbox
  23. Click on the
    button (shortcut d)
  24. Create the zones of the surrounding VOID keeping in mind that the SPH void is *always* selected. When you finish the message Errors found should disappear
  25. Finally click on the
    Unfreeze All
    to unfreeze the frozen bodies.
  26. If by mistake you have created multiple regions like COOLING1, 2, 3, or CORE 1,2.. you can select them and click the
    button to create one REGION out of them
  27. Press Control-S key to save the project
Lets make now a nice 3D plot of our dump. There is already an existing 3D layer which is quite primitive so several options will be added on it.
  1. Click on the
    Layout ▼
    to visualize all 4 viewports. You should have an image like
  2. Go to the Green viewport (top-right) which should be already in 3D. We are looking from the 45° azm and polar angle the plot towards the center O(0,0,0).
    Pan backward with Control + Mouse-wheel towards you, the viewport until you see the whole image, like:
  3. Click with the Middle mouse button somewhere at the middle of our displayed dump. The middle mouse button will center the plot to this location and set it as a pivot point for all rotations.
  4. Click on the ribbon
    button. The orbit trackball will appear.
    You can orbit at any time directly with the middle mouse button, by pressing the Control key
  5. Click and drag the mouse on the Green ellipse which rotates around the Y-axis to make a rotation of about 180°.
    The same operation you can make from the Orientation cube. Note that everything in the orientation cube even the axis are clickable and perform an action.
  6. Pan backward the viewport with Control + Mouse-wheel until you see all the dump.
  7. Press t key to remove the trackball.
  8. Either pan the image dragging the middle mouse button or simply click it in the middle of the dump.
  9. We will make now a new 3D layer to customize it a bit. Press the button on the mini-toolbar of the green viewport, and it will show the layers tab and activate the 3D layer.
  10. Press the button on the layer, and a new layer named 3D 01 will be created based on the 3D.
  11. Renamed it to My3D
  12. Go to the Green viewport and select from the dropdown layers menu the new layer My3D
  13. Again in the layers listbox select the
    3D | [X]
    item and the 3D options will appear below.
  14. Experiment with the options:
    • Antialias
    • Edge detection
    • Xray level
    e.g. add a bit of Xray 30-40 should be ok
  15. Go to the magenta viewport and add an
    body as in the image.
  16. Correct the length in the Red or Blue viewports
  17. Name it as clip
  18. Go back to the My3D → 3D layer options and in the Clipped by: option select the new clip body.
  19. The Green viewport should now be clipped with and should look like this
  20. Press Control-S key to save the project