Module composite 

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

A CompositeBasis is a run of StationPieces. Each piece is a span of an atomic 2D or 3D curve (StationCurve) between two distances in that curve’s own station measure, traversed forwards or backwards, and optionally carried by a rigid placement; or of an offset of such a span (StationCurve::Offset, #289), in the offset’s own length (see the offset module). This is the form of a composite curve relation this module measures: a format adapter or a graph compiler flattens its trims, sense flags, nested composites and curves placed at stations into pieces, and this module measures stations along them.

The same pieces as an owned, neutral value are axiolid-curve’s CurvePath (#290), which the curve-evaluation contract can see: CompositeBasis::from_path measures a path with its pieces borrowed from it, CompositeBasis::path hands the pieces out as one, and a StationPiece converts to a PathPiece and back (StationPiece::from_path_piece). The contract’s path_* queries read a path through the same CompositeBasis::section_on in the reference provider. A StationPiece borrows its curve so that a station on a graph relation, resolved again for every station of a run, copies none.

Distance convention

A composite measures stations as its pieces do, end to end: the distance of a point is the sum of the lengths of the pieces before it plus its distance into its own piece, each in its piece’s station measure. A piece measures in its atomic curve’s convention (the parent module): PLAN distance on an elevated or banked curve, arc length on every other curve (a 2D curve’s arc length is its plan length). A rigid placement keeps arc length; it keeps plan distance only when it keeps +Z, and a plan-measured piece placed by one that tilts +Z is refused by name (SectionFrame::carried). So:

• every piece plan-measured (elevated or banked curves, trimmed, reversed or placed upright): the composite is measured in plan distance, DistanceConvention::PlanDistance;
• every piece arc-length-measured (lines, conics, polylines, B-splines, intrinsic curves and chains, 2D or 3D, placed or not): the composite is measured in arc length, DistanceConvention::ArcLength3d. A composite of segments placed at stations of an elevated curve is measured in ITS OWN pieces’ arc length, whatever the base the segments were placed on;
• pieces of both kinds: refused by name, since no one distance runs through it.

A piece with no length is refused by name, as is an unbounded one: an untrimmed line inside a composite is its parameter domain [0, 1], as a composite directrix reads it (StationPiece::whole).

Joints

Consecutive pieces must meet: the end of one within JOINT_TOLERANCE * max(1, |p|) of the start of the next, |p| the largest coordinate magnitude of the joint. A joint whose pieces do not meet is refused by name: as a reversed piece where the next piece’s END meets the previous one (or the first piece’s start meets the second), which is a piece whose sense was not declared; as a gap otherwise.

Every interior joint is a seam under the #263 rule (the seam module): it is never smooth, since a declared continuity is not a guarantee in the data. A station within ARC_LENGTH_TOLERANCE * max(1, s) of a joint is ON it and reads the piece its SeamSide names at the joint’s own distance: SeamSide::Outgoing the piece that starts there, at its start; SeamSide::Incoming the piece that ends there, at its end. Each side reads its own piece’s point: two pieces that meet within the joint tolerance are not snapped onto one another. At the composite’s start and end only one piece exists, and both sides read it; likewise a piece is always read from the inside at its own ends, so a trim that starts on a seam of its curve never reads the part of the curve it trims away. The seams of a piece’s curve strictly inside the piece are the composite’s seams too, read by the curve’s own rule.

Reversed and placed pieces

A reversed piece is its span read from its end: the point at distance u into the piece is the curve’s at end - u, the side of a seam is swapped (the incoming piece of the composite is the curve’s outgoing one), and the frame’s tangent and lateral are negated while up is kept, which is the section frame of the curve traversed the other way (the reference-up frame and the planar frame are exactly that; a banked curve’s rolled section keeps its up and keeps the left rail on the left).

A placed piece’s frame is its curve’s carried by the placement (SectionFrame::carried): moved rigidly where the placement keeps +Z; where it tilts +Z, the reference-up frame of the placed curve’s own point and tangent, since the moved frame would not be the placed 3D curve’s own section frame. A plan-measured curve placed tilted is refused by name.

Open ends (#298)

A PathPiece may leave its end open (PathPiece::to_end, PathPiece::whole): a caller with no provider cannot state the length of an offset beside a gradient curve, a clothoid or a B-spline. Its end is resolved, when the path is read, to where the curve ends by THIS evaluator’s length, the number StationPiece::whole and so a graph compiler’s flattening measure the whole curve by: a line’s parameter domain end, a length read from stored data exactly, and otherwise the numerical estimate (an ellipse’s or a B-spline’s arc-length quadrature, an offset’s own table, to super::OFFSET_TOLERANCE). An open path is therefore read exactly as the stated path holding those numbers, which CompositeBasis::path hands back: bitwise as a station resolved on the same pieces. The distance arithmetic, which joint a station is on and how far into its piece, runs through those numbers; where a joint truly lies is CompositeBasis::joint_intervals’ certified interval, whose piece ends are the curve’s own (no station is refused for falling within it: a caller who must know a side certifies the joint, or snaps by a window).

Bounds at a parameter or a point (#304)

A PathPiece may start or end at a PathBound: a native parameter of its curve, or a point on it in the curve’s own coordinates, since the distance to an interior parameter of an ellipse or a B-spline is a quadrature a caller with no provider cannot state. A point is resolved to the one parameter naming it, or refused by name when it is off the curve or several parameters name it (the path-bound module). A parameter is resolved to the curve’s measure there, the number StationPiece::between_parameters measures by: exact where the arc length to it is read from stored data (a line, a circle, a polyline, a curve parameterised by its measure), the arc-length quadrature of an ellipse or a B-spline otherwise. A piece bounded at both ends IS the piece between those parameters, so it reads bitwise as the composite a graph compiler builds for a trim between them in the curve’s sense. A closed conic’s angle runs round, as in such a trim: from the start’s angle forwards by t1 - t0 where that is within one turn, else by it wrapped into one turn (a point’s angle lies in [0, 2 pi), so an end before the start crosses the seam; the same place at both ends is the whole turn). One bound beside a stated or open other end is folded into the first turn, [0, 2 pi), and an end not after the start lies a turn further. Offsets take no bound of their own (their base piece may carry one). Certification is unchanged: CompositeBasis::joint_intervals bounds each numerical piece’s length between the points the kernel reads as its ends, which for a bounded piece are the curve’s at its resolved measures.

Cutting a composite (#424)

A graph compiler that cuts a composite at two distances reads the pieces between them (CompositeBasis::pieces_between), each piece’s native parameters (StationPiece::native_span) and, where a measure is a quadrature, how far the cut lies from the distance asked (CompositeBasis::distance_interval_at); CompositeBasis::end_points are the points read at distance 0 and at the length.

Exactness

A station frame on a composite is exact, rounding aside, only where every piece up to and including the one it is read on is exact (CompositeBasis::frame_is_exact_at): those pieces’ lengths make the distance, and the read piece makes the frame. A piece is exact when its curve is a line and its placement, if any, was exact (StationPiece::frame_is_exact). Elsewhere the frame carries the tolerances of the parent module.

Structs

CompositeBasis

Pieces of curves laid end to end as one station basis; 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.

Enums

StationCurve

The atomic curve under a StationPiece.

Constants

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.