include/G4OCCT/G4OCCTMaterialMap.hh

0001 // SPDX-License-Identifier: LGPL-2.1-or-later
0002 // Copyright (C) 2026 G4OCCT Contributors
0003
0004 /// @file G4OCCTMaterialMap.hh
0005 /// @brief Declaration of G4OCCTMaterialMap.
0006
0007 #ifndef G4OCCT_G4OCCTMaterialMap_hh
0008 #define G4OCCT_G4OCCTMaterialMap_hh
0009
0010 #include <G4String.hh>
0011
0012 #include <cstddef>
0013 #include <map>
0014
0015 class G4Material;
0016
0017 /**
0018  * @brief Maps STEP material names to Geant4 G4Material objects.
0019  *
0020  * Provides a strict, no-fallback lookup table from the material name strings
0021  * found in a STEP file (via the XDE material attribute) to the corresponding
0022  * Geant4 `G4Material` pointers.  The design follows the material-bridging
0023  * policy described in docs/material_bridging.md: every name encountered during
0024  * STEP import must have a registered entry; unresolved names produce a fatal
0025  * `G4Exception`.
0026  *
0027  * ### Usage
0028  * ```cpp
0029  * G4OCCTMaterialMap matMap;
0030  * matMap.Add("Al 6061-T6", G4NistManager::Instance()->FindOrBuildMaterial("G4_Al"));
0031  * matMap.Add("FR4",        myFR4Material);
0032  *
0033  * G4Material* mat        = matMap.Resolve("Al 6061-T6");  // returns the G4_Al pointer
0034  * G4Material* unknownMat = matMap.Resolve("Unknown");     // throws fatal G4Exception
0035  * ```
0036  */
0037 class G4OCCTMaterialMap {
0038 public:
0039   G4OCCTMaterialMap() = default;
0040
0041   /**
0042    * Register a mapping from a STEP material name to a Geant4 material.
0043    *
0044    * If @p stepName is already registered the previous entry is silently
0045    * overwritten.
0046    *
0047    * @param stepName STEP material name string (case-sensitive).
0048    * @param material Non-null pointer to a Geant4 material.
0049    */
0050   void Add(const G4String& stepName, G4Material* material);
0051
0052   /**
0053    * Look up the Geant4 material for a given STEP material name.
0054    *
0055    * @param stepName STEP material name to resolve.
0056    * @return Non-null pointer to the registered G4Material.
0057    * @throws G4Exception (severity FatalException) if @p stepName is not
0058    *         registered.
0059    */
0060   G4Material* Resolve(const G4String& stepName) const;
0061
0062   /**
0063    * Return true if @p stepName has been registered.
0064    */
0065   bool Contains(const G4String& stepName) const;
0066
0067   /**
0068    * Return the number of registered entries.
0069    */
0070   std::size_t Size() const { return fMap.size(); }
0071
0072   /**
0073    * Merge all entries from @p other into this map.
0074    *
0075    * If a STEP name already exists in this map, the entry from @p other
0076    * overwrites it (later files win on conflict).
0077    *
0078    * @param other Source map whose entries are merged into this one.
0079    */
0080   void Merge(const G4OCCTMaterialMap& other);
0081
0082 private:
0083   std::map<G4String, G4Material*> fMap;
0084 };
0085
0086 #endif // G4OCCT_G4OCCTMaterialMap_hh