Implementation:Facebookresearch Habitat lab Task Utils

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

Overview

This module provides geometric utility functions for navigation tasks, including quaternion-to-rotation matrix conversion, coordinate conversions, pixel coverage computation, and vector angle calculation.

Description

The module contains four focused utility functions used by Habitat navigation and perception tasks:

• quaternion_to_rotation(q_r, q_i, q_j, q_k) -- Converts a quaternion (real, i, j, k components) to a 3x3 rotation matrix using the standard quaternion-to-rotation formula from Wikipedia. Returns a np.float32 array. Assumes unit quaternions (s=1).

• cartesian_to_polar(x, y) -- Converts 2D Cartesian coordinates (x, y) to polar coordinates (rho, phi) where rho is the distance from origin and phi is the angle computed via np.arctan2.

• compute_pixel_coverage(instance_seg, object_id) -- Computes the fraction of pixels in an instance segmentation image that correspond to a given object ID. Returns a float64 score in the range [0.0, 1.0].

• get_angle(x, y) -- Computes the angle in radians between two vectors using the normalized dot product and np.arccos. Handles zero-norm vectors gracefully and clips the dot product to [-1, 1] to avoid numerical issues.

Usage

Use these functions in navigation and perception tasks: quaternion_to_rotation for converting sensor orientations, cartesian_to_polar for polar coordinate-based goal representations, compute_pixel_coverage for object visibility metrics, and get_angle for heading computations.

Code Reference

Source Location

• Repository: Facebookresearch_Habitat_lab
• File: habitat-lab/habitat/tasks/utils.py
• Lines: 1-64

Signature

def quaternion_to_rotation(q_r, q_i, q_j, q_k):

def cartesian_to_polar(x, y):

def compute_pixel_coverage(instance_seg, object_id):

def get_angle(x, y):

Import

from habitat.tasks.utils import (
    quaternion_to_rotation,
    cartesian_to_polar,
    compute_pixel_coverage,
    get_angle,
)

I/O Contract

Inputs (quaternion_to_rotation)

Name	Type	Required	Description
q_r	float	Yes	Real (w) component of the quaternion
q_i	float	Yes	Imaginary i component of the quaternion
q_j	float	Yes	Imaginary j component of the quaternion
q_k	float	Yes	Imaginary k component of the quaternion

Inputs (cartesian_to_polar)

Name	Type	Required	Description
x	float	Yes	X coordinate
y	float	Yes	Y coordinate

Inputs (compute_pixel_coverage)

Name	Type	Required	Description
instance_seg	np.ndarray	Yes	Instance segmentation image (2D array of object IDs)
object_id	int	Yes	The object ID to compute coverage for

Inputs (get_angle)

Name	Type	Required	Description
x	np.ndarray	Yes	First vector
y	np.ndarray	Yes	Second vector

Outputs

Name	Type	Description
quaternion_to_rotation()	np.ndarray	3x3 rotation matrix (float32)
cartesian_to_polar()	Tuple[float, float]	(rho, phi) polar coordinates
compute_pixel_coverage()	float	Fraction of pixels matching object_id, in range [0.0, 1.0]
get_angle()	float	Angle between the two vectors in radians

Usage Examples

Basic Usage

import numpy as np
from habitat.tasks.utils import (
    quaternion_to_rotation,
    cartesian_to_polar,
    compute_pixel_coverage,
    get_angle,
)

# Convert a quaternion to a rotation matrix
# Identity rotation: q = (1, 0, 0, 0)
rot_matrix = quaternion_to_rotation(1.0, 0.0, 0.0, 0.0)
# Result: 3x3 identity matrix

# Convert Cartesian to polar coordinates
rho, phi = cartesian_to_polar(3.0, 4.0)
# rho = 5.0, phi = arctan2(4, 3)

# Compute pixel coverage of an object in a segmentation image
seg = np.array([[1, 1, 2], [2, 2, 1], [1, 2, 2]])
coverage = compute_pixel_coverage(seg, object_id=2)
# coverage = 5/9

# Get angle between two vectors
angle = get_angle(np.array([1, 0, 0]), np.array([0, 1, 0]))
# angle = pi/2

Related Pages

• Implementation:Facebookresearch_Habitat_lab_Geometry_Utils