omni.isaac.lab.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.

备注

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 omni.isaac.debug_drawing module. It allows drawing of points and splines efficiently on the UI.

Classes

VisualizationMarkers	A class to coordinate groups of visual markers (loaded from USD).
VisualizationMarkersCfg	A class to configure a VisualizationMarkers.

Visualization Markers

class omni.isaac.lab.markers.VisualizationMarkers

基类：object

A class to coordinate groups of visual markers (loaded from USD).

This class allows visualization of different UI markers in the scene, such as points and frames. The class wraps around the UsdGeom.PointInstancer for efficient handling of objects in the stage via instancing the created marker prototype prims.

A marker prototype prim is a reusable template prim used for defining variations of objects in the scene. For example, a sphere prim can be used as a marker prototype prim to create multiple sphere prims in the scene at different locations. Thus, prototype prims are useful for creating multiple instances of the same prim in the scene.

The class parses the configuration to create different the marker prototypes into the stage. Each marker prototype prim is created as a child of the UsdGeom.PointInstancer prim. The prim path for the the marker prim is resolved using the key of the marker in the VisualizationMarkersCfg.markers dictionary. The marker prototypes are created using the omni.isaac.core.utils.create_prim() function, and then then instanced using UsdGeom.PointInstancer prim to allow creating multiple instances of the marker prims.

Switching between different marker prototypes is possible by calling the visualize() method with the prototype indices corresponding to the marker prototype. The prototype indices are based on the order in the VisualizationMarkersCfg.markers dictionary. For example, if the dictionary has two markers, “marker1” and “marker2”, then their prototype indices are 0 and 1 respectively. The prototype indices can be passed as a list or array of integers.

Usage:

The following snippet shows how to create 24 sphere markers with a radius of 1.0 at random translations within the range [-1.0, 1.0]. The first 12 markers will be colored red and the rest will be colored green.

import omni.isaac.lab.sim as sim_utils
from omni.isaac.lab.markers import VisualizationMarkersCfg, VisualizationMarkers

# Create the markers configuration
# This creates two marker prototypes, "marker1" and "marker2" which are spheres with a radius of 1.0.
# The color of "marker1" is red and the color of "marker2" is green.
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": VisualizationMarkersCfg.SphereCfg(
            radius=1.0,
            visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(0.0, 1.0, 0.0)),
        ),
    }
)
# Create the markers instance
# This will create a UsdGeom.PointInstancer prim at the given path along with the marker prototypes.
marker = VisualizationMarkers(cfg)

# Set position of the marker
# -- randomly sample translations between -1.0 and 1.0
marker_translations = np.random.uniform(-1.0, 1.0, (24, 3))
# -- this will create 24 markers at the given translations
# note: the markers will all be `marker1` since the marker indices are not given
marker.visualize(translations=marker_translations)

# alter the markers based on their prototypes indices
# first 12 markers will be marker1 and the rest will be marker2
# 0 -> marker1, 1 -> marker2
marker_indices = [0] * 12 + [1] * 12
# this will change the marker prototypes at the given indices
# note: the translations of the markers will not be changed from the previous call
#  since the translations are not given.
marker.visualize(marker_indices=marker_indices)

# alter the markers based on their prototypes indices and translations
marker.visualize(marker_indices=marker_indices, translations=marker_translations)

Methods:

__init__(cfg)	Initialize the class.
set_visibility(visible)	Sets the visibility of the markers.
is_visible()	Checks the visibility of the markers.
visualize([translations, orientations, ...])	Update markers in the viewport.

Attributes:

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

__init__(cfg: VisualizationMarkersCfg)

Initialize the class.

When the class is initialized, the UsdGeom.PointInstancer is created into the stage and the marker prims are registered into it.

备注

If a prim already exists at the given path, the function will find the next free path and create the UsdGeom.PointInstancer prim there.

参数:

cfg – The configuration for the markers.

抛出:

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)

Sets the visibility of the markers.

The method does this through the USD API.

参数:

visible – flag to set the visibility.

is_visible() → bool

Checks the visibility of the markers.

返回:

True if the markers are visible, False otherwise.

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 the viewport.

备注

If the prim PointInstancer is hidden in the stage, the function will simply return without updating the markers. This helps in unnecessary computation when the markers are not visible.

Whenever updating the markers, the input arrays must have the same number of elements in the first dimension. If the number of elements is different, the UsdGeom.PointInstancer will raise an error complaining about the mismatch.

Additionally, the function supports dynamic update of the markers. This means that the number of markers can change between calls. For example, if you have 24 points that you want to visualize, you can pass 24 translations, orientations, and scales. If you want to visualize only 12 points, you can pass 12 translations, orientations, and scales. The function will automatically update the number of markers in the scene.

The function will also update the marker prototypes based on their prototype indices. For instance, if you have two marker prototypes, and you pass the following marker indices: [0, 1, 0, 1], the function will update the first and third markers with the first prototype, and the second and fourth markers with the second prototype. This is useful when you want to visualize different markers in the same scene. The list of marker indices must have the same number of elements as the translations, orientations, or scales. If the number of elements is different, the function will raise an error.

小心

This function will update all the markers instanced from the prototypes. That means if you have 24 markers, you will need to pass 24 translations, orientations, and scales.

If you want to update only a subset of the markers, you will need to handle the indices yourself and pass the complete arrays to this function.

参数:

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

• orientations – Quaternion orientations (w, x, y, z) 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 in the scene.

抛出:

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

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

class omni.isaac.lab.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, omni.isaac.lab.sim.spawners.spawner_cfg.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.