sim3d.vehicle.ground.PassengerVehicle

Create four-wheeled passenger vehicle that follows ground in 3D environment

Since R2024b

Description

Use the sim3d.vehicle.ground.PassengerVehicle object to create a four-wheeled passenger vehicle that follows ground in the 3D environment. After you create a sim3d.vehicle.ground.PassengerVehicle object, you can modify aspects of the vehicle by setting property values.

Creation

Syntax

vehicle = sim3d.vehicle.ground.PassengerVehicle()

vehicle = sim3d.vehicle.ground.PassengerVehicle(Name=Value)

Description

vehicle = sim3d.vehicle.ground.PassengerVehicle() creates a default passenger vehicle object in the 3D environment.

vehicle = sim3d.vehicle.ground.PassengerVehicle(Name=Value) specifies options using one or more optional name-value arguments. You can also set the properties under Vehicle Attributes and Vehicle Light Attributes using name-value arguments.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: vehicle = sim3d.vehicle.ground.PassengerVehicle(ActorName="Vehicle",VehicleType='Sedan',Color='Blue')

ActorName — Name of actor

autogenerated name (default) | character array | string

Name of actor, specified as a character array or string. If you do not specify an actor name, then the software assigns the actor an autogenerated name. Use this argument to set the name of the sim3d.vehicle.ground.PassengerVehicle object.

Note

If you specify the same name as an actor that already exists, then the software appends actor name you specify with a unique identifier.

ActorClassId — Semantic segmentation map of object class identifiers

10 (default) | real positive scalar

Semantic segmentation map of object class identifiers, specified as real positive scalar. For a complete list of actor IDs and their corresponding object descriptions, see Labels.

CoordinateSystem — Coordinate system for actor transformation

'Default' (default) | 'MATLAB' | 'ISO8855' | 'AERO' | 'VRML' | 'SAE'

Since R2025a

Coordinate system that the actor uses for translation and rotation in the 3D environment, specified as one of these listed values:

• 'Default' – World coordinate system

• 'MATLAB' – MATLAB^® coordinate system

• 'ISO8855' – ISO 8855 standard coordinate system

• 'AERO' – SAE coordinate system

• 'VRML' – X3D ISO standard coordinate system

• 'SAE' – SAE coordinate system

For more details on the different coordinate systems, see Coordinate Systems in Simulink 3D Animation.

Data Types: string

Translation — Relative translation

[0 0 0; 0 0 0; 0 0 0; 0 0 0; 0 0 0] (default) | real 5-by-3 array

Relative translation of vehicle and wheels, specified as real 5-by-3 array, in m. Use this argument to set the initial translation of the passenger vehicle. The CoordinateSystem value specifies how Translation is applied. When you add an actor to the 3D environment, the default parent actor is the Scene Origin at (0,0,0).

• Translation(1,1), Translation(1,2), and Translation(1,3) — Vehicle translation relative to its parent actor about the X-, Y-, and Z- axes.

• Translation(...,1), Translation(...,2), and Translation(...,3) — Wheel translation relative to vehicle, about the X-, Y-, and Z- axes.

The signal contains translation information according to the axle and wheel locations.

$$Translation=\left[\begin{array}{ccc}{X}_v& Y_v& Z_v\\ X_{FL}& Y_{FL}& Z_{FL}\\ X_{FR}& Y_{FR}& Z_{FR}\\ X_{RL}& Y_{RL}& Z_{RL}\\ X_{RR}& Y_{RR}& Z_{RR}\end{array}\right]$$

Translation	Array Element	Translation Axis
Vehicle, Xv	Translation(1,1)	X-axis
Vehicle, Yv	Translation(1,2)	Y-axis
Vehicle, Zv	Translation(1,3)	Z-axis
Front left wheel, XFL	Translation(2,1)	X-axis
Front left wheel, YFL	Translation(2,2)	Y-axis
Front left wheel, ZFL	Translation(2,3)	Z-axis
Front right wheel, XFR	Translation(3,1)	X-axis
Front right wheel, YFR	Translation(3,2)	Y-axis
Front right wheel, ZFR	Translation(3,3)	Z-axis
Rear left wheel, XRL	Translation(4,1)	X-axis
Rear left wheel, YRL	Translation(4,2)	Y-axis
Rear left wheel, ZRL	Translation(4,3)	Z-axis
Rear right wheel, XRR	Translation(5,1)	X-axis
Rear right wheel, YRR	Translation(5,2)	Y-axis
Rear right wheel, ZRR	Translation(5,3)	Z-axis

Note

The sim3d.vehicle.ground.PassengerVehicle object implements an actor that follows the ground. Use X, Y, and Yaw properties to move the actor in the 3D environment. The actor object then determines the corresponding elevation, pitch, and roll by sensing the ground terrain.

Rotation — Relative rotation

[0 0 0; 0 0 0; 0 0 0; 0 0 0; 0 0 0] (default) | real 5-by-3 array

Relative rotation of vehicle and wheels, specified as real 5-by-3 array, in rad. Use this argument to set the initial rotation of the passenger vehicle. The CoordinateSystem value specifies how Rotation is applied.

• Rotation(1,1), Rotation(1,2), and Rotation(1,3) — Vehicle rotation relative to its parent actor about the X-, Y-, and Z- axes.

• Rotation(...,1), Rotation(...,2), and Rotation(...,3) — Wheel rotation relative to vehicle, about the X-, Y-, and Z- axes.

The signal contains rotation information according to the axle and wheel locations.

$$Rotation=\left[\begin{array}{ccc}Rol{l}_v& Pitc{h}_v& Ya{w}_v\\ Rol{l}_{FL}& Pitc{h}_{FL}& Ya{w}_{FL}\\ Rol{l}_{FR}& Pitc{h}_{FR}& Ya{w}_{FR}\\ Rol{l}_{RL}& Pitc{h}_{RL}& Ya{w}_{RL}\\ Rol{l}_{RR}& Pitc{h}_{RR}& Ya{w}_{RR}\end{array}\right]$$

Rotation	Array Element	Rotation Axis
Vehicle, Rollv	Rotation(1,1)	X-axis
Vehicle, Pitchv	Rotation(1,2)	Y-axis
Vehicle, Yawv	Rotation(1,3)	Z-axis
Front left wheel, RollFL	Rotation(2,1)	X-axis
Front left wheel, PitchFL	Rotation(2,2)	Y-axis
Front left wheel, YawFL	Rotation(2,3)	Z-axis
Front right wheel, RollFR	Rotation(3,1)	X-axis
Front right wheel, PitchFR	Rotation(3,2)	Y-axis
Front right wheel, YawFR	Rotation(3,3)	Z-axis
Rear left wheel, RollRL	Rotation(4,1)	X-axis
Rear left wheel, PitchRL	Rotation(4,2)	Y-axis
Rear left wheel, YawRL	Rotation(4,3)	Z-axis
Rear right wheel, RollRR	Rotation(5,1)	X-axis
Rear right wheel, PitchRR	Rotation(5,2)	Y-axis
Rear right wheel, YawRR	Rotation(5,3)	Z-axis

Note

The sim3d.vehicle.ground.PassengerVehicle object implements an actor that follows the ground. Use X, Y, and Yaw properties to move the actor in the 3D environment. The actor object then determines the corresponding elevation, pitch, and roll by sensing the ground terrain.

Output Arguments

vehicle — Actor object

sim3d.vehicle.ground.PassengerVehicle object

Actor object, returned as a sim3d.vehicle.ground.PassengerVehicle object.

Properties

Base Attributes

All the properties in base attributes and LightControls are run-time configurable.

Parent — Parent of actor

handle to parent actor object

Parent of actor, specified as a handle to the parent actor object. After you add an actor to the sim3d.World object, the default parent actor is the Scene Origin at (0,0,0). Use this property to set any actor in the 3D environment as the parent actor of a sim3d.vehicle.ground.PassengerVehicle object.

Children — Children of actor

Read-only: structure

This property is read-only.

Children of actor, specified as a structure. Each field of the structure contains a handle to the child of a sim3d.vehicle.ground.PassengerVehicle object.

ParentWorld — Parent world

handle to parent world object

Parent world, specified as a handle to the parent sim3d.World object. You can use this property only if the sim3d.vehicle.ground.PassengerVehicle object is added to the parent sim3d.World object.

CoordinateSystem — Coordinate system for actor transformation

'Default' (default) | 'MATLAB' | 'ISO8855' | 'AERO' | 'VRML' | 'SAE'

Since R2025a

Coordinate system that the actor uses for translation and rotation in the 3D environment, specified as one of these listed values:

• 'Default' – World coordinate system

• 'MATLAB' – MATLAB coordinate system

• 'ISO8855' – ISO 8855 standard coordinate system

• 'AERO' – SAE coordinate system

• 'VRML' – X3D ISO standard coordinate system

• 'SAE' – SAE coordinate system

For more details on the different coordinate systems, see Coordinate Systems in Simulink 3D Animation.

Data Types: string

X — Longitudinal position of actor

0 (default) | scalar

Longitudinal position of the actor along the X-axis of the scene, specified as scalar, in m. Use this property to move the actor along the X-axis of the scene. The CoordinateSystem value specifies how X is applied.

Y — Lateral position of actor

0 (default) | scalar

Lateral position of the actor along the Y-axis of the scene, specified as scalar, in m. Use this property to move the actor along the Y-axis of the scene. The CoordinateSystem value specifies how Y is applied.

Yaw — Yaw orientation angle of actor

0 (default) | scalar

Yaw orientation angle of the actor along the Z-axis of the scene, specified as scalar, in rad. Use this property to rotate the actor along the Z-axis of the scene. The CoordinateSystem value specifies how Yaw is applied.

Vehicle Attributes

VehicleType — Type of vehicle

'MuscleCar' (default) | 'Sedan' | 'SportUtilityVehicle' | 'SmallPickupTruck' | 'Hatchback' | 'BoxTruck' | 'FormulaStudentVehicle'

Type of vehicle, specified as one of these options. To obtain the dimensions of each vehicle type, see these reference pages:

• 'MuscleCar' — Muscle Car (Automated Driving Toolbox)

• 'Sedan' — Sedan (Automated Driving Toolbox)

• 'SportUtilityVehicle' — Sport Utility Vehicle (Automated Driving Toolbox)

• 'SmallPickupTruck' — Small Pickup Truck (Automated Driving Toolbox)

• 'Hatchback' — Hatchback (Automated Driving Toolbox)

• 'BoxTruck' — Box Truck (Automated Driving Toolbox)

Example: vehicle.VehicleType = 'Sedan'

Color — Color of vehicle

'Red' (default) | 'Orange' | 'Yellow' | 'Green' | 'Blue' | 'Black' | 'White' | 'Silver'

Select the color of the vehicle, specified as one of these options:

• 'Red'

• 'Orange'

• 'Yellow'

• 'Green'

• 'Blue'

• 'Black'

• 'White'

• 'Silver'

Example: vehicle.Color = 'Blue'

Data Types: string

Vehicle Light Attributes

EnableLightControls — Option to enable vehicle light control

0 or false (default) | 1 or true

Option to enable vehicle light control, specified as 0 (false) if light control is not enabled or 1 (true) if it is enabled. You can control these vehicle light parameters.

Lights	Light Parameters
Headlights	HeadlightColor HighBeamIntensity LowBeamIntensity HighBeamConeHalfAngle LowBeamConeHalfAngle LeftHeadlightBeamOrientation RightHeadlightBeamOrientation
BrakeLights	BrakeLightIntensity
ReverseLights	ReverseLightIntensity
TurnSignalLights	TurnSignalLightIntensity

Example: vehicle.EnableLightControls = 1

Data Types: logical

LightControls — Vehicle light controls

1-by-6 Boolean vector

Vehicle light controls, specified as a 1-by-6 Boolean vector. Each element of the vector turns a specific vehicle light on or off, as indicated in the table. A value of 1 turns the light on. A value of 0 turns the light off.

Value	Vehicle Light
[1 0 0 0 0 0]	Headlight high beam
[0 1 0 0 0 0]	Headlight low beam
[0 0 1 0 0 0]	Brake
[0 0 0 1 0 0]	Reverse
[0 0 0 0 1 0]	Left signal
[0 0 0 0 0 1]	Right signal

Example: To turn on the headlight low beam and reverse light, set vehicle.LightControls = [0 1 0 1 0 0]

Dependencies

• To set LightControls, set EnableLightControls to 1.

• This property is run-time configurable.

HeadlightColor — Headlight color

[1 1 1] (default) | 1-by-3 array of RGB triplet values

Headlight color, specified as a normalized 1-by-3 array of RGB triplet values.

Example: vehicle.HeadlightColor = [1 1 0]

Dependencies

To set HeadlightColor, set EnableLightControls to 1.

HighBeamIntensity — High beam intensity

100000 (default) | positive scalar

High beam intensity, in cd.

Example: vehicle.HighBeamIntensity = 500000

Dependencies

To set HighBeamIntensity, set EnableLightControls to 1.

LowBeamIntensity — Low beam intensity

60000 (default) | positive scalar

Low beam intensity, in cd.

Example: vehicle.LowBeamIntensity = 50000

Dependencies

To set LowBeamIntensity, set EnableLightControls to 1.

HighBeamConeHalfAngle — High beam cone half angle

70 (default) | positive scalar less than or equal to 90

High beam cone half angle, specified as a positive scalar less than or equal to 90, in deg.

Example: vehicle.HighBeamConeHalfAngle = 80

Dependencies

To set HighBeamConeHalfAngle, set EnableLightControls to 1.

LowBeamConeHalfAngle — Low beam cone half angle

70 (default) | positive scalar less than or equal to 90

Low beam cone half angle, specified as a positive scalar less than or equal to 90, in deg.

Example: vehicle.LowBeamConeHalfAngle = 50

Dependencies

To set LowBeamConeHalfAngle, set EnableLightControls to 1.

LeftHeadlightBeamOrientation — Left headlight beam orientation

[0,0] (default) | 1-by-2 array with values between -180 and 180

Pitch and yaw orientation of the left headlight beam orientation in the Z-up coordinate system, specified as a 1-by-2 array with values between -180 and 180, in deg. The first element of the array [1,1] is the pitch angle. The second element of the array [1,2] is the yaw angle.

Example: vehicle.LeftHeadlightBeamOrientation = [10,10]

Dependencies

To set LeftHeadlightBeamOrientation, set EnableLightControls to 1.

RightHeadlightBeamOrientation — Right headlight beam orientation

[0,0] (default) | 1-by-2 array with values between -180 and 180

Pitch and yaw orientation of the right headlight beam orientation in the Z-up coordinate system, specified as a 1-by-2 array with values between -180 and 180, in deg. The first element of the array [1,1] is the pitch angle. The second element of the array [1,2] is the yaw angle.

Example: vehicle.RightHeadlightBeamOrientation = [10,10]

Dependencies

To set RightHeadlightBeamOrientation, set EnableLightControls to 1.

BrakeLightIntensity — Intensity of brake light

500 (default) | positive scalar

Intensity of brake light, specified as a positive scalar, in cd/m^2.

Example: vehicle.BrakeLightIntensity = 600

Dependencies

To set BrakeLightIntensity, set EnableLightControls to 1.

ReverseLightIntensity — Intensity of reverse light

500 (default) | positive scalar

Intensity of reverse light, specified as a positive scalar, in cd/m^2.

Example: vehicle.ReverseLightIntensity = 600

Dependencies

To set ReverseLightIntensity, set EnableLightControls to 1.

TurnSignalLightIntensity — Intensity of turn signal light

500 (default) | positive scalar

Intensity of turn signal light, specified as a positive scalar, in cd/m^2.

Example: vehicle.TurnSignalLightIntensity = 600

Dependencies

To set TurnSignalLightIntensity, set EnableLightControls to 1.

Examples

Create Passenger Vehicle

Since R2025a

Create a passenger vehicle in a 3D environment using sim3d.vehicle.ground.PassengerVehicle object.

Create a 3D environment and set up communication with the Unreal Engine simulation environment using the output function OutputImpl. The sim3d.World object can send data about the 3D environment to the Unreal Engine at each simulation step using output function. Before the Unreal Engine simulates, MATLAB calls the output function and sends data to the Unreal Engine. Then, the Unreal Engine executes at each time step and sends data to MATLAB.

If the scene is not available, install the scene as described in the Scene name parameter of the Simulation 3D Scene Configuration block and then set the Scene argument.

world = sim3d.World(Scene="Straight road",Output=@OutputImpl);

Create a vehicle using sim3d.vehicle.ground.PassengerVehicle object and add the vehicle to the world.

vehicle = sim3d.vehicle.ground.PassengerVehicle( ...
    ActorName="Vehicle", ...
    Translation=[0 3 0; 0 0 0; 0 0 0; 0 0 0; 0 0 0]);
add(world,vehicle);

Run the co-simulation.

sampletime = 0.02;
stoptime = 10;
run(world,sampletime,stoptime);

Output Function

The output function sends data about the actor to the Unreal Engine environment at each simulation step. For this example, the function moves the Vehicle along X-axis by updating the X property of the Vehicle at each simulation step.

function OutputImpl(world)
world.Actors.Vehicle.X = world.Actors.Vehicle.X + 0.005;
end

Version History

Introduced in R2024b

R2025a: Set coordinate system

Set the CoordinateSystem argument and property of the sim3d.vehicle.ground.PassengerVehicle object to represent the coordinate system for actor transformation in the 3D environment.