`ifcopenshell.api.alignment`¶

Manages alignment layout (semantic definition) and alignment geometry (geometric definition).

This API is defined in terms of the semantic definition of an alignment. The corresponding geometric definition is created and maintained automatically. The manditory zero length segment for the semantic and geometric definitions are automatically created and maintained.

Stationing is defined explicitly by calling add_stationing_referent() after the layout segments (and therefore the basis curve geometry) exist - create() does not add one. update_key_point_referents() assigns each layout segment a position referent that informs about the start point of the segment. An example is the point of curvature of a horizontal circular curve. The referent is nested to the segment representing the circular arc and is named with the alignment name and an indicator of the position and the station, e.g. “MyAlignment 145+98.32 (P.C.)”

This API does not determine alignment parameters based on rules, such as minimum curve radius as a function of design speed or sight distance.

This API is under development and subject to code breaking changes in the future.

Presently, this API supports:

Creating alignments, both horizontal and vertical, using the PI method. Alignment definition can be read from a CSV file.
Creating alignments segment by segment.
Automatic creation of geometric definitions (IfcCompositeCurve, IfcGradientCurve, IfcSegmentedReferenceCurve)
Explicit definition of stationing, including station equations and reverse (decreasing) stationing
Automatic definition of alignment transition point referents
Utility functions for printing business logical and geometric representations, as well as minimal geometry evaluations

Future versions of this API may support:

Defining alignments using the PI method, including transition spirals
Updating horizontal curve definitions by revising transition spiral parameters and circular curve radii
Updating vertical curve definitions by revising horizontal length of curves
Removing a segment at any location along a curve
Adding a segment at any location along a curve

Submodules¶

Package Contents¶

ifcopenshell.api.alignment.add_positioning_referent(file: ifcopenshell.file, name: str, alignment: ifcopenshell.entity_instance, distance_along: float, station: float, positioned_product: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Semantically defines the position of a product along an alignment by adding an IfcReferent to the alignment that defines the stationing system.

Parameters:

alignment – the alignment to receive the referent
distance_along – distance along the alignment basis curve
station – station value
name – name to assign to IfcReferent.Name, typically a stringized version of the station value
positioned_product – the product whose position is informed by the referent

Returns:

referent

Example:

alignment = model.by_type("IfcAlignment")[0]
pier = model.by_type("IfcBridgePart")[0]
ifcopenshell.api.alignment.add_positioning_referent(model,name="Pier 1 Sta 1+00",alignment=alignment,distance_along=0.0,station=100.0,positioned_product=pier)

ifcopenshell.api.alignment.add_stationing_referent(file: ifcopenshell.file, name: str, alignment: ifcopenshell.entity_instance, distance_along: float, station: float, incoming_station: float | None = None, has_increasing_station: bool | None = None, on_basis_curve: bool | None = None) → ifcopenshell.entity_instance¶

Adds an IfcReferent to the alignment that defines the stationing system.

Call this once with distance_along=0.0 to define the starting station, and again for each station equation. If the alignment has no geometry yet, the referent is placed with an IfcLocalPlacement at the global origin; once the basis curve has real segments it is placed with an IfcLinearPlacement at distance_along on that curve. create_representation() restates an origin-placed starting referent onto the curve when geometry is added later.

Parameters:

name – name to assign to IfcReferent.Name, typically a stringized version of the station value
alignment – the alignment to receive the referent
distance_along – distance along the alignment basis curve
station – station value
incoming_station – station value of the incoming segment, only set to specify a station equation
has_increasing_station – sets Pset_Stationing.HasIncreasingStation, which records the direction of stationing for the referents nested after this one. Leave None (the default) or pass True for the common case where station values increase with distance along; pass False on the starting referent of a reverse-stationed alignment, where station values decrease as distance along increases.
on_basis_curve – whether the referent is positioned on the basis curve or the alignment curve, if None the function will default to the basis curve

Returns:

referent

Example:

alignment = model.by_type("IfcAlignment")[0]
ifcopenshell.api.alignment.add_stationing_referent(model,name="1+00.0",alignment=alignment,distance_along=0.0,station=100.0)

ifcopenshell.api.alignment.add_vertical_layout(file: ifcopenshell.file, parent_alignment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Adds a vertical layout to a previously created alignment.

If this is the first vertical layout assigned to the parent_alignment the IFC CT 4.1.4.4.1.1 Alignment Layout - Horizontal, Vertical and Cant is followed. If this is the second or subsequent vertical layout assigned to the parent_alignment the IFC CT 4.1.4.4.1.2 Alignment Layout - Reusing Horizontal Layout is followed.

When the second vertical layout is added, the structure of the IFC model must transition from one concept template to the other. Specifically, the following occurs:

The first child IfcAlignment is created and is IfcRelAggregates with the parent alignment.
The first vertical layout is unassigned from the IfcRelNests of the parent alignment and is IfcRelNests to the new child alignment.
A second child IfcAlignment is created and it is IfcRelAggregates with the parent alignment.
The vertical layout is IfcRelNests to the second child alignment

For the third and subsequent vertical layouts, a new child alignment is created and aggregated to the parent alignment.

A zero segment length terminated IfcGradientCurve is created for the new vertical layout

Parameters:: parent_alignment – The parent alignment
Returns:: The new vertical layout, including the manditory zero length segment

ifcopenshell.api.alignment.add_zero_length_segment(file: ifcopenshell.file, layout: ifcopenshell.entity_instance) → bool¶

Adds a zero length segment to the end of a layout.

If the layout already has a zero length segment, nothing is changed.

Parameters:: layout – An IfcAlignmentHorizontal, IfcAlignmentVertical, IfcAlignmentCant, IfcCompositeCurve, IfcGradientCurve, IfcSegmentedReferenceCurve
Returns:: True if segment is added

ifcopenshell.api.alignment.create(file: ifcopenshell.file, name: str, include_vertical: bool = False, include_cant: bool = False, include_geometry: bool = True) → ifcopenshell.entity_instance¶

Creates a new alignment with a horizontal layout. Optionally, vertical and cant layouts can be created as well. The geometric representations are created as well, unless they are explicitly excluded. Zero length segments are added at the end of the layouts and geometric representations. The alignment is automatically aggreated to the project if it exists.

Use get_horizontal_layout(alignment), get_vertical_layout(alignment) and get_cant_layout(alignment) to get the: corresponding IfcAlignmentHorizontal, IfcAlignmentVertical, and IfcAlignmentCant layout entities.

If the alignment has Viennese Bend transition curves, create the segments in the cant layout before the horizontal layout using create_layout_segment(). The horizontal geometry in the Viennese Bend transition curves depends on the Viennese Bend cant parameters. create_layout_segment() automatically creates the geometric representation from the semantic definition. The horizontal segment geometric representation will fail if the cant segment is not defined.

This function does not define the alignment’s stationing. Call add_stationing_referent() once the layout segments (and therefore the basis curve geometry) exist to place the starting-station IfcReferent, and again for any station equations. Until stationing is defined, get_alignment_start_station() reports 0.0.

Parameters:

file
name – name assigned to IfcAlignment.Name
include_vertical – If True, IfcAlignmentVertical is created. IfcGradientCurve is created if include_geometry is True
include_cant – If True, IfcAlignmentCant is created. IfcSegmentedReferenceCurve is created if include_geometry is True
include_geometry – If True, the geometric representations are added

Returns:

Returns an IfcAlignment

ifcopenshell.api.alignment.create_as_offset_curve(file: ifcopenshell.file, name: str, offsets: collections.abc.Sequence[ifcopenshell.entity_instance], start_station: float = 0.0) → ifcopenshell.entity_instance¶

Creates a new IfcAlignment with an IfcOffsetCurveByDistances representation.

The IfcAlignment is aggreated to IfcProject

Parameters:

file
name – name assigned to IfcAlignment.Name
offsets – offsets from the basis curve that defines the offset curve, expected to be IfcPointByDistanceExpression.
start_station – station value at the start of the alignment

Returns:

Returns an IfcAlignment

ifcopenshell.api.alignment.create_as_polyline(file: ifcopenshell.file, name: str, points: collections.abc.Sequence[ifcopenshell.entity_instance], start_station: float | None = None) → ifcopenshell.entity_instance¶

Creates a new IfcAlignment with an IfcPolyline representation.

The IfcAlignment is aggreated to IfcProject

If start_station is given, a STATION IfcReferent named “<alignment name> <station>” (e.g. “MyAlignment 49+00.00”) is added at distance along 0.0 - the same naming convention update_key_point_referents() uses for its own referents, so every referent nested under an alignment is identifiable by name alone. If None (the default), no stationing referent is created.

Parameters:

file
name – name assigned to IfcAlignment.Name
points – sequence of points defining the polyline
start_station – station value at the start of the alignment, or None for no stationing referent

Returns:

Returns an IfcAlignment

ifcopenshell.api.alignment.create_by_pi_method(file: ifcopenshell.file, name: str, hpoints: collections.abc.Sequence[collections.abc.Sequence[float]], radii: collections.abc.Sequence[float], vpoints: collections.abc.Sequence[collections.abc.Sequence[float]] = None, lengths: collections.abc.Sequence[float] = None, start_station: float | None = None) → ifcopenshell.entity_instance¶

Create an alignment using the PI layout method for both horizontal and vertical alignments. If vpoints and lengths are omitted, only a horizontal alignment is created.

Parameters:

name – value for Name attribute
points – (X,Y) pairs denoting the location of the horizontal PIs, including start and end
radii – radii values to use for transition
vpoints – (distance_along, Z_height) pairs denoting the location of the vertical PIs, including start and end.
lengths – parabolic vertical curve horizontal length values to use for transition
start_station – if given, the starting station value. A STATION IfcReferent named “<name> <station string>” is added at distance along 0.0 once the geometry exists. If None (the default), no stationing referent is created and get_alignment_start_station() reports 0.0.

Returns:

Returns an IfcAlignment

ifcopenshell.api.alignment.create_from_csv(file: ifcopenshell.file, filepath: str, start_station: float | None = None) → ifcopenshell.entity_instance¶

Creates an alignment from PI data stored in a CSV file.

The format of the file is:

X1,Y1,R1,X2,Y2,R2 … Xn-1,Yn-1,Rn-1,Xn,Yn

D1,Z1,L1,D2,Z2,L2 … Dn-1,Zn-1,Ln-1,Dn,Zn

D1,Z1,L1,D2,Z2,L2 … Dn-1,Zn-1,Ln-1,Dn,Zn

…

where:

X,Y are PI coordinates

R is the horizontal circular curve radius

D,Z are VPI coordinates as “Distance Along”,”Elevation”

L is the horizontal length of a parabolic vertical transition curve

R1 and Rn, as well as L1 and Ln are placeholders and not used. They are recommended to have values of 0.0.

R2 and Rn-2 are the radii of the first and last horizontal curves.

L2 and Ln-2 are the length of the first and last vertical curves.

The CSV file contains one horizontal alignment, zero, one, or more vertical alignments

Parameters:

filepath – path the to CSV file
start_station – if given, the starting station value; a STATION IfcReferent is added at distance along 0.0 once the geometry exists. If None (the default), no stationing referent is created.

Returns:

IfcAlignment

ifcopenshell.api.alignment.create_layout_segment(file: ifcopenshell.file, layout: ifcopenshell.entity_instance, design_parameters: ifcopenshell.entity_instance) → numpy.array | None¶

Creates a new IfcAlignmentSegment using the IfcAlignmentParameterSegment design parameters. The new segment is appended to the layout alignment and the corresponding IfcCurveSegment is created in the geometric representation if it exists.

Parameters:

layout – The layout to receive the new layout segment. This parameter is expected to be IfcAlignmentHorizontal, IfcAlignmentVertical or IfcAlignmentCant
design_parameters – The parameters defining the segment. Expected to be the appropreate subclass of IfcAlignmentParameterSegment

Returns:

4x4 matrix at end of segment as np.array intended to be used as the start point geometry for the next segment or None if there is the geometric representation is not defined.

ifcopenshell.api.alignment.create_representation(file: ifcopenshell.file, alignment: ifcopenshell.entity_instance) → None¶

Creates the geometric representation of an alignment if it does not already exist. This function is intended to be used when a model has only the semantic definition of an alignment and you want to add the geometric representation.

If the alignments are complete, it is recommended that add_zero_length_segment is called before this method to ensure the proper structure of the semantic and geometric definitions of the alignment.

It is presumed that the alignment does not have any geometric representation. However, if the alignment has stationing defined, the referent defining the stationing is not related to the alignment geometry (it can’t be because the geometry doesn’t exist yet). When the geometric representation is created, the referent is updated to have an IfcLinearPlacement that references the basis curve geometry. This function assumes the referent defines the stationing at the start of the alignment, and therefore sets the IfcLinearPlacement.RelativePlacement.Location.DistanceAlong to 0.0.

Parameters:: alignment – The alignment to create the representation.

ifcopenshell.api.alignment.create_segment_representations(file: ifcopenshell.file, alignment: ifcopenshell.entity_instance) → None¶

Creates curve segment representations for the alignment for IFC CT 4.1.7.1.1.4. The alignment is expected to have representations for “Axis/Curve2D” (horizontal only) or “FootPrint/Curve2D” and “Axis/Curve3D” (horizontal + vertical/cant). There is the additional expectation that there is a 1-to-1 relationship between IfcAlignmentSegment and IfcCurveSegment. That is, no Helmert curves in the alignment which have a 1-to-2 relationship

Parameters:: alignment – The alignment to create segment representations.

ifcopenshell.api.alignment.distance_along_from_station(file: ifcopenshell.file, alignment: ifcopenshell.entity_instance, station: float) → float | None¶

Given a station, returns the distance along the horizontal alignment.

If the alignment does not have stationing defined with an IfcReferent, the start of the alignment is assumed to be at station 0.0. That is, the station is the distance along.

Station equations (where Pset_Stationing.IncomingStation is set on a referent) and reverse (decreasing) stationing (where Pset_Stationing.HasIncreasingStation is False) are taken into account.

For each STATION referent nested to the alignment, DistanceAlong (D) and the outgoing station (S, i.e. Pset_Stationing.Station) are read off and sorted by DistanceAlong. A direction sign is tracked while walking the sorted referents: it starts at +1 and is set to +1 or -1 at any referent that carries an explicit Pset_Stationing.HasIncreasingStation, so each referent’s region has a sign sigma of +1 (increasing) or -1 (decreasing). HasIncreasingStation may flip any number of times along the alignment - unrealistic, but valid IFC, and handled. The governing referent is the last one, by DistanceAlong, for which sigma * (station - S) >= 0, and the distance along is D + sigma * (station - S).

If the station falls within a gap introduced by a station equation - that is, it was skipped over by the equation - there is no distance along that corresponds to it, and None is returned.

Note that an overlap station equation - or a HasIncreasingStation direction reversal, which creates an equivalent overlap zone - causes a range of stations to correspond to two (or more) distinct distances along the alignment. This implementation returns the most downstream one (largest DistanceAlong), i.e. the match in the region following the last equation / reversal.

Parameters:

alignment – the alignment
station – station value

Returns:

distance along the horizontal alignment, or None if the station falls inside a station equation gap

Example:

alignment = model.by_type("IfcAlignment")[0] # alignment with start station 1+00.00
dist_along = ifcopenshell.api.alignment.distance_along_from_station(model,alignment=alignment,station=200.0)
print(dist_along) # 100.00

ifcopenshell.api.alignment.get_alignment(layout: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶: Returns the alignment that nests this layout

ifcopenshell.api.alignment.get_alignment_layout_nest(alignment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Searches for the IfcRelNest that contains IfcAlignmentHorizontal, IfcAlignmentVertical, or IfcAlignmentCant

Parameters:: alignment – the alignment
Returns:: Returns the IfcRelNests containing the alignment layout

ifcopenshell.api.alignment.get_alignment_layouts(alignment: ifcopenshell.entity_instance) → collections.abc.Sequence[ifcopenshell.entity_instance]¶: Returns the layout alignments nested to this alignment

ifcopenshell.api.alignment.get_alignment_segment_nest(layout: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Searches for the IfcRelNest that contains IfcAlignmentSegment

Parameters:: layout – an alignment layout, expected to be one of IfcAlignmentHorizontal, IfcAlignmentVertical, or IfcAlignmentCant
Returns:: Returns the IfcRelNests

ifcopenshell.api.alignment.get_alignment_start_station(file: ifcopenshell.file, alignment: ifcopenshell.entity_instance) → float¶: Returns the start station of the alignment. The starting station is defined by the first nested IfcReferent. This is interpreted to mean the first IfcReferent with an occurance of Pset_Stationing.Station, otherwise returns 0.0.

ifcopenshell.api.alignment.get_axis_subcontext(file: ifcopenshell.file) → ifcopenshell.entity_instance¶: Returns the IfcGeometricRepresentationSubContext for Model, Axis, MODEL_VIEW. If one does not exist, it is created.

ifcopenshell.api.alignment.get_basis_curve(alignment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Returns the basis curve for an alignment. This curve is the geometric representation that is used as the basis curve for vertical and cant alignments.

Parameters:: alignment – The alignment
Returns:: The geometric representation that is used as a basis curve, typically an IfcCompositeCurve, or None if the alignment does not have a representation

Example:

ifcopenshell.api.alignment.get_cant_layout(alignment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶: Returns the IfcAlignmentCant assocated with this alignment

ifcopenshell.api.alignment.get_child_alignments(alignment: ifcopenshell.entity_instance) → collections.abc.Sequence[ifcopenshell.entity_instance]¶

Returns the aggregated child alignments to this alignment per CT 4.1.4.4.1.2 Alignment Layout - Reusing Horizontal Layout

Example:

alignment = model.by_type("IfcAlignment")[0]
children = ifcopenshell.api.alignment.get_child_alignments(alignment)

ifcopenshell.api.alignment.get_curve(alignment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Returns the geometric representation curve for an alignment. An alignment without layouts will have a curve of type IfcPolyLine or IfcIndexedPolyCurve A horizontal only will have a curve of type IfcCompositeCurve A horizontal+vertical will have a curve of type IfcGradientCurve A horizontal+vertical+cant will have a curve of tyep IfcSegmentedReferenceCurve

Parameters:: alignment – The alignment
Returns:: The geometric representation of the alignemnt or None if the alignment does not have a representation

Example:

ifcopenshell.api.alignment.get_curve_segment(layout: ifcopenshell.entity_instance, segment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Returns the IfcCurveSegment associated with the given alignment segment. If the curve segment does not exist, None is returned.

Example:

horizontal = model.by_type("IfcAlignmentHorizontal")[0]
curve_segment = ifcopenshell.api.alignment.get_curve_segment(horizontal, alignment_segment)

ifcopenshell.api.alignment.get_curve_segment_transition_code(segment: ifcopenshell.entity_instance, next_segment: ifcopenshell.entity_instance, position_tolerance: float = 0.001) → str¶

Returns the IfcCurveSegment.Transition of segment based on a comparison of the position, ref. direction, and curvature at the end of the segment and the start of next_segment.

Parameters:

segment – segment for which the position curve is being being determined
next_segment – next segment
position_tolerance – tolerance used for evaluation positions. The default is 1mm

Returns:

the transition code

ifcopenshell.api.alignment.get_horizontal_layout(alignment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶: Returns the IfcAlignmentHorizontal assocated with this alignment

ifcopenshell.api.alignment.get_layout(segment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶: Retrieves the layout to which an alignment segment belongs.

ifcopenshell.api.alignment.get_layout_curve(layout: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Returns the representation curve for the layout. This will be an IfcCompositeCurve, IfcGradientCurve, or IfcSegmentReferenceCurve for IfcAlignmentHorizontal, IfcAlignmentVertical, or IfcAlignmentCant, respectively.

Parameters:: layout – An alignment layout
Returns:: The geometric representation curve

Example:

ifcopenshell.api.alignment.get_layout_segments(layout: ifcopenshell.entity_instance) → collections.abc.Sequence[ifcopenshell.entity_instance]¶

Returns the IfcAlignmentSegment nested to this alignment layout

Example:

horizontal = model.by_type("IfcAlignmentHorizontal")[0]
segments = ifcopenshell.api.alignment.get_layout_segments(horizontal)

ifcopenshell.api.alignment.get_mapped_segments(layout_segment: ifcopenshell.entity_instance) → collections.abc.Sequence[ifcopenshell.entity_instance]¶: From an IfcAlignmentSegment, returns the related IfcCurveSegment. Typically the sequence has one entity, however there will be two for Helmert curve

ifcopenshell.api.alignment.get_parent_alignment(alignment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Returns the parent alignment. When multiple vertical alignments share a horizontal alignment the horizontal alignment is nested to the parent alignment, a child alignment is aggregated to the parent alignment for each vertical alignment, and the vertical alignment is nested with its child alignment.

Example:

ifcopenshell.api.alignment.get_stationing_nest(file: ifcopenshell.file, alignment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Searches for the IfcRelNests that defines the alignment’s stationing scheme.

The returned nest is nested to the IfcAlignment and its RelatedObjects contains only the IfcReferent(s) (PredefinedType=”STATION”) that establish the alignment’s starting station and any station equations along it, as created by add_stationing_referent. It does not contain any other kind of referent (e.g. key-point referents from update_key_point_referents live in their own, separate IfcRelNests).

Parameters:

file
alignment – The IfcAlignment which hosts the stationing IfcReferent(s)

Returns:

Returns the IfcRelNests or None

ifcopenshell.api.alignment.get_vertical_layout(alignment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶: Returns the IfcAlignmentVertical assocated with this alignment

ifcopenshell.api.alignment.has_zero_length_segment(layout: ifcopenshell.entity_instance) → bool¶

Returns true if the layout ends with a zero length segment.

Parameters:: layout – An IfcAlignmentHorizontal, IfcAlignmentVertical, IfcAlignmentCant, IfcCompositeCurve, IfcGradientCurve, or IfcSegmentedReferenceCurve
Returns:: True if the zero length segment is present

ifcopenshell.api.alignment.layout_horizontal_alignment_by_pi_method(file: ifcopenshell.file, layout: ifcopenshell.entity_instance, hpoints: collections.abc.Sequence[collections.abc.Sequence[float]], radii: collections.abc.Sequence[float]) → None¶

Appends IfcAlignmentHorizontalSegment to a previously defined IfcAlignmentHorizontal using the PI layout method. The zero length segment is updated.

Parameters:

file – file
layout – An IfcAlignmentHorizontal layout
hpoints – (X, Y) pairs denoting the location of the horizontal PIs, including start (POB) and end (POE).
radii – radius values to use for transition

Returns:

None

ifcopenshell.api.alignment.layout_vertical_alignment_by_pi_method(file: ifcopenshell.file, layout: ifcopenshell.entity_instance, vpoints: collections.abc.Sequence[collections.abc.Sequence[float]], lengths: collections.abc.Sequence[float]) → None¶

Appends IfcAlignmentVerticalSegment to a previously defined IfcAlignmentVertical using the PI layout method. The zero length segment is updated.

Parameters:

file – file
layout – An IfcAlignmentVertical layout
vpoints – (distance_along, Z_height) pairs denoting the location of the vertical PIs, including start and end.
lengths – horizontal length of parabolic vertical curves

Returns:

None

ifcopenshell.api.alignment.name_segments(prefix: str, layout: ifcopenshell.entity_instance) → None¶

Sets the IfcAlignmentSegment.Name attribute using a prefix and sequence number (e.g. “H1” for horizontal, “V1” for vertical, “C1” for cant)

Parameters:

prefix – The naming prefix
layout – The layout alignment whose segments are to be named. This should be a IfcAlignmentHorizontal, IfcAlignmentVertical or IfcAlignmentCant

ifcopenshell.api.alignment.register_referent_name_callback(horizontal=None, vertical=None, cant=None)¶

Referents are created at the start of each horizontal, vertical, and cant segment by ifcopenshell.api.alignment.update_key_point_referents. The referents represent key points in the alignment layout such as Point of Curvature, Point of Tangent, and others. Different juristicions use different naming systems for these key points.

The referent name callback functions provide a customizable method for naming these referents. If a callback is registered, it is called when creating the referent name, otherwise the default naming is used.

The callback function signature is

def mycallback(prev_segment : entity_instance, segment : entity_instance) -> str:

The callback function returns a string that is used in the referent name for the referent at the start of segment. The callback must accomodate the following cases: * prev_segment = None and segment != None - this indicates the first segment so the “Beginning of Alignment” name is returned * prev_segment != None and segment == None - this indicates the last segment so the “End of Alignment” name is returned * prev_segment != None and segment != None - this indicates an intermediate segment so a name representitive of the transition is returned

Setting any or all of the callbacks to None causes the default naming to be used.

ifcopenshell.api.alignment.update_alignment_parameter_segment_tags(file: ifcopenshell.file, layout: ifcopenshell.entity_instance, label_end_tag: bool = False) → None¶

Sets IfcAlignmentParameterSegment.StartTag (and, optionally, EndTag) for every segment transition in an alignment layout. Unlike update_key_point_referents, this does not create any IfcReferent or IfcRelNests – it only mutates the StartTag/EndTag string attributes already present on each segment’s DesignParameters.

Every real segment’s StartTag is set to a computed tag describing the point where it begins, using the same label-and-station format as update_key_point_referents’ Name minus the alignment name (via _get_key_point_tag), e.g. “145+98.32 (P.C.)”. The first segment’s StartTag comes from the “Beginning of Alignment” boundary label.

EndTag is left untouched unless label_end_tag is True. When enabled, for each transition between two consecutive segments, the outgoing segment’s EndTag is set to the same tag as the incoming segment’s StartTag (they describe the same physical point), and the last segment’s EndTag is set from the “End of Alignment” boundary label.

Labels come from _get_segment_start_point_label – if a callback has been registered via register_referent_name_callback(), its output is used instead of the built-in labels, exactly as in update_key_point_referents.

Parameters:

layout – IfcAlignmentHorizontal, IfcAlignmentVertical, or IfcAlignmentCant
label_end_tag – if True, also sets EndTag on every real segment. If False (default), EndTag is left untouched.

Returns:

None – this function mutates segment.DesignParameters.StartTag/EndTag in place

Example:

horizontal = ifcopenshell.api.alignment.get_horizontal_layout(alignment)
ifcopenshell.api.alignment.update_alignment_parameter_segment_tags(model, horizontal)

ifcopenshell.api.alignment.update_end_point(file: ifcopenshell.file, curve: ifcopenshell.entity_instance)¶

Updates the IfcGradientCurve.EndPoint and IfcSegmentedReferenceCurve.EndPoint.

If the curve does not have a zero length segment, one is added. The EndPoint is then updated to match the placement of the zero length segment.

Parameters:: curve – The gradient curve or segmented reference curve
Returns:: None

ifcopenshell.api.alignment.update_fallback_position(file: ifcopenshell.file, lp: ifcopenshell.entity_instance)¶

Updates the IfcLinearPlacement.CartesianPoint fallback position.

If the CartesianPosition is not assigned to the IfcLinearPlacement, one will be created

Parameters:: lp – The linear placement
Returns:: None

ifcopenshell.api.alignment.update_key_point_referents(file: ifcopenshell.file, layout: ifcopenshell.entity_instance, rel_nests: ifcopenshell.entity_instance | None = None, clear: bool = False) → ifcopenshell.entity_instance¶

Creates IfcReferent key-point markers for every segment transition in an alignment layout.

Labels are derived from _get_segment_start_point_label (e.g. “P.C.”, “P.T.”, “P.O.B.”, “P.V.C.”, …), and combined with the alignment name and station to build the Name, e.g. “MyAlignment 145+98.32 (P.C.)”. Different jurisdictions use different naming systems for these key points – register_referent_name_callback() lets a caller override the default horizontal/vertical/cant labeling before calling this function; if a callback is registered, its output is used here instead of the built-in labels. Referents are nested to rel_nests, an IfcRelNests distinct from the layout’s segment nest (found via get_alignment_segment_nest) and from the alignment’s stationing nest (found via get_stationing_nest) – key-point referents never belong in either of those.

Parameters:

layout – IfcAlignmentHorizontal, IfcAlignmentVertical, or IfcAlignmentCant
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.
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.

Returns:

the IfcRelNests, with RelatedObjects sorted ascending by Pset_Stationing.Station

Example:

horizontal = ifcopenshell.api.alignment.get_horizontal_layout(alignment)
nest = ifcopenshell.api.alignment.update_key_point_referents(model, horizontal)

Example, with custom labels for a jurisdiction that doesn’t use the built-in abbreviations:

def my_horizontal_labels(prev_segment, segment):
    if prev_segment is None:
        return "Start"
    if segment is None:
        return "End"
    return "Curve Point"  # a name representative of the prev_segment -> segment transition

ifcopenshell.api.alignment.register_referent_name_callback(horizontal=my_horizontal_labels)
horizontal = ifcopenshell.api.alignment.get_horizontal_layout(alignment)
nest = ifcopenshell.api.alignment.update_key_point_referents(model, horizontal)
# nest.RelatedObjects[0].Name ends with "(Start)" instead of the default "(P.O.B.)"

ifcopenshell.api.alignment¶

Submodules¶

Package Contents¶

`ifcopenshell.api.alignment`¶