TRANNDF- Transforms a list of images by resampling

Description:

This application performs the arbitrary transformation of a list of images. The output images are calculated by resampling the data of the input images. Output array elements are set to the bad value if their inverse-transformed coordinates lie outside the corresponding input image's coordinate limits. Many images can be resampled with a single invocation of TRANNDF, but it is the user's responsibility to ensure that they are resampled into the same coordinate system if they are subsequently to be combined or compared on a pixel-by-pixel basis.

Images processed by CCDPACK are resampled in one of two ways, depending on the value of the USEWCS parameter.

If USEWCS is TRUE then they are resampled from their Pixel coordinates into their Current attached coordinate system (this is the default). Since the resampling means that a 1 x 1 square in the Current coordinates will represent one pixel in the output image, the Current coordinate system must be of an appropriate size (so for instance resampling into SKY coordinates is not suitable because they have units of radians). The Current coordinate system will typically have been added by the CCDPACK REGISTER or WCSREG applications, and be labelled 'CCD_REG' or 'CCD_WCSREG' accordingly - if it has another label (domain) a warning will be issued but resampling will proceed. A copy of the original PIXEL coordinate system will be retained in the WCS component of the new image under the name CCD_OLDPIXEL; this can be useful for transforming positions back into the pre-transformation coordinate system.

If USEWCS is set to FALSE, then the resampling will take place according to the TRANSFORM structure stored in the .MORE.CCDPACK extension of the file. This option exists chiefly for compatibility with older versions of CCDPACK.

Usage:

tranndf in out [method]

Parameters:

CONSERVE = _LOGICAL (Read)

If CONSERVE is TRUE, the output values are normalised by the ratio of the output-to-input pixel areas. In other words this conserves flux. If CONSERVE is FALSE, there is no normalisation. Flux can only be conserved if the transformation is linear, so that even if CONSERVE is TRUE, flux will be incorrectly conserved if the transformation is of a non-linear nature. [TRUE]

IN = NDF (Read)

A list of image names whose data are to be transformed. The image names should be separated by commas and may include wildcards.

INEXT = _LOGICAL (Read)

If TRUE then the transformation which is to be applied to the image is stored in the image's CCDPACK extension (.MORE.CCDPACK.TRANSFORM). If FALSE then a transformation structure must be supplied via the parameter TRANSFORM. This transformation is then applied to the list of images. [TRUE]

LBOUND() = _INTEGER (Read)

If SHAPE is "SPECIFY" then this parameter specifies the lower pixel-index bounds of all the output images. The number of values should equal the maximum number of dimensions of the input images. The suggested defaults are the lower bounds generated by the SHAPE="AUTO" option for the first image. These bounds are probably small enough to ensure that all the transformed data (of the first image) will appear in the output image. [Dynamic default]

LOGFILE = FILENAME (Read)

Name of the CCDPACK logfile. If a null (!) value is given for this parameter then no logfile will be written, regardless of the value of the LOGTO parameter.

If the logging system has been initialised using CCDSETUP then the value specified there will be used. Otherwise, the default is "CCDPACK.LOG". [CCDPACK.LOG]

LOGTO = LITERAL (Read)

Every CCDPACK application has the ability to log its output for future reference as well as for display on the terminal. This parameter controls this process, and may be set to any unique abbreviation of the following:

• TERMINAL - Send output to the terminal only

• LOGFILE - Send output to the logfile only (see the LOGFILE parameter)

• BOTH - Send output to both the terminal and the logfile

• NEITHER - Produce no output at all

If the logging system has been initialised using CCDSETUP then the value specified there will be used. Otherwise, the default is "BOTH". [BOTH]

METHOD = LITERAL (Read)

The interpolation method used to resample the input image data arrays. Permitted values are "NEAREST" for nearest-neighbour, and "LININT" for linear interpolation. [NEAREST]

OUT = LITERAL (Write)

Names of the output - transformed - images. These may be specified as list of comma separated names, using indirection if required, or, as a single modification element (of the input names). The simplest modification element is the asterisk "*" which means call each of the output images the same name as the corresponding input images. So:

IN > *
OUT > *

signifies that all the images in the current directory should be used and the output images should have the same names. Other types of modification can also be used, such as,

OUT > *-TRN

which means call the output images the same as the input images but add -TRN to the end of the names. Replacement of a specified string with another in the output file names can also be used:

OUT > *|RAW|RES|

this replaces the string RAW with RES in any of the output names.

SHAPE = LITERAL (Read)

The method to be used to determine the SHAPE of the output images. Can take one of the values "AUTO", "SAME", "SPECIFY". With the meanings.

• AUTO - automatically determine the bounds of the output images such that all of the input data appears. This is achieved by transforming test points along the current bounds so assumes that the transformation will behave reasonably.

• SAME - set the output image bounds to those of the corresponding input images.

• SPECIFY - you will specify a single set of bounds for all the output images. (See the LBOUND and UBOUND parameters.) [AUTO]

TITLE = LITERAL (Read)

Title for the output images. [Output from TRANNDF]

TRANSFORM = TRN (Read)

If INEXT is FALSE then this parameter specifies the transformation structure. This includes the file name and the HDS object. For example, DISTORT.MAPPING would use the TRANSFORM structure called MAPPING in the HDS file DISTORT. Normally the object name is TRANSFORM. The structure must contain both the forward and inverse mappings. This transform if supplied acts on all the input images.

UBOUND() = _INTEGER (Read)

If SHAPE is "SPECIFY" then this parameter specifies the upper pixel-index bounds of all the output images. The number of values should equal the maximum number of dimensions of the input images. The suggested defaults are the upper bounds generated by the SHAPE="AUTO" option for the first image. These bounds are probably large enough to ensure that all the transformed data (of the first image) will appear in the output image. [Dynamic default]

USEWCS = _LOGICAL (Read)

If TRUE then the transformation which is to be applied to the image is stored in the image's WCS extension as an attached coordinate system. If FALSE then the transformation is either stored as a TRN structure in the image's CCDPACK extension (.MORE.CCDPACK.TRANSFORM), or is supplied by the user (see the INEXT parameter). [TRUE]

Examples:

tranndf '*' '*-resamp' reset

This transforms all the images in the current directory from pixel coordinates to their Current coordinate system. It uses nearest-neighbour resampling and conserves the flux levels (assuming that the transformation is linear). The output images are of a size such that all the input pixels have contributed.

tranndf curved straight linint shape=same

As above, except linear interpolation is used, and the straight array uses the bounds of curved.

tranndf 'a119*' '*s' inext=false transform=proj.merc shape=bounds lbound='[1,-20]' ubound='[256,172]'

This transforms the images called a119*, using the transformation structure merc in the HDS file called proj, into images called a119*s. It uses nearest-neighbour resampling. All the output images have size 256 x 192 pixels and origin (1,-20).

See also :

``Data resampling''.

Behaviour of parameters :

Most parameters retain their current value as default. The "current" value is the value assigned on the last run of the application. If the application has not been run then the "intrinsic" defaults, as shown in the parameter help, apply. The exceptions to this rule are:

• LBOUND - always uses a dynamic default

• UBOUND - always uses a dynamic default

• TITLE - always "Output from TRANNDF"

Retaining parameter values has the advantage of allowing you to define the default behaviour of the application but does mean that additional care needs to be taken when using the application after a break of sometime. The intrinsic default behaviour of the application may be restored by using the RESET keyword on the command line.

Certain parameters (LOGTO and LOGFILE) have global values. These global values will always take precedence, except when an assignment is made on the command line. Global values may be set and reset using the CCDSETUP and CCDCLEAR commands.

Implementation Status:

• Flux conservation can only be applied to constant-determinant or linear transformations. It is currently impossible to tell whether an AST Mapping is linear, but in the expectation that it is (most of them are, and most of the rest very nearly are), it is turned on, without a warning, by default.

• The NDF components are processed by this application as follows:

• AXES, LABEL, UNITS, HISTORY, and extensions are merely propagated.

• QUALITY is not derived from the input NDF for a linearly interpolated NDF. The DATA and VARIANCE arrays are resampled.

• If USEWCS is TRUE, then the NDF WCS component is updated and propagated.

• Bad pixels, including automatic quality masking, are supported.

• All non-complex numeric data types are supported.

• There can be an arbitrary number of NDF dimensions.