Skip to main content

Module derive

Module derive 

Source
Expand description

Deriving a placement frame from the basis curve.

The cached CartesianPosition path resolves a placement without any computation. When an authoring tool omits it, the frame has to be derived by evaluating the basis curve at the authored distance, which is computation and therefore an opt-in capability under ADR 0004.

This module holds the IFC-side half: it turns an IfcLinearPlacement into a curve, a measure and an offset, then asks an injected [CurveEvaluator] for the frame. It never picks an evaluator, and ifc-geometry links no implementation.

§What an IfcParameterValue means here

IfcPointByDistanceExpression.DistanceAlong is an IfcCurveMeasureSelect: a length, or a parameter of the basis curve (IFC4.3 ADD2 8.9.3.48). A parameter is only as defined as the basis curve’s parameterisation:

  • IfcPolyline counts one per segment (8.9.3.51), and so does a line-only IfcIndexedPolyCurve (see the polyline submodule); the neutral polyline uses the same convention, so the parameter crosses unchanged. Only where every segment is one unit long does it equal a length.
  • IfcGradientCurve takes the parameter of its BaseCurve (8.9.3.34.1), an IfcCompositeCurve of IfcCurveSegments. A composite accumulates the parametric ranges of its parent curves (8.9.3.20.1, after ISO 10303-42), which are not lengths (an IfcCircle counts its angle, 8.9.3.18.1; an IfcClothoid u = s / (A sqrt(pi)), 8.9.3.19.1), while IfcCurveSegment (8.9.3.28.1) states that no parametric space is yet defined for its parent curves and measures segments by length. The parameter of an alignment centreline is therefore undefined, and is refused by name rather than handed to an evaluator, whose own parameter on that curve is plan distance (axiolid ADR 0082), a different quantity. An IfcAlignment basis names the same centreline and is refused alike. This matches the station lowering, which refuses a parameter too.

§The derived frame (#355)

IFC4.3 ADD2 fixes the frame, so it is built here from the evaluator’s point and unit tangent alone, never from the evaluator’s own axis labelling. That labelling is x the tangent, y up and z to the right (the contract’s text, corrected by axiolid/kernel#242 to what the reference provider always returned), so the frame below is (x, -z, y) of it for a reference-up evaluator; reading only x keeps the frame right for any provider whatever it calls its other axes, and a banked curve’s roll never reaches it.

  • x is the tangent: IfcAxis2PlacementLinear.RefDirection defaults to it (8.9.3.4), and OffsetLongitudinal runs along it.
  • y is the horizontal left, normalise(Z x tangent): IfcPointByDistanceExpression.OffsetLateral is horizontal and “positive values indicate to the left of the basis curve”.
  • z = x x y is up, perpendicular to the tangent in its vertical plane: that is where OffsetVertical points, and what Axis defaults to, “the normal vector of the basis curve that lies within the vertical plane containing the RefDirection”.

Explicit Axis/RefDirection on the placement are components in that (tangent, left, up) frame (8.9.3.4), the reading the station lowering uses too, and derive_linear_placement_transform composes them.

§Tangent discontinuities (#409)

IFC4.3 ADD2 8.9.3.48.3: “If DistanceAlong coincides with a point of tangential discontinuity (within precision limits), then the tangent of the previous segment governs.” The derivation reads such a placement as the station lowering does (lower::station, #346): the seams are read from the basis curve’s stored data, a DistanceAlong within the model’s declared Precision (capped at 1 mm) or rounding of one is snapped to the seam’s own distance, and the evaluator is asked for the frame there with [CurveEvaluator::frame_at_on] and [SeamSide::Incoming]. Off a seam it is asked side-lessly, as before. The derived placement thus equals the lowered station’s frame on and near a seam, and Verify compares a cache against the incoming frame.

A native parameter on a polyline vertex is located by its distance, an exact running sum of edge lengths, and read at that distance: the contract lets a provider refuse the incoming side of a polyline’s native parameter, and the distance names the same place.

An evaluator that does not implement seam sides refuses Incoming with SEAM_SIDE_UNSUPPORTED; that is GeometryError::SeamSideUnsupported naming the placement, its basis curve and the seam, never the outgoing frame in its place.

§Curve-relation bases (#418)

A plain IfcCompositeCurve, an IfcTrimmedCurve (and the other composites and surface curves the curve lowering reads as relations), and a composite of IfcCurveSegments placed by IfcAxis2PlacementLinears lower to a curve relation, which the station lowering measures end to end through its pieces (#346). The derivation reads the same basis as Axiolid’s neutral CurvePath (axiolid/kernel#290), built from the stored relation in the path submodule, through the evaluator’s path_* queries: [CurveEvaluator::path_frame_at] off a seam, and [CurveEvaluator::path_frame_at_on] with [SeamSide::Incoming] on one. Every joint of the relation is a seam, as for the station, so a DistanceAlong within precision of a joint reads the segment that ends there, IFC’s previous segment. The distance is the relation’s: arc length, or plan distance where every piece is a gradient curve. A native parameter is refused by name: a relation’s pieces have no parameter that runs through them, and the station lowering refuses one too.

An evaluator that does not implement curve paths refuses them with CURVE_PATH_UNSUPPORTED; that is GeometryError::CurvePathUnsupported naming the placement and its basis curve, never a frame read on one piece in its place. An offset curve is read the same way (#414): its pieces are PathCurve::Offsets of its basis’s spans, measured in the offset’s own length, as the station lowering measures it. Where that length is a quadrature (an offset beside a gradient curve, a spiral or a B-spline, and a relation with an ellipse or a B-spline piece), the piece is handed over open-ended and the evaluator resolves its end with its own length (#427, axiolid/kernel#298); a placement within the model’s precision of a joint after it is located by the evaluator’s certified joint distances and read from the incoming piece, as the kernel reads the same basis’s station (#423). The path submodule states the rule and its typed refusals; nothing is derived from an estimate this crate makes.

§Which distance

DistanceAlong on an alignment centreline is plan distance (an IfcGradientCurve takes its BaseCurve’s measure, 8.9.3.34.1), and arc length along a straight-segment curve. An evaluator states which distance it measures per curve ([CurveEvaluator::distance_convention]); one that measures something else is refused rather than trusted.

§Checking a cached position (#354)

IfcLinearPlacement.CartesianPosition is, in IFC4.3’s words, “an optional fallback for the RelativePlacement attribute” for importers that do not support linear placement. The linear expression is authoritative. When a caller supplies an evaluator, CachedPositionPolicy decides what happens to a cached position; see there.

Enums§

CachedPositionPolicy
What lowering does with an IfcLinearPlacement’s cached CartesianPosition when the caller supplies a [CurveEvaluator] (#354).

Functions§

basis_curve_path
The basis curve of placement read as the neutral [CurvePath] its derivation evaluates (#418): a plain IfcCompositeCurve, an IfcTrimmedCurve or a composite of segments placed at stations, as the station lowering flattens it, each segment’s placement framed through evaluator (module documentation).
cached_position_tolerance
The tolerance a cached CartesianPosition is checked at, in metres (#354).
derive_linear_placement_transform
Resolve an IfcLinearPlacement from its linear expression alone, in metres, ignoring any cached CartesianPosition.
derive_placement_transform
Resolve an IfcPointByDistanceExpression by evaluating its basis curve.