#
# stub function definition file for docstring parsing
#
[docs]def imregrid(imagename, template='get', output='', asvelocity=True, axes=[-1], shape=[-1], interpolation='linear', decimate=10, replicate=False, overwrite=False):
r"""
regrid an image onto a template image
[`Description`_] [`Examples`_] [`Development`_] [`Details`_]
Parameters
- imagename_ (path) - Name of the source image
- template_ (variant='get') - A dictionary, refcode, or name of an image that provides the output shape and coordinate system
.. raw:: html
<details><summary><i> template != get </i></summary>
- shape_ (intVec=[-1]) - Shape of the output image. Only used if template is an image. If not specified (-1), the output image shape will be the same as the template image shape along the axes that are regridded and the same as input image shape along the axes which are not regridded.
.. raw:: html
</details>
- output_ (string='') - Name for the regridded image
- asvelocity_ (bool=True) - Regrid spectral axis in velocity space rather than frequency space?
- axes_ (intVec=[-1]) - The pixel axes to regrid. -1 => all.
- interpolation_ (string='linear') - The interpolation method. One of "nearest", "linear", "cubic".
- decimate_ (int=10) - Decimation factor for coordinate grid computation
- replicate_ (bool=False) - Replicate image rather than regrid?
- overwrite_ (bool=False) - Overwrite (unprompted) pre-existing output file?
.. _Description:
Description
.. warning:: There are `Known Issues <../../notebooks/introduction.html#Known-Issues>`__ for imregrid.
This task will regrid an input image onto a new coordinate system
from a template image or to a new directional and spectral
reference frame. If a template image is used, then the input and
template images must have the same coordinate structure. The
**imregrid** task currently finds the nearest input pixel center
and interpolates to the output pixel center.
.. warning:: No averaging is done in any direction!
.. warning:: PV images are not supported. Please first regrid as
desired the image from which the PV image was generated, and
then create the PV image from that regridded image.
The new coordinate system is defined by the *template* parameter,
which can be:
- a recognized directional reference frame string. Supported
case-insensitive values are 'J2000', 'JMEAN', 'JTRUE', 'APP',
'B1950', 'B1950_VLA', 'BMEAN', 'BTRUE', 'GALACTIC', 'HADEC',
'AZEL', 'AZELSW', 'AZELNE', 'AZELGEO', 'AZELSWGEO', 'AZELNEGEO',
'JNAT', 'ECLIPTIC', 'MECLIPTIC', 'TECLIPTIC', 'SUPERGAL', 'ITRF',
'TOPO', and 'ICRS'. Note that the conversion between one frame
and another in general becomes less accurate as distance from
the output image's reference pixel increases. After the image
is regridded, any masked slices remaining along the edges of
the image in the directional coordinate are cropped, so that
there are no masked slices in the directional coordinate along
the edges of the final image. Note that some direction
coordinate projections, such as SFL often found in GBT images,
have constraints which do not allow for simple regridding of
the direction coordinate. The application will throw an
exception in these cases.
- a {'csys':[valid coordinate system dictionary], 'shap':[int
array describing the output shape]} dictionary. This is
normally obtained by first running regrid with
*template='get'*. In this case **imregrid** returns the
necessary dictionary.
- 'get', which does not regrid but returns the template
dictionary for *imagename*, suitable for modification and reuse
(see the point immediately above), or
- the name of an image from which to get the coordinate system
and shape. The input and template images must have the same
coordinate structure.
Regridding of complex-valued images is supported. The real and
imaginary parts are regridded independently and the resulting
regridded pixel values are combined to form the regridded,
complex-valued image.
The *replicate* parameter can be used to simply replicate pixels
rather than regridding them. Normally, *replicate=False*, for
every output pixel, its world coordinate is computed and the
corresponding input pixel found (then a little interpolation grid
is generated). If you set *replicate=True*, then what happens is
that for every output axis, a vector of regularly sampled input
pixels is generated (based on the ratio of the output and input
axis shapes). So this just means the pixels get replicated (by
whatever interpolation scheme you use) rather than regridded in
world coordinate space. This process is much faster, but its not a
true world coordinate-based regrid.
As decribed above, when *replicate* is False, a coordinate is
computed for each output pixel; this is an expensive operation.
The *decimate* parameter allows you to decimate the computation of
that coordinate grid to a sparse grid, which is then filled in via
fast interpolation. The default for *decimate* is 10. The number
of pixels per axis in the sparse grid is the number of output
pixels for that axis divided by the decimation factor. A factor of
10 does pretty well. You may find that for very non-linear
coordinate systems (e.g. very close to the pole) that you have to
reduce the decimation factor. You may also have to reduce the
decimation factor if the number of pixels in the output image
along an axis to be regridded is less than about 50, or the output
image may be completely masked.
If one of the axes to be regridded is a spectral axis and
*asvelocity=True*, the axis will be regridded to match the
velocity, not the frequency, coordinate of the template coordinate
system. Thus the output pixel values will correspond only to the
velocity, not the frequency, of the output axis.
A variety of `standard interpolation
schemes <https://en.wikipedia.org/wiki/Interpolation>`__ are
provided (only the first three characters to be specified). The
'cubic' interpolation is substantially slower than 'linear', and
often the improvement is modest. By default 'linear' interpolation
is used.
If an image has per-plane beams and one attempts to regrid the
spectral axis, an exception is thrown. One should consider
convolving all planes to the same resolution in such cases and
then regridding.
.. rubric:: Rules Used for Generating Output Images in Specific Cases
There are numerous rules governing the shape and coordinate system
of the output image depending on the input image, template image,
and wheher default values of the axes and shape parameters are
used. They are enumerated below.
.. note:: **NOTE**: If you want to be certain of what type of output you
will get, it is highly recommended you specify both axes and
shape to avoid any ambiguity.
.. rubric:: *1. Rules governing Stokes axes*
1.1. If the input image has no stokes axis, then the output
image will have no stokes axis.
1.2. If the input image has a stokes axis, but the template
image/coordinate system does not, and if the default value of the
*shape* parameter is used or if *shape* is specified and the
specified value for the length stokes axis in equal to the length
of the input image stokes axis, then all stokes in the input image
will be present in the output image.
1.3. If the input image has a stokes axis, but the template
image/coordinate system does not, and if the value of the *shape*
parameter is specified but the length of the resulting stokes axis
is not equal to the length of the input image's stokes axis, a
failure will occur.
1.4. If the input image has a stokes axis, if the *template*
parameter is an image name, and if the template image has a
degenerate stokes axis, if the *axes* parameter is not specified
or is specified but does not contain the input stokes axis number,
and if the *shape* parameter is not specified, then all stokes
planes in the input image will be present in the output image.
1.5. If the input image has a stokes axis, if the *template*
parameter is an image name, and if the template image has a
degenerate stokes axis, if the *axes* parameter is not specified
or is specified but does not contain the input stokes axis number,
if the *shape* parameter is specified, and if the specified length
of the stokes axis is not equal to the length of the input stokes
axis, then a failure will occur.
1.6. If the input image has a stokes axis, if the *template*
parameter is an image name, if the template image has a degenerate
stokes axis, if the *axes* parameter is specified contains the
input stokes axis number, then use the applicable rule of rules
1.7. and 1.8. for the template image having a nondegenerate stokes
axis.
1.7. If the input image has a stokes axis, if the *template*
parameter is an image name, if the template image has a
nondegenerate stokes axis, and if *axes* parameter is not
specified or if it is, it contains the input stokes axis number,
then only the stokes parameters common to both the input image and
the template image will be present in the output image. If the
input image and the template image have no common stokes
parameters, failure will occur. If shape is specified and the
length of the specified stokes axis is not equal to the number of
common stokes parameters in the input image and the template
image, then failure will result.
1.8. If the input image has a stokes axis, if the *template*
parameter is an image name, if the template image has a
nondegenerate stokes axis, and if *axes* parameter is specified
but does not contain the input image stokes axis number, then all
stokes present in the input image will be present in the output
image. If the *shape* parameter is also specified but the length
of the specified stokes axis does not equal the length of the
input stokes axis, then failure will result.
.. rubric:: *2. Rules governing spectral axes*
In all cases, if the shape *parameter* is specified, the spectral
axis length must be consistent with what one would normally expect
in the special cases, or a failure will result.
2.1. If the input image does not have a spectral axis, then
the output image will not have a spectral axis.
2.2. If the input image has a degenerate spectral axis, if the
*template* parameter is an image name, and if the template image
has a spectral axis, if the *axes* parameter is not specified or
if it is and does not contain the input image spectral axis
number, then the spectral coordinate of the input image is copied
to the output image and the output image will have a degenerate
spectral axis.
2.3. If the input image has a degenerate spectral axis, if the
*template* parameter is an image name, and if the template image
has a spectral axis, if the *axes* parameter is specified and it
contains the input image spectral axis number, then the spectral
coordinate of the template image is copied to the output image. If
the *shape* parameter is not specified, the output image will have
the same number of channels as the input image. If the *shape*
parameter is specified, the output image will have the number of
channels as specified in shape for the spectral axis. In these
cases, the pixel and mask values for all spectral hyperplanes will
be identical; the regridded single spectral plane is simply
replicated n times, where n is the number of channels in the
output image.
2.4. If the input image has a spectral axis, if the *template*
parameter is an image name, and if the template image does not
have a spectral axis, if the *axes* parameter is not specified or
if it is and does not contain the input image spectral axis
number, then the spectral coordinate of the input image is copied
to the output image and the output image will have the same number
of channels as the input image.
2.5. If the input image has a spectral axis, if the *template*
parameter is an image name, if the template image does not have a
spectral axis, if the *axes* parameter is specified and it
contains the input image spectral axis number, then failure will
result.
2.6. If the input image has a spectral axis, if the *template*
parameter is an image name, if the template image has a degenerate
spectral axis, and if the *axes* parameter is unspecified or if it
is but does not contain the spectral axis number of the input
image, the spectral coordinate of the input image is copied to the
output image and the output image will have the same number of
channels as the input image.
2.7. If the input image has a spectral axis, if the *template*
parameter is an image name, if the template image has a
nondegenerate spectral axis, and if the *axes* parameter is
unspecified or if it is and contains the spectral axis number of
the input image, regrid the spectral axis of the input to match
the spectral axis of the template.
.. rubric:: Important Note About Flux Conservation
In general, regridding is inaccurate for images in which the
angular resolution is poorly sampled.
The issue is that CASA treats the values in "pixels" as
measurements of a sky brightness distribution, each at an
infinitessimally small single point at the location of the "pixel"
center (to enable the Fourier transforms and gridding that CASA
deals with regularly). If one has well-sampled the (beam-smoothed)
sky brightness distribution, then one can resample that
distribution to a different set of locations, and everything will
come out correctly. If one has not sampled the distribution well,
then interpolation to other locations will introduce significant
errors. Imagine a worst case of a (well-sampled) peak being
resampled to large "pixel" locations, such that the centers of
two output pixels fall on either side of the peak. The
interpolated values at those locations will effectively cause the
peak to completely disappear.
This is in contrast to software that considers the value in a
"pixel" to be the sum of the sky brightness subtended by that
finite-sized pixel. In such software, resampling to other pixels
requires calculating the overlap of the old and new finite-sized
pixels, and apportioning the summed flux among output pixels
accordingly. Such an operation is designed to conserve the total
flux in the image even if the beam is not well-sampled and is
common in most optical and infrared imaging and display software.
Again considering the pathological example of a peak being sampled
onto a large-pixel grid, explicitly flux-conserving software would
add up the values from all of the small input pixels, and thus
although the peak would be coarsely represented in the output
image, the flux from that peak would not disappear.
In CASA, the different definition of what a "pixel" is requires
that one have a well-sampled beam, or one will inherently not get
the right answer. A check is done for such cases and a warning
message is printed if a beam is present. However, no such check is
done if there is no beam present. To add a restoring beam to an
image, use **ia.setrestoringbeam**.
.. rubric:: Task-specific Parameter Summary
*template*
Indicates how the template coordinate system is being specified.
See above for details.
*shape*
Shape of the output image. Only used if template is an image. If
not specified (-1), the output image shape will be the same as the
template image shape along the axes that are regridded and the
same as input image shape along the axes which are not regridded.
*asvelocity*
Regrid spectral axis in velocity space rather than frequency
space?
*axes*
The pixel axes to regrid. -1 => all.
*interpolation*
The interpolation method. One of "nearest", "linear", "cubic".
*decimate*
Decimation factor for coordinate grid computation. A value of 10
is sufficient in most cases, except for images in which the length
of at least one axis to be regridded is less than about 70 or if
the input or output direction coordinate is close to a pole. In
these cases, a smaller factor will give signficantly better
accuracy.
*replicate*
Replicate image rather than regrid?
.. _Examples:
Examples
**Basic Examples**
::
# Regrid an image to the "B1950" or "GALACTIC" coordinate systems
imregrid(imagename="input.image", output="output.image", template="B1950")
imregrid(imagename="input.image", output="output.image", template="GALACTIC")
.. note:: When regridding to another coordinate system in the
manner above, if the input image's direction coordinate is
already in the frame specified by template, a straight copy of
the image is made. No regridding is actually done.
::
# Obtain a template dictionary from an image and then use it to regrid another image
temp_dict = imregrid(imagename="target.image", template="get")
imregrid(imagename="input.image", output="output.image", template=temp_dict)
In this example, the *template="get"* option is used in the first
command in order to characterize the desired shape and coordinate
system used, and a new dictionary, TEMP_DICT, is generated
accordingly. This is then used when performing the actual
regridding of input.image in the second command.
**More Advanced Examples**
It is also possible to directly use a template image for
regridding with **imregrid**. For this to work reliably and
predictably, the dimensionality (i.e. which dimensions are present
in an image) and the axis ordering of the input image must be the
same. The type and ordering of the axes of both the input and
template images can (and should) first be examined using the CASA
**imhead** task. Any necessary reordering of axes can be performed
using the CASA **imtrans** task. Unless the user explicitly
specifies which dimensions to regrid using the *axes* parameter
(see the following example), **imregrid** will also attempt to
regrid degenerate axes (i.e. image axes of length one pixel).
Stokes axes are never regridded. In the case where template is an
image name and the default value of shape is specified, the output
image's shape will be the same as the template image's shape along
the axes which are regridded and the same as the input image's
shape along the axes which are not regridded. So for example, if
the input image has a *shape* of [20, 30, 40] and the template
image has a *shape* of [10, 40, 70] and only *axes=[0, 1]*, the
output image will have a *shape* of [10, 40, 40]. If *axes=[2]*,
the output image will have a *shape* of [20, 30, 70].
::
# Regrid input.image by directly using target.image as a template
imregrid(imagename="input.image", output="output.image", template="target.image", shape=[500,500,40,1])
In this example, it is assumed that the axis order of the input
image is of the form (direction_x, direction_y, spectral, Stokes),
where 'direction_x' and 'direction_y' are the directional
coordinates on the sky (in some reference frame), 'spectral' is a
velocity/frequency axis, and 'Stokes' contains polarization
information. In this example, input.image might typically be a
data cube of shape [100, 100, 40, 1]. Note that the default value
of *asvelocity* (True) will be used so that the spectral axis will
be regridded to the same velocity system as that of the template
image.
::
# Regrid only the first two axes of an image
imregrid(imagename="input.image", output="output.image", template="target.image", axes=[0,1])
In this example, the user should inspect the type and ordering of
the axes with **imhead**, and then correct with **imtrans** if
necessary. The above command will regrid only the first two axes
(normally the directional axes) of input.image and leave all other
axes unchanged. The output image will have the shape of the
template image along the regridded axes [0, 1] and the shape of
the input image along the other axes since the shape parameter was
not explicitly specified.
::
# Regrid the third axis, considering velocity rather than frequency units
imregrid(imagename="input.image", output="output.image", template="target.image", axes=[2], asvelocity=True)
This example regrids the spectral axis (zero-based axis number 2)
with respect to velocity because the *asvelocity* parameter has
been set to True. This is useful when e.g., regridding a cube
containing one spectral line to match the velocity coordinate of
another cube containing a different spectral line.
::
# Regrid the third axis, considering velocity rather than frequency units but first set the rest frequency
imhead("input.image", mode="put", hdkey="restfreq", hdvalue="110GHz")
imregrid(imagename="input.image", output="output.image", template="target.image", axes=[2], asvelocity=True)
The first command in this example uses the **imhead** task to set
the value of the image rest frequency to a value of 110GHz in
input.image. The following **imregrid** command then performs a
frequency units regridding only of the third axis listed
(zero-based axis) (2), taking account of the input.image rest
frequency in the input file.
.. _Development:
Development
No additional development details
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _imagename:
| ``imagename (path)`` - Name of the source image
.. _template:
| ``template (variant='get')`` - A dictionary, refcode, or name of an image that provides the output shape and coordinate system
.. _output:
| ``output (string='')`` - Name for the regridded image
.. _asvelocity:
| ``asvelocity (bool=True)`` - Regrid spectral axis in velocity space rather than frequency space?
.. _axes:
| ``axes (intVec=[-1])`` - The pixel axes to regrid. -1 => all.
.. _shape:
| ``shape (intVec=[-1])`` - Shape of the output image. Only used if template is an image. If not specified (-1), the output image shape will be the same as the template image shape along the axes that are regridded and the same as input image shape along the axes which are not regridded.
.. _interpolation:
| ``interpolation (string='linear')`` - The interpolation method. One of "nearest", "linear", "cubic".
.. _decimate:
| ``decimate (int=10)`` - Decimation factor for coordinate grid computation
.. _replicate:
| ``replicate (bool=False)`` - Replicate image rather than regrid?
.. _overwrite:
| ``overwrite (bool=False)`` - Overwrite (unprompted) pre-existing output file?
"""
pass