cuboidModel

R2026b

Object for storing parametric cuboid model

Description

The cuboidModel object stores the parameters of a parametric cuboid model. After you create a cuboidModel object, you can extract cuboid corner points, and points within the cuboid using the object functions. Cuboid models are used to store the output of the pcfitcuboid and pcfitcuboidalign functions, which fit a cuboid over a point cloud.

Creation

There are two ways to create a cuboidModel object.

• Create a cuboid model by specifying the cuboid parameters in the cuboidModel object.

• Fit a cuboid model over a point cloud using the pcfitcuboid or pcfitcuboidalign functions.

Description

model = cuboidModel(params) constructs a parametric cuboid model from the 1-by-9 input vector, params.

model = pcfitcuboid(ptCloudIn) fits a cuboid over the input point cloud data. The pcfitcuboid function stores the properties of the cuboid in a parametric cuboid model object, model.

model = pcfitcuboid(ptCloudIn,indices) fits a cuboid over a selected set of points, indices, in the input point cloud.

Properties

Parameters — Cuboid model parameters

Read-only: nine-element row vector

This property is read-only.

Cuboid model parameters, stored as a nine-element row vector of the form [x_ctr y_ctr z_ctr x_len y_len z_len x_rot y_rot z_rot].

• x_ctr, y_ctr, and z_ctr specify the center of the cuboid.

• x_len, y_len, and z_len specify the length of the cuboid along the x-, y-, and z-axis, respectively, before rotation has been applied.

• x_rot, y_rot, and z_rot specify the rotation angles in degrees for the cuboid along the x-, y-, and z-axis, respectively. These angles are clockwise-positive when looking in the forward direction of their corresponding axes.

The figure shows how these values determine the position of a cuboid.

These parameters are specified by the params input argument.

Data Types: single | double

Center — Center of cuboid

Read-only: three-element row vector

This property is read-only.

Center of the cuboid, stored as a three-element row vector of the form [x_ctr y_ctr z_ctr]. The vector contains the 3-D coordinates of the cuboid center in the x-, y-, and z-axis, respectively.

This property is derived from the Parameters property.

Data Types: single | double

Dimensions — Dimensions of cuboid

Read-only: three-element row vector

This property is read-only.

Dimensions of the cuboid, stored as a three-element row vector of the form [x_len y_len z_len]. The vector contains the length of the cuboid along the x-, y-, and z-axis, respectively.

This property is derived from the Parameters property.

Data Types: single | double

Orientation — Orientation of cuboid

Read-only: three-element row vector

This property is read-only.

Orientation of the cuboid, stored as a three-element row vector of the form, [x_rot y_rot z_rot], in degrees. The vector contains the rotation of the cuboid along the x-, y-, and z-axis, respectively.

This property is derived from the Parameters property.

If the orientation is in quaternion, convert the quaternion to Euler angles in degrees to create a cuboid model.

• To convert a quaternion to Euler angles in radians, use the quat2eul (Robotics System Toolbox) function. Set the sequence (Robotics System Toolbox) argument of the quat2eul (Robotics System Toolbox) function to "ZYX".

• To convert angle units from radians to degrees, use the rad2deg function.

Data Types: single | double

Object Functions

getCornerPoints	Get corner points of cuboid model
findPointsInModel	Find points enclosed by cuboid model
plot	Plot cuboid model
transform	Transform geometric models between coordinate frames

Examples

Detect Cuboid in Point Cloud

Detect a cuboid in a point cloud using pcfitcuboid function. The function stores the cuboid parameters as a cuboidModel object.

Read point cloud data into the workspace.

ptCloud = pcread('highwayScene.pcd');

Search the point cloud within a specified region of interest (ROI). Create a point cloud of only the detected points.

roi = [-30 30 -20 30 -8 13];
in = findPointsInROI(ptCloud,roi);
ptCloudIn = select(ptCloud,in);

Plot the point cloud of detected points.

   figure
   pcshow(ptCloudIn.Location)
   xlabel('X(m)')
   ylabel('Y(m)')
   zlabel('Z(m)')
   title('Detected Points in ROI')

Find the indices of the points in a specified ROI within the point cloud.

roi = [9.6 13.8 7.9 9.3 -2.5 3];
sampleIndices = findPointsInROI(ptCloudIn,roi);

Fit a cuboid to the selected set of points in the point cloud.

 model = pcfitcuboid(ptCloudIn,sampleIndices);
  figure
  pcshow(ptCloudIn.Location)
  xlabel('X(m)')
  ylabel('Y(m)')
  zlabel('Z(m)')
  title('Detect a Cuboid in a Point Cloud')

Plot the cuboid box in the point cloud.

hold on
plot(model)

Display the internal properties of the cuboidModel object.

model

model = 
  cuboidModel with properties:

     Parameters: [11.4873 8.5997 -1.6138 3.6713 1.3220 1.7576 0 0 0.9999]
         Center: [11.4873 8.5997 -1.6138]
     Dimensions: [3.6713 1.3220 1.7576]
    Orientation: [0 0 0.9999]

Fit Cuboid over Point Cloud Data

Load the point cloud data into the workspace.

ptCloud = load("drivingLidarPoints.mat").ptCloud;

Select a region of interest for cuboid fitting.

roi = [-10 10 -6 8 -2 2];
idx = findPointsInROI(ptCloud,roi);
ptCloudROI = select(ptCloud,idx);

Visualize the cropped point cloud.

figure
pcshow(ptCloudROI)
title("Cropped Point Cloud")

Segment the ground plane.

maxDistance = 0.5;
[~,idxGround,idxNoGround] = pcfitplane(ptCloudROI,maxDistance);
groundPtCloud = select(ptCloudROI,idxGround);
ptCloudNoGround = select(ptCloudROI,idxNoGround);

Visualize the segmented ground plane.

figure
pcshowpair(groundPtCloud,ptCloudNoGround)
legend("Ground Point Cloud","Non-Ground Point Cloud")
title("Segmented Ground Plane")

Segment the non-ground point cloud into clusters.

minDistance = 1;
[labels,numClusters] = pcsegdist(ptCloudNoGround,minDistance);

Visualize the point cloud and each cluster in a different color.

figure
pcshow(ptCloudROI)
hold on
pcshow(ptCloudNoGround.Location,labels)

Fit a cuboid to each cluster, and visualize each cluster with its respective fitted cuboid.

for i = 1:numClusters
    idx = find(labels == i);
    model = pcfitcuboid(ptCloudNoGround,idx);
    plot(model)
end
title("Clustered Point Cloud with Fitted Cuboids")

Extended Capabilities

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

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2020b

R2026b: New transform object function

You can use the new transform object function to transform a cuboidModel between coordinate frames.