Implementation:Facebookresearch Habitat lab GuiNavigationHelper

Knowledge Sources	Facebookresearch_Habitat_lab
Domains	Embodied_AI, Human_in_the_Loop, Navigation
Last Updated	2026-02-15 00:00 GMT

Overview

Helper class for controlling a humanoid agent from the HITL GUI, computing navigation paths, walk directions, and drawing visual navigation hints using cubic Bezier curves.

Description

GuiNavigationHelper bridges the gap between user input (from remote XR clients or mouse raycasting) and the humanoid agent's navigation system. It provides:

• Path computation: Uses the Habitat simulator's pathfinder to compute shortest paths from the agent's current position to a target, constrained to the largest indoor navmesh island.
• Walk direction extraction: Computes the humanoid's walking direction from path waypoints.
• Walk hints from remote client state: Reads the XR headset pose to determine walk direction, distance multiplier, and forward gaze direction for the humanoid controller.
• Walk hints from raycasting: Uses mouse ray casting against the floor plane to determine a target navigation position.
• Path visualization: Draws the computed navigation path with endpoint circles using the GUI drawer.
• Navigation hint drawing: Renders animated cubic Bezier curve-based navigation hints from the agent to a target, with alpha ramping and circular indicators.
• Environment reset handling: Recomputes the largest indoor navmesh island on environment reset.

The class manages per-user navigation state, supporting multi-user HITL scenarios.

Usage

Use GuiNavigationHelper in HITL application states to translate user input into humanoid agent movement commands. It is typically instantiated per agent and per user, and called each frame to compute walk hints that are then passed to the humanoid rearrange controller.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-hitl/habitat_hitl/environment/gui_navigation_helper.py
• Lines: 1-317

Signature

class GuiNavigationHelper:
    def __init__(
        self, gui_service: AppService, agent_idx: int, user_index: int
    ) -> None: ...

    def on_environment_reset(self) -> None: ...

    def draw_nav_hint_from_agent(
        self,
        forward_dir: mn.Vector3,
        end_pos: mn.Vector3,
        end_radius: float,
        color: mn.Color3,
    ) -> None: ...

    def get_humanoid_walk_hints_from_remote_client_state(
        self, visualize_path: bool = True
    ) -> Tuple[Optional[mn.Vector3], float, Optional[mn.Vector3]]: ...

    def get_humanoid_walk_hints_from_ray_cast(
        self, visualize_path: bool = True
    ) -> Tuple[Optional[mn.Vector3], float]: ...

Import

from habitat_hitl.environment.gui_navigation_helper import GuiNavigationHelper

I/O Contract

Inputs

Name	Type	Required	Description
gui_service	AppService	Yes	The HITL application service providing access to sim, GUI input, remote client state, and drawing tools
agent_idx	int	Yes	Index of the agent being controlled
user_index	int	Yes	Index of the user controlling the agent

Outputs (get_humanoid_walk_hints_from_remote_client_state)

Name	Type	Description
walk_dir	Optional[mn.Vector3]	The computed walking direction for the humanoid, or None if no movement is needed
distance_multiplier	float	Multiplier on translation speed (0.0 for rotation-only, 1.0 for full movement)
forward_gaze	Optional[mn.Vector3]	The direction the humanoid should face, or None if no rotation target

Usage Examples

Getting Walk Hints from XR Client

from habitat_hitl.environment.gui_navigation_helper import GuiNavigationHelper

nav_helper = GuiNavigationHelper(
    gui_service=app_service,
    agent_idx=0,
    user_index=0,
)

# On environment reset
nav_helper.on_environment_reset()

# Each frame, compute walk hints from XR headset pose
walk_dir, distance_multiplier, forward_gaze = (
    nav_helper.get_humanoid_walk_hints_from_remote_client_state(
        visualize_path=True
    )
)

# Pass to humanoid controller
if walk_dir is not None:
    humanoid_controller.calculate_walk_pose(
        walk_dir, distance_multiplier=distance_multiplier
    )

Drawing Navigation Hints

import magnum as mn

nav_helper.draw_nav_hint_from_agent(
    forward_dir=mn.Vector3(0.0, 0.0, -1.0),
    end_pos=mn.Vector3(3.0, 0.0, -5.0),
    end_radius=0.3,
    color=mn.Color3(0.0, 0.6, 1.0),
)