GGeo Orientation : Geometry Modelling and Persisting

top level holder of geometry libraries : GMaterialLib, GSurfaceLib, GBndLib, GNodeLib, GGeoLib
created from G4VPhysicalVolume by X4PhysicalVolume::convertNode
collects GVolume instances GNodeLib::addVolume

Does multiple traversals over full GVolume tree, identifying repeated geometry and labelling the tree nodes with the repeat index (ridx). Remainder geometry that does not pass instancing cuts on numbers of repeats is left with repeat index zero.

  • used from GGeo::prepareVolumes
  • GInstancer::createInstancedMergedMeshes

Analytic Geometry Overview : GPt, GPts, GParts

minimally captures node(ndIdx) to solid(lvIdx,csgIdx) association and boundaryName, can also hold placement transforms
GPt structs instanciated and associated with GVolume (NB GParts instanciation now deferred )
GPt instances are collected into GPts after GPt::setPlacement with the appropriate GVolume (base relative or global) transform during GMergedMesh::mergeVolume.
collects GPt struct and handles their persisting to/from two transport buffers (ipt and plc) and one GItemList of boundary spec
invoked from GGeo::postLoadFromCache or GGeo::postDirectTranslation.
analytic geometry holding npy/NCSG NPY Orientation : array creation, updating and persisting
from from the volume combined GPts and std::vector<NCSG*> from m_meshlib


GPt captures node placement of a solid within the full geometry tree in a minimal way, holding only:

global transform
lvIdx, csgIdx
indices referencing the solid shape
index of the node in the full tree
string representing the boundary of this node in the tree (material and surface omat/osur/isur/imat)

GPt are canonically instanciated in X4PhysicalVolume::convertNode where instances are associated with the GVolume of the structural tree.

vectors of GPt instances are collected into GPts m_pts within GMergedMesh. The GPts are persisted into the geocache which allows GParts creation to be deferred postcache.


GPts::export_ serializes a vector of GPt into transport arrays

four indices from GPt struct referencing the solid and the node
placement transforms
list of boundary spec strings

Canonical m_pts instances are residents of GMergedMesh and are instanciated by GMergedMesh::GMergedMesh with GPts::Make.

GPt instances are created in X4PhysicalVolume::convertNode and associated with the GVolume which are also instanciated there.

Motivation for GPts is to allow postcache deferred creation of merged GParts instances. This capability is needed in order to reconcile the different Opticks/Geant4 requirements regarding balanced/unbalanced CSG trees, see notes/issues/x016.rst

Can think of GPts as gathering and persisting the arguments needed for deferred GParts creation and merging.

This GParts creation is done in GGeo::deferredCreateGParts which is invoked from on high in OpticksHub::init after GGeo is loaded or adopted.


  • handles the concatenation of analytic geometry, by combination of GParts instances

  • creates primitive buffer from the parts buffer

  • holds boundary specifications as lists of strings that are only converted into actual boundaries with indices pointing at materials and surface by GParts::registerBoundaries which is invoked by GParts::close which happens late (typically within oxrap just before upload to GPU).

    This approach was adopted to allow dynamic addition of geometry and boundaries, which is convenient for testing.

  • the GParts name derives from the history of being used to hold single primitive parts of Daya Bay PMT which were created by detdesc partitioning from python (pmt-/

Lifecycle Summary

  • single tree(ie single solid) GParts created from NCSG by X4PhysicalVolume::convertNode on first encountering an lvIdx, where they get attached to a GVolume
  • single tree GParts are merged together into combination GParts by GMergedMesh::mergeVolumeAnalytic where placement transforms are applied with GParts::applyPlacementTransform
  • combinend GParts are uses by OGeo::makeAnalyticGeometry to GParts::close and upload the GParts buffers into the OptiX context on GPU

Details on where GParts is used

Based on opticks-fl GParts.hh


     near dead code : to be removed



         within the visit of X4PhysicalVolume::convertStructure_r
         GParts::Make creates GParts instance from the NCSG
         associated to the GMesh for the lvIdx solid.  The GParts
         are associated with the GVolume nodes of the tree.

     NB for full(not test?) geometry GMergedMesh is orchestrated
     from GGeo::prepare by the GInstancer, but most action is in GMergedMesh

         GParts::add the pts from an "other" GMergedMesh into m_parts

         invokes GMergedMesh::mergeVolumeAnalytic with the pts
         and transform associated to the GVolume.
         The transform is the base or root relative flobal transform

         GParts::add the pts argument after GParts::applyPlacementTransform
         is applied to them, using transform argument


          GParts::Load and associates them with corresponding GMergedMesh also loaded



          GParts::setIndex to the collected m_meshes index


          GParts::Make from NCSG instance and spec : used
          from GGeoTest

          GParts::Make from parameters, type and spec : used for
          creation of simple geometries


          GParts::close constructs the primBuffer, also uploads the
          various buffers prim/tran/part/identity into OptiX context on GPU

Mesh-type or node-type

Boundary spec is a node-type-qty, not a mesh-type-qty so it does not belong inside GParts (a mesh-type-qty) … there are relatively few mesh-type-qty for each distinct shape (~249 DYB), but much more node-type-qty (~12k DYB)

BUT: GParts combination means that it kinda transitions between mesh-type when just for a single unplaced shape into node-type once applyPlacementTransform is used by GMergedMesh::mergeVolumeAnalytic

persisted structure detailed in GParts.rst

  • for examination of structure of multi-complete tree buffers see GParts.rst



Canonically invoked from GGeo::postLoadFromCache and GGeo::postDirectTranslation.

This is needed prior to GPU upload of analytic geometry by OGeo, it requires the GMergedMesh from GGeoLib and the NCSG solids from GMeshLib. Thus it can be done postcache, as all the ingredients are loaded from cache.

See ../notes/issues/GPts_GParts_optimization