From f1e874f1c022a8387aadfa83f9e4df48e1ac0ed9 Mon Sep 17 00:00:00 2001
From: David Stansby <dstansby@gmail.com>
Date: Sat, 6 Nov 2021 11:21:21 +0000
Subject: [PATCH] Add some more docs for reproject_interp

---
 reproject/interpolation/core.py       |  2 ++
 reproject/interpolation/high_level.py |  4 ++++
 reproject/wcs_utils.py                | 18 ++++++++++++++++--
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/reproject/interpolation/core.py b/reproject/interpolation/core.py
index 8e45cca28..c275eabf1 100644
--- a/reproject/interpolation/core.py
+++ b/reproject/interpolation/core.py
@@ -79,6 +79,7 @@ def _reproject_full(array, wcs_in, wcs_out, shape_out, order=1, array_out=None,
     pixel_out = np.meshgrid(*[np.arange(size, dtype=float) for size in shape_out],
                             indexing='ij', sparse=False, copy=False)
     pixel_out = [p.ravel() for p in pixel_out]
+    # For each pixel in the ouput array, get the pixel value in the input WCS
     pixel_in = efficient_pixel_to_pixel_with_roundtrip(wcs_out, wcs_in, *pixel_out[::-1])[::-1]
     pixel_in = np.array(pixel_in)
 
@@ -87,6 +88,7 @@ def _reproject_full(array, wcs_in, wcs_out, shape_out, order=1, array_out=None,
     else:
         array_out = np.empty(shape_out).ravel()
 
+    # Interpolate array on to the pixels coordinates in pixel_in
     map_coordinates(array, pixel_in, order=order, cval=np.nan,
                     mode='constant', output=array_out,).reshape(shape_out)
 
diff --git a/reproject/interpolation/high_level.py b/reproject/interpolation/high_level.py
index 70f2a833b..4a2336862 100644
--- a/reproject/interpolation/high_level.py
+++ b/reproject/interpolation/high_level.py
@@ -22,6 +22,10 @@ def reproject_interp(input_data, output_projection, shape_out=None, hdu_in=0,
     Reproject data to a new projection using interpolation (this is typically
     the fastest way to reproject an image).
 
+    The output pixel grid is transformed to the input pixel grid, and the
+    data values in ``input_data`` interpolated on to these coordinates to get
+    the reprojected data on the output grid.
+
     Parameters
     ----------
     input_data
diff --git a/reproject/wcs_utils.py b/reproject/wcs_utils.py
index 01ad148e3..fcb6b1834 100644
--- a/reproject/wcs_utils.py
+++ b/reproject/wcs_utils.py
@@ -158,8 +158,22 @@ def split_matrix(matrix):
 
 def efficient_pixel_to_pixel(wcs1, wcs2, *inputs):
     """
-    Wrapper that performs a pixel -> world -> pixel transformation with two
-    WCS instances, and un-broadcasting arrays whenever possible for efficiency.
+    Wrapper that performs a pixel -> world -> pixel transformation and
+    un-broadcasting arrays whenever possible for efficiency.
+
+    Parameters
+    ----------
+    wcs1 : `~astropy.wcs.WCS`
+        First WCS instance.
+    wcs2 : `~astropy.wcs.WCS`
+        Second WCS instance.
+    inputs : list[numpy.ndarray]
+        Pixels in the frame of ``wcs1``.
+
+    Returns
+    -------
+    outputs : list[numpy.ndarray]
+        Transformed pixels in the frame of ``wcs2``.
     """
 
     # Shortcut for scalars