include/G4OCCT/G4OCCTPlacement.hh

0001 // SPDX-License-Identifier: LGPL-2.1-or-later
0002 // Copyright (C) 2026 G4OCCT Contributors
0003
0004 /// @file G4OCCTPlacement.hh
0005 /// @brief Declaration of G4OCCTPlacement.
0006
0007 #ifndef G4OCCT_G4OCCTPlacement_hh
0008 #define G4OCCT_G4OCCTPlacement_hh
0009
0010 #include <G4PVPlacement.hh>
0011
0012 // OCCT
0013 #include <TopLoc_Location.hxx>
0014
0015 /**
0016  * @brief Extends Geant4's G4PVPlacement with the corresponding OCCT placement.
0017  *
0018  * Extends Geant4's G4PVPlacement to carry the corresponding OCCT placement
0019  * (TopLoc_Location), enabling round-trip translation between the two geometry
0020  * frameworks.
0021  *
0022  * In OCCT, placement information is encoded in TopLoc_Location objects that
0023  * are attached to TopoDS_Shape instances.  A TopLoc_Location wraps a
0024  * gp_Trsf (4×3 homogeneous transformation), which may be a pure rotation,
0025  * translation, or a general rigid-body motion—closely matching the rotation
0026  * (G4RotationMatrix*) and translation (G4ThreeVector) pair stored in a
0027  * Geant4 physical volume.
0028  *
0029  * The correspondence between the two representations is:
0030  *   G4PVPlacement / G4VPhysicalVolume  ↔  TopoDS_Shape with TopLoc_Location
0031  *   G4RotationMatrix + G4ThreeVector   ↔  gp_Trsf (stored in TopLoc_Location)
0032  *
0033  * Design strategies for efficiently converting between these representations
0034  * are discussed in docs/geometry_mapping.md.
0035  *
0036  * NOTE: The OCCT location stored here is informational only; conversion
0037  *       helpers are planned for a future milestone.
0038  */
0039 class G4OCCTPlacement : public G4PVPlacement {
0040 public:
0041   /**
0042    * Construct a placement using a rotation matrix and translation.
0043    *
0044    * @param pRot          Rotation relative to the mother volume (may be
0045    *                      nullptr for identity).
0046    * @param tlate         Translation relative to the mother volume.
0047    * @param pCurrentLogical Logical volume being placed.
0048    * @param pName         Name of this physical volume.
0049    * @param pMotherLogical Mother logical volume (nullptr for world).
0050    * @param pMany         Overlapping flag (must be false for now).
0051    * @param pCopyNo       Copy number.
0052    * @param location      Corresponding OCCT placement location (optional).
0053    * @param pSurfChk      Run overlap check during construction if true.
0054    */
0055   G4OCCTPlacement(G4RotationMatrix* pRot, const G4ThreeVector& tlate,
0056                   G4LogicalVolume* pCurrentLogical, const G4String& pName,
0057                   G4LogicalVolume* pMotherLogical, G4bool pMany, G4int pCopyNo,
0058                   const TopLoc_Location& location = TopLoc_Location(), G4bool pSurfChk = false);
0059
0060   ~G4OCCTPlacement() override = default;
0061
0062   // ── G4OCCTPlacement-specific interface ────────────────────────────────────
0063
0064   /// Read access to the OCCT placement location.
0065   const TopLoc_Location& GetOCCTLocation() const { return fLocation; }
0066
0067   /// Replace the OCCT placement location.
0068   void SetOCCTLocation(const TopLoc_Location& location) { fLocation = location; }
0069
0070 private:
0071   TopLoc_Location fLocation;
0072 };
0073
0074 #endif // G4OCCT_G4OCCTPlacement_hh