vehicle

Add vehicle to driving scenario

Syntax

vc = vehicle(scenario)

vc = vehicle(scenario,Name,Value)

Description

vc = vehicle(scenario) adds a Vehicle object, vc, to the driving scenario, scenario. The vehicle has default property values.

Vehicles are a specialized type of actor cuboid (box-shaped) object that has four wheels. For more details about how vehicles are defined, see Actor and Vehicle Positions and Dimensions.

vc = vehicle(scenario,Name,Value) sets vehicle properties using one or more name-value pairs. For example, you can set the position, velocity, dimensions, orientation, and wheelbase of the vehicle. You can also set a time for the vehicle to spawn or despawn in the scenario.

Note

You can configure the vehicles in a driving scenario to spawn and despawn, and then import the associated drivingScenario object into the Driving Scenario Designer app. The app considers the first vehicle created in the driving scenario to be the ego vehicle and does not allow the ego vehicle to either spawn or despawn in the scenario.

Examples

Create Driving Scenario with Multiple Actors and Roads

Create a driving scenario containing a curved road, two straight roads, and two actors: a car and a bicycle. Both actors move along the road for 60 seconds.

Create the driving scenario object.

scenario = drivingScenario('SampleTime',0.1','StopTime',60);

Create the curved road using road center points following the arc of a circle with an 800-meter radius. The arc starts at 0°, ends at 90°, and is sampled at 5° increments.

angs = [0:5:90]';
R = 800;
roadcenters = R*[cosd(angs) sind(angs) zeros(size(angs))];
roadwidth = 10;
road(scenario,roadcenters,roadwidth);

Add two straight roads with the default width, using road center points at each end.

roadcenters = [700 0 0; 100 0 0];
road(scenario,roadcenters)

ans = 
  Road with properties:

           Name: ""
         RoadID: 2
    RoadCenters: [2x3 double]
      RoadWidth: 6
      BankAngle: [2x1 double]

roadcenters = [400 400 0; 0 0 0];
road(scenario,roadcenters)

ans = 
  Road with properties:

           Name: ""
         RoadID: 3
    RoadCenters: [2x3 double]
      RoadWidth: 6
      BankAngle: [2x1 double]

Get the road boundaries.

rbdry = roadBoundaries(scenario);

Add a car and a bicycle to the scenario. Position the car at the beginning of the first straight road.

car = vehicle(scenario,'ClassID',1,'Position',[700 0 0], ...
    'Length',3,'Width',2,'Height',1.6);

Position the bicycle farther down the road.

bicycle = actor(scenario,'ClassID',3,'Position',[706 376 0]', ...
    'Length',2,'Width',0.45,'Height',1.5);

Plot the scenario.

plot(scenario,'Centerline','on','RoadCenters','on');
title('Scenario');

Display the actor poses and profiles.

poses = actorPoses(scenario)

poses=2×1 struct array with fields:
    ActorID
    Position
    Velocity
    Roll
    Pitch
    Yaw
    AngularVelocity

profiles = actorProfiles(scenario)

profiles=2×1 struct array with fields:
    ActorID
    ClassID
    Length
    Width
    Height
    OriginOffset
    MeshVertices
    MeshFaces
    RCSPattern
    RCSAzimuthAngles
    RCSElevationAngles

Spawn and Despawn Vehicles in Scenario During Simulation

Create a driving scenario. Set the stop time for the scenario to 3 seconds.

scenario = drivingScenario('StopTime',3);

Add a two-lane road to the scenario.

roadCenters = [0 1 0; 53 1 0];
laneSpecification = lanespec([1 1]);
road(scenario,roadCenters,'Lanes',laneSpecification);

Add another road that intersects the first road at a right angle to form a T-shape.

roadCenters = [20.3 33.4 0; 20 3 0];
laneSpecification = lanespec(2);
road(scenario,roadCenters,'Lanes',laneSpecification)

ans = 
  Road with properties:

           Name: ""
         RoadID: 2
    RoadCenters: [2x3 double]
      RoadWidth: 7.3500
      BankAngle: [2x1 double]

Add the ego vehicle to the scenario and define its waypoints. Set the ego vehicle speed to 20 m/s and generate the trajectories for the ego vehicle.

egoVehicle = vehicle(scenario,'ClassID',1, ...
                    'Position',[1.5 2.5 0]);
waypoints = [2 3 0; 13 3 0;
            21 3 0; 31 3 0;
            43 3 0; 47 3 0];
speed = 15;
trajectory(egoVehicle,waypoints,speed)

Add a non-ego vehicle to the scenario. Set the non-ego vehicle to spawn and despawn during the simulation by specifying an entry time and an exit time.

nonEgovehicle1 = vehicle(scenario,'ClassID',1, ...
                'Position',[22 30 0],'EntryTime',0.8,'ExitTime',2);

Define the waypoints for the non-ego vehicle. Set the non-ego vehicle speed to 35 m/s and generate its trajectories.

waypoints = [22 30 0; 22 23 0;
            22 13 0; 22 7 0;
            18 -0.3 0; 12 -0.8 0; 3 -0.8 0];
speed = 35;
trajectory(nonEgovehicle1,waypoints,speed)

Add another non-ego vehicle to the scenario. Set the second non-ego vehicle to spawn during the simulation by specifying an entry time. Since you do not specify an exit time, this vehicle will remain in the scenario until the scenario ends.

nonEgovehicle2 = vehicle(scenario,'ClassID',1, ...
                'Position',[48 -1 0],'EntryTime',2);

Define the waypoints for the second non-ego vehicle. Set the vehicle speed to 60 m/s and generate its trajectories.

waypoints = [48 -1 0; 42 -1 0; 28 -1 0;
            16 -1 0; 6 -1 0];
speed = 60;
trajectory(nonEgovehicle2,waypoints,speed)

Create a custom figure window to plot the scenario.

fig = figure;
set(fig,'Position',[0 0 600 600])
movegui(fig,'center')
hViewPnl = uipanel(fig,'Position',[0 0 1 1],'Title','Vehicle Spawn and Despawn');
hPlt = axes(hViewPnl);

Plot the scenario and run the simulation. Observe how the non-ego vehicles spawn and despawn in the scenario while simulation is running.

plot(scenario,'Waypoints','on','Parent',hPlt)
while advance(scenario)
    pause(0.1)
end

Input Arguments

scenario — Driving scenario

drivingScenario object

Driving scenario, specified as a drivingScenario object.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: vehicle('Length',2.2,'Width',0.6,'Height',1.5) creates a vehicle that has the dimensions of a motorcycle. Units are in meters.

'ClassID' — Classification identifier

0 (default) | nonnegative integer

Classification identifier of actor, specified as the comma-separated pair consisting of 'ClassID' and a nonnegative integer.

Specify ClassID values to group together actors that have similar dimensions, radar cross-section (RCS) patterns, or other properties. As a best practice, before adding actors to a drivingScenario object, determine the actor classification scheme you want to use. Then, when creating the actors, specify the ClassID name-value pair to set classification identifiers according to the actor classification scheme.

Suppose you want to create a scenario containing these actors:

• Two cars, one of which is the ego vehicle

• A truck

• A bicycle

The code shows a sample classification scheme for this scenario, where 1 refers to cars, 2 refers to trucks, and 3 refers to bicycles. The cars have default vehicle properties. The truck and bicycle have the dimensions of a typical truck and bicycle, respectively.

scenario = drivingScenario;
ego = vehicle(scenario,'ClassID',1);
car = vehicle(scenario,'ClassID',1);
truck = vehicle(scenario,'ClassID',2,'Length',8.2,'Width',2.5,'Height',3.5);
bicycle = actor(scenario,'ClassID',3,'Length',1.7,'Width',0.45,'Height',1.7);

The default ClassID of 0 is reserved for an object of an unknown or unassigned class. If you plan to import drivingScenario objects into the Driving Scenario Designer app, do not leave the ClassID property of actors set to 0. The app does not recognize a ClassID of 0 for actors and returns an error. Instead, set ClassID values of actors according to the actor classification scheme used in the app.

ClassID	Class Name
1	Car
2	Truck
3	Bicycle
4	Pedestrian
5	Barrier

'Name' — Name of vehicle

"" (default) | character vector | string scalar

Name of the vehicle, specified as the comma-separated pair consisting of 'Name' and a character vector or string scalar.

Example: 'Name','Vehicle1'

Example: "Name","Vehicle1"

Data Types: char | string

'EntryTime' — Entry time for vehicle to spawn

0 (default) | positive scalar

Entry time for a vehicle to spawn in the driving scenario, specified as the comma-separated pair consisting of 'EntryTime' and a positive scalar. Units are in seconds, measured from the start time of the scenario.

Specify this name-value pair argument to add or make a vehicle appear in the driving scenario at the specified time, while the simulation is running.

• If the vehicle has an associated exit time, then the entry time must be less than the specified exit time.

• If the vehicle does not have an associated exit time, then the entry time must be less than or equal to the stop time of the scenario. You can set the stop time for the scenario by specifying a value for the 'StopTime' property of the drivingScenario object.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

'ExitTime' — Exit time for vehicle to despawn

Inf (default) | positive scalar

Exit time for a vehicle to despawn from the driving scenario, specified as the comma-separated pair consisting of 'ExitTime' and a positive scalar. Units are in seconds, measured from the start time of the scenario.

Specify this name-value pair argument to remove or make a vehicle disappear from the scenario at a specified time while the simulation is running.

• If the vehicle has an associated entry time, then the exit time must be greater than the specified entry time.

• If the vehicle does not have an associated entry time, then the exit time must be less than or equal to the stop time of the scenario. You can set the stop time for the scenario by specifying a value for the 'StopTime' property of the drivingScenario object.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

'PlotColor' — Display color of vehicle

RGB triplet | hexadecimal color code | color name | short color name

Display color of vehicle, specified as the comma-separated pair consisting of 'PlotColor' and an RGB triplet, hexadecimal color code, color name, or short color name.

The vehicle appears in the specified color in all programmatic scenario visualizations, including the plot function, chasePlot function, and plotting functions of birdsEyePlot objects. If you import the scenario into the Driving Scenario Designer app, then the vehicle appears in this color in all app visualizations. If you import the scenario into Simulink^®, then the vehicle appears in this color in the Bird's-Eye Scope.

If you do not specify a color for the vehicle, the function assigns one based on the default color order of Axes objects. For more details, see the ColorOrder property for Axes objects.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

• A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes '#FF8800', '#ff8800', '#F80', and '#f80' are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
'red'	'r'	[1 0 0]	'#FF0000'
'green'	'g'	[0 1 0]	'#00FF00'
'blue'	'b'	[0 0 1]	'#0000FF'
'cyan'	'c'	[0 1 1]	'#00FFFF'
'magenta'	'm'	[1 0 1]	'#FF00FF'
'yellow'	'y'	[1 1 0]	'#FFFF00'
'black'	'k'	[0 0 0]	'#000000'
'white'	'w'	[1 1 1]	'#FFFFFF'

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB^® uses in many types of plots.

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	'#0072BD'
[0.8500 0.3250 0.0980]	'#D95319'
[0.9290 0.6940 0.1250]	'#EDB120'
[0.4940 0.1840 0.5560]	'#7E2F8E'
[0.4660 0.6740 0.1880]	'#77AC30'
[0.3010 0.7450 0.9330]	'#4DBEEE'
[0.6350 0.0780 0.1840]	'#A2142F'

'Position' — Position of vehicle center

[0 0 0] (default) | [x y z] real-valued vector

Position of the rotational center of the vehicle, specified as the comma-separated pair consisting of 'Position' and an [x y z] real-valued vector.

The rotational center of a vehicle is the midpoint of its rear axle. The vehicle extends rearward by a distance equal to the rear overhang. The vehicle extends forward by a distance equal to the sum of the wheelbase and forward overhang. Units are in meters.

Example: [10;50;0]

'Velocity' — Velocity of vehicle center

[0 0 0] (default) | [v_x v_y v_z] real-valued vector

Velocity (v) of the vehicle center in the x-, y- and z-directions, specified as the comma-separated pair consisting of 'Velocity' and a [v_x v_y v_z] real-valued vector. The 'Position' name-value pair specifies the vehicle center. Units are in meters per second.

Example: [-4;7;10]

'Yaw' — Yaw angle of vehicle

0 (default) | real scalar

Yaw angle of the vehicle, specified as the comma-separated pair consisting of 'Yaw' and a real scalar. Yaw is the angle of rotation of the vehicle around the z-axis. Yaw is clockwise-positive when looking in the forward direction of the axis, which points up from the ground. Therefore, when viewing vehicles from the top down, such as on a bird's-eye plot, yaw is counterclockwise-positive. Angle values are wrapped to the range [–180, 180]. Units are in degrees.

Example: -0.4

'Pitch' — Pitch angle of vehicle

0 (default) | real scalar

Pitch angle of the vehicle, specified as the comma-separated pair consisting of 'Pitch' and a real scalar. Pitch is the angle of rotation of the vehicle around the y-axis and is clockwise-positive when looking in the forward direction of the axis. Angle values are wrapped to the range [–180, 180]. Units are in degrees.

Example: 5.8

'Roll' — Roll angle of vehicle

0 (default) | real scalar

Roll angle of the vehicle, specified as the comma-separated pair consisting of 'Roll' and a real scalar. Roll is the angle of rotation of the vehicle around the x-axis and is clockwise-positive when looking in the forward direction of the axis. Angle values are wrapped to the range [–180, 180]. Units are in degrees.

Example: -10

'AngularVelocity' — Angular velocity of vehicle

[0 0 0] (default) | [ω_x ω_y ω_z] real-valued vector

Angular velocity (ω) of the vehicle, in world coordinates, specified as the comma-separated pair consisting of 'AngularVelocity' and a [ω_x ω_y ω_z] real-valued vector. Units are in degrees per second.

Example: [20 40 20]

'Length' — Length of vehicle

4.7 (default) | positive real scalar

Length of the vehicle, specified as the comma-separated pair consisting of 'Length' and a positive real scalar. Units are in meters.

In Vehicle objects, this equation defines the values of the Length, FrontOverhang, Wheelbase, and RearOverhang properties:

Length = FrontOverhang + Wheelbase + RearOverhang

• If you update the Length, RearOverhang, or Wheelbase property, to maintain the equation, the Vehicle object increases or decreases the FrontOverhang property and keeps the other properties constant.

• If you update the FrontOverhang property, to maintain this equation, the Vehicle object increases or decreases the Wheelbase property and keeps the other properties constant.

When setting both the FrontOverhang and RearOverhang properties, to prevent the Vehicle object from overriding the FrontOverhang value, set RearOverhang first, followed by FrontOverhang. The object calculates the new Wheelbase property value automatically.

Example: 5.5

'Width' — Width of vehicle

1.8 (default) | positive real scalar

Width of the vehicle, specified as the comma-separated pair consisting of 'Width' and a positive real scalar. Units are in meters.

Example: 2.0

'Height' — Height of vehicle

1.4 (default) | positive real scalar

Height of the vehicle, specified as the comma-separated pair consisting of 'Height' and a positive real scalar. Units are in meters.

Example: 2.1

'Mesh' — Extended object mesh

extendedObjectMesh object

Extended object mesh, specified as an extendedObjectMesh object.

'RCSPattern' — Radar cross-section pattern of vehicle

[10 10; 10 10] (default) | Q-by-P real-valued matrix

Radar cross-section (RCS) pattern of the vehicle, specified as the comma-separated pair consisting of 'RCSPattern' and a Q-by-P real-valued matrix. RCS is a function of the azimuth and elevation angles, where:

• Q is the number of elevation angles specified by the 'RCSElevationAngles' name-value pair.

• P is the number of azimuth angles specified by the 'RCSAzimuthAngles' name-value pair.

Units are in decibels per square meter (dBsm).

Example: 5.8

'RCSAzimuthAngles' — Azimuth angles of vehicle's RCS pattern

[-180 180] (default) | P-element real-valued vector

Azimuth angles of the vehicle's RCS pattern, specified as the comma-separated pair consisting of 'RCSAzimuthAngles' and a P-element real-valued vector. P is the number of azimuth angles. Values are in the range [–180°, 180°].

Each element of RCSAzimuthAngles defines the azimuth angle of the corresponding column of the 'RCSPattern' name-value pair. Units are in degrees.

Example: [-90:90]

'RCSElevationAngles' — Elevation angles of vehicle's RCS pattern

[-90 90] (default) | Q-element real-valued vector

Elevation angles of the vehicle's RCS pattern, specified as the comma-separated pair consisting of 'RCSElevationAngles' and a Q-element real-valued vector. Q is the number of elevation angles. Values are in the range [–90°, 90°].

Each element of RCSElevationAngles defines the elevation angle of the corresponding row of the 'RCSPattern' name-value pair. Units are in degrees.

Example: [0:90]

'FrontOverhang' — Front overhang of vehicle

0.9 (default) | real scalar

Front overhang of the vehicle, specified as the comma-separated pair consisting of 'FrontOverhang' and a real scalar. The front overhang is the distance that the vehicle extends beyond the front axle. If the vehicle does not extend past the front axle, then the front overhang is negative. Units are in meters.

In Vehicle objects, this equation defines the values of the Length, FrontOverhang, Wheelbase, and RearOverhang properties:

Length = FrontOverhang + Wheelbase + RearOverhang

• If you update the Length, RearOverhang, or Wheelbase property, to maintain the equation, the Vehicle object increases or decreases the FrontOverhang property and keeps the other properties constant.

• If you update the FrontOverhang property, to maintain this equation, the Vehicle object increases or decreases the Wheelbase property and keeps the other properties constant.

When setting both the FrontOverhang and RearOverhang properties, to prevent the Vehicle object from overriding the FrontOverhang value, set RearOverhang first, followed by FrontOverhang. The object calculates the new Wheelbase property value automatically.

Example: 0.37

'RearOverhang' — Rear overhang of vehicle

1.0 (default) | real scalar

Rear overhang of the vehicle, specified as the comma-separated pair consisting of 'RearOverhang' and a real scalar. The rear overhang is the distance that the vehicle extends beyond the rear axle. If the vehicle does not extend past the rear axle, then the rear overhang is negative. Negative rear overhang is common in semitrailer trucks, where the cab of the truck does not overhang the rear wheel. Units are in meters.

In Vehicle objects, this equation defines the values of the Length, FrontOverhang, Wheelbase, and RearOverhang properties:

Length = FrontOverhang + Wheelbase + RearOverhang

• If you update the Length, RearOverhang, or Wheelbase property, to maintain the equation, the Vehicle object increases or decreases the FrontOverhang property and keeps the other properties constant.

• If you update the FrontOverhang property, to maintain this equation, the Vehicle object increases or decreases the Wheelbase property and keeps the other properties constant.

When setting both the FrontOverhang and RearOverhang properties, to prevent the Vehicle object from overriding the FrontOverhang value, set RearOverhang first, followed by FrontOverhang. The object calculates the new Wheelbase property value automatically.

Example: 0.32

'Wheelbase' — Distance between vehicle axles

2.8 (default) | positive real scalar

Distance between the front and rear axles of a vehicle, specified as the comma-separated pair consisting of 'Wheelbase' and a positive real scalar. Units are in meters.

In Vehicle objects, this equation defines the values of the Length, FrontOverhang, Wheelbase, and RearOverhang properties:

Length = FrontOverhang + Wheelbase + RearOverhang

• If you update the Length, RearOverhang, or Wheelbase property, to maintain the equation, the Vehicle object increases or decreases the FrontOverhang property and keeps the other properties constant.

• If you update the FrontOverhang property, to maintain this equation, the Vehicle object increases or decreases the Wheelbase property and keeps the other properties constant.

When setting both the FrontOverhang and RearOverhang properties, to prevent the Vehicle object from overriding the FrontOverhang value, set RearOverhang first, followed by FrontOverhang. The object calculates the new Wheelbase property value automatically.

Example: 1.51

Output Arguments

vc — Driving scenario vehicle

Vehicle object

Driving scenario vehicle, returned as a Vehicle object belonging to the driving scenario specified in scenario.

You can modify the Vehicle object by changing its property values. The property names correspond to the name-value pair arguments used to create the object.

The only property that you cannot modify is ActorID, which is a positive integer indicating the unique, scenario-defined ID of the vehicle.

To specify and visualize vehicle motion, use these functions:

trajectory	Create actor or vehicle trajectory in driving scenario
chasePlot	Ego-centric projective perspective plot

To get information about vehicle characteristics, use these functions:

actorPoses	Positions, velocities, and orientations of actors in driving scenario
actorProfiles	Physical and radar characteristics of actors in driving scenario
targetOutlines	Outlines of targets viewed by actor
targetPoses	Target positions and orientations relative to ego vehicle
driving.scenario.targetsToEgo	Convert target actor poses from world coordinates of scenario to ego vehicle coordinates
driving.scenario.targetsToScenario	Convert target actor poses from ego vehicle coordinates to world coordinates of scenario

To get information about the roads and lanes that the vehicle is on, use these functions:

roadBoundaries	Get road boundaries
driving.scenario.roadBoundariesToEgo	Convert road boundaries to ego vehicle coordinates
currentLane	Get current lane of actor
laneBoundaries	Get lane boundaries of actor lane
laneMarkingVertices	Lane marking vertices and faces in driving scenario
roadMesh	Mesh representation of an actor's nearest roads in driving scenario.

More About

Actor and Vehicle Positions and Dimensions

In driving scenarios, an actor is a cuboid (box-shaped) object with a specific length, width, and height. Actors also have a radar cross-section (RCS) pattern, specified in dBsm, which you can refine by setting angular azimuth and elevation coordinates. The position of an actor is defined as the center of its bottom face. This center point is used as the actor's rotational center, its point of contact with the ground, and its origin in its local coordinate system. In this coordinate system:

• The X-axis points forward from the actor.

• The Y-axis points left from the actor.

• The Z-axis points up from the ground.

Roll, pitch, and yaw are clockwise-positive when looking in the forward direction of the X-, Y-, and Z-axes, respectively.

A vehicle is an actor that moves on wheels. Vehicles have three extra properties that govern the placement of their front and rear axle.

• Wheelbase — Distance between the front and rear axles

• Front overhang — Distance between the front of the vehicle and the front axle

• Rear overhang — Distance between the rear axle and the rear of the vehicle

Unlike other types of actors, the position of a vehicle is defined by the point on the ground that is below the center of its rear axle. This point corresponds to the natural center of rotation of the vehicle. As with nonvehicle actors, this point is the origin in the local coordinate system of the vehicle, where:

• The X-axis points forward from the vehicle.

• The Y-axis points left from the vehicle.

• The Z-axis points up from the ground.

Roll, pitch, and yaw are clockwise-positive when looking in the forward direction of the X-, Y-, and Z-axes, respectively.

This table shows a list of common actors and their dimensions. To specify these values in Actor and Vehicle objects, set the corresponding properties shown.

Actor Classification	Actor Object	Actor Properties
		Length	Width	Height	FrontOverhang	RearOverhang	Wheelbase	RCSPattern
Pedestrian	Actor	0.24 m	0.45 m	1.7 m	N/A	N/A	N/A	–8 dBsm
Car	Vehicle	4.7 m	1.8 m	1.4 m	0.9 m	1.0 m	2.8 m	10 dBsm
Motorcycle	Vehicle	2.2 m	0.6 m	1.5 m	0.37 m	0.32 m	1.51 m	0 dBsm