Skip to content

Add native OBJ, STL, PLY, SU2 and Nastran mesh I/O - #330

Open
vijaiaeroastro wants to merge 9 commits into
MmgTools:developfrom
vijaiaeroastro:feature/native-io-formats
Open

Add native OBJ, STL, PLY, SU2 and Nastran mesh I/O#330
vijaiaeroastro wants to merge 9 commits into
MmgTools:developfrom
vijaiaeroastro:feature/native-io-formats

Conversation

@vijaiaeroastro

Copy link
Copy Markdown

This PR makes progress on #44 by adding direct support for five commonly used
mesh-exchange formats through Mmg's existing public APIs and generic file
dispatch. The readers and writers are implemented directly in Mmg, without
requiring an additional runtime, and are available consistently to the C, C++,
Fortran and command-line interfaces.

I could not use meshio directly for this implementation because it is a
Python/NumPy library, while these readers and writers need to be available from
Mmg's native C, C++ and Fortran APIs without requiring a Python runtime.
meshio still provided a useful interoperability reference for the formats it
supports.

I intend this as a substantial first step toward #44 rather than closing the
issue. I have left formats such as Gmsh 4 and CGNS for follow-up PRs.

What is included

  • OBJ for MMGS

    • Reads polygonal faces and triangulates them for MMGS.
    • Supports positive and negative OBJ indices.
    • Maps groups and materials to stable Mmg references. Explicit
      mmg_ref_<id> names preserve the requested reference.
    • Writes a companion MTL file and uses materials to preserve triangle
      references across a round trip.
  • STL for MMGS

    • Reads both ASCII and binary STL, with content-based input detection.
    • Writes binary STL using the standard .stl extension.
    • Welds repeated facet vertices with a scale-aware tolerance, including for
      meshes with very small coordinates.
  • PLY for MMGS

    • Reads ASCII and binary little-endian PLY.
    • Handles arbitrary supported property ordering and ignores unrelated
      properties.
    • Writes binary PLY by default and ASCII PLY with the .plya extension.
    • Emits standard PLY 32-bit integer types. The reader remains permissive
      toward non-standard 64-bit integer properties, while the writer reports an
      error if a value cannot be represented by the PLY 1.0 scalar types.
  • SU2 for MMG2D, MMG3D and MMGS

    • Reads and writes native 2D, 3D volume and 3D surface SU2 meshes.
    • Supports triangles and quadrilaterals in 2D, and tetrahedra and prisms in
      3D, together with boundary markers.
    • Imports hexahedra and pyramids by conformingly decomposing hybrid volume
      meshes into tetrahedra. A warning is emitted when this conversion occurs.
    • Preserves explicit mmg_ref_<id> marker references and assigns
      collision-free fallback references to ordinary marker names.
    • MMGS imports triangular and quadrilateral faces from 3D marker sections,
      splitting quadrilaterals deterministically. It also accepts standalone
      surface-only files that place those faces in NELEM, provided no volume
      cells are mixed in.
    • MMGS output uses reference-grouped 3D marker sections, matching the usual
      SU2 representation of a boundary surface.
  • Nastran bulk data for MMGS and MMG3D

    • Reads common free-field and fixed-field mesh cards and writes a portable
      bulk-data representation.
    • Supports surface triangles/quadrilaterals and volume tetrahedra/prisms.
    • Imports CHEXA and CPYRAM cells through a conforming tetrahedral
      decomposition, with a warning when conversion is required.
    • Preserves Mmg references through property IDs and $MMG_REF metadata.

The new formats participate in the existing extension-based generic I/O path;
the established readers are otherwise left intact.

API and compatibility

  • Adds format identifiers after MMG5_FMT_Unknown without changing its public
    numeric value.
  • Adds format-specific load/save entry points to the relevant MMG2D, MMG3D and
    MMGS public APIs.
  • Adds corresponding Fortran wrappers and generated constants.
  • Keeps format behavior local to each Mmg variant: surface-only formats are
    not exposed as volume readers, and SU2/Nastran support follows the element
    types represented by the relevant API.
  • Introduces no new external runtime dependency.

Testing

Each format has API-level tests using actual mesh files generated by the test
programs. The tests cover generic and format-specific entry points, round trips,
reference preservation, element ordering, malformed or unsupported input, and
the hybrid-cell conversions used by SU2 and Nastran.

Additional checks include:

  • ASCII/binary STL detection and nanoscale vertex welding.
  • PLY property reordering, CRLF input, large floating-point coordinates,
    standard signed/unsigned reference output and 64-bit input policy.
  • OBJ polygon triangulation, negative indices, group/material precedence and
    MTL output.
  • SU2 and Nastran shared-face conformity, orientation, volume preservation and
    reference mapping.
  • SU2 surface extraction from volume-grid markers, standalone surface input,
    quadrilateral splitting and MMGS round trips.
  • Builds and focused tests with both 32-bit and 64-bit MMG5_int.
  • AddressSanitizer runs for the new readers and writers.
  • Shared-library and Fortran builds matching the failing GitHub Actions
    configuration.
  • PLY output interoperability checked with hapPLY.

Follow-up work

I intentionally kept the following formats out of this PR so that their design,
dependencies and review remain manageable:

  • Gmsh 4.x (especially 4.1): add native surface and volume support for the
    block-based $Entities, $Nodes and $Elements model. Version detection
    should select the new path without competing with or regressing the existing
    legacy Gmsh reader. Physical groups, entity tags, sparse node tags and both
    ASCII and binary encodings need explicit tests.

  • CGNS: add surface and volume I/O through optional libcgns/HDF5 support.
    This should use the project's established optional-dependency conventions,
    with a clear CMake feature switch and useful behavior when CGNS is not
    installed. Element sections, boundary conditions, families and Mmg
    references need a documented mapping.

  • Broader interoperability fixtures: add a small curated corpus produced by
    Gmsh, SU2, common CAD/meshing tools and Nastran-compatible solvers as the
    native readers mature.

@CLAassistant

CLAassistant commented Aug 30, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants