Main Content

RoadRunner Scenario Reader

Reads selected topic from RoadRunner scenario

Since R2022a

expand all in page
  • RoadRunner Scenario Reader block

Libraries:
Automated Driving Toolbox / RoadRunner Scenario

Description

The RoadRunner Scenario Reader block reads the selected topic from the RoadRunner scenario. You can set the Topic Category parameter to Actor , Action or Sensor. The block outputs data as messages.

When you select the Actor topic, the block outputs the data associated with the actor, such as Actor Specifications and Actor Pose. When you select the Action topic, the block outputs data such as Speed Change and Lane Change. The block returns the simulation states from the previous time step. You can filter data based on the actor associated with the Simulink® actor model.

When you select the Sensor topic, the block outputs the data associated with the sensor of specified Sensor ID. You can select the type of sensor data the block must output by specifying Target Poses or Lane Boundaries.

Examples

Add Sensors to RoadRunner Scenario Using Simulink

Add Sensors to RoadRunner Scenario Using Simulink

Simulate a RoadRunner Scenario with sensor models defined in Simulink and visualize object and lane detections.

Ports

Output

expand all

State information from scenario, returned as a Simulink message. To extract data from the Simulink message, connect the RoadRunner Scenario Reader block to the Receive (Simulink) block.

Parameters

expand all

Topic category, specified as one of these values:

  • Actor — Reads the actor data from the scenario

  • Action — Reads the action data from the scenario

  • Sensor — Reads the sensor data from the scenario

  • Event — Reads the event data from the scenario

Type of actor in scenario, specified as All Types or Vehicle. The Vehicle type includes additional wheel information of the actor.

Dependencies

To enable this parameter, set Topic Category to Actor.

Type of action that can be read from the scenario, specified as one of these values:

  • Change Parameter — Reads the user-created parameter from the scenario

  • Lateral Offset — Reads the lateral offset action data from the scenario

  • Path Following — Reads the path following action data from the scenario

  • Speed Change — Reads the speed change action data from the scenario

  • Lane Change — Reads the lane change action data from the scenario

  • Longitudinal Distance — Reads the longitudinal distance action data from the scenario

  • UserDefined — Reads the custom parameters of a user-defined action from the scenario

This table describes the output bus structure when you set Topic Category to Action and Action Type to Change Parameter.

Field NameDescription
Actor Action

Information about the current action of specified actor, returned as a struct.

Parameter

Information about the changed user-specified behavior parameter, returned as a struct.

The Actor Action structure is the same for all action types. This table describes the Actor Action structure of the above output bus structure.

Field NameDescription
ActionID

Identifier of the actor action, returned as a string.

ActorID

Identifier of actor performing the action, returned as a uint64.

PhaseInterval

Phase interval to which the action is applied.

  • Unspecified — Unknown phase interval for the action.

  • AtStart — Specified action is completed at the start of the current phase.

  • AtEnd — Specified action is completed by the end of the current phase.

  • Invariant — Specified action objective is maintained during the current phase.

ActionTypes

Action type.

  • Unspecified — Unknown action type.

  • LaneChange — Lane change action.

  • Path — Path action.

  • Speed — Speed action.

  • LateralOffset — Lateral offset action.

  • ChangeParameter — Change parameter action.

  • LongitudinalDistance — Longitudinal distance action.

  • UserDefined — Change user-defined parameters.

This table describes the Parameter structure of the above output bus structure.

Field NameDescription
Name

Name of the changed user-specified behavior parameter, returned as a string.

Value

New value of the user-specified behavior parameter, returned as a string.

ParameterTypeType of parameter.

This table describes the output bus structure when you set Topic Category to Action and Action Type to Lane Change.

Field NameDescription
ActorAction

Information about the current action of specified actor, returned as a struct.

LaneChangeTarget

Target lane after lane change, returned as a struct.

TransitionDynamics

Dynamics of the transition to the lane change, returned as a struct.

The ActorAction structure is the same for all action types and is described above.

This table describes the LaneChangeTarget structure of the above output bus structure.

Field NameDescription
LaneValueNumber of lanes to change before reaching the target lane, returned as an int32 value.
LaneComparison

Direction of the lane change.

  • Unspecified — Unknown lane change direction.

  • SameAs — Actor moves to the same lane as the reference actor.

  • LeftOf — Actor moves to the lane left of the reference actor.

  • RightOf — Actor moves to the lane right of the reference actor.

RefActorIDIdentifier of reference actor, returned as a uint64.

This table describes the TransitionDynamics structure of the above output bus structure.

Field NameDescription
Dimension

Transition metric measuring the action change.

  • Unspecified — Unknown transition metric to measure specified action.

  • Rate — The action occurs within specified rate value.

  • Time — The action occurs within specified time value (seconds).

  • Distance — The action occurs within specified distance value (meters).

Shape

Shape of the transition curve.

  • Unspecified — The shape of the transition curve is unknown.

  • Linear — The transition curve is linear.

  • Cubic — The transition curve is cubic.

  • Step — The transition curve is step-shaped.

ValueValue of the chosen transition metric, returned as a double.

Note

The TransitionDynamics structure is the same for all action types that employ its use.

This table describes the output bus structure when you set Topic Category to Action and Action Type to Lateral Offset.

Field NameDescription
ActorActionInformation about the current action of specified actor, returned as a struct.
LateralOffsetTargetLateral offset relative to the current path of specified actor, returned as a struct.
TransitionDynamicsTransition dynamics for the lateral offset change, specified as a struct.

The ActorAction structure is the same for all action types and is described above.

This table describes the LateralOffsetTarget structure of the above output bus structure.

Field NameDescription
OffsetValueTarget lateral offset relative to the current path, returned as a double.

  • A positive value indicates an offset to the right of the current path

  • A negative value indicates an offset to the left of the current path

The TransitionDynamics structure is the same for all action types that employ its use and is described above.

This table describes the output bus structure when you set Topic Category to Action and Action Type to Longitudinal Distance.

Field NameDescription
ActorActionInformation about the current action of the specified actor, returned as a struct.
DistanceTargetInformation about the longitudinal distance to the reference actor, returned as a struct.
ReferenceSamplingMode

Phase interval at which the target longitudinal distance is achieved.

  • Unspecified — Target longitudinal distance gap to reference actor is unknown.

  • AtActionStart — Target longitudinal distance gap to reference actor is achieved at the start of the current phase.

  • Continuous — Target longitudinal distance gap to reference actor is achieved and maintained until another action controlling longitudinal distance is activated.

DynamicConstraintsDynamic constraints for the longitudinal distance change, returned as a struct.

The ActorAction structure is the same for all action types and is described above.

This table describes the DistanceTarget structure of the above output bus structure.

Field NameDescription
RefActorIDIdentifier of reference actor, returned as a uint64.
DistanceDimensionType

Type of distance to reference actor.

  • Unspecified — Type of distance to reference actor is unknown.

  • Longitudinal —Type of distance to the reference actor is longitudinal.

  • Lateral — Type of distance to the reference actor is lateral.

  • Euclidean — Type of distance to the reference actor is Euclidean.

DistanceType

Specification of longitudinal distance as either time distance or space distance.

  • Unspecified — Unknown longitudinal distance specification

  • Space — Space distance

  • Time — Time distance

ActorCoordinateSystemType

Coordinate system in which to measure required longitudinal distance.

  • Unspecified — Unknown coordinate system

  • Lane — Lane-based st coordinate system (s-axis is the lane center line of the lane on which the entity is located)

  • Pose — Cartesian coordinate system

ValueLongitudinal distance, returned as a double.
PositionComparison

Relative position to reference actor.

  • Unspecified — Unknown relative position to reference actor

  • SameAs — Parallel to reference actor

  • AheadOf — Ahead of reference actor

  • Behind — Behind reference actor

  • Either — Ahead of or behind reference actor

MeasureFrom

Longitudinal distance is either measured between the closest points on two actors' bounding boxes or between the origin point of both actors.

  • Unspecified — Unknown distance measurement type.

  • BoundingBoxes — Distance is measured as the gap between the rear end of the leading vehicle and the front end of the trailing vehicle.

  • Origins — Distance is measured as the gap between the origin of the leading vehicle and the origin of the trailing vehicle.

This table describes the DynamicConstraints structure of the above output bus structure.

Field NameDescription
UnlimitedDynamicsPresence of dynamic constraints, returned as a Boolean value.
MaxSpeedMaximum speed that an actor can attain while approaching target longitudinal distance to reference actor, returned as a double.
MaxAccelerationMaximum acceleration that an actor can attain while approaching target longitudinal distance to reference actor, returned as a double.
MaxDecelerationMaximum deceleration that an actor can attain while approaching target longitudinal distance to reference actor, returned as a double.

This table describes the output bus structure when you set Topic Category to Action and Action Type to Path Following.

Field NameDescription
ActorActionInformation about the current action of specified actor, returned as a struct.
PathTargetActor target path, returned as a struct.

The ActorAction structure is the same for all action types and is described above.

This table describes the PathTarget structure of the above output bus structure.

Field NameDescription
Path

Set of 3-D coordinates representing the target path, returned as an N-by-3 array where N = NumPoints.

Each column value in the first row is the x-, y- and z- coordinate, respectively, of the first point in the target path, and so on.

NumPoints

Total number of points in the target path, returned as a positive integer.

Tip

Currently, the RoadRunner Scenario Reader block reads the first 500 points of a target path. To read longer paths, see the MATLAB System block, Path Action Adapter in the example, Trajectory Follower with RoadRunner Scenario.

HasTimingsIndication of target path containing timing information, returned as a Boolean value.
TimingsTiming information for each point of the path, returned as an N-by-1 structure array where N = NumPoints.

This table describes the Timings structure of the above PathTarget structure.

Field NameDescription
TimeTime of arrival of the actor at this point, relative to the time at the starting point of the path. Returned in seconds.
SpeedSpeed of actor at the time of arrival, returned in meters per second.
WaitTimeWaiting time period of actor at arrival, returned in seconds. If this value is non-zero, then the actor is at rest.

This table describes the output bus structure when you set Topic Category to Action and Action Type to Speed Change.

Field NameDescription
ActorActionInformation about the current action of specified actor, returned as a struct.
SpeedTargetTarget speed after speed change, returned as a struct.
TransitionDynamicsTransition dynamics for the speed change, specified as a struct.

The ActorAction structure is the same for all action types and is described above.

This table describes the SpeedTarget structure of the above output bus structure.

Field NameDescription
SpeedValueTarget speed value, returned as a double.
SpeedComparison

Comparison type of current speed with the target speed.

  • Unspecified — Unknown speed comparison type.

  • Absolute — The target speed is absolute.

  • SameAs — The speed difference is zero relative to the speed of the reference actor.

  • FasterThan — The target speed must be higher than the speed of the reference actor.

  • SlowerThan — The target speed must be lower than the speed of the reference actor.

  • FromPath — The target speed must match the speeds specified in the PathPointTiming structure of the PathTarget structure (within PathAction structure) of the actor reference path.

RefActorIDIdentifier of reference actor, if any, returned as a uint64.
RefSamplingMode

Speed sampling mode of reference actor, if any.

  • Unspecified — Target speed comparison to reference actor speed is unknown.

  • AtActionStart — Indicates that the target speed compares with point speed of reference actor at start of the phase.

  • Continuous — Indicates that the target speed compares with point speed of reference actor continuously through entire phase or until another action controlling target speed is activated.

The TransitionDynamics structure is the same for all action types that employ its use and is described above.

This table describes the output bus structure when you set Topic Category to Action and Action Type to UserDefined.

Field NameDescription
ActorAction

Information about the current action of specified actor, returned as a struct.

Name

Action name, returned as a string.

ParametersCustom parameters of the user-defined action, returned as a struct. This struct contains the name and value for each custom parameter.

The ActorAction structure is the same for all action types and is described above.

Dependencies

To enable this parameter, set Topic Category to Action.

Sensor data derived from the scenario ground truth, specified as one of these options:

  • Target Poses — The block outputs poses of targets within sensor range in host vehicle coordinates. For the bus structure of the output target poses, see the output argument description of the targetPoses function.

  • Target Poses For Host — The block outputs poses of all targets in the in host vehicle coordinates. For the bus structure of the output target poses, see the output argument description of the targetPoses function.

  • Lane Boundaries — The block outputs lane boundaries within sensor range in host vehicle coordinates. For the bus structure of the output lane boundaries, see the output argument description of the laneBoundaries function.

  • Target Poses And Lane Boundaries — The block outputs both lane boundaries and poses of targets within the sensor range in host vehicle coordinates.

The origin of the host vehicle coordinates is the geometric center of the host vehicle.

You can send the above outputs directly to sensor detection generator blocks and obtain detections.

Dependencies

To enable this parameter, set Topic Category to Sensor.

Type of event to read from a scenario.

The event being read must be mapped to the corresponding bus object in the RoadRunner Scenario block.

Dependencies

To enable this parameter, set Topic Category to Event.

Actor data for all types, specified as one of these options:

  • Actor Specifications — Static attributes associated with the actor, such as actor ID, actor name, and bounding box

  • Actor Pose — Dynamic data associated with the actor, such as pose, velocity, and angular velocity. For vehicle assets included with or created in RoadRunner, the actor origin is the geometric center of the actor.

  • Actor Pose (Driving Scenario compatible) — Dynamic data associated with the actor, such as actor ID, position, velocity, roll, pitch, yaw, and angular velocity. For vehicle assets included with or created in RoadRunner, the actor origin is the point on the ground below the center of its rear axle.

  • Actor Lane Location — Dynamic data associated with the lane location of actors.

This table describes the output bus structure when you set Topic Category to Actor, Actor Type to All Types and Topic to Actor Specifications.

Field NameDescription
ActorID

Actor identifier, returned as a uint64.

ActorName

Actor name, returned as a string.

BoundingBoxBounding box of the actor, returned as a struct.

This table describes the BoundingBox structure of the above output bus structure.

Field NameDescription
Min

The bounding box corner with minimal x-, y- and z- values, returned as a 1-by-3 array.

Max

The bounding box corner with maximal x-, y- and z- values, returned as a 1-by-3 array.

This table describes the output bus structure when you set Topic Category to Actor, Actor Type to All Types and Topic to Actor Pose.

Field NameDescription
ActorIDScenario-defined actor identifier, returned as a uint64.
PosePosition and orientation of the actor, returned as a 4-by-4 array. See What Is a RoadRunner Pose Matrix?
VelocityActor velocity, in meters per second, in the x-, y-and z- directions, returned as a 1-by-3 vector.
AngularVelocityAngular velocity, in radians per second, of actor in the x-, y-and z- directions, returned as a 1-by-3 vector.

This table describes the output bus structure when you set Topic Category to Actor, Actor Type to All Types and Topic to Actor Pose(Driving Scenario compatible).

Field NameDescription
ActorIDScenario-defined actor identifier, returned as a uint64.
PositionPosition of actor, returned as a real-valued vector of the form [x y z]. Units are in meters.
VelocityVelocity (v) of actor in the x- y-, and z-directions, returned as a real-valued vector of the form [vx vy vz]. Units are in meters per second.
RollRoll angle of actor, returned as a real-valued scalar. Units are in degrees.
PitchPitch angle of actor, returned as a real-valued scalar. Units are in degrees.
YawYaw angle of actor, returned as a real-valued scalar. Units are in degrees.
AngularVelocityAngular velocity (ω) of actor in the x-, y-, and z-directions, returned as a real-valued vector of the form [ωx ωy ωz]. Units are in degrees per second.

This table describes the output bus structure when you set Topic Category to Actor, Actor Type to All Types, and Topic to Actor Lane Location.

Field NameDescription
ActorIDScenario-defined actor identifier, returned as a uint64.
IsOnLaneBoolean value indicating if the actor is located on a lane. An actor is considered to be on a certain lane if its model origin lies in between the left and right boundaries of this lane.
LocationOnLaneCurrent lane of actor, returned as a struct. If an actor straddles several lanes, the most aligned lane is returned.

This table describes the LocationOnLane structure of the Actor Lane Location.

Field NameDescription
LaneIDUUID identifier of the most aligned lane, returned as a string.
PositionPosition of the actor on the lane-center polyline (in s-value). The s-value is a double value within [0, 1] that indicates a position on a 3-D polyline with 0 at the start and 1 at the end of the polyline.
AngleAngle between the actor travel direction and tangent at the lane position. Units are in radians.

You can use the RoadRunner Scenario Reader block to access the lane location of all the actors in your simulation by setting Filter to None. In this case, the block outputs a message associated with each actor and each message has a field for actor ID. You can use a Queue (Simulink) block to store and queue messages. See Filter.

Dependencies

To enable these options for this parameter, set Actor Type to All Types.

Actor data for vehicle type, specified as one of these options:

  • Vehicle Specifications — Static attributes associated with the vehicle, such as paint color, and wheel specifications.

  • Vehicle Pose — Dynamic data associated with the actor, such as wheel poses

This table describes the output bus structure when you set Topic Category to Actor, Actor Type to Vehicle and Topic to Vehicle Specifications.

Field NameDescription
ActorSpecActor specifications, returned as a struct.
PaintColorColor of the actor, returned as a struct.
NumWheels

Number of wheels, returned as a uint32 value.

WheelsWheel specifications of vehicle-type actor, returned as a struct.

This table describes the ActorSpec structure of the above output bus structure.

Field NameDescription
ActorID

Actor identifier, returned as a uint64.

ActorName

Actor name, returned as a string.

BoundingBoxBounding box of the actor, returned as a struct.

Note

The ActorSpec structure is also returned when you set Topic Category to Actor, Actor Type to All Types and Topic to Actor Specifications.

This table describes the PaintColor structure of the above output bus structure.

Field NameDescription
rRed color, returned as a uint32 value.
gGreen color, returned as a uint32 value.
bBlue color, returned as a uint32 value.
aTransparency of the color (alpha), returned as a uint32 value.

This table describes the Wheels structure of the above output bus structure.

Field NameDescription
AxleIndexAxle index of a wheel. The front-most axle has the starting index value of zero, with index values increasing towards the vehicle rear. Returned as a uint32 value.
WheelOffsetx-, y- and z- coordinates of the wheel center, in the vehicle coordinate system. Returned as a 1-by-3 vector.
WheelRadiusRadius of the wheel in meters. Returned as a double.

This table describes the output bus structure when you set Topic Category to Actor, Actor Type to Vehicle and Topic to Vehicle Pose.

Field NameDescription
ActorRuntimeActor runtime values, returned as a struct.
NumWheelsNumber of wheels, returned as a uint32 value.
WheelPoses

Runtime pose of each wheel of vehicle-type actor, returned as a multidimensional 4-by-4-by-N array. N is the number of wheels of the vehicle-type actor.

WheelPoses is returned for wheels starting on the leftmost side of the front axle, and moving to the right. After the first axle is complete, the leftmost wheel on the second axle is taken into consideration before moving to the right, and so on.

This table describes the ActorRuntime structure of the above output bus structure.

Field NameDescription
ActorIDScenario-defined actor identifier, returned as a uint64.
PosePosition and orientation of the actor, returned as a 4-by-4 array. See What Is a RoadRunner Pose Matrix? for more information.
VelocityActor velocity, in meters per second, in the x-, y-and z- directions, returned as a 1-by-3 vector.
AngularVelocityAngular velocity, in radians per second, of actor in the x-, y-and z- directions, returned as a 1-by-3 vector.

Note

The ActorRuntime structure is also returned when you set Topic Category to Actor, Actor Type to All Types and Topic to Actor Pose.

Dependencies

To enable these options for this parameter, set Actor Type to Vehicle.

Lane boundaries to output, specified as one of these options:

  • Ego-Lane — The block outputs the boundaries for the lane in which host vehicle actor is traveling.

  • Ego and Adjacent Lanes — The block outputs the boundaries for the adjacent left and right lanes along with the lane in which host vehicle actor is traveling.

  • All Lanes — The block outputs the boundaries for all lanes on the road.

Dependencies

To enable this parameter, set Topic Category to Sensor and Sensor View to Lane Boundaries.

Filter criteria for relevant topic data, specified as None or Self. None outputs data for all actors in the scenario.Self outputs data for the Simulink model actor.

When you set Filter to None, the block outputs a message for each actor in your simulation. Messages carry data, including the actor ID. You can store messages in a Queue (Simulink) block. Then, you can process these messages. For example, you can use MATLAB System block. For more information, see Process Message Payload Using MATLAB System Block (Simulink).

RoadRunner Scenario Reader block outputs messages associated actors when Filter is selected as None. Queue block stores messages and MATLAB Function block processes messages.

Unique index of the sensor, specified as a positive integer. The Sensor ID must correspond to the Unique identifier of sensor parameter of the corresponding sensor model detection generator block.

Dependencies

To enable this parameter, set Topic Category to Sensor and Sensor View to either Target Poses, Lane Boundaries or Target Poses And Lane Boundaries.

Sample time of simulation in seconds, specified as a positive real scalar.

Name of the user-defined event to read from a scenario.

Dependencies

To enable this parameter, set Topic Category to Event and Event Type to User-Defined.

Version History

Introduced in R2022a

expand all

See Also

| | (Simulink)