Skip to content

Blender Python PLY importer for point clouds and nonstandard models.

Notifications You must be signed in to change notification settings

TombstoneTumbleweedArt/import-ply-as-verts

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 

Repository files navigation

Import-PLY-As-Verts v3.0         Generic badge         Logo_Blender-Dark

Blender Python PLY Import Addon

Preamble

As of Blender 4.0 the original Python PLY import/export will be deprecated in favor of the new C++ modules. These modules are a great deal faster (at the moment) but nowhere near as source-friendly as Python. Due to the flexible nature of the PLY format, compatibility with Blender has remained an issue. Our open-source Python Addon is currently the most compatible and flexible option for 'nonstandard' models such as point clouds.

Our thanks to Ms. Katherine Jarvis, a true Pythonista.

New to 3.0


  • Attributes. ALL data in the PLY file - vertex colors, normals, etc., is parsed into usable Blender Attributes.
  • Improved compatibility, especially with CloudCompare.
  • Improved performance (more to come).
  • The program is now an actual Addon and not the kludgey install hack from previous versions :)

Why

  • Attempting to import certain PLY files with Blender's 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
      • Photogrammetry scans (MeshLab, CloudCompare, et. al.)
      • Practically any 'extra' value beyond xyz, vertex normal, and vertex color.

The result in Blender a system console window error message or no error at all.

Legacy Python error message, Blender 3.6 and earlier:

Error-Message

C++ Import error message, Blender 3.6 and higher:

image

Prior to this, a fair workaround was to process the point cloud in MeshLab. I love MeshLab and use it often. However, despite it being capable of importing a much wider variety of nonstandard PLY, MeshLab still strips out 'extra' data if the model is reexported.

Ms. Katherine Jarvis of The TriForce Institute for Multiphysics Modeling emailed the below:

“My name is Katie, I’m a current college student who has been using your import-ply-as-verts addon for the past year or so as part of the research that I do with a physics team I’m working on that focuses on particle simulation. I saw that Blender incorporated a lot of your changes into the most recent 4.0 update which is super cool but I noticed that they still don’t have an option for custom attributes that aren’t just location and color. … This summer and some of last summer, I made some personal edits to your python code that allowed for reading of the ply header in order to create custom named attributes. … I was wondering if you might be interested to take a look and possibly incorporate some of the changes onto your main branch? I think it could be really useful for some people. … (Basically, my university has a state of the art laser which is currently being used for nuclear research. My team is working with the Laser Lab to write code that can accurately simulate physics at similar conditions. And it’s going to be all open source and free to use so that other universities can do similar nuclear research without needing to have a massive building-sized laser at hand). I came in my freshman year with basically zero coding knowledge and a lot of experience in CAD modeling. I decided that I was going to focus on taking the outputs from the team’s simulations and make them easier to understand for people without physics or C.S. degrees by rendering them as points in 3D space. Through that path, I finally came across Blender and then your addon.”

Her generous contributions to the codebase in the form of the Jarvis Parser™ * addresses that issue by neatly converting said data into Blender Attributes.

*(Not actually trademarked, but innovative enough I feel she deserves one :).

Results

(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

The_Gang

The_Gang-Render

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 .

Cycles Point Cloud Render

The 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

31-Notes

Compatibility

  • If your PLY won't work, contact me and we'll figure out why.

  • Best results will be had with Blender 3.1 or later (4.0 is verified).

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

    Compatibility-sm

Installation

  1. Download the Import_PLY_as_Verts-3.zip file from the repo.
  2. Unzip the file.
  3. Do NOT unzip the PLY_As_Verts.zip file. That is the actual Addon.
  4. (Optional) Read The_Manual. It's quite good :)
  5. Open Blender. If using 3.6 or lower, disable the legacy PLY i/o modules:

image3

And if necessary, remove old versions of the Addon:

Cap-0028

  1. Install the new Addon. Make sure the checkbox is ticked.

Cap-0031

Usage

File->Import will now look like this:

File_Screenshot

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

image6

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.

As your model is importing, statistics about it will be sent to Blender's Console Window.

Cap-0035

However, said Console Window is not trivial to get to for non-Windows users.

As a remedy the Addon generates a text file inside of Blender's Text Editor.

Cap-0036

Once your model has loaded, two common workflows are:

A) Cycles Point Cloud Render

In the Geometry Nodes Editor, create a new nodetree. Add-> Mesh-> Operations-> Mesh to Points makes the cloud renderable (although NOT in Viewport Mode).

image Cap-0039-B

Geometry, but no color.

In order to connect the imported Vertex Colors, first create a new Material.

Go to Add-> Input-> Attributes-> Col and connect the Node. Name the Material something meaningful.

Cap-0038

Switch back to Geometry Nodes and Add-> Material-> Set Material.

Plug in the meaningful name you just bestowed upon the Material.

Cap-0039

image17

MUCH better :)

More details are covered in The_Manual.

B) Instancing

Another approach to visualization is to attach actual geometry to the points in the cloud. This allows great flexibility at the cost of higher memory use. However, unlike the Cycles workflow we just looked at, these do work in Viewport Render.

With this in mind, here is a basic Instancing setup:

In a new Geometry Nodes block, Add-> Instances-> Instance on Points

image

Nothing immediately happens because we have to supply some input geometry.

Add-> Mesh-> Primitives-> Cube and connect.

image image

The scale is usually off at the beginning, we'll fine-tune in a moment.

We see now we have 19.6K copies of the Cube as Instances.

image

Instances tend to bog down as the geometry increases.

To speed things up, add a Realize Instances node. Also drop the Size of our cube object to 0.02 meters.

image image

If you haven't already made a custom Material as discussed in the previous section, go ahead and do so.

When it's done, drop a Set Material node right after Realize Instances and name it.

image24 image25 image26

That is very attractive data.

This and other topics are covered in greater detail in The_Manual.

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 legacy 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 with Attributes (if present)

  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 still be improved. The worst bottleneck is loading Blender's data structures. This is under investigation.
  • Exporting Blender objects as verts is not yet supported. Not a huge priority but will be addressed.

Tutorials

Note: These are a bit dated but essentially the same. Newer videos are in the works.

  1. Mandelbulb3D - BTracer2 Workflow Basic
  2. Cycles 3.1 Point Cloud Render
  3. World Blender Meetup Day 2022 Presentation

Blog and Ephemera

ThePLYGuy Blog

Our YouTube Channel

BlenderArtists Article 8-13-2023