Python API Reference#

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

ovstage#

Version and Constants#

__version__ = '0.1.1'#

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. Used by ovstage.PathDictionary.

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 record a geometric 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).

Parameters:

path_list (int)

Return type:

Query

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

Read

release_group(group)#
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.

semantic is the AttributeSemantic (or raw ovstage_attribute_semantic_t value) carried on the write. Geometric semantics (POINT/VECTOR/NORMAL/COLOR/QUATERNION/MATRIX/TEXTURE_COORDINATE) record a geometric 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()).

Parameters:

path_list (int)

Return type:

None

create_path_list(primpaths)#
Parameters:

primpaths (Sequence[int])

Return type:

int

create_path_list_from_strings(paths)#
Parameters:

paths (Sequence[str])

Return type:

int

destroy()#
Return type:

None

destroy_path_list(path_list)#

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

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)#
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.

__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.

property attribute: int#
property is_array: bool#

Whether this result group carries array-valued attribute rows.

property is_delete: bool#
property ordinal: int#
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).

__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#

An enumeration.

__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#

An enumeration.

__new__(value)#
HAS = 0#
IN = 1#
CONTAINS = 2#
PREFIX = 3#
LT = 4#
LE = 5#
GT = 6#
GE = 7#
class PrimMode#

An enumeration.

__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/ TEXTURE_COORDINATE) record a geometric role on the column; storage stays in the requested numeric dtype.

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.

  • 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).

Byte-string semantics (ASSET_STRING, PATH_EXPRESSION_STRING) keep ragged (kDLUInt, 8, 1) byte-row storage with NUL-separated authored sub-values.

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_STRING = 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#
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#

An enumeration.

__new__(value)#
NONE = 0#
RENDERING = 1#
PHYSICS = 2#
ALL = 3#
class HierarchyRelation#

An enumeration.

__new__(value)#
PARENT = 0#
CHILDREN = 1#
SIBLINGS = 2#
class HierarchyComputationModel#

An enumeration.

__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#

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`

This does not invalidate np.from_dlpack(group.dlpack(0)) for ovstage read/map groups: their manager_ctx does not own the backing allocation, and the view remains valid while the owning read/map operation is alive.

__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)#

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.

An invalid dtype (lanes == 0) is rejected with ValueError. A tensor wrapping a numpy array (built by make_dltensor()) is also checked against the array’s real size, so the returned view can never extend past that backing buffer; tensors from other producers carry no buffer size to check against and are trusted to describe themselves.

Parameters:

tensor (DLTensor)

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, 65535]: the value lands in the DLPack uint16 lane field, so anything outside that range raises ValueError (TypeError for non-integers) instead of silently wrapping to a bogus lane count (e.g. -1 becoming 65535).

Parameters:

lanes (int)

Return type:

DLDataType

ovstage.population#

USD population: composes USD content into the runtime stage (see Population (USD → ovstage)).

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:
error_message()#
Return type:

str

property ok: bool#
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.

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

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

On this page