PCV 3 Documentation: https://jakubuhlik.com/docs/pcv/

Point Cloud Visualizer

Display, edit, filter, render, convert, generate and export colored point cloud PLY files


Available at Blender Market


PCV



PCV 3

Core

Data

File I/O

Display

Packer

Tools

Filter

Render

Convert

Generate

Sequence

Postprocess

UI

Known Issues

Other Notes



Documentation for latest PCV version 2.2.0

Contents

Requirements ^^

Installation ^^

Update ^^

Optional Libraries ^^

Supported libraries and their functionality in PCV

Compatibility ^^

Installation ^^

Please see compatibility notes for your platform first. It is not needed to install library unless you need functionality that depends on it.

Specific version of library that is tested that is compatible is always installed. If library with different version already exists in user site-packages directory, it will be overwritten with required version. So, if new PCV version requires newer library version, to update simply run install library operator.

Workarounds ^^

Building ^^

⚠️ The only library that need to be built from source is pye57 for reading E57 files and only on macOS.

On other platforms it is installed from PyPI as other libraries, there is no need to build wheel manually. Guide is included only so macOS users can also benefit from better E57 reading library then PyMeshLab which sometimes does not preserve colors, uses scalar as colors even when colors are available and there is no way to prevent that. Guide is for macOS 12 and Blender 3.5.

If you are using Blender 3.0, steps are almost identical, you only need to $ brew install python@3.9 and then use it to build wheel, and after building use Blender 3.0 python binary to install wheel. It will also install to a different directory (~/.local/lib/python3.9/site-packages).

General Concepts ^^

UI Locations ^^

Integration ^^

Large Datasets ^^

Main Panel ^^

Please see property or operator tooltip in ui for more info.

UI Default

Display ^^

UI Display

Shaders

Scalars ^^

Scalars

Colorize points by scalar value. Choose scalar name from list. By default scalar value are scaled to fit in range 0-1 from lowest to highest value found. This behavior can be turned off or run at any time with buttons next to Range values. You can also choose to display in color Scheme instead of grayscale or lower Alpha of scalar over original colors or choose blending Mode with original colors.

Clip ^^

Clip

Clip displayed points by 6 planes. You can set plane values directly (first three values are plane normal, last value is distance from origin) or use any Blender Object bounding box to set planes from it. If Clip Planes Live Update is enabled, bounding box source object can be animated and clip planes will be updated on each redraw.

Normals ^^

Normals

Display point normals as lines in viewport. Control their Length, Alpha and Color. If loaded points has no normals, default normal (0,0,1) will be displayed.

Bounding Box ^^

Bounding Box

Display points bounding box.

Options ^^

Load ^^

UI Load

Loading options mainly for PLY loading. Other file formats importing (from external libraries) does not follow chosen Method (except ASCII import). Load and Reload operators are for PLY files only only, they use path to PLY set in main panel on top.

You can load less points from a big PLY files to save gpu memory using Every Nth or Slice methods. Method Every Nth does exactly what is says: 1 = all points, 2 = every second, 3 = every third. Slice method loads continuous part of file between From and To markers. Value of 0.0 = file start, 0.25 = first quarter of file, 0.5 = middle of file, etc.., if Slice From > Slice To, values are swapped.

Post-load Processing section applies on all file formats.

Reset PCV button resets everything in current PCV instance to default values.

Import ^^

UI Import

LAS requires laspy, LAZ laspy with laszip and E57 either pye57 or PyMeshLab installed from PCV preferences.

Edit ^^

UI Edit

UI Edit

Tools ^^

UI Tools

Collection of modal operators for direct editing of points, points container object or mesh. If operator is running all panels but Tools are disabled. To switch tool, click its button on panel.

All Retopology and Transform tools and Place 3D Cursor (GPU) are GPU accelerated. They utilize GPU for point selection. Points are selected in Detection Radius around mouse pointer, point closest to screen space center is selected. Point selection works best if points are that dense so they cover points behind them. If your points are too sparse, there are several options how to prevent selection of points behind those on “surface”. Increase point pixel size for pixel based shaders, or switch to any Billboard type shader and adjust point size so they cover space between them, or enable Use Depth (D key shortcut) at running tool panel to utilize gpu depth buffer to determine which points are closest in tool Detection Radius.

3D Cursor ^^

UI Tools

3D Cursor tools operate only on 3d Cursor.

Place 3D Cursor

Place 3D Cursor

Place 3D Cursor on closest point in cloud under mouse cursor. CPU variant, faster on smaller datasets.

Place 3D Cursor (GPU)

Place 3D Cursor (GPU)

Place 3D Cursor on closest point in cloud under mouse cursor. GPU accelerated variant, faster on large datasets.

Transform ^^

UI Tools

Transform tools operate on points container object. They will not modify points only container transformation in world coordinates.

Translate

Translate

Translate points container so selected point is at chosen location.

Rotate XY

Rotate XY

Rotate points container to align AB and BC lines between chosen 3 points and world Y and X axes.

Align Z

Align Z

Rotate points container to align tow selected points with world Z axis.

Scale

Scale

Scale points container to make length between two selected points equal chosen value.

Cleanup ^^

UI Tools

Cleanup tools will remove selected points from memory. If you need to save edits, export as ply after you are finished with cleanup.

Box Select

Box Select

Select points using box selection.

Lasso Select

Lasso Select

Select points using lasso selection.

Circle Select

Circle Select

Select points using circle selection.

Gradient Select

Gradient Select

Select points using gradient selection.

Retopology ^^

UI Tools

Retopology tools operate on separate mesh object. You can create one before running tool or create new at any time while tool is running.

For better mesh visibility while any Retopology tool is running, target mesh is hidden from viewport and drawn on top of points with custom shaders.

All Retopology tools allow switching to Blender Mesh Edit mode at any time for using Blender tools. When edit mode is exited, initial Retopology tool will be restored. In short, TAB into mesh edit mode, do what is needed, TAB back to initial Retopology tool to continue.

Polygon

Polygon

Draw polygons while snapping vertices on points or existing vertices in target mesh.

Plane

Plane

Make quad plane rotated to fit selected points.

Cube

Cube

Draw Cube alias Rectangular Cuboid snapped to points by setting three initial corners and arbitrary height.

Filter ^^

UI Filter

Simplify ^^

Filter Simplify

Reduce number of points. There are four methods, Slice removes points the same way as Display > Percentage slider does, Distant Samples takes random point, then number random candidates, accepts the most distant of them from already accepted, repeat. Result is nice and even, but algorithm is very slow. Voxel Grid covers points with 3d grid, then takes single point from each cell. Can optionally align points to grid. Voxel Grid v2 is faster variant with more options and eventually will replace former variant.

Project ^^

Filter Project

Projects points along their normals (backwards, forwards or both) on mesh surface. Points can be moved to hit location, their normal can be replaced with surface normal and points can be colorized by mesh uv texture, vertex color or vertex group, all of these properties can be enabled individually. Can also discard points that can’t be projected.

Transfer Colors ^^

Filter Transfer Colors

Transfer colors from points to mesh object vertex colors or uv texture. By default, color is taken from closest point, optionally you can average point colors in some radius. Transfer colors to UV texture requires non-overlapping UV layout fully contained in unit square on target mesh and material with active Image Texture node with loaded image to operate on. Extending margins on UV texture uses Blender baking system and requires Cycles to be set as render engine.

Crop ^^

Filter Crop

Fast crop points by object bounding box. Crop points inside bounding box or outside.

Boolean ^^

Filter Boolean

Intersect or Exclude points with mesh object. Mesh have to be non-manifold.

Color Adjustment ^^

Filter Color Adjustment

Adjust points colors with Exposure, Gamma, Brightness, Contrast, Hue, Saturation, Value and Invert controls. For fast viewport preview uses Color Adjustment shader, need to be applied with Apply button to point data.

Remove Color ^^

Filter Remove Color

Select points by color sampled from viewport or by numeric values. Selected points can be removed or split to new PCV instance.

Remove Value ^^

Filter Remove Value

Select points by scalar value. Selected points can be removed or split to new PCV instance.

Colorize ^^

Filter Colorize

Colorize points by scalar value, grayscale or heat map false colors.

Add Scalar ^^

Filter Add Scalar

Create scalar value on points from other point properties.

Add Normals ^^

Recreate point normals from three scalar values. Handy when loaded data does not define known normals format and their values are read as regular scalar values.

Add Colors ^^

Recreate point colors from three (or four) scalar values. Handy when loaded data does not define known colors format and their values are read as regular scalar values.

Split ^^

Filter Split

Split points to multiple PCV instances. Points can be split to Grid, or by point Count per instance or to several Pieces with roughly same point count.

Join ^^

Join selected PCV instances to one.

Merge ^^

Merge points with other PLY file.

Discard ^^

Discard normals, colors or scalars from points.

Poisson Disk Elimination ^^

Filter Poisson Disk Elimination

Fast poisson disk downsampling, discard points that are within other point radius.

Remove Duplicates ^^

Remove points by distance to other points.

Voxel Downsample ^^

Filter Voxel Downsample

Voxel downsampling uses a regular voxel grid to create a uniformly downsampled point cloud from an input point cloud.

Estimate Normals ^^

Filter Estimate Normals

Compute normals on points. If there are no normals on points, for correct result orientation, Orient have to be set. If there are normals, Use Existing is enabled and Orient is None, normals will be only averaged in radius and result will be smoother.

Point Set Registration ^^

Filter Point Set Registration

Align multiple PCV instances, selected are always aligned to active. There are several Method types to choose from. For details on each method see Open3D documentation. Generally Fast Global is good enough, if more precision is required, use Global with Local Refinement.

Surface Reconstruction ^^

Filter Surface Reconstruction

Reconstruct mesh surface. Depth controls mesh resolution. For correct results, points have to have normals.

Hidden Point Removal ^^

Filter Surface Reconstruction

Estimates and removes hidden points (i.e. occluded by other points closer to view location). Can use current 3d viewport view or an object in scene.

Curvature ^^

Filter Curvature

Compute curvature on points from underlying surface and output to colors or scalar.

Render ^^

UI Render

Render with OpenGL single or multiple PCV instances to image or sequence of images with transparent or 3d viewport background (as looks in Solid viewport shading). Points are always rendered with active shader used for drawing in viewport. Scalars, normals and bounding box is rendered if enabled and drawn in viewport. Clipping planes are used during rendering as well.

Other blender objects can be rendered together with points if Type is Viewport. They will look as in viewport.

Images are rendered in Properties > Output Properties > Format Resolution X,Y and % dimensions and saved as set in Properties > Output Properties > Output (image file formats only) at path at the same panel. If Save As Render is enabled, Properties > Output Properties > Output > Color Management is used. Rendered images are directly saved to output directory, they are not opened in image editor area as regular Blender renders.

For anti-aliased images, use Supersampling 2 or larger. At value 2 renders image at 200% size (3 at 300% etc.) and then downsamples to output resolution. This is limited by maximal gpu image (texture) resolution so be careful with value, use the smallest acceptable, usually at 2, amount of anti-aliasing is sufficient.

If you render points with alpha per point and Alpha shader, or if you use other Global Alpha then 1.0, for best result enable Depth Sort Points Each Frame for correct alpha blending. On the other hand, rendering will be slower because sorting is performed in python and not in gpu.

Hidden Point Removal runs Hidden Point Removal filter (requires Open3D to be installed) on points on each frame using render camera location

Postprocess applies postprocesing on renders as in viewport, but adjust setting first for rendering in Render panel. Because of different resolution, result may look different then in viewport.

Mask Pass and Depth Pass saves separate files with mask and depth buffer.

If you start Blender from command line you can observe animation rendering progress in terminal.

If you want to render points with Blender render engine (Cycles, Eevee or any other), points need to be converted to regular Blender object, see Convert section.

Convert ^^

UI Convert

Convert

Convert points to native Blender data type. Converted points are then part of blend file and can be used like any other native Blender data. Colors (all types except plain vertices), normals and scalars (Geometry Nodes types) are always preserved.

Mesh ^^

Convert points to single mesh object where each point is replaced with mesh primitive. Material using original points colors is added.

Instancer ^^

Convert each point to triangle in mesh object and then instance sphere on all faces. Material using original points colors is added.

Particle-System ^^

Convert each point to triangle in mesh object and then add particle system emitting single particle from each face. Material using original points colors baked to texture is added.

Instanced Mesh (Geometry Nodes) ^^

Convert points to vertices with attributes, add geometry node system instancing mesh primitive on vertices, colored and rotated by attributes. Mesh primitive type can be changed by modifying node tree. Material using original points colors is added.

Points From Mesh (Geometry Nodes) ^^

Convert points to vertices with attributes, add geometry node system converting vertices to points, colored by attributes. Material using original points colors is added. Result will render only in Cycles as spheres (sphere radius can be set in nodes or on modifier).

Native Point Cloud Object ^^

Convert points to Blender native Pointcloud Object. Pointcloud Object is unfinished Blender feature, it is available only in Blender alpha builds.

Generate ^^

UI Generate

Generate

Generate points from meshes and other Blender data. Points can be colored by various methods, vertex colors, uv texture, vertex group or vertex attributes.

Mesh Vertices ^^

Direct mesh vertices to points.

Mesh Surface ^^

Generate points on mesh surface using one of algorithms:

Mesh Volume ^^

Generate points in mesh volume. Mesh have to be non-manifold.

Particle System ^^

Particles from particle system to points

Native Point Cloud Object ^^

Points from Pointcloud Object (Pointcloud Object is unfinished Blender feature, it is available only in Blender alpha builds)

Geometry Nodes Vertices ^^

Points from vertices generated by Geometry Nodes. Normals, colors and scalars can be set from different attributes found on evaluated vertices.

Export ^^

UI Export

Export loaded points as PLY file. All point data (including all hidden points or scalar values) is saved.

Sequence ^^

UI Sequence

Sequence

Display sequence of PLY files. Add PCV instance, load first file of sequence. Then use Sequence panel to load the rest of sequence. Points from files can be preloaded to memory for smooth playback, or loaded on fly. Preloaded sequence displays only current frame that need to fit in gpu memory, but the rest of loaded files is in system memory. If you run out of system memory it is better to use on the fly loading type.

Batch Filter ^^

Apply select filter on all loaded sequence frames. Settings for filter is taken from its panel in Filter section. Filter settings can also be animated.

If you start Blender from command line you can observe progress in terminal.

Batch Operations ^^

Place for other operations on sequences with character that does not fall under filter category.

If you start Blender from command line you can observe progress in terminal.

Batch Convert ^^

Sequence Batch Convert

Convert each frame to Blender data type as set in Convert panel. Animation hiding/unhiding frame object is created automatically so playback is preserved.

If you start Blender from command line you can observe progress in terminal.

Batch Export ^^

Export each frame as PLY file using setting from Export panel.

If you start Blender from command line you can observe progress in terminal.

3D Viewport Panel ^^

UI 3d Viewport Menu

Panel is located in 3D viewport header in right corner as last item (unless other addon adds its menu there)

Batch Actions ^^

Here you can run actions on all PCV instances in scene that fall under Influence selection. Draw, Erase, Load, Unload, Reload, Export and Synchronize Shader Properties all PCV instances in scene at once.

Postprocess ^^

Postprocess

Viewport postprocessing. All draw calls from PCV goes to Offscreen first, then everything is drawn on top of viewport using selected shader. Because of that points will be always on top. Currently there is only one shader option: Quasi EDL, something very similar to Eye-Dome-Lighting. Points are shaded in screen space by their depth. No normals are required. The best use for it is when your points have no other data than point locations.

Preferences ^^

UI Preferences

Tab Name ^^

General ^^

Calculator ^^

Calculate theoretical maximum of displayable points for given gpu memory, floored to nearest tens of millions. Result is valid only when Default shader is used and nothing else displayed, i.e. location and color per point only.

Optional Libraries ^^

Install optional libraries by clicking Install NAME. Restart Blender after each installed library. To uninstall library, click its X button.

Defaults ^^

Default options for helper operator (add empty object to scene and load points from selected PLY) 3D Viewport > Add > Point Cloud Visualizer [Shift+A]

Tools ^^

⚠️ Experimental Features ^^

UI Experimental

Feeling adventurous? Experimental section in Preferences lets you enable upcoming features. Detailed bug reports welcome!

Packer ^^

UI Packer

Store loaded points as hidden mesh datablock with attributes in blend file. Automatically restore and draw points from datablock at blend file load, save points to datablock on blend file save.

This operation is meant to be fully automatic (if Auto Pack and Auto Optimize options in preferences are enabled, they are by default) once loaded point data are marked for packing clicking Pack icon next to file path on main PCV panel (this will work for any file formats, even those loaded using Import panel).

If Packer is enabled, main operators (Draw, Erase, Reload etc.) will prioritize packed data (if available) over loading from ply file.

Operators

UI 3d Viewport Menu

Packer adds utility operators to 3D Viewport Panel as well as list of packed datablocks in blend file.

Preferences

Viewer ^^

Load and display very large datasets that does not fit into gpu memmory. Octree, Level of Detail, Camera Frustum, Threading, PLY, LAS/LAZ and E57, all of it is there..

UI Viewer

UI Viewer

Already processed octree can be saved to disk to speed up processing next time file is being loaded. It will save compressed JSON file next to original file, with -pcv_octree.json.gz suffix. This can be automated so it is always saved with Auto Save Serialized Octree option and with Use Serialized Octree enabled, serialized data will be preffered when file is loaded. However, file contents cannot be changed, otherwise saved octree will be invalid. Also, although compressed, serialized octree files are not small.

To significantly speed up json operations, install orjson library, it is installed as other libraries from PyPI with PCV Preferences > Experimental Features > Install Optional Libraries button. This step is optional, if library is not found, python builtin json module will be used.

UI Viewer

UI Viewer

Size and Alpha of displayed points, Default Shader basic stuff

UI Viewer

UI Viewer

Batch Files To Octrees: operator to preprocess multiple files in single directory to serialized octrees, this is blocking operator, to watch progress, start Blender from command line

UI Viewer

Debug Display: draw debug extras in viewport, viewport camera frustum and depth segments, octree cubes and tint point colors by their depth in octree

Add Menu ^^

UI Add Menu

Helper operator to add an empty object with PCV instance and points from selected file can be run from 3D Viewport > Add > Point Cloud Visualizer [Shift+A]. If multiple files are selected, they will be added as separated PCV instances. Any file format that is readable by PCV can be loaded this way, only ASCII file types need to use preset that has been made and saved in advance.

UI Add Menu File Browser Sidebar

Default options can be set in PCV > Preferences, options can be also overriden while operator is running in file browser sidebar.

API & Debug Mode ^^

API

Debug

Debug

To display some basic point data

import bpy
import numpy as np
import point_cloud_visualizer as pcv

# get container reference
o = bpy.context.active_object
# "register" object
pcvo = pcv.mechanist.PCVOverseer(o)

# generate some data to display
n = 1000
vs = np.random.normal(0, 2, (n, 3))
ns = np.full((n, 3), (0.0, 0.0, 1.0))
cs = np.random.random((n, 3))

# access properties and change default values to something more suitable
pcvo.props().display.vertex_normals = True
pcvo.props().display.vertex_normals_size = 1.0
pcvo.props().display.vertex_normals_alpha = 1.0
pcvo.props().display.point_size = 6
pcvo.props().display.draw_in_front = True

# load and draw data on screen
pcvo.load(vs, ns, cs, draw=True)

# stop drawing
# pcvo.erase()

# stop drawing and remove from memory
# pcvo.free()

To display some more advanced point data

import bpy
import numpy as np
import point_cloud_visualizer as pcv

o = bpy.context.active_object
pcvo = pcv.mechanist.PCVOverseer(o)

# generate some data including scalars
n = 1000
vs = np.random.normal(0, 2, (n, 3))
ns = np.full((n, 3), (0.0, 0.0, 1.0))
cs = np.random.random((n, 3))
dt = [('v0', int), ('v1', float)]
scalars = np.empty(n, dtype=dt)
scalars['v0'] = np.arange(n, dtype=int, )
scalars['v1'] = np.linspace(1.0, 0.0, num=n, dtype=float, )

# create internal data object
pd = pcv.data.PCVPointData.from_arrays('_.ply', {'vs': vs, 'ns': ns, 'cs': cs, 'scalars': scalars, })

pcvo.props().display.use_scalar = True
pcvo.props().display.point_size = 6
pcvo.props().display.draw_in_front = True

# load data and draw data object
pcvo.data(pd, draw=True)

Debug Mode

If Blender is started from command line with --debug-value 1 (basically any non zero value, this can be also set at runtime by searching for Debug Menu and setting value in menu) PCV will log more info to a console. In some cases even operation progress.

Troubleshooting ^^

Points looks weird in viewport, they flicker or look “stratified”

I got Missing vertex normals and Missing vertex colors warning messages under Shader drop down menu

Points are not drawn in viewport on macOS in Blender 3.5

Bugs? Suggestions? ^^



© 2023 Jakub Uhlik