Navigation Mesh

Warning

Navigation Mesh is currently in Beta. For more information on pre-release and beta terms, please see the Omniverse License Agreement

Overview

Navigation Mesh, or “NavMesh”, is a tool used to compute a polygonal mesh that represents the traversable area of one or more agents. From that mesh, a linear path between two points can be generated.

Table of Contents

• Navigation Mesh

  • Overview

  • Setup

    • Enabling the Extension

    • Creating a NavMesh

    • NavMesh Bake Settings

    • Baked Mesh Settings

  • NavMesh Volumes

  • NavMesh Obstacles

  • Samples

  • Navigation Mesh API Commands

    • start_navmesh_baking

    • force_navmesh_baking

    • cancel_navmesh_baking

    • query_navmesh_path

    • validate_navmesh_point

    • closest_navmesh_point

    • random_navmesh_point

    • get_navmesh_event_stream

    • is_supported_navmesh_prim

    • get_navmesh_cache_dir

    • get_navmesh_volume_count

    • CreateNavMeshVolumeCommand

    • ApplyNavMeshObstacleSchema

    • RemoveNavMeshObstacleSchema

Setup

Enabling the Extension

Upon enabling the omni.anim.navigation.bundle Extension bundle, the Navigation menu will be accessible through Window > Navigation. The omni.anim.navigation.core Extension contains the backend, and the omni.anim.navigation.ui Extension contains the frontend elements.

Creating a NavMesh

NavMesh is a ground-based system and needs one or more meshes that represent a traversable area to build upon. It can build off of simple geometry or a custom polygon mesh.

Once the meshes are in the scene, generate a NavMesh by creating a new volume via Create > Navigation > NavMesh Volume. A new NavMesh volume will be created, and the NavMesh automatically built on the ground.

NavMesh Bake Settings

There are two ways to access the build settings:

• The Window > Navigation > NavMesh menu item

• Select any NavMeshVolume prim in the Stage and and in the Property panel, go to the NavMesh Volume section. Click on the Edit NavMesh Settings button.

Agent Option	Result
Height	The height of the agent size in scene units. The NavMesh will build only in areas where the agent height will fit.
Radius	The radius of the agent size in scene units.The NavMesh will build a buffer area against objects so that the agent cannot get too close to collide through.
Max Slope	The maximum angle in degrees that the NavMesh will build for. If the angle of the base geometry is greater than the slope angle setting, the NavMesh will not build.
Max Climb	The maximum height of objects the agent can step over.

Auto Rebake Option	Result
Auto Rebake	If enabled, upon every stage update the NavMesh will rebuild. WARNING: this can be computationally expensive with large and complex scenes.
Auto Rebake Delay	The time in seconds it takes for the NavMesh to trigger a rebuild after the scene has changed. This is good to use for large and complex scenes.

Cache Option	Result
Enabled	If checked, the system will cache previous results to speed up future bake times.

• Bake: Takes the current settings and attempts to create a NavMesh.

• Cancel All: Cancels the current NavMesh bake.

Baked Mesh Settings

The Baked Mesh panel is used for assigning which objects in the scene will influence NavMesh baking and which ones will not.

Note

By default the NavMesh will exclude rigid Physics bodies. This can be disabled by unchecking Rigid Bodies.

NavMesh Volumes

As many NavMesh Volumes can be added to the Scene as needed by going to Create > Navigation > NavMesh Volume.

NavMesh Volumes can be moved, rotated, and scaled to ensure the right fit. Multiple NavMesh volumes can be be placed near each other to extend new areas of the NavMesh.

NavMesh Obstacles

NavMesh Obstacles can be used to create exclusion zones. Any prim type can have a NavMesh Obstacle attached. To add an Obstacle, right click on a Stage prim and go to Add > Navigation > Add NavMesh Obstacle.

Obstacle shapes can be either boxes or cylinders, and the sizing and offsets can be adjusted.

NavMesh Obstacle Property	Result
Box Size	If the shape is a box, non-uniformly adjust the size of the shape independent of the primary volume
Cylinder Height	If the shape is a cylinder, adjust the height.
Cylinder Radius	If the shape is a cylinder, adjust the radius size.
Offset	Offset the position of the Obstacle volume from the Primary volume
Shape	Choose between Box and Cylinder shapes for the Obstacle volume.

Samples

A sample scene using the NavMesh are available in the Samples panel. They can be accessed via menu: Window > Browsers > Samples and going to the Animation > Navigation in the tree.

Tip

You are permitted to use the included Samples assets in your own projects. To download the sample scene use File > Collect As….

Navigation Mesh API Commands

All Navigation Mesh Python API commands are called from the omni.anim.navigation.core module.

start_navmesh_baking

Begins baking the NavMesh using current settings and utilizes the NavMesh cache if available. Return true if NavMesh baking is successfully requested. Return false if not (e.g. no suitable Mesh or NavMeshVolume in the stage).

Example

import omni.anim.navigation.core as nav
import omni.usd
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()
inav.start_navmesh_baking()

force_navmesh_baking

Returns true if NavMesh baking is successfully requested. Returns false if not (e.g. no suitable Mesh or NavMeshVolume in the stage).

Example

import omni.anim.navigation.core as nav
import omni.usd
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()
inav.force_navmesh_baking()

cancel_navmesh_baking

Cancel all NavMesh baking jobs.

Example

import omni.anim.navigation.core as nav
import omni.usd
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()
inav.cancel_navmesh_baking()

query_navmesh_path

Returns a path of valid points path points in between specified start and end points on the NavMesh. Path Points can be generated in and out of Play mode in Kit.

Arguments

• start_pos (carb::float3): The starting point of the path to query.
• end_pos (carb::float3): The end point of the path query.
• half_extents (carb::float3): The search extents for NavMesh if the point is not exactly on the NavMesh.
• overrideRayCastProportions (carb::float): Raycast is used to find potentially shortcuts on the path. Pass this optional parameter to config how long the raycast distance should be. The default value is 50 * agent radius.

Example

import omni.anim.navigation.core as nav
import omni.usd
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()

# Set the start and end points. If valid, new path points will be generated along the NavMesh.
path = inav.query_navmesh_path((24, 40, 63), (-960, 106, -258))
path_points = path.query_navmesh_path()
print(path_points.get_points())

validate_navmesh_point

Return true if the point is on the NavMesh. Returns false if no NavMesh is available or the point is not on the NavMesh.

Arguments

• point (carb::float3): The point to query.
• normal (carb::float3): The normal found.
• half_extents (carb::float3)): The search extents for NavMesh if the point is not exactly on the NavMesh.

Example

import omni.anim.navigation.core as nav
import omni.usd
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()
is_point_valid = inav.validate_navmesh_point(point=(24, 40, 63))

closest_navmesh_point

Returns true if a nearby point on the NavMesh is found. Returns false if no NavMesh is available or the point is not reachable based on the Half Extents.

Arguments

• target (carb::float3): The target position in the world to test against.
• point (carb::float3): The nearest point on the NavMesh, if found.
• normal (carb::float3): The normal found of the point on the NavMesh, if found.
• half_extents (carb::float3): The search extents for NavMesh if the point is not exactly on the NavMesh.

Example

import omni.anim.navigation.core as nav
import omni.usd
import carb
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()
closest_point = carb.Float3(0, 0, 0)
result = inav.closest_navmesh_point(target=(0, 10, 0), point=closest_point, half_extents=(10,10,10))
print(result, closest_point)

random_navmesh_point

Returns a random point located on the NavMesh.

Example

import omni.anim.navigation.core as nav
import omni.usd
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()
random_point = inav.random_navmesh_point()

get_navmesh_event_stream

Returns the events stream for the NavMesh system.

Example

import omni.anim.navigation.core as nav
import omni.usd
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()
event_stream = inav.get_navmesh_event_stream()

is_supported_navmesh_prim

Returns true if specified prim supports NavMesh. Returns false if it is an unsupported prim type.

Arguments

• primPath (str): The path to the prim to test.
• includeExcludedPrims (bool): If true, include prims that have the NavMeshExcludeAPI.
• includeRigidBodies (bool): If true, include rigid body prims even if the excludeRigidBodies setting is True.

Example

import omni.anim.navigation.core as nav
import omni.usd
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()
test_prim = inav.is_supported_navmesh_prim(
    primPath="/World/Cube",
    includeExcludedPrims=True,
    includeRigidBodies=False
)

get_navmesh_cache_dir

Returns the directory that stores the NavMesh Cache.

Example

import omni.anim.navigation.core as nav
import omni.usd
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()
cache_dir = inav.get_navmesh_cache_dir()

get_navmesh_volume_count

Returns the number of NavMesh volumes in the stage.

Example

import omni.anim.navigation.core as nav
import omni.usd
stage = omni.usd.get_context().get_stage()
inav = nav.acquire_interface()
volume_count = inav.get_navmesh_volume_count()

CreateNavMeshVolumeCommand

Creates a NavMesh Volume prim.

Arguments

• parent_prim_path (str): The parent prim path in the stage where to add the NavMesh volume.
• layer (str): The layer to create the NavMesh volume.

Example

import omni.usd, omni.kit
from pxr import Sdf
stage = omni.usd.get_context().get_stage()
omni.kit.commands.execute("CreateNavMeshVolumeCommand",
    parent_prim_path=Sdf.Path("/World"),
    layer=stage.GetRootLayer()
)

ApplyNavMeshObstacleSchema

Specialized command to apply NavMeshObstacleAPI that automatically infers size from prim(s)

Arguments

• prim_path (str): The prim path in the stage on which to remove the API schema
• usd_context_name (str): The USD context where this command should be used. Allows for this command to be used by multiple USD contexts simultaneously.

Example

import omni.kit
omni.kit.commands.execute("ApplyNavMeshObstacleSchema",
    prim_path="/World/MyCube",
)

RemoveNavMeshObstacleSchema

Removes the NavMeshObstacleAPI schema from prim(s).

Arguments

• prim_path (str): The prim path in the stage on which to remove the API schema
• usd_context_name (str): The USD context where this command should be used. Allows for this command to be used by multiple USD contexts simultaneously.

Example

import omni.kit
omni.kit.commands.execute("RemoveNavMeshObstacleSchema",
    prim_path="/World/MySphere",
)