0
# Command Line Interface
1

2
Command-line tools for mesh format conversion, inspection, and manipulation without requiring Python programming. The meshio CLI provides a powerful set of utilities for working with mesh files from the shell.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
Primary command-line interface providing access to all mesh operations through subcommands.
9

10
```python { .api }
11
def main(argv=None):
12
    """
13
    Entry point for meshio command-line interface.
14
    
15
    Parameters:
16
    - argv: List[str] | None - Command line arguments
17
        If None, uses sys.argv. Primarily for testing and programmatic use.
18
        
19
    Returns:
20
    - int - Exit code (0 for success, non-zero for errors)
21
    
22
    Available Commands:
23
    - convert (c): Convert between mesh formats
24
    - info (i): Display mesh information and validate consistency
25
    - compress: Compress mesh files to reduce size
26
    - decompress: Decompress compressed mesh files  
27
    - ascii (a): Convert mesh files to ASCII format
28
    - binary (b): Convert mesh files to binary format
29
    
30
    Global Options:
31
    - --version, -v: Display version information
32
    - --help, -h: Show help message
33
    
34
    Examples:
35
    $ meshio convert input.msh output.vtk
36
    $ meshio info mesh.stl
37
    $ meshio compress large_file.vtu --max
38
    """
39
```
40

41
### Subcommand Functions
42

43
Individual CLI commands for specific mesh operations.
44

45
#### Format Conversion
46

47
```python { .api }
48
# meshio convert / meshio c
49
"""
50
Convert between different mesh file formats.
51

52
Usage:
53
  meshio convert [options] <input_file> <output_file>
54
  meshio c [options] <input_file> <output_file>
55

56
Arguments:
57
  input_file                    Source mesh file to read
58
  output_file                   Target mesh file to write
59

60
Options:
61
  --input-format, -i FORMAT     Explicit input format specification
62
                                Choices: {all_reader_formats}
63
  --output-format, -o FORMAT    Explicit output format specification
64
                                Choices: {all_writer_formats}
65
  --ascii, -a                   Write in ASCII format variant (default: binary)
66
  --float-format, -f FORMAT     Float format for ASCII output (default: .16e)
67
  --sets-to-int-data, -s        Convert sets to integer data arrays
68
                                Useful when output format doesn't support sets
69
  --int-data-to-sets, -d        Convert integer data to sets
70
                                Useful when output format doesn't support int data
71

72
Examples:
73
  meshio convert mesh.msh result.vtk
74
  meshio convert --ascii model.stl output.ply
75
  meshio convert -i gmsh -o vtk data.dat result.vtk
76
  meshio convert --sets-to-int-data mesh.msh output.stl
77
"""
78

79
# meshio info / meshio i  
80
"""
81
Display detailed information about mesh files and validate consistency.
82

83
Usage:
84
  meshio info [options] <input_file>
85
  meshio i [options] <input_file>
86

87
Arguments:
88
  input_file                    Mesh file to analyze
89

90
Options:
91
  --input-format, -i FORMAT     Explicit input format specification
92
                                Choices: {all_reader_formats}
93

94
Output Information:
95
  - Number of points and cells by type
96
  - Point data, cell data, and field data names
97
  - Point sets and cell sets
98
  - Mesh consistency validation
99
  - Warnings for unused points or invalid cell references
100

101
Examples:
102
  meshio info model.vtk
103
  meshio info --input-format gmsh data.dat
104
"""
105

106
# meshio compress
107
"""
108
Compress mesh files to reduce file size using format-specific compression.
109

110
Usage:
111
  meshio compress [options] <input_file>
112

113
Arguments:
114
  input_file                    Mesh file to compress
115

116
Options:
117
  --input-format, -i FORMAT     Explicit input format specification
118
  --max                         Use maximum compression level
119

120
Supported Formats:
121
  - VTU: Uses zlib or lzma compression
122
  - XDMF: Compresses HDF5 data arrays
123
  - Other formats: Converts to compressed variant if available
124

125
Examples:
126
  meshio compress large_mesh.vtu
127
  meshio compress --max simulation_data.xdmf
128
"""
129

130
# meshio decompress
131
"""
132
Decompress compressed mesh files.
133

134
Usage:  
135
  meshio decompress [options] <input_file>
136

137
Arguments:
138
  input_file                    Compressed mesh file to decompress
139

140
Options:
141
  --input-format, -i FORMAT     Explicit input format specification
142

143
Examples:
144
  meshio decompress compressed_mesh.vtu.gz
145
  meshio decompress data.xdmf
146
"""
147

148
# meshio ascii / meshio a
149
"""
150
Convert mesh files to ASCII/text format variants.
151

152
Usage:
153
  meshio ascii [options] <input_file>
154
  meshio a [options] <input_file>
155

156
Arguments:
157
  input_file                    Mesh file to convert to ASCII
158

159
Options:
160
  --input-format, -i FORMAT     Explicit input format specification
161

162
Behavior:
163
  - Creates ASCII version with same base name
164
  - Useful for debugging and human-readable output
165
  - Shows file size before and after conversion
166

167
Examples:
168
  meshio ascii binary_mesh.stl    # Creates ASCII version
169
  meshio ascii model.vtk          # Converts to ASCII VTK
170
"""
171

172
# meshio binary / meshio b  
173
"""
174
Convert mesh files to binary format variants.
175

176
Usage:
177
  meshio binary [options] <input_file>
178
  meshio b [options] <input_file>
179

180
Arguments:
181
  input_file                    Mesh file to convert to binary
182

183
Options:
184
  --input-format, -i FORMAT     Explicit input format specification
185

186
Behavior:
187
  - Creates binary version with same base name
188
  - Significantly reduces file size for large meshes
189
  - Faster I/O performance
190
  - Shows file size before and after conversion
191

192
Examples:
193
  meshio binary ascii_mesh.stl    # Creates binary version
194
  meshio binary large_model.vtk   # Converts to binary VTK
195
"""
196
```
197

198
## Usage Examples
199

200
### Basic Format Conversion
201

202
```bash
203
# Convert GMSH file to VTK format
204
meshio convert mesh.msh output.vtk
205

206
# Convert with explicit format specification
207
meshio convert --input-format gmsh --output-format vtk data.dat result.vtk
208

209
# Short form using aliases
210
meshio c input.stl output.ply
211

212
# Force ASCII output
213
meshio convert --ascii binary_mesh.stl text_mesh.obj
214

215
# Specify float precision for ASCII output
216
meshio convert --ascii --float-format .8e precise.vtk output.ply
217
```
218

219
### Mesh Information and Validation
220

221
```bash
222
# Display basic mesh information
223
meshio info model.vtk
224
# Output:
225
# <meshio mesh object>
226
#   Number of points: 1000
227
#   Number of cells:
228
#     triangle: 1800
229
#     quad: 200
230
#   Point data: temperature, velocity
231
#   Cell data: material_id
232
#   Field data: simulation_time
233

234
# Check mesh with explicit format
235
meshio info --input-format stl surface.dat
236

237
# Short form
238
meshio i complex_mesh.msh
239
```
240

241
### Data Conversion Between Set Types
242

243
```bash
244
# Convert sets to integer data (useful for formats that don't support sets)
245
meshio convert --sets-to-int-data mesh_with_sets.msh output.stl
246

247
# Convert integer data to sets (useful for formats that support sets)
248
meshio convert --int-data-to-sets data_with_ids.vtk output.msh
249
```
250

251
### File Compression and Optimization
252

253
```bash
254
# Compress large mesh files
255
meshio compress large_simulation.vtu
256
# Shows size reduction and creates compressed version
257

258
# Maximum compression
259
meshio compress --max huge_dataset.xdmf
260

261
# Decompress files
262
meshio decompress compressed_mesh.vtu.gz
263
```
264

265
### Format Conversion for Optimization
266

267
```bash
268
# Convert to binary for better performance
269
meshio binary slow_ascii.vtk
270
# Output: File size before: 25.3 MB
271
#         File size after: 8.7 MB
272

273
# Convert to ASCII for debugging
274
meshio ascii binary_mesh.stl
275
# Creates human-readable version for inspection
276

277
# Alternative short forms
278
meshio a binary_file.ply    # Convert to ASCII
279
meshio b ascii_file.obj     # Convert to binary
280
```
281

282
### Batch Processing Examples
283

284
```bash
285
# Convert multiple files (shell scripting)
286
for file in *.msh; do
287
    meshio convert "$file" "${file%.msh}.vtk"
288
done
289

290
# Compress all VTU files in directory
291
find . -name "*.vtu" -exec meshio compress {} \;
292

293
# Check all mesh files for consistency
294
for mesh in *.vtk *.msh *.stl; do
295
    echo "Checking $mesh:"
296
    meshio info "$mesh"
297
    echo "---"
298
done
299
```
300

301
### Advanced Format Conversion
302

303
```bash
304
# Handle formats without standard extensions
305
meshio convert --input-format nastran model.dat --output-format vtk result.vtk
306

307
# Convert with data type optimization
308
meshio convert --sets-to-int-data --ascii fem_model.msh cad_export.obj
309

310
# Chain operations using shell pipes and temporary files
311
meshio convert input.msh temp.vtk && meshio compress temp.vtk && rm temp.vtk
312
```
313

314
### Integration with Other Tools
315

316
```bash
317
# Use with ParaView (VTK formats)
318
meshio convert simulation.msh visualization.vtu
319
paraview visualization.vtu
320

321
# Prepare for 3D printing (STL format)
322
meshio convert cad_model.obj print_ready.stl
323
meshio info print_ready.stl  # Verify mesh is manifold
324

325
# Export for web visualization
326
meshio convert --ascii model.vtk web_display.obj
327

328
# Prepare for finite element analysis
329
meshio convert --int-data-to-sets geometry.stl analysis.msh
330
```
331

332
### Error Handling and Debugging
333

334
```bash
335
# Check file before conversion
336
meshio info problematic_file.msh
337
if [ $? -eq 0 ]; then
338
    meshio convert problematic_file.msh fixed_file.vtk
339
else
340
    echo "Mesh file has issues"
341
fi
342

343
# Verbose conversion with format specification
344
meshio convert --input-format vtk --output-format stl data.bin surface.stl
345

346
# Handle unknown extensions explicitly
347
meshio convert --input-format gmsh data.mesh --output-format ply output.ply
348
```
349

350
## CLI Integration Patterns
351

352
### Makefile Integration
353

354
```makefile
355
# Convert all source meshes to VTK for visualization
356
%.vtk: %.msh
357
	meshio convert $< $@
358

359
# Create ASCII versions for version control
360
%.ascii.vtk: %.vtk
361
	meshio ascii $<
362

363
# Compress final results
364
%.compressed: %
365
	meshio compress $<
366

367
# Batch target
368
convert_all: $(patsubst %.msh,%.vtk,$(wildcard *.msh))
369

370
check_all:
371
	@for mesh in *.msh *.vtk; do \
372
		echo "Checking $$mesh:"; \
373
		meshio info "$$mesh"; \
374
	done
375
```
376

377
### Shell Script Integration
378

379
```bash
380
#!/bin/bash
381
# mesh_pipeline.sh - Automated mesh processing pipeline
382

383
INPUT_DIR="input_meshes"
384
OUTPUT_DIR="processed_meshes"
385
TEMP_DIR="temp"
386

387
mkdir -p "$OUTPUT_DIR" "$TEMP_DIR"
388

389
for input_file in "$INPUT_DIR"/*.msh; do
390
    basename=$(basename "$input_file" .msh)
391
    temp_file="$TEMP_DIR/${basename}.vtk"
392
    output_file="$OUTPUT_DIR/${basename}_processed.vtu"
393
    
394
    echo "Processing $basename..."
395
    
396
    # Convert to VTK first
397
    if meshio convert "$input_file" "$temp_file"; then
398
        echo "  Converted to VTK"
399
        
400
        # Validate mesh
401
        if meshio info "$temp_file" > /dev/null 2>&1; then
402
            echo "  Mesh validation passed"
403
            
404
            # Convert to compressed VTU
405
            meshio convert --sets-to-int-data "$temp_file" "$output_file"
406
            meshio compress "$output_file"
407
            echo "  Final output: $output_file"
408
        else
409
            echo "  WARNING: Mesh validation failed for $basename"
410
        fi
411
    else
412
        echo "  ERROR: Conversion failed for $basename"
413
    fi
414
done
415

416
# Cleanup
417
rm -rf "$TEMP_DIR"
418
echo "Pipeline complete!"
419
```
420

421
### Python Script Integration
422

423
```python
424
#!/usr/bin/env python3
425
import subprocess
426
import sys
427
import os
428

429
def run_meshio_command(cmd, *args):
430
    """Run meshio command and return success status."""
431
    try:
432
        result = subprocess.run(['meshio'] + [cmd] + list(args), 
433
                              capture_output=True, text=True)
434
        if result.returncode == 0:
435
            return True, result.stdout
436
        else:
437
            return False, result.stderr
438
    except Exception as e:
439
        return False, str(e)
440

441
def convert_mesh(input_file, output_file, **options):
442
    """Convert mesh with options."""
443
    cmd_args = ['convert']
444
    
445
    if 'input_format' in options:
446
        cmd_args.extend(['--input-format', options['input_format']])
447
    if 'output_format' in options:
448
        cmd_args.extend(['--output-format', options['output_format']])
449
    if options.get('ascii', False):
450
        cmd_args.append('--ascii')
451
    if options.get('sets_to_int_data', False):
452
        cmd_args.append('--sets-to-int-data')
453
        
454
    cmd_args.extend([input_file, output_file])
455
    
456
    success, output = run_meshio_command(*cmd_args)
457
    return success, output
458

459
# Usage example
460
if __name__ == "__main__":
461
    input_mesh = "model.msh"
462
    output_mesh = "model.vtk"
463
    
464
    success, message = convert_mesh(
465
        input_mesh, output_mesh,
466
        ascii=True,
467
        sets_to_int_data=True
468
    )
469
    
470
    if success:
471
        print(f"Successfully converted {input_mesh} to {output_mesh}")
472
    else:
473
        print(f"Conversion failed: {message}")
474
        sys.exit(1)
475
```
476

477
## Performance and Best Practices
478

479
### File Size Optimization
480

481
```bash
482
# For large files, binary formats are much smaller and faster
483
meshio convert large_mesh.msh large_mesh.vtu  # Binary VTU
484
meshio binary large_mesh.vtk                  # Convert to binary
485

486
# Compression for long-term storage
487
meshio compress simulation_results.vtu --max  # Maximum compression
488
```
489

490
### Format Selection Guidelines
491

492
- **For visualization**: Use VTK/VTU formats with ParaView
493
- **For CAD interchange**: Use STL, OBJ, or PLY formats
494
- **For FEA preprocessing**: Use GMSH, NASTRAN, or ABAQUS formats  
495
- **For large datasets**: Use XDMF with HDF5 backend
496
- **For version control**: Use ASCII formats in development
497

498
### Error Recovery
499

500
```bash
501
# Always validate before and after conversion
502
meshio info input.msh && meshio convert input.msh output.vtk && meshio info output.vtk
503

504
# Use explicit format specification for ambiguous extensions
505
meshio convert --input-format gmsh --output-format vtk data.dat result.vtk
506
```
507

508
The meshio CLI provides a comprehensive set of tools for mesh file manipulation, making it easy to integrate mesh processing into automated workflows and build robust mesh processing pipelines.