 News |
FAQ
|
| Search
|
Home
|
| Getting Started | Documentation | Glish | Learn More | Programming | Contact Us |
|
| Version 1.9 Build 1488 |
|
| Package | general | |
| Module | images | |
| Tool | image |
| outfile | in | Output image file name | |
| Allowed: | String | ||
| Default: | unset | ||
| shape | in | Shape of output image | |
| Allowed: | Vector of integers | ||
| Default: | Input shape | ||
| csys | in | Coordinate System for output image | |
| Allowed: | Coordsys tool | ||
| Default: | Input CoordinateSystem | ||
| axes | in | The output pixel axes to regrid | |
| Allowed: | Vecor of integers | ||
| Default: | All | ||
| region | in | The region of interest | |
| Allowed: | Region tool | ||
| Default: | Whole image | ||
| mask | in | OTF mask | |
| Allowed: | Boolean LEL expression or mask region | ||
| Default: | None | ||
| method | in | The interpolation method | |
| Allowed: | String from 'nearest', 'linear', 'cubic' | ||
| Default: | 'linear' | ||
| decimate | in | Decimation factor for coordinate grid computation | |
| Allowed: | Integer | ||
| Default: | 10 | ||
| replicate | in | Replicate image rather than regrid ? | |
| Allowed: | T or F | ||
| Default: | F | ||
| doref | in | Turn on reference frame changes | |
| Allowed: | T or F | ||
| Default: | T | ||
| dropdeg | in | Drop degenerate axes | |
| Allowed: | T or F | ||
| Default: | F | ||
| overwrite | in | Overwrite (unprompted) pre-existing output file ? | |
| Allowed: | T or F | ||
| Default: | F | ||
| force | in | Force specified axes to be regridded | |
| Allowed: | T or F | ||
| Default: | F | ||
| async | in | Run asynchronously? | |
| Allowed: | Bool | ||
| Default: | !dowait | ||
This function regrids the current image onto a grid specified by the given Coordinate System. You can also specify the shape of the output image.
The Coordinate System must be given via a Coordsys tool. It is optional; if not specified, the Coordinate System from the input image (i.e. the one to which you are applying the regrid function) is taken. The order of the coordinates and axes in the output image is always the same as the input image. It simply 'finds' the relevant coordinate in the supplied Coordinate System in order to figure out the regridding parameters. The supplied Coordinate System must have at least as many coordinates as are required to accomodate the axes you are regridding (e.g. if you regrid the first two axes, and these belong to a Direction Coordinate, you need one Direction Coordinate in the supplied Coordinate System). Coordinates pertaining to axes that are not being regridded are supplied from the input image, not the give Coordinate System.
Reference changes are handled (e.g. J2000 to B1950, LSR to TOPO). In general, the conversion machinery attempts to work out how sophisticated it needs to be (e.g. am I regridding LSR to LSR or LSR to TOPO). However, it errs on the side of conservatism so that it can be that the conversion machine requires more information than it actually needs. For full frame conversions, one needs to know things like location on earth (e.g. observatory), direction of observation, and time of observation.
If you get the above errors and you are doing a frame conversion, then that means you must insert some extra information into the Coordinate System of your image. Most likely it's the time (coordsys.setepoch) and location (coordsys.settelescope) that are missing. If you get these errors and you know that you are not specifying a frame change (e.g. regrid LSR to LSR) then try setting doref=F. This will (silently) bypass all possible frame conversions. Note that if you are requesting a frame conversion and you set doref=F you are doing a bad thing (and you will get no warnings).
If you regrid a plane holding a Direction Coordinate and the units are Jy/pixel then the output is scaled to conserve flux (roughly; just one scale factor at the reference pixel is computed).
A variety of interpolation schemes are provided (you need only specify the first three characters to method). The cubic interpolation is substantially slower than linear, and often the improvement is modest. By default you get linear interpolation.
You specify the shape of the output image (shape) and which output axes you want to regrid (axes). Note that a Stokes axis cannot be regridded (you will get a warning if you try and do this).
The axes argument cannot be used to discard axes from the output image; it can only be used to specify which output axes are going to be regridded and which are not. Any axis that you are not regridding must have the same output shape as the input image shape for that axis.
The axes argument can also be used to specify the order in which the output axes are regridded. This may give you significant performance benefits. For example, imagine we are going to regrid a spectral-line cube of shape [512,512,1204] to shape [256,256,32]. If you specified axes=[1,2,3] then first, the Direction axes would be regridded for each of the 1024 pixels (and stored in a temporary image). Then each profile at each spatial location in the temporary image would be regridded to 32 pixels. You could speed this process up significantly by setting axes=[3,1,2]. In this case, first each profile would be regridded to 32 pixels, and then each plane of the 32 pixels would be regridded. Note that the order of axes does not affect the order of the shape argument. I.e. it should be given in the natural pixel axis order of the image [256,256,32] in both cases.
You can also specify a region-of-interest to be applied to the input image. If you do this, you need to be careful with the output shape for non-regridded axes (must match that of the region - use function boundingbox to find that out).
If outfile is given, the image is written to the specified disk file. If outfile is unset, the Image tool is associated with a temporary image. This temporary image may be in memory or on disk, depending on its size. When you destroy the Image tool (with the done function) this temporary image is deleted.
The argument replicate can be used to simply replicate pixels rather than regridding them. Normally (replicate=F), for every output pixel, its world coordinate is computed and the corresponding input pixel found (then a little interpolation grid is generated). If you set replicate=T, then what happens is that for every output axis, a vector of regularly sampled input pixels is generated (based on the ratio of the output and input axis shapes). So this just means the pixels get replicated (by whatever interpolation scheme you use) rather than regridded in world coordinate space. This process is much faster, but its not a true world coordinate based regrid.
As decribed above, when replicate is False, a coordinate is computed for each output pixel; this is an expensive operation. The argument decimate allows you to decimate the computation of that coordinate grid to a sparse grid, which is then filled in via fast interpolation. The default for decimate is 10. The number of pixels per axis in the sparse grid is the number of output pixels for that axis divided by the decimation factor. A factor of 10 does pretty well. You may find that for very non-linear coordinate systems (e.g. very close to the pole) that you have to reduce the decimation factor.
Sometimes it is useful to drop axes of length one (degenerate axes). Use the dropdeg argument if you want to do this. It will discard the axes from the input image. Therefore the output shape and Coordinate System that you supply must be consistent with the input image after the degenerate axes are dropped.
Argument force can be used to force all specified axes to be regridded, even if the algorithm determines that they don't need to be (because the input and output coordinate information is identical).
There is a useful function setreferencelocation that you can use to keep a specific world coordinate in the center of an image when regridding (see example below).
The output pixel mask will be good (T) unless the regridding failed to find a value for that output pixel in which case it will be bad (F). For example, if the total input mask (default input pixel mask plus OTF mask) for all of the relevant input pixels were masked bad then the output pixel would be masked bad (F).
Multiple axis Coordinates limitation - Some cooordinates pertain to more than one axis. E.g. a Direction Coordinate holds longitude and latitude. A Linear Coordinate can also hold many axes. When you regrid *any* axis from a Coordinate which holds multiple axes, you must fully specify the coordinate information for all axes in that Coordinate in the Coordinate System that you provide. For example, you have a Linear Coordinate with two axes and you want to regrid axis one only. In the Coordinate System you provide, the coordinate information for axis two (not being regridded) must correctly be a copy from the input coordinate system (it won't be filled in for you).
- imr := image('radio.image')
- imo := image('optical.image')
- cs := imo.coordsys();
- imrr := imr.regrid(outfile='radio.regridded', csys=cs,
shape=imo.shape())
- imrr.view()
- cs.done()
- imr.done()
- imo.done()
In this example, we regrid a radio image onto the grid of an optical image - this probably (if the optical FITS image was correctly labelled !!) will involve a projection change (optical images are usually TAN projection, radio usually SIN).
- im := image('radio.image')
- cs := im.coordsys();
- cs.referencecode('dir')
J2000
- cs.setreferencecode(value='B1950', type='dir', adjust=T)
- im3 := im1.regrid(outfile='radio.regridded', csys=cs,
+ shape=im2.shape())
In this example, we regrid a radio image from J2000 to B1950. This is accomplished by first recovering the Coordinate System into a Coordsys tool, manipulating the reference code with that tool, and then supplying the new Coordinate System to the regrid function.
- im := imagemaketestimage('zz')
- cs := im.coordsys();
-
- p := im.shape() / 2.0
- p +:= 10;
- refval := im.toworld(pixel=p, format='n') # Location of interest
- inc := cs.increment(quant=F)
- inc /:= 2.0; # Halve increment
- cs.setincrement(value=inc) # Set increment
- shp := im.shape() * 2; # Double shape
- refpix := ((shp-1))/2.0 + 1; # New ref pix
- cs.setreferencelocation(pixel=refpix, world=refval) # Center image on location of interest
-
- imr := im.regrid(csys=cs, shape=shp) # Regrid
- cs.done()
- imagedones()