/picking-selection

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
#
# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
# property and proprietary rights in and to this material, related
# documentation and any modifications thereto. Any use, reproduction,
# disclosure or distribution of this material and related documentation
# without an express license agreement from NVIDIA CORPORATION or
# its affiliates is strictly prohibited.
name: picking-selection
description: >
  Viewport picking, marquee selection, pick-hit decoding, pickability, and selection
  outline drawing. Use when implementing click picking, drag selection, printing picked
  prim names, or highlighting selected prims.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - picking
  - selection
tools:
  - Read
  - Grep

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 outline width and fill mode.
• Runtime per-group state controls outline and fill colors. 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 befo