JWST Target Visibility Tools

Three target visibility tools are available to help proposers evaluate the visibility of targets, and their allowed position angles on the sky, for potential observations by JWST instruments: the General Target Visibility Tool (GTVT), the Moving Target Visibility Tool (MTVT), and the Coronagraphic Visibility Tool (CVT). Using these tools prior to developing a proposal in APT could save time and provide insight into observability. 

See also: JWST Interactive Sensitivity Tool

On this page

See also: JWST General Target Visibility Tool Help, JWST Moving Target Visibility Tool HelpJWST Coronagraphic Visibility Tool Help, JWST Position Angles, Ranges, and OffsetsJWST Observatory Coordinate System and Field of Regard

While the Astronomers Proposal Tool (APT) provides detailed schedulability information for each target, there may be instances where you'd want an overview of target visibilities and their available position angle ranges prior to entering them in your proposal in APT. For example, JWST pointing constraints may restrict position angles for targets near the ecliptic plane; in such a scenario, you may want to know upfront if observations at a particular position angle are feasible. (See the Specifying JWST Positions Angles, Ranges, and Offsets article for more information on this topic.)  

The JWST Project provides 3 quick-look target visibility tools to help in pre-planning observations, and for determining their feasibility, prior to entering them in APT: the General Target Visibility Tool (GTVT) predicts visibility windows and position angles for all instruments, the Moving Target Visibility Tool (MTVT) takes the movement of solar system bodies into account when predicting visibility windows and allowed position angles, and the Coronagraphic Visibility Tool (CVT) provides target visibility information for the NIRCam and MIRI coronagraphic modes.

For given target coordinates, the tools report (1) the ecliptic latitude, and (2) the target visibility windows and allowed position angles versus time. These tools have been vetted for accuracy against APT calculations, but are primarily intended to provide an overview capability that complements APT.

You should note that the checks made by the APT Visit Planner include other aspects of schedulability beyond just visibility, including the availability of guide stars at relevant position angles, and any special requirements levied on your observations in APT. APT is the final arbiter of schedulability.

For all JWST instruments, the "science-y" axis of each detector is used as the reference angle for specifying position angles. Many of the instruments are essentially aligned with the observatory V3 axis within a fraction of a degree, but MIRI and NIRSpec have offsets counterclockwise relative to V3. Figure 1 provides a schematic of the reference axes for each instrument in the JWST focal plane, showing the V3 axis direction for reference. See JWST Observatory Coordinate System and Field of Regard for details on the observatory coordinate system.

Figure 1. Reference axes for measuring JWST position angles

In this schematic view from the perspective of the instruments, through the telescope and onto the sky, the blue arrows indicate the approximate reference axis directions for each instrument and for the observatory V3 reference axis. When projected onto the sky, the position angle of the V3 axis (V3PA, degrees east of north) provides a reference for projecting the instrument fields of view onto the sky. Only MIRI and NIRSpec are significantly offset from the observatory V3 axis direction, as shown in the figure.

The JWST General Target Visibility Tool (GTVT) and Moving Target Visibility Tool (MTVT)

The GTVT and MTVT are Python command-line-driven tools that allow users to get a quick look at the visibility of a given target (fixed or moving) versus time, and the available position angles in those visibility windows. The calculations are performed for a single primary reference axis for each of the 4 science instruments, the FGS, and for the observatory "V3PA" (V3 position angle) reference angle, as highlighted in Figure 1. This feature is useful for observers planning multiple observations with absolute and/or relative timing or position angle constraints, target of opportunity (TOO) programs, or any case where the overall observing windows for a target are needed for planning observations.  

These tools can be run interactively, producing diagnostic plots and ASCII tables on the screen. In the interactive plot mode, users can pan and zoom within the individual panels for a more detailed view. Command-line options can also be used to save output to files. For bulk processing, users can write a simple script to run the GTVT or MTVT in batch mode. 

The GTVT help and MTVT help pages have detailed descriptions of each tool, including examples specific to each tool.

The JWST Coronagraphic Visibility Tool (CVT) 

Users planning observations for coronagraphy have additional constraints beyond target visibility, such as the position angle of a disk or the placement of a known companion relative to the host star. The CVT provides a GUI-based tool specifically for helping you pre-plan JWST coronagraphic observations with NIRCam and MIRI, and to verify that they will work in APT. This tool provides overall target visibility information as well as information on the location of assumed companions relative to instrumental structures such as occulting bars in NIRCam or boundaries in the MIRI 4-quadrant phase mask (4QPM) coronagraphs and a function of time. It also shows how the instantaneous roll flexibility changes (from approximately ±3.5° to ±7° from nominal) over the visibility period, which is an important consideration for many coronagraphic observations.  

The CVT is written in Python, but can be installed as an app that launches a GUI. Like the GTVT, the GUI can be manipulated to pan and zoom on the plots.  

A more detailed description and help file is available.

Accessing the target visibility tools 

The GTVT/MVTV and CVT have source code on GitHub:

Binary wheels are distributed by PyPI. Both packages can be installed using pip.

pip install jwst-gtvt jwst-coronagraph-visibility

Specific details for using the target visibility tools are provided in these help files:

Please contact the JWST Help Desk with any questions.

Synergy between the tools

The GTVT and CVT have been tested against each other and against APT for consistency. Hence, the visibility windows and angles found in the CVT for NIRCam or MIRI coronagraphs will be consistent with the general results for NIRCam and MIRI in the GTVT. (The reference axes for the imagers and the coronagraphs are aligned.)  

Some details are different between the tools. For example, the CVT has a name resolver to obtain coordinates while the GTVT does not. Meanwhile, the GTVT will accept coordinates in decimal or sexagesimal formats, but the CVT only uses decimal format. Also, since the GTVT is a command-line tool, a script can be used to run in batch mode whereas the CVT is designed to look at individual objects in detail.

Latest updates
    Removed references to AstroConda since it is no longer supported

    Added a note and link regarding the moving target option of GTVT
Originally published