PLYLoader: Allow custom attributes.

[alankalb]

Related discussion: https://discourse.threejs.org/t/dracoloader-how-to-read-custom-attributes/14785

Description

When creating a .ply file, it is possible to add custom element properties that do not map to the default buffer attributes for position, normal, uv and color that are included in the PLYLoader. This adds the ability to map custom element properties to a new buffer attribute.

A new property, customPropertyMapping was added to PLYLoader and can be set via the method setCustomPropertyNameMapping. The name of the new buffer attribute is added as the object key and the element properties are added as the object value as a list. For example, the following will map the element properties custom_property_a and custom_property_b to the attribute customAttribute:

loader.setCustomPropertyMapping( {
  customAttribute: ['custom_property_a', 'custom_property_b'],
} );

The function handleElement within the parse method will find the value for each custom property in an element and push it to its corresponding customAttribute within the temporary buffer created in the parseASCII or parseBinary functions. postProcess will then set a new Float32BufferAttribute attribute on the geometry. The number of element properties in the properties list is used to set the item size of the attribute. From the example above the resulting geometry will have a customAttribute buffer attribute with an item size of 2.

This was tested with a .ply file with the following element properties:

0: {type: 'double', name: 'x'}
1: {type: 'double', name: 'y'}
2: {type: 'double', name: 'z'}
3: {type: 'double', name: 'signed_distance'}

The signed_distance property was mapped to the attribute signedDistance using:

loader.setCustomPropertyMapping( {
  signedDistance: ['signed_distance'],
} );

Parsing the file resulted in a geometry with the following attributes:

{
   position: {
      array: [...],
      itemSize: 3,
      ...
   },
   signedDistance: {
     array: [...],
     itemSize: 1,
     ...
  }
}

[Mugen87]

Is there any popular PLY exporter that supports custom attributes? Do you create the PLY file with a tool or custom code? Do you mind sharing such a PLY file in this issue?

Adding support for custom attribute names was important since PLY does not clearly specify the names of common attributes. However, adding support for uncommon, custom attributes is a bit more special.

[alankalb]

@Mugen87 happly is a common exporter that allows for custom element properties. From happly:

Although the .ply format is commonly used to store 3D mesh and point cloud data, the format itself technically has nothing to do with meshes or point clouds; it simply specifies a collection elements, and data (called properties) associated with those elements. For instance in a mesh, the elements are vertices and faces; vertices then have properties like "position" and "color", while faces have a property which is a list of vertex indices. hapPLY exposes a general API for reading and writing elements and properties, as well as special-purpose helpers for the common conventions surrounding mesh data.

I am using happly at Lumafield to generate .ply files with a signed_distance property. This property represents a deviation between points on two meshes after a comparison. We have a custom vert shader that uses the signed distance values to derive vertex color values using a linear color map. Below is an example of the final render:

[Mugen87]

Thanks for sharing the additional information! I agree that it makes sense in context of PLY to allow custom attributes. It's definitely better than supporting properties like signed_distance explicitly since the final property set might vary from app to app.