kaolin.physics.simplicits.SimplicitsScene¶
API¶
- class kaolin.physics.simplicits.SimplicitsScene(device='cuda', direct_solve=True, use_cuda_graphs=False, timestep=0.03, max_newton_steps=5, max_ls_steps=10, newton_hessian_regularizer=0.0001, cg_tol=0.0001, cg_iters=100, conv_tol=0.0001)¶
Bases:
object- __init__(device='cuda', direct_solve=True, use_cuda_graphs=False, timestep=0.03, max_newton_steps=5, max_ls_steps=10, newton_hessian_regularizer=0.0001, cg_tol=0.0001, cg_iters=100, conv_tol=0.0001)¶
Initializes a simplicits scene. SimplicitsObjects can be added to the scene. Scene forces such as floor and gravity can be set on the scene. The scene defaults to using float32 for all computations.
- Parameters
device (str, optional) – Defaults to ‘cuda’.
direct_solve (bool, optional) – Whether to use direct solve for linear system. Defaults to True.
use_cuda_graphs (bool, optional) – Whether to use cuda graphs. Defaults to False.
timestep (float, optional) – Sim time-step. Defaults to 0.03.
max_newton_steps (int, optional) – Newton steps used in time integrator. Defaults to 5.
max_ls_steps (int, optional) – Line search steps used in time integrator. Defaults to 10.
newton_hessian_regularizer (float, optional) – Regularizer for hessian. Defaults to 1e-4.
cg_tol (float, optional) – Tolerance for conjugate gradient. Defaults to 1e-4.
cg_iters (int, optional) – Maximum number of conjugate gradient iterations. Defaults to 100.
conv_tol (float, optional) – Newtons Method convergence tolerance. Defaults to 1e-4.
- add_object(sim_object: Union[SimplicitsObject, SkinnedPhysicsPoints], num_qp=None, init_transform=None, is_kinematic=False, renderable_pts=None, normalize_weights_by_samples=True, apply_qr=True)¶
Adds a simplicits object to the scene as a SimulatedObject. Can add a just trained SimplicitsObject which contains a skinning weight field, or can also accept a baked version, sufficient for simulation.
Optionally allows the scene to keep track of a rendered entity, such as all the Gaussian points.
- Parameters
sim_object (SimplicitsObject | SkinnedPhysicsPoints) – trained simplicits object or already sampled skinned points, e.g. from USD file
num_qp (int, optional) – Number of quadrature points (sample points to integrate over). If not provided, the object will not be subsampled.
init_transform (torch.Tensor) – 3x4 or 4x4 torch tensor specifying object’s initial skinning transform. This argument takes a standard transformation, not a delta. Subsequently, the Identity matrix is subtracted from it and the delta transform is saved.
is_kinematic (bool) – Object is kinematic if it is not solved for during dynamics simulation.
renderable_pts (torch.Tensor, optional) – Points for rendering (e.g. Gaussian splat positions, in \(m\)). When provided and sim_object is a SimplicitsObject, skinning weights are baked for these points and stored in the SimulatedObject for use with get_object_deformed_pts(…, points=’rendered’). This is not to be used with already baked SkinnedPhysicsPointsProtocol.
normalize_weights_by_samples (bool) – If True, L2-normalize skinning weights over the sample set for better conditioning of the Newton system. Default: True.
apply_qr (bool) – If True, apply QR decomposition to orthogonalize the LBS basis. Default: True.
- Returns
The id assigned to the newly added object, usable with the other
get_object_*/set_object_*methods on this scene.- Return type
- enable_collisions(collision_particle_radius=0.1, detection_ratio=1.5, impenetrable_barrier_ratio=0.25, collision_penalty=1000.0, max_contact_pairs=10000, friction=0.5)¶
Sets collision for object in scene
- Parameters
collision_particle_radius (float, optional) – Scene-wide collision particle radius at which penalty begins to apply. Change this depending on the size of the object. Defaults: 0.1.
detection_ratio (float, optional) – Collision detection radius described as a ratio relative to the collision_particle_radius. Defaults: 1.5 times the collision_particle_radius.
impenetrable_barrier_ratio (float, optional) – Collision barrier radius described as a ratio relative to the collision_particle_radius. Defaults: 0.25 times the collision_particle_radius.
collision_penalty (float, optional) – Controls the stiffness of the collision interaction. Defaults: 1000 times the collision_particle_radius.
max_contact_pairs (int, optional) – Maximum number of contact pairs to detect. If this is too low, some contacts may be missed. If this is too high, memory may run out/jacobian may be too large. Defaults: 10000 contact pairs.
friction (float, optional) – Friction coefficient. Defaults: 0.5.
- get_object(obj_idx)¶
Get a particular object in the scene by its id.
- Parameters
obj_idx (int) – Id of object
- Returns
Simulated Object used by the scene. Also contains ref to simplicits object.
- Return type
- get_object_deformed_pts(obj_idx, points: Literal['rendered', 'simulated'] = 'simulated')¶
Applies linear blend skinning using object’s transformation to points provided.
- Parameters
- Returns
Transformed points
- Return type
- get_object_point_transforms(obj_idx, points: Literal['rendered', 'simulated'] = 'simulated')¶
Returns the absolute transform of the points of an object.
- Parameters
- Returns
Torch tensor of size \((\text{num_points}, 4, 4)\) for transforms.
- Return type
- get_object_transforms(object_id)¶
Returns the current 4x4 padded relative transforms in raw (physical) space.
Undoes any internal normalization (weight norms, QR) so the transforms can be used with unnormalized skinning weights (e.g. rendered points).
- Parameters
object_id (int) – Id of the object to get the transforms of
- Returns
Torch tensor of size \(( ext{num_handles}, 4, 4)\) for relative transforms.
- Return type
- reset_scene()¶
Resets the scene and all objects in it.
- run_sim_step()¶
Runs a single simulation step.
- set_kinematic_object_transform(obj_idx, transform)¶
Sets the transform of a kinematic object. This can be done during simulation to script the kinematic object’s motion.
- Parameters
obj_idx (int) – Id of object
transform (torch.Tensor) – 3x4 or 4x4 torch tensor specifying object’s transform.
- set_object_boundary_condition(obj_idx, name, fcn, bdry_penalty=10000.0, pinned_x=None)¶
Sets boundary condition for object in scene
- Parameters
obj_idx (int) – Id of object
name (str) – Boundary condition name
fcn (Callable) – Function that defines which indices the boundary condition applies to. fcn should return a boolean \((n)\) vector where bdry indices are 1.
bdry_penalty (float) – Boundary condition penalty coefficient.
pinned_x (torch.Tensor, optional) – Pinned positions of the boundary condition. Used for setting the boundary to a specific position. Default: The pinned positions are set from the current object’s positions.
- set_object_initial_transform(object_id, init_transform)¶
Sets the initial transform of an object.
Note
This method reset the scene
- Parameters
object_id (int) – Id of the object to set the initial transform of
init_transform (torch.Tensor) – 4x4 torch tensor specifying object’s initial skinning transform. This argument takes a standard transformation, not a delta. Subsequently, the Identity matrix is subtracted from it and the delta transform is saved.
- set_scene_floor(floor_height=0.0, floor_axis=1, floor_penalty=10000.0, flip_floor=False)¶
Sets the floor in the scene. Applies it to all objects in scene.
- Parameters
floor_height (float, optional) – Floor height. Defaults to 0.
floor_axis (int, optional) – Direction of floor. 0 is x, 1 is y, 2 is z. Defaults to 1.
floor_penalty (float, optional) – Stiffness of floor. Defaults to 10000.
flip_floor (bool, optional) – Flips the direction of the floor. Defaults to False.
- set_scene_gravity(acc_gravity=tensor([0.0000, 9.8000, 0.0000]), gravity_coeff=1.0)¶
Sets the gravity in the scene. Applies it to all objects in scene.
- Parameters
acc_gravity (torch.Tensor, optional) – Gravity acceleration. Defaults to torch.tensor([0, 9.8, 0]) with acceleration due to gravity in the downward y direction.
gravity_coeff (float, optional) – Gravity coefficient. Defaults to 1.0.