image.rotate - Function

rotate the direction coordinate axes attached to the image and regrid the image to the rotated Coordinate System

Synopsis
rotate(outfile, shape, pa, region, mask, method, decimate, replicate, overwrite, async)

Arguments

outfile	in	Output image file name
		Allowed:	String
		Default:	unset
shape	in	Shape of output image
		Allowed:	Vector of integers
		Default:	Input shape
pa	in	Angle by which to rotate
		Allowed:	Quantity, string, numeric
		Default:	0deg
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:	'cubic'
decimate	in	Decimation factor for coordinate grid computation
		Allowed:	Integer
		Default:	0
replicate	in	Replicate image rather than regrid ?
		Allowed:	T or F
		Default:	F
overwrite	in	Overwrite (unprompted) pre-existing output file ?
		Allowed:	T or F
		Default:	F
async	in	Run asynchronously?
		Allowed:	Bool
		Default:	!dowait

Returns
Image tool or fail

Description

This function rotates two axes of an image. These axes are either those associated with a Direction coordinate or with a Linear coordinate. The Direction coordinate takes precedence. If rotating a Linear coordinate, it must hold precisely two axes.

The method is that the Coordinate is rotated and then the input image is regridded to the rotated Coordinate System.

If the image brightness 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. By default you get cubic interpolation.

You can specify the shape of the output image (shape). However, all axis that are not regrided retain the same output shape as the input image shape for that axis. Only the direction coordinate axes are regridded.

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 0 (no decimation). 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.

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

Example

- im := imagemaketestimage();
- im.view(axislabels=T);
- imr:=im.rotate(pa=45);
- imr.view(axislabels=T);

In this example, we rotate the direction coordinate axes (RA/Dec) of a test image by 45 degress and regrid the image onto the axes. The viewer displays the before and after images.

Next: image.rename - Function Up: image - Tool Previous: image.regrid - Function Contents Index

	Package	general
	Module	images
	Tool	image