docs: def to_affine(aff, dims=None):
      '''
      to_affine(None) yields None.
      to_affine(data) yields an affine transformation matrix equivalent to that given in data. Such a
        matrix may be specified either as (matrix, offset_vector), as an (n+1)x(n+1) matrix, or, as an
        n x (n+1) matrix.
      to_affine(data, dims) additionally requires that the dimensionality of the data be dims; meaning
        that the returned matrix will be of size (dims+1) x (dims+1).
      '''
      if aff is None: return None
      if isinstance(aff, _tuple_type):
          # allowed to be (mtx, offset)
          if (len(aff) != 2                       or
              not pimms.is_matrix(aff[0], 'real') or
              not pimms.is_vector(aff[1], 'real')):
              raise ValueError('affine transforms must be matrices or (mtx,offset) tuples')
          mtx = np.asarray(aff[0])
          off = np.asarray(aff[1])
          if dims is not None:
              if mtx.shape[0] != dims or mtx.shape[1] != dims:
                  raise ValueError('%dD affine matrix must be %d x %d' % (dims,dims,dims))
              if off.shape[0] != dims:
                  raise ValueError('%dD affine offset must have length %d' % (dims,dims))
          else:
              dims = off.shape[0]
              if mtx.shape[0] != dims or mtx.shape[1] != dims:
                  raise ValueError('with offset size=%d, matrix must be %d x %d' % (dims,dims,dims))
          aff = np.zeros((dims+1,dims+1), dtype=np.float)
          aff[dims,dims] = 1
          aff[0:dims,0:dims] = mtx
          aff[0:dims,dims] = off
          return pimms.imm_array(aff)
      if not pimms.is_matrix(aff, 'real'):
          raise ValueError('affine transforms must be matrices or (mtx, offset) tuples')
      aff = np.asarray(aff)
      if dims is None:
          dims = aff.shape[1] - 1
      if aff.shape[0] == dims:
          lastrow = np.zeros((1,dims+1))
          lastrow[0,-1] = 1
          aff = np.concatenate((aff, lastrow))
      if aff.shape[1] != dims+1 or aff.shape[0] != dims+1:
          arg = (dims, dims,dims+1, dims+1,dims+1)
          raise ValueError('%dD affine matrix must be %dx%d or %dx%d' % arg)
      return aff