|
|||
NRAO Home > CASA > CASA Task Reference Manual |
|
0.1.59 imsmooth
Requires:
Synopsis
Smooth an image or portion of an image
Description
Arguments
Inputs |
| ||
imagename |
| Name of the input image. Must be specified.
| |
| allowed: | string |
|
| Default: |
| |
kernel |
| Type of kernel to use. Acceptable values are ”b”,
”box”, or ”boxcar” for a boxcar kernel, ”g”, ”gauss”,
or ”gaussian” for a gaussian kernel, ”c”, ”common”, or
”commonbeam” to use the common beam of an image
with multiple beams as the gaussian to which to convolve
all the planes, ”i” or ”image” to use an image as the
kernel. | |
| allowed: | string |
|
| Default: | gauss |
|
major |
| Major axis for the kernels.
Standard quantity representation. Must be specified for
kernel=”boxcar”. Example: ”4arcsec”.
| |
| allowed: | any |
|
| Default: | variant
|
|
minor |
| Minor axis. Standard quantity representation. Must be
specified for kernel=”boxcar”. Example: ”2arcsec”.
| |
| allowed: | any |
|
| Default: | variant
|
|
pa |
| Position angle used only for gaussian kernel. Standard
quantity representation. Example: ”40deg”.
| |
| allowed: | any |
|
| Default: | variant
|
|
targetres |
| If gaussian kernel, specified parameters are to be
resolution of output image (True) or parameters of
gaussian to convolve with input image (False).
| |
| allowed: | bool | |
| Default: | False |
|
kimage |
| Kernel image name. Only used if kernel=”i” or ”image”.
| |
| allowed: | string |
|
| Default: |
|
|
scale |
| Scale factor. -1.0 means auto-scale. Only used if
kernel=”i” or ”image”.
| |
| allowed: | double |
|
| Default: | -1.0 |
|
region |
| Region selection. Default is to use the full image.
| |
| allowed: | any |
|
| Default: | variant
|
|
box |
| Rectangular region to select in direction plane. Default
is to use the entire direction plane.
| |
| allowed: | string |
|
| Default: |
|
|
chans |
| Channels to use. Default is to use all channels.
| |
| allowed: | string |
|
| Default: |
|
|
stokes |
| Stokes planes to use. Default is to use all Stokes planes.
| |
| allowed: | string |
|
| Default: |
|
|
mask |
| Mask to use. Default is none.
| |
| allowed: | string |
|
| Default: |
|
|
outfile |
| Output image name. Must be specified.
| |
| allowed: | string |
|
| Default: |
|
|
stretch |
| Stretch the mask if necessary and possible?
| |
| allowed: | bool |
|
| Default: | False |
|
overwrite |
| Overwrite (unprompted) pre-existing output file?
| |
| allowed: | bool |
|
| Default: | False |
|
beam |
| Alternate way of describing a Gaussian. If specified,
must be a dictionary with keys ”major”, ”minor”,
and ”pa” (or ”positionangle”). Do not specify beam if
specifying major, minor, and pa. Example: Example:
”major”: ”5arcsec”, ”minor”: ”2arcsec”, ”pa”: ”20deg”.
| |
| allowed: | any |
|
| Default: | variant
|
|
any
Example
This task performs a Fourier-based convolution to ’smooth’ the
direction plane of an image. Smoothing is typically performed in order to reduce the noise in
an image.
Keyword arguments:
imagename Input image name. Must be specified.
outfile Output smoothed image file name. Must be specified.
kernel Type of kernel to use when smoothing ("g", "gauss", or "gaussian" for a gaussian
kernel or "b", "box", or "boxcar" for a boxcar kernel), or if the
image has multiple channels and kernel="commonbeam" (or "c", or "common"), convolve
all channels to the smallest beam that encloses all beams in the input image, "i" or "image"
to use an image as the kernel.
For boxcar smoothing, the major axis is parallel to the y-axis of the image
and the minor axis is parallel to the x-axis. For a Gaussian, the
orientation is specified by a position angle. A value of 0 degrees means
the major axis is parallel to the y-axis and an increasing value of the
position angle results in a counter-clockwise rotation of the ellipse.
default: ’gauss’
major Major axis of kernel which must be specified for boxcar smoothing. For
Gaussian smoothing, the kernel parameters can alternatively be specified
in the beam parameter. Standard quantity representations are supported.
Example "4arcsec".
minor Minor axis of kernel which must be specified for boxcar smoothing. For
Gaussian smoothing, the kernel parameters can alternatively be specified
in the beam parameter. Standard quantity representations are supported.
Example "3arcsec".
pa Position angle to use for gaussian kernel, unused for boxcar.
The Gaussian kernel parameters can alternatively be specified
in the beam parameter. Standard quantity representations are supported.
Example "40deg".
beam Record specifying Gaussian beam parameters. Do not specify any of
major, minor, or pa if you choose to specify this parameter.
Example: {"major": "5arcsec", "minor": "2arcsec", "pa": "20deg"}
targetres Boolean used only for kernel=’gauss’. If True, kernel parameters (major/minor/pa
or beam) are the resolution of the output image. If false, a gaussian
with these parameters is convolved with the input image to produce
the output image.
kimage The image to be used as the convolution kernel. Only used if kernel="image" or "i".
scale Scale factor to use if kernel="i" or "image". -1.0 means auto-scale, which is the default.
mask Mask to use. Default is none.
region Region selection. Default is to use the full image.
box Rectangular region to select in direction plane.
Default is to use the entire direction plane.
Example: "5, 10, 100, 200".
chans Channels to use. Default is to use all channels.
stokes Stokes planes to use. Default is to use
all Stokes planes.
Example: ’I’
GAUSSIAN KERNEL
The direction pixels must be square. If they are not, use imregrid to regrid your image onto a grid
of square pixels.
Under the hood, ia.convolve2d() is called with scale=-1 (auto scaling). This means that, when the input image
has a restoring beam, pixel values in the output image are scaled in such a way as to conserve flux density.
Major and minor are the full width at half maximum (FWHM) of the Gaussian. pa is the position angle
of the Gaussian. The beam parameter offers an alternate way of describing the convolving Gaussian.
If used, neither major, minor, nor pa can be specified. The beam parameter must have exactly three
fields: "major", "minor", and "pa" (or "positionangle"). This is the record format for the output
of ia.restoringbeam(). For example
beam = {"major": "5arcsec", "minor": "2arcsec", "pa": "20deg"}
If both beam and any of major, minor, and/or pa is specified for a Gaussian kernel,
an exception will be thrown.
Alternatively, if the input image has multiple beams, setting kernel=’commonbeam’ will result in the
smallest beam that encloses all beams in the image to be used as the target resolution to which to
convolve all planes.
In addition, the targetres parameter indicates if the specified Gaussian is to be the
resolution of the final image (True) or if it is to be used to convolve the input image.
If True, the input image must have a restoring beam. Use imhead() or ia.restoringbeam()
to check for its existence. If the image has multiple beams and targetres=True,
all planes in the image will be convolved so that the resulting resolution is that
specified by the kernel parameters. If the image has multiple beams and targetres=False,
each plane will be convolved with a Gaussian specified by beam (and hence, in
general, the output image will also have multiple beams that vary with spectral channel
and/or polarization).
If the units on the original image include Jy/beam, the units on the
output image will be rescaled by the ratio of the input and output
beams as well as rescaling by the area of convolution kernel.
If the units on the original image include K, then only the image
convolution kernel rescaling is done.
BOXCAR KERNEL
major is length of the box along the y-axis and minor is length of the box along the x-axis.
pa is not used and beam should not be specified. The value of targetres is not used.
IN GENERAL
The major, minor, and pa parameters can be specified in one of three ways
Quantity -- for example major=qa.quantity(1, ’arcsec’)
Note that you can use pixel units, such as
major=qa.quantity(1, ’pix’)
String -- for example minor=’1pix’ or major=’0.5arcsec’
(i.e. a string that the Quanta quantity function accepts).
Numeric -- for example major=10.
In this case, the units of major and minor are assumed to
be in arcsec and units of pa are assumed to be degrees.
Note: Using pixel units allows you to convolve axes with different units.
IMAGE KERNEL
If kernel="i" or "image", the image specified by kimage is used to convolve the input image.
The coordinate system of the convolution image is ignored; only the pixel values are considered.
Fourier-based convolution is performed.
The provided kernel can have fewer
dimensions than the image being convolved. In this case, it will be
padded with degenerate axes. An error will result if the kernel has
more dimensions than the image.
The scaling of the output image is determined by the argument {\stfaf scale}.
If this is left unset, then the kernel is normalized to unit sum.
If {\stfaf scale} is not left unset, then the convolution kernel
will be scaled (multiplied) by this value.
Masked pixels will be assigned the value 0.0 before convolution.
The output mask is the combination (logical OR) of the default input
\pixelmask\ (if any) and the OTF mask. Any other input \pixelmasks\
will not be copied. The function
maskhandler
should be used if there is a need to copy other masks too.
EXAMPLES
# smoothing with a gaussian kernel 20arseconds by 10 arseconds
imsmooth( imagename=’my.image’, kernel=’gauss’, major=’20arcsec’, minor=’10arcsec’, pa="0deg")
# the same as before, just a different way of specifying the kernel parameters
mybeam = {’major’: ’20arcsec’, ’minor’: ’10arcsec’, ’pa’: ’0deg’}
imsmooth( imagename=’my.image’, kernel=’gauss’, beam=mybeam)
# Smoothing using pixel coordinates and a boxcar kernel.
imsmooth( imagename=’new.image’, major=’20pix’, minor=’10pix’, kernel=’boxcar’)
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