Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/imsmooth.py: 56%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 19:53 +0000
1##################### generated by xml-casa (v2) from imsmooth.xml ##################
2##################### ab33d312a483ae3ea4502102cc6f10ba ##############################
3from __future__ import absolute_import
4import numpy
5from casatools.typecheck import CasaValidator as _val_ctor
6_pc = _val_ctor( )
7from casatools.coercetype import coerce as _coerce
8from casatools.errors import create_error_string
9from .private.task_imsmooth import imsmooth as _imsmooth_t
10from casatasks.private.task_logging import start_log as _start_log
11from casatasks.private.task_logging import end_log as _end_log
12from casatasks.private.task_logging import except_log as _except_log
14class _imsmooth:
15 """
16 imsmooth ---- Smooth an image or portion of an image
18 --------- parameter descriptions ---------------------------------------------
20 imagename Name of the input image. Must be specified.
21 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.
22 major Major axis for the kernels. Standard quantity representation. Must be specified for kernel="boxcar".
23 minor Minor axis. Standard quantity representation. Must be specified for kernel="boxcar".
24 pa Position angle used only for gaussian kernel. Standard quantity representation.
25 targetres If gaussian kernel, specified parameters are to be resolution of output image (True) or parameters of gaussian to convolve with input image (False).
26 kimage Kernel image name. Only used if kernel="i" or "image".
27 scale Scale factor. -1.0 means auto-scale. Only used if kernel="i" or "image".
28 region Region selection. Default is to use the full image.
29 box Rectangular region to select in direction plane. Default is to use the entire direction plane.
30 chans Channels to use. Default is to use all channels.
31 stokes Stokes planes to use. Default is to use all Stokes planes.
32 mask Mask to use. Default is none.
33 outfile Output image name. Must be specified.
34 stretch If true, stretch the mask if necessary and possible.
35 overwrite If true, overwrite (unprompted) pre-existing output file.
36 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.
37 [1;42mRETURNS[1;m any
39 --------- examples -----------------------------------------------------------
42 This task performs a Fourier-based convolution to 'smooth' the
43 direction plane of an image. Smoothing is typically performed in order to reduce the noise in
44 an image.
46 Keyword arguments:
48 imagename Input image name. Must be specified.
49 outfile Output smoothed image file name. Must be specified.
50 kernel Type of kernel to use when smoothing ("g", "gauss", or "gaussian" for a gaussian
51 kernel or "b", "box", or "boxcar" for a boxcar kernel), or if the
52 image has multiple channels and kernel="commonbeam" (or "c", or "common"), convolve
53 all channels to the smallest beam that encloses all beams in the input image, "i" or "image"
54 to use an image as the kernel.
55 For boxcar smoothing, the major axis is parallel to the y-axis of the image
56 and the minor axis is parallel to the x-axis. For a Gaussian, the
57 orientation is specified by a position angle. A value of 0 degrees means
58 the major axis is parallel to the y-axis and an increasing value of the
59 position angle results in a counter-clockwise rotation of the ellipse.
60 default: 'gauss'
61 major Major axis of kernel which must be specified for boxcar smoothing. For
62 Gaussian smoothing, the kernel parameters can alternatively be specified
63 in the beam parameter. Standard quantity representations are supported.
64 Example "4arcsec".
65 minor Minor axis of kernel which must be specified for boxcar smoothing. For
66 Gaussian smoothing, the kernel parameters can alternatively be specified
67 in the beam parameter. Standard quantity representations are supported.
68 Example "3arcsec".
69 pa Position angle to use for gaussian kernel, unused for boxcar.
70 The Gaussian kernel parameters can alternatively be specified
71 in the beam parameter. Standard quantity representations are supported.
72 Example "40deg".
73 beam Record specifying Gaussian beam parameters. Do not specify any of
74 major, minor, or pa if you choose to specify this parameter.
75 Example: {"major": "5arcsec", "minor": "2arcsec", "pa": "20deg"}
76 targetres Boolean used only for kernel='gauss'. If True, kernel parameters (major/minor/pa
77 or beam) are the resolution of the output image. If false, a gaussian
78 with these parameters is convolved with the input image to produce
79 the output image.
80 kimage The image to be used as the convolution kernel. Only used if kernel="image" or "i".
81 scale Scale factor to use if kernel="i" or "image". -1.0 means auto-scale, which is the default.
82 mask Mask to use. Default is none.
83 region Region selection. Default is to use the full image.
84 box Rectangular region to select in direction plane.
85 Default is to use the entire direction plane.
86 Example: "5, 10, 100, 200".
87 chans Channels to use. Default is to use all channels.
88 stokes Stokes planes to use. Default is to use
89 all Stokes planes.
90 Example: 'I'
92 GAUSSIAN KERNEL
94 The direction pixels must be square. If they are not, use imregrid to regrid your image onto a grid
95 of square pixels.
97 Under the hood, ia.convolve2d() is called with scale=-1 (auto scaling). This means that, when the input image
98 has a restoring beam, pixel values in the output image are scaled in such a way as to conserve flux density.
100 Major and minor are the full width at half maximum (FWHM) of the Gaussian. pa is the position angle
101 of the Gaussian. The beam parameter offers an alternate way of describing the convolving Gaussian.
102 If used, neither major, minor, nor pa can be specified. The beam parameter must have exactly three
103 fields: "major", "minor", and "pa" (or "positionangle"). This is the record format for the output
104 of ia.restoringbeam(). For example
106 beam = {"major": "5arcsec", "minor": "2arcsec", "pa": "20deg"}
108 If both beam and any of major, minor, and/or pa is specified for a Gaussian kernel,
109 an exception will be thrown.
111 Alternatively, if the input image has multiple beams, setting kernel='commonbeam' will result in the
112 smallest beam that encloses all beams in the image to be used as the target resolution to which to
113 convolve all planes.
115 In addition, the targetres parameter indicates if the specified Gaussian is to be the
116 resolution of the final image (True) or if it is to be used to convolve the input image.
117 If True, the input image must have a restoring beam. Use imhead() or ia.restoringbeam()
118 to check for its existence. If the image has multiple beams and targetres=True,
119 all planes in the image will be convolved so that the resulting resolution is that
120 specified by the kernel parameters. If the image has multiple beams and targetres=False,
121 each plane will be convolved with a Gaussian specified by beam (and hence, in
122 general, the output image will also have multiple beams that vary with spectral channel
123 and/or polarization).
125 If the units on the original image include Jy/beam, the units on the
126 output image will be rescaled by the ratio of the input and output
127 beams as well as rescaling by the area of convolution kernel.
129 If the units on the original image include K, then only the image
130 convolution kernel rescaling is done.
132 BOXCAR KERNEL
134 major is length of the box along the y-axis and minor is length of the box along the x-axis.
135 pa is not used and beam should not be specified. The value of targetres is not used.
137 IN GENERAL
139 The major, minor, and pa parameters can be specified in one of three ways
140 Quantity -- for example major=qa.quantity(1, 'arcsec')
141 Note that you can use pixel units, such as
142 major=qa.quantity(1, 'pix')
143 String -- for example minor='1pix' or major='0.5arcsec'
144 (i.e. a string that the Quanta quantity function accepts).
145 Numeric -- for example major=10.
146 In this case, the units of major and minor are assumed to
147 be in arcsec and units of pa are assumed to be degrees.
149 Note: Using pixel units allows you to convolve axes with different units.
151 IMAGE KERNEL
152 If kernel="i" or "image", the image specified by kimage is used to convolve the input image.
153 The coordinate system of the convolution image is ignored; only the pixel values are considered.
155 Fourier-based convolution is performed.
157 The provided kernel can have fewer
158 dimensions than the image being convolved. In this case, it will be
159 padded with degenerate axes. An error will result if the kernel has
160 more dimensions than the image.
162 The scaling of the output image is determined by the argument {stfaf scale}.
163 If this is left unset, then the kernel is normalized to unit sum.
164 If {stfaf scale} is not left unset, then the convolution kernel
165 will be scaled (multiplied) by this value.
167 Masked pixels will be assigned the value 0.0 before convolution.
169 The output mask is the combination (logical OR) of the default input
170 pixelmask (if any) and the OTF mask. Any other input pixelmasks
171 will not be copied. The function
172 maskhandler
173 should be used if there is a need to copy other masks too.
176 EXAMPLES
178 # smoothing with a gaussian kernel 20arseconds by 10 arseconds
179 imsmooth( imagename='my.image', kernel='gauss', major='20arcsec', minor='10arcsec', pa="0deg")
181 # the same as before, just a different way of specifying the kernel parameters
182 mybeam = {'major': '20arcsec', 'minor': '10arcsec', 'pa': '0deg'}
183 imsmooth( imagename='my.image', kernel='gauss', beam=mybeam)
185 # Smoothing using pixel coordinates and a boxcar kernel.
186 imsmooth( imagename='new.image', major='20pix', minor='10pix', kernel='boxcar')
189 """
191 _info_group_ = """analysis"""
192 _info_desc_ = """Smooth an image or portion of an image"""
194 def __call__( self, imagename='', kernel='gauss', major='', minor='', pa='', targetres=False, kimage='', scale=float(-1.0), region='', box='', chans='', stokes='', mask='', outfile='', stretch=False, overwrite=False, beam='' ):
195 schema = {'imagename': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'kernel': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'b', 'image', 'g', 'boxcar', 'c', 'commonbeam', 'gauss', 'box', 'i', 'common', 'gaussian' ]}, 'major': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'minor': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'pa': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'targetres': {'type': 'cBool'}, 'kimage': {'type': 'cStr', 'coerce': _coerce.to_str}, 'scale': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'region': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'box': {'type': 'cStr', 'coerce': _coerce.to_str}, 'chans': {'type': 'cStr', 'coerce': _coerce.to_str}, 'stokes': {'type': 'cStr', 'coerce': _coerce.to_str}, 'mask': {'type': 'cStr', 'coerce': _coerce.to_str}, 'outfile': {'type': 'cStr', 'coerce': _coerce.to_str}, 'stretch': {'type': 'cBool'}, 'overwrite': {'type': 'cBool'}, 'beam': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}}
196 doc = {'imagename': imagename, 'kernel': kernel, 'major': major, 'minor': minor, 'pa': pa, 'targetres': targetres, 'kimage': kimage, 'scale': scale, 'region': region, 'box': box, 'chans': chans, 'stokes': stokes, 'mask': mask, 'outfile': outfile, 'stretch': stretch, 'overwrite': overwrite, 'beam': beam}
197 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
198 _logging_state_ = _start_log( 'imsmooth', [ 'imagename=' + repr(_pc.document['imagename']), 'kernel=' + repr(_pc.document['kernel']), 'major=' + repr(_pc.document['major']), 'minor=' + repr(_pc.document['minor']), 'pa=' + repr(_pc.document['pa']), 'targetres=' + repr(_pc.document['targetres']), 'kimage=' + repr(_pc.document['kimage']), 'scale=' + repr(_pc.document['scale']), 'region=' + repr(_pc.document['region']), 'box=' + repr(_pc.document['box']), 'chans=' + repr(_pc.document['chans']), 'stokes=' + repr(_pc.document['stokes']), 'mask=' + repr(_pc.document['mask']), 'outfile=' + repr(_pc.document['outfile']), 'stretch=' + repr(_pc.document['stretch']), 'overwrite=' + repr(_pc.document['overwrite']), 'beam=' + repr(_pc.document['beam']) ] )
199 task_result = None
200 try:
201 task_result = _imsmooth_t( _pc.document['imagename'], _pc.document['kernel'], _pc.document['major'], _pc.document['minor'], _pc.document['pa'], _pc.document['targetres'], _pc.document['kimage'], _pc.document['scale'], _pc.document['region'], _pc.document['box'], _pc.document['chans'], _pc.document['stokes'], _pc.document['mask'], _pc.document['outfile'], _pc.document['stretch'], _pc.document['overwrite'], _pc.document['beam'] )
202 except Exception as exc:
203 _except_log('imsmooth', exc)
204 raise
205 finally:
206 task_result = _end_log( _logging_state_, 'imsmooth', task_result )
207 return task_result
209imsmooth = _imsmooth( )