DOC: Clarify point set transform order

ants/registration/apply_transforms.py

@@ -215,38 +215,39 @@ def apply_transforms(fixed, moving, transformlist,
         libfn(processed_args)
 
 
-
-
-
-
 def apply_transforms_to_points( dim, points, transformlist,
                      whichtoinvert=None, verbose=False ):
     """
-     Apply a transform list to map a pointset from one domain to
-     another. In registration, one computes mappings between pairs of
-     domains. These transforms are often a sequence of increasingly
-     complex maps, e.g. from translation, to rigid, to affine to
-     deformation.  The list of such transforms is passed to this
-     function to interpolate one image domain into the next image
-     domain, as below.  The order matters strongly and the user is
-     advised to familiarize with the standards established in examples.
-     Importantly, point mapping goes the opposite direction of image
-     mapping, for both reasons of convention and engineering.
+     Apply a transform list to map a pointset of physical coordinates from one domain
+     to another. When using this function, the transform list will be the opposite
+     of that used to resample images with :func:`ants.apply_transforms`, because image
+     resampling in apply_transforms internally transforms points from the reference or target
+     space to the source or "moving" space.
+
+     If you ran ``tx = ants.registration(fixed, moving,...)``, then ``tx['fwdtransforms']``
+     transforms *points* from the _fixed_ space to the _moving_ space, and ``tx['invtransforms']``
+     (with whichtoinvert set appropriately) transforms points from the _moving_ space to the
+     _fixed_ space.
 
     ANTsR function: `antsApplyTransformsToPoints`
 
     Arguments
     ---------
     dim: integer
-         dimensionality of the transformation.
+         Dimensionality of the transformation.
+
+    points: :class:`pandas.DataFrame`
+        Moving point set with n-points in rows of at least dim
+        columns - we maintain extra information in additional
+        columns. this should be a data frame with columns names x, y, z, t.
 
-    points: data frame
-          moving point set with n-points in rows of at least dim
-          columns - we maintain extra information in additional
-          columns. this should be a data frame with columns names x, y, z, t.
+        The points must be in LPS+ physical coordinates. If your points are in index
+        coordinates, you can use :func:`ants.transform_index_to_physical_point` to convert
+        them before applying transforms.
 
     transformlist : list of strings
-        list of transforms generated by ants.registration where each transform is a filename.
+        List of transforms generated by ants.registration where each transform is a filename.
+        The order of the transforms is important, see the function description.
 
     whichtoinvert : list of booleans (optional)
         Must be same length as transformlist.
@@ -258,19 +259,23 @@ def apply_transforms_to_points( dim, points, transformlist,
         to [False]*len(transformlist)).
 
     verbose : boolean
+        Verbose output.
 
     Returns
     -------
-    data frame of transformed points
+    :class:`pandas.DataFrame`
+            Data frame with the same columns as the input points, but with spatial coordinates
+            transformed according to the transform list.
 
     Example
     -------
     >>> import ants
     >>> fixed = ants.image_read( ants.get_ants_data('r16') )
     >>> moving = ants.image_read( ants.get_ants_data('r27') )
     >>> reg = ants.registration( fixed, moving, 'Affine' )
-    >>> d = {'x': [128, 127], 'y': [101, 111]}
+    >>> d = {'x': [128, 127], 'y': [101, 111]} # point in the fixed space
     >>> pts = pd.DataFrame(data=d)
+    >>> # Warping this point from fixed to moving space with forward transforms
     >>> ptsw = ants.apply_transforms_to_points( 2, pts, reg['fwdtransforms'])
     """