io

triwarp.io

Mesh file loading via the optional meshio dependency.

load_mesh_data

load_mesh_data(
    path: str | Path, *, device: DeviceLike = None
) -> dict[str, wp.array[Any]]

Load every mesh attribute meshio can read from a file into Warp arrays.

Reads path once with meshio and returns a dictionary whose keys are present only when the corresponding data exists in the file. vertices is always present; everything else is optional.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to a mesh file in any format supported by `meshio` (PLY, STL, OBJ, OFF, VTK, glTF, ...).	required
`device`	`DeviceLike`	Warp device for the returned arrays. Defaults to the current Warp device.	`None`

Returns:

Type Description

dict

Mapping with these possible keys:

vertices : wp.array[wp.vec3] of float32 vertex positions (always present).
faces : flat wp.array[wp.int32] of length 3 * n_faces (triangle cells only).
vertex_normals : wp.array[wp.vec3] from nx, ny, nz per-vertex data.
uv : wp.array[wp.vec2] from u, v (or s, t / texture_u, texture_v).
colors : wp.array[wp.vec3] or wp.array[wp.vec4] from red, green, blue (and optional alpha); integer channels are normalized to [0, 1].
face_normals : wp.array[wp.vec3] — only when the file stored per-face normals.

See Also

load_mesh

Notes

Only triangle cells are consumed; non-triangle cell blocks are ignored. meshio reads attributes verbatim and never computes them, so face_normals appears only when the file itself contained per-face normals.

Source code in triwarp/io.py

def load_mesh_data(path: str | Path, *, device: wp.DeviceLike = None) -> dict[str, wp.array[Any]]:
    """
    Load every mesh attribute ``meshio`` can read from a file into Warp arrays.

    Reads ``path`` once with ``meshio`` and returns a dictionary whose keys are present
    only when the corresponding data exists in the file. ``vertices`` is always present;
    everything else is optional.

    Parameters
    ----------
    path
        Path to a mesh file in any format supported by ``meshio`` (PLY, STL, OBJ, OFF,
        VTK, glTF, ...).
    device
        Warp device for the returned arrays. Defaults to the current Warp device.

    Returns
    -------
    dict
        Mapping with these possible keys:

        - ``vertices`` : ``wp.array[wp.vec3]`` of ``float32`` vertex positions (always present).
        - ``faces`` : flat ``wp.array[wp.int32]`` of length ``3 * n_faces`` (triangle cells only).
        - ``vertex_normals`` : ``wp.array[wp.vec3]`` from ``nx, ny, nz`` per-vertex data.
        - ``uv`` : ``wp.array[wp.vec2]`` from ``u, v`` (or ``s, t`` / ``texture_u, texture_v``).
        - ``colors`` : ``wp.array[wp.vec3]`` or ``wp.array[wp.vec4]`` from ``red, green, blue``
          (and optional ``alpha``); integer channels are normalized to ``[0, 1]``.
        - ``face_normals`` : ``wp.array[wp.vec3]`` — only when the file stored per-face normals.

    See Also
    --------
    [`load_mesh`][triwarp.io.load_mesh]

    Notes
    -----
    Only triangle cells are consumed; non-triangle cell blocks are ignored. ``meshio`` reads
    attributes verbatim and never computes them, so ``face_normals`` appears only when the
    file itself contained per-face normals.
    """
    meshio = _import_meshio()
    mesh = meshio.read(path)

    result: dict[str, wp.array[Any]] = {}

    points = np.ascontiguousarray(mesh.points, dtype=np.float32)
    result["vertices"] = wp.array(points, dtype=wp.vec3, device=device)

    faces_np = mesh.cells_dict.get("triangle")
    if faces_np is not None and len(faces_np) > 0:
        faces_flat = np.ascontiguousarray(faces_np.reshape(-1), dtype=np.int32)
        result["faces"] = wp.array(faces_flat, dtype=wp.int32, device=device)

    point_data = mesh.point_data

    normals = _stack_columns(point_data, _NORMAL_COLUMNS)
    if normals is not None:
        result["vertex_normals"] = wp.array(
            np.ascontiguousarray(normals, dtype=np.float32), dtype=wp.vec3, device=device
        )

    for names in _UV_COLUMN_SETS:
        uv = _stack_columns(point_data, names)
        if uv is not None:
            result["uv"] = wp.array(
                np.ascontiguousarray(uv, dtype=np.float32), dtype=wp.vec2, device=device
            )
            break

    colors_raw = _stack_columns(point_data, _COLOR_COLUMNS_RGBA)
    color_dtype = wp.vec4
    if colors_raw is None:
        colors_raw = _stack_columns(point_data, _COLOR_COLUMNS)
        color_dtype = wp.vec3
    if colors_raw is not None:
        colors = colors_raw.astype(np.float32)
        if np.issubdtype(colors_raw.dtype, np.integer):
            colors /= 255.0
        result["colors"] = wp.array(
            np.ascontiguousarray(colors, dtype=np.float32), dtype=color_dtype, device=device
        )

    face_normals = _face_normals_from_cell_data(mesh)
    if face_normals is not None:
        result["face_normals"] = wp.array(
            np.ascontiguousarray(face_normals, dtype=np.float32), dtype=wp.vec3, device=device
        )

    return result

load_mesh

load_mesh(
    path: str | Path, *, device: DeviceLike = None
) -> wp.Mesh

Load a triangle mesh file into a warp.Mesh.

Thin wrapper over load_mesh_data that keeps only the vertices and triangle faces and wraps them in a warp.Mesh that owns its buffers.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to a mesh file in any format supported by `meshio`.	required
`device`	`DeviceLike`	Warp device for the returned mesh. Defaults to the current Warp device.	`None`

Returns:

Type	Description
`Mesh`	Mesh with `vec3` points and flat `int32` indices.

Raises:

Type	Description
`ValueError`	If the file contains no triangle faces (e.g. a point cloud or a triangle-strip PLY that `meshio` cannot decode), or if a face references a vertex index the file's own vertex count does not cover.

mesh_from_numpy

mesh_from_numpy(
    vertices: ndarray,
    faces: ndarray,
    *,
    device: DeviceLike = None,
) -> Trimesh

Build a Trimesh from NumPy vertex and face arrays.

Parameters:

Name	Type	Description	Default
`vertices`	`ndarray`	`(n_vertices, 3)` vertex positions, any NumPy float dtype.	required
`faces`	`ndarray`	`(n_faces, 3)` (or already-flat length-`3 * n_faces`) triangle vertex indices, any NumPy integer dtype.	required
`device`	`DeviceLike`	Warp device for the returned mesh. Defaults to the current Warp device.	`None`

Returns:

Type	Description
`Trimesh`	New mesh with `vec3` vertices and a flat `int32` face buffer, owning freshly allocated Warp arrays (no aliasing with `vertices` / `faces`).

Raises:

Type	Description
`ValueError`	If a face references a vertex index `vertices` does not cover.