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

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.

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

ptCloud — Point cloud

pointCloud object

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 — Filename

string scalar | character vector

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

color — Color for points in point cloud

RGB triplet | short color name | long color name | M-by-3 matrix | M-by-N-by-3 array | string array | cell array of character vectors

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.

Color	Format	Example
Specify one color for all points	Short or long color name.	"r" "red"
	1-by-3 vector (RGB triplet).	[255 0 0]
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-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.

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.

CameraProjection — Camera projection for 3-D views

"perspective" (default) | "orthographic"

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.

ViewPlane — Axes plane to display of point cloud

"auto" (default) | "XY" | "YX" | "XZ" | "ZX" | "YZ" | "ZY"

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

VerticalAxis — Vertical axis and direction

"ZUp" (default) | "ZDown" | "XUp" | "XDown" | "YUp" | "YDown"

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

ColorSource — Source of colormap data to use for the viewer

"auto" (default) | "X" | "Y" | "Z" | "Intensity" | "Color" | "Row" | "Column"

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.

BackgroundColor — Viewer background color

[0 0 0] (default) | RGB triplet | hexadecimal color code | short color name | long color name

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.

PointSize — Size of point cloud points

2 (default) | positive scalar

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

AxesVisibility — State of axes visibility

"off" (default) | "on" | 0 or false | 1 or true

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

Color — Color of points

RGB triplet | short or long color name | M-by-3 matrix | M-by-N-by-3 array

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.

PointSize — Size of points

2 (default) | positive scalar

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

MagnifyPointDisplay — Point display magnification

"off" (default) | "on" | 0 or false | 1 or true

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.

CameraPosition — Camera position viewpoint

[1 1 1] (default) | three-element vector

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.

CameraTarget — Camera target

[0 0 0] (default) | three-element vector

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.

CameraUpVector — Upwards direction

[0 0 1] (default) | three-element vector

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.

CameraZoom — Camera zoom level

1 (default) | positive number

Camera zoom level, specified as a positive number.

CameraProjection — Type of camera view projection

"projection" | "orthographic"

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

CameraViewAngle — Vertical field of view

60 (default) | positive scalar

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

BackgroundColor — Viewer background color

[0 0 0] (default) | RGB triplet | hexadecimal color code | short color name | long color name

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.

ShowOrientationAxes — Orientation axes visibility

"off" (default) | "on" | 0 or false | 1 or true

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.

ShowPointCloudAxes — Gridded axes visibility

"off" or 0 (false) (default) | "on" or 1 (true)

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

Plot Spherical Point Cloud with Texture Mapping

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

More About

Color Values

This table shows the valid long color names, their short name and RGB triplet equivalents, and how they appear in MATLAB^®.

Color Name	Short Name	RGB Triplet	Appearance
"red"	"r"	[1 0 0]
"green"	"g"	[0 1 0]
"blue"	"b"	[0 0 1]
"cyan"	"c"	[0 1 1]
"magenta"	"m"	[1 0 1]
"yellow"	"y"	[1 1 0]
"black"	"k"	[0 0 0]
"white"	"w"	[1 1 1]

Point Cloud Viewer Toolstrip and Interactions

You can expand the viewer toolstrip by clicking the Point Cloud Viewer tab. By default, the toolstrip is collapsed.

Feature	Viewer Interaction	Description
Camera Projection		Projection style of the camera.
Vertical Axis		Vertical axis and direction, specified by ZUp, ZDown, XUp, XDown, YUp, or YDown. This value sets the selected axis of the point cloud as the vertical axis, positive in the direction specified.
View Plane		Axes plane to display point cloud, specified as XY, YX, XZ, ZX, YZ, or ZY.
Navigation		View projection used to display the 3-D point cloud, specified as Orbital or First person. For more details, see Camera Navigation Controls
Rotate Around Point		Select any point as the center of rotation. When the Rotate Around Point is disabled, the center of rotation is the axes center. The Rotate Around Point mode can only be with theOrbital Navigation mode.
Camera Properties		Set camera location and orientation. The CameraViewAngle value applies only for the Perspective camera projection.
Color Source		Color source from which to render color values for the points. The available options depend on the data in the input point cloud. X, Y, Z — Available for all point clouds Color — Point cloud must have a non-empty color property. Intensity — Point cloud must have non- empty Intensity property. Range, Azimuth, and Elevation — Point cloud must come from a velodyneFileReader or a Pandar file reader. Row, Column — Organized point clouds. Custom — Color set when launching the pcviewer with the color argument, or by setting the Color property of the pcviewer object.
Colormap		Colormap used to render color.
Background Color		Viewer background color.
Point Size		Size of points, in pixels.
Point Size Attenuation		Attenuate the display of points. Enabling this option attenuates the size of the points based on the camera position. If the camera is positioned closer to the points, the points appear bigger than when the camera is far away. Attenuation size applies only for the perspective camera projection and the first person controls.
View Shortcuts		View the point cloud viewer keyboard shortcuts.

Mouse interactions:

Behavior	Mouse Interaction
Rotate	Left-click and drag
Pan	Hold Ctrl, then left-click and drag
Zoom	Scroll the wheel

Axes toolbar:

Behavior	Mouse Interaction or Interaction after Selection
Rotate	Left-click and drag
Pan	Left-click and drag
Zoom buttons	Scroll wheel
Default	Return to view from launch of viewer instance

Camera Navigation Controls

The point cloud viewer provides orbital and first-person navigation controls. These controls describe the behavior of the observer or first person, represented as the camera, with respect to the object to visualize or orbital, represented as the target.

• Orbital — Camera target is fixed. Only the camera position can change.

• First person — Both the camera position and the target position can change. Enables first-person navigation for the perspective camera projection.

This table lists the mouse interactions for the Orbital and First person camera controls:

Interaction	Orbital	First person
Rotate	Rotate the object around the observer	Observer rotates. (Looks around the scene.)
Pan	Pan the object with respect to the observer	Observer moves or "walks" through the scene in the left, right, up, or down directions.
Zoom	Zoom object toward or away from observer. (Make the object appear larger or smaller).	Observer moves or "walks" in the forward or backward directions.

This table shows the orbital keyboard shortcuts:

Behavior	Keyboard shortcut
Rotate by Z-axis	Left and right arrows
Rotate by X-axis	Up and down arrows
Rotate by Y-axis	Q and E

This table shows the first-person keyboard shortcuts:

Behavior	Keyboard Shortcut
Move forward	W — Forward S — Backward
Move left or right	A — Left D — Right
Move up or down	R — Up F — Down
Look around the scene (Pitch/Yaw rotation of camera)	Up arrow — Pitch up Down arrow — Pitch down Left arrow — Yaw left Right arrow — Yaw right
Roll the scene (Roll rotation of camera)	Q — Clockwise roll E — Counter-clockwise roll

Version History

Introduced in R2023a