Main Content

pcviewer

Visualize and inspect large 3-D point cloud

Since R2023a

    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

    Description

    example

    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.

    viewer = pcviewer(filename) visualizes points stored in the file specified by filename.

    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 or PCD formatted file.

    Color for points in the point cloud, specified as an RGB triplet, an M-by-3 matrix, or an M-by-N-by-3 array for an organized point cloud, a short color name, a long color name, array of color names, or a cell array of color names. 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 matrix 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

    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 Color property of the input point cloud is available, the object uses those color values. Otherwise, the object assigns the colormap based on the z-coordinates in the Location property of the input point cloud.

    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.

    Size of point cloud points, specified as a positive scalar, in pixels.

    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.)

    Properties

    expand all

    Color of the points, specified as an RGB triplet, short or long color name, M-by-3 matrix for unorganized point clouds, or an M-by-N-by-3 array for organized point clouds. If you do not provide the color input when you create the viewer, the object sets the color of the points by using the ColorSource name-value argument.

    Sizes of points, specified as a positive scalar, in pixels.

    Point display magnification, 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 shows the points magnified. A value of "off" is equivalent to false and shows points unmagnified, as they would appear from the position of the camera.

    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.

    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".

    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.

    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.

    Examples

    collapse all

    Create a sphere with 2500 faces. This generates a point cloud with approximately 6.25 million points.

    numFaces = 2500;
    [x,y,z] = sphere(numFaces);

    Load an image into the workspace, then map it to the coordinates of the point cloud points.

    I = imresize(imread("visionteam1.jpg"),size(x));
    color = flipud(im2double(I));
    color = reshape(color,[],3);

    Create a point cloud object with the location of the sphere and the color from the image.

    ptCloud = pointCloud([x(:) y(:) z(:)], Color=color);

    Visualize the point cloud, and optionaly interact with it using the viewer controls.

    pcviewer(ptCloud);

    2023-01-20_11-12-39.png

    More About

    expand all

    Version History

    Introduced in R2023a