How Stingray computes what it shows

1. Data ingestion and provenance

Stingray reads AIS and VDR recordings as text. It accepts CSV exports and six NMEA packaging dialects: bare AIVDM, ETX-wrapped, Wärtsilä VDR-4370 hex wrappers, VDR tab/comma channel columns, simple tab, and NMEA 4.10 tag blocks with their per-sentence receive clocks. Stingray scans and classifies a whole VDR folder before the import. A time window can limit everything that Stingray loads.

If Stingray does not recognize the packaging, or if the file is a binary container, Stingray starts salvage mode. Salvage mode extracts every sentence with a valid NMEA checksum. The checksum is the test that accepts a sentence, so an accidental run of bytes does not pass it.

Every position carries a timing-quality tier:

Stingray always marks a salvaged sentence coarse. Stingray clocks these sentences from the nearest ZDA or RMC time sentence, not from a per-sentence timestamp. The load report states this. The load report also states what Stingray did not decode. It counts the unrecognized sentence types, and it lists the proprietary sentences as opaque. Stingray removes none of them from the report.

2. The AIS decoder (ITU-R M.1371)

Stingray decodes AIS payloads bit-for-bit to ITU-R M.1371-6, and it decodes every message type 1–27. Types 1–3 (Class A position), 5 (static and voyage) and 9 (SAR aircraft position) supply the vessel tracks. Types 18/19 (Class B position, standard and extended) and 24 (Class B static) also supply tracks. Stingray decodes all the other types but does not plot them: base station reports, aids to navigation, safety text, station traffic, and binary containers. For a binary container, Stingray decodes the header only and keeps the payload as raw bits. The reference tables list the handling of each type.

Stingray rejects a malformed payload. A payload is malformed if it has an illegal armor character, a truncated bit field, or an invalid fill-bit count. Stingray does not decode such a payload into data that looks correct.

Stingray decodes type 27 (long-range broadcast) but does not plot it. The reason is the resolution of its position field: type 27 quantizes the position to 1/10 minute (≈185 m). That is an order of magnitude coarser than every other position report. A distance measured on a track that contains type 27 positions is not reliable. Stingray therefore keeps type 27 out of the tracks, and the load report counts these messages.

M.1371 defines “not available” sentinel values for most fields. Stingray shows a sentinel as a blank, never as a zero:

True heading is the one sentinel that changes what the map draws, not only a readout. A hull needs a bow direction, so Stingray draws it at COG instead. If COG is also missing, Stingray draws the hull at due north. Stingray always marks this fallback: the hull gets a dashed amber rim, and the info dialog names the stand-in (Section 4).

Rate of turn is the field that the standard encodes non-linearly. Most decoders get this field wrong:

The saturation markers ±127 mean “the turn is faster than 10°/min, and the rate is not measured”. Stingray shows them as “>10°/min port/stbd”, never as a precise number. The marker −128 means “no turn information”, and Stingray shows it as a blank.

3. Track reconstruction and interpolation

An AIS transmitter reports at discrete instants. The playhead can be between two fixes. Between two fixes, Stingray interpolates with a cubic Hermite spline. The tangents of the spline come from the transmitted velocity (SOG and COG) of each fix. Thus the curve agrees with the motion that the vessel transmitted at both ends.

If a fix carries no velocity, the tangent falls back to a Catmull-Rom estimate from the adjacent fixes. If that estimate is also not available, the tangent falls back to the chord (linear motion). Four guards limit the result:

• Stingray interpolates a segment shorter than 5 seconds linearly. A spline adds nothing at that density.
• Stingray interpolates a segment linearly if either fix has coarse or inferred timing. An unreliable time delta makes the velocity tangents overshoot.
• Stingray clamps the tangents to 2× the chord length. This limits the overshoot on a sparse segment.
• Stingray does not extrapolate. Before the first fix of a track, and after the last fix, the position clamps to the recorded endpoint. Stingray flags the position as clamped.

An interpolated position is an estimate, and Stingray marks it as an estimate internally. Stingray always draws the recorded fixes as track dots. Thus you can always tell the measured data from the curve through it.

4. Vessel geometry

An AIS position is the position of the AIS antenna of the vessel. The transmitted A/B/C/D dimensions give the position of that antenna. They give it in relation to the bow, the stern, the port side and the starboard side. Stingray draws every hull around the antenna at the reported offsets. Stingray never moves the fix to the centre of the hull. A vessel without usable dimensions shows as a dot or an arrow, not as a hull with guessed dimensions. One corrupt dimension field makes the whole set invalid, because a degenerate hull is worse than no hull.

θ is the transmitted true heading. A hull polygon shows the physical attitude of the vessel, and the true heading is that attitude. A transponder with no heading input sends the not-available code 511. Stingray then draws the hull at COG, which is a different quantity: the direction of travel. If the course is also missing, Stingray draws the hull at due north.

Stingray never adopts a stand-in without a mark. A hull at a fallback orientation carries a dashed amber rim on the map, and its info dialog names the stand-in. Stingray marks the hull but does not correct the data. A tool that replaces a heading with COG each time the two disagree removes the findings that this tool exists to report. Those findings are a vessel that goes astern, or a vessel with a failed compass.

The direct GPS track of the own ship comes from a different antenna. That antenna is the navigation GPS, not the AIS transponder. You can enter the hull particulars and the position of the GPS antenna from the configuration sheet of the installation. Stingray then draws the direct-source hull around that point. The analyst always enters these documented particulars. Stingray never infers them.

5. CPA and TCPA

Stingray computes the closest point of approach in two ways. The two ways complement each other, and Stingray labels each one:

• Actual CPA is a scan across the window where two recorded tracks overlap in time. It gives the true minimum separation and the time of that minimum. At each sampled instant, Stingray holds every vessel at its last recorded fix. The scan never measures against spline geometry. The distances are haversine (great-circle) metres. Actual CPA is what happened.
• Predictive CPA is the classic ARPA formula. It uses the instantaneous position, SOG and COG of each vessel, and it assumes a constant velocity. It gives the picture that a bridge radar shows at that moment. Predictive CPA is a reconstruction of the picture available then. It is not a statement about what happened after that moment.

Stingray measures both of these between two reference points. The selection of the reference points is separate from the selection of the distance. The default reference points are the antennas. An AIS position is the position of the antenna (Section 4), and that is what the recording transmits.

In a close-quarters encounter, the antenna distance overstates the clearance by the sum of the two antenna insets. On a large ship, that sum is most of a hull length. You can therefore read the same measurement and the same projection between the hulls instead. Stingray places both hulls as their broadcast-dimension rectangles and solves the exact minimum distance between them. On contact, the value is zero.

The projected hull calculation is different from the published method. Equation 15 corrects the separation at the instant when the two antennas are closest. That instant is one configuration out of the whole projection. As an estimate of the closest approach of the hulls, equation 15 is therefore an upper bound.

That bound can be larger than the separation of the hulls at the present moment, because the hulls reach their own minimum first. Next to a measured separation of zero, such a value is a contradiction. Stingray therefore minimises the projected hull separation exactly, under the same assumptions of constant velocity and held heading.

Stingray takes the minimum over the whole projection, and this includes the past. The backward extrapolation of a pair that is already apart can therefore pass through contact. That result is a statement about a configuration that the vessels are no longer in. Stingray reports it as a zero with a negative time and does not flag it as a contact. The contact flag is only for a projected overlap that is current or still ahead. A contact in the recorded data is a separate finding, and Stingray always flags it.

A vessel can carry both an AIS track and a directly recorded navigation track. Stingray then computes the closest approach from the track that you selected for display. Thus the figures agree with the geometry on the screen. The two tracks come from different receivers on the same hull, so they give different answers. Every readout names the track that it used.

Stingray needs an attitude to place a hull, and the measurement uses the transmitted heading. It falls back to COG only if the vessel broadcast no heading. If a vessel broadcast neither, Stingray gives no value at that instant, not a hull that points north. The time to the closest approach also depends on the reference points. The hulls reach their closest moment before the antennas reach theirs, so the time to that moment is a different number. It is not the same number read from other points.

Stingray never redefines the transmitted antenna quantity. A figure from another tool that reads the same recording therefore still matches. Every readout states the reference points that it used. You can chart both forms together on one panel. The gap between the two traces is the antenna inset.

6. Own-ship sensors and decode tables

Stingray keeps the own-ship sensor stream of a VDR as a second source beside the AIS track. Stingray never merges the two sources. The sentences fall into three confidence tiers:

Stingray interprets a coded value only through a decode table. A decode table holds analyst-authored rules that come from the Record of Configuration of the installation. An LLM can write a first version of the rules from that document. The analyst then reviews each rule and adopts it explicitly. The meaning of a code is reviewable data, never hardcoded vendor logic.

The cross-checks report findings, not corrections. Stingray compares the identity in the configuration sheet (MMSI, IMO with its check digit, and call sign) against the identity that the recording transmitted. Stingray also compares the expectation for each channel against the data that the channel carried. Stingray states both agreement and disagreement, and it resolves nothing automatically.

The same rule applies to orientation. A vessel with a heading that disagrees with its course is evidence of a broken gyro or of sternway. It is not noise to remove. Stingray never substitutes COG for a transmitted heading.

7. Exports and validation

The MP4 export renders through the same layer builders as the live map. Stingray takes an immutable snapshot when the export starts. What you see is what Stingray exports, and no later interaction can change an export in progress. The Rhino .3dm export writes georeferenced track curves. It also writes an antenna point and a hull outline for each sample, in a projected CRS that you select.

8. Known limits

• A position between two fixes is an interpolated estimate (Section 3). Base a conclusion at metre scale on the recorded fixes.
• A salvaged recording carries coarse, clock-derived timestamps. The load report flags them.
• Stingray counts the type-27 long-range reports but does not plot them (Section 2).
• A decode-table interpretation is the transcription that the analyst made from the documents of the installation. Stingray always keeps the raw coded sentences and shows them next to the interpretation.
• AIS static data (name, dimensions, draught) is what the vessel transmitted. A transmitter can have a wrong configuration. That fact is itself a finding, and the identity checks exist to report it.
• Hull separation (Section 5) trusts the broadcast dimensions and the antenna offsets. It also inherits the position error of both fixes: GPS accuracy of 2–5 m each (approximately 3–7 m together), about 18 cm of AIS lat/lng quantization, and the whole-metre rounding of the A/B/C/D offsets. A single-digit-metre reading is indicative, not survey-grade. A contact verdict at an interpolated instant also inherits the interpolation model, because a spline can move a hull through another hull between two fixes. If you turn interpolation off, the verdict holds to the recorded fixes. If a vessel broadcast no heading and no course, Stingray gives no value at all, never a guess.
• A hull at a fallback orientation (Section 4) shows a bow direction that Stingray selected. That direction is not a measurement. Stingray always marks it and never corrects it. The dashed amber rim and the info dialog state that the bow direction came from COG, or from no source at all. Read such a hull as position and dimensions with an unknown attitude.

The privacy policy covers where Stingray keeps the data and what leaves the browser.