`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, element: ifcopenshell.entity_instance, basis_curve: ifcopenshell.entity_instance, distance_along: float, station: float, name: str) → ifcopenshell.entity_instance¶

Adds an IfcReferent to the element with the Pset_Stationing property set. If element is an IfcAlignment, IfcReferent.PredefinedType is set to “STATION”, otherwise “POSITION”

Parameters:

element – the element to receive the referent, expected to be an IfcAlignment or IfcAlignmentSegment
basis_curve – the basis curve for positining
distance_along – distance along the basis curve
station – station value
name – name to assign to IfcReferent.Name, typically a stringized version of the station value

Returns:

referent

Example:

alignment = model.by_type("IfcAlignment")[0]
basis_curve = ifcopenshell.api.alignment.get_basis_curve(alignment)
ifcopenshell.api.alignment.add_stationing_referent(model,entity=alignment,basis_curve=basis_curve,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.create(file: ifcopenshell.file, name: str, include_vertical: bool = False, include_cant: bool = False, start_station: float = 0.0) → ifcopenshell.entity_instance¶

Creates a new IfcAlignment with an IfcRelNests nesting an IfcReferent (for stationing) and IfcAlignmentHorizontal. The nest relationship can optionally include IfcAlignmentVertical and IfcAlignmentCant. Geometric representations for the alignment layouts (IfcCompositeCurve, IfcGradientCurve, IfcSegmentedReferenceCurve) are created as well.

Zero length segments are added at the end.

The IfcAlignment is aggreated to IfcProject

Use get_horizontal_layout(alignment) to get the IfcAlignmentHorizontal layout.

Parameters:

file
name – name assigned to IfcAlignment.Name
include_vertical – If True, IfcAlignmentVertical and IfcGradientCurve are created
include_cant – If True, IfcAlignmentCant and IfcSegmentedReferenceCurve are created
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¶

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

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.

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_layouts(alignment: ifcopenshell.entity_instance) → collections.abc.Sequence[ifcopenshell.entity_instance]¶: Returns the layout alignments nested to this alignment

ifcopenshell.api.alignment.get_alignment_station(file: ifcopenshell.file, alignment: ifcopenshell.entity_instance) → float¶: Returns the start station of the alignment. If the alignment is nested by an IfcReferent the referent is checked for PredefinedType of STATION and an occurance of Pset_Stationing.Station, otherwise start station is taken to be 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. 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_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_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, or IfcAlignmentCant
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¶

Submodules¶

Package Contents¶

`ifcopenshell.api.alignment`¶