the JWST user documentation is under development; current versions are preliminary and subject to revision.

Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Content Layer
Content Column
Content Block

Instructions for designing JWST NIRCam Coronagraphic Imaging observations using APT, the Astronomer's Proposal Tool, v25.1.

Content Block


Coronagraphic imaging is 1 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

Multiexcerpt include
PageWithExcerptMIRI Imaging Template APT Guide

Note: mosaics are not available for NIRCam coronagraphic imaging.


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

Coronagraphic Mask

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

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

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.

MultiExcerptNameTA SNR
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 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 642 (SW) or 1282 (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 2 identical, full-frame exposures using the 4 SW SCAs (for the SW masks), or the 1 LW SCA (for the LW masks). 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. 

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


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 SUBARRAYparameter 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 × 2048132"
(with 4"–5" gaps)
640 × 64020.3" 4.179321
SUB320320 × 320 20.7"1.065721

Dither Pattern

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 PATTERNvalues 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

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

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

For a survey of many targets, they may serve as PSF references for one another.  In that case, the user may check this box and explain with additional text in the science justification section of a submitted proposal.  The user must still select the science targets as PSF Reference Observations in the list above.

Other Tabs

Special Requirements

A variety of observatory level special requirements may be chosen, including Position Angle (PA) offsets and non-interruptible observing sequences.


The comments field should be used only to record observing notes.

Content Block
nameRelated links

Related links

NIRCam Coronagraphic Imaging
NIRCam Coronagraphic Imaging Template Parameters
NIRCam Coronagraphic Target Acquisition
NIRCam Coronagraphic Occulting Masks and Lyot Stops
NIRCam Filters for Coronagraphy
JWST High Contrast Imaging Overview
JWST Coronagraphy Strategies
JWST Coronagraphic Observation Planning
JWST Coronagraphic Sequences
JWST High Contrast Imaging in APT
NIRCam Coronagraphic PSF Estimation
JWST Exposure Time Calculator Overview
NIRCam Detector Readout Patterns
NIRCam Overview
NIRCam Modules
NIRCam Detector Subarrays
NIRCam Detectors
NIRCam Field of View 

Content Block


Reference papers and reports.

Content Column
Content Block

Multiexcerpt include
MultiExcerptNameAPT icon and name
PageWithExcerptMR:APT icon and name

Content Block

Last updated

Updated June 1, 2017

Published May 13, 2017



The format for 'Last updated' is shown below. Enter updates above this internal"Comment" box. Only enter major updates (not typos or formatting changes).

Updated April 5, 2017

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam fermentum vestibulum est. Cras rhoncus. 
  • Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed quis tortor. 

Published March 2, 2017

Restrict Content

Tables are only visible to JDox content providers

"Updated" refers to the updated or publish dates for the public pages.

Page properties
UpdatedJune 1, 2017
Open commentsYes
AuthorCoe, Correnti
Page properties
UpdatedJune 1, 2017
Fix pageNo