STY: Geometry -> Pointset

nipy · effigies · Sep 17, 2021 · Sep 29, 2021 · Oct 8, 2021 · Oct 8, 2021
commit e6be497ff02a482a68baca5f036fb19c92e124c8
diff --git a/nibabel/surfaceimages.py b/nibabel/surfaceimages.py
@@ -3,13 +3,42 @@
 from nibabel.dataobj_images import DataobjImage
 
 
-class Geometry:
+class Pointset:
+    """ A collection of related sets of coordinates in 3D space.
+
+    Coordinates are in RAS+ orientation, i.e., $(x, y, z)$ refers to
+    a point $x\mathrm{mm}$ right, $y\mathrm{mm}$ anterior and $z\mathrm{mm}$
+    superior of the origin.
+
+    The order of coordinates should be assumed to be significant.
+    """
+
     def get_coords(self, name=None):
-        """ Nx3 array of coordinates in RAS+ space """
+        """ Get coordinate data in RAS+ space
+
+        Parameters
+        ----------
+        name : str
+            Name of one of a family of related coordinates.
+            For example, ``"white"`` and ``"pial"`` surfaces
+
+        Returns
+        -------
+        coords : (N, 3) array-like
+            Coordinates in RAS+ space
+        """
         raise NotImplementedError
 
+    @property
+    def n_coords(self):
+        """ Number of coordinates
+
+        The default implementation loads coordinates. Subclasses may
+        override with more efficient implementations.
+        """
+        return self.get_coords().shape[0]
 
-class SurfaceGeometry(Geometry):
+class SurfaceGeometry(Pointset):
     def __init__(self, meshes=None):
         """ Surface header objects have access to an internal
         ``_meshes`` dictionary that has keys that are mesh names.
@@ -21,15 +50,6 @@ def __init__(self, meshes=None):
         self._meshes = meshes
         super().__init__()
 
-    @property
-    def n_coords(self):
-        """ Number of coordinates (vertices)
-
-        The default implementation loads coordinates. Subclasses may
-        override with more efficient implementations.
-        """
-        return self.get_coords().shape[0]
-
     @property
     def n_triangles(self):
         """ Number of triangles (faces)
@@ -39,10 +59,6 @@ def n_triangles(self):
         """
         return self.get_triangles().shape[0]
 
-    def get_coords(self, name=None):
-        """ Nx3 array of coordinates in RAS+ space """
-        raise NotImplementedError
-
     def get_triangles(self, name=None):
         """ Mx3 array of indices into coordinate table """
         raise NotImplementedError
@@ -101,7 +117,7 @@ def load_geometry(self, pathlike):
         """ Specify a header to a data-only image """
 
 
-class VolumeGeometry(Geometry):
+class VolumeGeometry(Pointset):
     def __init__(self, affines, *, indices=None):
         try:
             self._affines = dict(affines)
@@ -141,7 +157,7 @@ def from_spec(klass, pathlike):
         raise NotImplementedError
 
 
-class GeometrySequence(GeometryCollection, Geometry):
+class GeometrySequence(GeometryCollection, Pointset):
     def __init__(self, structures=()):
         super().__init__(structures)
         self._indices = {}