isaaclab.markers

Sub-package for marker utilities to simplify creation of UI elements in the GUI.

Currently, the sub-package provides the following classes:

• VisualizationMarkers for creating a group of markers using UsdGeom.PointInstancer.

Note

For some simple use-cases, it may be sufficient to use the debug drawing utilities from Isaac Sim. The debug drawing API is available in the isaacsim.util.debug_drawing module. It allows drawing of points and splines efficiently on the UI.

Classes

VisualizationMarkers	Coordinate groups of visual markers across active visualizer backends.
VisualizationMarkersCfg	A class to configure a VisualizationMarkers.

Visualization Markers

class isaaclab.markers.VisualizationMarkers

Bases: object

Coordinate groups of visual markers across active visualizer backends.

This class allows visualization of different UI markers in the scene, such as points, frames, arrows, and shapes. Marker prototypes are reusable templates that define variations of objects to visualize. For example, a sphere marker prototype can be used to create many sphere marker instances at different locations.

The class parses the configuration to create the marker prototypes in each active backend. The marker prototype name comes from the key in the VisualizationMarkersCfg.markers dictionary, and prototype indices are based on the dictionary order. For example, if the dictionary has two markers, "marker1" and "marker2", their prototype indices are 0 and 1 respectively. These indices can be passed to visualize() as a list or array of integers.

Switching between marker prototypes is possible by calling visualize() with the corresponding prototype indices. The marker transforms are updated only for the arguments that are provided; omitted translations, orientations, scales, or marker indices are left unchanged when supported by the active backend.

Usage:

The following snippet creates 24 sphere markers at random translations. The first 12 markers use the first prototype and the rest use the second prototype.

import numpy as np

import isaaclab.sim as sim_utils
from isaaclab.markers import VisualizationMarkers, VisualizationMarkersCfg

cfg = VisualizationMarkersCfg(
    prim_path="/World/Visuals/testMarkers",
    markers={
        "marker1": sim_utils.SphereCfg(
            radius=1.0,
            visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(1.0, 0.0, 0.0)),
        ),
        "marker2": sim_utils.SphereCfg(
            radius=1.0,
            visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.0, 1.0, 0.0)),
        ),
    },
)

marker = VisualizationMarkers(cfg)
marker_translations = np.random.uniform(-1.0, 1.0, (24, 3))

# This creates 24 markers using the first prototype because marker
# indices are not given.
marker.visualize(translations=marker_translations)

# 0 -> marker1, 1 -> marker2. Since translations are omitted here,
# only the marker prototypes are changed.
marker_indices = [0] * 12 + [1] * 12
marker.visualize(marker_indices=marker_indices)

# Update both marker prototypes and translations.
marker.visualize(marker_indices=marker_indices, translations=marker_translations)

The public API intentionally remains the historical marker API: set_visibility(), is_visible(), and visualize(). Backend details are delegated to Kit and Newton marker implementations.

Methods:

__init__(cfg)	Initialize visualization marker backends from the active simulation context.
set_visibility(visible)	Set marker visibility for all initialized backends.
is_visible()	Return whether the marker group is visible.
visualize([translations, orientations, ...])	Update markers in all initialized visualizer backends.

Attributes:

num_prototypes	The number of marker prototypes available.
count	The total number of marker instances.

__init__(cfg: VisualizationMarkersCfg)

Initialize visualization marker backends from the active simulation context.

Parameters:

cfg – The configuration for the markers.

Raises:

ValueError – When no markers are provided in the cfg.

property num_prototypes: int

The number of marker prototypes available.

property count: int

The total number of marker instances.

set_visibility(visible: bool)

Set marker visibility for all initialized backends.

is_visible() → bool

Return whether the marker group is visible.

visualize(translations: np.ndarray | torch.Tensor | None = None, orientations: np.ndarray | torch.Tensor | None = None, scales: np.ndarray | torch.Tensor | None = None, marker_indices: list[int] | np.ndarray | torch.Tensor | None = None)

Update markers in all initialized visualizer backends.

Note

If the markers are hidden, the function returns without updating backend marker state. This avoids unnecessary work while debug visualization is disabled.

Whenever updating the markers, the input arrays must have the same number of elements in the first dimension. Backends generally require all per-marker arrays to describe the same number of marker instances.

The function supports dynamic updates of the marker count. For example, if you have 24 points to visualize, you can pass 24 translations, orientations, and scales. If you later want to visualize only 12 points, you can pass arrays with 12 rows and the backends will update the number of marker instances.

The function also updates marker prototypes based on prototype indices. For instance, if there are two marker prototypes and you pass marker indices [0, 1, 0, 1], the first and third markers use the first prototype and the second and fourth markers use the second prototype.

Caution

This function updates all markers instanced from the prototypes. If you want to update only a subset of markers, handle the indexing externally and pass complete arrays to this function.

Parameters:

• translations – Translations w.r.t. parent prim frame. Shape is (M, 3). Defaults to None, which means left unchanged.

• orientations – Quaternion orientations (x, y, z, w) w.r.t. parent prim frame. Shape is (M, 4). Defaults to None, which means left unchanged.

• scales – Scale applied before any rotation is applied. Shape is (M, 3). Defaults to None, which means left unchanged.

• marker_indices – Decides which marker prototype to visualize. Shape is (M). Defaults to None, which means left unchanged provided that the total number of markers is the same as the previous call. If the number of markers is different, the function will update the number of markers.

Raises:

• ValueError – When input arrays do not follow the expected shapes.

• ValueError – When the function is called with all None arguments.

class isaaclab.markers.VisualizationMarkersCfg

A class to configure a VisualizationMarkers.

Attributes:

prim_path	The prim path where the UsdGeom.PointInstancer will be created.
markers	The dictionary of marker configurations.

prim_path: str

The prim path where the UsdGeom.PointInstancer will be created.

markers: dict[str, SpawnerCfg]

The dictionary of marker configurations.

The key is the name of the marker, and the value is the configuration of the marker. The key is used to identify the marker in the class.