|
|||
NRAO Home > CASA > CASA Task Reference Manual |
|
0.1.58 imregrid
Requires:
Synopsis
regrid an image onto a template image
Description
Imregrid will regrid an input image onto a new coordinate system from a
template image or to a new directional reference frame. If a template image is
used, then the input and template images must have the same coordinate
structure.
Arguments
Inputs |
| ||
imagename |
| Name of the source image
| |
| allowed: | string |
|
| Default: |
| |
template |
| A dictionary, refcode, or name of an image that provides
the output shape and coordinate system
| |
| allowed: | any |
|
| Default: | variant get |
|
output |
| Name for the regridded image
| |
| allowed: | string |
|
| Default: |
| |
asvelocity |
| Regrid spectral axis in velocity space rather than
frequency space?
| |
| allowed: | bool | |
| Default: | True |
|
axes |
| The pixel axes to regrid. -1 => all.
| |
| allowed: | intArray |
|
| Default: | -1 | |
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.
| |
| allowed: | intArray |
|
| Default: | -1 |
|
interpolation |
| The interpolation method. One of ”nearest”, ”linear”,
”cubic”.
| |
| allowed: | string |
|
| Default: | linear |
|
decimate |
| Decimation factor for coordinate grid computation
| |
| allowed: | int |
|
| Default: | 10 |
|
replicate |
| Replicate image rather than regrid?
| |
| allowed: | bool |
|
| Default: | False |
|
overwrite |
| Overwrite (unprompted) pre-existing output file?
| |
| allowed: | bool |
|
| Default: | False |
|
The imregrid task currently finds the nearest input pixel center and interpolates to the output pixel center.
No averaging is done in any direction!
Imregrid will regrid an input image onto a new coordinate system from a template image
or to a new directional reference frame. If a template image is used, then the input and
template images must have the same coordinate structure.
Keyword arguments:
imagename Name of the source image that needs to be regridded. Must be specified.
example: imagename=’orion.image’
template Dictionary, directional reference code, or imagename defining the new
shape and coordinate system, or ’get’ to return the template
dictionary for imagename. Recognized directional reference codes are:
’J2000’, ’B1950’, ’B1950_VLA’, ’GALACTIC’, ’HADEC’, ’AZEL’,
’AZELSW’, ’AZELNE’, ’ECLIPTIC’, ’MECLIPTIC’, ’TECLIPTIC’,
and ’SUPERGAL’.
default: ’get’; example: template=’orion_j2000.im’ (for a template image),
template=’J2000’ (to regrid the input image to J2000 coordinates).
shape Shape of the output image. Only used if template is an image.
If not specified (-1), the output image will be the same as the template image
shape along the axes which are regridded and the same as the input image shpae
along the axes which are not regridded. If specified and the axis ordering between
the input image and the template are not the same, the values in the array correspond
to the axis ordering of the input image; the output image will have the same axis
ordering as the input image. Ignored if template is set equal to a
reference code. If template is a dictionary, the output shape is
retrieved from the dictionary so the shape input parameter is ignored.
output Name for the regridded image. Must be specified.
example: imagename=’orion_shifted.im’
asvelocity If True, regrid spectral axis with respect to velocity, not frequency. If False,
regrid with respect to frequency. default: True
axes The pixel axes to regrid. Default value [-1] => all except Stokes. Ignored
if template is set equal to a reference code (in which case only the directional
axes are regridded). If specified, this should
be provided as an array. example axes=[0,1] (only regrid the first two axes, which
are normally the directional axes).
interpolation The interpolation method. One of ’nearest’, ’linear’, ’cubic’.
decimate Decimation factor for coordinate grid computation
replicate Replicate image rather than regrid?
overwrite"> Overwrite (unprompted) pre-existing output file?
async Run task in a separate process (return CASA prompt)
default: False; example: async=True
The new coordinate system is defined by the template parameter, which can be:
* a recognized directional reference frame string. This will rotate the image and the coordinate system so that
the new reference frame’s axes are aligned to the cardinal directions (left-right, up-down).
Rotation occurs about the center direction pixel. If this pixel is not the reference pixel,
a temporary copy of the original image is created and the coordinate system is adjusted so
the center direction pixel is the reference pixel. The coordinate system of the input image
is not modified and the output image’s reference direction pixel is the center pixel.
Note that the conversion between one frame and another in general becomes less accurate
as distance from the output image’s reference pixel increases. Before the rotation occurs, the
image is padded with masked pixels to ensure that all good pixels are used in the rotation (ie the
corners of the image are not cropped after the rotation). After the image is rotated, 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.
* 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 argument {\stfaf replicate} can be used to simply replicate pixels
rather than regridding them. Normally ({\stfaf replicate=F}), 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 {\stfaf replicate=T}, 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 {\stfaf replicate} is False, a coordinate is
computed for each output pixel; this is an expensive operation. The
argument {\stfaf decimate} 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 {\stfaf 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=T,
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 interpolation schemes 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.
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: 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.
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 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 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 shape 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.
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 axes 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 axes 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 shape is not specified, the output image will have the same number of channels
as the input image. If shape 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 axes 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 axes is specified 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 axes 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 axes 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.
IMPORTANT NOTE ABOUT FLUX CONSERVATION
in general regridding is inaccurate for images that the angular resolution is poorly
sampled. A check is done for such cases and a warning message is emitted if a beam present.
However, no such check is done if there is no beam present. To add a restoring beam to
an image, use ia.setrestoringbeam().
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 that 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
Firstly, the user should inspect the type and ordering of the axes with imhead,
and then correct with imtrans if necessary.
imregrid(imagename="input.image", output="output.image", template="target.image", axes=[0,1])
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 eg, 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.
More information about CASA may be found at the
CASA web page
Copyright © 2016 Associated Universities Inc., Washington, D.C.
This code is available under the terms of the GNU General Public Lincense
Home |
Contact Us |
Directories |
Site Map |
Help |
Privacy Policy |
Search