pcviewer

R2026b

Visualize and inspect large 3-D point clouds

Since R2023a

expand all in page

    Description

    Use the pcviewer object to view and inspect large 3-D point clouds. You can interact with the point cloud, and set camera and viewer properties. Point cloud interactions include navigating through the point cloud, modifying the size of points or enlarging their display, and selecting viewing planes. Camera and viewer properties enable you to select between first-person and orbital camera navigation, select a perspective or orthographic camera projection, and set camera location properties.

    Creation

    Syntax

    viewer = pcviewer(ptCloud)
    viewer = pcviewer(filename)
    viewer = pcviewer(___,color)
    viewer = pcviewer(___,Name=Value)

    Description

    viewer = pcviewer(ptCloud) creates a point cloud viewer that visualizes points stored in the object specified by ptCloud. You can access and modify point cloud viewer properties using the returned pcviewer object viewer.

    example

    viewer = pcviewer(filename) visualizes points stored in the file specified by filename. filename must be a PLY, PCD, LAS, or LAZ file type. LAS/LAZ files support requires the Point Cloud Toolbox™.

    viewer = pcviewer(___,color) specifies the colors with which to visualize the points of the point cloud, in addition to any combination of input arguments from previous syntaxes.

    viewer = pcviewer(___,Name=Value) specifies options using one or more name-value arguments. For example, VerticalAxis="XUp" sets the x-axis as the vertical axis in the viewer, with up as positive.

    Input Arguments

    expand all

    Point cloud, specified as a pointCloud object. The viewer uses the Location property of the input point cloud object to render the position of the points. By default, the viewer sets the colors of the points from the Color property of the input pointCloud object or by applying a colormap based on the z-values from the Location property of the object.

    Filename, specified as a string scalar or a character vector. The file must be provided as a PLY, PCD, LAS, or LAZ file type. formatted file.

    LAS/LAZ files support requires the Point Cloud Toolbox. LAZ files returned by the lasFileWriter object, which facilitates writing point cloud data to LAS/LAZ formats, are optimized for display. The viewer is also optimized for LAZ files stored in the Cloud Optimized Point Cloud (COPC) format. For more details, see the COPC website.

    Color for points in the point cloud, specified as an RGB triplet, an M-by-3 array, or an M-by-N-by-3 array for an organized point cloud, a short color name, or a long color name. The color input sets the Color property. For details on color values, see Color Values table.

    • If the data type of the point cloud Location property is single or double, each color RGB value must be in the range [0, 1].

    • If the data type of the point cloud Location property is uint8, each color RGB value must be in the range [0, 255].

    • The Color property of the pcviewer object stores the color value as an RGB triplet, an M-by-3 matrix, or an M-by-N-by-3 array. If you specify the color one or more color names, the function converts them to their corresponding RGB triplets.

    ColorFormatExample
    Specify one color for all points

    Short or long color name.

    "r"

    "red"

    1-by-3 vector (RGB triplet).

    [255 0 0]1-by-3 grid, with columns labeled r, g, and b respectively.

    Specify a color for each point

    String array, or cell array of character vectors.

    ["red","yellow","blue"]

    M-by-3 array for an unorganized point cloud, in which each row is an RGB triplet. M is the number of rows in the unorganized point cloud.

    255 0 0
255 0 0
0 255 255
    M-by-3 grid, with columns labeled r,g,b respectively.

    M-by-N-by-3 array for an organized point cloud, in which each page specifies the red, green, or blue value for the corresponding point in the point cloud. M-by-N is the size of the organized point cloud.

    M-by-N-by3 grid, with 3 m-by-n matrices labeled r, g, and b respectively.

    Name-Value Arguments

    expand 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: viewer = pcviewer(ptCloud,ViewPlane="XY")" visualizes the point cloud from the xy-plane.

    Camera projection for 3-D views, specified as one of these values:

    • "perspective" — Projects the viewing volume as the frustum of a pyramid (a pyramid whose apex has been cut off parallel to the base). Objects further from the camera appear smaller. Distance causes foreshortening, which enables you to perceive the depth of 3-D objects. This projection type is useful when you want to display realistic views of real objects. Perspective projection does not preserve the relative dimensions of objects. Instead, it displays a distant line segment smaller than a nearer line segment of the same length. Lines that are parallel in the data might not appear parallel in the scene.

    • "orthographic" — This projection type maintains the correct relative dimensions of graphics objects regarding the distance of a given point from the viewer. Relative distance from the camera does not affect the size of objects. Lines that are parallel in the data parallel appear parallel on the screen. This projection type is useful when it is important to maintain the actual size of objects and the angles between objects.

    Axes plane to display of point cloud, specified as "auto", "XY", "YX", "XZ", "ZX", "YZ", or "ZY".

    Vertical axis and direction, specified as "ZUp", "ZDown", "XUp", "XDown", "YUp", or "YDown". This argument sets the selected axis of the point cloud as the vertical axis, positive in the specified direction..

    Source of colormap data to use for the viewer, specified as one of:

    • "X" — Viewer maps the x-coordinates in the Location property of the input point cloud.

    • "Y" — Viewer maps the y-coordinates in the Location property of the input point cloud.

    • "Z" — Viewer maps the z-coordinates in the Location property of the input point cloud.

    • "Intensity" — Viewer maps the Intensity property of the input point cloud.

    • "Color" — Viewer maps the Color property of the input point cloud.

    • "Row" — Viewer maps the row values of an organized point cloud.

    • "Column" — Viewer maps the column values of an organized point cloud.

    • "auto" — If the input point cloud has RGB color data, the object uses those color values. If RGB color data is not available but intensity data is present, the object uses the intensity values. Otherwise, the object applies a colormap based on the z-coordinates in the Location property.

    If you provided the color input, the ColorSource name-value argument is not used.

    Viewer background color, specified as an RGB triplet, hexadecimal color code, or a character vector for a short or long color name. For details on color values, see the Color Value table.

    State of axes visibility, specified as "on" or "off", or as a numeric or logical 0 (false) or 1 (true). A value of "on" is equivalent to true, and "off" is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    • "on" — Display the axes and its children.

    • "off" — Hide the axes without deleting it. You still can access the properties of an invisible axes object. (Child objects such as lines remain visible.)

    Logical to enable point cloud optimization for display performance, specified as 1 (true) or 0 (false). When you set this argument to true, point clouds with more than 30 million points are converted into an octree structure. This structure renders a subset of points visible from the current viewpoint and adapts as the viewpoint changes. Enabling this optimization enhances interaction performance.

    When you set this argument to false, all points are displayed. Displaying all points can decrease interaction performance, depending on your graphics hardware. For more details about graphics rendering in MATLAB®, see System Requirements for Graphics

    Creating an octree structure requires the Point Cloud Toolbox. If the Point Cloud Toolbox is not available, all points will be displayed, which can decrease interaction performance.

    Parent container for the pcviewer object, specified as a Figure, Panel, GridLayout, or Tab object. You can use the uifigure, figure, uipanel, uigridlayout, and uitab functions, respectively, to create these parent containers.

    When you set Parent to [], the viewer opens in a separate window with a toolstrip. When you specify a parent container, pcviewer displays in that container without a toolstrip.

    Properties

    expand all

    Viewer background color, specified as an RGB triplet, hexadecimal color code, or a short or long color name. For details on color values, see the Color Value table.

    Point cloud points objects, specified as an M-by-1 array. M is the number of Points or BlockedPoints objects, returned by the addPointCloud object function.

    Surface mesh objects, specified as an M-by-1 array. M is the number of Surface objects, returned by the addSurfaceMesh object function.

    Shape objects, specified as an M-by-1 array. M is the number of shape objects, returned by the addShape, drawShape, and addCamera object functions. The type of object or objects depends on the which object function and shape added to the scene:

    • Camera — Camera object

    • Points — Points object

    • Lines — Lines object

    • Polyines — Polylines object

    • Cuboids — Cuboids object

    • Angles — Angles object

    • Elevations — Elevations object

    • Circles — Circles object

    • Freehand — Freehand object

    Camera position viewpoint, specified as a three-element vector of the form [x y z]. The camera is oriented along the view axis, which is a straight line that connects the camera position and the camera target. Changing the CameraPosition property changes the point from which you view the volume. For an illustration, see Camera Graphics Terminology.

    Camera target, specified as a three-element vector of the form [x y z]. The camera is oriented along the view axis, which is a straight line that connects the camera position and the camera target. For an illustration, see Camera Graphics Terminology.

    Upwards direction for the camera, specified as a three-element vector of the form [x y z]. For example, the default orientation of the z-axis is the up direction ([0 0 1]). For an illustration, see Camera Graphics Terminology.

    Camera zoom level, specified as a positive number.

    Camera pose, specified as a rigidtform3d (Image Processing Toolbox) object.

    Type of camera view projection, specified as a "projection" or "orthographic".

    Vertical field of view (FOV) for the perspective camera, specified as a positive scalar, in degrees. This property applies only when you set the CameraProjection property to "perspective".

    Camera navigation style, specified as "orbital-rotate-point", "orbital-rotate-center", "first-person", or "flyover".

    Orientation axes visibility, specified as "on" or "off", or as a numeric or logical 0 (false) or 1 (true). A value of "on" is equivalent to true, and "off" is equivalent to false. Thus, you can use the value of this property as a logical value.

    Gridded axes visibility, specified as "on" or "off", or as a numeric or logical 0 (false) or 1 (true). A value of "on" is equivalent to true, and "off" is equivalent to false. Thus, you can use the value of this property as a logical value.

    Object Functions

    addCameraDisplay camera in point cloud viewer
    addPointCloudDisplay point cloud in point cloud viewer
    addShapeDisplay shape in point cloud viewer
    addSurfaceMeshDisplay surface mesh in point cloud viewer
    drawShapeInteractively draw shape in point cloud viewer

    Examples

    collapse all

    Open Live Script

    Download two point clouds from the U.S. Geological Survey (USGS) 3D Elevation Program (3DEP) [1], covering the University of Utah campus and adjacent Wasatch Mountain foothills. The combined point cloud contains approximately 21 million RGB points.

    baseURL = "https://rockyweb.usgs.gov/vdelivery/Datasets/Staged/Elevation/LPC/Projects/Wasatch_Fault_UT_LiDAR/UT_Wasatch_L4_2013/LAZ/";

tiles = [
    "USGS_LPC_Wasatch_Fault_UT_LiDAR_12TVL2900012000.laz"
    "USGS_LPC_Wasatch_Fault_UT_LiDAR_12TVL3000012000.laz"
];

    Read each tile as a point cloud. Download tiles only if they are not already stored locally.

    pcArray = pointCloud.empty;
for i = 1:numel(tiles)
    localFile = fullfile(tempdir, tiles(i));
    if ~exist(localFile,"file")
        websave(localFile, baseURL + tiles(i));
    end
    reader = lasFileReader(localFile);
    pcArray(i) = readPointCloud(reader);
end

    Concatenate the tiles into a single point cloud.

    pc = pccat(pcArray);

    Visualize the large point cloud using the pcviewer object.

    pcview = pcviewer(pc);

    References

    [1] USGS Lidar Point Cloud UT_Wasatch_L4_2013 courtesy of the U.S. Geological Survey

    More About

    expand all

    Version History

    Introduced in R2023a

    expand all

    See Also

    Objects

    Functions

    Topics

    External Websites