kaolin.physics.simplicits.SimplicitsObject

API

class kaolin.physics.simplicits.SimplicitsObject(pts, yms, prs, rhos, appx_vol, skinning_mod: SkinningModule)

Bases: PhysicsPoints

__init__(pts, yms, prs, rhos, appx_vol, skinning_mod: SkinningModule)

Initialize a SimplicitsObject with geometry, material properties, and skinning weights.

A SimplicitsObject is a collection of points, material properties, and a linear blend skinning weight function that can be used to deform the object. Objects can be initialized in several ways using the static factory methods (read their docstrings for more details). Objects can also be denoted as kinematic or dynamic (default). Kinematic objects still have handles, but they are not solved for during simulation.

Parameters

  • pts (torch.Tensor) – Points tensor of shape \((N, 3)\) representing the object’s geometry (in \(m\))

  • yms (Union[torch.Tensor, float]) – Young’s moduli defining material stiffness (in \(kg/m/s^2\)). Can be either: - A tensor of shape \((N,)\) for per-point values - A float value that will be applied to all points

  • prs (Union[torch.Tensor, float]) – Poisson’s ratios defining material compressibility. Can be either: - A tensor of shape \((N,)\) for per-point values - A float value that will be applied to all points

  • rhos (Union[torch.Tensor, float]) – Density defining material density (in \(kg/m^3\)). Can be either: - A tensor of shape \((N,)\) for per-point values - A float value that will be applied to all points

  • appx_vol (Union[torch.Tensor, float]) – Approximate volume (in \(m^3\)). Can be either: - A tensor of shape \((1,)\) or \((0,)\) - A float value

  • skinning_mod (SkinningModule) – SkinningModule to be used to compute the skinning weights.

as_dict(only_tensors=False) → Dict[str, Any]

Return all non-None attributes as a {name: value} dict.

classmethod assert_supported(attr)

Raises an exception if class does not support provided attribute name.

bake(num_qps=None, sampling_indices=None, renderable_pts=None) → SkinnedPhysicsPoints

Bakes the skinning weights for simulation, and optionally also bakes renderable points.

Produces a SkinnedPhysicsPoints object ready for use in a SimplicitsScene. If renderable_pts is provided, those points are also skinned and stored in the returned object for later use in rendering queries.

Parameters

  • num_qps (int, optional) – Number of quadrature points to sample. Mutually exclusive with sampling_indices.

  • sampling_indices (torch.Tensor, optional) – Explicit quadrature point indices to use, of shape \((\text{num_qps},)\). Mutually exclusive with num_qps.

  • renderable_pts (torch.Tensor, optional) – Additional points (e.g. Gaussian splat positions, in \(m\)) whose skinning weights should be baked for rendering. Defaults to None.

Returns

Baked object suitable for simulation.

Return type

(SkinnedPhysicsPoints)

bake_for_rendering(renderable_pts) → SkinnedPoints

Bakes the skinning weights for rendering.

Parameters

renderable_pts (torch.Tensor) – Additional points (e.g. Gaussian splat positions) whose skinning weights should be baked for rendering, of shape \((\text{num_renderable_pts}, 3)\) (in \(m\)).

Returns

Baked SkinnedPoints for renderable.

Return type

(SkinnedPoints)

check_other_attribute(attr, log_error=False)

Checks a non-tensor attribute validity; returns True if ok.

check_sanity(log_error=True)

Validates that all tensor attributes are correct; implement abstract methods.

Parameters

log_error (bool) – If True, logs each failed check via logger.error.

Returns

True if all checks pass, False otherwise.

Return type

bool

check_tensor_attribute(attr, log_error=False)

Checks tensor attribute validity; returns True if valid.

classmethod class_other_attributes()

Returns attribute names that are not PyTorch tensors or dicts thereof.

classmethod class_tensor_attributes()

Returns attribute names that are PyTorch tensors or dicts thereof.

cpu(attributes: Optional[Sequence[str]] = None)

Calls cpu on all or selected tensor attributes; returns a shallow copy.

classmethod create_from_function(physics_points: PhysicsPointsProtocol, fcn: Callable)

Creates a SimplicitsObject with a custom skinning weight function.

This method creates a SimplicitsObject using a user-provided function to compute skinning weights. The function should take points as input and return a matrix of skinning weights.

Parameters

  • physics_points (PhysicsPoints) – PhysicsPoints object to be used for training.

  • fcn (Callable) – Trained skinning module or callable returning per-point weights.

Returns

A SimplicitsObject with the provided skinning weight function.

Return type

SimplicitsObject

classmethod create_rigid(pts=None, yms=None, prs=None, rhos=None, appx_vol=None, physics_points: Optional[PhysicsPointsProtocol] = None)

Creates a rigid SimplicitsObject with a single weight for affine deformations.

This method creates a SimplicitsObject that behaves as a rigid body. At low stiffness values (young’s modulus/ym), deformations will not be expressive, but with high stiffness values, the object will act as rigid.

Parameters

  • pts (torch.Tensor, optional) – Deprecated, use physics_points instead. Points tensor of shape \((N, 3)\) representing the object’s geometry (in \(m\)). Required unless physics_points is provided.

  • yms (Union[torch.Tensor, float], optional) – Deprecated, use physics_points instead. Young’s moduli defining material stiffness (in \(kg/m/s^2\)); either a tensor of shape \((N,)\) for per-point values, or a float value applied to all points. Required unless physics_points is provided.

  • prs (Union[torch.Tensor, float], optional) – Deprecated, use physics_points instead. Poisson’s ratios defining material compressibility; either a tensor of shape \((N,)\) for per-point values, or a float value applied to all points. Required unless physics_points is provided.

  • rhos (Union[torch.Tensor, float], optional) – Deprecated, use physics_points instead. Density defining material density (in \(kg/m^3\)); either a tensor of shape \((N,)\) for per-point values, or a float value applied to all points. Required unless physics_points is provided.

  • appx_vol (Union[torch.Tensor, float], optional) – Deprecated, use physics_points instead. Approximate volume (in \(m^3\)); either a tensor of shape \((1,)\) or \((0,)\), or a float value. Required unless physics_points is provided.

  • physics_points (PhysicsPoints, optional) – PhysicsPoints object describing the object’s geometry and material properties. Defaults to None. If provided, pts, yms, prs, rhos, and appx_vol must all be None and the values are taken from this object instead.

Returns

A rigid SimplicitsObject with a constant weight function.

Return type

(SimplicitsObject)

classmethod create_trained(pts, yms, prs, rhos, appx_vol, num_handles=10, num_samples=1000, model_layers=6, training_batch_size=10, training_num_steps=10000, training_lr_start=0.001, training_lr_end=0.001, training_le_coeff=0.1, training_lo_coeff=1000000.0, training_log_every=1000, normalize_for_training=True, display_progress=False)

Constructs a SimplicitsObject by training a neural network to learn skinning weights.

Deprecated since version 0.19.0: This function is deprecated, use create_with_mlp() instead.

This method creates a SimplicitsObject by training a neural network to learn skinning weights that can be used for deformation. The network is trained to minimize a combination of local and global energy terms.

Note

If num_handles is set to 1, the object will be created as rigid instead of deformable. The training process uses a combination of local and global energy terms to ensure both local detail preservation and global shape maintenance.

Parameters

  • pts (torch.Tensor) – Points tensor of shape \((N, 3)\) representing the object’s geometry (in \(m\)).

  • yms (Union[torch.Tensor, float]) – Young’s moduli defining material stiffness (in \(kg/m/s^2\)); either a tensor of shape \((N,)\) for per-point values, or a float value applied to all points.

  • prs (Union[torch.Tensor, float]) – Poisson’s ratios defining material compressibility; either a tensor of shape \((N,)\) for per-point values, or a float value applied to all points.

  • rhos (Union[torch.Tensor, float]) – Density defining material density (in \(kg/m^3\)); either a tensor of shape \((N,)\) for per-point values, or a float value applied to all points.

  • appx_vol (Union[torch.Tensor, float]) – Approximate volume (in \(m^3\)); either a tensor of shape \((1,)\) or \((0,)\), or a float value.

  • num_handles (int, optional) – Number of control handles for deformation. Defaults to 10

  • num_samples (int, optional) – Number of samples used for training. Defaults to 1000

  • model_layers (int, optional) – Number of layers in the neural network. Defaults to 6

  • training_batch_size (int, optional) – Batch size for training. Defaults to 10

  • training_num_steps (int, optional) – Number of training iterations. Defaults to 10000.

  • training_lr_start (float, optional) – Starting learning rate. Defaults to 1e-3.

  • training_lr_end (float, optional) – Final learning rate. Defaults to 1e-3

  • training_le_coeff (float, optional) – Coefficient for local energy term. Defaults to 1e-1

  • training_lo_coeff (float, optional) – Coefficient for global energy term. Defaults to 1e6

  • training_log_every (int, optional) – Logging frequency during training. Defaults to 1000

  • normalize_for_training (bool, optional) – Whether to normalize points to unit cube for training. Defaults to True

  • display_progress (bool, optional) – If True, display a tqdm progress bar during training. Defaults to False.

Returns

A trained SimplicitsObject with learned skinning weights.

Return type

(SimplicitsObject)

classmethod create_with_mlp(physics_points: PhysicsPointsProtocol, num_handles, num_samples, model_layers, training_batch_size=10, training_num_steps=10000, training_lr_start=0.001, training_lr_end=0.001, training_le_coeff=0.1, training_lo_coeff=1000000.0, training_log_every=1000, normalize_for_training=True, display_progress=False)

Constructs a SimplicitsObject by training a neural network to learn skinning weights.

This method creates a SimplicitsObject by training a neural network to learn skinning weights that can be used for deformation. The network is trained to minimize a combination of local and global energy terms.

Note

If num_handles is set to 1, the object will be created as rigid instead of deformable. The training process uses a combination of local and global energy terms to ensure both local detail preservation and global shape maintenance.

Parameters

  • physics_points (PhysicsPoints) – PhysicsPoints object to be used for training.

  • num_handles (int) – Number of control handles for deformation.

  • num_samples (int) – Number of samples used for training.

  • model_layers (int) – Number of layers in the neural network.

  • training_batch_size (int, optional) – Batch size for training. Defaults to 10

  • training_num_steps (int, optional) – Number of training iterations. Defaults to 10000.

  • training_lr_start (float, optional) – Starting learning rate. Defaults to 1e-3.

  • training_lr_end (float, optional) – Final learning rate. Defaults to 1e-3

  • training_le_coeff (float, optional) – Coefficient for local energy term. Defaults to 1e-1

  • training_lo_coeff (float, optional) – Coefficient for global energy term. Defaults to 1e6

  • training_log_every (int, optional) – Logging frequency during training. Defaults to 1000

  • normalize_for_training (bool, optional) – Whether to normalize points to unit cube for training. Defaults to True

  • display_progress (bool, optional) – If True, display a tqdm progress bar during training. Defaults to False.

Returns

A trained SimplicitsObject with learned skinning weights.

Return type

(SimplicitsObject)

classmethod create_with_rkpm(physics_points: PhysicsPointsProtocol, num_handles, num_nodes, num_points=None, dtype=torch.float64)

Constructs a SimplicitsObject using RKPM-based skinning weights as explained in Freeform. RKPM based simplicits shows more accurate behavior and better convergence than MLP based simplicits when compared to FEM with the same material parameters. This may appear as less stiffness in the object when compared to MLP based simplicits deformations.

This method creates a SimplicitsObject by computing skinning weights via Reproducing Kernel Particle Method (RKPM) eigenanalysis. RKPM nodes are selected by Farthest Point Sampling and deformation modes are derived from the generalized eigenvalue problem of the mass and stiffness matrices.

Note

If num_handles is set to 1, the object will be created as rigid instead of deformable.

Parameters

  • physics_points (PhysicsPoints) – PhysicsPoints object to be used for training.

  • num_handles (int) – Number of deformation handles (RKPM eigenvectors).

  • num_nodes (int) – Number of RKPM kernel nodes.

  • num_points (int, optional) – Number of samples from pts to use when constructing the mass and stiffness matrices for the RKPM generalized eigenproblem (i.e., this controls the number of samples from the object’s geometry fed into the basis construction; it does not affect the input points used for the final object). This only affects offline mode construction; the returned SimplicitsObject still stores the full pts geometry, and skinning can be evaluated at any point. Using a large number of samples may lead to high memory usage during basis construction. Defaults to all points in pts being used as samples.

  • dtype (torch.dtype, optional) – Floating-point precision used for RKPM kernel evaluations and eigenanalysis. Defaults to torch.float64 for numerical stability.

Returns

A SimplicitsObject with RKPM-based skinning weights.

Return type

SimplicitsObject

cuda(device: Optional[Union[int, device, str]] = None, attributes: Optional[Sequence[str]] = None)

Calls cuda on all or selected tensor attributes; returns a shallow copy.

describe_attribute(attr, print_stats=False, detailed=False)

Outputs an informative string about an attribute; the same method used for all attributes in to_string.

Parameters

  • attr (str) – attribute name

  • print_stats (bool) – if to print statistics about values in each tensor

  • detailed (bool) – if to include additional information about each tensor

Returns

multi-line string with attribute information

Return type

(str)

Raises

ValueError if attr is not supported –

detach(attributes: Optional[Sequence[str]] = None)

Detaches all or selected tensor attributes; returns a shallow copy.

get_attributes(only_tensors=False)

Returns names of all attributes that are currently set to non-None value in this class instance.

Parameters

only_tensors – if true, will only include tensor attributes

Returns

list of string names

Return type

(list)

subsample(num_pts=None, sample_indices=None)

Subsample into another SimplicitsObject sharing the same skinning module.

Parameters

  • num_pts (int, optional) – Number of points to sample. Mutually exclusive with sample_indices.

  • sample_indices (torch.Tensor, optional) – Explicit indices to use for subsampling, of shape \((\text{num_pts},)\). Mutually exclusive with num_pts.

Returns

The subsampled SimplicitsObject with the same skinning_mod.

Return type

(SimplicitsObject)

to(*args: Any, attributes: Optional[Sequence[str]] = None, **kwargs: Any)

Moves or casts tensors like torch.Tensor.to() / torch.nn.Module.to().

Parameters

  • *args – forwarded to tensor.to(*args)

  • attributes (list of str, optional) – if set, only these tensor attributes are updated

  • **kwargs – forwarded to tensor.to(**kwargs)

Returns

shallow copy with converted tensors

Return type

PointSamples

to_string(print_stats=False, detailed=False)

Returns information about tensor attributes currently contained in the object.

Parameters

  • print_stats (bool) – if to print statistics about values in each tensor

  • detailed (bool) – if to include additional information about each tensor

Returns

multi-line string with attribute information

Return type

(str)