Omniverse Realtime Viewer

Prim Info Display

Triggers

Use this skill for object information, show properties, inspect prim, selected object panels, tooltips, prim info, read_attribute, or metadata requests.

Use this skill when a selected object should reveal readable USD information.

What To Show

Minimum useful fields:

• Display name: prim.GetName()

• Full path: str(prim.GetPath())

• Type: prim.GetTypeName()

• Kind/model metadata if available.

• Transform: authored xformOp:* values and computed world transform.

• Material: direct or inherited material binding path.

• Visibility/purpose and selected variant sets when relevant.

For broad property inspection, use stage-hierarchy serialization rules and cap large arrays.

Summary And Detail Contract

For asset review, show a compact summary immediately, then organize the full payload into a detailed read-only table. The summary should contain the name, full path, type name, classification or kind when authored, child count, and available state flags: active, defined, loaded, abstract, and instance or instance-proxy. Treat these fields as optional because a prim type or the active runtime may not expose every one.

Group the detailed table so a reviewer can scan rather than parse an arbitrary JSON blob:

Use a compact placeholder while a newly selected prim's detail request is in flight. Do not retain the prior prim's table until the response arrives.

Preferred Data Path

Use OVStage runtime reads for current inspector attributes first:

1. Use the runtime query adapter with a specific or all-attribute filter to discover available attributes and descriptors.

2. Use runtime scalar reads for one value per prim, such as omni:xform, radius-like numeric values, tokens, or shader inputs.

3. Use runtime array reads for variable-length values, such as mesh points, normals, or faceVertexCounts.

4. Use pxr only for variant sets, relationship targets, material binding strings, and USD metadata until runtime APIs cover those at the same fidelity.

import numpy as np

COMMON_ATTRS = ["omni:xform", "visibility", "purpose", "inputs:Fader"]

def runtime_prim_info(runtime, path: str) -> dict:
    query = runtime.query_prims(
        attribute_filter_mode="specific",
        attribute_names=COMMON_ATTRS,
    )
    attrs = query.get(path, {})
    data = {
        "name": path.rsplit("/", 1)[-1],
        "path": path,
        "attributes": sorted(attrs.keys()),
    }
    if "omni:xform" in attrs:
        values = runtime.read_attribute("omni:xform", [path])
        data["local_transform"] = np.asarray(values).reshape(1, 4, 4)[0].tolist()
        data["world_transform"] = runtime.read_world_transform(path).tolist()
    if "inputs:Fader" in attrs:
        values = runtime.read_attribute("inputs:Fader", [path])
        data["fader"] = float(np.asarray(values).reshape(-1)[0])
    return data

read_world_transform is an application adapter, not an OVStage attribute alias. It composes current ancestor locals and reset-stack flags through the shared transform model. Read both inspector transforms from the same runtime snapshot.

Do not force every inspector field through pxr just because the UI already has a worker. The worker should augment runtime data with variants, material relationship strings, and authored metadata when those fields are requested. Direct OVRTX reads are for renderer diagnostics or legacy pre-OVStage viewers, not the default inspector path.

Delivery-Mode Field Sets

The exact fields shown differ by delivery path:

Runtime Property Query Pattern

For selected-prim panels, keep a small allowlist of high-value attributes and cap payload size before sending over a data channel:

def read_selected_attributes(runtime, path: str, attr_names: list[str]) -> dict:
    info = runtime.query_prims(
        attribute_filter_mode="specific",
        attribute_names=attr_names,
    ).get(path, {})

    values = {}
    for name, desc in info.items():
        if desc.is_array:
            arrays = runtime.read_array_attribute(name, [path])
            values[name] = np.asarray(arrays[path])[:1000].copy().tolist()
        else:
            value = runtime.read_attribute(name, [path])
            values[name] = np.asarray(value).copy().tolist()
    return values

Token/path-valued data may surface as numeric token or path IDs rather than user-facing strings. Keep pxr fallback for readable visibility tokens, material binding targets, relationship lists, and variant sets when the UI needs display strings:

from pxr import UsdGeom, UsdShade

def prim_info(stage, path: str) -> dict:
    prim = stage.GetPrimAtPath(path)
    if not prim or not prim.IsValid():
        return {}
    data = {"name": prim.GetName(), "path": str(prim.GetPath()), "type": prim.GetTypeName()}
    xformable = UsdGeom.Xformable(prim)
    if xformable:
        data["world_transform"] = [list(xformable.ComputeLocalToWorldTransform(Usd.TimeCode.Default()).GetRow(i)) for i in range(4)]
    binding = UsdShade.MaterialBindingAPI(prim).ComputeBoundMaterial()[0]
    if binding:
        data["material"] = str(binding.GetPath())
    data["properties"] = {a.GetName(): serialize_value(a.Get()) for a in prim.GetAttributes()}
    return data

UI Patterns

• Sidebar panel: best for dense property lists and stage-tree selection.

• Floating panel: best for visual selection feedback near the selected object.

• Tooltip: best for short name/type/path hints.

Do not duplicate a full editor property inspector unless the user asks for the ovui editor path.

Floating Panel Projection

Build a ui.Placer in the viewport ZStack, store a world-space anchor, and update the projected screen position each frame. Use the rendered image rect, not the full widget rect, so letterboxing does not offset the panel.

def world_to_screen(point_3d, view_matrix, proj_matrix, viewport_w, viewport_h):
    point = np.array([point_3d[0], point_3d[1], point_3d[2], 1.0], dtype=np.float64)
    view = np.asarray(view_matrix, dtype=np.float64).reshape(4, 4)
    proj = np.asarray(proj_matrix, dtype=np.float64).reshape(4, 4)
    clip = proj @ (view @ point)
    depth = float(clip[3])
    if abs(depth) < 1e-9:
        return math.nan, math.nan, depth
    ndc = clip[:3] / clip[3]
    return (ndc[0] * 0.5 + 0.5) * viewport_w, (ndc[1] * 0.5 + 0.5) * viewport_h, depth

placer = ui.Placer(offset_x=8, offset_y=8, width=0, height=0, stable_size=False, visible=False)
with placer:
    build_prim_info_panel()

def update_overlay_position(world_center):
    vp_w, vp_h = viewport.widget_size()
    image_x, image_y, image_w, image_h = viewport.image_content_rect()
    sx, bottom_y, depth = world_to_screen(
        world_center,
        camera.get_view_matrix(),
        camera.get_projection_matrix(aspect_ratio=image_w / max(1.0, image_h)),
        int(round(image_w)),
        int(round(image_h)),
    )
    sx = image_x + sx
    sy = image_y + (image_h - bottom_y)  # top-left UI origin
    if depth <= 0.0 or not (math.isfinite(sx) and math.isfinite(sy)):
        placer.visible = False
        return
    panel_w, panel_h = 260, max(130.0, float(getattr(panel_container, "computed_height", 0.0) or 0.0))
    placer.offset_x = min(max(8.0, sx - panel_w * 0.5), max(8.0, vp_w - panel_w - 8.0))
    placer.offset_y = min(max(8.0, sy - panel_h - 80.0), max(8.0, vp_h - panel_h - 8.0))
    placer.visible = True

Use bbox top-center as the anchor when available; fall back to local-to-world translation. Hide the panel when selection clears, the prim is invalid after scene switching, or the projected point is behind the camera.

Streaming Overlay Path

For server-side WebRTC overlays, viewport-overlays owns the headless ovui composition path. It uses the same info fields and projection idea but renders to an alpha frame that is blended over the stream.

See also: stage-attribute-reads, stage-hierarchy, object-selection, viewport-overlays, local-viewer, ovstage-data-plane.

Adding This To An Existing Omniverse Realtime Viewer

• Add server/prim_info.py or extend server/stage_queries.py with selected-prim info queries backed by OVStage runtime queries and read_attribute() / read_array_attribute() wrappers.

• Maintain current selected prim path, latest info payload, and an invalidation flag for scene reloads.

• Use stageSelectionChanged as the trigger to request or push fresh prim info.

• Reuse getPropertiesRequest -> getPropertiesResponse for dense property panels.

• Do not emit only getPropertiesResult for the current React inspector; it listens for getPropertiesResponse.

• Frontend wires a PrimInfoPanel to selection state and property responses. In React, update a selectedPathRef.current synchronously inside the stageSelectionChanged handler, clear the panel, then request properties. Accept getPropertiesResponse only when response.prim_path equals that ref. Do not guard with closure-captured selectedPath; fast property responses can otherwise be dropped after selection changes.

• Local Omniverse Realtime Viewer apps can use a sidebar or viewport overlay tied directly to the local stage query object.

• Include name, path, type, transform, material, visibility, purpose, metadata, and variants when available.

• Prefer OVStage runtime attribute reads for transform and numeric/tensor values; use pxr for variant sets, relationships, material binding strings, and USD metadata.

• Cap large arrays and serialize USD values using stage-hierarchy rules before sending JSON. For inspector panels, send counts plus a small preview for mesh buffers such as points, normals, faceVertexIndices, and UV primvars; do not send complete geometry arrays over WebRTC.

• Hide or clear the panel when selection clears, the scene switches, or the prim becomes invalid.

• Floating panels need bbox anchors, camera projection, and viewport letterbox offsets from the viewer shell.