monoCamera

Configure monocular camera sensor

Description

The monoCamera object holds information about the configuration of a monocular camera sensor. Configuration information includes the camera intrinsics, camera extrinsics such as its orientation (as described by pitch, yaw, and roll), and the camera location within the vehicle. To estimate the intrinsic and extrinsic camera parameters, see Calibrate a Monocular Camera.

For images captured by the camera, you can use the imageToVehicle and vehicleToImage functions to transform point locations between image coordinates and vehicle coordinates. These functions apply projective transformations (homography), which enable you to estimate distances from a camera mounted on the vehicle to locations on a flat road surface.

Creation

Syntax

sensor = monoCamera(intrinsics,height)

sensor = monoCamera(intrinsics,height,Name,Value)

Description

sensor = monoCamera(intrinsics,height) creates a monoCamera object that contains the configuration of a monocular camera sensor, given the intrinsic parameters of the camera and the height of the camera above the ground. intrinsics and height set the Intrinsics and Height properties of the camera.

sensor = monoCamera(intrinsics,height,Name,Value) sets properties using one or more name-value pairs. For example, monoCamera(intrinsics,1.5,'Pitch',1) creates a monocular camera sensor that is 1.5 meters above the ground and has a 1-degree pitch toward the ground. Enclose each property name in quotes.

Properties

Intrinsics — Intrinsic camera parameters

cameraIntrinsics object | cameraParameters object

Intrinsic camera parameters, specified as either a cameraIntrinsics or cameraParameters object. The intrinsic camera parameters include the focal length and optical center of the camera, and the size of the image produced by the camera.

You can set this property when you create the object. After you create the object, this property is read-only.

Height — Height from road surface to camera sensor

real scalar

Height from the road surface to the camera sensor, specified as a real scalar. The height is the perpendicular distance from the ground to the focal point of the camera. Specify the height in world units, such as meters. To estimate this value, use the estimateMonoCameraParameters function.

Pitch — Pitch angle

real scalar

Pitch angle between the horizontal plane of the vehicle and the optical axis of the camera, specified as a real scalar in degrees. To estimate this value, use the estimateMonoCameraParameters function.

Pitch uses the ISO convention for rotation, with a clockwise positive angle direction when looking in the positive direction of the vehicle's Y_V axis.

For more details, see Angle Directions.

Yaw — Yaw angle

real scalar

Yaw angle between the X_V axis of the vehicle and the optical axis of the camera, specified as a real scalar in degrees. To estimate this value, use the estimateMonoCameraParameters function.

Yaw uses the ISO convention for rotation, with a clockwise positive angle direction when looking in the positive direction of the vehicle's Z_V axis.

For more details, see Angle Directions.

Roll — Roll angle

real scalar

Roll angle of the camera around its optical axis, returned as a real scalar in degrees. To estimate this value, use the estimateMonoCameraParameters function.

Roll uses the ISO convention for rotation, with a clockwise positive angle direction when looking in the positive direction of the vehicle's X_V axis.

For more details, see Angle Directions.

SensorLocation — Location of center of camera sensor

[0 0] (default) | two-element vector

Location of the center of the camera sensor, specified as a two-element vector of the form [x y]. Use this property to change the placement of the camera. Units are in the vehicle coordinate system (X_V, Y_V, Z_V).

By default, the camera sensor is located at the (X_V, Y_V) origin, at the height specified by Height.

WorldUnits — World coordinate system units

'meters' | character vector | string scalar

World coordinate system units, specified as a character vector or string scalar. This property only stores the unit type and does not affect any calculations. Any text is valid.

You can set this property when you create the object. After you create the object, this property is read-only.

Object Functions

imageToVehicle	Convert image coordinates to vehicle coordinates
vehicleToImage	Convert vehicle coordinates to image coordinates

Examples

Create Monocular Camera Object

Create a forward-facing monocular camera sensor mounted on an ego vehicle. Examine an image captured from the camera and determine locations within the image in both vehicle and image coordinates.

Set the intrinsic parameters of the camera. Specify the focal length, the principal point of the image plane, and the output image size. Units are in pixels. Save the intrinsics as a cameraIntrinsics object.

focalLength = [800 800];
principalPoint = [320 240];
imageSize = [480 640];

intrinsics = cameraIntrinsics(focalLength,principalPoint,imageSize);

Specify the position of the camera. Position the camera 2.18 meters above the ground with a 14-degree pitch toward the ground.

height = 2.18;
pitch = 14;

Define a monocular camera sensor using the intrinsic camera parameters and the position of the camera. Load an image from the camera.

sensor = monoCamera(intrinsics,height,'Pitch',pitch);

Ioriginal = imread('road.png');
figure
imshow(Ioriginal)
title('Original Image')

Determine the image coordinates of a point 10 meters directly in front of the camera. The X-axis points forward from the camera and the Y-axis points to the left.

xyVehicleLoc1 = [10 0];
xyImageLoc1 = vehicleToImage(sensor,xyVehicleLoc1)

xyImageLoc1 = 1×2

  320.0000  216.2296

Display the point on the image.

IvehicleToImage = insertMarker(Ioriginal,xyImageLoc1);
IvehicleToImage = insertText(IvehicleToImage,xyImageLoc1 + 5,'10 meters');
figure
imshow(IvehicleToImage)
title('Vehicle-to-Image Point')

Determine the vehicle coordinates of a point that lies on the road surface in the image.

xyImageLoc2 = [300 300];
xyVehicleLoc2 = imageToVehicle(sensor,xyImageLoc2)

xyVehicleLoc2 = 1×2

    6.5959    0.1732

The point is about 6.6 meters in front of the vehicle and about 0.17 meters to the left of the vehicle center.

Display the vehicle coordinates of the point on the image.

IimageToVehicle = insertMarker(Ioriginal,xyImageLoc2);
displayText = sprintf('(%.2f m, %.2f m)',xyVehicleLoc2);
IimageToVehicle = insertText(IimageToVehicle,xyImageLoc2 + 5,displayText);

figure
imshow(IimageToVehicle)
title('Image-to-Vehicle Point')

Generate Visual Detections from Monocular Camera

Create a vision sensor by using a monocular camera configuration, and generate detections from that sensor.

Specify the intrinsic parameters of the camera and create a monoCamera object from these parameters. The camera is mounted on top of an ego vehicle at a height of 1.5 meters above the ground and a pitch of 1 degree toward the ground.

focalLength = [800 800];
principalPoint = [320 240];
imageSize = [480 640];
intrinsics = cameraIntrinsics(focalLength,principalPoint,imageSize);

height = 1.5;
pitch = 1;
monoCamConfig = monoCamera(intrinsics,height,'Pitch',pitch);

Create a vision detection generator using the monocular camera configuration.

visionSensor = visionDetectionGenerator(monoCamConfig);

Generate a driving scenario with an ego vehicle and two target cars. Position the first target car 30 meters directly in front of the ego vehicle. Position the second target car 20 meters in front of the ego vehicle but offset to the left by 3 meters.

scenario = drivingScenario;
egoVehicle = vehicle(scenario,'ClassID',1);
targetCar1 = vehicle(scenario,'ClassID',1,'Position',[30 0 0]);
targetCar2 = vehicle(scenario,'ClassID',1,'Position',[20 3 0]);

Use a bird's-eye plot to display the vehicle outlines and sensor coverage area.

figure
bep = birdsEyePlot('XLim',[0 50],'YLim',[-20 20]);

olPlotter = outlinePlotter(bep);
[position,yaw,length,width,originOffset,color] = targetOutlines(egoVehicle);
plotOutline(olPlotter,position,yaw,length,width);

caPlotter = coverageAreaPlotter(bep,'DisplayName','Coverage area','FaceColor','blue');
plotCoverageArea(caPlotter,visionSensor.SensorLocation,visionSensor.MaxRange, ...
    visionSensor.Yaw,visionSensor.FieldOfView(1))

Obtain the poses of the target cars from the perspective of the ego vehicle. Use these poses to generate detections from the sensor.

poses = targetPoses(egoVehicle);
[dets,numValidDets] = visionSensor(poses,scenario.SimulationTime);

Display the (X,Y) positions of the valid detections. For each detection, the (X,Y) positions are the first two values of the Measurement field.

for i = 1:numValidDets
    XY = dets{i}.Measurement(1:2);
    detXY = sprintf('Detection %d: X = %.2f meters, Y = %.2f meters',i,XY);
    disp(detXY)
end

Detection 1: X = 19.09 meters, Y = 2.79 meters
Detection 2: X = 27.81 meters, Y = 0.08 meters

More About

Vehicle Coordinate System

In the vehicle coordinate system (X_V, Y_V, Z_V) defined by monoCamera:

• The X_V-axis points forward from the vehicle.

• The Y_V-axis points to the left, as viewed when facing forward.

• The Z_V-axis points up from the ground to maintain the right-handed coordinate system.

The default origin of this coordinate system is on the road surface, directly below the camera center. The focal point of the camera defines this center point.

To change the placement of the origin within the vehicle coordinate system, update the SensorLocation property.

For more details about the vehicle coordinate system, see Coordinate Systems in Automated Driving Toolbox.

Angle Directions

The monocular camera sensor uses clockwise positive angle directions when looking in the positive direction of the Z-, Y-, and X-axes, respectively.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2017a

R2018a: Direction of yaw angle rotation adjusted

Starting in R2018a, the monoCamera object uses the correct direction of rotation for the yaw angle. When you look in the positive direction of the vehicle's Z-axis, the yaw angle is now positive in the clockwise direction. Previously, this angle was positive in the counterclockwise direction.

If you are using R2017b or earlier, to use the correct direction of rotation, update the yaw angle to its negative value. For example, to update the yaw angle for a monoCamera object named sensor, use this code:

sensor.Yaw = -sensor.Yaw;