RoadRunner Scenario Reader

Reads selected topic from RoadRunner scenario

Since R2022a

• 

×

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

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

• Open Live Script

Ports

Output

Message — State information from scenario

Simulink message

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

Topic Category — Topic category

Actor (default) | Action | Sensor | Event

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

Actor Type — Type of actor in scenario

All Types (default) | Vehicle

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.

Action Type — Type of action

Path Following (default) | Change Parameter | Lane Change | Lateral Offset | Longitudinal Distance | Speed Change | UserDefined

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 Name	Description
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 Name	Description
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 Name	Description
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.
ParameterType	Type of parameter.

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

Field Name	Description
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 Name	Description
LaneValue	Number 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.
RefActorID	Identifier of reference actor, returned as a uint64.

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

Field Name	Description
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.
Value	Value 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 Name	Description
ActorAction	Information about the current action of specified actor, returned as a struct.
LateralOffsetTarget	Lateral offset relative to the current path of specified actor, returned as a struct.
TransitionDynamics	Transition 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 Name	Description
OffsetValue	Target 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 Name	Description
ActorAction	Information about the current action of the specified actor, returned as a struct.
DistanceTarget	Information 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.
DynamicConstraints	Dynamic 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 Name	Description
RefActorID	Identifier 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
Value	Longitudinal 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 Name	Description
UnlimitedDynamics	Presence of dynamic constraints, returned as a Boolean value.
MaxSpeed	Maximum speed that an actor can attain while approaching target longitudinal distance to reference actor, returned as a double.
MaxAcceleration	Maximum acceleration that an actor can attain while approaching target longitudinal distance to reference actor, returned as a double.
MaxDeceleration	Maximum 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 Name	Description
ActorAction	Information about the current action of specified actor, returned as a struct.
PathTarget	Actor 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 Name	Description
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.
HasTimings	Indication of target path containing timing information, returned as a Boolean value.
Timings	Timing 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 Name	Description
Time	Time of arrival of the actor at this point, relative to the time at the starting point of the path. Returned in seconds.
Speed	Speed of actor at the time of arrival, returned in meters per second.
WaitTime	Waiting 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 Name	Description
ActorAction	Information about the current action of specified actor, returned as a struct.
SpeedTarget	Target speed after speed change, returned as a struct.
TransitionDynamics	Transition 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 Name	Description
SpeedValue	Target 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.
RefActorID	Identifier 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 Name	Description
ActorAction	Information about the current action of specified actor, returned as a struct.
Name	Action name, returned as a string.
Parameters	Custom 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 View — Sensor data derived from scenario ground truth

Target Poses (default) | Target Poses For Host | Lane Boundaries | Target Poses And Lane Boundaries

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.

Event Type — Type of event

User-Defined

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.

Topic — Actor data for all types

Actor Specifications (default) | Actor Pose | Actor Pose (Driving Scenario compatible) | Actor Lane Location

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 Name	Description
ActorID	Actor identifier, returned as a uint64.
ActorName	Actor name, returned as a string.
BoundingBox	Bounding box of the actor, returned as a struct.

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

Field Name	Description
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 Name	Description
ActorID	Scenario-defined actor identifier, returned as a uint64.
Pose	Position and orientation of the actor, returned as a 4-by-4 array. See What Is a RoadRunner Pose Matrix?
Velocity	Actor velocity, in meters per second, in the x-, y-and z- directions, returned as a 1-by-3 vector.
AngularVelocity	Angular 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 Name	Description
ActorID	Scenario-defined actor identifier, returned as a uint64.
Position	Position of actor, returned as a real-valued vector of the form [x y z]. Units are in meters.
Velocity	Velocity (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.
Roll	Roll angle of actor, returned as a real-valued scalar. Units are in degrees.
Pitch	Pitch angle of actor, returned as a real-valued scalar. Units are in degrees.
Yaw	Yaw angle of actor, returned as a real-valued scalar. Units are in degrees.
AngularVelocity	Angular 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 Name	Description
ActorID	Scenario-defined actor identifier, returned as a uint64.
IsOnLane	Boolean 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.
LocationOnLane	Current 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 Name	Description
LaneID	UUID identifier of the most aligned lane, returned as a string.
Position	Position 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.
Angle	Angle 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.

Topic — Actor data for vehicle type

Vehicle Specifications (default) | Vehicle Pose

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 Name	Description
ActorSpec	Actor specifications, returned as a struct.
PaintColor	Color of the actor, returned as a struct.
NumWheels	Number of wheels, returned as a uint32 value.
Wheels	Wheel specifications of vehicle-type actor, returned as a struct.

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

Field Name	Description
ActorID	Actor identifier, returned as a uint64.
ActorName	Actor name, returned as a string.
BoundingBox	Bounding 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 Name	Description
r	Red color, returned as a uint32 value.
g	Green color, returned as a uint32 value.
b	Blue color, returned as a uint32 value.
a	Transparency of the color (alpha), returned as a uint32 value.

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

Field Name	Description
AxleIndex	Axle 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.
WheelOffset	x-, y- and z- coordinates of the wheel center, in the vehicle coordinate system. Returned as a 1-by-3 vector.
WheelRadius	Radius 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 Name	Description
ActorRuntime	Actor runtime values, returned as a struct.
NumWheels	Number 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 Name	Description
ActorID	Scenario-defined actor identifier, returned as a uint64.
Pose	Position and orientation of the actor, returned as a 4-by-4 array. See What Is a RoadRunner Pose Matrix? for more information.
Velocity	Actor velocity, in meters per second, in the x-, y-and z- directions, returned as a 1-by-3 vector.
AngularVelocity	Angular 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.

Topic — Lane boundaries to output

Ego-Lane (default) | Ego and Adjacent Lanes | All Lanes

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 — Filter criteria

Self (default) | None

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).

Sensor ID — Unique index of sensor

1 (default) | positive integer

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 — Sample time of simulation

positive real scalar

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

Event Name — Name of event

string

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

R2023a: LaneLocation topic for all actors

Starting in R2023a, MapLocation and its bus definition BusVehicleMaplocation are not supported, when you access Vehicle Pose using a RoadRunner Scenario Reader block. To read an actor location, use the new dedicated topic Actor Lane Location. The change allows you to access location data associated with any actor in your RoadRunner Scenario simulation.