Resolve ambiguity in definition of `VehiclePosition.Position.Bearing`

[e-lo]

Issue: The definition of VehiclePosition.Position.Bearing doesn't sufficiently define the direction of the vehicle because the reference direction could be either true north, an intermediate stop, or other intermediate location and there is nowhere to specify which it is.

Context

VehiclePosition.Position.Bearing is defined in the spec as (emphasis mine):

Bearing, in degrees, clockwise from True North, i.e., 0 is North and 90 is East. This can be the compass bearing, or the direction towards the next stop or intermediate location. This should not be deduced from the sequence of previous positions, which clients can compute from previous data.

The general statement in the VehiclePositions documentation has even less detail:

Bearing - direction that the vehicle is facing

The TIDES data spec would like to be consistent with GTFS, but without this variable being sufficiently defined we will not be able to do so.

Options

1. Keep ambiguous definition of Bearing, add new enum field to define what it is in reference to i.e. BearingReference
2. Keep field name of Bearing, but tighten up the definition to be a reference to True North (potential breaking change if the alternate def is used)
3. Add new field Heading which is tightly defined as degrees clockwise from True North

Discussion Points / Questions

1. What is the probable universe of data producers which produce bearings that are not relative to True North? Is it a handful, a zillion?
2. If there are a few of the above...then are data-consumers just inferring the reference direction from the data?

[leonardehrenfried]

Personally, I think 1. is the least destructive. I have not seen a feed that wasn't True North but maybe there is one out there.

We could make True North the default, so if you change nothing that's what you get, and allow those that aren't to opt out.

[paulswartz]

If we make True North the default, we'd still break any producers who aren't staying up-to-date with the spec. So unless there's a particular producer who a) is producing stop-relative bearings b) can't update their code to produce True North bearings, I'd go for option 2.

[derhuerst]

Sorry to derail the discussion, but yet again there is a use case for a mechanism to express which version of the GTFS(-RT) specs a system is intending to be compatible with, ideally even machine-readable. Is there such a system? If not, I will create a separate Issue.

[botanize]

I interpret the issue as the GTFS-realtime reference message Position documentation, and protobuf comments, allow bearing to mean either the direction the vehicle is facing or the direction to the next stop or other intermediate reference point. Both of those would be relative to true north. For example, the vehicle could be facing North (0 degrees), but the bearing to the next stop is East (90 degrees).

The VehiclePositions documentation is precise, clarifying that bearing is the direction the vehicle is facing, and not the direction to an arbitrary reference point.

It's unclear to me what the relationship between those two sources of documentation are, both were added to the repo in the same commit, but it seems like one of them shouldn't exist!

I'm in favor of using the precise definition that exists in the VehiclePositions documentation.

I think this is what option 2 means, but I'd re-word to "Keep field name of Bearing, but tighten up the definition to be a reference to direction the vehicle is facing (potential breaking change if the alternate def is used)"

[e-lo]

I interpret the issue as the GTFS-realtime reference message Position documentation, and protobuf comments, allow bearing to mean either the direction the vehicle is facing or the direction to the next stop or other intermediate reference point. Both of those would be relative to true north. For example, the vehicle could be facing North (0 degrees), but the bearing to the next stop is East (90 degrees).

Ohhh. That makes a lot more sense. So:

...This can be the compass bearing of the vehicle

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It may be closed manually after one month of inactivity. Thank you for your contributions.