glTF (.glb, .gltf)

glTF 2.0 output and input — a web-native skin export, with a general reader for the way back: the browser viewer, three.js, Blender, model viewers and dashboards load it directly, with no meshio++ in the loop. The surface of the mesh is exported; .glb writes the single-file binary container and .gltf writes JSON with a .bin sidecar beside it (the debuggable alternative).

Format name	gltf
Extensions	.glb, .gltf
Read / Write	✓ / ✓
Extra dependencies	—

Reading & writing

Reading is described under Reading. Full write signature:

import meshioplusplus

meshioplusplus.gltf.write(
    "out.glb", mesh,
    split_angle=30.0,
    normal_weight="angle",
    normals=True,
    fields=True,
    color_by=None,
    component=None,
    cmap="viridis",
    vmin=None,
    vmax=None,
    nan_color="#808080",
    unlit=True,
    up_axis="auto",
    recenter=True,
    scale=1.0,
    by_region=True,
    container="auto",
)

• container — "auto" (default) follows the suffix: .glb is binary, anything else is JSON plus <name>.bin. "glb" and "gltf" override it. A file-like object always receives the binary container.
• split_angle / normal_weight / normals — see Normals.
• fields — export the point_data arrays as _NAME attributes, see Fields.
• color_by … unlit — bake a field into COLOR_0, see Colour.
• up_axis / recenter / scale — see Conventions.
• by_region — one node per cell region (default) or a single node named mesh.

meshioplusplus convert in.vtu out.glb writes the defaults. The colour flags of convert (--color-by, --component, --cmap, --vmin, --vmax, --nan-color) apply to glTF output too, plus --split-angle and --up-axis; --colorbar is svg/tikz only. The MCP server exposes every option as export_gltf. Flat bindings retain the default mio_write/writeMesh path and also expose every GltfWriteOptions field through mio_gltf_opts_init + mio_write_gltf (C), m%write_gltf(..., options=...) (Fortran), write_gltf (Julia), mio_write_gltf (R) and writeGltf (WASM). Components are 0-based in C/WASM and 1-based in Fortran/Julia/R; unset selects magnitude. Unset range endpoints select the native automatic range.

Reading

meshioplusplus.read("model.glb") is a general glTF 2.0 reader, not one limited to meshio++'s own output (C++ core and a Python twin, gltf/_gltf_read.py). Signature: meshioplusplus.gltf.read(filename, points_only=False, arrays=None, weld=False).

• Containers: .glb (the JSON chunk and the BIN chunk) and .gltf with external buffers (a relative path, percent-decoded, never leaving the file's directory) or data: base64 URIs.
• Primitives: POINTS become vertex cells, LINES, LINE_STRIP and LINE_LOOP line cells, TRIANGLES, TRIANGLE_STRIP and TRIANGLE_FAN triangle cells, indexed or not (degenerate strip and fan joins are dropped). Blocks come back in the order triangle, line, vertex; every primitive keeps its own vertices unless weld=True.
• Accessors: every componentType, normalized, byteStride, sparse accessors, and KHR_mesh_quantization data (integer, normalized positions with the scale on the node).
• Transforms: node TRS or matrix, applied down the hierarchy into world space (glTF's Y-up). The root node meshio++ as this writer emits it (up-axis rotation, uniform scale, recentring translation) is undone, so a file written from Z-up data reads back Z-up, within float32 precision. A node reached twice is an error.
• Structure: a node name becomes a cell region (unassigned and mesh, the writer's names for "no region", give none); the _NAME attributes become point_data under the accessor's name (or the attribute name without its underscore); COLOR_0 becomes gltf:color; the NORMAL of a POINTS primitive becomes normals (the normals of triangles are derived, so they are not kept). A field present on only some primitives is NaN elsewhere.
• weld=True merges vertices with identical world positions across the file, undoing the per-fan split of the writer's normals; the first vertex's attributes win. Positions are compared by value, so -0.0 and +0.0 are one position and a position holding a NaN merges with none (the C++ core matches the Python twin's points + 0.0 here since roadmap 5.7.3; before, the two zeros met only when their hashes happened to collide).
• Refused: Draco (KHR_draco_mesh_compression) and meshopt (EXT_meshopt_compression) by name. Skipped with one warning: morph targets, skins, animations and textures (materials are ignored silently); TEXCOORD_0 is read as uv. Malformed input — a bad index, an accessor past its buffer view, a truncated GLB, invalid JSON — is a ReadError.
• Volume cells came out of the writer as their skin, so the round trip is → tri in the conformance matrix.

What is exported

Everything is reduced to a surface, in this order:

• The skin of volume blocks — the boundary facets of tetra, hexahedron, wedge, pyramid and their higher-order forms, linearised to triangles and quads (see Skin extraction). Interior faces are not written.
• 2-D cells — triangle, quad and polygon blocks (ragged or rectangular), triangulated with the same fan convert_cells(simplexify) uses; higher-order cells contribute their corner nodes. A 2-D cell that coincides with a skin facet wins: the facet is dropped and the cell is exported instead, so a boundary patch such as a wall region keeps its own cells and does not z-fight with the skin.
• line cells as LINES primitives (a two-node segment per cell).
• vertex cells as POINTS; and a mesh with no cells at all — which is how a .pcd or .xyz point cloud arrives — as one POINTS primitive over every point, so those formats get a web output for free.

Triangles with a repeated point id are dropped. Other cell types (for example the VTK_LAGRANGE_* families) have no glTF equivalent: they are skipped with a warning and a provenance note.

Normals

glTF normals are per vertex, so a crease needs its position twice. Triangles are grouped into smooth fans exactly as compute_normals does — the same kernel, run over the whole soup so that smoothing crosses region borders — and each fan becomes its own vertex. split_angle is the largest dihedral angle, in degrees and in [0, 180], still treated as smooth; boundary edges, non-manifold edges and edges whose two triangles are wound the same way always cut, and the triangles fanned from one polygon or one volume facet are never separated from each other. normal_weight is "angle" (default) or "area". normals=False writes no NORMAL and shares vertices.

A group whose triangles have no area gets the normal (0, 0, 1). A POINTS primitive gets a NORMAL from the normals point data when every exported row of it is finite and non-zero (it is normalised first), which is how a cloud written by compute_normals keeps its normals; otherwise NORMAL is omitted with a warning.

Fields

glTF has no scalar-field concept. Every point_data array of one to four components is exported raw as an underscore-prefixed custom attribute — temperature becomes _TEMPERATURE, a 3-component velocity becomes a VEC3 _VELOCITY — cast to float32, with the original name in the accessor's name. Names are upper-cased (ASCII), every other character becomes _, and two names that collapse onto one get a numeric suffix (_T, _T_2). There is no 32-bit integer vertex attribute type, so integer arrays are cast to float. An array with more than four components, and an array with a non-finite value on an exported point (glTF cannot hold one), is skipped with a warning and a provenance note. normals is never exported as a field. uv (two values per point, finite on the exported points) is written as TEXCOORD_0 on the triangles instead, with v flipped to 1 - v (glTF's texture origin is the image's top left, uv's the bottom left), and the reader turns TEXCOORD_0 back into uv; see parameterize. With weld=True a seam's copies are merged and keep one of their uv.

Colour

color_by names a point_data or cell_data array (a point array wins if both exist) to bake through a colormap into COLOR_0, with the raw values alongside as _NAME:

• Point data colours each vertex by its point's value; the renderer interpolates between the vertex colours. Cell data colours each triangle by its cell's value — through the parent volume cell for a skin facet — and vertices are split per cell so the colour stays flat.
• Multi-component arrays reduce to component or to their magnitude. The range is vmin..vmax, defaulting to the finite range of the exported vertices. Non-finite values take nan_color, given as #rrggbb. cmap is one of the built-in tables the SVG and TikZ writers and the software rasterizer use: viridis, coolwarm, turbo, magma, inferno, plasma or grey, or the reversed _r variant of any.
• COLOR_0 is linear in glTF, while the colormap tables hold 8-bit sRGB display values, so each byte goes through the inverse sRGB transfer function first — otherwise every viewer would brighten the map. The conversion is a 256-entry table of float32 bit patterns (generated by tools/gen_srgb_linear.py), not a pow, so both engines write the same bytes whatever libm they link.
• color_by="rgb" (when no array is named rgb) takes the UInt8 red, green and blue point or cell data colorize bakes as they are, through the same sRGB-to-linear step, with no colormap or range: a banded deviation map, or any colouring made beforehand, reaches glTF unchanged.
• The material becomes KHR_materials_unlit with a white base colour, because shading distorts a colour reading; unlit=False keeps the standard PBR material. Without color_by no vertex colours are written and the material is a plain grey.

Structure

One glTF node, and one mesh, per cell region, named by the region. A cell that is in several regions goes to the smallest one (ties go to the first in the canonical (kind, name, dim, tag) order), regions with the same name share a node, and a cell in no region goes to a node named unassigned; a note in the provenance record counts the overlaps. Only regions of kind cell matter — point and side regions are not exported. A mesh with no cell regions, or by_region=False, is one node named mesh. Nodes that would hold nothing are not written. Under one root node named meshio++, the scene has a single material shared by every primitive, which is doubleSided because the operation does not reorient the surface.

Conventions

glTF is float32, right-handed, Y-up and metric. CAE data is usually Z-up and in its own unit, and often far from the origin, so the changes are carried by the root node's transform rather than written into the coordinates:

• up_axis names the source axis that points up: "z" is a rotation of −90° about X (a source (x, y, z) lands at (x, z, −y)), "x" a rotation of +90° about Z ((−y, x, z)), "y" none. "auto" (default) picks y for a flat mesh — 2-D points, or every exported z within 1e-14 of zero, the SVG writer's rule — and z otherwise.
• recenter subtracts the exported points' bounding-box centre from every position, so a model with coordinates in the millions keeps float32 precision; the root node's translation is that centre, rotated and scaled, so the world position of every vertex is exactly the source position.
• scale is the factor from the source unit to metres (0.001 for millimetres), carried as the root node's scale.

The rotation is a permutation with signs, so the transform is exactly reversible.

Container

The writer follows the specification's rules for the binary container. A 12-byte header (magic 0x46546C67, version 2, total length), then chunks of length, type, data, each 4-byte aligned: the JSON chunk padded with spaces, and the BIN chunk (omitted when there is no geometry) padded with zeros. Every accessor has its own bufferView with its target; indices are uint32 (a primitive with more than 2^32 − 2 vertices, or a container beyond 4 GiB, is a WriteError); POSITION carries min and max, written as the exact float32 values, which is what the validator checks them against. Numbers are written with %.17g, so the JSON is byte-exact between the engines. asset.generator is the provenance tag; with a scope open, the full record goes in asset.extras["meshioplusplus:provenance"].

An empty mesh writes an empty scene ("scenes":[{}]) with no buffer. A non-finite coordinate on an exported point is a WriteError.

C++ vs Python

The C++ core (write_gltf, in formats/gltf.hpp) and the Python reference (gltf/_gltf.py) follow the same steps in the same order with the same arithmetic — the smooth-fan grouping is the bit-exact pair detail::vertex_normal_groups / _normals.vertex_normal_groups — and write identical bytes for .glb and for .gltf and its sidecar; tests/python/test_gltf.py pins that across cubes, volumes, a sphere, an open cylinder, regions, ragged polygons, lines and point clouds under six option sets. Set MESHIOPLUSPLUS_STRICT_CORE=1 to prove the native path handles a file.

Validation

The output passes the Khronos glTF-Validator with zero errors, zero warnings and zero infos on those fixtures, in both containers: tests/python/test_gltf.py runs it through tests/python/gltf_validate.mjs (the gltf-validator npm package) when node and the package are present, and the gltf-validator CI job requires it. It also loads in trimesh with the correct Y-up bounds. Loading in three.js and Blender, with the orientation and colours checked by eye, was not automated.

Not supported

Draco or meshopt compression (the reader refuses them by name); textures (UVs are written, from uv); transient results as morph targets (a plausible follow-up); EXT_structural_metadata, the principled carrier of typed fields, if a consumer asks; point and side regions.