DOC: First pass at SurfaceImage BIAP

doc/source/devel/biaps/biap_0009.rst

@@ -0,0 +1,159 @@
+.. _biap9:
+
+#############################
+BIAP9 - The Surface Image API
+#############################
+
+:Author: Chris Markiewicz
+:Status: Draft
+:Type: Standards
+:Created: 2021-09-16
+
+**********
+Background
+**********
+
+Surface data is generally kept separate from geometric metadata
+===============================================================
+
+In contrast to volumetric data, whose geometry can be fully encoded in the
+shape of a data array and a 4x4 affine matrix, data sampled to a surface
+requires the location of each sample to be explicitly represented by a
+coordinate. In practice, the most common approach is to have a geometry file
+and a data file.
+
+A geometry file consists of a vertex coordinate array and a triangle array
+describing the adjacency of vertices, while a data file is an n-dimensional
+array with one axis corresponding to vertex.
+
+Keeping these files separate is a pragmatic optimization to avoid costly
+reproductions of geometric data, but presents an administrative burden to
+direct consumers of the data.
+
+Terminology
+===========
+
+For the purposes of this BIAP, the following terms are used:
+
+* Coordinate - a triplet of floating point values in RAS+ space
+* Vertex - an index into a table of coordinates
+* Triangle (or face) - a triplet of adjacent vertices (A-B-C);
+  the normal vector for the face is ($\overline{AB}\times\overline{AC}$)
+* Topology - vertex adjacency data, independent of vertex coordinates,
+  typically in the form of a list of triangles
+* Geometry - topology + a specific set of coordinates for a surface
+* Patch - a connected subset of vertices (can be the full topology)
+* Data array - an n-dimensional array with one axis corresponding to the the
+  vertices (typical) OR faces (more rare) in a patch
+
+
+Currently supported surface formats
+===================================
+
+* FreeSurfer
+   * Geometry (e.g. ``lh.pial``):
+     :py:func:`~nibabel.freesurfer.io.read_geometry` / 
+     :py:func:`~nibabel.freesurfer.io.write_geometry`
+   * Data
+      * Morphometry:
+        :py:func:`~nibabel.freesurfer.io.read_morph_data` /
+        :py:func:`~nibabel.freesurfer.io.write_morph_data`
+      * Labels: :py:func:`~nibabel.freesurfer.io.read_label`
+      * MGH: :py:class:`~nibabel.freesurfer.mghformat.MGHImage`
+* GIFTI: :py:class:`~nibabel.gifti.gifti.GiftiImage`
+   * Every image contains a collection of data arrays, which may be
+     coordinates, topology, or data (further subdivided by type and intent)
+* CIFTI-2: :py:class:`~nibabel.cifti2.cifti2.Cifti2Image`
+   * Pure data array, with image header containing flexible axes
+   * Geometry referred to by an associated ``wb.spec`` file
+     (no current implementation in NiBabel)
+
+
+*********************************
+Desiderata for a SurfaceImage API
+*********************************
+
+The following are provisional guiding principles 
+
+1. A surface image (data array) should carry a reference to geometric metadata
+   that is easily transferred to a new image.
+2. Partial images (data only or geometry only) should be possible. Absence of
+   components should have a well-defined signature, such as a property that is
+   ``None`` or a specific ``Exception`` is raised.
+3. All arrays (coordinates, triangles, data arrays) should be proxied to
+   avoid excess memory consumption
+4. Selecting among coordinates (e.g., gray/white boundary, inflated surface)
+   for a single topology should be possible.
+5. Combining multiple brain structures (canonically, left and right hemispheres)
+   in memory should be easy; serializing to file may be format-specific.
+6. Splitting a data array into independent patches that can be separately
+   operated on and serialized should be possible.
+
+
+Prominent use cases
+===================
+
+* Arithmetic/modeling - per-vertex mathematical operations
+* Smoothing - topology/geometry-respecting smoothing
+* Plotting - paint the data array as a texture on a surface
+* Decimation - subsampling a topology (possibly a subset, possibly with
+  interpolated vertex locations)
+* Resampling to a geometrically-aligned surface
+  * Downsampling by decimating, smoothing, resampling
+  * Inter-subject resampling by using ``?h.sphere.reg``
+* Interpolation of per-vertex and per-face data arrays
+
+These are not necessarily operations that NiBabel must provide, but the
+components needed for each should be readily retrieved.
+
+********
+Proposal
+********
+
+.. code-block:: python
+
+    class SurfaceHeader:
+        @property
+        def ncoords(self):
+            """ Number of coordinates """
+
+        @property
+        def nfaces(self):
+            """ Number of faces """
+
+        def get_coords(self, name=None):
+            """ Nx3 array of coordinates in RAS+ space """
+
+        def get_faces(self, name=None):
+            """ Mx3 array of indices into coordinate table """
+
+        def get_mesh(self, name=None):
+            return self.get_coords(name=name), self.get_faces(name=name)
+
+        def decimate(self, *, ncoords=None, ratio=None):
+            """ Return a SurfaceHeader with a smaller number of vertices that
+            preserves the geometry of the original """
+            # To be overridden when a format provides optimization opportunities
+
+        def load_vertex_data(self):
+            """ Return a SurfaceImage with data corresponding to each vertex """
+
+        def load_face_data(self):
+            """ Return a SurfaceImage with data corresponding to each face """
+
+
+    class SurfaceImage:
+        @property
+        def header(self):
+            """ A SurfaceHeader or None """
+
+        @property
+        def dataobj(self):
+            """ An ndarray or ArrayProxy with one of the following properties:
+            
+            1) self.dataobj.shape[0] == self.header.ncoords
+            2) self.dataobj.shape[0] == self.header.nfaces
+            """
+
+        def load_header(self, pathlike):
+            """ Specify a header to a data-only image """

doc/source/devel/biaps/index.rst

@@ -19,6 +19,7 @@ proposals.
    biap_0006
    biap_0007
    biap_0008
+   biap_0009
 
 .. toctree::
    :hidden: