Usage Examples

An intuitive collection dialog will appear when call following api function, allowing you to customize the collection by selecting the appropriate configuration options.

These options include: USD Only: Only collect USD files and other other dependencies are ignored (like material files and textures.) if it enabled.

Material Only: If this options is enabled, it will only collect all material related dependencies including textures, and USD files will be ignored.

Flat Collection: By default, it will collect USD project by keeping the directory structure. If this option is enabled, the directory structure will not be kept and all dependencies will be put into specified folders.

Flat Collection Texture Options: When collecting in Flat mode, users can specify the grouping for texture files via this option; Currently there are 3 available options:

Options	Description
Group by MDL	Textures will be grouped by their parent MDL file name.
Group by USD	Textures will be grouped by their parent USD file name.
Flat	All textures will be collected under the same hierarchy under “textures” folder. Note that there might be potential danger of textures overwriting each other, if they have the same names but belong to different assets/mdls.

Collect signle USD file

from omni.kit.tool.collect import get_instance

# Initialize Collect Extension
collect_extension = get_instance()
collect_extension.collect("your_usd_path.usd")

Collect Multiple USD Files

from omni.kit.tool.collect import get_instance

# Initialize Collect Extension
collect_extension = get_instance()
collect_extension.collect_multiple(["path_to_first_usd.usd", "path_to_second_usd.usd"], "your_folder_name")

Collect USD files in Folder

from omni.kit.tool.collect import get_instance

# Initialize Collect Extension and Collect USD files in Folder
collect_extension = get_instance()
collect_extension.collect_multiple_in_folder("your_folder_path")

Export Selected With Dependencies

collect_selection slices selected prim subtrees out of a stage without touching the source. Each selection is written to its own subfolder of target_folder as a self-contained USD: the subtree with its hierarchy intact (it is not merged down to a single mesh), whatever it depends on that lives elsewhere in the stage, and every referenced texture, with asset paths rewritten to be relative. The same operation is available from the Stage panel by right-clicking a selection and choosing Export Selected With Dependencies.

Dependencies are relocated under the default prim of the exported layer and everything pointing at them is repointed, so the result keeps its look both when opened on its own and when referenced into another stage. Bound materials, UsdSkel skeletons and animations, PointInstancer prototypes, proxy prims and the prototypes behind instanceable prims are followed, transitively; instancing is preserved rather than expanded. Anything the selection still points at outside the exported asset is reported as a warning in the log.

from omni.kit.tool.collect import collect_selection

# Slice two rooms out of a large master stage into ./chunks/Wing and ./chunks/Lobby.
roots = await collect_selection(stage, ["/World/Wing", "/World/Lobby"], "file:/path/to/chunks")

The returned list holds the root USD of every selection that was exported successfully. A material_only run writes no USD, so it returns each selection’s collection folder instead.

Options mirror the whole-stage collect dialog. flat_collection is enabled by default, which puts each selection into one USD plus a textures folder; disable it to mirror the source directory structure instead.

from omni.kit.tool.collect import collect_selection
from omni.kit.usd.collect import FlatCollectionTextureOptions

roots = await collect_selection(
    stage,
    ["/World/Wing"],
    "file:/path/to/chunks",
    flat_collection=True,
    texture_option=FlatCollectionTextureOptions.BY_MDL,
)

Long-running exports can report progress and be cancelled:

from omni.kit.tool.collect import CollectSelectionCancelToken, collect_selection

cancel_token = CollectSelectionCancelToken()
roots = await collect_selection(
    stage,
    prim_paths,
    target_folder,
    on_progress=lambda completed, total, name: print(f"{completed}/{total} {name}"),
    cancel_token=cancel_token,
)
# cancel_token.cancel() from elsewhere stops the run.