Point Cloud Visualizer 3.0 Documentation

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

Available at Blender Market

Key Features:

• Display hundreds of millions of colored points in 3d viewport, limited only by system and gpu memory.
• Any Blender object can be used as container for points, points are not part of Blender data (until converted to) for maximal performance.
• Supported file formats - read: PLY, LAS/LAZ, E57, PCD, any text based file format such as PTS, XYZ, TXT, CSV etc., write: PLY, LAS/LAZ, E57 and PTS.
• Custom PLY reader/writer optimized for point data and performance.
• Supports loading/editing/writing of 3D Gaussian Splatting PLY files, can reconstruct points colors from spherical harmonics and convert to Blender mesh that can be rendered in Cycles engine approximating 3DGS effect.
• Display points with many shading options that can be mixed together, display points with analytic shaders, display point normals, use clipping planes, display scalar values (value remapping in range, color schemes).
• Fast Navigation option that draws subsampled points into 3d viewport while is being navigated for smooth working with very large datasets.
• Cleanup points directly with modal selection tools or by using Blender edit mode with temporary mesh linked with points using Blender tools.
• Mesh Retopology tools that utilize vertices snapping to points and mesh drawn with custom shaders over points.
• Clip planes modal tool to interact with clipping planes visually, store/restore clip planes named states.
• Abundance of editing filters: subsample/voxelize/slice points, crop, boolean, join, split, color adjustment, remove by color or value, project on mesh, remove duplicates, estimate normals, point set registration, surface reconstruction and many more.
• Builtin gpu rendering to image or images sequence with viewport or transparent background.
• Convert points to various Blender mesh (and vdb volume) data for use with Geometry Nodes and rendering with any render engine while preserving all loaded scalar fields and normals.
• Generate point clouds from mesh surface, mesh volume, Geometry Nodes vertices with attributes and generate point clouds from whole scene by simulating lidar scanner or photogrametry.
• Working with PLY sequences, playback, batch convert, filter and export. Sequence can also be generated from mesh or scene.
• Can be used as debugging tool to display 3d location/normal/color data with easy to use python api.

Platform Compatibility

• Windows, Linux and macOS

Blender Compatibility

• Blender 3.6 LTS or later

Installation

• download latest version point_cloud_visualizer-###.zip
• install as regular Blender addon: docs.blender.org

Update

• download latest version point_cloud_visualizer-###.zip
• start Blender, go to Preferences > Add-ons and find PCV in list
• expand by clicking left corner triangle
• disable PCV unchecking checkbox next to addon name
• click Remove button
• click Save Preferences button at bottom (skip if you have Auto-Save Preferences enabled)
• quit Blender
• start Blender
• install new PCV version and enable

About Optional Libraries

• NONE of them is required for regular use, majority of PCV functionality has no dependencies
• functionality that depends on any library is marked in PCV panel with plugin icon and library is imported in just executed operator, if not available, message is displayed
• all of them are installed from The Python Package Index (PyPI) using pip command
• libraries are not installed automatically, you need to open PCV preferences and click each install library button
• they are installed to user site-packages directory as defined in site.getusersitepackages(), exact location differs for each platform, if you click Read Me First button in PCV preferences, it will print out path to user site-packages directory

Where are Optional Libraries used?

• Open3D
  • Voxel Downsample
  • Normal Estimation
  • Point Set Registration
  • Surface Reconstruction
  • ...
• laspy
  • LAS file import/export
• lazrs
  • LAZ file import/export (requires laspy, recommended)
• laszip
  • LAZ file import/export (requires laspy)
• pye57
  • E57 file import/export (recommended)
• PyMeshLab
  • E57 file import (alternative)
  • Curvature filter
  • Screened Poisson Surface Reconstruction
• SciPy
  • Remove Duplicates
  • Poisson Disk Elimination
  • Blur Scalar
  • Calculate Density
  • Voxel Downsample
  • faster Transfer Colors
  • Tools > Retopology > Snap All/Selected
  • ...

Optional Libraries Compatibility

• Windows

  • do NOT use Open3D and PyMeshLab together, Blender will crash when one and the other is used (see workarounds)
  • do NOT use Open3D and pye57 together, Blender will crash when one and the other is used (see workarounds)
  • do NOT use Open3D and laspy + laszip together, Blender will crash when one and the other is used (see workarounds)
  • PCV will prevent crashes by default by monitoring which library has been used in current Blender session and not allowing problematic operation to be run, this behavior can be turned off in PCV preferences

• macOS

  • on Apple Silicon you need to use Blender Intel build to install and use PyMeshLab
  • pye57 have to be built from source, see step by step guide

• Linux

  • no known limitations/problems

Libraries Installation

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

• go to Preferences > Add-ons and find PCV
• expand to see PCV preferences
• click Install LIBRARY_NAME button
• wait until Blender is responsive again (if you start Blender from command line you can observe progress)
• restart Blender after each installed library

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.

Libraries Workarounds

• Windows
  • E57 files reading libraries (pye57 or PyMeshLab) and Open3D will crash Blender if both are used in single Blender session. To use both, install Open3D and pye57 (better option for E57 files reading) and use following system: start Blender, add an empty, go to PCV panel, import E57 file, export as PLY with PCV, quit Blender, start Blender, add PCV instance again and load exported PLY, use filters using Open3D as needed. Blender will only crash is one of libraries is used and then the other.
  • the same with LAZ files, reading LAS files is not affected

⚠️ 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.6. For Blender 4.0+ you need to install and use python 3.11 and Blender 4.0 python, but steps are identical.

• install homebrew
• install correct python version (for Blender 3.6 it is python 3.10) with homebrew

$ brew install python@3.10

• install wheel and pybind11 packages into python

$ /usr/local/opt/python@3.10/bin/pip3.10 install wheel
$ /usr/local/opt/python@3.10/bin/pip3.10 install pybind11

• install xerces-c library with homebrew

$ brew install xerces-c

• check path to xerces-c, we will use it later

$ brew info xerces-c

• at the time of writing: /usr/local/Cellar/xerces-c/3.2.5

• clone pye57 repository

$ cd ~/Desktop
$ git clone --recursive --depth 1 --branch v0.4.5 https://github.com/davidcaron/pye57.git
$ cd pye57/

• open setup.py in your favorite source code editor..
• after line libE57_cpp = sorted(map(str, (HERE / "libE57Format" / "src").glob("*.cpp"))) add following line:

libE57_cpp = [os.path.relpath(p, start=HERE, ) for p in libE57_cpp]

• after line package_data.append("xerces-c_3_2.dll") add following lines so it creates another platform related block between windows and linux (some basic python skills are needed to understand, sorry) and use path to xerces-c we checked earlier

elif platform.system() == "Darwin":
    libraries.append("xerces-c")
    library_dirs.append("/usr/local/Cellar/xerces-c/3.2.5/lib")
    include_dirs.append("/usr/local/Cellar/xerces-c/3.2.5/include")

• save and close
• build wheel

$ /usr/local/opt/python@3.10/bin/python3.10 setup.py bdist_wheel

• if there is error: Error: setup script specifies an absolute path, delete ~/Desktop/pye57/src/pye57.egg-info directory and run again, that directory will be recreated

• install wheel with Blender python

• ensure pip is present Blender python (not a copy-paste command, adjust path to Blender.app)

$ /Applications/Blender/blender-3.6.4.app/Contents/Resources/3.6/python/bin/python3.10 -m ensurepip

• macOS 11+ versioning is not that easy.. lets it turn off for a session, otherwise pip will fail with ERROR: pye57-0.4.5-cp310-cp310-macosx_12_0_x86_64.whl is not a supported wheel on this platform.

$ export SYSTEM_VERSION_COMPAT=0

• use pip from Blender python to install just built wheel into user site-packages (~/.local/lib/python3.10/site-packages) (not a copy-paste command, adjust path to Blender.app and wheel filename)

$ /Applications/Blender/blender-3.6.4.app/Contents/Resources/3.6/python/bin/python3.10 -m pip install --user ~/Desktop/pye57/dist/pye57-0.4.5-cp310-cp310-macosx_12_0_x86_64.whl

• library files will be installed to ~/.local/lib/python3.10/site-packages
• start Blender and check if e57 file are being loaded
• now you can archive or delete ~/Desktop/pye57

Integration

• PCV uses any Blender object as a "point in space", that object origin serves as zero point. Point cloud will then draw in object local space. i.e. point cloud will be transformed in the same way as container object. The best is to use Empty object type as containers.
• PCV by default does not store loaded points in blend file because there is no suitable data type available. Only PCV settings and path to data file is stored. when blend file is reopened, points need to loaded from linked file again by clicking Draw button. If you wish to store points in .blend file, see Packer in Preferences for more info.
• Any changes to points made with PCV have to be saved using Export panel before quitting Blender or loading other blend file, otherwise will be lost.

UI Locations

• main PCV panel is located in 3D Viewport Sidebar N under Point Cloud Visualizer tab
• one more extra pop up panel in 3D Viewport header at the top right corner
• helper operator in 3D Viewport > Add menu

General Use

To load and display point cloud from any supported file type, you can add an Empty type object to scene (or use any other Blender object type that exists in scene), then go to 3d Viewport sidebar > PCV tab and click Choose File , file browser will open, select your file and click Load. File will be loaded and contents displayed.

Add Menu Helper Operator

Faster and preferable way of adding PCV instance to scene is to use helper operator from Add menu: 3d Viewport header > Add or Shift+A anywhere in viewport and choose Point Cloud Visualizer menu item. File browser will open where you can choose single or multiple files, click Add PCV Instance(s) and for each selected file, new Empty object will be added, named after file name and file contents will be loaded and drawn.

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 and multiple files have to have the same format.

Large Datasets

• currently, PCV needs to load all points from source file and keep them in system memory
• during loading, system memory usage will peak quite high, 4 (and more in some cases) times the runtime usage
• for display, PCV need to upload all points that are going to be displayed (you can control amount with PCV > Display > Percentage slider) to gpu memory
• to determine approximate maximum number of points your gpu can display at once you can use calculator in PCV preferences (for example 8GB gpu can display ~300M points with default shader and disabled scalars), calculator formula is simple:

ram = 8192  # MB
b = (1024*1024) * ram  # bytes
# default shader uses 3x float32 for point location and 4x float32 for color (rgba)
# float32 takes 4 bytes, hence 3*4 + 4*4 bytes
n = int(b / (12 + 16))
print(n)  # 306783378

• trying to display more points (i.e. uploading more data than gpu memory can contain) will result in Blender crash or freeze
• when extremely big data need to be loaded and is not required to work with exactly all points, alternative loading methods Every Nth or Slice can be used to reduce number of points during loading

Fast Navigation

Draw low resolution point cloud during viewport navigation, it is enabled in PCV Preferences globally and will apply on all PCV instances in scene. During viewport navigation, normals and bounding box drawing is skipped, there rest of shading options is kept, selection is always drawn in full. Each PCV instance can be excluded by unchecking PCV > Display > Options > Use Fast Navigation.

Note: Blender API has no way to tell if user is navigating viewport (well, at least without using modal operator and that is not applicable in this case) so solution involves timers and because of that, when you are still navigating, but pause any movement a bit, high resolution will be drawn after delay and also first redraw when you just started navigating might lag a bit, API does not provide mouse events so i cannot react before view is really changed.

Panels

Main Panel

Main PCV panel is located in 3D Viewport Sidebar N under Point Cloud Visualizer tab. This panel shows active object properties and operators.

Main Controls

• Choose file clicking browse icon and from now on, active object is considered a "PCV Instance".
• and indicates Pack flag status. See Preferences for more info.
• reloads linked file contents.
• Linked file name and number of loaded / displayed points.
• Draw and Erase operators. Draw operator will also load points if they are not loaded. Erase will only stop drawing in viewport, loaded points will remain in system memory.
• Frame Points will center points in viewport camera and adjust its Clip End property if needed to show all points.

3D Viewport Panel

Pop up panel at the top right corner of 3D Viewport header contains actions that can run on multiple PCV instances at the same time, Packer operators that work with current blend file and Postprocess options.

Batch Operators

• Run basic loading, drawing and export operators on every PCV instance that is found in scene and falls under Influence. It is the same like selecting object by object and clicking operator button.
• Synchronize Shader Properties will copy display properties from active to influenced instance.

Packer

• Packer is fully automated storing of loaded points directly in .blend file as hidden mesh datablocks on .blend file save and restoring points from stored meshes on .blend file load. See Preferences for more info.
• Pack and Unpack operators are run automatically on .blend file events or can be run manually from here.
• Optimize will remove stored meshes if PCV instance is no longer present in .blend file, this is also automated during packing or can be run manually from here.
• Clear will remove all stored meshes.
• Mark All Loaded and Unmark All will set Pack flag on all pcv instances in scene.
• Packed Points are will show summary of stored mesh datablocks.

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 above everything else. Currently there is: 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. And Image Ouput that will create image datablock with the same content as is drawn on screen, useful for quick screen renders without camera and setting anything.

Display

Points

Colors

Alpha

Depth

Depth Effects

Matcap

Color Adjust

Shade

Illumination

Phong

Fresnel

X-Ray

Effects

Displace

Noise

Position Colors Shader Properties

Height Colors Shader Properties

Scalar Field

Clip

Normals

Bounding Box

Options

Load

General

Reader Options

ASCII Preset Builder

Example of typical PTS file preset

Data

Edit

Edit Mode

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, or enable Display > Points > Adaptive Size 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.

All tools when running shows help panel in viewport with all modal shortcuts. This help panel can be toggled with H key or disabled in preferences Show Help Panel At Tool Start.

3D Cursor

Place 3D Cursor

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

• LMB: Place
• Shift+LMB: Place and align with normal
• LMB+drag: Continuous place
• H: Toggle Help panel
• ESC: Exit

Place 3D Cursor (GPU)

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

• LMB: Place
• Shift+LMB: Place and align with normal
• LMB+drag: Continuous place
• D: Toggle using depth buffer for point selection
• H: Toggle Help panel
• ESC: Exit

Clip Planes

Clip Planes

Manipulate clip planes visually with gizmos.

• LMB: Manipulate
• RMB: Cancel current action
• G: Move mode
• SHIFT+LMB: Move facing planes together mode
• CTRL+LMB: Move facing plane in opposite direction mode
• A: Toggle move all gizmo
• R: Rotation mode
• SHIFT+LMB: Rotation precision mode
• CTRL+LMB: Rotation snap to 5° mode
• A: Toggle rotate along view axis gizmo
• E: Frame clip box
• F: Frame points
• B: Fit to bounding box
• [1-6]: Toggle plane enabled
• CTRL+[1-6]: Align viewport with plane
• V: Set all planes enabled
• [ or ]: Plane size
• S: Store current state
• CTRL(+SHIFT)+Z: Undo(Redo)
• H: Toggle Help panel
• ESC: Exit

Transform

Translate

Translate points container so selected point is at chosen location.

• LMB(+drag): Set point
• F: Translate
• D: Toggle using depth buffer for point selection
• RMB: Cancel current transform
• CTRL(+SHIFT)+Z: Undo(Redo)
• H: Toggle Help panel
• ESC: Exit

Rotate XY

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

• LMB(+drag): Set 3 points
• F: Rotate
• C: Toggle Use Corner
• D: Toggle using depth buffer for point selection
• RMB: Cancel current transform
• CTRL(+SHIFT)+Z: Undo(Redo)
• H: Toggle Help panel
• ESC: Exit

Align Z

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

• LMB(+drag): Set 2 points
• F: Align
• C: Toggle Use First
• D: Toggle using depth buffer for point selection
• RMB: Cancel current transform
• CTRL(+SHIFT)+Z: Undo(Redo)
• H: Toggle Help panel
• ESC: Exit

Scale

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

• LMB(+drag): Set points
• F: Scale
• C: Toggle Use Center
• D: Toggle using depth buffer for point selection
• RMB: Cancel current transform
• CTRL(+SHIFT)+Z: Undo(Redo)
• H: Toggle Help panel
• ESC: Exit

Cleanup

Box Select

Select points using box selection.

• LMB+drag: Draw selection
• SHIFT+LMB+drag: Add to selection
• CTRL+LMB+drag: Subtract from selection
• A: (De)Select all
• RMB: Deselect all
• I: Invert selection
• X: Remove selected
• H: Toggle Help panel
• ESC: Exit

Lasso Select

Select points using lasso selection.

• LMB+drag: Draw selection
• SHIFT+LMB+drag: Add to selection
• CTRL+LMB+drag: Subtract from selection
• A: (De)Select all
• RMB: Deselect all
• I: Invert selection
• X: Remove selected
• H: Toggle Help panel
• ESC: Exit

Circle Select

Select points using circle selection.

• LMB+drag: Draw selection
• SHIFT+LMB+drag: Add to selection
• CTRL+LMB+drag: Subtract from selection
• [ and ]: Adjust radius
• A: (De)Select all
• RMB: Deselect all
• I: Invert selection
• X: Remove selected points
• H: Toggle Help panel
• ESC: Exit

Gradient Select

Select points using gradient selection.

• LMB+drag: Draw selection
• SHIFT+LMB+drag: Add to selection
• CTRL+LMB+drag: Subtract from selection
• C: toggle constrain to vertical and horizontal axes
• A: (De)Select all
• RMB: Deselect all
• I: Invert selection
• X: Remove selected points
• H: Toggle Help panel
• ESC: Exit

Retopology

Polygon

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

• LMB: Place (on points) / Select (vertex in mesh)
• LMB+drag: Continuous place (on points) / Select more (vertices in mesh)
• CTRL+LMB+drag: Tweak placed point (while snapping on points and vertices) / Tweak mesh vertex (while snapping on points and vertices)
• D: Toggle using depth buffer for point selection
• B: Toggle Ignore Backfacing (for mesh vertices selection)
• M: Toggle Merge Mesh Vertices (disabled if selection exists)
• RMB: Cancel current polygon / Cancel tweak if active
• F: Make polygon from placed and/or selected / Make quad from single selected mesh vertex in corner and mouse location
• X: Delete selected mesh vertices
• TAB: Toggle Mesh Edit mode
• CTRL(+SHIFT)+Z: Undo(Redo) mesh edits only (Toggle Mesh Edit mode resets history)
• CTRL+S: Save the current Blender file
• H: Toggle Help panel
• ESC: Exit

Plane

Make quad plane rotated to fit selected points.

• LMB(+drag): Select points
• CTRL+LMB(+drag): Deselect points
• CTRL+SHIFT+LMB(+drag): Rotate plane
• RMB: Cancel current plane
• F: Make plane
• N: Make plane as new mesh object
• D: Toggle using depth buffer for point selection
• TAB: Toggle Mesh Edit mode
• CTRL(+SHIFT)+Z: Undo(Redo) (Mesh Edit mode resets history)
• CTRL+S: Save the current Blender file
• H: Toggle Help panel
• ESC: Exit

Cube

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

• 3x LMB(+drag): Place Cube Corners (drag moves last placed)
• After 3rd corner, set cube height
• 4th LMB: Make cube
• CTRL+LMB: Tweak last cube vertices freely
• CTRL+SHIFT+LMB: Tweak last cube vertices and snap to points
• RMB: Cancel current cube
• D: Toggle using depth buffer for point selection
• TAB: Toggle Mesh Edit mode
• CTRL(+SHIFT)+Z: Undo(Redo) (Mesh Edit mode resets history)
• CTRL+S: Save the current Blender file
• H: Toggle Help panel
• ESC: Exit

Filter

Points

Simplify

Remove Duplicates

Poisson Disk Elimination

Voxel Downsample

Crop

Boolean

Outlier Removal

Hidden Point Removal

Project

Split

Split By Scalar Value

Point Set Registration

Join

Apply Shader Effects

Transfer Data

Add Noise

Histogram 3D

DBSCAN Clustering

Normals

Estimate Normals

Add Normals

Colors

Remove Color

Color Adjustment

Clip Colors

Add Colors

Add Alphas

Add Colors From Spherical Harmonics

Transfer Colors

Project Image From Camera

Scalars

Remove Value

Blur Scalar

Posterize Scalar

Convert Scalar

Distance To Mesh

Colorize Scalar

Scalar From Mesh Vertex Group

Scalars From Mesh UV Map

Density

Curvature

Add Scalar

Mesh

Surface Reconstruction

Screened Poisson

Render

Output

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, unless Create Image Datablock is enabled, then will render to image datablock (single render, animation is always saved to disk), consecutive renders will create new image datablock each, images have to be saved manualy or packed to blend file.

Performance

Cache Buffers speeds up animation rendering by creating buffers once and reusing for the rest of frames. Works only on static point data (no sequences) and Display properties cannot be animated, Depth Sorting and HPR cannot be used. Only container transformation can be animated.

Anti-aliasing

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.

Look

• 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 or SciPy (depends on selected implementetion) 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.

Other Notes

• 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

Conversion Blender object/data type is set at panel top with Target enum.

Preset menu in panel header will save all panel settings into a preset.

Mesh

Volume

3D Gaussian Splatting

Pointcloud

Generate

Generation source Blender object/data type is set at panel top with Source enum.

Preset menu in panel header will save all panel settings into a preset.

Remove Generated operator will remove generated points and Move Points operator will move generated points from source object to a new Empty object.

Colors

Generation methods that use single object as source can generate point colors from various source found on mesh set with Colors enum.

• Constant Color - Use constant color value
• Color Attribute - Use active color attribute
• UV Texture - Generate colors from active image texture node in active material using active UV layout
• Vertex Group Monochromatic - Use active vertex group, result will be shades of grey
• Vertex Group Colorized - Use active vertex group, result will be colored from red (1.0) to blue (0.0) like in weight paint viewport

Other methods that use whole scene use rendered image that is rendered automatically in background. Generation from rendered image uses image itself.

Mesh Vertices

Mesh Surface > Random

Mesh Surface > Poisson

Mesh Surface > Project

Mesh Volume

Native Point Cloud

Geometry Nodes Vertices

Scene > Lidar Simulation

Scene > Project

Render

Export

File type is set at panel top with Type enum.

Preset menu in panel header will save all panel settings into a preset.

PLY

LAS/LAZ

E57

PTS

Sequence

Batch Filter

Batch Operations

Batch Convert

Batch Generate

Batch Export

Preferences

Tab Name

• Tab Name - if Point Cloud Visualizer is too long for your tabs, you can change to shorter PCV.
• Custom Tab Name - if set to existing tan name, PCV panel is moved there.

GPU Memory To Max. Points 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. See Large Datasets for more info.

Optional Libraries

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

• Check - Check each library if it is reported as available and show results. This check is executed without importing to prevent crashes, results may not be accurate.
• Prevent Library Conflicts - See Optional Libraries Compatibility and Libraries Workarounds for more info.

Defaults when using "PCV > Load" operator

Default options for load operator: 3d Viewport sidebar > PCV tab and click Choose File .

Defaults when using "Add > Point Cloud Visualizer" helper operator

Default options for helper operator (adds empty object to scene and loads points for each selected file): 3D Viewport > Add > Point Cloud Visualizer Shift+A

Fast Navigation

Draw low resolution point cloud during viewport navigation. See Fast Navigation for more info.

• Delay - Delay drawing of high resolution point cloud to viewport after navigation ended
• Percentage - Low resolution point cloud percentage, used until point count exceeds Maximum
• Maximum (Millions) - Low resolution point cloud maximum number of points, used when point count exceeds Percentage
• Auto Exclude (Millions) - Skip Fast Navigation if instance point count is lower, set to zero to disable and use on all instances, will not apply on points if low resolution is already generated in current session, reload files to update

UI

Tools

• Show Help Panel At Tool Start - Disable to hide help panel for each tool.
• Show Tools Color Theme - Edit color theme of Tools to fit your Blender theme.

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.

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

• Auto Pack: pack all points that are loaded and/or displayed when blend file is being saved
• Auto Optimize: remove packed datablocks on blend file save if container object is not found in scene

Utilities

• Reset PCV On Active Object - Reset all PCV properties stored on active object
• Reset PCV Preferences - Reset all PCV Preferences

Experimental

Patch 'pye57' library

Patch pye57 reader class at runtime to read files with scans without translation and rotation elements in its header.

Helps when reading e57 file ends in error E57 element path well formed but not defined (E57_ERROR_PATH_UNDEFINED) and in console with lines similar to this:

  File "/Users/redacted/.local/lib/python3.10/site-packages/pye57/e57.py", line 214, in read_scan
    xyz = self.to_global(xyz, header.rotation, header.translation)
  File "/Users/redacted/.local/lib/python3.10/site-packages/pye57/scan_header.py", line 32, in rotation
    q = Quaternion([e.value() for e in self.node["pose"]["rotation"]])
pye57.libe57.E57Exception: E57 element path well formed but not defined (E57_ERROR_PATH_UNDEFINED)

Viewer

Load and display very large datasets that does not fit into gpu memmory. Octree, Level of Detail, Camera Frustum, Threading, everything..

• Viewer is indirectly connected with 3d viewport where it has been started, if you change viewport to some other editor type, viewer will stop, if you maximalize viewport area, it will stop, if you open non-popup file select dialog, it will stop. If by any way original viewport is not found, Viewer will stop and reset (this behavior might change in future for some cases, if viewport connection is resumed in some given timeout). Other 3d viewports then initial will draw points, but they will not react on camera view changes (may be changed in future, but because of performance it is now omitted and most likely it will stay like that).
• Loading, octree preprocessing, sorting octree nodes according to camera view and their distance from camera, all of it runs in separate threads, so it does not block Blender, however processing data for gpu just before drawing cannot be done in background (Blender will crash instantly) so Blender will freeze a bit if a lot of octree nodes have to be updated at once (this might improve in future by processing it in smaller batches, but will not be eliminated).

Advanced

Debug Mode

Is enabled when Blender is started from command line with --debug-value 1 argument (or any non zero value) or you can set this at runtime by searching for Debug Menu and setting value in popup menu.

If Debug Mode is enabled, PCV will log more info to a console (terminal window, not Blender Info panel). In some cases even operation progress. PCV panels will also get several extra buttons to force shader rebuilding, debug options, some more panels with runtime info etc.

PCV preferences will also show more utility operators for pip command, listing installed packages, install package prompt, uninstall all packages from user site-packages directory etc. These operators are hidden from Blender Search Function to prevent accidental running. Can be only run from button in preferences.

API

A few utility functions are re-exported at PCV module level to aid with general script or addon development. If there is problem with function input, error will be logged to console, but all exceptions will be handled to not interrupt main script from running.

draw(data=None, *, name=None, matrix=None, is_debug=False, )

• Draw data with pcv
  • data: dict with vs, ns, cs and scalars keys (all optional except vs) with numpy arrays as values, all of them must have the same length, shapes of arrays must be: vs and ns (n, 3), cs (n, 4) or (n, 3) and scalars must be a structured array (n, ). if None is passed instead of a dict, empty arrays will be used, nothing will be drawn, but pcv will be initialized
  • name: string, assumes object is in scene, if not raises error, if None is passed, pcv_debug object will be created if needed and drawing mode is set to debug (is_debug=True) (i.e. bigger points, drawn on top, normals visible if exists, fast nav disabled..)
  • matrix: if not None, target object will get assigned this matrix to matrix_world, if not instance of Matrix, it will be converted (if possible, if not, will be ignored)
  • is_debug: if True, some for-better-visibility properties will be adjusted, see source for details, also set to True when no object name is passed (and pcv_debug is used instead)

properties(*, name=None, )

• Get property group with pcv properties
  • it is the same as bpy.context.scene.objects[name].point_cloud_visualizer
  • name: string, assumes object is in scene, if not raises error. if None is passed, pcv_debug name will be used

erase(*, name=None, )

• Stop drawing and unload data
  • if name is None, pcv_debug name will be used, if such object is found and is EMPTY type, will be removed
  • name: string, assumes object is in scene, if not raises error. if None is passed, pcv_debug name will be used

Basic Example

import numpy as np
import point_cloud_visualizer as pcv
# will create `pcv_debug` empty object in scene, to use existing object pass `name="OBJECT_NAME"`
pcv.draw(data={
    'vs': np.array([(0, 0, 0), (0.1, 0, 0), (0.2, 0, 0)], dtype=np.float32, ),
}, )

Full Example

import bpy
import numpy as np
import point_cloud_visualizer as pcv
from mathutils import Matrix
# add an empty object
o = bpy.data.objects.new("points", None)
bpy.context.view_layer.active_layer_collection.collection.objects.link(o)
# craft some object level transformation
m = Matrix.LocRotScale((0.1, 0.2, 0.3), Matrix.Rotation(np.pi / 4, 3, 'X'), (1, 1, 1))
# scalars got to be a structured array with named fields
sc = np.empty(3, dtype=[('intensity', np.float32, ), ])
sc['intensity'] = np.linspace(0, 1.0, 3)
pcv.draw(name='points', data={
    'vs': np.array([(0, 0, 0), (0.1, 0, 0), (0.2, 0, 0)], dtype=np.float32, ),
    'ns': np.array([(-1, 0, 0), (0, 1, 0), (0, 0, 1)], dtype=np.float32, ),
    'cs': np.array([(1, 0, 0, 1), (0, 1, 0, 1), (0, 0, 1, 1)], dtype=np.float32, ),
    'scalars': sc,
}, matrix=m, is_debug=True, )

Context Manager

Context manager for running PCV operators from custom scripts

Will make sure that name object exists, has loaded points in cache and drawn on screen (if not, tries to load linked file if possible), object is selected and active and operators are called with proper context.temp_override (i.e. 3d viewport exists, if not it will swap area, this is especially important when running render operator). On exit it will restore selection and original area (if has been swapped before).

Example (assuming there is an object named points in scene with linked file and (maybe) loaded points):

import bpy
import point_cloud_visualizer as pcv
with pcv.common.PCVOperatorContextManager('points'):
    bpy.ops.point_cloud_visualizer.render()

FAQ

I got warning icons and Missing vertex normals, Missing vertex colors and Missing scalars messages in Display panel

Loaded data does not have normals, colors or scalar fields so affected shading options cannot work properly, missing values are substitued by default normal or colors (exact values are in PCV > Load > General).

Points are missing when blend file is saved and reopened?

• PCV does not store loaded points in blend file because there is no suitable data type available. only PCV settings and path to data file is stored. when blend file is reopened, points need to loaded or imported from linked file again by clicking Draw button.
• If you are working with multiple PLY clouds at once, you can use PCV 3d viewport panel (viewport header top right corner: cloud icon) to Draw all PCV instances in scene at once.
• Any changes to points made with PCV have to be saved using Export panel to PLY before quiting Blender or loading blend file otherwise will be lost.
• Other option is to use Pack option that will automatically convert points to hidden mesh datablock on blend file save and restore on blend file load, but since blender uses only single precision floating point numbers for vertex positions, geolocated point data will lost its precision and cannot be moved exactly back. If you don't need to export points back to "world" locations (i.e. LAS/LAZ or E57 files) you can ignore this limitation.

How to render points in Cycles or Eeveee (with colors)?

• Points need to be converted to Blender native data type that can be rendered in engine. Conversion target is mesh vertices with Geometry Nodes to turn them to instances or points, see PCV > Convert panel.
• Converting points will create suitable color data and adds basic material using it so colors are preserved and available for render engine.
• Mesh instances can be rendered in Cycles and Eevee, points are supported only by Cycles.

Platform Compatibility

• Windows, Linux and macOS
• see Optional Libraries Compatibility for more details on 3rd party libraries

Blender Compatibility

• PCV 3.0 is for Blender 3.6 LTS and later

Large Datasets

• currently, PCV needs to load all points from source file and keep them in system memory
• during loading, system memory usage will peak quite high, 4 (and more in some cases) times the runtime usage
• for display, PCV need to upload all points that are going to be displayed (you can control amount with PCV > Display > Percentage slider) to gpu memory
• to determine approximate maximum number of points your gpu can display at once you can use calculator in PCV preferences (for example 8GB gpu can display ~300M points with default shader and disabled scalars), calculator formula is simple:

ram = 8192  # MB
b = (1024*1024) * ram  # bytes
# default shader uses 3x float32 for point location and 4x float32 for color (rgba)
# float32 takes 4 bytes, hence 3*4 + 4*4 bytes
n = int(b / (12 + 16))
print(n)  # 306783378

• trying to display more points (i.e. uploading more data than gpu memory can contain) will result in Blender crash or freeze
• when extremely big data need to be loaded and is not required to work with exactly all points, alternative loading methods Every Nth or Slice can be used to reduce number of points during loading

Is there a trial version?

No, sorry. it is not possible.

I got an error..

Please let me know "Ask a Question" sidebar button.

Ideal for any bug report would be starting Blender from command line and repeating error situation. Then copy messages from console window, add steps to reproduce it. If it is related to loading a point cloud file include it in report if it is possible.

I'd like to have X feature implemented..

Please let me know "Ask a Question" sidebar button. I am always open to suggestions.