kaolin.physics.simplicits

API

Classes

Other

class kaolin.physics.simplicits.SimulatedObject(pts, yms, prs, rhos, appx_vol, skinning_weights, dwdx, renderable: SkinnedPointsProtocol = None, init_transform=None, is_kinematic=False, normalize_weights_by_samples=False, apply_qr=False)

Bases: SkinnedPhysicsPoints

Class containing minimal information for a simulatable simplicits object AND ALSO all the variables and state variables needed to run actual simulation.

This class contains time-varying simulation state and is internal to the Simulator logic.

property B_dense
property dFdz_dense
classmethod from_skinned_physics_points(phys_pts: SkinnedPhysicsPoints, init_transform, is_kinematic=False, normalize_weights_by_samples=False, apply_qr=False)

Creates simulation object given skinned physics points, minimal data needed for Simplicits simulation (e.g. this data can be read from disk).

Parameters

  • phys_pts (SkinnedPhysicsPoints) – SkinnedPhysicsPoints object to use to define SimulatedObject properties.

  • init_transform – Initial transform of the SimulatedObject.

  • is_kinematic – If true, the object will be kinematic in the scene. Default: False.

  • normalize_weights_by_samples – If true, normalize skinning weights by L2 norm for better conditioning. Default: False.

  • apply_qr – If true, apply QR decomposition to orthogonalize the LBS basis. Default: False.

Returns

SimulatedObject object.

Return type

(SimulatedObject)

reset_sim_state()

Reset the simulation state. Object’s handle transforms are set back to initial deformations. This does not reset any material parameters or simplicits object parameters.

class kaolin.physics.simplicits.SkinningModule(bb_min=None, bb_max=None)

Bases: Module

Base class for skinning weight modules.

Handles bounding-box normalization and provides helpers to compute skinning weights (with a constant handle appended) and their spatial Jacobian for use in physics simulation.

Parameters

  • bb_min (torch.Tensor or array-like, optional) – Minimum corner of the bounding box used to normalize input points, of shape \((3,)\). Defaults to torch.zeros(3).

  • bb_max (torch.Tensor or array-like, optional) – Maximum corner of the bounding box used to normalize input points, of shape \((3,)\). Defaults to torch.ones(3).

compute_dwdx(pts)

Computes the Jacobian of the skinning weights with respect to the points.

Parameters

pts (torch.Tensor) – The points to be skinned, of shape \((N, 3)\) (in \(m\)).

Returns

The Jacobian of the skinning weights, of shape \((N, \text{num_handles}, 3)\).

Return type

torch.Tensor

compute_skinning_weights(pts)

Computes the skinning weights for the given points (including the normalization and padding with constant handle).

Parameters

pts (torch.Tensor) – The points to be skinned, of shape \((N, 3)\) (in \(m\)).

Returns

The skinning weights, of shape \((N, \text{num_handles})\).

Return type

torch.Tensor

static from_function(function: Callable, bb_min=0, bb_max=1)

Create a SkinningModule from a function.

Parameters

  • function (Callable) – The function to be used to compute the skinning weights.

  • bb_min (float or torch.Tensor or array-like, optional) – Minimum corner of the bounding box. Defaults to 0.

  • bb_max (float or torch.Tensor or array-like, optional) – Maximum corner of the bounding box. Defaults to 1.

Returns

A SkinningModule whose forward delegates to function.

Return type

SkinningModule

kaolin.physics.simplicits.compute_losses(skinning_mod, normalized_pts, yms, prs, rhos, en_interp, batch_size, appx_vol, num_samples, le_coeff, lo_coeff)

Perform a step of the simplicits training process

Parameters

  • skinning_mod (SkinningModule) – Skinning module

  • normalized_pts (torch.Tensor) – Spatial points in \(R^3\), of shape \((\text{num_pts}, 3)\)

  • yms (torch.Tensor) – Point-wise youngs modulus, of shape \((\text{num_pts})\) (in \(kg/m/s^2\))

  • prs (torch.Tensor) – Point-wise poissons ratio, of shape \((\text{num_pts})\)

  • rhos (torch.Tensor) – Point-wise density, of shape \((\text{num_pts})\) (in \(kg/m^3\))

  • en_interp (float) – interpolation between energy at current step

  • batch_size (int) – Number of sample deformations

  • appx_vol (float) – Approximate volume of object (in \(m^3\))

  • num_samples (int) – Number of sample points.

  • le_coeff (float) – floating point coefficient for elastic loss

  • lo_coeff (float) – floating point coefficient for orthogonal loss

Returns

The elastic loss term, the orthogonality losses terms

Return type

torch.Tensor, torch.Tensor

kaolin.physics.simplicits.compute_losses_warp(model, normalized_pts, yms, prs, rhos, en_interp, batch_size, num_handles, appx_vol, num_samples, le_coeff, lo_coeff)

Perform a step of the simplicits training process

Parameters

  • model (nn.module) – Simplicits network

  • normalized_pts (torch.Tensor) – Spatial points in \(\mathbb{R}^3\), of shape \((\text{num_pts}, 3)\)

  • yms (torch.Tensor) – Point-wise youngs modulus, of shape \((\text{num_pts})\) (in \(kg/m/s^2\))

  • prs (torch.Tensor) – Point-wise poissons ratio, of shape \((\text{num_pts})\)

  • rhos (torch.Tensor) – Point-wise density, of shape \((\text{num_pts})\) (in \(kg/m^3\))

  • en_interp (float) – interpolation between energy at current step

  • batch_size (int) – Number of sample deformations

  • num_handles (int) – Number of handles

  • appx_vol (float) – Approximate volume of object (in \(m^3\))

  • num_samples (int) – Number of sample points.

  • le_coeff (float) – floating point coefficient for elastic loss

  • lo_coeff (float) – floating point coefficient for orthogonal loss

Returns

The elastic loss term, the orthogonality losses terms

Return type

torch.Tensor, torch.Tensor

kaolin.physics.simplicits.jacobian_dF_dz(model, x0, z)

Calculates jacobian dF/dz

Parameters

  • model (nn.Module) – Simplicits object network + constant handle

  • x0 (torch.Tensor) – Matrix of sample points, of shape \((\text{num_samples}, 3)\)

  • z (torch.Tensor) – Vector of flattened transforms, of shape \((12 \text{num_samples})\)

Returns

Jacobian matrix, of shape \((9 \text{num_samples}, 12 \text{num_handles})\)

Return type

torch.Tensor

kaolin.physics.simplicits.lbs_matrix(x0, w)

Encodes the lbs equation \(x_i = sum(w(x^0_i)_j * T_j * \begin{pmatrix}x^0_i\\1\end{pmatrix},\; \forall \; j=0...\|handles\|)\) for all pts into matrix B such that flatten(x) = B(x0, w(x0))*flatten(T)

Parameters

  • x0 (torch.Tensor) – Input points, of shape \((\text{num_samples}, 3)\)

  • w (torch.Tensor) – Weights, of shape \((\text{num_samples}, \text{num_handles})\)

Returns

Matrix that encodes the lbs transformation, given a set of vertices and corresponding weights, shape \((3 \text{num_samples}, 12 \text{num_handles})\)

Return type

torch.Tensor

kaolin.physics.simplicits.loss_elastic(model, pts, yms, prs, rhos, transforms, appx_vol, interp_step, elasticity_type='neohookean', interp_material=False)

Calculate a version of simplicits elastic loss for training.

Parameters

  • model (SkinningModule) – Skinning module

  • pts (torch.Tensor) – Tensor of sample points in \(\mathbb{R}^dim\), for now dim=3, of shape \((\text{num_samples}, \text{dim})\) (in \(m\))

  • yms (torch.Tensor) – Length pt-wise youngs modulus, of shape \((\text{num_samples})\) (in \(kg/m/s^2\))

  • prs (torch.Tensor) – Length pt-wise poisson ratios, of shape \((\text{num_samples})\)

  • rhos (torch.Tensor) – Length pt-wise density, of shape \((\text{num_samples})\) (in \(kg/m^3\))

  • transforms (torch.Tensor) – Batch of sample transformations, of shape \((\text{batch_size}, \text{num_handles}, \text{dim}, \text{dim}+1)\)

  • appx_vol (float) – Approximate (or exact) volume of object (in \(m^3\))

  • interp_step (float) – Length interpolation schedule for neohookean elasticity (0%->100%)

Returns

Elastic loss, single value tensor

Return type

torch.Tensor

kaolin.physics.simplicits.loss_elastic_warp(model, pts, yms, prs, rhos, transforms, appx_vol, interp_step)

Calculate a version of simplicits elastic loss for training. This version uses Nvidia’s Warp .

Parameters

  • model (nn.Module) – Simplicits object network

  • pts (torch.Tensor) – Tensor of sample points in \(\mathbb{R}^dim\), for now dim=3, of shape \((\text{num_samples}, \text{dim})\) (in \(m\))

  • yms (torch.Tensor) – Length pt-wise youngs modulus, of shape \((\text{num_samples})\) (in \(kg/m/s^2\))

  • prs (torch.Tensor) – Length pt-wise poisson ratios, of shape \((\text{num_samples})\)

  • rhos (torch.Tensor) – Length pt-wise density, of shape \((\text{num_samples})\) (in \(kg/m^3\))

  • transforms (torch.Tensor) – Batch of sample transformations, of shape \((\text{batch_size}, \text{num_handles}, \text{dim}, \text{dim}+1)\)

  • appx_vol (float) – Approximate (or exact) volume of object (in \(m^3\))

  • interp_step (float) – Length interpolation schedule for neohookean elasticity (0%->100%)

Returns

Elastic loss, single value tensor

Return type

torch.Tensor

kaolin.physics.simplicits.loss_ortho(weights)

Calculate orthogonality of weights

Parameters

weights (torch.Tensor) – Tensor of weights, of shape \((\text{num_samples}, \text{num_handles})\)

Returns

Orthogonality loss, single value tensor

Return type

torch.Tensor

kaolin.physics.simplicits.lumped_mass_matrix(rhos, total_volume, dim=3)

Calculate the lumped mass matrix of an object sampled via points with spatially uniform sampling, and potentially spatially varying density

Parameters

  • rhos (torch.Tensor) – Point-wise vector of densities, of shape \((\text{num_samples})\) (in \(kg/m^3\))

  • total_volume (float) – Total volume of object (in \(m^3\))

  • dim (int, optional) – Spatial dimensions. Defaults to 3.

Returns

Diagonal mass matrix of size \((3 \text{num_samples}, 3 \text{num_samples})\) torch.Tensor: Diagonal INVERSE mass matrix of size \((3 \text{num_samples}, 3 \text{num_samples})\)

Return type

torch.Tensor

kaolin.physics.simplicits.sparse_collision_jacobian_matrix(sim_weights, sim_pts, indices, cp_is_static)

Creates a sparse collision Jacobian matrix from the global weights and points of the scene. Indices holds to the indices of the sim_pts and sim_weights to include in the matrix. If index corresponds to a static object, the point is not included, but zeros are added instead.

Parameters

  • sim_weights (wp.array2d(dtype=wp.float32)) – Skinning weights.

  • sim_pts (wp.array(dtype=wp.vec3)) – Sample points.

  • indices (wp.array(dtype=wp.int32)) – Indices of the sim_pts and sim_weights to include in the matrix.

  • cp_is_static (wp.array(dtype=wp.int32)) – 1 if the point is in a static object, 0 otherwise.

Returns

Sparse LBS matrix size \((3 \text{num_indices}, 12 \text{num_handles})\)

Return type

wp.sparse.bsr_matrix

kaolin.physics.simplicits.sparse_dFdz_matrix(sim_weights, sim_weights_jac, sim_pts)

Creates a sparse Jacobian matrix of the deformation gradient with respect to the sample points, using precomputed skinning weights and their spatial Jacobian.

Parameters

  • sim_weights (wp.array2d(dtype=wp.float32)) – Skinning weights, of shape \((\text{num_samples}, \text{num_handles})\).

  • sim_weights_jac (wp.array3d(dtype=wp.float32)) – Gradient of the skinning weights with respect to the sample points, of shape \((\text{num_samples}, \text{num_handles}, 3)\).

  • sim_pts (wp.array(dtype=wp.vec3)) – 3D positions of the sample points, of shape \((\text{num_samples},)\) of vec3.

Returns

Sparse Jacobian matrix of size \((9 \text{num_samples}, 12 \text{num_handles})\)

Return type

wp.sparse.bsr_matrix

kaolin.physics.simplicits.sparse_dFdz_matrix_from_dense(enriched_weights_fcn, pts)

Creates a sparse Jacobian matrix of the deformation gradient with respect to the sample points.

Parameters

  • enriched_weights_fcn (function) – Function that returns the skinning weights for a given point.

  • pts (torch.Tensor) – Sample points (in \(m\)).

Returns

Sparse Jacobian matrix of size \((9 \text{num_samples}, 12 \text{num_handles})\)

Return type

wp.sparse.bsr_matrix

kaolin.physics.simplicits.sparse_lbs_matrix(sim_weights, sim_pts)

Creates a sparse LBS matrix from a set of points and corresponding weights.

Parameters

  • sim_weights (wp.array2d(dtype=wp.float32)) – Skinning weights.

  • sim_pts (wp.array(dtype=wp.vec3)) – Sample points.

Returns

Sparse LBS matrix of size \((3 \text{num_samples}, 12 \text{num_handles})\)

Return type

wp.sparse.bsr_matrix

kaolin.physics.simplicits.sparse_mass_matrix(sim_rhos: ndarray)

Creates a sparse mass matrix from a set of densities.

Parameters

sim_rhos (np.ndarray) – Densities (in \(kg/m^3\)).

Returns

Sparse mass matrix of size \((3 \text{num_samples}, 3 \text{num_samples})\)

Return type

wp.sparse.bsr_matrix

kaolin.physics.simplicits.standard_lbs(x0, tfms, w_x0)

Applies the linear blend skinning transform batched over all pts (\(x_0\)) for a batch of transforms (\(T\)), given skinning weights (\(w_{x0}\)), as \(x_i = \sum_{j=1}^{n} w_j(x_{0,i}) \cdot T_j \begin{bmatrix} x_{0,i} \\ 1 \end{bmatrix} + x_{0,i}\)

Parameters

  • x0 (torch.Tensor) – Rest state points, of shape \((\text{num_pts}, \text{dim})\)

  • tfms (torch.Tensor) – Tensor of affine handles, of shape \((\text{batch_size}, \text{num_handles}, \text{dim}, \text{dim}+1)\)

  • w_x0 (torch.Tensor) – Matrix of skinning weights, of shape \((\text{num_pts}, \text{num_handles})\)

Returns

Transformed points, of shape \((\text{num_pts}, \text{dim})\)

Return type

(torch.Tensor)

kaolin.physics.simplicits.weight_function_lbs(x0, tfms, fcn)

Applies the linear blend skinning transform batched over all pts: x0 for a batch of transforms, given skinning weight function fcn. Differentiable over fcn.

Parameters

  • x0 (torch.Tensor) – Rest state points, of shape \((\text{num_pts}, \text{dim})\)

  • tfms (torch.Tensor) – Tensor of affine handles, of shape \((\text{batch_size}, \text{num_handles}, \text{dim}, \text{dim}+1)\)

  • fcn (callable) – Skinning weights function

Returns

Transformed points, of shape \((\text{num_pts}, \text{dim})\)

Return type

(torch.Tensor)