Implementation:Facebookresearch Habitat lab GuiInput

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

Overview

GuiInput is a container class that holds the current state of keyboard and mouse input for the Habitat HITL framework, providing query methods for key presses, mouse buttons, mouse position, scroll offset, and mouse ray.

Description

The GuiInput class maintains sets of held, pressed-down, and released keys and mouse buttons, along with mouse position, relative mouse position, scroll offset, and an optional mouse ray. It does not directly interface with OS input APIs; instead, it is populated externally (e.g., by InputHandlerApplication in gui_application.py or by remote client input consolidation).

Key features include:

• Key state tracking: held, down (just pressed), and up (just released) states for keyboard keys.
• Mouse button tracking: held, down, and up states for left, right, and middle mouse buttons.
• Mouse properties: absolute and relative position, scroll offset, and an optional Ray for 3D picking.
• Frame reset: The reset method clears per-frame events (key down/up, button down/up) and optionally resets continuous input (scroll, relative position) for proper integration with remote client input timing.
• Copy support: The copy_from method allows cloning the entire input state from another GuiInput instance.

Usage

Use GuiInput as the central input state object in HITL applications. It is typically accessed via app_service.gui_input and queried each frame to determine user actions such as key presses, mouse clicks, and mouse ray direction for 3D interaction.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-hitl/habitat_hitl/core/gui_input.py
• Lines: 1-123

Signature

class GuiInput:
    def __init__(self):
        ...

    def get_key(self, key) -> bool:
        ...

    def get_any_key_down(self) -> bool:
        ...

    def get_any_input(self) -> bool:
        ...

    def get_key_down(self, key) -> bool:
        ...

    def get_key_up(self, key) -> bool:
        ...

    def get_mouse_button(self, mouse_button) -> bool:
        ...

    def get_mouse_button_down(self, mouse_button) -> bool:
        ...

    def get_mouse_button_up(self, mouse_button) -> bool:
        ...

    @property
    def mouse_position(self):
        ...

    @property
    def relative_mouse_position(self):
        ...

    @property
    def mouse_scroll_offset(self):
        ...

    @property
    def mouse_ray(self):
        ...

    def reset(self, reset_continuous_input: bool = True):
        ...

    def copy_from(self, other: GuiInput):
        ...

Import

from habitat_hitl.core.gui_input import GuiInput

I/O Contract

Inputs

Name	Type	Required	Description
(none)	-	-	The constructor takes no parameters. Input state is populated externally.

Outputs

Name	Type	Description
get_key(key)	bool	Whether the specified KeyCode is currently held down.
get_key_down(key)	bool	Whether the specified KeyCode was pressed this frame.
get_key_up(key)	bool	Whether the specified KeyCode was released this frame.
get_any_key_down()	bool	Whether any key was pressed this frame.
get_any_input()	bool	Whether any input (key or mouse button) event occurred this frame.
get_mouse_button(button)	bool	Whether the specified MouseButton is currently held down.
get_mouse_button_down(button)	bool	Whether the specified MouseButton was pressed this frame.
get_mouse_button_up(button)	bool	Whether the specified MouseButton was released this frame.
mouse_position	list[int]	Current absolute mouse position [x, y].
relative_mouse_position	list[int]	Relative mouse movement since last frame [dx, dy].
mouse_scroll_offset	float	Mouse scroll wheel offset.
mouse_ray	Optional[Ray]	3D ray from camera through mouse position for picking.

Usage Examples

Basic Usage

from habitat_hitl.core.gui_input import GuiInput
from habitat_hitl.core.key_mapping import KeyCode, MouseButton

gui_input = GuiInput()

# In the frame update loop (state is populated externally):
if gui_input.get_key_down(KeyCode.SPACE):
    print("Space was just pressed!")

if gui_input.get_mouse_button_down(MouseButton.LEFT):
    print(f"Left click at position: {gui_input.mouse_position}")

if gui_input.mouse_ray is not None:
    print(f"Mouse ray origin: {gui_input.mouse_ray.origin}")

# At end of frame, reset per-frame events
gui_input.reset()