Implementation:Facebookresearch Habitat lab KeyMapping

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

Overview

KeyMapping defines the keyboard, mouse, and XR input enumerations used throughout the Habitat HITL framework, along with mappings from Magnum GLFW application keys to the framework's platform-agnostic key codes.

Description

This module provides several interrelated components for input mapping:

• KeyCode (IntEnum): Enumerates all available keyboard keys using USB HID Usage Table values (A-Z, 0-9, ESC, SPACE, TAB). Uses a custom KeyCodeMetaEnum metaclass that caches values for fast in operator lookups.
• MouseButton (IntEnum): Enumerates mouse buttons (LEFT, RIGHT, MIDDLE) with a similar MouseButtonMetaEnum metaclass for cached containment checks.
• XRButton (IntEnum): Enumerates XR controller buttons (START, ONE, TWO, PRIMARY_HAND_TRIGGER, PRIMARY_INDEX_TRIGGER, PRIMARY_THUMBSTICK) with XRButtonMetaEnum.
• magnum_keymap: A dictionary mapping Magnum GLFW Application.Key values to KeyCode values (only available when Magnum GLFW is importable).
• magnum_mouse_keymap: A dictionary mapping Magnum GLFW Application.Pointer values to MouseButton values.
• MagnumKeyConverter: A utility class with static methods to convert Magnum key and mouse button types to the framework's KeyCode and MouseButton enums.

On headless systems where Magnum GLFW is unavailable, the module gracefully falls back to an agnostic implementation (magnum_enabled = False) that disables local keyboard/mouse input while still allowing the key code enums to be used.

Usage

Use KeyCode, MouseButton, and XRButton throughout HITL application code when checking or mapping user input. Use MagnumKeyConverter to translate Magnum GLFW events into the framework's key codes within the GUI application event handlers.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-hitl/habitat_hitl/core/key_mapping.py
• Lines: 1-192

Signature

class KeyCode(IntEnum, metaclass=KeyCodeMetaEnum):
    A       = 0x04
    B       = 0x05
    # ... (A-Z, 0-9, ESC, SPACE, TAB)
    ...

class MouseButton(IntEnum, metaclass=MouseButtonMetaEnum):
    LEFT   = 0
    RIGHT  = 1
    MIDDLE = 2

class XRButton(IntEnum, metaclass=XRButtonMetaEnum):
    START                   = 0x01
    ONE                     = 0x02
    TWO                     = 0x03
    PRIMARY_HAND_TRIGGER    = 0x04
    PRIMARY_INDEX_TRIGGER   = 0x05
    PRIMARY_THUMBSTICK      = 0x06

class MagnumKeyConverter:
    def convert_key(key: Any) -> Optional[KeyCode]:
        ...

    def convert_mouse_button(button: Any) -> Optional[MouseButton]:
        ...

Import

from habitat_hitl.core.key_mapping import KeyCode, MouseButton, XRButton, MagnumKeyConverter

I/O Contract

Inputs (MagnumKeyConverter.convert_key)

Name	Type	Required	Description
key	Any (typically Application.Key)	Yes	A Magnum GLFW key value to convert to a KeyCode.

Outputs (MagnumKeyConverter.convert_key)

Name	Type	Description
return value	Optional[KeyCode]	The corresponding KeyCode, or None if the key is not mapped.

Inputs (MagnumKeyConverter.convert_mouse_button)

Name	Type	Required	Description
button	Any (typically Application.Pointer)	Yes	A Magnum GLFW pointer value to convert to a MouseButton.

Outputs (MagnumKeyConverter.convert_mouse_button)

Name	Type	Description
return value	Optional[MouseButton]	The corresponding MouseButton, or None if the button is not mapped.

Usage Examples

Basic Usage

from habitat_hitl.core.key_mapping import KeyCode, MouseButton

# Check a key code in an input handler
if gui_input.get_key_down(KeyCode.W):
    print("W key pressed - move forward")

if gui_input.get_mouse_button_down(MouseButton.LEFT):
    print("Left mouse button clicked")

# Check containment (fast, uses cached value set)
key_value = 0x04
if key_value in KeyCode:
    print("Valid key code")

Converting Magnum Keys

from habitat_hitl.core.key_mapping import MagnumKeyConverter

# In a Magnum GLFW event handler
def key_press_event(self, event):
    key_code = MagnumKeyConverter.convert_key(event.key)
    if key_code is not None:
        gui_input._key_down.add(key_code)
        gui_input._key_held.add(key_code)