Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/imsmooth.py: 100%

27 statements  

« prev     ^ index     » next       coverage.py v7.6.4, created at 2024-11-01 07:19 +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 

13 

14class _imsmooth: 

15 """ 

16 imsmooth ---- Smooth an image or portion of an image 

17 

18 --------- parameter descriptions --------------------------------------------- 

19 

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 RETURNS any 

38 

39 --------- examples ----------------------------------------------------------- 

40 

41  

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. 

45  

46 Keyword arguments: 

47  

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' 

91  

92 GAUSSIAN KERNEL 

93  

94 The direction pixels must be square. If they are not, use imregrid to regrid your image onto a grid 

95 of square pixels. 

96  

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. 

99  

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 

105  

106 beam = {"major": "5arcsec", "minor": "2arcsec", "pa": "20deg"} 

107  

108 If both beam and any of major, minor, and/or pa is specified for a Gaussian kernel, 

109 an exception will be thrown. 

110  

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. 

114  

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

124  

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. 

128  

129 If the units on the original image include K, then only the image 

130 convolution kernel rescaling is done. 

131  

132 BOXCAR KERNEL 

133  

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. 

136  

137 IN GENERAL 

138  

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. 

148  

149 Note: Using pixel units allows you to convolve axes with different units. 

150  

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. 

154  

155 Fourier-based convolution is performed. 

156  

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. 

161  

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. 

166  

167 Masked pixels will be assigned the value 0.0 before convolution. 

168  

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. 

174  

175  

176 EXAMPLES 

177  

178 # smoothing with a gaussian kernel 20arseconds by 10 arseconds 

179 imsmooth( imagename='my.image', kernel='gauss', major='20arcsec', minor='10arcsec', pa="0deg") 

180  

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) 

184  

185 # Smoothing using pixel coordinates and a boxcar kernel. 

186 imsmooth( imagename='new.image', major='20pix', minor='10pix', kernel='boxcar') 

187 

188 

189 """ 

190 

191 _info_group_ = """analysis""" 

192 _info_desc_ = """Smooth an image or portion of an image""" 

193 

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 

208 

209imsmooth = _imsmooth( ) 

210