ifcopenshell.api.alignment.distance_along_from_station

Module Contents

ifcopenshell.api.alignment.distance_along_from_station.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