JWST Moving Target Visibility Tool Help

The JWST Moving Target Visibility Tool (MTVT) is a command-line Python tool that provides quick-look assessments of moving target visibilities and position angles for all JWST instruments.

On this page

See also: JWST General Target Visibility Tool Help, JWST Position Angles, Ranges, and OffsetsSolar System Special Requirements, JWST Observatory Coordinate System and Field of Regard

The JWST Moving Target Visibility Tool (MTVT) is a Python command-line tool for calculating moving (solar system) target visibility windows as a function of time. It has similar functionality to that of the JWST General Target Visibility Tool (GTVT), with a few additional features specific to moving targets. The MTVT is packaged with the GTVT, and is automatically installed when users install the GTVT (no standalone installation process is provided for the MTVT). Both the GTVT and MTVT currently use the post-launch JWST ephemeris.

Unlike the GTVT, users input a solar system target designation, rather than a fixed (RA, Dec) sky position. The designation can be an official name (e.g., Saturn, Gaspra, Encke), number (e.g., 599, 20000), or provisional designation (e.g., 2002 MS4). MTVT uses the JPL Horizons system to resolve the designation, and retrieves the target ephemeris (RA, Dec) at one day intervals. At that point, the functionality of the MTVT is identical to that of the GTVT.

For a given RA and Dec, the MTVT provides aperture position angle (APA) information for all 4 science instruments and the FGS within the allowed visibility windows. It also outputs the V3-axis position angle (V3PA). Results are in the form of an ASCII file as well as one or more summary plots. A number of options are available from the command line for tailoring the output to your needs. Once the interactive plot is displayed, icons can be selected to pan and zoom in on the plot to see detailed information.

The allowable position angles output by the MTVT can, for example, be used to help users plan observations of giant planet satellites to ensure that the giant planet avoids falling on a nearby science or FGS aperture, or to determine the visibility windows and durations for Mars or fast moving near-Earth asteroids (NEAs). In order to visualize an observation in APT using Aladin, users should add a PA range special requirement that reflects the range of allowed position angles from MTVT, and create a fixed target proxy with coordinates consistent with those position angles. Once that is done, visualization can proceed as described in the Visualizing Dithers of a Solar System Observation in APT tutorial.

The schedulability of a given target observation is more complex that just its visibility. It also involves the availability of guide stars as a function of time and other constraints that may be set with special requirements and/or Solar System special requirements in APT. The MTVT is a "quick look" tool for pre-planning purposes, but the Astronomers Proposal Tool is the true arbiter of schedulability for a given proposed observation.



Installation and dependencies

The MTVT is currently incompatible with Windows operating systems.

The MTVT comes packaged with the GTVT. The user is referred to the "Installation and usage" section on the JWST General Target Visibility Tool Help article for instructions on how to install the GTVT/MTVT (or update it if an older version of GTVT/MTVT was installed).

Similarly, the user should refer to the "Dependencies" section on the JWST General Target Visibility Tool Help page for information on the packages and libraries required to run GTVT/MTVT.

Once successfully installed, MTVT is run from the command line, as described below.



Usage tips

To see the MTVT help information, type jwst_mtvt -h or jwst_mtvt --help

$ jwst_mtvt -h
Usage:
  jwst_mtvt <desg> [--start_date=<obs_start>] [--end_date=<obs_end>] [--instrument=<inst>] [--write_ephemeris=<write_path>] [--write_plot=<plot_path>] [--smallbody] [--silent]

Arguments:
  <desg>    Name of moving target. 

Options:
  [--start_date]         Start date for plot
  [--end_date]           End date for plot
  [--instrument]         JWST instrument to plot individually
  [--write_ephemeris]    File name to write ephemeris to
  [--write_plot]         File name to write plot out to
  [--smallbody]          Smallbody designation for major body
  --silent               Boolean to print results to screen [default: False]
  -h --help              Show this screen.
  --version              Show version.


MTVT command line examples

The user is referred to the "GTVT command line examples" section of the JWST General Target Visibility Tool Help article for basic GTVT/MTVT commands.

Basic use of the MTVT is shown with the example command below:

jwst_mtvt Ceres

Note that the following command will produce the same results, i.e., the provided designation is not case-sensitive:

jwst_mtvt ceres

After running this command, a table will be output in the terminal and a plot will open in a new window that includes the allowable aperture position angles as a function of time for the 4 science instruments (NIRCam, MIRI, NIRSpec, NIRISS), the FGS, and the V3-axis. Examples of these outputs are shown in the "MTVT outputs" section below.

Official names such as "Ceres," "Jupiter," and "Chiron" are not case-sensitive. However, primary designations such as "2002 MS4" and "2003 AZ84" are case-sensitive. Specifically, provisional designations must use capital letters or else the MTVT will output an error.

Evaluating planet visibility

An example command for running the MTVT for a planet is shown below:

jwst_mtvt Jupiter

However, running the above command will result in the following message

ValueError: Ambiguous target name; provide unique id:      
  ID#      Name                               Designation  IAU/aliases/other   
  -------  ---------------------------------- -----------  ------------------- 
        5  Jupiter Barycenter                                                   
      599  Jupiter                                                              

In order to obtain a result from the MTVT, the user must select Jupiter Barycenter as the target using ID# 5:

jwst_mtvt 5

Or Jupiter as the target using ID# 599:

jwst_mtvt 599

The ID# of the planet barycenters and the planets themselves used by JPL Horizons are presented in Table 1.


Table 1. JPL Horizons planet ID numbers

ID#

Name

4

Mars barycenter

5

Jupiter barycenter

6

Saturn barycenter

7

Uranus barycenter

8

Neptune barycenter

9

Pluto barycenter

499

Mars

599

Jupiter

699

Saturn

799

Uranus

899

Neptune

999

Pluto

Evaluating minor body visibility

An example command for running the MTVT for a minor body using its name is shown below.

jwst_mtvt Makemake

An example command for running the MTVT for a minor body using its provisional designation is shown below (quotation marks are required).

jwst_mtvt '2002 MS4'

An example command for running the MTVT for a minor body using its number and the --smallbody optional argument is shown below. The purpose of this optional argument is to remove ambiguity between low-numbered minor bodies and major bodies. The example below will return information on the asteroid 4 Vesta. But, without the --smallbody optional argument, the MTVT would return information for the Mars barycenter.

jwst_mtvt 4 --smallbody

For higher-numbered minor bodies, the --smallbody optional argument is not necessary, as shown below for the dwarf planet Haumea.

jwst_mtvt 136108

The special case of comets

An example command for running the MTVT for a comet using its name is shown below:

jwst_mtvt Encke

An example command for running the MTVT for a comet using its designation is shown below. Use of the --smallbody optional argument is not necessary for comets when using the designation as the identifier.

jwst_mtvt 2P

The commands above are equivalent and will both result in the following message:

ValueError: Ambiguous target name; provide unique id:
    Record #  Epoch-yr  >MATCH DESIG<  Primary Desig  Name  
    --------  --------  -------------  -------------  -------------------------
    90000031    1786    2P             2P              Encke
    90000032    1796    2P             2P              Encke
    90000033    1805    2P             2P              Encke
    90000034    1819    2P             2P              Encke
    90000035    1822    2P             2P              Encke
    90000036    1825    2P             2P              Encke
    90000037    1828    2P             2P              Encke
    90000038    1832    2P             2P              Encke
    90000039    1835    2P             2P              Encke
    90000040    1838    2P             2P              Encke
    90000041    1842    2P             2P              Encke
    90000042    1845    2P             2P              Encke
    90000043    1848    2P             2P              Encke
    90000044    1852    2P             2P              Encke
    90000045    1855    2P             2P              Encke
    90000046    1858    2P             2P              Encke
    90000047    1862    2P             2P              Encke
    90000048    1865    2P             2P              Encke
    90000049    1868    2P             2P              Encke
    90000050    1872    2P             2P              Encke
    90000051    1875    2P             2P              Encke
    90000052    1878    2P             2P              Encke
    90000053    1881    2P             2P              Encke
    90000054    1885    2P             2P              Encke
    90000055    1888    2P             2P              Encke
    90000056    1891    2P             2P              Encke
    90000057    1895    2P             2P              Encke
    90000058    1898    2P             2P              Encke
    90000059    1901    2P             2P              Encke
    90000060    1904    2P             2P              Encke
    90000061    1908    2P             2P              Encke
    90000062    1911    2P             2P              Encke
    90000063    1914    2P             2P              Encke
    90000064    1918    2P             2P              Encke
    90000065    1921    2P             2P              Encke
    90000066    1924    2P             2P              Encke
    90000067    1928    2P             2P              Encke
    90000068    1931    2P             2P              Encke
    90000069    1934    2P             2P              Encke
    90000070    1937    2P             2P              Encke
    90000071    1941    2P             2P              Encke
    90000072    1947    2P             2P              Encke
    90000073    1951    2P             2P              Encke
    90000074    1954    2P             2P              Encke
    90000075    1957    2P             2P              Encke
    90000076    1961    2P             2P              Encke
    90000077    1964    2P             2P              Encke
    90000078    1967    2P             2P              Encke
    90000079    1971    2P             2P              Encke
    90000080    1974    2P             2P              Encke
    90000081    1977    2P             2P              Encke
    90000082    1980    2P             2P              Encke
    90000083    1984    2P             2P              Encke
    90000084    1987    2P             2P              Encke
    90000085    1990    2P             2P              Encke
    90000086    1994    2P             2P              Encke
    90000087    1995    2P             2P              Encke
    90000088    1998    2P             2P              Encke
    90000089    2004    2P             2P              Encke
    90000090    2016    2P             2P              Encke

JPL Horizons contains multiple orbital solutions for periodic comets, so the user must select one option to proceed. The user is less likely to receive this message for long-period comets. If the user does not know the "Record #" for the orbital solution of interest ahead of time, this is an easy way to see a list of possible values. If the user knows the "Record #" ahead of time, they can skip the step of viewing the list. If the user wants the most recent orbital solution for 2P/Encke, they would type the following command:

jwst_mtvt 900090

Note that the most recent orbital solution is not selected as a default when running the MTVT.



MTVT outputs

The default outputs for the MTVT are identical to the GTVT: a 6-panel plot showing the allowable position angles for the V3 axis, the 4 science instruments, and the FGS; and an ASCII table containing the information in the plot in table form. See the "Example plots from GTVT" section of the JWST General Target Visibility Tool Help page for instructions on how to output a plot for only one instrument.

Figure 1. Default 6-panel MTVT output plot

Allowable aperture position angles are shown on the y-axis in degrees plotted against date on the x-axis. The allowable position angles for each date can be found in the ASCII output table. In general, the visibility windows for Solar System objects along the ecliptic will be separated by position angles of ~180°; see the Moving Target Field of Regard article for a diagram of the JWST focal plane orientation for observations along the ecliptic. For a more distant, slower-moving target like the TNO 47171 Lempo, the range of allowable position angles will be very small. Objects closer to JWST will have a larger range of allowable position angles.
Figure 2. Zoom in on a MIRI visibility window

The zoom tool (magnifying glass icon in the lower left corner of the plot window) can be used to zoom in on visibility windows of interest in individual plots. In the image above, the zoom tool was used to focus on one particular visibility window for MIRI, showing the allowable position angles in more detail.

The table below shows the dates and duration of each visibility window when the target is in JWST's field of regard, as well as the allowable position angles and the start and end RA and Dec values for these dates. The RA and Dec, along with the allowable position angles for the V3 axis, each of the 4 science instruments, and the FGS, are output for each date that the object is observable by JWST. The table written to the terminal is much longer than shown and has been truncated for the purpose of presentation in this article. The table can be scrolled horizontally to reveal the hidden columns.

$ jwst_mtvt Lempo     

+------------------------------------------+
| JWST General Target Visibility Tool      |
+------------------------------------------+
| Runtime/Date: 2023-07-05 20:35:21.299422 |
+------------------------------------------+
| Version Number: 1.0.0                    |
+------------------------------------------+

Target Name: 47171 Lempo (1999 TC36) Ecliptic Latitude: 24.284867
-----------------------------------------------------------------

Checked Interval [2021-12-26 00:00:00.000, 2025-06-11 00:00:00.000]

+--------------------------------+--------------------------------+-------------------+------------------+----------------+
| Window Start                   | Window End                     |   Window Duration |   V3 Angle Start |   V3 Angle End |
|--------------------------------+--------------------------------+-------------------+------------------+----------------|
| A.D. 2021-Dec-27 00:00:00.0000 | A.D. 2022-Feb-12 00:00:00.0000 |                47 |          67.953  |        74.4873 |
| A.D. 2022-Aug-11 00:00:00.0000 | A.D. 2022-Oct-01 00:00:00.0000 |                51 |         254.685  |       261.785  |
| A.D. 2022-Dec-27 00:00:00.0000 | A.D. 2023-Feb-14 00:00:00.0000 |                49 |          68.5274 |        75.0445 |
| A.D. 2023-Aug-13 00:00:00.0000 | A.D. 2023-Oct-03 00:00:00.0000 |                51 |         255.396  |       262.158  |
| A.D. 2023-Dec-30 00:00:00.0000 | A.D. 2024-Feb-17 00:00:00.0000 |                49 |          69.5487 |        75.7348 |
| A.D. 2024-Aug-15 00:00:00.0000 | A.D. 2024-Oct-05 00:00:00.0000 |                51 |         256.242  |       262.736  |
| A.D. 2025-Jan-01 00:00:00.0000 | A.D. 2025-Feb-18 00:00:00.0000 |                48 |          70.5794 |        76.3487 |
+--------------------------------+--------------------------------+-------------------+------------------+----------------+
+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+-------------+-------------+
|   NRC Max PA |   NRC Min PA |   NRS Max PA |   NRS Min PA |   NIS Max PA |   NIS Min PA |   MIR Max PA |   MIR Min PA |   FGS Max PA |   FGS Min PA |   V3 Max PA |   V3 Min PA |
|--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+--------------+-------------+-------------|
|      74.7723 |      60.9911 |     213.418  |     199.637  |      75.4049 |      61.6237 |      79.6791 |      65.8979 |      73.6024 |      59.8212 |     74.8436 |     61.0624 |
|      74.9025 |      61.3385 |     213.548  |     199.984  |      75.5351 |      61.9711 |      79.8093 |      66.2453 |      73.7326 |      60.1686 |     74.9738 |     61.4098 |
|      75.0219 |      61.6646 |     213.668  |     200.311  |      75.6546 |      62.2973 |      79.9287 |      66.5714 |      73.8521 |      60.4948 |     75.0933 |     61.736  |
|      75.1358 |      61.9749 |     213.782  |     200.621  |      75.7684 |      62.6075 |      80.0426 |      66.8817 |      73.9659 |      60.805  |     75.2071 |     62.0462 |
|      75.2456 |      62.2713 |     213.892  |     200.917  |      75.8782 |      62.9039 |      80.1524 |      67.1781 |      74.0758 |      61.1014 |     75.317  |     62.3426 |
|      75.3525 |      62.5554 |     213.998  |     201.201  |      75.9851 |      63.188  |      80.2593 |      67.4622 |      74.1826 |      61.3855 |     75.4238 |     62.6267 |
|      75.4568 |      62.8282 |     214.103  |     201.474  |      76.0895 |      63.4608 |      80.3637 |      67.735  |      74.287  |      61.6583 |     75.5282 |     62.8995 |
|      75.5592 |      63.0906 |     214.205  |     201.737  |      76.1919 |      63.7232 |      80.466  |      67.9974 |      74.3894 |      61.9207 |     75.6306 |     63.1619 |
|      75.6599 |      63.3434 |     214.306  |     201.989  |      76.2925 |      63.976  |      80.5667 |      68.2502 |      74.4901 |      62.1735 |     75.7313 |     63.4147 |
|      75.7592 |      63.5871 |     214.405  |     202.233  |      76.3918 |      64.2198 |      80.666  |      68.4939 |      74.5893 |      62.4173 |     75.8305 |     63.6585 |
|      75.8572 |      63.8225 |     214.503  |     202.468  |      76.4898 |      64.4551 |      80.764  |      68.7293 |      74.6873 |      62.6526 |     75.9285 |     63.8938 |
|      75.9542 |      64.0499 |     214.6    |     202.696  |      76.5868 |      64.6826 |      80.861  |      68.9567 |      74.7843 |      62.8801 |     76.0255 |     64.1213 |
|      76.0503 |      64.27   |     214.696  |     202.916  |      76.6829 |      64.9026 |      80.9571 |      69.1768 |      74.8804 |      63.1001 |     76.1216 |     64.3413 |
|      76.1457 |      64.483  |     214.792  |     203.129  |      76.7783 |      65.1156 |      81.0525 |      69.3898 |      74.9758 |      63.3132 |     76.217  |     64.5544 |
|      76.2404 |      64.6894 |     214.886  |     203.335  |      76.8731 |      65.3221 |      81.1472 |      69.5962 |      75.0706 |      63.5196 |     76.3118 |     64.7608 |
|      76.3347 |      64.8896 |     214.981  |     203.536  |      76.9673 |      65.5222 |      81.2415 |      69.7964 |      75.1648 |      63.7198 |     76.4061 |     64.961  |
|      76.4286 |      65.0839 |     215.074  |     203.73   |      77.0612 |      65.7165 |      81.3354 |      69.9907 |      75.2587 |      63.9141 |     76.4999 |     65.1553 |
|      76.5221 |      65.2726 |     215.168  |     203.919  |      77.1548 |      65.9052 |      81.429  |      70.1794 |      75.3523 |      64.1027 |     76.5935 |     65.3439 |
|      76.6155 |      65.456  |     215.261  |     204.102  |      77.2481 |      66.0886 |      81.5223 |      70.3628 |      75.4457 |      64.2861 |     76.6869 |     65.5273 |
|      76.7088 |      65.6343 |     215.355  |     204.28   |      77.3414 |      66.2669 |      81.6156 |      70.5411 |      75.5389 |      64.4645 |     76.7801 |     65.7057 |
|      76.8019 |      65.8079 |     215.448  |     204.454  |      77.4346 |      66.4405 |      81.7087 |      70.7147 |      75.6321 |      64.638  |     76.8733 |     65.8792 |
|      76.8952 |      65.9769 |     215.541  |     204.623  |      77.5278 |      66.6095 |      81.802  |      70.8837 |      75.7253 |      64.807  |     76.9665 |     66.0482 |
|      76.9885 |      66.1415 |     215.634  |     204.787  |      77.6211 |      66.7741 |      81.8953 |      71.0483 |      75.8186 |      64.9717 |     77.0598 |     66.2129 |
|      77.082  |      66.3021 |     215.728  |     204.948  |      77.7146 |      66.9347 |      81.9888 |      71.2089 |      75.9121 |      65.1322 |     77.1533 |     66.3734 |
|      77.1757 |      66.4587 |     215.822  |     205.105  |      77.8083 |      67.0913 |      82.0825 |      71.3655 |      76.0059 |      65.2888 |     77.2471 |     66.53   |
|      77.2697 |      66.6115 |     215.916  |     205.257  |      77.9024 |      67.2441 |      82.1765 |      71.5183 |      76.0999 |      65.4417 |     77.3411 |     66.6829 |
|      77.3641 |      66.7608 |     216.01   |     205.407  |      77.9967 |      67.3934 |      82.2709 |      71.6676 |      76.1943 |      65.5909 |     77.4355 |     66.8321 |
|      77.459  |      66.9067 |     216.105  |     205.553  |      78.0916 |      67.5393 |      82.3658 |      71.8135 |      76.2891 |      65.7368 |     77.5303 |     66.978  |
|      77.5543 |      67.0493 |     216.2    |     205.695  |      78.1869 |      67.6819 |      82.4611 |      71.9561 |      76.3844 |      65.8794 |     77.6256 |     67.1206 |
|      77.6501 |      67.1888 |     216.296  |     205.835  |      78.2827 |      67.8214 |      82.5569 |      72.0956 |      76.4803 |      66.0189 |     77.7215 |     67.2601 |
|      77.7466 |      67.3253 |     216.393  |     205.971  |      78.3792 |      67.9579 |      82.6534 |      72.2321 |      76.5767 |      66.1554 |     77.8179 |     67.3966 |
|      77.8437 |      67.459  |     216.49   |     206.105  |      78.4763 |      68.0916 |      82.7505 |      72.3658 |      76.6739 |      66.2891 |     77.9151 |     67.5303 |
|      77.9416 |      67.5899 |     216.588  |     206.236  |      78.5742 |      68.2225 |      82.8484 |      72.4967 |      76.7717 |      66.4201 |     78.0129 |     67.6613 |
|      78.0402 |      67.7182 |     216.686  |     206.364  |      78.6728 |      68.3509 |      82.947  |      72.625  |      76.8704 |      66.5484 |     78.1116 |     67.7896 |
|      78.1397 |      67.8441 |     216.786  |     206.49   |      78.7723 |      68.4767 |      83.0465 |      72.7509 |      76.9698 |      66.6742 |     78.211  |     67.9154 |
|      78.2401 |      67.9675 |     216.886  |     206.613  |      78.8727 |      68.6002 |      83.1469 |      72.8744 |      77.0702 |      66.7977 |     78.3114 |     68.0389 |
|      78.3414 |      68.0887 |     216.987  |     206.735  |      78.974  |      68.7213 |      83.2482 |      72.9955 |      77.1715 |      66.9189 |     78.4127 |     68.1601 |
|      78.4437 |      68.2077 |     217.09   |     206.854  |      79.0763 |      68.8403 |      83.3505 |      73.1145 |      77.2739 |      67.0378 |     78.5151 |     68.279  |
|      78.5471 |      68.3246 |     217.193  |     206.97   |      79.1798 |      68.9572 |      83.4539 |      73.2314 |      77.3773 |      67.1547 |     78.6185 |     68.3959 |
|      78.6517 |      68.4394 |     217.298  |     207.085  |      79.2843 |      69.072  |      83.5585 |      73.3462 |      77.4818 |      67.2696 |     78.723  |     68.5108 |
|      78.7574 |      68.5523 |     217.403  |     207.198  |      79.3901 |      69.185  |      83.6642 |      73.4592 |      77.5876 |      67.3825 |     78.8288 |     68.6237 |
|      78.8645 |      68.6634 |     217.51   |     207.309  |      79.4971 |      69.296  |      83.7713 |      73.5702 |      77.6946 |      67.4936 |     78.9358 |     68.7348 |
|      78.9728 |      68.7727 |     217.619  |     207.419  |      79.6054 |      69.4054 |      83.8796 |      73.6795 |      77.8029 |      67.6029 |     79.0441 |     68.8441 |
|      79.0825 |      68.8803 |     217.728  |     207.526  |      79.7151 |      69.513  |      83.9893 |      73.7871 |      77.9127 |      67.7105 |     79.1539 |     68.9517 |
|      79.1937 |      68.9863 |     217.84   |     207.632  |      79.8263 |      69.6189 |      84.1005 |      73.8931 |      78.0239 |      67.8165 |     79.2651 |     69.0577 |
|      78.8763 |      69.5208 |     217.522  |     208.167  |      79.509  |      70.1534 |      83.7831 |      74.4276 |      77.7065 |      68.351  |     78.9477 |     69.5922 |
|      78.3628 |      70.2516 |     217.009  |     208.898  |      78.9954 |      70.8842 |      83.2696 |      75.1584 |      77.193  |      69.0817 |     78.4342 |     70.3229 |
|      77.8501 |      70.9818 |     216.496  |     209.628  |      78.4827 |      71.6144 |      82.7569 |      75.8886 |      76.6802 |      69.8119 |     77.9214 |     71.0531 |

[ ... Additional output not shown ... ]



Credits

The MTVT was originally developed by Michael S. P. Kelley (University of Maryland) and is maintained by Mees Fix (Space Telescope Science Institute).




Latest updates
  •  
    Updated for JWST Moving Target Visibility Tool (MTVT) version 1.0.

  •  
    Updated for JWST Moving Target Visibility Tool (MTVT) version 0.3.0.

  •  
    Updated for version 0.2.0.


  • Revised language about specific launch date to make generic.

  •   
    Added a note about incompatibility with Windows.


  • Removed mention of callhorizons and added installation instructions for astroquery.

  •  
    Added notation regarding updated orbital ephemeris.
Originally published