Supported Geometry File Formats

This page documents the surface file formats accepted by filename in Geometries, by the triangulation refinement-zone specifier and grid_file in Grid Generation, and the restrictions each format carries. The file extension alone selects the reader — there is no override.

Extension	Format	Notes
.vtk	Legacy ASCII VTK PolyData	The most common/recommended format. See restrictions below.
.tri	Cart3D-style ASCII triangulation	Plain-text points/faces/components.
.stl	STL (ASCII or binary, auto-detected)	Widely exported by CAD tools; some caveats around patches.
.fro	Custom ASCII front/component format	Simple explicit connectivity + component tag per face.
.cgns	CGNS	Requires CHAMPS+ built with CGNS support. HDF5 only.

All formats are triangulated on import

Internally, CHAMPS+ only ever represents surfaces as triangles. CGNS is the one format that may contain quads — each quad is silently split into two triangles at import. No other format's reader accepts anything but 3-node faces.

---

Restrictions common to every format

• Coordinates are read at face value. No reader performs unit conversion. If your file isn't already in the unit system used by the rest of your input file, convert it with a scale entry in Transforms — see the Blunt Cone tutorial for an example converting a cone.vtk authored in millimeters to the meters used elsewhere in the case.
• Winding/normal direction is corrected automatically, but only within a connected surface. After import, CHAMPS+ walks each connected group of triangles ("island") and flips winding as needed so triangle normals are consistent and oriented per the geometry's is_external flag. You do not need to pre-orient normals correctly. However, this correction is done per-island — if your surface is split into disconnected pieces that should be topologically connected (e.g. due to duplicate, non-coincident vertices at a seam), each piece is corrected independently and can end up with mismatched orientation across the seam.
• A closed, manifold, single-surface-per-component mesh is the practical requirement, even though most readers won't reject a bad one outright. Every reader computes an internal is_manifold flag from face-edge adjacency, but only the triangulation refinement-zone specifier and the general immersed-boundary machinery actually require manifoldness — a plain Geometries import of a non-manifold or non-watertight surface will not throw at read time, but is likely to produce incorrect interior/exterior classification (is_interior, IBM setup) later, since that logic depends on a well-defined, closed surface. Treat "watertight, 2-manifold, single connected component per geometry" as a hard requirement even where it isn't enforced at import.
• Patches come from per-face integer/name tags baked into the file, and what counts as that tag differs by format (see below). There's no way to assign or rename patches from the input file itself — Patches in Geometries only lets you group existing ids/names from the source file under a new label; the underlying ids must already be correct in the file.

---

Per-format details

.vtk

• Must be a legacy, ASCII VTK file (ASCII, DATASET POLYDATA) — binary-format VTK is not supported and is rejected immediately.
• Every entry in POLYGONS must be a triangle. The reader always consumes exactly 3 vertex indices per polygon regardless of the stated vertex count, so a non-triangular polygon (e.g. a quad) throws off the connectivity for the remainder of the file rather than producing a clear error at that entry.
• CELL_DATA must include an integer SCALARS array named exactly Components with a LOOKUP_TABLE default line, one entry per face. This is where per-face patch ids come from — patch names in Geometries end up as the stringified unique values of this array, sorted ascending and remapped to a contiguous range starting at 0. A file missing this named array will not be read correctly.

.tri

• Plain-text: a header line of num_points num_faces, followed by point coordinates, then one-based triangle connectivity (i0 i1 i2), then a trailing block of one integer component id per face (no other structure or metadata is read).
• Component ids come from that trailing per-face integer block, following the same stringify/sort/remap convention as .vtk's Components array.

.stl

• Both ASCII and binary STL are accepted; the format is auto-detected by sniffing the first bytes of the file for facet/normal.
• A binary file may contain multiple concatenated solids (each with its own 80-byte header and triangle count) back-to-back; each concatenated block becomes a separate patch. The patch name is taken from that block's raw 80-byte header text, which many CAD/meshing tools leave blank or fill with non-human-readable bytes — don't rely on STL patch names being meaningful without checking the file.
• An ASCII file may only contain a single solid ... endsolid block; the patch name is taken from the file's basename (extension stripped), not the solid name in the file.
• STL stores no shared-vertex connectivity — vertices are implicit per-triangle. On import, CHAMPS+ welds coincident vertices using a tolerance derived from the smallest edge length found anywhere in the file (0.1% of it). A file with one very short edge (a sliver triangle, or near-duplicate points from a bad export) tightens this tolerance for the whole file and can leave the mesh insufficiently welded elsewhere — watch for stray/duplicate vertices producing a non-manifold result from a source mesh that looked fine in a viewer.

.fro

• Plain-text, explicit format: a header line of counts, then one-based id x y z node lines, then id n0 n1 n2 comp triangle lines (component id is the trailing column).
• Triangles only — there's no quad or higher-order element support in this format.

.cgns

• Requires CHAMPS+ to have been built with CGNS support; without it, any .cgns filename throws at runtime regardless of the file's validity.
• The file must be CGNS/HDF5, not the older ADF/ADF2 CGNS file types — those are rejected outright.
• The file's CGNS library version must not be newer than the version CHAMPS+ was built against.
• Each zone becomes one patch, named after the zone's CGNS name. Structured zones are read as an implicit quad grid (each quad split into two triangles); unstructured zones are read section-by-section.
• Only TRI_3 and QUAD_4 element sections are supported in unstructured zones. Any other element type in any section — including boundary/edge (e.g. BAR_2) sections that some CGNS exporters attach to a surface zone — aborts the entire import. If a CGNS surface export includes such sections, strip them before importing.