Collision Mesh

class ipctk.CollisionMesh

Bases: pybind11_object

Public Data Attributes:

num_vertices

Get the number of vertices in the collision mesh.

num_codim_vertices

Get the number of codimensional vertices in the collision mesh.

num_codim_edges

Get the number of codimensional edges in the collision mesh.

num_edges

Get the number of edges in the collision mesh.

num_faces

Get the number of faces in the collision mesh.

dim

Get the dimension of the mesh.

ndof

Get the number of degrees of freedom in the collision mesh.

full_num_vertices

Get the number of vertices in the full mesh.

full_ndof

Get the number of degrees of freedom in the full mesh.

rest_positions

Get the vertices of the collision mesh at rest (#V × dim).

codim_vertices

Get the indices of codimensional vertices of the collision mesh (#CV x 1).

codim_edges

Get the indices of codimensional edges of the collision mesh (#CE x 1).

edges

Get the edges of the collision mesh (#E × 2).

faces

Get the faces of the collision mesh (#F × 3).

faces_to_edges

Get the mapping from faces to edges of the collision mesh (#F × 3).

is_selection_dof_map

Whether the full ↔ collision DOF map is a pure selection matrix.

vertex_vertex_adjacencies

Get the vertex-vertex adjacency matrix.

vertex_edge_adjacencies

Get the vertex-edge adjacency matrix.

edge_vertex_adjacencies

Get the edge-vertex adjacency matrix.

vertex_areas

The vertex areas used as collision weights (barycentric by default).

edge_areas

The edge areas used as collision weights (barycentric by default).

vertex_thicknesses

The thickness of the vertices (empty without a thickness).

edge_thicknesses

The thickness of the edges (empty without a thickness).

face_thicknesses

The thickness of the faces (empty without a thickness).

max_thickness

The largest thickness of any primitive (zero without a thickness).

can_collide

A function that takes two vertex IDs and returns true if the vertices (and faces or edges containing the vertices) can collide.

planes

A vector of planes in the collision mesh.

Public Methods:

__init__(*args, **kwargs)

Overloaded function.

build_from_full_mesh(full_rest_positions, edges)

Helper function that automatically builds include_vertex using construct_is_on_surface.

init_adjacencies(self)

Initialize vertex-vertex and edge-vertex adjacencies.

init_area_jacobians(self)

Initialize vertex and edge areas.

face_normals(self, vertices)

Compute the unit normal of each face for the given vertex positions.

vertices(self, full_positions)

Compute the vertex positions from the positions of the full mesh.

displace_vertices(self, full_displacements)

Compute the vertex positions from vertex displacements on the full mesh.

map_displacements(self, full_displacements)

Map vertex displacements on the full mesh to vertex displacements on the collision mesh.

to_full_vertex_id(*args, **kwargs)

Overloaded function.

to_full_dof(*args, **kwargs)

Overloaded function.

are_adjacencies_initialized(self)

Determine if the adjacencies have been initialized by calling init_adjacencies().

is_vertex_on_boundary(self, vi)

Is a vertex on the boundary of the collision mesh?

vertex_area(self, vi)

Get the barycentric area of a vertex.

vertex_area_gradient(self, vi)

Get the gradient of the barycentric area of a vertex wrt the rest positions of all points.

edge_area(self, ei)

Get the barycentric area of an edge.

edge_area_gradient(self, ei)

Get the gradient of the barycentric area of an edge wrt the rest positions of all points.

are_area_jacobians_initialized(self)

Determine if the area Jacobians have been initialized by calling init_area_jacobians().

has_thickness(self)

Determine if the primitives have a thickness (see set_thickness).

vertex_thickness(self, vi)

Get the thickness of a vertex (zero without a thickness).

edge_thickness(self, ei)

Get the thickness of an edge (zero without a thickness).

face_thickness(self, fi)

Get the thickness of a face (zero without a thickness).

set_thickness(self, vertex_thickness, ...)

Give every vertex, edge, and face a thickness.

set_vertex_thickness(self, vertex_thickness)

Give each vertex a thickness, which its edges and faces inherit.

set_face_thickness(self, face_thickness[, ...])

Give each face a thickness, which its edges and vertices inherit.

clear_thickness(self)

Remove the primitives' thickness.

construct_is_on_surface(num_vertices, edges)

Construct a vector of bools indicating whether each vertex is on the surface.

construct_faces_to_edges(faces, edges)

Construct a matrix that maps from the faces' edges to rows in the edges matrix.

Private Methods:

_pybind11_conduit_v1_


__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: ipctk.CollisionMesh, rest_positions: typing.Annotated[numpy.typing.NDArray[numpy.float64], “[m, n]”, “flags.f_contiguous”], edges: typing.Annotated[numpy.typing.NDArray[numpy.int32], “[m, n]”, “flags.f_contiguous”] = array([], shape=(0, 0), dtype=int32), faces: typing.Annotated[numpy.typing.NDArray[numpy.int32], “[m, n]”, “flags.f_contiguous”] = array([], shape=(0, 0), dtype=int32), displacement_map: scipy.sparse.csc_matrix[numpy.float64] = <Compressed Sparse Column sparse matrix of dtype ‘float64’ with 0 stored elements and shape (0, 0)>) -> None

    Construct a new Collision Mesh object directly from the collision mesh vertices.

    Parameters:

    rest_positions: The vertices of the collision mesh at rest (#V × dim). edges: The edges of the collision mesh (#E × 2). faces: The faces of the collision mesh (#F × 3). displacement_map: The displacement mapping from displacements on the full mesh to the collision mesh.

  2. __init__(self: ipctk.CollisionMesh, include_vertex: collections.abc.Sequence[bool], orient_vertex: collections.abc.Sequence[bool], full_rest_positions: typing.Annotated[numpy.typing.NDArray[numpy.float64], “[m, n]”, “flags.f_contiguous”], edges: typing.Annotated[numpy.typing.NDArray[numpy.int32], “[m, n]”, “flags.f_contiguous”] = array([], shape=(0, 0), dtype=int32), faces: typing.Annotated[numpy.typing.NDArray[numpy.int32], “[m, n]”, “flags.f_contiguous”] = array([], shape=(0, 0), dtype=int32), displacement_map: scipy.sparse.csc_matrix[numpy.float64] = <Compressed Sparse Column sparse matrix of dtype ‘float64’ with 0 stored elements and shape (0, 0)>) -> None

    Construct a new Collision Mesh object from a full mesh vertices.

    Parameters:

    include_vertex: Vector of bools indicating whether each vertex should be included in the collision mesh. orient_vertex: Vector of bools indicating whether each vertex is orientable. full_rest_positions: The vertices of the full mesh at rest (#V × dim). edges: The edges of the collision mesh indexed into the full mesh vertices (#E × 2). faces: The faces of the collision mesh indexed into the full mesh vertices (#F × 3). displacement_map: The displacement mapping from displacements on the full mesh to the collision mesh.

are_adjacencies_initialized(self) → bool

Determine if the adjacencies have been initialized by calling init_adjacencies().

are_area_jacobians_initialized(self) → bool

Determine if the area Jacobians have been initialized by calling init_area_jacobians().

static build_from_full_mesh(full_rest_positions: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]', 'flags.f_contiguous'], edges: Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]', 'flags.f_contiguous'], faces: Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]', 'flags.f_contiguous'] = array([], shape=(0, 0), dtype=int32)) → ipctk.CollisionMesh

Helper function that automatically builds include_vertex using construct_is_on_surface.

Parameters:
full_rest_positions: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]', 'flags.f_contiguous']

The full vertices at rest (#FV × dim).

edges: Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]', 'flags.f_contiguous']

The edge matrix of mesh (#E × 2).

faces: Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]', 'flags.f_contiguous'] = array([], shape=(0, 0), dtype=int32)

The face matrix of mesh (#F × 3).

Returns:

Constructed CollisionMesh.

property can_collide : ipctk.CollisionFilter

A function that takes two vertex IDs and returns true if the vertices (and faces or edges containing the vertices) can collide.

By default all primitives can collide with all other primitives.

clear_thickness(self) → None

Remove the primitives’ thickness.

property codim_edges : Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']

Get the indices of codimensional edges of the collision mesh (#CE x 1).

property codim_vertices : Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']

Get the indices of codimensional vertices of the collision mesh (#CV x 1).

static construct_faces_to_edges(faces: Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]', 'flags.f_contiguous'], edges: Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]', 'flags.f_contiguous']) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]']

Construct a matrix that maps from the faces’ edges to rows in the edges matrix.

Parameters:
faces: Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]', 'flags.f_contiguous']

The face matrix of mesh (#F × 3).

edges: Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]', 'flags.f_contiguous']

The edge matrix of mesh (#E × 2).

Returns:

Matrix that maps from the faces’ edges to rows in the edges matrix.

static construct_is_on_surface(num_vertices: SupportsInt, edges: Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]', 'flags.f_contiguous'], codim_vertices: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'] = array([], dtype=int32)) → list[bool]

Construct a vector of bools indicating whether each vertex is on the surface.

Parameters:
num_vertices: SupportsInt

The number of vertices in the mesh.

edges: Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]', 'flags.f_contiguous']

The surface edges of the mesh (#E × 2).

codim_vertices: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'] = array([], dtype=int32)

The indices of codimensional vertices (#CV x 1).

Returns:

A vector of bools indicating whether each vertex is on the surface.

property dim : int

Get the dimension of the mesh.

displace_vertices(self, full_displacements: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]', 'flags.f_contiguous']) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]']

Compute the vertex positions from vertex displacements on the full mesh.

Parameters:
full_displacements: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]', 'flags.f_contiguous']

The vertex displacements on the full mesh (#FV × dim).

Returns:

The vertex positions of the collision mesh (#V × dim).

edge_area(self, ei: SupportsInt) → float

Get the barycentric area of an edge.

Parameters:
ei: SupportsInt

Edge ID.

Returns:

Barycentric area of edge ei.

edge_area_gradient(self, ei: SupportsInt) → scipy.sparse.csc_matrix[numpy.float64]

Get the gradient of the barycentric area of an edge wrt the rest positions of all points.

Parameters:
ei: SupportsInt

Edge ID.

Returns:

Gradient of the barycentric area of edge ei wrt the rest positions of all points.

property edge_areas : Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

The edge areas used as collision weights (barycentric by default).

See vertex_areas for the caveats on custom areas.

edge_thickness(self, ei: SupportsInt) → float

Get the thickness of an edge (zero without a thickness).

property edge_thicknesses : Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

The thickness of the edges (empty without a thickness).

property edge_vertex_adjacencies : list[list[int]]

Get the edge-vertex adjacency matrix.

property edges : Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]']

Get the edges of the collision mesh (#E × 2).

face_normals(self, vertices: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]', 'flags.f_contiguous']) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]']

Compute the unit normal of each face for the given vertex positions.

Note

3D only (requires triangular faces).

Parameters:
vertices: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]', 'flags.f_contiguous']

The vertex positions of the collision mesh (#V × 3).

Returns:

The per-face unit normals (#F × 3).

face_thickness(self, fi: SupportsInt) → float

Get the thickness of a face (zero without a thickness).

property face_thicknesses : Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

The thickness of the faces (empty without a thickness).

property faces : Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]']

Get the faces of the collision mesh (#F × 3).

property faces_to_edges : Annotated[numpy.typing.NDArray[numpy.int32], '[m, n]']

Get the mapping from faces to edges of the collision mesh (#F × 3).

property full_ndof : int

Get the number of degrees of freedom in the full mesh.

property full_num_vertices : int

Get the number of vertices in the full mesh.

has_thickness(self) → bool

Determine if the primitives have a thickness (see set_thickness).

init_adjacencies(self) → None

Initialize vertex-vertex and edge-vertex adjacencies.

init_area_jacobians(self) → None

Initialize vertex and edge areas.

property is_selection_dof_map : bool

Whether the full ↔ collision DOF map is a pure selection matrix.

This is the case unless a (non-empty) displacement map was provided at construction. When true, to_full_dof() is equivalent to scattering each collision DOF to the full DOF of the same vertex and component, so derivatives can be assembled directly in full-mesh DOFs instead of applying to_full_dof() after the fact. The scalar index of that scatter depends on IPC_TOOLKIT_VERTEX_DERIVATIVE_LAYOUT: collision DOF i maps to full DOF dim * to_full_vertex_id(i // dim) + i % dim when the layout is RowMajor (the default), and to full_num_vertices * d + to_full_vertex_id(v) for collision DOF num_vertices * d + v when it is ColMajor.

is_vertex_on_boundary(self, vi: SupportsInt) → bool

Is a vertex on the boundary of the collision mesh?

Parameters:
vi: SupportsInt

Vertex ID.

Returns:

True if the vertex is on the boundary of the collision mesh.

map_displacements(self, full_displacements: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]', 'flags.f_contiguous']) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]']

Map vertex displacements on the full mesh to vertex displacements on the collision mesh.

Parameters:
full_displacements: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]', 'flags.f_contiguous']

The vertex displacements on the full mesh (#FV × dim).

Returns:

The vertex displacements on the collision mesh (#V × dim).

property max_thickness : float

The largest thickness of any primitive (zero without a thickness).

property ndof : int

Get the number of degrees of freedom in the collision mesh.

property num_codim_edges : int

Get the number of codimensional edges in the collision mesh.

property num_codim_vertices : int

Get the number of codimensional vertices in the collision mesh.

property num_edges : int

Get the number of edges in the collision mesh.

property num_faces : int

Get the number of faces in the collision mesh.

property num_vertices : int

Get the number of vertices in the collision mesh.

property planes : list[ipctk.Hyperplane]

A vector of planes in the collision mesh.

Each plane is represented as a Hyperplane object (wrapping Eigen::Hyperplane<double, 3>). In Python, a Hyperplane can be constructed from either:

  • a normal and a point on the plane: Hyperplane(normal, point), or

  • a normal and an offset: Hyperplane(normal, offset),

where normal and point are 3D vectors and offset is a scalar.

property rest_positions : Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]']

Get the vertices of the collision mesh at rest (#V × dim).

set_face_thickness(self, face_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], vertex_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'] = array([], dtype=float64)) → None

Give each face a thickness, which its edges and vertices inherit.

An edge or vertex takes the largest thickness of the faces it bounds. An edge on no face takes the larger thickness of its two vertices.

Parameters:
face_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

Thickness of each face (size num_faces).

vertex_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'] = array([], dtype=float64)

Least thickness of each vertex (size num_vertices), or empty for zero. It is the whole thickness of a vertex on no face.

set_thickness(self, vertex_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], edge_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], face_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']) → None

Give every vertex, edge, and face a thickness.

Each primitive is offset outward by its thickness, so two primitives touch when they are the sum of their thicknesses apart. Collisions built from this mesh add that sum to their minimum distance (NormalCollision.dmin), the broad phase inflates each primitive’s box by its thickness, and CCD stops each pair at that sum plus the minimum distance. A sheet of total thickness h, for example, gives each of its primitives h / 2.

Parameters:
vertex_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

Thickness of each vertex (size num_vertices).

edge_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

Thickness of each edge (size num_edges).

face_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

Thickness of each face (size num_faces).

set_vertex_thickness(self, vertex_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']) → None

Give each vertex a thickness, which its edges and faces inherit.

An edge or face takes the largest thickness of its vertices.

Parameters:
vertex_thickness: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

Thickness of each vertex (size num_vertices).

to_full_dof(*args, **kwargs)

Overloaded function.

  1. to_full_dof(self: ipctk.CollisionMesh, x: typing.Annotated[numpy.typing.NDArray[numpy.float64], “[m, 1]”]) -> typing.Annotated[numpy.typing.NDArray[numpy.float64], “[m, 1]”]

    Map a vector quantity on the collision mesh to the full mesh.

    This is useful for mapping gradients from the collision mesh to the full mesh (i.e., applies the chain-rule).

    Parameters:

    x: Vector quantity on the collision mesh with size equal to ndof().

    Returns:

    Vector quantity on the full mesh with size equal to full_ndof().

  2. to_full_dof(self: ipctk.CollisionMesh, X: scipy.sparse.csc_matrix[numpy.float64]) -> scipy.sparse.csc_matrix[numpy.float64]

    Map a matrix quantity on the collision mesh to the full mesh.

    This is useful for mapping Hessians from the collision mesh to the full mesh (i.e., applies the chain-rule).

    Parameters:

    X: Matrix quantity on the collision mesh with size equal to ndof() × ndof().

    Returns:

    Matrix quantity on the full mesh with size equal to full_ndof() × full_ndof().

to_full_vertex_id(*args, **kwargs)

Overloaded function.

  1. to_full_vertex_id(self: ipctk.CollisionMesh, id: typing.SupportsInt) -> int

    Map a vertex ID to the corresponding vertex ID in the full mesh.

    Parameters:

    id: Vertex ID in the collision mesh.

    Returns:

    Vertex ID in the full mesh.

  2. to_full_vertex_id(self: ipctk.CollisionMesh) -> typing.Annotated[numpy.typing.NDArray[numpy.int32], “[m, 1]”]

    Get the complete mapping of vertex IDs to their corresponding vertex IDs in the full mesh.

    Returns:

    Vector of size num_vertices() where each entry is the full vertex ID corresponding to the collision mesh vertex ID.

vertex_area(self, vi: SupportsInt) → float

Get the barycentric area of a vertex.

Parameters:
vi: SupportsInt

Vertex ID.

Returns:

Barycentric area of vertex vi.

vertex_area_gradient(self, vi: SupportsInt) → scipy.sparse.csc_matrix[numpy.float64]

Get the gradient of the barycentric area of a vertex wrt the rest positions of all points.

Parameters:
vi: SupportsInt

Vertex ID.

Returns:

Gradient of the barycentric area of vertex vi wrt the rest positions of all points.

property vertex_areas : Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

The vertex areas used as collision weights (barycentric by default).

Setting custom areas (e.g., 2πR·ds for axisymmetric models) does not support shape derivatives and must be done before init_area_jacobians(). Collisions built earlier keep their old weights.

property vertex_edge_adjacencies : list[list[int]]

Get the vertex-edge adjacency matrix.

vertex_thickness(self, vi: SupportsInt) → float

Get the thickness of a vertex (zero without a thickness).

property vertex_thicknesses : Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']

The thickness of the vertices (empty without a thickness).

property vertex_vertex_adjacencies : list[list[int]]

Get the vertex-vertex adjacency matrix.

vertices(self, full_positions: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]', 'flags.f_contiguous']) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]']

Compute the vertex positions from the positions of the full mesh.

Parameters:
full_positions: Annotated[numpy.typing.NDArray[numpy.float64], '[m, n]', 'flags.f_contiguous']

The vertex positions of the full mesh (#FV × dim).

Returns:

The vertex positions of the collision mesh (#V × dim).