%N xyzread %F $MIR/src/subs/xyzio.c
%D Read arbitrary subcube
%P bpw
%: image-i/o
%B
      subroutine xyzread( tno, coords, data, mask, ndata )
      integer    tno
      integer    coords(*)
      real       data(*)
      logical    mask(*)
      integer    ndata

This routine, xyzsetup and xyzs2c work together to allow reading an
arbitrary subcube in a n-dimensional datacube. xyzread reads a subcube
from the datacube, as defined by xyzsetup at coordinates calculated by
xyzs2c.

The array coords gives the coordinates of the axes complementary to the
subcube axes. E.g., if 'subcube' in the call to xyzsetup was 'y' and
the datacube is 3-dimensional, coords(1) and coords(2) give the 'x' and
'z' coordinate of the requested line profile, respectively. Or, if
'subcube' was 'xz', coords(1) gives the 'y'-coordinate of the plane.
For a datacube of dimension 'd', only the first 'd - dimsub' elements
of the array coords will be used (where 'dimsub' is the dimension of
the subcube).

The array data (of dimension ndata) will hold the requested information.
If the subcube was 0-dimensional, the result is the pixel value. For a
1-d subcube the profile is returned in data. The number of returned
elements is vircubesize(1), as returned by xyzsetup. For a 2-d subcube
the array data gives the requested plane, as a 1-d array of length
vircubesize(2). Etc.

The mask array indicates if pixels in the data array were undefined
(a TRUE value means the pixel is OK). Element 1 corresponds to data(1),
etc.
(this is not yet implemented, so all elements are returned as TRUE).

N.B.: to scan a datacube pixel by pixel it is more efficient to use
subroutine xyzpixrd instead of xyzread, as the conversion from offset to
coordinates to offset that xyzs2c and xyzread do then is superfluous and
time-consuming.

    Input:
      tno           image file handle
      coords        array of which the first (dim cube)-(dim subcube)
                     elements are used, giving the coordinate values
                     along the complementary axes
    Output:
      data          array containing data read in
      mask          FALSE values indicate undefined pixels
      ndata         number of elements read                                   
