Implement a PLY importer/exporter in C++ #101294

New Issue

The problem

There is an importer/exporter for PLY already implemented in Blender, but it is implemented in Python which means it is slow for bigger files. The importer is also missing support for point cloud PLY files with vertex colors. Since PLY is often used for laser scan data (which are big files that contain a point cloud and sometimes vertex colors) it would be a shame not to address these issues.

The idea

We are a group of software engineering students from the university of applied sciences Windesheim in the Netherlands. And we would like to rewrite the current Python based importer/exporter to C++, with a focus on performance, extendibility and implementing missing functionality.

Requirements

Importer

Vertex data
Face data
Edge data
Vertex colors
Vertex normals
UV data

Exporter

Vertex data
Face data
Edge data
Vertex colors
Vertex normals
UV data
Triangulation

Nonfunctional requirements

The C++ based importer/exporter should be 5x faster than the current Python based implementation.
The behavior and results of current python add-on should be matched as closely as possible. Divergences, if any, should be clearly justified and documented.

Priorities

Our main focus will be implementing a fully featured importer, since we feel that will benefit Blender users the most. But having the importer in C++, and the exporter in Python is not optimal So we will split the development team into two parts, so we can work on the importer and exporter in parallel.

Possible additions

The PLY file format supports user-defined properties; we could make use of this fact by exposing these properties to geometry nodes as attributes. This would allow us to generically support all user defined properties (which we personally think is very cool). But some research needs to be done to see if this is practical and able to be implemented.

Scope

Since this is a student project, we have a definite deadline (20th of January). And after that deadline we won’t be able to work on the importer/exporter as much, if at all. @aras_p is willing to maintain the code after the project ends (if we send him some cookies), so we will be counting on him.

Testing strategy

For this project we are planning on utilizing test driven development. Detailed unit tests will be written for a large part of the added code. We will also gather a large amount of PLY files from different sources, to keep track of which files get loaded correctly. Both fine grain and coarse grain tests will be written.

If there is functionality missing in this design, or if you have other feedback. Please let us know.

## The problem There is an importer/exporter for PLY already implemented in Blender, but it is implemented in Python which means it is slow for bigger files. The importer is also missing support for point cloud PLY files with vertex colors. Since PLY is often used for laser scan data (which are big files that contain a point cloud and sometimes vertex colors) it would be a shame not to address these issues. ## The idea We are a group of software engineering students from the university of applied sciences Windesheim in the Netherlands. And we would like to rewrite the current Python based importer/exporter to C++, with a focus on performance, extendibility and implementing missing functionality. - - - ## Requirements **Importer** - Vertex data - Face data - Edge data - Vertex colors - Vertex normals - UV data **Exporter** - Vertex data - Face data - Edge data - Vertex colors - Vertex normals - UV data - Triangulation **Nonfunctional requirements** - The C++ based importer/exporter should be 5x faster than the current Python based implementation. - The behavior and results of current python add-on should be matched as closely as possible. Divergences, if any, should be clearly justified and documented. ## Priorities Our main focus will be implementing a fully featured importer, since we feel that will benefit Blender users the most. But having the importer in C++, and the exporter in Python is not optimal So we will split the development team into two parts, so we can work on the importer and exporter in parallel. ## Possible additions The PLY file format supports user-defined properties; we could make use of this fact by exposing these properties to geometry nodes as attributes. This would allow us to generically support all user defined properties (which we personally think is very cool). But some research needs to be done to see if this is practical and able to be implemented. ## Scope Since this is a student project, we have a definite deadline (20th of January). And after that deadline we won’t be able to work on the importer/exporter as much, if at all. @aras_p is willing to maintain the code after the project ends (if we send him some cookies), so we will be counting on him. ## Testing strategy For this project we are planning on utilizing test driven development. Detailed unit tests will be written for a large part of the added code. We will also gather a large amount of PLY files from different sources, to keep track of which files get loaded correctly. Both fine grain and coarse grain tests will be written. If there is functionality missing in this design, or if you have other feedback. Please let us know.

Added subscribers: @aras_p, @super_jo_nathan

Looks good! Questions I have:

"should be faster" -- by how much? e.g. I'd imagine if it's 20% faster, then it's not worth replacing the current (Python) one with the C++ one. If it's 2x faster, then it's an open question. If it's 10x faster, then it's a "yes, replace of course".
"utilizing test driven development" -- to what extent and at what granularity? Would it be more like "unit testing" (testing individual pieces of the importer/exporter), or more like "functionality testing", perhaps based on exporting some .blend files and comparing result to "golden" .stl results? The latter is what OBJ importer/exporter mostly uses, btw.
Do you plan to write the importer/exporter by first closely following the existing Python one, i.e. "first literally port it to C++", or do you plan to write the new one based on PLY spec only? The first approach has an advantage that you'd likely find various "under-specified bits" or gotchas that the existing Python code had to work around with. My experience with OBJ C++ rewrite is that because it was "written from scratch", it had to re-discover 10 or 20 various issues that were handled by Python code, but are not there in any official OBJ spec.

Looks good! Questions I have: - "should be faster" -- by how much? e.g. I'd imagine if it's 20% faster, then it's not worth replacing the current (Python) one with the C++ one. If it's 2x faster, then it's an open question. If it's 10x faster, then it's a "yes, replace of course". - "utilizing test driven development" -- to what extent and at what granularity? Would it be more like "unit testing" (testing individual pieces of the importer/exporter), or more like "functionality testing", perhaps based on exporting some .blend files and comparing result to "golden" .stl results? The latter is what OBJ importer/exporter mostly uses, btw. - Do you plan to write the importer/exporter by first closely following the existing Python one, i.e. "first literally port it to C++", or do you plan to write the new one based on PLY spec only? The first approach has an advantage that you'd likely find various "under-specified bits" or gotchas that the existing Python code had to work around with. My experience with OBJ C++ rewrite is that because it was "written from scratch", it had to re-discover 10 or 20 various issues that were handled by Python code, but are not there in any official OBJ spec.

Thank you for your feedback! We have discussed your questions within our team.

After looking at the initial implementation D3114: Move STL import/export to C++ (WIP) and the current implementation D14941: Native STL Importer of the C++ based STL importer/exporter. We think that a 5x speed increase can be expected at least, so we will set that as a requirement.
We would like to implement both fine grain testing of individual pieces of code, and functionality testing of the importer/exporter as a whole. With functionality testing you can only see when the importer/exporter is broken or functional. But you can’t see where the fault is located if there is one. We hope to decrease time spent debugging for us and future developers by writing fine grain tests.
Our plan is to read through the current Python based implementation first, to deeply understand what it is doing. Using that information and the information given by the specs we will design the C++ based implementation. So, to answer your question: a combination of both.

Thank you for your feedback! We have discussed your questions within our team. - After looking at the initial implementation [D3114: Move STL import/export to C++ (WIP)](https://archive.blender.org/developer/D3114) and the current implementation [D14941: Native STL Importer](https://archive.blender.org/developer/D14941) of the C++ based STL importer/exporter. We think that a 5x speed increase can be expected at least, so we will set that as a requirement. - We would like to implement both fine grain testing of individual pieces of code, and functionality testing of the importer/exporter as a whole. With functionality testing you can only see when the importer/exporter is broken or functional. But you can’t see where the fault is located if there is one. We hope to decrease time spent debugging for us and future developers by writing fine grain tests. - Our plan is to read through the current Python based implementation first, to deeply understand what it is doing. Using that information and the information given by the specs we will design the C++ based implementation. So, to answer your question: a combination of both.

Added subscriber: @GeorgiaPacific

Added subscriber: @Arjan-van-Diest

Added subscriber: @MichaelAProstka

Possible thing to also keep in mind: this abandoned Python patch, that's meant for improving PLY import support for some software that produces "slightly odd" file syntax. https://developer.blender.org/D14718

Added subscriber: @mont29

Project looks good to me, I would just add to the requirements something like "Match as closely as possible the behavior and results of current python add-on. Divergences, if any, should be clearly justified and documented."

Working on the importer first makes sense, but I would strongly recommend also considering the exporter as mandatory for this project. Would really rather not have a situation where we have a fully finished working importer in C++, and exporter still in python add-on.

Project looks good to me, I would just add to the requirements something like "Match as closely as possible the behavior and results of current python add-on. Divergences, if any, should be clearly justified and documented." Working on the importer first makes sense, but I would strongly recommend also considering the exporter as mandatory for this project. Would really rather not have a situation where we have a fully finished working importer in C++, and exporter still in python add-on.

Added subscriber: @KeirCB

Very excited for this,
In the possible additions section you discuss other attributes.
In point clouds generated with photogrammetry you generate the normals of the points. This is incredibly useful for mesh generation and is for me an integral attribute, I hope this can make it into the final release.

Very excited for this, In the possible additions section you discuss other attributes. In point clouds generated with photogrammetry you generate the normals of the points. This is incredibly useful for mesh generation and is for me an integral attribute, I hope this can make it into the final release.

Added subscriber: @Lilith-Houtjes

In #101294#1428606, @aras_p wrote:
Possible thing to also keep in mind: this abandoned Python patch, that's meant for improving PLY import support for some software that produces "slightly odd" file syntax. https://developer.blender.org/D14718

@MichaelAProstka contacted us and gave some helpful pointers about what the current importer struggles with. So we are definitely keeping this in mind!

> In #101294#1428606, @aras_p wrote: > Possible thing to also keep in mind: this abandoned Python patch, that's meant for improving PLY import support for some software that produces "slightly odd" file syntax. https://developer.blender.org/D14718 @MichaelAProstka contacted us and gave some helpful pointers about what the current importer struggles with. So we are definitely keeping this in mind!

In #101294#1429084, @mont29 wrote:
Project looks good to me, I would just add to the requirements something like "Match as closely as possible the behavior and results of current python add-on. Divergences, if any, should be clearly justified and documented."

Thanks for the feedback! Where should these divergences be documented?

Working on the importer first makes sense, but I would strongly recommend also considering the exporter as mandatory for this project. Would really rather not have a situation where we have a fully finished working importer in C++, and exporter still in python add-on.

We will set the exporter as part of the minimum viable product.

> In #101294#1429084, @mont29 wrote: > Project looks good to me, I would just add to the requirements something like "Match as closely as possible the behavior and results of current python add-on. Divergences, if any, should be clearly justified and documented." Thanks for the feedback! Where should these divergences be documented? > Working on the importer first makes sense, but I would strongly recommend also considering the exporter as mandatory for this project. Would really rather not have a situation where we have a fully finished working importer in C++, and exporter still in python add-on. We will set the exporter as part of the minimum viable product.

In #101294#1429823, @KeirCB wrote:
Very excited for this,
In the possible additions section you discuss other attributes.
In point clouds generated with photogrammetry you generate the normals of the points. This is incredibly useful for mesh generation and is for me an integral attribute, I hope this can make it into the final release.

Thanks for the feedback! We will try our best to support this. But we are sadly not able to guarantee this functionality.

> In #101294#1429823, @KeirCB wrote: > Very excited for this, > In the possible additions section you discuss other attributes. > In point clouds generated with photogrammetry you generate the normals of the points. This is incredibly useful for mesh generation and is for me an integral attribute, I hope this can make it into the final release. Thanks for the feedback! We will try our best to support this. But we are sadly not able to guarantee this functionality.

In #101294#1430140, @super_jo_nathan wrote:

In #101294#1429084, @mont29 wrote:
Project looks good to me, I would just add to the requirements something like "Match as closely as possible the behavior and results of current python add-on. Divergences, if any, should be clearly justified and documented."

Thanks for the feedback! Where should these divergences be documented?

In the design task first, then in the release notes once pushed to master.

> In #101294#1430140, @super_jo_nathan wrote: >> In #101294#1429084, @mont29 wrote: >> Project looks good to me, I would just add to the requirements something like "Match as closely as possible the behavior and results of current python add-on. Divergences, if any, should be clearly justified and documented." > > Thanks for the feedback! Where should these divergences be documented? In the design task first, then in the release notes once pushed to master.

Added subscriber: @T.R.O.Nunes

Added subscriber: @softyoda

Added subscriber: @Yoran-Huzen

Added subscriber: @bashendriks10

The project got done, reviewed, feedback addressed and just landed to main branch for Blender 3.6 (43e9c90061).

The project got done, reviewed, feedback addressed and just landed to main branch for Blender 3.6 (43e9c90061fc1eb).

~~Please remember to update the release notes. ;)~~

Yikes please ignore, as @super_jo_nathan reminded me, this is for 3.6, not 3.5!

~~Please remember to update the [release notes](https://wiki.blender.org/wiki/Reference/Release_Notes/3.5/Pipeline_Assets_IO). ;)~~ Yikes please ignore, as @super_jo_nathan reminded me, this is for 3.6, not 3.5!

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Implement a PLY importer/exporter in C++ #101294