pcshow

Plot 3-D point cloud

Syntax

``pcshow(ptCloud)``
``pcshow(xyzPoints)``
``pcshow(xyzPoints,color)``
``pcshow(xyzPoints,colorMap)``
``pcshow(filename)``
``pcshow(___,Name=Value)``
``ax = pcshow(___)``

Description

example

````pcshow(ptCloud)` displays points using the locations and colors stored in the point cloud object.```
````pcshow(xyzPoints)` displays points specified by the `xyzPoints` matrix.```
````pcshow(xyzPoints,color)` displays points contained in the `xyzPoints` matrix, with colors specified by `color`.```
````pcshow(xyzPoints,colorMap)` displays points contained in the `xyzPoints` matrix, with colors specified by `colorMap`.```
````pcshow(filename)` displays the point cloud stored in the file specified by `filename`.```
````pcshow(___,Name=Value)` specifies options using one or more name-value arguments in addition to any combination input of arguments from previous syntaxes. For example, `ViewPlane="XY"` sets the plane from which to visualize the point cloud as the XY-plane.```
````ax = pcshow(___)` returns the plot axes.```

Examples

collapse all

Generate a sphere consisting of 600-by-600 faces.

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

Plot the sphere using the default color map.

```figure; pcshow([x(:) y(:) z(:)]) title("Sphere with Default Color Map") xlabel("X") ylabel("Y") zlabel("Z")```

Load and display an image for texture mapping.

```I = im2double(imread("visionteam1.jpg")); imshow(I)```

Resize and flip the image in preparation for mapping the coordinates.

`J = flipud(imresize(I,size(x)));`

Plot the sphere with the image as a color texture.

```pcshow([x(:) y(:) z(:)],reshape(J,[],3)) title("Sphere with Color Texture") xlabel("X") ylabel("Y") zlabel("Z")```

Load an organized lidar point cloud that includes intensity data.

`ld = load("drivingLidarPoints.mat");`

Plot the point cloud and label the figure. By default, the intensity is mapped to the `jet` colormap.

```figure pcshow(ld.ptCloud) title("Lidar Point Cloud with Intensity") xlabel("X") ylabel("Y") zlabel("Z") colorbar colormap("winter")```

Input Arguments

collapse all

Point cloud, specified as a `pointCloud` object. The object contains the locations, intensities, and RGB colors to render the point cloud.

Point cloud filename, specified as a character vector or a string scalar. The file must be of a type supported by `pcread`. The `pcshow` function calls `pcread` to read the point cloud from the file, but does not store the data in the MATLAB® workspace.

Point cloud x-, y-, and z- locations, specified as either an M-by-3 numeric matrix or an M-by-N-by-3 numeric array. The `xyzPoints` argument contains M or M-by-N points in the form [x,y,z]. The z values, which generally correspond to depth or elevation, determine the color of each point. When you do not specify the input color, the function maps each z value to a color in the current colormap.

Color for points in the point cloud, specified as an RGB triplet, an M-by-3 matrix, an M-by-N-by-3 array, a short color name, a long color name, array of color names, or a cell array of color names. For details on color values, see the Color Value table.

• For the `single` or `double` data type, each `color` RGB value must be in the range [0, 1].

• For the `uint8` data type, each `color` RGB value must be in the range [0, 255].

• The function stores the `color` value as either an M-by-3 matrix or M-by-N-by-3 array. If you specify the color as a string or a 1-by-3 vector, the function converts it to one of these dimensions.

ColorFormatExample
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 of character vectors

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

M-by-3 matrix, in which each row is an RGB triplet

```255 0 0 255 0 0 0 255 255```

M-by-N-by-3 array for an organized point cloud, containing RGB values for each point, where M-by-N is the size of the point cloud.

Point cloud color map, specified as an M-by-1 vector or an M-by-N matrix.

Points InputColor SelectionValid Values of color
`xyzPoints`Different color for each pointVector or M-by-N matrix. The matrix must contain values that are linearly mapped to a color in the current `colormap`.

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: `ViewPlane="XY"` sets the plane to the x-y axes from which to visualize the point cloud.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Diameter of the marker, specified as a positive scalar. The value specifies the approximate diameter of the point marker. MATLAB graphics defines the unit as points. A marker size larger than 6 can reduce rendering performance.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Background color, specified as an RGB triplet, hexadecimal color code, or a character vector that specifies a long or short color name.

Data Types: `cell` | `char` | `uint8` | `uint16` | `int16` | `double` | `single`

Vertical axis, specified as `"X"`, `"Y"`, or `"Z"`. This value sets the selected axis of the point cloud in the vertical direction.

Vertical axis direction, specified as `"Up"` or `"Down"`.

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.

Plane to visualize point cloud, specified as `"auto"`, `"XY"`, `"YX"`, `"XZ"`, `"ZX"`, `"YZ"`, or `"ZY"`. The `ViewPlane` argument sets the line of sight from the camera, centered in the selected plane, to the center of the plot.

Point cloud property for colormap, specified as `"auto"`,`"X"`, `"Y"`, `"Z"`, `"Intensity"`, `"Color"`, `"Row"`, `"Column"`. The `pcshow` function uses the value of `ColorSource` to assign a colormap when rendering the point cloud. The values use these properties:

• `"X"`x-coordinates in the `Location` property of the input point cloud.

• `"Y"`y-coordinates in the `Location` property of the input point cloud.

• `"Z"`z-coordinates in the `Location` property of the input point cloud.

• `"Intensity"``Intensity` property of the input point cloud.

• `"Color"``Color` property of the input point cloud.

• `"Row"` — Row values of an organized point cloud.

• `"Column"` — Column values of an organized point cloud.

When you set `ColorSource` to `"auto"`, the function sets the colormap depending on which property values are available in the input point cloud object:

Available Point Cloud PropertyColor Source
`Location` only Maps the z-value to a color value in the current colormap.
`Location` and `Intensity` Maps the z-value to a color value in the current colormap.
`Location` and `Color` Maps the color values to the current colormap.
`Location`, `Intensity`, and `Color` Maps the color values to the current colormap.

State of axes visibility, specified as `"off"` or `"on"`, or as numeric or logical `0` (`false`) or `1` (`true`). A value of `"off"` is equivalent to `false`, and `"on"` is equivalent to `true`. 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`.

• `"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.)

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

Axes on which to display the visualization, specified as an `Axes` object. To create an `Axes` object, use the `axes` function. To display the visualization in a new figure, leave `Parent` unspecified.

Output Arguments

collapse all

Plot axes, returned as an `axes` graphics object. Points that are represented as `NaN` or `Inf` are not included.

You can set the default center of rotation for the point cloud viewer as the axes center or as a point. Set the default behavior from the Computer Vision Toolbox Preferences.

A rotation axes (represented with red, blue, and green lines) appears at the center of rotation when rotating the point cloud.

collapse all

Axes Toolbar Operations

To view the axes toolbar operations, point to the figure and select one of these options. Click the Restore View icon to reset the display.

Feature Left to RightDescription
Vertical AxisSelect an X, Y, or Z direction to set that axis of the point cloud into the vertical direction. Use the keyboard arrow keys to move the point cloud with respect to the direction selected.
View Plane

Select the viewing angle of the point cloud figure as the XY, YX, XZ, ZX, YZ, or ZY plane.

Background ColorDisplay a color chart from which you can select a background color.
Axes On/OffTurn the display axes on or off.
ProjectionSelect perspective or orthogonal view.
Export
• : Save the content as a tightly cropped image or PDF.

• : Copy the content as an image.

• : Copy the content as a vector graphic.

BrushEnable data brushing mode.
Data Tips

View the point data values by selecting any point in the point cloud figure. The Data Tips display shows the x, y, and z values. Point clouds for depth images and lidar contain these additional data properties:

Depth image (RGB-D sensor), , and
Lidar, , angle, angle, , and

Rotate 3D

Drag to rotate the point cloud figure. You can also right-click any point on the point cloud figure, and select to specify that point as the center of rotation for the figure. To return to axes rotation, right-click again and select .

While in mode, you can also select the color source for the point cloud by right-clicking and selecting , and then an option from the list. The figure applies the active colormap to the point cloud based on the values in the selected source. For a point cloud of only position data, the options are , , , and. Point clouds for depth image and lidar data include these additional color source options:

Depth image (RGB-D sensor), , and
Lidar, , , , , and

Pan, Zoom in, and Zoom outManeuver the point cloud, or zoom the point cloud figure in or out.
Restore ViewRestore the original view of axes.

Move Camera Through Scene

To navigate into a point cloud and observe the scene, use these keyboard shortcuts:

ActionKeyboard ShortcutExample
Move forward or backward

w — Forward

s — Backward

Move left or right

a — Left

d — Right

Look around the scene (pitch/yaw rotation of the camera)

Up arrow — Camera pitches up

Down arrow — Camera pitches down

Left arrow — Camera turns left in yaw

Right arrow — Camera turns right in yaw

Roll the scene (roll rotation of the camera)

q — Camera moves clockwise. (Scene appears to move counterclockwise.)

e — Camera moves counterclockwise. (Scene appears to move clockwise.)

Rotate the scene (rotate the camera around the point cloud)

Shift + Left or Right — Camera orbits horizontally around the point cloud. (Scene appears to stand still as camera moves externally around it horizontally.)

Shift + Up or Down — Camera orbits vertically around the point cloud. (Scene appears to stand still as camera moves externally around it vertically.)

Zoom in or out

z — Zoom in

x — Zoom out

Look at a view plane

1 — XY

2 — YX

3 — XZ

4 — ZX

5 — YZ

6 — ZY

Camera positioned in the selected plane with a line of sight to the center of the plot.

Switch between rotate and pan Spacebar — Press and hold the spacebar to switch the interaction to pan. Release the spacebar to switch back to rotate.

Rotate in X-, Y-, and Z- dimensionsT — Adds rotate interaction in the third dimension.

Color Values

Color NameShort NameRGB TripletAppearance
`"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]`

Performance and Tips

• To improve performance, the function automatically downsamples the rendered point cloud when you rotate, pan, or zoom in or out by clicking the mouse. Downsampling is not applied for zoom in or out by using the mouse scroll mechanism. When using data tips, the figure does not apply downsampling. The downsampling occurs only for rendering the point cloud and does not affect the saved points.

• The keyboard shortcuts described in Move Camera Through Scene are not supported for popped-out windows using Live Editor.

• When you reload a saved figure, any action on the figure resets the vertical axis to the z-axis and in the up direction.

Version History

Introduced in R2015b

expand all