This page provides advice and tips to help with aligning NIRCam imaging data. There are two supported software packages that can be used for image alignment. The first is the tweakreg step within the Stage 3 calibration pipeline. This is very similar to the tweakreg step within Drizzlepac. The second is the JWST/HST Alignment Tool (JHAT). 

Introduction

The JWST science calibration pipeline is designed to produce fully calibrated, rectified mosaics using a common set of parameters; however, the parameters may not be optimal to produce well-aligned images and mosaics in some cases. There are parameters within the pipeline that can be updated to tweak and improve the alignment results, and community tools for cases where the calibration pipeline is not performing optimally. These are described below, along with common questions about improving image alignment.

Tweakreg

There are essentially two parts to tweakreg: (1) it first does relative alignment across all exposures in the association (using sets of overlapping sources across the various sets of exposures), then (2) it carries out absolute alignment of the entire association of exposures onto an external frame -- at this point it considers all the relative alignments between exposures to now be fixed, so it applies the absolute alignment to the entire association of exposures, without further adjusting the relative alignments between exposures.

The relative alignment (part 1) includes these parameters (in the "Object matching parameters" section in the page for the step arguments):

• minobj, searchrad, use2dhist, separation, tolerance, fitgeometry, nclip, sigma

and the absolute alignment (part 2) has a completely independent set of similarly named parameters just with "abs_" prepended, ie:

• abs_refcat, abs_minobj, abs_searchrad, abs_use2dhist, abs_separation, abs_tolerance, abs_fitgeometry, abs_nclip, abs_sigma

The relative alignment (part 1) creates catalogs from the exposures and uses those to do the alignment. When doing this, it assumes all the SCAs in a given exposure are already tied together with accurate relative WCS (ie, it doesn't try to solve for shifts or rotations of each SCA separately). Within each SW module, the separate SCAs generally do seem to be quite well aligned (to a few mas or better), but modules A and B may still have some noticeable residual differences (which are currently being worked on and will be improved in future updates to the instrument WCS in the operational archive); the following approach describes how to improve this alignment.

If the overall goal is to align to Gaia, and some SCAs in the SW channel have too few (or no) Gaia sources, which can happen quite regularly, then if the dataset also has LW data, and if the LW data have enough Gaia sources (more likely, given the larger area of the SCAs in the LW channel), then a fairly robust approach to provide improved alignment, which has been used in a significant number of JWST programs so far, is the following recipe:

1. Start with a LW filter that's fairly close to the SW wavelengths (eg, F277W, but another filter can be used too) and run tweakreg with the full relative and absolute alignment on each set of LW exposures separately, ie module A by itself, and module B by itself (for example, by running in a subdirectory where only the files from a single module are present, or alternatively by giving tweakreg an association containing files only for one module at a time, or as a 3rd option using the new "meta.group_id" option in tweakreg to give it files for only one module at a time),  so it can accurately place each of module A and module B onto Gaia. Then stop the image3 pipeline at this point, ie don't continue beyond tweakreg, by setting "skip=True" for the subsequent steps in the pipeline (and also being sure to set "save_results = True" in tweakreg, so that it produces a set of *_tweakreg.fits files).
   (Note: if the exposures are from different visits, then it may be desirable to run the above for each visit separately by itself).
2. Produce a full mosaic of all these LW tweakreg files in this filter (ie, combining all the exposures in module A and B), by rerunning the calwebb_image3 pipeline,  giving it all the *_tweakreg.fits files from both modules A and B as input: in this rerun, tweakreg would now be skipped by setting skip=True, so that the pipeline can continue directly onto the subsequent steps of outlier rejection, mosaic production and catalog generation; the resulting LW catalog should now be on the Gaia frame.
3. Then run tweakreg on all the other data from the other filters in SW and LW, doing the same approach of running all the files separately for each module (and again, it may be desirable to run this separately for each visit, if that’s the case), and this time providing the above LW catalog as input for the "abs_refcat" parameter (ie no longer needing to use Gaia, which may be too sparse for some of the detectors, but rather using the much denser LW catalog produced above, which should be on the Gaia frame), and also being sure to stop the pipeline at the end of the tweareg step by setting "skip=True" for the subsequent steps (again being sure to set "save_results = True" so that it produces a set of *_tweakreg.fits files)

Once all the *_tweakreg.fits files have been produced for all the exposures in a given filter, these can then be provided to the calwebb_image3 pipeline for the next steps (ie, tweakreg would now be skipped by setting skip=True, so that the pipeline can continue directly onto outlier rejection, mosaic production and catalog generation).

JWST/HST Alignment Tool (JHAT)

The JHAT Documentation page contains several examples involving alignment of JWST and HST datasets.

Common Questions

• I have been having issues aligning a large NIRCam mosaic. Some of the individual exposures seem to be well aligned, but others have offsets of several arcseconds from where they should be. These offsets are present in the cal.fits files prior to running the Stage 3 pipeline.

In cases where some data have a noticeable shift compared to others, it can be that FGS was guiding on the wrong star when some of the data were acquired. In that case, the FGS pointing is incorrect, which propagates into the reported NIRCam pointing. In these cases, if the pointing is incorrect by several arcseconds, it is possible to correct the pointing and produce a well-aligned mosaic. 

• • To correct using tweakreg: Try setting the fit_geometry keyword to "rscale" or "general". The value to use depends on the number of sources in the images. "rscale" will only adjust the rotation and scale of the input images, while "general" will adjust the shift, rotation, and scale. For a description of these and other tweakreg parameters, see the step arguments page in the tweakreg documentation. "general" requires more sources (hundreds to thousands) than "rscale". This will allow more flexibility in how the images are adjusted/oriented relative to one another. Next increase the values of the "separation" and "tolerance" parameters. When attempting to match sources, tolerance is the maximum offset allowed after applying an initial WCS correction to a file. Both are in units of arcseconds, and in general, separation should be ~2x tolerance. Example code to make these changes is shown below:

# call just the tweakreg step and save the results to a fits file
from jwst.tweakreg import TweakRegStep
tweakreg = TweakRegStep.call(asn_file, fitgeometry='general', tolerance=1.0, separation=2.0, save_results=True)
 
# or as part of a call to the stage 3 pipeline:
from jwst.pipeline.calwebb_image3 import Image3Pipeline
params = {'tweakreg': {'fitgeometry': 'general',
                       'tolerance': 1.0,
                       'separation': 2.0
                       }
          }
output = Image3Pipeline.call(asn_file, steps=params, save_results=True)

• • To correct with JHAT: Call JHAT once using only the data with the bad WCS offset. In this call set the xshift/yshift parameter values to roughly the values needed to bring the WCS closer to what it should be (or what it is in the data with no offset). In addition, use the --iterate_with_xyshifts flag. Once that is complete, make a second call to JHAT using the data without the WCS offfset. In that case, no xshift/yshift is needed. If those steps are successful, then you can call the stage3 pipeline on all the data together, but be sure to turn off the tweakreg step so that it does not try to re-adjust the WCS of the data.

• There appear to be some NIRCAM tiles in my mosaic that have incorrect WCS. Many tiles appear arcminutes from where they should be. What's going on?

WCS offsets this large are most likely due to missing engineering data. Check the value of the ENGQLPTG header keyword in your files. If the value is "PLANNED" then most likely the engineering data needed to calculate the pointing was not found during the initial pipeline run, and therefore the pointing was never updated. To resolve this, try running the set_telescope_pointing.py script on each of the files with the bad WCS. This script is part of the jwst calibration package. At the command line (rather than within python), use: set_telescope_pointing.py <file_uncal.fits>, and replace <file_uncal.fits> with the name of your uncal file. This will search the engineering data and update the pointing information in the file. You'll then have to run the corrected uncal files through the calibration pipeline.

• I am trying to align NIRCam and archival ACS images. However, I have noticed a small systematic offset (<1") in the WCS coordinates between these two image sets. I would like to update the NIRCam WCS information by utilizing the reference HST images.

The JHAT documentation has a number of examples that should be helpful. If you are happy with the relative alignment of the NIRCam images to one another, then it should be a relatively straight forward process to generate a source catalog by running JHAT on the ACS data, and then applying that catalog to the JWST data with another JHAT run.

•  I successfully aligned a single NIRCam image with an HST reference image. Now I am looking to align my remaining NIRCam images with the initial NIRCam image. Could you please provide me with some examples?

The path forward depends on your data. If you have a good amount of overlap between the image that you aligned with HST and the other images, then you can treat the former as your reference image and align the others to it using JHAT. See the NIRCam example in the JHAT documentation: Relative Alignment

If you are working with an extended mosaic where there is not a lot of overlap (or not a lot of sources in the overlap regions) between the NIRCam images, then it might be better to align the images using a catalog, such as GAIA: Align to Catalog. In this case though, JHAT may adjust the WCS in the image that you aligned to HST. In that case, you might need to go back and align the HST data using GAIA as well.

References

Rest, A., Roberts-Pierel, J., Correnti, M., Hilbert, B., Canipe, A., and Sunnquist, B., vol. 55, no. 2, 2023.
JWST/HST Alignment Tool (JHAT)