triangulateInitialViews

R2026b

Triangulate initial views for SfM 3-D reconstruction

Since R2026b

Syntax

sfmObj = triangulateInitialViews(sfmObj)

sfmObj = triangulateInitialViews(sfmObj,viewPairIDs)

[sfmObj,info] = triangulateInitialViews(sfmObj,___)

[___] = triangulateInitialViews(sfmObj,Name=Value)

Description

The triangulateInitialViews object function selects the best pair of views from the view graph geometrically verified by the verifyImagePairs function and initializes the sparse 3-D reconstruction. Use the triangulateInitialViews object function as the third step in the SfM pipeline, followed by the reconstruct object function, which reconstructs the point cloud of the full 3-D scene by processing all the remaining views in the view graph. Use the isVerified function to verify whether an sfm object is ready for 3-D reconstruction initialization before calling the triangulateInitialViews function.

The triangulateInitialViews object function picks the pair of views with the most reliable feature matches and sufficient baseline separation, or parallax, estimates the relative camera pose between the two views, and triangulates the first set of 3-D points. For more information about the algorithm, see Algorithms.

If the initialization fails, the triangulateInitialViews function returns an error. For more information on resolving issues during initialization, see Tips.

sfmObj = triangulateInitialViews(sfmObj) selects the best initial view pair from the view graph associated with the sfm object sfmObj, and triangulates the corresponding 3-D points from the selected views. The function then returns a version of the input SfM object with updated WorldPointSet, ViewGraph, and ProcessedImages properties.

sfmObj = triangulateInitialViews(sfmObj,viewPairIDs) uses the two views specified by the view IDs viewPairID to triangulate the first set of 3-D points, instead of automatically selecting the best view pair.

[sfmObj,info] = triangulateInitialViews(sfmObj,___) returns more details about the selected best view pair and the 3-D triangulation process using any combination of input arguments from the previous syntaxes. You can use the info output to inspect and validate the initialization results.

[___] = triangulateInitialViews(sfmObj,Name=Value) specifies additional options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, triangulateInitialViews(sfmObj,MinMedianAngle=10) relaxes the minimum parallax requirement for triangulation.

Examples

Reconstruct 3-D Scene from Indoor Image Sequence

Use the sfm object to recover camera poses and a sparse 3-D point cloud from images of an indoor scene.

Create Image Datastore and Define Camera Intrinsics

Create an ImageDatastore from the image sequence. Specify the camera intrinsic parameters.

unzip("sfm_images.zip")
imageFolder = fullfile(pwd,"images");
imds = imageDatastore(imageFolder);
intrinsics = cameraIntrinsics([535.1307 532.1860],[323.3722 239.7986],[480 640]);

Visualize the indoor scene.

imshow(preview(imds))

Create SfM Object and Run Pipeline

Create an sfm object and execute each stage of the incremental SfM pipeline sequentially.

sfmObj = sfm(imds,intrinsics);

Connect image pairs based on visual similarity.

sfmObj = connectImagePairs(sfmObj);

Visualize the similarity matrix for the connected image pairs using the imagesc function.

imagesc(sfmObj.SimilarityMatrix)
title("Similarity Matrix for Connected Image Pairs")

Verify that the view graph was created successfully before proceeding to geometric verification.

if isConnected(sfmObj)
    sfmObj = verifyImagePairs(sfmObj);
end

Visualize the similarity matrix for the refined image pair connections using the imagesc function.

imagesc(sfmObj.SimilarityMatrix)
title("Similarity Matrix after Refining Connected Image Pairs")

Confirm that geometric verification completed successfully before initializing the reconstruction. Specify a minimum median angle of 5 degrees and a maximum triangulation error of 4 pixels. Display the initialization metrics.

if isVerified(sfmObj)
    [sfmObj,info] = triangulateInitialViews(sfmObj,MinMedianAngle=5,MaxTriangulationError=4);
    disp(info)
end

                     ViewId1: 9
                     ViewId2: 10
                RelativePose: [1×1 rigidtform3d]
                     Matches: [380×2 uint32]
    MedianTriangulationAngle: 8.6016
       MeanReprojectionError: 0.2799

Confirm that initialization succeeded before running incremental reconstruction.

if isInitialized(sfmObj)
    sfmObj = reconstruct(sfmObj);
end

Retrieve Results

Retrieve the estimated camera poses and the sparse 3-D point cloud.

camPoses = poses(sfmObj);
sparsePoints = pointCloud(sfmObj);

Visualize Reconstruction

Display the reconstructed scene showing the camera trajectory and sparse point cloud. Adjust the view orientation and zoom for better visualization.

plot(sfmObj,CameraSize=0.5,MarkerSize=25)
view(82.69,-15.53)
camroll(-90)
camva(4.52)

Analyze 3-D Reconstruction from Triangulating Initial View Pair

This example shows how to analyze triangulation results and visualize 3-D points reconstructed by the triangulateInitialViews function.

Create Image Datastore and Define Camera Intrinsics

Create an imageDatastore object from the image sequence. Specify the camera intrinsics parameters.

unzip("sfm_images.zip")
imageFolder = fullfile(pwd,"images");
imds = imageDatastore(imageFolder);
intrinsics = cameraIntrinsics([535.1307 532.1860],[323.3722 239.7986],[480 640]);

Visualize images in the sequence.

figure
montage(imds)
title("Image Sequence")

Create sfm Object and Construct Refined View Graph

Initialize the sfm object with the image datastore and camera intrinsics. The first two steps in the Structure from Motion (SfM) process are view graph construction and refinement. Connect visually similar image pairs to create a view graph. Then, refine the view graph by removing edges that violate epipolar geometric constraints.

sfmObj = sfm(imds,intrinsics);
sfmObjViewGraph = connectImagePairs(sfmObj);
sfmObjRefined = verifyImagePairs(sfmObjViewGraph);

Triangulate 3-D Points from Initial View Pair

Select a robust image pair and initialize the 3-D reconstruction. A strong initial pair typically comes from a densely connected region of the refined view graph, where both images share substantial scene overlap. A poor initial pair can reduce accuracy, increase drift during incremental reconstruction, and slow convergence.

[sfmObjInit,info] = triangulateInitialViews(sfmObjRefined, Verbose=true);

23 of 39 edges have more than 100 feature matches.
23 of 23 edges are selected after applying the grid threshold.
Views 3 and 6 are selected for initial triangulation.
Median triangulation angle: 23.571169

Inspect Triangulation Diagnostics

Display the triangulation metrics returned by the info output argument from the triangulateInitialViews function. The info structure contains these triangulation metrics:

• Matches — Inlier matches that survived 3-D triangulation and outlier rejection. These differ from the inlier feature matches between connected image pairs in sfmObjRefined.

• MedianTriangulationAngle — A value below 5 degrees indicates a weak baseline, which can produce unreliable 3-D points and cause drift during incremental reconstruction.

• MeanReprojectionError — A value above several pixels indicates imprecise calibration or poor feature localization.

These thresholds are rough guidelines. Exact values depend on your specific dataset.

disp(info)

                     ViewId1: 3
                     ViewId2: 6
                RelativePose: [1×1 rigidtform3d]
                     Matches: [28×2 uint32]
    MedianTriangulationAngle: 23.5712
       MeanReprojectionError: 0.5639

Visualize Triangulated Image Pair

Visualize the initial image pair and matched 2-D keypoints.

I1 = readimage(imds, info.ViewId1);
I2 = readimage(imds, info.ViewId2);

points1 = sfmObjInit.ViewGraph.Views.Points{info.ViewId1};
points2 = sfmObjInit.ViewGraph.Views.Points{info.ViewId2};
matchedPoints1 = points1(info.Matches(:,1));
matchedPoints2 = points2(info.Matches(:,2));

figure
showMatchedFeatures(I1,I2,matchedPoints1,matchedPoints2,"montage",PlotOptions={"ro","g+","y--"})
title("View pair: "+num2str(info.ViewId1)+" and "+num2str(info.ViewId2))

Visualize Triangulated 3-D Points

To visualize the triangulated 3-D points and camera positions of the initial view pair, call the plot object function of the sfm object.

figure
plot(sfmObjInit,CameraSize=0.1,MarkerSize=25)
xlabel("X")
ylabel("Y")
zlabel("Z")
title("Triangulated points")

Tune Initial Triangulation Parameters

The MinMedianAngle and MaxTriangulationError name-value arguments control how strictly the algorithm filters candidate view pairs. These thresholds depend on the scene geometry and camera motion, and may require tuning for your dataset.

Attempt initial triangulation with a strict threshold. The function throws an error because no view pair satisfies the 25-degree minimum angle constraint.

sfmObjInitError = triangulateInitialViews(sfmObjRefined, Verbose=true, MinMedianAngle=25);

23 of 39 edges have more than 100 feature matches.
23 of 23 edges are selected after applying the grid threshold.

Relax the threshold to allow the algorithm to find a valid view pair.

sfmObjInit = triangulateInitialViews(sfmObjRefined, Verbose=true, MinMedianAngle=20);

23 of 39 edges have more than 100 feature matches.
23 of 23 edges are selected after applying the grid threshold.
Views 8 and 11 are selected for initial triangulation.
Median triangulation angle: 33.884075

Similar reasoning applies to MaxTriangulationError argument. Increasing its value relaxes the reprojection error tolerance and admits view pairs that stricter settings would reject. Adjust both thresholds together for your dataset to balance reconstruction accuracy and successful initialization.

Input Arguments

sfmObj — Structure from motion object with a geometrically verified view graph

sfm object

Structure from motion object with a geometrically verified view graph, specified as an sfm object. You must specify an sfm object that contains a view graph created by the connectImagePairs object function and refined by the verifyImagePairs function. You can use the isVerified function to confirm if an sfm object contains a geometrically verified view graph.

viewPairIDs — View IDs of image views to use for initialization

two element vector of positive integers

View IDs of the image views to use for initialization, specified as a two element vector of positive integers. Both views must exist in the view graph. If you do not specify this argument, the function ranks each pair, as outlined in the Algorithms section, and selects the top-ranked pair.

Note

The order of the view pair IDs is not significant. For example, [view1,view2] and [view2,view1] specify the same view pair.

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: triangulateInitialViews(sfmObj,MinMedianAngle=10,MaxTriangulationError=6)

MinNumMatches — Minimum number of matches for a view pair to qualify as initialization candidate

100 (default) | positive integer

Minimum number of matches for a view pair to qualify as initialization candidate, specified as a positive integer.

MinMedianAngle — Minimum median triangulation angle between a view pair to qualify as initialization candidate

16 (default) | scalar in degrees

Minimum median triangulation angle between a view pair, across all their 3-D points, to qualify as an initialization candidate, specified as a scalar in degrees. The MinMedianAngle argument ensures that the selected two views have sufficient parallax to produce reliable 3-D points. The function rejects view pairs with a median angle below this threshold.

If the function cannot find a suitable view pair using a specified MinMedianAngle value, reduce it to relax the triangulation conditions.

MaxTriangulationError — Maximum reprojection error for a triangulated 3-D point

4 (default) | positive scalar

Maximum reprojection error for a triangulated 3-D point, specified as a positive scalar in pixels. Decreasing the MaxTriangulationError value enables the function to classify more triangulated 3-D points as valid at the cost of potentially lower triangulation accuracy.

MinTriangulationAngle — Minimum triangulation angle for a triangulated 3-D point

1.5 (default) | scalar in degrees

Minimum triangulation angle for a triangulated 3-D point, specified as a scalar in degrees. Decreasing the MinTriangulationAngle value enables the function to classify more triangulated 3-D points as valid at the cost of potentially lower triangulation accuracy.

Verbose — Display progress information

false or 0 (default) | true or 1

Display progress information on the command line, specified as a logical 1 (true) or 0 (false). To monitor the progress of the function, specify this argument as true.

Output Arguments

sfmObj — Structure from motion object initialized with first set of triangulated 3-D points

sfm object

Structure from motion object initialized with the first set of triangulated 3-D points, returned as an sfm object. The triangulateInitialViews function returns an sfm object identical to the input sfmObj, but with these updated property values:

• ViewGraph — Contains the relative pose and matched features between the selected initial view pair.

• WorldPointSet — Contains the 3-D world points triangulated using the selected initial view pair.

• ProcessedImages — Contains the view IDs of the initial view pair selected for triangulation.

info — Initialization details

structure

Initialization details, returned as a structure with these fields:

• ViewId1 — Index of the selected first view, returned as a positive integer.

• ViewId2 — Index of the selected second view, returned as a positive integer.

• RelativePose — Estimated relative pose between the two selected views, returned as a rigidtform3d object.

• Matches — Indices to the features matched between the two selected image views, returned as a K-by-2 matrix of integers.

• MedianTriangulationAngle — Median triangulation angle, returned as a scalar in degrees.

• MeanReprojectionError — Average reprojection error across all the triangulated 3-D points, returned as a scalar in pixels.

Use this information to visualize and debug the initial triangulation.

Tips

• If the function returned an error, the most common cause is that no view pair satisfies the MinMedianAngle or MaxTriangulationError threshold. Reduce the MinMedianAngle argument or increase the MaxTriangulationError argument to enable more view pairs to qualify.

• Use the info output argument to retrieve the exact view pair selected for initialization and verify that the selected pair makes sense for your scene. Also, a median triangulation angle below 5 degrees might indicate that the initial points are unreliable.

• For turntable or orbital capture patterns, you can usually achieve good initialization with the default parameters. For forward-motion sequences, such as driving, you might need to reduce the MinMedianAngle argument because the baseline between consecutive frames is small.

• After initialization, use the plot object function to visually confirm the two-view reconstruction before proceeding to the reconstruct function.

• For more information, see Best Practices for 3-D Reconstruction Using Structure from Motion.

Algorithms

SfM initialization establishes the first stable 3‑D reconstruction for an image sequence by selecting a robust initial image pair from the verified view graph. By default, the triangulateInitialViews function selects a pair that provides reliable feature correspondences and a sufficient baseline for accurate triangulation. It estimates the relative camera pose for the selected pair and triangulates an initial set of 3‑D points. This initial reconstruction forms the foundation for incrementally adding views and expanding the scene structure. Selecting a strong initial view pair is critical because it directly affects the accuracy, scale consistency, and stability of the entire SfM process.

The function selects the initial view pair using these steps:

1. Rank candidate image pairs — The function ranks connected image pairs in the view graph based on the number of geometrically verified feature matches obtained during image pair verification. It also evaluates the spatial distribution of these matches to ensure uniform coverage across the image plane, prioritizing pairs that provide both strong connectivity and well‑distributed correspondences.

2. Estimate relative camera pose — Starting from the highest ranked pair, the function estimates the relative camera pose using the essential matrix to model general 3‑D scene geometry.

3. Triangulate initial 3‑D points — The function triangulates inlier feature correspondences between the two views to generate an initial set of 3‑D world points.

4. Evaluate triangulation quality — The function computes the median triangulation angle of the reconstructed points and selects the pair only if this value exceeds the required minimum threshold, indicating a sufficient baseline.

5. Filter unreliable 3‑D points — The function removes triangulated points with reprojection errors above the maximum allowed threshold or with triangulation angles below the minimum acceptable angle to improve reconstruction robustness.

After selecting a valid initial pair, the function initializes the SfM reconstruction state using the estimated camera poses and filtered 3‑D points.

Version History

Introduced in R2026b