Cloning Prims#

Note

Python uses ovstage cloning. Renderer.clone_usd* and ovrtx_clone_usd() are deprecated compatibility APIs. Refer to skills/update-0_3-0_4-python/SKILL.md. Ovstage cloning differs from the compatibility API:

  • An ordinal is assigned to the clone operation for change tracking.

  • The _usd suffix is dropped from clone destination paths.

  • A missing source prim returns OVSTAGE_ERROR_NOT_FOUND rather than a generic error.

Refer to ovstage Integration for the attached-stage workflow.

Cloning copies a USD subtree already present on the runtime stage to a new prim path. Use it for making additional copies of loaded geometry, sensors, or other stage content without re-authoring the original USD.

Clone destinations must be new absolute prim paths. If the cloned subtree contains relationships, make sure the copied content still points at the desired targets after cloning.

Clone a Subtree#

stage.clone("/World/Plane", ["/World/PlaneCloneA", "/World/PlaneCloneB"], ordinal=2)
stage.advance_write_floor(2, ovstage.Scope.ALL).wait()

ovx_string_t source = ovx_str("/World/Plane");
ovx_string_t targets[] = {
    ovx_str("/World/PlaneCloneA"),
    ovx_str("/World/PlaneCloneB"),
};

ovstage_enqueue_result_t eq = ovstage_clone(stage_, source, targets, 2, /*ordinal=*/2);
ASSERT_EQ(eq.status, OVSTAGE_OK) << format_ovstage_last_error();
docs_wait_ovstage_no_errors(stage_, eq.op_index);
docs_ovstage_advance_write_floor(stage_, 2);

Async Cloning#

op = stage.clone_async("/World/Plane", ["/World/PlaneCloneAsync"], ordinal=2)
op.wait()
stage.advance_write_floor(2, ovstage.Scope.ALL).wait()

Notes#

  • Clone loaded content, then use Writing Transforms to place each copy.

  • Use Stage Queries to discover source paths before cloning generated or externally supplied scenes.

  • Use Loading USD references when the content should remain removable by handle or when it has not yet been loaded onto the stage.