[xrfez]

Why

Field record numbers and channel numbers in seismic data often differ from the relation (X) file's. A recorder numbers all its live channels; reshoots and renumbered post-plots move records. Meanwhile the header stations are right. The old join keyed on (record, channel) first, and with overwrite = true it replaced header stations from it. On a 3D land survey this assigned every trace of a shot the stations of another shot (the file's FFID was another shot's X record). The trace numbers also matched the X channels for only 23 of 1127 traces.

What changes

Station-first join. Traces are matched by their source and receiver line/point. Header stations are never replaced; the relations only fill stations a header lacks:

• both stations in the header: coordinates by station only;
• source station only: the receiver comes from the X records of that source station. When there are repeats, the one with the trace's record number is used; otherwise they must agree, or the trace is ambiguous;
• receiver station only: the source comes from the O gathers of that receiver. Without O records, the X relation of the trace's record and channel is used, but only if its receiver is the header's;
• no station: record and channel, the fallback.

overwrite now refreshes coordinates, offset and midpoint only. Auxiliary traces are left alone. joinStations exposes the station step. JoinMatch and JoinStats (new applySurvey overloads, printed by the CLI) say how traces matched.

Receiver-domain relations. O records (.ops files) are the X layout with source and receiver swapped, one gather per receiver. They are read with record letter O; X-lettered records in an .ops file are taken as O by default. receiverRelations(g) builds them from X, one receiver line in memory at a time: 11.2 M pairs → 1.07 M O records in about 3 s.

Lookups. records, relations (iterators), expectedChannels, recordsAt (the records of a source station / gathers of a receiver), channelOf, sameStation, relationCount(g, domain).

Fix. writeGeometry/copyWithGeometry reported a value that rounds to the bytes already in the file (shotpoint 99.5 into an espnum holding 100) as a write the journal dropped, a fatal error. It is now no change, with a regression test.

Behaviour changes for callers

• A join no longer replaces stations a header has, even with overwrite.
• The conversion guide's example used to relabel record.sgd's own stations through X; it now uses the file's real stations.
• Tests that relied on stations being replaced now clear the station in the keys first, as a header without one would read.

Testing

nim test passes, including the 44 guide examples. The sample-file tests were run with the samples available here: the tgeomwrite and tcli survey blocks pass. segd_rev3_position_blocks needs the INOVA sample, which was not available. It now expects 2 changed traces instead of 5, because its 3 auxiliary traces are left alone. Please run the sample suite with the INOVA file.

🤖 Generated with Claude Code