OpticalPath
OpticalPath is the ordered optical-distance axis that ties fiber metadata to DAS data. It describes the media in which the light travels as well as the corresponding geographical location, coupling conditions, and annotations. To do this, the OpticalPath has independent interval tracks:
- Optical components describe fiber, connectors, splices, and terminators.
- Geometry describes physical coordinates along optical distance.
- Coupling conditions describe how the fiber is acoustically coupled.
- Annotations describe named or categorized intervals.
These tracks are independent because their boundaries often differ. A cable segment, trench section, geometry vertex, and quality note may all start and stop at different optical distances.
The tracks come in three kinds, and every track’s rules follow from its kind. Optical components are the tiling track: they cover the whole path exactly once — no gaps, no overlaps — so total component length is the canonical optical length. Geometry and coupling are function tracks: at most one value at any optical distance; coverage may be partial (uncovered distance is undefined, not invalid), and overlap raises. Annotations are the set track: labeled intervals that overlap freely. The acquisition-side DistanceMap is a function track over the channel axis in the same sense.
Geometry
Geometry objects map optical distance onto coordinates: paired distance and coordinates arrays of equal length, at least two strictly increasing distances, interpreted using the inventory CRS. Coverage is the span of the distance array (half-open); there is no separate length field.
Interpolation between listed points is piecewise linear in the inventory CRS, so control points must be dense enough that linearity is faithful; where linear-in-degrees breaks down — near the antimeridian or poles, or over long sparse segments — declare a projected local CRS in the envelope. A coil, slack loop, or clump is a segment whose coordinates repeat while distance advances; every channel in it resolves to the coil’s location. Vertical coordinates (elevation, z) are positive-up against the CRS vertical datum.
Geometries act as piecewise segments: interpolation never crosses segments, and uncovered distance — surveyed boreholes separated by unmapped lead cable — is undefined, enriching as missing values. Loops that double back (a fiber running down and up the same borehole) are represented directly: optical distance keeps increasing while coordinates retrace. Segments may not overlap (check() raises); a recalibration replaces the old segment — a correction.
Geometry describes where the path is, not what optical material is present, so components, coordinates, and calibrations evolve independently.
Coupling Conditions
CouplingCondition objects describe the acoustic or mechanical environment over optical-distance intervals. They capture properties such as coupling_type, surrounding medium, attachment, and depth.
coupling_type uses a controlled vocabulary: conduit, trench, outside_borehole_casing, wireline, surface, aerial, coiled, or other. Use medium and attachment for more specific details such as soil, steel, loose, clamped, bonded, or direct burial.
Each condition covers the half-open interval [start_distance, end_distance) — the same idiom as time epochs, and the two numbers read directly off OTDR or interrogator displays; coverage and overlap follow the function-track rules above. Layered descriptions (“in conduit and under the road”) belong on annotations. depth is positive-down from the local surface.
Coupling need not follow component or geometry boundaries: one fiber segment can include a buried trench interval, a conduit interval, and a loose surface run.
Annotations
OpticalPathAnnotation objects attach key/value facts to optical-distance intervals. They are the extension space for anything that should travel with the path but does not belong in geometry or coupling: operational zones, quality flags, field observations, analysis regions, and user-defined variables of any kind.
Each annotation states a group — the name of the variable — and a value over its interval. The type of the value decides the shape of the group:
| Value | Group shape | Overlap | Uncovered distance |
|---|---|---|---|
true (bool) |
membership flag | allowed | false |
"granite" (str) |
single-valued category | raises | missing |
1.2 (numeric) |
single-valued measurement | raises | missing |
A bare flag is simply a boolean value, so group: noisy with no value states membership over its interval. Overlap is legal exactly where it is meaningful: two intervals can both flag noisy, but one rock_type cannot be granite and shale at the same distance, so single-valued groups raise on overlap. Within a group every value must be the same kind.
Annotations cover [start_distance, end_distance); equal start and end marks a point.
Annotations And Typed Tracks
Coupling is a typed track rather than an annotation group, and the distinction is deliberate. A typed track carries guarantees an open key/value space cannot: a controlled vocabulary (a mistyped coupling_type raises), correlated fields bundled into one record (this trench, with soil, direct-buried, stated together and unable to drift apart), and a fixed place in the standard, so a consumer can rely on coupling existing without discovering each producer’s naming conventions.
Annotations are therefore the proving ground, and typed tracks are what a vocabulary graduates into once it proves universal. Anything can start life as an annotation group without a schema change; the ones that turn out to be shared across the community can later become tracks of their own.
The OpticalPath API makes it simple to update optical paths when breaks occur, segments are added, or broken cable is bypassed.