Main Content

apply

Process blocks of blocked point cloud

Description

example

bres = apply(bpc,fcn) processes the entire blockedPointCloud object bpc by applying the function handle fcn to each block. Returns bres, a new blocked point cloud containing the processed data.

[bres1,bres2,...] = apply(bpc,fcn) returns multiple output arguments. The specified function handle fcn must point to a user function that returns the same number of arguments.

[bres1s,bres2s,...] = apply(bpcs,fcn) processes the array of blocked point cloud bpcs by applying the function handle fcn to each block of each blocked point cloud. Returns an array of blocked point clouds containing the processed data.

example

[___] = apply(___,Name=Value) modifies aspects of block processing using name-value arguments.

Examples

collapse all

Create a full file path for a LAZ file that contains aerial lidar data.

pcfile = fullfile(toolboxdir("lidar"),"lidardata", ...
                "las","aerialLidarData.laz");

Create a pcdownsample function handle.

fun = @(block)pcdownsample(block.Data,random=0.1);

Create a blockedPointCloud object using the LAZ file.

bpc = blockedPointCloud(pcfile,[50 50]);

Process each block of the aerial point cloud data using the specified pcdownsample function handle.

pcdown = apply(bpc,fun);

Create a full file path for a LAZ file that contains aerial lidar data.

pcfile = fullfile(toolboxdir("lidar"),"lidardata", ...
                    "las","aerialLidarData.laz");

Create a pcnormals function handle.

fun = @(block)pcnormals(block.Data);

Create a blockedPointCloud object using the LAZ file.

bpc = blockedPointCloud(pcfile,[50 50]);

Create a MAT adapter for writing the files from the block processing operation as MAT files.

matad = lidar.blocked.MATBlocks;
outfile = fullfile(tempdir,"pcnormout");

Perform a block processing operation on the point cloud file to extract the normals.

pcnorms = apply(bpc,fun,Adapter=matad,OutputLocation=outfile);

Input Arguments

collapse all

Blocked point cloud, specified as a blockedPointCloud object.

Blocked point clouds, specified as an array of blockedPointCloud objects.

Processing function, specified as a function handle. For more information, see Create Function Handle. The processing function fcn must accept a bstruct as input. To pass additional arguments, specify fcn as an anonymous function. For more information, see Anonymous Functions.

bstruct is a structure with these fields:

FieldDescription
DataBlock of data from bpc
BlockSizeValue of the BlockSize parameter.
ROI

ROI of the block, specified as a six-element numeric row vector in the order [xmin xmax ymin ymax zmin zmax].

PointAttributes

Attributes for each point, specified as a lidarPointAttributes object.

PCNumber

Index into the bpc array from the current point cloud.

The function fcn typically returns the results for one block. The results can be a pointCloud object or a structure.

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: apply(bpc,fun,DisplayWaitbar=true) displays a wait bar for operations with long run times.

Adapter used for writing blocked point cloud data, specified as an adapter object. To specify different adapters for different outputs, use a cell array. If you specify a scalar object, the function uses the specified adapter for every output.

This table lists the adapters included with the toolbox.

AdapterDescription
LASStore blocks in a single LAS file
InMemoryStore blocks in a variable in main memory
LASBlocksStores each block as a LAS file in a folder
MATBlocksStores each block as a MAT file in a folder

If you do not specify the OutputLocation argument, then the default value of Adapter is InMemory. If OutputLocation argument, then the value of Adapter is MATBlocks for non-point cloud output and LASBlocks for point cloud output.

Wait bar visualization, specified as a logical 1 (true) or 0 (false). When set to true, the apply object function displays a wait bar operations with long run times. If you cancel the wait bar, the apply object function returns partial output, if available.

Data Types: logical

Location of the output folder, specified as a string scalar or character vector.

If there is a single output, the apply object function writes it directly to this location.

For multiple outputs, the apply object function creates subfolders of the format outputN, where N is the sequential number of the output. If the input is an array, the apply object function derives the output name of each element from its Source property. If the input is in-memory, the apply function reports an error.

If the UseParallel property is true, OutputLocation must be a valid path on the client session. Use the AlternateFileSystemRoots property of the input to specify the required mapping for worker sessions. All outputs inherit this value.

Use parallel processing, specified as a logical 0 (false) or 1 (true). The function first determines whether to use a new or an existing parallel pool. If no parallel pool is active, the function opens a new pool based on the default parallel settings. All adapters specified by the Adapter property must support parallel processing. You must specify a valid OutputLocation.

This argument requires Parallel Computing Toolbox™.

Data Types: logical

Output Arguments

collapse all

New blocked point cloud, returned as a blockedPointCloud object.

Version History

Introduced in R2022a