Skip to content

Add Relocates lesson to Creating Composition Arcs - #102

Open
dillonbbailey wants to merge 2 commits into
NVIDIA-Omniverse:mainfrom
dillonbbailey:add-relocates-unit
Open

dillonbbailey wants to merge 2 commits into
NVIDIA-Omniverse:mainfrom
dillonbbailey:add-relocates-unit

Conversation

@dillonbbailey

Copy link
Copy Markdown
Contributor

Summary

Adds the Relocates lesson that issue #5 asked for, and removes the placeholder admonition that promised it.

Relocates have been covered only by a note in _includes/LIVRPSvLIVERPS.md explaining that LIVRPS had become LIVERPS and that "Learn OpenUSD will be updated soon to cover relocates." This delivers that content and retires the note.

Fixes #5

What's here

New unit under creating-composition-arcs/relocates/, following the module's existing shape (index + what-are-* + working-with-*):

  • What Are Relocates? — the problem relocates solve, renaming in place, reparenting across the hierarchy, removal via an empty target path, and the two constraints that cause the most confusion.
  • Exercise: Working With Relocates — usdview walkthrough plus a Python exercise, matching how the rest of this module teaches (no executable {code-cell} blocks; this module uses downloadable exercise content).

Exercise content under exercise_content/composition_arcs/relocates/: a rename example, a reparent example, and starter + solution scripts. These are picked up automatically by the generated composition-arcs-exercise-files.zip.

Supporting updates: a Relocates section in Composition Basics strength ordering, relocates added to the LIVERPS ordering list in what-is-liverps, and the LIVRPSvLIVERPS include deleted along with its four include sites. A second commit normalizes the remaining bare LIVRPS spellings now that the acronym is no longer in transition.

Verification

Behaviour described in the lesson was checked against usd-core 25.11 rather than written from memory. Three things that changed the content as a result:

  • Reparenting a referenced child into a sibling subtree is legal. I expected USD to reject it; it doesn't, so it's documented as a supported pattern.
  • Relocating a locally-defined prim silently drops it — no composition error, and localErrors is empty. That footgun is called out in a caution on both pages.
  • Authoring at a relocated-away source path does warn. The lesson quotes USD's actual message.

Also verified:

  • Every exercise file composes to exactly the prim set the lesson claims (4/4 automated checks).
  • Clean Sphinx build: warning set is byte-identical to main (195 vs 195, nothing added or removed).
  • Test suite matches main exactly (130 passed / 17 failed, with the 17 being a pre-existing local usd2gltf environment gap, not a regression).

Notes for reviewers

Attribution needs a decision. This builds on the detailed draft @Maalvi14 posted in issue #5 back in March — the structure and several passages derive from it, and the first commit credits them with a Co-Authored-By trailer. They have not signed off on a commit, and CONTRIBUTING.md requires sign-off on all contributions. Either @Maalvi14 signs off, or I rewrite the derived passages and move the credit to an acknowledgment here. Happy to do whichever maintainers prefer.

No images. Sibling lessons in this module lean heavily on diagrams and usdview screenshots; this unit is prose and code blocks only. The content stands alone, but it's visually plainer than its neighbours and would benefit from diagrams and screenshots before it ships.

🤖 Generated with Claude Code

dillonbbailey and others added 2 commits October 3, 2026 19:08
OpenUSD's relocates arc was covered only by a placeholder admonition
noting that LIVRPS had become LIVERPS and that content was coming soon.
This adds the lesson that admonition promised and removes it.

New unit under creating-composition-arcs/relocates covering what
relocates are, renaming in place, reparenting across the hierarchy,
removal via an empty target path, and the two constraints that cause
the most confusion: only prims introduced by a composition arc can be
relocated, and the source path stops being valid to author against.

Exercise content follows the module's usdview-driven pattern with a
simple rename example, a reparent example, and a Python exercise that
authors relocates as layer metadata.

Composition Basics strength ordering gains a Relocates section, and
what-is-liverps gains relocates in its ordering list. The acronym is
spelled LIVERPS in those two files because adding relocates to their
enumerations makes the old spelling wrong; the remaining unrelated
LIVRPS spellings are normalized separately.

Behaviour described in the lesson was verified against usd-core 25.11.

Fixes NVIDIA-Omniverse#5

Signed-off-by: Dillon Bailey <dillonb@nvidia.com>

Co-Authored-By: Manuel Villanueva <118570103+Maalvi14@users.noreply.github.com>
Co-Authored-By: Claude <noreply@anthropic.com>
With relocates now covered by its own lesson, the acronym is no longer
in transition and the two spellings should not appear interchangeably.

These files only mention the acronym in passing; none of them enumerate
the arcs, so this is a terminology change with no content impact. The
style guide is updated to name LIVERPS as the canonical spelling. The
glossary keeps LIVRPS under "Also Known As" so the older spelling
remains searchable.

Signed-off-by: Dillon Bailey <dillonb@nvidia.com>

Co-Authored-By: Claude <noreply@anthropic.com>
@Maalvi14

Maalvi14 commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Hi Dillon, thanks for getting this through! As for the sign-off, do you need just a confirmation through here, if not you could give me access to your fork so I add a commit with my sign-off in there

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Update to Include Relocates

2 participants