docs: def imread(filename, masked = False):
      """Convenience function that uses the QImage_ constructor to read an
      image from the given file and return an `rgb_view` of the result.
      This is intentionally similar to scipy.ndimage.imread (which uses
      PIL), scipy.misc.imread, or matplotlib.pyplot.imread (using PIL
      for non-PNGs).
  
      For grayscale images, return 2D array (even if it comes from a 32-bit
      representation; this is a consequence of the QImage API).
  
      For images with an alpha channel, the resulting number of channels
      will be 2 (grayscale+alpha) or 4 (RGB+alpha).  Alternatively, one may
      pass `masked = True` in order to get `masked arrays`_ back.
      Note that only fully transparent pixels are masked
      (and that masked arrays only support binary masks).  The value of
      `masked` is ignored when the loaded image has no alpha channel
      (i.e., one would not get a masked array in that case).
  
      This function has been added in version 1.3.
  
      """
      qImage = _qt.QImage(filename)
  
      if qImage.isNull():
          raise IOError('loading %r failed' % filename)
  
      isGray = qImage.isGrayscale()
      if isGray and qImage.depth() == 8:
          return byte_view(qImage)[...,0]
  
      hasAlpha = qImage.hasAlphaChannel()
  
      if hasAlpha:
          targetFormat = _qt.QImage.Format_ARGB32
      else:
          targetFormat = _qt.QImage.Format_RGB32
      if qImage.format() != targetFormat:
          qImage = qImage.convertToFormat(targetFormat)
  
      result = rgb_view(qImage)
      if isGray:
          result = result[...,0]
      if hasAlpha:
          if masked:
              mask = (alpha_view(qImage) == 0)
              if _np.ndim(result) == 3:
                  mask = _np.repeat(mask[...,None], 3, axis = 2)
              result = _np.ma.masked_array(result, mask)
          else:
              result = _np.dstack((result, alpha_view(qImage)))
      return result