Implementation:Facebookresearch Habitat lab GuiThrowHelper

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

Overview

GuiThrowHelper is a helper class for computing and visualizing a parabolic throw trajectory from a humanoid agent to a mouse-ray-determined floor target in the HITL framework.

Description

The GuiThrowHelper class provides functionality for throwing objects from a humanoid agent's position to a target on the floor. The target is computed by intersecting the mouse ray with a hardcoded floor plane (y=0.15, corresponding to ReplicaCAD floor height).

The compute_velocity_throw method calculates the initial velocity vector required to throw an object from a start point to an end point under projectile motion physics. It computes the time of flight based on vertical displacement and gravity, then derives the x, y, and z velocity components. It also generates a set of 10 interpolated path points along the parabolic trajectory for visualization.

The viz_and_get_humanoid_throw method:

1. Casts the mouse ray to find the floor intersection point.
2. Computes the throw velocity from the humanoid's root position to the floor target.
3. Draws the parabolic path with endpoint circles on the server viewport using GuiDrawer.
4. Returns the velocity vector to be applied to the thrown object.

If the mouse ray is invalid (pointing upward or below floor height), the method returns None.

Usage

Use GuiThrowHelper in HITL rearrangement or interactive tasks where users need to throw objects from their humanoid agent to a target location. The helper provides both the physics computation and visual path preview.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-hitl/habitat_hitl/environment/gui_throw_helper.py
• Lines: 1-88

Signature

class GuiThrowHelper:
    def __init__(self, gui_service: AppService, agent_idx: int):
        ...

    def compute_velocity_throw(self, start_point, end_point, gravity=-9.8):
        ...

    def viz_and_get_humanoid_throw(self):
        ...

Import

from habitat_hitl.environment.gui_throw_helper import GuiThrowHelper

I/O Contract

Inputs

Name	Type	Required	Description
gui_service	AppService	Yes	The HITL application service providing access to the simulator, GUI input, and GUI drawer.
agent_idx	int	Yes	The index of the agent performing the throw.

Inputs (compute_velocity_throw)

Name	Type	Required	Description
start_point	Vector3/array-like	Yes	The 3D starting position of the throw.
end_point	Vector3/array-like	Yes	The 3D target position of the throw.
gravity	float	No	Gravity acceleration value. Defaults to -9.8.

Outputs

Name	Type	Description
compute_velocity_throw()	tuple(mn.Vector3, list[mn.Vector3])	The initial velocity vector and a list of 10 path points along the parabolic trajectory.
viz_and_get_humanoid_throw()	Optional[mn.Vector3]	The velocity vector for the throw, or None if the mouse ray is invalid.
(visual output)	Rendered path	Purple parabolic path with endpoint circles drawn on the server viewport.

Usage Examples

Basic Usage

from habitat_hitl.environment.gui_throw_helper import GuiThrowHelper
from habitat_hitl.core.key_mapping import MouseButton

# Create a throw helper for agent 0
throw_helper = GuiThrowHelper(
    gui_service=app_service,
    agent_idx=0,
)

# Each frame, visualize the throw trajectory and get velocity
throw_velocity = throw_helper.viz_and_get_humanoid_throw()

# On mouse click, apply the throw
if throw_velocity is not None:
    if app_service.gui_input.get_mouse_button_down(MouseButton.LEFT):
        # Apply velocity to the held object
        held_obj = sim.get_rigid_object_manager().get_object_by_id(held_obj_id)
        held_obj.linear_velocity = throw_velocity
        print(f"Throwing object with velocity: {throw_velocity}")