casa6

<casaxml xsi:schemaLocation="http://casa.nrao.edu/schema/casa.xsd file:///opt/casa/code/xmlcasa/xml/casa.xsd" xmlns="http://casa.nrao.edu/schema/psetTypes.html" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

​

<task type="function" name="imregrid" category="analysis">

<shortdescription>regrid an image onto a template image</shortdescription>

<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.

</description>

<input>

     <param type="path" name="imagename" mustexist="true"><shortdescription>Name of the source image</shortdescription><description>Name of the source image</description>

          <value/>

     </param>

     <param type="any" name="template"><shortdescription>A dictionary, refcode, or name of an image that provides the output shape and coordinate system</shortdescription><description>A dictionary, refcode, or name of an image that provides the output shape and coordinate system</description>

        <any type="variant"/>

          <value type="string">get</value>

     </param>

​

     <param type="string" name="output"><shortdescription>Name for the regridded image</shortdescription><description>Name for the regridded image</description>

          <value/>

     </param>

​

     <param type="bool" direction="in" name="asvelocity"><shortdescription>Regrid spectral axis in velocity space rather than frequency space?</shortdescription><description>Regrid spectral axis in velocity space rather than frequency space?</description>

        <value>True</value>

     </param>

     <param type="intVec" direction="in" name="axes"><shortdescription>The pixel axes to regrid. -1 =&gt; all.</shortdescription><description>The pixel axes to regrid. -1 =&gt; all.</description>

         <value><value>-1</value></value>

     </param>

     <param type="intVec" name="shape" subparam="true"><shortdescription>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.</shortdescription><description>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.</description>

        <value><value>-1</value></value>

     </param>

     <param type="string" name="interpolation"><shortdescription>The interpolation method.  One of &quot;nearest&quot;, &quot;linear&quot;, &quot;cubic&quot;.</shortdescription><description>The interpolation method.  One of &quot;nearest&quot;, &quot;linear&quot;, &quot;cubic&quot;.</description>

        <value>linear</value>

     </param>

     <param type="int" name="decimate"><shortdescription>Decimation factor for coordinate grid computation</shortdescription><description>Decimation factor for coordinate grid computation</description>

     <value>10</value>

     </param>

     <param type="bool" name="replicate"><shortdescription>Replicate image rather than regrid?</shortdescription><description>Replicate image rather than regrid?</description>

     <value>False</value>

     </param>

     <param type="bool" name="overwrite"><shortdescription>Overwrite (unprompted) pre-existing output file?</shortdescription><description>Overwrite (unprompted) pre-existing output file?</description>

     <value>False</value>

     </param>

     <constraints>

        <when param="template">

            <notequals type="string" value="get">

                <default param="shape"><value type="intVec"><value>-1</value></value></default>

            </notequals>

        </when>

     </constraints>

</input>

<example>

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?

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.

​

​

</example> 

​

<returns>void</returns></task>

</casaxml>