Simulation 3D Vehicle with Ground Following

Implement vehicle that follows ground in 3D environment

• 

Libraries:
Automated Driving Toolbox / Simulation 3D
Vehicle Dynamics Blockset / Vehicle Scenarios / Sim3D / Sim3D Vehicle / Components
Simulink 3D Animation / Simulation 3D / Actors

Description

Note

Simulating models with the Simulation 3D Vehicle with Ground Following block requires Simulink^® 3D Animation™.

The Simulation 3D Vehicle with Ground Following block implements a vehicle with four wheels in a 3D simulation environment. This environment is rendered using the Unreal Engine^® from Epic Games^®. The block uses the input (X, Y) position and yaw angle of the vehicle to adjust the elevation, roll angle, and pitch angle of the vehicle so that it follows the ground terrain. The block determines the vehicle velocity and heading and adjusts the steering angle and rotation for each wheel. Use this block for automated driving applications.

To use this block, ensure that the Simulation 3D Scene Configuration block is in your model. If you set the Sample time parameter of the Simulation 3D Vehicle with Ground Following block to -1, the block inherits the sample time specified in the Simulation 3D Scene Configuration block.

The Coordinate system parameter of the block specifies how the actor transformations are applied in the 3D environment. The output of the block also follows the specified coordinate system.

By default, the block input uses the vehicle Z-down right-handed (RH) Cartesian coordinate system defined in SAE J670¹. The coordinate system is inertial and initially aligned with the vehicle geometric center:

• X-axis — Along vehicle longitudinal axis, points forward

• Y-axis — Along vehicle lateral axis, points to the right

• Z-axis — Points downward

Tip

The Simulation 3D Vehicle with Ground Following block must execute before the Simulation 3D Scene Configuration block. That way, the Simulation 3D Vehicle with Ground Following block prepares the signal data before the Unreal Engine 3D visualization environment receives it. To check the block execution order, right-click the blocks and then click the Properties button . On the General tab, confirm these Priority settings:

• Simulation 3D Scene Configuration — 0

• Simulation 3D Vehicle with Ground Following — -1

For more information about execution order, see Control and Display Execution Order.

You can configure the Simulation 3D Vehicle with Ground Following block to import custom meshes and control vehicle lights.

Examples

Scene Interrogation with Camera and Ray Tracing Reference Application

Interrogate a 3D Unreal Engine scene with a vehicle dynamics model by using a camera and ray tracing reference application project.

• Open Script

Ports

Input

X — Longitudinal position of vehicle

scalar

Longitudinal position of the vehicle along the X-axis of the scene.

Y — Lateral position of vehicle

scalar

Lateral position of the vehicle along the Y-axis of the scene.

Yaw — Yaw orientation angle of vehicle

scalar

Yaw orientation angle of the vehicle along the Z-axis of the scene. .

Light controls — Vehicle light controls

1-by-6 vector

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

Vector Element	Vehicle Light
(1,1)	Headlight high beam
(1,2)	Headlight low beam
(1,3)	Brake
(1,4)	Reverse
(1,5)	Left signal
(1,6)	Right signal

Dependencies

To create this port, on the Light Controls tab, select Enable light controls.

Data Types: Boolean

Parameters

Vehicle Parameters

Type — Type of vehicle

Muscle car (default) | Sedan | Sport utility vehicle | Small pickup truck | Hatchback | Box truck | Formula student vehicle | Custom

Select the type of vehicle. To obtain the dimensions of each vehicle type, see these reference pages:

• Muscle car — Muscle Car

• Sedan — Sedan

• Sport utility vehicle — Sport Utility Vehicle

• Small pickup truck — Small Pickup Truck

• Hatchback — Hatchback

• Box truck — Box Truck

• Formula student vehicle — Formula Student Vehicle

Dependencies

Selecting Custom enables parameters that allow you to import a custom mesh for your vehicle.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	PassVehMesh
Values:	Muscle car (default) | Sedan | Sport utility vehicle | Small pickup truck | Hatchback | Box Truck | Formula student vehicle | Custom
Data Types:	character vector

Path to custom mesh, MeshPath — Path to custom mesh

/MathWorksSimulation/Vehicles/Muscle/Meshes/SK_MuscleCar.SK_MuscleCar (default) | valid path

Path to custom mesh.

To create a custom vehicle mesh, see Prepare Custom Vehicle Mesh for the Unreal Editor.

Example: /MathWorksSimulation/Vehicles/Muscle/Meshes/SK_Sedan.SK_Sedan

Dependencies

To enable this parameter, set Type to Custom.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	MeshPath
Values:	/MathWorksSimulation/Vehicles/Muscle/Meshes/SK_MuscleCar.SK_MuscleCar (default) | valid path
Data Types:	character vector

Track width in custom mesh, TrackWidth — Track width

1.9 (default) | scalar

Track width in custom mesh, in m.

Dependencies

To enable this parameter, set Type to Custom.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	TrackWidth
Values:	1.9 (default) | scalar
Data Types:	double

Wheel base in custom mesh, WheelBase — Wheel base

3 (default) | scalar

Wheel base in custom mesh, in m.

Dependencies

To enable this parameter, set Type to Custom.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	WheelBase
Values:	3 (default) | scalar
Data Types:	double

Wheel radius in custom mesh, WheelRadius — Wheel radius

0.35 (default) | scalar

Wheel radius in custom mesh, in m.

Dependencies

To enable this parameter, set Type to Custom.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	WheelRadius
Values:	0.35 (default) | scalar
Data Types:	double

Color — Color of vehicle

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

Select the color of the vehicle.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	VehColor
Values:	Red (default) | Orange | Yellow | Green | Blue | Black | White | Silver
Data Types:	character vector

Coordinate system — Coordinate system for actor transformation

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

Specify the coordinate system that the actor uses for translation and rotation in the 3D environment.

• Default – World coordinate system. Units are in m and rad.

• MATLAB – MATLAB^® coordinate system. Units are in m and rad.

• ISO8855 – ISO 8855 standard coordinate system. Units are in m and deg.

• AERO – SAE coordinate system. Units are in m and rad.

• VRML – X3D ISO standard coordinate system. Units are in m and rad.

• SAE – SAE coordinate system. Units are in m and rad.

For more details on the different coordinate systems, see Actor Coordinate Systems.

Example: MATLAB

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	CoordinateSystem
Values:	SAE (default) | Default | AERO | ISO8855 | MATLAB | VRML
Data Types:	string

Initial position [X, Y, Z], InitialPos — Initial vehicle position

[0, 0, 0] (default) | real-valued 1-by-3 vector

Initial vehicle position along the X-axis, Y-axis, and Z-axis of the scene.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	InitialPos
Values:	[0, 0, 0] (default) | vector
Data Types:	double

Initial rotation [Roll, Pitch, Yaw], InitialRot — Initial angle of vehicle rotation

[0, 0, 0] (default) | real-valued 1-by-3 vector

Initial angle of vehicle rotation. The angle of rotation is defined by the roll, pitch, and yaw of the vehicle. The rotation order is Roll, then Pitch, then Yaw. When you update any of the three rotation values and leave others unchanged, the software reapplies all three rotations in the same order.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	InitialRot
Values:	[0, 0, 0] (default) | vector
Data Types:	double

Name, ActorName — Name of vehicle

SimulinkVehicle1 (default) | vehicle name

Name of vehicle. By default, when you use the block in your model, the block sets the Name parameter to SimulinkVehicleX. The value of X depends on the number of Simulation 3D Vehicle with Ground Following blocks that you have in your model.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	ActorName
Values:	SimulinkVehicle1 (default) | character vector
Data Types:	character vector

Sample time, SampleTime — Sample time

-1 (default) | positive scalar

Sample time, T_s. The graphics frame rate is the inverse of the sample time.

If you set the sample time to -1, the block uses the sample time specified in the Simulation 3D Scene Configuration block.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	SampleTime
Values:	-1 (default) | scalar
Data Types:	double

Light Controls

Enable light controls — Option to control vehicle lights

off (default) | on

Select whether to control the vehicle headlights. Use the enabled parameters to set the light parameters, including headlight intensity.

Dependencies

Selecting this parameter:

• Creates the input port Light controls.

• Enables these light parameters.

  Lights	Light Parameters
  Headlights	Headlight color High beam intensity Low beam intensity High beam cone half angle Low beam cone half angle Left headlight beam orientation Right headlight beam orientation
  Brake lights	Brake light intensity
  Reverse lights	Reverse light intensity
  Turn signal lights	Turn signal light intensity Period Pulse width

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	VehLightsControl
Values:	Off (default) | On
Data Types:	character vector

Headlights

Headlight color [R,G,B], HeadlightColor — Headlight color

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

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

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	HeadlightColor
Values:	[1,1,1] (default) | vector
Data Types:	double

High beam intensity, HighBeamIntensity — High beam intensity

100000 (default) | positive scalar

High beam intensity, in cd.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	HighBeamIntensity
Values:	100000 (default) | scalar
Data Types:	double

Low beam intensity, LowBeamIntensity — Low beam intensity

60000 (default) | positive scalar

Low beam intensity, in cd.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	LowBeamIntensity
Values:	60000 (default) | scalar
Data Types:	double

High beam cone half angle, HighBeamConeAngle — High beam cone half angle

1.22 (default) | positive scalar less than pi/2

High beam cone half angle, in rad.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	HighBeamConeAngle
Values:	1.22 (default) | scalar
Data Types:	double

Low beam cone half angle, LowBeamConeAngle — Low beam cone half angle

1.22 (default) | positive scalar less than pi/2

Low beam cone half angle, in rad.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	LowBeamConeAngle
Values:	1.22 (default) | scalar
Data Types:	double

Left headlight beam orientation [Pitch, Yaw], LeftHeadlightOrientation — Left headlight beam orientation

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

Pitch and yaw orientation of the left headlight beam orientation in the Z-down coordinate system, specified as a 1-by-2 vector, in rad. The first element of the vector, [1,1], is the pitch angle. The second element of the vector, [1,2], is the yaw angle.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	LeftHeadlightOrientation
Values:	[0,0] (default) | vector
Data Types:	double

Right headlight beam orientation [Pitch, Yaw], RightHeadlightOrientation — Right headlight beam orientation

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

Pitch and yaw orientation of the right headlight beam orientation in the Z-down coordinate system, specified as a 1-by-2 vector, in rad. The first element of the vector, [1,1], is the pitch angle. The second element of the vector, [1,2], is the yaw angle.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	RightHeadlightOrientation
Values:	[0,0] (default) | vector
Data Types:	double

Brake Lights

Brake light intensity, BrakelightIntensity — Brake light intensity

500 (default) | positive scalar

Brake light intensity, in cd/m^2.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	BrakelightIntensity
Values:	500 (default) | scalar
Data Types:	double

Reverse Lights

Reverse light intensity, ReverselightIntensity — Reverse light intensity

500 (default) | positive scalar

Reverse light intensity, in cd/m^2.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	ReverselightIntensity
Values:	500 (default) | scalar
Data Types:	double

Turn Signal Lights

Turn signal light intensity, SignallightIntensity — Turn signal light intensity

500 (default) | positive scalar

Turn signal light intensity, in cd/m^2.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	SignallightIntensity
Values:	500 (default) | scalar
Data Types:	double

Period, SignallightPeriod — Turn signal light period

1 (default) | positive scalar

Turn signal light period, in s.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	SignallightPeriod
Values:	1 (default) | scalar
Data Types:	double

Pulse width, SignalPulseWidth — Pulse width

50 (default) | positive scalar less than 100

Turn signal light pulse width, specified as a percent of the period.

Dependencies

To enable this parameter, select Enable light controls.

Programmatic Use

To set the block parameter value programmatically, use the set_param function.

To get the block parameter value programmatically, use the get_param function.

Parameter:	SignalPulseWidth
Values:	50 (default) | scalar
Data Types:	double

More About

Import Custom Meshes

To import custom meshes for defining custom vehicles, follow these steps:

1. Install the Vehicle Dynamics Blockset™ Interface for Unreal Engine Projects support package. See Customize 3D Scenes for Vehicle Dynamics Simulations.

2. On the block Parameters tab, set Type to Custom.

3. In the Path to custom mesh field, enter the path to the vehicle mesh in the Unreal Engine project. For example, enter /MathWorksSimulation/Vehicles/Muscle/Meshes/SK_MuscleCar.SK_MuscleCar.

   To create a custom vehicle mesh, see Prepare Custom Vehicle Mesh for the Unreal Editor.

4. Use the vehicle dimensions in the custom mesh to enter the dimensions in the corresponding block parameter fields.

Control Vehicle Lights

To control the lights of vehicles in a scene, follow these steps:

1. Install the Vehicle Dynamics Blockset Interface for Unreal Engine Projects support package. See Customize 3D Scenes for Vehicle Dynamics Simulations.

2. On the block Light Controls tab, select Enable light controls.

3. Use the enabled parameters to specify the vehicle light for:

   • Headlights

   • Brake lights

   • Reverse lights

   • Turn signal lights

4. Connect Boolean light control signals to the Signal lights input port.

References

[1] Vehicle Dynamics Standards Committee. Vehicle Dynamics Terminology. SAE J670. Warrendale, PA: Society of Automotive Engineers, 2008.

[2] Technical Committee. Road vehicles — Vehicle dynamics and road-holding ability — Vocabulary. ISO 8855:2011. Geneva, Switzerland: International Organization for Standardization, 2011.

Version History

R2026a: Set coordinate system parameter

Set the Coordinate system parameter in the Simulation 3D Vehicle with Ground Following block to represent the coordinate system for actor transformation in the 3D environment.

R2024a: Requires Simulink 3D Animation

Simulating models with the Simulation 3D Vehicle with Ground Following block requires Simulink 3D Animation.