0
# meshio
1

2
A comprehensive Python library for input/output of mesh files, supporting over 30 different mesh formats used in scientific computing and finite element analysis. meshio enables seamless conversion between formats and provides both command-line tools and a Python API for programmatic mesh manipulation.
3

4
## Package Information
5

6
- **Package Name**: meshio
7
- **Language**: Python
8
- **Installation**: `pip install meshio` or `pip install meshio[all]` (includes optional dependencies)
9

10
## Core Imports
11

12
```python
13
import meshio
14
```
15

16
For working with specific formats:
17

18
```python
19
import meshio.vtk
20
import meshio.gmsh
21
import meshio.xdmf
22
```
23

24
## Basic Usage
25

26
```python
27
import meshio
28

29
# Read a mesh from any supported format
30
mesh = meshio.read("input.msh")
31

32
# Write mesh to a different format
33
meshio.write("output.vtk", mesh)
34

35
# Access mesh properties
36
print(f"Number of points: {len(mesh.points)}")
37
print(f"Cell types: {[cell.type for cell in mesh.cells]}")
38

39
# Create mesh from scratch
40
import numpy as np
41

42
points = np.array([
43
    [0.0, 0.0, 0.0],
44
    [1.0, 0.0, 0.0],
45
    [0.0, 1.0, 0.0],
46
])
47

48
cells = [
49
    ("triangle", [[0, 1, 2]])
50
]
51

52
mesh = meshio.Mesh(points, cells)
53
meshio.write("triangle.vtk", mesh)
54
```
55

56
## Architecture
57

58
meshio uses a unified mesh representation with format-specific readers and writers:
59

60
- **Mesh**: Central class representing mesh data with points, cells, and associated data
61
- **CellBlock**: Container for cells of the same type with connectivity information
62
- **Format modules**: Specialized readers/writers for each supported format (VTK, GMSH, STL, etc.)
63
- **Helper functions**: High-level I/O functions that automatically detect format from file extension
64
- **CLI tools**: Command-line interface for format conversion and mesh inspection
65

66
## Capabilities
67

68
### Core I/O Functions
69

70
Primary functions for reading and writing mesh files across all supported formats, with automatic format detection and comprehensive error handling.
71

72
```python { .api }
73
def read(filename, file_format=None):
74
    """
75
    Read mesh data from file.
76
    
77
    Parameters:
78
    - filename: file path or buffer to read from
79
    - file_format: optional explicit format specification
80
    
81
    Returns:
82
    Mesh object containing points, cells, and data
83
    """
84

85
def write(filename, mesh, file_format=None, **kwargs):
86
    """
87
    Write mesh data to file.
88
    
89
    Parameters:
90
    - filename: file path or buffer to write to
91
    - mesh: Mesh object to write
92
    - file_format: optional explicit format specification
93
    - **kwargs: format-specific options
94
    """
95

96
def write_points_cells(filename, points, cells, point_data=None, cell_data=None, field_data=None, point_sets=None, cell_sets=None, file_format=None, **kwargs):
97
    """
98
    Write mesh data without creating Mesh object.
99
    
100
    Parameters:
101
    - filename: output file path
102
    - points: array-like of mesh points
103
    - cells: cell connectivity data
104
    - point_data: optional point-associated data
105
    - cell_data: optional cell-associated data  
106
    - field_data: optional field data
107
    - point_sets: optional point sets
108
    - cell_sets: optional cell sets
109
    - file_format: optional format specification
110
    """
111
```
112

113
[Core I/O](./core-io.md)
114

115
### Mesh Data Structures
116

117
Core classes for representing mesh geometry, topology, and associated data with methods for manipulation and data conversion.
118

119
```python { .api }
120
class Mesh:
121
    """
122
    Central mesh representation with points, cells, and data.
123
    
124
    Attributes:
125
    - points: array of vertex coordinates
126
    - cells: list of CellBlock objects
127
    - point_data: dict of point-associated data arrays
128
    - cell_data: dict of cell-associated data arrays  
129
    - field_data: dict of field data
130
    - point_sets: dict of point sets
131
    - cell_sets: dict of cell sets
132
    """
133

134
class CellBlock:
135
    """
136
    Container for cells of the same type.
137
    
138
    Attributes:
139
    - type: cell type string
140
    - data: connectivity array
141
    - dim: topological dimension
142
    - tags: list of tags
143
    """
144
```
145

146
[Mesh Data](./mesh-data.md)
147

148
### Format-Specific I/O
149

150
Specialized readers and writers for individual mesh formats, providing format-specific functionality and advanced features like time series support for XDMF.
151

152
```python { .api }
153
# Standard format modules (each provides read/write functions)
154
import meshio.vtk     # VTK legacy format
155
import meshio.vtu     # VTK XML format  
156
import meshio.gmsh    # GMSH format with type conversion utilities
157
import meshio.stl     # STL format
158
import meshio.ply     # PLY format
159
import meshio.obj     # Wavefront OBJ format
160
import meshio.xdmf    # XDMF format with time series support
161
# ... and 25+ more formats
162

163
# Time series support for XDMF
164
from meshio.xdmf import TimeSeriesWriter, TimeSeriesReader
165
```
166

167
[Format Modules](./formats.md)
168

169
### Format Registration
170

171
System for registering custom file formats and managing format detection based on file extensions.
172

173
```python { .api }
174
def register_format(format_name, extensions, reader, writer_map):
175
    """
176
    Register new file format with readers and writers.
177
    
178
    Parameters:
179
    - format_name: name identifier for format
180
    - extensions: list of file extensions  
181
    - reader: reader function for format
182
    - writer_map: dict mapping format to writer function
183
    """
184

185
def deregister_format(format_name):
186
    """
187
    Remove previously registered format.
188
    
189
    Parameters:
190
    - format_name: name of format to remove
191
    """
192
```
193

194
[Format Registration](./format-registration.md)
195

196
### Command Line Interface
197

198
Command-line tools for mesh format conversion, inspection, and manipulation without requiring Python programming.
199

200
```python { .api }
201
def main(argv=None):
202
    """
203
    Entry point for meshio command-line interface.
204
    
205
    Commands:
206
    - convert: convert between formats
207
    - info: display mesh information
208
    - compress/decompress: handle compressed formats
209
    - binary/ascii: convert between binary and ASCII
210
    """
211
```
212

213
[CLI Tools](./cli.md)
214

215
### Error Handling
216

217
Exception classes for handling mesh reading and writing errors with descriptive error messages.
218

219
```python { .api }
220
class ReadError(Exception):
221
    """Exception raised when mesh reading fails."""
222

223
class WriteError(Exception):
224
    """Exception raised when mesh writing fails."""
225
```
226

227
### Constants and Utilities
228

229
Constants and utility functions for working with cell types and format detection.
230

231
```python { .api }
232
topological_dimension: dict
233
# Mapping from cell type names to topological dimensions
234
# e.g., {"triangle": 2, "tetra": 3, "line": 1, ...}
235

236
extension_to_filetypes: dict
237
# Mapping from file extensions to supported format names
238
```
239

240
## Types
241

242
```python { .api }
243
from typing import Optional, Dict, List, Union, Any
244
from numpy.typing import ArrayLike
245

246
# Core types used throughout the API
247
Points = ArrayLike  # Array of point coordinates
248
CellData = List[int]  # Cell connectivity data
249
PointData = Dict[str, ArrayLike]  # Point-associated data
250
CellDataDict = Dict[str, List[ArrayLike]]  # Cell-associated data
251
FieldData = Dict[str, Any]  # Field data
252
PointSets = Dict[str, ArrayLike]  # Named point sets
253
CellSets = Dict[str, List[ArrayLike]]  # Named cell sets
254
```