segmentAllObjects

R2026b

Segment all objects automatically in point cloud using SNAP model

Since R2026b

collapse all in page

    Syntax

    masks = segmentAllObjects(segmenter,ptCloud)
    [masks,labels,scores] = segmentAllObjects(segmenter,ptCloud)
    [___] = segmentAllObjects(___,Name=Value)

    Description

    Add-On Required: This feature requires the Point Cloud Toolbox Model for SNAP Segmentation Network add-on.

    masks = segmentAllObjects(segmenter,ptCloud) segments all objects in the input point cloud ptCloud using the pretrained SNAP model segmenter and returns object masks.

    example

    [masks,labels,scores] = segmentAllObjects(segmenter,ptCloud) additionally returns predicted object labels and confidence scores for the segmented objects.

    [___] = segmentAllObjects(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, Verbose=false specifies not to display progress information in the Command Window.

    Examples

    collapse all

    This example uses:

    Open Live Script

    Specify a full file path for a LAS file that contains aerial lidar data. Then, read the point cloud data from the file using the readPointCloud function of the lasFileReader object.

    filename = fullfile(matlabroot,"toolbox","pointcloud", ...
    "pcdata","las","aerialLidarData2.las");
lasReader = lasFileReader(filename);
ptCloud = readPointCloud(lasReader);

    To get better segmentation results, remove the ground plane from the point cloud using simple morphological filter (SMRF) algorithm.

    [~,nonGroundPtCloud] = segmentGroundSMRF(ptCloud);

    Create a SNAP segmentation model configured for aerial point cloud data.

    segmenter = snap("Aerial");

    Segment all objects in the point cloud.

    [masks,labels,scores] = segmentAllObjects(segmenter,nonGroundPtCloud,Verbose=false);

    Release GPU memory allocated to the SNAP model.

    releaseGPUMemory(segmenter)

    Visualize the segmented point cloud using the helperVisualizeSegmentation helper function. The helper function maps each mask index to corresponding class label and assigns a distinct color per class. Points with a mask value of zero are unclassified and shown in gray.

    figure(Position=[100 100 700 500])
helperVisualizeSegmentation(nonGroundPtCloud,masks,labels)

    Supporting Function

    function helperVisualizeSegmentation(ptCld,masks,labels)

% Identify points that belong to a segment
validIdx = masks > 0;
pointLabels = labels(masks(validIdx));

% Assign a distinct color to each unique class
classNames = unique(pointLabels);
numClasses = numel(classNames);
classColors = hsv(numClasses);

% Map each point to its class color index
[~,classIdx] = ismember(pointLabels,classNames);
numericLabels = zeros(ptCld.Count,1);
numericLabels(validIdx) = classIdx;

% Display with colorbar as legend
pcshow(ptCld.Location,numericLabels)
colormap([0.5 0.5 0.5; classColors])
clim([-0.5 numClasses+0.5])
cb = colorbar(Ticks=0:numClasses, ...
    TickLabels=["Unclassified";string(classNames)], ...
    Location="southoutside");
cb.TickLength = 0;
end

    Input Arguments

    collapse all

    SNAP segmentation model, specified as a snap object.

    Note

    To use this functionality, your system must have a CUDA® enabled NVIDIA® GPU. For information on the supported compute capabilities, see GPU Computing Requirements (Parallel Computing Toolbox).

    Input point cloud, specified as a pointCloud object. The point cloud can be unorganized or organized. The point cloud must use a coordinate system in which the positive Z-axis points upward. If your data uses a different coordinate system, use the pctransform function to reorient the point cloud. For large aerial point clouds, divide the scene into 50 m-by-50 m blocks before segmentation.

    Name-Value Arguments

    collapse all

    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: masks = segmentAllObjects(segmenter,ptCloud,ScoreThreshold=0.8) specifies removal of detections with scores less than 0.8.

    Size of the voxel grid, specified as a positive scalar in meters. The default value is 20 for aerial scenes and 10 for outdoor and indoor scenes. To segment small or closely spaced objects, use smaller values.

    The function divides the point cloud into voxels of this size and selects the point closest to each voxel centroid as a prompt for segmentation. In subsequent iterations controlled by NumLevels, the function halves the voxel size and generates denser prompts to cover remaining unsegmented regions.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Number of segmentation iterations, specified as a positive integer. To improve detection of small objects, increase this value. However, increasing this value increases computation time.

    The function segments the point cloud from coarse to fine, starting at the resolution set by VoxelSize and halving it at each subsequent iteration. Earlier iterations detect large objects; later iterations detect smaller objects in regions not yet covered.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Minimum confidence score for segmented objects, specified as a scalar in the range [0, 1]. The function discards objects with confidence scores below this threshold. To reduce false positives, increase this value.

    Data Types: single | double

    Overlap threshold for selecting strongest objects, specified as a scalar in the range [0, 1]. When overlap between two segments, measured as intersection over union (IoU), exceeds this threshold, the function keeps the higher-scoring segment and discards the other.

    Data Types: single | double

    Visible progress display, specified as a logical 1 (true) or 0 (false).

    Data Types: logical

    Output Arguments

    collapse all

    Object index for each point, returned as an M-by-1 vector of positive integers. M is the number of points in the input point cloud. Each element identifies the object instance for the corresponding point.

    Label for each segmented object, returned as an N-by-1 categorical vector. N is the number of segmented objects.

    The supported class names depend on the specified SNAP model. For example, indoor models use classes from ScanNet data set, outdoor models from the KITTI, nuScenes, and PandaSet data sets, and aerial models from the STPLS3D and DALES data sets.

    Confidence score for each segmented object, returned as an N-by-1 numeric vector. N is the number of segmented objects. The value of the confidence score is in the range of [0, 1]. A higher score indicates greater confidence in the segmentation.

    Version History

    Introduced in R2026b

    See Also

    | | |