JP-3285: Allow negative angles in engineering format. Add support for angle units (#7683)

Author: mcara

CHANGES.rst

@@ -50,6 +50,16 @@ ramp_fitting
   group, the timing for these ramps is not group time.  These adjusted times
   are now used. [#7612, spacetelescope/stcal#173]
 
+tweakreg
+--------
+
+- Fixed a bug in the ``adjust_wcs`` *script* that was preventing passing
+  negative angular arguments in the engineering format. Exposed ``adjust_wcs``
+  function's docstring to be used in building ``jwst`` documentation. [#7683]
+
+- Added support for units for angular arguments to both ``adjust_wcs`` script
+  and function. [#7683]
+
 
 1.11.0 (2023-06-21)
 ===================
@@ -83,7 +93,7 @@ cube_build
 ----------
 
 - Remove deleting the ``spaxel_dq`` array twice when using a weighting method of either msm or emsm. [#7586]
-  
+
 - Updated to read wavelength range for NIRSpec IFU cubes from the cubepars reference file,
   instead of setting it based on the data. This makes use of new NIRSpec IFU cubepars reference
   files with wavelength arrays for the drizzle method. [#7559]
@@ -134,7 +144,7 @@ flat_field
 ----------
 
 - Added log messages for reporting flat reference file(s) used. [#7606]
-  
+
 other
 -----
 
@@ -216,7 +226,7 @@ tweakreg
   another. It is an analog of the ``tweakback`` task in the
   ``drizzlepac``. [#7573, #7591]
 
-- Added the 'GAIADR3' catalog to the available options for alignment; 
+- Added the 'GAIADR3' catalog to the available options for alignment;
   this has been enabled as the default option [#7611].
 
 

jwst/scripts/adjust_wcs.py

@@ -39,13 +39,14 @@
 
 From command line::
 
-    % adjust_wcs [-h] (-u | --suffix SUFFIX | -f FILE) [--overwrite] [-w]
-                 [-r RA_DELTA] [-d DEC_DELTA] [-o ROLL_DELTA] [-s SCALE_FACTOR]
+    % adjust_wcs [-h] (-u | --suffix SUFFIX | -f FILE) [--overwrite]
+                 [-r RA_DELTA [units]] [-d DEC_DELTA [units]]
+                 [-o ROLL_DELTA [units]] [-s SCALE_FACTOR]
                  [-v] [input ...]
 
     % adjust_wcs data_model_*_cal.fits -u -s 1.002
 
-    % adjust_wcs data_model_*_cal.fits --suffix wcsadj -s 1.002 -o 0.0023
+    % adjust_wcs data_model_*_cal.fits --suffix wcsadj -s 1.002 -r 0.2 arcsec -o 0.0023 deg
 """
 import argparse
 import glob
@@ -56,6 +57,10 @@
 import jwst
 from jwst.tweakreg.utils import adjust_wcs
 from jwst.assign_wcs.util import update_fits_wcsinfo
+from astropy import units
+
+
+_ANGLE_PARS = ["-r", "--ra_delta", "-d", "--dec_delta", "-o", "--roll_delta"]
 
 
 # Configure logging
@@ -80,6 +85,36 @@ def _replace_suffix(file, new_suffix):
     return new_file_name
 
 
+def _is_float(arg):
+    try:
+        float(arg)
+        return True
+    except ValueError:
+        pass
+    return False
+
+
+def _is_unit(arg):
+    if arg.startswith("-"):
+        return False
+    try:
+        units.Unit(arg)
+        return True
+    except ValueError:
+        pass
+    return False
+
+
+def angle(arg):
+    args = arg.strip().split(' ')
+    if len(args) == 1:
+        return float(args[0])
+    elif len(args) == 2:
+        return units.Quantity(float(args[0]), units.Unit(args[1]), dtype=float)
+    else:
+        raise argparse.ArgumentTypeError()
+
+
 def main():
     if len(sys.argv) <= 1:
         raise ValueError("Missing required arguments.")
@@ -129,21 +164,21 @@ def main():
     group_wcs.add_argument(
         "-r",
         "--ra_delta",
-        type=float,
+        type=angle,
         default=0.0,
         help="Delta RA (longitude), degrees."
     )
     group_wcs.add_argument(
         "-d",
         "--dec_delta",
-        type=float,
+        type=angle,
         default=0.0,
         help="Delta DEC (latitude), degrees."
     )
     group_wcs.add_argument(
         "-o",
         "--roll_delta",
-        type=float,
+        type=angle,
         default=0.0,
         help="Delta roll angle, degrees."
     )
@@ -162,7 +197,25 @@ def main():
         version="v{0}".format(jwst.__version__)
     )
 
-    options = parser.parse_args()
+    # pre-process argv for units and negative floats:
+    argv = sys.argv[1:]
+    argv_new = [os.path.basename(sys.argv[0])]
+    while argv:
+        argv_new.append(argv.pop(0))
+
+        # check whether next argument is a float:
+        if (argv_new[-1] in _ANGLE_PARS and len(argv) >= 1 and
+                _is_float(argv[0])):
+            angle_value = argv.pop(0)
+            # check whether next argument is a unit:
+            if len(argv) >= 1 and _is_unit(argv[0]):
+                angle_unit = argv.pop(0)
+                argv_new.append(f" {angle_value} {angle_unit}")
+            else:
+                # assume angle units are degrees
+                argv_new.append(f" {angle_value}")
+
+    options = parser.parse_args(argv_new)
 
     files = []
     for f in options.arg0:

jwst/tweakreg/utils.py

@@ -1,6 +1,7 @@
 from copy import deepcopy
 
 from astropy.modeling.rotations import RotationSequence3D
+from astropy import units
 from gwcs.wcs import WCS
 import numpy as np
 from tweakwcs.correctors import JWSTWCSCorrector
@@ -14,6 +15,9 @@
 _RAD2ARCSEC = 3600.0 * np.rad2deg(1.0)
 
 
+__all__ = ["adjust_wcs", "transfer_wcs_correction"]
+
+
 def _wcsinfo_from_wcs_transform(wcs):
     frames = wcs.available_frames
     if 'v2v3' not in frames or 'world' not in frames or frames[-1] != 'world':
@@ -70,17 +74,17 @@ def adjust_wcs(wcs, delta_ra=0.0, delta_dec=0.0, delta_roll=0.0,
         WCS object to be adjusted. Must be an imaging JWST WCS of a calibrated
         data model.
 
-    delta_ra : float, optional
-        Additional rotation (in degrees) to be applied along the longitude
-        direction.
+    delta_ra : float, astropy.units.Quantity, optional
+        Additional rotation (in degrees if units not provided) to be applied
+        along the longitude direction.
 
-    delta_dec : float, optional
-        Additional rotation (in degrees) to be applied along the latitude
-        direction.
+    delta_dec : float, astropy.units.Quantity, optional
+        Additional rotation (in degrees if units not provided) to be applied
+        along the latitude direction.
 
-    delta_roll : float, optional
-        Additional rotation (in degrees) to be applied to the telescope roll
-        angle (rotation about V1 axis).
+    delta_roll : float, astropy.units.Quantity, optional
+        Additional rotation (in degrees if units not provided) to be applied
+        to the telescope roll angle (rotation about V1 axis).
 
     scale_factor : float, optional
         A multiplicative scale factor to be applied to the current scale
@@ -94,6 +98,16 @@ def adjust_wcs(wcs, delta_ra=0.0, delta_dec=0.0, delta_roll=0.0,
     wcs : `gwcs.WCS`
         Adjusted WCS object.
     """
+    # convert input angles to degrees:
+    u_deg = units.Unit('deg')
+
+    if isinstance(delta_ra, units.Quantity):
+        delta_ra = delta_ra.to(u_deg).value
+    if isinstance(delta_dec, units.Quantity):
+        delta_dec = delta_dec.to(u_deg).value
+    if isinstance(delta_roll, units.Quantity):
+        delta_roll = delta_roll.to(u_deg).value
+
     # find the last frame in the pipeline that starts with 'v2v3':
     pipeline = deepcopy(wcs.pipeline)
     for step in pipeline[::-1]: