Python API Reference#

The Python API provides a ctypes-based interface to the ovstage runtime data plane.

ovstage#

Version and Constants#

__version__ = '0.2.0'#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

library_version()#

Return the loaded library’s (major, minor, patch) version.

Forces the lazy load so a standalone ovstage.library_version() returns a real version (or raises if the library can’t load) instead of None before first use.

Return type:

tuple | None

TIMEOUT_INFINITE = 18446744073709551615#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

OVSTAGE_TIMEOUT_INFINITE = 18446744073709551615#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

OVX_API_SUCCESS = 0#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

OVX_API_ERROR = 1#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

Stage and Path Dictionary#

class Stage#

An ovstage instance: the unit of stage-data read/write/query.

Parameters:

  • name – Optional instance name used for diagnostics.

  • config – Optional process configuration. Its runtime-default hierarchy model is captured by this instance and controls automatic transform updates.

__init__(name=None, config=None)#
Parameters:
advance_write_floor(ordinal, scope=Scope.ALL, attributes=None)#

Advance the write floor; scope selects the affected attributes (see Scope).

Advances clamp to the current value, so a non-monotonic ordinal is a no-op rather than an error.

Parameters:
Return type:

Operation

clone(source_path, target_paths, ordinal)#

Clone the subtree under source_path to each path in target_paths (blocking).

Data-plane peer of ovrtx’s clone_usd (the _usd postfix is dropped). Like write_attribute(), clone is ordinal-keyed: ordinal must be greater than the write floor or the op fails with a write-floor violation. The source must exist; each target must not already exist.

Parameters:
Return type:

None

clone_async(source_path, target_paths, ordinal)#

Enqueue a subtree clone of source_path to target_paths at ordinal (asynchronous).

Parameters:
Return type:

Operation

compute_hierarchy(
input_ordinal,
output_ordinal,
model=HierarchyComputationModel.CPU_INCREMENTAL,
)#

Compute hierarchy-derived data for input_ordinal (blocking).

Parameters:

  • input_ordinal (int)

  • output_ordinal (int)

  • model (int)

Return type:

None

compute_hierarchy_async(
input_ordinal,
output_ordinal,
model=HierarchyComputationModel.CPU_INCREMENTAL,
)#

Enqueue hierarchy-derived data computation for input_ordinal.

Parameters:

  • input_ordinal (int)

  • output_ordinal (int)

  • model (int)

Return type:

Operation

delete_attributes(query, attributes, ordinal)#

Enqueue a delete. Empty attributes deletes entire prims.

Parameters:
Return type:

Operation

destroy()#
Return type:

None

fetch_hierarchy_result(hierarchy)#

Fetch, copy, and release a completed hierarchy lookup result payload.

Return type:

HierarchyResult

fetch_map_next(mapping, timeout=18446744073709551615)#
Parameters:

timeout (int)

Return type:

MapGroup | None

fetch_ordinal(ordinal_query, timeout=18446744073709551615)#
Parameters:

timeout (int)

Return type:

int

fetch_query_result(query, timeout=18446744073709551615)#

Fetch (and release) a query result, copying out its scalar summary.

Parameters:

timeout (int)

Return type:

QueryResult

fetch_read_next(read, timeout=18446744073709551615)#

Fetch the next read group, or None at end of iteration.

Parameters:

timeout (int)

Return type:

ReadGroup | None

get_attribute_write_floor(attribute=None)#

Query a per-attribute write floor, or the global write floor if attribute is None.

Parameters:

attribute (str | int | None)

Return type:

OrdinalQuery

get_hierarchy(path_list, ordinal, relation)#

Return parent/children/siblings for an ordered path list (blocking).

Parameters:

  • path_list (int)

  • ordinal (int)

  • relation (int)

Return type:

HierarchyResult

get_hierarchy_async(path_list, ordinal, relation)#

Enqueue a parent/children/siblings lookup for an ordered path list.

Parameters:

  • path_list (int)

  • ordinal (int)

  • relation (int)

Return type:

Hierarchy

get_hierarchy_computation_models()#

Return the hierarchy computation models supported by this backend.

Return type:

List[HierarchyComputationModelDesc]

get_oldest_preserved_ordinal()#
Return type:

OrdinalQuery

get_path_dictionary()#

Return the instance’s shared path-dictionary bundle ({vtable, context}).

The dictionary is owned by ovstage and stays valid while at least one instance is alive; callers must not tear it down. This is the raw bundle the binding dispatches through, not a ovstage.PathDictionary — to work with tokens, paths, and path lists from Python, construct PathDictionary(stage), which calls this for you.

Return type:

LP_path_dictionary_instance_t

static get_version()#
Return type:

tuple

map_attribute(
query,
attribute,
ordinal,
*,
prim_mode=PrimMode.UPSERT,
dtype=None,
semantic=0,
element_sizes=None,
)#

Reserve a zero-copy map session for an attribute.

dtype is the element storage type used only when the column does not yet exist (the full per-element tuple width must be encoded in dtype.lanes); it is ignored when the attribute already has a type. Fixed-size map groups expose the same lane-canonical layout as raw reads: ndim=1, shape=(data_rows,), and the complete tuple width in dtype.lanes. Use the group’s data_row_index(local) to resolve a logical element through any data index map. Map groups do not reconstruct a convenience write shape such as (N, 4, 4). semantic is the AttributeSemantic (or raw ovstage_attribute_semantic_t value) carried on the map. Geometric semantics and TIME_CODE record a role on the column when the map creates it; ID semantics select the corresponding ID storage type and require pre-interned ids in the map buffer (TOKEN_ID / RELATIONSHIP_PATH_ID use dtype = (kDLUInt, 64, 1), CONNECTION_PATH_ID uses dtype = (kDLUInt, 64, 2)). element_sizes gives per-prim element counts for ragged columns.

Parameters:
Return type:

Map

query(filter=None, attrs=None)#

Enqueue a filter query. attrs scopes attribute discovery (tokens).

Parameters:
Return type:

Query

query_from_path_list(path_list)#

Create a query handle from an interned prim path list (synchronous).

The handle wraps a caller-owned list (see query_from_path_list in ovstage_api.h), so keep your list alive for as long as the query and release it when you are done:

with paths.create_path_list_from_strings(paths_) as plist:
    with stage.query_from_path_list(plist) as query:
        ...

When given a PathList, the returned Query holds a reference to it, so the list cannot be finalized while the query is live. That is a safety net, not a transfer of ownership: releasing the query does not release your list. Passing a freshly created list inline — stage.query_from_path_list(paths.create_path_list_from_strings(...)) — leaves no handle to release, so the list is eventually reclaimed by PathList.__del__() with a ResourceWarning. Bind it.

Parameters:

path_list (int)

Return type:

Query

read_attributes(query, attrs, ordinal_range)#
Parameters:
Return type:

Read

release_group(group)#

Release a read group’s pinned storage.

A group released twice would free storage the instance has already reclaimed, so a ReadGroup raises instead — this is what keeps an explicit release plus a later finalizer from double-releasing.

Release state is tracked on every ReadGroup, including one a caller constructed themselves (no owning stage). Such a group has no finalizer, but it still needs the flag: without it a second release_group would reach the C API, and ReadGroup.tensor() / ReadGroup.prim_index() would keep reading storage that has been handed back.

Parameters:

group (ReadGroup)

Return type:

None

release_hierarchy(hierarchy)#
Return type:

Operation

release_op(op_id)#

Release op tracking state; returns the raw ovstage_api_status_t.

Parameters:

op_id (int)

Return type:

int

release_ordinal_query(ordinal_query)#
Return type:

Operation

release_query(query)#
Return type:

Operation

release_read(read)#
Return type:

Operation

unmap_attribute(mapping, cuda_event=None, cuda_stream=None)#
Parameters:

  • cuda_event (int | None)

  • cuda_stream (int | None)

Return type:

Operation

unmap_group(mapping, group, cuda_event=None, cuda_stream=None)#
Parameters:
Return type:

Operation

wait_op(op_id, timeout=18446744073709551615)#

Low-level wait: returns (code, error_op_ids, lowest_pending_op_id).

Does not release the op. Lets callers inspect the wait result struct directly (e.g. timeout’s lowest_pending_op_id or a failed producer’s error_op_ids).

Parameters:
wait_op_raw(op_id, timeout=18446744073709551615)#

Wait without raising or releasing; returns the raw ovstage_api_status_t.

Parameters:
Return type:

int

write_attribute(
query,
attribute,
ordinal,
tensors,
*,
is_array,
prim_mode=PrimMode.UPSERT,
semantic=0,
index_map=None,
mask=None,
count=None,
cuda_event=None,
cuda_stream=None,
)#

Enqueue a copy-in write.

is_array explicitly declares the logical attribute kind and is never inferred from tensor count, tensor shape, payload width, attribute name, semantic, or existing storage. tensors is a numpy array / DLTensor, or a list thereof (one per source row for array attributes). Caller-owned tensors are kept alive on the returned Operation until wait().

Fixed-size writes (is_array=False) are normalized to the raw API’s lane-canonical layout: reads and maps return ndim=1, a leading dimension equal to the transported data-row count, and the complete per-row tuple width in dtype.lanes. Logical prims select those rows directly or through the group’s data index map. Compact convenience inputs such as a point array shaped (N, 3) or a matrix array shaped (N, 4, 4) are accepted, but their trailing shape is folded and not preserved. Without an index map, the leading dimension must equal the logical element count; a flat (N * L,) array is not inferred as N rows of width L. This normalization does not describe array/ragged attributes.

Array element types are never inferred from tensor shape. If a non-NumPy DLPack producer exposes a vector element as a trailing component axis (for example Warp vec3f as (N, 3), lanes=1), first call make_dltensor() with the explicit lane dtype. That helper permits only a validated, compact trailing-axis fold, so point3f[] can remain zero-copy without ambiguously reinterpreting scalar arrays.

Reserved metadata uses the same contract: usd-prim-type requires is_array=False and usd-schemas requires is_array=True. Neither attribute is implicitly broadcast; use index_map when target rows intentionally share source data.

count is the number of logical elements the write addresses — the leading count prims of the query, in query order. With neither index_map nor mask it defaults to the query’s prim count. When given it must be positive: 0 is the C contract’s spelling of “the whole query”, so passing it — including as len() of an empty selection — raises ValueError rather than writing nothing. index_map and mask are mutually exclusive and both refine that logical element axis:

  • index_map[i] is the source row logical element i reads from, not the prim being written. Use it to gather, reorder, or broadcast rows (index_map=[0, 0] writes one source row to two prims). Every entry must be less than the transported row count, which for a fixed-size write is shape[0]. The map holds one entry per logical element, so count defaults to len(index_map) and may not exceed it — to address more of the query, lengthen the map rather than raising count.

  • mask is a bitmask over the same logical element axis selecting which prims are written; unselected prims are left untouched. It has no default count: supply one, along with enough 64-bit words to cover it (ceil(count / 64)).

To write a subset of a query’s prims, use mask; index_map selects source data, not targets.

All three carry the width of the C fields behind them: count and every index_map entry must fit in uint32 and each mask word in uint64. An out-of-range value raises ValueError rather than wrapping into the field — count=2**32 is rejected, not silently turned into the whole-query 0.

semantic is the AttributeSemantic (or raw ovstage_attribute_semantic_t value) carried on the write. Geometric semantics (POINT/VECTOR/NORMAL/COLOR/QUATERNION/MATRIX/FRAME/TEXTURE_COORDINATE) and TIME_CODE record a role on the column; ID semantics select the corresponding ID storage type and require pre-interned id payloads (TOKEN_ID / RELATIONSHIP_PATH_ID use dtype = (kDLUInt, 64, 1), CONNECTION_PATH_ID uses dtype = (kDLUInt, 64, 2)). 0 (NONE) writes the payload without stamping a role / base type on the column.

Parameters:
Return type:

Operation

write_attributes(
query,
writes,
ordinal,
*,
prim_mode=PrimMode.UPSERT,
)#

Enqueue one copy-in operation for multiple attribute columns.

Every write is validated before the operation is queued. The returned operation owns all ctypes/tensor keepalives until wait(). Each fixed-size entry follows the same lane-canonical normalization as write_attribute().

Parameters:
Return type:

Operation

class StageConfig#

Process configuration applied when creating a Stage.

The configuration is process-scoped. Configured stages may coexist when their concrete settings match; creating a stage with a conflicting setting while another stage is live raises OvstageError.

__init__(runtime_default_hierarchy_computation_model=None)#
Parameters:

runtime_default_hierarchy_computation_model (HierarchyComputationModel | None)

Return type:

None

runtime_default_hierarchy_computation_model: HierarchyComputationModel | None = None#
class PathDictionary#

A shared interning dictionary for tokens, prim paths, and path lists.

The dictionary is owned by an ovstage instance. Pass an existing Stage to share its dictionary, or omit stage to manage a private backing instance whose lifetime is tied to this object.

__init__(stage=None)#
add_path_list_reference(path_list)#

Increment a path list’s refcount (pair with destroy_path_list()).

The added reference is yours alone: dropping the PathList never revokes it, because the finalizer reclaims only the reference create_path_list* minted. The path-dictionary contract sanctions holding a bare handle beyond the object you added it through — release it with a matching destroy_path_list().

The count is still recorded, so a later destroy_path_list through a plain int is attributed to one of these references rather than silently consuming the owner’s claim.

Parameters:

path_list (int)

Return type:

None

create_path_list(primpaths)#

Build a path list from interned prim paths, owning one reference.

The returned PathList is the handle (an int subclass) and releases that reference on with-exit, PathList.release(), or destroy_path_list().

Parameters:

primpaths (Sequence[int])

Return type:

PathList

create_path_list_from_strings(paths)#

Build a path list from path strings, owning one reference.

See create_path_list() for the returned handle’s lifetime.

Parameters:

paths (Sequence[str])

Return type:

PathList

destroy()#
Return type:

None

destroy_path_list(path_list)#

Release one reference on a path list (erases it at refcount zero).

Which reference this drops is attributed as follows, because the C API counts references without distinguishing them:

  • passing the PathList releases its reference, clearing the owner flag so the finalizer will not release it a second time;

  • passing a plain int releases one you added with add_path_list_reference() when any are outstanding, and only falls through to the owner’s reference when none are. Otherwise releasing an added reference through the handle would steal the owner’s claim and strand the create reference for good.

Ownership is keyed by handle on the Stage, so this holds whether the call goes through the PathList, a plain int copy of the handle, or a different PathDictionary wrapper over the same stage. A handle no wrapper minted — a borrowed list from a read result, or one already fully released — is untracked and passes straight through to the C API, exactly as before.

Parameters:

path_list (int)

Return type:

None

get_path_strings(path_list)#
Parameters:

path_list (int)

Return type:

List[str]

get_paths(path_list)#
Parameters:

path_list (int)

Return type:

List[int]

intern_path(path)#
Parameters:

path (str)

Return type:

int

intern_token(string)#
Parameters:

string (str)

Return type:

int

path_list_count(path_list)#
Parameters:

path_list (int)

Return type:

int

path_to_string(primpath)#

Resolve a prim-path handle to its path string.

Raises OvxError if the handle is invalid, unknown, or expired. The absolute root resolves to "/", matching SdfPath; a valid handle never resolves to the empty string, so "" is exclusively the shape no successful decode produces.

Parameters:

primpath (int)

Return type:

str

token_to_string(token)#
Parameters:

token (int)

Return type:

str

Queries, Reads, and Maps#

class Query#
release()#
Return type:

Operation

result(timeout=18446744073709551615)#

Fetch (and release) the query result.

Parameters:

timeout (int) – max nanoseconds to wait for the result; TIMEOUT_INFINITE (default) blocks, 0 polls.

Raises:

  • TypeError – if timeout is not an integer (e.g. None).

  • ValueError – if timeout is negative or does not fit in uint64.

Return type:

QueryResult

class OrdinalQuery#
fetch(timeout=18446744073709551615)#

Fetch the queried ordinal value.

Parameters:

timeout (int) – max nanoseconds to wait for the value; TIMEOUT_INFINITE (default) blocks, 0 polls.

Raises:

  • TypeError – if timeout is not an integer (e.g. None).

  • ValueError – if timeout is negative or does not fit in uint64.

Return type:

int

release()#
Return type:

Operation

class Read#
fetch_next(timeout=18446744073709551615)#

Fetch the next read group, or None at end of iteration.

Parameters:

timeout (int) – max nanoseconds to wait for the next group; TIMEOUT_INFINITE (default) blocks, 0 polls.

Raises:

  • TypeError – if timeout is not an integer (e.g. None).

  • ValueError – if timeout is negative or does not fit in uint64.

  • OvstageError – with ErrorCode.TIMEOUT if no group is ready in time.

Return type:

ReadGroup | None

groups(timeout=18446744073709551615)#

Generator over read groups. The caller must release each group.

Parameters:

timeout (int)

release()#
Return type:

Operation

class Map#

A reserved zero-copy map (write) session.

Reserve via Stage.map_attribute(), iterate writable groups with groups() / fetch_next(), fill each group, and commit it with unmap_group(). Finalize with unmap(), which commits any remaining groups and releases the handle.

An outstanding map pins session state (a reserved layout) and blocks overlapping writes, maps, and deletes on the same prims until it is unmapped. To guarantee release even when an error interrupts the fill loop, use the session as a context manager:

with stage.map_attribute(query, attr, ordinal=o) as m:
    m.wait()
    for mg in m.groups():
        fill(mg)
        m.unmap_group(mg)

Leaving the with block — normally or via an exception — calls unmap(). The C API has no cancel: unmap always commits whatever the map buffers currently hold, so an exception mid-fill still persists the partially filled storage (there is no rollback). If a session is dropped without ever unmapping, __del__() issues a best-effort unmap and emits a ResourceWarning; rely on the context manager (or an explicit unmap()) rather than the finalizer.

__init__(stage, handle, op)#
Parameters:
fetch_next(timeout=18446744073709551615)#

Fetch the next writable map group, or None at end of iteration.

Parameters:

timeout (int) – max nanoseconds to wait for the next group; TIMEOUT_INFINITE (default) blocks, 0 polls.

Raises:

  • TypeError – if timeout is not an integer (e.g. None).

  • ValueError – if timeout is negative or does not fit in uint64.

  • OvstageError – with ErrorCode.TIMEOUT if no group is ready in time.

Return type:

MapGroup | None

groups(timeout=18446744073709551615)#
Parameters:

timeout (int)

unmap(cuda_event=None, cuda_stream=None)#

Commit remaining groups and release the map handle (see class docstring).

Parameters:

  • cuda_event (int | None)

  • cuda_stream (int | None)

Return type:

Operation

unmap_group(group, cuda_event=None, cuda_stream=None)#
Parameters:
Return type:

Operation

class Operation#

A handle to an enqueued (asynchronous) ovstage operation.

status is the enqueue status (OVSTAGE_OK = accepted); op_id is the per-op identifier. Call wait() to block until the op (and its ordinal-keyed dependencies) completes, raising OvstageError if it failed.

__init__(stage, status, op_id, keepalive=None)#
Parameters:
error_message()#
Return type:

str

property ok: bool#
wait(timeout=18446744073709551615)#

Wait for completion and release the op. Raises on failure.

Mirrors the C++ waitOk helper: if the enqueue was rejected, or the op or its dependencies failed, raises OvstageError.

Parameters:

timeout (int) – max nanoseconds to wait; TIMEOUT_INFINITE (default) blocks, 0 polls.

Raises:

  • TypeError – if timeout is not an integer (e.g. None).

  • ValueError – if timeout is negative or does not fit in uint64.

Return type:

None

class Hierarchy#
release()#
Return type:

Operation

result()#
Return type:

HierarchyResult

Instancing Queries#

available()#

Return whether the loaded libovstage exports all instancing queries.

Return type:

bool

get_prototype_roots(stage)#

Return every scene-graph-instancing prototype-root path in stage.

Return type:

list[str]

get_prototype_root(stage, instance_root)#

Return the prototype-root path referenced by instance_root.

Raises:

OvstageError – If instance_root is not an instance root or the native query otherwise fails.

Parameters:

instance_root (str)

Return type:

str

get_instance_roots(stage, prototype_root)#

Return the instance-root paths that reference prototype_root.

Parameters:

prototype_root (str)

Return type:

list[str]

Data and Result Types#

class WriteDesc#

Python-facing form of one native ovstage_attribute_write_t.

Each instance supplies one named attribute write to Stage.write_attributes().

is_array is required and explicitly declares the logical attribute kind; it is never inferred from tensors. tensors accepts the same numpy/DLTensor forms as Stage.write_attribute(). Sparsity and CUDA synchronization are write-local, as is semantic; the ordinal and prim mode are shared by the batch. Fixed-size convenience shapes are normalized to one source-data-row dimension with the tuple width in dtype.lanes; their trailing dimensions are not preserved.

count, index_map, and mask carry the same bounds as Stage.write_attribute().

__init__(
attribute,
tensors,
is_array,
index_map=None,
mask=None,
count=None,
cuda_event=None,
cuda_stream=None,
semantic=AttributeSemantic.NONE,
)#
Parameters:
Return type:

None

count: int | None = None#
cuda_event: int | None = None#
cuda_stream: int | None = None#
index_map: Sequence[int] | None = None#
mask: Sequence[int] | None = None#
semantic: AttributeSemantic = 0#
attribute: int | str#
tensors: Any#
is_array: bool#
class OrdinalRange#

Ordinal range for reads.

  • OrdinalRange.latest(N) → latest snapshot request; recorded columns return current committed payload rather than historical payload <= N.

  • OrdinalRange.between(start, end) → select the keys that changed in inclusive [start, end]. An unsealed selected change raises WRITE_FLOOR_VIOLATION. If a selected key also changed after end, latest-only storage raises OUT_OF_RANGE because the payload for that fixed range is no longer available.

__init__(end_ordinal, start_ordinal=None)#
Parameters:

  • end_ordinal (int)

  • start_ordinal (int | None)

Return type:

None

classmethod between(start_ordinal, end_ordinal)#
Parameters:

  • start_ordinal (int)

  • end_ordinal (int)

Return type:

OrdinalRange

classmethod latest(end_ordinal)#
Parameters:

end_ordinal (int)

Return type:

OrdinalRange

start_ordinal: int | None = None#
to_c()#
Return type:

ovstage_ordinal_range_t

end_ordinal: int#
class Predicate#

A single filter predicate. attribute may be an int token or a string.

__init__(attribute, op, values=<factory>)#
Parameters:
Return type:

None

attribute: int | str#
op: FilterOp#
values: Sequence[str]#
class Filter#

Conjunction (AND) of predicates. None filter = match all prims.

__init__(predicates)#
Parameters:

predicates (Sequence[Predicate])

to_c()#

Return (ovstage_filter_t, keepalive).

The keepalive list owns every ctypes buffer the filter struct points into (predicate array, attribute string refs, value-string arrays); the caller must keep it alive for the duration of the query enqueue call.

Return type:

Tuple[ovstage_filter_t, list]

class ReadGroup#

A read result group (ovstage_read_group_t).

Valid until released via Stage.release_group(). Exposes the attribute token, ordinal, delete flag, prim grouping, and tensor data.

A group’s pinned storage is an independent resource: it is reclaimed only by release_group. Releasing the owning Read does not reclaim it, so a dropped group stays pinned for the life of the Stage — and, because the pin also holds the group’s outstanding-read coverage, later writes to the same attribute and prims keep failing with an “overlapping outstanding read” error reported at the write site, far from the group that caused it.

Use it as a context manager so the group is released even when an error interrupts processing. fetch_next() returns None at end of iteration, so bind it before entering the block:

group = read.fetch_next()
if group is not None:
    with group:
        values = np.array(group.array(0))  # copy out to outlive the group

or iterate, which only yields real groups:

for group in read.groups():
    with group:
        ...

If a group is dropped without release, __del__() issues a best-effort release and emits a ResourceWarning; rely on the context manager (or an explicit Stage.release_group()) rather than the finalizer. Note the zero-copy views handed out by array() / tensor() point into that pinned storage and must not outlive the release.

__init__(raw, stage=None)#
array(index)#

Zero-copy flat read-only numpy view of tensor index (CPU only).

Tuple lanes are folded into this one-dimensional base-element view.

The view borrows this group’s storage and does not keep the group alive: it is valid only while the group is, and the group is released by Stage.release_group(), by with exit, or by the finalizer once the group becomes unreachable. Keep the group bound for as long as you read through the view, and copy out (np.array(...)) anything that must outlive it.

Parameters:

index (int)

property attribute: int#
property is_array: bool#

Whether this result group carries array-valued attribute rows.

property is_delete: bool#
property ordinal: int#
release()#

Release this group’s pinned storage (see Stage.release_group()).

Return type:

None

property released: bool#

Whether this group’s pinned storage has been released.

class MapGroup#

A writable map group (ovstage_map_group_t).

Fill array(i) then commit via Stage.unmap_group() (or finalize the whole session with Stage.unmap_attribute()).

dlpack(index, *, readonly=False)#

Writable DLPack view of tensor index (a map group is writable).

Fill it in place — wp.from_dlpack(group.dlpack(i)) for a GPU kernel, or np.from_dlpack(group.dlpack(i))[:] = ... on CPU (numpy >= 2.1 honors the writable flag) — then commit via Stage.unmap_group() / Stage.unmap_attribute().

Parameters:
Return type:

ManagedDLTensor

class AttributeMeta#

Read-only view of ovstage_attribute_meta_t.

attribute_write_floor_ordinal#
layout_generation#
__init__(raw)#
Parameters:

raw (ovstage_attribute_meta_t)

class QueryResult#

Snapshot of a fetched query result (copied out before release).

Owns no C-side resources: Stage.fetch_query_result() copies the scalar summary and the attribute tokens out, then releases the payload before returning. Nothing here needs to be freed.

__init__(attributes, total_prim_count, all_handle)#
Parameters:
Return type:

None

attributes: List[int]#
total_prim_count: int#
all_handle: int#
class HierarchyItem#

Per-input hierarchy lookup result.

__init__(status, paths)#
Parameters:
Return type:

None

property ok: bool#
status: int#
paths: Tuple[str, ...]#
class HierarchyResult#

Copied hierarchy lookup result.

items preserves the input path-list order. Each item carries its own status so a missing input prim can be reported without failing the whole batch.

__init__(ordinal, items)#
Parameters:
Return type:

None

property input_count: int#
item_paths(index)#
Parameters:

index (int)

Return type:

Tuple[str, …]

ordinal: int#
items: List[HierarchyItem]#
class HierarchyComputationModelDesc#

Runtime-supported hierarchy computation model descriptor.

__init__(model_id, name, description)#
Parameters:

  • model_id (int)

  • name (str)

  • description (str)

Return type:

None

model_id: int#
name: str#
description: str#

Enums#

class ErrorCode#
__new__(value)#
OK = 0#
INVALID_ARGUMENT = 1#
INVALID_HANDLE = 2#
NOT_FOUND = 3#
PRIM_NOT_FOUND = 4#
WRITE_FLOOR_VIOLATION = 5#
NOT_SUPPORTED = 6#
QUEUE_FULL = 7#
END_OF_ITERATION = 8#
OUT_OF_MEMORY = 9#
LAYOUT_CHANGED = 10#
TIMEOUT = 11#
OP_FAILED = 12#
OUT_OF_RANGE = 13#
INTERNAL = 99#
class FilterOp#
__new__(value)#
HAS = 0#
IN = 1#
CONTAINS = 2#
PREFIX = 3#
LT = 4#
LE = 5#
GT = 6#
GE = 7#
class PrimMode#
__new__(value)#
UPSERT = 0#
INSERT = 1#
class AttributeSemantic#

Authored USD interpretation of a column’s bytes (ovstage_attribute_semantic_t).

Geometric semantics (POINT/VECTOR/NORMAL/COLOR/QUATERNION/MATRIX/FRAME/ TEXTURE_COORDINATE) record a geometric role on the column; storage stays in the requested numeric dtype.

TIME_CODE marks a time code – a unitless time value – again with storage in the requested numeric dtype. Only the plain numeric value is carried: sentinel time codes have no portable numeric encoding, so they are not representable.

ID semantics select the corresponding ID storage type and require pre-interned id payloads (producers must intern via the path dictionary / token dictionary before writing – ovstage does not stringify or resolve):

  • TOKEN_ID → dtype = (kDLUInt, 64, 1) carrying one 64-bit token id per row; id 0 is the empty token.

  • RELATIONSHIP_PATH_ID → dtype = (kDLUInt, 64, 1) carrying one 64-bit path id per row.

  • CONNECTION_PATH_ID → dtype = (kDLUInt, 64, 2) carrying one (path_id, token_id) pair per row (one 16-byte element per row).

  • ASSET_PATH_ID → dtype = (kDLUInt, 64, 2) carrying one (authored_token, resolved_token) pair per row (one 16-byte element per row).

An asset has two paths: the path as authored, and the path after resolution. ASSET_PATH_ID carries both as token ids. A token id of 0 means no path, so an unresolved asset has a resolved token id of 0.

PATH_EXPRESSION_STRING carries the expression text as one interned token id, (kDLUInt, 64, 1). is_array = False is a scalar pathExpression; True is pathExpression[], one id per element. Writes reject other layouts. A token id of 0 means no expression. ovstage does not evaluate the expression; it stores the id of the authored text.

STRING carries a plain USD string as raw UTF-8 bytes in a ragged (kDLUInt, 8, 1) byte array (is_array = True), not a token id. It records the USD-string role so the column uses the canonical USD-string representation.

The semantic round-trips through the attribute column: writes record it at creation, reads recover it by decoding the column.

__new__(value)#
NONE = 0#
ASSET_PATH_ID = 1#
TOKEN_ID = 2#
PATH_EXPRESSION_STRING = 3#
RELATIONSHIP_PATH_ID = 4#
POINT = 5#
VECTOR = 6#
NORMAL = 7#
COLOR = 8#
QUATERNION = 9#
MATRIX = 10#
TEXTURE_COORDINATE = 11#
CONNECTION_PATH_ID = 12#
STRING = 13#
TIME_CODE = 14#
FRAME = 15#
class Scope#

Write-floor advance scope (see Stage.advance_write_floor()).

  • ALL → advance the global write floor and every known attribute.

  • INCLUDE → advance only the listed attributes.

  • EXCLUDE → advance every known attribute except the listed ones (an empty list behaves like ALL).

__new__(value)#
ALL = 0#
INCLUDE = 1#
EXCLUDE = 2#
class PopulationDomain#
__new__(value)#
NONE = 0#
RENDERING = 1#
PHYSICS = 2#
ALL = 3#
class HierarchyRelation#
__new__(value)#
PARENT = 0#
CHILDREN = 1#
SIBLINGS = 2#
class HierarchyComputationModel#
__new__(value)#
INVALID = 0#
CPU_INCREMENTAL = 1#
GPU_INCREMENTAL = 2#
GPU_GLOBAL = 3#
RUNTIME_DEFAULT = 4#
DEFAULT_CPU = 1#
DEFAULT_GPU = 3#

Errors#

class OvstageError#

Raised when an ovstage call or enqueued op fails.

code is the raw ovstage_api_status_t; message is the human-readable detail from ovstage_get_last_op_error / ovstage_get_last_error when available.

__init__(code, message='')#
Parameters:
class OvxError#

Raised on a non-success ovx_api_result_t from a path-dictionary call.

__init__(code, message='')#
Parameters:

Logging#

set_log_callback(callback, severity=None, channel_filter=None)#

Install (or clear) a process-global log callback.

Routes ovstage’s log messages — and messages from its USD support layer — to callback(severity, timestamp, message), where severity is a LogSeverity, timestamp is wall-clock seconds since the epoch, and message is an owned str (a decoded copy that remains valid after the call returns).

Delivery is asynchronous on a dedicated dispatcher thread (created lazily on the first callback), so the callback never runs on the logging hot path and invocations are serialized. Use flush_log() to force pending messages through before a checkpoint.

Requires the runtime to be bootstrapped — hold a live Stage when calling this.

Note

An exception raised by callback has its traceback printed to stderr (so it is visible for debugging) and is then suppressed — it never unwinds into the C dispatcher. Do not emit ovstage/USD log messages from inside callback: they re-enter the dispatcher and can feed back indefinitely.

Parameters:

  • callback – f(severity, timestamp, message) callable, or None to flush pending messages and disable delivery.

  • severity – default LogSeverity threshold for channels not matched by channel_filter; messages below it are dropped. Defaults to WARNING.

  • channel_filter (str | None) – optional comma-separated <channel>=<level> list (e.g. "omni.ovstage=verbose"); None applies severity uniformly. Levels: verbose|debug|info|warn|warning|error|fatal|none.

Raises:

OvstageError – INVALID_ARGUMENT if the filter fails to parse, or OP_FAILED if the runtime is not bootstrapped.

Return type:

None

flush_log(timeout=18446744073709551615)#

Block until log messages emitted before this call have been delivered.

Point-in-time barrier: messages produced concurrently with or after the call are not guaranteed to be included. Returns immediately if no callback is installed (nothing is buffered).

Warning

With the default OVSTAGE_TIMEOUT_INFINITE this blocks until the dispatcher drains; a stuck callback makes it hang. Pass a finite timeout if the callback might block.

Parameters:

timeout (int) – max nanoseconds to wait; OVSTAGE_TIMEOUT_INFINITE blocks, 0 polls.

Returns:

True if drained (or no callback installed); False if not drained within timeout.

Raises:

  • TypeError – if timeout is not an integer (e.g. None).

  • ValueError – if timeout is negative or does not fit in uint64.

  • OvstageError – on any error other than a timeout.

Return type:

bool

class LogSeverity#

Log severity levels (mirrors ovstage_log_severity_t).

Values follow the underlying log-level ordering. NONE is a threshold sentinel: as a filter level it disables all logging and is never delivered to a callback.

__new__(value)#
VERBOSE = -2#
INFO = -1#
WARNING = 0#
ERROR = 1#
NONE = 3#

USD Schemas#

register_usd_schemas(paths)#

Register USD schema definitions with the USD runtime population reads through.

Population registers only what its USD build provides (the core Usd* schemas). Register any additional family your stages use, so population resolves each prim’s full schema-declared property set rather than only its authored properties.

Registering does not load schema code, so a family that ships a C++ library or Python module is usable for its definitions alone.

Warning

Call this before the first ovstage call that reads USD schema definitions – populating a stage and exporting one both do. A family registered after that contributes nothing and raises OvstageError. One registered after some other USD consumer in the process has read schemas cannot be detected and fails silently.

Registration is irreversible. Re-registering an already-registered family is a no-op, not an error.

Parameters:

paths – one path, or an iterable of paths. Each is either a USD plugin descriptor (plugInfo.json) or a directory containing one. A descriptor’s Includes are followed, so a single entry can bring in a whole tree of schema families.

Raises:

OvstageError – if a path names no readable descriptor, or the call came too late to take effect.

Return type:

None

Note

Only the paths themselves are checked. What a descriptor contains is USD’s to validate: a malformed one, or an Includes pattern matching nothing, raises a USD diagnostic, contributes no plugins, and still returns normally — surfacing later as schema properties that never resolve.

DLPack Tensor Interchange#

class DLTensor#

Plain C tensor object; does not manage memory.

byte_offset#

Structure/Union member

data#

Structure/Union member

device#

Structure/Union member

dtype#

Structure/Union member

classmethod from_dlpack(obj, stream=None)#

Build a DLTensor viewing any object implementing the DLPack protocol.

Accepts numpy / warp / torch / cupy / jax tensors (anything exposing __dlpack__) resident on CPU or CUDA and aliases their memory zero-copy, so a GPU producer’s device buffer can be handed straight to ovstage without a host round-trip. Shape and strides are deep-copied, while the consumed producer descriptor/deleter and source object are retained on the returned tensor so the aliased buffer remains valid until the returned tensor is destroyed. The caller must keep the returned tensor alive until the consuming op completes (Stage.write_attribute does this via the Operation keepalive).

stream is forwarded to a CUDA producer so it can synchronize the exporting stream against the consumer; it is ignored for CPU tensors and for producers that do not advertise __dlpack_device__.

Parameters:

  • obj (Any)

  • stream (int | None)

Return type:

DLTensor

ndim#

Structure/Union member

shape#

Structure/Union member

property shape_tuple: tuple#
strides#

Structure/Union member

class DLDataType#

Descriptor of the element data type of a DLTensor.

bits#

Structure/Union member

code#

Structure/Union member

lanes#

Structure/Union member

class DLDevice#

Device where DLTensor memory is allocated.

device_id#

Structure/Union member

device_type#

Structure/Union member

class DLDeviceType#

The enum encoding the type of device where DLTensor memory lives.

kDLCPU = 1#
kDLCUDA = 2#
kDLCUDAHost = 3#
kDLCUDAManaged = 13#
kDLExtDev = 12#
kDLHexagon = 16#
kDLMAIA = 17#
kDLMetal = 8#
kDLOneAPI = 14#
kDLOpenCL = 4#
kDLROCM = 10#
kDLROCMHost = 11#
kDLTrn = 18#
kDLVPI = 9#
kDLVulkan = 7#
kDLWebGPU = 15#
class DLDataTypeCode#

An integer encoding the category of a DLTensor element’s data type.

kDLBfloat = 4#
kDLBool = 6#
kDLComplex = 5#
kDLFloat = 2#
kDLInt = 0#
kDLOpaqueHandle = 3#
kDLUInt = 1#
class ManagedDLTensor#

A DLPack-exportable view of an ovstage tensor.

Obtained from ovstage.ReadGroup.dlpack() / ovstage.MapGroup.dlpack(). Pass the instance to np.from_dlpack() / wp.from_dlpack() / torch.from_dlpack() for zero-copy access (CPU or CUDA), or call numpy() for a CPU numpy view.

The tensor data is borrowed from ovstage and valid only until the owning read/map group is released — copy it if it must outlive the read. A read group is exported readonly=True; a (writable) map group readonly=False. DLPack consumers see one trailing dimension added for a multi-lane dtype; for example, a raw fixed matrix shape=(N,), lanes=16 is exported as (N, 16) rather than as any convenience input shape. ManagedDLTensor.shape and its representation report the raw, unexpanded (N,) shape; the trailing lane axis materializes only in a DLPack consumer such as np.from_dlpack().

manager_ctx is retained by this object and by any capsule it exports, but a capsule is destroyed as soon as a consumer takes ownership of it — which is before that consumer releases the tensor. The DLPack deleter runs no Python (see _C_FREE_DELETER), so it cannot release a Python reference at that later point. If manager_ctx is the sole owner of the backing memory, keep this ManagedDLTensor alive for as long as the consumer’s view is used:

managed = ManagedDLTensor(tensor, manager_ctx=owner)
view = np.from_dlpack(managed)  # `managed` must outlive `view`

For ovstage read/map groups the manager_ctx does not own the backing allocation, so the view stays valid while the owning group is alive — but a consumer view does not keep that group alive. Bind the group for as long as you use the view:

group = read.fetch_next()
arr = np.from_dlpack(group.dlpack(0))  # `group` must outlive `arr`

np.from_dlpack(read.fetch_next().dlpack(0)) drops the group on the same line: its finalizer releases the pinned storage and arr is left reading memory that has been handed back.

__dlpack__(
*,
stream=None,
max_version=None,
dl_device=None,
copy=None,
)#

Return a DLPack capsule. stream is accepted but ignored — GPU synchronization is the caller’s responsibility (see the dlpack skill).

Parameters:

  • stream (int | None)

  • max_version (tuple | None)

  • dl_device (tuple | None)

  • copy (bool | None)

Return type:

Any

__init__(
dl_tensor,
manager_ctx,
deleter_callback=None,
readonly=True,
)#
Parameters:
property data: int#
property device: DLDevice#
property dtype: DLDataType#
property ndim: int#
numpy()#

Zero-copy numpy view (CPU tensors only).

property raw_dltensor: DLTensor#
property shape: tuple#
make_dltensor(
array,
*,
dtype=None,
shape=None,
ndim=None,
strides=None,
device_type=1,
device_id=0,
)#

Build a DLTensor viewing the memory of an array.

A numpy array (CPU) is wrapped directly; the array, the shape storage, and the tensor are linked by reference so the C-visible pointers stay valid for as long as the returned tensor is alive. shape/ndim/dtype/strides may be overridden to describe vector (multi-lane) layouts a plain numpy dtype cannot express, matching an explicitly authored multi-lane DLTensor descriptor. A fixed-size ovstage write may also accept the numpy shape directly as a convenience layout (for example, (N, 4, 4) with lanes=1); subsequent raw reads/maps normalize it to shape=(N,), lanes=16.

Any non-numpy object exposing the DLPack protocol (warp / torch / cupy / jax, CPU or CUDA) is ingested zero-copy via DLTensor.from_dlpack() instead, so a GPU device buffer can be written without a host round-trip. Such a producer may be re-described with a vector dtype only through a validated fold of complete trailing dimensions into dtype.lanes. The source must be compact row-major with byte-aligned elements, its base type and positive bit width are unchanged, and any explicit shape/ndim/strides must match the folded compact view. For example, a Warp vec3f export shaped (N, 3) can be viewed as shape=(N,) with lanes=3 without copying its CPU or CUDA allocation. A lane fold that consumes every source axis is normalized to shape=(1,), ndim=1.

The caller owns the data: it must keep the returned tensor (and thus the backing array) alive until the consuming op completes.

Parameters:
Return type:

DLTensor

dltensor_to_numpy(tensor, *, readonly=False)#

Return a zero-copy numpy view of a CPU DLTensor.

The view is flat: its length is prod(shape) * dtype.lanes base elements, matching the raw-buffer indexing the C++ tests perform. Vector lanes are folded into the element count rather than the dtype. The data is owned by ovstage and only valid until the owning group/result is released.

When readonly is true, the view is backed by a read-only buffer so its WRITEABLE flag cannot be re-enabled. The default remains writable for caller-owned tensors and map buffers.

Every tensor’s lane count is checked against the transportable range [1, 255] and a dtype outside it is rejected with ValueError, whatever produced the descriptor. That bound needs no buffer size, so it also covers a raw DLTensor decoded straight out of the C read/map result, where the lanes field is a uint16 that a wrapped value (-1 -> 65535) would otherwise turn into a view far past the payload.

Where a real buffer size is known — a numpy array wrapped by make_dltensor(), or the extent a DLPack producer described at DLTensor.from_dlpack() time — the decoded view is additionally checked against it and can never extend past it. A raw descriptor carries no buffer length at all, so for those the lane bound is the guarantee.

Parameters:
numpy_to_dldatatype(np_dtype, lanes=1)#

Build a DLDataType from a numpy dtype (with optional vector lanes).

lanes must be an integer in [1, 255], the range ovstage can transport: anything outside it raises ValueError (TypeError for non-integers) rather than building a dtype no ovstage read or write accepts. The value lands in the DLPack uint16 lane field, which would otherwise also wrap a negative count silently (-1 becoming 65535).

Parameters:

lanes (int)

Return type:

DLDataType

ovstage.population#

USD population composes USD content into the runtime stage; population export authors selected runtime state back into a USD destination that ovstage opens and owns. See Population (USD → ovstage) and Exporting ovstage to USD.

ovstage population: populate an ovstage instance from USD.

Thin wrappers over the ovstage_population_* C entry points (the USD -> ovstage bridge in ovstage_population.h). The application owns the ordinal lifecycle and passes the current ordinal to the calls that carry one.

The surface follows the ovrtx Python conventions: every mutating entry point comes as a blocking foo(...) that returns once the work has completed, plus an asynchronous foo_async(...) that returns an Operation to wait on explicitly. Per-stage population state is created lazily on first use and released automatically when the stage is destroyed (no manual detach).

class Operation#

A handle to an enqueued (asynchronous) population operation.

Mirrors the ovrtx Operation ergonomics: wait() blocks until the op (and the ordinal-keyed ops before it) completes, returning the op’s payload on success — a USD reference handle for an add-reference op, True for a void op — or None on timeout, and raising OvstageError on failure. status is the enqueue status (OVSTAGE_OK = accepted).

__init__(
stage,
status,
op_id,
*,
value=True,
keepalive=None,
name='',
)#
Parameters:
property ok: bool#
error_message()#
Return type:

str

wait(timeout=18446744073709551615)#

Wait for completion. Returns the payload, None on timeout; raises on failure.

Parameters:

timeout (int) – max nanoseconds to wait; OVSTAGE_TIMEOUT_INFINITE (default) blocks, 0 polls.

Raises:

  • TypeError – if timeout is not an integer (e.g. None).

  • ValueError – if timeout is negative or does not fit in uint64.

class ExportOperation#

Handle for an enqueued runtime-to-USD export operation.

Every accepted operation must eventually receive a terminal wait(). Timeout polling does not consume the native report or destination keepalive.

__init__(stage, lib, status, op_id, *, name)#
Parameters:
error_message()#
Return type:

str

property ok: bool#
wait(timeout=18446744073709551615)#

Return the export report, None on timeout, or raise on failure.

Parameters:

timeout (int)

class ExportProjection#

Automatic source-attribute projection policy.

__new__(value)#
EXPLICIT_RULES = 0#
SCHEMA_DECLARED = 1#
class SourceApiSchemaPolicy#

Policy for applied API schemas recorded on source prims.

__new__(value)#
EXPLICIT_ONLY = 0#
APPLY_RECORDED = 1#
class DestinationCreateOperation#

Async creation operation whose reserved destination is immediately available.

property destination#
class DestinationOperation#

Handle for an enqueued destination lifecycle operation.

__init__(
stage,
lib,
status,
op_id,
*,
value=True,
keepalive=None,
on_terminal=None,
)#
Parameters:
property ok: bool#
wait(timeout=18446744073709551615)#

Return the operation value, None on timeout, or raise on failure.

Parameters:

timeout (int)

class ExportDestination#

ABI-opaque, source-stage-bound USD export destination.

Export calls accumulate in memory. Call save() explicitly to persist; context-manager exit only closes and discards any unsaved changes. If an open destination is dropped while its source stage remains live, the finalizer best-effort queues release without saving and emits ResourceWarning.

__init__(stage, lib, handle, identifier)#
Parameters:

  • handle (int)

  • identifier (str)

close()#

Release the destination without implicitly saving.

Return type:

None

close_async()#

Enqueue ordered release without implicitly saving.

Return type:

DestinationOperation

property closed: bool#
classmethod create(
stage,
identifier,
mode=ExportDestinationMode.EMPTY,
)#

Create a destination and wait until it is ready.

Parameters:
classmethod create_async(
stage,
identifier,
mode=ExportDestinationMode.EMPTY,
)#

Enqueue creation and expose the reserved destination immediately.

Parameters:
Return type:

DestinationCreateOperation

export(ordinal, **options)#

Export one selected runtime slice into this destination.

Parameters:

ordinal (int)

Return type:

dict

export_async(ordinal, **options)#

Enqueue one selected runtime slice into this destination.

Parameters:

ordinal (int)

Return type:

ExportOperation

property handle: int#
save()#

Persist all currently accumulated opinions.

Return type:

None

save_async()#

Enqueue persistence after previously submitted destination work.

Return type:

DestinationOperation

class ExportDestinationMode#

Initial-content policy for a reusable USD export destination.

__new__(value)#
EMPTY = 0#
OPEN_EXISTING = 1#
open_usd(
stage,
path,
ordinal=1,
time_code=nan,
domains=<PopulationDomain.RENDERING: 1>,
)#

Open a USD file and populate the stage (blocking).

time_code is in seconds (converted via the stage’s timeCodesPerSecond, like the C time parameter); math.nan (the default) evaluates at USD’s Default time code. Wraps the C entry point ovstage_population_open_usd_from_file.

Parameters:
Return type:

None

open_usd_async(
stage,
path,
ordinal=1,
time_code=nan,
domains=<PopulationDomain.RENDERING: 1>,
)#

Open a USD file and populate the stage (asynchronous). See open_usd().

Parameters:
Return type:

Operation

open_usd_from_string(
stage,
usda,
ordinal=1,
time_code=nan,
domains=<PopulationDomain.RENDERING: 1>,
)#

Open inline USDA content and populate the stage (blocking).

time_code follows the same contract as open_usd(): seconds, with math.nan (the default) evaluating at USD’s Default time code.

Parameters:
Return type:

None

open_usd_from_string_async(
stage,
usda,
ordinal=1,
time_code=nan,
domains=<PopulationDomain.RENDERING: 1>,
)#

Open inline USDA content and populate the stage (asynchronous). See open_usd_from_string().

Parameters:
Return type:

Operation

open_usd_with_desc(stage, path, ordinal, time_code, descs)#

Open a USD file and populate the stage through a description (blocking).

descs is a Desc or a sequence of them, mirroring the C entry point: each contributor supplies one, their domains are OR-ed and their selectors and stage metadata paths combined. A description carrying only domains is exactly open_usd(). An empty sequence selects nothing. time_code follows the same contract as open_usd().

Parameters:
Return type:

None

open_usd_with_desc_async(stage, path, ordinal, time_code, descs)#

Open a USD file through a description (asynchronous). See open_usd_with_desc().

Parameters:
Return type:

Operation

open_usd_from_string_with_desc(stage, usda, ordinal, time_code, descs)#

Open inline USDA and populate the stage through a description (blocking).

See open_usd_with_desc().

Parameters:
Return type:

None

open_usd_from_string_with_desc_async(
stage,
usda,
ordinal,
time_code,
descs,
)#

Open inline USDA through a description (asynchronous). See open_usd_with_desc().

Parameters:
Return type:

Operation

add_usd_reference(stage, ref_file_path, target_path)#

Add a USD file as a reference at target_path (blocking). Returns the handle.

The merge is additive in every case; target_path selects its shape: the root "/" merges the layer’s top-level prims into the stage, an existing prim path adds the reference onto that prim (leaving its prior content), and a not-yet-existing prim path defines a new prim there. Call apply_usd_changes() afterwards to reflect it into the stage.

Parameters:

  • ref_file_path (str)

  • target_path (str)

Return type:

int

add_usd_reference_async(stage, ref_file_path, target_path)#

Add a USD file as a reference at target_path (asynchronous).

Parameters:

  • ref_file_path (str)

  • target_path (str)

Return type:

Operation

add_usd_reference_from_string(stage, ref_str, target_path)#

Add inline USDA content as a reference at target_path (blocking). Returns the handle.

Same additive target_path semantics as add_usd_reference() (root "/" merge, overlay onto an existing prim, or a new prim), but the layer is provided as inline USDA text instead of a file.

Parameters:

  • ref_str (str)

  • target_path (str)

Return type:

int

add_usd_reference_from_string_async(stage, ref_str, target_path)#

Add inline USDA content as a reference at target_path (asynchronous).

Parameters:

  • ref_str (str)

  • target_path (str)

Return type:

Operation

remove_usd(stage, handle)#

Remove a USD reference previously added by add_usd_reference* (blocking).

Parameters:

handle (int)

Return type:

None

remove_usd_async(stage, handle)#

Remove a USD reference previously added by add_usd_reference* (asynchronous).

Parameters:

handle (int)

Return type:

Operation

reset_usd(stage)#

Clear all USD source content from the stage (blocking).

Return type:

None

reset_usd_async(stage)#

Clear all USD source content from the stage (asynchronous).

Return type:

Operation

update_from_usd_time(stage, ordinal, time_code)#

Advance time and propagate time-sampled attribute changes (blocking).

time_code is in seconds (converted via the stage’s timeCodesPerSecond, like the C time parameter). Wraps the C entry point ovstage_population_apply_usd_time.

Parameters:
Return type:

None

update_from_usd_time_async(stage, ordinal, time_code)#

Advance time and propagate time-sampled changes (asynchronous). See update_from_usd_time().

Parameters:
Return type:

Operation

apply_usd_changes(stage, ordinal=1)#

Propagate USD edits accumulated since the last call into the stage (blocking).

Parameters:

ordinal (int)

Return type:

None

apply_usd_changes_async(stage, ordinal=1)#

Propagate USD edits accumulated since the last call into the stage (asynchronous).

Parameters:

ordinal (int)

Return type:

Operation

last_error()#

Thread-local detail for the latest population call on this thread.

Return type:

str

available()#

True when the loaded libovstage exports the ovstage population bridge.

Return type:

bool

export_available()#

True when libovstage exports the ovstage population USD export bridge.

Return type:

bool

create_export_destination(
stage,
identifier,
mode=ExportDestinationMode.EMPTY,
)#

Create a reusable destination and wait until it is ready.

Parameters:
Return type:

ExportDestination

create_export_destination_async(
stage,
identifier,
mode=ExportDestinationMode.EMPTY,
)#

Enqueue destination creation and expose its reserved handle immediately.

Parameters:
Return type:

DestinationCreateOperation

export_to_destination(
stage,
destination,
ordinal,
*,
since_ordinal=0,
selection=0,
layer_mode=0,
transform_policy=0,
unknown_metadata_policy=0,
source_api_schema_policy=0,
projection=0,
prim_predicate=None,
property_predicate=None,
prim_rules=None,
api_schema_rules=None,
attribute_rules=None,
property_rules=None,
metadata_rules=None,
)#

Accumulate one selected runtime slice in a reusable destination.

Parameters:
Return type:

dict

export_to_destination_async(
stage,
destination,
ordinal,
*,
since_ordinal=0,
selection=0,
layer_mode=0,
transform_policy=0,
unknown_metadata_policy=0,
source_api_schema_policy=0,
projection=0,
prim_predicate=None,
property_predicate=None,
prim_rules=None,
api_schema_rules=None,
attribute_rules=None,
property_rules=None,
metadata_rules=None,
)#

Enqueue one selected runtime slice into a reusable destination.

Parameters:
Return type:

ExportOperation

export_to_usd_file(
stage,
identifier,
ordinal,
*,
since_ordinal=0,
selection=0,
layer_mode=0,
transform_policy=0,
unknown_metadata_policy=0,
source_api_schema_policy=0,
projection=0,
prim_predicate=None,
property_predicate=None,
prim_rules=None,
api_schema_rules=None,
attribute_rules=None,
property_rules=None,
metadata_rules=None,
)#

Export one selected snapshot and persist it as a replacement USD file.

Parameters:
Return type:

dict

export_to_usd_file_async(
stage,
identifier,
ordinal,
*,
since_ordinal=0,
selection=0,
layer_mode=0,
transform_policy=0,
unknown_metadata_policy=0,
source_api_schema_policy=0,
projection=0,
prim_predicate=None,
property_predicate=None,
prim_rules=None,
api_schema_rules=None,
attribute_rules=None,
property_rules=None,
metadata_rules=None,
)#

Enqueue one selected snapshot export and persistence operation.

Parameters:
Return type:

ExportOperation

export_typed_hierarchy_to_usd_file(
stage,
identifier,
root_path,
ordinal,
*,
prim_predicate=None,
property_predicate=None,
include_custom_namespaces=None,
transform_policy=0,
unknown_metadata_policy=0,
)#

Export a typed runtime hierarchy and persist it as a replacement USD file.

Parameters:
Return type:

dict

export_typed_hierarchy_to_usd_file_async(
stage,
identifier,
root_path,
ordinal,
*,
prim_predicate=None,
property_predicate=None,
include_custom_namespaces=None,
transform_policy=0,
unknown_metadata_policy=0,
)#

Enqueue typed-hierarchy export and persistence as one export operation.

Parameters:
Return type:

ExportOperation

Descriptions and Selectors#

class Desc#

What one contributor asks to be populated.

Descs compose: domains is OR-ed across the array an entry point is given, and their selectors and stage metadata paths are combined.

domains#
selectors#
stage_metadata_paths#
__init__(
domains=<PopulationDomain.NONE: 0>,
selectors=(),
stage_metadata_paths=(),
)#
Parameters:

domains (int)

class Selector#

One (which prims, which of their properties, which metadata) rule.

Selectors compose: a prim is in scope if any selector matches it, and its properties are the union over the selectors that did.

prim_predicate#
property_predicate#
prim_metadata_paths#
property_metadata_paths#
__init__(
prim_predicate=None,
property_predicate=None,
prim_metadata_paths=(),
property_metadata_paths=(),
)#
class PrimPredicate#

Which prims a selector puts in scope.

Several values of one kind match if any one of them does, so a list of schema names is a single predicate; combine different kinds with and_(), or_() and not_().

kind#
strings#
subpredicates#
nested#
static all()#

Matches every prim.

Return type:

PrimPredicate

static and_(*subpredicates)#

Matches when every subpredicate matches.

Parameters:

subpredicates (PrimPredicate)

Return type:

PrimPredicate

static has_ancestor(subpredicate)#

Matches when any strict ancestor matches. A prim is not its own ancestor.

Parameters:

subpredicate (PrimPredicate)

Return type:

PrimPredicate

static has_applied_schema(*schema_names)#

Matches an applied API schema exactly, including any :instance suffix.

Parameters:

schema_names (str)

Return type:

PrimPredicate

static has_applied_schema_in_namespace(*family_names)#

Matches every instance of a multiple-apply schema family.

Parameters:

family_names (str)

Return type:

PrimPredicate

static has_kind(*kinds)#

Matches the prim’s model kind exactly; the kind hierarchy is not consulted.

Parameters:

kinds (str)

Return type:

PrimPredicate

static has_metadata(*paths)#

Matches a prim resolving one of the named metadata paths.

Paths take the form Desc metadata paths do: a field name, extended with a :-joined key path to reach inside a dictionary field. Presence, not value: a path resolving to False matches as much as one resolving to True.

Name a key, not a whole dictionary field: a field matches whenever anything resolves beneath it, including what a schema registers rather than the prim authoring it. has_metadata("customData:myTool:export") selects the prims carrying that key.

Parameters:

paths (str)

Return type:

PrimPredicate

static has_parent(subpredicate)#

Matches when the prim’s parent matches subpredicate.

A top-level prim has no parent to match: the pseudo-root is not offered to a predicate, so this is false for it.

Parameters:

subpredicate (PrimPredicate)

Return type:

PrimPredicate

static has_path(*paths)#

Matches the prim’s absolute path exactly.

Parameters:

paths (str)

Return type:

PrimPredicate

static has_property(subpredicate)#

Matches when any property of the prim matches subpredicate.

The properties considered are the union of what the prim authors and what its schemas declare, so an unauthored schema property counts; combine with PropertyPredicate.is_authored() for “carries an authored value”.

Parameters:

subpredicate (PropertyPredicate)

Return type:

PrimPredicate

static has_purpose(*purposes)#

Matches the prim’s purpose, as inherited down the tree.

Parameters:

purposes (str)

Return type:

PrimPredicate

static has_schema(*schema_names)#

Matches a schema the prim conforms to: its type or an applied API schema.

The form to use when a list of schema names mixes the two, which a schema family generally does.

Parameters:

schema_names (str)

Return type:

PrimPredicate

static has_type(*type_names)#

Matches the prim’s type name exactly.

Parameters:

type_names (str)

Return type:

PrimPredicate

static is_a_type(*type_names)#

Matches the prim’s type name or any type it derives from.

Parameters:

type_names (str)

Return type:

PrimPredicate

static is_under_path(*paths)#

Matches a prim at or beneath an absolute path, at path-component boundaries.

Parameters:

paths (str)

Return type:

PrimPredicate

static none()#

Matches no prim. A selector built on it contributes nothing.

Return type:

PrimPredicate

static not_(subpredicate)#

Matches when subpredicate does not.

Parameters:

subpredicate (PrimPredicate)

Return type:

PrimPredicate

static or_(*subpredicates)#

Matches when any subpredicate matches.

Parameters:

subpredicates (PrimPredicate)

Return type:

PrimPredicate

class PropertyPredicate#

Which of an in-scope prim’s properties a selector publishes.

kind#
strings#
subpredicates#
nested#
static all()#

Matches every property of an in-scope prim.

Return type:

PropertyPredicate

static and_(*subpredicates)#

Matches when every subpredicate matches.

Parameters:

subpredicates (PropertyPredicate)

Return type:

PropertyPredicate

static declared_by_schema(*schema_names)#

Matches a property whose name one of the named schemas declares.

Whether the prim carrying the property has that schema applied is not considered. A name is tried as both a type and an applied API schema, so a mixed list needs no partitioning.

Parameters:

schema_names (str)

Return type:

PropertyPredicate

static has_metadata(*paths)#

Matches a property resolving one of the named metadata paths.

Same path form and presence semantics as PrimPredicate.has_metadata(), against the property’s own metadata.

Parameters:

paths (str)

Return type:

PropertyPredicate

static has_name(*names)#

Matches the property’s name exactly.

Parameters:

names (str)

Return type:

PropertyPredicate

static in_namespace(*namespaces)#

Matches a property in a namespace, at : boundaries.

material:binding matches material:binding:physics but not material:bindingStrength, and not a property named material:binding itself – a name is in a namespace rather than equal to it.

Parameters:

namespaces (str)

Return type:

PropertyPredicate

static is_attribute()#

Matches an attribute.

Return type:

PropertyPredicate

static is_authored()#

Matches a property carrying an authored opinion rather than a schema fallback.

Return type:

PropertyPredicate

static is_custom()#

Matches a property carrying USD’s custom modifier.

Return type:

PropertyPredicate

static is_relationship()#

Matches a relationship.

Return type:

PropertyPredicate

static none()#

Matches no property. The prim is still populated, with its reserved values.

Return type:

PropertyPredicate

static not_(subpredicate)#

Matches when subpredicate does not.

Parameters:

subpredicate (PropertyPredicate)

Return type:

PropertyPredicate

static or_(*subpredicates)#

Matches when any subpredicate matches.

Parameters:

subpredicates (PropertyPredicate)

Return type:

PropertyPredicate

class PrimPredicateKind#

How an ovstage_population_prim_predicate_t matches.

A kind that takes values matches when any one of them matches: the values of a single predicate are a disjunction, never a conjunction. Requiring more than one condition is what AND is for.

__new__(value)#
NONE = 0#
ALL = 1#
AND = 2#
OR = 3#
NOT = 4#
HAS_PARENT = 5#
HAS_ANCESTOR = 6#
HAS_PROPERTY = 7#
HAS_TYPE = 8#
IS_A_TYPE = 9#
HAS_SCHEMA = 10#
HAS_APPLIED_SCHEMA = 11#
HAS_APPLIED_SCHEMA_IN_NAMESPACE = 12#
HAS_PATH = 13#
IS_UNDER_PATH = 14#
HAS_KIND = 15#
HAS_PURPOSE = 16#
HAS_METADATA = 17#
class PropertyPredicateKind#

How an ovstage_population_property_predicate_t matches.

Values disjoin exactly as they do for PrimPredicateKind.

__new__(value)#
NONE = 0#
ALL = 1#
AND = 2#
OR = 3#
NOT = 4#
DECLARED_BY_SCHEMA = 5#
HAS_NAME = 6#
IN_NAMESPACE = 7#
HAS_METADATA = 8#
IS_ATTRIBUTE = 9#
IS_RELATIONSHIP = 10#
IS_CUSTOM = 11#
IS_AUTHORED = 12#
On this page