docs: def to_image(img, image_type=None, meta_data=None, **kwargs):
      '''
      to_image(array) yields a Nifti1Image of the given array with default meta-data.
      to_image(array, image_type) yields an image object of the given type; image_type may either be
        an image class or a class name (see supported types below).
      to_image((array, meta_data)) uses the given mapping of meta-data to fill in the image's
        meta-data; note that meta_data may simply be an affine transformation matrix.
      to_image((array, affine, meta_data)) uses the given affine specifically (the given affine
        overrides any affine included in the meta_data).
  
      Note that the array may optionally be an image itself, in which case its meta-data is used as a
      starting point for the new meta-data. Any meta-data passed as a tuple overwrites this meta-data,
      and any meta-data passed as an optional argument overwrites this meta-data in turn.
  
      The first optional argument, specifying image_type is as an image type if possible, but if a
      meta-data mapping is passed as the first argument it is used as such; otherwise, the optional
      third argument is named meta_data, and any additional keyword arguments passed to to_image are
      merged into this meta_data object left-to-right (i.e., keyword arguments overwrite the meta_data
      keys).
      '''
      # quick cleanup of args:
      meta_data = pimms.merge({} if meta_data is None else meta_data, kwargs)
      if image_type is None: image_type = 'nifti1'
      # deduce image type
      image_type = to_image_type(image_type)
      # okay, next, parse the image argument itself:
      if is_tuple(img):
          if   len(img) == 1: (img,aff,mdat) = (img[0], None, None)
          elif len(img) == 2: (img,aff,mdat) = (img[0], None, img[1])
          elif len(img) == 3: (img,aff,mdat) = img
          else: raise ValueError('cannot parse more than 3 elements from image tuple')
      else: (aff,mdat) = (None,None)
      # see if the img argument is an image object
      try: (img,aff0,mdat0) = (img.dataobj, img.affine, to_image_meta_data(img))
      except Exception: (aff0,mdat0) = (None, {})
      # check that the affine wasn't given as the meta-data (e.g. (img,aff) instead of (img,mdat))
      if aff is None and mdat is not None:
          try:    (aff, mdat) = (to_affine(mdat, 3), {})
          except Exception: pass
      # parse the meta-data that has been given
      mdat = dict(pimms.merge(mdat0, {} if mdat is None else mdat, meta_data))
      # if there is an explicit affine, we put it into mdat now
      if aff is not None: mdat['affine'] = to_affine(aff, 3)
      if aff0 is not None and 'affine' not in mdat: mdat['affine'] = to_affine(aff0, 3)
      # okay, we create the image now:
      return image_type.create(img, meta_data=mdat)