newton.sim.Style3DModelBuilder#

class newton.sim.Style3DModelBuilder(up_axis=Axis.Z, gravity=-9.81)[source]#

Bases: ModelBuilder

A helper class for building style3d simulation models at runtime.

Use the Style3DModelBuilder to construct a simulation scene. The Style3DModelBuilder builds the scene representation using standard Python data structures (lists), this means it is not differentiable. Once finalize() has been called the ModelBuilder transfers all data to Warp tensors and returns an object that may be used for simulation.

Example

Example code:

import newton
from newton.solvers import Style3DSolver
from newton.sim import Style3DModelBuilder

builder = Style3DModelBuilder()

builder.add_cloth_grid(
    pos=wp.vec3(-0.5, 2.0, 0.0),
    rot=wp.quat_from_axis_angle(axis=wp.vec3(1, 0, 0), angle=wp.pi / 2.0),
    dim_x=grid_dim,
    dim_y=grid_dim,
    cell_x=grid_width / grid_dim,
    cell_y=grid_width / grid_dim,
    vel=wp.vec3(0.0, 0.0, 0.0),
    mass=cloth_density * (grid_width * grid_width) / (grid_dim * grid_dim),
    tri_ke=1.0e2,
    tri_ka=1.0e2,
    tri_kd=2.0e-6,
    edge_ke=1,
    tri_aniso_ke=wp.vec3(1.0e2, 1.0e2, 1.0e1),
    edge_aniso_ke=wp.vec3(2.0e-5, 1.0e-5, 5.0e-6),
)

# create model
model = builder.finalize()

state_0, state_1 = model.state(), model.state()
control = model.control()
solver = Style3DSolver(model)

for i in range(10):
    state_0.clear_forces()
    contacts = model.collide(state_0)
    solver.step(state_0, state_1, control, contacts, dt=1.0 / 60.0)
    state_0, state_1 = state_1, state_0

Note

It is strongly recommended to use the Style3DModelBuilder to construct a simulation rather than creating your own Model object directly, however it is possible to do so if desired.

__init__(up_axis=Axis.Z, gravity=-9.81)#
add_aniso_cloth_grid(pos, rot, vel, dim_x, dim_y, cell_x, cell_y, mass, reverse_winding=False, fix_left=False, fix_right=False, fix_top=False, fix_bottom=False, tri_aniso_ke=None, tri_ka=None, tri_kd=None, tri_drag=None, tri_lift=None, edge_aniso_ke=None, edge_kd=None, add_springs=False, spring_ke=None, spring_kd=None, particle_radius=None)#

Helper to create a regular planar cloth grid with anisotropic attributes

Creates a rectangular grid of particles with FEM triangles and bending elements automatically.

Parameters:

  • pos (list[float] | tuple[float, float, float] | vec3f) – The position of the cloth in world space

  • rot (list[float] | tuple[float, float, float, float] | quatf) – The orientation of the cloth in world space

  • vel (list[float] | tuple[float, float, float] | vec3f) – The velocity of the cloth in world space

  • dim_x (int) – The number of rectangular cells along the x-axis

  • dim_y (int) – The number of rectangular cells along the y-axis

  • cell_x (float) – The width of each cell in the x-direction

  • cell_y (float) – The width of each cell in the y-direction

  • mass (float) – The mass of each particle

  • reverse_winding (bool) – Flip the winding of the mesh

  • fix_left (bool) – Make the left-most edge of particles kinematic (fixed in place)

  • fix_right (bool) – Make the right-most edge of particles kinematic

  • fix_top (bool) – Make the top-most edge of particles kinematic

  • fix_bottom (bool) – Make the bottom-most edge of particles kinematic

add_aniso_cloth_mesh(pos, rot, vel, scale, density, indices, vertices, panel_verts, panel_indices=None, tri_aniso_ke=None, edge_aniso_ke=None, tri_ka=None, tri_kd=None, tri_drag=None, tri_lift=None, edge_kd=None, add_springs=False, spring_ke=None, spring_kd=None, particle_radius=None)#

Helper to create a cloth model from a regular triangle mesh with anisotropic attributes

Creates one FEM triangle element and one bending element for every face and edge in the input triangle mesh

Parameters:

  • pos (list[float] | tuple[float, float, float] | vec3f) – The position of the cloth in world space

  • rot (list[float] | tuple[float, float, float, float] | quatf) – The orientation of the cloth in world space

  • vel (list[float] | tuple[float, float, float] | vec3f) – The velocity of the cloth in world space

  • vertices (list[list[float] | tuple[float, float, float] | vec3f]) – A list of vertex positions

  • indices (list[int]) – A list of triangle indices, 3 entries per-face

  • density (float) – The density per-area of the mesh

  • panel_indices (list[int] | None) – A list of triangle indices, 3 entries per-face, passes None will use indices as panel_indices

  • panel_verts (list[list[float] | tuple[float, float] | vec2f]) – A list of vertex 2D positions for panel-based cloth simulation.

  • particle_radius (float | None) – The particle_radius which controls particle based collisions.

  • tri_aniso_ke (list[float] | tuple[float, float, float] | vec3f | None) – anisotropic stretch stiffness (weft, warp, shear) for panel-based cloth simulation.

  • edge_aniso_ke (list[float] | tuple[float, float, float] | vec3f | None) – anisotropic bend stiffness (weft, warp, shear) for panel-based cloth simulation.

Note

The mesh should be two manifold.

add_aniso_edges(i, j, k, l, f0, f1, v0_order, v1_order, panel_verts, panel_indices, rest=None, edge_aniso_ke=None, edge_kd=None)#

Adds bending edge elements between two adjacent triangles in the cloth mesh, defined by four vertices.

The bending energy model follows the discrete shell formulation from [Grinspun et al. 2003]. The anisotropic bending stiffness is controlled by the edge_aniso_ke parameter, and the bending damping by the edge_kd parameter.

Parameters:

  • i – The index of the first particle, i.e., opposite vertex 0

  • j – The index of the second particle, i.e., opposite vertex 1

  • k – The index of the third particle, i.e., vertex 0

  • l – The index of the fourth particle, i.e., vertex 1

  • rest (list[float] | None) – The rest angles across the edges in radians, if not specified they will be computed

  • edge_aniso_ke (list[list[float] | tuple[float, float, float] | vec3f] | None) – The anisotropic bending stiffness coefficient

  • edge_kd (list[float] | None) – The bending damping coefficient

Note

The edge lies between the particles indexed by ‘k’ and ‘l’ parameters with the opposing vertices indexed by ‘i’ and ‘j’. This defines two connected triangles with counterclockwise winding: (i, k, l), (j, l, k).

add_aniso_triangles(i, j, k, density, panel_verts, panel_indices, tri_aniso_ke=None, tri_ka=None, tri_kd=None, tri_drag=None, tri_lift=None)#

Adds anisotropic triangular FEM elements between groups of three particles in the system.

Triangles are modeled as viscoelastic elements with elastic stiffness and damping Parameters specified on the model.

Parameters:

  • i (list[int]) – The indices of the first particle

  • j (list[int]) – The indices of the second particle

  • k (list[int]) – The indices of the third particle

  • density (float) – The density per-area of the mesh

  • panel_indices (list[int]) – A list of triangle indices, 3 entries per-face

  • panel_verts (list[list[float] | tuple[float, float] | vec2f]) – A list of vertex 2D positions for panel-based cloth simulation.

  • tri_aniso_ke (list[list[float] | tuple[float, float, float] | vec3f] | None) – anisotropic stretch stiffness (weft, warp, shear) for pattern-based cloth simulation.

Note

A triangle is created with a rest-length based on the distance between the particles in their initial configuration.

add_builder(builder, xform=None, update_num_env_count=True, separate_collision_group=True)#

Copies the data from builder, another Style3DModelBuilder to this Style3DModelBuilder.

Parameters:

  • builder (ModelBuilder) – a model builder to add model data from.

  • xform (Transform) – offset transform applied to root bodies.

  • update_num_env_count (bool) – if True, the number of environments is incremented by 1.

  • separate_collision_group (bool) – if True, the shapes from the articulations in builder will all be put into a single new collision group, otherwise, only the shapes in collision group > -1 will be moved to a new group.

finalize(device=None, requires_grad=False)#

Convert this builder object to a concrete model for simulation.

After building simulation elements this method should be called to transfer all data to device memory ready for simulation.

Parameters:

  • device (Device | str | None) – The simulation device to use, e.g.: ‘cpu’, ‘cuda’

  • requires_grad (bool) – Whether to enable gradient computation for the model

Returns:

A model object.

Return type:

Style3DModel

sew_close_vertices(sew_distance=1.0e-3, sew_interior=False)#

Sew close vertices by creating sew springs.

Parameters:

  • sew_distance – Vertices within sew_distance will be connected by springs.

  • sew_interior – If True, can sew between interior vertices, otherwise only sew boundary-interior or boundary-boundary vertices