sim3d.sensors.IdealCamera

Create ideal camera actor to capture image and make it available in MATLAB

Since R2022b

Description

Use the sim3d.sensors.IdealCamera object to create a virtual ideal camera object in the 3D environment. You can use the ideal camera actor to capture an image and return the image to MATLAB^®. After you create a sim3d.sensors.IdealCamera object you can modify aspects of the actor object by setting property values.

Creation

Syntax

idealCamera = sim3d.sensors.IdealCamera()

idealCamera = sim3d.sensors.IdealCamera(Name=Value)

Description

idealCamera = sim3d.sensors.IdealCamera() creates a default sim3d.sensors.IdealCamera object in the 3D environment.

idealCamera = sim3d.sensors.IdealCamera(Name=Value) specifies options using one or more optional name-value arguments. For example, to create an ideal camera actor with horizontal field of view of 60, set HorizontalFieldOfView to 60.

Input 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: idealCamera = sim3d.sensors.IdealCamera('ActorName',"Camera",'ImageSize',[768,1024],'HorizontalFieldOfView',60)

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.sensors.IdealCamera 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.

Translation — Relative translation

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

Relative translation (x,y,z) of the actor object to its parent actor, specified as a real 1-by-3 vector, in m. Use Translation to change the position of the sim3d.sensors.IdealCamera object in the 3D environment along the X, Y, and Z axes of the coordinate system. When you add an actor to the 3D environment, the default parent actor is the Scene Origin at (0,0,0).

Example: Translation = [1 2 1]

Rotation — Relative rotation

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

Relative rotation (roll, pitch, yaw) of the actor object to its parent actor, specified as a real 1-by-3 vector, in rad. Use Rotation to rotate the sim3d.sensors.IdealCamera object in the 3D environment.

Example: Rotation = [pi/4 pi/8 pi/2]

ImageSize — Image size produced by camera

[768,1024] (default) | 1-by-2 real positive integer vector

Image size produced by the sim3d.sensors.IdealCamera object, specified as a real-valued 1-by-2 vector of positive integers of the form [m,n], in pixels. ImageSize is equivalent to the ImageSize (Computer Vision Toolbox) property of a cameraIntrinsics object.

HorizontalFieldOfView — Horizontal field of view in degrees

90 (default) | real nonnegative scalar

Horizontal field of view in degrees, specified as a real nonnegative scalar.

Properties

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.sensors.IdealCamera object.

Children — Children of actor

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.sensors.IdealCamera 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.sensors.IdealCamera object is added to the parent sim3d.World object.

SensorIdentifier — Unique ID of sensor

real positive scalar

This property is read-only.

Unique ID of the sensor, specified as a real positive scalar.

Data Types: uint32

ImageSize — Image size produced by camera

[768,1024] (default) | 1-by-2 real positive integer vector

This property is read-only.

Image size produced by the sim3d.sensors.IdealCamera object, specified as a real-valued 1-by-2 vector of positive integers of the form [m,n], in pixels. ImageSize is equivalent to the ImageSize (Computer Vision Toolbox) property of a cameraIntrinsics object.

HorizontalFieldOfView — Horizontal field of view

90 (default) | real nonnegative scalar

This property is read-only.

Horizontal field of view in degrees, specified as a real nonnegative scalar.

CoordinateSystem — Actor orientation

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

Actor orientation representation in the 3D environment, specified as one of the listed values. The values are not case-sensitive.

• '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

To display the actor transformation in the specified coordinate system, set this property first, and then set the transform properties Translation, Rotation, and Scale. For more details on the different coordinate systems, see Coordinate Systems in Simulink 3D Animation.

Data Types: string

Translation — Relative translation

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

Relative translation (x,y,z) of the actor object to its parent actor, specified as a real 1-by-3 vector, in m. Use Translation to change the position of the sim3d.sensors.IdealCamera object in the 3D environment along the X, Y, and Z axes of the coordinate system. When you add an actor to the 3D environment, the default parent actor is the Scene Origin at (0,0,0).

Example: idealCamera.Translation = [1 2 1]

Rotation — Relative rotation

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

Relative rotation (roll, pitch, yaw) of the actor object to its parent actor, specified as a real 1-by-3 vector, in rad. Use Rotation to rotate the sim3d.sensors.IdealCamera object in the 3D environment.

Example: idealCamera.Rotation = [pi/4 pi/8 pi/2]

Mobility — Type of actor mobility

'sim3d.utils.MobilityTypes.Static' (default) | 'sim3d.utils.MobilityTypes.Movable'

Type of actor mobility to respond to physics, move the actor during simulation, or both, specified as 'sim3d.utils.MobilityTypes.Movable' or 'sim3d.utils.MobilityTypes.Static'.

Example: idealCamera.Mobility = sim3d.utils.MobilityTypes.Movable

Data Types: sim3d.utils.MobilityTypes

Object Functions

read	Return image data captured with ideal camera

Examples

Create Ideal Camera and Extract Data

Create an ideal camera in the 3D environment using the sim3d.sensors.IdealCamera object. You can capture images of the 3D environment and display them in MATLAB®. Use the read function to extract image data 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 ideal camera object using sim3d.sensors.IdealCamera object and set the location of the ideal camera using the Translation property. Add the idealcamera to the world.

idealCamera = sim3d.sensors.IdealCamera( ...
        ActorName="IdealCamera");
idealCamera.Translation = [-3 0 0];
add(world,idealCamera);

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

viewport = createViewport(world,Translation=[-3 0 0]);
sampletime = 1/60;
stoptime = 5;
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 rotates the Cube abut 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.IdealCamera object to get image data from the IdealCamera in the Unreal Engine and uses the image function to display it in MATLAB.

function updateImpl(world)
    sceneImage = read(world.Actors.IdealCamera);
    image(sceneImage);
end

Version History

Introduced in R2022b