Skip to content

base

Abstract interface for a pluggable physics-engine backend.

The Simulator constructs one PhysicsBackend instance (exposed as og.sim.physics_backend), chosen via gm.PHYSICS_BACKEND.

Rendering lives in the sibling render_backends.RenderBackend interface.

PhysicsBackend

Bases: ABC

Abstract base class for a physics engine backend.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
class PhysicsBackend(ABC):
    """
    Abstract base class for a physics engine backend.
    """

    def __init__(self, sim=None):
        self.sim = sim

    # ---- Application lifecycle ----

    @classmethod
    def create_app(cls):
        """
        Creates and returns the application this backend needs to run at all. Called on the class,
        before any Simulator or backend instance exists, from `Simulator._launch_app()`.
        """
        raise NotImplementedError

    def assert_clean_start(self):
        """
        Raises if process-global state left over from a previous Simulator would break this backend.
        Called at the very top of `Simulator.__init__`. Default no-op.
        """

    def before_clear(self):
        """
        Hook called by `og.clear()` immediately before the Simulator tears down everything it owns.
        """

    def after_clear(self):
        """
        Hook called by `og.clear()` immediately after `Simulator._partial_clear()`, to undo
        `before_clear()` and release whatever engine-global state would otherwise leak into the
        replacement Simulator.
        """

    def finalize(self):
        """
        Hook called by `og.clear()` after `og.sim` has already been dropped, for engine-global
        teardown that must outlive the Simulator it belonged to.
        """

    def in_warmup(self):
        """
        Whether the engine is currently inside its own internal warmup stepping, during which
        OmniGibson's per-step controller/view bookkeeping must be skipped.

        Returns:
            bool: True if warming up. Default False; a backend with no concept of warmup returns False.
        """
        return False

    @abstractmethod
    def add_ground_plane(self, prim_path, visible=True, color=None):
        """
        Creates this backend's ground-plane collider at @prim_path.

        Args:
            prim_path (str): Absolute prim path to create the ground plane at.
            visible (bool): Whether the plane should be visible to a renderer.
            color (None or 3-array): Optional RGB color.
        """

    def enable_extensions(self):
        """
        One-time, process-level setup performed once before any Simulator/Kit app exists (called from
        `Simulator._launch_app()` on a transient, sim-less backend instance).
        """

    def before_play(self, sim):
        """
        Hook called every time `Simulator.play()` transitions from stopped to playing.
        """

    # ---- Lifecycle ----

    @abstractmethod
    def create_physics_context(self, physics_dt, rendering_dt, device):
        """Construct the sim-lifecycle context this backend uses for play/pause/stop/current_time bookkeeping."""

    @abstractmethod
    def stop_step_callbacks(self):
        """
        Tears down the subscriptions made by start_step_callbacks().
        """

    @abstractmethod
    def start_step_callbacks(self, pre_step_fn, post_step_fn, joint_break_fn):
        """
        Register the given callables to be invoked right before / after each physics step, and whenever
        a simulation event occurs.
        """

    @abstractmethod
    def apply_engine_settings(
        self,
        gravity,
        enable_ccd,
        use_gpu_dynamics,
        gpu_pairs_capacity,
        gpu_aggr_pairs_capacity,
        gpu_max_particle_contacts,
        gpu_max_rigid_contact_count,
        gpu_max_rigid_patch_count,
    ):
        """Apply global engine settings (gravity, CCD, GPU dynamics, buffer capacities)."""

    @abstractmethod
    def get_physics_context(self):
        """Return the low-level physics scene context object (used by particle/cloth authoring code)."""

    @property
    @abstractmethod
    def stage(self):
        """The USD stage backing this simulation."""

    @property
    @abstractmethod
    def current_time(self):
        pass

    @property
    @abstractmethod
    def current_time_step_index(self):
        pass

    @property
    @abstractmethod
    def initial_physics_dt(self):
        pass

    @property
    @abstractmethod
    def initial_rendering_dt(self):
        pass

    @abstractmethod
    def is_playing(self):
        pass

    @abstractmethod
    def is_stopped(self):
        pass

    @abstractmethod
    def get_physics_dt(self):
        pass

    @abstractmethod
    def get_rendering_dt(self):
        pass

    @abstractmethod
    def set_simulation_dt(self, physics_dt=None, rendering_dt=None):
        pass

    @abstractmethod
    def get_device(self):
        pass

    @abstractmethod
    def set_device(self, device):
        pass

    @abstractmethod
    def play(self):
        pass

    @abstractmethod
    def pause(self):
        pass

    @abstractmethod
    def stop(self):
        pass

    @abstractmethod
    def render(self):
        pass

    @abstractmethod
    def step(self, render):
        """Advance the underlying sim context and renderer by one step."""

    @abstractmethod
    def step_physics_once(self, current_time):
        """Advance physics only, used for manual single-step physics."""

    @property
    @abstractmethod
    def physics_sim_view(self):
        """
        The engine's batch-view factory object, exposing ``create_articulation_view(pattern)``,
        ``create_rigid_contact_view(pattern, filter_patterns, max_contact_data_count)``, and
        ``create_rigid_body_view(pattern)`` for pattern-based, scene-wide batch views.
        """

    @abstractmethod
    def refresh_physics_sim_view(self):
        """Rebuild/invalidate the batch physics views after the set of prims in the stage has changed."""

    @abstractmethod
    def invalidate_physics_sim_view(self):
        """
        Preemptively invalidate/de-initialize the batch physics views. A no-op if
        no view currently exists.
        """

    @abstractmethod
    def flush_changes(self):
        """Flush any pending USD changes into the physics engine's own simulation state."""

    @abstractmethod
    def sync_to_render_layer(self):
        """
        Push physics-side pose changes into the renderer layer (e.g. Fabric).
        """

    # ---- Batched DOF target writes ----
    #
    # @view is one of this backend's own articulation views. These methods take it explicitly because the
    # caller (`BatchControlViewAPIImpl`) holds one view spanning every controllable object rather
    # than one per prim.

    @abstractmethod
    def set_dof_position_targets(self, view, data, indices, cast=False):
        """Writes DOF position targets @data at @indices through @view."""

    @abstractmethod
    def set_dof_velocity_targets(self, view, data, indices, cast=False):
        """Writes DOF velocity targets @data at @indices through @view."""

    @abstractmethod
    def set_dof_actuation_forces(self, view, data, indices, cast=False):
        """Writes DOF actuation forces @data at @indices through @view."""

    # ---- Prim transform reads ----

    @abstractmethod
    def get_world_transform_with_scale(self, prim_path):
        """
        Returns:
            Gf.Matrix4d: @prim_path's world transform, including scale, read from wherever this
                backend keeps live poses.
        """

    @abstractmethod
    def get_local_transform_with_scale(self, prim_path):
        """
        Returns:
            Gf.Matrix4d: @prim_path's local (parent-relative) transform, including scale.
        """

    # ---- Engine-specific USD schema authoring ----
    #
    # OmniGibson authors the generic `UsdPhysics.*` schemas itself -- those are engine-agnostic and
    # every backend understands them. These hooks are for whatever an engine needs in addition.

    def apply_rigid_body_schemas(self, prim):
        """Applies any engine-specific rigid-body schema to @prim."""

    def apply_collision_schemas(self, prim):
        """Applies any engine-specific collider schema to @prim."""

    def configure_collision_approximation(self, prim, approximation_type):
        """
        Applies the engine-specific schema and tuning for @approximation_type (one of "convexHull",
        "convexDecomposition", "meshSimplification", "sdf", "none", ...) on @prim.
        """

    def apply_joint_schemas(self, prim):
        """Applies any engine-specific joint schema to @prim."""

    def apply_articulation_schemas(self, prim, self_collisions=False):
        """
        Applies any engine-specific articulation-root schema to @prim, configured for
        @self_collisions.
        """

    def strip_articulation_schemas(self, prim):
        """
        Removes any engine-specific articulation-root schema from @prim (the generic
        `UsdPhysics.ArticulationRootAPI` is removed by the caller).
        """

    def enable_contact_reporting(self, prim):
        """
        Opts @prim into per-body contact reporting, for an engine that needs it requested per body.
        """

    def contact_reporting_enabled(self, prim, visual_only):
        """
        Returns:
            bool: Whether contact reporting is active for @prim. Defaults to every
                non-visual-only body).
        """
        return not visual_only

    def get_collision_api(self, prim):
        """
        Returns:
            None or object: @prim's engine-specific collider API handle, whose attributes the caller
                writes collider settings through, or None if this engine has no such API.
        """
        return None

    def is_mimic_joint(self, prim):
        """
        Returns:
            bool: Whether @prim is a mimic joint (one whose motion is slaved to another joint's).
                Default False.
        """
        return False

    # ---- Per-prim articulation view I/O (backs EntityPrim / JointPrim) ----

    @abstractmethod
    def create_articulation_view(self, prim_path):
        """
        Return a handle for the articulation rooted at ``prim_path``, exposing: joint
        position/velocity/effort get+set, position/velocity targets, coriolis/gravity/mass-matrix/
        jacobian, world-pose set, solver iteration counts, and the public ``joint_count``/
        ``joint_dof_counts``/``joint_names``/``joint_dof_offsets``/``dof_path``/``dof_index_of_path``
        DOF-layout accessors, plus ``has_dof_metadata`` reporting whether those accessors are usable
        yet.
        """

    # ---- Per-prim rigid-body view I/O (backs RigidDynamicPrim) ----

    @abstractmethod
    def create_rigid_body_view(self, prim_path):
        """
        Return a handle for the rigid body at ``prim_path``, exposing: linear/angular
        velocity get+set, world-pose get+set, center-of-mass/mass/density get+set, and gravity
        enable/disable.
        """

    # ---- Sleep / wake ----

    @abstractmethod
    def is_asleep(self, prim_path):
        pass

    @abstractmethod
    def wake(self, prim_path):
        pass

    @abstractmethod
    def sleep(self, prim_path):
        pass

    @abstractmethod
    def apply_force_at_pos(self, prim_path, force, pos):
        pass

    @abstractmethod
    def apply_torque(self, prim_path, torque):
        pass

    # ---- Scene queries / raycasts ----

    @abstractmethod
    def raycast_closest(self, *args, **kwargs):
        pass

    def raycast_closest_batch(self, origins, dirs, distances):
        """
        Closest hit for a batch of rays.

        Args:
            origins (list of 3-array): per-ray (x,y,z) world-frame ray origin
            dirs (list of 3-array): per-ray unit-length world-frame ray direction
            distances (list of float): per-ray maximum hit distance

        Returns:
            list of dict: one raycast_closest() result per input ray, in the same order
        """
        return [
            self.raycast_closest(origin=origin, dir=dir, distance=distance)
            for origin, dir, distance in zip(origins, dirs, distances)
        ]

    @abstractmethod
    def raycast_all(self, *args, **kwargs):
        pass

    @abstractmethod
    def overlap_sphere(self, *args, **kwargs):
        pass

    @abstractmethod
    def overlap_box(self, *args, **kwargs):
        pass

    @abstractmethod
    def overlap_mesh(self, *args, **kwargs):
        pass

    @abstractmethod
    def overlap_shape(self, *args, **kwargs):
        pass

    @abstractmethod
    def overlap_sphere_any(self, radius, pos):
        pass

    # ---- Cloth particle state I/O (backs ClothPrim) ----
    # Positions/velocities are always in the WORLD frame -- each backend hides its own internal
    # convention (e.g. a local-mesh-frame USD attribute vs. an already-world-space solver state array).

    @abstractmethod
    def get_cloth_particle_positions(self, prim_path, idxs=None):
        """Return an (N, 3) (or (len(idxs), 3) if idxs given) world-frame particle position tensor."""

    @abstractmethod
    def set_cloth_particle_positions(self, prim_path, positions, idxs=None):
        """Set world-frame particle positions (shape must match get_cloth_particle_positions)."""

    @abstractmethod
    def get_cloth_particle_velocities(self, prim_path):
        """Return an (N, 3) world-frame particle velocity tensor."""

    @abstractmethod
    def set_cloth_particle_velocities(self, prim_path, velocities):
        """Set world-frame particle velocities (shape must match get_cloth_particle_velocities)."""

    @abstractmethod
    def get_cloth_stiffness(self, prim_path):
        """Return a dict with 'bend'/'damping'/'shear'/'stretch' stiffness values for this cloth."""

    @abstractmethod
    def set_cloth_stiffness(self, prim_path, bend=None, damping=None, shear=None, stretch=None):
        """Set any subset of this cloth's bend/damping/shear/stretch stiffness values (None = unchanged)."""

    # ---- Joint-break events ----

    @abstractmethod
    def is_joint_break_event(self, event):
        pass

    @abstractmethod
    def decode_joint_break_event(self, event):
        """Return the broken joint's prim path as a string, given a raw backend event."""

physics_sim_view abstractmethod property

The engine's batch-view factory object, exposing create_articulation_view(pattern), create_rigid_contact_view(pattern, filter_patterns, max_contact_data_count), and create_rigid_body_view(pattern) for pattern-based, scene-wide batch views.

stage abstractmethod property

The USD stage backing this simulation.

add_ground_plane(prim_path, visible=True, color=None) abstractmethod

Creates this backend's ground-plane collider at @prim_path.

Parameters:

Name Type Description Default
prim_path str

Absolute prim path to create the ground plane at.

 required
visible bool

Whether the plane should be visible to a renderer.

 True
color None or 3 - array

Optional RGB color.

 None
Source code in OmniGibson/omnigibson/physics_backends/base.py 
65
66
67
68
69
70
71
72
73
74
@abstractmethod
def add_ground_plane(self, prim_path, visible=True, color=None):
    """
    Creates this backend's ground-plane collider at @prim_path.

    Args:
        prim_path (str): Absolute prim path to create the ground plane at.
        visible (bool): Whether the plane should be visible to a renderer.
        color (None or 3-array): Optional RGB color.
    """

after_clear()

Hook called by og.clear() immediately after Simulator._partial_clear(), to undo before_clear() and release whatever engine-global state would otherwise leak into the replacement Simulator.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
42
43
44
45
46
47
def after_clear(self):
    """
    Hook called by `og.clear()` immediately after `Simulator._partial_clear()`, to undo
    `before_clear()` and release whatever engine-global state would otherwise leak into the
    replacement Simulator.
    """

apply_articulation_schemas(prim, self_collisions=False)

Applies any engine-specific articulation-root schema to @prim, configured for @self_collisions.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
286
287
288
289
290
def apply_articulation_schemas(self, prim, self_collisions=False):
    """
    Applies any engine-specific articulation-root schema to @prim, configured for
    @self_collisions.
    """

apply_collision_schemas(prim)

Applies any engine-specific collider schema to @prim.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
274
275
def apply_collision_schemas(self, prim):
    """Applies any engine-specific collider schema to @prim."""

apply_engine_settings(gravity, enable_ccd, use_gpu_dynamics, gpu_pairs_capacity, gpu_aggr_pairs_capacity, gpu_max_particle_contacts, gpu_max_rigid_contact_count, gpu_max_rigid_patch_count) abstractmethod

Apply global engine settings (gravity, CCD, GPU dynamics, buffer capacities).

Source code in OmniGibson/omnigibson/physics_backends/base.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
@abstractmethod
def apply_engine_settings(
    self,
    gravity,
    enable_ccd,
    use_gpu_dynamics,
    gpu_pairs_capacity,
    gpu_aggr_pairs_capacity,
    gpu_max_particle_contacts,
    gpu_max_rigid_contact_count,
    gpu_max_rigid_patch_count,
):
    """Apply global engine settings (gravity, CCD, GPU dynamics, buffer capacities)."""

apply_joint_schemas(prim)

Applies any engine-specific joint schema to @prim.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
283
284
def apply_joint_schemas(self, prim):
    """Applies any engine-specific joint schema to @prim."""

apply_rigid_body_schemas(prim)

Applies any engine-specific rigid-body schema to @prim.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
271
272
def apply_rigid_body_schemas(self, prim):
    """Applies any engine-specific rigid-body schema to @prim."""

assert_clean_start()

Raises if process-global state left over from a previous Simulator would break this backend. Called at the very top of Simulator.__init__. Default no-op.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
31
32
33
34
35
def assert_clean_start(self):
    """
    Raises if process-global state left over from a previous Simulator would break this backend.
    Called at the very top of `Simulator.__init__`. Default no-op.
    """

before_clear()

Hook called by og.clear() immediately before the Simulator tears down everything it owns.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
37
38
39
40
def before_clear(self):
    """
    Hook called by `og.clear()` immediately before the Simulator tears down everything it owns.
    """

before_play(sim)

Hook called every time Simulator.play() transitions from stopped to playing.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
82
83
84
85
def before_play(self, sim):
    """
    Hook called every time `Simulator.play()` transitions from stopped to playing.
    """

configure_collision_approximation(prim, approximation_type)

Applies the engine-specific schema and tuning for @approximation_type (one of "convexHull", "convexDecomposition", "meshSimplification", "sdf", "none", ...) on @prim.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
277
278
279
280
281
def configure_collision_approximation(self, prim, approximation_type):
    """
    Applies the engine-specific schema and tuning for @approximation_type (one of "convexHull",
    "convexDecomposition", "meshSimplification", "sdf", "none", ...) on @prim.
    """

contact_reporting_enabled(prim, visual_only)

Returns:

Type Description
bool

Whether contact reporting is active for @prim. Defaults to every non-visual-only body).
Source code in OmniGibson/omnigibson/physics_backends/base.py 
303
304
305
306
307
308
309
def contact_reporting_enabled(self, prim, visual_only):
    """
    Returns:
        bool: Whether contact reporting is active for @prim. Defaults to every
            non-visual-only body).
    """
    return not visual_only

create_app() classmethod

Creates and returns the application this backend needs to run at all. Called on the class, before any Simulator or backend instance exists, from Simulator._launch_app().

Source code in OmniGibson/omnigibson/physics_backends/base.py 
23
24
25
26
27
28
29
@classmethod
def create_app(cls):
    """
    Creates and returns the application this backend needs to run at all. Called on the class,
    before any Simulator or backend instance exists, from `Simulator._launch_app()`.
    """
    raise NotImplementedError

create_articulation_view(prim_path) abstractmethod

Return a handle for the articulation rooted at prim_path, exposing: joint position/velocity/effort get+set, position/velocity targets, coriolis/gravity/mass-matrix/ jacobian, world-pose set, solver iteration counts, and the public joint_count/ joint_dof_counts/joint_names/joint_dof_offsets/dof_path/dof_index_of_path DOF-layout accessors, plus has_dof_metadata reporting whether those accessors are usable yet.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
329
330
331
332
333
334
335
336
337
338
@abstractmethod
def create_articulation_view(self, prim_path):
    """
    Return a handle for the articulation rooted at ``prim_path``, exposing: joint
    position/velocity/effort get+set, position/velocity targets, coriolis/gravity/mass-matrix/
    jacobian, world-pose set, solver iteration counts, and the public ``joint_count``/
    ``joint_dof_counts``/``joint_names``/``joint_dof_offsets``/``dof_path``/``dof_index_of_path``
    DOF-layout accessors, plus ``has_dof_metadata`` reporting whether those accessors are usable
    yet.
    """

create_physics_context(physics_dt, rendering_dt, device) abstractmethod

Construct the sim-lifecycle context this backend uses for play/pause/stop/current_time bookkeeping.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
89
90
91
@abstractmethod
def create_physics_context(self, physics_dt, rendering_dt, device):
    """Construct the sim-lifecycle context this backend uses for play/pause/stop/current_time bookkeeping."""

create_rigid_body_view(prim_path) abstractmethod

Return a handle for the rigid body at prim_path, exposing: linear/angular velocity get+set, world-pose get+set, center-of-mass/mass/density get+set, and gravity enable/disable.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
342
343
344
345
346
347
348
@abstractmethod
def create_rigid_body_view(self, prim_path):
    """
    Return a handle for the rigid body at ``prim_path``, exposing: linear/angular
    velocity get+set, world-pose get+set, center-of-mass/mass/density get+set, and gravity
    enable/disable.
    """

decode_joint_break_event(event) abstractmethod

Return the broken joint's prim path as a string, given a raw backend event.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
453
454
455
@abstractmethod
def decode_joint_break_event(self, event):
    """Return the broken joint's prim path as a string, given a raw backend event."""

enable_contact_reporting(prim)

Opts @prim into per-body contact reporting, for an engine that needs it requested per body.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
298
299
300
301
def enable_contact_reporting(self, prim):
    """
    Opts @prim into per-body contact reporting, for an engine that needs it requested per body.
    """

enable_extensions()

One-time, process-level setup performed once before any Simulator/Kit app exists (called from Simulator._launch_app() on a transient, sim-less backend instance).

Source code in OmniGibson/omnigibson/physics_backends/base.py 
76
77
78
79
80
def enable_extensions(self):
    """
    One-time, process-level setup performed once before any Simulator/Kit app exists (called from
    `Simulator._launch_app()` on a transient, sim-less backend instance).
    """

finalize()

Hook called by og.clear() after og.sim has already been dropped, for engine-global teardown that must outlive the Simulator it belonged to.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
49
50
51
52
53
def finalize(self):
    """
    Hook called by `og.clear()` after `og.sim` has already been dropped, for engine-global
    teardown that must outlive the Simulator it belonged to.
    """

flush_changes() abstractmethod

Flush any pending USD changes into the physics engine's own simulation state.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
221
222
223
@abstractmethod
def flush_changes(self):
    """Flush any pending USD changes into the physics engine's own simulation state."""

get_cloth_particle_positions(prim_path, idxs=None) abstractmethod

Return an (N, 3) (or (len(idxs), 3) if idxs given) world-frame particle position tensor.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
423
424
425
@abstractmethod
def get_cloth_particle_positions(self, prim_path, idxs=None):
    """Return an (N, 3) (or (len(idxs), 3) if idxs given) world-frame particle position tensor."""

get_cloth_particle_velocities(prim_path) abstractmethod

Return an (N, 3) world-frame particle velocity tensor.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
431
432
433
@abstractmethod
def get_cloth_particle_velocities(self, prim_path):
    """Return an (N, 3) world-frame particle velocity tensor."""

get_cloth_stiffness(prim_path) abstractmethod

Return a dict with 'bend'/'damping'/'shear'/'stretch' stiffness values for this cloth.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
439
440
441
@abstractmethod
def get_cloth_stiffness(self, prim_path):
    """Return a dict with 'bend'/'damping'/'shear'/'stretch' stiffness values for this cloth."""

get_collision_api(prim)

Returns:

Type Description
None or object

@prim's engine-specific collider API handle, whose attributes the caller writes collider settings through, or None if this engine has no such API.
Source code in OmniGibson/omnigibson/physics_backends/base.py 
311
312
313
314
315
316
317
def get_collision_api(self, prim):
    """
    Returns:
        None or object: @prim's engine-specific collider API handle, whose attributes the caller
            writes collider settings through, or None if this engine has no such API.
    """
    return None

get_local_transform_with_scale(prim_path) abstractmethod

Returns:

Type Description
Matrix4d

@prim_path's local (parent-relative) transform, including scale.
Source code in OmniGibson/omnigibson/physics_backends/base.py 
259
260
261
262
263
264
@abstractmethod
def get_local_transform_with_scale(self, prim_path):
    """
    Returns:
        Gf.Matrix4d: @prim_path's local (parent-relative) transform, including scale.
    """

get_physics_context() abstractmethod

Return the low-level physics scene context object (used by particle/cloth authoring code).

Source code in OmniGibson/omnigibson/physics_backends/base.py 
120
121
122
@abstractmethod
def get_physics_context(self):
    """Return the low-level physics scene context object (used by particle/cloth authoring code)."""

get_world_transform_with_scale(prim_path) abstractmethod

Returns:

Type Description
Matrix4d

@prim_path's world transform, including scale, read from wherever this backend keeps live poses.
Source code in OmniGibson/omnigibson/physics_backends/base.py 
251
252
253
254
255
256
257
@abstractmethod
def get_world_transform_with_scale(self, prim_path):
    """
    Returns:
        Gf.Matrix4d: @prim_path's world transform, including scale, read from wherever this
            backend keeps live poses.
    """

in_warmup()

Whether the engine is currently inside its own internal warmup stepping, during which OmniGibson's per-step controller/view bookkeeping must be skipped.

Returns:

Type Description
bool

True if warming up. Default False; a backend with no concept of warmup returns False.
Source code in OmniGibson/omnigibson/physics_backends/base.py 
55
56
57
58
59
60
61
62
63
def in_warmup(self):
    """
    Whether the engine is currently inside its own internal warmup stepping, during which
    OmniGibson's per-step controller/view bookkeeping must be skipped.

    Returns:
        bool: True if warming up. Default False; a backend with no concept of warmup returns False.
    """
    return False

invalidate_physics_sim_view() abstractmethod

Preemptively invalidate/de-initialize the batch physics views. A no-op if no view currently exists.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
214
215
216
217
218
219
@abstractmethod
def invalidate_physics_sim_view(self):
    """
    Preemptively invalidate/de-initialize the batch physics views. A no-op if
    no view currently exists.
    """

is_mimic_joint(prim)

Returns:

Type Description
bool

Whether @prim is a mimic joint (one whose motion is slaved to another joint's). Default False.
Source code in OmniGibson/omnigibson/physics_backends/base.py 
319
320
321
322
323
324
325
def is_mimic_joint(self, prim):
    """
    Returns:
        bool: Whether @prim is a mimic joint (one whose motion is slaved to another joint's).
            Default False.
    """
    return False

raycast_closest_batch(origins, dirs, distances)

Closest hit for a batch of rays.

Parameters:

Name Type Description Default
origins list of 3-array

per-ray (x,y,z) world-frame ray origin

 required
dirs list of 3-array

per-ray unit-length world-frame ray direction

 required
distances list of float

per-ray maximum hit distance

 required

Returns:

Type Description
list of dict

one raycast_closest() result per input ray, in the same order
Source code in OmniGibson/omnigibson/physics_backends/base.py 
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
def raycast_closest_batch(self, origins, dirs, distances):
    """
    Closest hit for a batch of rays.

    Args:
        origins (list of 3-array): per-ray (x,y,z) world-frame ray origin
        dirs (list of 3-array): per-ray unit-length world-frame ray direction
        distances (list of float): per-ray maximum hit distance

    Returns:
        list of dict: one raycast_closest() result per input ray, in the same order
    """
    return [
        self.raycast_closest(origin=origin, dir=dir, distance=distance)
        for origin, dir, distance in zip(origins, dirs, distances)
    ]

refresh_physics_sim_view() abstractmethod

Rebuild/invalidate the batch physics views after the set of prims in the stage has changed.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
210
211
212
@abstractmethod
def refresh_physics_sim_view(self):
    """Rebuild/invalidate the batch physics views after the set of prims in the stage has changed."""

set_cloth_particle_positions(prim_path, positions, idxs=None) abstractmethod

Set world-frame particle positions (shape must match get_cloth_particle_positions).

Source code in OmniGibson/omnigibson/physics_backends/base.py 
427
428
429
@abstractmethod
def set_cloth_particle_positions(self, prim_path, positions, idxs=None):
    """Set world-frame particle positions (shape must match get_cloth_particle_positions)."""

set_cloth_particle_velocities(prim_path, velocities) abstractmethod

Set world-frame particle velocities (shape must match get_cloth_particle_velocities).

Source code in OmniGibson/omnigibson/physics_backends/base.py 
435
436
437
@abstractmethod
def set_cloth_particle_velocities(self, prim_path, velocities):
    """Set world-frame particle velocities (shape must match get_cloth_particle_velocities)."""

set_cloth_stiffness(prim_path, bend=None, damping=None, shear=None, stretch=None) abstractmethod

Set any subset of this cloth's bend/damping/shear/stretch stiffness values (None = unchanged).

Source code in OmniGibson/omnigibson/physics_backends/base.py 
443
444
445
@abstractmethod
def set_cloth_stiffness(self, prim_path, bend=None, damping=None, shear=None, stretch=None):
    """Set any subset of this cloth's bend/damping/shear/stretch stiffness values (None = unchanged)."""

set_dof_actuation_forces(view, data, indices, cast=False) abstractmethod

Writes DOF actuation forces @data at @indices through @view.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
245
246
247
@abstractmethod
def set_dof_actuation_forces(self, view, data, indices, cast=False):
    """Writes DOF actuation forces @data at @indices through @view."""

set_dof_position_targets(view, data, indices, cast=False) abstractmethod

Writes DOF position targets @data at @indices through @view.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
237
238
239
@abstractmethod
def set_dof_position_targets(self, view, data, indices, cast=False):
    """Writes DOF position targets @data at @indices through @view."""

set_dof_velocity_targets(view, data, indices, cast=False) abstractmethod

Writes DOF velocity targets @data at @indices through @view.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
241
242
243
@abstractmethod
def set_dof_velocity_targets(self, view, data, indices, cast=False):
    """Writes DOF velocity targets @data at @indices through @view."""

start_step_callbacks(pre_step_fn, post_step_fn, joint_break_fn) abstractmethod

Register the given callables to be invoked right before / after each physics step, and whenever a simulation event occurs.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
 99
100
101
102
103
104
@abstractmethod
def start_step_callbacks(self, pre_step_fn, post_step_fn, joint_break_fn):
    """
    Register the given callables to be invoked right before / after each physics step, and whenever
    a simulation event occurs.
    """

step(render) abstractmethod

Advance the underlying sim context and renderer by one step.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
193
194
195
@abstractmethod
def step(self, render):
    """Advance the underlying sim context and renderer by one step."""

step_physics_once(current_time) abstractmethod

Advance physics only, used for manual single-step physics.

Source code in OmniGibson/omnigibson/physics_backends/base.py 
197
198
199
@abstractmethod
def step_physics_once(self, current_time):
    """Advance physics only, used for manual single-step physics."""

stop_step_callbacks() abstractmethod

Tears down the subscriptions made by start_step_callbacks().

Source code in OmniGibson/omnigibson/physics_backends/base.py 
93
94
95
96
97
@abstractmethod
def stop_step_callbacks(self):
    """
    Tears down the subscriptions made by start_step_callbacks().
    """

strip_articulation_schemas(prim)

Removes any engine-specific articulation-root schema from @prim (the generic UsdPhysics.ArticulationRootAPI is removed by the caller).

Source code in OmniGibson/omnigibson/physics_backends/base.py 
292
293
294
295
296
def strip_articulation_schemas(self, prim):
    """
    Removes any engine-specific articulation-root schema from @prim (the generic
    `UsdPhysics.ArticulationRootAPI` is removed by the caller).
    """

sync_to_render_layer() abstractmethod

Push physics-side pose changes into the renderer layer (e.g. Fabric).

Source code in OmniGibson/omnigibson/physics_backends/base.py 
225
226
227
228
229
@abstractmethod
def sync_to_render_layer(self):
    """
    Push physics-side pose changes into the renderer layer (e.g. Fabric).
    """