include warning in np.resize() docs

I find it counterintuitive that resizing a numpy array does NOT consider dimensions independent, but simply takes the first N elements of the input array that fit into the output array. I was expecting something more like `cv2.resize()` where axes are treated separately, and some form of interpolation is applied to each dimension.

numpy resizes an old 5x5x2 array into a new array with new = np.resize(old, (4, 4, 2)) by simply copying the first 4 * 4 * 2 entries from old into new. (e.g. old[0, 4, :] becomes new[1, 0, :])
This is a problem if we would like simple interpolation, or if different axes represent different entities. (If the above example is an image, the top right most pixel would get warped all the way to the left, which is most likely not the intention)

In response to my issue #11478: 'resize() is unintuitive by not treating axes separately?'
A warning in the docs might prevent some confusion.

For a discussion on the issue and a possible solution, see <https://github.com/numpy/numpy/issues/11478>

1 files changed, 11 insertions, 1 deletions

diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index 373e0fde8..a87437a47 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -1197,7 +1197,17 @@ def resize(a, new_shape):
     See Also
     --------
     ndarray.resize : resize an array in-place.
-
+    
+    Notes
+    -----
+    Warning: This functionality does **not** consider axes separately,
+    i.e. it does not apply interpolation/extrapolation of some sort.
+    It simply takes the first `np.prod(new_shape)` elements of `a`,
+    disregarding axes, and fills the returned array with these elements.
+    (This is in case the new shape is smaller. For larger, see above.)
+    This functionality is therefor not suitable to resize images,
+    or data where each axis represents a separate and distinct entity.
+    
     Examples
     --------
     >>> a=np.array([[0,1],[2,3]])