Documentation: Update GeoModel main page, add gmex, gmstatistics and gmcat,...

Documentation: Update GeoModel main page, add gmex, gmstatistics and gmcat, update FullSimLight main page

documentation/docs/components/geomodeltools/gmcat/index.md

+# GeoModelCat
+
+GeoModelCat (`gmcat`) is a command line tool that allows to concatenate different geometry files into a single final SQLite file. It is possible to concatenate plugins (.dylib/.so) and/or SQLite (.db) files.
+
+*gmcat* has the following parameters: 
+
+``` bash
+-o [MANDATORY] Name of the output .db file
+-v [OPTIONAL] Print verbose output to the screen (default: direct verbose output to /tmp)
+-g [OPTIONAL] Path to the local GeoModelATLAS repository (default: .)
+
+``` 
+
+## Examples
+
+In order to combine three different plugins into one single detector file one need to call gmcat in the following way:
+
+```bash
+
+./gmcat libPixelGeoPlugin.0.0.1.dylib libSCTGeoPlugin.0.0.1.dylib libTRTGeoPlugin.0.0.1.dylib  -o InnerDetector.db
+
+``` 
+
+<!--To convert a GDML geometry and save it in SQLite format with  *gdml2gm* :-->
+<!--``` bash-->
+<!--./gdml2gm -f myGeometry.gdml -o myGeometry.db-->
+<!--``` -->
+<!---->
+<!--To visualize a GDML geometry with  *gmex*, the user has to set the following environment variable: GDML_FILE_NAME. It has to point to the GDML file that the user wants to plug into *gmex*. Then it is sufficient to call gmex together with the *libGDMLtoGM.dylib/so* library:-->
+<!---->
+<!--``` bash-->
+<!--export GDML_FILE_NAME=<path-to-my-geometry-file>/myGeometry.gdml-->
+<!--./gmex ../lib/libGDMLtoGM.dylib   -->
+<!--``` -->

documentation/docs/components/geomodeltools/gmstatistics/index.md

+# GeoModelStatistics
+
+GeoModelStatistics (`gmstatistics`) is a command line tool that allows to extract information on the memory footprint of your detector description code. It takes one or more plugins (.dylib/.so) as input.
+
+*gmstatistics* has the following parameters: 
+
+``` bash
+./gmstatistics [-p] [plugin1.dylib] [plugin2.dylib] 
+
+``` 
+
+## Examples
+
+If you want to analyse the memory occupancy of your plugin (i.e. PixelGeoPlugin) you can type:
+
+```bash
+./gmstatistics ../lib/libPixelGeoPlugin.0.dylib 
+                    
+```
+
+This is the output retrieved by gmstatistics:
+
+```bash
+                     GeoLogVol            9998 instances              2239552 bytes
+                  GeoTransform            9856 instances              1419264 bytes
+                        GeoBox            9835 instances               472080 bytes
+                    GeoPhysVol            7941 instances              1905840 bytes
+                    GeoNameTag            4904 instances               235392 bytes
+              GeoIdentifierTag            4293 instances                68688 bytes
+                GeoFullPhysVol            4088 instances              1896832 bytes
+         GeoAlignableTransform            2059 instances               494160 bytes
+    GeoAlignableTransform[216]            2058 instances                32928 bytes
+                 GeoShapeShift            1914 instances               306240 bytes
+           GeoShapeSubtraction            1190 instances                57120 bytes
+                   GeoMaterial             812 instances               116928 bytes
+               GeoMaterial[56]             794 instances                48752 bytes
+                       GeoTube             746 instances                35808 bytes
+              GeoMaterial[120]             571 instances                25408 bytes
+                 GeoShapeUnion             492 instances                23616 bytes
+               GeoMaterial[72]             447 instances                35904 bytes
+                       GeoTubs             190 instances                12160 bytes
+               GeoMaterial[64]             167 instances                 5280 bytes
+                 GeoLogVol[32]             132 instances                 4544 bytes
+                    GeoElement              97 instances                 7760 bytes
+              GeoMaterial[128]              87 instances                 2080 bytes
+                GeoPhysVol[48]              71 instances                 2720 bytes
+               GeoMaterial[32]              60 instances                 1920 bytes
+                GeoPhysVol[40]              49 instances                 3392 bytes
+          GeoSimplePolygonBrep              45 instances                 3600 bytes
+                       GeoTrap              44 instances                 4928 bytes
+              GeoMaterial[136]              36 instances                 2144 bytes
+      GeoSimplePolygonBrep[40]              29 instances                  960 bytes
+      GeoSimplePolygonBrep[64]              29 instances                  960 bytes
+                GeoPhysVol[56]              22 instances                 2560 bytes
+                        GeoTrd              20 instances                 1280 bytes
+      GeoSimplePolygonBrep[32]              16 instances                 1120 bytes
+                       GeoCons              15 instances                 1200 bytes
+      GeoSimplePolygonBrep[48]              11 instances                  832 bytes
+            GeoFullPhysVol[56]              10 instances                17408 bytes
+                       GeoPgon              10 instances                 1280 bytes
+      GeoSimplePolygonBrep[56]               9 instances                  576 bytes
+                   GeoPgon[48]               9 instances                  144 bytes
+                   GeoPgon[56]               9 instances                  144 bytes
+                       GeoPara               8 instances                  640 bytes
+            GeoFullPhysVol[40]               7 instances                20992 bytes
+                  GeoPgon[104]               7 instances                  112 bytes
+      GeoSimplePolygonBrep[72]               3 instances                  192 bytes
+                   GeoPgon[72]               2 instances                   32 bytes
+                   GeoPgon[80]               2 instances                   32 bytes
+                GeoNameTag[32]               1 instances                   32 bytes
+                GeoElement[56]               1 instances                   16 bytes
+                   GeoPgon[96]               1 instances                   16 bytes
+Total GeoModel object allocation:  9.51557MB
+
+```
+
+<!--To analyse a GDML geometry and save it in SQLite format with  *gdml2gm* :-->
+<!--``` bash-->
+<!--./gdml2gm -f myGeometry.gdml -o myGeometry.db-->
+<!--``` -->
+<!---->
+<!--To visualize a GDML geometry with  *gmex*, the user has to set the following environment variable: GDML_FILE_NAME. It has to point to the GDML file that the user wants to plug into *gmex*. Then it is sufficient to call gmex together with the *libGDMLtoGM.dylib/so* library:-->
+<!---->
+<!--``` bash-->
+<!--export GDML_FILE_NAME=<path-to-my-geometry-file>/myGeometry.gdml-->
+<!--./gmex ../lib/libGDMLtoGM.dylib   -->
+<!--``` -->

documentation/docs/components/geomodelvisualization/gmex/index.md

 # GeoModelVisualization
 
-GeoModelVisualization (gmex) 
+GeoModelVisualization (gmex) is a 3D interactive visualization tool that allows you to display, navigate and debug complex detector geometries as the HEP experiments ones. 
+
+## Examples
+
+In order to launch gmex you could simply type:
 
 ``` bash
 ./gmex 
 ``` 
 
+This will open a dialogue window where you will be able to select a SQLite (.db) file that you want to display (see Figure 1).
 
-## Examples
+{{ imgutils_image_caption('Fig 1.png', 
+   alt='GmexGui', 
+   cap='Figure 1: Gmex GUI with dialogue window to select the geometry to be visualized.',
+   urlFix=False) 
+}}
+
+Alternatively you can feed the geometry to `gmex` directly via the command line. For example:
+
+``` bash
+./gmex myGeometry.db
+``` 
+
+Once the geometry is selected, by clicking on the `Geo`tab on the left, gmex will diplay a list of all the subdetectors present in the loaded geometry, as shown in Figure 2
+{{ imgutils_image_caption('Fig 2.png', 
+   alt='Subdetectors', 
+   cap='Figure 2: List of all the subdetectors present in the loaded geometry.',
+   urlFix=False) 
+}}
+
+In order to visualize all or some of them you have to click on the respective checkbox and click on the `eye icon` on the right (3rd icon from the top, in the right panel).
+
+{{ imgutils_image_caption('Fig 3.png', 
+   alt='SelectedGeometry', 
+   cap='Figure 3: Visualization of the selected geometry.',
+   urlFix=False) 
+}}
+
+Now that you have loaded your geometry you can start investigating it. A good way to improve the visualization experience is to apply Phi sector cutouts. To do that you have to click on the `Display` tab under `Geo` (Figure 4), unselect a few of the `phi sector cutaways` (Fig 4a) and then click `Close`. 
+
+{{ imgutils_image_caption('Fig 4.png', 
+   alt='DisplayTab', 
+   cap='Figure 4: `Display` tab under `Geo`.',
+   urlFix=False) 
+}}
+
+{{ imgutils_image_caption('Fig 4a.png', 
+   alt='PhiSector', 
+   cap='Figure 4a: Select/unselect the `phi sector cutaways`.',
+   urlFix=False) 
+}}
+
+At this point you have a cutaway view of your detector (Fig 5) and you can start investigating it by "opening" it. 
+
+{{ imgutils_image_caption('Fig 5.png', 
+   alt='Cutaway', 
+   cap='Figure 5: Cutaway view of the ATLAS detector.',
+   urlFix=False) 
+}}
+
+In order to do so you can follow the instructions written on the bottom part of the left panel. For instance, if you want to expand to child volumes you will have to use the following combination 'Ctrl/Cmd'+click. In this way you will remove the first layer of your geometry and be able to inspect its content (see Fig. 6). 
 
-To run *gmex* 
+{{ imgutils_image_caption('Fig 6.png', 
+   alt='TrackDisplay', 
+   cap='Figure 6: Cutaway view of the ATLAS detector without the first mother volume layer.',
+   urlFix=False) 
+}}
+ 

documentation/docs/index.md

@@ -73,6 +73,17 @@ A standalone tool to **generate geantino maps** of your newly built detector
 
 
 
+The GeoModel Toolkit includes:
+
+* **gmex**, the geometry explorer, an interactive 3D geometry visualizer
+* **gmstatistics**, tool to monitor the memory consumption
+* **fullsimlight**, a command-line tool to run experiment agnostic Geant4 simulation, and its graphical user interface, *fsl*.
+* **gmclash**, a Geant4 based command-line tool to perform clash detection
+* **gmgeantino**, a Geant4 based command-line tool to generate geantino maps
+* **gmmasscalc**, a Geant4 based command-line tool to compute the mass of a given piece of detector geometry
+* **gm2gdml** and **gdml2gm**, command line tools to convert GeoModel to and from GDML
+* **gmcat**, a command line tool to assemble geometry from multiple inputs
+
 ----
 
 ## External Dependencies

documentation/docs/start/install.md

@@ -2,17 +2,6 @@
 
 In this section, you will find instructions on how to **install** the latest **stable** version of GeoModel applications and development kits on different platforms.  If you are a developer and would like to install the GeoModel toolkit from source, please refer to the [Developers installation instructions](../dev/index.md).
 
-The GeoModel applications include:
-
-* **gmex**, the geometry explorer, an interactive 3d geometry visualizer
-* **gmstatistics**, tool to monitor the memory consumption
-* **fullsimlight**, a command-line tool to run Geant4 simulation, and its graphical user interface, *fsl*.
-* **gmclash**, a Geant4 based command-line tool to perform clash detection
-* **gmgeantino**, a Geant4 based command-line tool to generate geantino maps
-* **gmmasscalc**, a Geant4 based command-line tool to compute the mass of a given piece of detector geometry
-* **gm2gdml** and **gdml2gm**, command line tools to convert GeoModel to and from GDML
-* **gmcat**, a command line tool to assemble geometry from multiple inputs
-
 The development kits include header files and precompiled libraries for the development of detector description code. On some platforms (macOS) the development environment is installed together with the prebuild applications and libraries.  
 
 

documentation/mkdocs.yml

@@ -27,7 +27,9 @@ nav:
             - 'Overview': 'components/kernel/overview/index.md'
             - 'Class Reference': 'components/kernel/reference/index.md'
         - GeoModelTools:
-            - 'GDML2GeoModel': 'components/geomodeltools/gdml2gm/index.md'
+            - 'GeoModelCat (gmcat)': 'components/geomodeltools/gmcat/index.md'
+            - 'GeoModelStatistics (gmstatistics)': 'components/geomodeltools/gmstatistics/index.md'
+            - 'GDML2GeoModel (gdml2gm)': 'components/geomodeltools/gdml2gm/index.md'
         - GeoModelXML:
             - 'GeoModelXML Overview' : 'components/geomodelxml/index.md'
             - 'Building a geometry' : 'components/geomodelxml/buildinggeometry.md'
@@ -40,18 +42,18 @@ nav:
             - 'Troubleshooting' : 'components/geomodelxml/troubleshooting.md'    
             - 'User Guide (old, ATLAS specific)' : 'components/geomodelxml/old.md'
         - GeoModelVisualization:
-            - 'GeoModelExplorer': 'components/geomodelvisualization/gmex/index.md'
+            - 'GeoModelExplorer (gmex)': 'components/geomodelvisualization/gmex/index.md'
     - FullSimLight tools:
         - 'FullSimLight': 'fullsimlight/fullsimlight/index.md'
-        - 'GeoModelClash': 'fullsimlight/gmclash/index.md'
-        - 'GeoModelGeantino': 'fullsimlight/gmgeantino/index.md'
-        - 'GeoModelMassCalculator': 'fullsimlight/gmmasscalc/index.md'
-        - 'GeoModel2GDML': 'fullsimlight/gm2gdml/index.md'
-        - 'fsl': 'fullsimlight/fsl/index.md'
+        - 'fsl GUI': 'fullsimlight/fsl/index.md'
+        - 'GeoModelClash (gmclash)': 'fullsimlight/gmclash/index.md'
+        - 'GeoModelGeantino (gmgeantino)': 'fullsimlight/gmgeantino/index.md'
+        - 'GeoModelMassCalculator (gmmasscalc)': 'fullsimlight/gmmasscalc/index.md'
+        - 'GeoModel2GDML (gm2gdml)': 'fullsimlight/gm2gdml/index.md'
+        
         - 'Plugin Examples': 'fullsimlight/plugins/index.md'
         - 'Plugin Support': 'fullsimlight/plugin-support/index.md'
         - 'ATLAS Extensions': 'fullsimlight/atlas-extensions/index.md'
-    - FAQ: 'faq.md'
     - For Developers:
         - 'Build the Libraries and Tools': 'dev/index.md'
         - 'Build FullSimLight': 'dev/build_fullsimlight.md'
@@ -60,6 +62,7 @@ nav:
         - 'Doxygen documentation': https://cern.ch/geomodel/doxygen
         - 'Contributing to the Documentation': 'dev/docs-contrib.md'
         - 'Dev FAQ': 'dev/dev-faq.md'
+    - FAQ: 'faq.md'
     - Papers & Presentations: 'papers.md'
       #   - 'Public': 'papers/public.md'
       #  - 'Internal': 'papers/internal.md'