#1251 Added Pointset and Grid. #1090 also proposes TriangularMesh, but with the refactoring seen in #1251, that seemed like a bit of extra work for minimal benefit to the transformations use-case. This PR re-adds triangular meshes.

Overall, the approach of multiple names feels clunky and pushes the concerns of surface families into pointsets. #1251 removed that, and this PR extends this by keeping TriangularMesh focused on the base data structure and moves TriangularMeshFamily logic into a CoordinateFamilyMixin class that permits swapping out coordinates with a .with_name() method (open to bikeshedding). Hence, we would change:

left_surfaces.get_coords(name='pial')

to:

left_surfaces.with_name('pial').get_coords()

It also follows the lead of Grid and gets rid of the omni-__init__ in favor of targeted factory classmethods.

Notes from previous discussion:

• @oesteban wrote: "As a note, if some time we support other meshes with more than three edges, then n_triangles should be better named n_faces."
  • This was part of early discussions of BIAP9. IIRC the universality of triangular meshes makes them worth special-casing for now. FreeSurfer has old formats that use non-triangular meshes, and both FreeSurfer and we convert them to triangular on load:

    nibabel/nibabel/freesurfer/io.py

    Lines 145 to 168 in 590b226

    if magic in (QUAD_MAGIC, NEW_QUAD_MAGIC): # Quad file

    nvert = _fread3(fobj)

    nquad = _fread3(fobj)

    (fmt, div) = ('>i2', 100.0) if magic == QUAD_MAGIC else ('>f4', 1.0)

    coords = np.fromfile(fobj, fmt, nvert * 3).astype(np.float64) / div

    coords = coords.reshape(-1, 3)

    quads = _fread3_many(fobj, nquad * 4)

    quads = quads.reshape(nquad, 4)

    #

    # Face splitting follows

    #

    faces = np.zeros((2 * nquad, 3), dtype=int)

    nface = 0

    for quad in quads:

    if (quad[0] % 2) == 0:

    faces[nface] = quad[0], quad[1], quad[3]

    nface += 1

    faces[nface] = quad[2], quad[3], quad[1]

    nface += 1

    else:

    faces[nface] = quad[0], quad[1], quad[2]

    nface += 1

    faces[nface] = quad[0], quad[2], quad[3]

    nface += 1