import-ply-as-verts v2.1

Blender 3.0 * / 3.1 Alpha (and later) New PLY Importer

* Vertex colored mesh only in 3.0 (see Compatibility).
Complete drop-in replacement for the stock Blender PLY import module.
Correctly loads vertex-colored point clouds and nonstandard PLY files that the original importer wasn't intended for.
Retains the functionality of the original codebase.

3 April 2022 - Version 2.1 Release: fixed several compatibility issues with various odd types of Ply.

Why

Attempting to import any of the below PLY files with the stock importer will fail:
- Triangle/Quad Meshes with nonstandard file terminators (BTracer2 PLY export)
- Zero edge/face point cloud files, ie:
  - Mandelbulb3D BTracer Point Cloud (v.1.99 and earlier)
  - Mandelbulb3D BTracer2 PLY (1.99.12 and later)
  - J-Wildfire Point Cloud (Some incompatible edge cases may yet exist. They will be patched as needed.
  - Photogrammetry scans (MeshLab, et. al.)

The result in Blender is the system console window error message "Invalid header, etc..."

Which has proven most frustrating for several years now.

Prior to this, a good workaround was to process the point cloud in MeshLab. I love MeshLab and use it often, but it is daunting at best. The real idea was to have native Blender import. Recent functions added under the hood of the Realize Instances node suddenly dovetailed with a standalone instancing app I had been working on since 2017. Realizing that six nodes can replace my entire program, I cheerfully abandoned it and put full effort into the importer.

The combined result is a completely new workflow for the point cloud enthusiast.

Result

(Left to Right, Back Row First)

Vertex-Painted Suzanne (Same file as Mesh and Verts);

BTracer2 (Same file as Mesh and Verts);

J-Wildfire Point Cloud;

Photogrammetry Point Cloud

All the objects in this scene share a single Material of correctly imported vertex colors. The point clouds have a simple Geometry Node tree applied . (Material and Nodetree included in the Example.blend file).

Cycles Point Cloud Render

The brand new Point Cloud Render mode in Cycles works beautifully well with these (thank you to Bone Studio and Daniel Leike). A tutorial is available on YouTube, and our image was included in the Blender 3.1 Release Notes - Cycles

Compatibility

Mesh Import is verified for 3.0 (thanks to Carisma Alex for asking!) and works exactly like the process in Mandelbulb3D - BTracer2 Workflow Basic. However, the Point Cloud object requires new functionality added in Blender 3.1 to correctly assign the colors. Direct import results in a charcoal briquette with missing surface normals. A workaround is to create the Point Cloud in 3.1 (with applied Geo Node Modifier), save as a .blend file or export to a modern format like .gltf, and open in 3.0. A call to (Edit Mode) Mesh->Normals->Recalculate Outside is usually necessary.

Install

Since these are Scripts and not an Addon, the __init__.py and import_ply.py files from the repo will need to be manually pasted alongside the stock importer files.

Open Blender's location on your computer. On Windows this is generally 'C:\Program Files\Blender Foundation'
If multiple version numbers are present, open the folder of the version you want to upgrade (for our example here, 'Blender 3.1')
Open the '3.1' folder
Open the 'scripts' folder
Open the 'addons' folder
Open the 'io_mesh_ply' folder
Rename '__init__.py' to something like '__init__-OLD.py'
Remame 'import_ply.py' to something like 'import_ply-OLD.py'
Paste in the new __init__.py and import_ply.py from the repository
Restart Blender

This will need to be done once for each version of Blender you would like to use the script with. If you want to revert to the original script, reverse steps 7 and 8.

The install procedure is also contained in Install-v2.pdf and How to Install v2.0.

Usage

Once the scripts are replaced, File->Import will now look like this:

Selecting Stanford PLY as Verts will bring up the Filebrowser as usual, with an additional checkbox:

Several things may happen at this point:

A triangle/quad mesh file may be loaded as either point cloud (checkbox selected) or mesh (checkbox deselected).
A point cloud file may be loaded with the checkbox selected.
A point cloud file may be loaded with the checkbox deselected, and the autodetect routine will use the correct loading method.
- Known Issue:- a bug in the autodetect slows performance as it causes the file to be read twice. Currently working on a fix.

Performance

Importing a mesh is the heaviest operation, as importing the same file as verts is about 60% faster. This is due to the triangle-building algorithm from the stock importer. Improvements can be made here!

*Stock time is listed only for reference - it's faster because it bails out and produces an unusable model.

Known Issues

The autodetect bug mentioned above.
The checkbox occasionally remains checked despite being False under the hood. This is under investigation.

Python API

The API call has a new optional Boolean parameter, use_verts (default=False):

bpy.ops.import_mesh.ply(filepath="", files=[], use_verts=False, directory="", filter_glob="*.ply")

and is used similar to

Dave = bpy.ops.import_mesh.ply(filepath="C:\\mb3d_mesh.ply", use_verts=True)

Backward Compatibility

A call like Dave = bpy.ops.import_mesh.ply(filepath="C:\\mb3d_mesh.ply") is equivalent to using the stock importer and shouldn't break existing scripts.

Proposed API Docs

bpy.ops.import_mesh.ply(<i>filepath='', files=None, use_verts=False, directory='', filter_glob='*.ply'</i>)

Load a PLY geometry file as verts or mesh

  Parameters: filepath (string, (optional, never None)) – File Path, Filepath used for importing the file
              files (bpy_prop_collection of OperatorFileListElement, (optional)) – File Path, File path used for importing the PLY file
              use_verts (boolean, (optional)) - Load as verts or triangle/quad mesh
              hide_props_region (boolean, (optional)) – Hide Operator Properties, Collapse the region displaying the operator settings
              directory (string, (optional, never None)) – directory
              filter_glob (string, (optional, never None)) – filter_glob

File: addons/io_mesh_ply/init.py:81

Roadmap

Performance can likely be improved. I haven't looked too deeply into the read() module which is a common bottleneck in file i/o.
Exporting Blender objects as verts is not yet supported. Not a huge priority but will be addressed.
Various refactoring.

Tutorials

How to Install v2.0
Mandelbulb3D - BTracer2 Workflow Basic
Mandelbulb3D - BTracer2 Workflow Advanced
J-Wildfire
Photogrammetry Rescue with MeshLab and VisualSFM
Cycles 3.1 Point Cloud Render
World Blender Meetup Day 2022 Presentation
...

Blog and References

Under construction

mnmly/import-ply-as-verts