Clarify the role of out_mask and out_alpha in _make_image.

anntzer · anntzer · commit af2fb9c4fce6 · 2024-04-24T13:09:50.000+02:00
The previous comment (initially from 12c27f3) slowly got out of sync with the implementation (e.g. "Agg updates out_alpha in place" doesn't make sense in the local context anymore); rewrite it.
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -518,19 +518,17 @@ def _make_image(self, A, in_bbox, out_bbox, clip_bbox, magnification=1.0,
                 if isinstance(self.norm, mcolors.NoNorm):
                     A_resampled = A_resampled.astype(A.dtype)
 
+                # Compute out_mask (what screen pixels include "bad" data
+                # pixels) and out_alpha (to what extent screen pixels are
+                # covered by data pixels: 0 outside the data extent, 1 inside
+                # (even for bad data), and intermediate values at the edges).
                 mask = (np.where(A.mask, np.float32(np.nan), np.float32(1))
                         if A.mask.shape == A.shape  # nontrivial mask
                         else np.ones_like(A, np.float32))
                 # we always have to interpolate the mask to account for
                 # non-affine transformations
                 out_alpha = _resample(self, mask, out_shape, t, resample=True)
                 del mask  # Make sure we don't use mask anymore!
-                # Agg updates out_alpha in place.  If the pixel has no image
-                # data it will not be updated (and still be 0 as we initialized
-                # it), if input data that would go into that output pixel than
-                # it will be `nan`, if all the input data for a pixel is good
-                # it will be 1, and if there is _some_ good data in that output
-                # pixel it will be between [0, 1] (such as a rotated image).
                 out_mask = np.isnan(out_alpha)
                 out_alpha[out_mask] = 1
                 # Apply the pixel-by-pixel alpha values if present
