Layout of road functions in Roads.Interfaces.Base

GarronFish commented 3 years ago

The VehicleInterfaces.Roads.Interfaces.Base is used as the base for many roads. These roads add in many other parameters and replaceable functions so it would be good to group the road functions in Base into a Tab to tidy up the layout of these functions. The description strings could also be improved and I think adding choicesAllMatching makes modifying these replaceable functions easier.

So I would like to propose that the road functions in Base be replaced with the following code.

  replaceable function position = VehicleInterfaces.Roads.Interfaces.positionBase
    "Function to get position at a road position" annotation (
    choicesAllMatching=true,
    Dialog(tab="Functions"),
    Documentation(info="<html>
<p>
The road position function returns the world location of the road location (s,w).
</p>
</html>"));
  replaceable function trackOffset = VehicleInterfaces.Roads.Interfaces.trackOffsetBase
    "Function to get position at a driving line position" annotation (
    choicesAllMatching=true,
    Dialog(tab="Functions"),
    Documentation(info="<html>
<p>
The track offset function returns the location of the driving line location (s,w).  This location can either be relative to the road centre line or in world coordinates.
</p>
</html>"));

  replaceable function normal = VehicleInterfaces.Roads.Interfaces.normalBase
    "Function to get road normal at a road position" annotation (
    choicesAllMatching=true,
    Dialog(tab="Functions"),
    Documentation(info="<html>
<p>
The normal function returns the normal of the road surface at (s,w).
</p>
</html>"));

  replaceable function headingDirection = VehicleInterfaces.Roads.Interfaces.headingDirectionBase
    "Function to get heading direction at a road position" annotation (
    choicesAllMatching=true,
    Dialog(tab="Functions"),
    Documentation(info="<html>
<p>
The heading direction function returns the direction in which the road is going at (s,w).
</p>
</html>"));

  replaceable function frictionCoefficient = VehicleInterfaces.Roads.Interfaces.frictionCoefficientBase
    "Function to get friction coefficient at road position" annotation (
    choicesAllMatching=true,
    Dialog(tab="Functions"),
    Documentation(info="<html>
<p>
The frictionCoefficient function returns the friction coefficient of the road at (s,w).
</p>
</html>"));

tobolar commented 3 years ago

As far as I understand the current concept, the roads' functions are firmly coupled to a particular road. Thus, they shall not be directly accessible to a user. A road developer shall first declare the protected particular functions within a particular road and link them then to the base road functions. So IMO the benefit of adding choicesAllMatching=true and collecting functions within tab="Functions" has effect only when linking the base and the particular functions. And this is generally done just at once when implementing a new road. Or am I missing something?

GarronFish commented 3 years ago

In our case we are extending VehicleInterfaces.Roads.Interfaces.Base to create a road model. Then the road functions are redeclared. Clients using the VeSyMA road models requested that the road models we create have replaceable road functions as this allows them to create their road models without having to duplicate road models. Previously we had firmly fixed these road functions, however even in this case we would like to improve the description string and tab option to make the models neater.

Is there a workaround that does not generate warnings?

modelica / VehicleInterfaces

Layout of road functions in Roads.Interfaces.Base #89