Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/imregrid.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 imregrid.xml ##################
2##################### ec3b2b50981cea05bc279bf990506942 ##############################
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_imregrid import imregrid as _imregrid_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 _imregrid:
15 """
16 imregrid ---- regrid an image onto a template image
19 Imregrid will regrid an input image onto a new coordinate system from a template image
20 or to a new directional reference frame. If a template image is used, then the input and
21 template images must have the same coordinate structure.
23 --------- parameter descriptions ---------------------------------------------
25 imagename Name of the source image
26 template A dictionary, refcode, or name of an image that provides the output shape and coordinate system
27 output Name for the regridded image
28 asvelocity Regrid spectral axis in velocity space rather than frequency space?
29 axes The pixel axes to regrid. -1 => all.
30 shape 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.
31 interpolation The interpolation method. One of "nearest", "linear", "cubic".
32 decimate Decimation factor for coordinate grid computation
33 replicate Replicate image rather than regrid?
34 overwrite Overwrite (unprompted) pre-existing output file?
36 --------- examples -----------------------------------------------------------
39 The imregrid task currently finds the nearest input pixel center and interpolates to the output pixel center.
40 No averaging is done in any direction!
42 Imregrid will regrid an input image onto a new coordinate system from a template image
43 or to a new directional reference frame. If a template image is used, then the input and
44 template images must have the same coordinate structure.
46 Keyword arguments:
48 imagename Name of the source image that needs to be regridded. Must be specified.
49 example: imagename='orion.image'
50 template Dictionary, directional reference code, or imagename defining the new
51 shape and coordinate system, or 'get' to return the template
52 dictionary for imagename. Recognized directional reference codes are:
53 'J2000', 'B1950', 'B1950_VLA', 'GALACTIC', 'HADEC', 'AZEL',
54 'AZELSW', 'AZELNE', 'ECLIPTIC', 'MECLIPTIC', 'TECLIPTIC',
55 and 'SUPERGAL'.
56 default: 'get'; example: template='orion_j2000.im' (for a template image),
57 template='J2000' (to regrid the input image to J2000 coordinates).
58 shape Shape of the output image. Only used if template is an image.
59 If not specified (-1), the output image will be the same as the template image
60 shape along the axes which are regridded and the same as the input image shpae
61 along the axes which are not regridded. If specified and the axis ordering between
62 the input image and the template are not the same, the values in the array correspond
63 to the axis ordering of the input image; the output image will have the same axis
64 ordering as the input image. Ignored if template is set equal to a
65 reference code. If template is a dictionary, the output shape is
66 retrieved from the dictionary so the shape input parameter is ignored.
67 output Name for the regridded image. Must be specified.
68 example: imagename='orion_shifted.im'
69 asvelocity If True, regrid spectral axis with respect to velocity, not frequency. If False,
70 regrid with respect to frequency. default: True
71 axes The pixel axes to regrid. Default value [-1] => all except Stokes. Ignored
72 if template is set equal to a reference code (in which case only the directional
73 axes are regridded). If specified, this should
74 be provided as an array. example axes=[0,1] (only regrid the first two axes, which
75 are normally the directional axes).
76 interpolation The interpolation method. One of 'nearest', 'linear', 'cubic'.
77 decimate Decimation factor for coordinate grid computation
78 replicate Replicate image rather than regrid?
79 overwrite"> Overwrite (unprompted) pre-existing output file?
81 The new coordinate system is defined by the template parameter, which can be:
83 * a recognized directional reference frame string. This will rotate the image and the coordinate system so that
84 the new reference frame's axes are aligned to the cardinal directions (left-right, up-down).
85 Rotation occurs about the center direction pixel. If this pixel is not the reference pixel,
86 a temporary copy of the original image is created and the coordinate system is adjusted so
87 the center direction pixel is the reference pixel. The coordinate system of the input image
88 is not modified and the output image's reference direction pixel is the center pixel.
89 Note that the conversion between one frame and another in general becomes less accurate
90 as distance from the output image's reference pixel increases. Before the rotation occurs, the
91 image is padded with masked pixels to ensure that all good pixels are used in the rotation (ie the
92 corners of the image are not cropped after the rotation). After the image is rotated, any masked slices
93 remaining along the edges of the image in the directional coordinate are cropped, so that there are
94 no masked slices in the directional coordinate along the edges of the final image.
95 * a {'csys': [valid coordinate system dictionary], 'shap': [int array describing the output shape]} dictionary.
96 This is normally obtained by first running regrid with template='get'. In this case imregrid returns the
97 necessary dictionary.
98 * 'get', which does not regrid but returns the template dictionary
99 for imagename, suitable for modification and reuse (see the point immediately above), or
100 * the name of an image from which to get the coordinate system and shape.
101 The input and template images must have the same
102 coordinate structure.
104 Regridding of complex-valued images is supported. The real and imaginary parts are
105 regridded independently and the resulting regridded pixel values are combined to
106 form the regridded, complex-valued image.
108 The argument {stfaf replicate} can be used to simply replicate pixels
109 rather than regridding them. Normally ({stfaf replicate=F}), for every
110 output pixel, its world coordinate is computed and the corresponding
111 input pixel found (then a little interpolation grid is generated). If
112 you set {stfaf replicate=T}, then what happens is that for every output
113 axis, a vector of regularly sampled input pixels is generated (based on
114 the ratio of the output and input axis shapes). So this just means the
115 pixels get replicated (by whatever interpolation scheme you use) rather
116 than regridded in world coordinate space. This process is much faster,
117 but its not a true world coordinate based regrid.
119 As decribed above, when {stfaf replicate} is False, a coordinate is
120 computed for each output pixel; this is an expensive operation. The
121 argument {stfaf decimate} allows you to decimate the computation of
122 that coordinate grid to a sparse grid, which is then filled in via fast
123 interpolation. The default for {stfaf decimate} is 10. The number of
124 pixels per axis in the sparse grid is the number of output pixels for
125 that axis divided by the decimation factor. A factor of 10 does pretty
126 well. You may find that for very non-linear coordinate systems (e.g.
127 very close to the pole) that you have to reduce the decimation factor.
128 You may also have to reduce the decimation factor if the number of pixels
129 in the output image along an axis to be regridded is less than about 50, or
130 the output image may be completely masked.
132 If one of the axes to be regridded is a spectral axis and asvelocity=T,
133 the axis will be regridded to match the velocity, not the frequency,
134 coordinate of the template coordinate system. Thus the output pixel
135 values will correspond only to the velocity, not the frequency, of the
136 output axis.
138 A variety of interpolation schemes are provided (only
139 the first three characters to be specified). The cubic interpolation
140 is substantially slower than linear, and often the improvement is
141 modest. By default linear interpolation is used.
143 If an image has per-plane beams and one attempts to regrid the spectral axis,
144 an exception is thrown.
146 RULES USED FOR GENERATING OUTPUT IMAGES IN SPECIFIC CASES
148 There are numerous rules governing the shape and coordinate system of the output
149 image depending on the input image, template image, and wheher default values of the
150 axes and shape parameters are used. They are enumerated below.
152 NOTE: If you want to be certain of what type of output you will get, it is highly
153 recommended you specify both axes and shape to avoid any ambiguity.
155 1. Rules governing Stokes axes
156 1.1. If the input image has no stokes axis, then the output image will have no stokes axis.
157 1.2. If the input image has a stokes axis, but the template image/coordinate system does not,
158 and if the default value of the shape parameter is used or if shape is specified and the
159 specified value for the length stokes axis in equal to the length of the input image
160 stokes axis, then all stokes in the input
161 image will be present in the output image
162 1.3. If the input image has a stokes axis, but the template image/coordinate system does not,
163 and if the value of the shape parameter is specified but the length of the resulting stokes
164 axis is not equal to the length of the input image's stokes axis, a failure will occur.
165 1.4. If the input image has a stokes axis, if the template parameter is an image name, and if the
166 template image has a degenerate stokes axis, if the axes parameter is not specified or is specified
167 but does not contain the input stokes axis number, and if the shape parameter is not specified, then
168 all stokes planes in the input image will be present in the output image.
169 1.5. If the input image has a stokes axis, if the template parameter is an image name, and if the
170 template image has a degenerate stokes axis, if the axes parameter is not specified or is specified
171 but does not contain the input stokes axis number, if the shape parameter is specified, and if the
172 specified length of the stokes axis is not equal to the length of the input stokes axis, then
173 a failure will occur.
174 1.6. If the input image has a stokes axis, if the template parameter is an image name, if the
175 template image has a degenerate stokes axis, if the axes parameter is specified contains the
176 input stokes axis number, then use the applicable rule of rules 1.7. and 1.8. for the template
177 image having a nondegenerate stokes axis.
178 1.7. If the input image has a stokes axis, if the template parameter is an image name, if the
179 template image has a nondegenerate stokes axis, and if axes is not specified or if it is, it contains
180 the input stokes axis number, then only the stokes parameters common to both the input image and
181 the template image will be present in the output image. If the input image and the template image
182 have no common stokes parameters, failure will occur. If shape is specified and the length of the
183 specified stokes axis is not equal to the number of common stokes parameters in the input image and
184 the template image, then failure will result.
185 1.8. If the input image has a stokes axis, if the template parameter is an image name, if the
186 template image has a nondegenerate stokes axis, and if axes is specified but does not contain the input
187 image stokes axis number, then all stokes present in the input image will be present in the output image.
188 If shape is also specified but the length of the specified stokes axis does not equal the length of
189 the input stokes axis, then failure will result.
191 2. Rules governing spectral axes
192 In all cases, if the shape parameter is specified, the spectral axis length must be consistent with what
193 one would normally expect in the special cases, or a failure will result.
194 2.1. If the input image does not have a spectral axis, then the output image will not have a spectral axis.
195 2.2. If the input image has a degenerate spectral axis, if the template parameter is an image name, and if the
196 template image has a spectral axis, if axes is not specified or if it is and does not
197 contain the input image spectral axis number, then the spectral coordinate of the input image is copied
198 to the output image and the output image will have a degenerate spectral axis.
199 2.3. If the input image has a degenerate spectral axis, if the template parameter is an image name, and if the
200 template image has a spectral axis, if axes is specified and it
201 contains the input image spectral axis number, then the spectral coordinate of the template image is copied
202 to the output image. If shape is not specified, the output image will have the same number of channels
203 as the input image. If shape is specified, the output image will have the number of channels as specified
204 in shape for the spectral axis. In these cases, the pixel and mask values for all spectral hyperplanes
205 will be identical; the regridded single spectral plane is simply replicated n times, where n is the
206 number of channels in the output image.
207 2.4. If the input image has a spectral axis, if the template parameter is an image name, and if the
208 template image does not have a spectral axis, if axes is not specified or if it is and does not
209 contain the input image spectral axis number, then the spectral coordinate of the input image is copied
210 to the output image and the output image will have the same number of channels as the input image.
211 2.5. If the input image has a spectral axis, if the template parameter is an image name, if the
212 template image does not have a spectral axis, if axes is specified it
213 contains the input image spectral axis number, then failure will result.
214 2.6. If the input image has a spectral axis, if the template parameter is an image name, if the
215 template image has a degenerate spectral axis, and if axes is unspecified or if it is but does not
216 contain the spectral axis number of the input image, the spectral coordinate of the input image is
217 copied to the output image and the output image will have the same number of channels as the input
218 image.
219 2.7. If the input image has a spectral axis, if the template parameter is an image name, if the
220 template image has a nondegenerate spectral axis, and if axes is unspecified or if it is and
221 contains the spectral axis number of the input image, regrid the spectral axis of the input to
222 match the spectral axis of the template.
224 IMPORTANT NOTE ABOUT FLUX CONSERVATION
225 in general regridding is inaccurate for images that the angular resolution is poorly
226 sampled. A check is done for such cases and a warning message is emitted if a beam present.
227 However, no such check is done if there is no beam present. To add a restoring beam to
228 an image, use ia.setrestoringbeam().
230 Basic Examples
232 # Regrid an image to the "B1950" or "GALACTIC" coordinate systems
234 imregrid(imagename="input.image", output="output.image", template="B1950")
235 imregrid(imagename="input.image", output="output.image", template="GALACTIC")
237 Note that when regridding to another coordinate system in the manner above, if the
238 input image's direction coordinate is already in the frame specified by template,
239 a straight copy of the image is made. No regridding is actually done.
241 # Obtain a template dictionary from an image and then use it to regrid another image
243 temp_dict = imregrid(imagename="target.image", template="get")
244 imregrid(imagename="input.image", output="output.image", template=temp_dict)
246 In this example, the template="get" option is used in the first command in order to
247 characterize the desired shape and coordinate system used, and a new dictionary,
248 temp_dict, is generated accordingly. This is then used when performing the actual
249 regridding of input.image in the second command.
252 More Advanced Examples
254 It is also possible to directly use a template image for regridding with imregrid.
255 For this to work reliably and predictably, the dimensionality (i.e. which
256 dimensions are present in an image) and the axis ordering of the input image must
257 be the same. The type and ordering of the axes of both the input and template
258 images can (and should) first be examined using the CASA imhead task. Any
259 necessary reordering of axes can be performed using the CASA imtrans task.
261 Unless the user explicitly specifies which dimensions to regrid using the axes
262 parameter (see the following example), imregrid will also attempt to regrid
263 degenerate axes (i.e. image axes of length one pixel). Stokes axes are never
264 regridded.
266 In the case where template is an image name and the default value of shape is specified,
267 the output image's shape will be the same as the template image's shape along the axes which
268 are regridded and the same as the input image's shape along the axes which are not regridded.
269 So for example, if the input image has a shape of [20, 30, 40] and the template image has a shape
270 of [10, 40, 70] and only axes=[0, 1], the output image will have a shape of [10, 40, 40]. If axes=[2],
271 the output image will have a shape of [20, 30, 70].
273 # Regrid input.image by directly using target.image as a template
275 imregrid(imagename="input.image", output="output.image", template="target.image", shape=[500,500,40,1])
277 In this example, it is assumed that the axis order of the input image is of the
278 form (direction_x, direction_y, spectral, Stokes), where 'direction_x' and 'direction_y'
279 are the directional coordinates on the sky (in some reference frame),
280 'spectral' is a velocity/frequency axis, and 'Stokes' contains polarization
281 information. In this example, input.image might typically be a data cube of
282 shape [100, 100, 40, 1]. Note that the default value of asvelocity (True) will be used so that
283 the spectral axis will be regridded to the same velocity system as that of the template image.
286 # Regrid only the first two axes of an image
288 Firstly, the user should inspect the type and ordering of the axes with imhead,
289 and then correct with imtrans if necessary.
291 imregrid(imagename="input.image", output="output.image", template="target.image", axes=[0,1])
293 The above command will regrid only the first two axes (normally the directional axes) of input.image and
294 leave all other axes unchanged. The output image will have the shape of the template image along the regridded
295 axes [0, 1] and the shape of the input image along the other axes since the shape parameter was not
296 explicitly specified.
299 # Regrid the third axis, considering velocity rather than frequency units
301 imregrid(imagename="input.image", output="output.image", template="target.image", axes=[2], asvelocity=True)
303 This example regrids the spectral axis (zero-based axis number 2) with respect to velocity because the asvelocity parameter
304 has been set to True. This is useful when eg, regridding a cube containing one spectral line to match the velocity coordinate
305 of another cube containing a different spectral line.
308 # Regrid the third axis, considering velocity rather than frequency units but first set the rest frequency
310 imhead("input.image", mode="put", hdkey="restfreq", hdvalue="110GHz")
311 imregrid(imagename="input.image", output="output.image", template="target.image", axes=[2], asvelocity=True)
313 The first command in this example uses the imhead task to set the value of the
314 image rest frequency to a value of 110GHz in input.image. The following
315 imregrid command then performs a frequency units regridding only of the third
316 axis listed (zero-based axis) (2), taking account of the input.image rest frequency in the input file.
319 """
321 _info_group_ = """analysis"""
322 _info_desc_ = """regrid an image onto a template image"""
324 def __call__( self, imagename='', template='get', output='', asvelocity=True, axes=[ int(-1) ], shape=[ int(-1) ], interpolation='linear', decimate=int(10), replicate=False, overwrite=False ):
325 schema = {'imagename': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'template': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'output': {'type': 'cStr', 'coerce': _coerce.to_str}, 'asvelocity': {'type': 'cBool'}, 'axes': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'shape': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'interpolation': {'type': 'cStr', 'coerce': _coerce.to_str}, 'decimate': {'type': 'cInt'}, 'replicate': {'type': 'cBool'}, 'overwrite': {'type': 'cBool'}}
326 doc = {'imagename': imagename, 'template': template, 'output': output, 'asvelocity': asvelocity, 'axes': axes, 'shape': shape, 'interpolation': interpolation, 'decimate': decimate, 'replicate': replicate, 'overwrite': overwrite}
327 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
328 _logging_state_ = _start_log( 'imregrid', [ 'imagename=' + repr(_pc.document['imagename']), 'template=' + repr(_pc.document['template']), 'output=' + repr(_pc.document['output']), 'asvelocity=' + repr(_pc.document['asvelocity']), 'axes=' + repr(_pc.document['axes']), 'shape=' + repr(_pc.document['shape']), 'interpolation=' + repr(_pc.document['interpolation']), 'decimate=' + repr(_pc.document['decimate']), 'replicate=' + repr(_pc.document['replicate']), 'overwrite=' + repr(_pc.document['overwrite']) ] )
329 task_result = None
330 try:
331 task_result = _imregrid_t( _pc.document['imagename'], _pc.document['template'], _pc.document['output'], _pc.document['asvelocity'], _pc.document['axes'], _pc.document['shape'], _pc.document['interpolation'], _pc.document['decimate'], _pc.document['replicate'], _pc.document['overwrite'] )
332 except Exception as exc:
333 _except_log('imregrid', exc)
334 raise
335 finally:
336 task_result = _end_log( _logging_state_, 'imregrid', task_result )
337 return task_result
339imregrid = _imregrid( )