ultrasonicDetectionGenerator
Generate ultrasonic range detections in driving scenario or RoadRunner Scenario
Since R2022a
Description
The ultrasonicDetectionGenerator
System object™ generates detections from an ultrasonic sensor mounted on an ego vehicle. The
detections are range measurements that indicate the distance between the sensor and the
closest point of the detected object. You can use an ultrasonicDetectionGenerator
object in a scenario containing actors and
trajectories, which you can create by using a drivingScenario
object.
You can also use the ultrasonicDetectionGenerator
object with vehicle
actors in RoadRunner Scenario simulation. First you must create a SensorSimulation
object to interface sensors with RoadRunner Scenario and then register the lidar as a sensor model using the addSensors
object function before simulation.
To generate ultrasonic detections:
Create the
ultrasonicDetectionGenerator
object and set its properties.Call the object with arguments, as if it were a function.
To learn more about how System objects work, see What Are System Objects?
Creation
Syntax
Description
creates an ultrasonic
= ultrasonicDetectionGeneratorultrasonicDetectionGenerator
object with
default property values to generate range detections for a simulated ultrasonic
sensor.
sets properties using
one or more name-value arguments. For example,
ultrasonic
= ultrasonicDetectionGenerator(Name=Value
)ultrasonicDetectionGenerator(MountingLocation=[1 0 0.5],MountingAngles=[0 0
pi/20])
specifies the mounting location and angle of the ultrasonic sensor on
the ego vehicle.
Properties
Unless otherwise indicated, properties are nontunable, which means you cannot change their
values after calling the object. Objects lock when you call them, and the
release
function unlocks them.
If a property is tunable, you can change its value at any time.
For more information on changing property values, see System Design in MATLAB Using System Objects.
SensorIndex
— Unique sensor identifier
1
(default) | positive integer
Unique sensor identifier, specified as a positive integer. This property distinguishes detections that come from different sensors in a multisensor system.
Example: 5
Data Types: double
UpdateRate
— Sensor update rate
10
(default) | positive real scalar
Sensor update rate, specified as a positive real scalar, in Hz. The value of this
property must be an integer multiple of the simulation update rate defined by the
associated drivingScenario
object. Simulation updates
between sensor updates contain no detections
Example: 5
Data Types: double
MountingLocation
— Sensor mounting location on ego vehicle
[3.4 0 0.2]
(default) | 1-by-3 real-valued vector of form [x
y
z]
Sensor mounting location on the ego vehicle, specified as a 1-by-3 real-valued vector of the form [x y z]. This property defines the coordinates of the sensor in meters, along the x-, y-, and z-axes relative to the ego vehicle origin, where:
The x-axis points forward from the vehicle.
The y-axis points to the left of the vehicle.
The z-axis points up from the ground.
The default value defines an ultrasonic sensor that is mounted at the center of the front bumper of a sedan.
For more details on the ego vehicle coordinate system, see Coordinate Systems in Automated Driving Toolbox.
Data Types: double
MountingAngles
— Sensor mounting orientation on ego vehicle
[0 0 0]
(default) | 1-by-3 real-valued vector of form [zyaw
ypitch
xroll]
Sensor mounting orientation on ego vehicle, specified as a 1-by-3 real-valued vector of form [zyaw ypitch xroll]. This property defines the intrinsic Euler angle rotation of the sensor, in degrees, around the z-, y-, and x-axes with respect to the ego vehicle body frame, where:
zyaw, or yaw angle, rotates the sensor around the z-axis of the ego vehicle.
ypitch, or pitch angle, rotates the sensor around the y-axis of the ego vehicle. This rotation is relative to the sensor position that results from the zyaw rotation.
xroll, or roll angle, rotates the sensor around the x-axis of the ego vehicle. This rotation is relative to the sensor position that results from the zyaw and ypitch rotations.
These angles are clockwise-positive when looking in the forward direction of the z-axis, y-axis, and x-axis, respectively. If you visualize sensor data from a bird's-eye view perspective, then the yaw angle is counterclockwise-positive because you are viewing the data in the negative direction of the z-axis, which points up from the ground.
For more details on this coordinate system, see Coordinate Systems in Automated Driving Toolbox.
Data Types: double
FieldOfView
— Angular field of view of ultrasonic sensor
[70 35]
(default) | 1-by-2 positive real-valued vector of form [azfov elfov]
Angular field of view of the ultrasonic sensor, specified as a 1-by-2 positive
real-valued vector of the form [azfov elfov]
. The field of view
defines the total angular extent spanned by the sensor. You must specify the azimuth
field of view azfov
in the range (0, 360], and the elevation field of
view elfov
in the range (0, 180]. Units are in degrees.
Data Types: double
DetectionRange
— Detection range vector of ultrasonic sensor (m)
[0.03 0.15 5.5]
(default) | 1-by-3 nonnegative real-valued vector of form [minDetOnlyRange
minDistRange maxDistRange]
Detection range vector of the ultrasonic sensor, specified as a 1-by-3 nonnegative
real-valued vector of the form [minDetOnlyRange minDistRange
maxDistRange]
, where minDetOnlyRange < minDistRange <
maxDistRange
. Units are in meters. These values determine the detections and
distance values returned by the ultrasonic sensor.
When the detected object is at a distance between
minDistRange
andmaxDistRange
, the sensor returns a positive distance value.When the detected object is at a distance between
minDetOnlyRange
andminDistRange
, the sensor detects the object, but cannot determine the distance and returns a value of0
.When the object is at a distance below
minDetOnlyRange
or abovemaxDistRange
, the sensor returns an empty cell array.
Data Types: double
Profiles
— Actor profiles
structure | array of structures
Actor profiles, specified as a structure or as an array of structures. Each structure contains the physical and radar characteristics of an actor.
If
ActorProfiles
is a single structure, all actors passed into theultrasonicDetectionGenerator
object use this profile.If
ActorProfiles
is an array, each actor passed into the object must have a unique actor profile.
To generate an array of structures for your driving scenario, use the
actorProfiles
function. The table shows
the valid structure fields. If you do not specify a field, that field is set to its
default value. If no actors are passed into the object, then the
ActorID
field is not included.
Field | Description |
---|---|
ActorID | Scenario-defined actor identifier, specified as a positive integer. |
ClassID | Classification identifier, specified as a nonnegative integer.
0 is reserved for an object of an unknown or unassigned
class. |
Length | Length of actor, specified as a positive real scalar. The default is
4.7 . Units are in meters. |
Width | Width of actor, specified as a positive real scalar. The default is
1.8 . Units are in meters. |
Height | Height of actor, specified as a positive real scalar. The default is
1.4 . Units are in meters. |
OriginOffset | Offset of the rotational center of the actor from its geometric
center, specified as an [x
y
z] real-valued vector. The rotational center, or origin,
is located at the bottom center of the actor. For vehicles, the rotational
center is the point on the ground beneath the center of the rear axle. The
default is |
RCSPattern | Radar cross-section pattern of actor, specified as a
numel(RCSElevationAngles) -by-numel(RCSAzimuthAngles)
real-valued matrix. The default is [10 10; 10 10] . Units
are in decibels per square meter. |
RCSAzimuthAngles | Azimuth angles corresponding to rows of RCSPattern ,
specified as a vector of real values in the range [–180, 180]. The default is
[-180 180] . Units are in degrees. |
RCSElevationAngles | Elevation angles corresponding to rows of RCSPattern ,
specified as a vector of real values in the range [–90, 90]. The default is
[-90 90] . Units are in degrees. |
For full definitions of the structure fields, see the actor
and vehicle
functions.
Data Types: struct
Usage
Description
[
also returns a logical value, dets
,isValidTime
] = ultrasonic(targets
,simTime
)isValidTime
, indicating whether
simTime
is a valid time for generating detections. If
simTime
is an integer multiple of the reciprocal of the UpdateRate
property value, then isValidTime
is
1
(true
).
Input Arguments
targets
— Target actor poses
structure | structure array
Target actor poses, specified as a structure or structure array. Each structure
describes the pose of a target actor relative to the ego vehicle. To generate these
structures, use the targetPoses
function. You can also
create these structures manually. Do not include the ego vehicle pose in this
argument.
This table shows the required fields for the structures.
Field | Description |
---|---|
ActorID | Scenario-defined actor identifier, specified as a positive integer. |
ClassID | Classification identifier, specified as a nonnegative integer. 0
represents an object of an unknown or unassigned class. |
Position | Position of actor, specified 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, specified as a real-valued vector of the form [vx vy vz]. Units are in meters per second. |
Roll | Roll angle of actor, specified as a real scalar. Units are in degrees. |
Pitch | Pitch angle of actor, specified as a real scalar. Units are in degrees. |
Yaw | Yaw angle of actor, specified as a real scalar. Units are in degrees. |
AngularVelocity | Angular velocity (ω) of actor in the x-, y-, and z-directions, specified as a real-valued vector of the form [ωx ωy ωz]. Units are in degrees per second. |
simTime
— Current simulation time
nonnegative real scalar
Current simulation time, specified as a nonnegative real scalar in seconds.
Example: 10.5
Data Types: double
Output Arguments
dets
— Generated detections
cell array of objectDetection
objects
Generated detections, returned as a cell array of objectDetection
objects. Each object contains these
properties:
Property | Description |
---|---|
Time | Measurement time |
Measurement | Distance measurement to the closest object |
MeasurementNoise | Measurement noise covariance matrix |
SensorIndex | Unique ID of the sensor |
ObjectClassID | Object classification |
ObjectAttributes | Additional information passed to tracker |
MeasurementParameters | Parameters used by initialization functions of nonlinear Kalman tracking filters |
This table describes the additional information in the
ObjectAttributes
property.
ObjectAttributes
Attribute | Definition |
---|---|
TargetIndex | Identifier of the actor, ActorID , that generated the
detection. For false alarms, this value is negative. |
PointOnTarget | Coordinate of the point on the detected object that the sensor used to compute the distance measurement. It is in the vehicle coordinate system. |
For MeasurementParameters
, the measurements are relative to
the parent frame. The parent frame is the ego vehicle body.
MeasurementParameters
Parameter | Definition |
---|---|
Frame | Enumerated type indicating the frame used to report measurements. The
Frame is always set to 'spherical'
and the detections are reported in spherical coordinates for ultrasonicDetectionGenerator . |
OriginPosition | 3-D vector offset of the sensor origin from the parent frame origin. |
OriginVelocity | Velocity of the sensor coordinate system with respect to the parent frame. |
IsParentToChild | Logical scalar indicating if Orientation performs a
frame rotation from the parent coordinate frame to the child coordinate
frame. When IsParentToChild is false, then
Orientation performs a frame rotation from the child
coordinate frame to the parent coordinate frame. |
HasAzimuth | Indicates whether measurements contain azimuth components. |
HasRange | Indicates whether measurements contain range components. Always
true for ultrasonicDetectionGenerator . |
HasElevation | Indicates whether measurements contain elevation components. Always
false for Ultrasonic Detection
Generator. |
HasVelocity | Indicates whether measurements contain velocity or range rate
components. Always false for ultrasonicDetectionGenerator . |
FieldOfView | 2-D vector containing the azimuth and elevation field of view values of the sensor. |
isValidTime
— Valid time for generating reports
0
| 1
Valid time for generating reports, returned as a logical 0
(false
) or 1
(true
).
If the reports dets
generated by the sensor are invalid
because the sensor generated them at a time inconsistent with the sensor update rate,
then isValidTime
is 0
.
The sensor generates reports only when the current simulation time,
simTime
, is an integer multiple of the time interval at which
the sensor generates reports. This time interval is equal to the reciprocal of the
UpdateRate
property value.
Data Types: logical
Object Functions
To use an object function, specify the
System object as the first input argument. For
example, to release system resources of a System object named obj
, use
this syntax:
release(obj)
Examples
Generate Ultrasonic Detections of Multiple Vehicles
Use a simulated ultrasonic sensor to generate detections for multiple vehicles in a driving scenario.
Create Driving Scenario
Create a driving scenario containing a three-lane road using lane specifications.
scenario = drivingScenario; roadCenters = [-120 30 0;-60 0 0;0 0 0; 60 0 0; 120 30 0]; lspc = lanespec(3); road(scenario,roadCenters,Lanes=lspc);
Create an ego vehicle that travels in the center lane at a velocity of 30 m/s.
egovehicle = vehicle(scenario,ClassID=1); egopath = [1.5 0 0; 60 0 0; 111 25 0]; egospeed = 30; smoothTrajectory(egovehicle,egopath,egospeed);
Add a target vehicle that travels ahead of the ego vehicle at 30.5 m/s in the right lane, and changes lanes close to the ego vehicle.
ftargetcar = vehicle(scenario,ClassID=1); ftargetpath = [8 2; 60 -3.2; 120 33]; ftargetspeed = 30.5; smoothTrajectory(ftargetcar,ftargetpath,ftargetspeed);
Add a second target vehicle that travels in the left lane at 32m/s.
ltargetcar = vehicle(scenario,ClassID=1); ltargetpath = [-5.0 3.5 0; 60 3.5 0; 111 28.5 0]; ltargetspeed = 32; smoothTrajectory(ltargetcar,ltargetpath,ltargetspeed);
Display a chase plot from behind the ego vehicle for a 3D view of the scenario..
chasePlot(egovehicle)
Create Ultrasonic Sensors
Create an ultrasonic sensor mounted at the front of the ego vehicle.
frontUltrasonic = ultrasonicDetectionGenerator(1,FieldOfView=[70 35]); frontUltrasonic.Profiles = actorProfiles(scenario);
Create a second ultrasonic sensor mounted on the left side of the ego vehicle.
leftUltrasonic = ultrasonicDetectionGenerator(2,MountingLocation=[0.5 1 0.2],MountingAngles=[90 0 0],FieldOfView=[70 35]); leftUltrasonic.Profiles = actorProfiles(scenario);
Create Bird's-Eye-Plot
Create a bird's-eye-plot for visualizing the sensor data. Add plotters for visualizing the ultrasonic coverage areas, detections, and points on targets. Use a rangeDetectionPlotter
object to visualize ultrasonic detections as arcs and a detectionPlotter
object to visualize the closest points on the target as markers. Add plotters to display the lane markings and vehicle outlines.
% Create bird's eye plot bep = birdsEyePlot(XLim=[-20 20],YLim=[-12 12]); % Plotters for Coverage areas of two ultrasonic sensors fcaPlotter = coverageAreaPlotter(bep,DisplayName="Front Ultrasonic field of view"); plotCoverageArea(fcaPlotter,frontUltrasonic.MountingLocation(1:2), ... frontUltrasonic.DetectionRange(3),frontUltrasonic.MountingAngles(1),frontUltrasonic.FieldOfView(1)); lcaPlotter = coverageAreaPlotter(bep,DisplayName="Left Ultrasonic field of view",FaceColor="y"); plotCoverageArea(lcaPlotter,leftUltrasonic.MountingLocation(1:2), ... leftUltrasonic.DetectionRange(3),leftUltrasonic.MountingAngles(1),leftUltrasonic.FieldOfView(1)); % Range Detection Plotters for Ultrasonic Detections frdPlotter = rangeDetectionPlotter(bep,DisplayName="Front Ultrasonic Ranges"); lrdPlotter = rangeDetectionPlotter(bep,DisplayName="Left Ultrasonic Ranges",LineStyle=":"); % Detection plotters for closest points on targets fdetPlotter = detectionPlotter(bep,DisplayName="Point-On-Target (Front Ultrasonic)",MarkerFaceColor="r"); ldetPlotter = detectionPlotter(bep,DisplayName="Point-On-Target (Rear Ultrasonic)",MarkerFaceColor="k"); % Plotters for vehicle and target outlines, lane markings olPlotter = outlinePlotter(bep); lmPlotter = laneMarkingPlotter(bep,DisplayName="Lane markings");
Run the Simulation and Generate Detections
Run the scenario simulation. At each timestep:
Obtain the ground truth target poses, and generate detections for the two ultrasonic sensors.
Obtain and display the target outlines and lane markings.
When there are valid detections, display the detections and the corresponding points-on-targets generated by the ultrasonic sensor.
while advance(scenario) tgtpose = targetPoses(egovehicle); [fobdets,fisValid] = frontUltrasonic(tgtpose,scenario.SimulationTime); [lobdets,lisValid] = leftUltrasonic(tgtpose,scenario.SimulationTime); [objposition,objyaw,objlength,objwidth,objoriginOffset,color] = targetOutlines(egovehicle); plotOutline(olPlotter,objposition,objyaw,objlength,objwidth, ... OriginOffset=objoriginOffset,Color=color) [lmv,lmf] = laneMarkingVertices(egovehicle); plotLaneMarking(lmPlotter,lmv,lmf) if ~isempty(fobdets) && fisValid franges = fobdets{1}.Measurement; plotRangeDetection(frdPlotter,franges,frontUltrasonic.FieldOfView(1),frontUltrasonic.MountingLocation,frontUltrasonic.MountingAngles) plotDetection(fdetPlotter,fobdets{1}.ObjectAttributes{1}.PointOnTarget(1:2)') end if ~isempty(lobdets) && lisValid lranges = lobdets{1}.Measurement; plotRangeDetection(lrdPlotter,lranges,leftUltrasonic.FieldOfView(1),leftUltrasonic.MountingLocation,leftUltrasonic.MountingAngles) plotDetection(ldetPlotter,lobdets{1}.ObjectAttributes{1}.PointOnTarget(1:2)') end end
Version History
Introduced in R2022a
See Also
Objects
objectDetection
|drivingScenario
|drivingRadarDataGenerator
|visionDetectionGenerator
|lidarPointCloudGenerator
|insSensor
Functions
Apps
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)