Repository: scipy/scipy

Issue:
DOC: clarify that `prewitt` filter does not return the magnitude by default
### Issue with current documentation:

Like the `sobel` filter (#18444), `prewitt` by default computes a one dimensional transform. We should show how to compute the magnitude as that is typically the more useful image (cf. #18444).

![image](https://github.com/scipy/scipy/assets/40656107/de0ec92b-6e92-4697-a87d-b47c02c5de15)


```python

from scipy import ndimage, datasets
import matplotlib.pyplot as plt
from skimage import filters

def prewitt_2d(image):
    image = image.astype('int32')
    dx = ndimage.prewitt(image, 0)  # horizontal derivative
    dy = ndimage.prewitt(image, 1)  # vertical derivative
    mag = np.hypot(dx, dy)  # magnitude
    mag *= 255.0 / np.max(mag)
    return mag

fig = plt.figure(figsize=(12, 3))
plt.gray()  # show the filtered result in grayscale
ax1 = fig.add_subplot(141)
ax2 = fig.add_subplot(142)
ax3 = fig.add_subplot(143)
ax4 = fig.add_subplot(144)


ascent = datasets.ascent()
ax1.imshow(ascent)
ax2.imshow(ndimage.prewitt(ascent))
ax2.set_title("scipy prewitt default (1D)")
ax3.imshow(filters.prewitt(ascent))
ax3.set_title("skimage prewitt default")
ax4.imshow(prewitt_2d(ascent))
ax4.set_title("scipy prewitt 2D magnitude")
for ax in [ax1, ax2, ax3, ax4]:
    ax.set_axis_off()
plt.show()

```


Discussion:
Hi, can you emphasize what has to be done, the description seems to be a bit vague. Thankyou!
The root issue is that `scipy.ndimage.prewitt ` by default computes a one dimensional Prewitt filter. This is not the "typical" use case in image processing. For example, skimage implements the magnitude instead (see images above).

In https://github.com/scipy/scipy/pull/18444, the same issue was fixed for the sobel filter. The documentation/examples should emphasize how to get the "typical" Prewitt filter from the function.

What needs to be done is a documentation PR. The Sobel filter PR can serve as an example. For general SciPy development, I recommend having a look at the [quickstart](https://docs.scipy.org/doc/scipy/dev/dev_quickstart.html) and [documentation](https://docs.scipy.org/doc/scipy/dev/contributor/rendering_documentation.html) related parts of the developer docs.



Resolving patch:
diff --git a/scipy/ndimage/_filters.py b/scipy/ndimage/_filters.py
--- a/scipy/ndimage/_filters.py
+++ b/scipy/ndimage/_filters.py
@@ -396,19 +396,39 @@ def prewitt(input, axis=-1, output=None, mode="reflect", cval=0.0):
     %(mode_multiple)s
     %(cval)s
 
+    Notes
+    -----
+    This function computes the one-dimensional Prewitt filter.
+    Horizontal edges are emphasised with the horizontal transform (axis=0),
+    vertical edges with the vertical transform (axis=1), and so on for higher
+    dimensions. These can be combined to give the magnitude.
+
+    See Also
+    --------
+    sobel: Sobel filter
+
     Examples
     --------
     >>> from scipy import ndimage, datasets
     >>> import matplotlib.pyplot as plt
-    >>> fig = plt.figure()
-    >>> plt.gray()  # show the filtered result in grayscale
-    >>> ax1 = fig.add_subplot(121)  # left side
-    >>> ax2 = fig.add_subplot(122)  # right side
+    >>> import numpy as np
     >>> ascent = datasets.ascent()
-    >>> result = ndimage.prewitt(ascent)
-    >>> ax1.imshow(ascent)
-    >>> ax2.imshow(result)
+    >>> prewitt_h = ndimage.prewitt(ascent, axis=0)
+    >>> prewitt_v = ndimage.prewitt(ascent, axis=1)
+    >>> magnitude = np.sqrt(prewitt_h ** 2 + prewitt_v ** 2)
+    >>> magnitude *= 255 / np.max(magnitude) # Normalization
+    >>> fig, axes = plt.subplots(2, 2, figsize = (8, 8))
+    >>> plt.gray()
+    >>> axes[0, 0].imshow(ascent)
+    >>> axes[0, 1].imshow(prewitt_h)
+    >>> axes[1, 0].imshow(prewitt_v)
+    >>> axes[1, 1].imshow(magnitude)
+    >>> titles = ["original", "horizontal", "vertical", "magnitude"]
+    >>> for i, ax in enumerate(axes.ravel()):
+    ...     ax.set_title(titles[i])
+    ...     ax.axis("off")
     >>> plt.show()
+
     """
     input = numpy.asarray(input)
     axis = normalize_axis_index(axis, input.ndim)
@@ -436,7 +456,7 @@ def sobel(input, axis=-1, output=None, mode="reflect", cval=0.0):
     Notes
     -----
     This function computes the axis-specific Sobel gradient.
-    The horizontal edges can emphasised with the horizontal trasform (axis=0),
+    The horizontal edges can be emphasised with the horizontal trasform (axis=0),
     the vertical edges with the vertical transform (axis=1) and so on for higher
     dimensions. These can be combined to give the magnitude.
 


Test patch: