Allows key point referents to be nested to the parent alignment in the reusing horizontal scenario

src/ifcopenshell-python/ifcopenshell/api/alignment/update_key_point_referents.py

@@ -115,11 +115,19 @@ def update_key_point_referents(
     get_stationing_nest) -- key-point referents never belong in either of those.
 
     :param layout: IfcAlignmentHorizontal, IfcAlignmentVertical, or IfcAlignmentCant
-    :param rel_nests: an existing IfcRelNests to (re)populate; its RelatingObject must be the
-        IfcAlignment that nests `layout` (TypeError is raised otherwise). If omitted, a new
-        IfcRelNests is always created and related to that IfcAlignment -- there is no implicit
-        search for or reuse of a previously created nest. Callers who want to regenerate into an
-        existing nest must pass it back in explicitly via `rel_nests`.
+    :param rel_nests: an existing IfcRelNests to (re)populate; its RelatingObject must be an
+        IfcAlignment (TypeError is raised otherwise), but need not be the IfcAlignment that
+        directly nests `layout` -- passing an ancestor's own IfcRelNests is supported
+        specifically so that a vertical/cant layout living under a child IfcAlignment (per CT
+        4.1.4.4.1.2, once a second vertical layout is added) can still have its key-point
+        referents named after and nested to the top-level parent alignment, matching how the
+        alignment's horizontal key points are named, rather than a generic "Child of X" name.
+        When `rel_nests` is given, `rel_nests.RelatingObject` -- not `layout`'s own direct
+        parent -- is used for both the created referents' Name and the returned IfcRelNests. If
+        omitted, a new IfcRelNests is always created and related to `layout`'s own direct
+        parent alignment -- there is no implicit search for or reuse of a previously created
+        nest. Callers who want to regenerate into an existing nest must pass it back in
+        explicitly via `rel_nests`.
     :param clear: if True, deletes all IfcReferent currently in rel_nests.RelatedObjects (and their
         Pset_Stationing) before regenerating. If False (default), new referents are appended to
         whatever already exists -- no deduplication.
@@ -155,17 +163,25 @@ def update_key_point_referents(
             f"Expected entity type to be one of {[_ for _ in expected_types]}, instead received {layout.is_a()}"
         )
 
-    alignment = ifcopenshell.api.alignment.get_alignment(layout)
-    if alignment is None:
+    layout_alignment = ifcopenshell.api.alignment.get_alignment(layout)
+    if layout_alignment is None:
         raise ValueError(f"{layout.is_a()} #{layout.id()} is not nested under an IfcAlignment.")
 
+    # `alignment` is used below for referent naming (and as the fallback-placement basis) --
+    # it defaults to layout's own direct parent, but an explicitly passed rel_nests overrides
+    # it with rel_nests.RelatingObject instead (see the rel_nests docstring above). Station
+    # computation always uses layout_alignment, unaffected by this -- get_alignment_start_station
+    # already walks up to the true top-level alignment's own stationing referent regardless of
+    # which (possibly child) alignment it's given.
     if rel_nests is not None:
         if not rel_nests.RelatingObject.is_a("IfcAlignment"):
             raise TypeError(
                 f"Expected rel_nests.RelatingObject to be IfcAlignment, instead received "
                 f"{rel_nests.RelatingObject.is_a()}"
             )
+        alignment = rel_nests.RelatingObject
     else:
+        alignment = layout_alignment
         rel_nests = file.createIfcRelNests(
             GlobalId=ifcopenshell.guid.new(), RelatingObject=alignment, RelatedObjects=()
         )
@@ -185,7 +201,7 @@ def update_key_point_referents(
         )
         return rel_nests
 
-    start_station = ifcopenshell.api.alignment.get_alignment_start_station(file, alignment)
+    start_station = ifcopenshell.api.alignment.get_alignment_start_station(file, layout_alignment)
     curve = ifcopenshell.api.alignment.get_layout_curve(layout)
     is_horizontal = layout.is_a("IfcAlignmentHorizontal")