Python API Reference#

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

ovstage#

Version and Constants#

__version__ = '0.1.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.

__init__(name=None)#
Parameters:

name (str | None)

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

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.

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

Parameters:
Return type:

Operation

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)#
Parameters:

timeout (int)

Return type:

QueryResult

class OrdinalQuery#
fetch(timeout=18446744073709551615)#
Parameters:

timeout (int)

Return type:

int

release()#
Return type:

Operation

class Read#
fetch_next(timeout=18446744073709551615)#
Parameters:

timeout (int)

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)#
Parameters:

timeout (int)

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)

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.

__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) → most recent value with ordinal <= N.

  • OrdinalRange.between(start, end) → all changes in [start, end].

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

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__(
*,
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 — mirroring how stage_api_test_utils.h authors its write tensors.

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. The numpy-specific overrides are not accepted on that path.

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.

Parameters:

tensor (DLTensor)

numpy_to_dldatatype(np_dtype, lanes=1)#

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

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:
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)

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