Module station 

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.

Re-exports

pub use certify::MAX_CERTIFIED_PANELS;

pub use certify::POINT_ROUNDING;

pub use certify::UNCERTIFIED_LENGTH;

pub use composite::CompositeBasis;

pub use composite::StationCurve;

pub use composite::StationPiece;

pub use composite::JOINT_TOLERANCE;

pub use frame_bound::piece_frame_bounds;

pub use frame_bound::BendBounds;

pub use frame_bound::FrameLaw;

pub use frame_bound::FrameLawBounds;

pub use frame_bound::FrameReading;

pub use frame_bound::StationFrameError;

pub use offset::offset_pieces;

pub use offset::StationOffset;

pub use offset::CUSP_TOLERANCE;

pub use offset::OFFSET_TOLERANCE;

pub use path_bound::point_bound_tolerance;

pub use path_bound::POINT_BOUND_UNSUPPORTED;

pub use seam::exact_station_seams2;

pub use seam::exact_station_seams3;

pub use seam::station_seams2;

pub use seam::station_seams3;

pub use seam::Mitre;

pub use seam::StationSeam;

pub use seam::MITRE_TOLERANCE;

pub use seam::SEAM_TANGENT_TOLERANCE;

pub use window::snapped_distance2;

pub use window::snapped_distance3;

pub use window::SEAM_WINDOW_AMBIGUOUS;

pub use window::SEAM_WINDOW_STRADDLED;

pub use window::WINDOW_CERTIFICATION;

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

DistanceInterval

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

SectionFrame

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

Enums

DistanceConvention

The convention a station basis is measured in (#285): the curve-evaluation contract’s, re-exported so a caller can name it. Which distance a CurveEvaluator measures.

Constants

KEEPS_UP_TOLERANCE

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

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.

Functions

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