Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/specsmooth.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 specsmooth.xml ################ 

2##################### 750dccf3562318cbdb15c36de3abf077 ############################## 

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_specsmooth import specsmooth as _specsmooth_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 _specsmooth: 

15 """ 

16 specsmooth ---- Smooth an image region in one dimension 

17 

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

19 

20 imagename Name of the input image 

21 outfile Output image name. 

22 box Rectangular region to select in direction plane. Default is to use the entire direction plane. 

23 chans Channels to use. Channels must be contiguous. Default is to use all channels. 

24 stokes Stokes planes to use. Planes specified must be contiguous. Default is to use all Stokes planes. 

25 region Region selection. Default is to use the full image. 

26 mask Mask to use. Default is none.. 

27 overwrite Overwrite the output if it exists? 

28 stretch Stretch the mask if necessary and possible? Default False 

29 axis The profile axis. Default: use the spectral axis if one exists, axis 0 otherwise (<0). 

30 function Convolution function. hanning and boxcar are supported functions. Minimum match is supported. 

31 width Width of boxcar, in pixels. 

32 dmethod Decimation method. "" means no decimation, "copy" and "mean" are also supported (minimum match). 

33 RETURNS record 

34 

35 --------- examples ----------------------------------------------------------- 

36 

37  

38  

39 Smooth an image region in one dimension. 

40  

41 ARAMETER SUMMARY 

42 imagename Name of the input (CASA, FITS, MIRIAD) image 

43 box Rectangular region to select in direction plane. 

44 Default is to use the entire direction plane. Only a single box may be specified. 

45 chans Channels to use. Channels must be contiguous. 

46 Default is to use all channels. 

47 stokes Stokes planes to use. Planes specified must be 

48 contiguous. Default is to use all Stokes planes. 

49 region Region selection. Default is to use the full image. 

50 mask Mask to use. Default is none. 

51 overwrite If the specified outfile already exists, overwrite it if True. 

52 stretch Stretch the input mask if necessary and possible? Only used if a mask is specified. 

53  

54 axis Pixel axis along which to do the convolution <0 means use the spectral axis. 

55 function Convolution function to use. Supported values are "boxcar" and "hanning". Minimum 

56 match is supported. 

57 width Width of boxcar in pixels. Used only if function parameter minimally matches "boxcar". 

58 dmethod Plane decimation method. "" means no decimation should be performed. Other supported 

59 values are "copy" and "mean". Minimal match is supported. See below for details. 

60  

61 This application performs one dimensional convolution along a specified axis of an image 

62 or selected region of an image. Hanning smoothing and boxcar smoothing are supported. 

63 Both float valued and complex valued images are supported. Masked pixel values are set to 

64 zero prior to convolution. All nondefault pixel masks are ignored during 

65 the calculation. The convolution is done in the image domain (i.e., not 

66 with an FFT). 

67  

68 BOXCAR SMOOTHING 

69  

70 One dimensional boxcar convolution is defined by 

71  

72 z[i] = (y[i] + y[i+i] + ... + y[i+w])/w 

73  

74 where z[i] is the value at pixel i in the box car smoothed image, y[k] 

75 is the pixel value of the input image at pixel k, and w is a postivie integer 

76 representing the width of the boxcar in pixels. The length of the axis along which the 

77 convolution is to occur must be at least w pixels in the selected region, 

78 unless decimation using the mean function is chosen in which case the axis 

79 length must be at least 2*w (see below). 

80  

81 If dmethod="" (no decimation), the length of the output axis will be equal 

82 to the length of the input axis - w + 1. The pixel mask, ORed with the OTF mask 

83 if specified, is copied from the selected region of the input image to the 

84 output image. Thus for example, if the selected region in the input image has 

85 six planes along the convolution axis, if the specified boxcar width is 2, 

86 and if the pixel values, which are all unmasked, on a slice along this axis 

87 are [1, 2, 5, 10, 17, 26], then the corresponding output slice will be of 

88 length five pixels and the output pixel values will be [1.5, 3.5, 7.5, 13.5, 21.5]. 

89  

90 If dmethod="copy", the output image is the image calculated 

91 if dmethod="", except that only every wth plane is kept. Both the pixel and mask 

92 values of these planes are copied directly to the output image, without further 

93 processing. Thus for example, if the selected region in the input image has six 

94 planes along the convolution axis, the boxcar width is chosen to be 2, and if 

95 the pixel values, which are all unmasked, on a slice along this axis are [1, 2, 

96 5, 10, 17, 26], the corresponding output pixel values will be [1.5, 7.5, 21.5]. 

97  

98 If dmethod="mean", first the image described in the dmethod="" 

99 case is calculated. Then, the ith plane of the output image is calculated by 

100 averaging the i*w to the (i+1)*w-1 planes of this intermediate image. Thus, for 

101 example, if the selected region in the input image has six planes along the 

102 convolution axis, the boxcar width is chosen to be 2, and if the pixel values, 

103 which are all unmasked, on a slice along this axis are [1, 2, 5, 10, 17, 26], 

104 then the corresponding output pixel values will be [2.5, 10.5]. Any pixels at the 

105 end of the convolution axis of the intermediate image that do not fall into a complete bin of 

106 width w are ignored. Masked values are taken into consideration when forming this 

107 average, so if one of the values is masked, it is not used in the average. If at 

108 least one of the values in the intermediate image bin is not masked, the 

109 corresponding output pixel will not be masked. 

110  

111 HANNING SMOOTHING 

112  

113 Hanning convolution of one axis of an image is defined by 

114  

115 z[i] = 0.25*y[i-1] + 0.5*y[i] + 0.25*y[i+1] (equation 1) 

116  

117 where z[i] is the value at pixel i in the hanning smoothed image, and 

118 y[i-1], y[i], and y[i+1] are the values of the input image at pixels i-1, 

119 i, and i+1 respectively. The length of the axis along which the convolution is 

120 to occur must be at least three pixels in the selected region. 

121  

122 If dmethod="" (no decimation of image planes), the length of the output axis will 

123 be the same as that of the input axis. The output pixel values along the convolution 

124 axis will be related to those of the input values according to equation 1, except 

125 the first and last pixels. In that case, 

126  

127 z[0] = 0.5*(y[0] + y[1]) 

128  

129 and, 

130  

131 z[N-1] = 0.5*(y[N-2] + y[N-1]) 

132  

133 where N is the number of pixels along the convolution aixs. 

134 The pixel mask, ORed with the OTF mask if specified, is copied from the selected 

135 region of the input image to the output image. Thus for example, if the selected 

136 region in the input image has six planes along the convolution axis, and if the pixel 

137 values, which are all unmasked, on a slice along this axis are [1, 2, 5, 10, 17, 26], 

138 the corresponding output pixel values will be [1.5, 2.5, 5.5, 10.5, 17.5, 21.5]. 

139  

140 If dmethod="copy", the output image is the image calculated if 

141 dmethod="", except that only the odd-numbered planes are kept. Furthermore, if the 

142 number of planes along the convolution axis in the selected region of the input image 

143 is even, the last odd number plane is also discarded. Thus, if the selected region 

144 has N pixels along the convolution axis in the input image, along the convolution 

145 axis the output image will have (N-1)/2 planes if N is odd, or (N-2)/2 planes if N 

146 is even. The pixel and mask values are copied directly, without further 

147 processing. Thus for example, if the selected region in the input image has six planes 

148 along the convolution axis, and if the pixel values, which are all unmasked, on a slice 

149 along this axis are [1, 2, 5, 10, 17, 26], the corresponding output pixel values will be 

150 [2.5, 10.5]. 

151  

152 If dmethod="mean", first the image described in the dmethod="" case 

153 is calculated. The first plane and last plane(s) of that image are then discarded as 

154 described in the dmethod="copy" case. Then, the ith plane of the output 

155 image is calculated by averaging the (2*i)th and (2*i + 1)th planes of the intermediate 

156 image. Thus for example, if the selected region in the input image has six planes 

157 along the convolution axis, and if the pixel values, which are all unmasked, on a slice 

158 along this axis are [1, 2, 5, 10, 17, 26], the corresponding output pixel values will be 

159 [4.0, 14.0]. Masked values are taken into consideration when forming this average, so if 

160 one of the values is masked, it is not used in the average. If at least one of the values 

161 in the input pair is not masked, the corresponding output pixel will not be masked. 

162  

163  

164 EXAMPLES 

165  

166 # boxcar smooth the spectral axis by 3 pixels, say it's axis 2 and only 

167 # write every other pixel 

168 specsmooth(imagename="mynonsmoothed.im", outfile="myboxcarsmoothed.im", 

169 axis=2, function="boxcar", dmethod="copy", width=3, overwrite=True) 

170  

171 # hanning smooth the spectral axis, say it's axis 2 and do not perform decimation 

172 # of image planes 

173 specsmooth(imagename="mynonsmoothed.im", outfile="myhanningsmoothed.im", 

174 axis=2, dmethod=""," overwrite=True) 

175 

176 

177 """ 

178 

179 _info_group_ = """analysis""" 

180 _info_desc_ = """Smooth an image region in one dimension""" 

181 

182 def __call__( self, imagename='', outfile='', box='', chans='', stokes='', region='', mask='', overwrite=False, stretch=False, axis=int(-1), function='hanning', width=int(2), dmethod='copy' ): 

183 schema = {'imagename': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'outfile': {'type': 'cStr', 'coerce': _coerce.to_str}, 'box': {'type': 'cStr', 'coerce': _coerce.to_str}, 'chans': {'type': 'cStr', 'coerce': _coerce.to_str}, 'stokes': {'type': 'cStr', 'coerce': _coerce.to_str}, 'region': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'mask': {'type': 'cStr', 'coerce': _coerce.to_str}, 'overwrite': {'type': 'cBool'}, 'stretch': {'type': 'cBool'}, 'axis': {'type': 'cInt'}, 'function': {'type': 'cStr', 'coerce': _coerce.to_str}, 'width': {'type': 'cInt'}, 'dmethod': {'type': 'cStr', 'coerce': _coerce.to_str}} 

184 doc = {'imagename': imagename, 'outfile': outfile, 'box': box, 'chans': chans, 'stokes': stokes, 'region': region, 'mask': mask, 'overwrite': overwrite, 'stretch': stretch, 'axis': axis, 'function': function, 'width': width, 'dmethod': dmethod} 

185 assert _pc.validate(doc,schema), create_error_string(_pc.errors) 

186 _logging_state_ = _start_log( 'specsmooth', [ 'imagename=' + repr(_pc.document['imagename']), 'outfile=' + repr(_pc.document['outfile']), 'box=' + repr(_pc.document['box']), 'chans=' + repr(_pc.document['chans']), 'stokes=' + repr(_pc.document['stokes']), 'region=' + repr(_pc.document['region']), 'mask=' + repr(_pc.document['mask']), 'overwrite=' + repr(_pc.document['overwrite']), 'stretch=' + repr(_pc.document['stretch']), 'axis=' + repr(_pc.document['axis']), 'function=' + repr(_pc.document['function']), 'width=' + repr(_pc.document['width']), 'dmethod=' + repr(_pc.document['dmethod']) ] ) 

187 task_result = None 

188 try: 

189 task_result = _specsmooth_t( _pc.document['imagename'], _pc.document['outfile'], _pc.document['box'], _pc.document['chans'], _pc.document['stokes'], _pc.document['region'], _pc.document['mask'], _pc.document['overwrite'], _pc.document['stretch'], _pc.document['axis'], _pc.document['function'], _pc.document['width'], _pc.document['dmethod'] ) 

190 except Exception as exc: 

191 _except_log('specsmooth', exc) 

192 raise 

193 finally: 

194 task_result = _end_log( _logging_state_, 'specsmooth', task_result ) 

195 return task_result 

196 

197specsmooth = _specsmooth( ) 

198