USD Scene Graph Instancing Export Design #126470

New Issue

Michael Kowalski · 2024-08-18T21:53:00+02:00

Michael Kowalski commented

2024-08-18 21:53:00 +02:00

This document is to motivate discussion of strategies for extending the USD exporter to support instancing.

The USD exporter currently provides an experimental "instancing" option which was originally implemented by Sybren. This feature is very useful and powerful, but has certain limitations which I will describe below.

I propose that as a first step we extend the current "instancing" feature implementation to support true USD scene graph instancing, and this will be the main focus of this document. I believe it will be possible to extend the implementation further in a subsequent step to support exporting USD point instancers, and this will be briefly mentioned at the end.

Current Instancing Implementation

Sybren's orginal implementation provides a very elegant solution to allow sharing of mesh data for instanced objects. The strategy is to export the shared mesh data of the instanced Blender objects as internal references to one "original" mesh prim in the USD.

For example, if we have a collection containing a "Plane" mesh object which is instanced twice in Blender, as in the attached instanced_collection.blend, the exported USDA instanced_collection_current.usda (simplified) might look like this:

def Xform "root" 
{
    def Xform "Plane"
    {
        def Mesh "Plane" 
        {
           # Full mesh definition here
        }
    }

    def Xform "Plane_001"
    {
        # Instance transform here
    
        def Xform "Plane_0"
        {
            def Mesh "Plane" (
                prepend references = </Plane/Plane>
            )
            {
            }
        }
    }
    
    def Xform "Plane_002"
    {
        # Instance transform here
    
        def Xform "Plane_0"
        {
            def Mesh "Plane" (
                prepend references = </Plane/Plane>
            )
            {
            }
        }
    }
}

In this case meshes /root/Plane_001/Plane_0/Plane and /root/Plane_002/Plane_0/Plane have internal references to the full mesh definition in /root/Plane/Plane (the "original"), so the mesh is defined just once in the USD instead of three time. This feature can greatly reduce the size of the USD file on disk and speed up IO times significantly.

However, this strategy does not support true scene graph instancing as specified in the documentation and has the following limitations:

Each of the referenced mesh prims are composed into the scene as individual copies, so we don't necessarily get the runtime memory savings of instancing.
The current approach can only reference mesh prims and not prim hierarchies

Proposed Implementation

The following changes are proposed to fully support instancing:

Instanced objects in Blender should be exported as Xforms that are marked "instanceable".
The instance Xforms should reference the Xform parent of the original prototype (not the mesh prim itself).
The instance Xforms should have no children.

For example, the exported USDA with these changes would resemble the following (see the attached instanced_collection_proposed.usda):

def Xform "root"
{
    def Xform "Plane"
    {
        def Mesh "Plane" 
        {
            # Actual mesh data here
        }
    }

    def Xform "Plane_001"
    {
       # Instance transform here

        def Xform "Plane_0" (
            instanceable = true
            prepend references = </root/Plane>
        )
        {
        }
    }
    
    def Xform "Plane_002"
    {
        # Instance transform here

        def Xform "Plane_0" (
            instanceable = true
            prepend references = </root/Plane>
        )
        {
        }
    }
}

The primary changes in the code would include:

Modify AbstractHierarchyIterator::make_writers() to allow subclasses to optionally skip writing an object's data or an object's children in the hierarchy. This is needed because instances must be written as Xforms without data or children, as noted above.
Remove the logic that calls to mark_as_instance() from USDGenericMeshWriter::write_mesh(), because we will no longer be exporting meshes as references.
Add logic to USDTransformWriter::do_write() to mark the Xform as instanceable and to add the reference to the prototype when the exported object is an instance.

In addition, material export would need to be modified for prototypes to ensure the material is defined in the subtree of the prototype. For example, for prototype /root/Plane, the material might need to be written to /root/Plane/_materials instead of /root/_materials.

Point Instancing

As future work, additional logic could be added to support writing point instancers, but I haven't worked out the details for this. One approach could be to identify instanced objects whose duplicator is a point cloud and handle those with a new type of writer which would write the object's transform and prototype index to a point instancer prim.

This document is to motivate discussion of strategies for extending the USD exporter to support instancing. The USD exporter currently provides an experimental "instancing" option which was originally implemented by Sybren. This feature is very useful and powerful, but has certain limitations which I will describe below. I propose that as a first step we extend the current "instancing" feature implementation to support true USD scene graph instancing, and this will be the main focus of this document. I believe it will be possible to extend the implementation further in a subsequent step to support exporting USD point instancers, and this will be briefly mentioned at the end. ## Current Instancing Implementation Sybren's orginal implementation provides a very elegant solution to allow sharing of mesh data for instanced objects. The strategy is to export the shared mesh data of the instanced Blender objects as internal references to one "original" mesh prim in the USD. For example, if we have a collection containing a "Plane" mesh object which is instanced twice in Blender, as in the attached `instanced_collection.blend`, the exported USDA `instanced_collection_current.usda` (simplified) might look like this: ``` def Xform "root" { def Xform "Plane" { def Mesh "Plane" { # Full mesh definition here } } def Xform "Plane_001" { # Instance transform here def Xform "Plane_0" { def Mesh "Plane" ( prepend references = </Plane/Plane> ) { } } } def Xform "Plane_002" { # Instance transform here def Xform "Plane_0" { def Mesh "Plane" ( prepend references = </Plane/Plane> ) { } } } } ``` In this case meshes `/root/Plane_001/Plane_0/Plane` and `/root/Plane_002/Plane_0/Plane` have internal references to the full mesh definition in `/root/Plane/Plane` (the "original"), so the mesh is defined just once in the USD instead of three time. This feature can greatly reduce the size of the USD file on disk and speed up IO times significantly. However, this strategy does not support true scene graph instancing as specified in the [documentation](https://openusd.org/release/api/_usd__page__scenegraph_instancing.html) and has the following limitations: - Each of the referenced mesh prims are composed into the scene as individual copies, so we don't necessarily get the runtime memory savings of instancing. - The current approach can only reference mesh prims and not prim hierarchies ## Proposed Implementation The following changes are proposed to fully support instancing: - Instanced objects in Blender should be exported as Xforms that are marked "instanceable". - The instance Xforms should reference the Xform parent of the original prototype (not the mesh prim itself). - The instance Xforms should have no children. For example, the exported USDA with these changes would resemble the following (see the attached `instanced_collection_proposed.usda`): ``` def Xform "root" { def Xform "Plane" { def Mesh "Plane" { # Actual mesh data here } } def Xform "Plane_001" { # Instance transform here def Xform "Plane_0" ( instanceable = true prepend references = </root/Plane> ) { } } def Xform "Plane_002" { # Instance transform here def Xform "Plane_0" ( instanceable = true prepend references = </root/Plane> ) { } } } ``` The primary changes in the code would include: - Modify `AbstractHierarchyIterator::make_writers()` to allow subclasses to optionally skip writing an object's data or an object's children in the hierarchy. This is needed because instances must be written as Xforms without data or children, as noted above. - Remove the logic that calls to `mark_as_instance()` from `USDGenericMeshWriter::write_mesh()`, because we will no longer be exporting meshes as references. - Add logic to `USDTransformWriter::do_write()` to mark the Xform as instanceable and to add the reference to the prototype when the exported object is an instance. In addition, material export would need to be modified for prototypes to ensure the material is defined in the subtree of the prototype. For example, for prototype `/root/Plane`, the material might need to be written to `/root/Plane/_materials` instead of `/root/_materials`. ## Point Instancing As future work, additional logic could be added to support writing point instancers, but I haven't worked out the details for this. One approach could be to identify instanced objects whose duplicator is a point cloud and handle those with a new type of writer which would write the object's transform and prototype index to a point instancer prim.

instanced_collection.blend

460 KiB

instanced_collection_proposed.usda

1.9 KiB

instanced_collection_current.usda

2.0 KiB

Michael Kowalski added the

Type

Design

label 2024-08-18 21:53:00 +02:00

Jesse Yurkovich added the