plotCamera

Plot a camera in 3-D coordinates

Syntax

cam = plotCamera

cam = plotCamera(cameraTable)

cam = plotCamera(Name=Value)

Description

cam = plotCamera plots a default camera in 3-D coordinates in the current axes. The function returns cam, a Camera object that contains the properties of the plotted camera.

cam = plotCamera(cameraTable) plots one or more cameras specified by cameraTable.

cam = plotCamera(Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, Opacity=0.4 sets the opacity of the plotted camera to 0.4.

The name-value pair arguments set the associated properties of the plotted camera visualization object.

Examples

Plot Animated Camera Using Absolute Pose

Create a rigidtform3d object.

initialRotation = [1  0  0;
                   0  0  1;
                   0 -1  0];
initialTranslation = [10 0 20];
pose = rigidtform3d(initialRotation,initialTranslation);

Plot a camera with an opacity of zero and an absolute pose based on the created rigidtform3d object.

cam = plotCamera(AbsolutePose=pose,Opacity=0)

cam = 
  Camera with properties:

           Parent: [1x1 Axes]
             Size: 1
     AbsolutePose: [1x1 rigidtform3d]
          Visible: 1
      AxesVisible: 0
    ButtonDownFcn: ''
            Color: [1 0 0]
          Opacity: 0
            Label: ''

Set viewing properties for the current axes.

grid on
axis equal
axis manual

Expand the viewable limits of each axis. These changes enable the entire animation to be visible in the next step.

xlim([-15 20]);
ylim([-15 20]);
zlim([15 25]);

Rotate the camera around the y-axis.

for theta = 0:10:1800
    updateAngles = [0 -theta 0];
    updateTranslation = [10*cosd(theta) 10*sind(theta) 20];
    updateTform = rigidtform3d(updateAngles, updateTranslation);
    cam.AbsolutePose = rigidtform3d(initialRotation * updateTform.R, updateTform.Translation);
    drawnow();
end

Visualize Camera Extrinsics

Create a set of calibration images.

imds = imageDatastore(fullfile(toolboxdir("vision"),"visiondata","calibration","slr"));

Detect the checkerboard corners in the images.

[imagePoints,boardSize] = detectCheckerboardPoints(imds.Files);

Generate the world coordinates of the checkerboard corners in the pattern-centric coordinate system, with the upper-left corner at (0,0). Set the square size to 29 mm.

squareSize = 29;
worldPoints = generateCheckerboardPoints(boardSize,squareSize);

Load an image at its new location.

imOrig = imread(fullfile(toolboxdir("vision"),"visiondata","calibration","slr","image9.jpg"));
figure;
imshow(imOrig,InitialMagnification=50);
title("Input Image");

Calibrate the camera.

cameraParams = estimateCameraParameters(imagePoints,worldPoints,"ImageSize",size(imOrig,1:2));

Undistort the image.

im = undistortImage(imOrig,cameraParams.Intrinsics);

Find the reference object in the new image.

[imagePoints,boardSize] = detectCheckerboardPoints(im);

Compute the new extrinsics.

camExtrinsics = estimateExtrinsics(imagePoints,worldPoints,cameraParams.Intrinsics);

Plot the world points.

figure;
plot3(worldPoints(:,1),worldPoints(:,2),zeros(size(worldPoints, 1),1),"*");
hold on

Mark the origin.

plot3(0,0,0,"g*");

Compute the camera location and orientation.

absPose = extr2pose(camExtrinsics);

Plot the camera.

cam = plotCamera(AbsolutePose=absPose,Size=20);

Make the z -axis point down.

set(gca,CameraUpVector=[0 0 -1]);

Set the view parameters.

camorbit(gca,-110,60,data=[0 0 1]);
axis equal
grid on

Turn on 3-D rotation.

cameratoolbar('SetMode','orbit');

Label the axes.

xlabel("X (mm)");
ylabel("Y (mm)");
zlabel("Z (mm)");

Input Arguments

cameraTable — Properties of cameras for visualization

table

Properties of cameras for visualization, specified as a table. Each row represents a single camera. Each column title must match the name-part of a name-value pair argument. The nth-row values set the properties for the nth element of cam. You cannot specify values for Parent. If the table contains a ViewId column, then the view IDs are used to set the Label values of the cameras.

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: Size=0.3 specifies the camera-base width as 0.3.

AbsolutePose — Camera absolute pose

rigidtform3d object

Camera absolute pose in the world coordinate system, specified as a rigidtform3d object.

Size — Camera-base width

1 (default) | positive real number

Camera-base width, specified as a positive real number.

Label — Camera label

'' (default) | character vector | string scalar

Camera label, specified as a character vector or a string scalar.

Color — Camera color

[1 0 0] (red) (default) | RGB triplet

Camera color, specified as an RGB triplet. An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0, 1].

Opacity — Camera opacity

0.2 (default) | scalar in the range [0, 1]

Camera opacity, specified as a scalar in the range [0, 1].

Visible — Camera visibility

true or 1 (default) | false or 0

Camera visibility, specified as a numeric or logical 1 (true) or 0 (false).

AxesVisible — Camera axes visibility

false or 0 (default) | true or 1

Camera axes visibility, specified as a numeric or logical 1 (true) or 0 (false).

ButtonDownFcn — Callback function

'' (default) | function handle

Callback function, specified as a function handle that executes when you click the camera.

Parent — Output axes

axes handle

Output axes, specified as an axes handle. By default, plotCamera uses the current axes handle. To return the current axes, use the gca function.

Output Arguments

cam — Camera visualization object

Camera object | row vector of Camera objects

Camera visualization object, returned as one of these options.

• Camera object — The function returns this option when plotting a single camera. Name-value arguments or cameraTable input elements set the corresponding Camera object properties.

• Row vector of Camera objects — The function returns this option when plotting multiple cameras. The nth -row values of the cameraTable input set the properties for the nth Camera object in this vector.

Camera objects are created using the vision.graphics.Camera class, which contains the following properties:

• Parent

• Size

• AbsolutePose

• Visible

• AxesVisible

• ButtonDownFcn

• Color

• Opacity

• Label

Version History

Introduced in R2015a

R2022b: Specify AbsolutePose as a rigidtform3d object

Starting in R2022b, most Computer Vision Toolbox™ functions create and perform geometric transformations using the premultiply convention. Accordingly, you can now specify the AbsolutePose name-value argument as a rigidtform3d object, which uses the premultiply convention.

Although you can still specify AbsolutePose as a rigid3d object, this object is not recommended because it uses the postmultiply convention. You can streamline your geometric transformation workflows by switching to the new premultiply geometric transformation objects. For more information, see Migrate Geometric Transformations to Premultiply Convention.

R2020a: The Location and Orientation properties belonging to the plotCamera function are removed

The plotCamera function now accepts a rigid3d object to specify a camera pose. Starting in R2020a, you must use the rigid3d object instead of the Location and Orientation properties to specify the pose.