habitat.sims.habitat_simulator.sim_utilities module

This module provides a diverse set of functional utilities for common operations involving the Simulator and ManagedObjects including: object getters from id and handle, geometric utilities, prepositional logic, region queries, articulated object interactions, and more.

Functions

def above(sim: habitat_sim.simulator.Simulator, object_a: typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject]) -> typing.List[int]: Get a list of all objects that a particular object_a is ‘above’. Concretely, ‘above’ is defined as: a downward raycast of any object keypoint hits the object below.
def bb_next_to(bb_a: _magnum.Range3D, bb_b: _magnum.Range3D, transform_a: typing.Optional[_magnum.Matrix4] = None, transform_b: typing.Optional[_magnum.Matrix4] = None, hor_l2_threshold: float = 0.3, vertical_padding: float = 0.1) -> bool: Check whether or not two bounding boxes should be considered “next to” one another.
def bb_ray_prescreen(sim: habitat_sim.simulator.Simulator, obj: habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, support_obj_ids: typing.Optional[typing.List[int]] = None, ignore_obj_ids: typing.Optional[typing.List[int]] = None, check_all_corners: bool = False) -> typing.Dict[str, typing.Any]: Pre-screen a potential placement by casting rays in the gravity direction from the object center of mass (and optionally each corner of its bounding box) checking for interferring objects below.
def close_link(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int) -> None: Set a link to the “closed” state. Sets the joint position to the minimum joint limit.
def get_all_object_ids(sim: habitat_sim.simulator.Simulator) -> typing.Dict[int, str]: Generate a dict mapping all active object ids to a descriptive string containing the object instance handle and, for ArticulatedLinks, the link name.
def get_all_objects(sim: habitat_sim.simulator.Simulator) -> typing.List[typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject]]: Get a list of all ManagedRigidObjects and ManagedArticulatedObjects in the scene.
def get_ao_default_link(ao: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, compute_if_not_found: bool = False) -> typing.Optional[int]: Get the “default” link index for a ManagedArticulatedObject. The “default” link is the one link which should be used if only one joint can be actuated. For example, the largest or most accessible drawer or door.
def get_ao_link_id_map(sim: habitat_sim.simulator.Simulator) -> typing.Dict[int, int]: Construct a dict mapping ArticulatedLink object_id to parent ArticulatedObject object_id. NOTE: also maps ao’s root object id to itself for ease of use.
def get_articulated_link_global_keypoints(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_index: int) -> typing.List[_magnum.Vector3]: Get global bb keypoints for an ArticulatedLink.
def get_bb_corners(range3d: _magnum.Range3D) -> typing.List[_magnum.Vector3]: Get the corner points for an Axis-aligned bounding box (AABB).
def get_bb_for_object_id(sim: habitat_sim.simulator.Simulator, obj_id: int, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.Tuple[_magnum.Range3D, _magnum.Matrix4]: Wrapper to get a bb and global transform directly from an object id. Handles RigidObject and ArticulatedLink ids.
def get_floor_point_in_region(sim: habitat_sim.simulator.Simulator, region_index: int, island_index: int = -1, max_center_samples: int = 100, max_global_samples: int = 1000, quick_return: bool = False) -> typing.Optional[_magnum.Vector3]: Sample the navmesh to find a point on the floor within a given region.
def get_global_keypoints_from_bb(aabb: _magnum.Range3D, local_to_global: _magnum.Matrix4) -> typing.List[_magnum.Vector3]: Get a list of bounding box keypoints in global space. 0th point is the bounding box center, others are bounding box corners.
def get_global_keypoints_from_object_id(sim: habitat_sim.simulator.Simulator, object_id: int, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.List[_magnum.Vector3]: Get a list of object keypoints in global space given an object id. 0th point is the center of bb, others are bounding box corners.
def get_link_normalized_joint_position(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int) -> float: Normalize the joint limit range [min, max] -> [0,1] and return the current joint state in this range.
def get_obj_from_handle(sim: habitat_sim.simulator.Simulator, obj_handle: str) -> typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject]: Get a ManagedRigidObject or ManagedArticulatedObject from its instance handle.
def get_obj_from_id(sim: habitat_sim.simulator.Simulator, obj_id: int, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject]: Get a ManagedRigidObject or ManagedArticulatedObject from an object_id.
def get_obj_receptacle_and_confidence(sim: habitat_sim.simulator.Simulator, obj: habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, candidate_receptacles: typing.Dict[str, Receptacle], support_surface_id: typing.Optional[int] = None, obj_bottom_location: typing.Optional[_magnum.Vector3] = None, max_dist_to_rec: float = 0.25, island_index: int = -1) -> typing.Tuple[typing.List[str], float, str]: Heuristic to match a potential placement point with a Receptacle and provide some confidence.
def get_obj_size_along(sim: habitat_sim.simulator.Simulator, object_id: int, global_vec: _magnum.Vector3, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.Tuple[float, _magnum.Vector3]: Uses object bounding box ellipsoid scale as a heuristic to estimate object size in a particular global direction.
def get_obj_transform_from_id(sim: habitat_sim.simulator.Simulator, obj_id: int, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> _magnum.Matrix4: Retrieve the local to global transform of the object or link identified by the object_id.
def get_object_regions(sim: habitat_sim.simulator.Simulator, object_a: typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject], ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.List[typing.Tuple[int, float]]: Get a sorted list of regions containing an object using bounding box keypoints.
def link_is_closed(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int, threshold: float = 0.1) -> bool: Check whether a particular AO link is in the “closed” state. We assume that joint limits define the closed state (min) and open state (max).
def link_is_open(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int, threshold: float = 0.4) -> bool: Check whether a particular AO link is in the “open” state. We assume that joint limits define the closed state (min) and open state (max).
def obj_next_to(sim: habitat_sim.simulator.Simulator, object_id_a: int, object_id_b: int, hor_l2_threshold: float = 0.5, vertical_padding: float = 0.1, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> bool: Check whether or not two objects should be considered “next to” one another.
def object_in_region(sim: habitat_sim.simulator.Simulator, object_a: typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject], region: habitat_sim._ext.habitat_sim_bindings.SemanticRegion, containment_threshold = 0.25, center_only = False, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.Tuple[bool, float]: Check if an object is within a region by checking region containment of keypoints.
def object_keypoint_cast(sim: habitat_sim.simulator.Simulator, object_a: habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, direction: typing.Optional[_magnum.Vector3] = None) -> typing.List[habitat_sim._ext.habitat_sim_bindings.RaycastResults]: Computes object global keypoints, casts rays from each in the specified direction and returns the resulting RaycastResults.
def object_shortname_from_handle(object_handle: str) -> str: Splits any path directory and instance increment from the handle.
def on_floor(sim: habitat_sim.simulator.Simulator, object_a: habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, distance_threshold: float = 0.04, alt_pathfinder: typing.Optional[habitat_sim._ext.habitat_sim_bindings.PathFinder] = None, island_index: int = -1, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> bool
def ontop(sim: habitat_sim.simulator.Simulator, object_a: typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, int], do_collision_detection: bool, vertical_normal_error_threshold: float = 0.75) -> typing.List[int]: Get a list of all object ids or objects that are “ontop” of a particular object_a. Concretely, ‘ontop’ is defined as: contact points between object_a and object_b have vertical normals “upward” relative to object_a. This function uses collision points to determine which objects are resting on or contacting the surface of object_a.
def open_link(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int) -> None: Set a link to the “open” state. Sets the joint position to the maximum joint limit.
def point_to_tri_dist(point: numpy.ndarray, triangles: numpy.ndarray) -> typing.Tuple[float, numpy.ndarray]: Compute the minimum distance between a 3D point and a set of triangles (e.g. a triangle mesh) and return both the minimum distance and that closest point. Uses vectorized numpy operations for high performance with a large number of triangles. Implementation adapted from https://stackoverflow.com/questions/32342620/closest-point-projection-of-a-3d-point-to-3d-triangles-with-numpy-scipy Algorithm is vectorized form of e.g. https://www.geometrictools.com/Documentation/DistancePoint3Triangle3.pdf
def set_link_normalized_joint_position(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int, normalized_pos: float) -> None: Set the joint’s state within its limits from a normalized range [0,1] -> [min, max]
def size_regularized_bb_distance(bb_a: _magnum.Range3D, bb_b: _magnum.Range3D, transform_a: typing.Optional[_magnum.Matrix4] = None, transform_b: typing.Optional[_magnum.Matrix4] = None, flatten_axis: typing.Optional[int] = None) -> float: Get the heuristic surface-to-surface distance between two bounding boxes (regularized by their individual heuristic sizes). Estimate the distance from center to boundary along the line between bb centers. These sizes are then subtracted from the center-to-center distance as a heuristic for surface-to-surface distance.
def size_regularized_object_distance(sim: habitat_sim.simulator.Simulator, object_id_a: int, object_id_b: int, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> float: Get the heuristic surface-to-surface distance between two objects (regularized by their individual heuristic sizes). Uses each object’s bounding box to estimate the distance from center to boundary along the line between object centers. These object sizes are then subtracted from the center-to-center distance as a heuristic for surface-to-surface distance.
def snap_down(sim: habitat_sim.simulator.Simulator, obj: habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, support_obj_ids: typing.Optional[typing.List[int]] = None, ignore_obj_ids: typing.Optional[typing.List[int]] = None, dbv: typing.Optional[debug_visualizer.DebugVisualizer] = None, max_collision_depth: float = 0.01) -> bool: Attempt to project an object in the gravity direction onto the surface below it.
def within(sim: habitat_sim.simulator.Simulator, object_a: typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject], max_distance: float = 1.0, keypoint_vote_threshold: int = 2, center_ensures_containment: bool = True) -> typing.List[int]: Get a list of all objects that a particular object_a is ‘within’. Concretely, ‘within’ is defined as: a threshold number of opposing keypoint raycasts hit the same object. This function computes raycasts along all global axes from all keypoints and checks opposing rays for collision with the same object.

Data

TYPE_CHECKING = False

Function documentation

def habitat.sims.habitat_simulator.sim_utilities.above(sim: habitat_sim.simulator.Simulator, object_a: typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject]) -> typing.List[int]

Get a list of all objects that a particular object_a is ‘above’. Concretely, ‘above’ is defined as: a downward raycast of any object keypoint hits the object below.

Parameters
sim	The Simulator instance.
object_a	The ManagedRigidObject for which to query the ‘above’ set.
Returns	a list of object ids.

def habitat.sims.habitat_simulator.sim_utilities.bb_next_to(bb_a: _magnum.Range3D, bb_b: _magnum.Range3D, transform_a: typing.Optional[_magnum.Matrix4] = None, transform_b: typing.Optional[_magnum.Matrix4] = None, hor_l2_threshold: float = 0.3, vertical_padding: float = 0.1) -> bool

Check whether or not two bounding boxes should be considered “next to” one another.

Parameters
bb_a	local bounding box of one object
bb_b	local bounding box of another object
transform_a	local to global transform for the first object. Default is identity.
transform_b	local to global transform for the second object. Default is identity.
hor_l2_threshold	regularized horizontal L2 distance allowed between the objects’ centers.
vertical_padding	vertical distance padding used when comparing bounding boxes. Higher value is a looser constraint.
Returns	Whether or not the objects are heuristically “next to” one another.

Concretely, consists of two checks:

assert overlap between the vertical range of the two bounding boxes.
regularized horizontal L2 distance between object centers. Regularized in this case means projected displacement vector is truncated by each object’s heuristic size.

def habitat.sims.habitat_simulator.sim_utilities.bb_ray_prescreen(sim: habitat_sim.simulator.Simulator, obj: habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, support_obj_ids: typing.Optional[typing.List[int]] = None, ignore_obj_ids: typing.Optional[typing.List[int]] = None, check_all_corners: bool = False) -> typing.Dict[str, typing.Any]

Pre-screen a potential placement by casting rays in the gravity direction from the object center of mass (and optionally each corner of its bounding box) checking for interferring objects below.

Parameters
sim	The Simulator instance.
obj	The RigidObject instance.
support_obj_ids	A list of object ids designated as valid support surfaces for object placement. Contact with other objects is a criteria for placement rejection.
ignore_obj_ids	A list of object ids which should be ignored in contact checks and raycasts. For example, the body of the agent placing an object.
check_all_corners	Optionally cast rays from all bounding box corners instead of only casting a ray from the center of mass.
Returns	a dict of raycast metadata: “base_rel_height”,”surface_snap_point”, “raycast_results”

def habitat.sims.habitat_simulator.sim_utilities.close_link(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int) -> None

Set a link to the “closed” state. Sets the joint position to the minimum joint limit.

TODO: does not do any collision checking to validate the state or move any other objects which may be contained in or supported by this link.

param object_a:: The parent ArticulatedObject of the link to check.
param link_ix:: The index of the link within the parent object. Not the link's object_id.

def habitat.sims.habitat_simulator.sim_utilities.get_all_object_ids(sim: habitat_sim.simulator.Simulator) -> typing.Dict[int, str]

Generate a dict mapping all active object ids to a descriptive string containing the object instance handle and, for ArticulatedLinks, the link name.

Parameters
sim	The Simulator instance.
Returns	a dict mapping object ids to a descriptive string.

def habitat.sims.habitat_simulator.sim_utilities.get_all_objects(sim: habitat_sim.simulator.Simulator) -> typing.List[typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject]]

Get a list of all ManagedRigidObjects and ManagedArticulatedObjects in the scene.

Parameters
sim	The Simulator instance.
Returns	a list of ManagedObject wrapper instances containing all objects currently instantiated in the scene.

def habitat.sims.habitat_simulator.sim_utilities.get_ao_default_link(ao: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, compute_if_not_found: bool = False) -> typing.Optional[int]

Get the “default” link index for a ManagedArticulatedObject. The “default” link is the one link which should be used if only one joint can be actuated. For example, the largest or most accessible drawer or door.

Parameters
ao	The ManagedArticulatedObject instance.
compute_if_not_found	If true, try to compute the default link if it isn’t found.
Returns	The default link index or None if not found. Cannot be base link (-1).

The default link is determined by:

must be “prismatic” or “revolute” joint type

first look in the metadata Configuration for an annotated link.

(if compute_if_not_found) - if not annotated, it is programmatically computed from a heuristic.

Default link heuristic: the link with the lowest Y value in the bounding box with appropriate joint type.

def habitat.sims.habitat_simulator.sim_utilities.get_ao_link_id_map(sim: habitat_sim.simulator.Simulator) -> typing.Dict[int, int]

Construct a dict mapping ArticulatedLink object_id to parent ArticulatedObject object_id. NOTE: also maps ao’s root object id to itself for ease of use.

Parameters
sim	The Simulator instance.
Returns	dict mapping ArticulatedLink object ids to parent object ids.

def habitat.sims.habitat_simulator.sim_utilities.get_articulated_link_global_keypoints(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_index: int) -> typing.List[_magnum.Vector3]

Get global bb keypoints for an ArticulatedLink.

Parameters
object_a	The parent ManagedArticulatedObject for the link.
link_index	The local index of the link within the parent ArticulatedObject. Not the object_id of the link.
Returns	A set of global 3D keypoints for the link.

def habitat.sims.habitat_simulator.sim_utilities.get_bb_corners(range3d: _magnum.Range3D) -> typing.List[_magnum.Vector3]

Get the corner points for an Axis-aligned bounding box (AABB).

Parameters
range3d	The bounding box for which to get the corners.
Returns	a list of AABB (Range3D) corners in object local space.

def habitat.sims.habitat_simulator.sim_utilities.get_bb_for_object_id(sim: habitat_sim.simulator.Simulator, obj_id: int, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.Tuple[_magnum.Range3D, _magnum.Matrix4]

Wrapper to get a bb and global transform directly from an object id. Handles RigidObject and ArticulatedLink ids.

Parameters
sim	The Simulator instance.
obj_id	The integer id of the object or link.
ao_link_map	A pre-computed map from link object ids to their parent ArticulatedObject’s object id.
Returns	tuple (local_aabb, global_transform)

def habitat.sims.habitat_simulator.sim_utilities.get_floor_point_in_region(sim: habitat_sim.simulator.Simulator, region_index: int, island_index: int = -1, max_center_samples: int = 100, max_global_samples: int = 1000, quick_return: bool = False) -> typing.Optional[_magnum.Vector3]

Sample the navmesh to find a point on the floor within a given region.

Parameters
sim	The Simulator instance.
region_index	The index of the Region within which to sample.
island_index	The index of the navmesh island representing the active floor area. Default -1 is all islands. Should be set to the same island used for other navmesh operations in the application. For example, the largest indoor island for the scene.
max_center_samples	The number of samples near the center point to attempt if applicable. This will be done first. <=0 skips center sampling.
max_global_samples	The number of global navmesh samples to attempt if center point samples were unsuccessful. <=0 skips this step.
quick_return	If True, the first valid sample will be returned instead of continuing to search for a better sample. Use this option when speed is more important than the quality or consistency.
Returns	The sampled floor point within the given region or None if a point could not be found.

This method attempts to find a point in the region with maximum navmesh clearance by sorting candidates on distance_to_closest_obstacle. Because this method uses multiple sampling passes it is advised to use it in initialization and pre-processes rather than within an application loop.

def habitat.sims.habitat_simulator.sim_utilities.get_global_keypoints_from_bb(aabb: _magnum.Range3D, local_to_global: _magnum.Matrix4) -> typing.List[_magnum.Vector3]

Get a list of bounding box keypoints in global space. 0th point is the bounding box center, others are bounding box corners.

Parameters
aabb	The local bounding box.
local_to_global	The local to global transformation matrix.
Returns	A set of global 3D keypoints for the bounding box.

def habitat.sims.habitat_simulator.sim_utilities.get_global_keypoints_from_object_id(sim: habitat_sim.simulator.Simulator, object_id: int, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.List[_magnum.Vector3]

Get a list of object keypoints in global space given an object id. 0th point is the center of bb, others are bounding box corners.

Parameters
sim	The Simulator instance.
object_id	The integer id for the object from which to extract keypoints.
ao_link_map	A pre-computed map from link object ids to their parent ArticulatedObject’s object id. If not provided, recomputed as necessary.
Returns	A set of global 3D keypoints for the object.

def habitat.sims.habitat_simulator.sim_utilities.get_link_normalized_joint_position(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int) -> float

Normalize the joint limit range [min, max] -> [0,1] and return the current joint state in this range.

Parameters
object_a	The parent ArticulatedObject of the link.
link_ix	The index of the link within the parent object. Not the link’s object_id.
Returns	normalized joint position [0,1]

def habitat.sims.habitat_simulator.sim_utilities.get_obj_from_handle(sim: habitat_sim.simulator.Simulator, obj_handle: str) -> typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject]

Get a ManagedRigidObject or ManagedArticulatedObject from its instance handle.

Parameters
sim	The Simulator instance.
obj_handle	object instance handle for which ManagedObject is desired.
Returns	a ManagedObject or None

def habitat.sims.habitat_simulator.sim_utilities.get_obj_from_id(sim: habitat_sim.simulator.Simulator, obj_id: int, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject]

Get a ManagedRigidObject or ManagedArticulatedObject from an object_id.

Parameters
sim	The Simulator instance.
obj_id	object id for which ManagedObject is desired.
ao_link_map	A pre-computed map from link object ids to their parent ArticulatedObject’s object id.
Returns	a ManagedObject or None

ArticulatedLink object_ids will return the ManagedArticulatedObject. If you want link id, use ManagedArticulatedObject.link_object_ids[obj_id].

def habitat.sims.habitat_simulator.sim_utilities.get_obj_receptacle_and_confidence(sim: habitat_sim.simulator.Simulator, obj: habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, candidate_receptacles: typing.Dict[str, Receptacle], support_surface_id: typing.Optional[int] = None, obj_bottom_location: typing.Optional[_magnum.Vector3] = None, max_dist_to_rec: float = 0.25, island_index: int = -1) -> typing.Tuple[typing.List[str], float, str]

Heuristic to match a potential placement point with a Receptacle and provide some confidence.

Parameters
sim
obj	The ManagedRigidObject for which to find a Receptacle match.
candidate_receptacles	Optionally provide a dict (unique_name to Receptacle) of candidate Receptacles for matching. If not provided, uses sim.receptacles.
support_surface_id	The object_id of the intended support surface (rigid object, articulated link, or stage_id). If not provided, a downward raycast from object center will determine the first hit as the support surface.
obj_bottom_location	The optional location of the candidate bottom point of the object. If not provided, project the object center to the lowest extent.
max_dist_to_rec	The threshold point to mesh distance for an object to be matched with a Receptacle.
island_index	Optionally provide an island_index for identifying navigable floor points. Default is full navmesh.
Returns	Tuple containing: (1): list of receptacle strings: “floor,region”, Receptacle.unique_name, or None (2): a floating point confidence score [0,1] (3): a message string describing the results for use in a UI tooltip

When using this util for candidate placement with raycasting (e.g. HitL): provide ‘support_surface_id’ and ‘obj_bottom_location’ overrides from the raycast. When using this util for assessing current object state (e.g. episode evaluation): leave ‘support_surface_id’ and ‘obj_bottom_location’ as default.

def habitat.sims.habitat_simulator.sim_utilities.get_obj_size_along(sim: habitat_sim.simulator.Simulator, object_id: int, global_vec: _magnum.Vector3, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.Tuple[float, _magnum.Vector3]

Uses object bounding box ellipsoid scale as a heuristic to estimate object size in a particular global direction.

Parameters
sim	The Simulator instance.
object_id	The integer id of the object or link.
global_vec	Vector in global space indicating the direction to approximate object size.
ao_link_map	A pre-computed map from link object ids to their parent ArticulatedObject’s object id.
Returns	distance along the specified direction and global center of bounding box from which distance was estimated.

def habitat.sims.habitat_simulator.sim_utilities.get_obj_transform_from_id(sim: habitat_sim.simulator.Simulator, obj_id: int, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> _magnum.Matrix4

Retrieve the local to global transform of the object or link identified by the object_id.

Parameters
sim	The Simulator instance.
obj_id	object id for which ManagedObject is desired.
ao_link_map	A pre-computed map from link object ids to their parent ArticulatedObject’s object id.
Returns	a Matrix4 local to global transform or None

def habitat.sims.habitat_simulator.sim_utilities.get_object_regions(sim: habitat_sim.simulator.Simulator, object_a: typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject], ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.List[typing.Tuple[int, float]]

Get a sorted list of regions containing an object using bounding box keypoints.

Parameters
sim	The Simulator instance.
object_a	The object instance.
ao_link_map	A pre-computed map from link object ids to their parent ArticulatedObject’s object id.
Returns	A sorted list of region index, ratio pairs. First item in the list the primary containing region.

def habitat.sims.habitat_simulator.sim_utilities.link_is_closed(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int, threshold: float = 0.1) -> bool

Check whether a particular AO link is in the “closed” state. We assume that joint limits define the closed state (min) and open state (max).

Parameters
object_a	The parent ArticulatedObject of the link to check.
link_ix	The index of the link within the parent object. Not the link’s object_id.
threshold	The normalized threshold ratio of joint ranges which are considered “closed”. E.g. 0.1 = 10%
Returns	Whether or not the link is considered “closed”.

def habitat.sims.habitat_simulator.sim_utilities.link_is_open(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int, threshold: float = 0.4) -> bool

Check whether a particular AO link is in the “open” state. We assume that joint limits define the closed state (min) and open state (max).

Parameters
object_a	The parent ArticulatedObject of the link to check.
link_ix	The index of the link within the parent object. Not the link’s object_id.
threshold	The normalized threshold ratio of joint ranges which are considered “open”. E.g. 0.8 = 80%
Returns	Whether or not the link is considered “open”.

def habitat.sims.habitat_simulator.sim_utilities.obj_next_to(sim: habitat_sim.simulator.Simulator, object_id_a: int, object_id_b: int, hor_l2_threshold: float = 0.5, vertical_padding: float = 0.1, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> bool

Check whether or not two objects should be considered “next to” one another.

Concretely, consists of two checks:

bounding boxes must overlap vertically.
regularized horizontal L2 distance between object centers must be less than a threshold. Regularized in this case means displacement vector is truncated by each object’s heuristic size.

def habitat.sims.habitat_simulator.sim_utilities.object_in_region(sim: habitat_sim.simulator.Simulator, object_a: typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject], region: habitat_sim._ext.habitat_sim_bindings.SemanticRegion, containment_threshold = 0.25, center_only = False, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> typing.Tuple[bool, float]

Check if an object is within a region by checking region containment of keypoints.

Parameters
sim	The Simulator instance.
object_a	The object instance.
region	The SemanticRegion to check.
containment_threshold	threshold ratio of keypoints which need to be in a region to count as containment.
center_only	If True, only use the BB center keypoint, all or nothing.
ao_link_map	A pre-computed map from link object ids to their parent ArticulatedObject’s object id.
Returns	boolean containment and the ratio of keypoints which are inside the region.

def habitat.sims.habitat_simulator.sim_utilities.object_keypoint_cast(sim: habitat_sim.simulator.Simulator, object_a: habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, direction: typing.Optional[_magnum.Vector3] = None) -> typing.List[habitat_sim._ext.habitat_sim_bindings.RaycastResults]

Computes object global keypoints, casts rays from each in the specified direction and returns the resulting RaycastResults.

Parameters
sim	The Simulator instance.
object_a	The ManagedRigidObject from which to extract keypoints and raycast.
direction	Optionally provide a unit length global direction vector for the raycast. If None, default to -Y.
Returns	A list of RaycastResults, one from each object keypoint.

def habitat.sims.habitat_simulator.sim_utilities.object_shortname_from_handle(object_handle: str) -> str

Splits any path directory and instance increment from the handle.

Parameters
object_handle	The raw object template or instance handle.
Returns	the shortened name string.

def habitat.sims.habitat_simulator.sim_utilities.ontop(sim: habitat_sim.simulator.Simulator, object_a: typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, int], do_collision_detection: bool, vertical_normal_error_threshold: float = 0.75) -> typing.List[int]

Get a list of all object ids or objects that are “ontop” of a particular object_a. Concretely, ‘ontop’ is defined as: contact points between object_a and object_b have vertical normals “upward” relative to object_a. This function uses collision points to determine which objects are resting on or contacting the surface of object_a.

Parameters
sim	The Simulator instance.
object_a	The ManagedRigidObject or object id for which to query the ‘ontop’ set.
do_collision_detection	If True, a fresh discrete collision detection is run before the contact point query. Pass False to skip if a recent sim step or pre-process has run a collision detection pass on the current state.
vertical_normal_error_threshold	The allowed error in normal alignment for a contact point to be considered “vertical” for this check. Functionally, if dot(contact normal, Y) <= threshold, the contact is ignored.
Returns	a list of integer object_ids for the set of objects “ontop” of object_a.

def habitat.sims.habitat_simulator.sim_utilities.open_link(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int) -> None

Set a link to the “open” state. Sets the joint position to the maximum joint limit.

Parameters
object_a	The parent ArticulatedObject of the link to check.
link_ix	The index of the link within the parent object. Not the link’s object_id.

TODO: does not do any collision checking to validate the state or move any other objects which may be contained in or supported by this link.

def habitat.sims.habitat_simulator.sim_utilities.point_to_tri_dist(point: numpy.ndarray, triangles: numpy.ndarray) -> typing.Tuple[float, numpy.ndarray]

Compute the minimum distance between a 3D point and a set of triangles (e.g. a triangle mesh) and return both the minimum distance and that closest point. Uses vectorized numpy operations for high performance with a large number of triangles. Implementation adapted from https://stackoverflow.com/questions/32342620/closest-point-projection-of-a-3d-point-to-3d-triangles-with-numpy-scipy Algorithm is vectorized form of e.g. https://www.geometrictools.com/Documentation/DistancePoint3Triangle3.pdf

Parameters
point	A 3D point.
triangles	An nx3x3 numpy array of triangles. Each entry of the first axis is a triangle with three 3D vectors, the vertices of the triangle.
Returns	The minimum distance from point to triangle set and the closest point on the surface of any triangle.

def habitat.sims.habitat_simulator.sim_utilities.set_link_normalized_joint_position(object_a: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject, link_ix: int, normalized_pos: float) -> None

Set the joint’s state within its limits from a normalized range [0,1] -> [min, max]

Parameters
object_a	The parent ArticulatedObject of the link.
link_ix	The index of the link within the parent object. Not the link’s object_id.
normalized_pos	The normalized position [0,1] to set.

Assumes the joint has valid joint limits.

def habitat.sims.habitat_simulator.sim_utilities.size_regularized_bb_distance(bb_a: _magnum.Range3D, bb_b: _magnum.Range3D, transform_a: typing.Optional[_magnum.Matrix4] = None, transform_b: typing.Optional[_magnum.Matrix4] = None, flatten_axis: typing.Optional[int] = None) -> float

Get the heuristic surface-to-surface distance between two bounding boxes (regularized by their individual heuristic sizes). Estimate the distance from center to boundary along the line between bb centers. These sizes are then subtracted from the center-to-center distance as a heuristic for surface-to-surface distance.

Parameters
bb_a	local bounding box of one object
bb_b	local bounding box of another object
transform_a	local to global transform for the first object. Default is identity.
transform_b	local to global transform for the second object. Default is identity.
flatten_axis	Optionally flatten one axis of the displacement vector. This effectively projects the displacement. For example, index “1” would result in horizontal (xz) distance.
Returns	heuristic surface-to-surface distance.

def habitat.sims.habitat_simulator.sim_utilities.size_regularized_object_distance(sim: habitat_sim.simulator.Simulator, object_id_a: int, object_id_b: int, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> float

Get the heuristic surface-to-surface distance between two objects (regularized by their individual heuristic sizes). Uses each object’s bounding box to estimate the distance from center to boundary along the line between object centers. These object sizes are then subtracted from the center-to-center distance as a heuristic for surface-to-surface distance.

Parameters
sim	The Simulator instance.
object_id_a	integer id of the first object
object_id_b	integer id of the second object
ao_link_map	A pre-computed map from link object ids to their parent ArticulatedObject’s object id.
Returns	The heuristic surface-2-surface distance between the objects.

def habitat.sims.habitat_simulator.sim_utilities.snap_down(sim: habitat_sim.simulator.Simulator, obj: habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, support_obj_ids: typing.Optional[typing.List[int]] = None, ignore_obj_ids: typing.Optional[typing.List[int]] = None, dbv: typing.Optional[debug_visualizer.DebugVisualizer] = None, max_collision_depth: float = 0.01) -> bool

Attempt to project an object in the gravity direction onto the surface below it.

Parameters
sim	The Simulator instance.
obj	The RigidObject instance.
support_obj_ids	A list of object ids designated as valid support surfaces for object placement. Contact with other objects is a criteria for placement rejection. If none provided, default support surface is the stage/ground mesh (0).
ignore_obj_ids	A list of object ids which should be ignored in contact checks and raycasts. For example, the body of the agent placing an object.
dbv	Optionally provide a DebugVisualizer (dbv) to render debug images of each object’s computed snap position before collision culling.
max_collision_depth	The maximum contact penetration depth between the object and the support surface. Higher values are easier to sample, but result in less dynamically stabile states.
Returns	boolean placement success.

Reject invalid placements by checking for penetration with other existing objects. If placement is successful, the object state is updated to the snapped location. If placement is rejected, object position is not modified and False is returned.

To use this utility, generate an initial placement for any object above any of the designated support surfaces and call this function to attempt to snap it onto the nearest surface in the gravity direction.

def habitat.sims.habitat_simulator.sim_utilities.within(sim: habitat_sim.simulator.Simulator, object_a: typing.Union[habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject, habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject], max_distance: float = 1.0, keypoint_vote_threshold: int = 2, center_ensures_containment: bool = True) -> typing.List[int]

Get a list of all objects that a particular object_a is ‘within’. Concretely, ‘within’ is defined as: a threshold number of opposing keypoint raycasts hit the same object. This function computes raycasts along all global axes from all keypoints and checks opposing rays for collision with the same object.

Parameters
sim	The Simulator instance.
object_a	The ManagedRigidObject for which to query the ‘within’ set.
max_distance	The maximum ray distance to check in each opposing direction (this is half the “wingspan” of the check). Makes the raycast more efficienct and realistically containing objects will have a limited size.
keypoint_vote_threshold	The minimum number of keypoints which must indicate containment to qualify object_a as “within” another object.
center_ensures_containment	If True, positive test of object_a’s center keypoint alone qualifies object_a as “within” another object.
Returns	a list of object_id integers.