UsdUtilsFlattenLayerStack and add/append relationships

I have a question about UsdUtilsFlattenLayerStack and its behaviour with “add rel”.
The documentation for UsdUtilsFlattenLayerStack

A few historical scene description features cannot be flattened into a single opinion because they unfortunately encode operations that are not closed under composition. Specifically, the SdfListOp operations “add” and “reorder” cannot be flattened. Instead, “add” will be converted to “append”, and “reorder” will be discarded.

We’re finding that “add” is causing the relationship to be cleared, but “append” works fine, so we’re unclear what the documentation means.

This USD file demonstrates the issue:

#usda 1.0 

def Scope "A" { }
def Scope "B" { add rel test = </A> }

If I run this Python code:

from pxr import Usd, UsdUtils
stage = Usd.Stage.Open('test.usda')
flat = UsdUtils.FlattenLayerStack(stage)
stage = Usd.Stage.Open(flat.identifier)
print(stage.ExportToString())

The result is that the test relationship ends up empty. If I change “add” to “append” in the USD, the relationship ends up with the original value.

Is this expected behaviour for UsdUtilsFlattenLayerStack, and if so, could the documentation be made clearer?

We came across this problem with the PointInstancedMedCity example, which sets its prototypes with “add rel =”.

Hi Jerry – unfortunately, it looks like the flattening code wasn’t handling that case properly, but we’ll have a fix in the next release.

Also, given that authoring of “add” and “reorder” statements was deprecated between USD releases 0.8.3 and 19.07, we should update the City Set (and any other example assets) to reflect that…

Ah, you may just need to download a newer version of the City Set example. The version below was updated 2022-7-21 to replace “add” operations with “prepend”:

https://openusd.org/release/dl_downloads.html

Thanks for that. It’s good to know it’s a bug and we weren’t doing anything wrong (apart from having an old version of the City set).