Clarify that the value of reduced_speed_limit should be in kilometers per hour

[j-d-b]

This PR resolves issue #169.

Specifically, it renames the reduced_speed_limit property on the RoadEvent object to reduced_speed_limit_kph and adds clarifying text to the description indicating that the value should be in kilometers per hour.

In addition, to help reduced confusion on the usage of reduced_speed_limit_kph, the following was added to the property description: "this property only needs to be supplied if the speed limit within the road event is lower than the posted speed limit of the roadway."

Edit: updated to use kph

[sergebeaudry]

If we want WZDx to become an international standard. the current suggestion will halt its adoption. An alternative that cost nothing in the standard per say but effort on the data user is to define it as using the unit standardized at the defined location for the road event. EX: the roadevent is in USA = MPH, From Canada= KPH. Would be nice to understand how the mapping/Automaker companies are managing the speed currently across the world.

[eli104]

...

EX: the roadevent is in USA = MPH, From Canada= KPH. Would be nice to understand how the mapping/Automaker companies are managing the speed currently across the world.

From my knowledge of the data provided by major mapping companies, (e.g. HERE, others), the GDF data includes EITHER km\h OR mph, based on the speed unit defined in each map "section" By example: the speed unit for each County in the US is defined as MPH as a part of the data set. The same is true for data sets for each area of other countries as well.

Side note: If I am correct, there is only one road in Arizona that defines DISTANCE in Kilometers, but retains the MPH designation for speeds.

[j-d-b]

EX: the roadevent is in USA = MPH, From Canada= KPH.

From a consumer perspective I do not like this approach as it requires more logic and reliance on other services/maintained mappings to know the units:

• One would have to know what units countries use and maintain that mapping
• One have to have a way to determine the country that the road event geometry occurs in

This seems unnecessarily cumbersome.

Having the units either specified by the property (as originally proposed) or specified by the producer in the feed header or a reduced_speed_limit_units property gives the consumer all the information they need—they would not have to reference any mappings or external sources.

[j-d-b]

Based on further discussion having the specification require a certain unit (MPH or KPH) as proposed in this PR is desirable because it is the simplest approach and easiest to consume.

Whether WZDx requires miles per hour (as proposed) or kilometers per hour was discussed. Kilometers is the global standard and is used by TMDD and Ver-Mac and GM internally. kph is what I would lean towards, and @davidcraig4300 and @sknick-iastate are on board with that. A negative of kph is that WZDx already has elements specific to the USA (either imperial system or right-side driving), such as "milepost" and "center-left-turn-lane", though we could globalize those in a future release.

Whatever we chose, we should not change it in the future, as that would be an annoying, confusing breaking change.

I'd also suggest we rename the property to include the units, that is, reduce_speed_limit_kph, which helps clarify the units without having to refer to documentation.

[tfoster-vm]

I vote for kph, as this is what most manufacturers utilize. It is an easy conversion by any consumer...no different than converting time from UTC to a local time zone. My two cents.

[devorah-ql]

I agree here with @sergebeaudry

If we want WZDx to become an international standard. the current suggestion will halt its adoption. An alternative that cost nothing in the standard per say but effort on the data user is to define it as using the unit standardized at the defined location for the road event. EX: the roadevent is in USA = MPH, From Canada= KPH. Would be nice to understand how the mapping/Automaker companies are managing the speed currently across the world.

This doesn't necessarily have to be specified by country, but should be specified as MPH or KPH, leaving the option. I think this should be the precedent for WZDX. I do understand that here we are talking about a single speed limit value, so true it is not difficult to convert. However, when we get to the WZDX data feeds, for example, providers may literally be providing millions upon millions of lines of data. Since both the DOT and the vendor will be operating in standard U.S. units of mph, this would require processing huge amounts of data to KPH by the vendor, and then back to MPH by the DOT, which requires a lot of processing, for no purpose whatsoever. I think the precedent for the entire feed should be considered, as it makes little sense to have one part demanding KPH, while others are flexible. I believe the flexible approach should be set as the precedent for all areas.

[dxpack]

Depending on the use case of this field, defining the field as either KPH or MPH is going to be problematic in terms of value precision. For example, if one use case is to notify drivers that the speed is reduced, either via in-vehicle communication or DMS, a KPH value of 85 used in an MPH-region would be converted to 52.81655 MPH and then rounded to 50, 52, 53, or 55, depending on the rounding parameters, before communication to the vehicles. If the field is fixed to one or the other units, many consumers (everyone in the US if KPH, everyone outside the US if MPH) will have to drop precision via rounding. Including an additional field to specify the units would likely resolve the majority of use cases. MPH-region feeds can specify the fields as MPH, KPH-region feeds as KPH. Subsequently, only when data from one region is being consumed in another region would the precision become a factor. Alternatively, a higher-level field could be defined to specify global feed parameters such as distance/speed units, which would apply to all fields like reduced_speed_limit.

[j-d-b]

@devorah-ql and @dxpack, FYI, the KPH implementation as proposed in this PR was decided on after several months of working group meetings and then presented for voting in the WZDWG semi-annual meeting in early November. The approach for the v4.0 release cannot be changed now. If it passes and you still have issues with the implementation, I will move both of your comments to a new issue to continue the discussion about further revision in a future release.