nvidia-omniverse/ovrtx/picking-selection

Picking and Selection

When to Use

Use this skill when implementing click picking, drag selection, printing picked prim names, or highlighting selected prims.

Inputs

Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.

• Target API surface: Python, C/C++, USD, or a combination.
• RenderProduct path, plus the UI click or marquee coordinates converted to normalized RenderProduct coordinates.
• Desired pick result handling: path ID decoding, picked prim names, pickability filtering, or selected-path storage.
• Selection outline requirements: group IDs, colors, fill mode, and whether the picking RenderProduct must be pinned to CUDA-visible GPU 0.
• Repository source snippets referenced below. Treat these snippets as the API source of truth.

Prerequisites

• Use an ovrtx checkout that contains the referenced examples and docs tests.
• Read the relevant > **Source:** snippet before writing or explaining API usage.
• Confirm the picking RenderProduct is pinned to CUDA-visible GPU 0; use render-product-device-pinning when that USD authoring is missing.
• Use reading-render-output only for general render-var readback; pick hit decoding follows this skill's snippets.

Instructions

1. Identify whether the task is click picking, marquee selection, pickability filtering, path decoding, or selection-outline styling.
2. Ensure the RenderProduct used for picking is running on CUDA-visible GPU 0 before adding pick queries.
3. Read the matching Python or C snippet for enqueueing the pick query, mapping the hit buffer, and resolving prim path IDs.
4. Keep selection outline group assignment separate from pick-hit decoding; use the style/group snippets only after the selected paths are known.
5. When changing code, run the picking-selection docs test that owns the snippet whenever practical.

Output Format

• For explanations, cite the relevant API names, source snippets, and caveats.
• For code changes, summarize the files changed, snippets affected, and validation run.

Scripts

This skill has no scripts.

Limitations

• Picking currently only works for RenderProducts running on CUDA-visible GPU 0.
• Outline dashing or stippling is not supported by the underlying RTX outline pipeline.
• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.

Overview

Picking is a RenderProduct-space query consumed by the next renderer step. The result is a synthetic render var named ovrtx_pick_hit / OVRTX_RENDER_VAR_PICK_HIT. Each hit stores a path-dictionary id, not a string.

Picking coordinates are normalized RenderProduct coordinates, not window or pixel coordinates. Use [0, 1] top-left-origin semantics:

• x = 0 is the left edge, and x = 1 is the right edge.
• y = 0 is the top edge, and y = 1 is the bottom edge.
• The rectangle uses the same convention as the old pixel API: right_ndc and

bottom_ndc mark the edge just past the last included pixel.

• The old one-pixel rectangle [50, 50, 51, 51] on a 100 x 100 RenderProduct is

[0.50, 0.50, 0.51, 0.51] in NDC.

• The full RenderProduct is [0, 0, 1, 1].
• A one-pixel pick at pixel (px, py) on a width x height RenderProduct is:

left_ndc = px / width, top_ndc = py / height, right_ndc = (px + 1) / width, bottom_ndc = (py + 1) / height.

• Callers should clamp UI drags to [0, 1]. The API rejects out-of-bounds

coordinates, but old pixel-space values that already fall inside [0, 1] are valid NDC and can be ambiguous during migration (boundary values may be clamped to the valid range to account for floating-point roundoff).

Current limitation: picking only works for RenderProducts running on CUDA-visible GPU 0. In multi-GPU scenes, restrict picking RenderProducts to CUDA-visible GPU 0 by authoring uint[] deviceIds = [0]. deviceIds is an allow-list of indices into CUDA_VISIBLE_DEVICES; ovrtx may choose any CUDA-visible GPU from the list.

Selection drawing is separate from picking. The selection outline pass is enabled by default. Set non-zero selection outline group ids on the prims that should be outlined, and write group 0 to clear an outline. Pass selection_outline_enabled=False at renderer creation to disable the global pass.

Selection styling has two layers:

• Global renderer-creation state controls the default outline width and fill mode.
• Runtime per-group state controls outline color, fill color, and outline width.

Omitting per-group width leaves that group's width unchanged, so it keeps the default. Prims opt into a style by passing that group's id to Renderer.set_selection_outline_group() / ovrtx_set_selection_outline_group().

Fill colors are visible only when the renderer is created with a fill mode that uses per-group fill color, such as GROUP_FILL_COLOR / OVRTX_SELECTION_FILL_MODE_GROUP_FILL_COLOR.

Workflow

1. Load the stage and identify the RenderProduct path. For picking, ensure that RenderProduct is restricted to CUDA-visible GPU 0 in USD.
2. Convert UI/window input into normalized RenderProduct coordinates.
3. Queue a pick query before the next step. Use a one-pixel-equivalent NDC rectangle for click picking and a larger rectangle for marquee selection.
4. Step the renderer for the same RenderProduct.
5. Find and CPU-map the synthetic pick-hit render var.
6. Validate the magic / version params and read named tensors such as primPath.
7. Resolve primPath ids through the renderer path dictionary when reporting picked prim names.
8. Print or otherwise report the resolved prim names.
9. Optionally set group 0 to clear the previous selection and group 1 to outline the new selection.

Python

Create a renderer for selection outlines

Source: tests/docs/python/test_picking_selection.py snippet doc-create-selection-outline-renderer-python

Enqueue a click or marquee pick

Source: tests/docs/python/test_picking_selection.py snippet doc-enqueue-pick-query-python

Decode the pick-hit buffer

Wrap numeric primPath tensor elements as ovrtx.PrimPath handles before passing them to path resolution, selection, or pickability APIs. Those APIs reject bare integers and other handle kinds.

Source: tests/docs/python/test_picking_selection.py snippet doc-read-pick-hit-buffer-python

Resolve picked prim names

Source: tests/docs/python/test_picking_selection.py snippet doc-resolve-picked-prim-paths-python

Resolve path ids before printing names. Selection outline calls accept duplicate path ids or strings; the last occurrence wins. Print the resolved strings, not the numeric path ids.

Mark prims pickable or unpickable

Source: tests/docs/python/test_picking_selection.py snippet doc-set-pickable-python

Draw selection outlines

Source: tests/docs/python/test_picking_selection.py snippet doc-set-selection-outline-group-python

Clear selection outlines

Source: tests/docs/python/test_picking_selection.py snippet doc-clear-selection-outline-group-python

Create a styled selection renderer

Source: tests/docs/python/test_picking_selection.py snippet doc-create-styled-selection-renderer-python

Configure global style state at renderer creation:

• selection_outline_width is the default outline thickness in pixels (0..15,

where 0 draws no outline).

• selection_fill_mode controls whether selected prim interiors are filled and

which color source they use.

Changing these global settings requires recreating the renderer. Per-group SelectionGroupStyle.outline_width overrides the default thickness at runtime.

Set per-group selection styles

Source: tests/docs/python/test_picking_selection.py snippet doc-set-selection-group-styles-python

Use Renderer.set_selection_group_styles() to assign outline color, fill color, and outline width to group ids. Omitting outline_width leaves that group's width unchanged, so it keeps the default. The operation is stream-ordered and affects subsequent steps. Later writes to the same group id win.

Assign styled groups to prims

Source: tests/docs/python/test_picking_selection.py snippet doc-assign-selection-style-groups-python

Use Renderer.set_selection_outline_group() to choose which styled selection group each prim uses. This is the per-prim part of selection styling.

C

Create a renderer with outline drawing enabled

Source: tests/docs/c/test_picking_selection.cpp snippet doc-create-selection-outline-renderer-c

Enqueue a click or marquee pick

Source: tests/docs/c/test_picking_selection.cpp snippet doc-enqueue-pick-query-c

Decode the pick-hit buffer

Source: tests/docs/c/test_picking_selection.cpp snippet doc-read-pick-hit-buffer-c

The CPU primPath column is backed by contiguous uint64_t IDs, matching its DLPack dtype. Apply the tensor byte offset and read through const uint64_t* in C/C++, then construct each handle with ovx_primpath_t{ids[i]}. Keep handles typed outside this tensor boundary; an array of single-field handle structs is not a uint64_t array for C++ pointer arithmetic.

Resolve picked prim names

Source: tests/docs/c/test_picking_selection.cpp snippet doc-resolve-picked-prim-paths-c

The helper used by the C snippet shows the path dictionary calls needed to turn an ovx_primpath_t into a UTF-8 path.

Source: tests/docs/c/helpers.h snippet doc-resolve-primpath-helper-c

Mark prims pickable or unpickable

Source: tests/docs/c/test_picking_selection.cpp snippet doc-set-pickable-c

Draw selection outlines

Source: tests/docs/c/test_picking_selection.cpp snippet doc-set-selection-outline-group-c

Clear selection outlines

Source: tests/docs/c/test_picking_selection.cpp snippet doc-clear-selection-outline-group-c

Create a styled selection renderer

Source: tests/docs/c/test_picking_selection.cpp snippet doc-create-styled-selection-renderer-c

Configure global style state at renderer creation with ovrtx_config_entry_selection_outline_width() (default thickness) and ovrtx_config_entry_selection_fill_mode(). Changing these global settings requires recreating the renderer. Per-group outline_width on ovrtx_selection_group_style_t overrides the default thickness at runtime.

Set per-group selection styles

Source: tests/docs/c/test_picking_selection.cpp snippet doc-set-selection-group-styles-c

Use ovrtx_set_selection_group_styles() to assign outline color, fill color, and outline width to group ids. Omitting outline_width leaves that group's width unchanged, so it keeps the default. The operation is stream-ordered and affects subsequent steps. Later writes to the same group id win.

Assign styled groups to prims

Source: tests/docs/c/test_picking_selection.cpp snippet doc-assign-selection-style-groups-c

Use ovrtx_set_selection_outline_group() to set each prim's outline group id. The group id selects which per-group style that prim uses.

Key Types / Functions