meshio

5.3.5 · active · verified Mon Apr 13

meshio is a Python library for reading and writing various unstructured mesh formats, facilitating smooth conversion between them. It supports a wide array of formats including Abaqus, ANSYS msh, Gmsh, STL, VTK, XDMF, and many others. Currently at version 5.3.5, meshio is actively maintained with regular updates and requires Python 3.8 or newer. It can be used both as a command-line tool for conversions and as a Python API for programmatic mesh manipulation.

Warnings

breaking Breaking changes in meshio versions 4.0.0 and newer, particularly concerning the internal representation and handling of mesh.cells, can cause compatibility issues with code written for older versions, especially when interfacing with other finite element libraries like FEniCS.
Fix: Review and update code that accesses `mesh.cells` or `mesh.cell_data` directly. The structure for `cells` is a list of `(cell_type_string, numpy_array_of_indices)` tuples. Ensure compatibility with meshio's current data structures.
gotcha For full support of all advertised mesh formats (e.g., H5M, NetCDF, comprehensive XDMF features), `meshio` requires several optional dependencies. Without these, attempts to read or write specific formats will result in `ModuleNotFoundError` or similar errors.
Fix: Install `meshio` with all optional dependencies using `pip install meshio[all]` or install specific dependencies (e.g., `h5py`, `netCDF4`, `lxml`) as needed for the desired formats.
gotcha When constructing a `meshio.Mesh` object programmatically, the `cells` argument expects a list of tuples, where each tuple must contain a string identifying the cell type (e.g., "triangle", "quad", "tetra") and a NumPy array of node indices for that cell type. Misunderstanding or incorrectly formatting this can lead to errors, particularly with mixed cell types or incorrect node ordering.
Fix: Always provide the `cells` argument as a list of `(cell_type_string, numpy_array_of_indices)` tuples. Refer to `meshio` documentation or source for exact cell type strings and expected node ordering for each type (e.g., `meshio._common.num_nodes_per_cell`).
breaking Older versions of `meshio` (prior to 5.3.5) exhibited compatibility issues with NumPy 2.0, leading to runtime errors or unexpected behavior.
Fix: Upgrade `meshio` to version 5.3.5 or newer to ensure full compatibility with NumPy 2.0. If an upgrade is not possible, downgrade NumPy to a compatible version (e.g., NumPy 1.x).

Install

pip install meshio Core installation
pip install meshio[all] Installation with all optional dependencies for full format support

Imports

meshio
```
import meshio
```

Quickstart

This quickstart demonstrates how to create a mesh from points and cells, add associated data (point data, cell data), write it to a VTK file, and then read it back. The `meshio.Mesh` constructor takes points, a list of cell blocks (type and indices), and optional point/cell/field data. The `mesh.write()` method saves the mesh, and `meshio.read()` loads it.

import meshio
import numpy as np

# Define points (vertices) of the mesh
points = [
    [0.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [0.0, 1.0, 0.0],
    [1.0, 1.0, 0.0],
    [2.0, 0.0, 0.0],
    [2.0, 1.0, 0.0],
]

# Define cells (elements) of the mesh, grouped by type
# Here, two triangles and one quad
cells = [
    ("triangle", np.array([[0, 1, 2], [1, 3, 2]])),
    ("quad", np.array([[1, 4, 5, 3]])),
]

# Create a Mesh object
mesh = meshio.Mesh(
    points,
    cells,
    # Optionally provide extra data on points, cells, etc.
    point_data={"T": np.array([0.3, -1.2, 0.5, 0.7, 0.0, -3.0])},
    # Each item in cell data must match the cells array structure
    cell_data={"a": [np.array([0.1, 0.2]), np.array([0.4])]}
)

# Write the mesh to a file (format inferred from extension, or explicitly specified)
mesh.write(
    "output.vtk",
    # file_format="vtk", # optional, inferred from extension
    binary=True # Write in binary format (e.g. for VTK)
)

# Read a mesh from a file
read_mesh = meshio.read("output.vtk")

print(f"Read mesh points:\n{read_mesh.points}")
print(f"Read mesh cells:\n{read_mesh.cells}")
print(f"Read mesh point data (T):\n{read_mesh.point_data['T']}")
print(f"Read mesh cell data (a):\n{read_mesh.cell_data['a']}")

view raw JSON →