JWST Target Visibility Tools

See also: JWST Interactive Sensitivity Tool

Two standalone 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. Using these tools prior to developing a proposal in APT could save time and provide insight into observability. 

On this page

See also: JWST General Target Visibility Tool Help, JWST Moving Target Visibility Tool Help, and JWST Coronagraphic Visibility Tool Help.
See also: JWST Position Angles, Ranges, and Offsets and JWST 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 2 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, and the Coronagraphic Visibility Tool (CVT) provides target visibility information for the NIRCam and MIRI coronagraphic modes.

For given target coordinates, both 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) for all instruments 

The GTVT is a Python command-line-driven tool that allows you to get a quick look at the visibility of a given target 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.  

This tool can be run interactively, producing results like diagnostic plots and ASCII tables on the screen. In the interactive plot mode, you 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, you can write a simple script to run the GTVT in batch mode. 

As of early March 2018, the GTVT contains an option for use with moving targets as well as fixed targets. If you downloaded the GTVT prior to that time and want the version that permits moving targets to be assessed, you will need to re-install it. See JWST Moving Target Visibility Tool Help for further details.

The GTVT tool help page has a detailed description of the tool, including examples.

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 

GTVT and the CVT are distributed as part of the AstroConda Python software release. AstroConda, maintained by the Space Telescope Science Institute (STScI), provides tools and utilities for working on data from HST, JWST and other telescopes. Installation instructions  are available at the AstroConda website. AstroConda, in turn, runs under the Conda package management system, and in particular is compatible with the Continuum Analytics, Inc.’s Miniconda and Anaconda distributions, one of which must be dowloaded and installed prior to installing AstroConda. Information is available to help you decide what download is right for you.

The visibility tools should be run in the AstroConda environment to ensure connectivity to all dependencies such as Python or Matplotlib code libraries. Future updates to the tools will be readily available by executing a single command in the AstroConda environment. Contact the JWST Help Desk with any questions.

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

GTVT help

CVT help

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. You may want to familiarize yourself with both tools to understand the pros and cons of each.

Latest updates

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