worldpointset

Manage 3-D to 2-D point correspondences

Since R2020b

Description

The worldpointset object stores correspondences between 3-D world points and 2-D image points across camera views. You can use a worldpointset object with an imageviewset object to manage image and map data for structure-from-motion, visual odometry, and visual simultaneous localization and mapping (SLAM).

Creation

Syntax

wpSet = worldpointset

Description

wpSet = worldpointset creates a worldpointset object with default properties. Use the object functions to perform actions such as adding, modifying or removing correspondences, finding points in a view, and finding views of points.

Properties

WorldPoints — 3-D world points

[ ] (default) | M-by-3 matrix

This property is read-only.

3-D world points, specified as an M-by-3 matrix with rows containing [x y z] world points. M is the number of 3-D world points.

ViewIds — Identifiers for views

[ ] (default) | N-element row vector of integers

This property is read-only.

Identifiers for views associated with world points, specified as an N-element row vector of integers.

PointIds — Identifiers for 3-D points

[ ] (default) | M-element row vector of integers

This property is read-only.

Identifiers for 3-D points in WorldPoints, specified as an M-element row vector of integers.

Correspondences — 3-D to 2-D point correspondences

empty three-column table (default) | three-column table

This property is read-only.

3-D to 2-D point correspondences, specified as a three-column table.

Column	Description
PointIndex	Each row contains the linear index of a world point.
ViewId	Each row contains a 1-by-N vector specifying the IDs of the views associated with the corresponding world points. N is the number of views associated with the world point.
FeatureIndex	Each row contains a 1-by-N vector specifying the indices of the feature points that correspond to the world point. Each element is the index of the feature point in the view specified by the corresponding element in the ViewID cell.

ViewingDirection — Mean viewing direction of each world point

empty matrix (default) | M-by-3 matrix

This property is read-only.

Mean viewing direction of each world point, specified as an M-by-3 matrix, where M is the number of points. The viewing direction provides an estimate for a view angle from which a 3-D point can be observed. The mean viewing direction is the average of all the unit vectors pointing from the world point to the camera centers of the associated views. When a new camera view is introduced into the system, the 3-D world points that can potentially be observed in this view can be predicted based on the range set by the distance limits and the ViewingDirection.

DistanceLimits — Distance limits for 3-D point observation

empty vector (default) | M-by-2 vector

This property is read-only.

An representing the minimum and maximum distances from which each world point is observed.

Distance limits for 3-D point observation, specified as an M-by-2 vector that represents the minimum and maximum distance, where M is the number of points. The range indicates how far the 3-D point can be observed. When a new camera view is introduced into the system, the 3-D world points that can potentially be observed in this view can be predicted based on the range set by the distance limits and the ViewingDirection.

RepresentativeViewId — View IDs of the representative views

empty vector (default) | M-element column vector

This property is read-only.

View IDs of the representative views, specified as an M-element column vector, where M is the number of points. The representative view corresponds to the view that contains the representative feature in the representative view for each world point. A representative feature is the medoid of all the feature descriptors associated with the world point.

RepresentativeFeatureIndex — Representative feature descriptor index

empty vector (default) | M-element column vector

This property is read-only.

Representative feature descriptor index, specified as an M-element column vector, where M is the number of points. The index value corresponds to the view that contains the representative feature descriptor for each world point.

Count — Number of 3-D world points

0 (default) | scalar

This property is read-only.

Number of 3-D world points, specified as a scalar.

Object Functions

addWorldPoints	Add world points to world point set
removeWorldPoints	Remove world points from world point set
updateWorldPoints	Update world points in world point set
selectWorldPoints	Select world points from world point set
addCorrespondences	Update world points in a world point set
removeCorrespondences	Remove 3-D to 2-D correspondences from world point set
updateCorrespondences	Update 3-D to 2-D correspondences in world point set
updateLimitsAndDirection	Update distance limits and viewing direction
updateRepresentativeView	Update representative view ID and corresponding feature index
findViewsOfWorldPoint	Find views that observe a world point
findWorldPointsInTracks	Find world points that correspond to point tracks
findWorldPointsInView	Find world points observed in view

Examples

Triangulate Stereo Images

Load a MAT-file containing stereo parameters into the workspace.

load('webcamsSceneReconstruction.mat');

Read a stereo pair of images into the workspace.

I1 = imread('sceneReconstructionLeft.jpg');
I2 = imread('sceneReconstructionRight.jpg');

Undistort the images.

I1 = undistortImage(I1,stereoParams.CameraParameters1);
I2 = undistortImage(I2,stereoParams.CameraParameters2);

Define a rectangular region of interest (ROI), in the format [x y width height].

roi = [30 30 size(I1,2)-30 size(I1,1)-30];

Detect and extract Speeded-Up Robust Features (SURF) from both images using the ROI.

imagePoints1 = detectSURFFeatures(im2gray(I1),'ROI',roi);
imagePoints2 = detectSURFFeatures(im2gray(I2),'ROI',roi);
  
[feature1,validPoints1] = extractFeatures(im2gray(I1),imagePoints1,'Upright',true);
[feature2,validPoints2] = extractFeatures(im2gray(I2),imagePoints2,'Upright',true);

Match the extracted features to each other.

indexPairs = matchFeatures(feature1,feature2);

Compute the 3-D world points.

matchedPoints1 = validPoints1(indexPairs(:,1));
matchedPoints2 = validPoints2(indexPairs(:,2));
worldPoints    = triangulate(matchedPoints1,matchedPoints2,stereoParams);

Create a worldpointset object to manage correspondences.

wpSet = worldpointset;

Add the world points to the worldpointset.

[wpSet,newPointIndices] = addWorldPoints(wpSet,worldPoints);

Add the 3-D to 2-D point correspondences to the worldpointset.

wpSet = addCorrespondences(wpSet,1,newPointIndices,indexPairs(:,1));
wpSet = addCorrespondences(wpSet,2,newPointIndices,indexPairs(:,2));

Display the world points.

pcshow(wpSet.WorldPoints,'VerticalAxis','y','VerticalAxisDir','down','MarkerSize',45)

Extended Capabilities

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

Version History

Introduced in R2020b

R2024a: Use unique point identifiers to specify world points

Use the new selectWorldPoints object function to select world points from a worldpointset object. Also, you can now specify unique point IDs to manage world points. In prior releases if you did not specify unique identifiers when points were added, then points were saved with sequential identifiers.

R2022b: Visual SLAM: Track Visibility Relationship Between 3-D World Points and Camera Views

• Added ViewingDirection, DistanceLimits, RepresentativeViewId, and RepresentativeFeatureIndex properties.

• Added updateLimitsAndDirection and updateRepresentativeView object functions.