| Title: | 'OpenUSD' Scene Description Import and Export |
|---|---|
| Description: | Provides the 'OpenUSD' 'C++' library for reading, composing, and writing Universal Scene Description files <https://openusd.org/>. Exposes stage import and export through R functions and a registered native interface for rendering packages. |
| Authors: | Tyler Morgan-Wall [aut, cre] (ORCID: <https://orcid.org/0000-0002-3131-3814>), Pixar [aut, cph] (Bundled OpenUSD library) |
| Maintainer: | Tyler Morgan-Wall <[email protected]> |
| License: | file LICENSE |
| Version: | 26.8-0 |
| Built: | 2026-11-16 06:17:14 UTC |
| Source: | https://github.com/tylermorganwall/libopenusd |
Read prim custom data and selected properties through native OpenUSD queries. Values retain their numeric precision and array lengths.
usd_inspect(filename, selectors = "", properties = character())usd_inspect(filename, selectors = "", properties = character())
filename |
Path to a USD stage. |
selectors |
Default |
properties |
Default |
Supports dictionaries, boolean/integer/float/double/string/token scalars and
arrays, unsigned-byte arrays, and asset paths. Other value types fail explicitly.
This API and its registered libopenusd_inspect_v1 native entry point use R
objects and must only be called on R's main thread.
A list of prim records with paths, types, custom data, properties, and
child paths. Asset values contain authored and resolved paths. Missing prims
are omitted and missing properties return NULL.
# Read a custom scalar without converting through a text serialization. scene = usd_from_usda('#usda 1.0\ndef Xform "World" (customData = { int count = 4 }) {}') path = tempfile(fileext = ".usdc") usd_export(scene, path) usd_inspect(path, "/World")[[1]]$custom_data$count usd_close(scene) unlink(path)# Read a custom scalar without converting through a text serialization. scene = usd_from_usda('#usda 1.0\ndef Xform "World" (customData = { int count = 4 }) {}') path = tempfile(fileext = ".usdc") usd_export(scene, path) usd_inspect(path, "/World")[[1]]$custom_data$count usd_close(scene) unlink(path)
Retrieve native library messages to investigate warnings and debug output produced while reading or writing scenes.
usd_messages()usd_messages()
Messages from native workers are collected without calling R on those threads. The queue holds 128 messages of up to 2047 bytes each and reports overflow.
A character vector of buffered messages, clearing those messages
from the queue. Returns character(0) when no messages are pending.
# Inspect any diagnostics from earlier scene operations. usd_messages()# Inspect any diagnostics from earlier scene operations. usd_messages()
Open, compose, and export USD scenes using the native OpenUSD library. Stage handles retain their layers until closed or garbage collected.
usd_open(filename) usd_create() usd_from_usda(text) usd_to_usda(stage, flatten = FALSE) usd_export(stage, filename, flatten = FALSE) usd_close(stage)usd_open(filename) usd_create() usd_from_usda(text) usd_to_usda(stage, flatten = FALSE) usd_export(stage, filename, flatten = FALSE) usd_close(stage)
filename |
Path to a USD file. The extension selects the output format:
|
text |
One character string containing a complete USDA layer. |
stage |
A stage handle returned by these functions. |
flatten |
Default |
Handles belong to the current R process and cannot be restored with
saveRDS(). Export a USD file and reopen it in the next session instead.
Export does not copy textures, referenced layers, volumes, or other assets.
Root-layer export preserves authored relative asset paths, which must remain
valid relative to the destination. Anonymous layers imported from text have
no file location; use absolute asset paths or open a file with usd_open()
when relative references are required. Flattening resolves composition but
does not embed external assets. USDZ packaging is not provided by this API.
Compiled consumers can include libopenusd.h and obtain the versioned
R_GetCCallable() function table documented in the installed headers.
usd_open(), usd_create(), and usd_from_usda() return an external
pointer of class usd_stage. usd_to_usda() returns a character string.
usd_export() invisibly returns the output path. usd_close() returns
invisible NULL.
# Write a native binary USD file and reopen it for a later rendering step. scene = usd_from_usda('#usda 1.0\ndef Sphere "Ball" {\n double radius = 2\n}\n') filename = tempfile(fileext = ".usdc") usd_export(scene, filename) restored = usd_open(filename) cat(usd_to_usda(restored)) usd_close(scene) usd_close(restored) unlink(filename)# Write a native binary USD file and reopen it for a later rendering step. scene = usd_from_usda('#usda 1.0\ndef Sphere "Ball" {\n double radius = 2\n}\n') filename = tempfile(fileext = ".usdc") usd_export(scene, filename) restored = usd_open(filename) cat(usd_to_usda(restored)) usd_close(scene) usd_close(restored) unlink(filename)
Return the upstream library release used by the native stage interface.
usd_version()usd_version()
A character string containing the OpenUSD release version.
# Distinguish the upstream release from the R packaging revision. usd_version() packageVersion("libopenusd")# Distinguish the upstream release from the R packaging revision. usd_version() packageVersion("libopenusd")