API Commands#

The INavigation Python command APIs are called from the omni.anim.navigation.core module.

NavMesh events#

NavMesh baking and updates are reported via Events 2.0. Subscribe using the event dispatcher and these constants from omni.anim.navigation.core:

GLOBAL_EVENT_NAVMESH_UPDATED — Fires when the NavMesh finishes updating/baking. Payload: {'status': bool} (true on success, false on failure or cancellation).

GLOBAL_EVENT_NAVMESH_UPDATING — Fires during baking progress, at least once. Payload: {'progress': float} (0 to 1).

Example
import carb.eventdispatcher
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()

def on_navmesh_updated(event):
    print("NavMesh updated, success:", event.payload.get("status"))

dispatcher = carb.eventdispatcher.get_eventdispatcher()
sub = dispatcher.observe_event(
    observer_name="my_observer",
    event_name=nav.GLOBAL_EVENT_NAVMESH_UPDATED,
    on_event=on_navmesh_updated
)
inav.start_navmesh_baking()

INavigation.start_navmesh_baking#

Starts a task to asynchronously bake a NavMesh for the currently opened stage. Subscribe to NavMesh events (see above) to observe baking progress and completion.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking()

INavigation.start_navmesh_baking_and_wait#

Starts a task to bake a NavMesh for the currently opened stage and waits for baking to complete.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()

INavigation.cancel_navmesh_baking#

Cancels all pending NavMesh baking tasks.

Example

import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.cancel_navmesh_baking()

INavigation.is_navmesh_baking#

Checks if the NavMesh is currently baking.

Example

import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
baking = inav.is_navmesh_baking()

INavigation.get_navmesh#

Returns the currently baked NavMesh if available. The NavMesh is immutable.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()

INavigation.create_area#

Creates a new area and returns the index of the new area, or -1 if the max area count was exceeded.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
area_index = inav.create_area()

INavigation.destroy_area#

Destroys the area at the specified index.

Arguments

area_index (int): The index of the area to be removed.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
area_index = inav.create_area()
inav.destroy_area(area_index)

INavigation.get_area_count()#

Returns the number of navigation areas defined in the stage.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
area_count = inav.get_area_count()

INavigation.find_area#

Finds and returns area index of an area by name, or -1 if no area is found.

Arguments

area_name (str): The name of the area to find.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
not_walkable_area_index = inav.find_area("NotWalkable")

INavigation.get_area_name#

Returns the name of the area at the specified index.

Arguments

area_index (int): The index of the area to access. Should be between 0 and get_area_count() - 1.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
area_name = inav.get_area_name(0)

INavigation.set_area_name#

Sets the name of the area at the specified index.

Arguments

area_index (int): The index of the area to access. Should be between 0 and get_area_count() - 1.

area_name (str): The new area name.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
new_area_index = inav.create_area()
inav.set_area_name(new_area_index, "MyNewArea")

INavigation.get_area_color#

Returns the area color given an area index.

Arguments

area_index (int): The index of the area to access. Should be between 0 and get_area_count() - 1.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
area_color = inav.get_area_color(0)

INavigation.set_area_color#

Sets the color of the area at the specified area_index to area_color for debug visualization.

Arguments

area_index (int): The index of the area to access. Should be between 0 and get_area_count() - 1.

area_color (int): The color to set the area to for debug visualization.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
new_area_index = inav.create_area()
inav.set_area_name(new_area_index, "MyNewArea")

def rgb_to_int(red, green, blue):
    return (red << 16) + (green << 8) + blue

inav.set_area_color(new_area_index, rgb_to_int(255, 255, 0))

INavigation.get_area_default_cost#

Returns the default cost of the area at the specified index.

Arguments

area_index (int): The index of the area to access. Should be between 0 and get_area_count() - 1.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
default_cost = inav.get_area_default_cost(0)

INavigation.set_area_default_cost#

Sets the default cost of the area at the specified index.

Arguments

area_index (int): The index of the area to access. Should be between 0 and get_area_count() - 1.

default_cost (float): The default cost to set the area to. Must be >= 0 or -1 to specify the area is inaccessible.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
new_area_index = inav.create_area()
inav.set_area_name(new_area_index, "MyNewArea")
inav.set_area_default_cost(new_area_index, 10.0)

INavigation.set_random_seed#

Sets the random seed to allow for deterministic random outputs.

Arguments

randomizer_id (str): Identifies a randomizer to set the seed for. This enables each consumer of randomness to return its own deterministic outcomes.

seed (int): The seed to use for the randomizer.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
session = "robots"
inav.set_random_seed(session, 12345)
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
random_point = navmesh.query_random_point(session)

INavigation.get_cache_dir#

Returns the directory that stores various cached Navigation files.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
cache_dir = inav.get_cache_dir()

INavigation.clear_cache_dir#

Clears the cached NavMesh files in the cache dir.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.clear_cache_dir()

INavigation.get_area_names#

Returns a list of all navigation area names defined in the stage (same order as area indices).

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
names = inav.get_area_names()

INavigation.reorder_areas#

Atomically reorders the area table. Use this to avoid the destructive overwrite that can occur when reordering via individual set calls. Prim attributes are not renamed because nav:area stores area names (strings), not indices.

Arguments

new_order (list of int): A list of length get_area_count(). new_order[i] is the old area index that should occupy position i after reordering.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
count = inav.get_area_count()
# Swap first two areas
new_order = [1, 0] + list(range(2, count))
inav.reorder_areas(new_order)

The INavMesh Python command APIs are called from the omni.anim.navigation.core module.

NavAgentDesc#

Agent descriptor used by path and query APIs. Attributes: radius (float), height (float), collision_gap (float). Default constructor uses 0 for all. Pass as the agent argument to query_shortest_path, query_closest_point, and query_random_point when you need to override the baked agent bounds.

INavMesh.query_shortest_path#

Queries to find a shortest path on the NavMesh between a start and end position.

Arguments

start_pos (carb.Float3): The starting position of the path.

end_pos (carb.Float3): The ending position of the path.

agent (NavAgentDesc): Optional. Agent descriptor for the path query; default uses baked agent bounds.

area_costs (float[]): Optional. Overridden area costs for the path, or empty array to use default area costs.

straighten (bool): True to straighten the shortest path from A*, false to leave as-is.

prev_navmesh_path (INavMeshPath or None): Optional. Previous path to reuse for A*; can speed up incremental queries.

Example
import carb
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
start = carb.Float3(-200.0, 0.0, -30.0)
end = carb.Float3(250.0, 0.0, 150.0)
navmesh_path = navmesh.query_shortest_path(start_pos=start, end_pos=end)

INavMesh.query_closest_point#

Queries to find the closest point on the NavMesh to the specified target. Returns a tuple (point, island_id): the closest point (carb.Float3) and the island id (int), or (None, -1) if not found.

The NavMesh can contain several islands for navigation. You can filter by island or area.

Arguments

target (carb.Float3): The target position to be closest to.

agent (NavAgentDesc): Optional. Agent descriptor; default uses baked agent bounds.

area_indices (int[]): Optional. Array of area indices to restrict the search, or empty array for all areas.

search_island_id (int): Island to search, or -1 for any island.

Example
import carb
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
p = carb.Float3(-100.0, 0.0, -30.0)
closest_point, island_id = navmesh.query_closest_point(target=p)

INavMesh.query_random_point#

Queries to find a random point on the NavMesh. Returns a carb.Float3 or None if no point is found.

Arguments

randomizer_id (str): Identifies the randomizer (use with INavigation.set_random_seed for deterministic results).

agent (NavAgentDesc): Optional. Agent descriptor; default uses baked agent bounds.

area_probabilities (float[]): Optional. Indexed array of weighted probabilities per area.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
session = "robots"
inav.set_random_seed(session, 12345)
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
random_point = navmesh.query_random_point(session)

INavMesh.get_agent_min_height#

Returns the minimum height of the navigation agent for the baked NavMesh.

Example

import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
agent_min_height = navmesh.get_agent_min_height()

INavMesh.get_agent_min_radius#

Returns the minimum radius of the navigation agent for the baked NavMesh.

Example

import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
agent_min_radius = navmesh.get_agent_min_radius()

INavMesh.get_agent_max_radius#

Returns the maximum radius of the navigation agent for the baked NavMesh.

Example

import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
agent_max_radius = navmesh.get_agent_max_radius()

INavMesh.get_agent_max_step_height#

Returns the maximum step height of the navigation agent for the baked NavMesh.

Example

import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
agent_max_step_height = navmesh.get_agent_max_step_height()

INavMesh.get_agent_max_slope#

Returns the maximum slope angle of the navigation agent for the baked NavMesh.

Example

import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
agent_max_slope_angle = navmesh.get_agent_max_slope()

INavMesh.get_agent_min_island_radius#

Returns the minimum radius of the island that the agent can navigate for the baked NavMesh.

Example

import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
agent_min_island_radius = navmesh.get_agent_min_island_radius()

INavMesh.get_agent_sampling_distance#

Returns the sampling distance of the navigation agent for the baked NavMesh (distance between agent and NavMesh surface).

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
agent_sampling_distance = navmesh.get_agent_sampling_distance()

INavMesh.get_area_count#

Returns the number of areas defined in the baked NavMesh.

Example

import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
area_count = navmesh.get_area_count()

INavMesh.get_area_name#

Returns the name of the area at the specified index from the baked NavMesh.

Arguments

area_index (int): The index of the area to access. Should be between 0 and get_area_count() - 1.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
area_name = navmesh.get_area_name(0)

INavMesh.compute_area_costs#

Computes area costs for the baked NavMesh from a list of allowed area names. Areas in the list get cost 0; others get -1 (inaccessible).

Arguments

allowed_area_names (list of str): Optional. Names of areas that are traversable; default uses all areas.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
costs = navmesh.compute_area_costs(allowed_area_names=["Walkable"])

INavMesh.get_draw_triangles#

Returns a list of mesh triangles(carb.Float3) for each point in the triangle needed to visualize the NavMesh surface for a given area index.

Recommended for debug drawing only.

Arguments

area_index (int): The index of the area to access. Should be between 0 and get_area_count() - 1.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
triangles = navmesh.get_draw_triangles(0)

INavMesh.get_draw_lines#

Returns the lines points(carb.Float3) for each line point for visualization of the NavMesh outline.

Recommended for debug drawing only.

Arguments

border_only (bool): True if only the border lines be drawn; false if detailed edges.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
line_points = navmesh.get_draw_lines(border_only=True)

INavMesh.get_mesh_signature#

Returns a signature to define and encode a hash representation of the mesh data that was baked.

Example
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
signature = navmesh.get_mesh_signature()

The INavMeshPath Python command APIs are called from the omni.anim.navigation.core module.

INavMeshPath.get_point_count#

Returns the number of points on the path.

Example

import carb
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
start = carb.Float3(-200.0, 0.0, -30.0)
end = carb.Float3(250.0, 0.0, 150.0)
navmesh_path = navmesh.query_shortest_path(start_pos=start, end_pos=end)
count = navmesh_path.get_point_count()

INavMeshPath.get_points#

Returns an array of 2 or more points of type carb.Float3 for the path points/waypoints.

Example

import carb
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
start = carb.Float3(-200.0, 0.0, -30.0)
end = carb.Float3(250.0, 0.0, 150.0)
navmesh_path = navmesh.query_shortest_path(start_pos=start, end_pos=end)
points = navmesh_path.get_points()

INavMeshPath.closest_distance#

Computes the distance along the path that is closest to the given reference position.

Arguments

position (carb.Float3): Position for which the closest point on the path should be calculated.

out_path_position (carb.Float3): Output; pass a carb.Float3 to receive the closest point on the path.

out_path_tangent (carb.Float3): Output; pass a carb.Float3 to receive the tangent at that point.

Example
import carb
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
start = carb.Float3(-200.0, 0.0, -30.0)
end = carb.Float3(250.0, 0.0, 150.0)
navmesh_path = navmesh.query_shortest_path(start_pos=start, end_pos=end)
target = carb.Float3(100.0, 0.0, 100.0)
path_position = carb.Float3()
path_tangent = carb.Float3()
distance = navmesh_path.closest_distance(
    position=target,
    out_path_position=path_position,
    out_path_tangent=path_tangent
)

INavMeshPath.length#

Returns the total length of the path.

Example

import carb
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
start = carb.Float3(-200.0, 0.0, -30.0)
end = carb.Float3(250.0, 0.0, 150.0)
navmesh_path = navmesh.query_shortest_path(start_pos=start, end_pos=end)
path_length = navmesh_path.length()

INavMeshPath.evaluate_position#

Evaluates the position at the given distance along the path (0 to length()).

Arguments

distance (float): Distance along the path for which to evaluate the position.

Example

import carb
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
start = carb.Float3(-200.0, 0.0, -30.0)
end = carb.Float3(250.0, 0.0, 150.0)
navmesh_path = navmesh.query_shortest_path(start_pos=start, end_pos=end)
path_position = carb.Float3()
path_tangent = carb.Float3()
dist_along_path = navmesh_path.closest_distance(
    position=carb.Float3(100.0, 0.0, 100.0),
    out_path_position=path_position,
    out_path_tangent=path_tangent
)
position = navmesh_path.evaluate_position(dist_along_path)

INavMeshPath.evaluate_tangent#

Evaluates the tangent that corresponds to the given distance along the path.

Arguments

distance (carb.Float3): Distance for which the corresponding position is to be evaluated.

Example

import carb
import omni.anim.navigation.core as nav

inav = nav.acquire_interface()
inav.start_navmesh_baking_and_wait()
navmesh = inav.get_navmesh()
start = carb.Float3(-200.0, 0.0, -30.0)
end = carb.Float3(250.0, 0.0, 150.0)
navmesh_path = navmesh.query_shortest_path(start_pos=start, end_pos=end)

target = carb.Float3(100.0, 0.0, 100.0)
path_position = carb.Float3()
path_tangent = carb.Float3()
distance = navmesh_path.closest_distance(
    position=target,
    out_path_position=path_position,
    out_path_tangent=path_tangent
)
tangent = navmesh_path.evaluate_tangent(distance)

The authoring Python command APIs available from the omni.anim.navigation.core module.

CreateNavMeshVolumeCommand#

Creates a NavMesh Volume prim of include or exclude volume type.

Arguments

parent_prim_path (Sdf.Path): The parent prim path in the stage where to add the NavMesh volume.

volume_type (int): Use 0 for include, 1 for exclude. Constants NAVMESH_VOLUME_INCLUDE and NAVMESH_VOLUME_EXCLUDE are available from omni.anim.navigation.core.scripts.command.

position (Gf.Vec3d): Optional. World position for the new volume.

usd_context_name (str): Optional. Name of the USD context.

layer (Sdf.Layer): Optional. Layer to create the volume on; defaults to the stage edit target.

Example
import omni.kit.commands
import omni.usd
from pxr import Sdf

stage = omni.usd.get_context().get_stage()
omni.kit.commands.execute(
    "CreateNavMeshVolumeCommand",
    parent_prim_path=Sdf.Path("/World"),
    volume_type=0
)