Simulation 3D Physics Vehicle

Implement controllable 6DOF vehicle 3D environment

• Library:
• Vehicle Dynamics Blockset / Vehicle Scenarios / Sim3D / Sim3D Vehicle / Components

Description

The Simulation 3D Physics Vehicle block implements a controllable 10DOF vehicle in the 3D simulation environment, with a vertical DOF for each vehicle and 6DOF for the chassis.

To use the Simulation 3D Physics Vehicle block, ensure that the Simulation 3D Scene Configuration block is in your model. If you set the Sample time parameter of the Simulation 3D Physics Vehicle block to `-1`, the block uses the sample time specified in the Simulation 3D Scene Configuration block.

The block input uses the vehicle Z-down right-handed (RH) Cartesian coordinate system defined in SAE J6701. 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

Verify that the Simulation 3D Scene Configuration block executes before the Simulation 3D Physics Vehicle block. That way, the Unreal Engine® 3D visualization environment prepares the data before the Simulation 3D Physics Vehicle block receives it. To check the block execution order, right-click the blocks and select Properties. On the General tab, confirm these Priority settings:

• Simulation 3D Scene Configuration`0`

• Simulation 3D Physics Vehicle`-1`

Ports

Input

expand all

Normalized steer angle, specified as a scalar. `SteerCmd` corresponds to the minimum and maximum range of the steering angle as determined by the`Front wheel max steer angle` and ```Rear wheel max steer angle``` parameters, respectively

Normalized acceleration torque request to the vehicle powertrain, specified as a scalar. The exact response will be characterized by the engine, transmission and other vehicle parameters.

Normalized deceleration torque request to the vehicle braking system, specified as a scalar. The exact braking response will be characterized by the engine, transmission and other vehicle parameters.

Gear input, specified as either `1`, `-1`, or `0`, with:

• `1` – Forward shift gear.

• `-1` – Reverse gear.

• `0` – Neutral gear.

If manual shift mode is selected, then the vehicle will shift according to what the signal is, but the values listed will still apply. Any input set that doesn't correspond to a valid gear will be ignored.

Output

expand all

Bus signal containing these block values.

SignalDescriptionValueUnits
`InertFrm``Cg``Disp``X`Vehicle CG displacement along the earth-fixed X-axis

Computed

m
`Y`Vehicle CG displacement along the earth-fixed Y-axis

Computed

m

`Z`Vehicle CG displacement along the earth-fixed Z-axis`0`m
`Vel``Xdot`Vehicle CG velocity along the earth-fixed X-axis

Computed

m/s

`Ydot`Vehicle CG velocity along the earth-fixed Y-axis

Computed

m/s
`Zdot`Vehicle CG velocity along the earth-fixed Z-axis`0`m/s
`Ang``phi`Rotation of the vehicle-fixed frame about the earth-fixed X-axis (roll)`0`rad
`theta`Rotation of the vehicle-fixed frame about the earth-fixed Y-axis (pitch)`0`rad
`psi`Rotation of the vehicle-fixed frame about the earth-fixed Z-axis (yaw)

Computed

`BdyFrm``Cg``Vel``xdot`Vehicle CG velocity along the vehicle-fixed x-axis

Computed

m/s
`ydot`Vehicle CG velocity along the vehicle-fixed y-axis

Computed

m/s
`zdot`Vehicle CG velocity along the vehicle-fixed z-axis`0`m/s
`Ang``Beta`

Body slip angle, β

`$\beta =\frac{{V}_{y}}{{V}_{x}}$`

Computed

`AngVel``p`Vehicle angular velocity about the vehicle-fixed x-axis (roll rate)`0`rad/s
`q`Vehicle angular velocity about the vehicle-fixed y-axis (pitch rate)`0`rad/s
`r`Vehicle angular velocity about the vehicle-fixed z-axis (yaw rate)

Computed

`Acc``ax`Vehicle CG acceleration along the vehicle-fixed x-axis

Computed

gn
`ay`Vehicle CG acceleration along the vehicle-fixed y-axis

Computed

gn
`az`Vehicle CG acceleration along the vehicle-fixed z-axis`0`gn
`xddot`Vehicle CG acceleration along the vehicle-fixed x-axis

Computed

m/s^2
`yddot`Vehicle CG acceleration along the vehicle-fixed y-axis

Computed

m/s^2
`zddot`Vehicle CG acceleration along the vehicle-fixed z-axis`0`m/s^2
`AngAcc``pdot`Vehicle angular acceleration about the vehicle-fixed x-axis`0`rad/s
`qdot`Vehicle angular acceleration about the vehicle-fixed y-axis`0`rad/s
`rdot`Vehicle angular acceleration about the vehicle-fixed z-axis

Computed

`DCM`

Direction cosine matrix

Computed

`Forces``Tires``FrntTires``Lft``Fx`

Front left tire force, along the vehicle-fixed x-axis

ComputedN
`Fy`

Front left tire force, along the vehicle-fixed y-axis

ComputedN
`Fz`

Front left tire force, along the vehicle-fixed z-axis

ComputedN
`Rght``Fx`

Front right tire force, along the vehicle-fixed x-axis

ComputedN
`Fy`

Front right tire force, along the vehicle-fixed y-axis

ComputedN
`Fz`

Front right tire force, along the vehicle-fixed z-axis

ComputedN
`RearTires``Lft``Fx`

Rear left tire force, along the vehicle-fixed x-axis

ComputedN
`Fy`

Rear left tire force, along the vehicle-fixed y-axis

ComputedN
`Fz`

Rear left tire force, along the vehicle-fixed z-axis

ComputedN
`Rght``Fx`

Rear right tire force, along the vehicle-fixed x-axis

ComputedN
`Fy`

Rear right tire force, along the vehicle-fixed y-axis

ComputedN

SignalDescriptionVariableUnits
`Mtr``MtrSpd`

Applied drive shaft angular speed input

ωi

RPM

`Trans``TransGearCmd`

Commanded gear

Ncmd

N/A

`TransGear`

Engaged gear

N

N/A

The `Info` output parameter is optional.

Vehicle CG velocity along the vehicle-fixed x-axis, in m/s.

Vehicle CG velocity along the vehicle-fixed y-axis, in m/s.

Rotation of the vehicle-fixed frame about the earth-fixed Z-axis (yaw), in rad.

Vehicle angular velocity, `r`, about the vehicle-fixed z-axis (yaw rate), in rad/s.

Parameters

expand all

Chassis

Specify the vehicle type. This table provides links to the vehicle dimensions.

Vehicle type SettingVehicle Dimensions
`Muscle car`

Muscle Car

`Sedan`

Sedan

`Sport utility vehicle`

Sport Utility Vehicle

`Small pickup truck`

Small Pickup Truck

`Hatchback`

Hatchback

`Box truck`

Box Truck

Dependencies

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

Select the color of the vehicle.

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 Physics Vehicle and Simulation 3D Vehicle blocks that you have in your model.

Initial vehicle position specified by a `1`-by-`3` array, in m. Array elements are values along the Coordinate system parameter X-, Y-, and Z- axes, respectively.

Initial vehicle rotation specified by a `1`-by-`3` array, in rad. Array elements are values about the Coordinate system parameter X-, Y-, and Z- axes, respectively.

Vehicle mass, in kg. This value does not include the wheel masses.

Vehicle drag coefficient, dimensionless.

The vehicle track width refers to the distance between the wheels, or the axle length, specified in meters. This parameter is only used for custom mesh options.

Height of chassis used to calculate drag force, specified in meters.

Offset in center of mass, specified as a three element vector, in meters.

Scaling of inertia tensor, specified as a three element dimensionless vector.

Powertrain and Driveline

Powertrain

Motor torque indices, in N·m. You can use these pre-transmission values to represent either an electric motor or a conventional engine.

Data Types: `double`

Motor speed breakpoints, in rpm.

Data Types: `double`

Max powertrain speed, in rpm. If you select an automatic transmission option, this value also corresponds to the normalized shift points used in the up and downshift logic.

Data Types: `double`

Powertrain rotational inertia, in kg·m2.

Data Types: `double`

Powertrain damping at full max torque request, in kg·m2/s.

Data Types: `double`

Powertrain damping at zero torque request, in gear, in kg·m2/s.

Data Types: `double`

Powertrain damping at zero torque request, in neutral, in kg·m2/s.

Data Types: `double`

Driveline

For both `Limited Slip` and `Open` differentials, the block implements a differential as a planetary bevel gear train. The block matches the driveshaft bevel gear to the crown (ring) bevel gear.

If you select `Limited Slip`, the block prevents one of the wheels from slipping by splitting the torque applied to the left and right axles. With different torque applied to the axles, the wheels can move at different angular velocities, preventing slip.

Implement rear wheel, front wheel, or all wheel drive.

Implement an automatic or manual transmission.

Note

A response is required for the `GearCmd` input even if `Transmission type` is set to `Automatic`.

Clutch slip torque, specified as a scalar in N·m.

Data Types: `double`

Time taken to complete a shift, specified as a scalar in s.

Data Types: `double`

Minimum time the transmission will stay in a newly selected gear to mitigate shift hunting, specified as a scalar in s.

Data Types: `double`

Normalized engine speeds with respect to the ```Max powertrain speed``` parameter, at which a shift up for forward gears will be initiated, specified as a scalar in s.

Data Types: `double`

Normalized engine speeds with respect to the ```Max powertrain speed``` parameter, at which a shift down for forward gears will be initiated, specified as a scalar in s.

Data Types: `double`

Gear ratios, dimensionless.

Note

At least one negative ratio is required for reverse gear. A neutral ratio is also required such that the length of the array should correspond to the number of forward gears plus two one for reverse and one for neutral.

Data Types: `double`

Gear number vector, dimensionless.

Data Types: `double`

Front to rear torque split ratio, dimensionless.

`1` indicates 100% torque to the front, whereas `0` indicates 100% to the rear.

Final drive ratio, dimensionless. This is the post transmission ratio, typically found in a differential or final drive gearbox.

Data Types: `double`

Steering and Brakes

Steering

Front wheel max steer angle, in radians. This is the absolute angle which the front wheels will turn with a `-1` or `1` steer command input signal

Data Types: `double`

Rear wheel max steer angle, in radians. This is the absolute angle which the rear wheels will turn with a `-1` or `1` steer command input signal

Data Types: `double`

Constant value of percent Ackerman, in percent. A value of `100` indicates an ideal Ackermann inside or outside steering adjustment, while `0` indicates a pure parallel steer adjustment.

Data Types: `double`

Maximum steering ratio breakpoints, dimensionless. This is the gain by which the steering command is affected by the vehicle speed brake points.

Data Types: `double`

Steering ratio speed breakpoints, in m/s. This is the vehicle forward speed break points used by the steer ratio gains.

Data Types: `double`

Brakes

Maximum front wheel torque, in N·m. This is the maximum braking torque applied to the front wheels corresponding to the normalized `DecelCmd` input.

Data Types: `double`

Maximum rear wheel torque, in N·m. This is the maximum braking torque applied to the rear wheels corresponding to the normalized `DecelCmd` input.

Data Types: `double`

Front wheels affected by handbrake.

Data Types: `Boolean`

Rear wheels affected by handbrake.

Data Types: `Boolean`

Enable handbrake input.

Data Types: `Boolean`

Suspension, Wheels and Tires

Suspension

Front suspension force offset, specified as a scalar in meters.

Maximum front suspension compression or jounce, specified as a scalar in meters. Jounce is the upward movement or compression of suspension components.

Maximum front suspension extension or rebound, specified as a scalar in meters. Rebound is the downward movement or extension of suspension components.

Natural frequency of front suspension, in Hz. Suspension frequencies are the rate that a spring oscillates after applying a load (or hitting a bump).

Damping ratio of front suspension, dimensionless. Damping ratio is the coefficient of the damper at its peak level, where the vehicle will be in a completely stable state.

Rear suspension force offset, specified as a scalar in meters.

Maximum rear suspension compression or jounce, specified as a scalar in meters. Jounce is the upward movement or compression of suspension components.

Maximum rear suspension extension or rebound, specified as a scalar in meters. Rebound is the downward movement or extension of suspension components.

Natural frequency of rear suspension, in Hz. Suspension frequencies are the rate that a spring oscillates after applying a load (or hitting a bump).

Wheels

Front wheel mass, in kg.

Data Types: `double`

Front wheel damping, in N·m/s.

Data Types: `double`

Rear wheel mass, in kg.

Data Types: `double`

Rear wheel damping, in N·m/s.

Data Types: `double`

Tires

Front tire max lateral stiffness factor, dimensionless.

Data Types: `double`

Front tire lateral stiffness, dimensionless.

Data Types: `double`

Front tire longitudinal stiffness, dimensionless.

Data Types: `double`

Front tire max lateral stiffness factor, dimensionless.

Data Types: `double`

Rear tire lateral stiffness, dimensionless.

Data Types: `double`

Front tire longitudinal stiffness, dimensionless.

Data Types: `double`

Nominal friction scale, dimensionless.

Data Types: `double`

Light Controls

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.

LightsLight Parameters

• High beam intensity

• Low beam intensity

• High beam cone half angle

• Low beam cone half angle

Brake lights

Brake light intensity

Reverse lights

Reverse light intensity

Turn signal lights

• Turn signal light intensity

• Period

• Pulse width

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

Dependencies

To enable this parameter, select Enable light controls.

Data Types: `int8` | `uint8`

High beam intensity, in cd.

Dependencies

To enable this parameter, select Enable light controls.

Data Types: `double`

Low beam intensity, in cd.

Dependencies

To enable this parameter, select Enable light controls.

Data Types: `double`

High beam cone half angle, in rad.

Dependencies

To enable this parameter, select Enable light controls.

Data Types: `double`

Low beam cone half angle, in rad.

Dependencies

To enable this parameter, select Enable light controls.

Data Types: `double`

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.

Data Types: `double`

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.

Brake Lights

Brake light intensity, in cd/m^2.

Dependencies

To enable this parameter, select Enable light controls.

Data Types: `double`

Reverse Lights

Reverse light intensity, in cd/m^2.

Dependencies

To enable this parameter, select Enable light controls.

Data Types: `double`

Turn Signal Lights

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

Dependencies

To enable this parameter, select Enable light controls.

Data Types: `double`

Turn signal light period, in s.

Dependencies

To enable this parameter, select Enable light controls.

Data Types: `double`

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

Dependencies

To enable this parameter, select Enable light controls.

Data Types: `double`

Sample Time

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

Ground Truth

Select to return location and orientation.

Data Types: `Boolean`

Select to return nominal vehicle state feedback

Data Types: `Boolean`

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

Introduced in R2022b