Reading Sensor Pointclouds

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/radar/main.cpp snippet read-radar-pointcloud

The radar C example uses the same map/read/unmap flow and additionally reads radar-specific RCS and RadialVelocityMs channels.

Common Channel Notes

The model auto-enables Counts and Flags, and they are delivered as ordinary PointCloud channel tensors. Other payload channels must be requested by the sensor PointCloud RenderVar. There are additional modality specific channels, see configuring-lidar-sensors and configuring-radar-sensors.

Troubleshooting

• Do not iterate over the full tensor allocation; only the first Counts[0] entries are delivered.
• When invalid entries may be present, filter the delivered range with (Flags[i] & 0x40) != 0.
• Lifetime. In Python the mapping is consumer-owned: a held DLPack consumer view (e.g. a NumPy array) keeps the buffer valid even after unmap, so lifetime is not a manual concern — copy only if you need data beyond the last view. In C, mapped tensors are valid until unmap — copy before unmapping if the data must outlive it.
• CPU examples can use NumPy or raw host pointers. GPU mappings require DLPack-compatible CUDA consumers or custom CUDA code plus correct unmap synchronization.
• For point-cloud tensors in C, use OVRTX_MAP_DEVICE_TYPE_CUDA for linear CUDA memory; OVRTX_MAP_DEVICE_TYPE_CUDA_ARRAY is intended for image-style outputs.
• Read channel names exactly as authored in the USDA PointCloud RenderVar.

Related Skills

• reading-render-output for general render-var mapping, lifetime, and sync rules.
• configuring-lidar-sensors and configuring-radar-sensors for authoring the PointCloud channel set.
• interpreting-lidar-pointclouds and interpreting-radar-pointclouds for channel-specific units and meaning.

Related Docs

• docs/sensors/sensor_outputs.rst -- conceptual reference for the render variable output format, mapping flow, tensor/param layout, and lifetime rules.

References

• Use the > **Source:** directives in this skill to locate tested snippets before reusing API patterns.
• Keep related skills, docs, and snippets synchronized when changing the workflow.