Crate mshio

Parser for Gmsh mesh files using the MSH file format version 4.1

The library supports parsing ASCII and binary encoded MSH files adhering to the MSH file format version 4.1 as specified in the Gmsh documention.

use std::error::Error;
use std::fs;

fn main() -> Result<(), Box<dyn Error>> {
    // Try to read and parse a MSH file
    let msh_bytes = fs::read("tests/data/sphere_coarse.msh")?;
    let parser_result = mshio::parse_msh_bytes(msh_bytes.as_slice());

    // Note that the a parser error cannot be propagated directly using the ?-operator, as it
    // contains a reference into the u8 slice where the error occurred.
    let msh = parser_result.map_err(|e| format!("Error while parsing:\n{}", e))?;
    assert_eq!(msh.total_element_count(), 891);

    Ok(())
}

If parsing was successful, the parse_msh_bytes function returns a MshFile instance. The structure of MshFile closely mirrors the MSH format specification. For example the MeshData associated to a MshFile may contain an optional Elements section. This Elements section can contain an arbitray number of ElementBlock instances, where each ElementBlock only contains elements of the same type and dimension.

Currently, only the following sections of MSH files are actually parsed: Entities, Nodes, Elements. All other sections are silently ignored, if they follow the pattern of being delimited by $SectionName and $EndSectionName (in accordance to the MSH format specification).

Note that the actual values are not checked for consistency beyond what is defined in the MSH format specification. This means, that a parsed element may refer to node indices that are not present in the node section (if the MSH file already contains such an inconsistency). In the future, utility functions may be added to check this.

Although the MshFile struct and all related structs are generic over their value types, the parse_msh_bytes function enforces the usage of u64, i32 and f64 as output value types corresponding to the MSH input value types size_t, int and double (of course size_t values will still be parsed as having the size specified in the file header). We did not encounter MSH files using different types (e.g. 64 bit integers or 32 bit floats) and therefore cannot test it. In addition, the MSH format specification does not specify the size of the float and integer types. If the user desires narrowing conversions, they should be performed manually after parsing the file.

Note that when loading collections of elements/nodes and other entities, the parser checks if the number of these objects can be represented in the system's usize type. If this is not the case it returns an error as they cannot be stored in a Vec in this case.

Re-exports

pub use error::MshParserError;

pub use mshfile::*;

Modules

error	Error handling components of the parser
mshfile	Contains all types that are used to represent the structure of parsed MSH files
parsers	Parser utility functions used by this MSH parser (may be private in the future)

Functions

parse_msh_bytes

Try to parse a MshFile from a slice of bytes