Feature/set behavior parameter in object controller

[hakuturu583]

Description

Abstract

• The maximum speed, maximum acceleration, etc. of the vehicle to be used by the vehicle control algorithm can be specified in ObjectController.
• Fixed a bug that caused the target speed to be treated as an error instead of being corrected if the target speed specification exceeded the speed limit.
• API::setVelocityLimit function was performing an operation that did nothing.
• Fixed a bug that caused scenarios to fail with an exception when 0 was specified for the speed limit, acceleration limit, acceleration rate limit.

Background

About ObjectController in OpenSCENARIO.

Currently, it is not possible to specify in ObjectController the maximum speed, maximum acceleration, etc. of the vehicle to be used by the vehicle control algorithm.
Therefore, the only way to specify these parameters is to use SpeedProfileAction, which specifies the target speed at the same time.
This Pull Request improves this situation and allows the parameters to be set in the ObjectController.

About velocity limit

When the maximum speed of Entity was set using API::setVelocityLimit function and OpenSCENARIO's AssingControllerAction or ObjectController., it was doing "nothing", so the maximum speed was not set.

After this Pull-Request merged, the maximum speed is set.

Details

The reason I want to write limitations in ObjectController this time is because I want to specify the acceleration limit of driver behaviors that will continue to be applied as long as Entity exists in the simulation.

I searched this xsd for "Acceleration" and found that the only two types of acceleration that can be specified for an Entity are DynamicConstraints and Performance.
Among these, "Performance" specifies the "maximum acceleration that the vehicle Entity can physically achieve," so it does not match the purpose of this search.
The remaining "DynamicConstraints" can be used for LateralDistanceAction, LongitudinalDistanceAction, and SpeedProfileAction.

LateralDistanceAction

See also official document.

This Action cannot "specify an acceleration limit for Driver that will continue to be applied as long as the Entity exists in the simulation" and does not fit the purpose of this time.

LongitudinalDistanceAction

See also official document.

It does not fit this purpose for the same reason as LateralDistanceAction.

SpeedProfileAction

It does not fit this purpose for the same reason as LateralDistanceAction.

After conducting the above review work, it was determined that it would be appropriate to allow the ObjectController to write limits such as maximum acceleration.

After this pull request is merged, you will be able to set acceleration limits, etc. in the following format.
See here for samples below.

Entities:
    ScenarioObject:
      - name: Npc1
        Vehicle:
          name: ''
          vehicleCategory: car
          BoundingBox:
            Center:
              x: 0
              y: 0
              z: 1.25
            Dimensions:
              length: 4
              width: 1.8
              height: 2.5
          Performance:
            maxSpeed: 50.0
            maxAcceleration: INF
            maxDeceleration: INF
          Axles:
            FrontAxle:
              maxSteering: 0.5236
              wheelDiameter: 0.6
              trackWidth: 1.8
              positionX: 2
              positionZ: 0.3
            RearAxle:
              maxSteering: 0.5236
              wheelDiameter: 0.6
              trackWidth: 1.8
              positionX: 0
              positionZ: 0.3
          Properties:
            Property: []
        ObjectController:
          Controller:
            name: ''
            Properties:
              Property:                
                - name: maxSpeed
                  value: 2.5
                - name: maxAcceleration
                  value: 1.0
                - name: maxAccelerationRate
                  value: INF
                - name: maxDeceleration
                  value: 1.0
                - name: maxDecelerationRate
                  value: INF

References

Internal URL

Regression test result

Destructive Changes

Changed behavior of the AssignControllerAction

Although this bug fix is intended to comply with the OpenSCENARIO standard, some existing scenarios were found to have been judged successful by the bug to be fixed.

In the past, in some scenarios, the maximum speed was set to 0 using AssignControllerAction to stop the PedestrianEntity before the pedestrian crossing.
When the maximum speed was specified in AssignControllerAction, it should not have been higher than that, but the function used inside it was behaving as if it was working as intended by the scenario writer because it was "doing nothing".

In this situation, I recommend to use SpeedAction instead of using AssingControllerAction if you want to set target speed of the entity. (e.g A pedestrian is stopped before an intersection.)

Example is below.

Not recommended description method

  # Setting `target linear velocity` of the entity.
  - LongitudinalAction:
      SpeedAction:
        SpeedActionDynamics:
          dynamicsDimension: time
          value: 0
          dynamicsShape: step
        SpeedActionTarget:
          AbsoluteTargetSpeed:
            value: 0
  # Setting `maximum linear velocity` of the entity.
  - ControllerAction:
      AssignControllerAction:
        Controller:
          name: ''
          Properties:
            Property:
              - name: maxSpeed
                value: '0'

Recommended description method

  # Setting `target linear velocity` of the entity.
  - LongitudinalAction:
      SpeedAction:
        SpeedActionDynamics:
          dynamicsDimension: time
          value: 0
          dynamicsShape: step
        SpeedActionTarget:
          AbsoluteTargetSpeed:
            value: 0

Known Limitations

N/A

[github-actions]

Checklist for reviewers ☑️

All references to "You" in the following text refer to the code reviewer.

• Is this pull request written in a way that is easy to read from a third-party perspective?
• Is there sufficient information (background, purpose, specification, algorithm description, list of disruptive changes, and migration guide) in the description of this pull request?
• If this pull request contains a destructive change, does this pull request contain the migration guide?
• Labels of this pull request are valid?
• All unit tests/integration tests are included in this pull request? If you think adding test cases is unnecessary, please describe why and cross out this line.
• The documentation for this pull request is enough? If you think adding documents for this pull request is unnecessary, please describe why and cross out this line.