0
# Format-Specific Modules
1

2
Specialized readers and writers for individual mesh formats, providing format-specific functionality and advanced features for over 30 different mesh file formats.
3

4
## Capabilities
5

6
### Standard Format Modules
7

8
Most format modules follow a consistent pattern, providing `read` and `write` functions for their respective file formats.
9

10
#### Scientific Computing Formats
11

12
High-performance formats commonly used in finite element analysis and computational fluid dynamics.
13

14
```python { .api }
15
# VTK Legacy Format
16
import meshio.vtk
17
def vtk.read(filename):
18
    """Read VTK legacy format files (.vtk)."""
19
def vtk.write(filename, mesh, binary=True):
20
    """Write VTK legacy format with binary option."""
21

22
# VTU (VTK XML) Format  
23
import meshio.vtu
24
def vtu.read(filename):
25
    """Read VTU XML format files (.vtu)."""
26
def vtu.write(filename, mesh, binary=True, compression=None):
27
    """Write VTU format with compression options (zlib, lzma)."""
28

29
# Exodus Format
30
import meshio.exodus
31
def exodus.read(filename):
32
    """Read Exodus II format files (.e, .exo)."""
33
def exodus.write(filename, mesh):
34
    """Write Exodus II format files."""
35

36
# CGNS Format
37
import meshio.cgns
38
def cgns.read(filename):
39
    """Read CGNS format files (.cgns)."""
40
def cgns.write(filename, mesh):
41
    """Write CGNS format files."""
42
```
43

44
#### CAD and Graphics Formats
45

46
Formats commonly used in computer-aided design and 3D graphics applications.
47

48
```python { .api }
49
# STL Format
50
import meshio.stl
51
def stl.read(filename):
52
    """Read STL format files (.stl) - both ASCII and binary."""
53
def stl.write(filename, mesh, binary=True):
54
    """Write STL format with binary/ASCII option."""
55

56
# PLY Format
57
import meshio.ply
58
def ply.read(filename):
59
    """Read PLY format files (.ply) - Stanford Triangle Format."""
60
def ply.write(filename, mesh, binary=True, encoding="ascii"):
61
    """Write PLY format with encoding options."""
62

63
# Wavefront OBJ Format
64
import meshio.obj
65
def obj.read(filename):
66
    """Read Wavefront OBJ format files (.obj)."""
67
def obj.write(filename, mesh):
68
    """Write Wavefront OBJ format files."""
69

70
# OFF Format
71
import meshio.off
72
def off.read(filename):
73
    """Read Object File Format files (.off)."""
74
def off.write(filename, mesh):
75
    """Write Object File Format files."""
76
```
77

78
#### Engineering Analysis Formats
79

80
Formats used by commercial finite element analysis software.
81

82
```python { .api }
83
# NASTRAN Format
84
import meshio.nastran
85
def nastran.read(filename):
86
    """Read NASTRAN format files (.nas, .bdf)."""
87
def nastran.write(filename, mesh):
88
    """Write NASTRAN format files."""
89

90
# ABAQUS Format
91
import meshio.abaqus
92
def abaqus.read(filename):
93
    """Read ABAQUS format files (.inp)."""
94
def abaqus.write(filename, mesh):
95
    """Write ABAQUS format files."""
96

97
# ANSYS Format
98
import meshio.ansys
99
def ansys.read(filename):
100
    """Read ANSYS format files (.ans)."""
101
def ansys.write(filename, mesh):
102
    """Write ANSYS format files."""
103

104
# PERMAS Format
105
import meshio.permas
106
def permas.read(filename):
107
    """Read PERMAS format files (.post, .dat)."""
108
def permas.write(filename, mesh):
109
    """Write PERMAS format files."""
110
```
111

112
#### Specialized Scientific Formats
113

114
Formats for specific domains and applications.
115

116
```python { .api }
117
# MED Format (Salome)
118
import meshio.med
119
def med.read(filename):
120
    """Read MED format files (.med) - Salome platform."""
121
def med.write(filename, mesh):
122
    """Write MED format files."""
123

124
# AVS-UCD Format  
125
import meshio.avsucd
126
def avsucd.read(filename):
127
    """Read AVS-UCD format files (.avs)."""
128
def avsucd.write(filename, mesh):
129
    """Write AVS-UCD format files."""
130

131
# TetGen Format
132
import meshio.tetgen
133
def tetgen.read(filename):
134
    """Read TetGen format files (.node, .ele, .face)."""
135
def tetgen.write(filename, mesh):
136
    """Write TetGen format files."""
137

138
# Netgen Format
139
import meshio.netgen
140
def netgen.read(filename):
141
    """Read Netgen format files (.vol)."""
142
def netgen.write(filename, mesh):
143
    """Write Netgen format files."""
144

145
# FLAC3D Format
146
import meshio.flac3d
147
def flac3d.read(filename):
148
    """Read FLAC3D format files (.f3grid)."""
149
def flac3d.write(filename, mesh):
150
    """Write FLAC3D format files."""
151

152
# SU2 Format
153
import meshio.su2
154
def su2.read(filename):
155
    """Read SU2 format files (.su2)."""
156
def su2.write(filename, mesh):
157
    """Write SU2 format files."""
158
```
159

160
#### Other Specialized Formats
161

162
Additional formats for various applications and software packages.
163

164
```python { .api }
165
# Tecplot Format
166
import meshio.tecplot
167
def tecplot.read(filename):
168
    """Read Tecplot format files (.dat)."""
169
def tecplot.write(filename, mesh):
170
    """Write Tecplot format files."""
171

172
# UGRID Format
173
import meshio.ugrid
174
def ugrid.read(filename):
175
    """Read UGRID format files (.ugrid)."""
176
def ugrid.write(filename, mesh):
177
    """Write UGRID format files."""
178

179
# Medit Format
180
import meshio.medit
181
def medit.read(filename):
182
    """Read Medit format files (.mesh)."""
183
def medit.write(filename, mesh):
184
    """Write Medit format files."""
185

186
# H5M Format (MOAB)
187
import meshio.h5m
188
def h5m.read(filename):
189
    """Read H5M format files (.h5m) - MOAB mesh format."""
190
def h5m.write(filename, mesh):
191
    """Write H5M format files."""
192

193
# MDPA Format (Kratos)
194
import meshio.mdpa
195
def mdpa.read(filename):
196
    """Read MDPA format files (.mdpa) - Kratos MultiPhysics."""
197
def mdpa.write(filename, mesh):
198
    """Write MDPA format files."""
199

200
# HMF Format
201
import meshio.hmf
202
def hmf.read(filename):
203
    """Read HMF format files (.hmascii)."""
204
def hmf.write(filename, mesh):
205
    """Write HMF format files."""
206

207
# Neuroglancer Format
208
import meshio.neuroglancer
209
def neuroglancer.read(filename):
210
    """Read Neuroglancer format files (.ng)."""
211
def neuroglancer.write(filename, mesh):
212
    """Write Neuroglancer format files."""
213

214
# DOLFIN XML Format
215
import meshio.dolfin
216
def dolfin.read(filename):
217
    """Read DOLFIN XML format files (.xml) - FEniCS."""
218
def dolfin.write(filename, mesh):
219
    """Write DOLFIN XML format files."""
220

221
# WKT Format
222
import meshio.wkt
223
def wkt.read(filename):
224
    """Read Well-Known Text format files (.wkt)."""
225
def wkt.write(filename, mesh):
226
    """Write Well-Known Text format files."""
227
```
228

229
### Special Format Modules
230

231
Format modules with enhanced functionality beyond basic read/write operations.
232

233
#### GMSH Format
234

235
Enhanced GMSH support with cell type conversion utilities.
236

237
```python { .api }
238
import meshio.gmsh
239

240
def gmsh.read(filename):
241
    """
242
    Read GMSH format files (.msh) with support for all GMSH versions.
243
    
244
    Supports:
245
    - GMSH format versions 2.2, 4.0, 4.1
246
    - Physical names and entity information
247
    - Periodic boundary conditions
248
    - Node and element data
249
    """
250

251
def gmsh.write(filename, mesh, fmt_version="4.1", binary=True):
252
    """
253
    Write GMSH format files with version control.
254
    
255
    Parameters:
256
    - fmt_version: str - GMSH format version ("2.2", "4.0", "4.1") 
257
    - binary: bool - Write in binary format for better performance
258
    """
259

260
def gmsh.gmsh_to_meshio_type(gmsh_type):
261
    """
262
    Convert GMSH cell type ID to meshio cell type string.
263
    
264
    Parameters:
265
    - gmsh_type: int - GMSH element type ID
266
    
267
    Returns:
268
    - str - Corresponding meshio cell type name
269
    
270
    Examples:
271
    >>> meshio.gmsh.gmsh_to_meshio_type(2)  # "triangle"
272
    >>> meshio.gmsh.gmsh_to_meshio_type(4)  # "tetra"
273
    """
274

275
def gmsh.meshio_to_gmsh_type(meshio_type):
276
    """
277
    Convert meshio cell type string to GMSH cell type ID.
278
    
279
    Parameters:
280
    - meshio_type: str - meshio cell type name
281
    
282
    Returns:
283
    - int - Corresponding GMSH element type ID
284
    
285
    Examples:
286
    >>> meshio.gmsh.meshio_to_gmsh_type("triangle")  # 2
287
    >>> meshio.gmsh.meshio_to_gmsh_type("tetra")     # 4
288
    """
289
```
290

291
#### XDMF Format
292

293
Advanced XDMF support with time series functionality for temporal data.
294

295
```python { .api }
296
import meshio.xdmf
297

298
def xdmf.read(filename):
299
    """
300
    Read XDMF format files (.xdmf, .xmf) with HDF5 data support.
301
    
302
    Supports:
303
    - XDMF version 3.0 specification
304
    - Heavy data stored in HDF5 format
305
    - Structured and unstructured grids
306
    """
307

308
def xdmf.write(filename, mesh, data_format="HDF", compression="gzip"):
309
    """
310
    Write XDMF format files with HDF5 backend.
311
    
312
    Parameters:
313
    - data_format: str - Data storage format ("HDF", "Binary", "XML")
314
    - compression: str - Compression algorithm ("gzip", "lzf", "szip")
315
    """
316

317
class xdmf.TimeSeriesReader:
318
    """
319
    Read time series data from XDMF files.
320
    
321
    Handles temporal datasets where mesh geometry may change over time
322
    or data is associated with different time steps.
323
    """
324
    
325
    def __init__(self, filename):
326
        """
327
        Initialize time series reader.
328
        
329
        Parameters:
330
        - filename: str - Path to XDMF file containing time series data
331
        """
332
    
333
    @property
334
    def num_steps(self):
335
        """
336
        Get number of time steps in the series.
337
        
338
        Returns:
339
        - int - Number of time steps
340
        """
341
    
342
    def read_times(self):
343
        """
344
        Get all available time steps.
345
        
346
        Returns:
347
        - List[float] - List of time values
348
        """
349
    
350
    def read_points_cells(self):
351
        """
352
        Read mesh geometry (points and cells) from time series.
353
        
354
        Returns:
355
        - Tuple[np.ndarray, List[CellBlock]] - Points array and cell blocks
356
        """
357
    
358
    def read_data(self, time_step):
359
        """
360
        Read mesh data for specific time step.
361
        
362
        Parameters:
363
        - time_step: int - Time step index
364
        
365
        Returns:
366
        - Tuple[Mesh, float] - Mesh object and time value
367
        """
368

369
class xdmf.TimeSeriesWriter:
370
    """
371
    Write time series data to XDMF files.
372
    
373
    Allows writing temporal datasets with multiple time steps.
374
    """
375
    
376
    def __init__(self, filename):
377
        """
378
        Initialize time series writer.
379
        
380
        Parameters:
381
        - filename: str - Output XDMF file path
382
        """
383
    
384
    def write_points_cells(self, points, cells):
385
        """
386
        Write mesh geometry (points and cells) to time series file.
387
        
388
        Parameters:
389
        - points: np.ndarray - Point coordinates
390
        - cells: List[CellBlock] - Cell connectivity data
391
        """
392
    
393
    def write_data(self, time, point_data=None, cell_data=None):
394
        """
395
        Write data for specific time step.
396
        
397
        Parameters:
398
        - time: float - Time value for this step
399
        - point_data: Dict[str, np.ndarray] | None - Point-based data
400
        - cell_data: Dict[str, List[np.ndarray]] | None - Cell-based data
401
        """
402
    
403
    def close(self):
404
        """Close the time series file and write final metadata."""
405
```
406

407
#### SVG Format
408

409
Write-only format for creating 2D visualizations.
410

411
```python { .api }
412
import meshio.svg
413

414
def svg.write(filename, mesh, line_width=1.0, point_size=2.0):
415
    """
416
    Write 2D mesh visualization to SVG format (write-only).
417
    
418
    Parameters:
419
    - line_width: float - Width of mesh edges in SVG units
420
    - point_size: float - Size of mesh vertices in SVG units
421
    
422
    Note: Only supports 2D meshes. 3D meshes are projected to 2D.
423
    Primarily used for visualization and documentation purposes.
424
    """
425
```
426

427
## Usage Examples
428

429
### Basic Format Usage
430

431
```python
432
import meshio
433

434
# Standard format usage - automatic detection
435
mesh = meshio.read("input.msh")        # GMSH format
436
mesh = meshio.read("model.vtk")        # VTK format
437
mesh = meshio.read("geometry.stl")     # STL format
438

439
# Write to different formats
440
meshio.write("output.vtu", mesh)       # VTU format
441
meshio.write("surface.ply", mesh)      # PLY format
442
meshio.write("cad_model.obj", mesh)    # OBJ format
443

444
# Format-specific options
445
meshio.write("model.stl", mesh, binary=True)
446
meshio.write("result.vtu", mesh, compression="zlib")
447
```
448

449
### Direct Format Module Usage
450

451
```python
452
# Use format modules directly
453
import meshio.gmsh as gmsh_io
454
import meshio.vtk as vtk_io
455

456
# Read with format-specific functions
457
mesh = gmsh_io.read("complex.msh")
458
legacy_mesh = vtk_io.read("legacy.vtk")
459

460
# Write with format-specific options
461
gmsh_io.write("output.msh", mesh, fmt_version="4.1", binary=True)
462
vtk_io.write("result.vtk", mesh, binary=False)  # ASCII VTK
463
```
464

465
### GMSH Type Conversion
466

467
```python
468
import meshio.gmsh
469

470
# Convert between GMSH and meshio cell types
471
gmsh_triangle_id = meshio.gmsh.meshio_to_gmsh_type("triangle")  # Returns 2
472
meshio_type = meshio.gmsh.gmsh_to_meshio_type(4)               # Returns "tetra"
473

474
# Useful when working directly with GMSH API
475
cell_type_mapping = {
476
    "triangle": meshio.gmsh.meshio_to_gmsh_type("triangle"),
477
    "quad": meshio.gmsh.meshio_to_gmsh_type("quad"), 
478
    "tetra": meshio.gmsh.meshio_to_gmsh_type("tetra")
479
}
480
```
481

482
### XDMF Time Series Operations
483

484
```python
485
import meshio.xdmf
486

487
# Reading time series data
488
reader = meshio.xdmf.TimeSeriesReader("simulation.xdmf")
489
times = reader.read_times()
490
print(f"Available time steps: {times}")
491

492
for i, t in enumerate(times):
493
    mesh, time_val = reader.read_data(i)
494
    print(f"Time {time_val}: {len(mesh.points)} points")
495
    # Process mesh data for this time step
496

497
# Writing time series data
498
writer = meshio.xdmf.TimeSeriesWriter("output_series.xdmf")
499

500
# Assume we have simulation data at multiple time steps
501
time_steps = [0.0, 0.1, 0.2, 0.3, 0.4, 0.5]
502
for i, t in enumerate(time_steps):
503
    # Generate or load data for this time step
504
    point_data = {"temperature": temperature_field[i]}
505
    cell_data = {"pressure": [pressure_field[i]]}
506
    
507
    writer.write_data(t, point_data=point_data, cell_data=cell_data)
508

509
writer.close()
510
```
511

512
### Engineering Format Examples
513

514
```python
515
# NASTRAN format with material properties
516
import meshio.nastran
517
mesh = meshio.nastran.read("model.bdf") 
518
meshio.nastran.write("analysis.nas", mesh)
519

520
# ABAQUS format for finite element analysis
521
import meshio.abaqus
522
fem_mesh = meshio.abaqus.read("part.inp")
523
meshio.abaqus.write("modified.inp", fem_mesh)
524

525
# Exodus format for large-scale simulations
526
import meshio.exodus
527
simulation_mesh = meshio.exodus.read("results.e")
528
meshio.exodus.write("processed.exo", simulation_mesh)
529
```
530

531
### CAD Format Conversions
532

533
```python
534
# Convert CAD formats
535
cad_mesh = meshio.stl.read("part.stl")      # Read STL
536
meshio.obj.write("part.obj", cad_mesh)      # Convert to OBJ
537
meshio.ply.write("part.ply", cad_mesh)      # Convert to PLY
538

539
# STL with specific options
540
meshio.stl.write("binary_part.stl", cad_mesh, binary=True)
541
meshio.stl.write("ascii_part.stl", cad_mesh, binary=False)
542

543
# PLY with encoding options
544
meshio.ply.write("model.ply", cad_mesh, encoding="binary_little_endian")
545
```
546

547
### Visualization Output
548

549
```python
550
# Create 2D visualization
551
import numpy as np
552

553
# Create 2D triangle mesh
554
points = np.array([[0, 0], [1, 0], [0.5, 1]])
555
cells = [("triangle", [[0, 1, 2]])]
556
mesh_2d = meshio.Mesh(points, cells)
557

558
# Write as SVG for documentation
559
meshio.svg.write("mesh_diagram.svg", mesh_2d, line_width=2.0, point_size=3.0)
560
```
561

562
### Format-Specific Features
563

564
```python
565
# GMSH with physical names
566
mesh = meshio.gmsh.read("model.msh")
567
print("Physical entities:", mesh.field_data)
568

569
# VTU with compression
570
meshio.vtu.write("compressed.vtu", mesh, compression="lzma")
571

572
# TetGen multi-file format
573
tetgen_mesh = meshio.tetgen.read("mesh.1")  # Reads .node, .ele, .face files
574
```
575

576
## Format Capabilities Matrix
577

578
| Format | Read | Write | Binary | Compression | Time Series | Special Features |
579
|--------|------|-------|--------|-------------|-------------|------------------|
580
| VTK | ✓ | ✓ | ✓ | - | - | Legacy format |
581
| VTU | ✓ | ✓ | ✓ | ✓ | - | XML-based |
582
| GMSH | ✓ | ✓ | ✓ | - | - | Type conversion |
583
| STL | ✓ | ✓ | ✓ | - | - | Surface meshes |
584
| PLY | ✓ | ✓ | ✓ | - | - | Point clouds |
585
| XDMF | ✓ | ✓ | ✓ | ✓ | ✓ | HDF5 backend |
586
| Exodus | ✓ | ✓ | ✓ | - | ✓ | Large datasets |
587
| NASTRAN | ✓ | ✓ | - | - | - | FEA format |
588
| ABAQUS | ✓ | ✓ | - | - | - | FEA format |
589
| SVG | - | ✓ | - | - | - | 2D visualization |
590
| OBJ | ✓ | ✓ | - | - | - | Graphics format |
591
| TetGen | ✓ | ✓ | - | - | - | Multi-file |
592
593
## Performance Considerations
594

595
### Binary vs ASCII
596

597
```python
598
# Binary formats are faster for large meshes
599
meshio.write("large.vtu", big_mesh, binary=True)     # Faster
600
meshio.write("large.vtu", big_mesh, binary=False)    # Slower, human-readable
601

602
# STL binary is much more compact
603
meshio.stl.write("model.stl", mesh, binary=True)     # Recommended
604
meshio.stl.write("model.stl", mesh, binary=False)    # For debugging
605
```
606

607
### Compression Options
608

609
```python
610
# Use compression for storage efficiency
611
meshio.write("data.vtu", mesh, compression="zlib")   # Good compression/speed balance
612
meshio.write("data.vtu", mesh, compression="lzma")   # Better compression, slower
613
meshio.write("data.vtu", mesh, compression=None)     # No compression, fastest I/O
614
```
615

616
### Format Selection Guidelines
617

618
- **VTK/VTU**: General-purpose, good ParaView support
619
- **GMSH**: Mesh generation, preprocessor compatibility  
620
- **STL**: CAD interchange, 3D printing
621
- **PLY**: Point clouds, computer graphics
622
- **XDMF**: Large datasets, time series, parallel I/O
623
- **Exodus**: Large-scale simulations, Sandia tools
624
- **NASTRAN/ABAQUS**: Commercial FEA software
625
- **HDF5-based formats**: Very large datasets, parallel access