Mosaic Parameters

JWST's Mosaic tool, available in the Astronomer’s Proposal Tool (APT), has parameters for specifying mosaics of large targets.


Purple text indicates the parameter is Limited Access.

Boldface italics type indicates the name of an APT parameter or a value for a parameter.

(warning)Red text indicates restrictions on a parameter.

(red star) Black text indicates an important note.

Brown text indicates notes for the developers.

Green text indicates the name of the parameter used by Commanding.

Items in brackets - <value> - are required values.

Items in square brackets - [<value>] - are optional.

For imaging observations of large, extended targets, it is sometimes necessary to mosaic the target to cover the entire object. The Mosaic tool in APT will assist the proposer in creating the mosaic. Note that this tool is only supported for the templates list in Table 1.

Table 1. Templates that support Mosaics 

MIRI Imaging

NIRCam Imaging

NIRISS Imaging


NIRCam Wide Field Slitless Spectroscopy

NIRISS Wide Field Slitless Spectroscopy


NIRCam External Flat

NIRISS Internal Flat

MIRI Imager Flat

NIRCam Engineering

NIRISS External Calibrations



NIRSpec Fixed Slit

FGS External Calibration (Imaging option only)

MIRI Coronagraphic Photometric Calibration 


MIRI MRS Cross-Grating Engineering

NIRSpec Imaging

The Mosaic Tool (see Figure 1) has 7 parameters:

  • Rows - the number of rows in the mosaic; (warning)the range is 1-50
  • Columns - the number of columns in the mosaic; (warning)the range is 1-50
  • Row overlap - the percent overlap for rows; (warning)the range is -200% to 100%. Default is 10% with the following exception: Default overlap is 20% for the MIRI Imager with SUBARRAY=SUB64 or SUB128 in the MIRI Imaging and MIRI External Flat templates, with a warning given for values less than 20%.
  • Column overlap - the percent overlap for columns; (warning)the range is -200% to 100%. Default is 10% with the following exception: Default overlap is 20% for the MIRI Imager with SUBARRAY=SUB64 or SUB128 in the MIRI Imaging and MIRI External Flat templates, with a warning given for values less than 20%.
  • Row shift - the offset for rows; (default ) (warning)the range is -90° to +90°
  • Column shift - the offset for columns; (default ) (warning)the range is -90° to +90°

 The final parameter is the Tile Order, which specifies the order in which the tiles are considered for inclusion in multi tile visits (see Figure 2); as a result, this feature is only available when the mosaic is composed of more than one multi-tile visit. (Note that Tile Order does not influence the order of execution of the resulting visits, that is determined in scheduling.) There are 4 options:

  1. DEFAULT - APT will choose the search order.  (If one side of the grid is shorter than the Visit Splitting Distance of the Observation then use whichever of ROW_ORDER or COLUMN_ORDER traverses the shortest side. If both sides are longer than the splitting distance, use the HILBERT_CURVE.)
  2. ROW_ORDER considered in an order traversing fully across one row then dropping down to the next row and traversing in the reverse direction
  3. COLUMN_ORDER - the tiles are considered in an order traversing fully down one column then shifting to the right and traversing in the reverse direction
  4. HILBERT_CURVE -the tiles are considered in an order which is a space filling curve that better preserves spatial locality

There is a table that lists all the tiles in the mosaic with the following fields:

  • Tile Number – the tile number in the mosaic
  • Tile State – the state of the tile (Included or Removed), which can be toggled by the user
  • Visits – the Visit(s) that the tile is included in (expressed as Observation:Visit)  

There are also buttons to perform the following functions:

  • Split Tile to New Observation (e.g. if there are no guide stars for that particular tile)
  • Copy Tile to a New Observation (e.g. if a tile failed and needs to be repeated)
  • Insert New Observation into Mosaic (e.g. to add a new individual tile)

Note that when a tile is split from a mosaic, the Tile Order is fixed to be the one selected at the time of the splitting.

Note to developer: When each tile is associated with a distinct set of visits, disable the Tile Order option. When the entire mosaic fits in a single visit, set the option to DEFAULT and make it un-editable.


Figure 1. The Mosaic Tool
Figure 2. Tile Order Options

Basic Example 

As an example, we want to mosaic the galaxy NGC 4151 using the MIRI Imaging template. In this case, we want a 5x3 mosaic with an APERTURE PA of 316° (to align the apertures with the galaxy) and 10% row and column overlap; there is no row or column shift required (see Figure 3). We will use the DEFAULT tile ordering, which in this case is the HILBERT_CURVE.

Figure 3. NGC 4151 Simple Mosaic

Using Shift parameters

In some cases, it may not be possible to observe the target at the Aperture PA needed for a simple mosaic to cover the target. For those cases, it may be possible to use the Row Shift  and/or Column Shift parameters to align the mosaic with the target. For M98 example, the optimum APERTURE PA is 326° (see Figure 4(A)). Let’s assume that APERTURE PA is not schedulable, and instead we use a value of 0° (see Figure 4(B) . The galaxy is not aligned with the apertures, but if we use a Row Shift of -30° we can get a good alignment (see Figure 4(C)); remember when using row or column shifts to create an asymmetric mosaic, you need to remember to specify an appropriate range of APERTURE PA.

Figure 4. (A) M98 at optimal APERTUE PA, (B) Mosaic without shift, (C) Mosaic with shift

Change log

The initial version of this chapter was written by Ron Downes.


  1. PROPINSTJWST-91586 Added default 20% exceptions to row and column overlap.

Version 5 (April 16, 2019)

  1. Editorial change (moved change log to main article).

Version 4 (November 8, 2018)

  1. No PR - editorial change, updated link for Visit Splitting Distance.

Version 3 (January 2, 2018)

  1. PR 89490 - added capability to select tile ordering algorithm

Version 2 (February 21, 2017)

  1. Updated template name in Table 1 (to NIRCam WFSS)

Version 1 (December 14, 2016)

This is the converted Word File from Chapter 8, with updates to reflect the current state of the tool.