Module station 

Stations: a section frame at a distance along a curve (#241), re-exported on the same footing as curve and surface. Stations: a position at a distance along a curve, framed by the curve’s section (#241, ADR 0082).

A station names a place by a measure along a basis curve instead of by coordinates, the way an alignment is staked out. Reading it back is curve evaluation, so it lives here, beside the arc-length machinery it reuses (crate::arc_parameter).

Distance convention

The distance is measured in the basis curve’s own convention, from its start:

• an Elevated3 or a Banked3 is authored against PLAN distance, its own parameter, and a station on it is a plan distance (the curve-evaluation contract’s DistanceConvention::PlanDistance);
• every other curve, 2D or 3D, is measured by its arc length (for a 2D curve, the plan length).

The start is parameter 0 for a line, a circle, an ellipse, an intrinsic curve and a chain, and the first parameter of the domain for a polyline or a B-spline. A distance must lie in [0, L], L the curve’s length (station_length2, station_length3): one full turn for a closed conic, no limit for a line. A negative or non-finite distance, and one past L by more than ARC_LENGTH_TOLERANCE * max(1, L), is refused by name; one past it by less is read at L.

Section frame

SectionFrame carries the point and three unit axes: tangent along the curve, lateral to the LEFT of it, and up = tangent x lateral.

• A 2D curve lies in the plane z = 0: lateral is the left normal, up is +Z.
• A Banked3 is framed by its rolled section (crate::banked::banked_section): lateral towards the left rail head.
• Every other 3D curve, an Elevated3 included, gets the reference-up frame against +Z, the one ReferenceCurveEvaluator::frame_at returns: lateral is horizontal, up leans back with the grade. A vertical tangent has no such frame and is refused by name.

SectionFrame::frame returns the axes in the curve-evaluation provider’s layout: x the tangent, y up, z = -lateral (to the right), the layout the contract’s frame_at documents (#242).

The curve-evaluation provider reads a seam side through this module: ReferenceCurveEvaluator’s point_at_on, tangent_at_on and frame_at_on answer a measure on a seam (below) with station_section3_on (#286).

SectionFrame::plan is the vertical alternative: the tangent’s horizontal projection, the horizontal left normal and +Z, with grade and bank dropped.

Explicit orientation (#246)

SectionFrame::oriented turns a section frame by an explicit axis and reference direction given as components in that frame, (tangent, lateral, up), not in world coordinates: a linear placement’s axes “are relative to the curve used for linear referencing …, maintaining the relationship to the tangent of the curve” (buildingSMART IFC 4.3, IfcAxis2PlacementLinear), whose local X, Y, Z are the tangent, the left lateral and up. The axis is the oriented up, exact; the reference direction is made perpendicular to it (Gram-Schmidt, axis primary) and becomes the oriented tangent. The point does not move.

Seams (#263)

A curve made of pieces has two frames where a polyline turns at a vertex, a B-spline at a corner knot, an elevated curve’s grade breaks or a banked curve’s cant jumps. A station within ARC_LENGTH_TOLERANCE * max(1, s) of such a seam is ON it: it is read at the seam’s own distance, from the piece that starts there (SeamSide::Outgoing, station_section2 and station_section3) or from the side station_section2_on and station_section3_on are given. station_seams2 and station_seams3 say where the seams are without evaluating the curve, and Mitre is the plane a run of sections crossing one stands in; see seam for both. At the curve’s start and end there is one piece, and both sides read it.

Placing at a station (#264)

SectionFrame::placement is the rigid motion a node placed at a station is moved by: local x, y, z onto the tangent, the left lateral and up, the origin onto the point (a linear placement’s reading). station_frame_is_exact2 and station_frame_is_exact3 say whether that frame is exact (a line) or carries the tolerances below. SectionFrame::carried is the frame a station on the placed curve has (#285): the source’s moved where the placement keeps +Z, the placed curve’s own reference-up frame where it tilts it.

Composite bases (#285)

CompositeBasis measures stations along pieces of atomic curves laid end to end (StationPiece: a span of a curve, reversed or placed), the neutral form of a composite curve relation. The distance runs through the pieces in their common convention, every joint is a seam read by the rule above, and a frame is exact only where every piece up to the one read is; see composite.

Offset bases (#289)

A piece may be an offset of a base piece (StationOffset), measured in its OWN length from its start: arc length, or its own plan length beside an elevated or banked curve. offset_pieces offsets pieces laid end to end, one offset piece per span between seams; see offset for the closed forms, the numerical reading and the refusals.

Certified joint distances and seam-snapping windows (#294)

A composite’s joints lie at the running sum of its pieces’ lengths, and some of those lengths are quadratures (an offset other than a line or a circle beside one, an ellipse, a B-spline). certify bounds each from both sides, so CompositeBasis::joint_intervals answers every joint with a DistanceInterval that contains its true distance, no wider than a requested tolerance; a sum of stored lengths is a point. The curve-evaluation provider hands them out as path_joint_distances.

A station may carry a seam-snapping window, wider than the arc-length tolerance: snapped_distance2, snapped_distance3 and CompositeBasis::snapped_distance read a station within its window of exactly one seam whose frame may jump at that seam, using the certified intervals where a seam’s distance is numerical, and refuse a window holding two seams or with one on its edge by name; see window.

Accuracy contract

The point and frame are the exact curve’s at a measure within ARC_LENGTH_TOLERANCE * max(1, s) of s where the arc length is numerical (a conic, a polyline is exact, a B-spline), at s itself on a line, an intrinsic curve, a chain and an elevated or banked curve (their parameter is the measure), each evaluated to its own stated accuracy (Gauss-Legendre quadrature for intrinsic positions, ADR 0060). A station on a seam is read at the seam’s distance, within the same tolerance of its own.

Modules

certify

Certified lengths of station pieces, and so certified joint and seam distances (#294, ADR 0082 amendment).

composite

A composite station basis: stations along pieces of curves laid end to end (#285, ADR 0082 amendment).

frame_bound

Certified bounds on a section frame law’s derivatives in station distance (#247, ADR 0082 amendment).

offset

Offset pieces of a station basis: the curve beside a span of an atomic curve, measured in its own length (#289, ADR 0082 amendment).

path_bound

Curve-path piece bounds given as a native parameter or a point (#304, ADR 0082 amendment).

seam

Seams of a station’s basis curve: where they lie, which piece a station on one reads, and the mitre between the two (#263, ADR 0082 amendment).

window

Seam-snapping windows (#294, ADR 0082 amendment).

Structs

CompositeBasis

Pieces of curves laid end to end as one station basis; see the module documentation.

DistanceInterval

A distance certified to lie in [lower, upper]: what CurveEvaluator::path_joint_distances returns for each joint of a curve path.

FrameLaw

Certified bounds on the frame law along a station basis (#316): an atomic curve or a CompositeBasis, over spans that cross no seam.

FrameLawBounds

Certified suprema, over a span of station distance, of the derivatives of a section frame law in that distance; see the module documentation.

Mitre

The plane a section stands in where a run crosses a seam whose tangents differ; see the module documentation.

SectionFrame

A point on a curve and the section axes there: tangent, left lateral and up, unit and right-handed (up = tangent x lateral).

StationOffset

An offset of one base piece, measured in its own length; see the module documentation.

StationPiece

One piece of a CompositeBasis: the span [start, end] of an atomic curve, in that curve’s station measure, traversed forwards or backwards, optionally placed by a rigid motion; see the module documentation.

StationSeam

A place inside a curve where two of its pieces meet; see the module documentation.

Enums

DistanceConvention

Which distance a CurveEvaluator measures.

FrameReading

Which section frame a run places its sections in.

StationCurve

The atomic curve under a StationPiece.

Constants

CUSP_TOLERANCE

Smallest speed of an offset in its base’s direction, relative to the base’s, that is not a cusp; also the smallest scale (r - a) / r of an offset circle that has not collapsed.

JOINT_TOLERANCE

Relative tolerance within which two consecutive pieces of a CompositeBasis meet: their joint points may be JOINT_TOLERANCE * max(1, |p|) apart, |p| the joint’s largest coordinate magnitude.

KEEPS_UP_TOLERANCE

How far a rigid placement’s image of +Z may lean and still count as keeping +Z (SectionFrame::carried): rounding only.

MAX_CERTIFIED_PANELS

Most panels one certified length may use.

MITRE_TOLERANCE

Smallest cosine of half the turn at a seam, |t_in + t_out| / 2, that a Mitre admits; below it the tangents nearly reverse and the mitre plane would stretch a section without bound.

OFFSET_TOLERANCE

Relative tolerance of a numerical offset’s own length and its inverse: OFFSET_TOLERANCE * max(1, L) in the length unit. An estimate, as the quadrature’s agreement test is.

ORIENTATION_TOLERANCE

Largest sine of the angle between an orientation’s axis and reference direction that still counts as parallel (SectionFrame::oriented); the graph refuses the same pairs when a station is pushed.

PATH_POINT_AMBIGUOUS

The input a point bound of a curve path piece (#304) is refused for when several parameters of the curve name it: a curve that passes through it more than once, or the seam of a closed curve other than a circle or an ellipse (whose angle runs round).

PATH_POINT_OFF_CURVE

The input a point bound of a curve path piece (#304) is refused for when it does not lie on the piece’s curve within the joint tolerance 1e-9 * max(1, |p|): a provider never projects it onto the curve.

POINT_BOUND_UNSUPPORTED

The input a point bound on a curve this evaluator does not invert is refused for.

POINT_ROUNDING

The rounding error of a point evaluated in closed form, relative to the largest coordinate magnitude of the curve’s data, the point and the displacement (at least 1): about 45 units in the last place, several times what a de Boor or conic evaluation and a frame accumulate.

SEAM_TANGENT_TOLERANCE

Largest angle, in radians, between the incoming and outgoing tangents of a seam that still counts as one direction: no mitre is cut there.

SEAM_WINDOW_AMBIGUOUS

The input a window holding two seams is refused for.

SEAM_WINDOW_STRADDLED

The input a seam straddling a window’s edge is refused for.

UNCERTIFIED_LENGTH

The input a length no certified bound here reaches is refused for.

WINDOW_CERTIFICATION

How finely a seam’s distance is certified for a window: the certified interval is at most this fraction of the window wide.

Functions

exact_station_seams2

station_seams2, refusing a curve with a seam whose distance is not read from stored data alone.

exact_station_seams3

station_seams3, refusing a curve with a seam whose distance is not read from stored data alone.

offset_pieces

The offset of pieces laid end to end (a composite’s, in its measure) by law: one StationOffset piece per span of a base piece between the seams of its curve, so every seam and joint of the base is a joint of the offset. A OffsetLaw::Linear law runs from its start at the first piece’s start to its end at the last piece’s end, linearly in the base’s measure.

piece_frame_bounds

Certified bounds on the derivatives, in station distance, of the section frame piece presents over [from, to] (distances into the piece, in the composite’s direction), read as reading; see the module documentation.

point_bound_tolerance

How far from its curve a point bound may lie: the joint tolerance at the point.

snapped_distance2

The distance a station at distance along a 2D curve, with the seam-snapping window, is read at; see the module documentation.

snapped_distance3

snapped_distance2 along a 3D curve.

station_frame_is_exact2

Whether a station frame on this 2D curve is exact (#264): its point and axes at the station’s distance itself, in closed form, rounding aside, with no quadrature or root find behind them.

station_frame_is_exact3

station_frame_is_exact2 for a 3D curve: only a line.

station_length2

The length a station on a 2D curve is measured against: None for a line (unbounded), one turn for a circle or an ellipse, the arc length of its domain for a polyline or a B-spline, the stated length of an intrinsic curve or a chain.

station_length3

The length a station on a 3D curve is measured against, as station_length2; an elevated curve’s is its plan’s, a banked curve’s the span of its cant law.

station_seams2

The seams of a 2D curve, every one located (see the module documentation); a B-spline’s corner knots by quadrature, flagged not exact.

station_seams3

The seams of a 3D curve, every one located; see station_seams2.

station_section2

The section of a 2D curve at arc length distance from its start; see the module documentation for the conventions.

station_section3

The section of a 3D curve at distance from its start: plan distance on an elevated or banked curve, arc length on any other; see the module documentation.

station_section2_on

station_section2 reading side of a seam the station lies on (see the module documentation); off a seam the side does not matter.

station_section3_on

station_section3 reading side of a seam the station lies on (see the module documentation); off a seam the side does not matter.