kappa: Add new parameter ALIGNREF to wcsalign and wcsmosaic

This parameter is a boolean which if set true causes alignment to be
performed in the coordinate system defined by the reference NDF. By
default, alignment occurs in the coordinate system defined by the AST
attributes AlignSystem, AlignStdOfRest, AlignTimeScale, etc, all of which
default to fixed values (ICRS/Wavelength/MJD for AlignSystem,
Heliocentrix for AlignStdOfRest, etc).

So for instance if you have two images which both have (az,el) axes but
which were taken at different times, then by default they will be aligned
in ICRS, meaning that stars will be align properly in the result. If
ALIGNREF is set TRUE, then they will be aligned in (az,el) (the system of
the reference NDF), meaning that stars will not be aligned propely since
they will have moved in (az,el) due to the different times of the two
images.

applications/kappa/kappa.ifd.in

@@ -18359,6 +18359,15 @@ iraf! {
             helpkey *
          }
 
+         parameter alignref {
+            type _LOGICAL
+            vpath DEFAULT
+            ppath CURRENT DEFAULT
+            prompt {Align using the WCS attributes of the reference?}
+            helpkey *
+            default FALSE
+         }
+
          parameter conserve {
             type _LOGICAL
             vpath DEFAULT
@@ -18538,6 +18547,15 @@ iraf! {
             helpkey *
          }
 
+         parameter alignref {
+            type _LOGICAL
+            vpath DEFAULT
+            ppath CURRENT DEFAULT
+            prompt {Align using the WCS attributes of the reference?}
+            helpkey *
+            default FALSE
+         }
+
          parameter conserve {
             type _LOGICAL
             vpath DYNAMIC

applications/kappa/kappa.news.in

@@ -23,6 +23,17 @@
       -  A new parameter QVALUE can be used to store a constant integer
       value in the range 0 to 255 in the QUALITY component for all pixels.
 
+   o WCSALIGN
+
+      - A new parameter ALIGNREF can be used to control the coordinate
+      system in which the input NDFs are aligned.
+
+   o WCSMOSAIC
+
+      - A new parameter ALIGNREF can be used to control the coordinate
+      system in which the input NDFs are aligned.
+
+
 1 KAPPA_Version_2.1
 
    A new release of KAPPA (2.1) is available.  The main

applications/kappa/kapsub/kps1_wala7.f

@@ -1,4 +1,5 @@
-      SUBROUTINE KPS1_WALA7( INDF1, IWCSR, MAP, MAP4, ORIGIN, STATUS )
+      SUBROUTINE KPS1_WALA7( INDF1, REFALN, IWCSR, MAP, MAP4, ORIGIN,
+     :                       STATUS )
 *+
 *  Name:
 *     KPS1_WALA7
@@ -10,7 +11,7 @@ SUBROUTINE KPS1_WALA7( INDF1, IWCSR, MAP, MAP4, ORIGIN, STATUS )
 *     Starlink Fortran 77
 
 *  Invocation:
-*     CALL KPS1_WALA7( INDF1, IWCSR, MAP, MAP4, ORIGIN, STATUS )
+*     CALL KPS1_WALA7( INDF1, REFALN, IWCSR, MAP, MAP4, ORIGIN, STATUS )
 
 *  Description:
 *     This routine finds the Mapping from input pixel co-ordinates to
@@ -21,6 +22,15 @@ SUBROUTINE KPS1_WALA7( INDF1, IWCSR, MAP, MAP4, ORIGIN, STATUS )
 *  Arguments:
 *     INDF1 = INTEGER (Given)
 *        Identifier for the input NDF.
+*     REFALN = LOGICAL (Given)
+*        If .TRUE., the WCS attributes in the current Frame of each NDF
+*        (both reference NDF and input NDFs) are set so that alignment
+*        occurs in the System, Standard of Rest, Time Scale, etc, of the
+*        reference NDF. This is done by setting each AST "AlignXxx"
+*        attribute in the current Frame to the value of the corresponding
+*        "Xxx" attribute in the current Frame of the reference NDF. If
+*        FALSE, the existing values of teh "AlignXxx" attributes are left
+*        unchanged.
 *     IWCSR = INTEGER (Given)
 *        AST pointer for the WCS FrameSet from the reference NDF.
 *     MAP = INTEGER (Returned)
@@ -69,6 +79,8 @@ SUBROUTINE KPS1_WALA7( INDF1, IWCSR, MAP, MAP4, ORIGIN, STATUS )
 *     6-JAN-2008 (DSB):
 *        Correct conversion from pixel index limits to pixel coordinate
 *        limits before checking for a linear mapping.
+*     1-DEC-2014 (DSB):
+*        Added argument REFALN.
 *     {enter_further_changes_here}
 
 *-
@@ -84,6 +96,7 @@ SUBROUTINE KPS1_WALA7( INDF1, IWCSR, MAP, MAP4, ORIGIN, STATUS )
 
 *  Arguments Given:
       INTEGER INDF1
+      LOGICAL REFALN
       INTEGER IWCSR
 
 *  Arguments Returned:
@@ -108,6 +121,7 @@ SUBROUTINE KPS1_WALA7( INDF1, IWCSR, MAP, MAP4, ORIGIN, STATUS )
       INTEGER IPIX1              ! Index of PIXEL Frame in input NDF FrameSet
       INTEGER IPIXR              ! Index of PIXEL Frame in ref. NDF FrameSet
       INTEGER IWCS1              ! AST pointer to input WCS FrameSet
+      INTEGER IWCSRC             ! Temp copy of the reference WCS FrameSet
       INTEGER LBND( NDF__MXDIM ) ! Lower bounds of input NDF
       INTEGER N                  ! Nearest integer to fit coefficient
       INTEGER NDIM1              ! No. of pixel axes in input NDF
@@ -153,10 +167,20 @@ SUBROUTINE KPS1_WALA7( INDF1, IWCSR, MAP, MAP4, ORIGIN, STATUS )
       CALL CHR_APPND( AST_GETC( IWCS1, 'DOMAIN', STATUS ), DOMLST, IAT )
       CALL CHR_APPND( ',PIXEL', DOMLST, IAT )
 
+*  If required, set the alignment properties of the current Frame to match
+*  the main properties of the reference frame.
+      IF( REFALN ) THEN
+         CALL KPG1_ASALN( IWCS1, IWCSR, STATUS )
+         IWCSRC = AST_COPY( IWCSR, STATUS )
+         CALL KPG1_ASALN( IWCSRC, IWCSR, STATUS )
+      ELSE
+         IWCSRC = AST_CLONE( IWCSR, STATUS )
+      END IF
+
 *  Merge the reference WCS FrameSet into this NDFs WCS FrameSet, aligning
 *  them in a suitable Frame (the current Frame of IWCSR by preference, or
 *  the first possible domain in the above list otherwise).
-      CALL KPG1_ASMRG( IWCS1, IWCSR, DOMLST( : IAT ), .FALSE., 4,
+      CALL KPG1_ASMRG( IWCS1, IWCSRC, DOMLST( : IAT ), .FALSE., 4,
      :                 STATUS )
 
 *  Get the simplified Mapping from input pixel Frame to reference (i.e.

applications/kappa/kapsub/kps1_wmos0.f

@@ -1,5 +1,5 @@
-      SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
-     :                       MAPS, IWCSR, STATUS )
+      SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, REFALN, LBND,
+     :                       UBND, USEVAR, MAPS, IWCSR, STATUS )
 *+
 *  Name:
 *     KPS1_WMOS0
@@ -12,8 +12,8 @@ SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
 *     Starlink Fortran 77
 
 *  Invocation:
-*     CALL KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR, MAPS,
-*                      IWCSR, STATUS )
+*     CALL KPS1_WMOS0( INDFR, IGRP, NDIM, REFALN, LBND, UBND, USEVAR,
+*                      MAPS, IWCSR, STATUS )
 
 *  Description:
 *     This routine extracts the global information required by WCSMOSAIC
@@ -24,8 +24,17 @@ SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
 *        The NDF identifier for the reference NDF.
 *     IGRP = INTEGER (Given)
 *        The GRP identifier for the group containing the input NDF names.
-*     NDIM
+*     NDIM = INTEGER (Given)
 *        The number of pixel axes in the output NDF.
+*     REFALN = LOGICAL (Given)
+*        If .TRUE., the WCS attributes in the current Frame of each NDF
+*        (both reference NDF and input NDFs) are set so that alignment
+*        occurs in the System, Standard of Rest, Time Scale, etc, of the
+*        reference NDF. This is done by setting each AST "AlignXxx"
+*        attribute in the current Frame to the value of the corresponding
+*        "Xxx" attribute in the current Frame of the reference NDF. If
+*        FALSE, the existing values of teh "AlignXxx" attributes are left
+*        unchanged.
 *     LBND( NDIM ) = INTEGER (Returned)
 *        The lower pixel index bounds for the output NDF so that the output NDF just
 *        encompasses all the input data.
@@ -51,8 +60,7 @@ SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
 
 *  Copyright:
 *     Copyright (C) 2005 Particle Physics & Astronomy Research Council.
-*     Copyright (C) 2007 Science & Technology Facilities Council.
-*     Copyright (C) 2012 Science & Technology Facilities Council.
+*     Copyright (C) 2007,2012,2014 Science & Technology Facilities Council.
 *     All Rights Reserved.
 
 *  Licence:
@@ -101,6 +109,8 @@ SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
 *     15-OCT-2012 (DSB):
 *        Allow 2D input images to align with 3D reference images, if the
 *        extra reference axis is a degenerate pixel axis.
+*     1-DEC-2014 (DSB):
+*        Added argument REFALN.
 *     {enter_further_changes_here}
 
 *-
@@ -119,6 +129,7 @@ SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
       INTEGER INDFR
       INTEGER IGRP
       INTEGER NDIM
+      LOGICAL REFALN
 
 *  Arguments Returned:
       INTEGER LBND( NDIM )
@@ -153,6 +164,7 @@ SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
       INTEGER IPIXR              ! Index of PIXEL Frame in ref. NDF FrameSet
       INTEGER IU                 ! Integer upper bound
       INTEGER IWCS1              ! AST pointer to input WCS FrameSet
+      INTEGER IWCSRA             ! Reference WCS with "AlignXxx" atts set
       INTEGER J                  ! Axis count
       INTEGER LBND1( NDF__MXDIM )! Lower bounds of input NDF
       INTEGER LBNDR( NDF__MXDIM )! Lower bounds of reference NDF
@@ -201,8 +213,17 @@ SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
 
       END IF
 
+*  If required, set the alignment properties of the current Frame to match
+*  the main properties of the current frame.
+      IF( REFALN ) THEN
+         IWCSRA = AST_COPY( IWCSR, STATUS )
+         CALL KPG1_ASALN( IWCSRA, IWCSR, STATUS )
+      ELSE
+         IWCSRA = AST_CLONE( IWCSR, STATUS )
+      END IF
+
 *  Find the index of the PIXEL Frame in the reference NDF.
-      CALL KPG1_ASFFR( IWCSR, 'PIXEL', IPIXR, STATUS )
+      CALL KPG1_ASFFR( IWCSRA, 'PIXEL', IPIXR, STATUS )
 
 *  Get the pixel index bounds of the reference NDF.
       CALL NDF_BOUND( INDFR, NDF__MXDIM, LBNDR, UBNDR, NDIMR,
@@ -234,6 +255,10 @@ SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
 *  Get the WCS FrameSet from the current input NDF.
          CALL KPG1_GTWCS( INDF1, IWCS1, STATUS )
 
+*  If required, set the alignment properties of the current Frame to match
+*  the properties of the current frame in the reference NDF.
+         IF( REFALN ) CALL KPG1_ASALN( IWCS1, IWCSRA, STATUS )
+
 *  Find the index of the PIXEL Frame in the input NDF.
          CALL KPG1_ASFFR( IWCS1, 'PIXEL', IPIX1, STATUS )
 
@@ -242,7 +267,7 @@ SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
 
 *  Store the list of preferences for the alignment Frame Domain (current
 *  FRAME in the input NDF, followed by PIXEL). KPG1_ASMRG always uses the
-*  Domain of the second FrameSet (IWCSR) first, so we do not need to include
+*  Domain of the second FrameSet (IWCSRA) first, so we do not need to include
 *  it in this list.
          DOMLST = ' '
          IAT = 0
@@ -251,9 +276,9 @@ SUBROUTINE KPS1_WMOS0( INDFR, IGRP, NDIM, LBND, UBND, USEVAR,
          CALL CHR_APPND( ',PIXEL', DOMLST, IAT )
 
 *  Merge the reference WCS FrameSet into this NDFs WCS FrameSet, aligning
-*  them in a suitable Frame (the current Frame of IWCSR by preference, or
+*  them in a suitable Frame (the current Frame of IWCSRA by preference, or
 *  the first possible domain in the above list otherwise).
-         CALL KPG1_ASMRG( IWCS1, IWCSR, DOMLST( : IAT ), .TRUE., 4,
+         CALL KPG1_ASMRG( IWCS1, IWCSRA, DOMLST( : IAT ), .TRUE., 4,
      :                    STATUS )
 
 *  Get the simplified Mapping from input pixel Frame to reference (i.e.

applications/kappa/libkappa/wcsalign.f

@@ -79,6 +79,57 @@ SUBROUTINE WCSALIGN( STATUS )
 *        region is used. High accuracy is paid for by larger run times.
 *        A value of zero prevents any linear approximations being used -
 *        each pixel position is transformed explicitly. [0.05]
+*     ALIGNREF = _LOGICAL (Read)
+*        Determines the coordinate system in which each input NDF is
+*        aligned with the reference NDF. If TRUE, alignment is performed
+*        in the coordinate system described by the current Frame of the WCS
+*        FrameSet in the reference NDF. If FALSE, alignment is performed
+*        in the coordinate system specified by the following set of WCS
+*        attributes in the reference NDF: AlignSystem AlignStdOfRest,
+*        AlignOffset, AlignSpecOffset, AlignSideBand, AlignTimeScale. The
+*        AST library provides fixed defaults for all these. So for
+*        instance, AlignSystem defaults to ICRS for celestial axes and
+*        Wavelength for spectral axes, meaning that celestial axes will
+*        be aligned in ICRS and spectral axes in wavelength, by default.
+*        Similarly, AlignStdOfRest defaults to Heliocentric, meaning that
+*        by default spectral axes will be aligned in the Heliocentric rest
+*        frame.
+*
+*        As an example, if you are aligning two spectra which both use
+*        radio velocity as the current WCS, but which have different rest
+*        frequencies, then setting ALIGNREF to TRUE will cause alignment
+*        to be performed in radio velocity, meaning that the differences
+*        in rest frequency are ignored. That is, a channel with 10 Km/s
+*        in the input is mapping onto the channel with 10 km/s in the output.
+*        If ALIGNREF is FALSE (and no value has been set for the AlignSystem
+*        attribute in the reference WCS), then alignment will be performed
+*        in wavelength, meaning that the different rest frequencies cause
+*        an additional shift. That is, a channel with 10 Km/s in the input
+*        will be mapping onto which ever output channel has the same
+*        wavelength, taking into account the different rest frequencies.
+*
+*        As another example, consider aligning two maps which both have
+*        (azimuth,elevation) axes. If ALIGNREF is TRUE, then any given
+*        (az,el) values in one image will be mapped onto the exact same
+*        (az,el) values in the other image, regardless of whether the
+*        two images were taken at the same time. But if ALIGNREF is FALSE,
+*        then a given (az,el) value in one image will be mapped onto
+*        pixel that has the same ICRS coordinates in the other image
+*        (since AlignSystem default to ICRS for celestial axes). Thus any
+*        different in the observation time of the two images will result
+*        in an additional shift.
+*
+*        As yet another example, consider aligning two spectra which are
+*        both in frequency with respect to the LSRK, but which refer to
+*        different points on the sky. If ALIGNREF is TRUE, then a given
+*        LSRK frequency in one spectra will be mapped onto the exact same
+*        LSRK frequency in the other image, regardless of the different sky
+*        positions. But if ALIGNREF is FALSE, then a given input frequency
+*        will first be converted to Heliocentric frequency (the default
+*        value for AlignStdOfRest is "Heliocentric"), and will be mapped
+*        onto the output channel that has the same Heliocentric frequency.
+*        Thus the differecen in sky positions will result in an additional
+*        shift.   [FALSE]
 *     CONSERVE = _LOGICAL (Read)
 *        If set TRUE, then the output pixel values will be scaled in
 *        such a way as to preserve the total data value in a feature on
@@ -455,6 +506,8 @@ SUBROUTINE WCSALIGN( STATUS )
 *        Allow an ACC value of zero to be supplied.
 *     6-DEC-2013 (DSB):
 *        No longer any reason prevent Gauss kernel being used with REBIN=NO.
+*     1-DEC-2014 (DSB):
+*        Added parameter ALIGNREF.
 *     {enter_further_changes_here}
 
 *-
@@ -514,6 +567,7 @@ SUBROUTINE WCSALIGN( STATUS )
       LOGICAL ISECT              ! Do 2 NDF intersect?
       LOGICAL MORE               ! Continue looping?
       LOGICAL REBIN              ! Create output pixels by rebinning?
+      LOGICAL REFALN             ! Use ref. to define alignment properties?
       LOGICAL SAME               ! Do 2 NDF identifier refer to the same NDF?
       REAL ERRLIM                ! Positional accuracy in pixels
       REAL WLIM                  ! Minimum good output weight
@@ -548,6 +602,10 @@ SUBROUTINE WCSALIGN( STATUS )
 *  Get the associated WCS FrameSet.
       CALL KPG1_GTWCS( INDFR, IWCSR, STATUS )
 
+*  See if the reference NDF is to be used to define the cordinate system
+*  in which alignment will occur.
+      CALL PAR_GET0L( 'ALIGNREF', REFALN, STATUS )
+
 *  Get the dimensionality and pixel bounds of the reference NDF.
       CALL NDF_BOUND( INDFR, NDF__MXDIM, LBNDR, UBNDR, NDIMR, STATUS )
 
@@ -748,7 +806,8 @@ SUBROUTINE WCSALIGN( STATUS )
 *  output) pixel co-ordinates. This also determines if the Mapping is a
 *  simple integer pixel shift of origin. If it is, it returns the new pixel
 *  origin in ORIGIN.
-         CALL KPS1_WALA7( INDF1, IWCSRT, MAP, MAP4, ORIGIN, STATUS )
+         CALL KPS1_WALA7( INDF1, REFALN, IWCSRT, MAP, MAP4, ORIGIN,
+     :                    STATUS )
 
 *  If the input pixel->output pixel Mapping is a shift of origin, we do
 *  not need to do a full resampling or rebinning. However, if the output