habitat.sims.habitat_simulator.sim_utilities module

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 add_transformed_wire_box(sim: habitat_sim.simulator.Simulator, size: _magnum.Vector3, transform: typing.Optional[_magnum.Matrix4] = None) -> habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject
Generate a transformed wire box in world space. Returns the new object.
def add_viz_sphere(sim: habitat_sim.simulator.Simulator, radius: float, pos: _magnum.Vector3) -> habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject
Add a visualization-only sphere to the world at a global position. Returns the new object.
def add_wire_box(sim: habitat_sim.simulator.Simulator, size: _magnum.Vector3, center: _magnum.Vector3, attach_to: typing.Optional[habitat_sim._ext.habitat_sim_bindings.SceneNode] = None, orientation: typing.Optional[_magnum.Quaternion] = None) -> habitat_sim._ext.habitat_sim_bindings.ManagedRigidObject
Generate a wire box object and optionally attach it to another existing object (automatically applies object scale). Returns the new object.
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 = 0.3) -> bool
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]
def get_ao_global_bb(obj: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject) -> typing.Optional[_magnum.Range3D]
Compute the cumulative bounding box of an ArticulatedObject by merging all link bounding boxes.
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_ao_root_bb(ao: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject) -> _magnum.Range3D
Get the local bounding box of all links of an articulated object in the root frame.
def get_ao_root_bbs(sim: habitat_sim.simulator.Simulator) -> typing.Dict[int, _magnum.Range3D]
Computes a dictionary mapping AO handles to a global bounding box of parts. Must be updated when AO state changes to correctly bound the full set of links.
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]
Return a list of AABB (Range3D) corners in object local space.
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_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 = 0.5, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> bool
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 register_custom_wireframe_box_template(sim: habitat_sim.simulator.Simulator, size: _magnum.Vector3, template_name: str = 'custom_wireframe_box') -> str
Generate and register a custom template for a wireframe box of given size. Return the new template’s handle.
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.

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.

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 = 0.3) -> bool

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.

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.

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.

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.

def habitat.sims.habitat_simulator.sim_utilities.get_ao_root_bb(ao: habitat_sim._ext.habitat_sim_bindings.ManagedArticulatedObject) -> _magnum.Range3D

Get the local bounding box of all links of an articulated object in the root frame.

Parameters
ao The ArticulatedObject instance.

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

Computes a dictionary mapping AO handles to a global bounding box of parts. Must be updated when AO state changes to correctly bound the full set of links.

Parameters
sim The Simulator instance.

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.

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.

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.

param sim:
The Simulator instance.
param region_index:
The index of the Region within which to sample.
param 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.
param max_center_samples:
The number of samples near the center point to attempt if applicable. This will be done first. <=0 skips center sampling.
param max_global_samples:
The number of global navmesh samples to attempt if center point samples were unsuccessful. <=0 skips this step.
param 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.
return:
The sampled floor point within the given region or None if a point could not be found.

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.

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.

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.

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.

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

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

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.

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.

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.

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 = 0.5, ao_link_map: typing.Optional[typing.Dict[int, int]] = None) -> bool

Parameters
sim The Simulator instance.
object_id_a object_id of the first ManagedObject or link.
object_id_b object_id of the second ManagedObject or link.
hor_l2_threshold regularized horizontal L2 distance allow between the objects’ centers. This should be tailored to the scenario.
ao_link_map A pre-computed map from link object ids to their parent ArticulatedObject’s object id.

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.

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.

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.

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.

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.

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.

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.

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.