Main Content

pcsegsam

Segment all objects automatically in lidar point cloud using Segment Anything Model (SAM)

Since R2024b

collapse all in page

    Syntax

    [labels,scores] = pcsegsam(ptCloud)
    [labels,scores] = pcsegsam(ptCloud,Name=Value)

    Description

    [labels,scores] = pcsegsam(ptCloud) segments all objects from the input lidar point cloud ptCloud using the pretrained Segment Anything Model (SAM), and returns the labels of all points in the point cloud and the confidence score for each segmented object.

    example

    [labels,scores] = pcsegsam(ptCloud,Name=Value) specifies options using one or more name-value arguments. For example, Verbose=false specifies not to display progress information in the Command Window.

    Note

    This functionality requires Deep Learning Toolbox™ and the Image Processing Toolbox™ Model for Segment Anything Model support package. You can download and install the Image Processing Toolbox Model for Segment Anything Model from Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.

    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","lidar", ...
         "lidardata","las","aerialLidarData2.las");
lasReader = lasFileReader(filename);
ptCloud = readPointCloud(lasReader);

    Remove the ground plane from the point cloud to get better segmentation results.

    [~,nonGroundPtCloud] = segmentGroundSMRF(ptCloud);

    Segment the point cloud by using the pcsegsam function.

    [labels,scores] = pcsegsam(nonGroundPtCloud);
    Segmenting using Segment Anything Model.
---------------------------------------------
Processing crop 1/1. 
Processed 1024/1024 point prompts.

    Visualize the labels.

    pcshow(nonGroundPtCloud.Location,labels)
colormap(hsv)

    Input Arguments

    collapse all

    Unorganized point cloud, specified as a pointCloud object.

    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: pcsegsam(nonGroundPtCloud,GridSize=[32 48]) specifies the number of grid points to sample along the x- and y-directions of the input point cloud as 32 and 48, respectively.

    Size of the rectangular grid along the x- and y-directions, specified as a 1-by-2 vector of positive integers. The function uses sampled grid points along each direction as point prompts for the SAM. Specify a higher value of grid size when the input point cloud contains small, closely spaced objects.

    If the specified value of the NumCropLevels argument is greater than 1, the function scales down the GridSize value. For more information, see GridDownscaleFactor.

    Data Types: single | double

    Region of interest (ROI), specified as an M-by-1 logical vector. M is the number of points in the input point cloud. The value 1 (true) specifies that the corresponding point is within the ROI to perform segmentation. The value 0 (false) specifies that the corresponding point is outside the ROI, and the function discards it while performing segmentation.

    Data Types: logical

    Number of point cloud crop levels, specified as a positive integer. For each level n, the function divides the point cloud into grids of size 2(n – 1)-by- 2(n – 1).

    Increase the number of point cloud crop levels when the input point cloud contains small objects that cannot be segmented using a single level.

    Note

    Increasing the number of point cloud crop level can significantly increase processing time.

    Data Types: single | double

    Factor by which to downscale grid size, specified as a positive integer. For a crop level, n, the pcsegsam function scales down the GridSize value by a factor of D(n – 1), where D is the downscale factor. If you specify NumCropLevels as a value greater than 1, you can specify a higher GridDownscaleFactor value to decrease computation time.

    Data Types: single | double

    Batch size, specified as a positive integer. Increase the batch size to increase the number of points the function processes together in a batch. A larger batch size increases processing speed at the expense of more memory usage. If you run out of memory, try decreasing the batch size.

    Data Types: single | double

    Confidence score threshold, specified as a numeric scalar in the range [0, 1]. The pcsegsam function filters out predictions with confidence scores lower than the threshold value. Increase this value to reduce the number of false positives, at the possible expense of missing some true positives.

    Data Types: single | double

    Threshold at which to remove an overlapping object, specified as a numeric scalar in the range [0, 1]. When the overlap proportion between two segmented objects is greater than this value, the function retains the object with the higher confidence score and removes the other object. Decrease the threshold to reduce the number of overlapping segmentations. However, a very low value for this threshold can eliminate segmentations with only minor overlap in the point cloud.

    Data Types: single | double

    Minimum area of an object, specified as a nonnegative numeric scalar. If the area of a segmented object is less than this threshold, the function discards the object.

    Data Types: single | double

    Maximum area of an object, specified as a positive numeric scalar. The function discards a segmented object if its area greater is than this threshold.

    Data Types: single | double

    Hardware resource on which to process point cloud data, specified as "auto", "gpu", or "cpu".

    • "auto" — Use a GPU, if available. Otherwise, use the CPU.

    • "gpu" — Use the GPU. To use a GPU, you must have Parallel Computing Toolbox™ and a CUDA® enabled NVIDIA® GPU. If a suitable GPU is not available, the function returns an error. For information about the supported compute capabilities, see GPU Computing Requirements (Parallel Computing Toolbox).

    • "cpu" — Use the CPU.

    Data Types: logical | char

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

    Data Types: logical

    Output Arguments

    collapse all

    Segmentation labels of points, returned as an M-by-1 vector of positive integers. M is the number of points in the input point cloud.

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

    Version History

    Introduced in R2024b

    See Also

    | |