Tiles a group of NDFs using World Co-ordinate System information
The WCSMOSAIC algorithm proceeds as follows. First, the output NDF is filled with zeros. An associated array of weights (one weight for each output pixel) is created and is also filled with zeros. Each input NDF is then processed in turn. For each pixel in the current input NDF, the corresponding transformed position in the output NDF is found (based on the WCS information in both NDFs). The input pixel value is then divided up between a small group of output pixels centred on this central output position. The method used for choosing the fraction of the input pixel value assigned to each output pixel is determined by the METHOD and PARAMS parameters. Each of the affected output pixel values is then incremented by its allocated fraction of the input pixel value. The corresponding weight values are incremented by the fractions used (that is, if 0.25 of an input pixel is assigned to an output pixel, the weight for the output pixel is incremented by 0.25). Once all pixels in the current input NDF have been rebinned into the output NDF in this way, the algorithm proceeds to rebin the next input NDF in the same way. Once all input NDFs have been processed, output pixels which have a weight less than the value given by Parameter WLIM are set bad. The output NDF may then optionally (see Parameter NORM) be normalised by dividing it by the weights array. This normalisation of the output NDF takes account of any difference in the number of pixels contributing to each output pixel, and also removes artefacts which may be produced by aliasing between the input and output pixel grids. Thus each output pixel value is a weighted mean of the input pixel values from which it receives contributions. This means that the units of the output NDF are the same as the input NDF. In particular, any difference between the input and output pixel sizes is ignored, resulting in the total input data sum being preserved only if the input and output NDFs have equal pixel sizes. However, an option exists to scale the input values before use so that the total data sum in each input NDF is preserved even if the input and output pixel sizes differ (see Parameter CONSERVE).
If the input NDFs contain variances, then these are propagated to the output. Alternatively, output variances can be generated from the spread of input values contributing to each output pixel (see Parameter GENVAR). Any input variances can also be used to weight the input data (see Parameter VARIANCE). By default, all input data are given equal weight. An additional weight for each NDF can be specified using Parameter WEIGHTS.
The transformations needed to produce alignment are derived from the co-ordinate system information stored in the WCS components of the supplied NDFs. For each input NDF, alignment is first attempted in the current co-ordinate Frame of the reference NDF. If this fails, alignment is attempted in the current co-ordinate Frame of the input NDF. If this fails, alignment occurs in the pixel co-ordinate Frame. A message indicating which Frame alignment was achieved in is displayed.
[0.05]
TRUE
, alignment
is performed in the co-ordinate system described by the current Frame of the
WCS FrameSet in the reference NDF. If FALSE
, alignment is performed in the
co-ordinate system specified by the following set of WCS attributes in the reference
NDF: AlignSystem AlignStdOfRest, AlignOffset, AlignSpecOffset, AlignSideBand,
AlignTimeScale. The AST library provides fixed defaults for all these. So for instance,
AlignSystem defaults to ICRS for celestial axes and Wavelength for spectral
axes, meaning that celestial axes will be aligned in ICRS and spectral axes in
wavelength, by default. Similarly, AlignStdOfRest defaults to Heliocentric,
meaning that by default spectral axes will be aligned in the Heliocentric rest
frame.
As an example, if you are mosaicing two spectra which both use radio velocity as the
current WCS, but which have different rest frequencies, then setting ALIGNREF to TRUE
will cause alignment to be performed in radio velocity, meaning that the differences in
rest frequency are ignored. That is, a channel with 10 Km/s in the input is mapping
onto the channel with 10 km/s in the output. If ALIGNREF is FALSE
(and no value has
been set for the AlignSystem attribute in the reference WCS), then alignment will be
performed in wavelength, meaning that the different rest frequencies cause an
additional shift. That is, a channel with 10 Km/s in the input will be mapping onto
which ever output channel has the same wavelength, taking into account the different
rest frequencies.
As another example, consider mosaicing two maps which both have (azimuth,elevation)
axes. If ALIGNREF is TRUE
, then any given (az,el) values in one image will be mapped
onto the exact same (az,el) values in the other image, regardless of whether the two
images were taken at the same time. But if ALIGNREF is FALSE
, then a given (az,el)
value in one image will be mapped onto pixel that has the same ICRS co-ordinates in the
other image (since AlignSystem default to ICRS for celestial axes). Thus any
different in the observation time of the two images will result in an additional
shift.
As yet another example, consider mosaicking two spectra which are both in frequency
with respect to the LSRK, but which refer to different points on the sky. If ALIGNREF
is TRUE
, then a given LSRK frequency in one spectrum will be mapped onto the
exact same LSRK frequency in the other image, regardless of the different sky
positions. But if ALIGNREF is FALSE
, then a given input frequency will first be
converted to Heliocentric frequency (the default value for AlignStdOfRest is
Heliocentric"
), and will be mapped onto the output channel that has the same
Heliocentric frequency. Thus the difference in sky positions will result in an
additional shift. [FALSE]
TRUE
, then
the output pixel values will be scaled in such a way as to preserve the total
data value in a feature on the sky. The scaling factor is the ratio of the
output pixel size to the input pixel size. This option can only be used if the
Mapping is successfully approximated by one or more linear transformations.
Thus an error will be reported if it used when the ACC parameter is set to
zero (which stops the use of linear approximations), or if the Mapping is too
non-linear to be approximated by a piece-wise linear transformation. The ratio of
output to input pixel size is evaluated once for each panel of the piece-wise
linear approximation to the Mapping, and is assumed to be constant for all
output pixels in the panel. This parameter is ignored if the NORM parameter is
set FALSE
. [TRUE]
TRUE
, output variances are
generated based on the spread of input pixel values contributing to each output
pixel. Any input variances then have no effect on the output variances (although
input variances will still be used to weight the input data if the VARIANCE
parameter is set TRUE
). If GENVAR is set FALSE
, the output variances are based on
the variances in the input NDFs, so long as all input NDFs contain variances
(otherwise the output NDF will not contain any variances). If a null (!
) value
is supplied, then a value of FALSE
is adopted if and only if all the input
NDFs have variance components (TRUE
is used otherwise). [FALSE]
An NDF name, optionally containing wild-cards and/or regular expressions
("$\ast $"
,
"?"
, "[a-z]"
etc.).
The name of a text file, preceded by an up-arrow character
"$$
.
Each line in the text file should contain a comma-separated list of elements, each of
which can in turn be an NDF name (with optional wild-cards, etc.), or another file
specification (preceded by an up-arrow). Comments can be included in the file by
commencing lines with a hash character
""#"
.
If the value supplied for this parameter ends with a hyphen, then you are re-prompted for further input until a value is given which does not end with a hyphen. All the NDFs given in this way are concatenated into a single group.
!
) also
results in these same defaults being used. [!]
[1000]
"Bilinear"
–- The input pixel value is divided bi-linearly between the four nearest
output pixels. This produces smoother output NDFs than the nearest-neighbour scheme,
but is marginally slower.
"Nearest"
–- The input pixel value is assigned completely to the single nearest output
pixel.
"Sinc"
–- Uses the $\mathrm{\text{sinc}}\left(\pi x\right)$
kernel, where $x$
is the pixel offset from the transformed input pixel centre, and
$\mathrm{\text{sinc}}\left(z\right)=sin\left(z\right)/z$. Use
of this scheme is not recommended.
"SincSinc"
–- Uses the $\mathrm{\text{sinc}}\left(\pi x\right)\mathrm{\text{sinc}}\left(k\pi x\right)$
kernel. This is a valuable general-purpose scheme, intermediate in its visual effect on
NDFs between the bilinear and nearest-neighbour schemes.
"SincCos"
–- Uses the $\mathrm{\text{sinc}}\left(\pi x\right)cos\left(k\pi x\right)$
kernel. It gives similar results to the "Sincsinc"
scheme.
"SincGauss"
–- Uses the $\mathrm{\text{sinc}}\left(\pi x\right){e}^{-k{x}^{2}}$
kernel. Good results can be obtained by matching the FWHM of the envelope function to
the point-spread function of the input data (see Parameter PARAMS).
"Somb"
–- Uses the $\mathrm{\text{somb}}\left(\pi x\right)$
kernel, where $\mathrm{\text{somb}}\left(z\right)=2\ast {J}_{1}\left(z\right)/z$.
${J}_{1}$ is
the first-order Bessel function of the first kind. This scheme is similar to the "Sinc"
scheme.
"SombCos"
–- Uses the $\mathrm{\text{somb}}\left(\pi x\right)cos\left(k\pi x\right)$
kernel. This scheme is similar to the "SincCos"
scheme.
"Gauss"
–- Uses the ${e}^{-k{x}^{2}}$
kernel. The FWHM of the Gaussian is given by Parameter PARAMS(2), and the point at
which to truncate the Gaussian to zero is given by Parameter PARAMS(1).
All methods propagate variances from input to output, but the variance estimates
produced by schemes other than nearest neighbour need to be treated with care since the
spatial smoothing produced by these methods introduces correlations in the variance
estimates. Also, the degree of smoothing produced varies across the NDF. This is
because a sample taken at a pixel centre will have no contributions from the
neighbouring pixels, whereas a sample taken at the corner of a pixel will have equal
contributions from all four neighbouring pixels, resulting in greater smoothing and
lower noise. This effect can produce complex Moiré patterns in the output variance
estimates, resulting from the interference of the spatial frequencies in the sample
positions and in the pixel-centre positions. For these reasons, if you want
to use the output variances, you are generally safer using nearest-neighbour
interpolation. The initial default is "SincSinc"
. [
current value]
TRUE
(the default), then
each output value is normalised by dividing it by the number of contributing
input pixels, resulting in each output value being the weighted mean of the
contibuting input values. However, if NORM is set FALSE, this normalisation is not
applied. See also Parameter CONSERVE. Setting NORM to FALSE
and VARIANCE to TRUE
results in an error being reported. [TRUE]
!
) value is supplied, WCSMOSAIC will terminate early without
creating an output cube, but without reporting an error. Note, the pixel bounds
which the output cube would have had will still be written to output Parameters
LBOUND and UBOUND, even if a null value is supplied for OUT. PARAMS(1) is required by all the above schemes. It is used to specify how many output
pixels on either side of the central output pixel are to receive contribution from the
corresponding input pixel. Typically, a value of 2
is appropriate and the minimum
allowed value is 1
(i.e. one pixel on each side). A value of zero or fewer
indicates that a suitable number of pixels should be calculated automatically.
[0]
PARAMS(2) is required only by the Gauss, SombCos, SincSinc, SincCos, and SincGauss
schemes. For the SombCos, SincSinc and SincCos schemes, it specifies the number of
output pixels at which the envelope of the function goes to zero. The minimum value is
1.0
, and the run-time default value is 2.0
. For the Gauss and SincGauss schemes, it
specifies the full-width at half-maximum (FWHM) of the Gaussian envelope measured in
output pixels. The minimum value is 0.1
, and the run-time default is 1.0
. []
[!]
!
) also results in these same defaults being used. [!]
TRUE
, then any input VARIANCE components in the input
NDFs are used to weight the input data (the weight used for each data value
is the reciprocal of the variance). If FALSE
, all input data is given equal
weight. Note, some applications (such as CCDPACK:MAKEMOS) use a parameter named
USEVAR to determine both whether input variances are used to weights input data
values, and also how to calculate output variances. However, WCSMOSAIC uses the
VARIANCE parameter only for the first of these purposes (determining whether to
weight the input data). The second purpose (determining how to create output
variances) is fulfilled by the GENVAR parameter. [FALSE]
TRUE
, the weight assigned to
each input pixel is the value supplied in this group correspoinding to the
appropriate input NDF, divided by the variance of the pixel value. An error
is reported if the number of supplied weights does not equal the number of
supplied input NDFs. [!]
1.0E-10
is used. [1.0E-10]
"m51"
in the current directory so that they are aligned with the first input
NDF, and combines them all into a single output NDF called mosaic. The output NDF is
just big enough to contain all the pixels in all the input NDFs. WCS information (including the current co-ordinate Frame) is propagated from the reference NDF to the output NDF.
QUALITY is not propagated from input to output.
There are different facts reported, their verbosity depending on the current
message-reporting level set by environment variable MSG_FILTER. If this is set to
QUIET
, no information will be displayed while the command is executing. When the
filtering level is at least as verbose as NORMAL
, the interpolation method being used
will be displayed. If set to VERBOSE
, the name of each input NDF will also be displayed
as it is processed.
This routine correctly processes the DATA, VARIANCE, LABEL, TITLE, UNITS, WCS, and HISTORY components of the input NDFs (see the METHOD parameter for notes on the interpretation of output variances).
Processing of bad pixels and automatic quality masking are supported.
All non-complex numeric data types can be handled, but the data type will be converted to one of _INTEGER, _DOUBLE or _REAL for processing.