`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.

Alignments are created with stationing referents. Each layout segment is assigned 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 a indicator of the position and the station, e.g. “P.C. (145+98.32)”

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)
Automatic definition of 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_stationing_referent(file: ifcopenshell.file, alignment: ifcopenshell.entity_instance, distance_along: float, station: float, name: str, positioned_product: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Adds an IfcReferent to the alignment with the Pset_Stationing property set.

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]
ifcopenshell.api.alignment.add_stationing_referent(model,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, include_referent: bool = True) → 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
include_referent – If True, an IfcReferent representing the ending point of the layout is included for IfcLinearElement layouts (i.e. business logic)

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, start_station: float = 0.0) → 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.

If geometric representations are created, the alignment stationing referent is also created using the start_station value. IfcReferent.ObjectPlacement is required for linear positiion elements and IfcLinearPlacement is defined relative to alignment curve geometry.

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
start_station – station value at the start of the alignment.

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 IfcOffsetCurveByDistances.
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 = 0.0) → ifcopenshell.entity_instance¶

Creates a new IfcAlignment with an IfcPolyline representation.

The IfcAlignment is aggreated to IfcProject

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

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 = 0.0) → 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

Returns:

Returns an IfcAlignment

ifcopenshell.api.alignment.create_from_csv(file: ifcopenshell.file, filepath: str) → 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
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 after this method to ensure the proper structure of the semantic and geometric definitions of the alignment

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¶

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.

Note

The current implementation does not account for station equations and assumes stationing is increasing along the alignment.

Parameters:

alignment – the alignment
station – station value

Returns:

distance along the horizontal alignment

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_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_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_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_referent_nest(file: ifcopenshell.file, alignment: ifcopenshell.entity_instance) → ifcopenshell.entity_instance¶

Searches for the IfcRelNest that contains IfcReferent. If one is not found, a empty IfcRelNests is created.

Parameters:

file
alignment – The IfcAlignment which hosts IfcReferent

Returns:

Returns the IfcRelNests.

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 automatically created at the start of each horizontal, vertical, and cant segment. 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 last segment so the “End of Alignment” name is returned * 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 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_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¶

Submodules¶

Package Contents¶

`ifcopenshell.api.alignment`¶