NIRCam Coronagraphic Imaging APT Template

Instructions for designing JWST NIRCam Coronagraphic Imaging observations using the Astronomer's Proposal Tool (APT).

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 3 primary parameters for NIRCam coronagraphic imaging:

  1. coronagraphic mask + filter combination
  2. small grid-dithering type
  3. detector read out pattern and exposure time (via the number of groups and integrations).

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

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

Step-by-Step APT instructions

Mosaics are not available for NIRCam coronagraphic imaging.


Words in bold italics are buttons 
or parameters in GUI tools. Bold 
style represents GUI menus/
panels & data software packages.

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.


See also: NIRCam Modules

NIRCam coronagraphic imaging is available only 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 determines also the Acq Filter parameter and the Target Acquisition Subarray. The available coronagraphic masks are: MASK210R, MASKSWB, MASK335R, MASK430R, MASKLWB.

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

A Target ACQ must be completed by selecting a MULTIACCUM exposure configuration. Each exposure is configured by setting the readout pattern and characteristic parameters: Acq Readout Pattern and Acq Groups per Integration.

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 nine NIRCam readout patterns are available for the Target Acquistion: RAPID, BRIGHT1, BRIGHT2, SHALLOW2, SHALLOW4, MEDIUM2, MEDIUM8, DEEP2, DEEP8.

Acq Groups per Integration

 Acq Groups/Int 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 ACQ 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 ACQ, Acq Integrations/Exp is always 1.

Astrometric confirmation image parameters

Obtain astrometric confirmation images?

If Yes is selected, confirmation images are taken. These are two identical exposures using 1 SW SCA ( A2 for the occulter MASK210R, A4 for the occulter MASKSWB), or one LW SCA (A5 for all the LW occulters). 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, Conf. Integrations/Exp. The maximum number of groups per integration is 10. The resulting exposure time is displayed in Conf. Total Exposure TimeConf. 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 subarray on a single detector.  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 using the the appropriate SW detector. 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 (each side) 
Long wavelength 
FOV (each side) 
time (s)
FULL2048 × 204863"129"10.736764
640 × 64020"
SUB320320 × 320

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, MASK335R, and MASK430R)

Dither type

Number of dithers








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

Table 3. Dither patterns for bar-shaped coronagraphic masks (MASKSWB, 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 Filter 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.  Groups/Int 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, three 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 Coronagraphic Sequences page. 

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 reference star observations have no proprietary period.

PSF reference observations

If this observation is of a science target, then use this field to associate it with an appropriate PSF reference observation (based on those that have been defined elsewhere in the observing proposal).

Additional justification

In case the user does not need any PSF Reference Observations  (e.g. for a survey of many targets, some of the science targets may serve as PSF references for one another), 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. 


Latest updates

  • 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