KPG1_ASGET

Gets an AST FrameSet from the WCS component of an NDF

Description:

This routine determines the axes to be used from an NDF and returns a FrameSet representing the WCS information in the NDF.

Each axis of the supplied NDF is checked to see if it is significant (i.e. has a size greater than 1). The index of each significant axis is returned in SDIM, and the bounds of the axis are returned in SLBND and SUBND. If EXACT is .TRUE., an error is reported if the number of significant axes is not exactly NDIM. This mode is intended for case where (say) the user has supplied a single plane from a three-dimensional data cube to an application that requires a two-dimensional array.

If EXACT is .FALSE. an error is only reported if the number of significant dimensions is higher than NDIM. If there are fewer than NDIM significant dimensions then the insignificant dimensions are used (starting from the lowest) to ensure that the required number of dimensions are returned. This mode is intended for cases where (say) the user supplies a one-dimensional data stream to an application that requires a two-dimensional array.

The GRID Frame (i.e. the Base Frame) obtained from the NDFs WCS component is modified so that it has NDIM axes corresponding to the axes returned in SDIM (the value 1.0 is used for the other axes).

Likewise, the PIXEL Frame obtained from the NDFs WCS component is modified so that it has NDIM axes corresponding to the axes returned in SDIM (the lower pixel bound is used for the other axes). The original PIXEL Frame is retained, but with Domain changed to NDF_PIXEL.

If TRIM is .TRUE., then the Current Frame obtained from the NDFs WCS component is also modified so that it has NDIM axes. If the original Current Frame has more than NDIM axes, then the axes to use are obtained from the environment using parameter USEAXIS. A new Current Frame is then made by picking these axes from the original Current Frame, assigning the value AST__BAD to the axes which have not been chosen.

If the original Current Frame has fewer than NDIM axes, then simple axes are added into the new Current Frame to make up a total of NDIM. These axes are given the value 1.0.

Various environment parameters may be used to obtain options, etc. The names of these parameters are hard-wired into this subroutine in order to ensure conformity between applications.

Invocation

CALL KPG1_ASGET( INDF, NDIM, EXACT, TRIM, REQINV, SDIM, SLBND, SUBND, IWCS, STATUS )

Arguments

INDF = INTEGER (Given)
The identifier for the NDF.
NDIM = INTEGER (Given)
The number of dimensions required by the application.
EXACT = LOGICAL (Given)
Must the NDF have exactly NDIM significant axes? Otherwise it is acceptable for the NDIM axes to include some insignificant axes.
TRIM = LOGICAL (Given)
Should the returned FrameSet be trimmed to ensure that the Current Frame has NDIM axes? Otherwise, the Current Frame read from the NDF is not changed.
REQINV = LOGICAL (Given)
Is the inverse mapping (from Current Frame to Base Frame) required? If it is, an error is reported if the inverse mapping is not available. REQINV should be supplied .TRUE. in most cases.
SDIM( NDIM ) = INTEGER (Returned)
The indices of the significant dimensions.
SLBND( NDIM ) = INTEGER (Returned)
The lower pixel index bounds of the significant dimensions. These are stored in the same order as the indices in SDIM.
SUBND( NDIM ) = INTEGER (Returned)
The upper pixel index bounds of the significant dimensions. These are stored in the same order as the indices in SDIM.
IWCS = INTEGER (Returned)
An AST pointer to the WCS FrameSet. Returned equal to AST__NULL if an error occurs. The Base Frame is an NDIM-dimensional GRID Domain.
STATUS = INTEGER (Given and Returned)
The global status.

Notes:

Environment Parameters :

USEAXIS = LITERAL (Read)
A set of NDIM axes to be selected from the Current Frame. Each axis can be specified either by giving its index within the Current Frame in the range 1 to the number of axes in the Frame, or by giving its symbol. This parameter is only accessed if TRIM is .TRUE. and the original Current Frame in the supplied NDF has too many axes. The dynamic default selects the axes with the same indices as the selected NDF axes. The value should be given as a GRP group expression, with default control characters.