read

Return target detections using ultrasonic sensor

Since R2024b

Syntax

[hasObject,point] = read(ultrasonicSensor)

Description

[hasObject,point] = read(ultrasonicSensor) returns target detections from range measurements taken by the ultrasonic sensor specified by ultrasonicSensor in the 3D environment.

Examples

Create Ultrasonic Sensor and Extract Data

Since R2025a

Create a ultrasonic sensor in the 3D environment using the sim3d.sensors.UltrasonicSensor object. You can adjust the detection range and field of view of the sensor for your scene and test scenario. Use the read function to extract the target detection from the 3D environment.

Create a 3D environment and set up communication with the Unreal Engine simulation environment using the output function OutputImpl and the update function UpdateImpl. The sim3d.World object can send and receive data about the 3D environment to and from the Unreal Engine at each simulation step using output and update functions, respectively. 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 in the update function. You can use the update function to read this data or change values after each simulation step.

world = sim3d.World('Output',@outputImpl,'Update',@updateImpl);

Create a box actor in the 3D environment using the sim3d.Actor object and add the box to the world.

cube = sim3d.Actor( ...
        ActorName="Cube", ...
        Mobility=sim3d.utils.MobilityTypes.Movable);
createShape(cube,"box");
add(world,cube);

Create an ultrasonic sensor object using the sim3d.sensors.UltrasonicSensor object and set the location, range, and field of view of the sensor. Add the UltrasonicSensor to the world.

UltrasonicSensor = sim3d.sensors.UltrasonicSensor( ...
        ActorName = "UltrasonicSensor", ...
        Translation = [-3, 0, 0], ...
        Range = 10.0, ...
        FieldOfView = [20 20]);
add(world,UltrasonicSensor);

Set the Simulation 3D Viewer window point of view and run the co-simulation.

viewport = createViewport(world,Translation=[-3 0 0]);
sampletime = 0.5;
stoptime = 10;
run(world,sampletime,stoptime);

2.499793e+00 1.819821e-02 0
2.499172e+00 3.639460e-02 0
2.498137e+00 5.458734e-02 0
2.496687e+00 7.277462e-02 0
2.491871e+00 1.499477e-01 0
2.489009e+00 1.679558e-01 0
2.485736e+00 1.859328e-01 0
2.482051e+00 2.038770e-01 0
2.477953e+00 2.217864e-01 0
2.473444e+00 2.396593e-01 0
2.468521e+00 2.574937e-01 0
2.463184e+00 2.752877e-01 0
2.457434e+00 2.930396e-01 0
2.451269e+00 3.107473e-01 0
2.444688e+00 3.284091e-01 0
2.437690e+00 3.460229e-01 0
2.430275e+00 3.635869e-01 0
2.422441e+00 3.810993e-01 0
2.414569e+00 3.965727e-01 0
2.410634e+00 3.906916e-01 0
2.406754e+00 3.847855e-01 0

Output Function

The output function sends data about the actor to the Unreal Engine environment at each simulation step. For this example, the function rotates the Cube about its Z-axis by updating the Rotation property of the Cube at each simulation step.

function outputImpl(world)
    world.Actors.Cube.Rotation(3) = world.Actors.Cube.Rotation(3) ...
    + 0.01; 
end

Update Function

The update function reads data from the Unreal Engine environment at each simulation step. For this example, the update function uses the read function of the sim3d.sensors.UltrasonicSensor object to get the distance to the closest target from the UltrasonicSensor in the Unreal Engine environment.

function updateImpl(world)
    [~, point] = world.Actors.UltrasonicSensor.read();
    fprintf("%d %d %d\n", point(1), point(2), point(3));
end

Input Arguments

ultrasonicSensor — Virtual ultrasonic sensor that detects target

sim3d.sensors.UltrasonicSensor object

Virtual ultrasonic sensor that detects target in the 3D environment, specified as a sim3d.sensors.UltrasonicSensor object.

Example: ultrasonicSensor = sim3d.sensors.UltrasonicSensor

Output Arguments

hasObject — Detectable object present in sensor field-of-view

boolean scalar

Detectable object present in the sensor field-of-view, returned as a Boolean scalar. An object is considered detectable if its closest distance to the sensor is greater than the minimum detection-only range specified in the Range argument.

point — Distance to closest object

real 1-by-3 vector

Distance to the closest object in (x,y,z), returned as a real 1-by-3 vector, in meters.

Version History

Introduced in R2024b