Fixing Paths For Moved Objects

If a prim or property is moved/renamed/reparented, and other objects in the composed stage use paths to the original prim or property (for example, via a relationship path, or composition arc), namespace editing will attempt to correct those paths to use the new path for the edited prim or property.

For example, if you had a prim with a relationship to another prim:

def "groupA" ()
{
    custom rel charA = </asset/charA>
}

And you moved /asset/charA to /oldAssets/reviewed/charA:

editor.MovePrimAtPath("/asset/charA","/oldAssets/reviewed/charA")

The relationship property in primA would be automatically updated in the composed stage to /oldAssets/reviewed/charA:

def "groupA" ()
{
    custom rel charA = </oldAssets/reviewed/charA>
}

Places where paths are used that will get fixed currently include:

• Relationship targets

• Attribute connections

Namespace editing will support fixing paths used in other areas (e.g. path expressions for pattern based collections) in future updates.

Note that fixes for edits that delete or move a prim or property that is introduced across a composition arc (like a reference) may have undesired consequences for other objects using an arc to the edited prim or property. For example, if you had a prim /asset that was referenced by two other prims, /Shot1/shotAsset and /Shot2/shotAsset:

def "asset" ()
{
    def "assetChild" ()
    {
    }
}

def "Shot1" ()
{
    def "shotAsset" (
        prepend references = </asset>
    )
    {
    }
}

def "Shot2" ()
{
    def "shotAsset" (
        prepend references = </asset>
    )
    {
    }
}

Any edits to /asset will be reflected in both /Shot1/shotAsset and /Shot2/shotAsset:

editor.MovePrimAtPath("/asset/assetChild", "/asset/assetUpdatedForShot1")

With the flattened results looking like:

def "asset" ()
{
    def "assetUpdatedForShot1" ()
    {
    }
}

def "Shot1" ()
{
    def "shotAsset" (
    )
    {
        def "assetUpdatedForShot1" ()
        {
        }
    }
}

def "Shot2" ()
{
    def "shotAsset" (
    )
    {
        def "assetUpdatedForShot1" ()
        {
        }
    }
}

Batch Edits

UsdNamespaceEditor provides the ability to create a sequence of edit operations and execute them as a batch. Each edit operation you call will be added to a queue and the queue will be executed (and cleared) when you call UsdNamespaceEditor.ApplyEdits().

# Start a batch of edits to remove deprecated assets and mark other
# assets as now deprecated
editor.DeletePrimAtPath("/oldAssets/deprecated/protoModel")
editor.MovePrimAtPath("/currentAssets/model1", "/oldAssets/model1")
...other additional related edits...
batchApplyResult = editor.ApplyEdits()  # Apply this batch of edits

The batch is validated before applying, so if any of the edit operations would fail, none of the batch is actually applied, and ApplyEdits() will return false. If you want to sanity-check whether your edits can successfully be applied to the stage, use UsdNamespaceEditor.CanApplyEdits(). This will verify any queued edits and return true if the edits can be applied to the current stage, and false otherwise.

canApply = editor.CanApplyEdits()
if canApply:
    editor.ApplyEdits()

Executing batches of edits will usually be more efficient than applying each edit individually. USD will process the list of edits in a batch to determine the most efficient way to apply them.

Use CanApplyEdits() To Validate Edit Operations

When you call edit operations, operation parameters like paths are sanity-checked, but the operation itself is not applied until you call ApplyEdits(). If you want to confirm if your operation can be applied, use CanApplyEdits() before calling ApplyEdits(). CanApplyEdits() will return an annotated bool that evaluates to True if the edits can be applied, and False if the edits cannot be applied, with the return result including a whyNot attribute with further details.

For example, you might have a delete operation that uses a path to a prim that unbeknownst to you does not exist in the current stage. The DeletePrimAtPath call will succeed as the provided path is a valid Sdf path, however both CanApplyEdits() and ApplyEdits() will fail indicating the path does not resolve to a valid prim.

editor.DeletePrimAtPath("/primDoesNotExist")
# Check first if we can delete /primDoesNotExist
canApplyResult = editor.CanApplyEdits()
if canApplyResult:
    editor.ApplyEdits()
else:
    # Handle error, using canApplyResult.whyNot as needed, etc.

Built-In Properties From Schemas Are Not Editable

The namespace editor does not allow deleting or moving built-in properties. For example, if you had a UsdGeomSphere with an authored opinion for the radius attribute:

def Sphere "testSphere" (
)
{
    custom string customProp = "custom property"

    # UsdGeomSphere schema radius attribute
    double radius = 2
}

You could edit the customProp attribute, but editing radius would fail.

editor.DeletePropertyAtPath("/testSphere/customProp")  # This is allowed
editor.DeletePropertyAtPath("/testSphere/radius")  # This is not allowed and will cause an error