NIRCam Coronagraphic Imaging APT Template

Instructions for designing JWST NIRCam coronagraphic imaging observations using the Astronomer's Proposal Tool (APT) are provided in this article.

On this page

See also: NIRCam Coronagraphic ImagingHCI RoadmapHCI APT InstructionsNIRCam Coronagraphic Imaging Recommended StrategiesNIRCam and MIRI Coronagraphy of HR8799 bNIRCam and MIRI Coronagraphy of the Beta Pictoris Debris Disk

Coronagraphic imaging is one of 5 observing modes available with the Near Infrared Camera (NIRCam)NIRCam offers 5 coronagraphic occulting masks in the focal plane and 2 Lyot stops in the pupil plane. One Lyot stop is used with the round coronagraphic masks, and the other Lyot stop is used with the bar-shaped coronagraphic masks.

NIRCam's 3 round coronagraphic masks, MASK210R, MASK335R, and MASK430R, have inner working angles IWA = 0.40", 0.63", and 0.81" (radius), corresponding to 6λ/D at 2.1, 3.35 and 4.1 μm.

The 2 bar-shaped coronagraphic masks, MASKSWB and MASKLWB, are tapered, with IWA varying by a factor of 3 along their lengths. The half widths at half maximum (HWHM) at the bar end points for the short wavelength (SW) occulter MASKSWB are 0.13" and 0.39", whereas for the long wavelength (LW) occulter MASKLWB are 0.29" and 0.87".

The observer will have control over 5 primary parameters for NIRCam coronagraphic imaging:

  1. Coronagraphic mask + filter combination
  2. Small grid dithering type
  3. Detector subarray (FULL or the smaller subarray corresponding to each mask)  
  4. Detector read out pattern and exposure time (via the number of groups and integrations).
  5. Astrometric confirmation images (YES or NO to two FULL frame images before and after centering the prime target behind the mask)

Performing multiple coronagraphic observations enables PSF subtraction as described below in the PSF Reference Observations section.

Allowed values are documented in the NIRCam Coronagraphic Imaging Template parameters page.

Step-by-step APT instructions are provided below.

Generic parameters

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

The following parameters are generic to all templates, and are not discussed in this article: observation Number, observation Labelobservations CommentsTarget name, ETC Wkbk. Calc ID (in the Filters dialog box), Mosaic Properties, and Special Requirements.

NIRCam Coronagraphic Imaging tab


See also: NIRCam Modules

NIRCam coronagraphic imaging is only available using module A (with module B as a back-up). This parameter is not user changeable. 

Coronagraphic Mask

See also: NIRCam Coronagraphic Occulting Masks and Lyot Stops

The user specifies the coronagraphic mask, depending on the target-host separation, necessary contrast, and desired filter. Selection of the Coronagraphic Mask also determines the Acq Filter parameter and the target acquisition subarray. The available coronagraphic masks are: 

  • MASK210R, MASKSWB: optimized for the short wavelength (SW) channel.
  • MASK335R, MASK430R, MASKLWB: optimized for the long wavelength (LW) channel.

For APT version 2022.7 and above (starting in Cycle 2), NIRCam coronagraphic imaging allows saving of the data seen by both SW and LW channels simultaneously (as for regular imaging but module A only).

The coronagraphic mask and associated Acq Filter is fixed. One should therefore chose the mask wisely based on which channel (filters, working angle) drives the science case.


  • MASK210R and MASKSWB allows reaching the smallest inner working angles (IWA) but the point spread function (PSF) scales with wavelength. When associated with LW filters, the larger PSF and possible saturation might yield a degraded IWA. For the longest wavelength, the smaller mask will block the core of the PSF which will feature strong satellite spots for an unocculted coronagraphic PSF. This can be checked with the ETC.
  • MASK430R is very close to the gap between SW detectors and thus will yield a very limited field of view.
  • MASKLWB only: there is a new rectangle subarray (SUB400X256) to accommodate better all filter-dependent field points along the bar. 

Target Acquisition Parameters

See also: NIRCam Coronagraphic Imaging Target AcquisitionJWST ETC NIRCam Target Acquisition

Target acquisition is required for coronagraphic imaging. This section specifies the Target ACQ and Acq Exposure Time.

Target ACQ

The user specifies the Acq Target and the Acq Target Brightness.

The Acq Filter is determined by the choice of the coronagraphic mask and it is not user changeable (F210M for the SW occulters MASK210R and MASKSWB, and F335M for the LW occulters MASK335R, MASK430R, and MASKLWB).

Acq Target

The selected Acq Target may be either the same as the science target or any other target defined in the APT file.

Acq Target Brightness

  1. FAINT

The user selects the Acq Target Brightness parameter as a function of the target magnitude in the Acq Filter. If BRIGHT is chosen, the target will be imaged through a neutral density (ND) square. BRIGHT should be used for targets with magnitudes brighter than approximately 8.2 mag (F210M) and 6.8 mag (F335M). 

Acq Exposure Time

See also: Understanding JWST Exposure Times

The Acq Exposure Time fields specify the MULTIACCUM exposure configuration. Each exposure is specified by readout pattern and characteristic parameters: Acq Readout Pattern and Acq Groups/Int.

Please consult the Exposure Time Calculator (ETC). We recommend a signal-to-noise ratio of 30 or higher to obtain a centroid accuracy of 0.1 pixel for the TA source. We also recommend not saturating any pixels.

Acq Readout Pattern

All 9 NIRCam readout patterns are available for target acquistion: RAPID, BRIGHT1, BRIGHT2, SHALLOW2, SHALLOW4, MEDIUM2, MEDIUM8, DEEP2, and DEEP8.

Acq Groups/Int 

This parameter defines the number of groups during an integration. The user can select one of the following options: 3, 5, 9, 17, 33, 65

Note that target acquisition images are taken using the 1282 (SW) or 642 (LW) subarray. For this reason, the number of groups per integration is not limited to 10 as in the astrometric confirmation image and science exposure.

Acq Integrations/ExpAcq Total Integrations, and Acq Total Exposure Time are not user changeable. For target acquisition, Acq Integrations/Exp is always 1.

Astrometric Confirmation Image Parameters

Obtain astrometric confirmation images?

If Yes is selected, confirmation images are taken. These are 2 identical exposures returning data from either all 4 SW detectors or the single LW detector. Images are taken before and after the science exposures. The first one is taken before and the second taken after the pointing adjustment that moves the target from the target acquisition position to the location behind the selected coronagraphic mask. The filter for confirmation images is the same as the target acquistion filter in Acq Filter (F210M for SW and F335M for LW).

Conf. Exposure Time

The user configures the astrometric confirmation image exposure time by setting the following parameters: Conf. Readout Pattern, Conf. Groups/Int, and Conf. Integrations/Exp. The maximum number of groups per integration is 10. The resulting exposure time (not user changeable) is displayed in Conf. Total Exposure Time. Note that Conf. Total Dithers and Conf. Total Integration are not user changeable. For the astrometric confirmation image Conf. Total Dithers is always 1. 

Science Exposures


See also: NIRCam Detector Subarrays

NIRCam coronagraphic imaging supports observations using the full frame or a smaller subarray. Subarrays reduce data volumes and readout times, enabling rapid observations of bright objects without saturation. If one of the SW masks is being used, data will be collected with all 4 SW detectors if Subarray FULL is used, or with a single appropriate SW detector when using a smaller subarray (SUB640A210R on the A2 detector for the occulter MASK210R, SUB640ASWB on the A4 detector for the occulter MASKSWB). If one of the LW masks is being used, data will be collected on the LW detector. Choices for the Subarray parameter are: FULL, SUB640 (for the SW channel), and SUB320 (for the LW channel).

Table 1. NIRCam coronagraphic imaging array and subarray properties




Size in pixels
Nrows × Ncolumns

Short wavelength FOV

Long wavelength FOV

Frame time





128 × 1284" × 4"-0.182001
TA LWMASK335R, MASK430R, MASKLWBSUB6464 × 64-4" × 4"0.050161



MASK210R, MASKSWBFULL 4 × 2048 × 2048 (SW)

4 × 64" × 64" + 4" to 5" gap




MASK335R, MASK430R, MASKLWBFULL2048 × 2048 (LW)


128" × 128"10.736774




640 × 64020" × 20"40" × 40"4.185841


 1 × 2048 × 2048 (SW)
2048 × 2048 (LW)

1 × 64" × 64" + 4" to 5" gap

128" × 128"10.73677








320 × 320

256 x 400**

10" × 10"

7" × 12"

20" × 20"

24" × 15"






 1 × 2048 × 2048 (SW)
2048 × 2048 (LW)

1 × 64" × 64" + 4" to 5" gap

128" × 128"10.736774

For use with target acquisition only

* The astrometric confirmation images are taken only in the channel used for target acquisition

** APT version 2022.7 and above (Cycle 2 and later)

Dither Pattern

See also: NIRCam Small Grid DithersHCI Small Grid Dithers

NIRCam coronagraphic imaging supports various small grid dithers. Dither Pattern values available for the round-shaped coronagraphic masks (MASK210R, MASK335R, and MASK430R) are:

Table 2. Dither patterns for round-shaped coronagraphic masks (MASK210R, MASK335Rand MASK430R)

Dither type

Number of dithers








DITHER PATTERN values available for the bar-shaped coronagraphic masks (MASKSWB and MASKLWB) are:

Table 3. Dither patterns for bar-shaped coronagraphic masks (MASKSWB and MASKLWB)

Dither TypeNumber of dithers

Filters and exposures

See also: NIRCam Filters for CoronagraphyUnderstanding JWST Exposure Times, HCI Coronagraphic SequencesHCI APT Coronagraphic Sequence Examples

The user specifies the Filters (Short Filter and Long Filter since Cycle 2) for the scientific observations. Available filters are a function of the chosen coronagraphic mask. The scientific exposure is configured by setting the readout patterns and characteristic parameters: Readout Pattern, Groups/Int, and Integrations/Exp. The Groups/Int parameter is limited to 10 for all readout patterns except DEEP2 and DEEP8, which allow up to 20.

Total Dithers and Total Integrations are not user changeable and they reflect the values selected in the Dither Pattern and Integrations/Exp fields. 

The resulting exposure time for each filter is displayed in Total Exposure Time.

Users should use the Exposure Time Calculator (ETC) to determine the best exposure configuration to optimize the signal to noise.

PSF reference observations

See also: NIRCam Detector Subarrays

In most cases, 3 or more coronagraphic observations should be defined to support PSF subtraction:

  • Science observation #1 
  • Science observation #2 with the telescope rotated by a specified offset
  • PSF reference star

For a detailed description of the observational strategies, see the HCI Coronagraphic Sequences article

This is a PSF Reference Observation

Checking this box designates the observation as a PSF reference star used for PSF subtraction. (A detailed discussion on the choice of a good PSF reference star can be found in the high-contrast imaging pages.) The observation for a PSF reference star should mirror the observation for the user's science target. Note that reference star observations have no proprietary period.

PSF Reference Observations

For a science target, uncheck the box mentioned above. This shows the PSF Reference Observations field that lists PSF reference observations that were previously specified in the same proposal; click on one of them to associate it with the science observation. 

Additional Justification

In case the user does not need any PSF Reference Observations  (e.g., for a survey of many targets where some of the science targets may serve as PSF references for others), they must check this box and explain with additional text in the science justification section of a submitted proposal the absence of PSF Reference Observations in APT. 

Other tabs

Special Requirements

A variety of observatory level Special Requirements may be chosen under the Special Requirements tab.

As is often the case with coronagraphic observations, the user may specify, in the, Special Requirements panes, that the observations be in sequence and non-interruptible. To add these special requirements, select Add... in the Special Requirements field, then select Timing followed by Group/Sequence Observations Link. In the pop-up window, select observations from the Observation List and check the Sequence and Non-interruptible boxes.

Additionally, the Special Requirements parameter is where the user could specify a roll dither for their science target. To do this, click on Add... under the Special Requirements parameters field, then select Position Angle followed by PA Offset Link. From there, the user select the 2 observations to offset in position angle, and specify the Min PA offset and Max PA offset (in degrees).

Mosaics are not available for NIRCam coronagraphic imaging.


The Comments field (under the Comments tab) should be used for observing notes.

Latest updates

  • Added information about simultaneous SW/LW operations

    Clarified that all 4 SW detectors return science data when using SUBARRAY FULL. Astrometric confirmation images always use SUBARRAY FULL and return data in 4 SW detectors or 1 LW detector, superseding the update below.

  • Updated text in the astrometric confirmation image parameters section to specify that images are collected using only 1 detector (A2 for MASK210R, A4 for MASKSWB, and A5 for LW occulters).
Originally published