/reading-sensor-pointclouds

# 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: reading-sensor-pointclouds
description: >
  Mapping and reading lidar or radar PointCloud composite render-var tensors. Use
  when user asks how to access PointCloud output data, map Coordinates, Counts,
  Intensity, RCS, RadialVelocityMs, or TimeOffsetNs tensors, slice valid entries, or
  move sensor point clouds through CPU/CUDA memory. For channel meanings and units,
  use the interpreting-lidar-pointclouds or interpreting-radar-pointclouds skills.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - sensors
  - pointclouds
tools:
  - Read
  - Grep

Reading Sensor PointClouds

When to Use

Use this skill when the user asks how to access PointCloud output data, map Coordinates, Counts, Intensity, RCS, RadialVelocityMs, or TimeOffsetNs tensors, slice valid entries, or move sensor point clouds through CPU/CUDA memory. Use an interpreting pointcloud skill instead when the tensors are already available and the question is what their channels mean.

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++, or both.
• Sensor modality, RenderProduct path, PointCloud RenderVar prim path, and requested tensor channels.
• Mapping target: CPU, linear CUDA memory, or host copy after map.
• Valid-entry handling: `Counts`, `Flags`, desired slice/copy behavior, and whether data must outlive the mapping.
• 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 that the scene already requests a `PointCloud` output; use the lidar or radar configuration skills when the output channel set still needs to be authored.
• Use the modality-specific interpreting skills for channel units, coordinate-frame meaning, validity semantics, or visualization choices.

Instructions

1. Identify the sensor modality, RenderProduct, full PointCloud RenderVar prim path, target device, and named tensors to map. 2. Read the matching Python or C/C++ source snippet before writing API usage. 3. Map the composite `PointCloud` output, access tensors by exact channel name, and use `Counts[0]` to bound per-point/per-detection tensors. 4. Handle lifetime by language: in Python the mapping is consumer-owned — a held DLPack consumer view (e.g. a NumPy array) keeps the buffer valid past `unmap`, so lifetime isn't a manual concern; in C, copy data before unmapping if later code needs it. Keep CUDA synchronization aligned with the selected mapping target. 5. Combine configuration, reading, and interpretation skills only when the user asks for an end-to-end sensor workflow. 6. When changing code, run the narrow docs test or example 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

• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.

Overview

Sensor `PointCloud` render vars are composite outputs: mapping one render var exposes one named tensor per channel. `Counts[0]` is the delivered-entry count; delivered indices are `[0, Counts[0])`. It is not, by itself, proof that every delivered entry is valid.

CPU mapping is simplest for examples and printing. GPU mapping is also supported for point-cloud pipelines: Python uses `map(device=ovrtx.Device.CUDA)`, and C uses `OVRTX_MAP_DEVICE_TYPE_CUDA`. GPU-mapped tensors must be consumed as CUDA DLTensors by GPU-aware code, not as host pointers.

Explicit CPU and CUDA mappings report `kDLCPU` and linear `kDLCUDA` tensors, respectively. In C, `OVRTX_MAP_DEVICE_TYPE_DEFAULT` lets the runtime choose the most efficient representation; inspect each returned DLTensor's `device` field. Params remain CPU-resident for every mapping mode.

Python

Lidar PointCloud

> **Source:** `examples/python/lidar/main.py` snippet `read-lidar-pointcloud`

The lidar example maps the full `PointCloud` RenderVar prim path to CPU, reads `Coordinates`, `Counts`, `Intensity`, and `TimeOffsetNs`, then copies the delivered range out of the mapping for visualization. Its scene explicitly sets `includeInvalidPoints = false`, so every delivered entry is valid.

Radar PointCloud

> **Source:** `examples/python/radar/main.py` snippet `read-radar-pointcloud`

The radar example maps the full `PointCloud` RenderVar prim path to CPU, reads `Coordinates`, `Counts`, `Flags`, and `RadialVelocityMs`, then filters the delivered detection range with the `VALID` bit. Approaching radar detections can have negative radial velocity.

C

Lidar PointCloud

> **Source:** `examples/c/lidar/main.cpp` snippet `step-lidar-pointcloud` > **Source:** `examples/c/lidar/main.cpp` snippet `read-lidar-pointcloud`

The lidar C example fetches the stepped render results, finds the full `PointCloud` RenderVar prim path, maps it to CPU, reads named tensors, and unmaps after computing summary values.

Radar PointCloud

> **Source:** `examples/c/radar/main.cpp` snippet `step-radar-pointcloud` > **Source:** `examples/c/r